jwt

type Claims struct {
	// UserID is the authenticated user's ID
	// Used for quick user lookup without database query
	UserID string `json:"user_id"`

	// TokenType indicates if this is an "access" or "refresh" token
	// Access tokens can be used for API requests
	// Refresh tokens can only be used to get new access tokens
	TokenType string `json:"token_type"`
}

type Config struct {
	// Issuer is the JWT "iss" claim identifying the token issuer.
	// Should be your application name or domain (e.g., "myapp.com").
	Issuer string

	// AccessTokenExpiry is how long access tokens remain valid.
	// Recommended: 15 minutes to 1 hour
	// Shorter = more secure, longer = fewer refresh requests
	AccessTokenExpiry time.Duration

	// RefreshTokenExpiry is how long refresh tokens remain valid.
	// Recommended: 7 days to 30 days
	// Shorter = more secure, longer = better UX (less frequent logins)
	RefreshTokenExpiry time.Duration

	// KeyRotationInterval is how often to rotate signing keys.
	// Recommended: 24 hours to 7 days
	// More frequent rotation limits the impact of key compromise.
	// Set to 0 to disable automatic rotation (manual rotation only).
	KeyRotationInterval time.Duration

	// KeySize is the RSA key size in bits (2048, 3072, or 4096).
	// Only used for RSA algorithm.
	// Recommended: 2048 (good balance of security and performance)
	// 4096 provides higher security but slower signing/verification.
	KeySize int

	// KeyAlgorithm indicates the signing algorithm.
	// Currently supported: "RSA" (uses RS256)
	// Future: ECDSA (ES256), HMAC (HS256) for symmetric keys
	KeyAlgorithm string

	// KeyRetention is how long to keep rotated keys in storage.
	// MUST be greater than the maximum token lifetime (RefreshTokenExpiry)
	// to ensure old tokens can still be verified.
	// Recommended: 30 days (covers refresh token lifetime + buffer)
	KeyRetention time.Duration
}

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

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

type JWK struct {
	// Kid is the Key ID (unique identifier for this key)
	// Used in JWT header to identify which key was used for signing
	// Format: timestamp-based or UUID
	Kid string `json:"kid"`

	// KeyData is the JSON-encoded JWK (includes public/private key material)
	// Stored as BYTEA/BLOB in database
	// For RSA: Contains n (modulus), e (exponent), d (private exponent)
	KeyData []byte `json:"keyData"`

	// Algorithm is the cryptographic algorithm (e.g., "RS256", "ES256")
	// Currently only RS256 (RSA with SHA-256) is supported
	Algorithm string `json:"algorithm"`

	// Use indicates the key purpose:
	//   - "sig": Signature/verification (most common)
	//   - "enc": Encryption/decryption (future feature)
	Use string `json:"use"`

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

	// ExpiresAt is when the key should be deleted from storage
	// Set to CreatedAt + KeyRetention duration
	// nil means the key never expires (not recommended)
	ExpiresAt *time.Time `json:"expiresAt,omitempty"`
}

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

type Provider interface {
	// GenerateTokenPair creates an access token + refresh token for a user.
	// Returns token strings and expiry times.
	GenerateTokenPair(userID string) (*TokenPair, error)

	// ValidateToken validates a JWT token and returns the claims.
	// Checks signature, expiry, issuer, and token type.
	ValidateToken(token string) (*Claims, error)

	// RefreshTokens validates a refresh token and generates a new token pair.
	// Old refresh token is invalidated (single-use refresh tokens).
	RefreshTokens(refreshToken string) (*TokenPair, error)

	// BlacklistToken adds a token to the blacklist (for logout/revocation).
	// Requires Redis for distributed blacklist.
	BlacklistToken(token string) error
}

type RefreshTokenRequest struct {
	RefreshToken string `json:"refresh_token"`
}

