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

package/dist/cjs/user/sequelize.js

@@ -3,28 +3,14 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.SequelizeUserStore = exports.AuthUserModel = void 0;
 exports.initAuthUserModel = initAuthUserModel;
 const sequelize_1 = require("sequelize");
+const user_id_js_1 = require("../auth-api/user-id.js");
+const sequelize_utils_js_1 = require("../sequelize-utils.js");
 const base_js_1 = require("./base.js");
-const DIALECTS_SUPPORTING_UNSIGNED = new Set(['mysql', 'mariadb']);
-function integerIdType(sequelize) {
-    return DIALECTS_SUPPORTING_UNSIGNED.has(sequelize.getDialect()) ? sequelize_1.DataTypes.INTEGER.UNSIGNED : sequelize_1.DataTypes.INTEGER;
-}
-function userTableOptions(sequelize) {
-    const opts = {
-        sequelize,
-        tableName: 'users',
-        timestamps: false
-    };
-    if (DIALECTS_SUPPORTING_UNSIGNED.has(sequelize.getDialect())) {
-        opts.charset = 'utf8mb4';
-        opts.collate = 'utf8mb4_unicode_ci';
-    }
-    return opts;
-}
 class AuthUserModel extends sequelize_1.Model {
 }
 exports.AuthUserModel = AuthUserModel;
