yieldagentx402-verify 1.0.0

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 YieldAgentX402
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,72 @@
+# yieldagentx402-verify
+
+> Zero-dependency verifier for YieldAgentX402 receipts and webhook signatures.
+> Works in **browser, Node 18+, Cloudflare Workers, Deno**.
+
+[Docs](https://yieldagentx402.app/mcp-server) · [Verify page](https://yieldagentx402.app/verify) · [npm](https://www.npmjs.com/package/yieldagentx402-verify)
+
+## Install
+
+```bash
+npm install yieldagentx402-verify
+```
+
+## Verify a receipt
+
+```js
+import { verifyReceipt } from "yieldagentx402-verify";
+
+const result = await verifyReceipt({
+  secret:   process.env.YAX_WEBHOOK_SECRET,
+  receipt:  receiptObjectFromGateway,
+  signature: receiptObjectFromGateway.receipt_signature,
+});
+
+if (result.ok) console.log("Receipt is genuine ✓");
+else console.warn("Receipt failed verification:", result);
+```
+
+## Verify a webhook
+
+```js
+import { verifyWebhook } from "yieldagentx402-verify";
+
+// In your webhook handler:
+const rawBody = await request.text();
+const result = await verifyWebhook({
+  secret:    process.env.YAX_WEBHOOK_SECRET,
+  body:      rawBody,
+  signature: request.headers,  // pass Headers directly
+});
+
+if (!result.ok) return new Response("invalid sig", { status: 401 });
+const event = JSON.parse(rawBody);
+// process event.run_id, event.status, event.receipt_signature ...
+```
+
+## Fetch + verify in one call
+
+```js
+import { fetchAndVerifyReceipt } from "yieldagentx402-verify";
+
+const { verified, receipt } = await fetchAndVerifyReceipt({
+  runId:   "run_abc123",
+  secret:  process.env.YAX_WEBHOOK_SECRET,
+  apiKey:  process.env.YAX_API_KEY,
+});
+
+console.log(verified ? "✓ anchored + signed" : "⚠ not verified");
+```
+
+## Why this lib exists
+
+YieldAgentX402 receipts are HMAC-SHA256 signatures over canonical receipt JSON. The signing happens inside an Intel TDX TEE, and the proof is anchored to Filecoin + BTFS. This package gives you a tiny, audit-able client to verify the signature yourself — **no trust in the YAX gateway required**.
+
+- **0 runtime deps** — uses WebCrypto only
+- **Timing-safe equality** — no leaks
+- **TypeScript types included**
+- **Works everywhere** — browser, Node, Workers, Deno
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "yieldagentx402-verify",
+  "version": "1.0.0",
+  "description": "Zero-dependency verifier for YieldAgentX402 receipts and webhook signatures. Works in browser, Node 18+, Cloudflare Workers, and Deno.",
+  "type": "module",
+  "main": "./src/index.js",
+  "module": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js"
+    }
+  },
+  "files": ["src", "README.md", "LICENSE"],
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "keywords": [
+    "yieldagentx402","yax","mcp","x402","receipt","verify","hmac","filecoin","webhook","agent-payments"
+  ],
+  "author": "YieldAgentX402",
+  "license": "MIT",
+  "homepage": "https://yieldagentx402.app/mcp-server",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Fabio662/Yieldagenticx402-Hub.git",
+    "directory": "integrations/verify-lib"
+  },
+  "publishConfig": { "access": "public" },
+  "engines": { "node": ">=18" }
+}

package/src/index.d.ts

@@ -0,0 +1,33 @@
+export interface VerifyResult {
+  ok: boolean;
+  computed: string;
+  provided: string;
+  reason?: string;
+}
+
+export interface VerifyReceiptOpts {
+  secret: string;
+  receipt: Record<string, unknown> | string;
+  signature: string;
+}
+export function verifyReceipt(opts: VerifyReceiptOpts): Promise<VerifyResult>;
+
+export interface VerifyWebhookOpts {
+  secret: string;
+  body: string | ArrayBuffer | Uint8Array;
+  signature: string | Headers;
+}
+export function verifyWebhook(opts: VerifyWebhookOpts): Promise<VerifyResult>;
+
+export interface FetchAndVerifyOpts {
+  runId: string;
+  secret: string;
+  apiKey?: string;
+  endpoint?: string;
+}
+export function fetchAndVerifyReceipt(opts: FetchAndVerifyOpts): Promise<{
+  ok: boolean;
+  receipt: Record<string, unknown> | null;
+  verified: boolean;
+  reason?: string;
+}>;

package/src/index.js

