persona

type APIRouteRule struct {
	// Connection is a glob (e.g. "crm-*") matched against the connection
	// name. Required.
	Connection string `json:"connection" yaml:"connection"`

	// Methods is a list of HTTP method globs (e.g. ["GET", "HEAD"]).
	// Empty = any method. Patterns are case-sensitive — typically
	// uppercase ("GET", "POST", etc.) since the toolkit normalizes
	// inbound methods to uppercase before this check runs.
	Methods []string `json:"methods,omitempty" yaml:"methods,omitempty"`

	// Paths is a list of path globs. Each is matched against both the
	// path a call reaches ("/v1/orders/42") and the catalog template it
	// resolved from ("/v1/orders/{id}"), so a rule may name either form:
	// the templated path an operation is listed under governs the calls
	// that operation serves, and a glob written by hand still governs a
	// path no catalog declares. Empty = any path.
	Paths []string `json:"paths,omitempty" yaml:"paths,omitempty"`

	// Action is "allow" (default) or "deny". Deny rules take precedence
	// over allow rules within the matching-Connection subset.
	Action string `json:"action,omitempty" yaml:"action,omitempty"`
}

type AccessDecision struct {
	Allowed        bool         `json:"allowed"`
	MatchedPattern string       `json:"matched_pattern"`
	Source         AccessSource `json:"source"`
}

type AccessSource string

type Authorizer struct {
	// contains filtered or unexported fields
}

type ChainedRoleMapper struct {
	Mappers []RoleMapper
}

type CoherenceFinding struct {
	// Persona is the name of the persona the finding is about.
	Persona string `json:"persona"`
	// Granted is the tool the persona holds that arms the rule.
	Granted string `json:"granted"`
	// Missing is the tool the persona lacks.
	Missing string `json:"missing"`
	// Why states the capability lost by the pairing being broken.
	Why string `json:"why"`
	// Remedy is the operator-facing fix.
	Remedy string `json:"remedy"`
}

type Config struct {
	DisplayName string                `yaml:"display_name"`
	Description string                `yaml:"description,omitempty"`
	Roles       []string              `yaml:"roles"`
	Tools       ToolRulesConfig       `yaml:"tools"`
	Connections ConnectionRulesConfig `yaml:"connections"`
	Context     ContextOverridesYAML  `yaml:"context"`
	Priority    int                   `yaml:"priority,omitempty"`
}

type ConnectionRules struct {
	// Allow patterns for allowed connections (supports wildcards like "prod-*").
	Allow []string `json:"allow,omitempty" yaml:"allow,omitempty"`

	// Deny patterns for denied connections (takes precedence over Allow).
	Deny []string `json:"deny,omitempty" yaml:"deny,omitempty"`
}

type ConnectionRulesConfig struct {
	Allow []string `yaml:"allow,omitempty"`
	Deny  []string `yaml:"deny,omitempty"`
}

type ContextOverrides struct {
	// DescriptionPrefix is prepended to the server description (separated by
	// a blank line). Use this to add persona-specific context before the
	// base platform description. Ignored if DescriptionOverride is set.
	DescriptionPrefix string `json:"description_prefix,omitempty" yaml:"description_prefix,omitempty"`

	// DescriptionOverride replaces the server description entirely.
	// Use this when a persona needs a completely different description.
	DescriptionOverride string `json:"description_override,omitempty" yaml:"description_override,omitempty"`

	// AgentInstructionsSuffix is appended to the server agent instructions
	// (separated by a blank line). Use this to add persona-specific guidance
	// after the base instructions. Ignored if AgentInstructionsOverride is set.
	AgentInstructionsSuffix string `json:"agent_instructions_suffix,omitempty" yaml:"agent_instructions_suffix,omitempty"`

	// AgentInstructionsOverride replaces the server agent instructions entirely.
	// Use this when a persona needs completely different instructions.
	AgentInstructionsOverride string `json:"agent_instructions_override,omitempty" yaml:"agent_instructions_override,omitempty"`
}

type ContextOverridesYAML struct {
	DescriptionPrefix         string `yaml:"description_prefix,omitempty"`
	DescriptionOverride       string `yaml:"description_override,omitempty"`
	AgentInstructionsSuffix   string `yaml:"agent_instructions_suffix,omitempty"`
	AgentInstructionsOverride string `yaml:"agent_instructions_override,omitempty"`
}

type OIDCRoleMapper struct {
	// ClaimPath is the dot-separated path to roles in claims.
	ClaimPath string

	// RolePrefix filters roles to those starting with this prefix.
	RolePrefix string

	// PersonaMapping maps roles to persona names.
	PersonaMapping map[string]string

	// Registry is the persona registry.
	Registry *Registry
}

