aauth

type AAuthID struct {
	// Local is the local part of the identifier (before @).
	// Must contain only lowercase letters, digits, hyphens, underscores,
	// plus signs, and periods. Maximum 255 characters.
	Local string

	// Domain is the domain part of the identifier (after @).
	// Must be a valid domain name.
	Domain string
}

type AccessServerMetadata = AuthServerMetadata

type Actor struct {
	// Subject is the subject of the actor.
	Subject string `json:"sub"`

	// Issuer is the issuer of the actor's identity.
	Issuer string `json:"iss,omitempty"`

	// Actor is a nested actor for multi-level delegation.
	Actor *Actor `json:"act,omitempty"`
}

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

type AgentOption func(*agentOptions)

type AgentProviderMetadata struct {
	// AgentProvider is the Agent Provider URL.
	AgentProvider string `json:"agent_provider"`

	// JWKSURI is the URL to the Agent Provider's JWKS.
	JWKSURI string `json:"jwks_uri,omitempty"`

	// RegistrationEndpoint is the agent registration endpoint.
	RegistrationEndpoint string `json:"registration_endpoint,omitempty"`

	// DelegationEndpoint is the delegation endpoint for human-to-agent delegation.
	DelegationEndpoint string `json:"delegation_endpoint,omitempty"`

	// SigningAlgorithmsSupported lists supported signing algorithms.
	SigningAlgorithmsSupported []string `json:"signing_algs_supported,omitempty"`

	// AgentIDFormats lists supported agent ID formats.
	AgentIDFormats []string `json:"agent_id_formats_supported,omitempty"`

	// KeyTypesSupported lists supported key types.
	KeyTypesSupported []string `json:"key_types_supported,omitempty"`
}

type AgentToken struct {
	// Issuer is the agent provider URL.
	Issuer string `json:"iss"`

	// Subject is the AAuth ID of the agent (e.g., "aauth:calendar-bot@example.com").
	Subject string `json:"sub"`

	// Audience is the intended audience (typically the resource URL).
	Audience []string `json:"aud,omitempty"`

	// IssuedAt is when the token was issued.
	IssuedAt time.Time `json:"iat"`

	// ExpiresAt is when the token expires.
	ExpiresAt time.Time `json:"exp"`

	// JWTID is a unique identifier for the token.
	JWTID string `json:"jti,omitempty"`

	// CNF is the confirmation claim binding the token to a key (required).
	CNF *CNF `json:"cnf"`

	// DWK is the delegate well-known URL for the agent provider.
	DWK string `json:"dwk,omitempty"`

	// PS is the person server URL (optional).
	PS string `json:"ps,omitempty"`

	// Actor represents a delegation chain (optional).
	Actor *Actor `json:"act,omitempty"`

	// Claims contains any additional custom claims.
	Claims map[string]any `json:"-"`
}

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

type AuthServerMetadata struct {
	// Issuer is the authorization server's issuer identifier
	Issuer string `json:"issuer"`

	// TokenEndpoint is the URL of the token endpoint
	TokenEndpoint string `json:"token_endpoint"`

	// JWKSURI is the URL of the JSON Web Key Set document
	JWKSURI string `json:"jwks_uri"`

	// GrantTypesSupported lists the supported grant types
	GrantTypesSupported []string `json:"grant_types_supported,omitempty"`

	// TokenEndpointAuthMethodsSupported lists the client auth methods
	TokenEndpointAuthMethodsSupported []string `json:"token_endpoint_auth_methods_supported,omitempty"`

	// ScopesSupported lists the supported scopes
	ScopesSupported []string `json:"scopes_supported,omitempty"`

	// SubjectTokenTypesSupported lists supported subject_token_type values
	SubjectTokenTypesSupported []string `json:"subject_token_types_supported,omitempty"`

	// ActorTokenTypesSupported lists supported actor_token_type values
	ActorTokenTypesSupported []string `json:"actor_token_types_supported,omitempty"`
}

type AuthServerOption func(*authServerOptions)

type AuthToken struct {
	// Issuer is the authorization server (Person Server or Access Server) URL.
	Issuer string `json:"iss"`

	// Subject is the AAuth ID of the authorized agent.
	Subject string `json:"sub"`

	// Audience is the resource(s) the token authorizes access to.
	Audience []string `json:"aud"`

	// IssuedAt is when the token was issued.
	IssuedAt time.Time `json:"iat"`

	// ExpiresAt is when the token expires.
	ExpiresAt time.Time `json:"exp"`

	// JWTID is a unique identifier for the token.
	JWTID string `json:"jti,omitempty"`

	// CNF is the confirmation claim binding the token to a key (required).
	CNF *CNF `json:"cnf"`

	// Scope is the authorized scope(s).
	Scope string `json:"scope,omitempty"`

	// Actor represents the delegation chain (optional).
	Actor *Actor `json:"act,omitempty"`

	// MayAct indicates the entity may act on behalf of another.
	MayAct *Actor `json:"may_act,omitempty"`

	// Claims contains any additional custom claims.
	Claims map[string]any `json:"-"`
}

