auth

type Asserted interface {
	Asserted() bool
}

type Authenticator interface {
	// Authenticate verifies r's credential (its Authorization header or
	// cookie, and any sender proof) and returns its Verified, or nil and an
	// error. It checks live: a credential whose sign-in was revoked, or whose
	// account is banned or deleted, is refused, not admitted until a token
	// expires. It admits people and applications alike.
	//
	// Its error matches ErrUnauthenticated when r carries no valid
	// credential, joined with ErrExpired, ErrRevoked or
	// ErrSenderProofRequired when that is why; ErrForbidden for a valid
	// credential the provider refuses here; ErrUnavailable when it could not
	// verify. It may be a *Challenge carrying the provider's headers.
	//
	// It is safe for concurrent use. A consumer calls it at most once per
	// request (a sender proof is spent once) and keeps the Verified for that
	// request alone; a provider whose own middleware already verified r's
	// credential reuses that verification.
	Authenticate(r *http.Request) (Verified, error)
}

type Bound interface {
	BoundScope() Scope
}

type Challenge struct {
	Err error
	// MaxAge is, with ErrStepUpRequired, how recent a sign-in the action
	// needs (RFC 9470 max_age); zero says nothing.
	MaxAge time.Duration
	// Header is set on the refusal, replacing Refuse's own values: a DPoP
	// challenge's WWW-Authenticate and DPoP-Nonce.
	Header http.Header
	// Metadata is the provider's challenge for its own client, such as its
	// step-up methods. Consumers return it unchanged and never read it.
	Metadata map[string]any
}

type Credential struct {
	Kind CredentialKind
	// ID names the credential when it has one: the session, device key or
	// API key, or a token's jti.
	ID string
	// contains filtered or unexported fields
}

type CredentialKind string

type Headers interface {
	// AllowedHeaders are the request headers a client sends credentials in
	// (Access-Control-Allow-Headers), such as Authorization and DPoP.
	AllowedHeaders() []string
	// ExposedHeaders are the response headers a client reads
	// (Access-Control-Expose-Headers), such as WWW-Authenticate and
	// DPoP-Nonce: every header a Challenge of the provider carries.
	ExposedHeaders() []string
}

type Identity struct {
	Issuer        string
	Subject       string
	SubjectKind   SubjectKind
	Invoker       Invoker
	Credential    Credential
	Email         string
	Username      string
	EmailVerified bool
}

type Invoker struct {
	Issuer string
	ID     string
}

type PermissionCatalog interface {
	KnownPermission(permission string) bool
}

type PermissionChecker interface {
	Can(ctx context.Context, scope Scope, permission string) (bool, error)
}

type RecentSignInChecker interface {
	CheckRecentSignIn(ctx context.Context) error
}

type Refusal struct {
	// Status is 401, 403 or 503.
	Status int
	// Header is set on the response: a 401's WWW-Authenticate challenge and
	// the provider's own headers.
	Header http.Header
	// Metadata is the provider's Challenge.Metadata, for the body.
	Metadata map[string]any
}

type Root interface {
	RootScope(ctx context.Context) (Scope, error)
}

type Scope struct {
	Authority string
	ID        string
}

type SubjectKind string

type Verified interface {
	Identity() Identity
}