@technomoron/api-server-base 2.0.0-beta.2 → 2.0.0-beta.21

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

@@ -5,12 +5,17 @@
  * LICENSE file in the root directory of this source tree.
  */
 import { randomUUID } from 'node:crypto';
+import { access, readFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import path from 'node:path';
 import cookieParser from 'cookie-parser';
 import cors from 'cors';
 import express from 'express';
 import multer from 'multer';
 import { nullAuthModule } from './auth-api/module.js';
-import { nullAuthStorage } from './auth-api/storage.js';
+import { nullAuthAdapter } from './auth-api/storage.js';
+import { toOptionalStringId } from './auth-api/user-id.js';
+import { buildAuthCookieOptions } from './auth-cookie-options.js';
 import { TokenStore } from './token/base.js';
 class JwtHelperStore extends TokenStore {
     async save() {
@@ -39,11 +44,14 @@ function guess_exception_text(error, defMsg = 'Unknown Error') {
         msg.push(error);
     }
     else if (error && typeof error === 'object') {
-        if (typeof error.message === 'string' && error.message.trim() !== '') {
-            msg.push(error.message);
+        const errorDetails = error;
+        if (typeof errorDetails.message === 'string' && errorDetails.message.trim() !== '') {
+            msg.push(errorDetails.message);
         }
-        if (error.parent && typeof error.parent.message === 'string' && error.parent.message.trim() !== '') {
-            msg.push(error.parent.message);
+        if (errorDetails.parent &&
+            typeof errorDetails.parent.message === 'string' &&
+            errorDetails.parent.message.trim() !== '') {
+            msg.push(errorDetails.parent.message);
         }
     }
     return msg.length > 0 ? msg.join(' / ') : defMsg;
@@ -64,6 +72,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) {
@@ -259,7 +268,9 @@ function collectClientIpChain(req) {
     }
     const realIp = req.headers['x-real-ip'];
     if (Array.isArray(realIp)) {
-        realIp.forEach((value) => pushNormalized(normalizeIpAddress(value)));
+        for (const value of realIp) {
+            pushNormalized(normalizeIpAddress(value));
+        }
     }
     else if (typeof realIp === 'string') {
         pushNormalized(normalizeIpAddress(realIp));
@@ -323,18 +334,36 @@ 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,
         apiHost: config.apiHost ?? 'localhost',
         uploadPath: config.uploadPath ?? '',
         uploadMax: config.uploadMax ?? 30 * 1024 * 1024,
+        staticDirs: config.staticDirs,
         origins: config.origins ?? [],
         debug: config.debug ?? false,
         apiBasePath: config.apiBasePath ?? '/api',
+        swaggerEnabled: config.swaggerEnabled ?? false,
+        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,
@@ -344,25 +373,45 @@ function fillConfig(config) {
         devMode: config.devMode ?? false,
         hydrateGetBody: config.hydrateGetBody ?? true,
         validateTokens: config.validateTokens ?? false,
+        refreshMaybe: config.refreshMaybe ?? false,
         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();
-        this.storageAdapter = nullAuthStorage;
+        this.storageAdapter = nullAuthAdapter;
         this.moduleAdapter = nullAuthModule;
         this.jwtHelper = new JwtHelperStore();
         this.tokenStoreAdapter = this.config.tokenStore ?? null;
@@ -373,17 +422,75 @@ export class ApiServer {
             this.passkeyServiceAdapter = passkeyService ?? null;
             this.oauthStoreAdapter = oauthStore ?? null;
             this.canImpersonateAdapter = canImpersonate ?? null;
-            this.storageAdapter = this;
+            this.storageAdapter = this.getServerAuthAdapter();
+        }
+        if ((this.config.authApi || this.config.authStores) &&
+            (!this.config.accessSecret || !this.config.refreshSecret)) {
+            console.warn('[api-server-base] Auth is enabled but accessSecret and/or refreshSecret are empty. JWT signing will fail at runtime.');
         }
         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;
@@ -413,9 +520,9 @@ export class ApiServer {
     }
     setTokenStore(store) {
         this.tokenStoreAdapter = store;
-        // If using direct stores, expose self as the auth storage.
+        // If using direct stores, expose the server-backed auth adapter.
         if (this.userStoreAdapter) {
-            this.storageAdapter = this;
+            this.storageAdapter = this.getServerAuthAdapter();
         }
         return this;
     }
@@ -440,13 +547,46 @@ export class ApiServer {
         }
         return this.passkeyServiceAdapter;
     }
+    async listUserCredentials(userId) {
+        return this.ensurePasskeyService().listUserCredentials(userId);
+    }
+    async deletePasskeyCredential(credentialId) {
+        return this.ensurePasskeyService().deleteCredential(credentialId);
+    }
     ensureOAuthStore() {
         if (!this.oauthStoreAdapter) {
             throw new Error('OAuth store is not configured');
         }
         return this.oauthStoreAdapter;
     }
-    // AuthStorage-compatible helpers (used by AuthModule)
+    getServerAuthAdapter() {
+        if (this.serverAuthAdapter) {
+            return this.serverAuthAdapter;
+        }
+        const server = this;
+        this.serverAuthAdapter = {
+            getUser: (identifier) => server.getUser(identifier),
+            getUserPasswordHash: (user) => server.getUserPasswordHash(user),
+            getUserId: (user) => server.getUserId(user),
+            filterUser: (user) => server.filterUser(user),
+            verifyPassword: (password, hash) => server.verifyPassword(password, hash),
+            storeToken: (data) => server.storeToken(data),
+            getToken: (query, opts) => server.getToken(query, opts),
+            deleteToken: (query) => server.deleteToken(query),
+            updateToken: (updates) => server.updateToken(updates),
+            createPasskeyChallenge: (params) => server.createPasskeyChallenge(params),
+            verifyPasskeyResponse: (params) => server.verifyPasskeyResponse(params),
+            listUserCredentials: (userId) => server.listUserCredentials(userId),
+            deletePasskeyCredential: (credentialId) => server.deletePasskeyCredential(credentialId),
+            getClient: (clientId) => server.getClient(clientId),
+            verifyClientSecret: (client, clientSecret) => server.verifyClientSecret(client, clientSecret),
+            createAuthCode: (request) => server.createAuthCode(request),
+            consumeAuthCode: (code, clientId) => server.consumeAuthCode(code, clientId),
+            canImpersonate: (params) => server.canImpersonate(params)
+        };
+        return this.serverAuthAdapter;
+    }
+    // AuthAdapter-compatible helpers (used by AuthModule)
     async getUser(identifier) {
         return this.userStoreAdapter ? this.userStoreAdapter.findUser(identifier) : null;
     }
@@ -466,36 +606,39 @@ export class ApiServer {
         if (this.tokenStoreAdapter) {
             return this.tokenStoreAdapter.save(data);
         }
-        if (typeof this.storageAdapter.storeToken === 'function') {
-            return this.storageAdapter.storeToken(data);
+        const storage = this.storageAdapter;
+        if (typeof storage.storeToken === 'function') {
+            return storage.storeToken(data);
         }
         throw new Error('Token store is not configured');
     }
     async getToken(query, opts) {
         const normalized = {
             ...query,
-            userId: query.userId !== undefined && query.userId !== null ? String(query.userId) : undefined,
-            ruid: query.ruid !== undefined && query.ruid !== null ? String(query.ruid) : undefined
+            userId: toOptionalStringId(query.userId),
+            ruid: toOptionalStringId(query.ruid)
         };
         if (this.tokenStoreAdapter) {
             return this.tokenStoreAdapter.get(normalized, opts);
         }
-        if (typeof this.storageAdapter.getToken === 'function') {
-            return this.storageAdapter.getToken(normalized, opts);
+        const storage = this.storageAdapter;
+        if (typeof storage.getToken === 'function') {
+            return storage.getToken(normalized, opts);
         }
         return null;
     }
     async deleteToken(query) {
         const normalized = {
             ...query,
-            userId: query.userId !== undefined && query.userId !== null ? String(query.userId) : undefined,
-            ruid: query.ruid !== undefined && query.ruid !== null ? String(query.ruid) : undefined
+            userId: toOptionalStringId(query.userId),
+            ruid: toOptionalStringId(query.ruid)
         };
         if (this.tokenStoreAdapter) {
             return this.tokenStoreAdapter.delete(normalized);
         }
-        if (typeof this.storageAdapter.deleteToken === 'function') {
-            return this.storageAdapter.deleteToken(normalized);
+        const storage = this.storageAdapter;
+        if (typeof storage.deleteToken === 'function') {
+            return storage.deleteToken(normalized);
         }
         return 0;
     }
@@ -568,12 +711,13 @@ export class ApiServer {
         if (this.tokenStoreAdapter) {
             return this.tokenStoreAdapter.update(updates);
         }
-        if (typeof this.storageAdapter.updateToken === 'function') {
-            return this.storageAdapter.updateToken(updates);
+        const storage = this.storageAdapter;
+        if (typeof storage.updateToken === 'function') {
+            return storage.updateToken(updates);
         }
         return false;
     }
-    guessExceptionText(error, defMsg = 'Unkown Error') {
+    guessExceptionText(error, defMsg = 'Unknown Error') {
         return guess_exception_text(error, defMsg);
     }
     async authorize(apiReq, requiredClass) {
@@ -599,11 +743,47 @@ 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;
+        if (!staticDirs || !isPlainObject(staticDirs)) {
+            return;
+        }
+        for (const [mountRaw, dirRaw] of Object.entries(staticDirs)) {
+            const mount = typeof mountRaw === 'string' ? mountRaw.trim() : '';
+            const dir = typeof dirRaw === 'string' ? dirRaw.trim() : '';
+            if (!mount || !dir) {
+                continue;
+            }
+            const resolvedMount = mount.startsWith('/') ? mount : `/${mount}`;
+            this.app.use(resolvedMount, express.static(dir));
+        }
     }
     installPingHandler() {
         const path = `${this.apiBasePath}/v1/ping`;
         this.app.get(path, (_req, res) => {
             const payload = {
+                success: true,
                 status: 'ok',
                 apiVersion: this.config.apiVersion ?? '',
                 minClientVersion: this.config.minClientVersion ?? '',
@@ -611,7 +791,66 @@ export class ApiServer {
                 startedAt: this.startedAt,
                 timestamp: new Date().toISOString()
             };
-            res.status(200).json({ code: 200, message: 'Success', data: payload });
+            res.status(200).json({ success: true, code: 200, message: 'Success', data: payload, errors: {} });
+        });
+    }
+    async loadSwaggerSpec() {
+        const candidates = [path.resolve(process.cwd(), 'docs/swagger/openapi.json')];
+        if (typeof __dirname === 'string') {
+            candidates.push(path.resolve(__dirname, '../../docs/swagger/openapi.json'));
+        }
+        try {
+            const require = createRequire(path.join(process.cwd(), 'package.json'));
+            const entry = require.resolve('@technomoron/api-server-base');
+            const packageRoot = path.resolve(path.dirname(entry), '..', '..');
+            candidates.push(path.join(packageRoot, 'docs/swagger/openapi.json'));
+        }
+        catch {
+            // Ignore resolution failures; fall back to any existing candidate.
+        }
+        for (const candidate of candidates) {
+            try {
+                await access(candidate);
+            }
+            catch {
+                continue;
+            }
+            try {
+                const raw = await readFile(candidate, 'utf8');
+                return JSON.parse(raw);
+            }
+            catch {
+                return null;
+            }
+        }
+        return null;
+    }
+    installSwaggerHandler() {
+        const rawPath = typeof this.config.swaggerPath === 'string' ? this.config.swaggerPath.trim() : '';
+        const enabled = Boolean(this.config.swaggerEnabled) || rawPath.length > 0;
+        if (!enabled) {
+            return;
+        }
+        const base = this.apiBasePath === '/' ? '' : this.apiBasePath;
+        const resolved = rawPath.length > 0 ? rawPath : `${base}/swagger`;
+        const path = resolved.startsWith('/') ? resolved : `/${resolved}`;
+        let specPromise;
+        this.app.get(path, async (_req, res) => {
+            if (!specPromise) {
+                specPromise = this.loadSwaggerSpec();
+            }
+            const spec = await specPromise;
+            if (!spec) {
+                res.status(500).json({
+                    success: false,
+                    code: 500,
+                    message: 'Swagger spec is unavailable',
+                    data: null,
+                    errors: {}
+                });
+                return;
+            }
+            res.status(200).json(spec);
         });
     }
     normalizeApiBasePath(path) {
@@ -634,6 +873,7 @@ export class ApiServer {
         }
         this.apiNotFoundHandler = (req, res) => {
             const payload = {
+                success: false,
                 code: 404,
                 message: this.describeMissingEndpoint(req),
                 data: null,
@@ -643,21 +883,12 @@ export 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) {
+    installApiErrorHandler() {
+        if (this.apiErrorHandlerInstalled) {
             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';
@@ -665,6 +896,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,
@@ -674,34 +909,123 @@ 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}`;
+            }
+            const err = new Error(message);
+            err.cause = error;
+            if (typeof this.config.onStartError === 'function') {
+                this.config.onStartError(err);
+                return;
             }
-            process.exit(1);
+            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' };
+            return { tokenData: undefined, error: 'JWT authentication disabled; no jwtSecret set', expired: false };
         }
         const result = this.jwtVerify(token, this.config.accessSecret);
         if (!result.success) {
-            return { tokenData: undefined, error: result.error };
+            return { tokenData: undefined, error: result.error, expired: result.expired };
         }
         if (!result.data.uid) {
-            return { tokenData: undefined, error: 'Missing/bad userid in token' };
+            return { tokenData: undefined, error: 'Missing/bad userid in token', expired: false };
+        }
+        return { tokenData: result.data, error: undefined, expired: false };
+    }
+    jwtCookieOptions(apiReq) {
+        return buildAuthCookieOptions(this.config, apiReq.req);
+    }
+    setAccessCookie(apiReq, accessToken, sessionCookie) {
+        const conf = this.config;
+        const options = this.jwtCookieOptions(apiReq);
+        const accessMaxAge = Math.max(1, conf.accessExpiry) * 1000;
+        const accessOptions = sessionCookie ? options : { ...options, maxAge: accessMaxAge };
+        apiReq.res.cookie(conf.accessCookie, accessToken, accessOptions);
+    }
+    async tryRefreshAccessToken(apiReq) {
+        const conf = this.config;
+        if (!conf.refreshSecret || !conf.accessSecret) {
+            return null;
+        }
+        const rawRefresh = apiReq.req.cookies?.[conf.refreshCookie];
+        if (typeof rawRefresh !== 'string') {
+            return null;
+        }
+        const refreshToken = rawRefresh.trim();
+        if (!refreshToken) {
+            return null;
+        }
+        const verify = this.jwtVerify(refreshToken, conf.refreshSecret);
+        if (!verify.success || !verify.data) {
+            return null;
+        }
+        let stored = null;
+        try {
+            stored = await this.storageAdapter.getToken({ refreshToken });
         }
-        return { tokenData: result.data, error: undefined };
+        catch {
+            return null;
+        }
+        if (!stored) {
+            return null;
+        }
+        const storedUid = String(stored.userId);
+        const verifyUid = verify.data.uid === undefined || verify.data.uid === null ? null : String(verify.data.uid);
+        if (verifyUid && verifyUid !== storedUid) {
+            return null;
+        }
+        const claims = verify.data;
+        const { exp: _exp, iat: _iat, nbf: _nbf, ...payload } = claims;
+        void _exp;
+        void _iat;
+        void _nbf;
+        // Ensure we never embed token secrets into refreshed access tokens.
+        delete payload.accessToken;
+        delete payload.refreshToken;
+        delete payload.userId;
+        delete payload.expires;
+        delete payload.issuedAt;
+        delete payload.lastSeenAt;
+        delete payload.status;
+        const access = this.jwtSign(payload, conf.accessSecret, conf.accessExpiry);
+        if (!access.success || !access.token) {
+            return null;
+        }
+        const updated = await this.updateToken({
+            refreshToken,
+            accessToken: access.token,
+            lastSeenAt: new Date()
+        });
+        if (!updated) {
+            return null;
+        }
+        this.setAccessCookie(apiReq, access.token, stored.sessionCookie ?? false);
+        if (apiReq.req.cookies) {
+            apiReq.req.cookies[conf.accessCookie] = access.token;
+        }
+        const verifiedAccess = await this.verifyJWT(access.token);
+        if (!verifiedAccess.tokenData) {
+            return null;
+        }
+        const refreshedStored = { ...stored, accessToken: access.token };
+        apiReq.authToken = refreshedStored;
+        return { token: access.token, tokenData: verifiedAccess.tokenData, stored: refreshedStored };
     }
     async authenticate(apiReq, authType) {
         if (authType === 'none') {
@@ -711,6 +1035,7 @@ export class ApiServer {
         let token = null;
         const authHeader = apiReq.req.headers.authorization;
         const requiresAuthToken = this.requiresAuthToken(authType);
+        const allowRefresh = requiresAuthToken || (authType === 'maybe' && this.config.refreshMaybe);
         const apiKeyAuth = await this.tryAuthenticateApiKey(apiReq, authType, authHeader);
         if (apiKeyAuth) {
             return apiKeyAuth;
@@ -719,32 +1044,84 @@ export class ApiServer {
             token = authHeader.slice(7).trim();
         }
         if (!token) {
-            const access = apiReq.req.cookies?.dat;
+            const access = apiReq.req.cookies?.[this.config.accessCookie];
             if (access) {
                 token = access;
             }
         }
-        if (!token || token === null) {
-            if (requiresAuthToken) {
-                throw new ApiError({ code: 401, message: 'Authorization token is required (Bearer/cookie)' });
-            }
-        }
+        let tokenData;
+        let error;
+        let expired = false;
         if (!token) {
             if (authType === 'maybe') {
-                return null;
+                if (!this.config.refreshMaybe) {
+                    return null;
+                }
+                const refreshed = await this.tryRefreshAccessToken(apiReq);
+                if (!refreshed) {
+                    return null;
+                }
+                token = refreshed.token;
+                tokenData = refreshed.tokenData;
+                error = undefined;
+                expired = false;
             }
-            else {
-                throw new ApiError({ code: 401, message: 'Unauthorized Access - requires authentication' });
+            else if (requiresAuthToken) {
+                const refreshed = await this.tryRefreshAccessToken(apiReq);
+                if (!refreshed) {
+                    throw new ApiError({ code: 401, message: 'Authorization token is required (Bearer/cookie)' });
+                }
+                token = refreshed.token;
+                tokenData = refreshed.tokenData;
+                error = undefined;
+                expired = false;
+            }
+        }
+        if (!token) {
+            throw new ApiError({ code: 401, message: 'Unauthorized Access - requires authentication' });
+        }
+        if (!tokenData) {
+            const verified = await this.verifyJWT(token);
+            tokenData = verified.tokenData;
+            error = verified.error;
+            expired = verified.expired ?? false;
+        }
+        if (!tokenData && allowRefresh && expired) {
+            const refreshed = await this.tryRefreshAccessToken(apiReq);
+            if (refreshed) {
+                token = refreshed.token;
+                tokenData = refreshed.tokenData;
+                error = undefined;
             }
         }
-        const { tokenData, error } = await this.verifyJWT(token);
         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);
         if (this.shouldValidateStoredToken(authType)) {
-            await this.assertStoredAccessToken(apiReq, token, tokenData);
+            try {
+                await this.assertStoredAccessToken(apiReq, token, tokenData);
+            }
+            catch (error) {
+                if (allowRefresh &&
+                    error instanceof ApiError &&
+                    error.code === 401 &&
+                    error.message === 'Authorization token is no longer valid') {
+                    const refreshed = await this.tryRefreshAccessToken(apiReq);
+                    if (!refreshed) {
+                        throw error;
+                    }
+                    token = refreshed.token;
+                    tokenData = refreshed.tokenData;
+                    const refreshedUserId = this.extractTokenUserId(tokenData);
+                    apiReq.realUid = this.resolveRealUserId(tokenData, refreshedUserId);
+                    await this.assertStoredAccessToken(apiReq, token, tokenData);
+                }
+                else {
+                    throw error;
+                }
+            }
         }
         apiReq.token = token;
         return tokenData;
@@ -770,6 +1147,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: '',
@@ -786,6 +1168,9 @@ export class ApiServer {
     }
     async assertStoredAccessToken(apiReq, token, tokenData) {
         const userId = String(this.extractTokenUserId(tokenData));
+        if (apiReq.authToken && apiReq.authToken.accessToken === token && String(apiReq.authToken.userId) === userId) {
+            return;
+        }
         const stored = await this.storageAdapter.getToken({
             accessToken: token,
             userId
@@ -820,38 +1205,118 @@ export class ApiServer {
         if (rawReal === null) {
             return effectiveUserId;
         }
-        if (typeof rawReal === 'number' && rawReal === 0) {
-            return effectiveUserId;
-        }
         return rawReal;
     }
-    handle_request(handler, auth) {
+    useExpress(pathOrHandler, ...handlers) {
+        this.assertNotFinalized('useExpress');
+        if (typeof pathOrHandler === 'string') {
+            const apiPath = this.toApiRouterPath(pathOrHandler);
+            if (apiPath) {
+                this.apiRouter.use(apiPath, ...handlers);
+            }
+            else {
+                this.app.use(pathOrHandler, ...handlers);
+            }
+        }
+        else {
+            this.app.use(pathOrHandler, ...handlers);
+        }
+        return this;
+    }
+    createApiRequest(req, res) {
+        const apiReq = {
+            server: this,
+            req,
+            res,
+            token: '',
+            tokenData: null,
+            realUid: null,
+            getClientInfo: () => ensureClientInfo(apiReq),
+            getClientIp: () => ensureClientInfo(apiReq).ip,
+            getClientIpChain: () => ensureClientInfo(apiReq).ipchain,
+            getRealUid: () => apiReq.realUid ?? null,
+            isImpersonating: () => {
+                const realUid = apiReq.realUid;
+                const tokenUid = apiReq.tokenData?.uid;
+                if (realUid === null || realUid === undefined) {
+                    return false;
+                }
+                if (tokenUid === null || tokenUid === undefined) {
+                    return false;
+                }
+                return realUid !== tokenUid;
+            }
+        };
+        return apiReq;
+    }
+    expressAuth(auth) {
         return async (req, res, next) => {
-            void next;
-            const apiReq = {
-                server: this,
-                req,
-                res,
-                token: '',
-                tokenData: null,
-                realUid: null,
-                getClientInfo: () => ensureClientInfo(apiReq),
-                getClientIp: () => ensureClientInfo(apiReq).ip,
-                getClientIpChain: () => ensureClientInfo(apiReq).ipchain,
-                getRealUid: () => apiReq.realUid ?? null,
-                isImpersonating: () => {
-                    const realUid = apiReq.realUid;
-                    const tokenUid = apiReq.tokenData?.uid;
-                    if (realUid === null || realUid === undefined) {
-                        return false;
-                    }
-                    if (tokenUid === null || tokenUid === undefined) {
-                        return false;
-                    }
-                    return realUid !== tokenUid;
+            const apiReq = this.createApiRequest(req, res);
+            req.apiReq = apiReq;
+            res.locals.apiReq = apiReq;
+            try {
+                if (this.config.hydrateGetBody) {
+                    hydrateGetBody(req);
                 }
+                if (this.config.debug) {
+                    this.dumpRequest(apiReq);
+                }
+                apiReq.tokenData = await this.authenticate(apiReq, auth.type);
+                await this.authorize(apiReq, auth.req);
+                next();
+            }
+            catch (error) {
+                next(error);
+            }
+        };
+    }
+    expressErrorHandler() {
+        return (error, _req, res, next) => {
+            void _req;
+            if (res.headersSent) {
+                next(error);
+                return;
+            }
+            if (error instanceof ApiError || isApiErrorLike(error)) {
+                const apiError = error;
+                const normalizedErrors = apiError.errors && typeof apiError.errors === 'object' && !Array.isArray(apiError.errors)
+                    ? apiError.errors
+                    : {};
+                const errorPayload = {
+                    success: false,
+                    code: apiError.code,
+                    message: apiError.message,
+                    data: apiError.data ?? null,
+                    errors: normalizedErrors
+                };
+                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.internalServerErrorMessage(error),
+                data: null,
+                errors: {}
             };
-            this.currReq = apiReq;
+            res.status(500).json(errorPayload);
+        };
+    }
+    handle_request(handler, auth) {
+        return async (req, res, next) => {
+            void next;
+            const apiReq = this.createApiRequest(req, res);
             try {
                 if (this.config.hydrateGetBody) {
                     hydrateGetBody(apiReq.req);
@@ -873,7 +1338,7 @@ export class ApiServer {
                     throw new ApiError({ code: 500, message: 'Handler result must start with a numeric status code' });
                 }
                 const message = typeof rawMessage === 'string' ? rawMessage : 'Success';
-                const responsePayload = { code, message, data };
+                const responsePayload = { success: true, code, message, data, errors: {} };
                 if (this.config.debug) {
                     this.dumpResponse(apiReq, responsePayload, code);
                 }
@@ -886,6 +1351,7 @@ export class ApiServer {
                         ? apiError.errors
                         : {};
                     const errorPayload = {
+                        success: false,
                         code: apiError.code,
                         message: apiError.message,
                         data: apiError.data ?? null,
@@ -898,8 +1364,9 @@ export class ApiServer {
                 }
                 else {
                     const errorPayload = {
+                        success: false,
                         code: 500,
-                        message: this.guessExceptionText(error),
+                        message: this.internalServerErrorMessage(error),
                         data: null,
                         errors: {}
                     };
@@ -912,25 +1379,46 @@ export class ApiServer {
         };
     }
     api(module) {
+        this.assertNotFinalized('api');
         const router = express.Router();
         module.server = this;
-        if (module?.moduleType === 'auth') {
+        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}`;
         module.mountpath = mountPath;
         module.defineRoutes().forEach((r) => {
             const handler = this.handle_request(r.handler, r.auth);
-            router[r.method](r.path, handler);
+            switch (r.method) {
+                case 'get':
+                    router.get(r.path, handler);
+                    break;
+                case 'post':
+                    router.post(r.path, handler);
+                    break;
+                case 'put':
+                    router.put(r.path, handler);
+                    break;
+                case 'patch':
+                    router.patch(r.path, handler);
+                    break;
+                case 'delete':
+                    router.delete(r.path, handler);
+                    break;
+            }
             if (this.config.debug) {
                 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) {
@@ -940,9 +1428,29 @@ export class ApiServer {
         console.log('URL:', url);
         console.log('Method:', req.method);
         console.log('Query Params:', req.query || {});
-        console.log('Body Params:', req.body || {});
-        console.log('Cookies:', req.cookies || {});
-        console.log('Headers:', req.headers);
+        const sensitiveBodyKeys = ['password', 'client_secret', 'clientSecret', 'secret'];
+        const body = req.body && typeof req.body === 'object' ? { ...req.body } : req.body;
+        if (body && typeof body === 'object') {
+            for (const key of sensitiveBodyKeys) {
+                if (key in body) {
+                    body[key] = '[REDACTED]';
+                }
+            }
+        }
+        console.log('Body Params:', body || {});
+        const cookies = req.cookies ? { ...req.cookies } : {};
+        const sensitiveCookieKeys = [this.config.accessCookie, this.config.refreshCookie];
+        for (const key of sensitiveCookieKeys) {
+            if (key in cookies) {
+                cookies[key] = '[REDACTED]';
+            }
+        }
+        console.log('Cookies:', cookies);
+        const headers = { ...req.headers };
+        if (headers.authorization) {
+            headers.authorization = '[REDACTED]';
+        }
+        console.log('Headers:', headers);
         console.log('------------------------');
     }
     formatDebugValue(value, maxLength = 50, seen = new WeakSet()) {