@fluxpointstudios/orynq-sdk-tool-receipts 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Flux Point Studios
+
+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/dist/index.cjs

@@ -0,0 +1,518 @@
+'use strict';
+
+var orynqSdkProcessTrace = require('@fluxpointstudios/orynq-sdk-process-trace');
+var utils = require('@fluxpointstudios/orynq-sdk-core/utils');
+var crypto = require('crypto');
+
+// src/record.ts
+async function hashToolPayload(value) {
+  const serialized = typeof value === "string" ? value : utils.canonicalize(value);
+  return utils.sha256StringHex(serialized);
+}
+async function addToolReceipt(run, spanId, opts) {
+  if (!opts.toolId) throw new Error("addToolReceipt: toolId is required");
+  if (!opts.receipt) throw new Error("addToolReceipt: receipt is required");
+  const event = {
+    kind: "tool-receipt",
+    visibility: opts.visibility ?? "private",
+    toolId: opts.toolId,
+    request: opts.request,
+    response: opts.response,
+    receipt: opts.receipt
+  };
+  const recorded = await orynqSdkProcessTrace.addEvent(run, spanId, event);
+  return recorded;
+}
+var textEncoder = new TextEncoder();
+function utf8(s) {
+  return Buffer.from(textEncoder.encode(s));
+}
+function constantTimeEqualHex(a, b) {
+  const ab = Buffer.from(a.toLowerCase(), "hex");
+  const bb = Buffer.from(b.toLowerCase(), "hex");
+  if (ab.length === 0 || ab.length !== bb.length) return false;
+  return crypto.timingSafeEqual(ab, bb);
+}
+async function resolveKey(event, ctx, { allowEmbedded }) {
+  if (ctx?.resolveKey) {
+    const k = await ctx.resolveKey(event);
+    if (k !== void 0) return k;
+  }
+  if (ctx?.keys && Object.prototype.hasOwnProperty.call(ctx.keys, event.receipt.signer)) {
+    return ctx.keys[event.receipt.signer];
+  }
+  if (allowEmbedded && ctx?.trustEmbeddedKeys === true) {
+    const p = event.receipt.params;
+    if (p && typeof p.publicKey === "string") return p.publicKey;
+  }
+  return void 0;
+}
+function keyToString(key) {
+  return typeof key === "string" ? key : Buffer.from(key).toString("utf8");
+}
+var SPKI_ALG_OIDS = [
+  // rsaEncryption 1.2.840.113549.1.1.1
+  [42, 134, 72, 134, 247, 13, 1, 1, 1],
+  // id-ecPublicKey 1.2.840.10045.2.1
+  [42, 134, 72, 206, 61, 2, 1],
+  // id-Ed25519 1.3.101.112
+  [43, 101, 112],
+  // id-Ed448 1.3.101.113
+  [43, 101, 113]
+];
+function looksLikeDerPublicKey(bytes) {
+  if (bytes.length < 8 || bytes[0] !== 48) return false;
+  const lenByte = bytes[1];
+  let contentStart;
+  let contentLen;
+  if (lenByte < 128) {
+    contentStart = 2;
+    contentLen = lenByte;
+  } else if (lenByte === 129) {
+    contentStart = 3;
+    contentLen = bytes[2];
+  } else if (lenByte === 130) {
+    contentStart = 4;
+    contentLen = bytes[2] << 8 | bytes[3];
+  } else {
+    return false;
+  }
+  if (contentStart + contentLen !== bytes.length) return false;
+  return SPKI_ALG_OIDS.some((oid) => indexOfBytes(bytes, oid) !== -1);
+}
+function indexOfBytes(haystack, needle) {
+  outer: for (let i = 0; i + needle.length <= haystack.length; i++) {
+    for (let j = 0; j < needle.length; j++) {
+      if (haystack[i + j] !== needle[j]) continue outer;
+    }
+    return i;
+  }
+  return -1;
+}
+function looksLikeAsymmetricPublicKey(key) {
+  if (typeof key !== "string" && looksLikeDerPublicKey(key)) return true;
+  const s = keyToString(key).trim();
+  if (s.includes("-----BEGIN PUBLIC KEY-----") || s.includes("-----BEGIN RSA PUBLIC KEY-----")) {
+    return true;
+  }
+  if (s.startsWith("{")) {
+    try {
+      const jwk = JSON.parse(s);
+      const kty = typeof jwk.kty === "string" ? jwk.kty.toUpperCase() : "";
+      return kty === "RSA" || kty === "EC" || kty === "OKP";
+    } catch {
+      return false;
+    }
+  }
+  return false;
+}
+function assertSymmetricSecret(key, algLabel) {
+  if (looksLikeAsymmetricPublicKey(key)) {
+    throw new Error(
+      `${algLabel}: refusing to HMAC with an asymmetric public key (algorithm confusion). Provide the signer's symmetric secret out-of-band, or pin the asymmetric alg via keyAlgs.`
+    );
+  }
+}
+function assertAlgAllowed(event, ctx, alg) {
+  const allow = ctx?.keyAlgs?.[event.receipt.signer];
+  if (allow && !allow.includes(alg)) {
+    throw new Error(
+      `alg "${alg}" is not in the expected-algorithm allow-list for signer "${event.receipt.signer}"`
+    );
+  }
+}
+function parseStripeSignature(raw, params) {
+  if (raw.includes("v1=") || raw.includes("t=")) {
+    const parts = raw.split(",").map((p) => p.trim());
+    let t2;
+    const v1 = [];
+    for (const part of parts) {
+      const eq = part.indexOf("=");
+      if (eq === -1) continue;
+      const k = part.slice(0, eq);
+      const v = part.slice(eq + 1);
+      if (k === "t") t2 = v;
+      else if (k === "v1") v1.push(v);
+    }
+    return t2 !== void 0 ? { t: t2, v1 } : { v1 };
+  }
+  const t = typeof params?.timestamp === "string" ? params.timestamp : void 0;
+  return t !== void 0 ? { t, v1: [raw] } : { v1: [raw] };
+}
+async function verifyStripeReceipt(event, ctx) {
+  const secret = await resolveKey(event, ctx, { allowEmbedded: false });
+  if (secret === void 0) {
+    throw new Error(
+      "stripe-webhook: signing secret not found \u2014 provide it via verify context (keys/resolveKey), not the trace"
+    );
+  }
+  const { t, v1 } = parseStripeSignature(event.receipt.signature, event.receipt.params);
+  if (t === void 0) throw new Error("stripe-webhook: missing timestamp (t)");
+  if (v1.length === 0) throw new Error("stripe-webhook: missing v1 signature");
+  const toleranceSec = ctx?.toleranceSec ?? 300;
+  const now = ctx?.nowSec ?? Math.floor(Date.now() / 1e3);
+  const ts = Number(t);
+  if (!Number.isFinite(ts)) throw new Error("stripe-webhook: invalid timestamp");
+  if (Math.abs(now - ts) > toleranceSec) {
+    throw new Error(`stripe-webhook: timestamp outside tolerance (${toleranceSec}s)`);
+  }
+  const signedBase = `${t}.${event.receipt.signedPayload}`;
+  const expected = crypto.createHmac("sha256", keyToString(secret)).update(signedBase).digest("hex");
+  return v1.some((candidate) => constantTimeEqualHex(expected, candidate));
+}
+async function verifyGitHubReceipt(event, ctx) {
+  const secret = await resolveKey(event, ctx, { allowEmbedded: false });
+  if (secret === void 0) {
+    throw new Error(
+      "github-webhook: signing secret not found \u2014 provide it via verify context (keys/resolveKey)"
+    );
+  }
+  const ts = event.receipt.params?.timestamp;
+  if (typeof ts === "string" || typeof ts === "number") {
+    const tsNum = Number(ts);
+    if (!Number.isFinite(tsNum)) throw new Error("github-webhook: invalid timestamp");
+    const toleranceSec = ctx?.toleranceSec ?? 300;
+    const now = ctx?.nowSec ?? Math.floor(Date.now() / 1e3);
+    if (Math.abs(now - tsNum) > toleranceSec) {
+      throw new Error(`github-webhook: timestamp outside tolerance (${toleranceSec}s)`);
+    }
+  }
+  const provided = event.receipt.signature.startsWith("sha256=") ? event.receipt.signature.slice("sha256=".length) : event.receipt.signature;
+  const expected = crypto.createHmac("sha256", keyToString(secret)).update(event.receipt.signedPayload).digest("hex");
+  return constantTimeEqualHex(expected, provided);
+}
+function parseJws(event) {
+  const sp = event.receipt.signedPayload;
+  const segments = sp.split(".");
+  let signingInput;
+  let sigB64;
+  if (segments.length === 3) {
+    signingInput = `${segments[0]}.${segments[1]}`;
+    sigB64 = segments[2];
+  } else if (segments.length === 2) {
+    signingInput = sp;
+    sigB64 = event.receipt.signature;
+  } else {
+    throw new Error("jws: signedPayload must be a compact JWS (h.p.s) or signing input (h.p)");
+  }
+  const headerJson = Buffer.from(segments[0], "base64url").toString("utf8");
+  const header = JSON.parse(headerJson);
+  return { signingInput, signature: Buffer.from(sigB64, "base64url"), header };
+}
+async function verifyJwsReceipt(event, ctx) {
+  const { signingInput, signature, header } = parseJws(event);
+  const alg = header.alg;
+  if (!alg || alg === "none") throw new Error(`jws: unsupported alg "${alg}"`);
+  assertAlgAllowed(event, ctx, alg);
+  const data = utf8(signingInput);
+  if (alg.startsWith("HS")) {
+    const secret = await resolveKey(event, ctx, { allowEmbedded: false });
+    if (secret === void 0) throw new Error(`jws(${alg}): HMAC secret not found in verify context`);
+    assertSymmetricSecret(secret, `jws(${alg})`);
+    const hashAlg = `sha${alg.slice(2)}`;
+    const expected = crypto.createHmac(hashAlg, keyToString(secret)).update(data).digest();
+    return expected.length === signature.length && crypto.timingSafeEqual(expected, signature);
+  }
+  const keyMaterial = await resolveKey(event, ctx, { allowEmbedded: true });
+  if (keyMaterial === void 0) throw new Error(`jws(${alg}): public key not found`);
+  const publicKey = toPublicKey(keyMaterial);
+  if (alg.startsWith("RS")) {
+    return crypto.verify(`sha${alg.slice(2)}`, data, publicKey, signature);
+  }
+  if (alg.startsWith("PS")) {
+    const bits = alg.slice(2);
+    return crypto.verify(
+      `sha${bits}`,
+      data,
+      { key: publicKey, padding: 6, saltLength: Number(bits) / 8 },
+      signature
+    );
+  }
+  if (alg.startsWith("ES")) {
+    return crypto.verify(
+      `sha${alg.slice(2)}`,
+      data,
+      { key: publicKey, dsaEncoding: "ieee-p1363" },
+      signature
+    );
+  }
+  if (alg === "EdDSA") {
+    return crypto.verify(null, data, publicKey, signature);
+  }
+  throw new Error(`jws: unsupported alg "${alg}"`);
+}
+var RFC9421_HASH = {
+  "rsa-pss-sha512": "sha512",
+  "rsa-v1_5-sha256": "sha256",
+  "ecdsa-p256-sha256": "sha256",
+  "ecdsa-p384-sha384": "sha384"
+};
+async function verifyHttpMessageReceipt(event, ctx) {
+  const params = event.receipt.params ?? {};
+  const alg = typeof params.alg === "string" ? params.alg : void 0;
+  if (!alg) {
+    throw new Error("http-message-signatures: receipt.params.alg is required (RFC 9421 alg id)");
+  }
+  assertAlgAllowed(event, ctx, alg);
+  const data = utf8(event.receipt.signedPayload);
+  const signature = decodeSignature(event.receipt.signature);
+  if (alg === "ed25519") {
+    const keyMaterial2 = await resolveKey(event, ctx, { allowEmbedded: true });
+    if (keyMaterial2 === void 0) throw new Error("http-message-signatures(ed25519): public key not found");
+    return crypto.verify(null, data, toPublicKey(keyMaterial2), signature);
+  }
+  if (alg === "hmac-sha256") {
+    const secret = await resolveKey(event, ctx, { allowEmbedded: false });
+    if (secret === void 0) throw new Error("http-message-signatures(hmac-sha256): secret not found");
+    assertSymmetricSecret(secret, "http-message-signatures(hmac-sha256)");
+    const expected = crypto.createHmac("sha256", keyToString(secret)).update(data).digest();
+    return expected.length === signature.length && crypto.timingSafeEqual(expected, signature);
+  }
+  const hash = RFC9421_HASH[alg];
+  if (!hash) throw new Error(`http-message-signatures: unsupported alg "${alg}"`);
+  const keyMaterial = await resolveKey(event, ctx, { allowEmbedded: true });
+  if (keyMaterial === void 0) throw new Error(`http-message-signatures(${alg}): public key not found`);
+  const publicKey = toPublicKey(keyMaterial);
+  if (alg === "rsa-pss-sha512") {
+    return crypto.verify(hash, data, { key: publicKey, padding: 6, saltLength: 64 }, signature);
+  }
+  if (alg === "rsa-v1_5-sha256") {
+    return crypto.verify(hash, data, publicKey, signature);
+  }
+  return crypto.verify(hash, data, { key: publicKey, dsaEncoding: "ieee-p1363" }, signature);
+}
+function toPublicKey(material) {
+  if (typeof material === "string") {
+    const trimmed = material.trim();
+    if (trimmed.startsWith("{")) {
+      return crypto.createPublicKey({ key: JSON.parse(trimmed), format: "jwk" });
+    }
+    return crypto.createPublicKey(material);
+  }
+  return crypto.createPublicKey(Buffer.from(material));
+}
+function decodeSignature(sig) {
+  if (sig.startsWith("0x")) return Buffer.from(sig.slice(2), "hex");
+  if (/[-_]/.test(sig)) return Buffer.from(sig, "base64url");
+  return Buffer.from(sig, "base64");
+}
+async function responseCommitmentHash(event) {
+  const { scheme, signedPayload } = event.receipt;
+  switch (scheme) {
+    case "jws": {
+      const segs = signedPayload.split(".");
+      if (segs.length < 2 || !segs[1]) return null;
+      const body = Buffer.from(segs[1], "base64url").toString("utf8");
+      return utils.sha256StringHex(body);
+    }
+    case "stripe-webhook":
+    case "github-webhook":
+      return utils.sha256StringHex(signedPayload);
+    case "http-message-signatures":
+      return contentDigestSha256Hex(signedPayload);
+    default:
+      return null;
+  }
+}
+function jwsBindingContext(event) {
+  if (event.receipt.scheme !== "jws") return null;
+  const seg0 = event.receipt.signedPayload.split(".")[0];
+  if (!seg0) return null;
+  try {
+    const header = JSON.parse(Buffer.from(seg0, "base64url").toString("utf8"));
+    const b = header.orynqBinding;
+    if (!b || typeof b.runId !== "string") return null;
+    return typeof b.requestHash === "string" ? { runId: b.runId, requestHash: b.requestHash } : { runId: b.runId };
+  } catch {
+    return null;
+  }
+}
+function contentDigestSha256Hex(signatureBase) {
+  for (const line of signatureBase.split("\n")) {
+    const m = /^"content-digest":\s*(.+)$/i.exec(line.trim());
+    if (!m) continue;
+    const d = /sha-256=:([A-Za-z0-9+/=]+):/.exec(m[1]);
+    if (!d || !d[1]) return null;
+    return Buffer.from(d[1], "base64").toString("hex");
+  }
+  return null;
+}
+var BUILTIN_TOOL_RECEIPT_VERIFIERS = {
+  "stripe-webhook": verifyStripeReceipt,
+  "github-webhook": verifyGitHubReceipt,
+  jws: verifyJwsReceipt,
+  "http-message-signatures": verifyHttpMessageReceipt
+};
+function hexEq(a, b) {
+  const na = a.startsWith("0x") ? a.slice(2) : a;
+  const nb = b.startsWith("0x") ? b.slice(2) : b;
+  return na.toLowerCase() === nb.toLowerCase();
+}
+function extractToolReceipts(bundle) {
+  return bundle.privateRun.events.filter(
+    (e) => e.kind === "tool-receipt"
+  );
+}
+async function verifyToolReceipt(event, ctx) {
+  const scheme = event.receipt.scheme;
+  const base = {
+    eventId: event.id,
+    toolId: event.toolId,
+    scheme,
+    signer: event.receipt.signer
+  };
+  const callBound = false;
+  const verifier = ctx?.verifiers?.[scheme] ?? BUILTIN_TOOL_RECEIPT_VERIFIERS[scheme];
+  if (!verifier) {
+    return {
+      ...base,
+      callBound,
+      verified: false,
+      error: `no verifier registered for scheme "${scheme}"`
+    };
+  }
+  try {
+    const sigValid = await verifier(event, ctx);
+    if (!sigValid) return { ...base, callBound, verified: false, reason: "signature-invalid" };
+    const commit = await responseCommitmentHash(event);
+    if (commit === null) {
+      return { ...base, callBound, verified: false, reason: "response-not-bound" };
+    }
+    if (!hexEq(commit, event.response.hash)) {
+      return { ...base, callBound, verified: false, reason: "response-binding-mismatch" };
+    }
+    if (event.response.payload !== void 0) {
+      const payloadHash = await hashToolPayload(event.response.payload);
+      if (!hexEq(payloadHash, event.response.hash)) {
+        return { ...base, callBound, verified: false, reason: "response-payload-mismatch" };
+      }
+    }
+    let provenCallBound = false;
+    if (scheme === "jws") {
+      const bound = jwsBindingContext(event);
+      if (bound !== null) {
+        if (ctx?.runId !== void 0 && bound.runId !== ctx.runId) {
+          return { ...base, callBound, verified: false, reason: "call-binding-mismatch" };
+        }
+        if (bound.requestHash !== void 0 && !hexEq(bound.requestHash, event.request.hash)) {
+          return { ...base, callBound, verified: false, reason: "call-binding-mismatch" };
+        }
+        provenCallBound = bound.requestHash !== void 0 && hexEq(bound.requestHash, event.request.hash) && ctx?.runId !== void 0 && bound.runId === ctx.runId;
+      }
+    }
+    if (ctx?.requireCallBinding && !provenCallBound) {
+      return { ...base, callBound: provenCallBound, verified: false, reason: "call-binding-required" };
+    }
+    return { ...base, callBound: provenCallBound, verified: true };
+  } catch (error) {
+    return {
+      ...base,
+      callBound,
+      verified: false,
+      error: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+async function verifyToolReceipts(bundle, ctx) {
+  const events = extractToolReceipts(bundle);
+  const boundCtx = {
+    ...ctx,
+    runId: ctx?.runId ?? bundle.privateRun.id
+  };
+  const results = [];
+  for (const event of events) {
+    results.push(await verifyToolReceipt(event, boundCtx));
+  }
+  const failed = results.filter((r) => !r.verified);
+  return {
+    valid: failed.length === 0,
+    errors: failed.map(
+      (f) => `tool-receipt "${f.toolId}" (${f.scheme}) failed${f.reason ? ` [${f.reason}]` : ""}${f.error ? `: ${f.error}` : ""}`
+    ),
+    results
+  };
+}
+async function verifyTrace(bundle, ctx) {
+  const outcome = await verifyToolReceipts(bundle, ctx);
+  const result = await orynqSdkProcessTrace.verifyBundle(bundle, {
+    toolReceipts: () => ({ valid: outcome.valid, errors: outcome.errors })
+  });
+  return { ...result, toolReceipts: outcome };
+}
+function b64url(input) {
+  return Buffer.from(input).toString("base64url");
+}
+function signJws(opts, signingInput) {
+  const data = Buffer.from(signingInput, "utf8");
+  if (opts.alg === "HS256") {
+    if (!opts.secret) throw new Error("createSigningProxy(HS256): `secret` is required");
+    return crypto.createHmac("sha256", opts.secret).update(data).digest();
+  }
+  if (!opts.privateKey) {
+    throw new Error(`createSigningProxy(${opts.alg}): \`privateKey\` is required`);
+  }
+  const key = typeof opts.privateKey === "string" ? crypto.createPrivateKey(opts.privateKey) : opts.privateKey;
+  if (opts.alg === "EdDSA") return crypto.sign(null, data, key);
+  if (opts.alg.startsWith("ES")) {
+    return crypto.sign(`sha${opts.alg.slice(2)}`, data, { key, dsaEncoding: "ieee-p1363" });
+  }
+  if (opts.alg.startsWith("PS")) {
+    return crypto.sign(`sha${opts.alg.slice(2)}`, data, {
+      key,
+      padding: 6,
+      saltLength: Number(opts.alg.slice(2)) / 8
+    });
+  }
+  if (opts.alg.startsWith("RS")) {
+    return crypto.sign(`sha${opts.alg.slice(2)}`, data, key);
+  }
+  throw new Error(`createSigningProxy: unsupported alg "${opts.alg}"`);
+}
+function createSigningProxy(opts) {
+  if (!opts.signer) throw new Error("createSigningProxy: `signer` is required");
+  return {
+    sign(payload) {
+      const header = { alg: opts.alg, typ: "JWT", kid: opts.signer };
+      if (opts.binding) {
+        header.orynqBinding = {
+          runId: opts.binding.runId,
+          ...opts.binding.requestHash !== void 0 ? { requestHash: opts.binding.requestHash } : {}
+        };
+      }
+      const h = b64url(JSON.stringify(header));
+      const body = typeof payload === "string" ? payload : utils.canonicalize(payload);
+      const p = b64url(body);
+      const signingInput = `${h}.${p}`;
+      const sigB64 = b64url(signJws(opts, signingInput));
+      return {
+        // signedPayload is the JWS *signing input* (the bytes actually signed);
+        // the signature is carried separately so it is independently checkable.
+        scheme: "jws",
+        signer: opts.signer,
+        signature: sigB64,
+        signedPayload: signingInput,
+        ...opts.publicKey ? { params: { publicKey: opts.publicKey } } : {}
+      };
+    }
+  };
+}
+
+// src/index.ts
+var VERSION = "0.1.0";
+
+exports.BUILTIN_TOOL_RECEIPT_VERIFIERS = BUILTIN_TOOL_RECEIPT_VERIFIERS;
+exports.VERSION = VERSION;
+exports.addToolReceipt = addToolReceipt;
+exports.createSigningProxy = createSigningProxy;
+exports.extractToolReceipts = extractToolReceipts;
+exports.hashToolPayload = hashToolPayload;
+exports.jwsBindingContext = jwsBindingContext;
+exports.verifyGitHubReceipt = verifyGitHubReceipt;
+exports.verifyHttpMessageReceipt = verifyHttpMessageReceipt;
+exports.verifyJwsReceipt = verifyJwsReceipt;
+exports.verifyStripeReceipt = verifyStripeReceipt;
+exports.verifyToolReceipt = verifyToolReceipt;
+exports.verifyToolReceipts = verifyToolReceipts;
+exports.verifyTrace = verifyTrace;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map