fa-mcp-sdk 0.3.16 → 0.3.17

package/cli-template/README.md

@@ -1,105 +1,105 @@
-# {{project.productName}}
-
-{{project.description}}
-
-## Install & Run
-
-### Quick Start
-```bash
-# Install
-npm install
-
-# Configure (copy config/local.yaml from config/_local.yaml)
-# Add database credentials
-
-# Build
-npm run build
-
-# Run (STDIO mode for Claude Desktop)
-npm start
-```
-
-### Test Run
-```bash
-# Unit tests
-npm test
-
-# MCP protocol tests
-npm run test:mcp        # STDIO mode
-npm run test:mcp-http   # HTTP mode
-npm run test:mcp-simple # Simple test
-```
-
-### Dual Transport System
-
-**STDIO Mode** (default for Claude Desktop):
-- Direct stdin/stdout communication
-- Optimal for Claude Desktop integration
-- No network ports required
-
-**HTTP Mode** (web integration):
-- HTTP server with Server-Sent Events (SSE)
-- Home page with server status at `http://localhost:{{port}}/`
-- Health check endpoint at `/health`
-- Direct JSON-RPC 2.0 endpoint at `/mcp`
-
-
-## Features
-
-
-
-## MCP Tools
-
-
-
-## MCP Prompts
-
-### `agent_brief`
-Brief description of agent capabilities for agent selection.
-
-### `agent_prompt`
-Complete prompt with instructions.
-
-## MCP Resources
-
-### `staff://agent/brief`
-Same as `agent_brief` prompt. **MIME:** text/plain
-
-### `staff://agent/prompt`
-Same as `agent_prompt` prompt. **MIME:** text/plain
-
-
-## 2. Configuration
-
-**Option A: Configuration File**
-
-**Option B: Environment Variables**
-
-
-## Claude Desktop Setup
-
-Add to `claude_desktop_config.json`:
-
-```json
-{
-  "mcpServers": {
-    "{{project.name}}": {
-      "command": "node",
-      "args": [
-        "<path-to-project>/mcp-staff-db/dist/src/index.js"
-      ],
-      "env": {
-      }
-    }
-  }
-}
-```
-
-## HTTP Mode Endpoints
-
-- **/** - Home page
-- **/health** - Health check
-- **/sse** - Server-Sent Events
-- **/mcp** - JSON-RPC 2.0
-
-## Security
+# {{project.productName}}
+
+{{project.description}}
+
+## Install & Run
+
+### Quick Start
+```bash
+# Install
+npm install
+
+# Configure (copy config/local.yaml from config/_local.yaml)
+# Add database credentials
+
+# Build
+npm run build
+
+# Run (STDIO mode for Claude Desktop)
+npm start
+```
+
+### Test Run
+```bash
+# Unit tests
+npm test
+
+# MCP protocol tests
+npm run test:mcp        # STDIO mode
+npm run test:mcp-http   # HTTP mode
+npm run test:mcp-simple # Simple test
+```
+
+### Dual Transport System
+
+**STDIO Mode** (default for Claude Desktop):
+- Direct stdin/stdout communication
+- Optimal for Claude Desktop integration
+- No network ports required
+
+**HTTP Mode** (web integration):
+- HTTP server with Server-Sent Events (SSE)
+- Home page with server status at `http://localhost:{{port}}/`
+- Health check endpoint at `/health`
+- Direct JSON-RPC 2.0 endpoint at `/mcp`
+
+
+## Features
+
+
+
+## MCP Tools
+
+
+
+## MCP Prompts
+
+### `agent_brief`
+Brief description of agent capabilities for agent selection.
+
+### `agent_prompt`
+Complete prompt with instructions.
+
+## MCP Resources
+
+### `staff://agent/brief`
+Same as `agent_brief` prompt. **MIME:** text/plain
+
+### `staff://agent/prompt`
+Same as `agent_prompt` prompt. **MIME:** text/plain
+
+
+## 2. Configuration
+
+**Option A: Configuration File**
+
+**Option B: Environment Variables**
+
+
+## Claude Desktop Setup
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "{{project.name}}": {
+      "command": "node",
+      "args": [
+        "<path-to-project>/mcp-staff-db/dist/src/index.js"
+      ],
+      "env": {
+      }
+    }
+  }
+}
+```
+
+## HTTP Mode Endpoints
+
+- **/** - Home page
+- **/health** - Health check
+- **/sse** - Server-Sent Events
+- **/mcp** - JSON-RPC 2.0
+
+## Security

package/cli-template/package.json

@@ -50,7 +50,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.26.0",
     "dotenv": "^17.2.4",
-    "fa-mcp-sdk": "^0.3.16"
+    "fa-mcp-sdk": "^0.3.17"
   },
   "devDependencies": {
     "@types/express": "^5.0.6",

package/cli-template/prompt-example-new-MCP.md

@@ -18,7 +18,7 @@ Authorization: Bearer <appConfig.accessPoints.currencyService.token>
 Example:
 
 ```http request
