personserver

package
v0.6.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 27, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package personserver implements the AAuth Person Server. The Person Server handles human consent for agent authorization.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrInvalidPrivateKey is returned when the private key is invalid.
	ErrInvalidPrivateKey = errors.New("private key must implement crypto.Signer")
)

Package errors.

Functions

This section is empty.

Types

type Agent 

type Agent struct {
	ID          string    `json:"id"`
	Name        string    `json:"name"`
	Description string    `json:"description,omitempty"`
	PublicKey   string    `json:"public_key"`
	RedirectURI string    `json:"redirect_uri,omitempty"`
	Trusted     bool      `json:"trusted"`
	CreatedAt   time.Time `json:"created_at"`
	UpdatedAt   time.Time `json:"updated_at"`
}

Agent represents a registered agent that can request authorization.

type AuthorizationRequest 

type AuthorizationRequest struct {
	AgentToken      string `json:"agent_token"`
	UserID          string `json:"user_id"`
	Scopes          string `json:"scope"`
	MissionName     string `json:"mission_name,omitempty"`
	MissionDesc     string `json:"mission_description,omitempty"`
	InteractionType string `json:"interaction_type,omitempty"`
	Duration        int64  `json:"duration,omitempty"` // Seconds
	RedirectURI     string `json:"redirect_uri,omitempty"`
	State           string `json:"state,omitempty"`
}

AuthorizationRequest is the request from an agent to authorize a mission.

type AuthorizationResponse 

type AuthorizationResponse struct {
	// For immediate approval (pre-authorized)
	AccessToken string `json:"access_token,omitempty"`
	TokenType   string `json:"token_type,omitempty"`
	ExpiresIn   int    `json:"expires_in,omitempty"`
	Scope       string `json:"scope,omitempty"`

	// For deferred consent
	ConsentURI string `json:"consent_uri,omitempty"`
	StatusURI  string `json:"status_uri,omitempty"`
	MissionID  string `json:"mission_id,omitempty"`
	Interval   int    `json:"interval,omitempty"`
}

AuthorizationResponse is returned when authorization is requested.

type ConsentRequest 

type ConsentRequest struct {
	MissionID   string   `json:"mission_id"`
	AgentID     string   `json:"agent_id"`
	AgentName   string   `json:"agent_name"`
	UserID      string   `json:"user_id"`
	UserName    string   `json:"user_name"`
	Scopes      []string `json:"scopes"`
	Description string   `json:"description"`
	Duration    string   `json:"duration"`
}

ConsentRequest represents a pending consent request shown to the user.

type ConsentStatusResponse 

type ConsentStatusResponse struct {
	Status      string `json:"status"` // pending, approved, denied, expired
	AccessToken string `json:"access_token,omitempty"`
	TokenType   string `json:"token_type,omitempty"`
	ExpiresIn   int    `json:"expires_in,omitempty"`
	Scope       string `json:"scope,omitempty"`
	Error       string `json:"error,omitempty"`
	ErrorDesc   string `json:"error_description,omitempty"`
}

ConsentStatusResponse is returned when polling for consent status.

type ErrorResponse 

type ErrorResponse struct {
	Error       string `json:"error"`
	Description string `json:"error_description,omitempty"`
}

ErrorResponse represents an OAuth-style error response.

type Mission 

type Mission struct {
	ID              string        `json:"id"`
	AgentID         string        `json:"agent_id"`
	UserID          string        `json:"user_id"`
	Name            string        `json:"name"`
	Description     string        `json:"description,omitempty"`
	Scopes          string        `json:"scopes"`
	InteractionType string        `json:"interaction_type"`
	Status          MissionStatus `json:"status"`
	Duration        int64         `json:"duration"`
	ExpiresAt       *time.Time    `json:"expires_at,omitempty"`
	ApprovedAt      *time.Time    `json:"approved_at,omitempty"`
	DeniedAt        *time.Time    `json:"denied_at,omitempty"`
	DenialReason    string        `json:"denial_reason,omitempty"`
	CreatedAt       time.Time     `json:"created_at"`
	UpdatedAt       time.Time     `json:"updated_at"`
}