@@ -0,0 +1,116 @@
+// @yieldagentx402/verify — zero-dep receipt + webhook signature verifier.
+// Browser-safe (WebCrypto), Node 18+, Cloudflare Workers, Deno.
+
+const enc = new TextEncoder();
+
+function hexToBytes(hex) {
+  const h = String(hex || "").replace(/^0x/i, "").toLowerCase();
+  if (h.length % 2 !== 0 || /[^0-9a-f]/.test(h)) throw new Error("invalid hex");
+  const out = new Uint8Array(h.length / 2);
+  for (let i = 0; i < out.length; i++) out[i] = parseInt(h.slice(i*2, i*2+2), 16);
+  return out;
+}
+function bytesToHex(buf) {
+  return Array.from(new Uint8Array(buf), b => b.toString(16).padStart(2, "0")).join("");
+}
+function timingSafeEqualHex(a, b) {
+  const A = String(a || "").toLowerCase();
+  const B = String(b || "").toLowerCase();
+  if (A.length !== B.length) return false;
+  let diff = 0;
+  for (let i = 0; i < A.length; i++) diff |= A.charCodeAt(i) ^ B.charCodeAt(i);
+  return diff === 0;
+}
+
+async function hmacSha256Hex(secret, message) {
+  const key = await crypto.subtle.importKey(
+    "raw", enc.encode(String(secret)),
+    { name: "HMAC", hash: "SHA-256" }, false, ["sign"]
+  );
+  const sig = await crypto.subtle.sign("HMAC", key,
+    typeof message === "string" ? enc.encode(message) : message
+  );
+  return bytesToHex(sig);
+}
+
+/**
+ * Verify a YAX receipt signature.
+ *
+ * @param {object} opts
+ * @param {string} opts.secret      - The shared HMAC secret. Issued with your prod API key.
+ * @param {object|string} opts.receipt - Receipt payload. If an object, JSON-stringified canonically.
+ * @param {string} opts.signature   - Signature string from receipt_signature. Accepts:
+ *                                    "hmac-sha256=<hex>", "<hex>", or "0x<hex>".
+ * @returns {Promise<{ok:boolean, computed:string, provided:string, reason?:string}>}
+ */
+export async function verifyReceipt({ secret, receipt, signature }) {
+  if (!secret)    return { ok: false, computed: "", provided: "", reason: "missing secret" };
+  if (!signature) return { ok: false, computed: "", provided: "", reason: "missing signature" };
+
+  const body = typeof receipt === "string"
+    ? receipt
+    : JSON.stringify(receipt, Object.keys(receipt).sort());
+  const sig = String(signature).replace(/^hmac-sha256=/i, "").replace(/^0x/, "").toLowerCase();
+  const computed = await hmacSha256Hex(secret, body);
+  return {
+    ok:       timingSafeEqualHex(computed, sig),
+    computed,
+    provided: sig,
+  };
+}
+
+/**
+ * Verify an incoming webhook from YieldAgentX402.
+ * Reads the X-YAX-Signature header (or `signature` opt) and checks against the raw body.
+ *
+ * @param {object} opts
+ * @param {string} opts.secret    - YAX_WEBHOOK_SECRET shared with you on production key issuance.
+ * @param {string|ArrayBuffer|Uint8Array} opts.body - Raw HTTP body (string preferred).
+ * @param {string|Headers} opts.signature - Either "hmac-sha256=<hex>" or a Headers object containing X-YAX-Signature.
+ * @returns {Promise<{ok:boolean, computed:string, provided:string, reason?:string}>}
+ */
+export async function verifyWebhook({ secret, body, signature }) {
+  if (!secret) return { ok: false, computed: "", provided: "", reason: "missing secret" };
+  let sigStr = signature;
+  if (signature && typeof signature === "object" && typeof signature.get === "function") {
+    sigStr = signature.get("X-YAX-Signature") || signature.get("x-yax-signature");
+  }
+  if (!sigStr) return { ok: false, computed: "", provided: "", reason: "missing X-YAX-Signature header" };
+  const sig = String(sigStr).replace(/^hmac-sha256=/i, "").replace(/^0x/, "").toLowerCase();
+  const bodyStr = typeof body === "string" ? body :
+                  body instanceof Uint8Array ? new TextDecoder().decode(body) :
+                  body instanceof ArrayBuffer ? new TextDecoder().decode(new Uint8Array(body)) :
+                  String(body);
+  const computed = await hmacSha256Hex(secret, bodyStr);
+  return {
+    ok:       timingSafeEqualHex(computed, sig),
+    computed,
+    provided: sig,
+  };
+}
+
+/**
+ * Convenience: fetch a receipt from the YAX gateway and verify it in one call.
+ *
+ * @param {object} opts
+ * @param {string} opts.runId
+ * @param {string} opts.secret
+ * @param {string} [opts.apiKey]   - Required for non-public receipts.
+ * @param {string} [opts.endpoint] - Defaults to https://api.yieldagentx402.app
+ * @returns {Promise<{ok:boolean, receipt:object|null, verified:boolean, reason?:string}>}
+ */
+export async function fetchAndVerifyReceipt({ runId, secret, apiKey, endpoint }) {
+  const base = String(endpoint || "https://api.yieldagentx402.app").replace(/\/+$/, "");
+  const headers = { "Content-Type": "application/json" };
+  if (apiKey) headers["Authorization"] = `Bearer ${apiKey}`;
+  const r = await fetch(`${base}/api/orchestration/runs/${encodeURIComponent(runId)}`, { headers });
+  if (!r.ok) return { ok: false, receipt: null, verified: false, reason: `HTTP ${r.status}` };
+  const d = await r.json();
+  const run = d.run || d;
+  const sig = run.receipt_signature;
+  if (!sig) return { ok: true, receipt: run, verified: false, reason: "receipt has no signature yet" };
+  const v = await verifyReceipt({ secret, receipt: run, signature: sig });
+  return { ok: true, receipt: run, verified: v.ok };
+}
+
+export default { verifyReceipt, verifyWebhook, fetchAndVerifyReceipt };