-GET http://smart-trade-ml.com:5002/currency-service/?rate=THBRUB
+GET http://smart-trade-ml.com:5001/currency-service/?rate=THBRUB
 Authorization: Bearer <appConfig.accessPoints.currencyService.token>
 ```
 
@@ -66,6 +66,7 @@ webServer:
       jwtToken:
          encryptKey: 'dbbe87db-90d0-4732-aae3-4089763ec392'
          checkMCPName: true
+         isCheckIP: false
       permanentServerTokens: ['psToken1']
 
    adminAuth:

package/cli-template/r/TEST HTTP.xml

@@ -1,9 +1,9 @@
-<component name="ProjectRunConfigurationManager">
-  <configuration
-      default="false"
-      name="TEST HTTP"
-      type="NodeJSConfigurationType"
-      path-to-js-file="tests/mcp/test-http.js" working-dir="$PROJECT_DIR$/">
-    <method v="2" />
-  </configuration>
-</component>
+<component name="ProjectRunConfigurationManager">
+  <configuration
+      default="false"
+      name="TEST HTTP"
+      type="NodeJSConfigurationType"
+      path-to-js-file="tests/mcp/test-http.js" working-dir="$PROJECT_DIR$/">
+    <method v="2" />
+  </configuration>
+</component>

package/cli-template/r/TEST SSE.xml

@@ -1,5 +1,5 @@
-<component name="ProjectRunConfigurationManager">
-  <configuration default="false" name="TEST SSE" type="NodeJSConfigurationType" path-to-js-file="tests/mcp/test-sse.js" working-dir="$PROJECT_DIR$/">
-    <method v="2" />
-  </configuration>
-</component>
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="TEST SSE" type="NodeJSConfigurationType" path-to-js-file="tests/mcp/test-sse.js" working-dir="$PROJECT_DIR$/">
+    <method v="2" />
+  </configuration>
+</component>

package/cli-template/r/TEST STDIO.xml

@@ -1,5 +1,5 @@
-<component name="ProjectRunConfigurationManager">
-  <configuration default="false" name="TEST STDIO" type="NodeJSConfigurationType" path-to-js-file="tests/mcp/test-stdio.js" working-dir="$PROJECT_DIR$">
-    <method v="2" />
-  </configuration>
-</component>
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="TEST STDIO" type="NodeJSConfigurationType" path-to-js-file="tests/mcp/test-stdio.js" working-dir="$PROJECT_DIR$">
+    <method v="2" />
+  </configuration>
+</component>

package/cli-template/r/generate-token.xml

@@ -1,14 +1,14 @@
-<component name="ProjectRunConfigurationManager">
-  <configuration default="false" name="generate-token" type="js.build_tools.npm" nameIsGenerated="true">
-    <package-json value="$PROJECT_DIR$/package.json" />
-    <command value="run" />
-    <scripts>
-      <script value="generate-token" />
-    </scripts>
-    <node-interpreter value="project" />
-    <envs>
-      <env name="DEBUG" value="ntlm:auth-flow,ntlm:ldap-proxy,ntlm:ldap-proxy-id" />
-    </envs>
-    <method v="2" />
-  </configuration>
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="generate-token" type="js.build_tools.npm" nameIsGenerated="true">
+    <package-json value="$PROJECT_DIR$/package.json" />
+    <command value="run" />
+    <scripts>
+      <script value="generate-token" />
+    </scripts>
+    <node-interpreter value="project" />
+    <envs>
+      <env name="DEBUG" value="ntlm:auth-flow,ntlm:ldap-proxy,ntlm:ldap-proxy-id" />
+    </envs>
+    <method v="2" />
+  </configuration>
 </component>

package/cli-template/r/lint-fix-build.xml

@@ -1,12 +1,12 @@
-<component name="ProjectRunConfigurationManager">
-  <configuration default="false" name="lint-fix-build" type="js.build_tools.npm" nameIsGenerated="true">
-    <package-json value="$PROJECT_DIR$/package.json" />
-    <command value="run" />
-    <scripts>
-      <script value="lint-fix-build" />
-    </scripts>
-    <node-interpreter value="project" />
-    <envs />
-    <method v="2" />
-  </configuration>
-</component>
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="lint-fix-build" type="js.build_tools.npm" nameIsGenerated="true">
+    <package-json value="$PROJECT_DIR$/package.json" />
+    <command value="run" />
+    <scripts>
+      <script value="lint-fix-build" />
+    </scripts>
+    <node-interpreter value="project" />
+    <envs />
+    <method v="2" />
+  </configuration>
+</component>

package/cli-template/r/remove-nul.xml

@@ -1,11 +1,11 @@
-<component name="ProjectRunConfigurationManager">
-  <configuration
-      default="false"
-      name="remove-nul.js"
-      type="NodeJSConfigurationType"
-      nameIsGenerated="true"
-      path-to-js-file="scripts/remove-nul.js"
-      working-dir="$PROJECT_DIR$">
-    <method v="2"/>
-  </configuration>
-</component>
+<component name="ProjectRunConfigurationManager">
+  <configuration
+      default="false"
+      name="remove-nul.js"
+      type="NodeJSConfigurationType"
+      nameIsGenerated="true"
+      path-to-js-file="scripts/remove-nul.js"
+      working-dir="$PROJECT_DIR$">
+    <method v="2"/>
+  </configuration>
+</component>

package/config/custom-environment-variables.yaml

@@ -44,6 +44,7 @@ webServer:
     jwtToken:
       encryptKey: WS_TOKEN_ENCRYPT_KEY
       checkMCPName: WS_CHECK_MC_NAME
+      isCheckIP: WS_JWT_CHECK_IP
     basic:
       username: WS_AUTH_BASIC_USERNAME
       password: WS_AUTH_BASIC_PASSWORD

package/config/default.yaml

@@ -176,6 +176,9 @@ webServer:
       encryptKey: '***'
       # If webServer.auth.enabled and the parameter true, the service name and the service specified in the token will be checked
       checkMCPName: true
+      # If true and JWT token contains non-empty 'ip' field,
+      # the client IP will be checked against the allowed list in the token
+      isCheckIP: false
 
     # ========================================================================
     # Basic Authentication - Base64 encoded username:password

package/config/development.yaml

@@ -1,4 +1,4 @@
----
-
-
-
+---
+
+
+

package/config/production.yaml

@@ -1,4 +1,4 @@
----
-
-
-
+---
+
+
+

package/dist/core/_types_/config.d.ts

@@ -16,6 +16,7 @@ interface IWebServerConfig {
             jwtToken: {
                 encryptKey: string;
                 checkMCPName: boolean;
+                isCheckIP: boolean;
             };
             permanentServerTokens: string[];
         };

package/dist/core/_types_/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/core/_types_/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC3D,OAAO,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAGzD,UAAU,gBAAgB;IACxB,SAAS,EAAE;QACT,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,EAAE,MAAM,EAAE,CAAC;QACtB,IAAI,EAAE;YACJ,OAAO,EAAE,OAAO,CAAC;YACjB,KAAK,CAAC,EAAE;gBACN,QAAQ,EAAE,MAAM,CAAC;gBACjB,QAAQ,EAAE,MAAM,CAAC;aAClB,CAAC;YACF,QAAQ,EAAE;gBACR,UAAU,EAAE,MAAM,CAAC;gBACnB,YAAY,EAAE,OAAO,CAAC;aACvB,CAAA;YACD,qBAAqB,EAAE,MAAM,EAAE,CAAC;SACjC,CAAC;QACF,SAAS,EAAE;YACT,OAAO,EAAE,OAAO,CAAC;YACjB,IAAI,EAAE,uBAAuB,GAAG,OAAO,GAAG,UAAU,GAAG,MAAM,CAAC;SAC/D,CAAC;KACH,CAAA;CACF;AAGD,UAAU,aAAa;IACrB,MAAM,EAAE;QACN,KAAK,EAAE,aAAa,CAAC;QACrB,aAAa,EAAE,OAAO,CAAC;QACvB,GAAG,CAAC,EAAE,MAAM,CAAC;KACd,CAAA;CACF;AAED,UAAU,UAAU;IAClB,GAAG,EAAE;QACH,SAAS,EAAE;YACT,WAAW,EAAE,MAAM,CAAC;YACpB,QAAQ,EAAE,MAAM,CAAC;SAClB,CAAC;QACF,YAAY,EAAE,MAAM,GAAG,mBAAmB,CAAA;QAC1C,aAAa,EAAE,OAAO,GAAG,MAAM,CAAC;KACjC,CAAA;CACF;AAED,UAAU,cAAc;IACtB,OAAO,EAAE;QACP,OAAO,CAAC,EAAE;YACR,GAAG,EAAE,MAAM,CAAC;YACZ,WAAW,EAAE,MAAM,CAAC;SACrB,EAAE,CAAC;KACL,CAAA;CACF;AAED,UAAU,kBAAkB;IAC1B,WAAW,CAAC,EAAE;QACZ,OAAO,EAAE,OAAO,CAAC;QACjB,OAAO,EAAE,OAAO,CAAC;QACjB,MAAM,CAAC,EAAE;YACP,MAAM,EAAE,MAAM,CAAC;YACf,OAAO,CAAC,EAAE,MAAM,CAAC;SAClB,CAAC;QACF,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACrC,OAAO,CAAC,EAAE,OAAO,CAAC;KACnB,CAAA;CACF;AAED,UAAU,YAAY;IACpB,KAAK,EAAE;QACL,UAAU,EAAE,GAAG,CAAC;QAChB,QAAQ,EAAE,IAAI,CAAC;KAChB,CAAA;CACF;AAED,MAAM,WAAW,SAAU,SAAQ,SAAS,EAC1C,YAAY,EACZ,aAAa,EACb,kBAAkB,EAClB,gBAAgB,EAChB,UAAU,EACV,cAAc,EACd,kBAAkB;IAElB,YAAY,EAAE,OAAO,CAAC;IAEtB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IAEpB,YAAY,EAAE,aAAa,CAAC;IAC5B,MAAM,EAAE,eAAe,GAAG;QACxB,OAAO,EAAE;YACP,IAAI,EAAE,MAAM,CAAC;YACb,GAAG,EAAE,MAAM,CAAC;SACb,CAAC;KACH,CAAC;IACF,OAAO,EAAE;QACP,OAAO,EAAE,MAAM,CAAC;KACjB,CAAA;CACF"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/core/_types_/config.ts"],"names":[],"mappings":"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"}

package/dist/core/auth/ip-check.d.ts

@@ -0,0 +1,18 @@
+/**
+ * IP address parsing and CIDR matching utilities for JWT IP checking.
+ * Pure TypeScript implementation — no external dependencies.
+ */
+/**
+ * Parses IP string (comma/semicolon/space-separated) into array of trimmed non-empty entries.
+ * Each entry is either a plain IP or a CIDR notation (e.g., "10.0.0.0/24").
+ */
+export declare function parseIpList(ipStr: string): string[];
+/**
+ * Checks if clientIp matches any entry in allowedIps.
+ * Supports:
+ *   - Exact match (IPv4 and IPv6)
+ *   - CIDR subnet match (e.g., 10.0.0.0/24)
+ *   - IPv4-mapped IPv6 normalization (::ffff:x.x.x.x → x.x.x.x)
+ */
+export declare function isIpAllowed(clientIp: string, allowedIps: string[]): boolean;
+//# sourceMappingURL=ip-check.d.ts.map

package/dist/core/auth/ip-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ip-check.d.ts","sourceRoot":"","sources":["../../../src/core/auth/ip-check.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;GAGG;AACH,wBAAgB,WAAW,CAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAQpD;AAmID;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,OAAO,CAK5E"}

package/dist/core/auth/ip-check.js

@@ -0,0 +1,148 @@
+/**
+ * IP address parsing and CIDR matching utilities for JWT IP checking.
+ * Pure TypeScript implementation — no external dependencies.
+ */
+/**
+ * Parses IP string (comma/semicolon/space-separated) into array of trimmed non-empty entries.
+ * Each entry is either a plain IP or a CIDR notation (e.g., "10.0.0.0/24").
+ */
+export function parseIpList(ipStr) {
+    if (!ipStr) {
+        return [];
+    }
+    return ipStr
+        .split(/[,;\s]+/)
+        .map((s) => s.trim())
+        .filter(Boolean);
+}
+/**
+ * Normalizes an IP address string:
+ * - Strips IPv4-mapped IPv6 prefix (::ffff:x.x.x.x → x.x.x.x)
+ * - Trims whitespace
+ */
+function normalizeIp(ip) {
+    ip = ip.trim();
+    // Strip IPv4-mapped IPv6 prefix
+    const mapped = /^::ffff:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/i.exec(ip);
+    if (mapped?.[1]) {
+        return mapped[1];
+    }
+    return ip;
+}
+/**
+ * Parses an IPv4 address string into a 32-bit number.
+ * Returns null if the string is not a valid IPv4 address.
+ */
+function parseIpv4(ip) {
+    const parts = ip.split('.');
+    if (parts.length !== 4) {
+        return null;
+    }
+    let result = 0;
+    for (const part of parts) {
+        const n = Number(part);
+        if (!Number.isInteger(n) || n < 0 || n > 255) {
+            return null;
+        }
+        result = (result << 8) | n;
+    }
+    return result >>> 0; // ensure unsigned
+}
+/**
+ * Parses an IPv6 address string into a BigInt (128-bit).
+ * Supports full and abbreviated (::) notation.
+ * Returns null if the string is not a valid IPv6 address.
+ */
+function parseIpv6(ip) {
+    // Handle IPv4-mapped IPv6
+    const v4mapped = /^::ffff:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/i.exec(ip);
+    if (v4mapped?.[1]) {
+        const v4 = parseIpv4(v4mapped[1]);
+        if (v4 === null) {
+            return null;
+        }
+        return BigInt(0xffff00000000n) | BigInt(v4);
+    }
+    const halves = ip.split('::');
+    if (halves.length > 2) {
+        return null;
+    }
+    let groups = [];
+    if (halves.length === 2) {
+        const left = halves[0] ? halves[0].split(':') : [];
+        const right = halves[1] ? halves[1].split(':') : [];
+        const missing = 8 - left.length - right.length;
+        if (missing < 0) {
+            return null;
+        }
+        groups = [...left, ...Array(missing).fill('0'), ...right];
+    }
+    else {
+        groups = ip.split(':');
+    }
+    if (groups.length !== 8) {
+        return null;
+    }
+    let result = 0n;
+    for (const group of groups) {
+        if (!/^[0-9a-fA-F]{1,4}$/.test(group)) {
+            return null;
+        }
+        result = (result << 16n) | BigInt(parseInt(group, 16));
+    }
+    return result;
+}
+/**
+ * Checks if a client IP matches a single allowed entry (exact IP or CIDR).
+ */
+function matchEntry(clientIp, entry) {
+    const cidrMatch = /^(.+)\/(\d+)$/.exec(entry);
+    if (cidrMatch?.[1] && cidrMatch[2]) {
+        const subnet = normalizeIp(cidrMatch[1]);
+        const prefixLen = Number(cidrMatch[2]);
+        const clientNorm = normalizeIp(clientIp);
+        // Try IPv4
+        const subnetV4 = parseIpv4(subnet);
+        const clientV4 = parseIpv4(clientNorm);
+        if (subnetV4 !== null && clientV4 !== null) {
+            if (prefixLen < 0 || prefixLen > 32) {
+                return false;
+            }
+            if (prefixLen === 0) {
+                return true;
+            }
+            const mask = (~0 << (32 - prefixLen)) >>> 0;
+            return (subnetV4 & mask) === (clientV4 & mask);
+        }
+        // Try IPv6
+        const subnetV6 = parseIpv6(subnet);
+        const clientV6 = parseIpv6(clientNorm);
+        if (subnetV6 !== null && clientV6 !== null) {
+            if (prefixLen < 0 || prefixLen > 128) {
+                return false;
+            }
+            if (prefixLen === 0) {
+                return true;
+            }
+            const shift = BigInt(128 - prefixLen);
+            return (subnetV6 >> shift) === (clientV6 >> shift);
+        }
+        return false;
+    }
+    // Exact match
+    return normalizeIp(clientIp) === normalizeIp(entry);
+}
+/**
+ * Checks if clientIp matches any entry in allowedIps.
+ * Supports:
+ *   - Exact match (IPv4 and IPv6)
+ *   - CIDR subnet match (e.g., 10.0.0.0/24)
+ *   - IPv4-mapped IPv6 normalization (::ffff:x.x.x.x → x.x.x.x)
+ */
+export function isIpAllowed(clientIp, allowedIps) {
+    if (!clientIp || !allowedIps.length) {
+        return false;
+    }
+    return allowedIps.some((entry) => matchEntry(clientIp, entry));
+}
+//# sourceMappingURL=ip-check.js.map

package/dist/core/auth/ip-check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ip-check.js","sourceRoot":"","sources":["../../../src/core/auth/ip-check.ts"],"names":[],"mappings":"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"}

package/dist/core/auth/jwt.d.ts

@@ -25,5 +25,6 @@ export declare const checkJwtToken: (arg: {
     token: string;
     expectedUser?: string;
     expectedService?: string;
+    clientIp?: string;
 }) => ICheckTokenResult;
 //# sourceMappingURL=jwt.d.ts.map

package/dist/core/auth/jwt.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"jwt.d.ts","sourceRoot":"","sources":["../../../src/core/auth/jwt.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,iBAAiB,EAAiB,MAAM,YAAY,CAAC;AAU9D,eAAO,MAAM,sBAAsB,IAAI,CAAC;AASxC,eAAO,MAAM,UAAU,QAAmC,CAAC;AAE3D;;GAEG;AACH,eAAO,MAAM,OAAO,GAAI,MAAM,MAAM,KAAG,MAStC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,OAAO,GAAI,cAAc,MAAM,WAW3C,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,aAAa,GAAI,MAAM,MAAM,EAAE,aAAa,MAAM,EAAE,UAAU,GAAG,KAAG,MAYhF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,aAAa,GAAI,KAAK;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B,KAAG,iBAqEH,CAAC"}
+{"version":3,"file":"jwt.d.ts","sourceRoot":"","sources":["../../../src/core/auth/jwt.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,iBAAiB,EAAiB,MAAM,YAAY,CAAC;AAY9D,eAAO,MAAM,sBAAsB,IAAI,CAAC;AASxC,eAAO,MAAM,UAAU,QAAmC,CAAC;AAE3D;;GAEG;AACH,eAAO,MAAM,OAAO,GAAI,MAAM,MAAM,KAAG,MAStC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,OAAO,GAAI,cAAc,MAAM,WAW3C,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,aAAa,GAAI,MAAM,MAAM,EAAE,aAAa,MAAM,EAAE,UAAU,GAAG,KAAG,MAYhF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,aAAa,GAAI,KAAK;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,KAAG,iBAmFH,CAAC"}

package/dist/core/auth/jwt.js

@@ -3,10 +3,12 @@ import crypto from 'crypto';
 import { appConfig } from '../bootstrap/init-config.js';
 import { logger as lgr } from '../logger.js';
 import { isObject, trim } from '../utils/utils.js';
+import { parseIpList, isIpAllowed } from './ip-check.js';
 import chalk from 'chalk';
 const logger = lgr.getSubLogger({ name: chalk.cyan('token-auth') });
 const { jwtToken } = appConfig.webServer?.auth || {};
 const checkMCPName = jwtToken?.checkMCPName || false;
+const isCheckIP = jwtToken?.isCheckIP || false;
 export const MIN_ENCRYPT_KEY_LENGTH = 8;
 const ALGORITHM = 'aes-256-ctr';
 const KEY = crypto
@@ -68,7 +70,7 @@ export const generateToken = (user, liveTimeSec, payload) => {
  * - If a user is transferred, it must match
  */
 export const checkJwtToken = (arg) => {
-    let { token, expectedUser, expectedService = appConfig.name } = arg;
+    let { token, expectedUser, expectedService = appConfig.name, clientIp } = arg;
     token = (token || '').trim();
     if (!token) {
         return {
@@ -130,6 +132,18 @@ export const checkJwtToken = (arg) => {
             errorReason: `JWT Token expired :: on ${expiredOn} mc`,
         };
     }
+    // IP check (after all other validations pass)
+    if (isCheckIP && payload.ip) {
+        if (clientIp) {
+            const allowedIps = parseIpList(payload.ip);
+            if (allowedIps.length > 0 && !isIpAllowed(clientIp, allowedIps)) {
+                return {
+                    isTokenDecrypted: true,
+                    errorReason: `JWT Token: client IP ${clientIp} is not in the allowed list`,
+                };
+            }
+        }
+    }
     // OK!
     return { payload };
 };