Mission represents an agent's request to act on behalf of a user.

func (*Mission) IsActive 

func (m *Mission) IsActive() bool

IsActive returns true if the mission is currently active.

type MissionStatus 

type MissionStatus string

MissionStatus represents the status of a mission request. 

const (
	MissionStatusPending  MissionStatus = "pending"
	MissionStatusApproved MissionStatus = "approved"
	MissionStatusDenied   MissionStatus = "denied"
	MissionStatusExpired  MissionStatus = "expired"
	MissionStatusRevoked  MissionStatus = "revoked"
)

Mission statuses.

type Option 

type Option func(*Server)

Option configures the Server.

func WithLogger 

func WithLogger(logger *slog.Logger) Option

WithLogger sets the logger.

func WithMissionTimeout 

func WithMissionTimeout(timeout time.Duration) Option

WithMissionTimeout sets the mission pending timeout.

func WithSigningMethod 

func WithSigningMethod(method jwt.SigningMethod) Option

WithSigningMethod sets the JWT signing method.

func WithTokenTTL 

func WithTokenTTL(ttl time.Duration) Option

WithTokenTTL sets the token TTL.

type PreAuthorization 

type PreAuthorization struct {
	ID        string `json:"id"`
	UserID    string `json:"user_id"`
	AgentID   string `json:"agent_id"`
	Scopes    string `json:"scopes"`
	CreatedAt string `json:"created_at"`
	ExpiresAt string `json:"expires_at,omitempty"`
}

PreAuthorization allows users to pre-approve certain scopes for agents.

type Server 

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

Server is the Person Server that handles human consent for agent authorization.

func New 

func New(store Store, issuer string, privateKey crypto.PrivateKey, keyID string, opts ...Option) (*Server, error)

New creates a new Person Server.

func (*Server) HandleAuthorize 

func (s *Server) HandleAuthorize(w http.ResponseWriter, r *http.Request)

HandleAuthorize handles authorization requests from agents (POST /authorize).

func (*Server) HandleConsentPage 

func (s *Server) HandleConsentPage(w http.ResponseWriter, r *http.Request)

HandleConsentPage renders the consent page for the user (GET /consent/{id}).

func (*Server) HandleConsentStatus 

func (s *Server) HandleConsentStatus(w http.ResponseWriter, r *http.Request)

HandleConsentStatus returns the consent status for polling (GET /consent/status/{id}).

func (*Server) HandleConsentSubmit 

func (s *Server) HandleConsentSubmit(w http.ResponseWriter, r *http.Request)

HandleConsentSubmit handles the user's consent decision (POST /consent/{id}).

func (*Server) HandleCreateAgent 

func (s *Server) HandleCreateAgent(w http.ResponseWriter, r *http.Request)

HandleCreateAgent creates a new agent (POST /admin/agents).

func (*Server) HandleCreateUser 

func (s *Server) HandleCreateUser(w http.ResponseWriter, r *http.Request)

HandleCreateUser creates a new user (POST /admin/users).

func (*Server) HandleJWKS 

func (s *Server) HandleJWKS(w http.ResponseWriter, r *http.Request)

HandleJWKS returns the public key set (/.well-known/jwks.json).

func (*Server) HandleListAgents 

func (s *Server) HandleListAgents(w http.ResponseWriter, r *http.Request)

HandleListAgents lists all agents (GET /admin/agents).

func (*Server) HandleListMissions 

func (s *Server) HandleListMissions(w http.ResponseWriter, r *http.Request)

HandleListMissions lists pending missions (GET /admin/missions).

func (*Server) HandleListUsers 

func (s *Server) HandleListUsers(w http.ResponseWriter, r *http.Request)

HandleListUsers lists all users (GET /admin/users).

func (*Server) HandleMetadata 

func (s *Server) HandleMetadata(w http.ResponseWriter, r *http.Request)

HandleMetadata returns the server metadata (/.well-known/aauth-configuration).

func (*Server) HandleRevoke 

func (s *Server) HandleRevoke(w http.ResponseWriter, r *http.Request)

HandleRevoke handles token revocation (POST /revoke).

func (*Server) HandleToken 

