persona

Documentation

Overview

Package persona provides persona-based access control and customization.

Index

• type Authorizer
  • func NewAuthorizer(registry *Registry, mapper RoleMapper) *Authorizer
  • func (a *Authorizer) IsAuthorized(ctx context.Context, _ string, roles []string, toolName string) (allowed bool, personaName, reason string)
• type ChainedRoleMapper
  • func (c *ChainedRoleMapper) MapToPersona(ctx context.Context, roles []string) (*Persona, error)
  • func (c *ChainedRoleMapper) MapToRoles(claims map[string]any) ([]string, error)
• type Config
• type OIDCRoleMapper
  • func (m *OIDCRoleMapper) MapToPersona(_ context.Context, roles []string) (*Persona, error)
  • func (m *OIDCRoleMapper) MapToRoles(claims map[string]any) ([]string, error)
• type Persona
  • func AdminPersona() *Persona
  • func DefaultPersona() *Persona
  • func (p *Persona) GetFullSystemPrompt() string
• type PromptConfig
• type PromptConfigYAML
• type Registry
  • func NewRegistry() *Registry
  • func (r *Registry) All() []*Persona
  • func (r *Registry) DefaultName() string
  • func (r *Registry) Get(name string) (*Persona, bool)
  • func (r *Registry) GetDefault() (*Persona, bool)
  • func (r *Registry) GetForRoles(roles []string) (*Persona, bool)
  • func (r *Registry) LoadFromConfig(config map[string]*Config) error
  • func (r *Registry) Register(p *Persona) error
  • func (r *Registry) SetDefault(name string)
  • func (r *Registry) Unregister(name string) error
• type RoleMapper
• type StaticRoleMapper
  • func (m *StaticRoleMapper) MapToPersona(_ context.Context, _ []string) (*Persona, error)
  • func (*StaticRoleMapper) MapToRoles(_ map[string]any) ([]string, error)
• type ToolFilter
  • func NewToolFilter(registry *Registry) *ToolFilter
  • func (f *ToolFilter) FilterTools(persona *Persona, tools []string) []string
  • func (*ToolFilter) IsAllowed(persona *Persona, toolName string) bool
• type ToolRules
• type ToolRulesConfig

Types

type Authorizer

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

Authorizer implements middleware.Authorizer using personas.

func NewAuthorizer

func NewAuthorizer(registry *Registry, mapper RoleMapper) *Authorizer

NewAuthorizer creates a new persona-based authorizer.

func (*Authorizer) IsAuthorized

func (a *Authorizer) IsAuthorized(ctx context.Context, _ string, roles []string, toolName string) (allowed bool, personaName, reason string)

IsAuthorized checks if the user is authorized for the tool. Returns the resolved persona name for audit logging.

type ChainedRoleMapper

type ChainedRoleMapper struct {
	Mappers []RoleMapper
}

ChainedRoleMapper tries multiple mappers in order.

func (*ChainedRoleMapper) MapToPersona

func (c *ChainedRoleMapper) MapToPersona(ctx context.Context, roles []string) (*Persona, error)

MapToPersona uses the first mapper that returns a persona.

func (*ChainedRoleMapper) MapToRoles

func (c *ChainedRoleMapper) MapToRoles(claims map[string]any) ([]string, error)

MapToRoles aggregates roles from all mappers.

type Config

type Config struct {
	DisplayName string            `yaml:"display_name"`
	Description string            `yaml:"description,omitempty"`
	Roles       []string          `yaml:"roles"`
	Tools       ToolRulesConfig   `yaml:"tools"`
	Prompts     PromptConfigYAML  `yaml:"prompts"`
	Hints       map[string]string `yaml:"hints,omitempty"`
	Priority    int               `yaml:"priority,omitempty"`
}

Config is the configuration format for personas.

type OIDCRoleMapper

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
}

OIDCRoleMapper extracts roles from OIDC token claims.

func (*OIDCRoleMapper) MapToPersona

func (m *OIDCRoleMapper) MapToPersona(_ context.Context, roles []string) (*Persona, error)

MapToPersona maps roles to a persona.

func (*OIDCRoleMapper) MapToRoles

func (m *OIDCRoleMapper) MapToRoles(claims map[string]any) ([]string, error)

MapToRoles extracts roles from OIDC claims.

