@technomoron/api-server-base 1.0.42 → 1.0.43

package/README.txt

@@ -105,6 +105,10 @@ Request Lifecycle
 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.
+
 Extending the Base Classes
 --------------------------
 Override getApiKey, getUser, authenticateUser, storeToken, getToken, updateToken, deleteToken, and verifyPassword to integrate with your persistence layer.

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

@@ -62,6 +62,76 @@ function hydrateGetBody(req) {
     }
     req.body = { ...query, ...body };
 }
+function normalizeIpAddress(candidate) {
+    let value = candidate.trim();
+    if (!value) {
+        return null;
+    }
+    value = value.replace(/^"+|"+$/g, '').replace(/^'+|'+$/g, '');
+    if (value.startsWith('::ffff:')) {
+        value = value.slice(7);
+    }
+    if (value.startsWith('[') && value.endsWith(']')) {
+        value = value.slice(1, -1);
+    }
+    const firstColon = value.indexOf(':');
+    const lastColon = value.lastIndexOf(':');
+    if (firstColon !== -1 && firstColon === lastColon) {
+        const maybePort = value.slice(lastColon + 1);
+        if (/^\d+$/.test(maybePort)) {
+            value = value.slice(0, lastColon);
+        }
+    }
+    value = value.trim();
+    return value || null;
+}
+function extractForwardedFor(header) {
+    if (!header) {
+        return [];
+    }
+    const values = Array.isArray(header) ? header : [header];
+    const ips = [];
+    for (const entry of values) {
+        for (const part of entry.split(',')) {
+            const normalized = normalizeIpAddress(part);
+            if (normalized) {
+                ips.push(normalized);
+            }
+        }
+    }
+    return ips;
+}
+function extractForwardedHeader(header) {
+    if (!header) {
+        return [];
+    }
+    const values = Array.isArray(header) ? header : [header];
+    const ips = [];
+    for (const entry of values) {
+        for (const part of entry.split(',')) {
+            const match = part.match(/for=([^;]+)/i);
+            if (match) {
+                const normalized = normalizeIpAddress(match[1]);
+                if (normalized) {
+                    ips.push(normalized);
+                }
+            }
+        }
+    }
+    return ips;
+}
+function isLoopbackAddress(ip) {
+    if (ip === '::1' || ip === '0:0:0:0:0:0:0:1') {
+        return true;
+    }
+    if (ip === '0.0.0.0' || ip === '127.0.0.1') {
+        return true;
+    }
+    if (ip.startsWith('127.')) {
+        return true;
+    }
+    return false;
+}
 class ApiError extends Error {
     constructor({ code, message, data, errors }) {
         const msg = guess_exception_text(message, '[Unknown error (null/undefined)]');
@@ -174,27 +244,36 @@ class ApiServer {
         }
     }
     async getApiKey(token) {
+        void token;
         return null;
     }
     async getUser(uid) {
+        void uid;
         throw new Error('getUser() not implemented');
     }
     async authenticateUser(params) {
+        void params;
         throw new Error('authenticateUser() not implemented');
     }
     async storeToken(params) {
+        void params;
         throw new Error('storeToken() not implemented');
     }
     async getToken(params) {
+        void params;
         throw new Error('getToken() not implemented');
     }
     async updateToken(params) {
+        void params;
         throw new Error('updateToken() not implemented');
     }
     async deleteToken(params) {
+        void params;
         throw new Error('deleteToken() not implemented');
     }
     async verifyPassword(password, hash) {
+        void password;
+        void hash;
         throw new Error('verifyPassword() not implemented');
     }
     filterUser(fullUser) {
@@ -203,7 +282,10 @@ class ApiServer {
     guessExceptionText(error, defMsg = 'Unkown Error') {
         return guess_exception_text(error, defMsg);
     }
-    async authorize(apiReq, requiredClass) { }
+    async authorize(apiReq, requiredClass) {
+        void apiReq;
+        void requiredClass;
+    }
     middlewares() {
         this.app.use(express_1.default.json());
         this.app.use((0, cookie_parser_1.default)());
@@ -320,6 +402,7 @@ class ApiServer {
     }
     handle_request(handler, auth) {
         return async (req, res, next) => {
+            void next;
             try {
                 const apiReq = (this.currReq = {
                     server: this,
@@ -359,6 +442,56 @@ 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

@@ -146,6 +146,8 @@ 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.d.ts

@@ -146,6 +146,8 @@ 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

@@ -55,6 +55,76 @@ function hydrateGetBody(req) {
     }
     req.body = { ...query, ...body };
 }
+function normalizeIpAddress(candidate) {
+    let value = candidate.trim();
+    if (!value) {
+        return null;
+    }
+    value = value.replace(/^"+|"+$/g, '').replace(/^'+|'+$/g, '');
+    if (value.startsWith('::ffff:')) {
+        value = value.slice(7);
+    }
+    if (value.startsWith('[') && value.endsWith(']')) {
+        value = value.slice(1, -1);
+    }
+    const firstColon = value.indexOf(':');
+    const lastColon = value.lastIndexOf(':');
+    if (firstColon !== -1 && firstColon === lastColon) {
+        const maybePort = value.slice(lastColon + 1);
+        if (/^\d+$/.test(maybePort)) {
+            value = value.slice(0, lastColon);
+        }
+    }
+    value = value.trim();
+    return value || null;
+}
+function extractForwardedFor(header) {
+    if (!header) {
+        return [];
+    }
+    const values = Array.isArray(header) ? header : [header];
+    const ips = [];
+    for (const entry of values) {
+        for (const part of entry.split(',')) {
+            const normalized = normalizeIpAddress(part);
+            if (normalized) {
+                ips.push(normalized);
+            }
+        }
+    }
+    return ips;
+}
+function extractForwardedHeader(header) {
+    if (!header) {
+        return [];
+    }
+    const values = Array.isArray(header) ? header : [header];
+    const ips = [];
+    for (const entry of values) {
+        for (const part of entry.split(',')) {
+            const match = part.match(/for=([^;]+)/i);
+            if (match) {
+                const normalized = normalizeIpAddress(match[1]);
+                if (normalized) {
+                    ips.push(normalized);
+                }
+            }
+        }
+    }
+    return ips;
+}
+function isLoopbackAddress(ip) {
+    if (ip === '::1' || ip === '0:0:0:0:0:0:0:1') {
+        return true;
+    }
+    if (ip === '0.0.0.0' || ip === '127.0.0.1') {
+        return true;
+    }
+    if (ip.startsWith('127.')) {
+        return true;
+    }
+    return false;
+}
 export class ApiError extends Error {
     constructor({ code, message, data, errors }) {
         const msg = guess_exception_text(message, '[Unknown error (null/undefined)]');
@@ -166,27 +236,36 @@ export class ApiServer {
         }
     }
     async getApiKey(token) {
+        void token;
         return null;
     }
     async getUser(uid) {
+        void uid;
         throw new Error('getUser() not implemented');
     }
     async authenticateUser(params) {
+        void params;
         throw new Error('authenticateUser() not implemented');
     }
     async storeToken(params) {
+        void params;
         throw new Error('storeToken() not implemented');
     }
     async getToken(params) {
+        void params;
         throw new Error('getToken() not implemented');
     }
     async updateToken(params) {
+        void params;
         throw new Error('updateToken() not implemented');
     }
     async deleteToken(params) {
+        void params;
         throw new Error('deleteToken() not implemented');
     }
     async verifyPassword(password, hash) {
+        void password;
+        void hash;
         throw new Error('verifyPassword() not implemented');
     }
     filterUser(fullUser) {
@@ -195,7 +274,10 @@ export class ApiServer {
     guessExceptionText(error, defMsg = 'Unkown Error') {
         return guess_exception_text(error, defMsg);
     }
-    async authorize(apiReq, requiredClass) { }
+    async authorize(apiReq, requiredClass) {
+        void apiReq;
+        void requiredClass;
+    }
     middlewares() {
         this.app.use(express.json());
         this.app.use(cookieParser());
@@ -312,6 +394,7 @@ export class ApiServer {
     }
     handle_request(handler, auth) {
         return async (req, res, next) => {
+            void next;
             try {
                 const apiReq = (this.currReq = {
                     server: this,
@@ -351,6 +434,56 @@ 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/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@technomoron/api-server-base",
-	"version": "1.0.42",
+	"version": "1.0.43",
 	"description": "Api Server Skeleton / Base Class",
 	"type": "module",
 	"main": "./dist/cjs/index.cjs",
@@ -35,34 +35,34 @@
 		"lint": "eslint --ext .js,.ts,.vue ./",
 		"lintfix": "eslint --fix --ext .js,.ts,.vue ./",
 		"format": "eslint --fix --ext .js,.ts,.vue ./ && prettier --write \"**/*.{js,jsx,ts,tsx,vue,json,css,scss,md}\"",
-		"cleanbuild": "rm -rf ./dist/ && eslint --fix --ext .js,.ts,.vue ./ && prettier --write \"**/*.{js,jsx,ts,tsx,vue,json,css,scss,md}\" && tsc --project tsconfig/tsconfig.cjs.json && tsc --project tsconfig/tsconfig.esm.json",
+		"cleanbuild": "rm -rf ./dist/ && eslint --fix --ext .js,.ts,.vue ./ && prettier --write \"**/*.{js,jsx,ts,tsx,vue,json,css,scss,md}\" && npm run build",
 		"pretty": "prettier --write \"**/*.{js,jsx,ts,tsx,vue,json,css,scss,md}\""
 	},
 	"dependencies": {
 		"@types/cookie-parser": "^1.4.9",
 		"@types/cors": "^2.8.19",
-		"@types/express": "^4.17.21",
-		"@types/jsonwebtoken": "^9.0.9",
+		"@types/express": "^4.17.23",
+		"@types/jsonwebtoken": "^9.0.10",
 		"@types/multer": "^1.4.13",
 		"cookie-parser": "^1.4.7",
 		"cors": "^2.8.5",
 		"express": "^4.21.2",
 		"jsonwebtoken": "^9.0.2",
-		"multer": "^2.0.1"
+		"multer": "^2.0.2"
 	},
 	"devDependencies": {
-		"@types/express-serve-static-core": "^5.0.6",
+		"@types/express-serve-static-core": "^5.1.0",
 		"@types/supertest": "^6.0.3",
-		"@typescript-eslint/eslint-plugin": "^8.33.0",
-		"@typescript-eslint/parser": "^8.33.0",
+		"@typescript-eslint/eslint-plugin": "^8.46.1",
+		"@typescript-eslint/parser": "^8.46.1",
 		"@vue/eslint-config-prettier": "10.2.0",
 		"@vue/eslint-config-typescript": "14.5.0",
-		"eslint": "^9.28.0",
-		"eslint-plugin-import": "^2.31.0",
-		"eslint-plugin-vue": "^10.1.0",
-		"prettier": "^3.5.3",
+		"eslint": "^9.37.0",
+		"eslint-plugin-import": "^2.32.0",
+		"eslint-plugin-vue": "^10.5.1",
+		"prettier": "^3.6.2",
 		"supertest": "^7.1.4",
-		"typescript": "^5.8.3",
+		"typescript": "^5.9.3",
 		"vitest": "^3.2.4"
 	},
 	"files": [