@particle-academy/fancy-connector-core 0.8.1 → 0.9.0

package/CHANGELOG.md

@@ -6,6 +6,56 @@ All notable changes to `fancy-connector-core` are documented here, in
 **This package is pre-1.0, so breaking changes land in MINOR releases.** The
 version number is not a promise it can keep yet; the entries below are.
 
+## [0.9.0] - 2026-09-15
+
+The verification half of Tynn #11 (Resend inbound email, signed by Svix),
+for the two providers that make it vocabulary: Svix and Stripe, both read
+from their own pages on 2026-09-15. Additive in both runtimes;
+`CONNECTOR_API_VERSION` stays at 1.
+
+### Added
+
+- **`HmacScheme.secretEncoding` (`utf8` | `base64`) and `secretPrefix`**, with
+  `secretKeyBytes()` / `WebhookVerifier::secretKeyBytes()`. Svix hands out
+  `whsec_<base64>`: the HMAC key is the DECODED remainder, raw bytes, half of
+  which are not valid UTF-8 — encoding the text signed with the wrong key and
+  failed exactly like a wrong secret. `utf8` stays the default, byte for
+  byte what 0.8.x did. A secret without its declared prefix, or a base64 one
+  that is not base64, is refused BY NAME (`signing secret does not start with
+  "whsec_"`, `signing secret is not valid base64`) before anything is signed.
+- **`verifyHmac` accepts a LIST of signatures and the delivery passes when
+  ANY matches**; `WebhookVerificationSpec.parse` may return `signatures`
+  beside the 0.8.x `signature`. Stripe signs once per active secret while a
+  secret is rolled and says to compare against EACH; Svix's header "could be
+  any number of signatures" of which yours must match one. An empty list is
+  no signature, never a vacuous match.
+- **`fixtures/signed-delivery/cases.json`** — 14 authored rows, every
+  signature computed by the provider's own rule with `node:crypto` rather
+  than by the code under test: Svix valid, a rotation where only the SECOND
+  signature is current, none current, at and outside the replay window, the
+  secret as text (never matches), a missing prefix and invalid base64 (both
+  named), no signature, no secret; Stripe valid, a roll, a re-serialised
+  body, a missing timestamp. Both runtimes read it; the seed of the
+  conformance suite of that name.
+- **`HmacVerificationSpec.idHeader`, and the payload's third argument.**
+  Svix signs `${svix-id}.${svix-timestamp}.${body}`: the delivery's ID is
+  part of the signed content, so `verifyDelivery` reads the declared header
+  and hands it to `scheme.payload(raw, timestamp, id)` — `verify(...,
+  id:)` in PHP, `verify_hmac(..., id=)` in the Python seed. A declared id
+  header the delivery does not carry is refused as `delivery carried no id
+  header`, never signed with a hole in it. Every two-argument payload
+  written before this release is called exactly as before.
+
+### Fixed
+
+- **A first-only signature rule fails a whole secret roll.** `verifyDelivery`
+  passed only the FIRST signature a header carried, so during Stripe's
+  24-hour roll (or a Svix rotation) every delivery whose first `v1` came
+  from the new secret was refused as `signature did not match` — which reads
+  as a wrong secret, on a day the secret was just changed. Found by Fancy's
+  review of the #11 design; the emitted parsers in weaver.agi collect every
+  signature from the same change on.
+
 ## [0.8.1] - 2026-09-15
 
 ### Changed

package/dist/index.cjs

