@technomoron/api-server-base 1.1.13 → 2.0.0-beta.10

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

@@ -4,13 +4,34 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
+import { randomUUID } from 'node:crypto';
 import cookieParser from 'cookie-parser';
 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';
+import { nullAuthModule } from './auth-api/module.js';
+import { nullAuthAdapter } from './auth-api/storage.js';
+import { TokenStore } from './token/base.js';
+class JwtHelperStore extends 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;
+    }
+}
 export { ApiModule } from './api-module.js';
 function guess_exception_text(error, defMsg = 'Unknown Error') {
     const msg = [];
@@ -323,19 +344,38 @@ 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 ?? ''
+        minClientVersion: config.minClientVersion ?? '',
+        tokenStore: config.tokenStore,
+        authStores: config.authStores
     };
 }
 export 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.startedAt = Date.now();
-        this.storageAdapter = nullAuthStorage;
+        this.storageAdapter = nullAuthAdapter;
         this.moduleAdapter = 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 = express();
         if (config.uploadPath) {
             const upload = multer({ dest: config.uploadPath });
@@ -372,72 +412,149 @@ export class ApiServer {
     getAuthModule() {
         return this.moduleAdapter;
     }
-    jwtSign(payload, secret, expiresInSeconds, options) {
-        options || (options = {});
-        const opts = { ...options, expiresIn: expiresInSeconds };
-        try {
-            const token = jwt.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 = jwt.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 jwt.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 = jwt.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
-            };
+    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');
         }
-        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;
+    }
+    // AuthAdapter-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 ?? 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;
@@ -455,16 +572,13 @@ export 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);
@@ -585,16 +699,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 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;
         }
-        return { tokenData: result.data, error: undefined };
+        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') {
@@ -604,6 +819,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;
@@ -612,32 +828,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;
@@ -678,7 +946,10 @@ export class ApiServer {
         return this.config.validateTokens || authType === 'strict';
     }
     async assertStoredAccessToken(apiReq, token, tokenData) {
-        const userId = this.extractTokenUserId(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
@@ -718,32 +989,98 @@ 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 = {
+                    code: apiError.code,
+                    message: apiError.message,
+                    data: apiError.data ?? null,
+                    errors: normalizedErrors
+                };
+                res.status(apiError.code).json(errorPayload);
+                return;
+            }
+            const errorPayload = {
+                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) {