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

package/dist/esm/{api-server-base.js → server/src/api-server-base.js}

@@ -4,19 +4,53 @@
  * This source code is licensed under the MIT license found in the
  * 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 cookie from '@fastify/cookie';
+import cors from '@fastify/cors';
+import multipart from '@fastify/multipart';
+import fastifyStatic from '@fastify/static';
+import fastify from 'fastify';
 import { nullAuthModule } from './auth-api/module.js';
 import { nullAuthAdapter } from './auth-api/storage.js';
 import { toOptionalStringId } from './auth-api/user-id.js';
 import { buildAuthCookieOptions } from './auth-cookie-options.js';
+import { ensureClientInfo } from './base/client-info.js';
+import { asHttpStatus, guessExceptionText, isApiErrorLike } from './base/error-utils.js';
+import { hydrateGetBody, isPlainObject } from './base/request-utils.js';
 import { TokenStore } from './token/base.js';
+class FastifyResponseAdapter {
+    constructor(reply) {
+        this.reply = reply;
+        this.locals = {};
+        this.statusCode = 200;
+    }
+    get headersSent() {
+        return this.reply.sent;
+    }
+    status(code) {
+        this.statusCode = code;
+        this.reply.code(code);
+        return this;
+    }
+    json(payload) {
+        if (!this.reply.sent) {
+            this.reply.code(this.statusCode).send(payload);
+        }
+    }
+    send(payload) {
+        if (!this.reply.sent) {
+            this.reply.code(this.statusCode).send(payload);
+        }
+    }
+    cookie(name, value, options = {}) {
+        this.reply.setCookie(name, value, options);
+    }
+    clearCookie(name, options = {}) {
+        this.reply.clearCookie(name, options);
+    }
+}
 class JwtHelperStore extends TokenStore {
     async save() {
         throw new Error('Token store is not configured');
@@ -38,288 +72,9 @@ class JwtHelperStore extends TokenStore {
     }
 }
 export { ApiModule } from './api-module.js';
-function guess_exception_text(error, defMsg = 'Unknown Error') {
-    const msg = [];
-    if (typeof error === 'string' && error.trim() !== '') {
-        msg.push(error);
-    }
-    else if (error && typeof error === 'object') {
-        const errorDetails = error;
-        if (typeof errorDetails.message === 'string' && errorDetails.message.trim() !== '') {
-            msg.push(errorDetails.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;
-}
-function isPlainObject(value) {
-    return !!value && typeof value === 'object' && !Array.isArray(value);
-}
-function hydrateGetBody(req) {
-    if ((req.method ?? '').toUpperCase() !== 'GET') {
-        return;
-    }
-    const query = isPlainObject(req.query) ? req.query : null;
-    if (!query || Object.keys(query).length === 0) {
-        return;
-    }
-    const body = isPlainObject(req.body) ? req.body : null;
-    if (!body || Object.keys(body).length === 0) {
-        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) {
-    let value = candidate.trim();
-    if (!value) {
-        return null;
-    }
-    value = value.replace(/^"+|"+$/g, '').replace(/^'+|'+$/g, '');
-    if (value.startsWith('::ffff:')) {
-        value = value.slice(7);
-    }
-    if (value.startsWith('[') && value.endsWith(']')) {
-        value = value.slice(1, -1);
-    }
-    const firstColon = value.indexOf(':');
-    const lastColon = value.lastIndexOf(':');
-    if (firstColon !== -1 && firstColon === lastColon) {
-        const maybePort = value.slice(lastColon + 1);
-        if (/^\d+$/.test(maybePort)) {
-            value = value.slice(0, lastColon);
-        }
-    }
-    value = value.trim();
-    return value || null;
-}
-function extractForwardedFor(header) {
-    if (!header) {
-        return [];
-    }
-    const values = Array.isArray(header) ? header : [header];
-    const ips = [];
-    for (const entry of values) {
-        for (const part of entry.split(',')) {
-            const normalized = normalizeIpAddress(part);
-            if (normalized) {
-                ips.push(normalized);
-            }
-        }
-    }
-    return ips;
-}
-function extractForwardedHeader(header) {
-    if (!header) {
-        return [];
-    }
-    const values = Array.isArray(header) ? header : [header];
-    const ips = [];
-    for (const entry of values) {
-        for (const part of entry.split(',')) {
-            const match = part.match(/for=([^;]+)/i);
-            if (match) {
-                const normalized = normalizeIpAddress(match[1]);
-                if (normalized) {
-                    ips.push(normalized);
-                }
-            }
-        }
-    }
-    return ips;
-}
-function detectBrowser(userAgent) {
-    const browserMatchers = [
-        { label: 'Edge', pattern: /(Edg|Edge|EdgiOS|EdgA)\/([\d.]+)/i, versionGroup: 2 },
-        { label: 'Chrome', pattern: /(Chrome|CriOS)\/([\d.]+)/i, versionGroup: 2 },
-        { label: 'Firefox', pattern: /(Firefox|FxiOS)\/([\d.]+)/i, versionGroup: 2 },
-        { label: 'Safari', pattern: /Version\/([\d.]+).*Safari/i, versionGroup: 1 },
-        { label: 'Opera', pattern: /(OPR|Opera)\/([\d.]+)/i, versionGroup: 2 },
-        { label: 'Brave', pattern: /Brave\/([\d.]+)/i, versionGroup: 1 },
-        { label: 'Vivaldi', pattern: /Vivaldi\/([\d.]+)/i, versionGroup: 1 },
-        { label: 'Electron', pattern: /Electron\/([\d.]+)/i, versionGroup: 1 },
-        { label: 'Node', pattern: /Node\.js\/([\d.]+)/i, versionGroup: 1 },
-        { label: 'IE', pattern: /MSIE ([\d.]+)/i, versionGroup: 1 },
-        { label: 'IE', pattern: /Trident\/.*rv:([\d.]+)/i, versionGroup: 1 }
-    ];
-    for (const matcher of browserMatchers) {
-        const m = userAgent.match(matcher.pattern);
-        if (m) {
-            const version = matcher.versionGroup ? m[matcher.versionGroup] : '';
-            return version ? `${matcher.label} ${version}` : matcher.label;
-        }
-    }
-    return '';
-}
-function detectOs(userAgent) {
-    const osMatchers = [
-        {
-            label: 'Windows',
-            pattern: /Windows NT ([\d.]+)/i,
-            transform: (match) => `Windows ${match[1]}`
-        },
-        {
-            label: 'iOS',
-            pattern: /iPhone OS ([\d_]+)/i,
-            transform: (match) => `iOS ${match[1].replace(/_/g, '.')}`
-        },
-        {
-            label: 'iPadOS',
-            pattern: /iPad; CPU OS ([\d_]+)/i,
-            transform: (match) => `iPadOS ${match[1].replace(/_/g, '.')}`
-        },
-        {
-            label: 'macOS',
-            pattern: /Mac OS X ([\d_]+)/i,
-            transform: (match) => `macOS ${match[1].replace(/_/g, '.')}`
-        },
-        {
-            label: 'Android',
-            pattern: /Android ([\d.]+)/i,
-            transform: (match) => `Android ${match[1]}`
-        },
-        {
-            label: 'ChromeOS',
-            pattern: /CrOS [^ ]+ ([\d.]+)/i,
-            transform: (match) => `ChromeOS ${match[1]}`
-        },
-        { label: 'Linux', pattern: /Linux/i },
-        { label: 'Unix', pattern: /X11/i }
-    ];
-    for (const matcher of osMatchers) {
-        const m = userAgent.match(matcher.pattern);
-        if (m) {
-            return matcher.transform ? matcher.transform(m) : matcher.label;
-        }
-    }
-    return '';
-}
-function detectDevice(userAgent, osLabel) {
-    if (/iPhone/i.test(userAgent)) {
-        return 'iPhone';
-    }
-    if (/iPad/i.test(userAgent)) {
-        return 'iPad';
-    }
-    if (/iPod/i.test(userAgent)) {
-        return 'iPod';
-    }
-    if (/Android/i.test(userAgent)) {
-        const match = userAgent.match(/;\s*([^;]+)\s+Build/i);
-        if (match) {
-            return match[1];
-        }
-        return 'Android Device';
-    }
-    if (/Macintosh/i.test(userAgent)) {
-        return 'Mac';
-    }
-    if (/Windows/i.test(userAgent)) {
-        return 'PC';
-    }
-    if (/CrOS/i.test(userAgent)) {
-        return 'Chromebook';
-    }
-    return osLabel;
-}
-function parseClientAgent(userAgentHeader) {
-    const raw = Array.isArray(userAgentHeader) ? userAgentHeader[0] : userAgentHeader;
-    const ua = typeof raw === 'string' ? raw.trim() : '';
-    if (!ua) {
-        return { ua: '', browser: '', os: '', device: '' };
-    }
-    const os = detectOs(ua);
-    const browser = detectBrowser(ua);
-    const device = detectDevice(ua, os);
-    return { ua, browser, os, device };
-}
-function isLoopbackAddress(ip) {
-    if (ip === '::1' || ip === '0:0:0:0:0:0:0:1') {
-        return true;
-    }
-    if (ip === '0.0.0.0' || ip === '127.0.0.1') {
-        return true;
-    }
-    if (ip.startsWith('127.')) {
-        return true;
-    }
-    return false;
-}
-function collectClientIpChain(req) {
-    const seen = new Set();
-    const result = [];
-    const pushNormalized = (ip) => {
-        if (!ip || seen.has(ip)) {
-            return;
-        }
-        seen.add(ip);
-        result.push(ip);
-    };
-    for (const ip of extractForwardedFor(req.headers['x-forwarded-for'])) {
-        pushNormalized(ip);
-    }
-    for (const ip of extractForwardedHeader(req.headers['forwarded'])) {
-        pushNormalized(ip);
-    }
-    const realIp = req.headers['x-real-ip'];
-    if (Array.isArray(realIp)) {
-        for (const value of realIp) {
-            pushNormalized(normalizeIpAddress(value));
-        }
-    }
-    else if (typeof realIp === 'string') {
-        pushNormalized(normalizeIpAddress(realIp));
-    }
-    if (Array.isArray(req.ips)) {
-        for (const ip of req.ips) {
-            pushNormalized(normalizeIpAddress(ip));
-        }
-    }
-    if (typeof req.ip === 'string') {
-        pushNormalized(normalizeIpAddress(req.ip));
-    }
-    const socketAddress = req.socket?.remoteAddress;
-    if (typeof socketAddress === 'string') {
-        pushNormalized(normalizeIpAddress(socketAddress));
-    }
-    const connectionAddress = req.connection?.remoteAddress;
-    if (typeof connectionAddress === 'string') {
-        pushNormalized(normalizeIpAddress(connectionAddress));
-    }
-    return result;
-}
-function selectClientIp(chain) {
-    for (const ip of chain) {
-        if (!isLoopbackAddress(ip)) {
-            return ip;
-        }
-    }
-    return chain[0] ?? null;
-}
-function buildClientInfo(req) {
-    const agent = parseClientAgent(req.headers['user-agent']);
-    const ipchain = collectClientIpChain(req);
-    const ip = selectClientIp(ipchain);
-    return {
-        ...agent,
-        ip,
-        ipchain
-    };
-}
-function ensureClientInfo(apiReq) {
-    if (!apiReq.clientInfo) {
-        apiReq.clientInfo = buildClientInfo(apiReq.req);
-    }
-    return apiReq.clientInfo;
-}
 export class ApiError extends Error {
     constructor({ code, message, data, errors }) {
-        const msg = guess_exception_text(message, '[Unknown error (null/undefined)]');
+        const msg = guessExceptionText(message, '[Unknown error (null/undefined)]');
         super(msg);
         this.message = msg;
         this.code = typeof code === 'number' ? code : 500;
@@ -327,24 +82,6 @@ export class ApiError extends Error {
         this.errors = errors !== undefined ? errors : {};
     }
 }
-function isApiErrorLike(candidate) {
-    if (!candidate || typeof candidate !== 'object') {
-        return false;
-    }
-    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,
@@ -364,6 +101,10 @@ function fillConfig(config) {
         cookieSameSite: config.cookieSameSite ?? 'lax',
         cookieSecure: config.cookieSecure ?? 'auto',
         cookieHttpOnly: config.cookieHttpOnly ?? true,
+        apiKeyPrefix: config.apiKeyPrefix ?? '',
+        apiKeyEnabled: config.apiKeyEnabled ?? false,
+        tokenParam: config.tokenParam ?? '',
+        tokenParamLocation: config.tokenParamLocation ?? 'body',
         accessCookie: config.accessCookie ?? 'dat',
         refreshCookie: config.refreshCookie ?? 'drt',
         accessExpiry: config.accessExpiry ?? 60 * 15,
@@ -377,36 +118,27 @@ function fillConfig(config) {
         apiVersion: config.apiVersion ?? '',
         minClientVersion: config.minClientVersion ?? '',
         tokenStore: config.tokenStore,
-        authStores: config.authStores,
-        onStartError: config.onStartError
+        onStartError: config.onStartError,
+        trustProxy: config.trustProxy ?? true
     };
 }
+/** Core Fastify-based API server with module mounting and auth integration hooks. */
 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.');
+            console.warn('[api-server-base] ApiServer.currReq is deprecated and always null. Use per-request ApiRequest in handlers.');
         }
         void _value;
     }
     constructor(config = {}) {
         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.compatGlobalErrorHandler = null;
         this.currReqDeprecationWarned = false;
         this.config = fillConfig(config);
         this.apiBasePath = this.normalizeApiBasePath(this.config.apiBasePath);
@@ -415,100 +147,153 @@ export class ApiServer {
         this.moduleAdapter = nullAuthModule;
         this.jwtHelper = new JwtHelperStore();
         this.tokenStoreAdapter = this.config.tokenStore ?? null;
-        if (this.config.authStores) {
-            const { userStore, tokenStore, passkeyService, oauthStore, canImpersonate } = this.config.authStores;
-            this.userStoreAdapter = userStore;
-            this.tokenStoreAdapter = tokenStore;
-            this.passkeyServiceAdapter = passkeyService ?? null;
-            this.oauthStoreAdapter = oauthStore ?? null;
-            this.canImpersonateAdapter = canImpersonate ?? null;
-            this.storageAdapter = this.getServerAuthAdapter();
-        }
-        if ((this.config.authApi || this.config.authStores) &&
-            (!this.config.accessSecret || !this.config.refreshSecret)) {
+        if (this.config.authApi && (!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, 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;
+        this.fastify = fastify({ logger: false, ajv: { customOptions: { allErrors: true, allowUnionTypes: true } } });
+        this.setupRuntime();
+        this.readyPromise = Promise.resolve(this.fastify.ready()).then(() => undefined);
+        const appHandler = (req, res) => {
+            void this.readyPromise
+                .then(() => {
+                this.fastify.routing(req, res);
+            })
+                .catch((error) => {
+                const message = this.internalServerErrorMessage(error);
+                res.statusCode = 500;
+                res.setHeader('content-type', 'application/json');
+                res.end(JSON.stringify({ success: false, code: 500, message, data: null, errors: {} }));
+            });
+        };
+        appHandler.listen = (...args) => {
+            const server = this.fastify.server;
+            void this.readyPromise.then(() => {
+                if (!server.listening) {
+                    server.listen(...args);
                 }
-                next(err);
             });
-        }
-        this.middlewares();
+            return server;
+        };
+        this.app = appHandler;
+    }
+    setupRuntime() {
+        this.fastify.register(cookie);
+        this.fastify.register(cors, {
+            origin: (origin, callback) => {
+                // No Origin header means a non-browser client (curl, server-to-server).
+                // CORS is a browser security feature; non-browser clients can bypass it
+                // by simply omitting the header, so blocking them here adds no security.
+                if (!origin) {
+                    callback(null, true);
+                    return;
+                }
+                // NOTE: An empty origins list means "allow all origins" (open/dev mode).
+                // Configure a non-empty origins list in production to restrict access.
+                if (this.config.origins.length > 0 && !this.config.origins.includes(origin)) {
+                    callback(new Error('Not allowed by CORS'), false);
+                    return;
+                }
+                callback(null, true);
+            },
+            credentials: true
+        });
+        this.fastify.register(multipart, {
+            limits: { fileSize: this.config.uploadMax }
+        });
+        this.fastify.addHook('preValidation', async (request) => {
+            if (request.method === 'GET' &&
+                request.body === undefined &&
+                typeof request.headers['content-length'] === 'string' &&
+                Number.parseInt(request.headers['content-length'], 10) > 0) {
+                const rawBody = await this.readRawBody(request.raw);
+                if (rawBody) {
+                    const contentType = (request.headers['content-type'] ?? '').toString().toLowerCase();
+                    request.body = this.parseRawBody(rawBody, contentType);
+                }
+            }
+            if (!request.isMultipart()) {
+                return;
+            }
+            const files = [];
+            const body = {};
+            for await (const part of request.parts()) {
+                if (part.type === 'file') {
+                    const buffer = await part.toBuffer();
+                    files.push({
+                        fieldname: part.fieldname,
+                        originalname: part.filename,
+                        encoding: part.encoding,
+                        mimetype: part.mimetype,
+                        size: buffer.length,
+                        buffer
+                    });
+                }
+                else {
+                    body[part.fieldname] = part.value;
+                }
+            }
+            request.__apiParsedBody = body;
+            request.__apiParsedFiles = files;
+        });
         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()`);
+    async readRawBody(req, maxBytes = 1048576) {
+        const chunks = [];
+        let total = 0;
+        for await (const chunk of req) {
+            const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
+            total += buf.length;
+            if (total > maxBytes) {
+                throw new ApiError({ code: 413, message: `Request body exceeds maximum size of ${maxBytes} bytes` });
+            }
+            chunks.push(buf);
         }
+        return Buffer.concat(chunks).toString('utf8');
     }
-    toApiRouterPath(candidate) {
-        if (typeof candidate !== 'string') {
-            return null;
-        }
-        const trimmed = candidate.trim();
-        if (!trimmed) {
-            return null;
+    parseRawBody(raw, contentType) {
+        if (!raw) {
+            return {};
         }
-        const normalized = trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
-        const base = this.apiBasePath;
-        if (base === '/') {
-            return normalized;
+        if (contentType.includes('application/json')) {
+            try {
+                return JSON.parse(raw);
+            }
+            catch {
+                return {};
+            }
         }
-        if (normalized === base) {
-            return '/';
+        if (contentType.includes('application/x-www-form-urlencoded')) {
+            const params = new URLSearchParams(raw);
+            return Object.fromEntries(params.entries());
         }
-        if (normalized.startsWith(`${base}/`)) {
-            return normalized.slice(base.length) || '/';
+        return raw;
+    }
+    assertNotFinalized(action) {
+        if (this.finalized) {
+            throw new Error(`Cannot call ApiServer.${action}() after finalize()/start()`);
         }
-        return null;
     }
     finalize() {
-        this.installApiNotFoundHandler();
-        this.installApiErrorHandler();
         this.finalized = true;
         return this;
     }
     authStorage(storage) {
+        this.assertNotFinalized('authStorage');
         this.storageAdapter = storage;
         return this;
     }
-    /**
-     * @deprecated Use {@link ApiServer.authStorage} instead.
-     */
     useAuthStorage(storage) {
         return this.authStorage(storage);
     }
     authModule(module) {
+        this.assertNotFinalized('authModule');
         this.moduleAdapter = module;
         return this;
     }
-    /**
-     * @deprecated Use {@link ApiServer.authModule} instead.
-     */
     useAuthModule(module) {
         return this.authModule(module);
     }
@@ -519,88 +304,39 @@ export class ApiServer {
         return this.moduleAdapter;
     }
     setTokenStore(store) {
+        this.assertNotFinalized('setTokenStore');
         this.tokenStoreAdapter = store;
-        // If using direct stores, expose the server-backed auth adapter.
-        if (this.userStoreAdapter) {
-            this.storageAdapter = this.getServerAuthAdapter();
-        }
         return this;
     }
     getTokenStore() {
         return this.tokenStoreAdapter;
     }
-    ensureUserStore() {
-        if (!this.userStoreAdapter) {
-            throw new Error('User store is not configured');
-        }
-        return this.userStoreAdapter;
-    }
-    ensureTokenStore() {
-        if (!this.tokenStoreAdapter) {
-            throw new Error('Token store is not configured');
-        }
-        return this.tokenStoreAdapter;
-    }
-    ensurePasskeyService() {
-        if (!this.passkeyServiceAdapter) {
+    async listUserCredentials(userId) {
+        if (typeof this.storageAdapter.listUserCredentials !== 'function') {
             throw new Error('Passkey service is not configured');
         }
-        return this.passkeyServiceAdapter;
-    }
-    async listUserCredentials(userId) {
-        return this.ensurePasskeyService().listUserCredentials(userId);
+        return this.storageAdapter.listUserCredentials(userId);
     }
     async deletePasskeyCredential(credentialId) {
-        return this.ensurePasskeyService().deleteCredential(credentialId);
-    }
-    ensureOAuthStore() {
-        if (!this.oauthStoreAdapter) {
-            throw new Error('OAuth store is not configured');
+        if (typeof this.storageAdapter.deletePasskeyCredential !== 'function') {
+            throw new Error('Passkey service is not configured');
         }
-        return this.oauthStoreAdapter;
-    }
-    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;
+        return this.storageAdapter.deletePasskeyCredential(credentialId);
     }
-    // AuthAdapter-compatible helpers (used by AuthModule)
     async getUser(identifier) {
-        return this.userStoreAdapter ? this.userStoreAdapter.findUser(identifier) : null;
+        return this.storageAdapter.getUser(identifier);
     }
     getUserPasswordHash(user) {
-        return this.ensureUserStore().getPasswordHash(user) ?? '';
+        return this.storageAdapter.getUserPasswordHash(user);
     }
     getUserId(user) {
-        return this.ensureUserStore().getUserId(user);
+        return this.storageAdapter.getUserId(user);
     }
     filterUser(user) {
-        return this.ensureUserStore().toPublic(user);
+        return this.storageAdapter.filterUser(user);
     }
     async verifyPassword(password, hash) {
-        return this.ensureUserStore().verifyPassword(password, hash);
+        return this.storageAdapter.verifyPassword(password, hash);
     }
     async storeToken(data) {
         if (this.tokenStoreAdapter) {
@@ -643,47 +379,55 @@ export class ApiServer {
         return 0;
     }
     async createPasskeyChallenge(params) {
-        return this.ensurePasskeyService().createChallenge(params);
+        if (typeof this.storageAdapter.createPasskeyChallenge !== 'function') {
+            throw new Error('Passkey service is not configured');
+        }
+        return this.storageAdapter.createPasskeyChallenge(params);
     }
     async verifyPasskeyResponse(params) {
-        return this.ensurePasskeyService().verifyResponse(params);
+        if (typeof this.storageAdapter.verifyPasskeyResponse !== 'function') {
+            throw new Error('Passkey service is not configured');
+        }
+        return this.storageAdapter.verifyPasskeyResponse(params);
     }
     async getClient(clientId) {
-        return this.oauthStoreAdapter ? this.oauthStoreAdapter.getClient(clientId) : null;
+        if (typeof this.storageAdapter.getClient !== 'function') {
+            return null;
+        }
+        return this.storageAdapter.getClient(clientId);
     }
     async verifyClientSecret(client, clientSecret) {
-        return this.ensureOAuthStore().verifyClientSecret(client.clientId, clientSecret);
+        if (typeof this.storageAdapter.verifyClientSecret !== 'function') {
+            throw new Error('OAuth store is not configured');
+        }
+        return this.storageAdapter.verifyClientSecret(client, clientSecret);
     }
     async createAuthCode(request) {
-        const expiresAt = new Date(Date.now() + (request.expiresInSeconds ?? 300) * 1000);
-        const code = request.code ?? randomUUID();
-        await this.ensureOAuthStore().createAuthCode({ ...request, code, expiresAt });
-        return {
-            code,
-            clientId: request.clientId,
-            userId: request.userId,
-            redirectUri: request.redirectUri,
-            scope: request.scope ?? [],
-            codeChallenge: request.codeChallenge,
-            codeChallengeMethod: request.codeChallengeMethod,
-            expiresAt,
-            metadata: request.metadata
-        };
+        if (typeof this.storageAdapter.createAuthCode !== 'function') {
+            throw new Error('OAuth store is not configured');
+        }
+        return this.storageAdapter.createAuthCode(request);
     }
     async consumeAuthCode(code, clientId) {
-        const consumed = await this.ensureOAuthStore().consumeAuthCode(code);
+        if (typeof this.storageAdapter.consumeAuthCode !== 'function') {
+            return null;
+        }
+        const consumed = await this.storageAdapter.consumeAuthCode(code, clientId);
         if (!consumed || consumed.clientId !== clientId) {
             return null;
         }
         return consumed;
     }
     async canImpersonate(params) {
-        if (this.canImpersonateAdapter) {
-            return !!(await this.canImpersonateAdapter(params));
+        if (typeof this.storageAdapter.canImpersonate === 'function') {
+            return !!(await this.storageAdapter.canImpersonate(params));
         }
         return params.realUserId === params.effectiveUserId;
     }
     jwtSign(payload, secret, expiresInSeconds, options) {
+        if (!secret) {
+            return { success: false, error: 'JWT secret is not configured' };
+        }
         return (this.tokenStoreAdapter ?? this.jwtHelper).jwtSign(payload, secret, expiresInSeconds, options);
     }
     jwtVerify(token, secret, options) {
@@ -694,6 +438,8 @@ export class ApiServer {
     }
     async getApiKey(token) {
         void token;
+        console.warn('[api-server-base] getApiKey() is not implemented. ' +
+            'Override getApiKey() in your ApiServer subclass to support API key authentication.');
         return null;
     }
     async authenticateUser(params) {
@@ -718,51 +464,30 @@ export class ApiServer {
         return false;
     }
     guessExceptionText(error, defMsg = 'Unknown Error') {
-        return guess_exception_text(error, defMsg);
+        return guessExceptionText(error, defMsg);
     }
     async authorize(apiReq, requiredClass) {
         void apiReq;
-        void requiredClass;
+        if (requiredClass && requiredClass !== 'any') {
+            console.warn(`[api-server-base] Route requires auth class "${requiredClass}" but the base authorize() is not overridden. ` +
+                'Override authorize() in your ApiServer subclass to enforce role/class requirements.');
+        }
     }
-    middlewares() {
-        this.app.use(express.json());
-        this.app.use(cookieParser());
-        const corsOptions = {
-            origin: (origin, callback) => {
-                if (!origin) {
-                    return callback(null, true);
-                }
-                if (this.config.origins && this.config.origins.length > 0) {
-                    if (this.config.origins.includes(origin)) {
-                        return callback(null, true);
-                    }
-                    return callback(new Error(`${origin} Not allowed by CORS`));
-                }
-                return callback(null, true);
-            },
-            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);
-        });
+    /**
+     * Authenticate and authorise an incoming Fastify request outside of the
+     * standard `defineRoutes` pipeline (e.g. TUS upload routes that need full
+     * control over their own response format).
+     *
+     * Throws `ApiError` on auth failure — callers should catch it and respond
+     * with the appropriate HTTP status code.
+     */
+    async resolveRequest(request, reply, auth) {
+        const req = this.toExtendedReq(request);
+        const res = new FastifyResponseAdapter(reply);
+        const apiReq = this.createApiRequest(req, res);
+        apiReq.tokenData = await this.authenticate(apiReq, auth.type);
+        await this.authorize(apiReq, auth.req ?? 'any');
+        return apiReq;
     }
     installStaticDirs() {
         const staticDirs = this.config.staticDirs;
@@ -776,12 +501,15 @@ export class ApiServer {
                 continue;
             }
             const resolvedMount = mount.startsWith('/') ? mount : `/${mount}`;
-            this.app.use(resolvedMount, express.static(dir));
+            void this.fastify.register(fastifyStatic, {
+                root: dir,
+                prefix: resolvedMount.endsWith('/') ? resolvedMount : `${resolvedMount}/`,
+                decorateReply: false
+            });
         }
     }
     installPingHandler() {
-        const path = `${this.apiBasePath}/v1/ping`;
-        this.app.get(path, (_req, res) => {
+        this.fastify.get(`${this.apiBasePath}/v1/ping`, async () => {
             const payload = {
                 success: true,
                 status: 'ok',
@@ -791,7 +519,7 @@ export class ApiServer {
                 startedAt: this.startedAt,
                 timestamp: new Date().toISOString()
             };
-            res.status(200).json({ success: true, code: 200, message: 'Success', data: payload, errors: {} });
+            return { success: true, code: 200, message: 'Success', data: payload, errors: {} };
         });
     }
     async loadSwaggerSpec() {
@@ -799,10 +527,11 @@ export class ApiServer {
         if (typeof __dirname === 'string') {
             candidates.push(path.resolve(__dirname, '../../docs/swagger/openapi.json'));
         }
+        let packageRoot;
         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), '..', '..');
+            packageRoot = path.resolve(path.dirname(entry), '..', '..');
             candidates.push(path.join(packageRoot, 'docs/swagger/openapi.json'));
         }
         catch {
@@ -817,7 +546,13 @@ export class ApiServer {
             }
             try {
                 const raw = await readFile(candidate, 'utf8');
-                return JSON.parse(raw);
+                const spec = JSON.parse(raw);
+                // Inject version from package.json at runtime
+                const version = await this.readPackageVersion(path.dirname(candidate));
+                if (version && spec.info && typeof spec.info === 'object') {
+                    spec.info.version = version;
+                }
+                return spec;
             }
             catch {
                 return null;
@@ -825,6 +560,27 @@ export class ApiServer {
         }
         return null;
     }
+    async readPackageVersion(specDir) {
+        // Walk up from the spec directory looking for package.json
+        const candidates = [
+            path.resolve(specDir, '../../package.json'),
+            path.resolve(specDir, '../package.json'),
+            path.resolve(process.cwd(), 'package.json')
+        ];
+        for (const candidate of candidates) {
+            try {
+                const raw = await readFile(candidate, 'utf8');
+                const pkg = JSON.parse(raw);
+                if (typeof pkg.version === 'string') {
+                    return pkg.version;
+                }
+            }
+            catch {
+                continue;
+            }
+        }
+        return null;
+    }
     installSwaggerHandler() {
         const rawPath = typeof this.config.swaggerPath === 'string' ? this.config.swaggerPath.trim() : '';
         const enabled = Boolean(this.config.swaggerEnabled) || rawPath.length > 0;
@@ -833,31 +589,35 @@ export class ApiServer {
         }
         const base = this.apiBasePath === '/' ? '' : this.apiBasePath;
         const resolved = rawPath.length > 0 ? rawPath : `${base}/swagger`;
-        const path = resolved.startsWith('/') ? resolved : `/${resolved}`;
+        const routePath = resolved.startsWith('/') ? resolved : `/${resolved}`;
         let specPromise;
-        this.app.get(path, async (_req, res) => {
+        this.fastify.get(routePath, async (_request, reply) => {
             if (!specPromise) {
                 specPromise = this.loadSwaggerSpec();
             }
             const spec = await specPromise;
             if (!spec) {
-                res.status(500).json({
+                // Clear cached failure so next request retries
+                specPromise = undefined;
+            }
+            if (!spec) {
+                reply.code(500);
+                return {
                     success: false,
                     code: 500,
                     message: 'Swagger spec is unavailable',
                     data: null,
                     errors: {}
-                });
-                return;
+                };
             }
-            res.status(200).json(spec);
+            return spec;
         });
     }
-    normalizeApiBasePath(path) {
-        if (!path || typeof path !== 'string') {
+    normalizeApiBasePath(routePath) {
+        if (!routePath || typeof routePath !== 'string') {
             return '/api';
         }
-        const trimmed = path.trim();
+        const trimmed = routePath.trim();
         if (!trimmed) {
             return '/api';
         }
@@ -868,47 +628,121 @@ export class ApiServer {
         return withLeadingSlash.replace(/\/+$/, '') || '/api';
     }
     installApiNotFoundHandler() {
-        if (this.apiNotFoundHandler) {
-            return;
-        }
-        this.apiNotFoundHandler = (req, res) => {
-            const payload = {
+        this.fastify.setNotFoundHandler((request, reply) => {
+            const target = request.raw.url ?? request.url;
+            if (!target.startsWith(this.apiBasePath)) {
+                reply.code(404).send('Not Found');
+                return;
+            }
+            const method = request.method.toUpperCase();
+            reply.code(404).send({
                 success: false,
                 code: 404,
-                message: this.describeMissingEndpoint(req),
+                message: `No such endpoint: ${method} ${target}`,
                 data: null,
                 errors: {}
-            };
-            res.status(404).json(payload);
-        };
-        this.app.use(this.apiBasePath, this.apiNotFoundHandler);
+            });
+        });
     }
     installApiErrorHandler() {
         if (this.apiErrorHandlerInstalled) {
             return;
         }
         this.apiErrorHandlerInstalled = true;
-        this.app.use(this.apiBasePath, this.expressErrorHandler());
-    }
-    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}`;
+        this.fastify.setErrorHandler((error, request, reply) => {
+            const message = error instanceof Error ? error.message : '';
+            if (message.includes('Not allowed by CORS')) {
+                const target = request.raw.url ?? request.url;
+                if (target.startsWith(this.apiBasePath)) {
+                    reply.code(403).send({
+                        success: false,
+                        code: 403,
+                        message: 'Origin not allowed by CORS',
+                        data: null,
+                        errors: {}
+                    });
+                    return;
+                }
+                reply.code(403).send('Origin not allowed by CORS');
+                return;
+            }
+            const validation = error.validation;
+            if (Array.isArray(validation)) {
+                const fieldErrors = {};
+                for (const v of validation) {
+                    const field = v.params?.missingProperty ?? (v.instancePath?.replace(/^\//, '') || 'body');
+                    fieldErrors[field] = v.message ?? 'Invalid value';
+                }
+                reply.code(400).send({
+                    success: false,
+                    code: 400,
+                    message: 'Validation failed',
+                    data: null,
+                    errors: fieldErrors
+                });
+                return;
+            }
+            if (error instanceof ApiError || isApiErrorLike(error)) {
+                const apiError = error;
+                reply.code(apiError.code).send({
+                    success: false,
+                    code: apiError.code,
+                    message: apiError.message,
+                    data: apiError.data ?? null,
+                    errors: apiError.errors && typeof apiError.errors === 'object' && !Array.isArray(apiError.errors)
+                        ? apiError.errors
+                        : {}
+                });
+                return;
+            }
+            const status = asHttpStatus(error);
+            if (status) {
+                if (status >= 500) {
+                    this.logUnhandledError(`Unhandled Fastify error mapped to HTTP ${status}`, error);
+                }
+                if (status === 413) {
+                    reply.code(413).send({
+                        success: false,
+                        code: 413,
+                        message: `Upload exceeds maximum size of ${this.config.uploadMax} bytes`,
+                        data: null,
+                        errors: {}
+                    });
+                    return;
+                }
+                reply.code(status).send({
+                    success: false,
+                    code: status,
+                    message: status === 400 ? 'Invalid request payload' : this.internalServerErrorMessage(error),
+                    data: null,
+                    errors: {}
+                });
+                return;
+            }
+            this.logUnhandledError('Unhandled Fastify error fallback to HTTP 500', error);
+            reply.code(500).send({
+                success: false,
+                code: 500,
+                message: this.internalServerErrorMessage(error),
+                data: null,
+                errors: {}
+            });
+        });
     }
     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
+        void this.fastify
             .listen({
             port: this.config.apiPort,
             host: this.config.apiHost
         })
-            .on('listening', () => {
+            .then(() => {
             console.log(`Server is running on http://${this.config.apiHost}:${this.config.apiPort}`);
         })
-            .on('error', (error) => {
+            .catch((error) => {
             let message;
             if (error.code === 'EADDRINUSE') {
                 message = `Port ${this.config.apiPort} is already in use.`;
@@ -928,13 +762,17 @@ export class ApiServer {
                 this.config.onStartError(err);
                 return;
             }
-            throw err;
+            this.logUnhandledError('Server startup failed', err);
+            process.exitCode = 1;
         });
         return this;
     }
     internalServerErrorMessage(error) {
         return this.config.debug ? this.guessExceptionText(error) : 'Internal server error';
     }
+    logUnhandledError(context, error) {
+        console.error(`[ApiServer] ${context}`, error);
+    }
     async verifyJWT(token) {
         if (!this.config.accessSecret) {
             return { tokenData: undefined, error: 'JWT authentication disabled; no jwtSecret set', expired: false };
@@ -943,7 +781,7 @@ export class ApiServer {
         if (!result.success) {
             return { tokenData: undefined, error: result.error, expired: result.expired };
         }
-        if (!result.data.uid) {
+        if (result.data.uid == null) {
             return { tokenData: undefined, error: 'Missing/bad userid in token', expired: false };
         }
         return { tokenData: result.data, error: undefined, expired: false };
@@ -986,8 +824,9 @@ export class ApiServer {
             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) {
+        const verifyUid = verify.data.uid != null ? String(verify.data.uid) : null;
+        // A missing uid claim is treated as a binding failure, not a skip.
+        if (!verifyUid || verifyUid !== storedUid) {
             return null;
         }
         const claims = verify.data;
@@ -995,7 +834,6 @@ export class ApiServer {
         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;
@@ -1034,19 +872,29 @@ export class ApiServer {
         }
         let token = null;
         const authHeader = apiReq.req.headers.authorization;
+        const headerValue = Array.isArray(authHeader) ? authHeader[0] : authHeader;
+        const bearerToken = headerValue?.startsWith('Bearer ') ? headerValue.slice(7).trim() || null : null;
+        const paramToken = bearerToken ? null : this.resolveTokenFromRequest(apiReq.req);
         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;
+        if (this.config.apiKeyEnabled || authType === 'apikey') {
+            const apiKeyAuth = await this.tryAuthenticateApiKey(apiReq, authType, bearerToken ?? paramToken);
+            if (apiKeyAuth) {
+                return apiKeyAuth;
+            }
+        }
+        token = bearerToken ?? paramToken;
+        if (bearerToken) {
+            apiReq.authMethod = 'bearer';
         }
-        if (authHeader?.startsWith('Bearer ')) {
-            token = authHeader.slice(7).trim();
+        else if (paramToken) {
+            apiReq.authMethod = 'param';
         }
         if (!token) {
             const access = apiReq.req.cookies?.[this.config.accessCookie];
             if (access) {
                 token = access;
+                apiReq.authMethod = 'cookie';
             }
         }
         let tokenData;
@@ -1126,40 +974,82 @@ export class ApiServer {
         apiReq.token = token;
         return tokenData;
     }
-    async tryAuthenticateApiKey(apiReq, authType, authHeader) {
-        if (!authHeader?.startsWith('Bearer ')) {
+    async tryAuthenticateApiKey(apiReq, authType, tokenCandidate) {
+        if (!tokenCandidate) {
             if (authType === 'apikey') {
                 throw new ApiError({ code: 401, message: 'Authorization header is missing or invalid' });
             }
             return null;
         }
-        const keyToken = authHeader.slice(7).trim();
-        if (!keyToken.startsWith('apikey-')) {
+        const keyToken = tokenCandidate;
+        const prefix = this.config.apiKeyPrefix;
+        const secret = prefix === '' ? keyToken : keyToken.startsWith(prefix) ? keyToken.slice(prefix.length) : null;
+        if (!secret) {
             if (authType === 'apikey') {
                 throw new ApiError({ code: 401, message: 'Invalid API Key' });
             }
             return null;
         }
-        const secret = keyToken.replace(/^apikey-/, '');
         const key = await this.getApiKey(secret);
         if (!key) {
-            throw new ApiError({ code: 401, message: 'Invalid API Key' });
+            if (authType === 'apikey') {
+                throw new ApiError({ code: 401, message: 'Invalid API Key' });
+            }
+            return null;
         }
         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;
+        apiReq.authMethod = 'apikey';
+        const resolvedRuid = this.normalizeAuthIdentifier(key.uid);
+        const resolvedEuid = key.euid !== undefined ? this.normalizeAuthIdentifier(key.euid) : null;
+        const effectiveUid = resolvedEuid ?? resolvedRuid;
+        if (resolvedRuid !== null) {
+            apiReq.realUid = resolvedRuid;
         }
         return {
-            uid: key.uid,
+            uid: effectiveUid,
+            ...(resolvedEuid !== null ? { ruid: resolvedRuid !== null ? String(resolvedRuid) : undefined } : {}),
             domain: '',
             fingerprint: '',
             iat: 0,
             exp: 0
         };
     }
+    resolveTokenFromRequest(req) {
+        const paramName = this.config.tokenParam.trim();
+        if (!paramName) {
+            return null;
+        }
+        const location = this.config.tokenParamLocation;
+        if (location === 'body') {
+            return this.readNamedValue(req.body, paramName);
+        }
+        if (location === 'query') {
+            return this.readNamedValue(req.query, paramName);
+        }
+        return this.readNamedValue(req.body, paramName) ?? this.readNamedValue(req.query, paramName);
+    }
+    readNamedValue(container, key) {
+        if (!container || typeof container !== 'object' || Array.isArray(container)) {
+            return null;
+        }
+        const raw = container[key];
+        if (typeof raw === 'string') {
+            const token = raw.trim();
+            return token.length > 0 ? token : null;
+        }
+        if (Array.isArray(raw)) {
+            for (const entry of raw) {
+                if (typeof entry === 'string') {
+                    const token = entry.trim();
+                    if (token.length > 0) {
+                        return token;
+                    }
+                }
+            }
+        }
+        return null;
+    }
     requiresAuthToken(authType) {
         return authType === 'yes' || authType === 'strict';
     }
@@ -1207,21 +1097,25 @@ export class ApiServer {
         }
         return rawReal;
     }
-    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;
+    toExtendedReq(request) {
+        const parsedBody = request.__apiParsedBody;
+        const parsedFiles = request.__apiParsedFiles;
+        const headers = request.headers;
+        return {
+            method: request.method,
+            url: request.url,
+            originalUrl: request.raw.url,
+            headers,
+            query: (request.query ?? {}),
+            body: parsedBody ?? request.body,
+            params: (request.params ?? {}),
+            cookies: (request.cookies ?? {}),
+            ip: request.ip,
+            ips: request.ips,
+            socket: request.socket,
+            protocol: request.protocol,
+            files: parsedFiles
+        };
     }
     createApiRequest(req, res) {
         const apiReq = {
@@ -1230,10 +1124,11 @@ export class ApiServer {
             res,
             token: '',
             tokenData: null,
+            authMethod: null,
             realUid: null,
-            getClientInfo: () => ensureClientInfo(apiReq),
-            getClientIp: () => ensureClientInfo(apiReq).ip,
-            getClientIpChain: () => ensureClientInfo(apiReq).ipchain,
+            getClientInfo: () => ensureClientInfo(apiReq, this.config.trustProxy),
+            getClientIp: () => ensureClientInfo(apiReq, this.config.trustProxy).ip,
+            getClientIpChain: () => ensureClientInfo(apiReq, this.config.trustProxy).ipchain,
             getRealUid: () => apiReq.realUid ?? null,
             isImpersonating: () => {
                 const realUid = apiReq.realUid;
@@ -1244,11 +1139,101 @@ export class ApiServer {
                 if (tokenUid === null || tokenUid === undefined) {
                     return false;
                 }
-                return realUid !== tokenUid;
+                // Normalise both sides to strings before comparing so that
+                // numeric 42 and string "42" are treated as the same identity.
+                return String(realUid) !== String(tokenUid);
             }
         };
         return apiReq;
     }
+    useExpress(pathOrHandler, ...handlers) {
+        this.assertNotFinalized('useExpress');
+        if (typeof pathOrHandler !== 'string') {
+            if (pathOrHandler.length === 4) {
+                this.compatGlobalErrorHandler = pathOrHandler;
+            }
+            return this;
+        }
+        const path = pathOrHandler;
+        const stack = handlers;
+        this.fastify.all(path, async (request, reply) => {
+            const req = this.toExtendedReq(request);
+            const res = new FastifyResponseAdapter(reply);
+            try {
+                await this.runCompatHandlers(stack, req, res);
+            }
+            catch (error) {
+                await this.runCompatErrorHandlers(error, stack, req, res);
+            }
+        });
+        return this;
+    }
+    async runCompatHandlers(stack, req, res) {
+        const handlers = stack.filter((fn) => fn.length !== 4);
+        for (const fn of handlers) {
+            await new Promise((resolve, reject) => {
+                let nextCalled = false;
+                const next = (error) => {
+                    nextCalled = true;
+                    if (error) {
+                        reject(error);
+                        return;
+                    }
+                    resolve();
+                };
+                try {
+                    const out = fn(req, res, next);
+                    Promise.resolve(out)
+                        .then(() => {
+                        if (!nextCalled) {
+                            resolve();
+                        }
+                    })
+                        .catch(reject);
+                }
+                catch (error) {
+                    reject(error);
+                }
+            });
+            if (res.headersSent) {
+                return;
+            }
+        }
+    }
+    async runCompatErrorHandlers(error, stack, req, res) {
+        const errorHandlers = stack.filter((fn) => fn.length === 4);
+        if (this.compatGlobalErrorHandler) {
+            errorHandlers.push(this.compatGlobalErrorHandler);
+        }
+        if (errorHandlers.length === 0) {
+            throw error;
+        }
+        let currentError = error;
+        for (const handler of errorHandlers) {
+            await new Promise((resolve, reject) => {
+                const next = (nextError) => {
+                    if (nextError) {
+                        currentError = nextError;
+                    }
+                    resolve();
+                };
+                try {
+                    Promise.resolve(handler(currentError, req, res, next))
+                        .then(() => resolve())
+                        .catch(reject);
+                }
+                catch (caught) {
+                    reject(caught);
+                }
+            });
+            if (res.headersSent) {
+                return;
+            }
+        }
+        if (!res.headersSent) {
+            throw currentError;
+        }
+    }
     expressAuth(auth) {
         return async (req, res, next) => {
             const apiReq = this.createApiRequest(req, res);
@@ -1294,6 +1279,9 @@ export class ApiServer {
             }
             const status = asHttpStatus(error);
             if (status) {
+                if (status >= 500) {
+                    this.logUnhandledError(`Unhandled compat middleware error mapped to HTTP ${status}`, error);
+                }
                 res.status(status).json({
                     success: false,
                     code: status,
@@ -1303,19 +1291,20 @@ export class ApiServer {
                 });
                 return;
             }
-            const errorPayload = {
+            this.logUnhandledError('Unhandled compat middleware error fallback to HTTP 500', error);
+            res.status(500).json({
                 success: false,
                 code: 500,
                 message: this.internalServerErrorMessage(error),
                 data: null,
                 errors: {}
-            };
-            res.status(500).json(errorPayload);
+            });
         };
     }
-    handle_request(handler, auth) {
-        return async (req, res, next) => {
-            void next;
+    handleRequest(handler, auth) {
+        return async (request, reply) => {
+            const req = this.toExtendedReq(request);
+            const res = new FastifyResponseAdapter(reply);
             const apiReq = this.createApiRequest(req, res);
             try {
                 if (this.config.hydrateGetBody) {
@@ -1338,11 +1327,11 @@ 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 = { success: true, code, message, data, errors: {} };
+                const responsePayload = { success: code < 400, code, message, data, errors: {} };
                 if (this.config.debug) {
                     this.dumpResponse(apiReq, responsePayload, code);
                 }
-                res.status(code).json(responsePayload);
+                reply.code(code).send(responsePayload);
             }
             catch (error) {
                 if (error instanceof ApiError || isApiErrorLike(error)) {
@@ -1360,27 +1349,53 @@ export class ApiServer {
                     if (this.config.debug) {
                         this.dumpResponse(apiReq, errorPayload, apiError.code);
                     }
-                    res.status(apiError.code).json(errorPayload);
+                    reply.code(apiError.code).send(errorPayload);
                 }
                 else {
+                    const status = asHttpStatus(error) ?? 500;
+                    if (status >= 500) {
+                        this.logUnhandledError('Unhandled API route error fallback to HTTP 500', error);
+                    }
+                    const uploadTooLarge = error &&
+                        typeof error === 'object' &&
+                        ('code' in error ? error.code === 'FST_REQ_FILE_TOO_LARGE' : false);
                     const errorPayload = {
                         success: false,
-                        code: 500,
-                        message: this.internalServerErrorMessage(error),
+                        code: uploadTooLarge ? 413 : status,
+                        message: uploadTooLarge
+                            ? `Upload exceeds maximum size of ${this.config.uploadMax} bytes`
+                            : this.internalServerErrorMessage(error),
                         data: null,
                         errors: {}
                     };
                     if (this.config.debug) {
-                        this.dumpResponse(apiReq, errorPayload, 500);
+                        this.dumpResponse(apiReq, errorPayload, uploadTooLarge ? 413 : status);
                     }
-                    res.status(500).json(errorPayload);
+                    reply.code(uploadTooLarge ? 413 : status).send(errorPayload);
+                }
+            }
+        };
+    }
+    // Test/compat shim for direct unit-level request wrapping without Fastify runtime.
+    handle_request(handler, auth) {
+        return async (req, res, next) => {
+            const apiReq = this.createApiRequest(req, res);
+            try {
+                if (this.config.hydrateGetBody) {
+                    hydrateGetBody(apiReq.req);
                 }
+                apiReq.tokenData = await this.authenticate(apiReq, auth.type);
+                await this.authorize(apiReq, auth.req);
+                await handler(apiReq);
+                next();
+            }
+            catch (error) {
+                next(error);
             }
         };
     }
     api(module) {
         this.assertNotFinalized('api');
-        const router = express.Router();
         module.server = this;
         const moduleType = module.moduleType;
         if (moduleType === 'auth') {
@@ -1391,44 +1406,51 @@ export class ApiServer {
             const name = module.constructor?.name ? String(module.constructor.name) : 'ApiModule';
             throw new Error(`${name}.checkConfig() returned false`);
         }
-        const base = this.apiBasePath;
+        module.onMount();
         const ns = module.namespace;
-        const mountPath = `${base}${ns}`;
+        const mountPath = `${this.apiBasePath}${ns}`;
         module.mountpath = mountPath;
-        module.defineRoutes().forEach((r) => {
-            const handler = this.handle_request(r.handler, r.auth);
-            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;
-            }
+        for (const route of module.defineRoutes()) {
+            const handler = this.handleRequest(route.handler, route.auth);
+            const method = route.method.toUpperCase();
+            const fullPath = this.joinRoutePath(this.apiBasePath, ns, route.path);
+            this.fastify.route({ method, url: fullPath, handler, ...(route.schema ? { schema: route.schema } : {}) });
             if (this.config.debug) {
-                console.log(`Adding ${mountPath}${r.path} (${r.method.toUpperCase()})`);
+                console.log(`Adding ${fullPath} (${method})`);
             }
-        });
-        this.apiRouter.use(ns, router);
+        }
         return this;
     }
+    joinRoutePath(base, namespace, routePath) {
+        const parts = [base, namespace, routePath]
+            .filter((value) => typeof value === 'string' && value.length > 0)
+            .map((value, index) => {
+            if (index === 0) {
+                return value.startsWith('/') ? value : `/${value}`;
+            }
+            return value.replace(/^\/+/, '').replace(/\/+$/, '');
+        });
+        const joined = parts.join('/').replace(/\/+/g, '/');
+        return joined.startsWith('/') ? joined : `/${joined}`;
+    }
     dumpRequest(apiReq) {
         const req = apiReq.req;
+        const tokenParam = this.config.tokenParam.trim();
         console.log('--- Incoming Request! ---');
         const url = req.originalUrl || req.url;
         console.log('URL:', url);
         console.log('Method:', req.method);
-        console.log('Query Params:', req.query || {});
+        if (tokenParam && req.query && tokenParam in req.query) {
+            const maskedQuery = { ...req.query, [tokenParam]: '[REDACTED]' };
+            console.log('Query Params:', maskedQuery);
+        }
+        else {
+            console.log('Query Params:', req.query || {});
+        }
         const sensitiveBodyKeys = ['password', 'client_secret', 'clientSecret', 'secret'];
+        if (tokenParam) {
+            sensitiveBodyKeys.push(tokenParam);
+        }
         const body = req.body && typeof req.body === 'object' ? { ...req.body } : req.body;
         if (body && typeof body === 'object') {
             for (const key of sensitiveBodyKeys) {
@@ -1450,6 +1472,12 @@ export class ApiServer {
         if (headers.authorization) {
             headers.authorization = '[REDACTED]';
         }
+        if (headers['x-api-key']) {
+            headers['x-api-key'] = '[REDACTED]';
+        }
+        if (headers.cookie) {
+            headers.cookie = '[REDACTED]';
+        }
         console.log('Headers:', headers);
         console.log('------------------------');
     }
@@ -1499,7 +1527,21 @@ export class ApiServer {
         return value;
     }
     dumpResponse(apiReq, payload, status) {
-        const url = apiReq.req.originalUrl || apiReq.req.url;
+        const rawUrl = apiReq.req.originalUrl || apiReq.req.url;
+        const tokenParam = this.config.tokenParam.trim();
+        let url = rawUrl;
+        if (tokenParam && rawUrl) {
+            try {
+                const parsed = new URL(rawUrl, 'http://x');
+                if (parsed.searchParams.has(tokenParam)) {
+                    parsed.searchParams.set(tokenParam, '[REDACTED]');
+                    url = parsed.pathname + '?' + parsed.searchParams.toString();
+                }
+            }
+            catch {
+                // Leave url unmodified if parsing fails
+            }
+        }
         console.log('--- Outgoing Response! ---');
         console.log('URL:', url);
         console.log('Status:', status);