@technomoron/apicore-server 1.0.0-beta.1

package/dist/esm/apicore-server.js

@@ -0,0 +1,1552 @@
+/**
+ * Copyright (c) 2025 Bjørn Erik Jacobsen / Technomoron
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import { access, readFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+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');
+    }
+    async get() {
+        throw new Error('Token store is not configured');
+    }
+    async delete() {
+        throw new Error('Token store is not configured');
+    }
+    async update() {
+        throw new Error('Token store is not configured');
+    }
+    async list() {
+        return [];
+    }
+    async close() {
+        return;
+    }
+}
+export { ApiModule } from './api-module.js';
+export class ApiError extends Error {
+    constructor({ code, message, data, errors }) {
+        const msg = guessExceptionText(message, '[Unknown error (null/undefined)]');
+        super(msg);
+        this.message = msg;
+        this.code = typeof code === 'number' ? code : 500;
+        this.data = data !== undefined ? data : null;
+        this.errors = errors !== undefined ? errors : {};
+    }
+}
+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 ?? '',
+        cookiePath: config.cookiePath ?? '/',
+        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,
+        refreshExpiry: config.refreshExpiry ?? 30 * 24 * 60 * 60,
+        sessionRefreshExpiry: config.sessionRefreshExpiry ?? 24 * 60 * 60,
+        authApi: config.authApi ?? false,
+        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,
+        onStartError: config.onStartError,
+        trustProxy: config.trustProxy ?? true
+    };
+}
+/** Core Fastify-based API server with module mounting and auth integration hooks. */
+export class ApiServer {
+    get currReq() {
+        return null;
+    }
+    set currReq(_value) {
+        if (this.config.devMode && !this.currReqDeprecationWarned) {
+            this.currReqDeprecationWarned = true;
+            console.warn('[apicore] ApiServer.currReq is deprecated and always null. Use per-request ApiRequest in handlers.');
+        }
+        void _value;
+    }
+    constructor(config = {}) {
+        this.finalized = false;
+        this.apiErrorHandlerInstalled = false;
+        this.tokenStoreAdapter = null;
+        this.compatGlobalErrorHandler = null;
+        this.currReqDeprecationWarned = false;
+        this.config = fillConfig(config);
+        this.apiBasePath = this.normalizeApiBasePath(this.config.apiBasePath);
+        this.startedAt = Date.now();
+        this.storageAdapter = nullAuthAdapter;
+        this.moduleAdapter = nullAuthModule;
+        this.jwtHelper = new JwtHelperStore();
+        this.tokenStoreAdapter = this.config.tokenStore ?? null;
+        if (this.config.authApi && (!this.config.accessSecret || !this.config.refreshSecret)) {
+            console.warn('[apicore] Auth is enabled but accessSecret and/or refreshSecret are empty. JWT signing will fail at runtime.');
+        }
+        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);
+                }
+            });
+            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.installApiNotFoundHandler();
+        this.installApiErrorHandler();
+    }
+    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');
+    }
+    parseRawBody(raw, contentType) {
+        if (!raw) {
+            return {};
+        }
+        if (contentType.includes('application/json')) {
+            try {
+                return JSON.parse(raw);
+            }
+            catch {
+                return {};
+            }
+        }
+        if (contentType.includes('application/x-www-form-urlencoded')) {
+            const params = new URLSearchParams(raw);
+            return Object.fromEntries(params.entries());
+        }
+        return raw;
+    }
+    assertNotFinalized(action) {
+        if (this.finalized) {
+            throw new Error(`Cannot call ApiServer.${action}() after finalize()/start()`);
+        }
+    }
+    finalize() {
+        this.finalized = true;
+        return this;
+    }
+    authStorage(storage) {
+        this.assertNotFinalized('authStorage');
+        this.storageAdapter = storage;
+        return this;
+    }
+    useAuthStorage(storage) {
+        return this.authStorage(storage);
+    }
+    authModule(module) {
+        this.assertNotFinalized('authModule');
+        this.moduleAdapter = module;
+        return this;
+    }
+    useAuthModule(module) {
+        return this.authModule(module);
+    }
+    getAuthStorage() {
+        return this.storageAdapter;
+    }
+    getAuthModule() {
+        return this.moduleAdapter;
+    }
+    setTokenStore(store) {
+        this.assertNotFinalized('setTokenStore');
+        this.tokenStoreAdapter = store;
+        return this;
+    }
+    getTokenStore() {
+        return this.tokenStoreAdapter;
+    }
+    async listUserCredentials(userId) {
+        if (typeof this.storageAdapter.listUserCredentials !== 'function') {
+            throw new Error('Passkey service is not configured');
+        }
+        return this.storageAdapter.listUserCredentials(userId);
+    }
+    async deletePasskeyCredential(credentialId) {
+        if (typeof this.storageAdapter.deletePasskeyCredential !== 'function') {
+            throw new Error('Passkey service is not configured');
+        }
+        return this.storageAdapter.deletePasskeyCredential(credentialId);
+    }
+    async getUser(identifier) {
+        return this.storageAdapter.getUser(identifier);
+    }
+    getUserPasswordHash(user) {
+        return this.storageAdapter.getUserPasswordHash(user);
+    }
+    getUserId(user) {
+        return this.storageAdapter.getUserId(user);
+    }
+    filterUser(user) {
+        return this.storageAdapter.filterUser(user);
+    }
+    async verifyPassword(password, hash) {
+        return this.storageAdapter.verifyPassword(password, hash);
+    }
+    async storeToken(data) {
+        if (this.tokenStoreAdapter) {
+            return this.tokenStoreAdapter.save(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: toOptionalStringId(query.userId),
+            ruid: toOptionalStringId(query.ruid)
+        };
+        if (this.tokenStoreAdapter) {
+            return this.tokenStoreAdapter.get(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: toOptionalStringId(query.userId),
+            ruid: toOptionalStringId(query.ruid)
+        };
+        if (this.tokenStoreAdapter) {
+            return this.tokenStoreAdapter.delete(normalized);
+        }
+        const storage = this.storageAdapter;
+        if (typeof storage.deleteToken === 'function') {
+            return storage.deleteToken(normalized);
+        }
+        return 0;
+    }
+    async createPasskeyChallenge(params) {
+        if (typeof this.storageAdapter.createPasskeyChallenge !== 'function') {
+            throw new Error('Passkey service is not configured');
+        }
+        return this.storageAdapter.createPasskeyChallenge(params);
+    }
+    async verifyPasskeyResponse(params) {
+        if (typeof this.storageAdapter.verifyPasskeyResponse !== 'function') {
+            throw new Error('Passkey service is not configured');
+        }
+        return this.storageAdapter.verifyPasskeyResponse(params);
+    }
+    async getClient(clientId) {
+        if (typeof this.storageAdapter.getClient !== 'function') {
+            return null;
+        }
+        return this.storageAdapter.getClient(clientId);
+    }
+    async verifyClientSecret(client, clientSecret) {
+        if (typeof this.storageAdapter.verifyClientSecret !== 'function') {
+            throw new Error('OAuth store is not configured');
+        }
+        return this.storageAdapter.verifyClientSecret(client, clientSecret);
+    }
+    async createAuthCode(request) {
+        if (typeof this.storageAdapter.createAuthCode !== 'function') {
+            throw new Error('OAuth store is not configured');
+        }
+        return this.storageAdapter.createAuthCode(request);
+    }
+    async consumeAuthCode(code, clientId) {
+        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 (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) {
+        return (this.tokenStoreAdapter ?? this.jwtHelper).jwtVerify(token, secret, options);
+    }
+    jwtDecode(token, options) {
+        return (this.tokenStoreAdapter ?? this.jwtHelper).jwtDecode(token, options);
+    }
+    async getApiKey(token) {
+        void token;
+        console.warn('[apicore] getApiKey() is not implemented. ' +
+            'Override getApiKey() in your ApiServer subclass to support API key authentication.');
+        return null;
+    }
+    async authenticateUser(params) {
+        if (!params?.login || !params?.password) {
+            return false;
+        }
+        const user = await this.storageAdapter.getUser(params.login);
+        if (!user) {
+            return false;
+        }
+        const hash = this.storageAdapter.getUserPasswordHash(user);
+        return this.storageAdapter.verifyPassword(params.password, hash);
+    }
+    async updateToken(updates) {
+        if (this.tokenStoreAdapter) {
+            return this.tokenStoreAdapter.update(updates);
+        }
+        const storage = this.storageAdapter;
+        if (typeof storage.updateToken === 'function') {
+            return storage.updateToken(updates);
+        }
+        return false;
+    }
+    guessExceptionText(error, defMsg = 'Unknown Error') {
+        return guessExceptionText(error, defMsg);
+    }
+    async authorize(apiReq, requiredClass) {
+        void apiReq;
+        if (requiredClass && requiredClass !== 'any') {
+            console.warn(`[apicore] Route requires auth class "${requiredClass}" but the base authorize() is not overridden. ` +
+                'Override authorize() in your ApiServer subclass to enforce role/class requirements.');
+        }
+    }
+    /**
+     * 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;
+        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}`;
+            void this.fastify.register(fastifyStatic, {
+                root: dir,
+                prefix: resolvedMount.endsWith('/') ? resolvedMount : `${resolvedMount}/`,
+                decorateReply: false
+            });
+        }
+    }
+    installPingHandler() {
+        this.fastify.get(`${this.apiBasePath}/v1/ping`, async () => {
+            const payload = {
+                success: true,
+                status: 'ok',
+                apiVersion: this.config.apiVersion ?? '',
+                minClientVersion: this.config.minClientVersion ?? '',
+                uptimeSec: process.uptime(),
+                startedAt: this.startedAt,
+                timestamp: new Date().toISOString()
+            };
+            return { 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'));
+        }
+        let packageRoot;
+        try {
+            const require = createRequire(path.join(process.cwd(), 'package.json'));
+            const entry = require.resolve('@technomoron/apicore-server');
+            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');
+                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;
+            }
+        }
+        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;
+        if (!enabled) {
+            return;
+        }
+        const base = this.apiBasePath === '/' ? '' : this.apiBasePath;
+        const resolved = rawPath.length > 0 ? rawPath : `${base}/swagger`;
+        const routePath = resolved.startsWith('/') ? resolved : `/${resolved}`;
+        let specPromise;
+        this.fastify.get(routePath, async (_request, reply) => {
+            if (!specPromise) {
+                specPromise = this.loadSwaggerSpec();
+            }
+            const spec = await specPromise;
+            if (!spec) {
+                // 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 spec;
+        });
+    }
+    normalizeApiBasePath(routePath) {
+        if (!routePath || typeof routePath !== 'string') {
+            return '/api';
+        }
+        const trimmed = routePath.trim();
+        if (!trimmed) {
+            return '/api';
+        }
+        const withLeadingSlash = trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+        if (withLeadingSlash.length === 1) {
+            return withLeadingSlash;
+        }
+        return withLeadingSlash.replace(/\/+$/, '') || '/api';
+    }
+    installApiNotFoundHandler() {
+        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: `No such endpoint: ${method} ${target}`,
+                data: null,
+                errors: {}
+            });
+        });
+    }
+    installApiErrorHandler() {
+        if (this.apiErrorHandlerInstalled) {
+            return;
+        }
+        this.apiErrorHandlerInstalled = true;
+        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('[apicore] ApiServer.start() called without finalize(); auto-finalizing. Call server.finalize() before start() to silence this warning.');
+            this.finalize();
+        }
+        void this.fastify
+            .listen({
+            port: this.config.apiPort,
+            host: this.config.apiHost
+        })
+            .then(() => {
+            console.log(`Server is running on http://${this.config.apiHost}:${this.config.apiPort}`);
+        })
+            .catch((error) => {
+            let message;
+            if (error.code === 'EADDRINUSE') {
+                message = `Port ${this.config.apiPort} is already in use.`;
+            }
+            else if (error.code === 'EACCES') {
+                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') {
+                message = `Address ${this.config.apiHost} is not available on this machine.`;
+            }
+            else {
+                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;
+            }
+            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 };
+        }
+        const result = this.jwtVerify(token, this.config.accessSecret);
+        if (!result.success) {
+            return { tokenData: undefined, error: result.error, expired: result.expired };
+        }
+        if (result.data.uid == null) {
+            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 });
+        }
+        catch {
+            return null;
+        }
+        if (!stored) {
+            return null;
+        }
+        const storedUid = String(stored.userId);
+        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;
+        const { exp: _exp, iat: _iat, nbf: _nbf, ...payload } = claims;
+        void _exp;
+        void _iat;
+        void _nbf;
+        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') {
+            apiReq.realUid = null;
+            return null;
+        }
+        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);
+        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';
+        }
+        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;
+        let error;
+        let expired = false;
+        if (!token) {
+            if (authType === 'maybe') {
+                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 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;
+            }
+        }
+        if (!tokenData) {
+            throw new ApiError({ code: 401, message: 'Unauthorized Access - ' + error });
+        }
+        const effectiveUserId = this.extractTokenUserId(tokenData);
+        apiReq.realUid = this.resolveRealUserId(tokenData, effectiveUserId);
+        if (this.shouldValidateStoredToken(authType)) {
+            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;
+    }
+    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 = 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 key = await this.getApiKey(secret);
+        if (!key) {
+            if (authType === 'apikey') {
+                throw new ApiError({ code: 401, message: 'Invalid API Key' });
+            }
+            return null;
+        }
+        apiReq.token = secret;
+        apiReq.apiKey = key;
+        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: 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';
+    }
+    shouldValidateStoredToken(authType) {
+        return this.config.validateTokens || authType === 'strict';
+    }
+    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
+        });
+        if (!stored) {
+            throw new ApiError({ code: 401, message: 'Authorization token is no longer valid' });
+        }
+        apiReq.authToken = stored;
+    }
+    normalizeAuthIdentifier(candidate) {
+        if (typeof candidate === 'number' && Number.isFinite(candidate)) {
+            return candidate;
+        }
+        if (typeof candidate === 'string') {
+            const trimmed = candidate.trim();
+            if (trimmed.length > 0) {
+                return trimmed;
+            }
+        }
+        return null;
+    }
+    extractTokenUserId(tokenData) {
+        const normalized = this.normalizeAuthIdentifier(tokenData.uid);
+        if (normalized === null) {
+            throw new ApiError({ code: 401, message: 'Authorization token is malformed' });
+        }
+        return normalized;
+    }
+    resolveRealUserId(tokenData, effectiveUserId) {
+        const withReal = tokenData;
+        const rawReal = this.normalizeAuthIdentifier(withReal.ruid);
+        if (rawReal === null) {
+            return effectiveUserId;
+        }
+        return rawReal;
+    }
+    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 = {
+            server: this,
+            req,
+            res,
+            token: '',
+            tokenData: null,
+            authMethod: null,
+            realUid: null,
+            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;
+                const tokenUid = apiReq.tokenData?.uid;
+                if (realUid === null || realUid === undefined) {
+                    return false;
+                }
+                if (tokenUid === null || tokenUid === undefined) {
+                    return false;
+                }
+                // 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);
+            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) {
+                if (status >= 500) {
+                    this.logUnhandledError(`Unhandled compat middleware error mapped to HTTP ${status}`, error);
+                }
+                res.status(status).json({
+                    success: false,
+                    code: status,
+                    message: status === 400 ? 'Invalid request payload' : this.internalServerErrorMessage(error),
+                    data: null,
+                    errors: {}
+                });
+                return;
+            }
+            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: {}
+            });
+        };
+    }
+    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) {
+                    hydrateGetBody(apiReq.req);
+                }
+                if (this.config.debug) {
+                    this.dumpRequest(apiReq);
+                }
+                apiReq.tokenData = await this.authenticate(apiReq, auth.type);
+                await this.authorize(apiReq, auth.req);
+                const handlerResult = await handler(apiReq);
+                if (!Array.isArray(handlerResult)) {
+                    throw new ApiError({
+                        code: 500,
+                        message: 'Handler result must be an array: [status, data?, message?]'
+                    });
+                }
+                const [code, data = null, rawMessage = 'Success'] = handlerResult;
+                if (typeof code !== 'number' || Number.isNaN(code)) {
+                    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: code < 400, code, message, data, errors: {} };
+                if (this.config.debug) {
+                    this.dumpResponse(apiReq, responsePayload, code);
+                }
+                reply.code(code).send(responsePayload);
+            }
+            catch (error) {
+                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
+                    };
+                    if (this.config.debug) {
+                        this.dumpResponse(apiReq, errorPayload, apiError.code);
+                    }
+                    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: 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, uploadTooLarge ? 413 : status);
+                    }
+                    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');
+        module.server = this;
+        const moduleType = module.moduleType;
+        if (moduleType === 'auth') {
+            this.authModule(module);
+        }
+        const configOk = module.checkConfig();
+        if (configOk === false) {
+            const name = module.constructor?.name ? String(module.constructor.name) : 'ApiModule';
+            throw new Error(`${name}.checkConfig() returned false`);
+        }
+        module.onMount();
+        const ns = module.namespace;
+        const mountPath = `${this.apiBasePath}${ns}`;
+        module.mountpath = mountPath;
+        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 ${fullPath} (${method})`);
+            }
+        }
+        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);
+        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) {
+                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]';
+        }
+        if (headers['x-api-key']) {
+            headers['x-api-key'] = '[REDACTED]';
+        }
+        if (headers.cookie) {
+            headers.cookie = '[REDACTED]';
+        }
+        console.log('Headers:', headers);
+        console.log('------------------------');
+    }
+    formatDebugValue(value, maxLength = 50, seen = new WeakSet()) {
+        if (value === null || value === undefined) {
+            return value;
+        }
+        if (typeof value === 'string') {
+            return value.length <= maxLength
+                ? value
+                : `${value.slice(0, maxLength)}… [truncated ${value.length - maxLength} chars]`;
+        }
+        if (typeof value === 'number' || typeof value === 'boolean' || typeof value === 'bigint') {
+            return value;
+        }
+        if (typeof value === 'symbol') {
+            return value.toString();
+        }
+        if (value instanceof Date) {
+            return value.toISOString();
+        }
+        if (typeof Buffer !== 'undefined' && Buffer.isBuffer(value)) {
+            return `<Buffer length=${value.length}>`;
+        }
+        if (typeof value === 'function') {
+            return `[Function ${value.name || 'anonymous'}]`;
+        }
+        if (typeof value === 'object') {
+            const obj = value;
+            if (seen.has(obj)) {
+                return '[Circular]';
+            }
+            seen.add(obj);
+            if (Array.isArray(value)) {
+                const arr = value.map((item) => this.formatDebugValue(item, maxLength, seen));
+                seen.delete(obj);
+                return arr;
+            }
+            const recordValue = value;
+            const entries = Object.entries(recordValue).reduce((acc, [key, val]) => {
+                acc[key] = this.formatDebugValue(val, maxLength, seen);
+                return acc;
+            }, {});
+            seen.delete(obj);
+            return entries;
+        }
+        return value;
+    }
+    dumpResponse(apiReq, payload, status) {
+        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);
+        console.log('Payload:', this.formatDebugValue(payload));
+        console.log('--------------------------');
+    }
+}
+export default ApiServer;