type CNF struct {
	// JWK contains the embedded public key (mutually exclusive with JKU/Kid).
	JWK json.RawMessage `json:"jwk,omitempty"`

	// JKU is a URL pointing to a JWK Set containing the key.
	JKU string `json:"jku,omitempty"`

	// Kid is the key ID for key lookup within a JWKS.
	Kid string `json:"kid,omitempty"`
}

type Challenge struct {
	// Scheme is the authentication scheme (always "AAuth").
	Scheme string

	// Realm is the protection realm.
	Realm string

	// Scope is the required scope (optional).
	Scope string

	// PersonServerURL is the person server URL (optional).
	PersonServerURL string

	// AccessServerURL is the access server URL (optional).
	AccessServerURL string

	// Error is an error code if the challenge is due to an error.
	Error string

	// ErrorDescription is a human-readable error description.
	ErrorDescription string
}

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

type DiscoveryOption func(*DiscoveryClient)

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

type ExchangeFlowType string

type HTTPClient interface {
	Do(req *http.Request) (*http.Response, error)
}

type JWK struct {
	// Key type (e.g., "EC", "RSA", "OKP")
	Kty string `json:"kty"`

	// Key ID
	Kid string `json:"kid,omitempty"`

	// Algorithm
	Alg string `json:"alg,omitempty"`

	// Key use (e.g., "sig", "enc")
	Use string `json:"use,omitempty"`

	// EC and OKP fields
	Crv string `json:"crv,omitempty"` // Curve: P-256, P-384, P-521, Ed25519
	X   string `json:"x,omitempty"`   // X coordinate (base64url)
	Y   string `json:"y,omitempty"`   // Y coordinate (base64url, EC only)

	// RSA fields
	N string `json:"n,omitempty"` // Modulus (base64url)
	E string `json:"e,omitempty"` // Exponent (base64url)
}

type JWKS struct {
	Keys []JWK `json:"keys"`
}

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

type KeyPair struct {
	PrivateKey crypto.PrivateKey
	PublicKey  crypto.PublicKey
	KeyID      string
	Algorithm  string
}

type PersonServerMetadata struct {
	// Issuer is the Person Server's issuer identifier.
	Issuer string `json:"issuer"`

	// TokenEndpoint is the URL of the token endpoint.
	TokenEndpoint string `json:"token_endpoint"`

	// JWKSURI is the URL of the JSON Web Key Set document.
	JWKSURI string `json:"jwks_uri"`

	// GrantTypesSupported lists the supported grant types.
	GrantTypesSupported []string `json:"grant_types_supported,omitempty"`

	// TokenEndpointAuthMethodsSupported lists the client auth methods.
	TokenEndpointAuthMethodsSupported []string `json:"token_endpoint_auth_methods_supported,omitempty"`

	// ScopesSupported lists the supported scopes.
	ScopesSupported []string `json:"scopes_supported,omitempty"`

	// SubjectTokenTypesSupported lists supported subject_token_type values.
	SubjectTokenTypesSupported []string `json:"subject_token_types_supported,omitempty"`

	// ActorTokenTypesSupported lists supported actor_token_type values.
	ActorTokenTypesSupported []string `json:"actor_token_types_supported,omitempty"`

	// DelegationSupported indicates if human-to-agent delegation is supported.
	DelegationSupported bool `json:"delegation_supported,omitempty"`

	// SigningAlgorithmsSupported lists supported signing algorithms.
	SigningAlgorithmsSupported []string `json:"signing_algs_supported,omitempty"`
}

type RequestVerificationResult struct {
	// AgentToken is the verified agent token.
	AgentToken *AgentToken

	// AuthToken is the verified auth token (if present).
	AuthToken *AuthToken

	// AgentID is the agent's identifier.
	AgentID *AAuthID

	// KeyID is the key ID used for signing.
	KeyID string
}

type ResourceMetadata struct {
	// Resource is the resource URL.
	Resource string `json:"resource"`

	// JWKSURI is the URL to the resource's JWKS.
	JWKSURI string `json:"jwks_uri,omitempty"`

	// PersonServerURI is the person server URL.
	PersonServerURI string `json:"person_server_uri,omitempty"`

	// AccessServerURI is the access server URL.
	AccessServerURI string `json:"access_server_uri,omitempty"`

	// ScopesSupported lists supported scopes.
	ScopesSupported []string `json:"scopes_supported,omitempty"`

	// SigningAlgorithmsSupported lists supported signing algorithms.
	SigningAlgorithmsSupported []string `json:"signing_algs_supported,omitempty"`
}

type ResourceOption func(*resourceOptions)

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