type Persona struct {
	// Name is the unique identifier for this persona.
	Name string `json:"name" yaml:"name"`

	// DisplayName is the human-readable name.
	DisplayName string `json:"display_name" yaml:"display_name"`

	// Description describes this persona.
	Description string `json:"description,omitempty" yaml:"description,omitempty"`

	// Roles are the roles that map to this persona. When a user authenticates
	// via OIDC, their token claims are mapped to roles. When using API keys,
	// roles are assigned directly. A user gets this persona when any of their
	// roles match.
	Roles []string `json:"roles" yaml:"roles"`

	// Tools defines tool access rules (allow/deny glob patterns).
	Tools ToolRules `json:"tools" yaml:"tools"`

	// Connections defines connection-level access rules. A tool call must pass
	// both the tool check and the connection check, and so must every discovery
	// surface (#1108): search, fetch, and list_connections show only the
	// connections these rules admit. Connections are deny-by-default (see
	// ToolFilter.IsConnectionAllowed) — an empty Allow grants no connection, so a
	// persona that should reach data must list what it may reach.
	Connections ConnectionRules `json:"connections" yaml:"connections"`

	// APIRoutes defines per-(connection, method, path) rules for the HTTP
	// API gateway toolkit (kind=api). Layered on top of Connections: if a
	// persona is allowed a connection at the tool/connection level, APIRoutes
	// can further restrict which HTTP methods and paths the model can invoke
	// against that connection. Personas with no APIRoutes entries for a
	// given connection get the existing connection-level behavior unchanged
	// (backward-compatible). See pkg/persona/filter.go IsAPIRouteAllowed.
	APIRoutes []APIRouteRule `json:"api_routes,omitempty" yaml:"api_routes,omitempty"`

	// Context defines per-persona overrides for the platform description and
	// agent instructions returned by the platform_info tool.
	Context ContextOverrides `json:"context" yaml:"context"`

	// Priority determines which persona takes precedence when a user's roles
	// match multiple personas. Higher values win. Default is 0; the built-in
	// admin persona uses 100.
	Priority int `json:"priority,omitempty" yaml:"priority,omitempty"`

	// ServiceAccount marks the persona an automated caller signs in under,
	// such as an integration holding an API key: its calls are audited but not
	// added to the call catalog, and the records it wrote before it was marked
	// are removed by the catalog's next sweep (#1980). A person's own persona
	// leaves it false, and its calls are cataloged.
	ServiceAccount bool `json:"service_account,omitempty" yaml:"service_account,omitempty"`

	// Portal is what the persona's people may do in the portal, one setting
	// per area (#2225). nil, and any field left unset, resolves to what the
	// persona reached before the setting existed; read it through
	// PortalPermissions. An administrator has every area whatever this says,
	// and the tools an agent calls are governed by Tools, not by this.
	Portal *PortalAccess `json:"portal,omitempty" yaml:"portal,omitempty"`

	// External marks a persona for people outside the organization (#2092),
	// whose accounts the platform creates. It sets limits the persona's other
	// settings cannot raise: no MCP tool, only what is shared with its people
	// in the portal, no sharing, no API keys and no people directory. Read the
	// portal half through PortalPermissions.
	External bool `json:"external,omitempty" yaml:"external,omitempty"`

	// AllowSharing lets the people signed in under this persona share what
	// they own: an asset, collection or prompt with a person, and an asset to
	// a notification channel (#2241). nil, which every persona written before
	// it carries, allows it; read it through SharingAllowed. Without it the
	// portal shows no Share action and every share-creating route and tool
	// action refuses. An administrator shares whatever the persona says.
	AllowSharing *bool `json:"allow_sharing,omitempty" yaml:"allow_sharing,omitempty"`

	// Source indicates where this persona was loaded from at runtime.
	// Values: "file" (YAML config), "database" (DB-managed), "both" (file
	// with DB override). This is runtime metadata — not persisted.
	Source string `json:"source,omitempty" yaml:"-"`
}

