@technomoron/api-server-base 1.1.3 → 1.1.4

package/README.txt

@@ -127,7 +127,9 @@ Request Lifecycle
 
 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-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)]');
@@ -420,13 +590,17 @@ class ApiServer {
         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 +647,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

@@ -46,6 +46,20 @@ export interface ApiRequest {
     res: Response;
     tokenData?: ApiTokenData | null;
     token?: string;
+    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';
@@ -121,8 +135,6 @@ export declare class ApiServer {
     private verifyJWT;
     private authenticate;
     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-server-base.d.ts

@@ -46,6 +46,20 @@ export interface ApiRequest {
     res: Response;
     tokenData?: ApiTokenData | null;
     token?: string;
+    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';
@@ -121,8 +135,6 @@ export declare class ApiServer {
     private verifyJWT;
     private authenticate;
     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)]');
@@ -412,13 +582,17 @@ export class ApiServer {
         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 +639,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.4",
 	"description": "Api Server Skeleton / Base Class",
 	"type": "module",
 	"main": "./dist/cjs/index.cjs",