@bloomneo/appkit 1.2.9

package/dist/auth/auth.d.ts

@@ -0,0 +1,182 @@
+/**
+ * Core authentication class with role-level-permission system
+ * @module @bloomneo/appkit/auth
+ * @file src/auth/authentication.ts
+ *
+ * @llm-rule WHEN: Building apps that need JWT operations, password hashing, and role-based middleware
+ * @llm-rule AVOID: Using directly - always get instance via auth.get()
+ * @llm-rule NOTE: Use requireUserRoles() for hierarchy-based access, requireUserPermissions() for action-specific access
+ * @llm-rule NOTE: Uses role.level format (user.basic, admin.tenant) with automatic inheritance
+ */
+import { type AuthConfig } from './defaults.js';
+export interface JwtPayload {
+    userId?: string | number;
+    keyId?: string;
+    type: 'login' | 'api_key';
+    role: string;
+    level: string;
+    permissions?: string[];
+    [key: string]: any;
+    iat?: number;
+    exp?: number;
+    iss?: string;
+    aud?: string;
+}
+export interface LoginTokenPayload {
+    userId: string | number;
+    type: 'login';
+    role: string;
+    level: string;
+    permissions?: string[];
+    [key: string]: any;
+}
+export interface ApiTokenPayload {
+    keyId: string;
+    type: 'api_key';
+    role: string;
+    level: string;
+    permissions?: string[];
+    [key: string]: any;
+}
+export interface ExpressRequest {
+    headers: {
+        [key: string]: string | string[] | undefined;
+    };
+    cookies?: {
+        [key: string]: string;
+    };
+    query?: {
+        [key: string]: any;
+    };
+    user?: JwtPayload;
+    token?: JwtPayload;
+    [key: string]: any;
+}
+export interface ExpressResponse {
+    status: (code: number) => {
+        json: (data: any) => void;
+    };
+    json: (data: any) => void;
+}
+export interface MiddlewareOptions {
+    getToken?: (request: ExpressRequest) => string | null;
+}
+export type ExpressMiddleware = (req: ExpressRequest, res: ExpressResponse, next: () => void) => void;
+/**
+ * Authentication class with JWT, password, and role-level-permission system
+ */
+export declare class AuthenticationClass {
+    config: AuthConfig;
+    constructor(config: AuthConfig);
+    /**
+     * Generates a login JWT token for user authentication
+     * @llm-rule WHEN: User successfully logs in to your app (mobile/web)
+     * @llm-rule AVOID: Using for API access - use generateApiToken instead
+     * @llm-rule NOTE: Creates JWT with userId and type: 'login'
+     */
+    generateLoginToken(payload: Omit<LoginTokenPayload, 'type' | 'iat' | 'exp' | 'iss' | 'aud'>, expiresIn?: string): string;
+    /**
+     * Generates an API JWT token for external access
+     * @llm-rule WHEN: Creating API keys for third-party integrations
+     * @llm-rule AVOID: Using for user authentication - use generateLoginToken instead
+     * @llm-rule NOTE: Creates JWT with keyId and type: 'api_key'
+     */
+    generateApiToken(payload: Omit<ApiTokenPayload, 'type' | 'iat' | 'exp' | 'iss' | 'aud'>, expiresIn?: string): string;
+    /**
+     * Internal method to create and sign JWT tokens
+     * @private
+     */
+    private signToken;
+    /**
+     * Verifies and decodes a JWT token (both login and API tokens)
+     * @llm-rule WHEN: Validating incoming tokens from requests
+     * @llm-rule AVOID: Using jwt.verify directly - this handles errors and validates structure
+     * @llm-rule NOTE: Handles both login tokens (userId) and API tokens (keyId)
+     */
+    verifyToken(token: string): JwtPayload;
+    /**
+     * Hashes a password using bcrypt
+     * @llm-rule WHEN: Storing user passwords - always hash before saving to database
+     * @llm-rule AVOID: Storing plain text passwords - major security vulnerability
+     * @llm-rule NOTE: Takes ~100ms with default 10 rounds - don't call in tight loops
+     */
+    hashPassword(password: string, rounds?: number): Promise<string>;
+    /**
+     * Compares a password with its hash
+     * @llm-rule WHEN: Validating user login credentials
+     * @llm-rule AVOID: Manual string comparison - timing attacks possible
+     * @llm-rule NOTE: Always returns boolean, never throws on comparison failure
+     */
+    comparePassword(password: string, hash: string): Promise<boolean>;
+    /**
+     * Safely extracts user from request - never crashes
+     * @llm-rule WHEN: Need to access user data from authenticated requests
+     * @llm-rule AVOID: Accessing req.user directly - may be undefined and cause crashes
+     * @llm-rule NOTE: Always returns null for unauthenticated requests - safe to use
+     * @llm-rule NOTE: Works with both login authentication (req.user) and API tokens (req.token)
+     */
+    user(request: ExpressRequest): JwtPayload | null;
+    /**
+     * Checks if user has specified role with automatic inheritance
+     * @llm-rule WHEN: Checking if user can access role-protected resources
+     * @llm-rule AVOID: Manual role comparisons - this handles inheritance automatically
+     * @llm-rule NOTE: Higher levels inherit lower (admin.org has admin.tenant access)
+     * @llm-rule NOTE: INHERITANCE EXAMPLES:
+     * @llm-rule NOTE: auth.hasRole('admin.org', 'admin.tenant') → TRUE (org > tenant)
+     * @llm-rule NOTE: auth.hasRole('admin.system', 'user.basic') → TRUE (system > basic)
+     * @llm-rule NOTE: auth.hasRole('user.basic', 'admin.tenant') → FALSE (basic < tenant)
+     * @llm-rule NOTE: Role hierarchy: admin.system > admin.org > admin.tenant > user.max > user.pro > user.basic
+     */
+    hasRole(userRoleLevel: string, requiredRoleLevel: string): boolean;
+    /**
+     * Checks if user has specific permission with automatic action inheritance
+     * @llm-rule WHEN: Checking fine-grained permissions for specific actions
+     * @llm-rule AVOID: Hardcoding permission checks - this handles action inheritance
+     * @llm-rule NOTE: 'manage:scope' includes ALL other actions for that scope
+     * @llm-rule NOTE: PERMISSION INHERITANCE EXAMPLES:
+     * @llm-rule NOTE: If user has 'manage:tenant' → can('edit:tenant') returns TRUE
+     * @llm-rule NOTE: If user has 'manage:tenant' → can('view:tenant') returns TRUE
+     * @llm-rule NOTE: If user has 'edit:tenant' → can('manage:tenant') returns FALSE
+     * @llm-rule NOTE: Actions hierarchy: manage > delete > edit > create > view
+     */
+    can(user: JwtPayload, permission: string): boolean;
+    /**
+     * Creates Express authentication middleware for login tokens
+     * @llm-rule WHEN: Protecting routes that need authenticated users
+     * @llm-rule AVOID: Using for API routes - use requireApiToken instead
+     * @llm-rule NOTE: Validates login tokens (type: 'login') and sets req.user
+     */
+    requireLoginToken(options?: MiddlewareOptions): ExpressMiddleware;
+    /**
+     * Creates Express role-based authorization middleware for authenticated users
+     * @llm-rule WHEN: Protecting routes that require specific user roles
+     * @llm-rule AVOID: Using without requireLoginToken - this assumes user is already authenticated
+     * @llm-rule AVOID: Using with API tokens - API tokens don't have user roles
+     * @llm-rule NOTE: User needs ANY role from the array (OR logic)
+     * @llm-rule NOTE: Role inheritance applies - admin.org can access admin.tenant routes
+     */
+    requireUserRoles(requiredRoles: string[]): ExpressMiddleware;
+    /**
+     * Creates Express permission-based authorization middleware for authenticated users
+     * @llm-rule WHEN: Protecting routes that require specific user permissions
+     * @llm-rule AVOID: Using without requireLoginToken - this assumes user is already authenticated
+     * @llm-rule AVOID: Using with API tokens - API tokens don't have user permissions
+     * @llm-rule NOTE: User needs ALL permissions from the array (AND logic)
+     * @llm-rule NOTE: Permission inheritance applies - manage:tenant can access edit:tenant routes
+     */
+    requireUserPermissions(requiredPermissions: string[]): ExpressMiddleware;
+    /**
+     * Creates Express API token authentication middleware for external access
+     * @llm-rule WHEN: Protecting API routes for third-party integrations
+     * @llm-rule AVOID: Using for user routes - use requireLoginToken instead
+     * @llm-rule NOTE: Validates API tokens (type: 'api_key') and sets req.token
+     */
+    requireApiToken(options?: MiddlewareOptions): ExpressMiddleware;
+    /**
+     * Gets default token extractor that checks headers, cookies, and query params
+     * @llm-rule WHEN: Need custom token extraction logic
+     * @llm-rule AVOID: Modifying directly - pass custom getToken to middleware options
+     */
+    private getDefaultTokenExtractor;
+}
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/auth/auth.ts"],"names":[],"mappings":"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"}