type PortalAccess struct {
	// Assets is assets and collections: shared or own.
	Assets string `json:"assets,omitempty" yaml:"assets,omitempty"`
	// Resources is managed resources: none, shared, own or persona.
	Resources string `json:"resources,omitempty" yaml:"resources,omitempty"`
	// Knowledge is knowledge pages: none, read or write.
	Knowledge string `json:"knowledge,omitempty" yaml:"knowledge,omitempty"`
	// Catalog is the platform catalog: none, read or write.
	Catalog string `json:"catalog,omitempty" yaml:"catalog,omitempty"`
	// APIs is the portal API browser: none or browse.
	APIs string `json:"apis,omitempty" yaml:"apis,omitempty"`
	// ScratchTables is the scratch-table routes and page: none, list or
	// register (#2257). The connections a table sits on are still the
	// persona's Connections.
	ScratchTables string `json:"scratch_tables,omitempty" yaml:"scratch_tables,omitempty"`
	// Feedback is threads, comments, activity, worklists and sign-off.
	Feedback *bool `json:"feedback,omitempty" yaml:"feedback,omitempty"`
	// Prompts is the prompt library.
	Prompts *bool `json:"prompts,omitempty" yaml:"prompts,omitempty"`
	// Automations is managed scripts in the portal; the script tools an agent
	// calls are governed by Tools. It replaces hide_automations (#2109).
	Automations *bool `json:"automations,omitempty" yaml:"automations,omitempty"`
	// Search is the portal's unified search.
	Search *bool `json:"search,omitempty" yaml:"search,omitempty"`
	// Memory is memory and insights.
	Memory *bool `json:"memory,omitempty" yaml:"memory,omitempty"`
	// Download is exporting an asset or a resource as PDF; the portal names
	// it PDF export (#2257). Reading content is the item's own sharing.
	Download *bool `json:"download,omitempty" yaml:"download,omitempty"`
	// Uploads lets the people of an external persona upload files, each one
	// shared on arrival with the recipients it names (#2258). nil is no
	// uploads; an internal persona's people upload by their Resources level
	// and this is dropped from its resolved block.
	Uploads *PortalUploads `json:"uploads,omitempty" yaml:"uploads,omitempty"`
	// External is reported, never set: the persona is external (#2092), so
	// the portal offers its people no people directory and no API keys.
	External bool `json:"external,omitempty" yaml:"-"`
}

type PortalUploads struct {
	// SharePersonas are personas whose people read each upload.
	SharePersonas []string `json:"share_personas,omitempty" yaml:"share_personas,omitempty"`
	// ShareEmails are addresses that read each upload.
	ShareEmails []string `json:"share_emails,omitempty" yaml:"share_emails,omitempty"`
}

type Registry struct {
	// contains filtered or unexported fields
}

type RoleMapper interface {
	// MapToRoles extracts roles from claims.
	MapToRoles(claims map[string]any) ([]string, error)

	// MapToPersona maps roles to a persona.
	MapToPersona(ctx context.Context, roles []string) (*Persona, error)
}

type RouteDecision struct {
	Allowed bool `json:"allowed"`
	// Source is "deny" when a deny rule refused the query and "allow" when
	// an allow rule admitted it. "default" means no rule decided, and
	// Allowed says which of its two cases this is: true when no rule named
	// the connection at all, which leaves the connection-level gate as the
	// sole one, and false when rules named it and none of them admitted
	// this query — a denial the rule set produced rather than any one rule.
	Source AccessSource `json:"source"`
	// MatchedRule is the rule the decision came from. Nil for
	// AccessSourceDefault, and nil when rules touch the connection but
	// none matched the query, which is a denial no single rule produced.
	MatchedRule *APIRouteRule `json:"matched_rule,omitempty"`
}

type RouteQuery struct {
	// Connection is the connection name the rules' Connection globs are
	// matched against.
	Connection string
	// Method is the HTTP method, uppercase.
	Method string
	// Path is the concrete request path.
	Path string
	// Template is the catalog path template Path resolved from. Empty
	// when the connection's catalog declares no matching operation, and
	// equal to Path for an operation whose path carries no placeholder.
	Template string
}

type StaticRoleMapper struct {
	// GroupPersonas maps groups to persona names.
	GroupPersonas map[string]string

	// PersonaName is the persona every caller is assigned. An empty name, or a
	// name absent from the registry, yields the deny-all DefaultPersona.
	PersonaName string

	// Registry is the persona registry.
	Registry *Registry
}

type ToolFilter struct {
	// contains filtered or unexported fields
}

type ToolRules struct {
	// Allow patterns for allowed tools (supports wildcards like "trino_*").
	Allow []string `json:"allow" yaml:"allow"`

	// Deny patterns for denied tools (takes precedence over Allow).
	Deny []string `json:"deny" yaml:"deny"`
}

type ToolRulesConfig struct {
	Allow []string `yaml:"allow"`
	Deny  []string `yaml:"deny"`
}