@technomoron/api-server-base 1.1.12 → 2.0.0-beta.1

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

@@ -10,13 +10,34 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ApiServer = exports.ApiError = exports.ApiModule = void 0;
+const node_crypto_1 = require("node:crypto");
 const cookie_parser_1 = __importDefault(require("cookie-parser"));
 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");
+const module_js_1 = require("./auth-api/module.js");
+const storage_js_1 = require("./auth-api/storage.js");
+const base_js_1 = require("./token/base.js");
+class JwtHelperStore extends base_js_1.TokenStore {
+    async save() {
+        throw new Error('Token store is not configured');
+    }
+    async get() {
+        throw new Error('Token store is not configured');
+    }
+    async delete() {
+        throw new Error('Token store is not configured');
+    }
+    async update() {
+        throw new Error('Token store is not configured');
+    }
+    async list() {
+        return [];
+    }
+    async close() {
+        return;
+    }
+}
 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') {
@@ -330,23 +351,45 @@ function fillConfig(config) {
         authApi: config.authApi ?? false,
         devMode: config.devMode ?? false,
         hydrateGetBody: config.hydrateGetBody ?? true,
-        validateTokens: config.validateTokens ?? false
+        validateTokens: config.validateTokens ?? false,
+        apiVersion: config.apiVersion ?? '',
+        minClientVersion: config.minClientVersion ?? '',
+        tokenStore: config.tokenStore,
+        authStores: config.authStores
     };
 }
 class ApiServer {
     constructor(config = {}) {
         this.currReq = null;
         this.apiNotFoundHandler = null;
+        this.tokenStoreAdapter = null;
+        this.userStoreAdapter = null;
+        this.passkeyServiceAdapter = null;
+        this.oauthStoreAdapter = null;
+        this.canImpersonateAdapter = null;
         this.config = fillConfig(config);
         this.apiBasePath = this.normalizeApiBasePath(this.config.apiBasePath);
-        this.storageAdapter = auth_storage_js_1.nullAuthStorage;
-        this.moduleAdapter = auth_module_js_1.nullAuthModule;
+        this.startedAt = Date.now();
+        this.storageAdapter = storage_js_1.nullAuthStorage;
+        this.moduleAdapter = module_js_1.nullAuthModule;
+        this.jwtHelper = new JwtHelperStore();
+        this.tokenStoreAdapter = this.config.tokenStore ?? null;
+        if (this.config.authStores) {
+            const { userStore, tokenStore, passkeyService, oauthStore, canImpersonate } = this.config.authStores;
+            this.userStoreAdapter = userStore;
+            this.tokenStoreAdapter = tokenStore;
+            this.passkeyServiceAdapter = passkeyService ?? null;
+            this.oauthStoreAdapter = oauthStore ?? null;
+            this.canImpersonateAdapter = canImpersonate ?? null;
+            this.storageAdapter = this;
+        }
         this.app = (0, express_1.default)();
         if (config.uploadPath) {
             const upload = (0, multer_1.default)({ dest: config.uploadPath });
             this.app.use(upload.any());
         }
         this.middlewares();
+        this.installPingHandler();
         // addSwaggerUi(this.app);
         this.installApiNotFoundHandler();
     }
@@ -376,72 +419,143 @@ class ApiServer {
     getAuthModule() {
         return this.moduleAdapter;
     }
-    jwtSign(payload, secret, expiresInSeconds, options) {
-        options || (options = {});
-        const opts = { ...options, expiresIn: expiresInSeconds };
-        try {
-            const token = jsonwebtoken_1.default.sign(payload, secret, opts);
-            return {
-                success: true,
-                token
-            };
+    setTokenStore(store) {
+        this.tokenStoreAdapter = store;
+        // If using direct stores, expose self as the auth storage.
+        if (this.userStoreAdapter) {
+            this.storageAdapter = this;
         }
-        catch (error) {
-            return {
-                success: false,
-                error: error instanceof Error ? error.message : String(error)
-            };
+        return this;
+    }
+    getTokenStore() {
+        return this.tokenStoreAdapter;
+    }
+    ensureUserStore() {
+        if (!this.userStoreAdapter) {
+            throw new Error('User store is not configured');
         }
+        return this.userStoreAdapter;
     }
-    jwtVerify(token, secret, options) {
-        options || (options = {});
-        try {
-            const data = jsonwebtoken_1.default.verify(token, secret, options);
-            return {
-                success: true,
-                data
-            };
+    ensureTokenStore() {
+        if (!this.tokenStoreAdapter) {
+            throw new Error('Token store is not configured');
         }
-        catch (error) {
-            if (error instanceof jsonwebtoken_1.default.TokenExpiredError) {
-                return {
-                    success: false,
-                    expired: true,
-                    error: 'Token expired'
-                };
-            }
-            else {
-                return {
-                    success: false,
-                    expired: false,
-                    error: error instanceof Error ? error.message : String(error)
-                };
-            }
+        return this.tokenStoreAdapter;
+    }
+    ensurePasskeyService() {
+        if (!this.passkeyServiceAdapter) {
+            throw new Error('Passkey service is not configured');
         }
+        return this.passkeyServiceAdapter;
     }
-    jwtDecode(token, options) {
-        options || (options = {});
-        try {
-            const data = jsonwebtoken_1.default.decode(token, options);
-            // jwt.decode returns null for invalid tokens rather than throwing
-            if (data === null) {
-                return {
-                    success: false,
-                    error: 'Invalid token format'
-                };
-            }
-            return {
-                success: true,
-                data
-            };
+    ensureOAuthStore() {
+        if (!this.oauthStoreAdapter) {
+            throw new Error('OAuth store is not configured');
         }
-        catch (error) {
-            // jwt.decode rarely throws, but might for severely malformed tokens
-            return {
-                success: false,
-                error: error instanceof Error ? error.message : String(error)
-            };
+        return this.oauthStoreAdapter;
+    }
+    // AuthStorage-compatible helpers (used by AuthModule)
+    async getUser(identifier) {
+        return this.userStoreAdapter ? this.userStoreAdapter.findUser(identifier) : null;
+    }
+    getUserPasswordHash(user) {
+        return this.ensureUserStore().getPasswordHash(user) ?? '';
+    }
+    getUserId(user) {
+        return this.ensureUserStore().getUserId(user);
+    }
+    filterUser(user) {
+        return this.ensureUserStore().toPublic(user);
+    }
+    async verifyPassword(password, hash) {
+        return this.ensureUserStore().verifyPassword(password, hash);
+    }
+    async storeToken(data) {
+        if (this.tokenStoreAdapter) {
+            return this.tokenStoreAdapter.save(data);
+        }
+        if (typeof this.storageAdapter.storeToken === 'function') {
+            return this.storageAdapter.storeToken(data);
+        }
+        throw new Error('Token store is not configured');
+    }
+    async getToken(query, opts) {
+        const normalized = {
+            ...query,
+            userId: query.userId !== undefined && query.userId !== null ? String(query.userId) : undefined,
+            ruid: query.ruid !== undefined && query.ruid !== null ? String(query.ruid) : undefined
+        };
+        if (this.tokenStoreAdapter) {
+            return this.tokenStoreAdapter.get(normalized, opts);
+        }
+        if (typeof this.storageAdapter.getToken === 'function') {
+            return this.storageAdapter.getToken(normalized, opts);
+        }
+        return null;
+    }
+    async deleteToken(query) {
+        const normalized = {
+            ...query,
+            userId: query.userId !== undefined && query.userId !== null ? String(query.userId) : undefined,
+            ruid: query.ruid !== undefined && query.ruid !== null ? String(query.ruid) : undefined
+        };
+        if (this.tokenStoreAdapter) {
+            return this.tokenStoreAdapter.delete(normalized);
+        }
+        if (typeof this.storageAdapter.deleteToken === 'function') {
+            return this.storageAdapter.deleteToken(normalized);
+        }
+        return 0;
+    }
+    async createPasskeyChallenge(params) {
+        return this.ensurePasskeyService().createChallenge(params);
+    }
+    async verifyPasskeyResponse(params) {
+        return this.ensurePasskeyService().verifyResponse(params);
+    }
+    async getClient(clientId) {
+        return this.oauthStoreAdapter ? this.oauthStoreAdapter.getClient(clientId) : null;
+    }
+    async verifyClientSecret(client, clientSecret) {
+        return this.ensureOAuthStore().verifyClientSecret(client.clientId, clientSecret);
+    }
+    async createAuthCode(request) {
+        const expiresAt = new Date(Date.now() + (request.expiresInSeconds ?? 300) * 1000);
+        const code = request.code ?? (0, node_crypto_1.randomUUID)();
+        await this.ensureOAuthStore().createAuthCode({ ...request, code, expiresAt });
+        return {
+            code,
+            clientId: request.clientId,
+            userId: request.userId,
+            redirectUri: request.redirectUri,
+            scope: request.scope ?? [],
+            codeChallenge: request.codeChallenge,
+            codeChallengeMethod: request.codeChallengeMethod,
+            expiresAt,
+            metadata: request.metadata
+        };
+    }
+    async consumeAuthCode(code, clientId) {
+        const consumed = await this.ensureOAuthStore().consumeAuthCode(code);
+        if (!consumed || consumed.clientId !== clientId) {
+            return null;
+        }
+        return consumed;
+    }
+    async canImpersonate(params) {
+        if (this.canImpersonateAdapter) {
+            return !!(await this.canImpersonateAdapter(params));
         }
+        return params.realUserId === params.effectiveUserId;
+    }
+    jwtSign(payload, secret, expiresInSeconds, options) {
+        return (this.tokenStoreAdapter ?? this.jwtHelper).jwtSign(payload, secret, expiresInSeconds, options);
+    }
+    jwtVerify(token, secret, options) {
+        return (this.tokenStoreAdapter ?? this.jwtHelper).jwtVerify(token, secret, options);
+    }
+    jwtDecode(token, options) {
+        return (this.tokenStoreAdapter ?? this.jwtHelper).jwtDecode(token, options);
     }
     async getApiKey(token) {
         void token;
@@ -459,16 +573,13 @@ class ApiServer {
         return this.storageAdapter.verifyPassword(params.password, hash);
     }
     async updateToken(updates) {
-        if (typeof this.storageAdapter.updateToken !== 'function') {
-            return false;
+        if (this.tokenStoreAdapter) {
+            return this.tokenStoreAdapter.update(updates);
         }
-        return this.storageAdapter.updateToken({
-            refreshToken: updates.refreshToken,
-            access: updates.accessToken,
-            expires: updates.expires,
-            clientId: updates.clientId,
-            scope: updates.scope
-        });
+        if (typeof this.storageAdapter.updateToken === 'function') {
+            return this.storageAdapter.updateToken(updates);
+        }
+        return false;
     }
     guessExceptionText(error, defMsg = 'Unkown Error') {
         return guess_exception_text(error, defMsg);
@@ -497,6 +608,20 @@ class ApiServer {
         };
         this.app.use((0, cors_1.default)(corsOptions));
     }
+    installPingHandler() {
+        const path = `${this.apiBasePath}/v1/ping`;
+        this.app.get(path, (_req, res) => {
+            const payload = {
+                status: 'ok',
+                apiVersion: this.config.apiVersion ?? '',
+                minClientVersion: this.config.minClientVersion ?? '',
+                uptimeSec: process.uptime(),
+                startedAt: this.startedAt,
+                timestamp: new Date().toISOString()
+            };
+            res.status(200).json({ code: 200, message: 'Success', data: payload });
+        });
+    }
     normalizeApiBasePath(path) {
         if (!path || typeof path !== 'string') {
             return '/api';
@@ -668,7 +793,7 @@ class ApiServer {
         return this.config.validateTokens || authType === 'strict';
     }
     async assertStoredAccessToken(apiReq, token, tokenData) {
-        const userId = this.extractTokenUserId(tokenData);
+        const userId = String(this.extractTokenUserId(tokenData));
         const stored = await this.storageAdapter.getToken({
             accessToken: token,
             userId

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

@@ -5,48 +5,39 @@
  * LICENSE file in the root directory of this source tree.
  */
 import { Application, Request, Response } from 'express';
-import jwt, { JwtPayload, SignOptions, VerifyOptions } from 'jsonwebtoken';
 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 type { AuthProviderModule } from './auth-module.js';
-import type { AuthStorage, AuthIdentifier, AuthTokenData, AuthTokenMetadata } from './auth-storage.js';
+import type { AuthProviderModule } from './auth-api/module.js';
+import type { AuthStorage, 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 { Token } from './token/types.js';
+import type { UserStore } from './user/base.js';
+import type { JwtPayload, SignOptions, VerifyOptions } from 'jsonwebtoken';
 export type { Application, Request, Response, NextFunction, Router } from 'express';
 export type { Multer } from 'multer';
 export type { JwtPayload, SignOptions, VerifyOptions } from 'jsonwebtoken';
-export interface RequestWithStuff extends Request {
+export interface ExtendedReq extends Request {
     file?: Express.Multer.File;
     files?: Express.Multer.File[] | {
         [fieldname: string]: Express.Multer.File[];
     };
 }
-interface JwtSignResult {
-    success: boolean;
-    token?: string;
-    error?: string;
-}
-interface JwtVerifyResult<T> {
-    success: boolean;
-    data?: T;
-    expired?: boolean;
-    error?: string;
-}
-interface JwtDecodeResult<T> {
-    success: boolean;
-    data?: T;
-    error?: string;
-}
-export interface ApiTokenData extends JwtPayload, AuthTokenMetadata {
+export interface ApiTokenData extends JwtPayload, Partial<Token> {
     uid: unknown;
     iat?: number;
     exp?: number;
 }
 export interface ApiRequest {
     server: any;
-    req: RequestWithStuff;
+    req: ExtendedReq;
     res: Response;
     tokenData?: ApiTokenData | null;
     token?: string;
-    authToken?: AuthTokenData | null;
+    authToken?: Token | null;
     apiKey?: ApiKey | null;
     clientInfo?: ClientInfo;
     realUid?: AuthIdentifier | null;
@@ -66,6 +57,16 @@ export interface ClientInfo extends ClientAgentProfile {
     ip: string | null;
     ipchain: string[];
 }
+export interface ApiServerAuthStores {
+    userStore: UserStore<any, any>;
+    tokenStore: TokenStore;
+    passkeyService?: PasskeyService;
+    oauthStore?: OAuthStore;
+    canImpersonate?: (params: {
+        realUserId: AuthIdentifier;
+        effectiveUserId: AuthIdentifier;
+    }) => boolean | Promise<boolean>;
+}
 export { ApiModule } from './api-module.js';
 export type { ApiHandler, ApiAuthType, ApiAuthClass, ApiRoute, ApiKey } from './api-module.js';
 export interface ApiErrorParams {
@@ -100,15 +101,26 @@ export interface ApiServerConf {
     devMode: boolean;
     hydrateGetBody: boolean;
     validateTokens: boolean;
+    apiVersion: string;
+    minClientVersion: string;
+    tokenStore?: TokenStore;
+    authStores?: ApiServerAuthStores;
 }
 export declare class ApiServer {
     app: Application;
     currReq: ApiRequest | null;
     readonly config: ApiServerConf;
+    readonly startedAt: number;
     private readonly apiBasePath;
     private storageAdapter;
     private moduleAdapter;
     private apiNotFoundHandler;
+    private tokenStoreAdapter;
+    private userStoreAdapter;
+    private passkeyServiceAdapter;
+    private oauthStoreAdapter;
+    private canImpersonateAdapter;
+    private readonly jwtHelper;
     constructor(config?: Partial<ApiServerConf>);
     authStorage<UserRow, SafeUser>(storage: AuthStorage<UserRow, SafeUser>): this;
     /**
@@ -122,24 +134,53 @@ export declare class ApiServer {
     useAuthModule<UserRow>(module: AuthProviderModule<UserRow>): this;
     getAuthStorage(): AuthStorage<any, any>;
     getAuthModule(): AuthProviderModule<any>;
+    setTokenStore(store: TokenStore): this;
+    getTokenStore(): TokenStore | null;
+    private ensureUserStore;
+    private ensureTokenStore;
+    private ensurePasskeyService;
+    private ensureOAuthStore;
+    getUser(identifier: AuthIdentifier): Promise<any | null>;
+    getUserPasswordHash(user: any): string;
+    getUserId(user: any): AuthIdentifier;
+    filterUser(user: any): any;
+    verifyPassword(password: string, hash: string): Promise<boolean>;
+    storeToken(data: Token): Promise<void>;
+    getToken(query: Partial<Token> & {
+        userId?: AuthIdentifier;
+        ruid?: AuthIdentifier;
+    }, opts?: {
+        includeExpired?: boolean;
+    }): Promise<Token | null>;
+    deleteToken(query: Partial<Token> & {
+        userId?: AuthIdentifier;
+        ruid?: AuthIdentifier;
+    }): Promise<number>;
+    createPasskeyChallenge(params: PasskeyChallengeParams): Promise<PasskeyChallenge>;
+    verifyPasskeyResponse(params: PasskeyVerificationParams): Promise<PasskeyVerificationResult>;
+    getClient(clientId: string): Promise<OAuthClient | null>;
+    verifyClientSecret(client: OAuthClient, clientSecret: string | null): Promise<boolean>;
+    createAuthCode(request: AuthCodeRequest): Promise<AuthCodeData>;
+    consumeAuthCode(code: string, clientId: string): Promise<AuthCodeData | null>;
+    canImpersonate(params: {
+        realUserId: AuthIdentifier;
+        effectiveUserId: AuthIdentifier;
+    }): Promise<boolean>;
     jwtSign(payload: 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>;
+    jwtDecode<T>(token: string, options?: import('jsonwebtoken').DecodeOptions): JwtDecodeResult<T>;
     getApiKey<T = ApiKey>(token: string): Promise<T | null>;
     authenticateUser(params: {
         login: string;
         password: string;
     }): Promise<boolean>;
-    updateToken(updates: {
-        accessToken: string;
+    updateToken(updates: Partial<Token> & {
         refreshToken: string;
-        expires?: Date;
-        clientId?: string;
-        scope?: string[];
     }): Promise<boolean>;
     guessExceptionText(error: any, defMsg?: string): string;
     protected authorize(apiReq: ApiRequest, requiredClass: ApiAuthClass): Promise<void>;
     private middlewares;
+    private installPingHandler;
     private normalizeApiBasePath;
     private installApiNotFoundHandler;
     private ensureApiNotFoundOrdering;

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

@@ -0,0 +1,96 @@
+import { type ApiRequest, type ApiRoute, type ApiServer } from '../api-server-base.js';
+import { BaseAuthModule, type AuthProviderModule } from './module.js';
+import type { AuthIdentifier, AuthStorage } from './types.js';
+import type { OAuthCallbackParams, OAuthCallbackResult, OAuthStartParams, OAuthStartResult } from '../oauth/types.js';
+import type { TokenPair, Token } from '../token/types.js';
+interface CanImpersonateContext<UserEntity> {
+    apiReq: ApiRequest;
+    realUser: UserEntity;
+    realUserId: AuthIdentifier;
+    targetUser: UserEntity;
+    effectiveUserId: AuthIdentifier;
+}
+interface AuthModuleOptions<UserEntity> {
+    namespace?: string;
+    defaultDomain?: string;
+    canImpersonate?: (context: CanImpersonateContext<UserEntity>) => Promise<boolean> | boolean;
+}
+type TokenMetadata = Partial<Token> & {
+    sessionCookie?: boolean;
+};
+interface TokenIssueOptions extends TokenMetadata {
+    expires?: Date;
+    sessionCookie?: boolean;
+}
+interface NormalizedTokenMetadata extends TokenMetadata {
+    domain: string;
+    fingerprint: string;
+    label: string;
+    browser: string;
+    device: string;
+    ip: string;
+    os: string;
+}
+type TokenClaims = TokenMetadata & {
+    uid: string;
+    exp?: number;
+    iat?: number;
+};
+type AuthCapableServer<PublicUser> = ApiServer & {
+    initiateOAuth?: (params: OAuthStartParams) => Promise<OAuthStartResult>;
+    completeOAuth?: (params: OAuthCallbackParams) => Promise<OAuthCallbackResult<PublicUser>>;
+};
+export default class AuthModule<UserEntity, PublicUser> extends BaseAuthModule<UserEntity> implements AuthProviderModule<UserEntity> {
+    static defaultNamespace: string;
+    server: AuthCapableServer<PublicUser>;
+    private readonly defaultDomain?;
+    private readonly canImpersonateHook?;
+    constructor(options?: AuthModuleOptions<UserEntity>);
+    protected get storage(): AuthStorage<UserEntity, PublicUser>;
+    protected canImpersonate(apiReq: ApiRequest, realUser: UserEntity, targetUser: UserEntity): Promise<boolean>;
+    protected ensureImpersonationAllowed(apiReq: ApiRequest, realUser: UserEntity, targetUser: UserEntity): Promise<void>;
+    protected buildTokenPayload(user: UserEntity, metadata?: TokenMetadata): TokenClaims;
+    protected buildTokenMetadata(metadata?: TokenMetadata): NormalizedTokenMetadata;
+    protected enrichTokenMetadata(apiReq: ApiRequest, metadata?: TokenMetadata): TokenMetadata;
+    private sessionRefreshTtlSeconds;
+    private normalizeRefreshTtlSeconds;
+    private resolveSessionPreferences;
+    private mergeSessionPreferences;
+    private sessionPrefsFromRecord;
+    private cookieOptions;
+    private setJwtCookies;
+    issueTokens(apiReq: ApiRequest, user: UserEntity, metadata?: TokenIssueOptions): Promise<TokenPair>;
+    private assertAuthReady;
+    private parseLoginBody;
+    private parseImpersonationRequest;
+    private resolveImpersonationIdentifier;
+    private buildImpersonationMetadata;
+    private getUserOrThrow;
+    private getRealUserIdentifier;
+    private resolveActorContext;
+    private extractRefreshToken;
+    private normalizeScope;
+    private postLogin;
+    private postRefresh;
+    private postLogout;
+    private postWhoAmI;
+    private postPasskeyChallenge;
+    private postPasskeyVerify;
+    private postImpersonation;
+    private deleteImpersonation;
+    private getUserFromPasskey;
+    private postOAuthStart;
+    private postOAuthCallback;
+    private postOAuthAuthorize;
+    private postOAuthToken;
+    private handleAuthorizationCodeGrant;
+    private handleRefreshTokenGrant;
+    private clearOAuthCookies;
+    private buildTokenResponse;
+    private resolveScope;
+    private resolveClientAuthentication;
+    private assertRedirectUriAllowed;
+    private resolveUserForOAuth;
+    defineRoutes(): ApiRoute[];
+}
+export {};