@technomoron/api-server-base 1.0.43 → 1.1.0

package/README.txt

@@ -62,13 +62,18 @@ class UserModule extends ApiModule<AppServer> {
 	}
 }
 
+const yourStorageAdapter = new YourStorageAdapter();
+
 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.
 

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

@@ -15,6 +15,8 @@ const cors_1 = __importDefault(require("cors"));
 const express_1 = __importDefault(require("express"));
 const jsonwebtoken_1 = __importDefault(require("jsonwebtoken"));
 const multer_1 = __importDefault(require("multer"));
+const auth_module_js_1 = require("./auth-module.cjs");
+const auth_storage_js_1 = require("./auth-storage.cjs");
 class ApiModule {
     constructor(opts = {}) {
         this.mountpath = '';
@@ -168,6 +170,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 +180,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 };
@@ -248,36 +278,51 @@ class ApiServer {
         return null;
     }
     async getUser(uid) {
-        void uid;
-        throw new Error('getUser() not implemented');
+        return this.storageAdapter.getUser(uid);
+    }
+    getUserPasswordHash(user) {
+        return this.storageAdapter.getUserPasswordHash(user);
+    }
+    getUserId(user) {
+        return this.storageAdapter.getUserId(user);
     }
     async authenticateUser(params) {
-        void params;
-        throw new Error('authenticateUser() not implemented');
+        if (!params?.login || !params?.password) {
+            return false;
+        }
+        const user = await this.getUser(params.login);
+        if (!user) {
+            return false;
+        }
+        const hash = this.storageAdapter.getUserPasswordHash(user);
+        return this.verifyPassword(params.password, hash);
     }
-    async storeToken(params) {
-        void params;
-        throw new Error('storeToken() not implemented');
+    async storeToken(data) {
+        await this.storageAdapter.storeToken(data);
     }
-    async getToken(params) {
-        void params;
-        throw new Error('getToken() not implemented');
+    async getToken(query) {
+        return this.storageAdapter.getToken(query);
     }
-    async updateToken(params) {
-        void params;
-        throw new Error('updateToken() not implemented');
+    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
+        });
     }
-    async deleteToken(params) {
-        void params;
-        throw new Error('deleteToken() not implemented');
+    async deleteToken(query) {
+        return this.storageAdapter.deleteToken(query);
     }
     async verifyPassword(password, hash) {
-        void password;
-        void hash;
-        throw new Error('verifyPassword() not implemented');
+        return this.storageAdapter.verifyPassword(password, hash);
     }
     filterUser(fullUser) {
-        return fullUser;
+        return this.storageAdapter.filterUser(fullUser);
     }
     guessExceptionText(error, defMsg = 'Unkown Error') {
         return guess_exception_text(error, defMsg);
@@ -495,6 +540,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,8 @@
  */
 import { Application, Request, Response } from 'express';
 import jwt, { JwtPayload, SignOptions, VerifyOptions } from 'jsonwebtoken';
+import type { AuthProviderModule } from './auth-module.js';
+import type { AuthIdentifier, AuthStorage, AuthTokenData, AuthTokenQuery } 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';
@@ -104,39 +106,42 @@ 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, SafeUser>(module: AuthProviderModule<UserRow, SafeUser>): this;
+    /**
+     * @deprecated Use {@link ApiServer.authModule} instead.
+     */
+    useAuthModule<UserRow, SafeUser>(module: AuthProviderModule<UserRow, SafeUser>): this;
+    getAuthStorage(): AuthStorage<any, any>;
+    getAuthModule(): AuthProviderModule<any, 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: {
+    getUser(uid: AuthIdentifier): Promise<unknown>;
+    getUserPasswordHash(user: unknown): string;
+    getUserId(user: unknown): AuthIdentifier;
+    authenticateUser(params: {
+        login: string;
+        password: string;
+    }): Promise<boolean>;
+    storeToken(data: AuthTokenData): Promise<void>;
+    getToken(query: AuthTokenQuery): Promise<AuthTokenData | null>;
+    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>;
+    deleteToken(query: AuthTokenQuery): Promise<number>;
     verifyPassword(password: string, hash: string): Promise<boolean>;
     filterUser<T = any, U = any>(fullUser: T): U;
     guessExceptionText(error: any, defMsg?: string): string;

package/dist/cjs/auth-module.cjs

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nullAuthModule = exports.BaseAuthModule = void 0;
+// Handy base that you can extend when wiring a real auth module. Subclasses
+// must provide their namespace. Methods throw by default so unimplemented
+// hooks fail loudly.
+class BaseAuthModule {
+    constructor() {
+        this.moduleType = 'auth';
+    }
+    // Override to mint tokens for the provided user and request context
+    async issueTokens(apiReq, user, metadata) {
+        void apiReq;
+        void user;
+        void metadata;
+        throw new Error('Auth module not configured');
+    }
+}
+exports.BaseAuthModule = BaseAuthModule;
+class NullAuthModule extends BaseAuthModule {
+    constructor() {
+        super(...arguments);
+        this.namespace = '__null__';
+    }
+}
+exports.nullAuthModule = new NullAuthModule();

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

@@ -0,0 +1,17 @@
+import type { ApiRequest } from './api-server-base.js';
+import type { AuthTokenMetadata, AuthTokenPair } from './auth-storage.js';
+export interface AuthProviderModule<UserRow, SafeUser> {
+    readonly moduleType: 'auth';
+    readonly namespace: string;
+    issueTokens(apiReq: ApiRequest, user: UserRow, metadata?: AuthTokenMetadata & {
+        expires?: Date;
+    }): Promise<AuthTokenPair>;
+}
+export declare abstract class BaseAuthModule implements AuthProviderModule<unknown, unknown> {
+    readonly moduleType: "auth";
+    abstract readonly namespace: string;
+    issueTokens(apiReq: ApiRequest, user: unknown, metadata?: AuthTokenMetadata & {
+        expires?: Date;
+    }): Promise<AuthTokenPair>;
+}
+export declare const nullAuthModule: AuthProviderModule<unknown, 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,15 @@ 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.ApiError = exports.ApiModule = 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 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,7 @@
 export { default as ApiServer } from './api-server-base.js';
 export { ApiModule, ApiError } from './api-server-base.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-server-base.d.ts

@@ -6,6 +6,8 @@
  */
 import { Application, Request, Response } from 'express';
 import jwt, { JwtPayload, SignOptions, VerifyOptions } from 'jsonwebtoken';
+import type { AuthProviderModule } from './auth-module.js';
+import type { AuthIdentifier, AuthStorage, AuthTokenData, AuthTokenQuery } 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';
@@ -104,39 +106,42 @@ 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, SafeUser>(module: AuthProviderModule<UserRow, SafeUser>): this;
+    /**
+     * @deprecated Use {@link ApiServer.authModule} instead.
+     */
+    useAuthModule<UserRow, SafeUser>(module: AuthProviderModule<UserRow, SafeUser>): this;
+    getAuthStorage(): AuthStorage<any, any>;
+    getAuthModule(): AuthProviderModule<any, 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: {
+    getUser(uid: AuthIdentifier): Promise<unknown>;
+    getUserPasswordHash(user: unknown): string;
+    getUserId(user: unknown): AuthIdentifier;
+    authenticateUser(params: {
+        login: string;
+        password: string;
+    }): Promise<boolean>;
+    storeToken(data: AuthTokenData): Promise<void>;
+    getToken(query: AuthTokenQuery): Promise<AuthTokenData | null>;
+    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>;
+    deleteToken(query: AuthTokenQuery): Promise<number>;
     verifyPassword(password: string, hash: string): Promise<boolean>;
     filterUser<T = any, U = any>(fullUser: T): U;
     guessExceptionText(error: any, defMsg?: string): string;

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

@@ -9,6 +9,8 @@ import cors from 'cors';
 import express from 'express';
 import jwt from 'jsonwebtoken';
 import multer from 'multer';
+import { nullAuthModule } from './auth-module.js';
+import { nullAuthStorage } from './auth-storage.js';
 export class ApiModule {
     constructor(opts = {}) {
         this.mountpath = '';
@@ -160,6 +162,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 +172,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 };
@@ -240,36 +270,51 @@ export class ApiServer {
         return null;
     }
     async getUser(uid) {
-        void uid;
-        throw new Error('getUser() not implemented');
+        return this.storageAdapter.getUser(uid);
+    }
+    getUserPasswordHash(user) {
+        return this.storageAdapter.getUserPasswordHash(user);
+    }
+    getUserId(user) {
+        return this.storageAdapter.getUserId(user);
     }
     async authenticateUser(params) {
-        void params;
-        throw new Error('authenticateUser() not implemented');
+        if (!params?.login || !params?.password) {
+            return false;
+        }
+        const user = await this.getUser(params.login);
+        if (!user) {
+            return false;
+        }
+        const hash = this.storageAdapter.getUserPasswordHash(user);
+        return this.verifyPassword(params.password, hash);
     }
-    async storeToken(params) {
-        void params;
-        throw new Error('storeToken() not implemented');
+    async storeToken(data) {
+        await this.storageAdapter.storeToken(data);
     }
-    async getToken(params) {
-        void params;
-        throw new Error('getToken() not implemented');
+    async getToken(query) {
+        return this.storageAdapter.getToken(query);
     }
-    async updateToken(params) {
-        void params;
-        throw new Error('updateToken() not implemented');
+    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
+        });
     }
-    async deleteToken(params) {
-        void params;
-        throw new Error('deleteToken() not implemented');
+    async deleteToken(query) {
+        return this.storageAdapter.deleteToken(query);
     }
     async verifyPassword(password, hash) {
-        void password;
-        void hash;
-        throw new Error('verifyPassword() not implemented');
+        return this.storageAdapter.verifyPassword(password, hash);
     }
     filterUser(fullUser) {
-        return fullUser;
+        return this.storageAdapter.filterUser(fullUser);
     }
     guessExceptionText(error, defMsg = 'Unkown Error') {
         return guess_exception_text(error, defMsg);
@@ -487,6 +532,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,17 @@
+import type { ApiRequest } from './api-server-base.js';
+import type { AuthTokenMetadata, AuthTokenPair } from './auth-storage.js';
+export interface AuthProviderModule<UserRow, SafeUser> {
+    readonly moduleType: 'auth';
+    readonly namespace: string;
+    issueTokens(apiReq: ApiRequest, user: UserRow, metadata?: AuthTokenMetadata & {
+        expires?: Date;
+    }): Promise<AuthTokenPair>;
+}
+export declare abstract class BaseAuthModule implements AuthProviderModule<unknown, unknown> {
+    readonly moduleType: "auth";
+    abstract readonly namespace: string;
+    issueTokens(apiReq: ApiRequest, user: unknown, metadata?: AuthTokenMetadata & {
+        expires?: Date;
+    }): Promise<AuthTokenPair>;
+}
+export declare const nullAuthModule: AuthProviderModule<unknown, unknown>;

package/dist/esm/auth-module.js

@@ -0,0 +1,22 @@
+// Handy base that you can extend when wiring a real auth module. Subclasses
+// must provide their namespace. Methods throw by default so unimplemented
+// hooks fail loudly.
+export class BaseAuthModule {
+    constructor() {
+        this.moduleType = 'auth';
+    }
+    // Override to mint tokens for the provided user and request context
+    async issueTokens(apiReq, user, metadata) {
+        void apiReq;
+        void user;
+        void metadata;
+        throw new Error('Auth module not configured');
+    }
+}
+class NullAuthModule extends BaseAuthModule {
+    constructor() {
+        super(...arguments);
+        this.namespace = '__null__';
+    }
+}
+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,7 @@
 export { default as ApiServer } from './api-server-base.js';
 export { ApiModule, ApiError } from './api-server-base.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,4 @@
 export { default as ApiServer } from './api-server-base.js';
 export { ApiModule, ApiError } from './api-server-base.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.0",
 	"description": "Api Server Skeleton / Base Class",
 	"type": "module",
 	"main": "./dist/cjs/index.cjs",