@mountsqli/auth 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,550 @@
+import * as _mountsqli_pg from '@mountsqli/pg';
+
+/**
+ * Auth type definitions.
+ */
+interface AuthConfig {
+    /** Database instance (MountSQLi Database) */
+    db: any;
+    /** Secret key for JWT signing */
+    secret: string;
+    /** Auth providers */
+    providers: AuthProvider[];
+    /** Session configuration */
+    session?: SessionConfig;
+    /** Custom pages */
+    pages?: PagesConfig;
+    /** Lifecycle callbacks */
+    callbacks?: CallbacksConfig;
+}
+interface SessionConfig {
+    strategy: 'jwt' | 'database';
+    maxAge: number;
+}
+interface PagesConfig {
+    signIn?: string;
+    signUp?: string;
+    error?: string;
+    verifyRequest?: string;
+}
+interface CallbacksConfig {
+    onRegister?: (user: User) => Promise<void> | void;
+    onLogin?: (user: User) => Promise<void> | void;
+    onLogout?: (session: SessionData) => Promise<void> | void;
+    onSession?: (session: SessionData) => Promise<SessionData | null> | SessionData | null;
+}
+interface User {
+    id: string;
+    email: string;
+    emailVerified: Date | null;
+    name: string | null;
+    image: string | null;
+    twoFactorEnabled: boolean;
+    createdAt: Date;
+    updatedAt: Date;
+}
+interface CreateUserInput {
+    email: string;
+    password?: string;
+    name?: string;
+    image?: string;
+    emailVerified?: Date;
+}
+interface Session {
+    id: string;
+    userId: string;
+    token: string;
+    expiresAt: Date;
+    ipAddress?: string;
+    userAgent?: string;
+}
+interface SessionData {
+    user: User;
+    expiresAt: Date;
+}
+interface AuthResult {
+    user: User;
+    session: SessionData;
+    token: string;
+}
+interface AuthProvider {
+    id: string;
+    name: string;
+    type: 'credentials' | 'oauth' | 'email';
+}
+interface CredentialsProvider extends AuthProvider {
+    type: 'credentials';
+    authorize: (credentials: Record<string, string>, req?: any) => Promise<User | null>;
+}
+interface OAuthProvider extends AuthProvider {
+    type: 'oauth';
+    clientId: string;
+    clientSecret: string;
+    scope?: string[];
+    authorizationUrl?: string;
+    tokenUrl?: string;
+    userInfoUrl?: string;
+}
+interface EmailProvider extends AuthProvider {
+    type: 'email';
+    sendVerificationEmail?: (email: string, token: string) => Promise<void>;
+}
+interface Role {
+    id: string;
+    name: string;
+    permissions: string[];
+    createdAt: Date;
+}
+interface UserRole {
+    userId: string;
+    roleId: string;
+}
+interface MiddlewareOptions {
+    required?: boolean;
+    requiredRole?: string;
+    requiredPermission?: string;
+}
+interface AuthMiddlewareResult {
+    user: User | null;
+    session: SessionData | null;
+}
+interface JWTPayload {
+    sub: string;
+    email: string;
+    name?: string;
+    image?: string;
+    iat: number;
+    exp: number;
+}
+interface OAuthCallbackParams {
+    code?: string;
+    state?: string;
+    error?: string;
+    error_description?: string;
+}
+interface OAuthTokenResponse {
+    access_token: string;
+    token_type: string;
+    expires_in?: number;
+    refresh_token?: string;
+    scope?: string;
+}
+interface OAuthUserInfo {
+    id: string;
+    email: string;
+    name?: string;
+    image?: string;
+    emailVerified?: boolean;
+}
+
+/**
+ * Main Auth class — orchestrates all auth functionality.
+ */
+
+declare class Auth {
+    private config;
+    private db;
+    private secret;
+    private sessionConfig;
+    private emailAdapter;
+    private rateLimiter;
+    private usersTable;
+    private sessionsTable;
+    private accountsTable;
+    private verificationTable;
+    private rolesTable;
+    private userRolesTable;
+    constructor(config: AuthConfig);
+    register(data: {
+        email: string;
+        password: string;
+        name?: string;
+    }): Promise<AuthResult>;
+    login(providerId: string, credentials: Record<string, string>): Promise<AuthResult>;
+    private loginWithCredentials;
+    signIn(providerId: string): Promise<string>;
+    handleCallback(providerId: string, params: {
+        code?: string;
+        state?: string;
+        error?: string;
+    }): Promise<AuthResult>;
+    getSession(request: {
+        headers?: Record<string, string | undefined>;
+    }): Promise<SessionData | null>;
+    logout(token: string): Promise<void>;
+    twoFactor: {
+        generate: (userId: string) => Promise<{
+            secret: string;
+            otpauthUrl: string;
+        }>;
+        enable: (userId: string, code: string) => Promise<void>;
+        disable: (userId: string) => Promise<void>;
+        verify: (secret: string, code: string) => boolean;
+    };
+    passwordReset: {
+        create: (email: string) => Promise<string>;
+        verify: (token: string, newPassword: string) => Promise<void>;
+    };
+    emailVerification: {
+        create: (userId: string) => Promise<string>;
+        verify: (token: string) => Promise<void>;
+    };
+    rbac: {
+        createRole: (data: {
+            name: string;
+            permissions: string[];
+        }) => Promise<Role>;
+        deleteRole: (roleId: string) => Promise<void>;
+        assignRole: (userId: string, roleName: string) => Promise<void>;
+        removeRole: (userId: string, roleName: string) => Promise<void>;
+        getUserRoles: (userId: string) => Promise<Role[]>;
+        hasRole: (userId: string, roleName: string) => Promise<boolean>;
+        authorize: (userId: string, permission: string) => Promise<boolean>;
+    };
+    private isValidEmail;
+    private isValidPassword;
+    /** Generate a CSRF token for a session */
+    generateCsrfToken(sessionToken: string): string;
+    /** Validate a CSRF token */
+    validateCsrfToken(sessionToken: string, csrfToken: string): boolean;
+    private extractToken;
+    private sanitizeUser;
+}
+
+/**
+ * Pre-built users table for auth.
+ */
+declare const authUsers: _mountsqli_pg.PgTable & {
+    columns: {
+        id: any;
+        email: any;
+        emailVerified: any;
+        password: any;
+        name: any;
+        image: any;
+        twoFactorEnabled: any;
+        twoFactorSecret: any;
+        createdAt: any;
+        updatedAt: any;
+    };
+};
+
+/**
+ * Pre-built sessions table for auth.
+ */
+declare const authSessions: _mountsqli_pg.PgTable & {
+    columns: {
+        id: any;
+        userId: any;
+        token: any;
+        expiresAt: any;
+        ipAddress: any;
+        userAgent: any;
+    };
+};
+
+/**
+ * Pre-built OAuth accounts table for auth.
+ */
+declare const authAccounts: _mountsqli_pg.PgTable & {
+    columns: {
+        id: any;
+        userId: any;
+        provider: any;
+        providerAccountId: any;
+        accessToken: any;
+        refreshToken: any;
+        expiresAt: any;
+        createdAt: any;
+    };
+};
+
+/**
+ * Pre-built verification tokens table for email verification and password reset.
+ */
+declare const authVerificationTokens: _mountsqli_pg.PgTable & {
+    columns: {
+        id: any;
+        identifier: any;
+        token: any;
+        expiresAt: any;
+    };
+};
+
+/**
+ * Pre-built roles table for RBAC.
+ */
+declare const authRoles: _mountsqli_pg.PgTable & {
+    columns: {
+        id: any;
+        name: any;
+        permissions: any;
+        createdAt: any;
+    };
+};
+
+/**
+ * Pre-built user_roles junction table for RBAC.
+ */
+declare const authUserRoles: _mountsqli_pg.PgTable & {
+    columns: {
+        userId: any;
+        roleId: any;
+    };
+};
+
+/**
+ * Credentials (email/password) provider.
+ */
+
+interface CredentialsProviderConfig {
+    /** Custom authorization function */
+    authorize?: (credentials: Record<string, string>) => Promise<any | null>;
+}
+declare function credentials(config?: CredentialsProviderConfig): CredentialsProvider;
+
+/**
+ * Google OAuth provider.
+ */
+
+interface GoogleProviderConfig {
+    clientId: string;
+    clientSecret: string;
+    scope?: string[];
+}
+declare function google(config: GoogleProviderConfig): OAuthProvider;
+
+/**
+ * GitHub OAuth provider.
+ */
+
+interface GitHubProviderConfig {
+    clientId: string;
+    clientSecret: string;
+    scope?: string[];
+}
+declare function github(config: GitHubProviderConfig): OAuthProvider;
+
+/**
+ * Framework-agnostic auth middleware helper.
+ */
+
+/**
+ * Resolve auth session from a request-like object.
+ */
+declare function resolveAuth(auth: Auth, request: {
+    headers?: Record<string, string | undefined>;
+}, options?: MiddlewareOptions): Promise<AuthMiddlewareResult>;
+
+/**
+ * Express middleware adapter.
+ */
+
+interface ExpressAuthMiddlewareOptions extends MiddlewareOptions {
+    /** Custom error handler */
+    onError?: (err: Error, req: any, res: any, next: any) => void;
+}
+/**
+ * Create Express middleware.
+ */
+declare function expressMiddleware(auth: Auth, options?: ExpressAuthMiddlewareOptions): (req: any, res: any, next: any) => Promise<void>;
+/**
+ * Create Express route protector.
+ */
+declare function requireAuth(auth: Auth, options?: ExpressAuthMiddlewareOptions): (req: any, res: any, next: any) => Promise<void>;
+
+interface NextAuthMiddlewareOptions extends MiddlewareOptions {
+    /** Pages to redirect to */
+    pages?: {
+        signIn?: string;
+        signUp?: string;
+    };
+    /** Authorized callbacks */
+    authorized?: (auth: {
+        user: any;
+    } | null, request: any) => boolean | Promise<boolean>;
+}
+/**
+ * Create Next.js middleware.
+ * Returns a redirect object or null (continue to next middleware).
+ */
+declare function nextjsMiddleware(auth: Auth, options?: NextAuthMiddlewareOptions): (request: any) => Promise<{
+    redirect: string;
+} | null>;
+/**
+ * Create Next.js API route helper.
+ */
+declare function nextjsApiAuth(auth: Auth): (request: any) => Promise<AuthMiddlewareResult>;
+
+/**
+ * Fastify middleware adapter.
+ */
+
+interface FastifyAuthMiddlewareOptions extends MiddlewareOptions {
+    onError?: (err: Error, request: any, reply: any) => void;
+}
+/**
+ * Create Fastify plugin.
+ */
+declare function fastifyPlugin(auth: Auth, options?: FastifyAuthMiddlewareOptions): (fastify: any) => Promise<void>;
+/**
+ * Create Fastify route protector.
+ */
+declare function requireAuthFastify(auth: Auth, options?: FastifyAuthMiddlewareOptions): (request: any, reply: any) => Promise<void>;
+
+/**
+ * Hono middleware adapter.
+ */
+
+interface HonoAuthMiddlewareOptions extends MiddlewareOptions {
+    onError?: (err: Error, c: any) => Response | Promise<Response>;
+}
+/**
+ * Create Hono middleware.
+ */
+declare function honoMiddleware(auth: Auth, options?: HonoAuthMiddlewareOptions): (c: any, next: () => Promise<void>) => Promise<any>;
+/**
+ * Create Hono route protector.
+ */
+declare function requireAuthHono(auth: Auth, options?: HonoAuthMiddlewareOptions): (c: any, next: () => Promise<void>) => Promise<any>;
+
+/**
+ * Password hashing using Node.js scrypt (built-in, no native deps).
+ */
+/**
+ * Hash a password using scrypt.
+ */
+declare function hashPassword(password: string): Promise<string>;
+/**
+ * Verify a password against a hash.
+ */
+declare function verifyPassword(password: string, hash: string): Promise<boolean>;
+
+/**
+ * JWT creation and verification using jose.
+ */
+
+/**
+ * Create a JWT token.
+ */
+declare function createToken(payload: Omit<JWTPayload, 'iat' | 'exp'>, secret: string, options?: {
+    maxAge?: number;
+}): Promise<string>;
+/**
+ * Verify and decode a JWT token.
+ */
+declare function verifyToken(token: string, secret: string): Promise<JWTPayload | null>;
+/**
+ * Decode a JWT without verification (for debugging).
+ */
+declare function decodeToken(token: string): JWTPayload | null;
+
+/**
+ * TOTP (Time-based One-Time Password) 2FA implementation.
+ * Uses HMAC-SHA1 based TOTP as per RFC 6238.
+ */
+interface TOTPConfig {
+    /** Number of digits in the code (default: 6) */
+    digits?: number;
+    /** Time step in seconds (default: 30) */
+    period?: number;
+    /** Algorithm (default: 'sha1') */
+    algorithm?: 'sha1' | 'sha256' | 'sha512';
+}
+/**
+ * Generate a random TOTP secret.
+ */
+declare function generateSecret(length?: number): string;
+/**
+ * Generate a TOTP code for a given secret and timestamp.
+ */
+declare function generateCode(secret: string, timestamp?: number, config?: TOTPConfig): string;
+/**
+ * Verify a TOTP code against a secret.
+ * Allows for ±1 time step drift.
+ * Uses timing-safe comparison to prevent timing attacks.
+ */
+declare function verifyCode(secret: string, code: string, config?: TOTPConfig): boolean;
+/**
+ * Generate a TOTP URI for QR code generation.
+ */
+declare function generateURI(secret: string, email: string, issuer?: string, config?: TOTPConfig): string;
+
+/**
+ * Email sending interface and built-in adapters.
+ */
+interface EmailAdapter {
+    send(params: {
+        to: string;
+        subject: string;
+        text?: string;
+        html?: string;
+    }): Promise<void>;
+}
+/**
+ * Console email adapter (logs to console — for development).
+ */
+declare class ConsoleEmailAdapter implements EmailAdapter {
+    send(params: {
+        to: string;
+        subject: string;
+        text?: string;
+        html?: string;
+    }): Promise<void>;
+}
+/**
+ * Send a verification email.
+ */
+declare function sendVerificationEmail(adapter: EmailAdapter, email: string, token: string, baseUrl?: string): Promise<void>;
+/**
+ * Send a password reset email.
+ */
+declare function sendPasswordResetEmail(adapter: EmailAdapter, email: string, token: string, baseUrl?: string): Promise<void>;
+
+/**
+ * Auth-specific error classes.
+ */
+declare class AuthError extends Error {
+    constructor(message: string);
+}
+declare class UnauthorizedError extends AuthError {
+    constructor(message?: string);
+}
+declare class ForbiddenError extends AuthError {
+    constructor(message?: string);
+}
+declare class InvalidCredentialsError extends AuthError {
+    constructor(message?: string);
+}
+declare class UserNotFoundError extends AuthError {
+    constructor(message?: string);
+}
+declare class EmailAlreadyExistsError extends AuthError {
+    constructor(message?: string);
+}
+declare class InvalidTokenError extends AuthError {
+    constructor(message?: string);
+}
+declare class TwoFactorRequiredError extends AuthError {
+    constructor(message?: string);
+}
+declare class TwoFactorInvalidError extends AuthError {
+    constructor(message?: string);
+}
+declare class SessionExpiredError extends AuthError {
+    constructor(message?: string);
+}
+declare class ProviderError extends AuthError {
+    constructor(message?: string);
+}
+
+/**
+ * @mountsqli/auth — Pre-built authentication system for MountSQLi.
+ */
+
+/**
+ * Create an Auth instance.
+ */
+declare function createAuth(config: AuthConfig): Auth;
+
+export { Auth, type AuthConfig, AuthError, type AuthMiddlewareResult, type AuthProvider, type AuthResult, type CallbacksConfig, ConsoleEmailAdapter, type CreateUserInput, type CredentialsProvider, type CredentialsProviderConfig, type EmailAdapter, EmailAlreadyExistsError, type EmailProvider, type ExpressAuthMiddlewareOptions, type FastifyAuthMiddlewareOptions, ForbiddenError, type GitHubProviderConfig, type GoogleProviderConfig, type HonoAuthMiddlewareOptions, InvalidCredentialsError, InvalidTokenError, type JWTPayload, type MiddlewareOptions, type NextAuthMiddlewareOptions, type OAuthCallbackParams, type OAuthProvider, type OAuthTokenResponse, type OAuthUserInfo, type PagesConfig, ProviderError, type Role, type Session, type SessionConfig, type SessionData, SessionExpiredError, TwoFactorInvalidError, TwoFactorRequiredError, UnauthorizedError, type User, UserNotFoundError, type UserRole, authAccounts, authRoles, authSessions, authUserRoles, authUsers, authVerificationTokens, createAuth, createToken, credentials, decodeToken, expressMiddleware, fastifyPlugin, generateCode, generateSecret, generateURI, github, google, hashPassword, honoMiddleware, nextjsApiAuth, nextjsMiddleware, requireAuth, requireAuthFastify, requireAuthHono, resolveAuth, sendPasswordResetEmail, sendVerificationEmail, verifyCode, verifyPassword, verifyToken };