jwt

type Algorithm string

type Audience []string

type Claims struct {
	// Issuer (iss) identifies the principal that issued the JWT.
	Issuer string `json:"iss,omitempty"`

	// Subject (sub) identifies the principal that is the subject of the JWT.
	Subject string `json:"sub,omitempty"`

	// Audience (aud) identifies the recipients that the JWT is intended for.
	Audience Audience `json:"aud,omitempty"`

	// ExpiresAt (exp) identifies the expiration time on or after which the JWT MUST NOT be accepted.
	ExpiresAt *NumericDate `json:"exp,omitempty"`

	// NotBefore (nbf) identifies the time before which the JWT MUST NOT be accepted.
	NotBefore *NumericDate `json:"nbf,omitempty"`

	// IssuedAt (iat) identifies the time at which the JWT was issued.
	IssuedAt *NumericDate `json:"iat,omitempty"`

	// ID (jti) provides a unique identifier for the JWT.
	ID string `json:"jti,omitempty"`

	// Custom contains additional non-standard application claims.
	Custom map[string]any `json:"-"`
}

type Config struct {
	// Issuer defines the default issuer string applied to issued tokens.
	Issuer string

	// DefaultAudience specifies the default audience list applied when claims.Audience is empty.
	DefaultAudience []string

	// DefaultTTL specifies the default token validity duration when ExpiresAt is not explicitly provided.
	DefaultTTL time.Duration

	// AllowedAlgorithms is the strict whitelist of algorithms permitted for verification.
	AllowedAlgorithms []Algorithm

	// KeyManager manages cryptographic keys, key rotation, and kid resolution.
	KeyManager KeyManager

	// Cache accelerates revocation verification lookups.
	Cache jwtcache.RevocationCache

	// Leeway provides clock skew tolerance during expiration (exp) and not-before (nbf) validation.
	Leeway time.Duration

	// Hooks provides lifecycle extension points for issue, verify, and revoke operations.
	Hooks *Hooks
}

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

type JWK struct {
	// Kty is the key type: RSA, EC, or OKP.
	Kty string `json:"kty"`

	// Use is the intended public key use: "sig".
	Use string `json:"use,omitempty"`

	// Kid is the key identifier.
	Kid string `json:"kid,omitempty"`

	// Alg is the algorithm intended for use with the key.
	Alg string `json:"alg,omitempty"`

	// Crv is the cryptographic curve for EC or OKP keys (e.g., "P-256", "Ed25519").
	Crv string `json:"crv,omitempty"`

	// X is the x coordinate for EC keys, or public key for OKP keys (base64url-encoded).
	X string `json:"x,omitempty"`

	// Y is the y coordinate for EC keys (base64url-encoded).
	Y string `json:"y,omitempty"`

	// N is the RSA modulus (base64url-encoded).
	N string `json:"n,omitempty"`

	// E is the RSA public exponent (base64url-encoded).
	E string `json:"e,omitempty"`
}

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

type JWT interface {
	// Issue signs and issues a new JWT token using the active signing key.
	Issue(ctx context.Context, claims Claims) (string, error)

	// IssueWithKey signs and issues a new JWT token using a specific key identifier (kid).
	IssueWithKey(ctx context.Context, keyID string, claims Claims) (string, error)

	// Verify parses the token, validates the cryptographic signature, validates standard claims
	// (iss, aud, sub, exp, nbf), prevents algorithm confusion, and checks revocation if configured.
	Verify(ctx context.Context, tokenString string, opts ...VerifyOption) (*Claims, error)

	// Revoke invalidates a specific token identifier (jti) until its expiration time.
	Revoke(ctx context.Context, jti string, expiresAt time.Time, reason string) error

	// RevokeSubject invalidates all tokens issued to the given subject before the specified cutoff timestamp.
	RevokeSubject(ctx context.Context, subject string, cutoff time.Time, reason string) error

	// IsRevoked checks if a token or subject has been marked as revoked.
	IsRevoked(ctx context.Context, jti string, subject string, issuedAt time.Time) (bool, error)

	// JWKS exports the public keys formatted as an RFC 7517 JSON Web Key Set.
	JWKS(ctx context.Context) (*JWKS, error)

	// Keys returns the active KeyManager for key registration and rotation.
	Keys() KeyManager
}

