@xrpl-utilities/mcp 0.2.194 → 0.2.201

package/README.md

@@ -40,7 +40,18 @@ sign and retry against whichever rail its wallet supports.
 
 Operators can set `MCP_BYPASS_KEY` on the server to enable an opt-in
 bypass for friendlies / demos. The caller passes the matching key as
-`_bypass_key` in the tool args. Rate-limited at the proxy layer.
+`_bypass_key` in the tool args.
+
+The hosted endpoint budgets failed `_bypass_key` attempts per caller
+separately from, and far more tightly than, ordinary requests: a 60
+requests-per-minute cap is a fair-use limit, not an access control on a
+secret. The budget is spent per guess, not per HTTP request, so a batched
+JSON-RPC body cannot outrun it, and only requests that actually carry a
+`_bypass_key` are held off once it is exhausted - `tools/list`, free tools
+and paid x402 calls keep working. Batches are capped at 20 messages. Use a key of at least 32 random bytes, and scope or rotate it
+per service rather than sharing one portfolio-wide key. Bucket keying
+depends on `TRUST_PROXY_HOPS` matching the real number of proxies in
+front of the container - see `.env.example`.
 
 ### H-Seal receipt co-signing (optional)
 
@@ -51,7 +62,16 @@ provider attestation. The attestation rides on the tool result's
 `_meta.hSeal`, so a caller can anchor a tamper-evident, independently
 verifiable on-chain receipt of the interaction. When either var is unset the
 feature is inert and responses are unchanged. Never hardcode the key — env
-only. See `src/hSeal.ts` and the ops runbook
+only.
+
+When a backend co-signs its own output, the MCP also builds a 2-party
+receipt (`_meta.hSealReceipt`). That signs with the operator key, so set
+`HSEAL_ALLOWED_PROVIDERS` to the CAIP-10 identities of the XR-* backends
+you are willing to vouch for. Without it any provider that proves it holds
+the key for the identity it names is accepted. The `responseHash` is always
+recomputed from the delivered body; `requestHash` stays provider-asserted
+(the backends hash a synthetic request object the MCP cannot reproduce) and
+the result says so via `requestHashBasis`. See `src/hSeal.ts` and the ops runbook
 [`docs/hseal-provider.md`](docs/hseal-provider.md) (current identity, the
 ed25519 curve gotcha, and how to rotate/recover the key).
 
@@ -106,11 +126,19 @@ useful as templates in any language.
 npm install
 npm run build
 node dist/index.js --transport http --port 8080
+npm test          # builds, then runs the node:test suite in tests/
 ```
 
 Point MCP Inspector at `http://localhost:8080/mcp` to walk through
 tool definitions interactively.
 
+Set `STRICT_VALIDATE=1` to treat a manifest that could not be read as
+drift instead of a warning. It is off by default because Railway restarts
+`ON_FAILURE`: failing closed on boot would crash-loop the endpoint, and
+take the other five healthy services' tools down with it, whenever one
+backend is cold. Either way, a service whose manifest was not read logs
+`NOT CHECKED` - "could not check" is never reported as "all clear".
+
 ## Releases
 
 Releases are cut by tag push. The `Release` workflow builds, validates

package/dist/dispatch.d.ts

