@juspay/neurolink 9.31.2 → 9.32.0

package/dist/types/authTypes.d.ts

@@ -1,10 +1,13 @@
 /**
  * Auth-related type definitions for NeuroLink
  *
- * Canonical location for OAuth token storage types and token refresher contracts.
+ * 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 } from "./common.js";
+import type { UnknownRecord } from "./common.js";
 /**
  * OAuth tokens structure for storage.
  * Stricter version of OAuthTokens with required fields for persistent storage.
@@ -54,3 +57,936 @@ export type StoredProviderTokens = {
     /** 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: MastraAuthProvider;
+    /** 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 MastraAuthProvider.
+ *
+ * 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<MastraAuthProvider>;
+/**
+ * Auth provider registration entry
+ */
+export type AuthProviderRegistration = {
+    /** Provider type */
+    type: AuthProviderType;
+    /** Factory function */
+    factory: AuthProviderFactoryFn;
+    /** Provider aliases */
+    aliases: string[];
+    /** Provider metadata */
+    metadata?: {
+        name: string;
+        description: string;
+        version?: string;
+        documentation?: string;
+    };
+};
+/**
+ * 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).
+ *
+ * Implements Mastra-style auth provider pattern with unified methods for:
+ * - Token validation  (AuthTokenValidator)
+ * - User authorization (AuthUserAuthorizer)
+ * - Session management (AuthSessionManager)
+ * - Request context    (AuthRequestHandler)
+ * - User management    (AuthUserManager)
+ * - Lifecycle          (AuthLifecycle)
+ */
+export type MastraAuthProvider = AuthTokenValidator & AuthUserAuthorizer & AuthSessionManager & AuthRequestHandler & AuthUserManager & AuthLifecycle & {
+    /** Provider type identifier */
+    readonly type: AuthProviderType;
+    /** Provider configuration */
+    readonly config: AuthProviderConfig;
+};