@particle-academy/fancy-connector-core 0.10.1 → 0.12.0

package/CHANGELOG.md

@@ -6,6 +6,67 @@ 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.12.0] - 2026-11-01
+
+### Added
+
+- **A signed REQUEST LINE and millisecond timestamps (HubSpot v3).** HubSpot
+  signs `base64(HMAC-SHA256(client secret, method + uri + body + timestamp))`,
+  sends `X-HubSpot-Request-Timestamp` in MILLISECONDS, and signs the URI with
+  only its QUERY portion percent-decoded for twelve escapes (never the leading
+  `?`, any `#fragment` dropped). The pieces:
+  - `InboundDelivery` gains optional `method` and `url`; pass the request
+    line exactly as it arrived.
+  - `HmacScheme` gains `timestampUnit` (`"s"` | `"ms"`), `signsRequestLine`
+    (a delivery without its method or URL is refused by name: `delivery
+    carried no request method or url`), and `uri: "hubspot-v3"`.
+  - The CORE normalises the URI (`normaliseSignedUri` /
+    `WebhookVerifier::normaliseSignedUri`; the rules ship as data, in
+    `SIGNED_URI_RULES`), and a scheme's `payload` receives the request line
+    as a fourth argument.
+  - PHP's new `verify()` parameters are appended, so existing calls are
+    unchanged.
+
+  The signed-delivery corpus gains four HubSpot rows, led by HubSpot's
+  PUBLISHED worked example, which reproduces from its inputs.
+- **`TriggerDescriptor.route` `{by, path}`.** It names the one key a delivery
+  that reaches ONE endpoint for many tenants may be routed by (HubSpot's
+  `portalId`; Gmail's `emailAddress`). The rule is fixed: route only after
+  verification, only to a connection or watch the host minted, and drop an
+  unmapped key with a 2xx and a log line, creating nothing. The package
+  declares; the host routes.
+
+`CONNECTOR_API_VERSION` is unchanged: everything here is optional.
+
+## [0.11.0] - 2026-10-28
+
+### Added
+
+- **`decodeFormFieldJson` / `FormFieldJson::decode`: the form-field-json
+  payload transform.** It reads a form-encoded body whose one named field
+  holds JSON, which is how Slack posts every interactivity callback
+  (`payload=<json>`). It runs AFTER signature verification, over the same raw
+  bytes. `+` and `%20` are both spaces. Every `%` must be `%XX` across the
+  WHOLE body, and the bytes must be UTF-8. A missing, doubled or malformed
+  field, or one that is not JSON, is refused BY NAME (`missing-field`,
+  `duplicate-field`, `bad-encoding`, `not-json`; `FormFieldJsonError.reason` /
+  `FormFieldJsonException->reason`). Neither runtime uses its built-in
+  decoder, because `decodeURIComponent` throws on `%zz` where `urldecode`
+  silently keeps it, and a field sent twice is refused rather than resolved
+  first-wins or last-wins. Both runtimes reproduce the hand-authored corpus
+  under `fixtures/form-field-json/`. In PHP, JSON objects come back as
+  arrays, so an empty `{}` is `[]`, as in `Mime::toArray()`.
+- **`TriggerDescriptor.decode` + `decodeDelivery` / `DeliveryDecode::apply`.**
+  A webhook trigger may declare how its verified body is read:
+  `{kind: "form-field-json", field: "payload"}`. A host verifies the raw
+  bytes, then calls the dispatcher with the declaration, then starts the run.
+  An unknown kind is refused by name, never passed through as raw bytes. The
+  kinds ship as data (`DELIVERY_DECODE_KINDS` / `DeliveryDecode::KINDS`).
+  Absent `decode` means a host reads the body as it always has.
+
+`CONNECTOR_API_VERSION` is unchanged: an optional descriptor field changes
+nothing a connector must implement.
+
 ## [0.10.1] - 2026-10-10
 
 ### Fixed

package/dist/index.cjs

@@ -38,14 +38,18 @@ __export(src_exports, {
   ConnectorUnreachable: () => ConnectorUnreachable,
   DEFAULT_IDEMPOTENCY_WINDOW_SECONDS: () => DEFAULT_IDEMPOTENCY_WINDOW_SECONDS,
   DEFAULT_RETRY: () => DEFAULT_RETRY,
+  DELIVERY_DECODE_KINDS: () => DELIVERY_DECODE_KINDS,
   EXPIRES_AT_UNITS: () => EXPIRES_AT_UNITS,
   FAKE_EPOCH: () => FAKE_EPOCH,
+  FORM_FIELD_JSON_REASONS: () => FORM_FIELD_JSON_REASONS,
+  FormFieldJsonError: () => FormFieldJsonError,
   MAX_IDEMPOTENCY_KEY_LENGTH: () => MAX_IDEMPOTENCY_KEY_LENGTH,
   NO_IDEMPOTENCY_KEY_WARNING: () => NO_IDEMPOTENCY_KEY_WARNING,
   PROBLEM_SEVERITIES: () => PROBLEM_SEVERITIES,
   RENDERER_VERSION: () => RENDERER_VERSION,
   REVIEW_STALE_DAYS: () => REVIEW_STALE_DAYS,
   SANDBOX_KINDS: () => SANDBOX_KINDS,
+  SIGNED_URI_RULES: () => SIGNED_URI_RULES,
   SUPPORTED_CONNECTOR_API: () => SUPPORTED_CONNECTOR_API,
   assertConnectorApi: () => assertConnectorApi,
   byteRangeOf: () => byteRangeOf,
@@ -60,6 +64,8 @@ __export(src_exports, {
   compareShape: () => compareShape,
   connectionsFor: () => connectionsFor,
   constantTimeEquals: () => constantTimeEquals,
+  decodeDelivery: () => decodeDelivery,
+  decodeFormFieldJson: () => decodeFormFieldJson,
   deliver: () => deliver,
   fakeRequest: () => fakeRequest,
   fakeValues: () => fakeValues,
@@ -83,6 +89,7 @@ __export(src_exports, {
   linkRanges: () => linkRanges,
   measure: () => measure,
   nextOccurrence: () => nextOccurrence,
+  normaliseSignedUri: () => normaliseSignedUri,
   parseInvite: () => parseInvite,
   parseMime: () => parseMime,
   payloadHash: () => payloadHash,
@@ -1789,6 +1796,77 @@ function parseMime(raw) {
   };
 }
 
+// src/form-field-json.ts
+var FORM_FIELD_JSON_REASONS = ["missing-field", "duplicate-field", "bad-encoding", "not-json"];
+var FormFieldJsonError = class extends Error {
+  constructor(reason, field, message) {
+    super(message);
+    this.reason = reason;
+    this.field = field;
+    this.name = "FormFieldJsonError";
+  }
+  reason;
+  field;
+};
+var UTF8 = new TextDecoder("utf-8", { fatal: true });
+var HEX = /^[0-9A-Fa-f]{2}$/;
+function decodeFormFieldJson(raw, field) {
+  const text = typeof raw === "string" ? raw : latin12(raw);
+  const found = [];
+  for (const pair of text.split("&")) {
+    if (pair === "") continue;
+    const eq = pair.indexOf("=");
+    const name = component(eq === -1 ? pair : pair.slice(0, eq), field);
+    const value2 = component(eq === -1 ? "" : pair.slice(eq + 1), field);
+    if (name === field) found.push(value2);
+  }
+  if (found.length === 0) {
+    throw new FormFieldJsonError("missing-field", field, `the body has no "${field}" field`);
+  }
+  if (found.length > 1) {
+    throw new FormFieldJsonError("duplicate-field", field, `the body has "${field}" ${found.length} times`);
+  }
+  const [value] = found;
+  try {
+    return JSON.parse(value);
+  } catch (error) {
+    throw new FormFieldJsonError("not-json", field, `"${field}" is not JSON: ${error.message}`);
+  }
+}
+function component(encoded, field) {
+  const bytes = [];
+  for (let i = 0; i < encoded.length; i++) {
+    const char = encoded[i];
+    if (char === "+") {
+      bytes.push(32);
+    } else if (char === "%") {
+      const hex = encoded.slice(i + 1, i + 3);
+      if (!HEX.test(hex)) {
+        throw new FormFieldJsonError("bad-encoding", field, `a "%" at byte ${i} is not followed by two hex digits`);
+      }
+      bytes.push(parseInt(hex, 16));
+      i += 2;
+    } else {
+      bytes.push(encoded.charCodeAt(i) & 255);
+    }
+  }
+  try {
+    return UTF8.decode(new Uint8Array(bytes));
+  } catch {
+    throw new FormFieldJsonError("bad-encoding", field, "the decoded bytes are not valid UTF-8");
+  }
+}
+var DELIVERY_DECODE_KINDS = ["form-field-json"];
+function decodeDelivery(decode, raw) {
+  if (decode.kind === "form-field-json") return decodeFormFieldJson(raw, decode.field);
+  throw new Error(`unknown decode kind ${JSON.stringify(decode.kind)}`);
+}
+function latin12(bytes) {
+  let out = "";
+  for (const byte of bytes) out += String.fromCharCode(byte);
+  return out;
+}
+
 // src/probe.ts
 async function probe(spec) {
   let response;
@@ -2005,6 +2083,29 @@ var PROBLEM_SEVERITIES = ["block", "warn"];
 var CANONICAL_METRICS = ["like", "share", "reply", "quote", "view"];
 
 // src/webhook.ts
+var SIGNED_URI_RULES = ["hubspot-v3"];
+var HUBSPOT_V3_DECODE = {
+  "%3A": ":",
+  "%2F": "/",
+  "%3F": "?",
+  "%40": "@",
+  "%21": "!",
+  "%24": "$",
+  "%27": "'",
+  "%28": "(",
+  "%29": ")",
+  "%2A": "*",
+  "%2C": ",",
+  "%3B": ";"
+};
+function normaliseSignedUri(url, rule) {
+  if (rule !== "hubspot-v3") throw new Error(`unknown signed-uri rule ${JSON.stringify(rule)}`);
+  const withoutFragment = url.split("#", 1)[0] ?? "";
+  const q = withoutFragment.indexOf("?");
+  if (q === -1) return withoutFragment;
+  const query = withoutFragment.slice(q + 1).replace(/%[0-9A-Fa-f]{2}/g, (e) => HUBSPOT_V3_DECODE[e.toUpperCase()] ?? e);
+  return `${withoutFragment.slice(0, q)}?${query}`;
+}
 function secretKeyBytes(secret, options = {}) {
   let material = secret;
   if (options.secretPrefix !== void 0) {
@@ -2039,13 +2140,26 @@ async function verifyHmac(options) {
     const sent = Number(timestamp);
     if (!Number.isFinite(sent)) return { ok: false, reason: "timestamp header is not a number" };
     const now = options.now ?? Math.floor(Date.now() / 1e3);
-    if (Math.abs(now - sent) > scheme.tolerance) {
+    const sentSeconds = scheme.timestampUnit === "ms" ? sent / 1e3 : sent;
+    if (Math.abs(now - sentSeconds) > scheme.tolerance) {
       return { ok: false, reason: `delivery is outside the ${scheme.tolerance}s replay window` };
     }
   }
   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);
+  let line;
+  if (scheme.signsRequestLine) {
+    const { method, url } = options.request ?? {};
+    if (!method || !url) return { ok: false, reason: "delivery carried no request method or url" };
+    line = { method, uri: scheme.uri ? normaliseSignedUri(url, scheme.uri) : url };
+  }
+  const expected = await hmac(
+    secret,
+    scheme.payload(raw, timestamp, id, line),
+    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", options = {}) {
@@ -2170,6 +2284,7 @@ async function verifyDelivery(trigger, delivery, secret, now) {
     scheme: spec.scheme,
     timestamp,
     id,
+    ...delivery.method === void 0 && delivery.url === void 0 ? {} : { request: { method: delivery.method ?? "", url: delivery.url ?? "" } },
     ...now === void 0 ? {} : { now }
   });
 }
@@ -2211,14 +2326,18 @@ function hasDelivery(value) {
   ConnectorUnreachable,
   DEFAULT_IDEMPOTENCY_WINDOW_SECONDS,
   DEFAULT_RETRY,
+  DELIVERY_DECODE_KINDS,
   EXPIRES_AT_UNITS,
   FAKE_EPOCH,
+  FORM_FIELD_JSON_REASONS,
+  FormFieldJsonError,
   MAX_IDEMPOTENCY_KEY_LENGTH,
   NO_IDEMPOTENCY_KEY_WARNING,
   PROBLEM_SEVERITIES,
   RENDERER_VERSION,
   REVIEW_STALE_DAYS,
   SANDBOX_KINDS,
+  SIGNED_URI_RULES,
   SUPPORTED_CONNECTOR_API,
   assertConnectorApi,
   byteRangeOf,
@@ -2233,6 +2352,8 @@ function hasDelivery(value) {
   compareShape,
   connectionsFor,
   constantTimeEquals,
+  decodeDelivery,
+  decodeFormFieldJson,
   deliver,
   fakeRequest,
   fakeValues,
@@ -2256,6 +2377,7 @@ function hasDelivery(value) {
   linkRanges,
   measure,
   nextOccurrence,
+  normaliseSignedUri,
   parseInvite,
   parseMime,
   payloadHash,