package/dist/auth/auth.js

@@ -0,0 +1,477 @@
+/**
+ * Core authentication class with role-level-permission system
+ * @module @bloomneo/appkit/auth
+ * @file src/auth/authentication.ts
+ *
+ * @llm-rule WHEN: Building apps that need JWT operations, password hashing, and role-based middleware
+ * @llm-rule AVOID: Using directly - always get instance via auth.get()
+ * @llm-rule NOTE: Use requireUserRoles() for hierarchy-based access, requireUserPermissions() for action-specific access
+ * @llm-rule NOTE: Uses role.level format (user.basic, admin.tenant) with automatic inheritance
+ */
+import jwt from 'jsonwebtoken';
+import bcrypt from 'bcrypt';
+import { validateRounds, validateRoleLevel, validatePermission, } from './defaults.js';
+/**
+ * Authentication class with JWT, password, and role-level-permission system
+ */
+export class AuthenticationClass {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Generates a login JWT token for user authentication
+     * @llm-rule WHEN: User successfully logs in to your app (mobile/web)
+     * @llm-rule AVOID: Using for API access - use generateApiToken instead
+     * @llm-rule NOTE: Creates JWT with userId and type: 'login'
+     */
+    generateLoginToken(payload, expiresIn) {
+        const loginPayload = {
+            ...payload,
+            type: 'login',
+        };
+        return this.signToken(loginPayload, expiresIn || '7d');
+    }
+    /**
+     * Generates an API JWT token for external access
+     * @llm-rule WHEN: Creating API keys for third-party integrations
+     * @llm-rule AVOID: Using for user authentication - use generateLoginToken instead
+     * @llm-rule NOTE: Creates JWT with keyId and type: 'api_key'
+     */
+    generateApiToken(payload, expiresIn) {
+        const apiPayload = {
+            ...payload,
+            type: 'api_key',
+        };
+        return this.signToken(apiPayload, expiresIn || '1y');
+    }
+    /**
+     * Internal method to create and sign JWT tokens
+     * @private
+     */
+    signToken(payload, expiresIn) {
+        if (!payload || typeof payload !== 'object') {
+            throw new Error('Payload must be an object');
+        }
+        // Validate based on token type
+        if (payload.type === 'login') {
+            if (!payload.userId) {
+                throw new Error('Login token must include userId');
+            }
+        }
+        else if (payload.type === 'api_key') {
+            if (!payload.keyId) {
+                throw new Error('API token must include keyId');
+            }
+        }
+        else {
+            throw new Error('Token type must be "login" or "api_key"');
+        }
+        if (!payload.role || !payload.level) {
+            throw new Error('Payload must include both role and level');
+        }
+        // Validate role.level exists
+        const roleLevel = `${payload.role}.${payload.level}`;
+        if (!validateRoleLevel(roleLevel, this.config.roles)) {
+            throw new Error(`Invalid role.level: "${roleLevel}"`);
+        }
+        const jwtSecret = this.config.jwt.secret;
+        if (!jwtSecret) {
+            throw new Error('JWT secret required. Set VOILA_AUTH_SECRET environment variable');
+        }
+        const tokenExpiration = expiresIn || this.config.jwt.expiresIn;
+        try {
+            return jwt.sign(payload, jwtSecret, {
+                expiresIn: tokenExpiration,
+            });
+        }
+        catch (error) {
+            throw new Error(`Failed to generate token: ${error.message}`);
+        }
+    }
+    /**
+     * Verifies and decodes a JWT token (both login and API tokens)
+     * @llm-rule WHEN: Validating incoming tokens from requests
+     * @llm-rule AVOID: Using jwt.verify directly - this handles errors and validates structure
+     * @llm-rule NOTE: Handles both login tokens (userId) and API tokens (keyId)
+     */
+    verifyToken(token) {
+        if (!token || typeof token !== 'string') {
+            throw new Error('Token must be a string');
+        }
+        const jwtSecret = this.config.jwt.secret;
+        if (!jwtSecret) {
+            throw new Error('JWT secret required. Set VOILA_AUTH_SECRET environment variable');
+        }
+        try {
+            const decoded = jwt.verify(token, jwtSecret, {
+                algorithms: [this.config.jwt.algorithm],
+            });
+            // Validate decoded token has required structure
+            if (!decoded.role || !decoded.level || !decoded.type) {
+                throw new Error('Token missing required role, level, or type information');
+            }
+            // Validate type-specific requirements
+            if (decoded.type === 'login' && !decoded.userId) {
+                throw new Error('Login token missing userId');
+            }
+            if (decoded.type === 'api_key' && !decoded.keyId) {
+                throw new Error('API token missing keyId');
+            }
+            return decoded;
+        }
+        catch (error) {
+            if (error.name === 'TokenExpiredError') {
+                throw new Error('Token has expired');
+            }
+            if (error.name === 'JsonWebTokenError') {
+                throw new Error('Invalid token');
+            }
+            throw new Error(`Token verification failed: ${error.message}`);
+        }
+    }
+    /**
+     * Hashes a password using bcrypt
+     * @llm-rule WHEN: Storing user passwords - always hash before saving to database
+     * @llm-rule AVOID: Storing plain text passwords - major security vulnerability
+     * @llm-rule NOTE: Takes ~100ms with default 10 rounds - don't call in tight loops
+     */
+    async hashPassword(password, rounds) {
+        if (!password || typeof password !== 'string') {
+            throw new Error('Password must be a non-empty string');
+        }
+        const saltRounds = rounds || this.config.password.saltRounds;
+        validateRounds(saltRounds);
+        try {
+            return await bcrypt.hash(password, saltRounds);
+        }
+        catch (error) {
+            throw new Error(`Password hashing failed: ${error.message}`);
+        }
+    }
+    /**
+     * Compares a password with its hash
+     * @llm-rule WHEN: Validating user login credentials
+     * @llm-rule AVOID: Manual string comparison - timing attacks possible
+     * @llm-rule NOTE: Always returns boolean, never throws on comparison failure
+     */
+    async comparePassword(password, hash) {
+        if (!password || typeof password !== 'string') {
+            return false;
+        }
+        if (!hash || typeof hash !== 'string') {
+            return false;
+        }
+        try {
+            return await bcrypt.compare(password, hash);
+        }
+        catch (error) {
+            // bcrypt.compare can fail on malformed hashes
+            return false;
+        }
+    }
+    /**
+     * Safely extracts user from request - never crashes
+     * @llm-rule WHEN: Need to access user data from authenticated requests
+     * @llm-rule AVOID: Accessing req.user directly - may be undefined and cause crashes
+     * @llm-rule NOTE: Always returns null for unauthenticated requests - safe to use
+     * @llm-rule NOTE: Works with both login authentication (req.user) and API tokens (req.token)
+     */
+    user(request) {
+        if (!request || typeof request !== 'object') {
+            return null;
+        }
+        // Check for user authentication first (login-based)
+        if (request.user && typeof request.user === 'object' && (request.user.userId || request.user.keyId)) {
+            return request.user;
+        }
+        // Check for token authentication (API-based)
+        if (request.token && typeof request.token === 'object' && (request.token.userId || request.token.keyId)) {
+            return request.token;
+        }
+        return null;
+    }
+    /**
+     * Checks if user has specified role with automatic inheritance
+     * @llm-rule WHEN: Checking if user can access role-protected resources
+     * @llm-rule AVOID: Manual role comparisons - this handles inheritance automatically
+     * @llm-rule NOTE: Higher levels inherit lower (admin.org has admin.tenant access)
+     * @llm-rule NOTE: INHERITANCE EXAMPLES:
+     * @llm-rule NOTE: auth.hasRole('admin.org', 'admin.tenant') → TRUE (org > tenant)
+     * @llm-rule NOTE: auth.hasRole('admin.system', 'user.basic') → TRUE (system > basic)
+     * @llm-rule NOTE: auth.hasRole('user.basic', 'admin.tenant') → FALSE (basic < tenant)
+     * @llm-rule NOTE: Role hierarchy: admin.system > admin.org > admin.tenant > user.max > user.pro > user.basic
+     */
+    hasRole(userRoleLevel, requiredRoleLevel) {
+        // INHERITANCE RULE: Higher role levels automatically include lower levels
+        // Example: admin.org (level 6) includes admin.tenant (level 5) access
+        if (!userRoleLevel || !requiredRoleLevel) {
+            return false;
+        }
+        if (!validateRoleLevel(userRoleLevel, this.config.roles)) {
+            return false;
+        }
+        if (!validateRoleLevel(requiredRoleLevel, this.config.roles)) {
+            return false;
+        }
+        const userLevel = this.config.roles[userRoleLevel]?.level;
+        const requiredLevel = this.config.roles[requiredRoleLevel]?.level;
+        if (userLevel === undefined || requiredLevel === undefined) {
+            return false;
+        }
+        // Higher numeric levels include lower levels
+        return userLevel >= requiredLevel;
+    }
+    /**
+     * Checks if user has specific permission with automatic action inheritance
+     * @llm-rule WHEN: Checking fine-grained permissions for specific actions
+     * @llm-rule AVOID: Hardcoding permission checks - this handles action inheritance
+     * @llm-rule NOTE: 'manage:scope' includes ALL other actions for that scope
+     * @llm-rule NOTE: PERMISSION INHERITANCE EXAMPLES:
+     * @llm-rule NOTE: If user has 'manage:tenant' → can('edit:tenant') returns TRUE
+     * @llm-rule NOTE: If user has 'manage:tenant' → can('view:tenant') returns TRUE
+     * @llm-rule NOTE: If user has 'edit:tenant' → can('manage:tenant') returns FALSE
+     * @llm-rule NOTE: Actions hierarchy: manage > delete > edit > create > view
+     */
+    can(user, permission) {
+        // PERMISSION INHERITANCE: 'manage:tenant' automatically includes:
+        // - view:tenant, create:tenant, edit:tenant, delete:tenant
+        // Example: if user has 'manage:tenant', they can do 'edit:tenant'
+        if (!user || !permission) {
+            return false;
+        }
+        if (!validatePermission(permission)) {
+            throw new Error(`Invalid permission format: "${permission}"`);
+        }
+        // Check if user has the specific permission
+        if (user.permissions && Array.isArray(user.permissions)) {
+            if (user.permissions.includes(permission)) {
+                return true;
+            }
+            // Check for manage permission (includes all other actions)
+            const [action, scope] = permission.split(':');
+            if (action !== 'manage') {
+                const managePermission = `manage:${scope}`;
+                if (user.permissions.includes(managePermission)) {
+                    return true;
+                }
+            }
+        }
+        // Fallback: check default permissions for user's role.level
+        const userRoleLevel = `${user.role}.${user.level}`;
+        const defaultPermissions = this.config.permissions.defaults[userRoleLevel];
+        if (defaultPermissions && Array.isArray(defaultPermissions)) {
+            if (defaultPermissions.includes(permission)) {
+                return true;
+            }
+            // Check for manage permission in defaults
+            const [action, scope] = permission.split(':');
+            if (action !== 'manage') {
+                const managePermission = `manage:${scope}`;
+                if (defaultPermissions.includes(managePermission)) {
+                    return true;
+                }
+            }
+        }
+        return false;
+    }
+    // ====================================================================
+    // EXPRESS MIDDLEWARE
+    // ====================================================================
+    /**
+     * Creates Express authentication middleware for login tokens
+     * @llm-rule WHEN: Protecting routes that need authenticated users
+     * @llm-rule AVOID: Using for API routes - use requireApiToken instead
+     * @llm-rule NOTE: Validates login tokens (type: 'login') and sets req.user
+     */
+    requireLoginToken(options = {}) {
+        if (!this.config.jwt.secret) {
+            throw new Error('JWT secret required for authentication middleware');
+        }
+        const getToken = options.getToken || this.getDefaultTokenExtractor();
+        return (req, res, next) => {
+            try {
+                const token = getToken(req);
+                if (!token) {
+                    return res.status(401).json({
+                        error: 'Authentication required',
+                        message: this.config.middleware.errorMessages.noToken,
+                    });
+                }
+                const payload = this.verifyToken(token);
+                if (payload.type !== 'login') {
+                    return res.status(401).json({
+                        error: 'Invalid token type',
+                        message: 'Login token required for this endpoint',
+                    });
+                }
+                req.user = payload;
+                next();
+            }
+            catch (error) {
+                const isExpired = error.message === 'Token has expired';
+                const message = isExpired
+                    ? this.config.middleware.errorMessages.expiredToken
+                    : this.config.middleware.errorMessages.invalidToken;
+                return res.status(401).json({
+                    error: 'Unauthorized',
+                    message,
+                });
+            }
+        };
+    }
+    /**
+     * Creates Express role-based authorization middleware for authenticated users
+     * @llm-rule WHEN: Protecting routes that require specific user roles
+     * @llm-rule AVOID: Using without requireLoginToken - this assumes user is already authenticated
+     * @llm-rule AVOID: Using with API tokens - API tokens don't have user roles
+     * @llm-rule NOTE: User needs ANY role from the array (OR logic)
+     * @llm-rule NOTE: Role inheritance applies - admin.org can access admin.tenant routes
+     */
+    requireUserRoles(requiredRoles) {
+        if (!Array.isArray(requiredRoles) || requiredRoles.length === 0) {
+            throw new Error('requiredRoles must be a non-empty array');
+        }
+        // Validate all roles exist
+        for (const role of requiredRoles) {
+            if (!validateRoleLevel(role, this.config.roles)) {
+                throw new Error(`Invalid role.level for middleware: "${role}"`);
+            }
+        }
+        return (req, res, next) => {
+            const user = this.user(req);
+            if (!user) {
+                return res.status(401).json({
+                    error: 'Authentication required',
+                    message: this.config.middleware.errorMessages.noToken,
+                });
+            }
+            if (user.type !== 'login') {
+                return res.status(403).json({
+                    error: 'Access denied',
+                    message: 'User roles only apply to login tokens',
+                });
+            }
+            const userRoleLevel = `${user.role}.${user.level}`;
+            const hasRequiredRole = requiredRoles.some(requiredRole => this.hasRole(userRoleLevel, requiredRole));
+            if (!hasRequiredRole) {
+                return res.status(403).json({
+                    error: 'Access denied',
+                    message: this.config.middleware.errorMessages.insufficientRole,
+                });
+            }
+            next();
+        };
+    }
+    /**
+     * Creates Express permission-based authorization middleware for authenticated users
+     * @llm-rule WHEN: Protecting routes that require specific user permissions
+     * @llm-rule AVOID: Using without requireLoginToken - this assumes user is already authenticated
+     * @llm-rule AVOID: Using with API tokens - API tokens don't have user permissions
+     * @llm-rule NOTE: User needs ALL permissions from the array (AND logic)
+     * @llm-rule NOTE: Permission inheritance applies - manage:tenant can access edit:tenant routes
+     */
+    requireUserPermissions(requiredPermissions) {
+        if (!Array.isArray(requiredPermissions) || requiredPermissions.length === 0) {
+            throw new Error('requiredPermissions must be a non-empty array');
+        }
+        // Validate all permissions
+        for (const permission of requiredPermissions) {
+            if (!validatePermission(permission)) {
+                throw new Error(`Invalid permission format for middleware: "${permission}"`);
+            }
+        }
+        return (req, res, next) => {
+            const user = this.user(req);
+            if (!user) {
+                return res.status(401).json({
+                    error: 'Authentication required',
+                    message: this.config.middleware.errorMessages.noToken,
+                });
+            }
+            if (user.type !== 'login') {
+                return res.status(403).json({
+                    error: 'Access denied',
+                    message: 'User permissions only apply to login tokens',
+                });
+            }
+            const hasAllPermissions = requiredPermissions.every(permission => this.can(user, permission));
+            if (!hasAllPermissions) {
+                return res.status(403).json({
+                    error: 'Access denied',
+                    message: this.config.middleware.errorMessages.insufficientPermissions,
+                });
+            }
+            next();
+        };
+    }
+    /**
+     * Creates Express API token authentication middleware for external access
+     * @llm-rule WHEN: Protecting API routes for third-party integrations
+     * @llm-rule AVOID: Using for user routes - use requireLoginToken instead
+     * @llm-rule NOTE: Validates API tokens (type: 'api_key') and sets req.token
+     */
+    requireApiToken(options = {}) {
+        if (!this.config.jwt.secret) {
+            throw new Error('JWT secret required for API token authentication middleware');
+        }
+        const getToken = options.getToken || this.getDefaultTokenExtractor();
+        return (req, res, next) => {
+            try {
+                const token = getToken(req);
+                if (!token) {
+                    return res.status(401).json({
+                        error: 'API token required',
+                        message: 'API token required for this endpoint',
+                    });
+                }
+                const payload = this.verifyToken(token);
+                if (payload.type !== 'api_key') {
+                    return res.status(401).json({
+                        error: 'Invalid token type',
+                        message: 'API token required for this endpoint',
+                    });
+                }
+                req.token = payload;
+                next();
+            }
+            catch (error) {
+                const isExpired = error.message === 'Token has expired';
+                const message = isExpired
+                    ? 'API token has expired'
+                    : 'Invalid API token';
+                return res.status(401).json({
+                    error: 'Unauthorized',
+                    message,
+                });
+            }
+        };
+    }
+    /**
+     * Gets default token extractor that checks headers, cookies, and query params
+     * @llm-rule WHEN: Need custom token extraction logic
+     * @llm-rule AVOID: Modifying directly - pass custom getToken to middleware options
+     */
+    getDefaultTokenExtractor() {
+        return (request) => {
+            // Check Authorization header (Bearer token)
+            const authHeader = request.headers.authorization;
+            if (authHeader && typeof authHeader === 'string') {
+                const match = authHeader.match(/^Bearer\s+(.+)$/);
+                if (match) {
+                    return match[1];
+                }
+            }
+            // Check cookies
+            if (request.cookies?.token) {
+                return request.cookies.token;
+            }
+            // Check query parameter
+            if (request.query?.token && typeof request.query.token === 'string') {
+                return request.query.token;
+            }
+            return null;
+        };
+    }
+}
+//# sourceMappingURL=auth.js.map