-function initAuthUserModel(sequelize) {
-    const idType = integerIdType(sequelize);
+function initAuthUserModel(sequelize, options = {}) {
+    const idType = (0, sequelize_utils_js_1.integerIdType)(sequelize);
     AuthUserModel.init({
         user_id: {
             type: idType,
@@ -47,7 +33,7 @@ function initAuthUserModel(sequelize) {
             allowNull: false
         }
     }, {
-        ...userTableOptions(sequelize)
+        ...(0, sequelize_utils_js_1.tableOptions)(sequelize, 'users', options.tablePrefix, { timestamps: false })
     });
     return AuthUserModel;
 }
@@ -63,7 +49,9 @@ class SequelizeUserStore extends base_js_1.UserStore {
         }
         this.Users = options.userModel
             ? options.userModel
-            : (options.userModelFactory ?? initAuthUserModel)(options.sequelize);
+            : (options.userModelFactory ?? initAuthUserModel)(options.sequelize, {
+                tablePrefix: options.tablePrefix
+            });
         this.recordMapper =
             options.recordMapper ??
                 ((model) => SequelizeUserStore.mapModelToUser(model));
@@ -112,11 +100,16 @@ class SequelizeUserStore extends base_js_1.UserStore {
         if (providedId !== undefined && providedId !== null && Number.isFinite(providedId)) {
             defaults.user_id = Number(providedId);
         }
-        const [model] = await this.Users.findOrCreate({
-            where: { login: rest.login },
-            defaults: defaults
-        });
-        return this.toUserRecord(model);
+        try {
+            const model = await this.Users.create(defaults);
+            return this.toUserRecord(model);
+        }
+        catch (error) {
+            if (error instanceof sequelize_1.UniqueConstraintError) {
+                throw new Error(`User with login ${rest.login} or email ${rest.email} already exists`);
+            }
+            throw error;
+        }
     }
     async upsertUser(input) {
         const normalized = this.normalizeUserInput(input);
@@ -170,13 +163,7 @@ class SequelizeUserStore extends base_js_1.UserStore {
         };
     }
     normalizeUserId(identifier) {
-        if (typeof identifier === 'number' && Number.isFinite(identifier)) {
-            return identifier;
-        }
-        if (typeof identifier === 'string' && /^\d+$/.test(identifier)) {
-            return Number(identifier);
-        }
-        throw new Error(`Unable to normalise user identifier: ${identifier}`);
+        return (0, user_id_js_1.normalizeNumericUserId)(identifier);
     }
 }
 exports.SequelizeUserStore = SequelizeUserStore;

package/dist/esm/api-module.d.ts

@@ -1,12 +1,13 @@
 import type { ApiRequest } from './api-server-base.js';
-export type ApiHandler = (apiReq: ApiRequest) => Promise<[number] | [number, any] | [number, any, string]>;
+export type ApiHandlerResult<Data = unknown> = [number] | [number, Data] | [number, Data, string];
+export type ApiHandler<Data = unknown> = (apiReq: ApiRequest) => Promise<ApiHandlerResult<Data>>;
 export type ApiAuthType = 'none' | 'maybe' | 'yes' | 'strict' | 'apikey';
 export type ApiAuthClass = 'any' | 'admin';
 export interface ApiKey {
     uid: unknown;
 }
 export type ApiRoute = {
-    method: 'get' | 'post' | 'put' | 'delete';
+    method: 'get' | 'post' | 'put' | 'patch' | 'delete';
     path: string;
     handler: ApiHandler;
     auth: {
@@ -14,8 +15,10 @@ export type ApiRoute = {
         req: ApiAuthClass;
     };
 };
-export declare class ApiModule<T> {
-    server: T;
+export declare class ApiModule<T = unknown> {
+    private _server?;
+    get server(): T;
+    set server(value: T);
     namespace: string;
     mountpath: string;
     static defaultNamespace: string;

package/dist/esm/api-module.js

@@ -1,4 +1,13 @@
 export class ApiModule {
+    get server() {
+        if (this._server === undefined) {
+            throw new Error('ApiModule.server is not set. Mount the module with ApiServer.api(...) before using it.');
+        }
+        return this._server;
+    }
+    set server(value) {
+        this._server = value;
+    }
     constructor(opts = {}) {
         this.mountpath = '';
         this.namespace = opts.namespace ?? this.constructor.defaultNamespace ?? '';

package/dist/esm/api-server-base.d.ts

@@ -4,16 +4,16 @@
  * 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 } from 'express';
+import { Application, Request, Response, type ErrorRequestHandler, type RequestHandler } from 'express';
 import { ApiModule } from './api-module.js';
-import { TokenStore, type JwtDecodeResult, type JwtSignResult, type JwtVerifyResult } from './token/base.js';
-import type { ApiAuthClass, ApiKey } from './api-module.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 { AuthProviderModule } from './auth-api/module.js';
-import type { AuthStorage, AuthIdentifier } from './auth-api/types.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, PasskeyVerificationParams, PasskeyVerificationResult } from './passkey/types.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';
@@ -32,7 +32,7 @@ export interface ApiTokenData extends JwtPayload, Partial<Token> {
     exp?: number;
 }
 export interface ApiRequest {
-    server: any;
+    server: ApiServer;
     req: ExtendedReq;
     res: Response;
     tokenData?: ApiTokenData | null;
@@ -47,6 +47,12 @@ export interface ApiRequest {
     getRealUid: () => AuthIdentifier | null;
     isImpersonating: () => boolean;
 }
+export interface ExpressApiRequest extends ExtendedReq {
+    apiReq?: ApiRequest;
+}
+export interface ExpressApiLocals {
+    apiReq?: ApiRequest;
+}
 export interface ClientAgentProfile {
     ua: string;
     browser: string;
@@ -58,7 +64,7 @@ export interface ClientInfo extends ClientAgentProfile {
     ipchain: string[];
 }
 export interface ApiServerAuthStores {
-    userStore: UserStore<any, any>;
+    userStore: UserStore<unknown, unknown>;
     tokenStore: TokenStore;
     passkeyService?: PasskeyService;
     oauthStore?: OAuthStore;
@@ -71,13 +77,13 @@ export { ApiModule } from './api-module.js';
 export type { ApiHandler, ApiAuthType, ApiAuthClass, ApiRoute, ApiKey } from './api-module.js';
 export interface ApiErrorParams {
     code?: number;
-    message?: any;
-    data?: any;
+    message?: unknown;
+    data?: unknown;
     errors?: Record<string, string>;
 }
 export declare class ApiError extends Error {
     code: number;
-    data: any;
+    data: unknown;
     errors: Record<string, string>;
     constructor({ code, message, data, errors }: ApiErrorParams);
 }
@@ -86,12 +92,29 @@ export interface ApiServerConf {
     apiHost: string;
     uploadPath: string;
     uploadMax: number;
+    staticDirs?: Record<string, string>;
     origins: string[];
     debug: boolean;
     apiBasePath: string;
+    swaggerEnabled?: boolean;
+    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;
     accessCookie: string;
     refreshCookie: string;
     accessExpiry: number;
@@ -101,49 +124,68 @@ export interface ApiServerConf {
     devMode: boolean;
     hydrateGetBody: boolean;
     validateTokens: boolean;
+    refreshMaybe: boolean;
     apiVersion: string;
     minClientVersion: string;
     tokenStore?: TokenStore;
     authStores?: ApiServerAuthStores;
+    onStartError?: (error: Error) => void;
 }
 export declare class ApiServer {
     app: Application;
-    currReq: ApiRequest | null;
     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 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>);
-    authStorage<UserRow, SafeUser>(storage: AuthStorage<UserRow, SafeUser>): this;
+    private assertNotFinalized;
+    private toApiRouterPath;
+    finalize(): this;
+    authStorage<UserRow, SafeUser>(storage: AuthAdapter<UserRow, SafeUser>): this;
     /**
      * @deprecated Use {@link ApiServer.authStorage} instead.
      */
-    useAuthStorage<UserRow, SafeUser>(storage: AuthStorage<UserRow, SafeUser>): this;
+    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(): AuthStorage<any, any>;
-    getAuthModule(): AuthProviderModule<any>;
+    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;
-    getUser(identifier: AuthIdentifier): Promise<any | null>;
-    getUserPasswordHash(user: any): string;
-    getUserId(user: any): AuthIdentifier;
-    filterUser(user: any): any;
+    private getServerAuthAdapter;
+    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> & {
@@ -166,7 +208,7 @@ export declare class ApiServer {
         realUserId: AuthIdentifier;
         effectiveUserId: AuthIdentifier;
     }): Promise<boolean>;
-    jwtSign(payload: any, secret: string, expiresInSeconds: number, options?: SignOptions): JwtSignResult;
+    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>;
@@ -177,16 +219,23 @@ export declare class ApiServer {
     updateToken(updates: Partial<Token> & {
         refreshToken: string;
     }): Promise<boolean>;
-    guessExceptionText(error: any, defMsg?: string): string;
+    guessExceptionText(error: unknown, defMsg?: string): string;
     protected authorize(apiReq: ApiRequest, requiredClass: ApiAuthClass): Promise<void>;
     private middlewares;
+    private installStaticDirs;
     private installPingHandler;
+    private loadSwaggerSpec;
+    private installSwaggerHandler;
     private normalizeApiBasePath;
     private installApiNotFoundHandler;
-    private ensureApiNotFoundOrdering;
+    private installApiErrorHandler;
     private describeMissingEndpoint;
     start(): this;
+    private internalServerErrorMessage;
     private verifyJWT;
+    private jwtCookieOptions;
+    private setAccessCookie;
+    private tryRefreshAccessToken;
     private authenticate;
     private tryAuthenticateApiKey;
     private requiresAuthToken;
@@ -195,8 +244,16 @@ export declare class ApiServer {
     private normalizeAuthIdentifier;
     private extractTokenUserId;
     private resolveRealUserId;
+    useExpress(path: string, ...handlers: Array<RequestHandler | ErrorRequestHandler>): this;
+    useExpress(...handlers: Array<RequestHandler | ErrorRequestHandler>): this;
+    private createApiRequest;
+    expressAuth(auth: {
+        type: ApiAuthType;
+        req: ApiAuthClass;
+    }): RequestHandler;
+    expressErrorHandler(): ErrorRequestHandler;
     private handle_request;
-    api<T extends ApiModule<any>>(module: T): this;
+    api<T extends ApiModule<unknown>>(module: T): this;
     dumpRequest(apiReq: ApiRequest): void;
     private formatDebugValue;
     dumpResponse(apiReq: ApiRequest, payload: unknown, status: number): void;