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

package/dist/{cjs → esm/server/src}/api-module.d.ts

@@ -4,7 +4,10 @@ export type ApiHandler<Data = unknown> = (apiReq: ApiRequest) => Promise<ApiHand
 export type ApiAuthType = 'none' | 'maybe' | 'yes' | 'strict' | 'apikey';
 export type ApiAuthClass = 'any' | 'admin';
 export interface ApiKey {
+    /** Real user identity — who the key belongs to. */
     uid: unknown;
+    /** Effective user identity — who the key acts as. When set, the request is treated as impersonation (isImpersonating() === true). */
+    euid?: unknown;
 }
 export type ApiRoute = {
     method: 'get' | 'post' | 'put' | 'patch' | 'delete';
@@ -14,17 +17,29 @@ export type ApiRoute = {
         type: ApiAuthType;
         req: ApiAuthClass;
     };
+    schema?: {
+        body?: Record<string, unknown>;
+        querystring?: Record<string, unknown>;
+        params?: Record<string, unknown>;
+    };
 };
+/** Base class for feature modules mounted into {@link ApiServer}. */
 export declare class ApiModule<T = unknown> {
     private _server?;
+    /** The server instance this module is mounted on. */
     get server(): T;
     set server(value: T);
+    /** Route namespace under `apiBasePath`. */
     namespace: string;
     mountpath: string;
     static defaultNamespace: string;
     constructor(opts?: {
         namespace?: string;
     });
+    /** Optional pre-mount configuration validation hook. */
     checkConfig(): boolean;
+    /** Return all routes exposed by this module. */
     defineRoutes(): ApiRoute[];
+    /** Optional mount-time hook for modules that need direct server integration. */
+    onMount(): void;
 }

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

