jwt

type Algorithm string

type Config struct {
	// Issuer defines the "iss" claim value included in generated tokens (default: "GoModularAuth").
	Issuer string

	// Audience defines the "aud" claim list validated and included in generated tokens.
	Audience []string

	// ExpirationTime defines the validity duration ("exp" claim) for issued tokens (default: 15 minutes).
	ExpirationTime time.Duration

	// Algorithm specifies the asymmetric signature algorithm to use (default: AlgEdDSA / Ed25519).
	Algorithm Algorithm

	// RSABits specifies the key size in bits when using RSA algorithms (RS256/PS256, default: 2048).
	RSABits int

	// RotationInterval defines how frequently active signing keys should be rotated (0 = rotation disabled).
	RotationInterval time.Duration

	// GracePeriod defines how long expired keys remain available in JWKS for token verification (default: 30 days).
	GracePeriod time.Duration

	// Secret defines the symmetric encryption key used to protect private keys in storage via AES-256-GCM.
	Secret string

	// DisablePrivateKeyEncryption specifies whether private keys should be stored unencrypted in repository.
	DisablePrivateKeyEncryption bool

	// ClockSkewLeeway defines the acceptable clock skew window during exp and nbf validation (default: 1 minute).
	ClockSkewLeeway time.Duration

	// DefinePayload is an optional custom callback to inject extra claims into session-based tokens.
	DefinePayload PayloadFunc

	// GetSubject is an optional custom callback to resolve the "sub" claim from session and user.
	GetSubject SubjectFunc
}

type GetJWKSParams struct {
	// IncludeExpired specifies whether to include keys older than the grace period (default: false).
	IncludeExpired bool `json:"include_expired,omitempty"`

	plugin.ExtraContainer
}

type GetJWKSResult struct {
	// JWKS is the RFC 7517 JSON Web Key Set containing active and grace-period public keys.
	JWKS *JWKS `json:"jwks"`

	// KeysCount is the number of public keys included.
	KeysCount int `json:"keys_count"`
}

type GetTokenParams struct {
	// Session is the active authenticated session (required).
	Session *entity.Session `json:"session"`

	// User is the authenticated user entity (optional, provides email/name for custom claims).
	User *entity.User `json:"user,omitempty"`

	// ExpiresIn overrides the default validity duration for this session token (optional).
	ExpiresIn time.Duration `json:"expires_in,omitempty"`

	plugin.ExtraContainer
}

type GetTokenResult struct {
	// Token is the issued compact JWT string.
	Token string `json:"token"`

	// KeyID is the key identifier used for the signature.
	KeyID string `json:"key_id"`

	// Algorithm is the cryptographic signature algorithm used.
	Algorithm Algorithm `json:"alg"`

	// ExpiresAt is the token expiration timestamp.
	ExpiresAt time.Time `json:"expires_at"`

	// HeaderValue is the formatted Authorization header string ("Bearer <token>").
	HeaderValue string `json:"header_value"`

	// AuthJWTHeader is the standard response header name ("set-auth-jwt").
	AuthJWTHeader string `json:"auth_jwt_header"`
}

type JWK struct {
	// Kty is the Key Type ("OKP", "EC", "RSA").
	Kty string `json:"kty"`

	// Kid is the unique Key ID string.
	Kid string `json:"kid"`

	// Use specifies the intended public key use (usually "sig").
	Use string `json:"use,omitempty"`

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

	// Crv identifies the cryptographic curve (for "OKP" and "EC" keys).
	Crv string `json:"crv,omitempty"`

	// X contains the Base64URL-encoded public key coordinate (or public Ed25519 key).
	X string `json:"x,omitempty"`

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

	// N contains the Base64URL-encoded RSA modulus.
	N string `json:"n,omitempty"`

	// E contains the Base64URL-encoded RSA exponent.
	E string `json:"e,omitempty"`
}

type JWKRecord struct {
	// ID is the unique Key ID ("kid") assigned to this key-pair.
	ID string `json:"id"`

	// PublicKey is the serialized JSON representation of the RFC 7517 public JWK.
	PublicKey string `json:"publicKey"`

	// PrivateKey is the serialized private key bytes or base64url-encoded AES-256-GCM ciphertext.
	PrivateKey string `json:"privateKey"`

	// Algorithm specifies the JWS signing algorithm (e.g. EdDSA, ES256, RS256).
	Algorithm Algorithm `json:"alg"`

	// Curve specifies the elliptic curve name for EC/OKP keys (e.g. "Ed25519", "P-256", "P-521").
	Curve string `json:"crv,omitempty"`

	// CreatedAt is the timestamp when the key-pair was generated.
	CreatedAt time.Time `json:"createdAt"`

	// ExpiresAt is the optional expiration timestamp after which this key is rotated out of active signing.
	ExpiresAt *time.Time `json:"expiresAt,omitempty"`
}

type JWKS struct {
	// Keys is the collection of public JSON Web Keys.
	Keys []JWK `json:"keys"`
}