type ResourceToken struct {
	// Issuer is the resource URL.
	Issuer string `json:"iss"`

	// Subject is the AAuth ID of the agent.
	Subject string `json:"sub"`

	// Audience is the Person Server or Access Server URL.
	Audience []string `json:"aud"`

	// IssuedAt is when the token was issued.
	IssuedAt time.Time `json:"iat"`

	// ExpiresAt is when the token expires (typically short, < 5 minutes).
	ExpiresAt time.Time `json:"exp"`

	// JWTID is a unique identifier for the token.
	JWTID string `json:"jti,omitempty"`

	// AgentJKT is the JWK thumbprint of the agent's key.
	AgentJKT string `json:"agent_jkt"`

	// Agent is the agent identifier (AAuth ID).
	Agent string `json:"agent,omitempty"`

	// Scope is the requested scope.
	Scope string `json:"scope,omitempty"`

	// DWK is the delegate well-known URL.
	DWK string `json:"dwk,omitempty"`

	// Mission contains mission-specific claims (optional).
	Mission map[string]any `json:"mission,omitempty"`

	// Claims contains any additional custom claims.
	Claims map[string]any `json:"-"`
}

type ResourceTokenExchangeRequest struct {
	// AgentToken is the agent's identity token.
	AgentToken *AgentToken

	// AgentJKT is the agent's JWK thumbprint.
	AgentJKT string

	// Scope is the requested scope.
	Scope string
}

type ScopeHandler func(agentID *AAuthID, requestedScope string) (grantedScope string, err error)

type SigningTransport struct {
	// Base is the underlying transport. If nil, http.DefaultTransport is used.
	Base http.RoundTripper

	// Agent is the agent used for signing.
	Agent *Agent

	// AddAgentToken controls whether to add the agent token.
	// Default is true.
	AddAgentToken bool
}

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

type TokenErrorResponse struct {
	Error            string `json:"error"`
	ErrorDescription string `json:"error_description,omitempty"`
	ErrorURI         string `json:"error_uri,omitempty"`
}

type TokenExchangeContext struct {
	// Request is the original exchange request
	Request *TokenExchangeRequest

	// AgentToken is the verified agent token (if subject is agent token)
	AgentToken *AgentToken

	// ResourceToken is the verified resource token (if present)
	ResourceToken *ResourceToken

	// ActorToken is the verified actor token (if present)
	ActorToken *AgentToken

	// AgentID is the agent's identity
	AgentID *AAuthID

	// AgentCNF is the agent's confirmation claim
	AgentCNF *CNF
}

type TokenExchangeRequest struct {
	// GrantType must be "urn:ietf:params:oauth:grant-type:token-exchange"
	GrantType string `json:"grant_type"`

	// SubjectToken is the token being exchanged (agent token or resource token)
	SubjectToken string `json:"subject_token"`

	// SubjectTokenType identifies the type of subject_token
	SubjectTokenType string `json:"subject_token_type"`

	// ActorToken is the token representing the acting party (optional)
	ActorToken string `json:"actor_token,omitempty"`

	// ActorTokenType identifies the type of actor_token
	ActorTokenType string `json:"actor_token_type,omitempty"`

	// RequestedTokenType is the type of token being requested
	RequestedTokenType string `json:"requested_token_type,omitempty"`

	// Audience is the logical name of the target service
	Audience []string `json:"audience,omitempty"`

	// Scope is the desired scope of the requested token
	Scope string `json:"scope,omitempty"`

	// Resource is the URI of the target service or resource
	Resource []string `json:"resource,omitempty"`
}

type TokenExchangeResponse struct {
	// AccessToken is the issued token
	AccessToken string `json:"access_token"`

	// IssuedTokenType identifies the type of the issued token
	IssuedTokenType string `json:"issued_token_type"`

	// TokenType is the token type (usually "Bearer")
	TokenType string `json:"token_type"`

	// ExpiresIn is the lifetime in seconds
	ExpiresIn int `json:"expires_in,omitempty"`

	// Scope is the granted scope
	Scope string `json:"scope,omitempty"`

	// RefreshToken is an optional refresh token
	RefreshToken string `json:"refresh_token,omitempty"`
}

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

type TokenVerifier interface {
	// VerifyAgentToken verifies an agent token and returns the parsed token.
	VerifyAgentToken(ctx context.Context, tokenString string) (*AgentToken, error)

	// VerifyAuthToken verifies an auth token and returns the parsed token.
	VerifyAuthToken(ctx context.Context, tokenString string) (*AuthToken, error)

	// VerifyResourceToken verifies a resource token and returns the parsed token.
	VerifyResourceToken(ctx context.Context, tokenString string) (*ResourceToken, error)
}

type TokenVerifierOption func(*TokenVerifierOptions)

type TokenVerifierOptions struct {
	// PublicKey is the key used for verification.
	PublicKey crypto.PublicKey

	// KeyID is the expected key ID (optional).
	KeyID string

	// Issuer is the expected issuer (optional).
	Issuer string

	// Audience is the expected audience (optional).
	Audience string

	// AllowedAlgorithms restricts which algorithms are accepted.
	AllowedAlgorithms []string

	// ClockSkew is the allowed clock skew for expiration checking.
	ClockSkew time.Duration
}

type VerifiedHandler func(w http.ResponseWriter, r *http.Request, result *RequestVerificationResult)