oauth2server

type AccessToken struct {
	IssuedAt  time.Time
	ExpiresAt time.Time

	// RevokedAt is when the token was revoked, or the zero time. Revocation is
	// recorded rather than deleting the row so that a sweep and a revocation
	// are different events, and so that the row survives long enough for a
	// resource server's next request to be answered "no" rather than "never
	// heard of it".
	RevokedAt time.Time

	Hash     string
	ClientID string

	// FamilyID ties this token to the refresh-token family it was minted
	// under, so revoking the family revokes it.
	FamilyID string

	Subject Subject

	Scopes []string

	// Audience is the RFC 8707 resource this token is for. A resource server
	// that finds its own identifier absent must refuse the token: that check
	// is the reason resource indicators exist, and this package cannot make it
	// on the resource server's behalf.
	Audience []string
}

type AuthorizationCode struct {
	IssuedAt  time.Time
	ExpiresAt time.Time

	// RedeemedAt is when the code was consumed, or the zero time. It is what
	// makes a second redemption detectable rather than merely unsuccessful.
	RedeemedAt time.Time

	// Hash is the hex-encoded SHA-256 digest of the code. It is the store's
	// primary key.
	Hash string

	ClientID string

	// RedirectURI is the one the authorization request nominated, re-checked at
	// the token endpoint. A code issued for one URI cannot be redeemed by
	// naming another.
	RedirectURI string

	// CodeChallenge is the S256 challenge the code is bound to. Never empty —
	// PKCE is mandatory.
	CodeChallenge string

	// Nonce is echoed into the token record for an OpenID-shaped caller that
	// wants it. This package does not issue ID tokens and does not interpret
	// it.
	Nonce string

	Subject Subject

	Scopes []string

	// Resources are the RFC 8707 resource indicators the authorization request
	// asked for. They become the access token's audience, which is what stops
	// a token minted for one resource server being replayed at another.
	Resources []string
}

type AuthorizationServerMetadata struct {
	Issuer                            string   `json:"issuer"`
	AuthorizationEndpoint             string   `json:"authorization_endpoint"`
	TokenEndpoint                     string   `json:"token_endpoint"`
	RegistrationEndpoint              string   `json:"registration_endpoint"`
	RevocationEndpoint                string   `json:"revocation_endpoint"`
	ServiceDocumentation              string   `json:"service_documentation,omitempty"`
	ScopesSupported                   []string `json:"scopes_supported,omitempty"`
	ResponseTypesSupported            []string `json:"response_types_supported"`
	GrantTypesSupported               []string `json:"grant_types_supported"`
	TokenEndpointAuthMethodsSupported []string `json:"token_endpoint_auth_methods_supported"`

	// CodeChallengeMethodsSupported lists S256 and nothing else, which is also
	// how a client discovers that PKCE is not optional here.
	CodeChallengeMethodsSupported []string `json:"code_challenge_methods_supported"`

	RevocationEndpointAuthMethodsSupported []string `json:"revocation_endpoint_auth_methods_supported"`

	// AuthorizationResponseIssParameterSupported reports that every
	// authorization response carries the "iss" parameter (RFC 9207), which is
	// what lets a client with more than one authorization server tell which one
	// answered. A client holding two servers and no iss cannot detect a mix-up
	// attack.
	AuthorizationResponseIssParameterSupported bool `json:"authorization_response_iss_parameter_supported"`
}

type Client struct {
	// CreatedAt is when the registration was accepted.
	CreatedAt time.Time

	// ExpiresAt is when the registration lapses, or the zero time for a
	// registration that does not.
	//
	// Dynamic registration is open by construction — RFC 7591 requires it for
	// the discovery flow to work at all — so the table it writes to has an
	// anonymous writer. An expiry is what keeps that table bounded without
	// requiring anybody to decide which rows are garbage: a client that is
	// still in use re-registers, and one that is not ages out.
	ExpiresAt time.Time

	// ID is the client_id. Minted by the server from crypto/rand.
	ID string

	// SecretHash is the SHA-256 digest of the client secret, hex-encoded, or
	// empty for a public client.
	//
	// SHA-256 rather than argon2, and that is not a shortcut. A client secret
	// is 256 bits minted by this server, so there is no dictionary to attack
	// and nothing a work factor would buy; what it would cost is an argon2
	// verification on every single token request. Passwords are the opposite
	// case and go through authentication/argon2.
	SecretHash string

	// Name is the client_name from the registration request, shown on the
	// consent form. Cosmetic, and attacker-supplied — render it, never trust
	// it.
	Name string

	// TokenEndpointAuthMethod is how this client authenticates at /token: one
	// of AuthMethodNone, AuthMethodClientSecret, AuthMethodClientBasic.
	TokenEndpointAuthMethod string

	// RedirectURIs are the exact URIs this client may receive an authorization
	// code at. Matched exactly, byte for byte, as OAuth 2.1 requires: no
	// prefix matching, no wildcard, no ignored query string.
	RedirectURIs []string

	// GrantTypes and ResponseTypes are what the registration asked for,
	// narrowed to what this server implements.
	GrantTypes    []string
	ResponseTypes []string

	// Scopes are the scopes this client may request. An authorization request
	// for anything outside it is rejected rather than silently narrowed —
	// silently narrowing hands back a token that looks like the one that was
	// asked for and is not.
	Scopes []string
}

