@technomoron/api-server-base 1.0.43 → 1.1.1

package/README.txt

@@ -27,18 +27,32 @@ All runtime dependencies and `@types/*` packages are bundled with the distributi
 
 Quick Start
 -----------
-import { ApiServer, ApiModule, ApiError } from '@technomoron/api-server-base';
+import { ApiServer, ApiModule, ApiError, BaseAuthStorage } from '@technomoron/api-server-base';
+
+type DemoUser = { id: string; email: string; password: string };
+
+class DemoStorage extends BaseAuthStorage<DemoUser, Omit<DemoUser, 'password'>> {
+	private readonly users = new Map<string, DemoUser>([
+		['1', { id: '1', email: 'demo@example.com', password: 'secret' }]
+	]);
 
-class AppServer extends ApiServer {
 	async getUser(uid: unknown) {
-		return { id: uid, email: 'demo@example.com' };
+		return this.users.get(String(uid)) ?? null;
+	}
+
+	getUserPasswordHash(user: DemoUser) {
+		return user.password;
 	}
 
-	filterUser(user: any) {
-		return { id: user.id, email: user.email };
+	filterUser(user: DemoUser) {
+		const { password: _password, ...safe } = user;
+		void _password;
+		return safe;
 	}
 }
 
+class AppServer extends ApiServer {}
+
 class UserModule extends ApiModule<AppServer> {
 	constructor() {
 		super({ namespace: '/users' });
@@ -51,24 +65,30 @@ class UserModule extends ApiModule<AppServer> {
 				path: '/',
 				auth: { type: 'yes', req: 'any' },
 				handler: async ({ server, tokenData }) => {
-					const user = await server.getUser(tokenData?.uid);
+					const storage = server.getAuthStorage();
+					const user = tokenData ? await storage.getUser(tokenData.uid) : null;
 					if (!user) {
 						throw new ApiError({ code: 404, message: 'User not found' });
 					}
-					return [200, server.filterUser(user)];
+					return [200, storage.filterUser(user)];
 				},
 			},
 		];
 	}
 }
 
+const yourStorageAdapter = new DemoStorage();
+
 const server = new AppServer({
 	apiPort: 3101,
 	apiHost: '127.0.0.1',
-	accessSecret: 'replace-me',
-});
+	accessSecret: 'replace-me'
+})
+	.authStorage(yourStorageAdapter)
+	.api(new UserModule())
+	.start();
 
-server.api(new UserModule()).start();
+Need a dedicated auth module as well? Chain `.authModule(...)` in the same spot.
 
 Handlers must return a tuple: [statusCode], [statusCode, data], or [statusCode, data, message]. Throw ApiError for predictable failures.
 
@@ -111,8 +131,8 @@ Use getClientIp(req) to obtain the most likely client address, skipping loopback
 
 Extending the Base Classes
 --------------------------
-Override getApiKey, getUser, authenticateUser, storeToken, getToken, updateToken, deleteToken, and verifyPassword to integrate with your persistence layer.
-Customize filterUser to trim sensitive data before sending it to the client.
+Implement the AuthStorage contract (getUser, verifyPassword, storeToken, updateToken, etc.) to integrate with your persistence layer, then supply it via authStorage().
+Use your storage adapter's filterUser helper to trim sensitive data before returning responses.
 Provide your own authorize method to enforce role based access control using the ApiAuthClass enum.
 Create feature modules by extending ApiModule. Use the optional checkConfig hook to validate prerequisites before routes mount.
 

package/dist/cjs/api-module.cjs

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApiModule = void 0;
+class ApiModule {
+    constructor(opts = {}) {
+        this.mountpath = '';
+        this.namespace = opts.namespace ?? this.constructor.defaultNamespace ?? '';
+    }
+    checkConfig() {
+        return true;
+    }
+    defineRoutes() {
+        return [];
+    }
+}
+exports.ApiModule = ApiModule;
+ApiModule.defaultNamespace = '';

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

@@ -0,0 +1,27 @@
+import type { ApiRequest } from './api-server-base.js';
+export type ApiHandler = (apiReq: ApiRequest) => Promise<[number] | [number, any] | [number, any, string]>;
+export type ApiAuthType = 'none' | 'maybe' | 'yes';
+export type ApiAuthClass = 'any' | 'admin';
+export interface ApiKey {
+    uid: unknown;
+}
+export type ApiRoute = {
+    method: 'get' | 'post' | 'put' | 'delete';
+    path: string;
+    handler: ApiHandler;
+    auth: {
+        type: ApiAuthType;
+        req: ApiAuthClass;
+    };
+};
+export declare class ApiModule<T> {
+    server: T;
+    namespace: string;
+    mountpath: string;
+    static defaultNamespace: string;
+    constructor(opts?: {
+        namespace?: string;
+    });
+    checkConfig(): boolean;
+    defineRoutes(): ApiRoute[];
+}

package/dist/cjs/api-server-base.cjs

@@ -15,20 +15,10 @@ const cors_1 = __importDefault(require("cors"));
 const express_1 = __importDefault(require("express"));
 const jsonwebtoken_1 = __importDefault(require("jsonwebtoken"));
 const multer_1 = __importDefault(require("multer"));
