@ekoindia/eps-context-mcp 0.1.13 → 0.1.15

package/README.md

@@ -45,6 +45,7 @@ clients can see this programmatically.
 | `get_topic`           | `topic` (`auth` \| `errors` \| `pricing` \| `environments`)                  | One documentation topic.                                                                                                                           |
 | `get_recipe`          | `id`                                                                         | One multi-step recipe (steps + branches).                                                                                                          |
 | `get_signing_snippet` | `language` (`php` \| `java` \| `csharp` \| `javascript` \| `python` \| `go`) | Paste-ready **backend** code to compute the request `secret-key`.                                                                                  |
+| `debug_auth`          | `timestamp?`, `secret_key?`                                                  | Diagnose a `403`: returns a known-answer test vector to check your signing against, mechanical checks on a supplied timestamp/signature, and ranked causes. **Never takes an `access_key`.** |
 | `get_meta`            | —                                                                            | Bundle org/version, data source (`baked` or `remote`), this server's `packageVersion`, and `updateAvailable` (whether a newer npm release exists). |
 
 **Tiered usage:** start with `list_apis` / `search` (cheap, compact), then call
@@ -206,6 +207,25 @@ languages. **This code is backend-only.**
   key. This MCP server holds **no credentials** and performs **no signing or API
   calls** itself; it only provides context and code.
 
+### Debugging a 403 without handing over a key
+
+`debug_auth` is **secret-free by design** and there is no plan to add an
+`access_key` parameter. Two reasons, both structural:
+
+1. This server is also reachable **anonymously over HTTP**, so a key in a tool
+   argument would travel to infrastructure that deliberately holds no secrets.
+2. A tool argument lands in the **caller's model context** and its transcript.
+   Today an agent writes `process.env.EKO_ACCESS_KEY` and never sees the value;
+   a signing tool would teach it to read the secret out and paste it into a chat.
+
+Instead the tool hands back a **known-answer test vector** — a dummy key, a
+fixed timestamp, and the signature they must produce. Reproduce it with your own
+code and the algorithm is proven; the 403 is then almost always provisioning
+(IP allowlist, inactive key, wrong environment), which `ranked_causes` walks in
+likelihood order. If you want a server that signs with real credentials, that is
+`@ekoindia/eps-transact-mcp`, which takes them from the environment or per-request
+headers — never as tool arguments.
+
 ## License
 
 MIT

package/data/eps.json

@@ -2,7 +2,7 @@
   "meta": {
     "org": "ekoindia",
     "apiVersion": "v3",
-    "bundleVersion": "c9e5f932",
+    "bundleVersion": "3f05bd61",
     "environments": [
       {
         "id": "sandbox",
@@ -70,7 +70,12 @@
         "Generate the current timestamp in milliseconds (as a string).",
         "Compute HMAC-SHA256 of the timestamp using the base64-encoded key.",
         "Base64-encode the resulting signature — this is the secret-key."
-      ]
+      ],
+      "testVector": {
+        "accessKey": "test-access-key-123",
+        "timestamp": "1700000000000",
+        "secretKey": "88lqTf9ew69XbVbeczjxVL8/B4vibfp1MvTi1mIj2Xo="
+      }
     },
     "errors": {
       "id": "errors",
@@ -7080,6 +7085,177 @@
       ],
       "responseTypes": []
     },
