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

package/README.txt

@@ -25,13 +25,13 @@ pnpm add @technomoron/api-server-base
 
 All runtime dependencies and `@types/*` packages are bundled with the distribution. The library exports ES modules by default. Consumers that rely on CommonJS can import via the require entry exposed in package.json.
 
-Quick Start
------------
-import { ApiServer, ApiModule, ApiError, BaseAuthStorage } from '@technomoron/api-server-base';
+	Quick Start
+	-----------
+	import { ApiServer, ApiModule, ApiError, BaseAuthAdapter } from '@technomoron/api-server-base';
 
 type DemoUser = { id: string; email: string; password: string };
 
-class DemoStorage extends BaseAuthStorage<DemoUser, Omit<DemoUser, 'password'>> {
+	class DemoStorage extends BaseAuthAdapter<DemoUser, Omit<DemoUser, 'password'>> {
 	private readonly users = new Map<string, DemoUser>([
 		['1', { id: '1', email: 'demo@example.com', password: 'secret' }]
 	]);
@@ -79,14 +79,15 @@ class UserModule extends ApiModule<AppServer> {
 
 const yourStorageAdapter = new DemoStorage();
 
-const server = new AppServer({
-	apiPort: 3101,
-	apiHost: '127.0.0.1',
-	accessSecret: 'replace-me'
-})
-	.authStorage(yourStorageAdapter)
-	.api(new UserModule())
-	.start();
+	const server = new AppServer({
+		apiPort: 3101,
+		apiHost: '127.0.0.1',
+		accessSecret: 'replace-me'
+	})
+		.authStorage(yourStorageAdapter)
+		.api(new UserModule())
+		.finalize()
+		.start();
 
 Need a dedicated auth module as well? Chain `.authModule(...)` in the same spot.
 
@@ -105,7 +106,11 @@ uploadMax (number, default 30 * 1024 * 1024) Maximum upload size in bytes.
 staticDirs (record, default empty object) Map of mount path => disk path for serving static files as-is (ex: { '/assets': './public' }).
 accessSecret (string, default empty string) Required for JWT signing and verification.
 refreshSecret (string, default empty string) Used for refresh tokens if you implement them.
-cookieDomain (string, default '.somewhere-over-the-rainbow.com') Domain applied to auth cookies.
+cookieDomain (string, default '') Domain applied to auth cookies.
+cookiePath (string, default '/') Path applied to auth cookies.
+cookieSameSite ('lax' | 'strict' | 'none', default 'lax') SameSite attribute applied to auth cookies.
+cookieSecure (boolean | 'auto', default 'auto') Secure attribute applied to auth cookies; 'auto' enables Secure only when the request is HTTPS (or forwarded as HTTPS).
+cookieHttpOnly (boolean, default true) HttpOnly attribute applied to auth cookies.
 accessCookie (string, default 'dat') Access token cookie name.
 refreshCookie (string, default 'drt') Refresh token cookie name.
 accessExpiry (number, default 60 * 15) Access token lifetime in seconds.
@@ -120,14 +125,14 @@ refreshMaybe (boolean, default false) When true, `auth: maybe` routes will try t
 
 Tip: If you add new configuration fields in downstream projects, extend ApiServerConf and update fillConfig so defaults stay aligned.
 
-Request Lifecycle
------------------
-1. Express middlewares (express.json, cookie-parser, optional multer) run before your handler.
-2. ApiServer wraps the route inside handle_request, setting currReq and logging when debug is enabled.
-3. authenticate enforces the ApiRoute auth type: `none`, `maybe`, `yes`, `strict`, or `apikey`. Bearer JWTs and the access cookie (`accessCookie`, default `dat`) are accepted for `yes`/`strict`, while API key tokens prefixed with `apikey-` always delegate to `getApiKey`. When `refreshSecret` is configured and your storage supports refresh lookups (`getToken({ refreshToken })` + `updateToken(...)`), `yes`/`strict` routes will automatically mint a new access token when it is missing or expired (and also recover from "Authorization token is no longer valid" by refreshing). `maybe` routes only do the same when `refreshMaybe: true`. The optional `strict` type (or server-wide `validateTokens` flag) requires the signed JWT to exist in storage; when it does, the persisted row is attached to `apiReq.authToken`. The dedicated `apikey` type simply means “an API key is required”; otherwise API keys are still accepted by `yes`/`strict` routes alongside JWTs, and `apiReq.apiKey` is populated when present.
-4. authorize runs with the requested auth class (any or admin in the base implementation). Override to connect to your role system.
-5. The handler executes and returns its tuple. Responses are normalized to { code, message, data } JSON.
-6. Errors bubble into the wrapper. ApiError instances respect the provided status codes; other exceptions result in a 500 with text derived from guessExceptionText.
+	Request Lifecycle
+	-----------------
+	1. Express middlewares (express.json, cookie-parser, optional multer) run before your handler.
+	2. ApiServer wraps the route inside handle_request, creating an ApiRequest and logging when debug is enabled.
+	3. authenticate enforces the ApiRoute auth type: `none`, `maybe`, `yes`, `strict`, or `apikey`. Bearer JWTs and the access cookie (`accessCookie`, default `dat`) are accepted for `yes`/`strict`, while API key tokens prefixed with `apikey-` always delegate to `getApiKey`. When `refreshSecret` is configured and your storage supports refresh lookups (`getToken({ refreshToken })` + `updateToken(...)`), `yes`/`strict` routes will automatically mint a new access token when it is missing or expired (and also recover from "Authorization token is no longer valid" by refreshing). `maybe` routes only do the same when `refreshMaybe: true`. The optional `strict` type (or server-wide `validateTokens` flag) requires the signed JWT to exist in storage; when it does, the persisted row is attached to `apiReq.authToken`. The dedicated `apikey` type simply means “an API key is required”; otherwise API keys are still accepted by `yes`/`strict` routes alongside JWTs, and `apiReq.apiKey` is populated when present.
+	4. authorize runs with the requested auth class (any or admin in the base implementation). Override to connect to your role system.
+	5. The handler executes and returns its tuple. Responses are normalized to { code, message, data } JSON.
+	6. Errors bubble into the wrapper. ApiError instances respect the provided status codes; other exceptions result in a 500 with text derived from guessExceptionText.
 
 Client IP Helpers
 -----------------
@@ -135,16 +140,20 @@ Call `apiReq.getClientInfo()` when you need the entire client fingerprint captur
 
 Call `apiReq.getClientIp()` to obtain the most likely client address, skipping loopback entries collected from proxy headers. Use `apiReq.getClientIpChain()` when you need the de-duplicated sequence gathered from the standard Forwarded/X-Forwarded-For/X-Real-IP headers as well as Express' `req.ip`/`req.ips` and the underlying socket. Both helpers reuse the cached payload returned by `apiReq.getClientInfo()`.
 
-Extending the Base Classes
---------------------------
-Implement the AuthStorage contract (getUser, verifyPassword, storeToken, updateToken, etc.) to integrate with your persistence layer, then supply it via authStorage().
-Use your storage adapter's filterUser helper to trim sensitive data before returning responses.
-Provide your own authorize method to enforce role based access control using the ApiAuthClass enum.
-Create feature modules by extending ApiModule. Use the optional checkConfig hook to validate prerequisites before routes mount.
+	Extending the Base Classes
+	--------------------------
+	Implement the AuthStorage contract (getUser, verifyPassword, storeToken, updateToken, etc.) to integrate with your persistence layer, then supply it via authStorage().
+	Use your storage adapter's filterUser helper to trim sensitive data before returning responses.
+	Provide your own authorize method to enforce role based access control using the ApiAuthClass enum.
+	Create feature modules by extending ApiModule. Use the optional checkConfig hook to validate prerequisites before routes mount.
+
+	OAuth Client Secrets
+	--------------------
+	If your OAuth client records use a client secret, make `getClient(clientId)` return a client with a truthy `clientSecret` (do not return the stored hash/secret itself) and implement `verifyClientSecret(client, clientSecret)` on your storage adapter. If `clientSecret` is truthy but `verifyClientSecret` is not overridden, the `/auth/v1/oauth2/token` endpoint returns 501.
 
-Sequelize Table Prefixes
-------------------------
-Sequelize-backed stores accept `tablePrefix` to prepend to the built-in table names (`users`, `jwttokens`, `passkey_credentials`, `passkey_challenges`, `oauth_clients`, `oauth_codes`).
+	Sequelize Table Prefixes
+	------------------------
+	Sequelize-backed stores accept `tablePrefix` to prepend to the built-in table names (`users`, `jwttokens`, `passkey_credentials`, `passkey_challenges`, `oauth_clients`, `oauth_codes`).
 
 SqlAuthStore supports both a global prefix (`tablePrefix`) and per-module overrides (`tablePrefixes.user|token|passkey|oauth`). When present, `tokenStoreOptions.tablePrefix` and `oauthStoreOptions.tablePrefix` take precedence.
 
@@ -158,16 +167,16 @@ Example:
 
 If you need a different base name (for example `myapp_tokens` instead of `myapp_jwttokens`), pass a custom model or model factory to the store and set the `tableName` yourself.
 
-Custom Express Endpoints
-------------------------
-ApiModule routes run inside the tuple wrapper (always responding with a standardized JSON envelope). For endpoints that need raw Express control (streaming, webhooks, tus uploads, etc.), mount your own handlers directly.
+	Custom Express Endpoints
+	------------------------
+	ApiModule routes run inside the tuple wrapper (always responding with a standardized JSON envelope). For endpoints that need raw Express control (streaming, webhooks, tus uploads, etc.), mount your own handlers directly.
 
 - `server.useExpress(...)` mounts middleware/routes and keeps the built-in `/api` 404 handler ordered last, so mounts under `apiBasePath` are not intercepted.
 - Protect endpoints by inserting `server.expressAuth({ type, req })` as middleware. It authenticates using the same JWT/cookie/API-key logic as ApiModule routes and then runs `authorize`.
 - On success, `expressAuth` attaches the computed ApiRequest to both `req.apiReq` and `res.locals.apiReq`.
 - If you want the same JSON error envelope for custom endpoints, mount `server.expressErrorHandler()` after your custom routes.
 
-Example:
+	Example:
 
 	server
 		.useExpress(
@@ -178,7 +187,11 @@ Example:
 				res.status(200).json({ uid: apiReq.tokenData?.uid ?? null });
 			}
 		)
-		.useExpress(server.expressErrorHandler());
+			.useExpress(server.expressErrorHandler());
+
+	Finalize And Start
+	------------------
+	Call `server.finalize()` after you have mounted all ApiModules and custom Express endpoints. After finalize (or after `start()`), calling `api()` / `useExpress()` will throw.
 
 
 Tooling and Scripts

package/dist/cjs/api-server-base.cjs

@@ -351,7 +351,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,
@@ -369,8 +373,19 @@ function fillConfig(config) {
     };
 }
 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) {
+        void _value;
+    }
     constructor(config = {}) {
-        this.currReq = null;
+        this.finalized = false;
         this.serverAuthAdapter = null;
         this.apiNotFoundHandler = null;
         this.tokenStoreAdapter = null;
@@ -395,17 +410,67 @@ class ApiServer {
             this.storageAdapter = this.getServerAuthAdapter();
         }
         this.app = (0, express_1.default)();
+        // 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_1.default.Router();
         if (config.uploadPath) {
-            const upload = (0, multer_1.default)({ dest: config.uploadPath });
+            const upload = (0, multer_1.default)({ 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();
     }
+    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.finalized = true;
+        return this;
+    }
     authStorage(storage) {
         this.storageAdapter = storage;
         return this;
@@ -631,7 +696,7 @@ class ApiServer {
         }
         return false;
     }
-    guessExceptionText(error, defMsg = 'Unkown Error') {
+    guessExceptionText(error, defMsg = 'Unknown Error') {
         return guess_exception_text(error, defMsg);
     }
     async authorize(apiReq, requiredClass) {
@@ -657,6 +722,26 @@ class ApiServer {
             credentials: true
         };
         this.app.use((0, cors_1.default)(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;
@@ -770,28 +855,16 @@ class ApiServer {
         };
         this.app.use(this.apiBasePath, this.apiNotFoundHandler);
     }
-    ensureApiNotFoundOrdering() {
-        this.installApiNotFoundHandler();
-        if (!this.apiNotFoundHandler) {
-            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);
-    }
     describeMissingEndpoint(req) {
         const method = typeof req.method === 'string' ? req.method.toUpperCase() : 'GET';
         const target = req.originalUrl || req.url || this.apiBasePath;
         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,
@@ -801,19 +874,22 @@ 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;
+            throw err;
         });
         return this;
     }
@@ -835,23 +911,33 @@ class ApiServer {
         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 forwardedProto = (typeof forwarded === 'string' ? forwarded : Array.isArray(forwarded) ? (forwarded[0] ?? '') : '')
+            .split(',')[0]
+            .trim()
+            .toLowerCase();
+        const isHttps = forwardedProto === 'https' || apiReq.req.protocol === 'https';
         const isLocalhost = origin.includes('localhost');
+        const secure = conf.cookieSecure === true ? true : conf.cookieSecure === false ? false : /* auto */ Boolean(isHttps);
+        let sameSite = conf.cookieSameSite ?? 'lax';
+        if (sameSite !== 'lax' && sameSite !== 'strict' && sameSite !== 'none') {
+            sameSite = 'lax';
+        }
+        let resolvedSecure = secure;
+        if (sameSite === 'none' && resolvedSecure !== true) {
+            // Modern browsers reject SameSite=None cookies unless Secure is set.
+            resolvedSecure = true;
+        }
         const options = {
-            httpOnly: true,
-            secure: true,
-            sameSite: 'strict',
+            httpOnly: conf.cookieHttpOnly ?? true,
+            secure: resolvedSecure,
+            sameSite,
             domain: conf.cookieDomain || undefined,
-            path: '/',
+            path: conf.cookiePath || '/',
             maxAge: undefined
         };
-        if (conf.devMode) {
-            options.secure = isHttps;
-            options.httpOnly = false;
-            options.sameSite = 'lax';
-            if (isLocalhost) {
-                options.domain = undefined;
-            }
+        if (conf.devMode && isLocalhost) {
+            // Domain cookies do not work on localhost; avoid breaking local development when cookieDomain is set.
+            options.domain = undefined;
         }
         return options;
     }
@@ -999,7 +1085,7 @@ 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);
@@ -1051,6 +1137,11 @@ 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: '',
@@ -1110,13 +1201,19 @@ 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) {
@@ -1150,7 +1247,6 @@ 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);
@@ -1203,7 +1299,6 @@ 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);
@@ -1266,13 +1361,18 @@ class ApiServer {
         };
     }
     api(module) {
+        this.assertNotFinalized('api');
         const router = express_1.default.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}`;
@@ -1297,8 +1397,7 @@ 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/cjs/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;
@@ -118,10 +132,11 @@ export interface ApiServerConf {
 }
 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;
@@ -132,7 +147,17 @@ export declare class ApiServer {
     private oauthStoreAdapter;
     private canImpersonateAdapter;
     private readonly jwtHelper;
+    /**
+     * @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,7 +225,6 @@ export declare class ApiServer {
     private installSwaggerHandler;
     private normalizeApiBasePath;
     private installApiNotFoundHandler;
-    private ensureApiNotFoundOrdering;
     private describeMissingEndpoint;
     start(): this;
     private verifyJWT;

package/dist/cjs/auth-api/auth-module.js

@@ -240,23 +240,31 @@ class AuthModule extends module_js_1.BaseAuthModule {
         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 forwardedProto = (typeof forwarded === 'string' ? forwarded : Array.isArray(forwarded) ? (forwarded[0] ?? '') : '')
+            .split(',')[0]
+            .trim()
+            .toLowerCase();
+        const isHttps = forwardedProto === 'https' || apiReq.req.protocol === 'https';
         const isLocalhost = origin.includes('localhost');
+        const secure = conf.cookieSecure === true ? true : conf.cookieSecure === false ? false : /* auto */ Boolean(isHttps);
+        let sameSite = conf.cookieSameSite ?? 'lax';
+        if (sameSite !== 'lax' && sameSite !== 'strict' && sameSite !== 'none') {
+            sameSite = 'lax';
+        }
+        let resolvedSecure = secure;
+        if (sameSite === 'none' && resolvedSecure !== true) {
+            resolvedSecure = true;
+        }
         const options = {
-            httpOnly: true,
-            secure: true,
-            sameSite: 'strict',
+            httpOnly: conf.cookieHttpOnly ?? true,
+            secure: resolvedSecure,
+            sameSite,
             domain: conf.cookieDomain || undefined,
-            path: '/',
+            path: conf.cookiePath || '/',
             maxAge: undefined
         };
-        if (conf.devMode) {
-            options.secure = isHttps;
-            options.httpOnly = false;
-            options.sameSite = 'lax';
-            if (isLocalhost) {
-                options.domain = undefined;
-            }
+        if (conf.devMode && isLocalhost) {
+            options.domain = undefined;
         }
         return options;
     }
@@ -552,10 +560,39 @@ class AuthModule extends module_js_1.BaseAuthModule {
                 apiReq.req.cookies[conf.accessCookie].trim().length > 0);
         const shouldRefresh = Boolean(body.refresh) || !hasAccessToken;
         if (shouldRefresh) {
-            const access = this.server.jwtSign(this.buildTokenPayload(user, stored), conf.accessSecret, conf.accessExpiry);
+            const updateToken = this.storage.updateToken;
+            if (typeof updateToken !== 'function' || !this.storageImplements('updateToken')) {
+                throw new api_server_base_js_1.ApiError({ code: 501, message: 'Token update storage is not configured' });
+            }
+            // Sign a new access token without embedding stored token secrets into the JWT payload.
+            const metadata = {
+                ruid: stored.ruid,
+                domain: stored.domain,
+                fingerprint: stored.fingerprint,
+                label: stored.label,
+                clientId: stored.clientId,
+                scope: stored.scope,
+                browser: stored.browser,
+                device: stored.device,
+                ip: stored.ip,
+                os: stored.os,
+                loginType: stored.loginType,
+                refreshTtlSeconds: this.normalizeRefreshTtlSeconds(stored.refreshTtlSeconds),
+                sessionCookie: stored.sessionCookie
+            };
+            const enrichedMetadata = this.enrichTokenMetadata(apiReq, metadata);
+            const access = this.server.jwtSign(this.buildTokenPayload(user, enrichedMetadata), conf.accessSecret, conf.accessExpiry);
             if (!access.success || !access.token) {
                 throw new api_server_base_js_1.ApiError({ code: 500, message: access.error ?? 'Unable to sign access token' });
             }
+            const updated = await updateToken.call(this.storage, {
+                refreshToken,
+                accessToken: access.token,
+                lastSeenAt: new Date()
+            });
+            if (!updated) {
+                throw new api_server_base_js_1.ApiError({ code: 500, message: 'Unable to persist refreshed access token' });
+            }
             const cookiePrefs = this.mergeSessionPreferences({
                 sessionCookie: stored.sessionCookie,
                 refreshTtlSeconds: this.normalizeRefreshTtlSeconds(stored.refreshTtlSeconds)
@@ -1001,14 +1038,11 @@ class AuthModule extends module_js_1.BaseAuthModule {
             if (!secretProvided) {
                 throw new api_server_base_js_1.ApiError({ code: 400, message: 'Client authentication is required' });
             }
-            let valid = false;
-            if (this.storage.verifyClientSecret) {
-                const verifySecret = this.storage.verifyClientSecret.bind(this.storage);
-                valid = await verifySecret(client, clientSecret);
-            }
-            else {
-                valid = client.clientSecret === clientSecret;
+            const verifySecret = this.storage.verifyClientSecret;
+            if (typeof verifySecret !== 'function' || !this.storageImplements('verifyClientSecret')) {
+                throw new api_server_base_js_1.ApiError({ code: 501, message: 'OAuth client secret verification is not configured' });
             }
+            const valid = await verifySecret.call(this.storage, client, clientSecret);
             if (!valid) {
                 throw new api_server_base_js_1.ApiError({ code: 401, message: 'Invalid client credentials' });
             }
@@ -1156,7 +1190,7 @@ class AuthModule extends module_js_1.BaseAuthModule {
                     auth: { type: 'strict', req: 'any' }
                 }, {
                     method: 'delete',
-                    path: '/v1/passkeys/:credentialId?',
+                    path: '/v1/passkeys/:credentialId',
                     handler: (req) => this.deletePasskey(req),
                     auth: { type: 'strict', req: 'any' }
                 });

package/dist/cjs/auth-api/mem-auth-store.js

@@ -25,7 +25,8 @@ function normalizePasskeyConfig(config = {}) {
         timeoutMs: typeof config.timeoutMs === 'number' && config.timeoutMs > 0
             ? config.timeoutMs
             : DEFAULT_PASSKEY_CONFIG.timeoutMs,
-        userVerification: config.userVerification ?? DEFAULT_PASSKEY_CONFIG.userVerification
+        userVerification: config.userVerification ?? DEFAULT_PASSKEY_CONFIG.userVerification,
+        debug: Boolean(config.debug)
     };
 }
 class MemAuthStore {