@juspay/neurolink 9.31.2 → 9.32.0

package/dist/lib/auth/providers/BaseAuthProvider.d.ts

@@ -0,0 +1,259 @@
+/**
+ * BaseAuthProvider - Abstract base class for authentication providers
+ *
+ * Provides common functionality for all auth providers including:
+ * - Token extraction (header, cookie, query param, custom function)
+ * - Session management (create, validate, refresh, revoke)
+ * - RBAC authorization (roles, permissions, wildcards, hierarchy)
+ * - Token validation utilities (JWT parsing, expiry checks)
+ * - Event emission for auth lifecycle hooks
+ * - Error handling via unified AuthError factory
+ */
+import { EventEmitter } from "events";
+import type { AuthenticatedContext, AuthHealthCheck, AuthorizationResult, AuthProviderConfig, AuthProviderType, AuthRequestContext, AuthSession, AuthUser, MastraAuthProvider, RBACConfig, SessionConfig, SessionStorage, SessionValidationResult, TokenClaims, TokenValidationResult } from "../../types/authTypes.js";
+/**
+ * @deprecated Use `AuthError` from `../errors.js` instead.
+ * Kept for backward compatibility with CognitoProvider / KeycloakProvider.
+ */
+export declare const AuthProviderError: {
+    codes: {
+        readonly INVALID_TOKEN: "AUTH-001";
+        readonly EXPIRED_TOKEN: "AUTH-002";
+        readonly MISSING_TOKEN: "AUTH-003";
+        readonly TOKEN_DECODE_FAILED: "AUTH-004";
+        readonly INVALID_SIGNATURE: "AUTH-005";
+        readonly SESSION_NOT_FOUND: "AUTH-010";
+        readonly SESSION_EXPIRED: "AUTH-011";
+        readonly SESSION_REVOKED: "AUTH-012";
+        readonly INSUFFICIENT_PERMISSIONS: "AUTH-020";
+        readonly INSUFFICIENT_ROLES: "AUTH-021";
+        readonly ACCESS_DENIED: "AUTH-022";
+        readonly USER_NOT_FOUND: "AUTH-030";
+        readonly USER_DISABLED: "AUTH-031";
+        readonly EMAIL_NOT_VERIFIED: "AUTH-032";
+        readonly MFA_REQUIRED: "AUTH-033";
+        readonly PROVIDER_ERROR: "AUTH-040";
+        readonly PROVIDER_NOT_FOUND: "AUTH-041";
+        readonly PROVIDER_INIT_FAILED: "AUTH-042";
+        readonly CONFIGURATION_ERROR: "AUTH-043";
+        readonly CREATION_FAILED: "AUTH-050";
+        readonly REGISTRATION_FAILED: "AUTH-051";
+        readonly DUPLICATE_REGISTRATION: "AUTH-052";
+        readonly MIDDLEWARE_ERROR: "AUTH-060";
+        readonly RATE_LIMITED: "AUTH-061";
+        readonly JWKS_FETCH_FAILED: "AUTH-070";
+        readonly JWKS_KEY_NOT_FOUND: "AUTH-071";
+    };
+    create: (code: "SESSION_NOT_FOUND" | "INVALID_TOKEN" | "EXPIRED_TOKEN" | "MISSING_TOKEN" | "TOKEN_DECODE_FAILED" | "INVALID_SIGNATURE" | "SESSION_EXPIRED" | "SESSION_REVOKED" | "INSUFFICIENT_PERMISSIONS" | "INSUFFICIENT_ROLES" | "ACCESS_DENIED" | "USER_NOT_FOUND" | "USER_DISABLED" | "EMAIL_NOT_VERIFIED" | "MFA_REQUIRED" | "PROVIDER_ERROR" | "PROVIDER_NOT_FOUND" | "PROVIDER_INIT_FAILED" | "CONFIGURATION_ERROR" | "CREATION_FAILED" | "REGISTRATION_FAILED" | "DUPLICATE_REGISTRATION" | "MIDDLEWARE_ERROR" | "RATE_LIMITED" | "JWKS_FETCH_FAILED" | "JWKS_KEY_NOT_FOUND", message: string, options?: {
+        retryable?: boolean;
+        details?: Record<string, unknown>;
+        cause?: Error;
+    } | undefined) => import("../../core/infrastructure/baseError.js").NeuroLinkFeatureError;
+};
+/**
+ * Default in-memory session storage
+ */
+export declare class InMemorySessionStorage implements SessionStorage {
+    private sessions;
+    private userSessions;
+    get(sessionId: string): Promise<AuthSession | null>;
+    save(session: AuthSession): Promise<void>;
+    delete(sessionId: string): Promise<void>;
+    deleteAllForUser(userId: string): Promise<void>;
+    getForUser(userId: string): Promise<AuthSession[]>;
+    exists(sessionId: string): Promise<boolean>;
+    touch(sessionId: string): Promise<void>;
+    clear(): Promise<void>;
+    /**
+     * Get session count (for testing/monitoring)
+     */
+    get size(): number;
+}
+/**
+ * BaseAuthProvider - Abstract base class for all auth providers
+ *
+ * Subclasses must implement:
+ * - authenticateToken() - Validate and decode JWT/access tokens
+ *
+ * Optionally override:
+ * - getUser() - Fetch user by ID from provider
+ * - updateUserRoles() - Update user roles in provider
+ * - updateUserPermissions() - Update user permissions in provider
+ * - dispose() - Clean up resources
+ */
+export declare abstract class BaseAuthProvider implements MastraAuthProvider {
+    abstract readonly type: AuthProviderType;
+    readonly config: AuthProviderConfig;
+    protected sessionStorage: SessionStorage;
+    protected sessionConfig: SessionConfig;
+    protected rbacConfig: RBACConfig;
+    protected emitter: EventEmitter<any>;
+    constructor(config: AuthProviderConfig);
+    /**
+     * Validate and authenticate a token
+     * Subclasses must implement provider-specific token validation
+     */
+    abstract authenticateToken(token: string, context?: AuthRequestContext): Promise<TokenValidationResult>;
+    /**
+     * Extract token using configured strategy
+     *
+     * Attempts extraction in order:
+     * 1. Header (Authorization: Bearer <token> by default)
+     * 2. Cookie
+     * 3. Query parameter
+     * 4. Custom function
+     *
+     * @param context - Request context containing headers, cookies, etc.
+     * @returns Extracted token or null if not found
+     */
+    extractToken(context: AuthRequestContext): Promise<string | null>;
+    /**
+     * Create a new session for an authenticated user
+     *
+     * Session duration and metadata are derived from `this.sessionConfig` and
+     * the optional `context`. This matches the `AuthSessionManager` type
+     * signature: `createSession(user, context?)`.
+     */
+    createSession(user: AuthUser, context?: AuthRequestContext): Promise<AuthSession>;
+    /**
+     * Validate an existing session
+     */
+    validateSession(sessionId: string): Promise<SessionValidationResult>;
+    /**
+     * Refresh a session (extend expiration)
+     */
+    refreshSession(sessionId: string): Promise<AuthSession>;
+    /**
+     * Revoke a session
+     *
+     * Marks the session as invalid rather than deleting it immediately.
+     * This keeps a tombstone so that "revoked" is distinguishable from
+     * "not found" during subsequent validation attempts.
+     */
+    revokeSession(sessionId: string): Promise<void>;
+    /**
+     * Revoke all sessions for a user
+     */
+    revokeAllSessions(userId: string): Promise<void>;
+    /**
+     * Check if a user is authorized for specific roles/permissions
+     */
+    authorize(user: AuthUser, options: {
+        roles?: string[];
+        permissions?: string[];
+        requireAllRoles?: boolean;
+    }): Promise<AuthorizationResult>;
+    /**
+     * Check if user is a super admin
+     */
+    protected isSuperAdmin(user: AuthUser): boolean;
+    /**
+     * Get effective roles including inherited roles from hierarchy (transitive)
+     */
+    protected getEffectiveRoles(user: AuthUser): Set<string>;
+    /**
+     * Get effective permissions including role-based permissions
+     */
+    protected getEffectivePermissions(user: AuthUser): Set<string>;
+    /**
+     * Check if a permission set grants a given permission.
+     * Supports exact match, global wildcard ("*"), and hierarchical wildcards
+     * (e.g. "tools:*" grants "tools:execute").
+     */
+    private hasPermission;
+    /**
+     * Parse JWT token (without validation)
+     */
+    protected parseJWT(token: string): TokenClaims | null;
+    /**
+     * Check if token is expired
+     */
+    protected isTokenExpired(claims: TokenClaims, clockTolerance?: number): boolean;
+    /**
+     * Check if token is not yet valid
+     */
+    protected isTokenNotYetValid(claims: TokenClaims, clockTolerance?: number): boolean;
+    /**
+     * Extract user from token claims
+     */
+    protected extractUserFromClaims(claims: TokenClaims, options?: {
+        rolesClaimKey?: string;
+        permissionsClaimKey?: string;
+        idClaimKey?: string;
+    }): AuthUser;
+    /**
+     * Get user by ID
+     * Override in subclass if provider supports user lookup
+     */
+    getUser?(_userId: string): Promise<AuthUser | null>;
+    /**
+     * Update user roles
+     * Override in subclass if provider supports role updates.
+     * Returns the user with updated roles.
+     */
+    updateUserRoles?(_userId: string, _roles: string[]): Promise<AuthUser>;
+    /**
+     * Update user permissions
+     * Override in subclass if provider supports permission updates.
+     * Returns the user with updated permissions.
+     */
+    updateUserPermissions?(_userId: string, _permissions: string[]): Promise<AuthUser>;
+    /**
+     * Clean up resources
+     */
+    dispose(): Promise<void>;
+    /**
+     * 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>;
+    /**
+     * Get an existing session by ID
+     */
+    getSession(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>;
+    /**
+     * Full request authentication flow
+     *
+     * Combines token extraction (with full strategy support), validation,
+     * and session creation/reuse.
+     *
+     * @param context - Request context
+     * @returns Authenticated context with user and session, or null
+     */
+    authenticateRequest(context: AuthRequestContext): Promise<AuthenticatedContext | null>;
+    /**
+     * Check provider health
+     */
+    healthCheck(): Promise<AuthHealthCheck>;
+    /**
+     * Subscribe to auth events
+     */
+    on(event: string, listener: (...args: unknown[]) => void): void;
+    /**
+     * Unsubscribe from auth events
+     */
+    off(event: string, listener: (...args: unknown[]) => void): void;
+    /**
+     * Emit an auth event
+     */
+    protected emit(event: string, ...args: unknown[]): void;
+}