@technomoron/api-server-base 1.1.4 → 1.1.5

package/README.txt

@@ -7,7 +7,7 @@ Toolkit for building authenticated Express APIs in TypeScript. ApiServer wraps E
 - The server can be extended and methods related to user authentication, API keys and more can be overridden in the derived class.
 - Create API endpoints that are either public, protected or open API calls that may or may not have an authenticated session for dual behaviour.
 - Standardized request handling (POST, GET, file uploads if enabled and more).
-- Authentication system using JWT or simple API bearer keys, fully customizable by overriding class methods.
+- Authentication system using JWT or simple API bearer keys, fully customizable by overriding class methods (now exposes both the resolved API key and stored token row to handlers).
 - Unified error handling. Just throw new ApiError(...) in any API callback in order ot emit the correct API response.
 - Create structured, standardized API response as JSON data, containing typed return data, response codes and more.
 
@@ -113,6 +113,7 @@ authApi (boolean, default false) Toggle you can use when mounting auth routes.
 devMode (boolean, default false) Custom hook for development only features.
 debug (boolean, default false) When true the server logs inbound requests via dumpRequest.
 hydrateGetBody (boolean, default true) Copy query parameters into `req.body` for GET requests; set false if you prefer untouched bodies.
+validateTokens (boolean, default false) When true, every JWT-authenticated request must match a stored token row (access token + user id) before reaching your handler. API keys remain stateless either way.
 
 Tip: If you add new configuration fields in downstream projects, extend ApiServerConf and update fillConfig so defaults stay aligned.
 
@@ -120,7 +121,7 @@ Request Lifecycle
 -----------------
 1. Express middlewares (express.json, cookie-parser, optional multer) run before your handler.
 2. ApiServer wraps the route inside handle_request, setting currReq and logging when debug is enabled.
-3. authenticate enforces the ApiRoute auth type: none, maybe, or yes. Bearer tokens and the dat cookie are accepted. API key tokens prefixed with apikey- delegate to getApiKey.
+3. authenticate enforces the ApiRoute auth type: `none`, `maybe`, `yes`, `strict`, or `apikey`. Bearer JWTs and the `dat` cookie are accepted for `yes`/`strict`, while API key tokens prefixed with `apikey-` always delegate to `getApiKey`. The optional `strict` type (or server-wide `validateTokens` flag) requires the signed JWT to exist in storage; when it does, the persisted row is attached to `apiReq.authToken`. The dedicated `apikey` type simply means “an API key is required”; otherwise API keys are still accepted by `yes`/`strict` routes alongside JWTs, and `apiReq.apiKey` is populated when present.
 4. authorize runs with the requested auth class (any or admin in the base implementation). Override to connect to your role system.
 5. The handler executes and returns its tuple. Responses are normalized to { code, message, data } JSON.
 6. Errors bubble into the wrapper. ApiError instances respect the provided status codes; other exceptions result in a 500 with text derived from guessExceptionText.

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

@@ -1,6 +1,6 @@
 import type { ApiRequest } from './api-server-base.js';
 export type ApiHandler = (apiReq: ApiRequest) => Promise<[number] | [number, any] | [number, any, string]>;
