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

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

@@ -10,7 +10,7 @@ import cors from 'cors';
 import express from 'express';
 import multer from 'multer';
 import { nullAuthModule } from './auth-api/module.js';
-import { nullAuthStorage } from './auth-api/storage.js';
+import { nullAuthAdapter } from './auth-api/storage.js';
 import { TokenStore } from './token/base.js';
 class JwtHelperStore extends TokenStore {
     async save() {
@@ -344,6 +344,7 @@ function fillConfig(config) {
         devMode: config.devMode ?? false,
         hydrateGetBody: config.hydrateGetBody ?? true,
         validateTokens: config.validateTokens ?? false,
+        refreshMaybe: config.refreshMaybe ?? false,
         apiVersion: config.apiVersion ?? '',
         minClientVersion: config.minClientVersion ?? '',
         tokenStore: config.tokenStore,
@@ -362,7 +363,7 @@ export class ApiServer {
         this.config = fillConfig(config);
         this.apiBasePath = this.normalizeApiBasePath(this.config.apiBasePath);
         this.startedAt = Date.now();
-        this.storageAdapter = nullAuthStorage;
+        this.storageAdapter = nullAuthAdapter;
         this.moduleAdapter = nullAuthModule;
         this.jwtHelper = new JwtHelperStore();
         this.tokenStoreAdapter = this.config.tokenStore ?? null;
@@ -440,13 +441,19 @@ export class ApiServer {
         }
         return this.passkeyServiceAdapter;
     }
+    async listUserCredentials(userId) {
+        return this.ensurePasskeyService().listUserCredentials(userId);
+    }
+    async deletePasskeyCredential(credentialId) {
+        return this.ensurePasskeyService().deleteCredential(credentialId);
+    }
     ensureOAuthStore() {
         if (!this.oauthStoreAdapter) {
             throw new Error('OAuth store is not configured');
         }
         return this.oauthStoreAdapter;
     }
-    // AuthStorage-compatible helpers (used by AuthModule)
+    // AuthAdapter-compatible helpers (used by AuthModule)
     async getUser(identifier) {
         return this.userStoreAdapter ? this.userStoreAdapter.findUser(identifier) : null;
     }
@@ -604,6 +611,7 @@ export class ApiServer {
         const path = `${this.apiBasePath}/v1/ping`;
         this.app.get(path, (_req, res) => {
             const payload = {
+                success: true,
                 status: 'ok',
                 apiVersion: this.config.apiVersion ?? '',
                 minClientVersion: this.config.minClientVersion ?? '',
@@ -611,7 +619,7 @@ export class ApiServer {
                 startedAt: this.startedAt,
                 timestamp: new Date().toISOString()
             };
-            res.status(200).json({ code: 200, message: 'Success', data: payload });
+            res.status(200).json({ success: true, code: 200, message: 'Success', data: payload, errors: {} });
         });
     }
     normalizeApiBasePath(path) {
@@ -634,6 +642,7 @@ export class ApiServer {
         }
         this.apiNotFoundHandler = (req, res) => {
             const payload = {
+                success: false,
                 code: 404,
                 message: this.describeMissingEndpoint(req),
                 data: null,
@@ -692,16 +701,117 @@ export class ApiServer {
     }
     async verifyJWT(token) {
         if (!this.config.accessSecret) {
-            return { tokenData: undefined, error: 'JWT authentication disabled; no jwtSecret set' };
+            return { tokenData: undefined, error: 'JWT authentication disabled; no jwtSecret set', expired: false };
         }
         const result = this.jwtVerify(token, this.config.accessSecret);
         if (!result.success) {
-            return { tokenData: undefined, error: result.error };
+            return { tokenData: undefined, error: result.error, expired: result.expired };
         }
         if (!result.data.uid) {
-            return { tokenData: undefined, error: 'Missing/bad userid in token' };
+            return { tokenData: undefined, error: 'Missing/bad userid in token', expired: false };
+        }
+        return { tokenData: result.data, error: undefined, expired: false };
+    }
+    jwtCookieOptions(apiReq) {
+        const conf = this.config;
+        const forwarded = apiReq.req.headers['x-forwarded-proto'];
+        const referer = apiReq.req.headers['origin'] ?? apiReq.req.headers['referer'];
+        const origin = typeof referer === 'string' ? referer : '';
+        const isHttps = forwarded === 'https' || apiReq.req.protocol === 'https';
+        const isLocalhost = origin.includes('localhost');
+        const options = {
+            httpOnly: true,
+            secure: true,
+            sameSite: 'strict',
+            domain: conf.cookieDomain || undefined,
+            path: '/',
+            maxAge: undefined
+        };
+        if (conf.devMode) {
+            options.secure = isHttps;
+            options.httpOnly = false;
+            options.sameSite = 'lax';
+            if (isLocalhost) {
+                options.domain = undefined;
+            }
         }
-        return { tokenData: result.data, error: undefined };
+        return options;
+    }
+    setAccessCookie(apiReq, accessToken, sessionCookie) {
+        const conf = this.config;
+        const options = this.jwtCookieOptions(apiReq);
+        const accessMaxAge = Math.max(1, conf.accessExpiry) * 1000;
+        const accessOptions = sessionCookie ? options : { ...options, maxAge: accessMaxAge };
+        apiReq.res.cookie(conf.accessCookie, accessToken, accessOptions);
+    }
+    async tryRefreshAccessToken(apiReq) {
+        const conf = this.config;
+        if (!conf.refreshSecret || !conf.accessSecret) {
+            return null;
+        }
+        const rawRefresh = apiReq.req.cookies?.[conf.refreshCookie];
+        if (typeof rawRefresh !== 'string') {
+            return null;
+        }
+        const refreshToken = rawRefresh.trim();
+        if (!refreshToken) {
+            return null;
+        }
+        const verify = this.jwtVerify(refreshToken, conf.refreshSecret);
+        if (!verify.success || !verify.data) {
+            return null;
+        }
+        let stored = null;
+        try {
+            stored = await this.storageAdapter.getToken({ refreshToken });
+        }
+        catch {
+            return null;
+        }
+        if (!stored) {
+            return null;
+        }
+        const storedUid = String(stored.userId);
+        const verifyUid = verify.data.uid === undefined || verify.data.uid === null ? null : String(verify.data.uid);
+        if (verifyUid && verifyUid !== storedUid) {
+            return null;
+        }
+        const claims = verify.data;
+        const { exp: _exp, iat: _iat, nbf: _nbf, ...payload } = claims;
+        void _exp;
+        void _iat;
+        void _nbf;
+        // Ensure we never embed token secrets into refreshed access tokens.
+        delete payload.accessToken;
+        delete payload.refreshToken;
+        delete payload.userId;
+        delete payload.expires;
+        delete payload.issuedAt;
+        delete payload.lastSeenAt;
+        delete payload.status;
+        const access = this.jwtSign(payload, conf.accessSecret, conf.accessExpiry);
+        if (!access.success || !access.token) {
+            return null;
+        }
+        const updated = await this.updateToken({
+            refreshToken,
+            accessToken: access.token,
+            lastSeenAt: new Date()
+        });
+        if (!updated) {
+            return null;
+        }
+        this.setAccessCookie(apiReq, access.token, stored.sessionCookie ?? false);
+        if (apiReq.req.cookies) {
+            apiReq.req.cookies[conf.accessCookie] = access.token;
+        }
+        const verifiedAccess = await this.verifyJWT(access.token);
+        if (!verifiedAccess.tokenData) {
+            return null;
+        }
+        const refreshedStored = { ...stored, accessToken: access.token };
+        apiReq.authToken = refreshedStored;
+        return { token: access.token, tokenData: verifiedAccess.tokenData, stored: refreshedStored };
     }
     async authenticate(apiReq, authType) {
         if (authType === 'none') {
@@ -711,6 +821,7 @@ export class ApiServer {
         let token = null;
         const authHeader = apiReq.req.headers.authorization;
         const requiresAuthToken = this.requiresAuthToken(authType);
+        const allowRefresh = requiresAuthToken || (authType === 'maybe' && this.config.refreshMaybe);
         const apiKeyAuth = await this.tryAuthenticateApiKey(apiReq, authType, authHeader);
         if (apiKeyAuth) {
             return apiKeyAuth;
@@ -719,32 +830,84 @@ export class ApiServer {
             token = authHeader.slice(7).trim();
         }
         if (!token) {
-            const access = apiReq.req.cookies?.dat;
+            const access = apiReq.req.cookies?.[this.config.accessCookie];
             if (access) {
                 token = access;
             }
         }
+        let tokenData;
+        let error;
+        let expired = false;
         if (!token || token === null) {
-            if (requiresAuthToken) {
-                throw new ApiError({ code: 401, message: 'Authorization token is required (Bearer/cookie)' });
+            if (authType === 'maybe') {
+                if (!this.config.refreshMaybe) {
+                    return null;
+                }
+                const refreshed = await this.tryRefreshAccessToken(apiReq);
+                if (!refreshed) {
+                    return null;
+                }
+                token = refreshed.token;
+                tokenData = refreshed.tokenData;
+                error = undefined;
+                expired = false;
+            }
+            else if (requiresAuthToken) {
+                const refreshed = await this.tryRefreshAccessToken(apiReq);
+                if (!refreshed) {
+                    throw new ApiError({ code: 401, message: 'Authorization token is required (Bearer/cookie)' });
+                }
+                token = refreshed.token;
+                tokenData = refreshed.tokenData;
+                error = undefined;
+                expired = false;
             }
         }
         if (!token) {
-            if (authType === 'maybe') {
-                return null;
-            }
-            else {
-                throw new ApiError({ code: 401, message: 'Unauthorized Access - requires authentication' });
+            throw new ApiError({ code: 401, message: 'Unauthorized Access - requires authentication' });
+        }
+        if (!tokenData) {
+            const verified = await this.verifyJWT(token);
+            tokenData = verified.tokenData;
+            error = verified.error;
+            expired = verified.expired ?? false;
+        }
+        if (!tokenData && allowRefresh && expired) {
+            const refreshed = await this.tryRefreshAccessToken(apiReq);
+            if (refreshed) {
+                token = refreshed.token;
+                tokenData = refreshed.tokenData;
+                error = undefined;
             }
         }
-        const { tokenData, error } = await this.verifyJWT(token);
         if (!tokenData) {
             throw new ApiError({ code: 401, message: 'Unathorized Access - ' + error });
         }
         const effectiveUserId = this.extractTokenUserId(tokenData);
         apiReq.realUid = this.resolveRealUserId(tokenData, effectiveUserId);
         if (this.shouldValidateStoredToken(authType)) {
-            await this.assertStoredAccessToken(apiReq, token, tokenData);
+            try {
+                await this.assertStoredAccessToken(apiReq, token, tokenData);
+            }
+            catch (error) {
+                if (allowRefresh &&
+                    error instanceof ApiError &&
+                    error.code === 401 &&
+                    error.message === 'Authorization token is no longer valid') {
+                    const refreshed = await this.tryRefreshAccessToken(apiReq);
+                    if (!refreshed) {
+                        throw error;
+                    }
+                    token = refreshed.token;
+                    tokenData = refreshed.tokenData;
+                    const refreshedUserId = this.extractTokenUserId(tokenData);
+                    apiReq.realUid = this.resolveRealUserId(tokenData, refreshedUserId);
+                    await this.assertStoredAccessToken(apiReq, token, tokenData);
+                }
+                else {
+                    throw error;
+                }
+            }
         }
         apiReq.token = token;
         return tokenData;
@@ -786,6 +949,9 @@ export class ApiServer {
     }
     async assertStoredAccessToken(apiReq, token, tokenData) {
         const userId = String(this.extractTokenUserId(tokenData));
+        if (apiReq.authToken && apiReq.authToken.accessToken === token && String(apiReq.authToken.userId) === userId) {
+            return;
+        }
         const stored = await this.storageAdapter.getToken({
             accessToken: token,
             userId
@@ -825,32 +991,100 @@ export class ApiServer {
         }
         return rawReal;
     }
-    handle_request(handler, auth) {
+    useExpress(pathOrHandler, ...handlers) {
+        if (typeof pathOrHandler === 'string') {
+            this.app.use(pathOrHandler, ...handlers);
+        }
+        else {
+            this.app.use(pathOrHandler, ...handlers);
+        }
+        this.ensureApiNotFoundOrdering();
+        return this;
+    }
+    createApiRequest(req, res) {
+        const apiReq = {
+            server: this,
+            req,
+            res,
+            token: '',
+            tokenData: null,
+            realUid: null,
+            getClientInfo: () => ensureClientInfo(apiReq),
+            getClientIp: () => ensureClientInfo(apiReq).ip,
+            getClientIpChain: () => ensureClientInfo(apiReq).ipchain,
+            getRealUid: () => apiReq.realUid ?? null,
+            isImpersonating: () => {
+                const realUid = apiReq.realUid;
+                const tokenUid = apiReq.tokenData?.uid;
+                if (realUid === null || realUid === undefined) {
+                    return false;
+                }
+                if (tokenUid === null || tokenUid === undefined) {
+                    return false;
+                }
+                return realUid !== tokenUid;
+            }
+        };
+        return apiReq;
+    }
+    expressAuth(auth) {
         return async (req, res, next) => {
-            void next;
-            const apiReq = {
-                server: this,
-                req,
-                res,
-                token: '',
-                tokenData: null,
-                realUid: null,
-                getClientInfo: () => ensureClientInfo(apiReq),
-                getClientIp: () => ensureClientInfo(apiReq).ip,
-                getClientIpChain: () => ensureClientInfo(apiReq).ipchain,
-                getRealUid: () => apiReq.realUid ?? null,
-                isImpersonating: () => {
-                    const realUid = apiReq.realUid;
-                    const tokenUid = apiReq.tokenData?.uid;
-                    if (realUid === null || realUid === undefined) {
-                        return false;
-                    }
-                    if (tokenUid === null || tokenUid === undefined) {
-                        return false;
-                    }
-                    return realUid !== tokenUid;
+            const apiReq = this.createApiRequest(req, res);
+            req.apiReq = apiReq;
+            res.locals.apiReq = apiReq;
+            this.currReq = apiReq;
+            try {
+                if (this.config.hydrateGetBody) {
+                    hydrateGetBody(req);
+                }
+                if (this.config.debug) {
+                    this.dumpRequest(apiReq);
                 }
+                apiReq.tokenData = await this.authenticate(apiReq, auth.type);
+                await this.authorize(apiReq, auth.req);
+                next();
+            }
+            catch (error) {
+                next(error);
+            }
+        };
+    }
+    expressErrorHandler() {
+        return (error, _req, res, next) => {
+            void _req;
+            if (res.headersSent) {
+                next(error);
+                return;
+            }
+            if (error instanceof ApiError || isApiErrorLike(error)) {
+                const apiError = error;
+                const normalizedErrors = apiError.errors && typeof apiError.errors === 'object' && !Array.isArray(apiError.errors)
+                    ? apiError.errors
+                    : {};
+                const errorPayload = {
+                    success: false,
+                    code: apiError.code,
+                    message: apiError.message,
+                    data: apiError.data ?? null,
+                    errors: normalizedErrors
+                };
+                res.status(apiError.code).json(errorPayload);
+                return;
+            }
+            const errorPayload = {
+                success: false,
+                code: 500,
+                message: this.guessExceptionText(error),
+                data: null,
+                errors: {}
             };
+            res.status(500).json(errorPayload);
+        };
+    }
+    handle_request(handler, auth) {
+        return async (req, res, next) => {
+            void next;
+            const apiReq = this.createApiRequest(req, res);
             this.currReq = apiReq;
             try {
                 if (this.config.hydrateGetBody) {
@@ -873,7 +1107,7 @@ export class ApiServer {
                     throw new ApiError({ code: 500, message: 'Handler result must start with a numeric status code' });
                 }
                 const message = typeof rawMessage === 'string' ? rawMessage : 'Success';
-                const responsePayload = { code, message, data };
+                const responsePayload = { success: true, code, message, data, errors: {} };
                 if (this.config.debug) {
                     this.dumpResponse(apiReq, responsePayload, code);
                 }
@@ -886,6 +1120,7 @@ export class ApiServer {
                         ? apiError.errors
                         : {};
                     const errorPayload = {
+                        success: false,
                         code: apiError.code,
                         message: apiError.message,
                         data: apiError.data ?? null,
@@ -898,6 +1133,7 @@ export class ApiServer {
                 }
                 else {
                     const errorPayload = {
+                        success: false,
                         code: 500,
                         message: this.guessExceptionText(error),
                         data: null,

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

@@ -1,6 +1,6 @@
 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 { AuthAdapter, AuthIdentifier } from './types.js';
 import type { OAuthCallbackParams, OAuthCallbackResult, OAuthStartParams, OAuthStartResult } from '../oauth/types.js';
 import type { TokenPair, Token } from '../token/types.js';
 interface CanImpersonateContext<UserEntity> {
@@ -46,7 +46,7 @@ export default class AuthModule<UserEntity, PublicUser> extends BaseAuthModule<U
     private readonly defaultDomain?;
     private readonly canImpersonateHook?;
     constructor(options?: AuthModuleOptions<UserEntity>);
-    protected get storage(): AuthStorage<UserEntity, PublicUser>;
+    protected get storage(): AuthAdapter<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;
@@ -57,6 +57,9 @@ export default class AuthModule<UserEntity, PublicUser> extends BaseAuthModule<U
     private resolveSessionPreferences;
     private mergeSessionPreferences;
     private sessionPrefsFromRecord;
+    private validateCredentialId;
+    private normalizeCredentialId;
+    private toIsoDate;
     private cookieOptions;
     private setJwtCookies;
     issueTokens(apiReq: ApiRequest, user: UserEntity, metadata?: TokenIssueOptions): Promise<TokenPair>;
@@ -76,6 +79,8 @@ export default class AuthModule<UserEntity, PublicUser> extends BaseAuthModule<U
     private postWhoAmI;
     private postPasskeyChallenge;
     private postPasskeyVerify;
+    private getPasskeys;
+    private deletePasskey;
     private postImpersonation;
     private deleteImpersonation;
     private getUserFromPasskey;
@@ -91,6 +96,10 @@ export default class AuthModule<UserEntity, PublicUser> extends BaseAuthModule<U
     private resolveClientAuthentication;
     private assertRedirectUriAllowed;
     private resolveUserForOAuth;
+    private hasPasskeyService;
+    private hasOAuthStore;
+    private storageImplements;
+    private storageImplementsAll;
     defineRoutes(): ApiRoute[];
 }
 export {};