jwt

type Claims struct {
	Sub    string `json:"sub"`
	Email  string `json:"email"`
	Name   string `json:"name"`
	Role   string `json:"role"`
	Tenant string `json:"tenant"`
	// Project is the control-plane project the token was minted for. It
	// scopes the token to one project so a token minted under project A is
	// rejected on a request resolved to project B (cross-project reuse).
	// Omitted from tokens minted before the project model (empty).
	Project   string   `json:"project,omitempty"`
	AvatarURL string   `json:"avatar_url"`
	SID       string   `json:"sid,omitempty"`
	Audience  []string `json:"aud,omitempty"`
	IssuedAt  int64    `json:"iat"`
	ExpiresAt int64    `json:"exp"`
}

type KeyProvider interface {
	// Keys returns every public key the provider currently advertises,
	// including keys past their ExpiresAt (so in-flight tokens still
	// verify). The slice MUST NOT be nil; it MAY be empty during
	// rotation only if the provider has no usable keys (which the
	// caller treats as a fatal condition at startup).
	//
	// Order is implementation-defined but stable for a given snapshot.
	Keys() []PublicKey

	// Get returns the public key for the supplied kid, or false when
	// no such key is published. Includes expired-but-not-yet-removed
	// keys, so the verifier can still validate tokens minted before
	// rotation completed.
	Get(kid string) (*rsa.PublicKey, bool)
}

type PublicKey struct {
	// KID is the JWS "kid" header value stamped on tokens this key signs.
	KID string

	// Key is the RSA public key. Always non-nil for keys returned from
	// [KeyProvider.Keys].
	Key *rsa.PublicKey

	// NotBefore is the earliest moment this key is allowed to sign new
	// tokens. Zero means "no lower bound".
	NotBefore time.Time

	// ExpiresAt is the moment after which the key must no longer sign
	// new tokens. Zero means "never expires". A key past its ExpiresAt
	// still participates in verification (so tokens minted before
	// expiry remain valid until their own [Claims.ExpiresAt]) until the
	// key is removed from the provider entirely.
	ExpiresAt time.Time
}

type Signer interface {
	KeyProvider

	// ActiveKID returns the kid the signer stamps on new tokens. It is
	// the kid of the currently-active key. Empty result indicates a
	// misconfigured signer (no usable active key); callers must treat
	// this as a fatal condition at startup.
	ActiveKID() string

	// SignAccessToken builds a standard access-token JWT from claims,
	// stamps iat/exp, signs with the active key, and returns the
	// compact-serialized JWS string.
	SignAccessToken(ctx context.Context, claims Claims, expiry time.Duration) (string, error)

	// SignClaims is the generic primitive: serialize the supplied claim
	// map as a JWT, sign with the active key, return the compact JWS.
	// Use this for non-access-token JWTs (e.g. OAuth state tokens).
	// Claim names follow the standard JWT/JWS conventions ("iat",
	// "exp", custom names).
	SignClaims(ctx context.Context, claims map[string]any) (string, error)
}