type JWTHeader struct {
	Alg string `json:"alg"`
	Typ string `json:"typ"`
	Kid string `json:"kid"`
}

type JWTIssuedEventPayload struct {
	// Token is the issued compact JWT string.
	Token string

	// KeyID is the key identifier used for the signature.
	KeyID string

	// Subject is the "sub" claim value.
	Subject string

	// SessionID is the associated session identifier (if applicable).
	SessionID string

	// UserID is the associated user identifier (if applicable).
	UserID string
}

type JWTRotateAfterEventPayload struct {
	// NewKeyID is the identifier of the newly active key.
	NewKeyID string

	// Algorithm is the cryptographic algorithm of the new key.
	Algorithm Algorithm

	// CreatedAt is the timestamp when the new key was created.
	CreatedAt time.Time
}

type JWTRotateBeforeEventPayload struct {
	// CurrentKeyID is the active key ID being rotated out.
	CurrentKeyID string

	// Params contains rotation configuration parameters.
	Params *RotateKeysParams
}

type JWTSignAfterEventPayload struct {
	// Token is the serialized compact JWT string.
	Token string

	// KeyID is the ID of the key used to sign the token.
	KeyID string

	// Algorithm is the cryptographic algorithm used.
	Algorithm Algorithm

	// ExpiresAt is the token expiration timestamp.
	ExpiresAt time.Time
}

type JWTSignBeforeEventPayload struct {
	// Params contains the mutable signing parameters (including Extra metadata).
	Params *SignParams

	// Subject is the resolved subject string ("sub").
	Subject string

	// Claims contains mutable custom payload claims.
	Claims map[string]any
}

type JWTVerifyAfterEventPayload struct {
	// Token is the processed JWT string.
	Token string

	// Valid indicates whether the token signature and standard claims were valid.
	Valid bool

	// KeyID is the key ID extracted from the token header.
	KeyID string

	// Claims contains the unmarshaled payload claims (if valid).
	Claims map[string]any

	// Error contains the verification failure reason (if invalid).
	Error error
}

type JWTVerifyBeforeEventPayload struct {
	// Token is the raw JWT string to verify.
	Token string

	// Params contains mutable verification parameters.
	Params *VerifyParams
}

type Option func(*Config)

type PayloadFunc func(session *entity.Session, user *entity.User) (map[string]any, error)

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

type Repository interface {
	// GetLatestKey retrieves the most recently created signing key record.
	//
	// Function:
	//   Used during initialization and token signing to acquire the active private key.
	//
	// Storage:
	//   Both (Cache-Aside Strategy) - Cached in memory/Redis to eliminate DB lookups per token signing.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//
	// Returns:
	//   - *JWKRecord: The latest active key record.
	//   - error: ErrKeyNotFound if no keys exist, or database error.
	//
	// Example SQL:
	//   SELECT id, public_key, private_key, alg, crv, created_at, expires_at FROM jwks ORDER BY created_at DESC LIMIT 1;
	//
	// Example Cache (In-Memory/Redis):
	//   val, err := rdb.Get(ctx, "jwks:latest").Bytes()
	GetLatestKey(ctx context.Context) (*JWKRecord, error)

	// GetKeyByID retrieves a specific key-pair record by its unique Key ID ("kid").
	//
	// Function:
	//   Used during token verification to locate the public/private key matching the token's header 'kid'.
	//
	// Storage:
	//   Both (Cache-Aside Strategy) - Cached in memory/Redis by kid.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - id: Unique Key ID string ("kid").
	//
	// Returns:
	//   - *JWKRecord: The matching key record.
	//   - error: ErrKeyNotFound if not found, or database error.
	//
	// Example SQL:
	//   SELECT id, public_key, private_key, alg, crv, created_at, expires_at FROM jwks WHERE id = $1 LIMIT 1;
	//
	// Example Cache (In-Memory/Redis):
	//   val, err := rdb.Get(ctx, "jwks:kid:" + id).Bytes()
	GetKeyByID(ctx context.Context, id string) (*JWKRecord, error)

	// GetAllKeys retrieves all persisted key records.
	//
	// Function:
	//   Used to assemble the public JWKS exposed to clients and microservices.
	//
	// Storage:
	//   Database (GORM / SQL) - Relational key set persistence.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//
	// Returns:
	//   - []*JWKRecord: Slice of all key records.
	//   - error: Database error if query fails.
	//
	// Example SQL:
	//   SELECT id, public_key, private_key, alg, crv, created_at, expires_at FROM jwks ORDER BY created_at DESC;
	GetAllKeys(ctx context.Context) ([]*JWKRecord, error)

	// CreateKey stores a newly generated key-pair record.
	//
	// Function:
	//   Invoked during initial bootstrap or key rotation to persist the new key pair.
	//
	// Storage:
	//   Database (GORM / SQL) - Persistent storage for cryptographic key pairs.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - record: Key pair record containing public JWK JSON and (optionally encrypted) private key.
	//
	// Returns:
	//   - error: Database error if insert fails.
	//
	// Example SQL:
	//   INSERT INTO jwks (id, public_key, private_key, alg, crv, created_at, expires_at) VALUES ($1, $2, $3, $4, $5, $6, $7);
	CreateKey(ctx context.Context, record *JWKRecord) error

	// DeleteKey deletes a key-pair record by its Key ID.
	//
	// Function:
	//   Optional maintenance operation for purging revoked or expired keys.
	//
	// Storage:
	//   Database (GORM / SQL) - Persistent record removal.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - id: Unique Key ID string to delete.
	//
	// Returns:
	//   - error: Database error if deletion fails.
	//
	// Example SQL:
	//   DELETE FROM jwks WHERE id = $1;
	DeleteKey(ctx context.Context, id string) error
}

