@technomoron/api-server-base 2.0.0-beta.17 → 2.0.0-beta.19

package/dist/esm/api-server-base.d.ts

@@ -100,7 +100,21 @@ export interface ApiServerConf {
     swaggerPath?: string;
     accessSecret: string;
     refreshSecret: string;
+    /** Cookie domain for auth cookies. Prefer leaving empty for localhost/development. */
     cookieDomain: string;
+    /** Cookie path for auth cookies. */
+    cookiePath?: string;
+    /** Cookie SameSite attribute for auth cookies. */
+    cookieSameSite?: 'lax' | 'strict' | 'none';
+    /**
+     * Cookie Secure attribute for auth cookies.
+     * - true: always secure
+     * - false: never secure
+     * - 'auto': secure when request is HTTPS (or forwarded as HTTPS)
+     */
+    cookieSecure?: boolean | 'auto';
+    /** Cookie HttpOnly attribute for auth cookies. */
+    cookieHttpOnly?: boolean;
     accessCookie: string;
     refreshCookie: string;
     accessExpiry: number;
@@ -115,24 +129,38 @@ export interface ApiServerConf {
     minClientVersion: string;
     tokenStore?: TokenStore;
     authStores?: ApiServerAuthStores;
+    onStartError?: (error: Error) => void;
 }
 export declare class ApiServer {
     app: Application;
-    currReq: ApiRequest | null;
     readonly config: ApiServerConf;
     readonly startedAt: number;
     private readonly apiBasePath;
+    private readonly apiRouter;
+    private finalized;
     private storageAdapter;
     private moduleAdapter;
     private serverAuthAdapter;
     private apiNotFoundHandler;
+    private apiErrorHandlerInstalled;
     private tokenStoreAdapter;
     private userStoreAdapter;
     private passkeyServiceAdapter;
     private oauthStoreAdapter;
     private canImpersonateAdapter;
     private readonly jwtHelper;
+    private currReqDeprecationWarned;
+    /**
+     * @deprecated ApiServer does not track a global "current request". This value is always null.
+     * Use the per-request ApiRequest passed to handlers, or `req.apiReq` / `res.locals.apiReq`
+     * when mounting raw Express endpoints.
+     */
+    get currReq(): ApiRequest | null;
+    set currReq(_value: ApiRequest | null);
     constructor(config?: Partial<ApiServerConf>);
+    private assertNotFinalized;
+    private toApiRouterPath;
+    finalize(): this;
     authStorage<UserRow, SafeUser>(storage: AuthAdapter<UserRow, SafeUser>): this;
     /**
      * @deprecated Use {@link ApiServer.authStorage} instead.
@@ -200,9 +228,10 @@ export declare class ApiServer {
     private installSwaggerHandler;
     private normalizeApiBasePath;
     private installApiNotFoundHandler;
-    private ensureApiNotFoundOrdering;
+    private installApiErrorHandler;
     private describeMissingEndpoint;
     start(): this;
+    private internalServerErrorMessage;
     private verifyJWT;
     private jwtCookieOptions;
     private setAccessCookie;

package/dist/esm/api-server-base.js

@@ -14,6 +14,7 @@ import express from 'express';
 import multer from 'multer';
 import { nullAuthModule } from './auth-api/module.js';
 import { nullAuthAdapter } from './auth-api/storage.js';
+import { buildAuthCookieOptions } from './auth-cookie-options.js';
 import { TokenStore } from './token/base.js';
 class JwtHelperStore extends TokenStore {
     async save() {
@@ -70,6 +71,7 @@ function hydrateGetBody(req) {
         req.body = { ...query };
         return;
     }
+    // Keep explicit body fields authoritative when both query and body provide the same key.
     req.body = { ...query, ...body };
 }
 function normalizeIpAddress(candidate) {
@@ -329,6 +331,17 @@ function isApiErrorLike(candidate) {
     const maybeError = candidate;
     return typeof maybeError.code === 'number' && typeof maybeError.message === 'string';
 }
+function asHttpStatus(error) {
+    if (!error || typeof error !== 'object') {
+        return null;
+    }
+    const maybe = error;
+    const status = typeof maybe.status === 'number' ? maybe.status : maybe.statusCode;
+    if (typeof status === 'number' && status >= 400 && status <= 599) {
+        return status;
+    }
+    return null;
+}
 function fillConfig(config) {
     return {
         apiPort: config.apiPort ?? 3101,
@@ -343,7 +356,11 @@ function fillConfig(config) {
         swaggerPath: config.swaggerPath ?? '',
         accessSecret: config.accessSecret ?? '',
         refreshSecret: config.refreshSecret ?? '',
-        cookieDomain: config.cookieDomain ?? '.somewhere-over-the-rainbow.com',
+        cookieDomain: config.cookieDomain ?? '',
+        cookiePath: config.cookiePath ?? '/',
+        cookieSameSite: config.cookieSameSite ?? 'lax',
+        cookieSecure: config.cookieSecure ?? 'auto',
+        cookieHttpOnly: config.cookieHttpOnly ?? true,
         accessCookie: config.accessCookie ?? 'dat',
         refreshCookie: config.refreshCookie ?? 'drt',
         accessExpiry: config.accessExpiry ?? 60 * 15,
@@ -357,19 +374,37 @@ function fillConfig(config) {
         apiVersion: config.apiVersion ?? '',
         minClientVersion: config.minClientVersion ?? '',
         tokenStore: config.tokenStore,
-        authStores: config.authStores
+        authStores: config.authStores,
+        onStartError: config.onStartError
     };
 }
 export class ApiServer {
+    /**
+     * @deprecated ApiServer does not track a global "current request". This value is always null.
+     * Use the per-request ApiRequest passed to handlers, or `req.apiReq` / `res.locals.apiReq`
+     * when mounting raw Express endpoints.
+     */
+    get currReq() {
+        return null;
+    }
+    set currReq(_value) {
+        if (this.config.devMode && !this.currReqDeprecationWarned) {
+            this.currReqDeprecationWarned = true;
+            console.warn('[api-server-base] ApiServer.currReq is deprecated and always null. Use req.apiReq or res.locals.apiReq.');
+        }
+        void _value;
+    }
     constructor(config = {}) {
-        this.currReq = null;
+        this.finalized = false;
         this.serverAuthAdapter = null;
         this.apiNotFoundHandler = null;
+        this.apiErrorHandlerInstalled = false;
         this.tokenStoreAdapter = null;
         this.userStoreAdapter = null;
         this.passkeyServiceAdapter = null;
         this.oauthStoreAdapter = null;
         this.canImpersonateAdapter = null;
+        this.currReqDeprecationWarned = false;
         this.config = fillConfig(config);
         this.apiBasePath = this.normalizeApiBasePath(this.config.apiBasePath);
         this.startedAt = Date.now();
@@ -387,16 +422,68 @@ export class ApiServer {
             this.storageAdapter = this.getServerAuthAdapter();
         }
         this.app = express();
+        // Mount API modules and any custom endpoints under `apiBasePath` on this router so we can keep
+        // the API 404 handler ordered last without relying on Express internals.
+        this.apiRouter = express.Router();
         if (config.uploadPath) {
-            const upload = multer({ dest: config.uploadPath });
+            const upload = multer({ dest: config.uploadPath, limits: { fileSize: this.config.uploadMax } });
             this.app.use(upload.any());
+            // Multer errors happen before ApiModule route wrappers; format the common "too large" failure.
+            this.app.use((err, _req, res, next) => {
+                const code = err && typeof err === 'object' ? err.code : undefined;
+                if (code === 'LIMIT_FILE_SIZE') {
+                    res.status(413).json({
+                        success: false,
+                        code: 413,
+                        message: `Upload exceeds maximum size of ${this.config.uploadMax} bytes`,
+                        data: null,
+                        errors: {}
+                    });
+                    return;
+                }
+                next(err);
+            });
         }
         this.middlewares();
         this.installStaticDirs();
         this.installPingHandler();
         this.installSwaggerHandler();
+        this.app.use(this.apiBasePath, this.apiRouter);
         // addSwaggerUi(this.app);
         this.installApiNotFoundHandler();
+        this.installApiErrorHandler();
+    }
+    assertNotFinalized(action) {
+        if (this.finalized) {
+            throw new Error(`Cannot call ApiServer.${action}() after finalize()/start()`);
+        }
+    }
+    toApiRouterPath(candidate) {
+        if (typeof candidate !== 'string') {
+            return null;
+        }
+        const trimmed = candidate.trim();
+        if (!trimmed) {
+            return null;
+        }
+        const normalized = trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+        const base = this.apiBasePath;
+        if (base === '/') {
+            return normalized;
+        }
+        if (normalized === base) {
+            return '/';
+        }
+        if (normalized.startsWith(`${base}/`)) {
+            return normalized.slice(base.length) || '/';
+        }
+        return null;
+    }
+    finalize() {
+        this.installApiNotFoundHandler();
+        this.installApiErrorHandler();
+        this.finalized = true;
+        return this;
     }
     authStorage(storage) {
         this.storageAdapter = storage;
@@ -623,7 +710,7 @@ export class ApiServer {
         }
         return false;
     }
-    guessExceptionText(error, defMsg = 'Unkown Error') {
+    guessExceptionText(error, defMsg = 'Unknown Error') {
         return guess_exception_text(error, defMsg);
     }
     async authorize(apiReq, requiredClass) {
@@ -649,6 +736,26 @@ export class ApiServer {
             credentials: true
         };
         this.app.use(cors(corsOptions));
+        // Provide a consistent and non-500 response when requests are blocked by the CORS allowlist.
+        this.app.use((err, req, res, next) => {
+            const message = err instanceof Error ? err.message : '';
+            if (message.includes('Not allowed by CORS')) {
+                const isApiRequest = Boolean(req.originalUrl?.startsWith(this.apiBasePath));
+                if (isApiRequest) {
+                    res.status(403).json({
+                        success: false,
+                        code: 403,
+                        message: 'Origin not allowed by CORS',
+                        data: null,
+                        errors: {}
+                    });
+                    return;
+                }
+                res.status(403).send('Origin not allowed by CORS');
+                return;
+            }
+            next(err);
+        });
     }
     installStaticDirs() {
         const staticDirs = this.config.staticDirs;
@@ -717,8 +824,12 @@ export class ApiServer {
         const base = this.apiBasePath === '/' ? '' : this.apiBasePath;
         const resolved = rawPath.length > 0 ? rawPath : `${base}/swagger`;
         const path = resolved.startsWith('/') ? resolved : `/${resolved}`;
-        const spec = this.loadSwaggerSpec();
+        let specCache;
         this.app.get(path, (_req, res) => {
+            if (specCache === undefined) {
+                specCache = this.loadSwaggerSpec();
+            }
+            const spec = specCache;
             if (!spec) {
                 res.status(500).json({
                     success: false,
@@ -762,21 +873,12 @@ export class ApiServer {
         };
         this.app.use(this.apiBasePath, this.apiNotFoundHandler);
     }
-    ensureApiNotFoundOrdering() {
-        this.installApiNotFoundHandler();
-        if (!this.apiNotFoundHandler) {
+    installApiErrorHandler() {
+        if (this.apiErrorHandlerInstalled) {
             return;
         }
-        const stack = this.app._router?.stack;
-        if (!stack) {
-            return;
-        }
-        const index = stack.findIndex((layer) => layer.handle === this.apiNotFoundHandler);
-        if (index === -1 || index === stack.length - 1) {
-            return;
-        }
-        const [layer] = stack.splice(index, 1);
-        stack.push(layer);
+        this.apiErrorHandlerInstalled = true;
+        this.app.use(this.apiBasePath, this.expressErrorHandler());
     }
     describeMissingEndpoint(req) {
         const method = typeof req.method === 'string' ? req.method.toUpperCase() : 'GET';
@@ -784,6 +886,10 @@ export class ApiServer {
         return `No such endpoint: ${method} ${target}`;
     }
     start() {
+        if (!this.finalized) {
+            console.warn('[api-server-base] ApiServer.start() called without finalize(); auto-finalizing. Call server.finalize() before start() to silence this warning.');
+            this.finalize();
+        }
         this.app
             .listen({
             port: this.config.apiPort,
@@ -793,22 +899,32 @@ export class ApiServer {
             console.log(`Server is running on http://${this.config.apiHost}:${this.config.apiPort}`);
         })
             .on('error', (error) => {
+            let message;
             if (error.code === 'EADDRINUSE') {
-                console.error(`Error: Port ${this.config.apiPort} is already in use.`);
+                message = `Port ${this.config.apiPort} is already in use.`;
             }
             else if (error.code === 'EACCES') {
-                console.error(`Error: Insufficient permissions to bind to port ${this.config.apiPort}. Try using a port number >= 1024 or running with elevated privileges.`);
+                message = `Insufficient permissions to bind to port ${this.config.apiPort}. Try using a port number >= 1024 or running with elevated privileges.`;
             }
             else if (error.code === 'EADDRNOTAVAIL') {
-                console.error(`Error: Address ${this.config.apiHost} is not available on this machine.`);
+                message = `Address ${this.config.apiHost} is not available on this machine.`;
             }
             else {
-                console.error(`Failed to start server: ${error.message}`);
+                message = `Failed to start server: ${error.message}`;
             }
-            process.exit(1);
+            const err = new Error(message);
+            err.cause = error;
+            if (typeof this.config.onStartError === 'function') {
+                this.config.onStartError(err);
+                return;
+            }
+            throw err;
         });
         return this;
     }
+    internalServerErrorMessage(error) {
+        return this.config.debug ? this.guessExceptionText(error) : 'Internal server error';
+    }
     async verifyJWT(token) {
         if (!this.config.accessSecret) {
             return { tokenData: undefined, error: 'JWT authentication disabled; no jwtSecret set', expired: false };
@@ -823,29 +939,7 @@ export class ApiServer {
         return { tokenData: result.data, error: undefined, expired: false };
     }
     jwtCookieOptions(apiReq) {
-        const conf = this.config;
-        const forwarded = apiReq.req.headers['x-forwarded-proto'];
-        const referer = apiReq.req.headers['origin'] ?? apiReq.req.headers['referer'];
-        const origin = typeof referer === 'string' ? referer : '';
-        const isHttps = forwarded === 'https' || apiReq.req.protocol === 'https';
-        const isLocalhost = origin.includes('localhost');
-        const options = {
-            httpOnly: true,
-            secure: true,
-            sameSite: 'strict',
-            domain: conf.cookieDomain || undefined,
-            path: '/',
-            maxAge: undefined
-        };
-        if (conf.devMode) {
-            options.secure = isHttps;
-            options.httpOnly = false;
-            options.sameSite = 'lax';
-            if (isLocalhost) {
-                options.domain = undefined;
-            }
-        }
-        return options;
+        return buildAuthCookieOptions(this.config, apiReq.req);
     }
     setAccessCookie(apiReq, accessToken, sessionCookie) {
         const conf = this.config;
@@ -991,7 +1085,7 @@ export class ApiServer {
             }
         }
         if (!tokenData) {
-            throw new ApiError({ code: 401, message: 'Unathorized Access - ' + error });
+            throw new ApiError({ code: 401, message: 'Unauthorized Access - ' + error });
         }
         const effectiveUserId = this.extractTokenUserId(tokenData);
         apiReq.realUid = this.resolveRealUserId(tokenData, effectiveUserId);
@@ -1043,6 +1137,11 @@ export class ApiServer {
         }
         apiReq.token = secret;
         apiReq.apiKey = key;
+        // Treat API keys as authenticated identities, consistent with JWT-based flows.
+        const resolvedUid = this.normalizeAuthIdentifier(key.uid);
+        if (resolvedUid !== null) {
+            apiReq.realUid = resolvedUid;
+        }
         return {
             uid: key.uid,
             domain: '',
@@ -1102,13 +1201,19 @@ export class ApiServer {
         return rawReal;
     }
     useExpress(pathOrHandler, ...handlers) {
+        this.assertNotFinalized('useExpress');
         if (typeof pathOrHandler === 'string') {
-            this.app.use(pathOrHandler, ...handlers);
+            const apiPath = this.toApiRouterPath(pathOrHandler);
+            if (apiPath) {
+                this.apiRouter.use(apiPath, ...handlers);
+            }
+            else {
+                this.app.use(pathOrHandler, ...handlers);
+            }
         }
         else {
             this.app.use(pathOrHandler, ...handlers);
         }
-        this.ensureApiNotFoundOrdering();
         return this;
     }
     createApiRequest(req, res) {
@@ -1142,7 +1247,6 @@ export class ApiServer {
             const apiReq = this.createApiRequest(req, res);
             req.apiReq = apiReq;
             res.locals.apiReq = apiReq;
-            this.currReq = apiReq;
             try {
                 if (this.config.hydrateGetBody) {
                     hydrateGetBody(req);
@@ -1181,10 +1285,21 @@ export class ApiServer {
                 res.status(apiError.code).json(errorPayload);
                 return;
             }
+            const status = asHttpStatus(error);
+            if (status) {
+                res.status(status).json({
+                    success: false,
+                    code: status,
+                    message: status === 400 ? 'Invalid request payload' : this.internalServerErrorMessage(error),
+                    data: null,
+                    errors: {}
+                });
+                return;
+            }
             const errorPayload = {
                 success: false,
                 code: 500,
-                message: this.guessExceptionText(error),
+                message: this.internalServerErrorMessage(error),
                 data: null,
                 errors: {}
             };
@@ -1195,7 +1310,6 @@ export class ApiServer {
         return async (req, res, next) => {
             void next;
             const apiReq = this.createApiRequest(req, res);
-            this.currReq = apiReq;
             try {
                 if (this.config.hydrateGetBody) {
                     hydrateGetBody(apiReq.req);
@@ -1245,7 +1359,7 @@ export class ApiServer {
                     const errorPayload = {
                         success: false,
                         code: 500,
-                        message: this.guessExceptionText(error),
+                        message: this.internalServerErrorMessage(error),
                         data: null,
                         errors: {}
                     };
@@ -1258,13 +1372,18 @@ export class ApiServer {
         };
     }
     api(module) {
+        this.assertNotFinalized('api');
         const router = express.Router();
         module.server = this;
         const moduleType = module.moduleType;
         if (moduleType === 'auth') {
             this.authModule(module);
         }
-        module.checkConfig();
+        const configOk = module.checkConfig();
+        if (configOk === false) {
+            const name = module.constructor?.name ? String(module.constructor.name) : 'ApiModule';
+            throw new Error(`${name}.checkConfig() returned false`);
+        }
         const base = this.apiBasePath;
         const ns = module.namespace;
         const mountPath = `${base}${ns}`;
@@ -1281,6 +1400,9 @@ export class ApiServer {
                 case 'put':
                     router.put(r.path, handler);
                     break;
+                case 'patch':
+                    router.patch(r.path, handler);
+                    break;
                 case 'delete':
                     router.delete(r.path, handler);
                     break;
@@ -1289,8 +1411,7 @@ export class ApiServer {
                 console.log(`Adding ${mountPath}${r.path} (${r.method.toUpperCase()})`);
             }
         });
-        this.app.use(mountPath, router);
-        this.ensureApiNotFoundOrdering();
+        this.apiRouter.use(ns, router);
         return this;
     }
     dumpRequest(apiReq) {

package/dist/esm/auth-api/auth-module.d.ts

@@ -10,10 +10,16 @@ interface CanImpersonateContext<UserEntity> {
     targetUser: UserEntity;
     effectiveUserId: AuthIdentifier;
 }
+type AuthRateLimitEndpoint = 'login' | 'passkey-challenge' | 'oauth-token';
 interface AuthModuleOptions<UserEntity> {
     namespace?: string;
     defaultDomain?: string;
     canImpersonate?: (context: CanImpersonateContext<UserEntity>) => Promise<boolean> | boolean;
+    rateLimit?: (context: {
+        apiReq: ApiRequest;
+        endpoint: AuthRateLimitEndpoint;
+    }) => Promise<void> | void;
+    allowInsecurePkcePlain?: boolean;
 }
 type TokenMetadata = Partial<Token> & {
     sessionCookie?: boolean;
@@ -42,9 +48,12 @@ type AuthCapableServer<PublicUser> = ApiServer & {
 };
 export default class AuthModule<UserEntity, PublicUser> extends BaseAuthModule<UserEntity> implements AuthProviderModule<UserEntity> {
     static defaultNamespace: string;
-    server: AuthCapableServer<PublicUser>;
+    get server(): AuthCapableServer<PublicUser>;
+    set server(value: AuthCapableServer<PublicUser>);
     private readonly defaultDomain?;
     private readonly canImpersonateHook?;
+    private readonly rateLimitHook?;
+    private readonly allowInsecurePkcePlain;
     constructor(options?: AuthModuleOptions<UserEntity>);
     protected get storage(): AuthAdapter<UserEntity, PublicUser>;
     protected canImpersonate(apiReq: ApiRequest, realUser: UserEntity, targetUser: UserEntity): Promise<boolean>;
@@ -100,6 +109,8 @@ export default class AuthModule<UserEntity, PublicUser> extends BaseAuthModule<U
     private hasOAuthStore;
     private storageImplements;
     private storageImplementsAll;
+    private applyRateLimit;
+    private resolvePkceChallengeMethod;
     defineRoutes(): ApiRoute[];
 }
 export {};