@@ -101,6 +101,7 @@ __export(src_exports, {
   sandboxIsSelectable: () => sandboxIsSelectable,
   sandboxRefusal: () => sandboxRefusal,
   satisfiesMinimum: () => satisfiesMinimum,
+  secretKeyBytes: () => secretKeyBytes,
   seedFrom: () => seedFrom,
   shapeOf: () => shapeOf,
   shouldRetry: () => shouldRetry,
@@ -1676,12 +1677,35 @@ var PROBLEM_SEVERITIES = ["block", "warn"];
 var CANONICAL_METRICS = ["like", "share", "reply", "quote", "view"];
 
 // src/webhook.ts
+function secretKeyBytes(secret, options = {}) {
+  let material = secret;
+  if (options.secretPrefix !== void 0) {
+    if (!material.startsWith(options.secretPrefix)) {
+      return { reason: `signing secret does not start with ${JSON.stringify(options.secretPrefix)}` };
+    }
+    material = material.slice(options.secretPrefix.length);
+  }
+  if ((options.secretEncoding ?? "utf8") === "base64") {
+    if (!/^[A-Za-z0-9+/]*={0,2}$/.test(material) || material.length % 4 !== 0) {
+      return { reason: "signing secret is not valid base64" };
+    }
+    try {
+      return { bytes: Uint8Array.from(atob(material), (c) => c.charCodeAt(0)) };
+    } catch {
+      return { reason: "signing secret is not valid base64" };
+    }
+  }
+  return { bytes: new TextEncoder().encode(material) };
+}
 async function verifyHmac(options) {
-  const { raw, signature, secret, scheme, timestamp } = options;
+  const { raw, secret, scheme, timestamp, id } = options;
+  const signatures = (Array.isArray(options.signature) ? options.signature : [options.signature]).filter(
+    (s) => typeof s === "string" && s !== ""
+  );
   if (!secret) {
     return { ok: false, reason: "no signing secret configured for this trigger" };
   }
-  if (!signature) return { ok: false, reason: "delivery carried no signature header" };
+  if (signatures.length === 0) return { ok: false, reason: "delivery carried no signature header" };
   if (scheme.tolerance !== void 0) {
     if (!timestamp) return { ok: false, reason: "delivery carried no timestamp header" };
     const sent = Number(timestamp);
@@ -1691,20 +1715,24 @@ async function verifyHmac(options) {
       return { ok: false, reason: `delivery is outside the ${scheme.tolerance}s replay window` };
     }
   }
-  const expected = await hmac(secret, scheme.payload(raw, timestamp), scheme.algorithm, scheme.encoding ?? "hex");
-  return constantTimeEquals(expected, signature) ? { ok: true } : { ok: false, reason: "signature did not match" };
+  const key = secretKeyBytes(secret, scheme);
+  if ("reason" in key) return { ok: false, reason: key.reason };
+  const expected = await hmac(secret, scheme.payload(raw, timestamp, id), scheme.algorithm, scheme.encoding ?? "hex", scheme);
+  return signatures.some((candidate) => constantTimeEquals(expected, candidate)) ? { ok: true } : { ok: false, reason: "signature did not match" };
 }
-async function hmac(secret, payload, algorithm, encoding = "hex") {
+async function hmac(secret, payload, algorithm, encoding = "hex", options = {}) {
   const subtle = globalThis.crypto?.subtle;
   if (!subtle) {
     throw new Error(
       "WebCrypto is not available in this runtime, so webhook signatures cannot be verified. Refusing to accept deliveries unverified."
     );
   }
+  const material = secretKeyBytes(secret, options);
+  if ("reason" in material) throw new Error(material.reason);
   const encoder2 = new TextEncoder();
   const key = await subtle.importKey(
     "raw",
-    encoder2.encode(secret),
+    material.bytes,
     { name: "HMAC", hash: algorithm },
     false,
     ["sign"]
@@ -1805,12 +1833,15 @@ async function verifyDelivery(trigger, delivery, secret, now) {
   const rawHeader = header2(delivery.headers, spec.signatureHeader);
   const parsed = spec.parse && rawHeader ? spec.parse(rawHeader) : { signature: rawHeader };
   const timestamp = parsed.timestamp ?? (spec.timestampHeader ? header2(delivery.headers, spec.timestampHeader) : void 0);
+  const id = spec.idHeader ? header2(delivery.headers, spec.idHeader) : void 0;
+  if (spec.idHeader && !id) return { ok: false, reason: "delivery carried no id header" };
   return verifyHmac({
     raw: delivery.raw,
-    signature: parsed.signature,
+    signature: parsed.signatures ?? parsed.signature,
     secret,
     scheme: spec.scheme,
     timestamp,
+    id,
     ...now === void 0 ? {} : { now }
   });
 }
@@ -1915,6 +1946,7 @@ function hasDelivery(value) {
   sandboxIsSelectable,
   sandboxRefusal,
   satisfiesMinimum,
+  secretKeyBytes,
   seedFrom,
   shapeOf,
   shouldRetry,