@@ -44,6 +44,22 @@ export interface DispatchOptions {
      * can distinguish MCP traffic from direct API users.
      */
     userAgent?: string;
+    /**
+     * Called when a caller presented a `_bypass_key` that did not match.
+     * The transport layer counts these per-IP: a 60/min request limit still
+     * permits thousands of guesses a day against the shared bypass key, and
+     * the 402-vs-200 divergence is a clean oracle, so failed attempts need
+     * their own much tighter budget.
+     */
+    onBypassFailure?: () => void;
+    /**
+     * True while this caller has already burned through the failed-`_bypass_key`
+     * budget. Checked here, at the point of the guess, not only at the start of
+     * the HTTP request: one batched JSON-RPC POST carries thousands of messages,
+     * so a per-request check let a single body spend thousands of guesses before
+     * the lockout could apply.
+     */
+    isBypassBlocked?: () => boolean;
 }
 /**
  * Run a single tool call. Throws on missing tool / network error /

package/dist/dispatch.js

@@ -55,6 +55,10 @@ export async function dispatchTool(toolName, args, opts = {}) {
     }
     const { service, tool } = owner;
     const baseUrl = opts.baseUrlOverride?.(service.id) ?? service.baseUrl;
+    // The low-level MCP Server does NOT check arguments against the advertised
+    // inputSchema - only McpServer.registerTool does - so every declared
+    // pattern/enum/limit is advisory until we enforce it here.
+    args = validateArgs(toolName, tool.inputSchema, args);
     // Substitute path params (e.g. /domain/{domain_id}) from args.
     let path = tool.path;
     const consumedPathArgs = new Set();
@@ -62,8 +66,17 @@ export async function dispatchTool(toolName, args, opts = {}) {
         if (!(key in args)) {
             throw new Error(`tool ${toolName} requires path parameter ${key}, missing from args`);
         }
+        // Unconditional, schema-independent. "." / ".." / a slash survive
+        // encodeURIComponent's intent because the WHATWG URL parser normalizes the
+        // built URL afterwards: /domain/.. collapses to the service root, and the
+        // paid drill-down tool then returns the root banner as a success - which,
+        // with H-Seal on, gets co-signed as an answer to the tool that was called.
+        const raw = String(args[key]);
+        if (raw === "" || raw === "." || raw === ".." || /[/\\]/.test(raw)) {
+            throw new Error(`tool ${toolName}: invalid value for path parameter ${key}`);
+        }
         consumedPathArgs.add(key);
-        return encodeURIComponent(String(args[key]));
+        return encodeURIComponent(raw);
     });
     // Strip args reserved for transport-level concerns (payment_signature,
     // _bypass_key) AND args already consumed by path params. What remains
@@ -95,10 +108,26 @@ export async function dispatchTool(toolName, args, opts = {}) {
         if (callerPaymentSig) {
             headers["PAYMENT-SIGNATURE"] = callerPaymentSig;
         }
-        else if (callerBypassKey && opts.bypassKey && timingSafeStringEqual(callerBypassKey, opts.bypassKey)) {
-            // Operator-issued bypass. Forward as the dev-bypass header that
-            // the underlying services accept.
-            headers["PAYMENT-SIGNATURE"] = callerBypassKey;
+        else if (callerBypassKey) {
+            // Check BEFORE comparing. Gating only the failure branch would leave the
+            // compare reachable, so a blocked caller who finally guesses right still
+            // gets granted - the budget would cap the noise, not the attack.
+            // Throwing rather than falling through to the 402 path also stops the
+            // upstream fan-out a batched body would otherwise amplify, and it reads
+            // the same for every key: the block is per-IP, so it leaks nothing.
+            if (opts.isBypassBlocked?.()) {
+                throw new Error("bypass key attempts exhausted; retry later");
+            }
+            if (opts.bypassKey && timingSafeStringEqual(callerBypassKey, opts.bypassKey)) {
+                // Operator-issued bypass. Forward as the dev-bypass header that
+                // the underlying services accept.
+                headers["PAYMENT-SIGNATURE"] = callerBypassKey;
+            }
+            else {
+                // A wrong key is a guess at the operator secret, not ordinary traffic.
+                // Report it so the transport can budget guesses separately from requests.
+                opts.onBypassFailure?.();
+            }
         }
         else {
             // No auth supplied. Fire the request anyway so the caller gets
@@ -168,4 +197,78 @@ export async function dispatchTool(toolName, args, opts = {}) {
 function stringArg(v) {
     return typeof v === "string" && v.length > 0 ? v : undefined;
 }
+// Args the dispatcher consumes itself. They are never part of the API payload
+// and are not declared on every schema, so the unknown-key drop must not eat
+// them or the operator bypass stops working.
+const RESERVED_ARGS = new Set(["payment_signature", "_bypass_key"]);
+/**
+ * Enforce the tool's advertised inputSchema. Throws on a violation; returns the
+ * args to actually send, with unknown keys dropped when the schema is closed
+ * (today every tool sets additionalProperties: false, so an invented key would
+ * otherwise be forwarded verbatim into the upstream query string or body).
+ *
+ * Deliberately tolerant about numbers-as-strings: LLM clients routinely send
+ * "10" for an integer arg and the backends coerce it, so rejecting that would
+ * break working callers without closing anything.
+ */
+function validateArgs(toolName, schema, args) {
+    const props = schema.properties ?? {};
+    const closed = schema.additionalProperties === false;
+    const out = {};
+    // `required` is deliberately NOT enforced here. A caller probing a paid tool
+    // with no args to get the real 402 challenge back is a supported discovery
+    // move (see the auth block below); turning that into a local error would
+    // break it.
+    for (const [key, value] of Object.entries(args)) {
+        const spec = props[key];
+        if (!spec) {
+            if (RESERVED_ARGS.has(key))
+                out[key] = value;
+            else if (!closed)
+                out[key] = value;
+            continue;
+        }
+        if (value === undefined || value === null) {
+            out[key] = value;
+            continue;
+        }
+        const problem = valueProblem(spec, value);
+        if (problem) {
+            throw new Error(`tool ${toolName}: invalid value for ${key}: ${problem}`);
+        }
+        out[key] = value;
+    }
+    return out;
+}
+function valueProblem(spec, value) {
+    if (spec.enum && !spec.enum.some((e) => e === value || String(e) === String(value))) {
+        return `must be one of [${spec.enum.map(String).join(", ")}]`;
+    }
+    if (spec.type === "number" || spec.type === "integer") {
+        const n = typeof value === "number" ? value : Number(String(value));
+        if (!Number.isFinite(n))
+            return `must be a ${spec.type}`;
+        if (spec.type === "integer" && !Number.isInteger(n))
+            return "must be an integer";
+        if (typeof spec.minimum === "number" && n < spec.minimum)
+            return `must be >= ${spec.minimum}`;
+        if (typeof spec.maximum === "number" && n > spec.maximum)
+            return `must be <= ${spec.maximum}`;
+        return null;
+    }
+    if (spec.type === "boolean") {
+        if (typeof value === "boolean")
+            return null;
+        return value === "true" || value === "false" ? null : "must be a boolean";
+    }
+    if (spec.type === "string") {
+        if (typeof value !== "string")
+            return "must be a string";
+        if (spec.pattern && !new RegExp(spec.pattern).test(value)) {
+            return `must match ${spec.pattern}`;
+        }
+        return null;
+    }
+    return null;
+}
 //# sourceMappingURL=dispatch.js.map

package/dist/dispatch.js.map