type Store interface {
	// GetCurrentJWK retrieves the most recent active key for signing.
	//
	// This is used during token generation to get the private key for signing.
	// Returns the newest non-expired key matching the algorithm and use.
	//
	// Parameters:
	//   - ctx: Context for cancellation and timeouts
	//   - algorithm: Key algorithm (e.g., "RS256")
	//   - use: Key use ("sig" for signing, "enc" for encryption)
	//
	// Returns:
	//   - jwk.Key: The most recent active key
	//   - error: Database errors or "key not found"
	//
	// Example:
	//
	//	privateKey, err := store.GetCurrentJWK(ctx, "RS256", "sig")
	//	if err != nil {
	//		// No active key - generate new one
	//	}
	GetCurrentJWK(ctx context.Context, algorithm, use string) (jwk.Key, error)

	// StoreJWK persists a JWK to the database with expiry.
	//
	// This is used during:
	//   - Initial key generation (plugin initialization)
	//   - Key rotation (periodic background job)
	//
	// The key is stored with an expiry time for automatic cleanup.
	// Expired keys are kept to verify old tokens until cleanup.
	//
	// Parameters:
	//   - ctx: Context for cancellation and timeouts
	//   - key: JWK to store (includes private/public key material)
	//   - algorithm: Key algorithm (e.g., "RS256")
	//   - use: Key use ("sig" or "enc")
	//   - expiresAt: When to delete this key (nil = never expires)
	//
	// Returns:
	//   - error: Database errors or duplicate key ID
	//
	// Example:
	//
	//	expiresAt := time.Now().Add(30 * 24 * time.Hour)
	//	err := store.StoreJWK(ctx, privateKey, "RS256", "sig", &expiresAt)
	StoreJWK(ctx context.Context, key jwk.Key, algorithm, use string, expiresAt *time.Time) error

	// DeleteExpiredJWKS removes all expired keys from storage.
	//
	// This is called periodically to clean up old keys that are no longer needed.
	// Only deletes keys where:
	//   - expires_at IS NOT NULL (keys with expiry set)
	//   - expires_at < NOW() (expiry time has passed)
	//
	// Note: Keys are kept past their "active" period to verify old tokens.
	// The expiry should be set to created_at + KeyRetention duration.
	//
	// Parameters:
	//   - ctx: Context for cancellation and timeouts
	//
	// Returns:
	//   - error: Database errors
	//
	// Example:
	//
	//	if err := store.DeleteExpiredJWKS(ctx); err != nil {
	//		log.Printf("Failed to cleanup expired keys: %v", err)
	//	}
	DeleteExpiredJWKS(ctx context.Context) error

	// ListJWKS returns all active (non-expired) keys.
	//
	// This is used by:
	//   - JWKS endpoint: Expose public keys for token verification
	//   - Token validation: Find key by kid (key ID) for signature verification
	//
	// Only returns keys where:
	//   - expires_at IS NULL (never expires), OR
	//   - expires_at > NOW() (not yet expired)
	//
	// Parameters:
	//   - ctx: Context for cancellation and timeouts
	//
	// Returns:
	//   - []JWK: List of active keys (includes both public and private keys)
	//   - error: Database errors
	//
	// Example:
	//
	//	keys, err := store.ListJWKS(ctx)
	//	for _, key := range keys {
	//		fmt.Printf("Key: %s, Algorithm: %s\n", key.Kid, key.Algorithm)
	//	}
	ListJWKS(ctx context.Context) ([]JWK, error)
}

type TokenPair struct {
	// AccessToken is the JWT access token (use for API requests)
	AccessToken string `json:"access_token"`

	// AccessExpiry is when the access token expires (UTC)
	AccessExpiry time.Time `json:"access_expiry"`

	// RefreshToken is the JWT refresh token (use to get new access token)
	RefreshToken string `json:"refresh_token"`

	// RefreshExpiry is when the refresh token expires (UTC)
	RefreshExpiry time.Time `json:"refresh_expiry"`
}

type TokenRequest struct {
	UserID string `json:"user_id"`
}