func (s *Server) HandleToken(w http.ResponseWriter, r *http.Request)

HandleToken handles token requests (POST /token).

func (*Server) Handler 

func (s *Server) Handler() http.Handler

Handler returns an http.Handler that serves all Person Server endpoints. Use this when you want the Person Server to handle all routes.

func (*Server) Issuer 

func (s *Server) Issuer() string

Issuer returns the token issuer URL.

func (*Server) KeyID 

func (s *Server) KeyID() string

KeyID returns the key identifier.

func (*Server) PublicKey 

func (s *Server) PublicKey() crypto.PublicKey

PublicKey returns the server's public key.

func (*Server) RegisterHandlers 

func (s *Server) RegisterHandlers(mux *http.ServeMux)

RegisterHandlers registers all Person Server handlers on the given mux. This is a convenience method for registering all handlers at once.

func (*Server) Store 

func (s *Server) Store() Store

Store returns the underlying store.

type Store 

type Store interface {
	// Close closes the store connection.
	Close() error

	// User operations
	CreateUser(ctx context.Context, user *User) error
	GetUser(ctx context.Context, id string) (*User, error)
	GetUserByEmail(ctx context.Context, email string) (*User, error)
	ListUsers(ctx context.Context) ([]*User, error)

	// Agent operations
	CreateAgent(ctx context.Context, agent *Agent) error
	GetAgent(ctx context.Context, id string) (*Agent, error)
	ListAgents(ctx context.Context) ([]*Agent, error)

	// Mission operations
	CreateMission(ctx context.Context, mission *Mission) error
	GetMission(ctx context.Context, id string) (*Mission, error)
	ApproveMission(ctx context.Context, id string, duration time.Duration) error
	DenyMission(ctx context.Context, id, reason string) error
	ListPendingMissions(ctx context.Context) ([]*Mission, error)
	ListMissionsByUser(ctx context.Context, userID string) ([]*Mission, error)

	// Token operations
	CreateToken(ctx context.Context, token *Token) error
	GetToken(ctx context.Context, id string) (*Token, error)
	RevokeToken(ctx context.Context, id string) error
}

Store defines the interface for Person Server storage. Implementations can use SQLite, DynamoDB, PostgreSQL, etc.

type StoreError 

type StoreError string

StoreError represents storage errors. 

const (
	ErrNotFound      StoreError = "not found"
	ErrAlreadyExists StoreError = "already exists"
	ErrInvalidInput  StoreError = "invalid input"
)

Store errors.

func (StoreError) Error 

func (e StoreError) Error() string

type Token 

type Token struct {
	ID        string     `json:"id"`
	MissionID string     `json:"mission_id,omitempty"`
	AgentID   string     `json:"agent_id"`
	UserID    string     `json:"user_id"`
	Scopes    string     `json:"scopes"`
	TokenType string     `json:"token_type"`
	Protocol  string     `json:"protocol"`
	IssuedAt  time.Time  `json:"issued_at"`
	ExpiresAt time.Time  `json:"expires_at"`
	RevokedAt *time.Time `json:"revoked_at,omitempty"`
}

Token represents an issued auth token record.

func (*Token) IsValid 

func (t *Token) IsValid() bool

IsValid returns true if the token is still valid.

type TokenRequest 

type TokenRequest struct {
	GrantType    string `json:"grant_type"`
	MissionID    string `json:"mission_id,omitempty"`
	AgentToken   string `json:"agent_token,omitempty"`
	RefreshToken string `json:"refresh_token,omitempty"`
	Scope        string `json:"scope,omitempty"`
}

TokenRequest is the request to exchange an approval for a token.

type TokenResponse 

type TokenResponse struct {
	AccessToken  string `json:"access_token"`
	TokenType    string `json:"token_type"`
	ExpiresIn    int    `json:"expires_in"`
	Scope        string `json:"scope,omitempty"`
	RefreshToken string `json:"refresh_token,omitempty"`
}

TokenResponse is returned when a token is issued.

type User 

type User struct {
	ID        string    `json:"id"`
	Email     string    `json:"email"`
	Name      string    `json:"name"`
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

User represents a person who can authorize agents.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.