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

package/CHANGELOG.md

@@ -6,6 +6,82 @@ 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.8.1] - 2026-09-15
+
+### Changed
+
+- **`verifyDelivery` dispatches on a NAMED scheme kind and refuses one it does
+  not know.** `HmacScheme` gains an optional `kind?: "hmac"`; absent still
+  means HMAC, because every scheme written before 0.8.0 is one, and
+  `"shared-token"` still goes to the token check — but any other value is now
+  refused by name (`declares a verification scheme "jwt" this runtime does not
+  know`) rather than verified as HMAC. From Fancy's alignment review of
+  0.8.0: `"kind" in scheme` had made refusal-by-default depend on every future
+  scheme remembering to declare a kind. Connectors compile unchanged.
+
+## [0.8.0] - 2026-09-15
+
+The declaration half of the subscription vocabulary (Tynn #15), so a
+generated `subscription` trigger can say how its lease is built and how its
+deliveries are verified, for the two providers that make it vocabulary:
+Google Calendar `events.watch` and Microsoft Graph subscriptions. Additive
+in both runtimes; `CONNECTOR_API_VERSION` stays at 1, because nothing a
+connector must implement changed.
+
+### Added
+
+- **`LeaseDeclaration`** on `TriggerDescriptor.lease` (`LeaseDeclaration.php`
+  with `ExpiresAtUnit`) — `expiresAtFrom` (a dotted path into the create or
+  renew response), `expiresAtUnit` (`rfc3339` | `epoch-ms`; `EXPIRES_AT_UNITS`
+  ships as data), `renewBeforeSeconds`, `renewOperation`.
+- **`leaseFromResponse` / `SubscriptionLease::fromResponse`** — the one
+  conversion from a provider's response to a `SubscriptionLease`. Refuses,
+  naming the path, rather than guess: a missing or null path, digits under
+  `rfc3339`, an instant under `epoch-ms`, a fractional epoch, an unknown unit.
+  Stores the expiry in UTC at millisecond precision, fraction truncated. Both
+  runtimes read `fixtures/lease-from-response/cases.json` (14 rows).
+- **`SharedTokenScheme` and `verifySharedToken`** (`WebhookVerifier::verifySharedToken`)
+  — verification by a token the provider echoes: in a header (Google's
+  `X-Goog-Channel-Token`) or at a dotted body path where `[]` fans out over a
+  batch and every item must match (Graph's `value[].clientState`). Fixed
+  reasons a host can log on: `no shared token configured for this trigger`,
+  `delivery carried no token`, `token did not match`, `delivery body is not
+  JSON`. Both runtimes read `fixtures/shared-token/cases.json` (16 rows).
+- **`ChallengeHandshake` and `handshakeResponse`**
+  (`WebhookVerifier::handshakeResponse`) — Graph's `validationToken` echo on
+  subscription creation, declared as data on the verification spec and
+  answered by a pure function: `{status: 200, contentType: "text/plain",
+  body}` or nothing when the request is not a challenge.
+- **`WebhookVerificationSpec` is a union** of `HmacVerificationSpec` (the
+  0.7.0 shape, unchanged, now with an optional `handshake`) and
+  `SharedTokenVerificationSpec`; `verifyDelivery` dispatches on it and
+  `isSharedTokenSpec` / `isSharedTokenScheme` narrow it. **What to do:** a
+  connector that only CONSTRUCTS a spec compiles unchanged. A host that READS
+  `verification.signatureHeader` off the spec must narrow first
+  (`!isSharedTokenSpec(spec)`); `tsc` will say so.
+
+### Fixed
+
+- **PHP refused a Graph-shaped instant.** `SubscriptionLease::of` parsed the
+  fraction with PHP's six-digit formats, so `2026-09-22T18:23:45.9356913Z`
+  was `not a real instant` in PHP and a lease in TypeScript. Both runtimes now
+  accept one to nine fractional digits and TRUNCATE to milliseconds before
+  comparing, so a `state` boundary cannot fall between a microsecond PHP saw
+  and a millisecond Node saw. (Fancy: the conformance suite gets a row for
+  this.)
+- `MimeMessage.php` had failed `pint --test` since 0.7.0, which is why the
+  core's CI has been red on `main` since that release while the tag's publish
+  run, which does not run pint, went green.
+
+### Changed
+
+- **The subscription-lease table is read from fancy-conformance 0.26.0**
+  (`shared/subscription-lease`), through the package's own `runTable` in both
+  runtimes, and `fixtures/subscription-lease/cases.json` is gone — it was the
+  seed of that suite and landed there unchanged, so keeping it would have been
+  a second table that agrees with the first until somebody edits one. Tests
+  and dev-dependencies only; nothing a consumer installs moved.
+
 ## [0.7.0] - 2026-09-15
 
 Two additions to the connector vocabulary, both approved by the owner on

package/dist/index.cjs

@@ -38,6 +38,7 @@ __export(src_exports, {
   ConnectorUnreachable: () => ConnectorUnreachable,
   DEFAULT_IDEMPOTENCY_WINDOW_SECONDS: () => DEFAULT_IDEMPOTENCY_WINDOW_SECONDS,
   DEFAULT_RETRY: () => DEFAULT_RETRY,
+  EXPIRES_AT_UNITS: () => EXPIRES_AT_UNITS,
   FAKE_EPOCH: () => FAKE_EPOCH,
   MAX_IDEMPOTENCY_KEY_LENGTH: () => MAX_IDEMPOTENCY_KEY_LENGTH,
   NO_IDEMPOTENCY_KEY_WARNING: () => NO_IDEMPOTENCY_KEY_WARNING,
@@ -64,14 +65,18 @@ __export(src_exports, {
   fakeValues: () => fakeValues,
   getConnectionHost: () => getConnectionHost,
   graphemes: () => graphemes,
+  handshakeResponse: () => handshakeResponse,
   header: () => header2,
   hmac: () => hmac,
   httpFailure: () => httpFailure,
   idempotencyKeyFor: () => idempotencyKeyFor,
   isEmptyPayload: () => isEmptyPayload,
   isRemote: () => isRemote,
+  isSharedTokenScheme: () => isSharedTokenScheme,
+  isSharedTokenSpec: () => isSharedTokenSpec,
   isUnconditionallyRetryable: () => isUnconditionallyRetryable,
   leaseAction: () => leaseAction,
+  leaseFromResponse: () => leaseFromResponse,
   leaseRenewAt: () => leaseRenewAt,
   leaseState: () => leaseState,
   linkRanges: () => linkRanges,
@@ -107,6 +112,7 @@ __export(src_exports, {
   utf8Length: () => utf8Length,
   verifyDelivery: () => verifyDelivery,
   verifyHmac: () => verifyHmac,
+  verifySharedToken: () => verifySharedToken,
   withResolvedLimit: () => withResolvedLimit
 });
 module.exports = __toCommonJS(src_exports);
@@ -1027,6 +1033,7 @@ function fnv1a(value) {
 }
 
 // src/lease.ts
+var EXPIRES_AT_UNITS = ["rfc3339", "epoch-ms"];
 var INSTANT = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?(?:Z|[+-]\d{2}:\d{2})$/;
 var DEFAULT_CONTEXT = { service: "", operation: "subscription" };
 function instantMs(value, field, at) {
@@ -1036,12 +1043,59 @@ function instantMs(value, field, at) {
       at
     );
   }
-  const ms = Date.parse(value);
+  const ms = Date.parse(value.replace(/(\.\d{3})\d+/, "$1"));
   if (Number.isNaN(ms)) {
     throw new ConnectorConfigError(`${field} is not a real instant: ${JSON.stringify(value)}`, at);
   }
   return ms;
 }
+function leaseFromResponse(declaration, response, at = DEFAULT_CONTEXT) {
+  const { expiresAtFrom: path, expiresAtUnit: unit } = declaration;
+  if (!EXPIRES_AT_UNITS.includes(unit)) {
+    throw new ConnectorConfigError(
+      `expiresAtUnit must be one of ${EXPIRES_AT_UNITS.join(" | ")}, got ${JSON.stringify(unit)}.`,
+      at
+    );
+  }
+  const value = readPath(response, path);
+  if (value === void 0 || value === null) {
+    throw new ConnectorConfigError(
+      `${path} is not present in the response, so no lease can be built \u2014 a subscription with no known expiry is one nobody renews.`,
+      at
+    );
+  }
+  let expiresAt;
+  if (unit === "epoch-ms") {
+    const ms = typeof value === "number" ? value : typeof value === "string" && /^\d+$/.test(value) ? Number(value) : Number.NaN;
+    if (!Number.isSafeInteger(ms)) {
+      throw new ConnectorConfigError(
+        `${path} must be epoch milliseconds as digits under "epoch-ms", got ${JSON.stringify(value)}.`,
+        at
+      );
+    }
+    expiresAt = new Date(ms).toISOString();
+  } else {
+    if (typeof value !== "string" || !INSTANT.test(value)) {
+      throw new ConnectorConfigError(
+        `${path} must be an RFC 3339 instant under "rfc3339", got ${JSON.stringify(value)}.`,
+        at
+      );
+    }
+    expiresAt = new Date(instantMs(value, path, at)).toISOString();
+  }
+  return subscriptionLease(
+    { expiresAt, renewBeforeSeconds: declaration.renewBeforeSeconds, renewOperation: declaration.renewOperation },
+    at
+  );
+}
+function readPath(value, path) {
+  let current = value;
+  for (const segment of path.split(".")) {
+    if (current === null || typeof current !== "object") return void 0;
+    current = current[segment];
+  }
+  return current;
+}
 function subscriptionLease(input, at = DEFAULT_CONTEXT) {
   instantMs(input.expiresAt, "expiresAt", at);
   if (!Number.isInteger(input.renewBeforeSeconds) || input.renewBeforeSeconds <= 0) {
@@ -1671,6 +1725,52 @@ function constantTimeEquals(a, b) {
   for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
   return diff === 0;
 }
+function isSharedTokenScheme(scheme) {
+  return "kind" in scheme && scheme.kind === "shared-token";
+}
+function verifySharedToken(options) {
+  const { raw, headers, secret, scheme } = options;
+  if (!secret) {
+    return { ok: false, reason: "no shared token configured for this trigger" };
+  }
+  let tokens;
+  if (scheme.in === "header") {
+    tokens = [header2(headers, scheme.name)];
+  } else {
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      return { ok: false, reason: "delivery body is not JSON" };
+    }
+    tokens = readTokens(parsed, scheme.path.split("."));
+  }
+  const present = tokens.filter((t) => t !== void 0 && t !== null && t !== "");
+  if (present.length === 0) return { ok: false, reason: "delivery carried no token" };
+  let matched = present.length === tokens.length;
+  for (const token of present) {
+    matched = typeof token === "string" && constantTimeEquals(secret, token) && matched;
+  }
+  return matched ? { ok: true } : { ok: false, reason: "token did not match" };
+}
+function readTokens(value, segments) {
+  if (segments.length === 0) return [value];
+  const [head, ...rest] = segments;
+  const eachElement = head.endsWith("[]");
+  const key = eachElement ? head.slice(0, -2) : head;
+  if (value === null || typeof value !== "object") return [void 0];
+  const next = value[key];
+  if (!eachElement) return readTokens(next, rest);
+  if (!Array.isArray(next)) return [void 0];
+  return next.flatMap((element) => readTokens(element, rest));
+}
+function handshakeResponse(handshake, query) {
+  if (!handshake) return void 0;
+  const raw = query[handshake.param];
+  const token = Array.isArray(raw) ? raw[0] : raw;
+  if (!token) return void 0;
+  return { status: 200, contentType: handshake.contentType ?? "text/plain", body: token };
+}
 function header2(headers, name) {
   const wanted = name.toLowerCase();
   for (const [key, value] of Object.entries(headers)) {
@@ -1681,6 +1781,9 @@ function header2(headers, name) {
 }
 
 // src/trigger.ts
+function isSharedTokenSpec(spec) {
+  return isSharedTokenScheme(spec.scheme);
+}
 async function verifyDelivery(trigger, delivery, secret, now) {
   const spec = trigger.verification;
   if (!spec) {
@@ -1689,6 +1792,16 @@ async function verifyDelivery(trigger, delivery, secret, now) {
       reason: `${trigger.service}.${trigger.operation} declares no signature scheme, so a delivery cannot be trusted.`
     };
   }
+  if (isSharedTokenSpec(spec)) {
+    return verifySharedToken({ raw: delivery.raw, headers: delivery.headers, secret, scheme: spec.scheme });
+  }
+  const kind = spec.scheme.kind ?? "hmac";
+  if (kind !== "hmac") {
+    return {
+      ok: false,
+      reason: `${trigger.service}.${trigger.operation} declares a verification scheme "${kind}" this runtime does not know \u2014 refusing rather than guessing.`
+    };
+  }
   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);
@@ -1739,6 +1852,7 @@ function hasDelivery(value) {
   ConnectorUnreachable,
   DEFAULT_IDEMPOTENCY_WINDOW_SECONDS,
   DEFAULT_RETRY,
+  EXPIRES_AT_UNITS,
   FAKE_EPOCH,
   MAX_IDEMPOTENCY_KEY_LENGTH,
   NO_IDEMPOTENCY_KEY_WARNING,
@@ -1765,14 +1879,18 @@ function hasDelivery(value) {
   fakeValues,
   getConnectionHost,
   graphemes,
+  handshakeResponse,
   header,
   hmac,
   httpFailure,
   idempotencyKeyFor,
   isEmptyPayload,
   isRemote,
+  isSharedTokenScheme,
+  isSharedTokenSpec,
   isUnconditionallyRetryable,
   leaseAction,
+  leaseFromResponse,
   leaseRenewAt,
   leaseState,
   linkRanges,
@@ -1808,6 +1926,7 @@ function hasDelivery(value) {
   utf8Length,
   verifyDelivery,
   verifyHmac,
+  verifySharedToken,
   withResolvedLimit
 });
 //# sourceMappingURL=index.cjs.map