@parsrun/auth 0.1.0

package/dist/base-BKyR8rcE.d.ts

@@ -0,0 +1,646 @@
+import { S as StorageConfig } from './types-DSjafxJ4.js';
+
+/**
+ * Pars Auth Configuration
+ * Passwordless-first, provider-based authentication
+ */
+
+/**
+ * Session configuration
+ */
+interface SessionConfig {
+    /** Access token expiry in seconds (default: 900 = 15 minutes) */
+    accessTokenExpiry?: number;
+    /** Refresh token expiry in seconds (default: 604800 = 7 days) */
+    refreshTokenExpiry?: number;
+    /** Enable sliding window for refresh tokens (default: true) */
+    slidingWindow?: boolean;
+    /** Maximum concurrent sessions per user (default: 5) */
+    maxSessions?: number;
+    /** Invalidate all sessions on password change (default: true) */
+    invalidateOnPasswordChange?: boolean;
+}
+/**
+ * JWT configuration
+ */
+interface JwtConfig {
+    /** JWT signing algorithm (default: HS256) */
+    algorithm?: 'HS256' | 'HS384' | 'HS512' | 'RS256' | 'RS384' | 'RS512' | 'ES256' | 'ES384' | 'ES512';
+    /** JWT issuer claim */
+    issuer?: string;
+    /** JWT audience claim */
+    audience?: string | string[];
+}
+/**
+ * Cookie configuration
+ */
+interface CookieConfig {
+    /** Cookie name prefix (default: 'pars') */
+    prefix?: string;
+    /** Cookie domain */
+    domain?: string;
+    /** Cookie path (default: '/') */
+    path?: string;
+    /** Use secure cookies (default: true in production) */
+    secure?: boolean;
+    /** SameSite attribute (default: 'lax') */
+    sameSite?: 'strict' | 'lax' | 'none';
+    /** HttpOnly for refresh token (default: true) */
+    httpOnly?: boolean;
+}
+/**
+ * CSRF configuration
+ */
+interface CsrfConfig {
+    /** Enable CSRF protection (default: true) */
+    enabled?: boolean;
+    /** CSRF header name (default: 'x-csrf-token') */
+    headerName?: string;
+    /** CSRF cookie name (default: 'csrf') */
+    cookieName?: string;
+}
+/**
+ * Tenant resolution strategy
+ */
+type TenantResolutionStrategy = 'subdomain' | 'header' | 'path' | 'query' | 'custom';
+/**
+ * Multi-tenant configuration
+ */
+interface TenantConfig {
+    /** Enable multi-tenancy (default: true) */
+    enabled?: boolean;
+    /** Tenant resolution strategy (default: 'header') */
+    strategy?: TenantResolutionStrategy;
+    /** Header name for tenant ID (default: 'x-tenant-id') */
+    headerName?: string;
+    /** Custom tenant resolver */
+    resolver?: (request: Request) => Promise<string | null>;
+}
+/**
+ * OAuth provider configuration
+ */
+interface OAuthProviderConfig {
+    /** Enable this provider */
+    enabled?: boolean;
+    /** OAuth client ID */
+    clientId: string;
+    /** OAuth client secret */
+    clientSecret: string;
+    /** OAuth scopes */
+    scopes?: string[];
+    /** Callback URL (default: baseUrl + /auth/callback/:provider) */
+    callbackUrl?: string;
+}
+/**
+ * OTP (One-Time Password) configuration
+ */
+interface OtpConfig {
+    /** Enable OTP authentication (default: true) */
+    enabled?: boolean;
+    /** Email OTP configuration */
+    email?: {
+        /** Enable email OTP (default: true) */
+        enabled?: boolean;
+        /** OTP expiry in seconds (default: 600 = 10 minutes) */
+        expiresIn?: number;
+        /** OTP code length (default: 6) */
+        length?: number;
+        /** Maximum verification attempts (default: 3) */
+        maxAttempts?: number;
+        /** Rate limit: max requests per window (default: 5) */
+        rateLimit?: number;
+        /** Rate limit window in seconds (default: 900 = 15 minutes) */
+        rateLimitWindow?: number;
+        /** Email sending function */
+        send: (to: string, code: string) => Promise<void>;
+    };
+    /** SMS OTP configuration */
+    sms?: {
+        /** Enable SMS OTP (default: false) */
+        enabled?: boolean;
+        /** OTP expiry in seconds (default: 300 = 5 minutes) */
+        expiresIn?: number;
+        /** OTP code length (default: 6) */
+        length?: number;
+        /** Maximum verification attempts (default: 3) */
+        maxAttempts?: number;
+        /** Rate limit: max requests per window (default: 3) */
+        rateLimit?: number;
+        /** Rate limit window in seconds (default: 900 = 15 minutes) */
+        rateLimitWindow?: number;
+        /** SMS sending function */
+        send: (to: string, code: string) => Promise<void>;
+    };
+}
+/**
+ * Magic Link configuration
+ */
+interface MagicLinkConfig {
+    /** Enable magic link authentication (default: false) */
+    enabled?: boolean;
+    /** Link expiry in seconds (default: 900 = 15 minutes) */
+    expiresIn?: number;
+    /** Email sending function */
+    send: (to: string, url: string) => Promise<void>;
+}
+/**
+ * TOTP (Time-based One-Time Password) configuration for 2FA
+ */
+interface TotpConfig {
+    /** Enable TOTP 2FA (default: false) */
+    enabled?: boolean;
+    /** TOTP issuer name (shown in authenticator apps) */
+    issuer?: string;
+    /** Number of backup codes to generate (default: 10) */
+    backupCodesCount?: number;
+}
+/**
+ * WebAuthn/Passkey configuration
+ */
+interface WebAuthnConfig {
+    /** Enable WebAuthn (default: false) */
+    enabled?: boolean;
+    /** Relying party name (your app name) */
+    rpName: string;
+    /** Relying party ID (your domain) */
+    rpId: string;
+    /** Allowed origins */
+    origins?: string[];
+}
+/**
+ * Password configuration (DISABLED BY DEFAULT)
+ */
+interface PasswordConfig {
+    /**
+     * Enable password authentication
+     * @default false - Passwordless is recommended
+     */
+    enabled?: boolean;
+    /** Minimum password length (default: 8) */
+    minLength?: number;
+    /** Require uppercase letters (default: false) */
+    requireUppercase?: boolean;
+    /** Require lowercase letters (default: false) */
+    requireLowercase?: boolean;
+    /** Require numbers (default: false) */
+    requireNumbers?: boolean;
+    /** Require special characters (default: false) */
+    requireSymbols?: boolean;
+    /** Check against common passwords (default: true) */
+    checkCommonPasswords?: boolean;
+}
+/**
+ * Security configuration
+ */
+interface SecurityConfig {
+    /** Rate limiting configuration */
+    rateLimit?: {
+        /** Enable rate limiting (default: true) */
+        enabled?: boolean;
+        /** Login attempts per window (default: 5) */
+        loginAttempts?: number;
+        /** Window size in seconds (default: 900 = 15 minutes) */
+        windowSize?: number;
+    };
+    /** Account lockout configuration */
+    lockout?: {
+        /** Enable account lockout (default: true) */
+        enabled?: boolean;
+        /** Failed attempts before lockout (default: 5) */
+        maxAttempts?: number;
+        /** Lockout duration in seconds (default: 900 = 15 minutes) */
+        duration?: number;
+    };
+    /** CSRF configuration */
+    csrf?: CsrfConfig;
+}
+/**
+ * Auth callbacks for extensibility
+ */
+interface AuthCallbacks {
+    /** Called after successful sign up */
+    onSignUp?: (user: {
+        id: string;
+        email?: string | null;
+    }) => Promise<void>;
+    /** Called after successful sign in */
+    onSignIn?: (user: {
+        id: string;
+        email?: string | null;
+    }, session: {
+        id: string;
+    }) => Promise<void>;
+    /** Called after sign out */
+    onSignOut?: (userId: string, sessionId: string) => Promise<void>;
+    /** Called when a new session is created */
+    onSessionCreated?: (session: {
+        id: string;
+        userId: string;
+    }) => Promise<void>;
+    /** Validate sign in (return false to reject) */
+    validateSignIn?: (user: {
+        id: string;
+        email?: string | null;
+    }) => Promise<boolean>;
+}
+/**
+ * Database adapter interface
+ * Implement this to connect Pars Auth to your database
+ */
+interface AuthAdapter {
+    findUserById(id: string): Promise<AdapterUser | null>;
+    findUserByEmail(email: string): Promise<AdapterUser | null>;
+    findUserByPhone(phone: string): Promise<AdapterUser | null>;
+    createUser(data: CreateUserInput): Promise<AdapterUser>;
+    updateUser(id: string, data: Partial<AdapterUser>): Promise<AdapterUser>;
+    deleteUser(id: string): Promise<void>;
+    findSessionById(id: string): Promise<AdapterSession | null>;
+    findSessionsByUserId(userId: string): Promise<AdapterSession[]>;
+    createSession(data: CreateSessionInput): Promise<AdapterSession>;
+    updateSession(id: string, data: Partial<AdapterSession>): Promise<AdapterSession>;
+    deleteSession(id: string): Promise<void>;
+    deleteSessionsByUserId(userId: string): Promise<void>;
+    findAuthMethod(provider: string, providerId: string): Promise<AdapterAuthMethod | null>;
+    findAuthMethodsByUserId(userId: string): Promise<AdapterAuthMethod[]>;
+    createAuthMethod(data: CreateAuthMethodInput): Promise<AdapterAuthMethod>;
+    deleteAuthMethod(id: string): Promise<void>;
+    findTenantById?(id: string): Promise<AdapterTenant | null>;
+    findTenantBySlug?(slug: string): Promise<AdapterTenant | null>;
+    findMembership?(userId: string, tenantId: string): Promise<AdapterMembership | null>;
+    findMembershipsByUserId?(userId: string): Promise<AdapterMembership[]>;
+    createMembership?(data: CreateMembershipInput): Promise<AdapterMembership>;
+    updateMembership?(id: string, data: Partial<AdapterMembership>): Promise<AdapterMembership>;
+    deleteMembership?(id: string): Promise<void>;
+}
+interface AdapterUser {
+    id: string;
+    email?: string | null;
+    phone?: string | null;
+    emailVerified?: boolean;
+    phoneVerified?: boolean;
+    name?: string | null;
+    avatar?: string | null;
+    twoFactorEnabled?: boolean;
+    status: 'active' | 'inactive' | 'suspended';
+    createdAt: Date;
+    updatedAt: Date;
+}
+interface AdapterSession {
+    id: string;
+    userId: string;
+    tenantId?: string | null;
+    expiresAt: Date;
+    refreshExpiresAt?: Date | null;
+    deviceType?: string | null;
+    deviceName?: string | null;
+    userAgent?: string | null;
+    ipAddress?: string | null;
+    status: 'active' | 'expired' | 'revoked';
+    createdAt: Date;
+    updatedAt: Date;
+}
+interface AdapterAuthMethod {
+    id: string;
+    userId: string;
+    provider: string;
+    providerId: string;
+    verified: boolean;
+    metadata?: Record<string, unknown>;
+    createdAt: Date;
+    updatedAt: Date;
+}
+interface AdapterTenant {
+    id: string;
+    name: string;
+    slug: string;
+    status: 'active' | 'suspended' | 'inactive';
+    createdAt: Date;
+    updatedAt: Date;
+}
+interface AdapterMembership {
+    id: string;
+    userId: string;
+    tenantId: string;
+    role: string;
+    permissions?: string[];
+    status: 'active' | 'inactive' | 'pending';
+    createdAt: Date;
+    updatedAt: Date;
+}
+interface CreateUserInput {
+    email?: string;
+    phone?: string;
+    name?: string;
+    avatar?: string;
+    emailVerified?: boolean;
+    phoneVerified?: boolean;
+}
+interface CreateSessionInput {
+    userId: string;
+    tenantId?: string;
+    expiresAt: Date;
+    refreshExpiresAt?: Date;
+    deviceType?: string;
+    deviceName?: string;
+    userAgent?: string;
+    ipAddress?: string;
+}
+interface CreateAuthMethodInput {
+    userId: string;
+    provider: string;
+    providerId: string;
+    verified?: boolean;
+    metadata?: Record<string, unknown>;
+}
+interface CreateMembershipInput {
+    userId: string;
+    tenantId: string;
+    role: string;
+    permissions?: string[];
+}
+/**
+ * Main Pars Auth Configuration
+ */
+interface ParsAuthConfig {
+    /**
+     * Secret key for signing tokens (required)
+     * Use a strong, random string of at least 32 characters
+     */
+    secret: string;
+    /**
+     * Base URL of your application
+     * Used for OAuth callbacks, magic links, etc.
+     */
+    baseUrl?: string;
+    /**
+     * Storage configuration for OTP, rate limiting, etc.
+     * Auto-detects runtime if not specified
+     */
+    storage?: StorageConfig;
+    /**
+     * Authentication providers
+     */
+    providers?: {
+        /** OTP configuration (enabled by default) */
+        otp?: OtpConfig;
+        /** Magic Link configuration */
+        magicLink?: MagicLinkConfig;
+        /** OAuth providers */
+        oauth?: {
+            google?: OAuthProviderConfig;
+            github?: OAuthProviderConfig;
+            microsoft?: OAuthProviderConfig;
+            apple?: OAuthProviderConfig;
+            /** Custom OAuth providers */
+            custom?: Record<string, OAuthProviderConfig>;
+        };
+        /** TOTP 2FA configuration */
+        totp?: TotpConfig;
+        /** WebAuthn/Passkey configuration */
+        webauthn?: WebAuthnConfig;
+        /**
+         * Password configuration
+         * @default { enabled: false }
+         */
+        password?: PasswordConfig;
+    };
+    /** Session configuration */
+    session?: SessionConfig;
+    /** JWT configuration */
+    jwt?: JwtConfig;
+    /** Cookie configuration */
+    cookies?: CookieConfig;
+    /** Security configuration */
+    security?: SecurityConfig;
+    /** Multi-tenant configuration */
+    tenant?: TenantConfig;
+    /** Database adapter (required) */
+    adapter: AuthAdapter;
+    /** Lifecycle callbacks */
+    callbacks?: AuthCallbacks;
+}
+/**
+ * Default configuration (passwordless-first)
+ */
+declare const defaultConfig: Partial<ParsAuthConfig>;
+/**
+ * Merge user config with defaults
+ */
+declare function mergeConfig(config: ParsAuthConfig): Required<ParsAuthConfig>;
+/**
+ * Validate configuration
+ */
+declare function validateConfig(config: ParsAuthConfig): void;
+
+/**
+ * Base provider types and interfaces
+ * All auth providers must implement these interfaces
+ */
+
+/**
+ * Provider types
+ */
+type ProviderType = 'otp' | 'magic-link' | 'oauth' | 'totp' | 'webauthn' | 'password';
+/**
+ * Provider metadata
+ */
+interface ProviderInfo {
+    /** Provider unique name */
+    name: string;
+    /** Provider type */
+    type: ProviderType;
+    /** Whether the provider is enabled */
+    enabled: boolean;
+    /** Human-readable display name */
+    displayName?: string;
+    /** Provider icon URL */
+    icon?: string;
+}
+/**
+ * Authentication input (varies by provider)
+ */
+interface AuthInput {
+    /** User identifier (email, phone, username) */
+    identifier?: string;
+    /** Credential (OTP code, password, OAuth code, etc.) */
+    credential?: string;
+    /** Tenant ID for multi-tenant apps */
+    tenantId?: string;
+    /** Provider-specific data */
+    data?: Record<string, unknown>;
+}
+/**
+ * Authentication result
+ */
+interface AuthResult {
+    /** Whether authentication was successful */
+    success: boolean;
+    /** Authenticated user (if successful) */
+    user?: AdapterUser;
+    /** Session (if created) */
+    session?: AdapterSession;
+    /** Whether this is a new user */
+    isNewUser?: boolean;
+    /** Whether 2FA is required */
+    requiresTwoFactor?: boolean;
+    /** 2FA challenge data */
+    twoFactorChallenge?: {
+        type: 'totp' | 'webauthn' | 'sms';
+        challengeId?: string;
+    };
+    /** Error message (if failed) */
+    error?: string;
+    /** Error code (if failed) */
+    errorCode?: string;
+}
+/**
+ * Verification input
+ */
+interface VerifyInput {
+    /** Verification target (email, phone) */
+    identifier: string;
+    /** Verification type */
+    type: 'email' | 'sms';
+    /** Verification code or token */
+    code: string;
+    /** Tenant ID */
+    tenantId?: string;
+}
+/**
+ * Verification result
+ */
+interface VerifyResult {
+    /** Whether verification was successful */
+    success: boolean;
+    /** Remaining attempts (if failed) */
+    attemptsLeft?: number;
+    /** Error message */
+    error?: string;
+}
+/**
+ * Base auth provider interface
+ * All providers must implement this interface
+ */
+interface AuthProvider {
+    /** Provider unique name (e.g., 'email-otp', 'google', 'password') */
+    readonly name: string;
+    /** Provider type */
+    readonly type: ProviderType;
+    /** Whether the provider is currently enabled */
+    readonly enabled: boolean;
+    /**
+     * Initialize the provider with config
+     * Called once during auth system setup
+     */
+    initialize?(config: ParsAuthConfig): Promise<void>;
+    /**
+     * Authenticate a user
+     * This is the main authentication entry point
+     */
+    authenticate(input: AuthInput): Promise<AuthResult>;
+    /**
+     * Verify a code/token (optional)
+     * Used by OTP, magic link, etc.
+     */
+    verify?(input: VerifyInput): Promise<VerifyResult>;
+    /**
+     * Get provider info for display
+     */
+    getInfo(): ProviderInfo;
+}
+/**
+ * Two-factor auth provider interface
+ * Extends base provider for 2FA capabilities
+ */
+interface TwoFactorProvider extends AuthProvider {
+    /** Provider type is always 'totp' or 'webauthn' for 2FA */
+    readonly type: 'totp' | 'webauthn';
+    /**
+     * Setup 2FA for a user
+     * Returns setup data (QR code, backup codes, etc.)
+     */
+    setup(userId: string): Promise<TwoFactorSetupResult>;
+    /**
+     * Verify 2FA and complete setup
+     */
+    verifySetup(userId: string, code: string): Promise<boolean>;
+    /**
+     * Verify 2FA during login
+     */
+    verifyLogin(userId: string, code: string): Promise<boolean>;
+    /**
+     * Disable 2FA for a user
+     */
+    disable(userId: string): Promise<void>;
+}
+/**
+ * 2FA setup result
+ */
+interface TwoFactorSetupResult {
+    /** Secret key (for TOTP) */
+    secret?: string;
+    /** QR code data URL */
+    qrCode?: string;
+    /** Backup codes */
+    backupCodes?: string[];
+    /** WebAuthn challenge */
+    challenge?: string;
+}
+/**
+ * OAuth provider interface
+ * Extends base provider for OAuth flows
+ */
+interface OAuthProvider extends AuthProvider {
+    /** Provider type is always 'oauth' */
+    readonly type: 'oauth';
+    /**
+     * Get OAuth authorization URL
+     */
+    getAuthorizationUrl(state: string, codeVerifier?: string): Promise<string>;
+    /**
+     * Exchange authorization code for tokens
+     */
+    exchangeCode(code: string, codeVerifier?: string): Promise<{
+        accessToken: string;
+        refreshToken?: string;
+        expiresIn?: number;
+        idToken?: string;
+    }>;
+    /**
+     * Get user info from OAuth provider
+     */
+    getUserInfo(accessToken: string): Promise<OAuthUserInfo>;
+}
+/**
+ * OAuth user info
+ */
+interface OAuthUserInfo {
+    /** Provider-specific user ID */
+    id: string;
+    /** User email */
+    email?: string;
+    /** Whether email is verified */
+    emailVerified?: boolean;
+    /** User name */
+    name?: string;
+    /** Avatar URL */
+    avatar?: string;
+    /** Raw provider data */
+    raw?: Record<string, unknown>;
+}
+/**
+ * Abstract base class for providers
+ * Provides common functionality
+ */
+declare abstract class BaseProvider implements AuthProvider {
+    abstract readonly name: string;
+    abstract readonly type: ProviderType;
+    protected config?: ParsAuthConfig;
+    protected _enabled: boolean;
+    get enabled(): boolean;
+    initialize(config: ParsAuthConfig): Promise<void>;
+    abstract authenticate(input: AuthInput): Promise<AuthResult>;
+    getInfo(): ProviderInfo;
+}
+
+export { type AuthProvider as A, BaseProvider as B, type CookieConfig as C, defaultConfig as D, mergeConfig as E, validateConfig as F, type JwtConfig as J, type MagicLinkConfig as M, type OAuthProvider as O, type ProviderType as P, type SessionConfig as S, type TwoFactorProvider as T, type VerifyInput as V, type WebAuthnConfig as W, type ProviderInfo as a, type AuthInput as b, type AuthResult as c, type VerifyResult as d, type TwoFactorSetupResult as e, type OAuthUserInfo as f, type OtpConfig as g, type AuthAdapter as h, type ParsAuthConfig as i, type CsrfConfig as j, type TenantConfig as k, type TenantResolutionStrategy as l, type TotpConfig as m, type PasswordConfig as n, type OAuthProviderConfig as o, type SecurityConfig as p, type AuthCallbacks as q, type AdapterUser as r, type AdapterSession as s, type AdapterAuthMethod as t, type AdapterTenant as u, type AdapterMembership as v, type CreateUserInput as w, type CreateSessionInput as x, type CreateAuthMethodInput as y, type CreateMembershipInput as z };