+    {
+      "slug": "pan-fetch",
+      "productId": "pan",
+      "productName": "PAN Verification",
+      "name": "Fetch PAN Details",
+      "method": "POST",
+      "path": "/tools/kyc/fetch-pan",
+      "summary": "Fetch the PAN holder's registered full name and category from the PAN number alone.",
+      "category": "verification",
+      "relevance": "H",
+      "description": "Fetch PAN is the lightest PAN lookup: pass only the PAN number and get back the registered full name, the holder category (person / company / firm …) and the PAN status. Unlike PAN Lite and PAN Advanced — which require the PAN number, holder name and date of birth to compute match flags — this endpoint needs no name or DOB, so use it when you have to *discover* the holder's name rather than verify one you already hold.",
+      "bestFor": "Resolving a PAN number to its registered name when no name or DOB is available",
+      "docsUrl": "https://eps.eko.in/docs/pan-fetch",
+      "headers": [
+        {
+          "name": "developer_key",
+          "in": "header",
+          "type": "string",
+          "required": true,
+          "description": "Static API key issued to your account after KYC."
+        },
+        {
+          "name": "secret-key",
+          "in": "header",
+          "type": "string",
+          "required": true,
+          "description": "Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key)))."
+        },
+        {
+          "name": "secret-key-timestamp",
+          "in": "header",
+          "type": "string",
+          "required": true,
+          "description": "Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time."
+        },
+        {
+          "name": "content-type",
+          "in": "header",
+          "type": "string",
+          "required": true,
+          "description": "application/json",
+          "example": "application/json"
+        }
+      ],
+      "requestParams": [
+        {
+          "name": "initiator_id",
+          "type": "string",
+          "required": true,
+          "description": "Registered mobile number of the API user (see Platform Credentials).",
+          "example": "9962981729",
+          "in": "body"
+        },
+        {
+          "name": "client_ref_id",
+          "type": "string",
+          "required": false,
+          "description": "Unique reference ID per API call, generated by your system (max 20 characters).",
+          "example": "2026010100123456789",
+          "in": "body"
+        },
+        {
+          "name": "pan_number",
+          "label": "PAN Number",
+          "type": "string",
+          "required": true,
+          "description": "10-character alphanumeric PAN identifier (5 letters, 4 digits, 1 letter).",
+          "example": "GGTPB7880Q",
+          "in": "body"
+        },
+        {
+          "name": "source",
+          "type": "string",
+          "required": false,
+          "description": "Origin of the request. Use 'API' for server-to-server calls.",
+          "example": "API",
+          "in": "body"
+        }
+      ],
+      "sampleRequest": {
+        "initiator_id": "9962981729",
+        "client_ref_id": "2026010100123456789",
+        "pan_number": "GGTPB7880Q",
+        "source": "API"
+      },
+      "responseFields": [
+        {
+          "name": "status",
+          "type": "number",
+          "description": "Primary success indicator (0 = success).",
+          "example": 0
+        },
+        {
+          "name": "message",
+          "type": "string",
+          "description": "Human-readable response / error message.",
+          "example": "Verification successful"
+        },
+        {
+          "name": "response_status_id",
+          "type": "number",
+          "description": "Granular status id; see the shared error-codes table.",
+          "example": 0
+        },
+        {
+          "name": "response_type_id",
+          "type": "number",
+          "description": "A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.",
+          "example": 1388
+        },
+        {
+          "name": "data",
+          "type": "object",
+          "description": "API-specific response payload.",
+          "children": [
+            {
+              "name": "upstream_rrn",
+              "label": "Upstream Reference",
+              "type": "string",
+              "description": "Reference number of the lookup at the upstream source.",
+              "example": "pan_ZLpBnmwapOwtixPUmijB"
+            },
+            {
+              "name": "pan_no",
+              "label": "PAN Number",
+              "type": "string",
+              "description": "The PAN number submitted in the request.",
+              "imp": true,
+              "example": "GGTPB7880Q"
+            },
+            {
+              "name": "fullname",
+              "label": "Full Name",
+              "type": "string",
+              "description": "Full name registered against the PAN.",
+              "imp": true,
+              "example": "YASHWANT BASNETT"
+            },
+            {
+              "name": "category",
+              "type": "string",
+              "description": "PAN holder category, e.g. 'person', 'company', 'firm', 'trust', 'huf'.",
+              "imp": true,
+              "example": "person"
+            },
+            {
+              "name": "status",
+              "label": "Lookup Status",
+              "type": "string",
+              "description": "Outcome of the PAN lookup, e.g. 'success'.",
+              "imp": true,
+              "example": "success"
+            }
+          ]
+        }
+      ],
+      "sampleSuccessResponse": {
+        "response_status_id": 0,
+        "data": {
+          "upstream_rrn": "pan_ZLpBnmwapOwtixPUmijB",
+          "pan_no": "GGTPB7880Q",
+          "fullname": "YASHWANT BASNETT",
+          "category": "person",
+          "status": "success"
+        },
+        "response_type_id": 0,
+        "status": 0
+      },
+      "errorScenarios": [],
+      "responseTypes": []
+    },
     {
       "slug": "pan-lite",
       "productId": "pan",

package/dist/index.js

@@ -67,6 +67,152 @@ var getApi = (bundle, slug) => bundle.apis.find((a) => a.slug === slug);
 var getTopic = (bundle, topic) => bundle.topics[topic];
 var getRecipe = (bundle, id) => bundle.recipes.find((r) => r.id === id);
 
+// src/auth-debug.ts
+var MS_DIGITS = 13;
+var SECONDS_DIGITS = 10;
+var DRIFT_WARN_MS = 5 * 60 * 1e3;
+var supplied = (value) => {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : void 0;
+};
+var checkTimestamp = (value, nowMs) => {
+  const timestamp = supplied(value);
+  if (!timestamp)
+    return [
+      {
+        name: "timestamp",
+        ok: null,
+        detail: "No timestamp supplied. Pass the exact secret-key-timestamp you sent."
+      }
+    ];
+  if (!/^\d+$/.test(timestamp))
+    return [
+      {
+        name: "timestamp_format",
+        ok: false,
+        detail: "Not a plain digit string. The timestamp is signed verbatim, so quotes, a decimal point, a '+' or whitespace all change the signature."
+      }
+    ];
+  if (timestamp.length === SECONDS_DIGITS)
+    return [
+      {
+        name: "timestamp_unit",
+        ok: false,
+        detail: "10 digits \u2014 these are epoch SECONDS. Eko expects MILLISECONDS (13 digits): use Date.now(), time.time()*1000, or System.currentTimeMillis()."
+      }
+    ];
+  if (timestamp.length !== MS_DIGITS)
+    return [
+      {
+        name: "timestamp_unit",
+        ok: false,
+        detail: `${timestamp.length} digits \u2014 epoch milliseconds is ${MS_DIGITS}. Check for a truncated or padded value.`
+      }
+    ];
+  const driftMs = Number(timestamp) - nowMs;
+  const magnitude = Math.abs(driftMs);
+  const direction = driftMs > 0 ? "in the future" : "in the past";
+  return [
+    { name: "timestamp_unit", ok: true, detail: "13 digits \u2014 milliseconds." },
+    {
+      name: "clock_drift",
+      ok: magnitude <= DRIFT_WARN_MS,
+      detail: magnitude <= DRIFT_WARN_MS ? `${driftMs} ms from this server's clock \u2014 within the ${DRIFT_WARN_MS} ms heuristic.` : `${magnitude} ms ${direction} vs this server's clock (heuristic threshold ${DRIFT_WARN_MS} ms). Either the machine's clock is wrong (check NTP) or the timestamp is being reused instead of regenerated per request.`
+    }
+  ];
+};
+var checkSignatureShape = (value) => {
+  const signature = supplied(value);
+  if (!signature)
+    return [
+      {
+        name: "signature_shape",
+        ok: null,
+        detail: "No secret-key supplied. Pass the signature your code produced \u2014 never the access_key it was derived from."
+      }
+    ];
+  if (value !== signature)
+    return [
+      {
+        name: "signature_shape",
+        ok: false,
+        detail: "Leading/trailing whitespace or a trailing newline. Header values are sent verbatim \u2014 strip it (a common artefact of reading the key from a file)."
+      }
+    ];
+  if (/^[0-9a-f]{64}$/i.test(signature))
+    return [
+      {
+        name: "signature_shape",
+        ok: false,
+        detail: "64 hex characters \u2014 this is the raw HMAC digest. The final base64 step was skipped: base64-encode the digest bytes."
+      }
+    ];
+  if (/[-_]/.test(signature))
+    return [
+      {
+        name: "signature_shape",
+        ok: false,
+        detail: "Contains '-' or '_' \u2014 URL-safe base64. Eko expects the standard alphabet ('+' and '/'), padded with '='."
+      }
+    ];
+  const decoded = Buffer.from(signature, "base64");
+  if (decoded.toString("base64") !== signature)
+    return [
+      {
+        name: "signature_shape",
+        ok: false,
+        detail: "Not canonical base64 \u2014 wrong padding or an out-of-alphabet character."
+      }
+    ];
+  if (decoded.length !== 32)
+    return [
+      {
+        name: "signature_shape",
+        ok: false,
+        detail: `Decodes to ${decoded.length} bytes; SHA-256 is 32. Check the hash algorithm \u2014 SHA-1 gives 20, SHA-512 gives 64.`
+      }
+    ];
+  return [
+    {
+      name: "signature_shape",
+      ok: true,
+      detail: "Canonical base64 of 32 bytes \u2014 the right shape for HMAC-SHA256. Shape alone cannot prove the value: run the test vector."
+    }
+  ];
+};
+var RANKED_403_CAUSES = [
+  {
+    id: "ip_not_allowlisted",
+    cause: "The calling server's public IP is not allowlisted for that key.",
+    fix: "Send your egress IP to Eko support. Note that serverless/dynamic egress (Vercel, Lambda) cannot be allowlisted \u2014 call from a fixed-IP host."
+  },
+  {
+    id: "key_inactive",
+    cause: "The key is not active, or not provisioned for that environment.",
+    fix: "Confirm with Eko that the keypair is live for the environment you are calling."
+  },
+  {
+    id: "environment_mismatch",
+    cause: "UAT credentials sent to the production base URL, or the reverse \u2014 the keys are environment-specific.",
+    fix: "Check the base URL against the environments topic; the developer_key and access_key must come from the same environment."
+  },
+  {
+    id: "header_name_typo",
+    cause: "Header spelled wrongly: `secret_key`/`secretKey` instead of `secret-key`, or `developer-key` instead of `developer_key`.",
+    fix: "Header names are exactly: developer_key, secret-key, secret-key-timestamp, content-type."
+  },
+  {
+    id: "timestamp_mismatch",
+    cause: "The signed timestamp is not the one sent in `secret-key-timestamp` \u2014 often a second Date.now() call, or a value cached across requests.",
+    fix: "Compute the timestamp once, sign that exact string, and send the same string."
+  },
+  {
+    id: "key_decoded_before_signing",
+    cause: "The base64 of the access_key was decoded back to bytes before being used as the HMAC key.",
+    fix: "The HMAC key is the base64 STRING itself, used as-is. Confirm with the test vector."
+  }
+];
+
 // src/signing-snippets.ts
 var SIGNING_LANGUAGES = [
   "php",
@@ -290,6 +436,28 @@ var createEpsServer = (bundle, source, versionState) => {
       content: [{ type: "text", text: getSigningSnippet(language) }]
     })
   );