@@ -1,4 +1,6 @@
+/** Base class for feature modules mounted into {@link ApiServer}. */
 export class ApiModule {
+    /** The server instance this module is mounted on. */
     get server() {
         if (this._server === undefined) {
             throw new Error('ApiModule.server is not set. Mount the module with ApiServer.api(...) before using it.');
@@ -12,11 +14,17 @@ export class ApiModule {
         this.mountpath = '';
         this.namespace = opts.namespace ?? this.constructor.defaultNamespace ?? '';
     }
+    /** Optional pre-mount configuration validation hook. */
     checkConfig() {
         return true;
     }
+    /** Return all routes exposed by this module. */
     defineRoutes() {
         return [];
     }
+    /** Optional mount-time hook for modules that need direct server integration. */
+    onMount() {
+        return;
+    }
 }
 ApiModule.defaultNamespace = '';

package/dist/{cjs → esm/server/src}/api-server-base.d.ts

@@ -4,41 +4,80 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import { Application, Request, Response, type ErrorRequestHandler, type RequestHandler } from 'express';
+import { type FastifyInstance, type FastifyReply, type FastifyRequest } from 'fastify';
 import { ApiModule } from './api-module.js';
+import { type ClientInfo } from './base/client-info.js';
 import { TokenStore, type JwtDecodeResult, type JwtSignPayload, type JwtSignResult, type JwtVerifyResult } from './token/base.js';
-import type { ApiAuthClass, ApiAuthType, ApiKey } from './api-module.js';
+import type { ApiAuthClass, ApiAuthType, ApiHandler, ApiKey } from './api-module.js';
 import type { AuthProviderModule } from './auth-api/module.js';
 import type { AuthAdapter, AuthIdentifier } from './auth-api/types.js';
-import type { OAuthStore } from './oauth/base.js';
 import type { AuthCodeData, AuthCodeRequest, OAuthClient } from './oauth/types.js';
-import type { PasskeyService } from './passkey/service.js';
 import type { PasskeyChallenge, PasskeyChallengeParams, StoredPasskeyCredential, PasskeyVerificationParams, PasskeyVerificationResult } from './passkey/types.js';
 import type { Token } from './token/types.js';
-import type { UserStore } from './user/base.js';
 import type { JwtPayload, SignOptions, VerifyOptions } from 'jsonwebtoken';
-export type { Application, Request, Response, NextFunction, Router } from 'express';
-export type { Multer } from 'multer';
 export type { JwtPayload, SignOptions, VerifyOptions } from 'jsonwebtoken';
-export interface ExtendedReq extends Request {
-    file?: Express.Multer.File;
-    files?: Express.Multer.File[] | {
-        [fieldname: string]: Express.Multer.File[];
+export type { ClientAgentProfile, ClientInfo } from './base/client-info.js';
+export interface ApiCookieOptions {
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: 'lax' | 'strict' | 'none';
+    domain?: string;
+    path?: string;
+    maxAge?: number;
+    expires?: Date;
+}
+export interface ApiUploadedFile {
+    fieldname: string;
+    originalname: string;
+    encoding: string;
+    mimetype: string;
+    size?: number;
+    buffer?: Buffer;
+    filepath?: string;
+}
+export interface ExtendedReq {
+    method: string;
+    url: string;
+    originalUrl?: string;
+    headers: Record<string, string | string[] | undefined>;
+    query: Record<string, unknown>;
+    body: unknown;
+    params: Record<string, unknown>;
+    cookies?: Record<string, string>;
+    ip?: string;
+    ips?: string[];
+    socket?: {
+        remoteAddress?: string;
     };
+    protocol?: string;
+    file?: ApiUploadedFile;
+    files?: ApiUploadedFile[] | Record<string, ApiUploadedFile[]>;
+    apiReq?: ApiRequest;
+}
+export interface ApiResponse {
+    locals: Record<string, unknown>;
+    headersSent: boolean;
+    status: (code: number) => ApiResponse;
+    json: (payload: unknown) => void;
+    send: (payload: unknown) => void;
+    cookie: (name: string, value: string, options?: ApiCookieOptions) => void;
+    clearCookie: (name: string, options?: ApiCookieOptions) => void;
 }
 export interface ApiTokenData extends JwtPayload, Partial<Token> {
     uid: unknown;
     iat?: number;
     exp?: number;
 }
+export type ApiAuthMethod = 'bearer' | 'cookie' | 'param' | 'apikey' | null;
 export interface ApiRequest {
     server: ApiServer;
     req: ExtendedReq;
-    res: Response;
+    res: ApiResponse;
     tokenData?: ApiTokenData | null;
     token?: string;
     authToken?: Token | null;
     apiKey?: ApiKey | null;
+    authMethod?: ApiAuthMethod;
     clientInfo?: ClientInfo;
     realUid?: AuthIdentifier | null;
     getClientInfo: () => ClientInfo;
@@ -47,32 +86,13 @@ export interface ApiRequest {
     getRealUid: () => AuthIdentifier | null;
     isImpersonating: () => boolean;
 }
-export interface ExpressApiRequest extends ExtendedReq {
-    apiReq?: ApiRequest;
-}
+export type ExpressApiRequest = ExtendedReq;
 export interface ExpressApiLocals {
     apiReq?: ApiRequest;
 }
-export interface ClientAgentProfile {
-    ua: string;
-    browser: string;
-    os: string;
-    device: string;
-}
-export interface ClientInfo extends ClientAgentProfile {
-    ip: string | null;
-    ipchain: string[];
-}
-export interface ApiServerAuthStores {
-    userStore: UserStore<unknown, unknown>;
-    tokenStore: TokenStore;
-    passkeyService?: PasskeyService;
-    oauthStore?: OAuthStore;
-    canImpersonate?: (params: {
-        realUserId: AuthIdentifier;
-        effectiveUserId: AuthIdentifier;
-    }) => boolean | Promise<boolean>;
-}
+type CompatNext = (error?: unknown) => void;
+type CompatRequestHandler = (req: ExtendedReq, res: ApiResponse, next: CompatNext) => unknown;
+type CompatErrorHandler = (err: unknown, req: ExtendedReq, res: ApiResponse, next: CompatNext) => unknown;
 export { ApiModule } from './api-module.js';
 export type { ApiHandler, ApiAuthType, ApiAuthClass, ApiRoute, ApiKey } from './api-module.js';
 export interface ApiErrorParams {
@@ -100,21 +120,15 @@ export interface ApiServerConf {
     swaggerPath?: string;
     accessSecret: string;
     refreshSecret: string;
-    /** Cookie domain for auth cookies. Prefer leaving empty for localhost/development. */
     cookieDomain: string;
-    /** Cookie path for auth cookies. */
     cookiePath?: string;
-    /** Cookie SameSite attribute for auth cookies. */
     cookieSameSite?: 'lax' | 'strict' | 'none';
-    /**
-     * Cookie Secure attribute for auth cookies.
-     * - true: always secure
-     * - false: never secure
-     * - 'auto': secure when request is HTTPS (or forwarded as HTTPS)
-     */
     cookieSecure?: boolean | 'auto';
-    /** Cookie HttpOnly attribute for auth cookies. */
     cookieHttpOnly?: boolean;
+    apiKeyPrefix: string;
+    apiKeyEnabled: boolean;
+    tokenParam: string;
+    tokenParamLocation: 'body' | 'query' | 'body-query';
     accessCookie: string;
     refreshCookie: string;
     accessExpiry: number;
@@ -128,60 +142,51 @@ export interface ApiServerConf {
     apiVersion: string;
     minClientVersion: string;
     tokenStore?: TokenStore;
-    authStores?: ApiServerAuthStores;
     onStartError?: (error: Error) => void;
+    /**
+     * Controls trust in proxy headers (X-Forwarded-For, Forwarded, X-Real-IP).
+     * - `true` (default): trust all forwarded headers
+     * - `false`: only use the socket address, ignore forwarded headers
+     * - number: trust that many rightmost forwarded entries (e.g., 1 = one reverse proxy)
+     */
+    trustProxy: boolean | number;
 }
+/** Core Fastify-based API server with module mounting and auth integration hooks. */
 export declare class ApiServer {
-    app: Application;
+    readonly app: ((req: import('node:http').IncomingMessage, res: import('node:http').ServerResponse) => void) & {
+        listen: (...args: unknown[]) => import('node:http').Server;
+    };
+    readonly fastify: FastifyInstance;
     readonly config: ApiServerConf;
     readonly startedAt: number;
     private readonly apiBasePath;
-    private readonly apiRouter;
     private finalized;
     private storageAdapter;
     private moduleAdapter;
-    private serverAuthAdapter;
-    private apiNotFoundHandler;
     private apiErrorHandlerInstalled;
     private tokenStoreAdapter;
-    private userStoreAdapter;
-    private passkeyServiceAdapter;
-    private oauthStoreAdapter;
-    private canImpersonateAdapter;
     private readonly jwtHelper;
+    private compatGlobalErrorHandler;
+    private readonly readyPromise;
     private currReqDeprecationWarned;
-    /**
-     * @deprecated ApiServer does not track a global "current request". This value is always null.
-     * Use the per-request ApiRequest passed to handlers, or `req.apiReq` / `res.locals.apiReq`
-     * when mounting raw Express endpoints.
-     */
     get currReq(): ApiRequest | null;
     set currReq(_value: ApiRequest | null);
     constructor(config?: Partial<ApiServerConf>);
+    private setupRuntime;
+    private readRawBody;
+    private parseRawBody;
     private assertNotFinalized;
-    private toApiRouterPath;
     finalize(): this;
     authStorage<UserRow, SafeUser>(storage: AuthAdapter<UserRow, SafeUser>): this;
-    /**
-     * @deprecated Use {@link ApiServer.authStorage} instead.
-     */
     useAuthStorage<UserRow, SafeUser>(storage: AuthAdapter<UserRow, SafeUser>): this;
     authModule<UserRow>(module: AuthProviderModule<UserRow>): this;
-    /**
-     * @deprecated Use {@link ApiServer.authModule} instead.
-     */
     useAuthModule<UserRow>(module: AuthProviderModule<UserRow>): this;
     getAuthStorage<UserRow = unknown, SafeUser = unknown>(): AuthAdapter<UserRow, SafeUser>;
     getAuthModule<UserRow = unknown>(): AuthProviderModule<UserRow>;
     setTokenStore(store: TokenStore): this;
     getTokenStore(): TokenStore | null;
-    private ensureUserStore;
-    private ensureTokenStore;
-    private ensurePasskeyService;
     listUserCredentials(userId: AuthIdentifier): Promise<StoredPasskeyCredential[]>;
     deletePasskeyCredential(credentialId: Buffer | string): Promise<boolean>;
-    private ensureOAuthStore;
-    private getServerAuthAdapter;
     getUser(identifier: AuthIdentifier): Promise<unknown | null>;
     getUserPasswordHash(user: unknown): string;
     getUserId(user: unknown): AuthIdentifier;
@@ -221,39 +226,61 @@ export declare class ApiServer {
     }): Promise<boolean>;
     guessExceptionText(error: unknown, defMsg?: string): string;
     protected authorize(apiReq: ApiRequest, requiredClass: ApiAuthClass): Promise<void>;
-    private middlewares;
+    /**
+     * 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.
+     */
+    resolveRequest(request: FastifyRequest, reply: FastifyReply, auth: {
+        type: ApiAuthType;
+        req?: ApiAuthClass;
+    }): Promise<ApiRequest>;
     private installStaticDirs;
     private installPingHandler;
     private loadSwaggerSpec;
+    private readPackageVersion;
     private installSwaggerHandler;
     private normalizeApiBasePath;
     private installApiNotFoundHandler;
     private installApiErrorHandler;
-    private describeMissingEndpoint;
     start(): this;
     private internalServerErrorMessage;
+    private logUnhandledError;
     private verifyJWT;
     private jwtCookieOptions;
     private setAccessCookie;
     private tryRefreshAccessToken;
     private authenticate;
     private tryAuthenticateApiKey;
+    private resolveTokenFromRequest;
+    private readNamedValue;
     private requiresAuthToken;
     private shouldValidateStoredToken;
     private assertStoredAccessToken;
     private normalizeAuthIdentifier;
     private extractTokenUserId;
     private resolveRealUserId;
-    useExpress(path: string, ...handlers: Array<RequestHandler | ErrorRequestHandler>): this;
-    useExpress(...handlers: Array<RequestHandler | ErrorRequestHandler>): this;
+    private toExtendedReq;
     private createApiRequest;
+    useExpress(path: string, ...handlers: Array<CompatRequestHandler | CompatErrorHandler>): this;
+    useExpress(...handlers: Array<CompatRequestHandler | CompatErrorHandler>): this;
+    private runCompatHandlers;
+    private runCompatErrorHandlers;
     expressAuth(auth: {
         type: ApiAuthType;
         req: ApiAuthClass;
-    }): RequestHandler;
-    expressErrorHandler(): ErrorRequestHandler;
-    private handle_request;
+    }): CompatRequestHandler;
+    expressErrorHandler(): CompatErrorHandler;
+    private handleRequest;
+    protected handle_request(handler: ApiHandler, auth: {
+        type: ApiAuthType;
+        req: ApiAuthClass;
+    }): (req: ExtendedReq, res: ApiResponse, next: (error?: unknown) => void) => Promise<void>;
     api<T extends ApiModule<unknown>>(module: T): this;
+    private joinRoutePath;
     dumpRequest(apiReq: ApiRequest): void;
     private formatDebugValue;
     dumpResponse(apiReq: ApiRequest, payload: unknown, status: number): void;