type Persona

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.
	Roles []string `json:"roles" yaml:"roles"`

	// Tools defines tool access rules.
	Tools ToolRules `json:"tools" yaml:"tools"`

	// Prompts defines prompt customizations.
	Prompts PromptConfig `json:"prompts" yaml:"prompts"`

	// Hints provides tool-specific hints for the AI.
	Hints map[string]string `json:"hints,omitempty" yaml:"hints,omitempty"`

	// Priority determines which persona takes precedence.
	// Higher values have higher priority.
	Priority int `json:"priority,omitempty" yaml:"priority,omitempty"`
}

Persona defines a user persona with associated permissions and customizations.

func AdminPersona

func AdminPersona() *Persona

AdminPersona creates an admin persona with full access.

func DefaultPersona

func DefaultPersona() *Persona

DefaultPersona creates a default persona that denies all access. This ensures fail-closed behavior - users must be explicitly granted access.

func (*Persona) GetFullSystemPrompt

func (p *Persona) GetFullSystemPrompt() string

GetFullSystemPrompt returns the complete system prompt by combining SystemPrefix, Instructions, and SystemSuffix.

type PromptConfig

type PromptConfig struct {
	// SystemPrefix is prepended to system prompts.
	SystemPrefix string `json:"system_prefix,omitempty" yaml:"system_prefix,omitempty"`

	// SystemSuffix is appended to system prompts.
	SystemSuffix string `json:"system_suffix,omitempty" yaml:"system_suffix,omitempty"`

	// Instructions are additional instructions for this persona.
	Instructions string `json:"instructions,omitempty" yaml:"instructions,omitempty"`
}

PromptConfig defines prompt customizations for a persona.

type PromptConfigYAML

type PromptConfigYAML struct {
	SystemPrefix string `yaml:"system_prefix,omitempty"`
	SystemSuffix string `yaml:"system_suffix,omitempty"`
	Instructions string `yaml:"instructions,omitempty"`
}

PromptConfigYAML is the YAML configuration for prompts.

type Registry

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

Registry manages persona definitions.

func NewRegistry

func NewRegistry() *Registry

NewRegistry creates a new persona registry.

func (*Registry) All

func (r *Registry) All() []*Persona

All returns all registered personas.

func (*Registry) DefaultName

func (r *Registry) DefaultName() string

DefaultName returns the default persona name.

func (*Registry) Get

func (r *Registry) Get(name string) (*Persona, bool)

Get retrieves a persona by name.

func (*Registry) GetDefault

func (r *Registry) GetDefault() (*Persona, bool)

GetDefault returns the default persona.

func (*Registry) GetForRoles

func (r *Registry) GetForRoles(roles []string) (*Persona, bool)

GetForRoles returns the best matching persona for the given roles.

func (*Registry) LoadFromConfig

func (r *Registry) LoadFromConfig(config map[string]*Config) error

LoadFromConfig loads personas from a configuration map.

func (*Registry) Register

func (r *Registry) Register(p *Persona) error

Register adds a persona to the registry.

func (*Registry) SetDefault

func (r *Registry) SetDefault(name string)

SetDefault sets the default persona name.

func (*Registry) Unregister

func (r *Registry) Unregister(name string) error

Unregister removes a persona by name. Returns error if not found.

type RoleMapper

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)
}

RoleMapper maps identity claims to platform roles and personas.

type StaticRoleMapper

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

	// DefaultPersonaName is the fallback persona.
	DefaultPersonaName string

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

StaticRoleMapper uses static configuration for mapping.

func (*StaticRoleMapper) MapToPersona

func (m *StaticRoleMapper) MapToPersona(_ context.Context, _ []string) (*Persona, error)

MapToPersona maps based on static configuration.

func (*StaticRoleMapper) MapToRoles

func (*StaticRoleMapper) MapToRoles(_ map[string]any) ([]string, error)

MapToRoles returns static roles (not used for static mapping).

type ToolFilter

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

ToolFilter filters tools based on persona rules.

func NewToolFilter

func NewToolFilter(registry *Registry) *ToolFilter

NewToolFilter creates a new tool filter.

func (*ToolFilter) FilterTools

func (f *ToolFilter) FilterTools(persona *Persona, tools []string) []string

FilterTools filters a list of tools based on persona rules.

func (*ToolFilter) IsAllowed

func (*ToolFilter) IsAllowed(persona *Persona, toolName string) bool

IsAllowed checks if a tool is allowed for a persona.

type ToolRules

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"`
}

ToolRules defines tool access rules for a persona.

type ToolRulesConfig

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

ToolRulesConfig is the YAML configuration for tool rules.