+  server.registerTool(
+    "debug_auth",
+    {
+      title: "Debug auth / 403",
+      description: "Diagnose a 403 from an EPS API. Returns a known-answer TEST VECTOR: run your own signing code over test_vector.accessKey + test_vector.timestamp \u2014 if you reproduce test_vector.secretKey, your HMAC is correct, so stop debugging the algorithm and work through ranked_causes instead. Optionally pass the timestamp and secret-key from the failing request and they are checked for the mechanical faults (seconds instead of milliseconds, clock drift, wrong digest length, stray newline). SECRET-FREE BY DESIGN: there is no access_key parameter and there never will be \u2014 never paste an access_key into a tool call; it is a server-side secret.",
+      inputSchema: {
+        timestamp: z.string().optional().describe("The secret-key-timestamp sent on the failing request."),
+        secret_key: z.string().optional().describe("The secret-key your code produced. Never the access_key.")
+      },
+      annotations: READ_ONLY
+    },
+    async ({ timestamp, secret_key }) => json({
+      test_vector: bundle.topics.auth.testVector,
+      how_to_use_test_vector: "secret-key = base64(HMAC_SHA256(key = base64(access_key) AS A STRING, message = timestamp)). Reproduce test_vector.secretKey from the vector's inputs to prove your implementation.",
+      checks: [
+        ...checkTimestamp(timestamp, Date.now()),
+        ...checkSignatureShape(secret_key)
+      ],
+      ranked_causes: RANKED_403_CAUSES,
+      docs_url: bundle.topics.auth.docsUrl
+    })
+  );
   server.registerTool(
     "get_meta",
     {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ekoindia/eps-context-mcp",
-	"version": "0.1.13",
+	"version": "0.1.15",
 	"description": "Local MCP server giving AI coding agents context for Eko Platform Services (EPS) APIs.",
 	"license": "MIT",
 	"type": "module",