@technomoron/api-server-base 1.1.3 → 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,14 +121,16 @@ 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.
 
 Client IP Helpers
 -----------------
-Use getClientIp(req) to obtain the most likely client address, skipping loopback entries collected from proxy headers. Call getClientIpChain(req) when you need the de-duplicated sequence gathered from the standard Forwarded/X-Forwarded-For/X-Real-IP headers as well as Express' req.ip/req.ips and the underlying socket.
+Call `apiReq.getClientInfo()` when you need the entire client fingerprint captured during request hydration. It returns the raw user-agent string plus derived browser/OS/device labels along with the computed `ip` and `ipchain`.
+
+Call `apiReq.getClientIp()` to obtain the most likely client address, skipping loopback entries collected from proxy headers. Use `apiReq.getClientIpChain()` when you need the de-duplicated sequence gathered from the standard Forwarded/X-Forwarded-For/X-Real-IP headers as well as Express' `req.ip`/`req.ips` and the underlying socket. Both helpers reuse the cached payload returned by `apiReq.getClientInfo()`.
 
 Extending the Base Classes
 --------------------------

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

@@ -110,6 +110,111 @@ function extractForwardedHeader(header) {
     }
     return ips;
 }
+function detectBrowser(userAgent) {
+    const browserMatchers = [
+        { label: 'Edge', pattern: /(Edg|Edge|EdgiOS|EdgA)\/([\d.]+)/i, versionGroup: 2 },
+        { label: 'Chrome', pattern: /(Chrome|CriOS)\/([\d.]+)/i, versionGroup: 2 },
+        { label: 'Firefox', pattern: /(Firefox|FxiOS)\/([\d.]+)/i, versionGroup: 2 },
+        { label: 'Safari', pattern: /Version\/([\d.]+).*Safari/i, versionGroup: 1 },
+        { label: 'Opera', pattern: /(OPR|Opera)\/([\d.]+)/i, versionGroup: 2 },
+        { label: 'Brave', pattern: /Brave\/([\d.]+)/i, versionGroup: 1 },
+        { label: 'Vivaldi', pattern: /Vivaldi\/([\d.]+)/i, versionGroup: 1 },
+        { label: 'Electron', pattern: /Electron\/([\d.]+)/i, versionGroup: 1 },
+        { label: 'Node', pattern: /Node\.js\/([\d.]+)/i, versionGroup: 1 },
+        { label: 'IE', pattern: /MSIE ([\d.]+)/i, versionGroup: 1 },
+        { label: 'IE', pattern: /Trident\/.*rv:([\d.]+)/i, versionGroup: 1 }
+    ];
+    for (const matcher of browserMatchers) {
+        const m = userAgent.match(matcher.pattern);
+        if (m) {
+            const version = matcher.versionGroup ? m[matcher.versionGroup] : '';
+            return version ? `${matcher.label} ${version}` : matcher.label;
+        }
+    }
+    return '';
+}
+function detectOs(userAgent) {
+    const osMatchers = [
+        {
+            label: 'Windows',
+            pattern: /Windows NT ([\d.]+)/i,
+            transform: (match) => `Windows ${match[1]}`
+        },
+        {
+            label: 'iOS',
+            pattern: /iPhone OS ([\d_]+)/i,
+            transform: (match) => `iOS ${match[1].replace(/_/g, '.')}`
+        },
+        {
+            label: 'iPadOS',
+            pattern: /iPad; CPU OS ([\d_]+)/i,
+            transform: (match) => `iPadOS ${match[1].replace(/_/g, '.')}`
+        },
+        {
+            label: 'macOS',
+            pattern: /Mac OS X ([\d_]+)/i,
+            transform: (match) => `macOS ${match[1].replace(/_/g, '.')}`
+        },
+        {
+            label: 'Android',
+            pattern: /Android ([\d.]+)/i,
+            transform: (match) => `Android ${match[1]}`
+        },
+        {
+            label: 'ChromeOS',
+            pattern: /CrOS [^ ]+ ([\d.]+)/i,
+            transform: (match) => `ChromeOS ${match[1]}`
+        },
+        { label: 'Linux', pattern: /Linux/i },
+        { label: 'Unix', pattern: /X11/i }
+    ];
+    for (const matcher of osMatchers) {
+        const m = userAgent.match(matcher.pattern);
+        if (m) {
+            return matcher.transform ? matcher.transform(m) : matcher.label;
+        }
+    }
+    return '';
+}
+function detectDevice(userAgent, osLabel) {
+    if (/iPhone/i.test(userAgent)) {
+        return 'iPhone';
+    }
+    if (/iPad/i.test(userAgent)) {
+        return 'iPad';
+    }
+    if (/iPod/i.test(userAgent)) {
+        return 'iPod';
+    }
+    if (/Android/i.test(userAgent)) {
+        const match = userAgent.match(/;\s*([^;]+)\s+Build/i);
+        if (match) {
+            return match[1];
+        }
+        return 'Android Device';
+    }
+    if (/Macintosh/i.test(userAgent)) {
+        return 'Mac';
+    }
+    if (/Windows/i.test(userAgent)) {
+        return 'PC';
+    }
+    if (/CrOS/i.test(userAgent)) {
+        return 'Chromebook';
+    }
+    return osLabel;
+}
+function parseClientAgent(userAgentHeader) {
+    const raw = Array.isArray(userAgentHeader) ? userAgentHeader[0] : userAgentHeader;
+    const ua = typeof raw === 'string' ? raw.trim() : '';
+    if (!ua) {
+        return { ua: '', browser: '', os: '', device: '' };
+    }
+    const os = detectOs(ua);
+    const browser = detectBrowser(ua);
+    const device = detectDevice(ua, os);
+    return { ua, browser, os, device };
+}
 function isLoopbackAddress(ip) {
     if (ip === '::1' || ip === '0:0:0:0:0:0:0:1') {
         return true;
@@ -122,6 +227,71 @@ function isLoopbackAddress(ip) {
     }
     return false;
 }
+function collectClientIpChain(req) {
+    const seen = new Set();
+    const result = [];
+    const pushNormalized = (ip) => {
+        if (!ip || seen.has(ip)) {
+            return;
+        }
+        seen.add(ip);
+        result.push(ip);
+    };
+    for (const ip of extractForwardedFor(req.headers['x-forwarded-for'])) {
+        pushNormalized(ip);
+    }
+    for (const ip of extractForwardedHeader(req.headers['forwarded'])) {
+        pushNormalized(ip);
+    }
+    const realIp = req.headers['x-real-ip'];
+    if (Array.isArray(realIp)) {
+        realIp.forEach((value) => pushNormalized(normalizeIpAddress(value)));
+    }
+    else if (typeof realIp === 'string') {
+        pushNormalized(normalizeIpAddress(realIp));
+    }
+    if (Array.isArray(req.ips)) {
+        for (const ip of req.ips) {
+            pushNormalized(normalizeIpAddress(ip));
+        }
+    }
+    if (typeof req.ip === 'string') {
+        pushNormalized(normalizeIpAddress(req.ip));
+    }
+    const socketAddress = req.socket?.remoteAddress;
+    if (typeof socketAddress === 'string') {
+        pushNormalized(normalizeIpAddress(socketAddress));
+    }
+    const connectionAddress = req.connection?.remoteAddress;
+    if (typeof connectionAddress === 'string') {
+        pushNormalized(normalizeIpAddress(connectionAddress));
+    }
+    return result;
+}
+function selectClientIp(chain) {
+    for (const ip of chain) {
+        if (!isLoopbackAddress(ip)) {
+            return ip;
+        }
+    }
+    return chain[0] ?? null;
+}
+function buildClientInfo(req) {
+    const agent = parseClientAgent(req.headers['user-agent']);
+    const ipchain = collectClientIpChain(req);
+    const ip = selectClientIp(ipchain);
+    return {
+        ...agent,
+        ip,
+        ipchain
+    };
+}
+function ensureClientInfo(apiReq) {
+    if (!apiReq.clientInfo) {
+        apiReq.clientInfo = buildClientInfo(apiReq.req);
+    }
+    return apiReq.clientInfo;
+}
 class ApiError extends Error {
     constructor({ code, message, data, errors }) {
         const msg = guess_exception_text(message, '[Unknown error (null/undefined)]');
@@ -158,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 {
@@ -367,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)' });
             }
         }
@@ -413,20 +570,76 @@ 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;
             try {
-                const apiReq = (this.currReq = {
+                const apiReq = {
                     server: this,
                     req,
                     res,
                     token: '',
-                    tokenData: null
-                });
+                    tokenData: null,
+                    getClientInfo: () => ensureClientInfo(apiReq),
+                    getClientIp: () => ensureClientInfo(apiReq).ip,
+                    getClientIpChain: () => ensureClientInfo(apiReq).ipchain
+                };
+                this.currReq = apiReq;
                 if (this.config.hydrateGetBody) {
                     hydrateGetBody(apiReq.req);
                 }
@@ -473,56 +686,6 @@ class ApiServer {
             }
         };
     }
