@juspay/neurolink
Version:
Universal AI Development Platform with working MCP integration, multi-provider support, voice (TTS/STT/realtime), and professional CLI. 58+ external MCP servers discoverable, multimodal file processing, RAG pipelines. Build, test, and deploy AI applicatio
1,141 lines (1,140 loc) • 35.9 kB
TypeScript
/**
* Auth-related type definitions for NeuroLink
*
* Canonical location for OAuth token storage types, token refresher contracts,
* and multi-provider authentication types.
* All auth type imports should reference this module (or the barrel re-export
* via src/lib/types/index.ts).
*/
import type { JsonValue, UnknownRecord } from "./common.js";
/**
* OAuth tokens structure for storage.
* Stricter version of OAuthTokens with required fields for persistent storage.
*/
export type StoredOAuthTokens = {
/** The access token for API authentication */
accessToken: string;
/** The refresh token for obtaining new access tokens (optional for some OAuth flows) */
refreshToken?: string;
/** Unix timestamp (ms) when the access token expires */
expiresAt: number;
/** Token type, typically "Bearer" */
tokenType: string;
/** Optional OAuth scopes granted */
scope?: string;
};
/**
* OAuth tokens structure (relaxed version for general use).
* Use StoredOAuthTokens when persisting (stricter — expiresAt and tokenType required).
*/
export type OAuthTokens = {
/** The access token for API authentication */
accessToken: string;
/** The refresh token for obtaining new access tokens */
refreshToken?: string;
/** Token expiration timestamp (Unix epoch) */
expiresAt?: number;
/** Token type (typically "Bearer") */
tokenType?: string;
/** OAuth scope granted */
scope?: string;
};
/**
* Token refresher function type.
* Takes a refresh token and returns new tokens.
*/
export type TokenRefresher = (refreshToken: string) => Promise<StoredOAuthTokens>;
/**
* Internal storage format for multi-provider tokens
*/
export type TokenStorageData = {
/** Version of the storage format */
version: string;
/** Last modified timestamp */
lastModified: number;
/** Tokens indexed by provider name */
providers: Record<string, StoredProviderTokens>;
};
/**
* Per-provider token storage structure
*/
export type StoredProviderTokens = {
/** The stored tokens */
tokens: StoredOAuthTokens;
/** When the tokens were stored */
createdAt: number;
/** When the tokens were last accessed */
lastAccessed: number;
/** Whether this provider's tokens are permanently disabled */
disabled?: boolean;
/** When the tokens were disabled (Unix ms) */
disabledAt?: number;
/** Reason the tokens were disabled (e.g., "refresh_failed") */
disabledReason?: string;
};
/**
* Supported authentication provider types
*/
export type AuthProviderType = "auth0" | "clerk" | "firebase" | "supabase" | "cognito" | "keycloak" | "workos" | "better-auth" | "oauth2" | "jwt" | "custom";
/**
* Authentication token types
*/
export type TokenType = "jwt" | "session" | "api-key" | "oauth";
/**
* User information from authentication
*/
export type AuthUser = {
/** Unique user identifier */
id: string;
/** User's email address */
email?: string;
/** User's display name */
name?: string;
/** Profile picture URL */
picture?: string;
/** User's roles */
roles: string[];
/** User's permissions */
permissions: string[];
/** Provider-specific user data */
providerData?: Record<string, JsonValue>;
/** Provider-specific metadata */
metadata?: UnknownRecord;
/** Organization/tenant ID for multi-tenant apps */
organizationId?: string;
/** Email verification status */
emailVerified?: boolean;
/** Account creation timestamp */
createdAt?: Date;
/** Last update timestamp */
updatedAt?: Date;
/** Last login timestamp */
lastLoginAt?: Date;
};
/**
* Session information
*/
export type AuthSession = {
/** Session identifier */
id: string;
/** Associated user */
user: AuthUser;
/** Session access token */
accessToken?: string;
/** Session refresh token */
refreshToken?: string;
/** Session creation time */
createdAt: Date;
/** Session expiration time */
expiresAt: Date;
/** Whether session is still valid */
isValid: boolean;
/** Last activity timestamp */
lastActivityAt?: Date;
/** IP address of session origin */
ipAddress?: string;
/** User agent string */
userAgent?: string;
/** Device fingerprint */
deviceId?: string;
/** Session metadata */
metadata?: UnknownRecord;
};
/**
* Token validation result
*/
export type TokenValidationResult = {
/** Whether the token is valid */
valid: boolean;
/** Decoded token payload */
payload?: UnknownRecord;
/** Associated user if token is valid */
user?: AuthUser;
/** Decoded token claims */
claims?: Record<string, JsonValue>;
/** Error message if invalid */
error?: string;
/** Error code for programmatic handling */
errorCode?: AuthErrorCode;
/** Token expiration time */
expiresAt?: Date;
/** Token type */
tokenType?: TokenType;
/** Token issuer */
issuer?: string;
/** Token audience */
audience?: string | string[];
};
/**
* Token claims extracted from JWT
*/
export type TokenClaims = {
/** Subject (user ID) */
sub?: string;
/** Issuer */
iss?: string;
/** Audience */
aud?: string | string[];
/** Expiration time */
exp?: number;
/** Issued at */
iat?: number;
/** Not before */
nbf?: number;
/** JWT ID */
jti?: string;
/** Email */
email?: string;
/** Email verified */
email_verified?: boolean;
/** Name */
name?: string;
/** Picture */
picture?: string;
/** Custom claims */
[key: string]: JsonValue | undefined;
};
/**
* JWKS (JSON Web Key Set) types
*/
export type JWK = {
kty: string;
kid?: string;
use?: string;
alg?: string;
n?: string;
e?: string;
x?: string;
y?: string;
crv?: string;
};
export type JWKS = {
keys: JWK[];
};
/**
* Token refresh result
*/
export type TokenRefreshResult = {
/** New access token */
accessToken: string;
/** New refresh token (if rotated) */
refreshToken?: string;
/** Token expiration in seconds */
expiresIn: number;
};
/**
* Session validation result
*/
export type SessionValidationResult = {
/** Whether the session is valid */
valid: boolean;
/** Validated session if valid */
session?: AuthSession;
/** Error message if validation failed */
error?: string;
/** Error code for programmatic handling */
errorCode?: AuthErrorCode;
/** Whether session was refreshed */
refreshed?: boolean;
};
/**
* Session storage interface
*/
export type SessionStorage = {
/** Get a session by ID */
get(sessionId: string): Promise<AuthSession | null>;
/** Save a session */
save(session: AuthSession): Promise<void>;
/** Delete a session */
delete(sessionId: string): Promise<void>;
/** Delete all sessions for a user */
deleteAllForUser(userId: string): Promise<void>;
/** Get all sessions for a user */
getForUser(userId: string): Promise<AuthSession[]>;
/** Check if a session exists */
exists(sessionId: string): Promise<boolean>;
/** Update session last activity */
touch(sessionId: string): Promise<void>;
/** Clear all sessions */
clear(): Promise<void>;
};
/**
* Authorization check result
*/
export type AuthorizationResult = {
/** Whether the user is authorized */
authorized: boolean;
/** User being authorized */
user?: AuthUser;
/** Required roles that were checked */
requiredRoles?: string[];
/** Required permissions that were checked */
requiredPermissions?: string[];
/** Reason for denial if not authorized */
reason?: string;
/** Missing permissions if denied */
missingPermissions?: string[];
/** Missing roles if denied */
missingRoles?: string[];
};
/**
* Authentication request context
*/
export type AuthRequestContext = {
/** HTTP method */
method?: string;
/** Request URL/path */
path?: string;
/** HTTP request headers */
headers: Record<string, string | string[] | undefined>;
/** Request cookies */
cookies?: Record<string, string>;
/** Query parameters */
query?: Record<string, string | string[] | undefined>;
/** Request body (if available) */
body?: unknown;
/** IP address */
ip?: string;
/** IP address (alias for session builders that expect this field) */
ipAddress?: string;
/** Request user agent */
userAgent?: string;
/** Request ID for tracing */
requestId?: string;
};
/**
* Enhanced request context with authenticated user.
*
* Extends AuthRequestContext so it can be passed wherever a plain
* request context is expected (e.g. RBAC middleware callbacks).
*/
export type AuthenticatedContext = AuthRequestContext & {
/** Authenticated user */
user: AuthUser;
/** Current session */
session?: AuthSession;
/** Original request context (for callers that embed it explicitly) */
request?: AuthRequestContext;
/** Authentication timestamp */
authenticatedAt?: Date;
/** Provider that performed authentication */
provider?: AuthProviderType;
/** Token used for authentication */
token?: string;
/** Token claims */
claims?: Record<string, JsonValue>;
};
/**
* Base authentication provider configuration.
*
* Contains the common fields shared by every provider-specific config variant.
* Provider-specific fields are added via intersection in {@link AuthProviderConfig}.
*/
export type BaseAuthProviderConfig = {
/** Provider type */
type: AuthProviderType;
/** Whether authentication is required */
required?: boolean;
/** Enable debug logging */
debug?: boolean;
/** Custom token validation options */
tokenValidation?: TokenValidationConfig;
/** Token extraction strategy */
tokenExtraction?: TokenExtractionStrategy;
/** Session configuration */
session?: SessionConfig;
/** RBAC configuration */
rbac?: RBACConfig;
/** Cache configuration */
cache?: AuthCacheConfig;
/** Provider-specific options (generic extensibility point) */
options?: UnknownRecord;
};
/**
* Token validation configuration
*/
export type TokenValidationConfig = {
/** Token issuer to validate against */
issuer?: string;
/** Token audience to validate against */
audience?: string | string[];
/** Clock tolerance in seconds for expiration checks */
clockTolerance?: number;
/** Custom claims to extract */
extractClaims?: string[];
/** Whether to validate token signature */
validateSignature?: boolean;
/** JWKS endpoint for signature verification */
jwksUri?: string;
/** Cache JWKS for this duration (ms) */
jwksCacheDuration?: number;
};
/**
* Auth cache configuration
*/
export type AuthCacheConfig = {
/** Enable caching */
enabled?: boolean;
/** Cache TTL in seconds */
ttl?: number;
/** Maximum cache entries */
maxEntries?: number;
/** Cache key prefix */
prefix?: string;
};
/**
* Token extraction configuration (detailed, used by middleware)
*/
export type TokenExtractionConfig = {
/** Extract from Authorization header (Bearer token) */
fromHeader?: {
name?: string;
prefix?: string;
};
/** Extract from cookie */
fromCookie?: {
name: string;
};
/** Extract from query parameter */
fromQuery?: {
name: string;
};
/** Custom extraction function */
custom?: (context: AuthRequestContext) => string | null | Promise<string | null>;
};
/**
* Token extraction configuration (simple strategy)
*/
export type TokenExtractionStrategy = {
/** Extract from Authorization header */
fromHeader?: {
name: string;
scheme?: string;
};
/** Extract from cookie */
fromCookie?: {
name: string;
};
/** Extract from query parameter */
fromQuery?: {
name: string;
};
/** Custom extraction function (may be sync or async) */
custom?: (context: AuthRequestContext) => string | null | Promise<string | null>;
};
/**
* Session configuration
*/
export type SessionConfig = {
/** Session storage type */
storage?: SessionStorageType;
/** Session duration in seconds */
duration?: number;
/** Auto-refresh sessions before expiration */
autoRefresh?: boolean;
/** Refresh threshold in seconds (refresh when this much time remains) */
refreshThreshold?: number;
/** Allow multiple sessions per user */
allowMultipleSessions?: boolean;
/** Maximum sessions per user */
maxSessionsPerUser?: number;
/** Session identifier prefix */
prefix?: string;
/** Custom session storage implementation */
customStorage?: SessionStorage;
/** Redis configuration for distributed sessions */
redis?: {
url: string;
prefix?: string;
ttl?: number;
};
};
/**
* Session storage types
*/
export type SessionStorageType = "memory" | "redis" | "custom";
/**
* Role-Based Access Control configuration
*/
export type RBACConfig = {
/** Enable RBAC */
enabled?: boolean;
/** Default roles for new users */
defaultRoles?: string[];
/** Role hierarchy (higher roles inherit lower role permissions) */
roleHierarchy?: Record<string, string[]>;
/** Permission definitions per role */
rolePermissions?: Record<string, string[]>;
/** Permission definitions */
permissions?: PermissionDefinition[];
/** Default permissions for authenticated users */
defaultPermissions?: string[];
/** Super admin roles (bypass all checks) */
superAdminRoles?: string[];
};
/**
* Permission definition
*/
export type PermissionDefinition = {
/** Permission identifier */
id: string;
/** Human-readable name */
name: string;
/** Description */
description?: string;
/** Required roles for this permission */
requiredRoles?: string[];
};
/**
* Auth middleware options
*/
export type AuthMiddlewareOptions = {
/** Auth provider instance */
provider: AuthProvider;
/** Routes to exclude from authentication */
excludePaths?: string[];
/** Whether auth is optional (continue if no token) */
optional?: boolean;
/** Custom unauthorized handler */
onUnauthorized?: (context: AuthRequestContext) => Response | Promise<Response>;
/** Custom error handler */
onError?: (error: Error, context: AuthRequestContext) => Response | Promise<Response>;
};
/**
* Auth middleware configuration
*/
export type AuthMiddlewareConfig = {
/** Auth provider to use */
provider: AuthProviderType;
/** Provider configuration */
providerConfig: AuthProviderConfig;
/** Token extraction configuration */
tokenExtraction?: TokenExtractionConfig;
/** Routes that don't require authentication */
publicRoutes?: string[];
/** Whether authentication is optional (request proceeds with or without auth) */
optional?: boolean;
/** Custom error handler */
onError?: (error: AuthErrorInfo, context: AuthRequestContext) => void | Promise<void>;
/** Hook called after successful authentication */
onAuthenticated?: (context: AuthenticatedContext) => void | Promise<void>;
};
/**
* RBAC middleware configuration
*/
export type RBACMiddlewareConfig = {
/** Required roles (user must have at least one) */
roles?: string[];
/** Required permissions (user must have all) */
permissions?: string[];
/** Whether all roles are required (default: false, any role matches) */
requireAllRoles?: boolean;
/** Super admin roles that bypass all role/permission checks */
superAdminRoles?: string[];
/** Mapping from role name to granted permissions */
rolePermissions?: Record<string, string[]>;
/** Role hierarchy: a role inherits permissions from its children */
roleHierarchy?: Record<string, string[]>;
/** Custom authorization function */
custom?: (user: AuthUser, context: AuthRequestContext) => boolean | Promise<boolean>;
/** Custom error handler */
onDenied?: (result: AuthorizationResult, context: AuthRequestContext) => void | Promise<void>;
};
/**
* Auth0 provider configuration
*/
export type Auth0Config = {
/** Auth0 domain (e.g., 'your-tenant.auth0.com') */
domain: string;
/** Auth0 client ID */
clientId: string;
/** Auth0 client secret (for backend operations) */
clientSecret?: string;
/** Auth0 audience (API identifier) */
audience?: string;
/** Auth0 scope */
scope?: string;
/** Custom namespace for claims */
claimsNamespace?: string;
/** Management API configuration */
managementApi?: {
clientId: string;
clientSecret: string;
};
};
/**
* Clerk provider configuration
*/
export type ClerkConfig = {
/** Clerk publishable key */
publishableKey?: string;
/** Clerk secret key */
secretKey: string;
/** Clerk JWT key (for local validation) */
jwtKey?: string;
/** Clerk API version */
apiVersion?: string;
/** JWKS endpoint override */
jwksUrl?: string;
/** Allowed origins */
allowedOrigins?: string[];
};
/**
* Firebase provider configuration
*/
export type FirebaseConfig = {
/** Firebase project ID */
projectId: string;
/** Firebase API key */
apiKey?: string;
/** Service account credentials */
serviceAccount?: {
clientEmail: string;
privateKey: string;
};
/** Firebase database URL */
databaseURL?: string;
/** Custom claims key for roles */
rolesClaimKey?: string;
/** Custom claims key for permissions */
permissionsClaimKey?: string;
};
/**
* Supabase provider configuration
*/
export type SupabaseConfig = {
/** Supabase project URL */
url: string;
/** Supabase anon key */
anonKey: string;
/** Supabase service role key (for backend operations) */
serviceRoleKey?: string;
/** JWT secret for custom token verification */
jwtSecret?: string;
};
/**
* AWS Cognito provider configuration
*/
export type CognitoConfig = {
/** Cognito user pool ID */
userPoolId: string;
/** Cognito client ID */
clientId: string;
/** Cognito client secret */
clientSecret?: string;
/** AWS region */
region: string;
/** Custom attributes to extract as claims */
customAttributes?: string[];
};
/**
* Keycloak provider configuration
*/
export type KeycloakConfig = {
/** Keycloak server URL */
serverUrl: string;
/** Keycloak realm */
realm: string;
/** Client ID */
clientId: string;
/** Client secret */
clientSecret?: string;
/** Verify token signature */
verifyToken?: boolean;
};
/**
* Generic OAuth2 provider configuration
*/
export type OAuth2Config = {
/** Authorization endpoint URL */
authorizationUrl: string;
/** Token endpoint URL */
tokenUrl: string;
/** User info endpoint URL */
userInfoUrl?: string;
/** JWKS endpoint URL */
jwksUrl?: string;
/** Client ID */
clientId: string;
/** Client secret */
clientSecret?: string;
/** OAuth scopes */
scopes?: string[];
/** Redirect URL */
redirectUrl?: string;
/** Enable PKCE */
usePKCE?: boolean;
};
/**
* JWT provider configuration
*/
export type JWTConfig = {
/** JWT secret for HMAC algorithms */
secret?: string;
/** Public key for RSA/EC algorithms */
publicKey?: string;
/** Supported algorithms */
algorithms?: string[];
/** Token issuer */
issuer?: string;
/** Token audience */
audience?: string | string[];
};
/**
* Better Auth provider configuration
*/
export type BetterAuthConfig = {
/** Better Auth secret */
secret: string;
/** Better Auth base URL */
baseUrl: string;
/** Database connection string */
databaseUrl?: string;
/** Social providers configuration */
socialProviders?: {
github?: {
clientId: string;
clientSecret: string;
};
google?: {
clientId: string;
clientSecret: string;
};
discord?: {
clientId: string;
clientSecret: string;
};
};
};
/**
* WorkOS provider configuration
*/
export type WorkOSConfig = {
/** WorkOS API key */
apiKey: string;
/** WorkOS client ID */
clientId: string;
/** Organization ID (optional for multi-tenant) */
organizationId?: string;
};
/**
* Custom auth provider configuration
*/
export type CustomAuthConfig = {
/** Custom token validation function */
validateToken: (token: string, context?: AuthRequestContext) => Promise<TokenValidationResult>;
/** Custom user fetching function */
getUser?: (userId: string) => Promise<AuthUser | null>;
/** Custom session creation function */
createSession?: (user: AuthUser, context?: AuthRequestContext) => Promise<AuthSession>;
};
/**
* Configuration for AuthProvider.
*
* Discriminated union of base + each provider-specific config so that
* provider factories receive the properly typed config without requiring
* `as any` casts or an open index signature.
*
* The `type` discriminant narrows to the correct provider-specific fields.
* The final `BaseAuthProviderConfig` branch serves as a generic fallback
* for code that only needs the common fields.
*/
export type AuthProviderConfig = (BaseAuthProviderConfig & Auth0Config & {
type: "auth0";
}) | (BaseAuthProviderConfig & ClerkConfig & {
type: "clerk";
}) | (BaseAuthProviderConfig & FirebaseConfig & {
type: "firebase";
}) | (BaseAuthProviderConfig & SupabaseConfig & {
type: "supabase";
}) | (BaseAuthProviderConfig & CognitoConfig & {
type: "cognito";
}) | (BaseAuthProviderConfig & KeycloakConfig & {
type: "keycloak";
}) | (BaseAuthProviderConfig & OAuth2Config & {
type: "oauth2";
}) | (BaseAuthProviderConfig & JWTConfig & {
type: "jwt";
}) | (BaseAuthProviderConfig & BetterAuthConfig & {
type: "better-auth";
}) | (BaseAuthProviderConfig & WorkOSConfig & {
type: "workos";
}) | (BaseAuthProviderConfig & CustomAuthConfig & {
type: "custom";
}) | BaseAuthProviderConfig;
/**
* Auth error codes
*/
export type AuthErrorCode = "AUTH-001" | "AUTH-002" | "AUTH-003" | "AUTH-004" | "AUTH-005" | "AUTH-006" | "AUTH-007" | "AUTH-008" | "AUTH-009" | "AUTH-010" | "AUTH-011" | "AUTH-012" | "AUTH-013" | "AUTH-014" | "AUTH-015" | "AUTH-016" | "AUTH-017" | "AUTH-018" | "AUTH-019" | "AUTH-020";
/**
* Auth error information with additional context.
*
* Renamed from `AuthError` to `AuthErrorInfo` to avoid collision with the
* `createErrorFactory` result that is named `AuthError` in errors.ts.
*/
export type AuthErrorInfo = Error & {
/** Error code */
code: AuthErrorCode;
/** Provider that threw the error */
provider?: AuthProviderType;
/** HTTP status code */
statusCode?: number;
/** Whether the error is retryable */
retryable?: boolean;
/** Additional error context */
context?: Record<string, JsonValue>;
/** Original error if wrapped */
cause?: Error;
};
/**
* Auth events for EventEmitter
*/
export type AuthEvents = {
"auth:login": (user: AuthUser) => void;
"auth:logout": (userId: string) => void;
"auth:tokenRefresh": (session: AuthSession) => void;
"auth:unauthorized": (context: AuthRequestContext, reason: string) => void;
"auth:error": (error: Error, context?: AuthRequestContext) => void;
};
/**
* Auth event types for hooks
*/
export type AuthEventType = "token:validated" | "token:expired" | "token:invalid" | "session:created" | "session:refreshed" | "session:expired" | "session:revoked" | "auth:success" | "auth:failed" | "rbac:allowed" | "rbac:denied";
/**
* Auth event data
*/
export type AuthEventData = {
type: AuthEventType;
timestamp: Date;
provider?: AuthProviderType;
user?: AuthUser;
session?: AuthSession;
error?: AuthErrorInfo;
context?: Record<string, JsonValue>;
};
/**
* Auth event handler
*/
export type AuthEventHandler = (event: AuthEventData) => void | Promise<void>;
/**
* Auth provider factory function type
*/
export type AuthProviderFactoryFn = (config: AuthProviderConfig) => Promise<AuthProvider>;
/**
* Auth health check result
*/
export type AuthHealthCheck = {
/** Overall health status */
healthy: boolean;
/** Provider connection status */
providerConnected: boolean;
/** Session storage status */
sessionStorageHealthy: boolean;
/** Last successful authentication */
lastSuccessfulAuth?: Date;
/** Error details if unhealthy */
error?: string;
};
/**
* Health check result for auth providers (detailed)
*/
export type AuthProviderHealthCheck = {
/** Provider is healthy */
healthy: boolean;
/** Provider type */
provider: AuthProviderType;
/** Response time in ms */
latency?: number;
/** Last successful check */
lastCheck?: Date;
/** Error message if unhealthy */
error?: string;
/** Additional details */
details?: Record<string, JsonValue>;
};
/**
* Provider registration metadata used by AuthProviderRegistry.
*
* Previously defined in `AuthProviderRegistry.ts`; centralised here so all
* auth-domain types live in a single canonical file.
*/
export type AuthProviderMetadata = {
/** Provider type */
type: AuthProviderType;
/** Human-readable name */
name: string;
/** Description */
description: string;
/** Version */
version?: string;
/** Documentation URL */
documentation?: string;
/** Provider aliases */
aliases: string[];
/** Features supported by the provider */
features?: string[];
/** Whether provider requires external dependencies */
requiresExternalDependencies?: boolean;
/** Whether the provider ships built-in (no extra install) */
builtIn?: boolean;
};
/**
* Auth-domain provider health status returned by AuthProviderRegistry.
*
* Not to be confused with the AI-provider `ProviderHealthStatus` union in
* `providers.ts`; this type tracks auth-provider connectivity.
*/
export type AuthProviderHealthStatus = {
type: AuthProviderType;
healthy: boolean;
lastCheck: Date;
latency?: number;
error?: string;
};
/**
* Token operations: validate, extract, refresh, revoke.
*/
export type AuthTokenValidator = {
/** Validate and decode an authentication token */
authenticateToken(token: string, context?: AuthRequestContext): Promise<TokenValidationResult>;
/** Extract token from request context */
extractToken(context: AuthRequestContext): string | null | Promise<string | null>;
/** Refresh an authentication token (optional) */
refreshToken?(refreshToken: string): Promise<TokenRefreshResult>;
/** Revoke a token / logout (optional) */
revokeToken?(token: string): Promise<void>;
};
/**
* Authorization: check roles and permissions.
*/
export type AuthUserAuthorizer = {
/** Check if a user is authorized to perform an action */
authorizeUser(user: AuthUser, permission: string): Promise<AuthorizationResult>;
/** Check if user has specific roles */
authorizeRoles(user: AuthUser, roles: string[]): Promise<AuthorizationResult>;
/** Check if user has all specified permissions */
authorizePermissions(user: AuthUser, permissions: string[]): Promise<AuthorizationResult>;
};
/**
* Session management: create, read, refresh, destroy.
*/
export type AuthSessionManager = {
/** Create a new session for a user */
createSession(user: AuthUser, context?: AuthRequestContext): Promise<AuthSession>;
/** Get an existing session by ID */
getSession(sessionId: string): Promise<AuthSession | null>;
/** Refresh/extend a session */
refreshSession(sessionId: string): Promise<AuthSession | null>;
/** Invalidate/destroy a session */
destroySession(sessionId: string): Promise<void>;
/** Get all active sessions for a user */
getUserSessions(userId: string): Promise<AuthSession[]>;
/** Invalidate all sessions for a user (global logout) */
destroyAllUserSessions(userId: string): Promise<void>;
};
/**
* Request-level authentication.
*/
export type AuthRequestHandler = {
/** Authenticate a request and return full context */
authenticateRequest(context: AuthRequestContext): Promise<AuthenticatedContext | null>;
};
/**
* Optional user management operations.
*/
export type AuthUserManager = {
/** Get user by ID */
getUser?(userId: string): Promise<AuthUser | null>;
/** Get user by email */
getUserByEmail?(email: string): Promise<AuthUser | null>;
/** Update user metadata */
updateUserMetadata?(userId: string, metadata: Record<string, unknown>): Promise<AuthUser>;
/** Update user roles */
updateUserRoles?(userId: string, roles: string[]): Promise<AuthUser>;
/** Update user permissions */
updateUserPermissions?(userId: string, permissions: string[]): Promise<AuthUser>;
};
/**
* Provider lifecycle hooks.
*/
export type AuthLifecycle = {
/** Check provider health */
healthCheck?(): Promise<AuthHealthCheck>;
/** Initialize the provider */
initialize?(): Promise<void>;
/** Cleanup provider resources */
cleanup?(): Promise<void>;
/** Clean up resources (alias for cleanup) */
dispose?(): Promise<void>;
};
/**
* Base interface for all authentication providers.
*
* Composed from focused sub-types so consumers can depend on only the
* slice they need (e.g. `AuthTokenValidator` for token-only middleware).
*
* Unified auth provider interface covering:
* - Token validation (AuthTokenValidator)
* - User authorization (AuthUserAuthorizer)
* - Session management (AuthSessionManager)
* - Request context (AuthRequestHandler)
* - User management (AuthUserManager)
* - Lifecycle (AuthLifecycle)
*/
export type AuthProvider = AuthTokenValidator & AuthUserAuthorizer & AuthSessionManager & AuthRequestHandler & AuthUserManager & AuthLifecycle & {
/** Provider type identifier */
readonly type: AuthProviderType;
/** Provider configuration */
readonly config: AuthProviderConfig;
};
/**
* Session storage interface for SessionManager
*
* Defines the contract for session storage backends (memory, Redis, custom).
* Note: This is a SessionManager-specific interface that uses `set()`/`getUserSessions()`/
* `deleteUserSessions()`/`isHealthy()` method names, which differ from the canonical
* `SessionStorage` type in `../types/auth.js` (which uses `save()`/`getForUser()`/
* `deleteAllForUser()`/`exists()`/`touch()`). Both interfaces coexist because
* SessionManager and BaseAuthProvider have separate storage patterns.
*/
export type SessionManagerStorage = {
/** Get a session by ID */
get(sessionId: string): Promise<AuthSession | null>;
/** Store a session */
set(session: AuthSession): Promise<void>;
/** Delete a session */
delete(sessionId: string): Promise<void>;
/** Get all sessions for a user */
getUserSessions(userId: string): Promise<AuthSession[]>;
/** Delete all sessions for a user */
deleteUserSessions(userId: string): Promise<void>;
/** Clear all sessions (for cleanup) */
clear(): Promise<void>;
/** Health check */
isHealthy(): Promise<boolean>;
};
/** Cached JWKS entry with TTL. Used by Cognito and Keycloak providers. */
export type AuthJWKSCacheEntry = {
jwks: JWKS;
expiresAt: number;
};
/** Async constructor for an auth provider given its config. */
export type AuthProviderConstructor = (config: AuthProviderConfig) => Promise<AuthProvider>;
/** Registration row for an auth provider in AuthProviderFactory. */
export type AuthProviderRegistration = {
factory: AuthProviderConstructor;
aliases: string[];
metadata?: AuthProviderMetadata;
};
/** Synthetic Claude Code client identity used for quota + identification. */
export type ClaudeCodeIdentity = {
deviceId: string;
accountUuid: string;
sessionId: string;
metadataUserId: string;
};
/** Minimal request object accepted by the auth middleware. */
export type IncomingRequest = {
method?: string;
url?: string;
path?: string;
headers?: Record<string, string | string[] | undefined>;
cookies?: Record<string, string>;
query?: Record<string, string | string[] | undefined>;
body?: unknown;
ip?: string;
user?: AuthUser;
authContext?: AuthenticatedContext;
};
/** Minimal Express-style response object used by the auth middleware. */
export type OutgoingResponse = {
status(code: number): OutgoingResponse;
json(body: unknown): void;
};
/** Middleware handler function type for the auth layer. */
export type AuthMiddlewareHandler<TContext = AuthRequestContext> = (context: TContext) => Promise<AuthMiddlewareResult>;
/** Result produced by an auth middleware handler. */
export type AuthMiddlewareResult = {
proceed: boolean;
context?: AuthenticatedContext;
error?: {
statusCode: number;
message: string;
code?: string;
};
};
/** Next-function for Express-style middleware chaining. */
export type NextFunction = () => Promise<void>;
/** Express-style auth middleware signature. */
export type ExpressMiddleware = (req: IncomingRequest, res: OutgoingResponse, next: NextFunction) => Promise<void>;
/** Token bucket state for a single user. */
export type TokenBucket = {
tokens: number;
lastRefill: number;
userId: string;
};
/** Rate limit configuration per user or role. */
export type AuthRateLimitConfig = {
maxRequests: number;
windowMs: number;
roleLimits?: Record<string, number>;
userLimits?: Record<string, number>;
skipRoles?: string[];
message?: string;
};
/** Rate limit result. */
export type RateLimitResult = {
allowed: boolean;
remaining: number;
resetIn: number;
limit: number;
error?: string;
};
/** Result of an atomic consume operation against a token bucket. */
export type AtomicConsumeResult = {
bucket: TokenBucket;
consumed: boolean;
};
/** Storage contract for rate-limit buckets (memory or Redis). */
export type RateLimitStorage = {
getBucket(userId: string): Promise<TokenBucket | null>;
setBucket(userId: string, bucket: TokenBucket): Promise<void>;
deleteBucket(userId: string): Promise<void>;
healthCheck(): Promise<boolean>;
cleanup(): Promise<void>;
atomicConsume?(userId: string, limit: number, windowMs: number, nowMs: number): Promise<AtomicConsumeResult | null>;
};
/**
* Minimal Redis client shape used by the rate-limiter to avoid a hard
* dependency on the full `RedisClientType`. Named with an Auth prefix to
* avoid collision with `RedisClientType` from the redis package.
*/
export type AuthRateLimitRedisClient = {
connect(): Promise<void>;
quit(): Promise<void>;
ping(): Promise<string>;
get(key: string): Promise<string | null>;
setEx(key: string, seconds: number, value: string): Promise<void>;
del(key: string): Promise<number>;
eval(script: string, numkeys: number, ...args: string[]): Promise<unknown>;
};
/** Middleware-level outcome returned by the rate limiter. */
export type RateLimitMiddlewareResult = {
proceed: boolean;
rateLimitResult: RateLimitResult;
response?: Response;
};
/** Auth0 JWT payload structure. */
export type Auth0TokenPayload = {
sub: string;
email?: string;
name?: string;
picture?: string;
email_verified?: boolean;
roles?: string[];
permissions?: string[];
iat: number;
exp: number;
aud: string | string[];
iss: string;
};