@focura/auth-core 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,593 @@
+import { z } from 'zod';
+
+interface RedisAdapter {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ...args: unknown[]): Promise<"OK" | null>;
+    setex(key: string, ttl: number, value: string): Promise<"OK" | null>;
+    setnx(key: string, value: string): Promise<number>;
+    del(...keys: string[]): Promise<number>;
+    exists(key: string): Promise<0 | 1>;
+    expire(key: string, seconds: number): Promise<0 | 1>;
+    ttl(key: string): Promise<number>;
+    sadd(key: string, ...members: string[]): Promise<number>;
+    srem(key: string, ...members: string[]): Promise<number>;
+    smembers(key: string): Promise<string[]>;
+    incr(key: string): Promise<number>;
+    scan(cursor: string, ...args: string[]): Promise<[string, string[]]>;
+    eval<T = unknown>(script: string, numKeys: number, ...args: string[]): Promise<T>;
+    pipeline(): RedisPipeline;
+}
+interface RedisPipeline {
+    setex(key: string, ttl: number, value: string): this;
+    incr(key: string): this;
+    expire(key: string, seconds: number): this;
+    exec(): Promise<[Error | null, unknown][]>;
+}
+interface UserStore {
+    findById(id: string): Promise<User | null>;
+    findByEmail(email: string): Promise<User | null>;
+    update(id: string, data: Partial<User>): Promise<void>;
+    updateEmailVerified(id: string, verified: Date): Promise<void>;
+}
+interface User {
+    id: string;
+    email: string;
+    name?: string | null;
+    role: string;
+    password?: string | null;
+    emailVerified?: Date | null;
+    twoFactorEnabled?: boolean;
+    twoFactorSecret?: string | null;
+    bannedAt?: Date | null;
+    banReason?: string | null;
+    lastLoginAt?: Date | null;
+    image?: string | null;
+}
+interface CacheAdapter {
+    get<T>(key: string): Promise<T | null>;
+    set(key: string, value: unknown, ttlSeconds?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+interface AuditLogger {
+    log(event: string, data: Record<string, unknown>): Promise<void>;
+}
+interface ObservabilitySink {
+    setUserContext?(user: {
+        id: string;
+        email?: string;
+    }): void;
+    addBreadcrumb?(breadcrumb: {
+        message: string;
+        data?: Record<string, unknown>;
+    }): void;
+    captureException?(error: Error, context?: Record<string, unknown>): void;
+}
+interface ErrorFactory {
+    UnauthorizedError(message?: string, code?: string): Error;
+    TokenExpiredError(): Error;
+    InvalidTokenError(code?: string): Error;
+    TokenRevokedError(): Error;
+    EmailNotVerifiedError(): Error;
+    AccountBannedError(reason?: string | null, bannedAt?: Date | null): Error;
+    ForbiddenError(message?: string): Error;
+    SessionHijackError(reason?: string): Error;
+    BadRequestError(message?: string, code?: string): Error;
+    ValidationError(message?: string, details?: unknown[], code?: string): Error;
+}
+interface SessionLifecycle {
+    recordCreation(sessionId: string): Promise<void>;
+    invalidate(sessionId: string): Promise<void>;
+    isTracked(sessionId: string): Promise<boolean>;
+    isInactive(sessionId: string): Promise<boolean>;
+}
+type RateLimiterFactory = (max: number, windowSeconds: number, keyFn?: (req: {
+    headers: Record<string, unknown>;
+    ip?: string;
+}) => string | undefined, options?: {
+    failOpen?: boolean;
+}) => (req: unknown, res: unknown, next: () => void) => void;
+interface ZodSchema {
+    safeParse(data: unknown): {
+        success: true;
+        data: unknown;
+    } | {
+        success: false;
+        error: {
+            issues: Array<{
+                path: (string | number)[];
+                message: string;
+            }>;
+        };
+    };
+}
+interface TokenConfig {
+    privateKey: string;
+    publicKey: string;
+    issuer?: string;
+    audience?: string;
+    accessTokenExpiry?: string;
+    refreshTokenExpiry?: string;
+    sseTokenExpiry?: string;
+    currentVersion?: number;
+}
+interface LockoutConfig {
+    maxFailures?: number;
+    lockoutSeconds?: number;
+    windowSeconds?: number;
+}
+interface SessionConfig {
+    inactivityTimeout?: number;
+    absoluteTimeout?: number;
+    maxConcurrent?: number;
+    metadataTtl?: number;
+}
+interface AuthCoreConfig {
+    redis: RedisAdapter;
+    userStore: UserStore;
+    hmacSecret: string;
+    jwt: TokenConfig;
+    cache?: CacheAdapter;
+    auditLogger?: AuditLogger;
+    observability?: ObservabilitySink;
+    errors?: ErrorFactory;
+    keyPrefix?: string;
+    lockout?: LockoutConfig;
+    session?: SessionConfig;
+}
+interface TokenPayload {
+    id: string;
+    email: string;
+    role: string;
+    type: "access" | "refresh" | "sse";
+    version: number;
+    jti: string;
+    sessionId?: string;
+}
+interface TokenPair {
+    accessToken: string;
+    refreshToken: string;
+    accessTokenExpiry: number;
+    refreshTokenExpiry: number;
+}
+interface DeviceFingerprint {
+    userAgent: string;
+    acceptLanguage: string;
+    acceptEncoding: string;
+    ipAddress: string;
+}
+interface SessionMetadata {
+    deviceId: string | null;
+    ipAddress: string;
+    userAgent: string;
+    location?: string;
+    lastActivity: number;
+}
+type AuditEventType = "LOGIN_SUCCESS" | "LOGIN_FAILED" | "LOGIN_BLOCKED" | "LOGOUT" | "LOGOUT_ALL_DEVICES" | "TOKEN_REFRESHED" | "TOKEN_REVOKED" | "TOKEN_EXPIRED" | "TOKEN_VERSION_MISMATCH" | "TOKEN_REPLAY_DETECTED" | "EXCHANGE_SUCCESS" | "EXCHANGE_FAILED" | "SSE_CONNECTED" | "SSE_DISCONNECTED" | "ACCOUNT_LOCKED" | "TOTP_VERIFIED" | "TOTP_FAILED" | "PERMISSION_DENIED" | "EMAIL_NOT_VERIFIED" | "SESSION_BOUND" | "SESSION_REBOUND" | "SESSION_HIJACK_DETECTED" | "SESSION_TIMEOUT" | "SESSION_REVOKED" | "SESSIONS_REVOKED" | "MAX_SESSIONS_REACHED" | "DEVICE_MISMATCH" | "SUSPICIOUS_IP_CHANGE" | "CSRF_VALIDATION_FAILED" | "UNAUTHORIZED_ACCESS" | "RATE_LIMIT_EXCEEDED" | "MALWARE_DETECTED" | "SUSPICIOUS_ACTIVITY" | "DATA_EXPORT" | "DATA_DELETION" | "SENSITIVE_DATA_ACCESS" | "WORKSPACE_CREATED" | "WORKSPACE_DELETED" | "MEMBER_ADDED" | "MEMBER_REMOVED" | "ROLE_CHANGED" | "SUBSCRIPTION_CREATED" | "SUBSCRIPTION_CANCELLED" | "PAYMENT_FAILED";
+type AuditSeverity = "info" | "warn" | "critical";
+
+declare class TokenManager {
+    private readonly privateKey;
+    private readonly publicKey;
+    private readonly issuer;
+    private readonly audience;
+    private readonly accessTokenExpiry;
+    private readonly refreshTokenExpiry;
+    private readonly sseTokenExpiry;
+    private readonly currentVersion;
+    constructor(config: TokenConfig);
+    createAccessToken(p: {
+        id: string;
+        email: string;
+        role: string;
+        sessionId: string;
+    }): string;
+    createRefreshToken(p: {
+        id: string;
+        email: string;
+        role: string;
+        sessionId: string;
+    }): string;
+    createTokenPair(p: {
+        id: string;
+        email: string;
+        role: string;
+        sessionId?: string;
+    }): TokenPair;
+    createSseToken(userId: string): string;
+    verifyToken(token: string, expectedType?: TokenPayload["type"]): TokenPayload;
+    getPublicKey(): string;
+    getAccessTokenExpiry(): string;
+    getRefreshTokenExpiry(): string;
+    getSseTokenExpiry(): string;
+    getCurrentVersion(): number;
+    getIssuer(): string;
+    getAudience(): string;
+    static parseExpiry(expiry: string): number;
+    static extractJti(token: string): string;
+}
+
+declare class TokenRevocation {
+    private readonly redis;
+    private readonly prefix;
+    constructor(redis: RedisAdapter, prefix?: string);
+    private refreshIndexKey;
+    private refreshTokenKey;
+    private revokedAccessKey;
+    private sseKey;
+    private sessionRevokedKey;
+    revokeAccessToken(jti: string, expiresInSeconds: number): Promise<void>;
+    isAccessTokenRevoked(jti: string): Promise<boolean>;
+    storeRefreshToken(userId: string, jti: string, expiresInSeconds: number): Promise<void>;
+    isRefreshTokenValid(userId: string, jti: string): Promise<boolean>;
+    revokeRefreshToken(userId: string, jti: string): Promise<void>;
+    revokeAllRefreshTokens(userId: string): Promise<void>;
+    rotateRefreshToken(userId: string, oldJti: string, newJti: string, expiresInSeconds: number): Promise<boolean>;
+    storeSseToken(jti: string, userId: string, ttlSeconds: number): Promise<void>;
+    consumeSseToken(jti: string): Promise<string | null>;
+    markSessionRevoked(sessionId: string): Promise<void>;
+    isSessionRevoked(sessionId: string): Promise<boolean>;
+}
+
+declare class RefreshLock {
+    private readonly redis;
+    private readonly prefix;
+    constructor(redis: RedisAdapter, prefix?: string);
+    private lockKey;
+    acquire(sessionId: string): Promise<boolean>;
+    release(sessionId: string): Promise<void>;
+    isLocked(sessionId: string): Promise<boolean>;
+}
+
+declare class SessionManager {
+    private readonly redis;
+    private readonly tokenRevocation;
+    private readonly auditLogger?;
+    private readonly maxConcurrent;
+    constructor(redis: RedisAdapter, tokenRevocation: {
+        markSessionRevoked(id: string): Promise<void>;
+    }, auditLogger?: AuditLogger | undefined, prefix?: string, maxConcurrent?: number);
+    private readonly prefix;
+    private sessionKey;
+    private metadataKey;
+    trackUserSession(userId: string, sessionId: string): Promise<void>;
+    private pickLeastActiveSession;
+    revokeUserSession(userId: string, sessionId: string): Promise<void>;
+    getUserActiveSessions(userId: string): Promise<Array<{
+        sessionId: string;
+        deviceInfo: string;
+        ipAddress?: string;
+        lastActivity: string;
+        createdAt: string;
+    }>>;
+}
+
+declare function looksLikeServerToServerUA(userAgent: string): boolean;
+declare function looksLikeServerToServerRequest(req: {
+    headers: Record<string, string | string[] | undefined>;
+}): boolean;
+declare function normalizeUserAgent(userAgent: string): string;
+declare function generateDeviceFingerprint(req: {
+    headers: Record<string, string | string[] | undefined>;
+}): string;
+declare function getClientIp(req: {
+    ip?: string;
+    headers: Record<string, string | string[] | undefined>;
+    socket?: {
+        remoteAddress?: string;
+    };
+}): string;
+declare function createSessionMetadata(req: {
+    ip?: string;
+    headers: Record<string, string | string[] | undefined>;
+    socket?: {
+        remoteAddress?: string;
+    };
+}): SessionMetadata;
+declare function isPrivateIp(ip: string): boolean;
+declare function validateSessionBinding(req: {
+    headers: Record<string, string | string[] | undefined>;
+    ip?: string;
+    socket?: {
+        remoteAddress?: string;
+    };
+}, storedMetadata: SessionMetadata): {
+    valid: boolean;
+    reason?: string;
+};
+
+declare class AccountLockout {
+    private readonly redis;
+    private readonly maxFailures;
+    private readonly lockoutSeconds;
+    private readonly windowSeconds;
+    private readonly prefix;
+    constructor(redis: RedisAdapter, config?: {
+        maxFailures?: number;
+        lockoutSeconds?: number;
+        windowSeconds?: number;
+        prefix?: string;
+    });
+    recordFailedAttempt(identifier: string): Promise<{
+        locked: boolean;
+        unlocksAt?: Date;
+        attempts: number;
+    }>;
+    clearFailedAttempts(identifier: string): Promise<void>;
+    isAccountLocked(identifier: string): Promise<{
+        locked: boolean;
+        unlocksAt?: Date;
+    }>;
+}
+
+declare class AuditLog {
+    private readonly logger?;
+    constructor(logger?: AuditLogger | undefined);
+    log(event: AuditEventType, data: Omit<Record<string, unknown>, "event" | "timestamp" | "severity">): void;
+}
+
+declare class TotpManager {
+    private readonly issuer;
+    constructor(issuer?: string);
+    generateSecret(): string;
+    createUri(secret: string, email: string): string;
+    verify(token: string, secret: string): Promise<boolean>;
+}
+
+declare class SessionTimeoutManager implements SessionLifecycle {
+    private readonly redis;
+    private readonly inactivityTimeout;
+    private readonly absoluteTimeout;
+    private readonly prefix;
+    constructor(redis: RedisAdapter, config?: {
+        inactivityTimeout?: number;
+        absoluteTimeout?: number;
+        prefix?: string;
+    });
+    private createdKey;
+    private activityKey;
+    recordCreation(sessionId: string): Promise<void>;
+    invalidate(sessionId: string): Promise<void>;
+    isTracked(sessionId: string): Promise<boolean>;
+    isInactive(sessionId: string): Promise<boolean>;
+    updateActivity(sessionId: string): Promise<boolean>;
+}
+
+declare const DEFAULTS: {
+    readonly keyPrefix: "focura:";
+    readonly issuer: "focura-app";
+    readonly audience: "focura-backend";
+    readonly accessTokenExpiry: "15m";
+    readonly refreshTokenExpiry: "7d";
+    readonly sseTokenExpiry: "30s";
+    readonly currentVersion: 1;
+    readonly maxConcurrentSessions: 5;
+    readonly sessionMetadataTtl: number;
+    readonly lockoutMaxFailures: 10;
+    readonly lockoutSeconds: number;
+    readonly lockoutWindowSeconds: number;
+    readonly refreshLockTtlSeconds: 45;
+    readonly refreshDedupeTtlSeconds: 30;
+    readonly revokedSessionTtl: number;
+    readonly inactivityTimeout: number;
+    readonly absoluteTimeout: number;
+};
+declare function resolveConfig(raw: AuthCoreConfig): {
+    keyPrefix: string;
+    issuer: string;
+    audience: string;
+    accessTokenExpiry: string;
+    refreshTokenExpiry: string;
+    sseTokenExpiry: string;
+    currentVersion: number;
+    maxConcurrentSessions: number;
+    sessionMetadataTtl: number;
+    lockoutMaxFailures: number;
+    lockoutSeconds: number;
+    lockoutWindowSeconds: number;
+    inactivityTimeout: number;
+    absoluteTimeout: number;
+    redis: RedisAdapter;
+    userStore: UserStore;
+    hmacSecret: string;
+    jwt: TokenConfig;
+    cache?: CacheAdapter;
+    auditLogger?: AuditLogger;
+    observability?: ObservabilitySink;
+    errors?: ErrorFactory;
+    lockout?: LockoutConfig;
+    session?: SessionConfig;
+};
+type ResolvedConfig = ReturnType<typeof resolveConfig>;
+declare const AUDIT_SEVERITY: Record<AuditEventType, AuditSeverity>;
+
+interface AuthRequest {
+    user?: {
+        id: string;
+        email: string;
+        role: string;
+        name?: string | null;
+        tokenJti?: string;
+        sessionId?: string;
+    };
+    headers: Record<string, string | string[] | undefined>;
+    ip?: string;
+    socket?: {
+        remoteAddress?: string;
+    };
+    body?: Record<string, unknown>;
+    params?: Record<string, unknown>;
+    query?: Record<string, unknown>;
+    path?: string;
+    method?: string;
+    originalUrl?: string;
+    [key: string]: unknown;
+}
+interface JwtPayload {
+    sub: string;
+    email: string;
+    role: string;
+    jti: string;
+    version: number;
+    type: string;
+    sessionId?: string;
+}
+declare class MiddlewareFactory {
+    private readonly config;
+    private readonly tokenManager;
+    private readonly tokenRevocation;
+    private readonly errors;
+    private readonly audit;
+    private readonly observability?;
+    private readonly cache?;
+    private sessionTimeoutManager;
+    constructor(rawConfig: AuthCoreConfig);
+    getTokenManager(): TokenManager;
+    getTokenRevocation(): TokenRevocation;
+    getAuditLog(): AuditLog;
+    getRedis(): RedisAdapter;
+    getConfig(): ResolvedConfig;
+    enforceSessionBinding(req: AuthRequest, decoded: JwtPayload): Promise<Error | null>;
+    createAuthenticateMiddleware(): (req: AuthRequest, res: {
+        status(code: number): {
+            json(data: unknown): unknown;
+        };
+    }, next: (err?: Error) => void) => Promise<void>;
+    createAuthorizeMiddleware(...roles: string[]): (req: AuthRequest, res: {
+        status(code: number): {
+            json(data: unknown): unknown;
+        };
+    }, next: (err?: Error) => void) => void;
+    createCsrfMiddleware(): {
+        generateToken: (userId: string, sessionId: string) => Promise<string>;
+        validateToken: (userId: string, sessionId: string, token: string) => Promise<boolean>;
+        middleware(): (req: AuthRequest, res: {
+            status(code: number): {
+                json(data: unknown): unknown;
+            };
+            end(): unknown;
+        }, next: (err?: Error) => void) => Promise<unknown>;
+    };
+    createRateLimitMiddleware(): (max: number, windowSeconds: number, keyFn?: (req: AuthRequest) => string | undefined, options?: {
+        failOpen?: boolean;
+    }) => (req: AuthRequest, res: {
+        status(code: number): {
+            json(data: unknown): unknown;
+        };
+    }, next: (err?: Error) => void) => Promise<unknown>;
+    createSessionTimeoutMiddleware(): (req: AuthRequest, res: {
+        status(code: number): {
+            json(data: unknown): unknown;
+        };
+    }, next: (err?: Error) => void) => Promise<unknown>;
+    createExchangeHandler(): (req: AuthRequest, res: {
+        status(code: number): {
+            json(data: unknown): unknown;
+        };
+    }) => Promise<unknown>;
+    createRefreshHandler(): (req: AuthRequest, res: {
+        status(code: number): {
+            json(data: unknown): unknown;
+        };
+    }) => Promise<unknown>;
+    createLogoutHandler(): (req: AuthRequest, res: {
+        status(code: number): {
+            json(data: unknown): unknown;
+        };
+    }) => Promise<unknown>;
+    private loadUser;
+    private assignUser;
+}
+
+declare const exchangeSchema: z.ZodObject<{
+    userId: z.ZodString;
+    email: z.ZodString;
+    role: z.ZodString;
+    sessionId: z.ZodString;
+    timestamp: z.ZodUnion<[z.ZodString, z.ZodNumber]>;
+    signature: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    email: string;
+    role: string;
+    sessionId: string;
+    userId: string;
+    timestamp: string | number;
+    signature: string;
+}, {
+    email: string;
+    role: string;
+    sessionId: string;
+    userId: string;
+    timestamp: string | number;
+    signature: string;
+}>;
+declare const refreshSchema: z.ZodObject<{
+    refreshToken: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    refreshToken: string;
+}, {
+    refreshToken: string;
+}>;
+declare const logoutSchema: z.ZodObject<{
+    logoutAll: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    logoutAll?: boolean | undefined;
+}, {
+    logoutAll?: boolean | undefined;
+}>;
+
+declare class UnauthorizedError extends Error {
+    readonly code: string;
+    readonly statusCode = 401;
+    constructor(message?: string, code?: string);
+}
+declare class TokenExpiredError extends Error {
+    readonly code = "TOKEN_EXPIRED";
+    readonly statusCode = 401;
+    constructor(message?: string);
+}
+declare class InvalidTokenError extends Error {
+    readonly code: string;
+    readonly statusCode = 401;
+    constructor(code?: string);
+}
+declare class TokenRevokedError extends Error {
+    readonly code = "TOKEN_REVOKED";
+    readonly statusCode = 401;
+    constructor(message?: string);
+}
+declare class EmailNotVerifiedError extends Error {
+    readonly code = "EMAIL_NOT_VERIFIED";
+    readonly statusCode = 403;
+    constructor(message?: string);
+}
+declare class AccountBannedError extends Error {
+    readonly code = "ACCOUNT_BANNED";
+    readonly statusCode = 403;
+    readonly bannedAt?: Date;
+    constructor(reason?: string | null, bannedAt?: Date | null);
+}
+declare class ForbiddenError extends Error {
+    readonly code = "FORBIDDEN";
+    readonly statusCode = 403;
+    constructor(message?: string);
+}
+declare class SessionHijackError extends Error {
+    readonly code = "SESSION_HIJACK_DETECTED";
+    readonly statusCode = 401;
+    constructor(reason?: string);
+}
+declare class BadRequestError extends Error {
+    readonly code: string;
+    readonly statusCode = 400;
+    constructor(message?: string, code?: string);
+}
+declare class ValidationError extends Error {
+    readonly code: string;
+    readonly statusCode = 400;
+    readonly details?: unknown[];
+    constructor(message?: string, details?: unknown[], code?: string);
+}
+
+declare const defaultErrors: ErrorFactory;
+
+export { AUDIT_SEVERITY, AccountBannedError, AccountLockout, type AuditEventType, AuditLog, type AuditLogger, type AuditSeverity, type AuthCoreConfig, type AuthRequest, BadRequestError, type CacheAdapter, DEFAULTS, type DeviceFingerprint, EmailNotVerifiedError, type ErrorFactory, ForbiddenError, InvalidTokenError, type LockoutConfig, MiddlewareFactory, type ObservabilitySink, type RateLimiterFactory, type RedisAdapter, type RedisPipeline, RefreshLock, type ResolvedConfig, type SessionConfig, SessionHijackError, type SessionLifecycle, SessionManager, type SessionMetadata, SessionTimeoutManager, type TokenConfig, TokenExpiredError, TokenManager, type TokenPair, type TokenPayload, TokenRevocation, TokenRevokedError, TotpManager, UnauthorizedError, type User, type UserStore, ValidationError, type ZodSchema, createSessionMetadata, defaultErrors, exchangeSchema, generateDeviceFingerprint, getClientIp, isPrivateIp, logoutSchema, looksLikeServerToServerRequest, looksLikeServerToServerUA, normalizeUserAgent, refreshSchema, resolveConfig, validateSessionBinding };