type LoginError struct {

	// Message is shown to the human. Write it for them.
	Message string
	// contains filtered or unexported fields
}

type LoginRenderer interface {
	RenderLogin(ctx context.Context, res http.ResponseWriter, view LoginView)
}

type LoginRendererFunc func(ctx context.Context, res http.ResponseWriter, view LoginView)

type LoginView struct {
	// Action is where the form posts: the /authorize URL with the original
	// query string intact. The authorization parameters travel in the query
	// rather than in hidden form fields so that the POST is validated against
	// exactly the same request the GET was.
	Action string

	// Error is the message to show, or empty on the first render.
	Error string

	// ClientName is the registered client_name, or the client_id if the
	// registration named none.
	ClientName string

	// Scopes are what the client asked for, so the human can see what they are
	// approving.
	Scopes []string
}

type Option func(*serverOptions)

type ProtectedResourceMetadata struct {
	Resource               string   `json:"resource"`
	ResourceName           string   `json:"resource_name,omitempty"`
	ResourceDocumentation  string   `json:"resource_documentation,omitempty"`
	AuthorizationServers   []string `json:"authorization_servers"`
	ScopesSupported        []string `json:"scopes_supported,omitempty"`
	BearerMethodsSupported []string `json:"bearer_methods_supported"`
}

type RefreshToken struct {
	IssuedAt  time.Time
	ExpiresAt time.Time

	// RedeemedAt is when this token was exchanged, or the zero time. One-time
	// use: a second exchange is a replay.
	RedeemedAt time.Time

	// RevokedAt is when this token was revoked, whether individually through
	// /revoke or as part of its family.
	RevokedAt time.Time

	Hash     string
	ClientID string
	FamilyID string

	Subject Subject

	Scopes    []string
	Audience  []string
	Resources []string
}

type RegistrationPolicy interface {
	// AllowRegistration vets a request. An error wrapping
	// ErrRegistrationRejected renders as a 400 with invalid_client_metadata
	// and the error's message; anything else is a 500.
	AllowRegistration(ctx context.Context, req *RegistrationRequest) error
}

type RegistrationPolicyFunc func(ctx context.Context, req *RegistrationRequest) error

type RegistrationRequest struct {
	ClientName              string   `json:"client_name,omitempty"`
	TokenEndpointAuthMethod string   `json:"token_endpoint_auth_method,omitempty"`
	Scope                   string   `json:"scope,omitempty"`
	RedirectURIs            []string `json:"redirect_uris"`
	GrantTypes              []string `json:"grant_types,omitempty"`
	ResponseTypes           []string `json:"response_types,omitempty"`
}

type RegistrationResponse struct {
	ClientID     string `json:"client_id"`
	ClientSecret string `json:"client_secret,omitempty"`
	ClientName   string `json:"client_name,omitempty"`

	Scope                   string `json:"scope,omitempty"`
	TokenEndpointAuthMethod string `json:"token_endpoint_auth_method"`

	RedirectURIs  []string `json:"redirect_uris"`
	GrantTypes    []string `json:"grant_types"`
	ResponseTypes []string `json:"response_types"`

	// ClientIDIssuedAt and ClientSecretExpiresAt are seconds since the epoch,
	// as RFC 7591 specifies. Zero for ClientSecretExpiresAt means the secret
	// does not expire.
	ClientIDIssuedAt      int64 `json:"client_id_issued_at"`
	ClientSecretExpiresAt int64 `json:"client_secret_expires_at"`
}

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

