@technomoron/apicore-server 1.0.0-beta.1

package/dist/cjs/apicore-server.d.ts

@@ -0,0 +1,288 @@
+/**
+ * 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 { 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, 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 { AuthCodeData, AuthCodeRequest, OAuthClient } from './oauth/types.js';
+import type { PasskeyChallenge, PasskeyChallengeParams, StoredPasskeyCredential, PasskeyVerificationParams, PasskeyVerificationResult } from './passkey/types.js';
+import type { Token } from './token/types.js';
+import type { JwtPayload, SignOptions, VerifyOptions } from 'jsonwebtoken';
+export type { JwtPayload, SignOptions, VerifyOptions } from 'jsonwebtoken';
+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: ApiResponse;
+    tokenData?: ApiTokenData | null;
+    token?: string;
+    authToken?: Token | null;
+    apiKey?: ApiKey | null;
+    authMethod?: ApiAuthMethod;
+    clientInfo?: ClientInfo;
+    realUid?: AuthIdentifier | null;
+    getClientInfo: () => ClientInfo;
+    getClientIp: () => string | null;
+    getClientIpChain: () => string[];
+    getRealUid: () => AuthIdentifier | null;
+    isImpersonating: () => boolean;
+}
+export type ExpressApiRequest = ExtendedReq;
+export interface ExpressApiLocals {
+    apiReq?: ApiRequest;
+}
+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 {
+    code?: number;
+    message?: unknown;
+    data?: unknown;
+    errors?: Record<string, string>;
+}
+export declare class ApiError extends Error {
+    code: number;
+    data: unknown;
+    errors: Record<string, string>;
+    constructor({ code, message, data, errors }: ApiErrorParams);
+}
+export interface ApiServerConf {
+    apiPort: number;
+    apiHost: string;
+    uploadPath: string;
+    uploadMax: number;
+    staticDirs?: Record<string, string>;
+    origins: string[];
+    debug: boolean;
+    apiBasePath: string;
+    swaggerEnabled?: boolean;
+    swaggerPath?: string;
+    accessSecret: string;
+    refreshSecret: string;
+    cookieDomain: string;
+    cookiePath?: string;
+    cookieSameSite?: 'lax' | 'strict' | 'none';
+    cookieSecure?: boolean | 'auto';
+    cookieHttpOnly?: boolean;
+    apiKeyPrefix: string;
+    apiKeyEnabled: boolean;
+    tokenParam: string;
+    tokenParamLocation: 'body' | 'query' | 'body-query';
+    accessCookie: string;
+    refreshCookie: string;
+    accessExpiry: number;
+    refreshExpiry: number;
+    sessionRefreshExpiry: number;
+    authApi: boolean;
+    devMode: boolean;
+    hydrateGetBody: boolean;
+    validateTokens: boolean;
+    refreshMaybe: boolean;
+    apiVersion: string;
+    minClientVersion: string;
+    tokenStore?: TokenStore;
+    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 {
+    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 finalized;
+    private storageAdapter;
+    private moduleAdapter;
+    private apiErrorHandlerInstalled;
+    private tokenStoreAdapter;
+    private readonly jwtHelper;
+    private compatGlobalErrorHandler;
+    private readonly readyPromise;
+    private currReqDeprecationWarned;
+    get currReq(): ApiRequest | null;
+    set currReq(_value: ApiRequest | null);
+    constructor(config?: Partial<ApiServerConf>);
+    private setupRuntime;
+    private readRawBody;
+    private parseRawBody;
+    private assertNotFinalized;
+    finalize(): this;
+    authStorage<UserRow, SafeUser>(storage: AuthAdapter<UserRow, SafeUser>): this;
+    useAuthStorage<UserRow, SafeUser>(storage: AuthAdapter<UserRow, SafeUser>): this;
+    authModule<UserRow>(module: AuthProviderModule<UserRow>): this;
+    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;
+    listUserCredentials(userId: AuthIdentifier): Promise<StoredPasskeyCredential[]>;
+    deletePasskeyCredential(credentialId: Buffer | string): Promise<boolean>;
+    getUser(identifier: AuthIdentifier): Promise<unknown | null>;
+    getUserPasswordHash(user: unknown): string;
+    getUserId(user: unknown): AuthIdentifier;
+    filterUser(user: unknown): unknown;
+    verifyPassword(password: string, hash: string): Promise<boolean>;
+    storeToken(data: Token): Promise<void>;
+    getToken(query: Partial<Token> & {
+        userId?: AuthIdentifier;
+        ruid?: AuthIdentifier;
+    }, opts?: {
+        includeExpired?: boolean;
+    }): Promise<Token | null>;
+    deleteToken(query: Partial<Token> & {
+        userId?: AuthIdentifier;
+        ruid?: AuthIdentifier;
+    }): Promise<number>;
+    createPasskeyChallenge(params: PasskeyChallengeParams): Promise<PasskeyChallenge>;
+    verifyPasskeyResponse(params: PasskeyVerificationParams): Promise<PasskeyVerificationResult>;
+    getClient(clientId: string): Promise<OAuthClient | null>;
+    verifyClientSecret(client: OAuthClient, clientSecret: string | null): Promise<boolean>;
+    createAuthCode(request: AuthCodeRequest): Promise<AuthCodeData>;
+    consumeAuthCode(code: string, clientId: string): Promise<AuthCodeData | null>;
+    canImpersonate(params: {
+        realUserId: AuthIdentifier;
+        effectiveUserId: AuthIdentifier;
+    }): Promise<boolean>;
+    jwtSign(payload: JwtSignPayload, secret: string, expiresInSeconds: number, options?: SignOptions): JwtSignResult;
+    jwtVerify<T>(token: string, secret: string, options?: VerifyOptions): JwtVerifyResult<T>;
+    jwtDecode<T>(token: string, options?: import('jsonwebtoken').DecodeOptions): JwtDecodeResult<T>;
+    getApiKey<T = ApiKey>(token: string): Promise<T | null>;
+    authenticateUser(params: {
+        login: string;
+        password: string;
+    }): Promise<boolean>;
+    updateToken(updates: Partial<Token> & {
+        refreshToken: string;
+    }): Promise<boolean>;
+    guessExceptionText(error: unknown, defMsg?: string): string;
+    protected authorize(apiReq: ApiRequest, requiredClass: ApiAuthClass): Promise<void>;
+    /**
+     * 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;
+    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;
+    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;
+    }): 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;
+}
+export default ApiServer;