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

package/CHANGELOG.md

@@ -6,6 +6,38 @@ 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

package/dist/index.cjs

@@ -49,6 +49,7 @@ __export(src_exports, {
   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,
@@ -88,6 +89,7 @@ __export(src_exports, {
   linkRanges: () => linkRanges,
   measure: () => measure,
   nextOccurrence: () => nextOccurrence,
+  normaliseSignedUri: () => normaliseSignedUri,
   parseInvite: () => parseInvite,
   parseMime: () => parseMime,
   payloadHash: () => payloadHash,
@@ -2081,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) {
@@ -2115,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 = {}) {
@@ -2246,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 }
   });
 }
@@ -2298,6 +2337,7 @@ function hasDelivery(value) {
   RENDERER_VERSION,
   REVIEW_STALE_DAYS,
   SANDBOX_KINDS,
+  SIGNED_URI_RULES,
   SUPPORTED_CONNECTOR_API,
   assertConnectorApi,
   byteRangeOf,
@@ -2337,6 +2377,7 @@ function hasDelivery(value) {
   linkRanges,
   measure,
   nextOccurrence,
+  normaliseSignedUri,
   parseInvite,
   parseMime,
   payloadHash,