-export type ApiAuthType = 'none' | 'maybe' | 'yes';
+export type ApiAuthType = 'none' | 'maybe' | 'yes' | 'strict' | 'apikey';
 export type ApiAuthClass = 'any' | 'admin';
 export interface ApiKey {
     uid: unknown;

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

@@ -328,7 +328,8 @@ function fillConfig(config) {
         refreshExpiry: config.refreshExpiry ?? 30 * 24 * 60 * 60 * 1000,
         authApi: config.authApi ?? false,
         devMode: config.devMode ?? false,
-        hydrateGetBody: config.hydrateGetBody ?? true
+        hydrateGetBody: config.hydrateGetBody ?? true,
+        validateTokens: config.validateTokens ?? false
     };
 }
 class ApiServer {
@@ -537,37 +538,23 @@ class ApiServer {
         }
         let token = null;
         const authHeader = apiReq.req.headers.authorization;
+        const requiresAuthToken = this.requiresAuthToken(authType);
+        const apiKeyAuth = await this.tryAuthenticateApiKey(apiReq, authType, authHeader);
+        if (apiKeyAuth) {
+            return apiKeyAuth;
+        }
         if (authHeader?.startsWith('Bearer ')) {
             token = authHeader.slice(7).trim();
         }
-        else if (authType === 'yes' && !authHeader) {
+        else if (requiresAuthToken && !authHeader) {
             throw new ApiError({ code: 401, message: 'Authorization header is missing or invalid' });
         }
-        if (token) {
-            const m = token.match(/^apikey-(.+)$/);
-            if (m) {
-                const key = await this.getApiKey(m[1]);
-                if (key) {
-                    apiReq.token = m[1];
-                    return {
-                        uid: key.uid,
-                        domain: '',
-                        fingerprint: '',
-                        iat: 0,
-                        exp: 0
-                    };
-                }
-                else {
-                    throw new ApiError({ code: 401, message: 'Invalid API Key' });
-                }
-            }
-        }
         if (!token || token === null) {
             const access = apiReq.req.cookies?.dat;
             if (access) {
                 token = access;
             }
-            else if (authType === 'yes') {
+            else if (requiresAuthToken) {
                 throw new ApiError({ code: 401, message: 'Authorization token is required (Bearer/cookie)' });
             }
         }
@@ -583,9 +570,61 @@ class ApiServer {
         if (!tokenData) {
             throw new ApiError({ code: 401, message: 'Unathorized Access - ' + error });
         }
+        if (this.shouldValidateStoredToken(authType)) {
+            await this.assertStoredAccessToken(apiReq, token, tokenData);
+        }
         apiReq.token = token;
         return tokenData;
     }
+    async tryAuthenticateApiKey(apiReq, authType, authHeader) {
+        if (!authHeader?.startsWith('Bearer ')) {
+            if (authType === 'apikey') {
+                throw new ApiError({ code: 401, message: 'Authorization header is missing or invalid' });
+            }
+            return null;
+        }
+        const keyToken = authHeader.slice(7).trim();
+        if (!keyToken.startsWith('apikey-')) {
+            if (authType === 'apikey') {
+                throw new ApiError({ code: 401, message: 'Invalid API Key' });
+            }
+            return null;
+        }
+        const secret = keyToken.replace(/^apikey-/, '');
+        const key = await this.getApiKey(secret);
+        if (!key) {
+            throw new ApiError({ code: 401, message: 'Invalid API Key' });
+        }
+        apiReq.token = secret;
+        apiReq.apiKey = key;
+        return {
+            uid: key.uid,
+            domain: '',
+            fingerprint: '',
+            iat: 0,
+            exp: 0
+        };
+    }
+    requiresAuthToken(authType) {
+        return authType === 'yes' || authType === 'strict';
+    }
+    shouldValidateStoredToken(authType) {
+        return this.config.validateTokens || authType === 'strict';
+    }
+    async assertStoredAccessToken(apiReq, token, tokenData) {
+        if (typeof tokenData.uid !== 'string' && typeof tokenData.uid !== 'number') {
+            throw new ApiError({ code: 401, message: 'Authorization token is malformed' });
+        }
+        const userId = tokenData.uid;
+        const stored = await this.storageAdapter.getToken({
+            accessToken: token,
+            userId
+        });
+        if (!stored) {
+            throw new ApiError({ code: 401, message: 'Authorization token is no longer valid' });
+        }
+        apiReq.authToken = stored;
+    }
     handle_request(handler, auth) {
         return async (req, res, next) => {
             void next;

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

@@ -9,7 +9,7 @@ import jwt, { JwtPayload, SignOptions, VerifyOptions } from 'jsonwebtoken';
 import { ApiModule } from './api-module.js';
 import type { ApiAuthClass, ApiKey } from './api-module.js';
 import type { AuthProviderModule } from './auth-module.js';
-import type { AuthStorage } from './auth-storage.js';
+import type { AuthStorage, AuthTokenData } 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';
@@ -46,6 +46,8 @@ export interface ApiRequest {
     res: Response;
     tokenData?: ApiTokenData | null;
     token?: string;
+    authToken?: AuthTokenData | null;
+    apiKey?: ApiKey | null;
     clientInfo?: ClientInfo;
     getClientInfo: () => ClientInfo;
     getClientIp: () => string | null;
@@ -93,6 +95,7 @@ export interface ApiServerConf {
     authApi: boolean;
     devMode: boolean;
     hydrateGetBody: boolean;
+    validateTokens: boolean;
 }
 export declare class ApiServer {
     app: Application;
@@ -134,6 +137,10 @@ export declare class ApiServer {
     start(): this;
     private verifyJWT;
     private authenticate;
+    private tryAuthenticateApiKey;
+    private requiresAuthToken;
+    private shouldValidateStoredToken;
+    private assertStoredAccessToken;
     private handle_request;
     api<T extends ApiModule<any>>(module: T): this;
     dumpRequest(apiReq: ApiRequest): void;

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

@@ -1,6 +1,6 @@
 import type { ApiRequest } from './api-server-base.js';
 export type ApiHandler = (apiReq: ApiRequest) => Promise<[number] | [number, any] | [number, any, string]>;
-export type ApiAuthType = 'none' | 'maybe' | 'yes';
+export type ApiAuthType = 'none' | 'maybe' | 'yes' | 'strict' | 'apikey';
 export type ApiAuthClass = 'any' | 'admin';
 export interface ApiKey {
     uid: unknown;

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

@@ -9,7 +9,7 @@ import jwt, { JwtPayload, SignOptions, VerifyOptions } from 'jsonwebtoken';
 import { ApiModule } from './api-module.js';
 import type { ApiAuthClass, ApiKey } from './api-module.js';
 import type { AuthProviderModule } from './auth-module.js';
-import type { AuthStorage } from './auth-storage.js';
+import type { AuthStorage, AuthTokenData } 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';
@@ -46,6 +46,8 @@ export interface ApiRequest {
     res: Response;
     tokenData?: ApiTokenData | null;
     token?: string;
+    authToken?: AuthTokenData | null;
+    apiKey?: ApiKey | null;
     clientInfo?: ClientInfo;
     getClientInfo: () => ClientInfo;
     getClientIp: () => string | null;
@@ -93,6 +95,7 @@ export interface ApiServerConf {
     authApi: boolean;
     devMode: boolean;
     hydrateGetBody: boolean;
+    validateTokens: boolean;
 }
 export declare class ApiServer {
     app: Application;
@@ -134,6 +137,10 @@ export declare class ApiServer {
     start(): this;
     private verifyJWT;
     private authenticate;
+    private tryAuthenticateApiKey;
+    private requiresAuthToken;
+    private shouldValidateStoredToken;
+    private assertStoredAccessToken;
     private handle_request;
     api<T extends ApiModule<any>>(module: T): this;
     dumpRequest(apiReq: ApiRequest): void;

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

@@ -320,7 +320,8 @@ function fillConfig(config) {
         refreshExpiry: config.refreshExpiry ?? 30 * 24 * 60 * 60 * 1000,
         authApi: config.authApi ?? false,
         devMode: config.devMode ?? false,
-        hydrateGetBody: config.hydrateGetBody ?? true
+        hydrateGetBody: config.hydrateGetBody ?? true,
+        validateTokens: config.validateTokens ?? false
     };
 }
 export class ApiServer {
@@ -529,37 +530,23 @@ export class ApiServer {
         }
         let token = null;
         const authHeader = apiReq.req.headers.authorization;
+        const requiresAuthToken = this.requiresAuthToken(authType);
+        const apiKeyAuth = await this.tryAuthenticateApiKey(apiReq, authType, authHeader);
+        if (apiKeyAuth) {
+            return apiKeyAuth;
+        }
         if (authHeader?.startsWith('Bearer ')) {
             token = authHeader.slice(7).trim();
         }
-        else if (authType === 'yes' && !authHeader) {
+        else if (requiresAuthToken && !authHeader) {
             throw new ApiError({ code: 401, message: 'Authorization header is missing or invalid' });
         }
-        if (token) {
-            const m = token.match(/^apikey-(.+)$/);
-            if (m) {
-                const key = await this.getApiKey(m[1]);
-                if (key) {
-                    apiReq.token = m[1];
-                    return {
-                        uid: key.uid,
-                        domain: '',
-                        fingerprint: '',
-                        iat: 0,
-                        exp: 0
-                    };
-                }
-                else {
-                    throw new ApiError({ code: 401, message: 'Invalid API Key' });
-                }
-            }
-        }
         if (!token || token === null) {
             const access = apiReq.req.cookies?.dat;
             if (access) {
                 token = access;
             }
-            else if (authType === 'yes') {
+            else if (requiresAuthToken) {
                 throw new ApiError({ code: 401, message: 'Authorization token is required (Bearer/cookie)' });
             }
         }
@@ -575,9 +562,61 @@ export class ApiServer {
         if (!tokenData) {
             throw new ApiError({ code: 401, message: 'Unathorized Access - ' + error });
         }
+        if (this.shouldValidateStoredToken(authType)) {
+            await this.assertStoredAccessToken(apiReq, token, tokenData);
+        }
         apiReq.token = token;
         return tokenData;
     }
+    async tryAuthenticateApiKey(apiReq, authType, authHeader) {
+        if (!authHeader?.startsWith('Bearer ')) {
+            if (authType === 'apikey') {
+                throw new ApiError({ code: 401, message: 'Authorization header is missing or invalid' });
+            }
+            return null;
+        }
+        const keyToken = authHeader.slice(7).trim();
+        if (!keyToken.startsWith('apikey-')) {
+            if (authType === 'apikey') {
+                throw new ApiError({ code: 401, message: 'Invalid API Key' });
+            }
+            return null;
+        }
+        const secret = keyToken.replace(/^apikey-/, '');
+        const key = await this.getApiKey(secret);
+        if (!key) {
+            throw new ApiError({ code: 401, message: 'Invalid API Key' });
+        }
+        apiReq.token = secret;
+        apiReq.apiKey = key;
+        return {
+            uid: key.uid,
+            domain: '',
+            fingerprint: '',
+            iat: 0,
+            exp: 0
+        };
+    }
+    requiresAuthToken(authType) {
+        return authType === 'yes' || authType === 'strict';
+    }
+    shouldValidateStoredToken(authType) {
+        return this.config.validateTokens || authType === 'strict';
+    }
+    async assertStoredAccessToken(apiReq, token, tokenData) {
+        if (typeof tokenData.uid !== 'string' && typeof tokenData.uid !== 'number') {
+            throw new ApiError({ code: 401, message: 'Authorization token is malformed' });
+        }
+        const userId = tokenData.uid;
+        const stored = await this.storageAdapter.getToken({
+            accessToken: token,
+            userId
+        });
+        if (!stored) {
+            throw new ApiError({ code: 401, message: 'Authorization token is no longer valid' });
+        }
+        apiReq.authToken = stored;
+    }
     handle_request(handler, auth) {
         return async (req, res, next) => {
             void next;

package/package.json

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