type Key struct {
	// ID uniquely identifies the key (kid).
	ID string

	// Algorithm declares the single cryptographic algorithm permitted for this key (alg).
	Algorithm Algorithm

	// Use defines the intended use of the key (typically "sig").
	Use string

	// PrivateKey contains the private key material (*rsa.PrivateKey, *ecdsa.PrivateKey, ed25519.PrivateKey, or []byte).
	// May be nil for verification-only keys.
	PrivateKey any

	// PublicKey contains the public key material (*rsa.PublicKey, *ecdsa.PublicKey, ed25519.PublicKey, or []byte for HMAC).
	PublicKey any

	// CreatedAt records when the key was created or added.
	CreatedAt time.Time
}

type KeyManager interface {
	// AddKey registers a key.
	AddKey(key Key) error

	// SetActiveSigningKey designates the default key ID used for signing.
	SetActiveSigningKey(keyID string) error

	// RotateSigningKey registers a new signing key and immediately designates it as active.
	RotateSigningKey(newKey Key) error

	// GetKey retrieves a key by its ID.
	GetKey(keyID string) (Key, error)

	// GetActiveSigningKey returns the active signing key.
	GetActiveSigningKey() (Key, error)

	// GetVerificationKey retrieves the matching key and enforces algorithm compatibility.
	GetVerificationKey(kid string, requestedAlg Algorithm) (Key, error)

	// ListKeys returns all registered keys.
	ListKeys() []Key

	// RemoveKey removes a key by ID.
	RemoveKey(keyID string) error
}

type KeyRotatedPayload struct {
	PreviousKeyID string    `json:"previous_key_id,omitempty"`
	NewKeyID      string    `json:"new_key_id"`
	Algorithm     Algorithm `json:"algorithm"`
	Time          time.Time `json:"time"`
}

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

type NumericDate struct {
	time.Time
}

type Option func(*Config)

type RevocationRecord struct {
	JTI       string    `json:"jti"`
	Subject   string    `json:"subject,omitempty"`
	Reason    string    `json:"reason,omitempty"`
	ExpiresAt time.Time `json:"expires_at"`
	RevokedAt time.Time `json:"revoked_at"`
}

type SubjectRevocationRecord struct {
	Subject   string    `json:"subject"`
	Cutoff    time.Time `json:"cutoff"`
	Reason    string    `json:"reason,omitempty"`
	RevokedAt time.Time `json:"revoked_at"`
}

type TokenIssuedPayload struct {
	KeyID     string    `json:"key_id"`
	JTI       string    `json:"jti,omitempty"`
	Subject   string    `json:"subject,omitempty"`
	Issuer    string    `json:"issuer,omitempty"`
	Audience  []string  `json:"audience,omitempty"`
	ExpiresAt time.Time `json:"expires_at,omitempty"`
	IssuedAt  time.Time `json:"issued_at,omitempty"`
}

type TokenRevokedPayload struct {
	JTI       string    `json:"jti,omitempty"`
	Subject   string    `json:"subject,omitempty"`
	Reason    string    `json:"reason,omitempty"`
	RevokedAt time.Time `json:"revoked_at"`
}

type TokenVerifiedPayload struct {
	KeyID   string    `json:"key_id"`
	JTI     string    `json:"jti,omitempty"`
	Subject string    `json:"subject,omitempty"`
	Issuer  string    `json:"issuer,omitempty"`
	Time    time.Time `json:"time"`
}

type VerifyOption func(*verifyConfig)