-    getClientIp(req) {
-        const chain = this.getClientIpChain(req);
-        for (const ip of chain) {
-            if (!isLoopbackAddress(ip)) {
-                return ip;
-            }
-        }
-        return chain[0] ?? null;
-    }
-    getClientIpChain(req) {
-        const seen = new Set();
-        const result = [];
-        const pushNormalized = (ip) => {
-            if (!ip || seen.has(ip)) {
-                return;
-            }
-            seen.add(ip);
-            result.push(ip);
-        };
-        for (const ip of extractForwardedFor(req.headers['x-forwarded-for'])) {
-            pushNormalized(ip);
-        }
-        for (const ip of extractForwardedHeader(req.headers['forwarded'])) {
-            pushNormalized(ip);
-        }
-        const realIp = req.headers['x-real-ip'];
-        if (Array.isArray(realIp)) {
-            realIp.forEach((value) => pushNormalized(normalizeIpAddress(value)));
-        }
-        else if (typeof realIp === 'string') {
-            pushNormalized(normalizeIpAddress(realIp));
-        }
-        if (Array.isArray(req.ips)) {
-            for (const ip of req.ips) {
-                pushNormalized(normalizeIpAddress(ip));
-            }
-        }
-        if (typeof req.ip === 'string') {
-            pushNormalized(normalizeIpAddress(req.ip));
-        }
-        const socketAddress = req.socket?.remoteAddress;
-        if (typeof socketAddress === 'string') {
-            pushNormalized(normalizeIpAddress(socketAddress));
-        }
-        const connectionAddress = req.connection?.remoteAddress;
-        if (typeof connectionAddress === 'string') {
-            pushNormalized(normalizeIpAddress(connectionAddress));
-        }
-        return result;
-    }
     api(module) {
         const router = express_1.default.Router();
         module.server = this;

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,22 @@ export interface ApiRequest {
     res: Response;
     tokenData?: ApiTokenData | null;
     token?: string;
+    authToken?: AuthTokenData | null;
+    apiKey?: ApiKey | null;
+    clientInfo?: ClientInfo;
+    getClientInfo: () => ClientInfo;
+    getClientIp: () => string | null;
+    getClientIpChain: () => string[];
+}
+export interface ClientAgentProfile {
+    ua: string;
+    browser: string;
+    os: string;
+    device: string;
+}
+export interface ClientInfo extends ClientAgentProfile {
+    ip: string | null;
+    ipchain: string[];
 }
 export { ApiModule } from './api-module.js';
 export type { ApiHandler, ApiAuthType, ApiAuthClass, ApiRoute, ApiKey } from './api-module.js';
@@ -79,6 +95,7 @@ export interface ApiServerConf {
     authApi: boolean;
     devMode: boolean;
     hydrateGetBody: boolean;
+    validateTokens: boolean;
 }
 export declare class ApiServer {
     app: Application;
@@ -120,9 +137,11 @@ export declare class ApiServer {
     start(): this;
     private verifyJWT;
     private authenticate;
+    private tryAuthenticateApiKey;
+    private requiresAuthToken;
+    private shouldValidateStoredToken;
+    private assertStoredAccessToken;
     private handle_request;
-    getClientIp(req: RequestWithStuff): string | null;
-    getClientIpChain(req: RequestWithStuff): string[];
     api<T extends ApiModule<any>>(module: T): this;
     dumpRequest(apiReq: ApiRequest): void;
 }

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

@@ -4,12 +4,18 @@ export interface AuthTokenMetadata {
     domain?: string;
     fingerprint?: string;
     label?: string;
+    browser?: string;
+    device?: string;
+    ip?: string;
+    os?: string;
     scope?: string | string[];
     revokeSessions?: 'device' | 'domain' | 'client' | 'user';
 }
 export interface AuthTokenData extends AuthTokenMetadata {
     access: string;
     expires?: Date;
+    issuedAt?: Date;
+    lastSeenAt?: Date;
     refresh: string;
     userId: AuthIdentifier;
 }

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,22 @@ export interface ApiRequest {
     res: Response;
     tokenData?: ApiTokenData | null;
     token?: string;
+    authToken?: AuthTokenData | null;
+    apiKey?: ApiKey | null;
+    clientInfo?: ClientInfo;
+    getClientInfo: () => ClientInfo;
+    getClientIp: () => string | null;
+    getClientIpChain: () => string[];
+}
+export interface ClientAgentProfile {
+    ua: string;
+    browser: string;
+    os: string;
+    device: string;
+}
+export interface ClientInfo extends ClientAgentProfile {
+    ip: string | null;
+    ipchain: string[];
 }
 export { ApiModule } from './api-module.js';
 export type { ApiHandler, ApiAuthType, ApiAuthClass, ApiRoute, ApiKey } from './api-module.js';
@@ -79,6 +95,7 @@ export interface ApiServerConf {
     authApi: boolean;
     devMode: boolean;
     hydrateGetBody: boolean;
+    validateTokens: boolean;
 }
 export declare class ApiServer {
     app: Application;
@@ -120,9 +137,11 @@ export declare class ApiServer {
     start(): this;
     private verifyJWT;
     private authenticate;
+    private tryAuthenticateApiKey;
+    private requiresAuthToken;
+    private shouldValidateStoredToken;
+    private assertStoredAccessToken;
     private handle_request;
-    getClientIp(req: RequestWithStuff): string | null;
-    getClientIpChain(req: RequestWithStuff): string[];
     api<T extends ApiModule<any>>(module: T): this;
     dumpRequest(apiReq: ApiRequest): void;
 }

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

@@ -103,6 +103,111 @@ function extractForwardedHeader(header) {
     }
     return ips;
 }
+function detectBrowser(userAgent) {
+    const browserMatchers = [
+        { label: 'Edge', pattern: /(Edg|Edge|EdgiOS|EdgA)\/([\d.]+)/i, versionGroup: 2 },
+        { label: 'Chrome', pattern: /(Chrome|CriOS)\/([\d.]+)/i, versionGroup: 2 },
+        { label: 'Firefox', pattern: /(Firefox|FxiOS)\/([\d.]+)/i, versionGroup: 2 },
+        { label: 'Safari', pattern: /Version\/([\d.]+).*Safari/i, versionGroup: 1 },
+        { label: 'Opera', pattern: /(OPR|Opera)\/([\d.]+)/i, versionGroup: 2 },
+        { label: 'Brave', pattern: /Brave\/([\d.]+)/i, versionGroup: 1 },
+        { label: 'Vivaldi', pattern: /Vivaldi\/([\d.]+)/i, versionGroup: 1 },
+        { label: 'Electron', pattern: /Electron\/([\d.]+)/i, versionGroup: 1 },
+        { label: 'Node', pattern: /Node\.js\/([\d.]+)/i, versionGroup: 1 },
+        { label: 'IE', pattern: /MSIE ([\d.]+)/i, versionGroup: 1 },
+        { label: 'IE', pattern: /Trident\/.*rv:([\d.]+)/i, versionGroup: 1 }
+    ];
+    for (const matcher of browserMatchers) {
+        const m = userAgent.match(matcher.pattern);
+        if (m) {
+            const version = matcher.versionGroup ? m[matcher.versionGroup] : '';
+            return version ? `${matcher.label} ${version}` : matcher.label;
+        }
+    }
+    return '';
+}
+function detectOs(userAgent) {
+    const osMatchers = [
+        {
+            label: 'Windows',
+            pattern: /Windows NT ([\d.]+)/i,
+            transform: (match) => `Windows ${match[1]}`
+        },
+        {
+            label: 'iOS',
+            pattern: /iPhone OS ([\d_]+)/i,
+            transform: (match) => `iOS ${match[1].replace(/_/g, '.')}`
+        },
+        {
+            label: 'iPadOS',
+            pattern: /iPad; CPU OS ([\d_]+)/i,
+            transform: (match) => `iPadOS ${match[1].replace(/_/g, '.')}`
+        },
+        {
+            label: 'macOS',
+            pattern: /Mac OS X ([\d_]+)/i,
+            transform: (match) => `macOS ${match[1].replace(/_/g, '.')}`
+        },
+        {
+            label: 'Android',
+            pattern: /Android ([\d.]+)/i,
+            transform: (match) => `Android ${match[1]}`
+        },
+        {
+            label: 'ChromeOS',
+            pattern: /CrOS [^ ]+ ([\d.]+)/i,
+            transform: (match) => `ChromeOS ${match[1]}`
+        },
+        { label: 'Linux', pattern: /Linux/i },
+        { label: 'Unix', pattern: /X11/i }
+    ];
+    for (const matcher of osMatchers) {
+        const m = userAgent.match(matcher.pattern);
+        if (m) {
+            return matcher.transform ? matcher.transform(m) : matcher.label;
+        }
+    }
+    return '';
+}
+function detectDevice(userAgent, osLabel) {
+    if (/iPhone/i.test(userAgent)) {
+        return 'iPhone';
+    }
+    if (/iPad/i.test(userAgent)) {
+        return 'iPad';
+    }
+    if (/iPod/i.test(userAgent)) {
+        return 'iPod';
+    }
+    if (/Android/i.test(userAgent)) {
+        const match = userAgent.match(/;\s*([^;]+)\s+Build/i);
+        if (match) {
+            return match[1];
+        }
+        return 'Android Device';
+    }
+    if (/Macintosh/i.test(userAgent)) {
+        return 'Mac';
+    }
+    if (/Windows/i.test(userAgent)) {
+        return 'PC';
+    }
+    if (/CrOS/i.test(userAgent)) {
+        return 'Chromebook';
+    }
+    return osLabel;
+}
+function parseClientAgent(userAgentHeader) {
+    const raw = Array.isArray(userAgentHeader) ? userAgentHeader[0] : userAgentHeader;
+    const ua = typeof raw === 'string' ? raw.trim() : '';
+    if (!ua) {
+        return { ua: '', browser: '', os: '', device: '' };
+    }
+    const os = detectOs(ua);
+    const browser = detectBrowser(ua);
+    const device = detectDevice(ua, os);
+    return { ua, browser, os, device };
+}
 function isLoopbackAddress(ip) {
     if (ip === '::1' || ip === '0:0:0:0:0:0:0:1') {
         return true;
@@ -115,6 +220,71 @@ function isLoopbackAddress(ip) {
     }
     return false;
 }
+function collectClientIpChain(req) {
+    const seen = new Set();
+    const result = [];
+    const pushNormalized = (ip) => {
+        if (!ip || seen.has(ip)) {
+            return;
+        }
+        seen.add(ip);
+        result.push(ip);
+    };
+    for (const ip of extractForwardedFor(req.headers['x-forwarded-for'])) {
+        pushNormalized(ip);
+    }
+    for (const ip of extractForwardedHeader(req.headers['forwarded'])) {
+        pushNormalized(ip);
+    }
+    const realIp = req.headers['x-real-ip'];
+    if (Array.isArray(realIp)) {
+        realIp.forEach((value) => pushNormalized(normalizeIpAddress(value)));
+    }
+    else if (typeof realIp === 'string') {
+        pushNormalized(normalizeIpAddress(realIp));
+    }
+    if (Array.isArray(req.ips)) {
+        for (const ip of req.ips) {
+            pushNormalized(normalizeIpAddress(ip));
+        }
+    }
+    if (typeof req.ip === 'string') {
+        pushNormalized(normalizeIpAddress(req.ip));
+    }
+    const socketAddress = req.socket?.remoteAddress;
+    if (typeof socketAddress === 'string') {
+        pushNormalized(normalizeIpAddress(socketAddress));
+    }
+    const connectionAddress = req.connection?.remoteAddress;
+    if (typeof connectionAddress === 'string') {
+        pushNormalized(normalizeIpAddress(connectionAddress));
+    }
+    return result;
+}
+function selectClientIp(chain) {
+    for (const ip of chain) {
+        if (!isLoopbackAddress(ip)) {
+            return ip;
+        }
+    }
+    return chain[0] ?? null;
+}
+function buildClientInfo(req) {
+    const agent = parseClientAgent(req.headers['user-agent']);
+    const ipchain = collectClientIpChain(req);
+    const ip = selectClientIp(ipchain);
+    return {
+        ...agent,
+        ip,
+        ipchain
+    };
+}
+function ensureClientInfo(apiReq) {
+    if (!apiReq.clientInfo) {
+        apiReq.clientInfo = buildClientInfo(apiReq.req);
+    }
+    return apiReq.clientInfo;
+}
 export class ApiError extends Error {
     constructor({ code, message, data, errors }) {
         const msg = guess_exception_text(message, '[Unknown error (null/undefined)]');
@@ -150,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 {
@@ -359,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)' });
             }
         }
@@ -405,20 +562,76 @@ 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;
             try {
-                const apiReq = (this.currReq = {
+                const apiReq = {
                     server: this,
                     req,
                     res,
                     token: '',
-                    tokenData: null
-                });
+                    tokenData: null,
+                    getClientInfo: () => ensureClientInfo(apiReq),
+                    getClientIp: () => ensureClientInfo(apiReq).ip,
+                    getClientIpChain: () => ensureClientInfo(apiReq).ipchain
+                };
+                this.currReq = apiReq;
                 if (this.config.hydrateGetBody) {
                     hydrateGetBody(apiReq.req);
                 }
@@ -465,56 +678,6 @@ export class ApiServer {
             }
         };
     }
-    getClientIp(req) {
-        const chain = this.getClientIpChain(req);
-        for (const ip of chain) {
-            if (!isLoopbackAddress(ip)) {
-                return ip;
-            }
-        }
-        return chain[0] ?? null;
-    }
-    getClientIpChain(req) {
-        const seen = new Set();
-        const result = [];
-        const pushNormalized = (ip) => {
-            if (!ip || seen.has(ip)) {
-                return;
-            }
-            seen.add(ip);
-            result.push(ip);
-        };
-        for (const ip of extractForwardedFor(req.headers['x-forwarded-for'])) {
-            pushNormalized(ip);
-        }
-        for (const ip of extractForwardedHeader(req.headers['forwarded'])) {
-            pushNormalized(ip);
-        }
-        const realIp = req.headers['x-real-ip'];
-        if (Array.isArray(realIp)) {
-            realIp.forEach((value) => pushNormalized(normalizeIpAddress(value)));
-        }
-        else if (typeof realIp === 'string') {
-            pushNormalized(normalizeIpAddress(realIp));
-        }
-        if (Array.isArray(req.ips)) {
-            for (const ip of req.ips) {
-                pushNormalized(normalizeIpAddress(ip));
-            }
-        }
-        if (typeof req.ip === 'string') {
-            pushNormalized(normalizeIpAddress(req.ip));
-        }
-        const socketAddress = req.socket?.remoteAddress;
-        if (typeof socketAddress === 'string') {
-            pushNormalized(normalizeIpAddress(socketAddress));
-        }
-        const connectionAddress = req.connection?.remoteAddress;
-        if (typeof connectionAddress === 'string') {
-            pushNormalized(normalizeIpAddress(connectionAddress));
-        }
-        return result;
-    }
     api(module) {
         const router = express.Router();
         module.server = this;

package/dist/esm/auth-storage.d.ts

@@ -4,12 +4,18 @@ export interface AuthTokenMetadata {
     domain?: string;
     fingerprint?: string;
     label?: string;
+    browser?: string;
+    device?: string;
+    ip?: string;
+    os?: string;
     scope?: string | string[];
     revokeSessions?: 'device' | 'domain' | 'client' | 'user';
 }
 export interface AuthTokenData extends AuthTokenMetadata {
     access: string;
     expires?: Date;
+    issuedAt?: Date;
+    lastSeenAt?: Date;
     refresh: string;
     userId: AuthIdentifier;
 }

package/package.json

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