type ResourceOption func(*ProtectedResourceMetadata)

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

type Store interface {
	// CreateClient records a registration. An identifier already in use is
	// ErrClientExists rather than an overwrite: registrations are created by
	// anonymous callers, and a silent overwrite would let one of them take over
	// another's client by guessing an identifier.
	CreateClient(ctx context.Context, client *Client) error

	// GetClient reads a registration. A registration past its ExpiresAt is
	// ErrExpired, not a value the caller has to check.
	GetClient(ctx context.Context, clientID string) (*Client, error)

	// DeleteClient removes a registration. A registration that was already
	// gone is not an error — the caller wanted it gone.
	DeleteClient(ctx context.Context, clientID string) error

	// CreateAuthorizationCode records an issued code.
	CreateAuthorizationCode(ctx context.Context, code *AuthorizationCode) error

	// ConsumeAuthorizationCode marks the code redeemed and returns it, in one
	// atomic operation.
	//
	// A code that was already redeemed returns the record *and*
	// ErrAlreadyRedeemed. The record is not a courtesy: RFC 6749 §4.1.2 says a
	// replayed code should revoke what it previously issued, and the caller
	// cannot find those tokens without knowing which family the code belongs
	// to.
	ConsumeAuthorizationCode(ctx context.Context, hash string) (*AuthorizationCode, error)

	// CreateAccessToken records an issued access token.
	CreateAccessToken(ctx context.Context, token *AccessToken) error

	// GetAccessToken reads an access token. Expired or revoked is ErrExpired —
	// a resource server asking about a token it holds wants a straight answer,
	// and "expired" and "revoked" are the same answer to it.
	GetAccessToken(ctx context.Context, hash string) (*AccessToken, error)

	// RevokeAccessToken marks one access token revoked. A token that is absent
	// or already revoked is not an error: RFC 7009 §2.2 requires the
	// revocation endpoint to answer 200 either way, and a store that
	// distinguished them would be inviting the endpoint to leak which tokens
	// exist.
	RevokeAccessToken(ctx context.Context, hash string) error

	// CreateRefreshToken records an issued refresh token.
	CreateRefreshToken(ctx context.Context, token *RefreshToken) error

	// ConsumeRefreshToken marks the token redeemed and returns it, in one
	// atomic operation. As with ConsumeAuthorizationCode, a replay returns the
	// record alongside ErrAlreadyRedeemed so that the family can be revoked.
	ConsumeRefreshToken(ctx context.Context, hash string) (*RefreshToken, error)

	// GetRefreshToken reads a refresh token without consuming it.
	//
	// It exists for /revoke, which needs the record to learn whose token this
	// is and which family to end — and must not spend the token to find out.
	// An already-redeemed token is still returned: a sign-out arriving after a
	// rotation is the ordinary case, and the family it names is exactly what
	// needs revoking. Expired or revoked is ErrExpired.
	GetRefreshToken(ctx context.Context, hash string) (*RefreshToken, error)

	// RevokeRefreshToken marks one refresh token revoked, without touching the
	// rest of its family. This is what /revoke does; RevokeFamily is what a
	// detected replay does.
	RevokeRefreshToken(ctx context.Context, hash string) error

	// RevokeFamily revokes every access and refresh token in a family and
	// reports how many records it touched.
	//
	// The count is for the caller's metric, not its control flow — a family
	// whose tokens have all expired legitimately revokes nothing.
	RevokeFamily(ctx context.Context, familyID string) (int64, error)

	// Sweep removes records whose deadlines have passed as of now, reporting
	// how many it removed.
	//
	// It is a garbage collector, not a security control: every read above
	// already refuses an expired record, so a row this has not reached yet is
	// unusable. What it stops is the table growing with every code ever
	// issued, which under dynamic registration is a table an anonymous caller
	// can add to.
	Sweep(ctx context.Context, now time.Time) (int64, error)

	// Close releases whatever the implementation holds.
	Close() error
}

type Subject struct {
	// Claims is the application-shaped part of a token's identity. Nil is
	// fine; an empty map and a nil map mean the same thing.
	Claims map[string]string

	// ID is the "sub" claim. Required — a token with no subject authorizes
	// nobody, and the store rejects it.
	ID string
}

type SubjectAuthenticator interface {
	AuthenticateSubject(ctx context.Context, req *http.Request) (*Subject, error)
}

type SubjectAuthenticatorFunc func(ctx context.Context, req *http.Request) (*Subject, error)

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