type RotateKeysParams struct {
	// Algorithm optionally specifies a different algorithm for the new key (optional).
	Algorithm Algorithm `json:"alg,omitempty"`

	// RSABits optionally specifies the RSA bit length if rotating to an RSA key (optional).
	RSABits int `json:"rsa_bits,omitempty"`

	// ExpiresIn optionally sets an expiration date for the old active key (optional).
	ExpiresIn time.Duration `json:"expires_in,omitempty"`

	plugin.ExtraContainer
}

type RotateKeysResult struct {
	// NewKey is the persisted record of the new active key pair.
	NewKey *JWKRecord `json:"new_key"`

	// JWK is the public JWK representation of the new key.
	JWK *JWK `json:"jwk"`

	// OldKeyID is the Key ID of the rotated previous key (if one was active).
	OldKeyID string `json:"old_key_id,omitempty"`
}

type SignParams struct {
	// Payload contains custom application claims to include in the token (optional).
	Payload map[string]any `json:"payload,omitempty"`

	// Subject sets the "sub" claim value (optional, overrides default).
	Subject string `json:"subject,omitempty"`

	// Issuer overrides the default configured "iss" claim value (optional).
	Issuer string `json:"issuer,omitempty"`

	// Audience overrides the default configured "aud" claim list (optional).
	Audience []string `json:"audience,omitempty"`

	// ExpiresIn overrides the default validity duration for this specific token (optional).
	ExpiresIn time.Duration `json:"expires_in,omitempty"`

	// NotBefore optionally sets the "nbf" claim timestamp (optional).
	NotBefore *time.Time `json:"not_before,omitempty"`

	// KeyID explicitly specifies which persisted key to use for signing (optional; uses active key if empty).
	KeyID string `json:"key_id,omitempty"`

	plugin.ExtraContainer
}

type SignResult struct {
	// Token is the serialized RFC 7519 compact JWT string.
	Token string `json:"token"`

	// KeyID is the ID of the key that signed the token.
	KeyID string `json:"key_id"`

	// Algorithm is the cryptographic signature algorithm used.
	Algorithm Algorithm `json:"alg"`

	// ExpiresAt is the calculated expiration timestamp.
	ExpiresAt time.Time `json:"expires_at"`

	// HeaderValue is the formatted Authorization header string ("Bearer <token>").
	HeaderValue string `json:"header_value"`

	// AuthJWTHeader is the standard response header name ("set-auth-jwt").
	AuthJWTHeader string `json:"auth_jwt_header"`
}

type SubjectFunc func(session *entity.Session, user *entity.User) (string, error)

type VerifyParams struct {
	// Token is the compact JWT string or authorization header value (required).
	Token string `json:"token"`

	// Issuer optionally enforces an expected "iss" claim match during verification.
	Issuer string `json:"issuer,omitempty"`

	// Audience optionally enforces expected "aud" claim recipients.
	Audience []string `json:"audience,omitempty"`

	// Leeway overrides the clock skew tolerance window for exp/nbf validation (optional).
	Leeway time.Duration `json:"leeway,omitempty"`

	plugin.ExtraContainer
}

type VerifyResult struct {
	// Valid indicates whether the signature and standard claims are valid.
	Valid bool `json:"valid"`

	// Subject is the "sub" claim extracted from the payload.
	Subject string `json:"subject,omitempty"`

	// Claims contains all claims present in the token payload.
	Claims map[string]any `json:"claims"`

	// KeyID is the "kid" identifier of the key used to verify the signature.
	KeyID string `json:"key_id"`

	// Algorithm is the cryptographic algorithm specified in the JWS header.
	Algorithm Algorithm `json:"alg"`

	// ExpiresAt is the expiration time parsed from the "exp" claim (if present).
	ExpiresAt *time.Time `json:"expires_at,omitempty"`

	// IssuedAt is the timestamp parsed from the "iat" claim (if present).
	IssuedAt *time.Time `json:"issued_at,omitempty"`

	// NotBefore is the timestamp parsed from the "nbf" claim (if present).
	NotBefore *time.Time `json:"not_before,omitempty"`
}