@ekoindia/eps-context-mcp 0.1.12 → 0.1.14

package/README.md

@@ -39,12 +39,13 @@ clients can see this programmatically.
 | --------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `list_apis`           | `category?`, `limit?`                                                        | Compact index of EPS endpoints (no request/response bodies). `category` is validated against the bundle's categories; all entries by default.      |
 | `list_topics`         | —                                                                            | Documentation topic ids: `auth`, `errors`, `pricing`, `environments`.                                                                              |
-| `list_recipes`        | —                                                                            | Multi-step recipe ids + names (e.g. `dmt-fino-send-money`, `aeps-cash-withdrawal`).                                                                     |
+| `list_recipes`        | —                                                                            | Multi-step recipe ids + names (e.g. `dmt-fino-send-money`, `aeps-fingpay-cash-withdrawal`).                                                                     |
 | `search`              | `query`, `limit?`                                                            | Ranked endpoint matches for a query (ids only, no bodies). Top 10 by default; raise `limit` for more.                                              |
 | `get_api`             | `slug`                                                                       | Full detail for one endpoint (params, response fields, errors, examples).                                                                          |
 | `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": "720a494b",
+    "bundleVersion": "a5376048",
     "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",
@@ -8050,394 +8055,6 @@
       ],
       "responseTypes": []
     },
-    {
-      "slug": "aadhaar-dmt-levin-validate",
-      "productId": "dmt",
-      "productName": "Domestic Money Transfer (DMT)",
-      "name": "Validate Aadhaar & Generate OTP",
-      "method": "POST",
-      "path": "/customer/payment/dmt-levin/sender/{customer_id}/aadhaar/otp",
-      "summary": "Validate a sender's Aadhaar number and trigger an OTP to the linked mobile for DMT Levin onboarding.",
-      "category": "bc",
-      "relevance": "M",
-      "description": "Submits the sender's Aadhaar number via the DMT Levin channel to initiate OTP-based Aadhaar validation. The `otp_ref_id` from the sender's existing profile plus the Aadhaar number are required. Returns a new `otp_ref_id` for the validation session. Part of the Levin DMT sender onboarding flow.",
-      "bestFor": "DMT Levin sender onboarding flows that require Aadhaar number validation as a step before completing identity verification.",
-      "docsUrl": "https://eps.eko.in/docs/aadhaar-dmt-levin-validate",
-      "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": "customer_id",
-          "type": "integer",
-          "required": true,
-          "description": "Sender's mobile number.",
-          "example": 9876543210,
-          "in": "path"
-        },
-        {
-          "name": "aadhar",
-          "type": "string",
-          "required": true,
-          "description": "12-digit Aadhaar number of the sender.",
-          "example": "123456789012",
-          "in": "body"
-        },
-        {
-          "name": "otp_ref_id",
-          "type": "string",
-          "required": true,
-          "description": "Reference ID returned from the Get Sender Info (or Create Sender) API for this customer.",
-          "example": "73849201",
-          "in": "body"
-        },
-        {
-          "name": "additional_info",
-          "type": "string",
-          "required": true,
-          "description": "Additional info flag. Defaults to 1.",
-          "example": "1",
-          "in": "body"
-        }
-      ],
-      "sampleRequest": {
-        "initiator_id": "9962981729",
-        "client_ref_id": "2026010100123456789",
-        "aadhar": "123456789012",
-        "otp_ref_id": "73849201",
-        "additional_info": "1"
-      },
-      "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": "otp_ref_id",
-              "type": "string",
-              "description": "New OTP reference ID for the Aadhaar validation session. Pass to Validate Sender Aadhaar OTP.",
-              "example": "93847201"
-            },
-            {
-              "name": "mobile_hint",
-              "type": "string",
-              "description": "Masked mobile number to which the OTP was dispatched.",
-              "example": "******3210"
-            }
-          ]
-        }
-      ],
-      "sampleSuccessResponse": {
-        "status": 0,
-        "response_status_id": 0,
-        "message": "Aadhaar OTP dispatched successfully",
-        "response_type_id": 1388,
-        "data": {
-          "otp_ref_id": "93847201",
-          "mobile_hint": "******3210"
-        }
-      },
-      "errorScenarios": [
-        {
-          "scenario": "Invalid Aadhaar number",
-          "statusCode": 200,
-          "example": {
-            "status": 1,
-            "response_status_id": 301,
-            "message": "Invalid Aadhaar number provided.",
-            "response_type_id": 1388,
-            "data": {}
-          }
-        }
-      ],
-      "responseTypes": []
-    },
-    {
-      "slug": "aadhaar-dmt-levin-verify-otp",
-      "productId": "dmt",
-      "productName": "Domestic Money Transfer (DMT)",
-      "name": "Validate Sender Aadhaar OTP",
-      "method": "POST",
-      "path": "/customer/payment/dmt-levin/sender/{customer_id}/aadhaar/otp/verify",
-      "summary": "Verify the Aadhaar OTP for a DMT Levin sender to complete identity validation.",
-      "category": "bc",
-      "relevance": "M",
-      "description": "Validates the OTP received on the sender's Aadhaar-linked mobile number in the DMT Levin flow. Use `intent_id: 20` for Aadhaar validation (as opposed to `intent_id: 19` for sender onboarding). On success, the sender's identity is confirmed and their DMT Levin wallet profile is updated.",
-      "bestFor": "Completing OTP-based Aadhaar validation in the DMT Levin sender onboarding flow.",
-      "docsUrl": "https://eps.eko.in/docs/aadhaar-dmt-levin-verify-otp",
-      "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": "customer_id",
-          "type": "string",
-          "required": true,
-          "description": "Sender's mobile number.",
-          "example": "9876543210",
-          "in": "path"
-        },
-        {
-          "name": "otp",
-          "type": "integer",
-          "required": false,
-          "description": "OTP received on the Aadhaar-linked mobile number.",
-          "example": 123456,
-          "in": "body"
-        },
-        {
-          "name": "otp_ref_id",
-          "type": "integer",
-          "required": true,
-          "description": "Reference ID from the Validate Aadhaar (DMT Levin) response.",
-          "example": 93847201,
-          "in": "body"
-        },
-        {
-          "name": "intent_id",
-          "type": "string",
-          "required": false,
-          "description": "Set to \"19\" for sender onboarding or \"20\" for Aadhaar validation.",
-          "example": "20",
-          "in": "body"
-        },
-        {
-          "name": "additional_info",
-          "type": "string",
-          "required": false,
-          "description": "Additional info flag. Defaults to 1.",
-          "example": "1",
-          "in": "body"
-        }
-      ],
-      "sampleRequest": {
-        "initiator_id": "9962981729",
-        "client_ref_id": "2026010100123456789",
-        "otp": 123456,
-        "otp_ref_id": 93847201,
-        "intent_id": "20",
-        "additional_info": "1"
-      },
-      "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": "verified",
-              "type": "boolean",
-              "description": "True if Aadhaar OTP validation was successful.",
-              "imp": true,
-              "example": true
-            },
-            {
-              "name": "name",
-              "type": "string",
-              "description": "Verified sender name from Aadhaar.",
-              "imp": true,
-              "example": "Arjun Mehta"
-            },
-            {
-              "name": "gender",
-              "type": "string",
-              "description": "Gender from Aadhaar record.",
-              "imp": true,
-              "example": "M"
-            },
-            {
-              "name": "dob",
-              "type": "string",
-              "description": "Date of birth from Aadhaar.",
-              "imp": true,
-              "example": "10-01-1988"
-            },
-            {
-              "name": "masked_aadhaar",
-              "type": "string",
-              "description": "Aadhaar number with first 8 digits masked.",
-              "imp": true,
-              "example": "XXXX-XXXX-3456"
-            }
-          ]
-        }
-      ],
-      "sampleSuccessResponse": {
-        "status": 0,
-        "response_status_id": 0,
-        "message": "Aadhaar OTP verified successfully",
-        "response_type_id": 1388,
-        "data": {
-          "verified": true,
-          "name": "Arjun Mehta",
-          "gender": "M",
-          "dob": "10-01-1988",
-          "masked_aadhaar": "XXXX-XXXX-3456"
-        }
-      },
-      "errorScenarios": [
-        {
-          "scenario": "Wrong OTP",
-          "statusCode": 200,
-          "example": {
-            "status": 1,
-            "response_status_id": 302,
-            "message": "Wrong OTP. Please check and retry.",
-            "response_type_id": 1388,
-            "data": {}
-          }
-        },
-        {
-          "scenario": "OTP expired",
-          "statusCode": 200,
-          "example": {
-            "status": 1,
-            "response_status_id": 303,
-            "message": "OTP expired. Please regenerate.",
-            "response_type_id": 1388,
-            "data": {}
-          }
-        }
-      ],
-      "responseTypes": []
-    },
     {
       "slug": "aadhaar-ppi-levin-validate",
       "productId": "ppi",
@@ -23050,38 +22667,84 @@
       "id": "dmt-fino-send-money",
       "slug": "dmt-fino-send-money",
       "name": "DMT (Fino) — Send Money",
-      "summary": "Full Fino DMT money-transfer flow: look up the sender, onboard them if new, add the recipient, then send an OTP-verified transfer.",
+      "summary": "Full Fino DMT money-transfer flow: look up the sender, onboard and biometric-eKYC them if new, pick or add the recipient, then send an OTP-verified transfer.",
       "productId": "dmt",
       "steps": [
         {
           "specSlug": "dmt-get-sender",
-          "purpose": "Check whether the customer is already a registered DMT sender.",
+          "purpose": "Check whether the customer is already a registered DMT sender, and which stage of onboarding they are at. The `response_type_id` decides where the flow enters.",
           "branches": [
             {
               "onResponseTypeId": 308,
               "goto": "dmt-onboard-sender",
               "note": "Sender not found — onboard them before continuing."
+            },
+            {
+              "onResponseTypeId": 2134,
+              "goto": "dmt-fino-sender-ekyc",
+              "note": "Sender found but biometric eKYC is pending — capture their fingerprint."
+            },
+            {
+              "onResponseTypeId": 2129,
+              "goto": "dmt-fino-validate-ekyc-otp",
+              "note": "Sender found mid-eKYC — only the OTP validation is left."
+            },
+            {
+              "onResponseTypeId": 309,
+              "goto": "dmt-get-recipients",
+              "note": "Sender found and KYC complete — skip onboarding and go straight to recipients."
             }
           ]
         },
         {
           "specSlug": "dmt-onboard-sender",
-          "purpose": "Register a new sender when Get Sender API returns `response_type_id=308`."
+          "purpose": "Register a new sender with name, date of birth and residence address. This opens the sender on Eko but leaves KYC pending on Fino (`response_type_id=2134`) — they cannot transact yet.",
+          "branches": [
+            {
+              "onResponseTypeId": 309,
+              "goto": "dmt-get-recipients",
+              "note": "Already onboarded on Fino externally, KYC complete — no eKYC needed."
+            }
+          ]
+        },
+        {
+          "specSlug": "dmt-fino-sender-ekyc",
+          "purpose": "Biometric Aadhaar eKYC — one-time per sender. Capture the PID block from an RD-service fingerprint scanner and submit it with the sender's Aadhaar number; the response returns the `kyc_request_id` and `otp_ref_id` the next step needs. Completing eKYC raises the sender's monthly limit from ₹5,000 to ₹25,000."
+        },
+        {
+          "specSlug": "dmt-fino-validate-ekyc-otp",
+          "purpose": "Confirm the eKYC by submitting the OTP sent to the sender's Aadhaar-linked mobile, along with the `kyc_request_id` and `otp_ref_id` from the biometric step. The sender is fully KYC-verified on success."
+        },
+        {
+          "specSlug": "dmt-get-recipients",
+          "purpose": "List the sender's saved beneficiaries. If the one they want is already there, reuse its `recipient_id` and skip Add Recipient.",
+          "branches": [
+            {
+              "onResponseTypeId": 22,
+              "goto": "dmt-add-recipient",
+              "note": "No recipients saved yet — add one before transacting."
+            },
+            {
+              "onResponseTypeId": 23,
+              "goto": "dmt-send-otp",
+              "note": "Recipient already saved — reuse its `recipient_id`."
+            }
+          ]
         },
         {
           "specSlug": "dmt-add-recipient",
-          "purpose": "Add the beneficiary the sender wants to transfer to."
+          "purpose": "Add the beneficiary the sender wants to transfer to; returns the `recipient_id` used by the two transaction steps."
         },
         {
           "specSlug": "dmt-send-otp",
-          "purpose": "Trigger the transaction OTP sent to the sender."
+          "purpose": "Pre-authorise the transfer: sends an OTP to the sender's registered mobile and returns the `otp_ref_id`. Required before every transfer — request a fresh one per attempt."
         },
         {
           "specSlug": "dmt-initiate-transfer",
-          "purpose": "Submit the OTP-verified transfer to complete the flow.",
+          "purpose": "Submit the transfer with the customer-entered OTP, its `otp_ref_id`, and a `client_ref_id` unique to this attempt. The only money-debit step — persist `tid` and `bank_ref_num` and reconcile before any retry.",
           "branches": [
             {
-              "onResponseStatusId": 0,
+              "onStatus": 0,
               "goto": "done"
             }
           ]
@@ -23125,7 +22788,7 @@
           "purpose": "Perform the biometric Aadhaar-enabled cash withdrawal.",
           "branches": [
             {
-              "onResponseStatusId": 0,
+              "onStatus": 0,
               "goto": "done"
             }
           ]

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.12",
+	"version": "0.1.14",
 	"description": "Local MCP server giving AI coding agents context for Eko Platform Services (EPS) APIs.",
 	"license": "MIT",
 	"type": "module",