-class ApiModule {
-    constructor(opts = {}) {
-        this.mountpath = '';
-        this.namespace = opts.namespace ?? this.constructor.defaultNamespace ?? '';
-    }
-    checkConfig() {
-        return true;
-    }
-    defineRoutes() {
-        return [];
-    }
-}
-exports.ApiModule = ApiModule;
-ApiModule.defaultNamespace = '';
+const auth_module_js_1 = require("./auth-module.cjs");
+const auth_storage_js_1 = require("./auth-storage.cjs");
+var api_module_js_1 = require("./api-module.cjs");
+Object.defineProperty(exports, "ApiModule", { enumerable: true, get: function () { return api_module_js_1.ApiModule; } });
 function guess_exception_text(error, defMsg = 'Unknown Error') {
     const msg = [];
     if (typeof error === 'string' && error.trim() !== '') {
@@ -168,6 +158,8 @@ class ApiServer {
     constructor(config = {}) {
         this.currReq = null;
         this.config = fillConfig(config);
+        this.storageAdapter = auth_storage_js_1.nullAuthStorage;
+        this.moduleAdapter = auth_module_js_1.nullAuthModule;
         this.app = (0, express_1.default)();
         if (config.uploadPath) {
             const upload = (0, multer_1.default)({ dest: config.uploadPath });
@@ -176,6 +168,32 @@ class ApiServer {
         this.middlewares();
         // addSwaggerUi(this.app);
     }
+    authStorage(storage) {
+        this.storageAdapter = storage;
+        return this;
+    }
+    /**
+     * @deprecated Use {@link ApiServer.authStorage} instead.
+     */
+    useAuthStorage(storage) {
+        return this.authStorage(storage);
+    }
+    authModule(module) {
+        this.moduleAdapter = module;
+        return this;
+    }
+    /**
+     * @deprecated Use {@link ApiServer.authModule} instead.
+     */
+    useAuthModule(module) {
+        return this.authModule(module);
+    }
+    getAuthStorage() {
+        return this.storageAdapter;
+    }
+    getAuthModule() {
+        return this.moduleAdapter;
+    }
     jwtSign(payload, secret, expiresInSeconds, options) {
         options || (options = {});
         const opts = { ...options, expiresIn: expiresInSeconds };
@@ -247,37 +265,28 @@ class ApiServer {
         void token;
         return null;
     }
-    async getUser(uid) {
-        void uid;
-        throw new Error('getUser() not implemented');
-    }
     async authenticateUser(params) {
-        void params;
-        throw new Error('authenticateUser() not implemented');
-    }
-    async storeToken(params) {
-        void params;
-        throw new Error('storeToken() not implemented');
-    }
-    async getToken(params) {
-        void params;
-        throw new Error('getToken() not implemented');
-    }
-    async updateToken(params) {
-        void params;
-        throw new Error('updateToken() not implemented');
-    }
-    async deleteToken(params) {
-        void params;
-        throw new Error('deleteToken() not implemented');
-    }
-    async verifyPassword(password, hash) {
-        void password;
-        void hash;
-        throw new Error('verifyPassword() not implemented');
+        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);
     }
-    filterUser(fullUser) {
-        return fullUser;
+    async updateToken(updates) {
+        if (typeof this.storageAdapter.updateToken !== 'function') {
+            return false;
+        }
+        return this.storageAdapter.updateToken({
+            refreshToken: updates.refreshToken,
+            access: updates.accessToken,
+            expires: updates.expires,
+            clientId: updates.clientId,
+            scope: updates.scope
+        });
     }
     guessExceptionText(error, defMsg = 'Unkown Error') {
         return guess_exception_text(error, defMsg);
@@ -495,6 +504,9 @@ class ApiServer {
     api(module) {
         const router = express_1.default.Router();
         module.server = this;
+        if (module?.moduleType === 'auth') {
+            this.authModule(module);
+        }
         module.checkConfig();
         const base = this.config.apiBasePath ?? '/api';
         const ns = module.namespace;

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

@@ -6,6 +6,10 @@
  */
 import { Application, Request, Response } from 'express';
 import jwt, { JwtPayload, SignOptions, VerifyOptions } from 'jsonwebtoken';
+import { ApiModule } from './api-module.js';
+import type { ApiAuthClass, ApiKey } from './api-module.js';
+import type { AuthProviderModule } from './auth-module.js';
+import type { AuthStorage } from './auth-storage.js';
 export type { Application, Request, Response, NextFunction, Router } from 'express';
 export type { Multer } from 'multer';
 export type { JwtPayload, SignOptions, VerifyOptions } from 'jsonwebtoken';
@@ -43,32 +47,8 @@ export interface ApiRequest {
     tokenData?: ApiTokenData | null;
     token?: string;
 }
-export type ApiHandler = (apiReq: ApiRequest) => Promise<[number] | [number, any] | [number, any, string]>;
-export type ApiAuthType = 'none' | 'maybe' | 'yes';
-export type ApiAuthClass = 'any' | 'admin';
-export interface ApiKey {
-    uid: unknown;
-}
-export type ApiRoute = {
-    method: 'get' | 'post' | 'put' | 'delete';
-    path: string;
-    handler: ApiHandler;
-    auth: {
-        type: ApiAuthType;
-        req: ApiAuthClass;
-    };
-};
-export declare class ApiModule<T> {
-    server: T;
-    namespace: string;
-    mountpath: string;
-    static defaultNamespace: string;
-    constructor(opts?: {
-        namespace?: string;
-    });
-    checkConfig(): boolean;
-    defineRoutes(): ApiRoute[];
-}
+export { ApiModule } from './api-module.js';
+export type { ApiHandler, ApiAuthType, ApiAuthClass, ApiRoute, ApiKey } from './api-module.js';
 export interface ApiErrorParams {
     code?: number;
     message?: any;
@@ -104,41 +84,36 @@ export declare class ApiServer {
     app: Application;
     currReq: ApiRequest | null;
     readonly config: ApiServerConf;
+    private storageAdapter;
+    private moduleAdapter;
     constructor(config?: Partial<ApiServerConf>);
+    authStorage<UserRow, SafeUser>(storage: AuthStorage<UserRow, SafeUser>): this;
+    /**
+     * @deprecated Use {@link ApiServer.authStorage} instead.
+     */
+    useAuthStorage<UserRow, SafeUser>(storage: AuthStorage<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>;
     jwtSign(payload: any, secret: string, expiresInSeconds: number, options?: SignOptions): JwtSignResult;
     jwtVerify<T>(token: string, secret: string, options?: VerifyOptions): JwtVerifyResult<T>;
     jwtDecode<T>(token: string, options?: jwt.DecodeOptions): JwtDecodeResult<T>;
     getApiKey<T = ApiKey>(token: string): Promise<T | null>;
-    getUser(uid: unknown): Promise<unknown>;
-    authenticateUser(params: unknown): Promise<boolean>;
-    storeToken(params: {
-        access: string;
-        refresh: string;
-        userId: unknown;
-        domain?: string;
-        fingerprint?: string;
-        label?: string;
-    }): Promise<void>;
-    getToken(params: {
-        accessToken?: string;
-        refreshToken?: string;
-        userId?: unknown;
-    }): Promise<unknown>;
-    updateToken(params: {
+    authenticateUser(params: {
+        login: string;
+        password: string;
+    }): Promise<boolean>;
+    updateToken(updates: {
         accessToken: string;
         refreshToken: string;
         expires?: Date;
+        clientId?: string;
+        scope?: string[];
     }): Promise<boolean>;
-    deleteToken(params: {
-        refreshToken?: string;
-        accessToken?: string;
-        userId?: unknown;
-        domain?: string;
-        fingerprint?: string;
-        label?: string;
-    }): Promise<number>;
-    verifyPassword(password: string, hash: string): Promise<boolean>;
-    filterUser<T = any, U = any>(fullUser: T): U;
     guessExceptionText(error: any, defMsg?: string): string;
     protected authorize(apiReq: ApiRequest, requiredClass: ApiAuthClass): Promise<void>;
     private middlewares;

package/dist/cjs/auth-module.cjs

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nullAuthModule = exports.BaseAuthModule = void 0;
+const api_module_js_1 = require("./api-module.cjs");
+// Handy base that you can extend when wiring a real auth module. Subclasses
+// must supply a namespace via the constructor and implement token issuance.
+class BaseAuthModule extends api_module_js_1.ApiModule {
+    constructor(opts) {
+        super(opts);
+        this.moduleType = 'auth';
+    }
+}
+exports.BaseAuthModule = BaseAuthModule;
+class NullAuthModule extends BaseAuthModule {
+    constructor() {
+        super({ namespace: '__null__' });
+    }
+    async issueTokens(apiReq, user, metadata) {
+        void apiReq;
+        void user;
+        void metadata;
+        throw new Error('Auth module not configured. Inject a real auth module before issuing tokens.');
+    }
+}
+exports.nullAuthModule = new NullAuthModule();

package/dist/cjs/auth-module.d.ts

@@ -0,0 +1,20 @@
+import { ApiModule } from './api-module.js';
+import type { ApiRequest } from './api-server-base.js';
+import type { AuthTokenMetadata, AuthTokenPair } from './auth-storage.js';
+export interface AuthProviderModule<UserRow = unknown> {
+    readonly moduleType: 'auth';
+    readonly namespace: string;
+    issueTokens(apiReq: ApiRequest, user: UserRow, metadata?: AuthTokenMetadata & {
+        expires?: Date;
+    }): Promise<AuthTokenPair>;
+}
+export declare abstract class BaseAuthModule<UserRow = unknown> extends ApiModule<any> implements AuthProviderModule<UserRow> {
+    readonly moduleType: "auth";
+    protected constructor(opts: {
+        namespace: string;
+    });
+    abstract issueTokens(apiReq: ApiRequest, user: UserRow, metadata?: AuthTokenMetadata & {
+        expires?: Date;
+    }): Promise<AuthTokenPair>;
+}
+export declare const nullAuthModule: AuthProviderModule<unknown>;

package/dist/cjs/auth-storage.cjs

@@ -0,0 +1,87 @@
+"use strict";
+// Numeric database id or lookup string such as username/email.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nullAuthStorage = exports.BaseAuthStorage = void 0;
+// Handy base you can extend when wiring a real storage adapter. Every method
+// throws by default so unimplemented hooks fail loudly.
+class BaseAuthStorage {
+    // Override to load a user record by identifier
+    async getUser(identifier) {
+        void identifier;
+        return null;
+    }
+    // Override to return the stored password hash for the user
+    getUserPasswordHash(user) {
+        void user;
+        throw new Error('Auth storage not configured');
+    }
+    // Override to expose the canonical user identifier
+    getUserId(user) {
+        void user;
+        throw new Error('Auth storage not configured');
+    }
+    // Override to strip sensitive fields from the user record
+    filterUser(user) {
+        return user;
+    }
+    // Override to validate a raw password against the stored hash
+    async verifyPassword(password, hash) {
+        void password;
+        void hash;
+        throw new Error('Auth storage not configured');
+    }
+    // Override to persist newly issued tokens
+    async storeToken(data) {
+        void data;
+        throw new Error('Auth storage not configured');
+    }
+    // Override to look up a stored token by query
+    async getToken(query) {
+        void query;
+        return null;
+    }
+    // Override to remove stored tokens that match the query
+    async deleteToken(query) {
+        void query;
+        return 0;
+    }
+    // Override to update metadata for an existing refresh token
+    async updateToken(updates) {
+        void updates;
+        return false;
+    }
+    // Override to create a new passkey challenge record
+    async createPasskeyChallenge(params) {
+        void params;
+        throw new Error('Auth storage not configured');
+    }
+    // Override to verify an incoming WebAuthn response
+    async verifyPasskeyResponse(params) {
+        void params;
+        throw new Error('Auth storage not configured');
+    }
+    // Override to fetch an OAuth client by identifier
+    async getClient(clientId) {
+        void clientId;
+        return null;
+    }
+    // Override to compare a provided client secret against storage
+    async verifyClientSecret(client, clientSecret) {
+        void client;
+        void clientSecret;
+        throw new Error('Auth storage not configured');
+    }
+    // Override to create a new authorization code entry
+    async createAuthCode(request) {
+        void request;
+        throw new Error('Auth storage not configured');
+    }
+    // Override to consume and invalidate an authorization code
+    async consumeAuthCode(code, clientId) {
+        void code;
+        void clientId;
+        return null;
+    }
+}
+exports.BaseAuthStorage = BaseAuthStorage;
+exports.nullAuthStorage = new BaseAuthStorage();

package/dist/cjs/auth-storage.d.ts

@@ -0,0 +1,114 @@
+export type AuthIdentifier = string | number;
+export interface AuthTokenMetadata {
+    clientId?: string;
+    domain?: string;
+    fingerprint?: string;
+    label?: string;
+    scope?: string | string[];
+}
+export interface AuthTokenData extends AuthTokenMetadata {
+    access: string;
+    expires?: Date;
+    refresh: string;
+    userId: AuthIdentifier;
+}
+export interface AuthTokenQuery extends AuthTokenMetadata {
+    accessToken?: string;
+    refreshToken?: string;
+    userId?: AuthIdentifier;
+}
+export interface AuthTokenPair {
+    accessToken: string;
+    refreshToken: string;
+}
+export interface AuthTokenPayload extends AuthTokenMetadata {
+    exp?: number;
+    iat?: number;
+    uid: AuthIdentifier;
+}
+export interface PasskeyChallengeParams extends AuthTokenMetadata {
+    action: 'register' | 'authenticate';
+    login?: string;
+    userAgent?: string;
+    userId?: AuthIdentifier;
+}
+export interface PasskeyChallenge extends Record<string, unknown> {
+    challenge: string;
+    expiresAt?: string | number | Date;
+    userId?: AuthIdentifier;
+}
+export interface PasskeyVerificationParams extends AuthTokenMetadata {
+    expectedChallenge: string;
+    login?: string;
+    response: Record<string, unknown>;
+    userId?: AuthIdentifier;
+}
+export interface PasskeyVerificationResult extends Record<string, unknown> {
+    login?: string;
+    tokens?: AuthTokenPair;
+    userId?: AuthIdentifier;
+    verified: boolean;
+}
+export interface OAuthClient {
+    clientId: string;
+    clientSecret: string;
+    firstParty?: boolean;
+    metadata?: Record<string, unknown>;
+    name?: string;
+    redirectUris: string[];
+    scope?: string[];
+}
+export interface AuthCodeData {
+    code: string;
+    clientId: string;
+    codeChallenge?: string;
+    codeChallengeMethod?: 'plain' | 'S256';
+    expiresAt: Date;
+    metadata?: Record<string, unknown>;
+    redirectUri: string;
+    scope: string[];
+    userId: AuthIdentifier;
+}
+export type AuthCodeRequest = Omit<AuthCodeData, 'code' | 'expiresAt'> & {
+    code?: string;
+    expiresInSeconds?: number;
+};
+export interface AuthStorage<UserRow, SafeUser> {
+    getUser(identifier: AuthIdentifier): Promise<UserRow | null>;
+    getUserPasswordHash(user: UserRow): string;
+    getUserId(user: UserRow): AuthIdentifier;
+    filterUser(user: UserRow): SafeUser;
+    verifyPassword(password: string, hash: string): Promise<boolean>;
+    storeToken(data: AuthTokenData): Promise<void>;
+    getToken(query: AuthTokenQuery): Promise<AuthTokenData | null>;
+    deleteToken(query: AuthTokenQuery): Promise<number>;
+    updateToken?(updates: Partial<AuthTokenData> & {
+        refreshToken: string;
+    }): Promise<boolean>;
+    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>;
+}
+export declare class BaseAuthStorage<UserRow = unknown, SafeUser = unknown> implements AuthStorage<UserRow, SafeUser> {
+    getUser(identifier: AuthIdentifier): Promise<UserRow | null>;
+    getUserPasswordHash(user: UserRow): string;
+    getUserId(user: UserRow): AuthIdentifier;
+    filterUser(user: UserRow): SafeUser;
+    verifyPassword(password: string, hash: string): Promise<boolean>;
+    storeToken(data: AuthTokenData): Promise<void>;
+    getToken(query: AuthTokenQuery): Promise<AuthTokenData | null>;
+    deleteToken(query: AuthTokenQuery): Promise<number>;
+    updateToken(updates: Partial<AuthTokenData> & {
+        refreshToken: string;
+    }): Promise<boolean>;
+    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>;
+}
+export declare const nullAuthStorage: AuthStorage<unknown, unknown>;

package/dist/cjs/index.cjs

@@ -3,9 +3,16 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ApiError = exports.ApiModule = exports.ApiServer = void 0;
+exports.BaseAuthModule = exports.nullAuthModule = exports.BaseAuthStorage = exports.nullAuthStorage = exports.ApiModule = exports.ApiError = exports.ApiServer = void 0;
 var api_server_base_js_1 = require("./api-server-base.cjs");
 Object.defineProperty(exports, "ApiServer", { enumerable: true, get: function () { return __importDefault(api_server_base_js_1).default; } });
 var api_server_base_js_2 = require("./api-server-base.cjs");
-Object.defineProperty(exports, "ApiModule", { enumerable: true, get: function () { return api_server_base_js_2.ApiModule; } });
 Object.defineProperty(exports, "ApiError", { enumerable: true, get: function () { return api_server_base_js_2.ApiError; } });
+var api_module_js_1 = require("./api-module.cjs");
+Object.defineProperty(exports, "ApiModule", { enumerable: true, get: function () { return api_module_js_1.ApiModule; } });
+var auth_storage_js_1 = require("./auth-storage.cjs");
+Object.defineProperty(exports, "nullAuthStorage", { enumerable: true, get: function () { return auth_storage_js_1.nullAuthStorage; } });
+Object.defineProperty(exports, "BaseAuthStorage", { enumerable: true, get: function () { return auth_storage_js_1.BaseAuthStorage; } });
+var auth_module_js_1 = require("./auth-module.cjs");
+Object.defineProperty(exports, "nullAuthModule", { enumerable: true, get: function () { return auth_module_js_1.nullAuthModule; } });
+Object.defineProperty(exports, "BaseAuthModule", { enumerable: true, get: function () { return auth_module_js_1.BaseAuthModule; } });

package/dist/cjs/index.d.ts

@@ -1,3 +1,8 @@
 export { default as ApiServer } from './api-server-base.js';
-export { ApiModule, ApiError } from './api-server-base.js';
+export { ApiError } from './api-server-base.js';
+export { ApiModule } from './api-module.js';
 export type { ApiErrorParams, ApiHandler, ApiKey, ApiServerConf, ApiRequest, ApiRoute, ApiAuthType, ApiAuthClass, ApiTokenData, RequestWithStuff } from './api-server-base.js';
+export type { AuthIdentifier, AuthTokenMetadata, AuthTokenData, AuthTokenQuery, AuthTokenPair, AuthTokenPayload, PasskeyChallengeParams, PasskeyChallenge, PasskeyVerificationParams, PasskeyVerificationResult, OAuthClient, AuthCodeData, AuthCodeRequest, AuthStorage } from './auth-storage.js';
+export type { AuthProviderModule } from './auth-module.js';
+export { nullAuthStorage, BaseAuthStorage } from './auth-storage.js';
+export { nullAuthModule, BaseAuthModule } from './auth-module.js';

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

@@ -0,0 +1,27 @@
+import type { ApiRequest } from './api-server-base.js';
+export type ApiHandler = (apiReq: ApiRequest) => Promise<[number] | [number, any] | [number, any, string]>;
+export type ApiAuthType = 'none' | 'maybe' | 'yes';
+export type ApiAuthClass = 'any' | 'admin';
+export interface ApiKey {
+    uid: unknown;
+}
+export type ApiRoute = {
+    method: 'get' | 'post' | 'put' | 'delete';
+    path: string;
+    handler: ApiHandler;
+    auth: {
+        type: ApiAuthType;
+        req: ApiAuthClass;
+    };
+};
+export declare class ApiModule<T> {
+    server: T;
+    namespace: string;
+    mountpath: string;
+    static defaultNamespace: string;
+    constructor(opts?: {
+        namespace?: string;
+    });
+    checkConfig(): boolean;
+    defineRoutes(): ApiRoute[];
+}

package/dist/esm/api-module.js

@@ -0,0 +1,13 @@
+export class ApiModule {
+    constructor(opts = {}) {
+        this.mountpath = '';
+        this.namespace = opts.namespace ?? this.constructor.defaultNamespace ?? '';
+    }
+    checkConfig() {
+        return true;
+    }
+    defineRoutes() {
+        return [];
+    }
+}
+ApiModule.defaultNamespace = '';

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

@@ -6,6 +6,10 @@
  */
 import { Application, Request, Response } from 'express';
 import jwt, { JwtPayload, SignOptions, VerifyOptions } from 'jsonwebtoken';
+import { ApiModule } from './api-module.js';
+import type { ApiAuthClass, ApiKey } from './api-module.js';
+import type { AuthProviderModule } from './auth-module.js';
+import type { AuthStorage } from './auth-storage.js';
 export type { Application, Request, Response, NextFunction, Router } from 'express';
 export type { Multer } from 'multer';
 export type { JwtPayload, SignOptions, VerifyOptions } from 'jsonwebtoken';
@@ -43,32 +47,8 @@ export interface ApiRequest {
     tokenData?: ApiTokenData | null;
     token?: string;
 }
-export type ApiHandler = (apiReq: ApiRequest) => Promise<[number] | [number, any] | [number, any, string]>;
-export type ApiAuthType = 'none' | 'maybe' | 'yes';
-export type ApiAuthClass = 'any' | 'admin';
-export interface ApiKey {
-    uid: unknown;
-}
-export type ApiRoute = {
-    method: 'get' | 'post' | 'put' | 'delete';
-    path: string;
-    handler: ApiHandler;
-    auth: {
-        type: ApiAuthType;
-        req: ApiAuthClass;
-    };
-};
-export declare class ApiModule<T> {
-    server: T;
-    namespace: string;
-    mountpath: string;
-    static defaultNamespace: string;
-    constructor(opts?: {
-        namespace?: string;
-    });
-    checkConfig(): boolean;
-    defineRoutes(): ApiRoute[];
-}
+export { ApiModule } from './api-module.js';
+export type { ApiHandler, ApiAuthType, ApiAuthClass, ApiRoute, ApiKey } from './api-module.js';
 export interface ApiErrorParams {
     code?: number;
     message?: any;
@@ -104,41 +84,36 @@ export declare class ApiServer {
     app: Application;
     currReq: ApiRequest | null;
     readonly config: ApiServerConf;
+    private storageAdapter;
+    private moduleAdapter;
     constructor(config?: Partial<ApiServerConf>);
+    authStorage<UserRow, SafeUser>(storage: AuthStorage<UserRow, SafeUser>): this;
+    /**
+     * @deprecated Use {@link ApiServer.authStorage} instead.
+     */
+    useAuthStorage<UserRow, SafeUser>(storage: AuthStorage<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>;
     jwtSign(payload: any, secret: string, expiresInSeconds: number, options?: SignOptions): JwtSignResult;
     jwtVerify<T>(token: string, secret: string, options?: VerifyOptions): JwtVerifyResult<T>;
     jwtDecode<T>(token: string, options?: jwt.DecodeOptions): JwtDecodeResult<T>;
     getApiKey<T = ApiKey>(token: string): Promise<T | null>;
-    getUser(uid: unknown): Promise<unknown>;
-    authenticateUser(params: unknown): Promise<boolean>;
-    storeToken(params: {
-        access: string;
-        refresh: string;
-        userId: unknown;
-        domain?: string;
-        fingerprint?: string;
-        label?: string;
-    }): Promise<void>;
-    getToken(params: {
-        accessToken?: string;
-        refreshToken?: string;
-        userId?: unknown;
-    }): Promise<unknown>;
-    updateToken(params: {
+    authenticateUser(params: {
+        login: string;
+        password: string;
+    }): Promise<boolean>;
+    updateToken(updates: {
         accessToken: string;
         refreshToken: string;
         expires?: Date;
+        clientId?: string;
+        scope?: string[];
     }): Promise<boolean>;
-    deleteToken(params: {
-        refreshToken?: string;
-        accessToken?: string;
-        userId?: unknown;
-        domain?: string;
-        fingerprint?: string;
-        label?: string;
-    }): Promise<number>;
-    verifyPassword(password: string, hash: string): Promise<boolean>;
-    filterUser<T = any, U = any>(fullUser: T): U;
     guessExceptionText(error: any, defMsg?: string): string;
     protected authorize(apiReq: ApiRequest, requiredClass: ApiAuthClass): Promise<void>;
     private middlewares;

package/dist/esm/api-server-base.js

@@ -9,19 +9,9 @@ import cors from 'cors';
 import express from 'express';
 import jwt from 'jsonwebtoken';
 import multer from 'multer';
-export class ApiModule {
-    constructor(opts = {}) {
-        this.mountpath = '';
-        this.namespace = opts.namespace ?? this.constructor.defaultNamespace ?? '';
-    }
-    checkConfig() {
-        return true;
-    }
-    defineRoutes() {
-        return [];
-    }
-}
-ApiModule.defaultNamespace = '';
+import { nullAuthModule } from './auth-module.js';
+import { nullAuthStorage } from './auth-storage.js';
+export { ApiModule } from './api-module.js';
 function guess_exception_text(error, defMsg = 'Unknown Error') {
     const msg = [];
     if (typeof error === 'string' && error.trim() !== '') {
@@ -160,6 +150,8 @@ export class ApiServer {
     constructor(config = {}) {
         this.currReq = null;
         this.config = fillConfig(config);
+        this.storageAdapter = nullAuthStorage;
+        this.moduleAdapter = nullAuthModule;
         this.app = express();
         if (config.uploadPath) {
             const upload = multer({ dest: config.uploadPath });
@@ -168,6 +160,32 @@ export class ApiServer {
         this.middlewares();
         // addSwaggerUi(this.app);
     }
+    authStorage(storage) {
+        this.storageAdapter = storage;
+        return this;
+    }
+    /**
+     * @deprecated Use {@link ApiServer.authStorage} instead.
+     */
+    useAuthStorage(storage) {
+        return this.authStorage(storage);
+    }
+    authModule(module) {
+        this.moduleAdapter = module;
+        return this;
+    }
+    /**
+     * @deprecated Use {@link ApiServer.authModule} instead.
+     */
+    useAuthModule(module) {
+        return this.authModule(module);
+    }
+    getAuthStorage() {
+        return this.storageAdapter;
+    }
+    getAuthModule() {
+        return this.moduleAdapter;
+    }
     jwtSign(payload, secret, expiresInSeconds, options) {
         options || (options = {});
         const opts = { ...options, expiresIn: expiresInSeconds };
@@ -239,37 +257,28 @@ export class ApiServer {
         void token;
         return null;
     }
-    async getUser(uid) {
-        void uid;
-        throw new Error('getUser() not implemented');
-    }
     async authenticateUser(params) {
-        void params;
-        throw new Error('authenticateUser() not implemented');
-    }
-    async storeToken(params) {
-        void params;
-        throw new Error('storeToken() not implemented');
-    }
-    async getToken(params) {
-        void params;
-        throw new Error('getToken() not implemented');
-    }
-    async updateToken(params) {
-        void params;
-        throw new Error('updateToken() not implemented');
-    }
-    async deleteToken(params) {
-        void params;
-        throw new Error('deleteToken() not implemented');
-    }
-    async verifyPassword(password, hash) {
-        void password;
-        void hash;
-        throw new Error('verifyPassword() not implemented');
+        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);
     }
-    filterUser(fullUser) {
-        return fullUser;
+    async updateToken(updates) {
+        if (typeof this.storageAdapter.updateToken !== 'function') {
+            return false;
+        }
+        return this.storageAdapter.updateToken({
+            refreshToken: updates.refreshToken,
+            access: updates.accessToken,
+            expires: updates.expires,
+            clientId: updates.clientId,
+            scope: updates.scope
+        });
     }
     guessExceptionText(error, defMsg = 'Unkown Error') {
         return guess_exception_text(error, defMsg);
@@ -487,6 +496,9 @@ export class ApiServer {
     api(module) {
         const router = express.Router();
         module.server = this;
+        if (module?.moduleType === 'auth') {
+            this.authModule(module);
+        }
         module.checkConfig();
         const base = this.config.apiBasePath ?? '/api';
         const ns = module.namespace;

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

@@ -0,0 +1,20 @@
+import { ApiModule } from './api-module.js';
+import type { ApiRequest } from './api-server-base.js';
+import type { AuthTokenMetadata, AuthTokenPair } from './auth-storage.js';
+export interface AuthProviderModule<UserRow = unknown> {
+    readonly moduleType: 'auth';
+    readonly namespace: string;
+    issueTokens(apiReq: ApiRequest, user: UserRow, metadata?: AuthTokenMetadata & {
+        expires?: Date;
+    }): Promise<AuthTokenPair>;
+}
+export declare abstract class BaseAuthModule<UserRow = unknown> extends ApiModule<any> implements AuthProviderModule<UserRow> {
+    readonly moduleType: "auth";
+    protected constructor(opts: {
+        namespace: string;
+    });
+    abstract issueTokens(apiReq: ApiRequest, user: UserRow, metadata?: AuthTokenMetadata & {
+        expires?: Date;
+    }): Promise<AuthTokenPair>;
+}
+export declare const nullAuthModule: AuthProviderModule<unknown>;

package/dist/esm/auth-module.js

@@ -0,0 +1,21 @@
+import { ApiModule } from './api-module.js';
+// Handy base that you can extend when wiring a real auth module. Subclasses
+// must supply a namespace via the constructor and implement token issuance.
+export class BaseAuthModule extends ApiModule {
+    constructor(opts) {
+        super(opts);
+        this.moduleType = 'auth';
+    }
+}
+class NullAuthModule extends BaseAuthModule {
+    constructor() {
+        super({ namespace: '__null__' });
+    }
+    async issueTokens(apiReq, user, metadata) {
+        void apiReq;
+        void user;
+        void metadata;
+        throw new Error('Auth module not configured. Inject a real auth module before issuing tokens.');
+    }
+}
+export const nullAuthModule = new NullAuthModule();

package/dist/esm/auth-storage.d.ts

@@ -0,0 +1,114 @@
+export type AuthIdentifier = string | number;
+export interface AuthTokenMetadata {
+    clientId?: string;
+    domain?: string;
+    fingerprint?: string;
+    label?: string;
+    scope?: string | string[];
+}
+export interface AuthTokenData extends AuthTokenMetadata {
+    access: string;
+    expires?: Date;
+    refresh: string;
+    userId: AuthIdentifier;
+}
+export interface AuthTokenQuery extends AuthTokenMetadata {
+    accessToken?: string;
+    refreshToken?: string;
+    userId?: AuthIdentifier;
+}
+export interface AuthTokenPair {
+    accessToken: string;
+    refreshToken: string;
+}
+export interface AuthTokenPayload extends AuthTokenMetadata {
+    exp?: number;
+    iat?: number;
+    uid: AuthIdentifier;
+}
+export interface PasskeyChallengeParams extends AuthTokenMetadata {
+    action: 'register' | 'authenticate';
+    login?: string;
+    userAgent?: string;
+    userId?: AuthIdentifier;
+}
+export interface PasskeyChallenge extends Record<string, unknown> {
+    challenge: string;
+    expiresAt?: string | number | Date;
+    userId?: AuthIdentifier;
+}
+export interface PasskeyVerificationParams extends AuthTokenMetadata {
+    expectedChallenge: string;
+    login?: string;
+    response: Record<string, unknown>;
+    userId?: AuthIdentifier;
+}
+export interface PasskeyVerificationResult extends Record<string, unknown> {
+    login?: string;
+    tokens?: AuthTokenPair;
+    userId?: AuthIdentifier;
+    verified: boolean;
+}
+export interface OAuthClient {
+    clientId: string;
+    clientSecret: string;
+    firstParty?: boolean;
+    metadata?: Record<string, unknown>;
+    name?: string;
+    redirectUris: string[];
+    scope?: string[];
+}
+export interface AuthCodeData {
+    code: string;
+    clientId: string;
+    codeChallenge?: string;
+    codeChallengeMethod?: 'plain' | 'S256';
+    expiresAt: Date;
+    metadata?: Record<string, unknown>;
+    redirectUri: string;
+    scope: string[];
+    userId: AuthIdentifier;
+}
+export type AuthCodeRequest = Omit<AuthCodeData, 'code' | 'expiresAt'> & {
+    code?: string;
+    expiresInSeconds?: number;
+};
+export interface AuthStorage<UserRow, SafeUser> {
+    getUser(identifier: AuthIdentifier): Promise<UserRow | null>;
+    getUserPasswordHash(user: UserRow): string;
+    getUserId(user: UserRow): AuthIdentifier;
+    filterUser(user: UserRow): SafeUser;
+    verifyPassword(password: string, hash: string): Promise<boolean>;
+    storeToken(data: AuthTokenData): Promise<void>;
+    getToken(query: AuthTokenQuery): Promise<AuthTokenData | null>;
+    deleteToken(query: AuthTokenQuery): Promise<number>;
+    updateToken?(updates: Partial<AuthTokenData> & {
+        refreshToken: string;
+    }): Promise<boolean>;
+    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>;
+}
+export declare class BaseAuthStorage<UserRow = unknown, SafeUser = unknown> implements AuthStorage<UserRow, SafeUser> {
+    getUser(identifier: AuthIdentifier): Promise<UserRow | null>;
+    getUserPasswordHash(user: UserRow): string;
+    getUserId(user: UserRow): AuthIdentifier;
+    filterUser(user: UserRow): SafeUser;
+    verifyPassword(password: string, hash: string): Promise<boolean>;
+    storeToken(data: AuthTokenData): Promise<void>;
+    getToken(query: AuthTokenQuery): Promise<AuthTokenData | null>;
+    deleteToken(query: AuthTokenQuery): Promise<number>;
+    updateToken(updates: Partial<AuthTokenData> & {
+        refreshToken: string;
+    }): Promise<boolean>;
+    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>;
+}
+export declare const nullAuthStorage: AuthStorage<unknown, unknown>;

package/dist/esm/auth-storage.js

@@ -0,0 +1,83 @@
+// Numeric database id or lookup string such as username/email.
+// Handy base you can extend when wiring a real storage adapter. Every method
+// throws by default so unimplemented hooks fail loudly.
+export class BaseAuthStorage {
+    // Override to load a user record by identifier
+    async getUser(identifier) {
+        void identifier;
+        return null;
+    }
+    // Override to return the stored password hash for the user
+    getUserPasswordHash(user) {
+        void user;
+        throw new Error('Auth storage not configured');
+    }
+    // Override to expose the canonical user identifier
+    getUserId(user) {
+        void user;
+        throw new Error('Auth storage not configured');
+    }
+    // Override to strip sensitive fields from the user record
+    filterUser(user) {
+        return user;
+    }
+    // Override to validate a raw password against the stored hash
+    async verifyPassword(password, hash) {
+        void password;
+        void hash;
+        throw new Error('Auth storage not configured');
+    }
+    // Override to persist newly issued tokens
+    async storeToken(data) {
+        void data;
+        throw new Error('Auth storage not configured');
+    }
+    // Override to look up a stored token by query
+    async getToken(query) {
+        void query;
+        return null;
+    }
+    // Override to remove stored tokens that match the query
+    async deleteToken(query) {
+        void query;
+        return 0;
+    }
+    // Override to update metadata for an existing refresh token
+    async updateToken(updates) {
+        void updates;
+        return false;
+    }
+    // Override to create a new passkey challenge record
+    async createPasskeyChallenge(params) {
+        void params;
+        throw new Error('Auth storage not configured');
+    }
+    // Override to verify an incoming WebAuthn response
+    async verifyPasskeyResponse(params) {
+        void params;
+        throw new Error('Auth storage not configured');
+    }
+    // Override to fetch an OAuth client by identifier
+    async getClient(clientId) {
+        void clientId;
+        return null;
+    }
+    // Override to compare a provided client secret against storage
+    async verifyClientSecret(client, clientSecret) {
+        void client;
+        void clientSecret;
+        throw new Error('Auth storage not configured');
+    }
+    // Override to create a new authorization code entry
+    async createAuthCode(request) {
+        void request;
+        throw new Error('Auth storage not configured');
+    }
+    // Override to consume and invalidate an authorization code
+    async consumeAuthCode(code, clientId) {
+        void code;
+        void clientId;
+        return null;
+    }
+}
+export const nullAuthStorage = new BaseAuthStorage();

package/dist/esm/index.d.ts

@@ -1,3 +1,8 @@
 export { default as ApiServer } from './api-server-base.js';
-export { ApiModule, ApiError } from './api-server-base.js';
+export { ApiError } from './api-server-base.js';
+export { ApiModule } from './api-module.js';
 export type { ApiErrorParams, ApiHandler, ApiKey, ApiServerConf, ApiRequest, ApiRoute, ApiAuthType, ApiAuthClass, ApiTokenData, RequestWithStuff } from './api-server-base.js';
+export type { AuthIdentifier, AuthTokenMetadata, AuthTokenData, AuthTokenQuery, AuthTokenPair, AuthTokenPayload, PasskeyChallengeParams, PasskeyChallenge, PasskeyVerificationParams, PasskeyVerificationResult, OAuthClient, AuthCodeData, AuthCodeRequest, AuthStorage } from './auth-storage.js';
+export type { AuthProviderModule } from './auth-module.js';
+export { nullAuthStorage, BaseAuthStorage } from './auth-storage.js';
+export { nullAuthModule, BaseAuthModule } from './auth-module.js';

package/dist/esm/index.js

@@ -1,2 +1,5 @@
 export { default as ApiServer } from './api-server-base.js';
-export { ApiModule, ApiError } from './api-server-base.js';
+export { ApiError } from './api-server-base.js';
+export { ApiModule } from './api-module.js';
+export { nullAuthStorage, BaseAuthStorage } from './auth-storage.js';
+export { nullAuthModule, BaseAuthModule } from './auth-module.js';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@technomoron/api-server-base",
-	"version": "1.0.43",
+	"version": "1.1.1",
 	"description": "Api Server Skeleton / Base Class",
 	"type": "module",
 	"main": "./dist/cjs/index.cjs",