@@ -1 +1 @@
-{"version":3,"file":"dispatch.js","sourceRoot":"","sources":["../src/dispatch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAG9C,SAAS,qBAAqB,CAAC,CAAS,EAAE,CAAS;IACjD,oEAAoE;IACpE,kEAAkE;IAClE,8DAA8D;IAC9D,gDAAgD;IAChD,MAAM,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC1B,MAAM,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC1B,IAAI,EAAE,CAAC,MAAM,KAAK,EAAE,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IAC1C,OAAO,eAAe,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;AACjC,CAAC;AAmBD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,QAAgB,EAChB,IAA6B,EAC7B,OAAwB,EAAE;IAE1B,MAAM,KAAK,GAAG,aAAa,CAAC,QAAQ,CAAC,CAAC;IACtC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CAAC,iBAAiB,QAAQ,EAAE,CAAC,CAAC;IAC/C,CAAC;IACD,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,KAAK,CAAC;IAChC,MAAM,OAAO,GAAG,IAAI,CAAC,eAAe,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,IAAI,OAAO,CAAC,OAAO,CAAC;IAEtE,+DAA+D;IAC/D,IAAI,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;IACrB,MAAM,gBAAgB,GAAG,IAAI,GAAG,EAAU,CAAC;IAC3C,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,+BAA+B,EAAE,CAAC,CAAC,EAAE,GAAW,EAAE,EAAE;QACtE,IAAI,CAAC,CAAC,GAAG,IAAI,IAAI,CAAC,EAAE,CAAC;YACnB,MAAM,IAAI,KAAK,CACb,QAAQ,QAAQ,4BAA4B,GAAG,qBAAqB,CACrE,CAAC;QACJ,CAAC;QACD,gBAAgB,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC1B,OAAO,kBAAkB,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IAC/C,CAAC,CAAC,CAAC;IAEH,uEAAuE;IACvE,sEAAsE;IACtE,6BAA6B;IAC7B,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAS;QAC/B,GAAG,CAAC,IAAI,CAAC,SAAS,IAAI,EAAE,CAAC;QACzB,aAAa;QACb,mBAAmB;KACpB,CAAC,CAAC;IACH,MAAM,OAAO,GAA4B,EAAE,CAAC;IAC5C,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QAC1C,IAAI,gBAAgB,CAAC,GAAG,CAAC,CAAC,CAAC;YAAE,SAAS;QACtC,IAAI,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC;YAAE,SAAS;QAC9B,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACjB,CAAC;IAED,kEAAkE;IAClE,mEAAmE;IACnE,oEAAoE;IACpE,qCAAqC;IACrC,MAAM,OAAO,GAA2B;QACtC,MAAM,EAAE,kBAAkB;QAC1B,YAAY,EAAE,IAAI,CAAC,SAAS,IAAI,sBAAsB,cAAc,EAAE;KACvE,CAAC;IAEF,MAAM,gBAAgB,GAAG,SAAS,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;IAC3D,MAAM,eAAe,GAAG,SAAS,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IAEpD,IAAI,IAAI,CAAC,QAAQ,KAAK,aAAa,EAAE,CAAC;QACpC,IAAI,gBAAgB,EAAE,CAAC;YACrB,OAAO,CAAC,mBAAmB,CAAC,GAAG,gBAAgB,CAAC;QAClD,CAAC;aAAM,IAAI,eAAe,IAAI,IAAI,CAAC,SAAS,IAAI,qBAAqB,CAAC,eAAe,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;YACvG,gEAAgE;YAChE,kCAAkC;YAClC,OAAO,CAAC,mBAAmB,CAAC,GAAG,eAAe,CAAC;QACjD,CAAC;aAAM,CAAC;YACN,+DAA+D;YAC/D,iEAAiE;YACjE,iEAAiE;YACjE,2DAA2D;QAC7D,CAAC;IACH,CAAC;IACD,mEAAmE;IACnE,sEAAsE;IACtE,+DAA+D;IAC/D,iCAAiC;IAEjC,wDAAwD;IACxD,IAAI,GAAG,GAAG,OAAO,GAAG,IAAI,CAAC;IACzB,IAAI,IAAwB,CAAC;IAC7B,IAAI,IAAI,CAAC,MAAM,KAAK,KAAK,EAAE,CAAC;QAC1B,MAAM,MAAM,GAAG,IAAI,eAAe,EAAE,CAAC;QACrC,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;YAC7C,IAAI,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,IAAI;gBAAE,SAAS;YAC5C,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;QAC9B,CAAC;QACD,MAAM,EAAE,GAAG,MAAM,CAAC,QAAQ,EAAE,CAAC;QAC7B,IAAI,EAAE;YAAE,GAAG,IAAI,GAAG,GAAG,EAAE,CAAC;IAC1B,CAAC;SAAM,IAAI,IAAI,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;QAClC,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;YACtB,OAAO,CAAC,cAAc,CAAC,GAAG,kBAAkB,CAAC;YAC7C,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QACjC,CAAC;IACH,CAAC;IAED,mEAAmE;IACnE,oEAAoE;IACpE,8DAA8D;IAC9D,MAAM,GAAG,GAAG,IAAI,eAAe,EAAE,CAAC;IAClC,MAAM,SAAS,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,MAAM,CAAC,CAAC;IACxD,IAAI,GAAa,CAAC;IAClB,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;IACrF,CAAC;YAAS,CAAC;QACT,YAAY,CAAC,SAAS,CAAC,CAAC;IAC1B,CAAC;IAED,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;IAC9B,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,GAAG,IAAI,CAAC;IAChB,CAAC;IAED,kEAAkE;IAClE,mEAAmE;IACnE,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;QACZ,OAAO;YACL,MAAM,EAAE,IAAI;YACZ,MAAM,EAAE,GAAG,CAAC,MAAM;YAClB,QAAQ,EAAE,MAAM;YAChB,IAAI,EACF,GAAG,CAAC,MAAM,KAAK,GAAG;gBAChB,CAAC,CAAC,mWAAmW;gBACrW,CAAC,CAAC,SAAS;SAChB,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,SAAS,CAAC,CAAU;IAC3B,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAC/D,CAAC"}
+{"version":3,"file":"dispatch.js","sourceRoot":"","sources":["../src/dispatch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAG9C,SAAS,qBAAqB,CAAC,CAAS,EAAE,CAAS;IACjD,oEAAoE;IACpE,kEAAkE;IAClE,8DAA8D;IAC9D,gDAAgD;IAChD,MAAM,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC1B,MAAM,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC1B,IAAI,EAAE,CAAC,MAAM,KAAK,EAAE,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IAC1C,OAAO,eAAe,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;AACjC,CAAC;AAmCD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,QAAgB,EAChB,IAA6B,EAC7B,OAAwB,EAAE;IAE1B,MAAM,KAAK,GAAG,aAAa,CAAC,QAAQ,CAAC,CAAC;IACtC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CAAC,iBAAiB,QAAQ,EAAE,CAAC,CAAC;IAC/C,CAAC;IACD,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,KAAK,CAAC;IAChC,MAAM,OAAO,GAAG,IAAI,CAAC,eAAe,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,IAAI,OAAO,CAAC,OAAO,CAAC;IAEtE,2EAA2E;IAC3E,qEAAqE;IACrE,2DAA2D;IAC3D,IAAI,GAAG,YAAY,CAAC,QAAQ,EAAE,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC;IAEtD,+DAA+D;IAC/D,IAAI,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;IACrB,MAAM,gBAAgB,GAAG,IAAI,GAAG,EAAU,CAAC;IAC3C,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,+BAA+B,EAAE,CAAC,CAAC,EAAE,GAAW,EAAE,EAAE;QACtE,IAAI,CAAC,CAAC,GAAG,IAAI,IAAI,CAAC,EAAE,CAAC;YACnB,MAAM,IAAI,KAAK,CACb,QAAQ,QAAQ,4BAA4B,GAAG,qBAAqB,CACrE,CAAC;QACJ,CAAC;QACD,kEAAkE;QAClE,2EAA2E;QAC3E,0EAA0E;QAC1E,0EAA0E;QAC1E,2EAA2E;QAC3E,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;QAC9B,IAAI,GAAG,KAAK,EAAE,IAAI,GAAG,KAAK,GAAG,IAAI,GAAG,KAAK,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YACnE,MAAM,IAAI,KAAK,CAAC,QAAQ,QAAQ,sCAAsC,GAAG,EAAE,CAAC,CAAC;QAC/E,CAAC;QACD,gBAAgB,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC1B,OAAO,kBAAkB,CAAC,GAAG,CAAC,CAAC;IACjC,CAAC,CAAC,CAAC;IAEH,uEAAuE;IACvE,sEAAsE;IACtE,6BAA6B;IAC7B,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAS;QAC/B,GAAG,CAAC,IAAI,CAAC,SAAS,IAAI,EAAE,CAAC;QACzB,aAAa;QACb,mBAAmB;KACpB,CAAC,CAAC;IACH,MAAM,OAAO,GAA4B,EAAE,CAAC;IAC5C,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QAC1C,IAAI,gBAAgB,CAAC,GAAG,CAAC,CAAC,CAAC;YAAE,SAAS;QACtC,IAAI,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC;YAAE,SAAS;QAC9B,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACjB,CAAC;IAED,kEAAkE;IAClE,mEAAmE;IACnE,oEAAoE;IACpE,qCAAqC;IACrC,MAAM,OAAO,GAA2B;QACtC,MAAM,EAAE,kBAAkB;QAC1B,YAAY,EAAE,IAAI,CAAC,SAAS,IAAI,sBAAsB,cAAc,EAAE;KACvE,CAAC;IAEF,MAAM,gBAAgB,GAAG,SAAS,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;IAC3D,MAAM,eAAe,GAAG,SAAS,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IAEpD,IAAI,IAAI,CAAC,QAAQ,KAAK,aAAa,EAAE,CAAC;QACpC,IAAI,gBAAgB,EAAE,CAAC;YACrB,OAAO,CAAC,mBAAmB,CAAC,GAAG,gBAAgB,CAAC;QAClD,CAAC;aAAM,IAAI,eAAe,EAAE,CAAC;YAC3B,yEAAyE;YACzE,yEAAyE;YACzE,iEAAiE;YACjE,sEAAsE;YACtE,wEAAwE;YACxE,oEAAoE;YACpE,IAAI,IAAI,CAAC,eAAe,EAAE,EAAE,EAAE,CAAC;gBAC7B,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAC;YAChE,CAAC;YACD,IAAI,IAAI,CAAC,SAAS,IAAI,qBAAqB,CAAC,eAAe,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;gBAC7E,gEAAgE;gBAChE,kCAAkC;gBAClC,OAAO,CAAC,mBAAmB,CAAC,GAAG,eAAe,CAAC;YACjD,CAAC;iBAAM,CAAC;gBACN,uEAAuE;gBACvE,0EAA0E;gBAC1E,IAAI,CAAC,eAAe,EAAE,EAAE,CAAC;YAC3B,CAAC;QACH,CAAC;aAAM,CAAC;YACN,+DAA+D;YAC/D,iEAAiE;YACjE,iEAAiE;YACjE,2DAA2D;QAC7D,CAAC;IACH,CAAC;IACD,mEAAmE;IACnE,sEAAsE;IACtE,+DAA+D;IAC/D,iCAAiC;IAEjC,wDAAwD;IACxD,IAAI,GAAG,GAAG,OAAO,GAAG,IAAI,CAAC;IACzB,IAAI,IAAwB,CAAC;IAC7B,IAAI,IAAI,CAAC,MAAM,KAAK,KAAK,EAAE,CAAC;QAC1B,MAAM,MAAM,GAAG,IAAI,eAAe,EAAE,CAAC;QACrC,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;YAC7C,IAAI,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,IAAI;gBAAE,SAAS;YAC5C,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;QAC9B,CAAC;QACD,MAAM,EAAE,GAAG,MAAM,CAAC,QAAQ,EAAE,CAAC;QAC7B,IAAI,EAAE;YAAE,GAAG,IAAI,GAAG,GAAG,EAAE,CAAC;IAC1B,CAAC;SAAM,IAAI,IAAI,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;QAClC,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;YACtB,OAAO,CAAC,cAAc,CAAC,GAAG,kBAAkB,CAAC;YAC7C,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QACjC,CAAC;IACH,CAAC;IAED,mEAAmE;IACnE,oEAAoE;IACpE,8DAA8D;IAC9D,MAAM,GAAG,GAAG,IAAI,eAAe,EAAE,CAAC;IAClC,MAAM,SAAS,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,MAAM,CAAC,CAAC;IACxD,IAAI,GAAa,CAAC;IAClB,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;IACrF,CAAC;YAAS,CAAC;QACT,YAAY,CAAC,SAAS,CAAC,CAAC;IAC1B,CAAC;IAED,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;IAC9B,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,GAAG,IAAI,CAAC;IAChB,CAAC;IAED,kEAAkE;IAClE,mEAAmE;IACnE,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;QACZ,OAAO;YACL,MAAM,EAAE,IAAI;YACZ,MAAM,EAAE,GAAG,CAAC,MAAM;YAClB,QAAQ,EAAE,MAAM;YAChB,IAAI,EACF,GAAG,CAAC,MAAM,KAAK,GAAG;gBAChB,CAAC,CAAC,mWAAmW;gBACrW,CAAC,CAAC,SAAS;SAChB,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,SAAS,CAAC,CAAU;IAC3B,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAC/D,CAAC;AAED,8EAA8E;AAC9E,6EAA6E;AAC7E,6CAA6C;AAC7C,MAAM,aAAa,GAAG,IAAI,GAAG,CAAS,CAAC,mBAAmB,EAAE,aAAa,CAAC,CAAC,CAAC;AAE5E;;;;;;;;;GASG;AACH,SAAS,YAAY,CACnB,QAAgB,EAChB,MAAmB,EACnB,IAA6B;IAE7B,MAAM,KAAK,GAAG,MAAM,CAAC,UAAU,IAAI,EAAE,CAAC;IACtC,MAAM,MAAM,GAAG,MAAM,CAAC,oBAAoB,KAAK,KAAK,CAAC;IACrD,MAAM,GAAG,GAA4B,EAAE,CAAC;IAExC,6EAA6E;IAC7E,2EAA2E;IAC3E,yEAAyE;IACzE,YAAY;IACZ,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QAChD,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,IAAI,aAAa,CAAC,GAAG,CAAC,GAAG,CAAC;gBAAE,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;iBACxC,IAAI,CAAC,MAAM;gBAAE,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;YACnC,SAAS;QACX,CAAC;QACD,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;YAC1C,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;YACjB,SAAS;QACX,CAAC;QACD,MAAM,OAAO,GAAG,YAAY,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QAC1C,IAAI,OAAO,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CAAC,QAAQ,QAAQ,uBAAuB,GAAG,KAAK,OAAO,EAAE,CAAC,CAAC;QAC5E,CAAC;QACD,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IACnB,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,YAAY,CAAC,IAAiB,EAAE,KAAc;IACrD,IAAI,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,KAAK,IAAI,MAAM,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC;QACpF,OAAO,mBAAmB,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;IAChE,CAAC;IACD,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QACtD,MAAM,CAAC,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QACpE,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;YAAE,OAAO,aAAa,IAAI,CAAC,IAAI,EAAE,CAAC;QACzD,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC;YAAE,OAAO,oBAAoB,CAAC;QACjF,IAAI,OAAO,IAAI,CAAC,OAAO,KAAK,QAAQ,IAAI,CAAC,GAAG,IAAI,CAAC,OAAO;YAAE,OAAO,cAAc,IAAI,CAAC,OAAO,EAAE,CAAC;QAC9F,IAAI,OAAO,IAAI,CAAC,OAAO,KAAK,QAAQ,IAAI,CAAC,GAAG,IAAI,CAAC,OAAO;YAAE,OAAO,cAAc,IAAI,CAAC,OAAO,EAAE,CAAC;QAC9F,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC5B,IAAI,OAAO,KAAK,KAAK,SAAS;YAAE,OAAO,IAAI,CAAC;QAC5C,OAAO,KAAK,KAAK,MAAM,IAAI,KAAK,KAAK,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,mBAAmB,CAAC;IAC5E,CAAC;IACD,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC3B,IAAI,OAAO,KAAK,KAAK,QAAQ;YAAE,OAAO,kBAAkB,CAAC;QACzD,IAAI,IAAI,CAAC,OAAO,IAAI,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YAC1D,OAAO,cAAc,IAAI,CAAC,OAAO,EAAE,CAAC;QACtC,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/hSealReceipt.d.ts

@@ -17,23 +17,52 @@
  * no new secret is required. Inert when unset. NB: the H-Seal API host is
  * h-seal.xr-utilities.ai (the .com host is a browser-only, Cloudflare-challenged
  * surface and returns 403 to server clients).
+ *
+ * NOTHING in the attestation may be taken on trust. The receipt carries a real
+ * signature from the operator's key, so a backend (or anything that can shape a
+ * proxied response) that hands us an invented (requestHash, responseHash,
+ * providerIdentity) triple would otherwise get the operator to vouch for
+ * arbitrary content on behalf of an arbitrary third party. Before signing:
+ *
+ *   1. responseHash is recomputed from the body we actually delivered. It is
+ *      the one hash the MCP can corroborate on its own.
+ *   2. The provider's own ed25519 signature is verified, AND the public key on
+ *      the wire must derive the r-address in providerIdentity - otherwise any
+ *      self-signed blob naming a real service would pass.
+ *   3. providerIdentity is pinned to HSEAL_ALLOWED_PROVIDERS when that env var
+ *      is set (comma-separated CAIP-10 identities).
+ *
+ * requestHash stays PROVIDER-ASSERTED: backends hash a synthetic
+ * {"tool": ...} object the MCP cannot reproduce, so a strict comparison would
+ * reject every live receipt. The result says so via `requestHashBasis` rather
+ * than implying the caller corroborated it.
  */
 export declare const hSealReceiptEnabled: boolean;
 export interface HSealReceiptResult {
-    body: unknown;
+    /** The signed receipt. Absent whenever the MCP refused to sign, or H-Seal explicitly rejected. */
+    body?: unknown;
     verdict?: unknown;
     verifyError?: string;
+    /** Always "provider_asserted" — the MCP cannot reproduce the backend's requestHash preimage. */
+    requestHashBasis?: string;
 }
 /**
- * Build + verify a 2-party receipt from a backend provider attestation. Always
- * returns the signed `body` (valid + independently verifiable) when signing
- * succeeds; `verdict` is best-effort — if the H-Seal service is unreachable the
- * body still stands and `verifyError` records why. Returns undefined only when
- * H-Seal isn't configured or the attestation is malformed. Never throws.
+ * Build + verify a 2-party receipt from a backend provider attestation. Returns
+ * the signed `body` (valid + independently verifiable) when signing succeeds;
+ * `verdict` is best-effort — if the H-Seal service is unreachable the body
+ * still stands and `verifyError` records why, but an explicit H-Seal reject
+ * drops the body. A responseHash that does not match what we delivered also
+ * drops the body, and says so in `verifyError` rather than vanishing, as does
+ * every other refusal: a malformed attestation, a provider signature that does
+ * not authenticate, and an identity outside HSEAL_ALLOWED_PROVIDERS all return
+ * a body-less result with a reason. Only two cases return undefined - H-Seal
+ * not being configured at all, and our own signing throwing. Never throws.
  */
 export declare function buildReceipt(opts: {
     serviceEndpoint: string;
     attestation: unknown;
+    /** The body actually delivered to the caller (result minus the attestation envelope). */
+    responseBody: unknown;
     startedAt: number;
     completedAt: number;
     latencyMs: number;

package/dist/hSealReceipt.js

@@ -17,40 +17,198 @@
  * no new secret is required. Inert when unset. NB: the H-Seal API host is
  * h-seal.xr-utilities.ai (the .com host is a browser-only, Cloudflare-challenged
  * surface and returns 403 to server clients).
+ *
+ * NOTHING in the attestation may be taken on trust. The receipt carries a real
+ * signature from the operator's key, so a backend (or anything that can shape a
+ * proxied response) that hands us an invented (requestHash, responseHash,
+ * providerIdentity) triple would otherwise get the operator to vouch for
+ * arbitrary content on behalf of an arbitrary third party. Before signing:
+ *
+ *   1. responseHash is recomputed from the body we actually delivered. It is
+ *      the one hash the MCP can corroborate on its own.
+ *   2. The provider's own ed25519 signature is verified, AND the public key on
+ *      the wire must derive the r-address in providerIdentity - otherwise any
+ *      self-signed blob naming a real service would pass.
+ *   3. providerIdentity is pinned to HSEAL_ALLOWED_PROVIDERS when that env var
+ *      is set (comma-separated CAIP-10 identities).
+ *
+ * requestHash stays PROVIDER-ASSERTED: backends hash a synthetic
+ * {"tool": ...} object the MCP cannot reproduce, so a strict comparison would
+ * reject every live receipt. The result says so via `requestHashBasis` rather
+ * than implying the caller corroborated it.
  */
-import { randomUUID } from "node:crypto";
-import { signReceipt, attachAttestation, HSealClient, ed25519Signer, } from "@xr-utilities/h-seal-provider";
+import { createHash, createPublicKey, randomUUID, verify as verifySignature } from "node:crypto";
+import { signReceipt, attachAttestation, hashCanonicalJson, sha256Hex, HSealClient, ed25519Signer, } from "@xr-utilities/h-seal-provider";
 const HSEAL_API = process.env["HSEAL_ENDPOINT"] ?? "https://h-seal.xr-utilities.ai";
 const RECEIPT_TOPIC = process.env["HSEAL_RECEIPT_TOPIC"] ?? "0.0.10500472";
 const callerIdentity = process.env["MCP_IDENTITY"] ?? process.env["PROVIDER_IDENTITY"];
 const callerKeyRaw = process.env["MCP_KEY_RAW"] ?? process.env["PROVIDER_KEY_RAW"];
+const allowedProviders = (process.env["HSEAL_ALLOWED_PROVIDERS"] ?? "")
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+/** How the receipt's requestHash was established. See the module header. */
+const REQUEST_HASH_BASIS = "provider_asserted";
 export const hSealReceiptEnabled = Boolean(callerIdentity && callerKeyRaw);
+/**
+ * A well-formed attestation carries the provider's own signature. Accepting a
+ * three-string blob would let a "2-party" receipt be emitted with no second
+ * party at all, so providerSignature / scheme / issuedAt are required here.
+ */
 function looksLikeAttestation(a) {
-    return (typeof a === "object" && a !== null &&
-        typeof a["requestHash"] === "string" &&
-        typeof a["responseHash"] === "string" &&
-        typeof a["providerIdentity"] === "string");
+    if (typeof a !== "object" || a === null)
+        return false;
+    const r = a;
+    return (typeof r["requestHash"] === "string" &&
+        typeof r["responseHash"] === "string" &&
+        typeof r["providerIdentity"] === "string" &&
+        typeof r["providerSignature"] === "string" &&
+        typeof r["providerSignatureScheme"] === "string" &&
+        typeof r["providerIssuedAt"] === "number");
+}
+const XRPL_BASE58 = "rpshnaf39wBUDNEGHJKLM4PQRST7VWXYZ2bcdeCg65jkm8oFqi1tuvAxyz";
+// SPKI DER header for a raw ed25519 public key: 12 fixed bytes + the 32-byte key.
+const ED25519_SPKI_PREFIX = Buffer.from("302a300506032b6570032100", "hex");
+function base58Xrpl(buf) {
+    let n = BigInt("0x" + (buf.toString("hex") || "0"));
+    let out = "";
+    while (n > 0n) {
+        out = XRPL_BASE58[Number(n % 58n)] + out;
+        n /= 58n;
+    }
+    for (const b of buf) {
+        if (b !== 0)
+            break;
+        out = XRPL_BASE58[0] + out;
+    }
+    return out;
+}
+/** Classic r-address for a 33-byte XRPL public key (0xED prefix + raw ed25519). */
+function xrplAddressFromPubKey(pubKey) {
+    const accountId = createHash("ripemd160")
+        .update(createHash("sha256").update(pubKey).digest())
+        .digest();
+    const payload = Buffer.concat([Buffer.from([0x00]), accountId]);
+    const checksum = createHash("sha256")
+        .update(createHash("sha256").update(payload).digest())
+        .digest()
+        .subarray(0, 4);
+    return base58Xrpl(Buffer.concat([payload, checksum]));
+}
+/**
+ * Authenticate the provider. Returns null when the attestation really was
+ * signed by the account it names, otherwise the reason it wasn't. The preimage
+ * mirrors the SDK's signProviderAttestation exactly: the sha256 of the
+ * canonical JSON of {kind: "provider_attest", payload}, signed raw for XRPL.
+ */
+function providerSignatureProblem(att) {
+    const parts = att.providerIdentity.split(":");
+    const namespace = parts[0];
+    const address = parts.slice(2).join(":");
+    if (namespace !== "xrpl" || !address) {
+        return `providerIdentity ${att.providerIdentity} is not an xrpl CAIP-10 identity; cannot authenticate it`;
+    }
+    if (att.providerSignatureScheme !== "ed25519") {
+        return `providerSignatureScheme ${att.providerSignatureScheme} is not ed25519`;
+    }
+    const wire = /^ed([0-9a-fA-F]{64}):([0-9a-fA-F]{128})$/.exec(att.providerSignature);
+    if (!wire) {
+        return "providerSignature is not the ed<pubkey_hex>:<sig_hex> wire form";
+    }
+    const pubKeyRaw = Buffer.from(wire[1], "hex");
+    const signature = Buffer.from(wire[2], "hex");
+    // Bind the key to the identity. Without this a self-signed blob naming any
+    // r-address verifies against its own key and passes.
+    const derived = xrplAddressFromPubKey(Buffer.concat([Buffer.from([0xed]), pubKeyRaw]));
+    if (derived !== address) {
+        return `providerSignature public key derives ${derived}, not the ${address} in providerIdentity`;
+    }
+    const digest = hashCanonicalJson({
+        kind: "provider_attest",
+        payload: {
+            providerIdentity: att.providerIdentity,
+            requestHash: att.requestHash,
+            responseHash: att.responseHash,
+            providerIssuedAt: att.providerIssuedAt,
+        },
+    });
+    const pubKey = createPublicKey({
+        key: Buffer.concat([ED25519_SPKI_PREFIX, pubKeyRaw]),
+        format: "der",
+        type: "spki",
+    });
+    if (!verifySignature(null, digest, pubKey, signature)) {
+        return "providerSignature does not verify over the attested payload";
+    }
+    return null;
 }
+// One line per unpinned provider, not one per call: the operator needs to see
+// it once to populate HSEAL_ALLOWED_PROVIDERS, not on every tool call.
+const warnedUnpinned = new Set();
 /**
- * Build + verify a 2-party receipt from a backend provider attestation. Always
- * returns the signed `body` (valid + independently verifiable) when signing
- * succeeds; `verdict` is best-effort — if the H-Seal service is unreachable the
- * body still stands and `verifyError` records why. Returns undefined only when
- * H-Seal isn't configured or the attestation is malformed. Never throws.
+ * Build + verify a 2-party receipt from a backend provider attestation. Returns
+ * the signed `body` (valid + independently verifiable) when signing succeeds;
+ * `verdict` is best-effort — if the H-Seal service is unreachable the body
+ * still stands and `verifyError` records why, but an explicit H-Seal reject
+ * drops the body. A responseHash that does not match what we delivered also
+ * drops the body, and says so in `verifyError` rather than vanishing, as does
+ * every other refusal: a malformed attestation, a provider signature that does
+ * not authenticate, and an identity outside HSEAL_ALLOWED_PROVIDERS all return
+ * a body-less result with a reason. Only two cases return undefined - H-Seal
+ * not being configured at all, and our own signing throwing. Never throws.
  */
 export async function buildReceipt(opts) {
+    // The ONLY branch that may stay silent: H-Seal genuinely is not configured,
+    // so the absence of _meta.hSealReceipt is the truthful answer.
     if (!hSealReceiptEnabled)
         return undefined;
-    if (!looksLikeAttestation(opts.attestation))
-        return undefined;
+    if (!looksLikeAttestation(opts.attestation)) {
+        // The server only calls us when the backend put SOMETHING in the
+        // attestation slot, so a shape we cannot parse is producer drift, not
+        // "no attestation". Do not echo the blob back to the caller.
+        console.error("[hSealReceipt] attestation is missing required fields (see looksLikeAttestation); refusing to sign");
+        return { verifyError: "provider attestation is malformed", requestHashBasis: REQUEST_HASH_BASIS };
+    }
     const att = opts.attestation;
+    // Corroborate the one hash we can compute ourselves. The backends hash the
+    // canonical JSON of the response minus the attestation envelope, which is
+    // exactly what the server hands us here. A mismatch means the receipt would
+    // bind our signature to bytes we never served.
+    if (sha256Hex(opts.responseBody) !== att.responseHash) {
+        // Refusing is right, but returning nothing made the refusal invisible: the
+        // flagship paid tool would just stop carrying _meta.hSealReceipt with no
+        // signal past one log line. Name the provider so an operator can tell which
+        // backend drifted (a producer that attests before its response model
+        // appends footer fields lands here on EVERY call).
+        console.error(`[hSealReceipt] responseHash does not match the delivered body for ${att.providerIdentity}; refusing to sign`);
+        return { verifyError: "responseHash does not match the delivered body", requestHashBasis: REQUEST_HASH_BASIS };
+    }
+    const problem = providerSignatureProblem(att);
+    if (problem) {
+        console.error(`[hSealReceipt] provider attestation rejected: ${problem}; refusing to sign`);
+        // `problem` names an UNAUTHENTICATED identity/key, so it stays in the log.
+        // The caller gets the fact of the refusal, which is the part that must not
+        // be indistinguishable from the feature being switched off.
+        return { verifyError: "provider attestation failed authentication", requestHashBasis: REQUEST_HASH_BASIS };
+    }
+    if (allowedProviders.length > 0) {
+        if (!allowedProviders.includes(att.providerIdentity)) {
+            console.error(`[hSealReceipt] providerIdentity ${att.providerIdentity} is not in HSEAL_ALLOWED_PROVIDERS; refusing to sign`);
+            return { verifyError: "provider is not in HSEAL_ALLOWED_PROVIDERS", requestHashBasis: REQUEST_HASH_BASIS };
+        }
+    }
+    else if (!warnedUnpinned.has(att.providerIdentity)) {
+        warnedUnpinned.add(att.providerIdentity);
+        console.error(`[hSealReceipt] HSEAL_ALLOWED_PROVIDERS is unset; co-signing for self-attested provider ${att.providerIdentity}. ` +
+            `Set it to the known XR-* identities to pin who this key will vouch for.`);
+    }
     try {
         const signed = await signReceipt({
             receipt: {
                 taskId: randomUUID(),
                 serviceEndpoint: opts.serviceEndpoint,
-                requestHash: att.requestHash, // MUST equal the attestation's
-                responseHash: att.responseHash, // MUST equal the attestation's
+                requestHash: att.requestHash, // provider-asserted, see REQUEST_HASH_BASIS
+                responseHash: att.responseHash, // corroborated against the delivered body above
                 resultStatus: "success",
                 startedAt: opts.startedAt,
                 completedAt: opts.completedAt,
@@ -65,10 +223,19 @@ export async function buildReceipt(opts) {
         const body = attachAttestation(signed.body, att);
         try {
             const verdict = await new HSealClient({ endpoint: HSEAL_API }).verify(body);
-            return { body, verdict };
+            if (verdict.ok === false) {
+                // An explicit reject is the one verdict that must drop the body:
+                // handing the caller a receipt H-Seal has already refused presents it
+                // as provenance it does not carry. An unreachable H-Seal is different
+                // — the body verifies independently, so it still rides out below.
+                const reason = verdict.reason ?? "no reason given";
+                console.error(`[hSealReceipt] H-Seal rejected the receipt: ${reason}`);
+                return { verifyError: `H-Seal rejected the receipt: ${reason}`, requestHashBasis: REQUEST_HASH_BASIS };
+            }
+            return { body, verdict, requestHashBasis: REQUEST_HASH_BASIS };
         }
         catch (err) {
-            return { body, verifyError: err.message };
+            return { body, verifyError: err.message, requestHashBasis: REQUEST_HASH_BASIS };
         }
     }
     catch (err) {

package/dist/hSealReceipt.js.map

@@ -1 +1 @@
-{"version":3,"file":"hSealReceipt.js","sourceRoot":"","sources":["../src/hSealReceipt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EACL,WAAW,EACX,iBAAiB,EACjB,WAAW,EACX,aAAa,GAEd,MAAM,+BAA+B,CAAC;AAEvC,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,IAAI,gCAAgC,CAAC;AACpF,MAAM,aAAa,GAAG,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC,IAAI,cAAc,CAAC;AAC3E,MAAM,cAAc,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,IAAI,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAC;AACvF,MAAM,YAAY,GAAG,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,IAAI,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;AAEnF,MAAM,CAAC,MAAM,mBAAmB,GAAY,OAAO,CAAC,cAAc,IAAI,YAAY,CAAC,CAAC;AAQpF,SAAS,oBAAoB,CAAC,CAAU;IACtC,OAAO,CACL,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI;QACnC,OAAQ,CAA6B,CAAC,aAAa,CAAC,KAAK,QAAQ;QACjE,OAAQ,CAA6B,CAAC,cAAc,CAAC,KAAK,QAAQ;QAClE,OAAQ,CAA6B,CAAC,kBAAkB,CAAC,KAAK,QAAQ,CACvE,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,IAMlC;IACC,IAAI,CAAC,mBAAmB;QAAE,OAAO,SAAS,CAAC;IAC3C,IAAI,CAAC,oBAAoB,CAAC,IAAI,CAAC,WAAW,CAAC;QAAE,OAAO,SAAS,CAAC;IAC9D,MAAM,GAAG,GAAG,IAAI,CAAC,WAAW,CAAC;IAC7B,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC;YAC/B,OAAO,EAAE;gBACP,MAAM,EAAE,UAAU,EAAE;gBACpB,eAAe,EAAE,IAAI,CAAC,eAAe;gBACrC,WAAW,EAAE,GAAG,CAAC,WAAW,EAAI,+BAA+B;gBAC/D,YAAY,EAAE,GAAG,CAAC,YAAY,EAAE,+BAA+B;gBAC/D,YAAY,EAAE,SAAS;gBACvB,SAAS,EAAE,IAAI,CAAC,SAAS;gBACzB,WAAW,EAAE,IAAI,CAAC,WAAW;gBAC7B,SAAS,EAAE,IAAI,CAAC,SAAS;gBACzB,cAAc,EAAE,cAAwB,EAAI,kBAAkB;gBAC9D,gBAAgB,EAAE,GAAG,CAAC,gBAAgB;gBACtC,cAAc,EAAE,aAAa;aAC9B;YACD,MAAM,EAAE,aAAa,CAAC,YAAsB,CAAC;YAC7C,OAAO,EAAE,SAAS;SACnB,CAAC,CAAC;QACH,MAAM,IAAI,GAAG,iBAAiB,CAAC,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QACjD,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,MAAM,IAAI,WAAW,CAAC,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YAC5E,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;QAC3B,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,EAAE,IAAI,EAAE,WAAW,EAAG,GAAa,CAAC,OAAO,EAAE,CAAC;QACvD,CAAC;IACH,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,CAAC,KAAK,CAAC,+BAAgC,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;QACvE,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC"}
+{"version":3,"file":"hSealReceipt.js","sourceRoot":"","sources":["../src/hSealReceipt.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -39,9 +39,17 @@ async function main() {
     // on stderr (Claude Desktop captures stdout for the JSON-RPC stream).
     // On HTTP we log normally.
     if (!skipValidate) {
-        const results = await validateAllServices({ strict: false });
+        // Opt-in, default off: railway.json restarts ON_FAILURE, so failing closed
+        // by default would crash-loop the endpoint whenever one backend is cold.
+        const strict = process.env["STRICT_VALIDATE"] === "1";
+        const results = await validateAllServices({ strict });
         const log = transport === "stdio" ? console.error : console.log;
         for (const r of results) {
+            if (!r.checked) {
+                // Always say it, strict or not: a boot that verified nothing must be
+                // impossible to mistake for a clean one.
+                log(`[validate] ${r.service}: NOT CHECKED (no manifest)`);
+            }
             if (r.errors.length) {
                 log(`[validate] ${r.service}: ERRORS`);
                 r.errors.forEach((e) => log(`  ${e}`));
@@ -52,7 +60,8 @@ async function main() {
             }
         }
         const anyError = results.some((r) => r.errors.length);
-        if (anyError && process.env["MCP_FAIL_ON_DRIFT"] === "1") {
+        const anyUnchecked = results.some((r) => !r.checked);
+        if ((anyError || (strict && anyUnchecked)) && process.env["MCP_FAIL_ON_DRIFT"] === "1") {
             process.exit(2);
         }
     }

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAChD,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAC9C,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAEpD,SAAS,SAAS,CAAC,IAAc;IAC/B,IAAI,SAAS,GACX,CAAC,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,KAAK,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;IAC/D,IAAI,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,CAAC;IACjD,IAAI,YAAY,GAAG,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC,KAAK,GAAG,CAAC;IAE5D,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC,CAAE,CAAC;QACnB,IAAI,CAAC,KAAK,aAAa,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC;YACtC,MAAM,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;YACpB,IAAI,CAAC,KAAK,OAAO,IAAI,CAAC,KAAK,MAAM;gBAAE,SAAS,GAAG,CAAC,CAAC;QACnD,CAAC;aAAM,IAAI,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC;YACxC,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC;QACnC,CAAC;aAAM,IAAI,CAAC,KAAK,iBAAiB,EAAE,CAAC;YACnC,YAAY,GAAG,IAAI,CAAC;QACtB,CAAC;IACH,CAAC;IACD,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC;AAC3C,CAAC;AAED,KAAK,UAAU,IAAI;IACjB,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,YAAY,EAAE,GAAG,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAE3E,sEAAsE;IACtE,sEAAsE;IACtE,2BAA2B;IAC3B,IAAI,CAAC,YAAY,EAAE,CAAC;QAClB,2EAA2E;QAC3E,yEAAyE;QACzE,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC,KAAK,GAAG,CAAC;QACtD,MAAM,OAAO,GAAG,MAAM,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC;QACtD,MAAM,GAAG,GAAG,SAAS,KAAK,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC;QAChE,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;YACxB,IAAI,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;gBACf,qEAAqE;gBACrE,yCAAyC;gBACzC,GAAG,CAAC,cAAc,CAAC,CAAC,OAAO,6BAA6B,CAAC,CAAC;YAC5D,CAAC;YACD,IAAI,CAAC,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;gBACpB,GAAG,CAAC,cAAc,CAAC,CAAC,OAAO,UAAU,CAAC,CAAC;gBACvC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC;YACzC,CAAC;YACD,IAAI,CAAC,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC;gBACtB,GAAG,CAAC,cAAc,CAAC,CAAC,OAAO,YAAY,CAAC,CAAC;gBACzC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC;YAC3C,CAAC;QACH,CAAC;QACD,MAAM,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QACtD,MAAM,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;QACrD,IAAI,CAAC,QAAQ,IAAI,CAAC,MAAM,IAAI,YAAY,CAAC,CAAC,IAAI,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC,KAAK,GAAG,EAAE,CAAC;YACvF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;IACH,CAAC;IAED,IAAI,SAAS,KAAK,OAAO,EAAE,CAAC;QAC1B,MAAM,QAAQ,EAAE,CAAC;IACnB,CAAC;SAAM,CAAC;QACN,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,CAAC;AACH,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE;IACjB,OAAO,CAAC,KAAK,CAAC,2BAA2B,EAAE,CAAC,CAAC,CAAC;IAC9C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}