requestprincipal

type Authenticator interface {
	Authenticate(r *http.Request) (*RequestPrincipal, error)
}

type AuthenticatorFunc func(r *http.Request) (*RequestPrincipal, error)

type Chain []Authenticator

type Challenger interface {
	Challenge(h http.Header)
}

type Error struct {
	// Status is the HTTP status (401 when zero).
	Status int
	// Header holds response headers, such as a challenge.
	Header http.Header
	// Code and Message form the default JSON body
	// {"code": ..., "message": ...}.
	Code    string
	Message string
	// Respond, when set, writes the whole response instead (after Header
	// is applied), for protocols with their own error bodies.
	Respond func(w http.ResponseWriter)
	// Err is the underlying cause, for logs.
	Err error
}

type Options struct {
	// Optional lets requests without credentials through without a
	// principal (handlers check FromContext). Invalid credentials are
	// still rejected.
	Optional bool
	// Logger receives internal errors. Default: slog.Default().
	Logger *slog.Logger
}

type Proof struct {
	// Method names the credential form (e.g. "access_token", "api_key",
	// "session", "aa-auth+jwt").
	Method string
	// Issuer is the party that issued the credential.
	Issuer string
	// Audience is the audience the credential was verified for.
	Audience string
	// TokenID is the credential's identifier (a JWT jti or an API key ID).
	TokenID string
	// KeyThumbprint is the RFC 7638 thumbprint of the key the request was
	// signed with, for proof-of-possession credentials.
	KeyThumbprint string
	// IssuedAt and ExpiresAt bound the credential, when it states them.
	IssuedAt  time.Time
	ExpiresAt time.Time
	// Params are further protocol-specific evidence (e.g. the signature's
	// covered components), by name.
	Params map[string]string
}

type RequestPrincipal struct {
	// PrincipalID is the stable identifier the application keys
	// authorization and records on: the app-local principal ID for
	// SystemAuth credentials, or an issuer-qualified subject for
	// credentials issued elsewhere (see the adapter's documentation).
	PrincipalID string
	// Type is the kind of party that made the request.
	Type Type
	// Subject is the credential's subject as its issuer states it. It is
	// unique within Proof.Issuer only.
	Subject string
	// Organization is the organization (tenant) the credential is scoped
	// to, when it is scoped to one.
	Organization string
	// Actor identifies the party that made the request when it is not
	// the subject: for an agent acting for a person, the agent.
	Actor string
	// Delegator identifies the party the actor acts for, when there is
	// one: for an agent acting for a person, the person.
	Delegator string
	// Mission identifies the task the credential was issued for, when
	// the protocol has one (AAuth: the mission's s256 digest).
	Mission string
	// Session identifies the authenticated session or grant: a BFF
	// session or an issued token's ID.
	Session string
	// Protocol is how the request authenticated (Protocol*).
	Protocol string
	// Proof is the verified evidence behind the principal.
	Proof Proof
	// Scopes are the scopes or grants the credential carries. Empty for
	// a session, which carries the principal's full access.
	Scopes []string
	// Claims are additional verified attributes, by name.
	Claims map[string]any
	// Native is the adapter's own, protocol-specific result (for example
	// *relyingparty.AuthenticatedPrincipal), for callers that need more
	// than the neutral view.
	Native any
}

type Type string