@particle-academy/fancy-connector-core 0.6.2 → 0.8.0

package/CHANGELOG.md

@@ -6,6 +6,97 @@ 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.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
+2026-09-14 and both meeting the two-provider bar before shipping: the
+subscription lease is for Google Calendar `events.watch` and Microsoft Graph
+subscriptions; the MIME transform is for inbound email, provider-agnostic,
+with Resend first.
+
+### Added
+
+- **`SubscriptionLease`** (`src/lease.ts`, `SubscriptionLease.php` with
+  `LeaseState` and `LeaseAction`) — the duty a `subscription` trigger carries,
+  as one value: the provider's expiry as an RFC 3339 instant, the connector's
+  `renewBeforeSeconds`, and the `renewOperation` the host calls when due.
+  `leaseState` says where it is (active / due / expired — both boundaries
+  inclusive, expired wins) and `leaseAction` what the host does (none / renew /
+  resync; a missed lease is resync, never a quiet re-create). Both runtimes
+  read `fixtures/subscription-lease/cases.json`. A host runs ONE renewal
+  scheduler for every expiring trigger instead of one per connector.
+- **`parseMime` / `Mime::parse`** — raw MIME in, `headers`, `subject`,
+  `messageId`, `text`, `html`, `parts` and `attachments` out, identical in both
+  runtimes and held to the authored corpus under `fixtures/mime/` (CRLF and
+  LF; folded headers; RFC 2047 B and Q words; quoted-printable and base64;
+  nested multipart; RFC 2231 `filename*`; utf-8, us-ascii, iso-8859-1,
+  iso-8859-15 and windows-1252 — any other charset leaves a part with no
+  text). Attachments carry their bytes as base64. **What to do:** nothing
+  unless you want them; neither touches an existing surface.
+
 ## [0.6.2] - 2026-09-14
 
 ### Fixed

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,15 +65,23 @@ __export(src_exports, {
   fakeValues: () => fakeValues,
   getConnectionHost: () => getConnectionHost,
   graphemes: () => graphemes,
-  header: () => header,
+  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,
   measure: () => measure,
+  parseMime: () => parseMime,
   payloadHash: () => payloadHash,
   postChain: () => postChain,
   probe: () => probe,
@@ -97,11 +106,13 @@ __export(src_exports, {
   shouldRetry: () => shouldRetry,
   sliceByteRange: () => sliceByteRange,
   splitToFit: () => splitToFit,
+  subscriptionLease: () => subscriptionLease,
   triggerEvent: () => triggerEvent,
   unchecked: () => unchecked,
   utf8Length: () => utf8Length,
   verifyDelivery: () => verifyDelivery,
   verifyHmac: () => verifyHmac,
+  verifySharedToken: () => verifySharedToken,
   withResolvedLimit: () => withResolvedLimit
 });
 module.exports = __toCommonJS(src_exports);
@@ -703,21 +714,21 @@ async function prepare(service, connection, options) {
 }
 function encodeForm(form) {
   const pairs = [];
-  const walk = (prefix, value) => {
+  const walk2 = (prefix, value) => {
     if (value === void 0 || value === null) return;
     if (Array.isArray(value)) {
-      value.forEach((item, index) => walk(`${prefix}[${index}]`, item));
+      value.forEach((item, index) => walk2(`${prefix}[${index}]`, item));
       return;
     }
     if (typeof value === "object") {
       for (const [key, nested] of Object.entries(value)) {
-        walk(prefix === "" ? key : `${prefix}[${key}]`, nested);
+        walk2(prefix === "" ? key : `${prefix}[${key}]`, nested);
       }
       return;
     }
     pairs.push(`${encodeURIComponent(prefix)}=${encodeURIComponent(String(value))}`);
   };
-  walk("", form);
+  walk2("", form);
   return pairs.join("&");
 }
 var fetchTransport = async (request) => {
@@ -1021,6 +1032,107 @@ function fnv1a(value) {
   return hash.toString(16).padStart(8, "0");
 }
 
+// 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) {
+  if (typeof value !== "string" || !INSTANT.test(value)) {
+    throw new ConnectorConfigError(
+      `${field} must be an RFC 3339 instant such as "2026-09-22T00:00:00Z", got ${JSON.stringify(value)}. A provider's own shape \u2014 Google's epoch milliseconds, say \u2014 is converted by the connector, never guessed at here.`,
+      at
+    );
+  }
+  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) {
+    throw new ConnectorConfigError(
+      `renewBeforeSeconds must be a positive whole number of seconds, got ${JSON.stringify(input.renewBeforeSeconds)}. Zero would make the lease due only at the instant it expires, which is a lease nobody renews.`,
+      at
+    );
+  }
+  if (typeof input.renewOperation !== "string" || input.renewOperation.trim() === "") {
+    throw new ConnectorConfigError(
+      "renewOperation must name the operation the host calls when the lease is due; a due lease with nothing to call is one nobody renews.",
+      at
+    );
+  }
+  return { expiresAt: input.expiresAt, renewBeforeSeconds: input.renewBeforeSeconds, renewOperation: input.renewOperation };
+}
+function leaseRenewAt(lease) {
+  return new Date(instantMs(lease.expiresAt, "expiresAt", DEFAULT_CONTEXT) - lease.renewBeforeSeconds * 1e3).toISOString();
+}
+function leaseState(lease, now) {
+  const at = now instanceof Date ? now.getTime() : instantMs(now, "now", DEFAULT_CONTEXT);
+  const expires = instantMs(lease.expiresAt, "expiresAt", DEFAULT_CONTEXT);
+  if (at >= expires) return "expired";
+  if (at >= expires - lease.renewBeforeSeconds * 1e3) return "due";
+  return "active";
+}
+function leaseAction(lease, now) {
+  switch (leaseState(lease, now)) {
+    case "active":
+      return "none";
+    case "due":
+      return "renew";
+    case "expired":
+      return "resync";
+  }
+}
+
 // src/metrics.ts
 function compareShape(connectorId, declared, produced) {
   const declaredKeys = new Set((declared ?? []).map((metric) => metric.key));
@@ -1115,6 +1227,245 @@ function providerSandboxIsSelectable(provider) {
   return sandboxIsSelectable(provider.sandbox);
 }
 
+// src/mime.ts
+var CR = 13;
+var LF = 10;
+function latin1(bytes) {
+  let s = "";
+  for (let i = 0; i < bytes.length; i++) s += String.fromCharCode(bytes[i]);
+  return s;
+}
+function bytesOfLatin1(s) {
+  const out = new Uint8Array(s.length);
+  for (let i = 0; i < s.length; i++) out[i] = s.charCodeAt(i) & 255;
+  return out;
+}
+function splitEntity(bytes) {
+  for (let i = 0; i < bytes.length; i++) {
+    if (bytes[i] === LF) {
+      if (bytes[i + 1] === LF) return [i, i + 2];
+      if (bytes[i + 1] === CR && bytes[i + 2] === LF) return [i, i + 3];
+    }
+  }
+  return [bytes.length, bytes.length];
+}
+function parseHeaders(block) {
+  const lines = block.split(/\r?\n/);
+  const unfolded = [];
+  for (const line of lines) {
+    if (line === "") continue;
+    if ((line.startsWith(" ") || line.startsWith("	")) && unfolded.length > 0) {
+      unfolded[unfolded.length - 1] += " " + line.trim();
+    } else {
+      unfolded.push(line);
+    }
+  }
+  const headers = [];
+  for (const line of unfolded) {
+    const colon = line.indexOf(":");
+    if (colon <= 0) continue;
+    headers.push({ name: line.slice(0, colon).trim().toLowerCase(), value: decodeWords(line.slice(colon + 1).trim()) });
+  }
+  return headers;
+}
+function header(headers, name) {
+  return headers.find((h) => h.name === name)?.value ?? null;
+}
+var ENCODED_WORD = /=\?([^?\s]+)\?([BbQq])\?([^?\s]*)\?=/g;
+function decodeWords(value) {
+  const joined = value.replace(/(\?=)[ \t\r\n]+(=\?)/g, "$1$2");
+  return joined.replace(ENCODED_WORD, (whole, charset, encoding, text) => {
+    const bytes = encoding.toUpperCase() === "B" ? base64Bytes(text) : bytesOfLatin1(text.replace(/_/g, " ").replace(/=([0-9A-Fa-f]{2})/g, (_m, h) => String.fromCharCode(parseInt(h, 16))));
+    const decoded = decodeCharset(bytes, charset);
+    return decoded ?? whole;
+  });
+}
+function parseParams(value) {
+  const [head, ...rest] = value.split(";");
+  const params = {};
+  const continued = {};
+  for (const piece of rest) {
+    const eq = piece.indexOf("=");
+    if (eq < 0) continue;
+    let key = piece.slice(0, eq).trim().toLowerCase();
+    let raw = piece.slice(eq + 1).trim();
+    if (raw.startsWith('"') && raw.endsWith('"') && raw.length >= 2) raw = raw.slice(1, -1).replace(/\\(.)/g, "$1");
+    const segment = /^(.+?)\*(\d+)(\*)?$/.exec(key);
+    if (segment) {
+      const [, base, n, star] = segment;
+      (continued[base] ??= [])[Number(n)] = star ? decode2231(raw, Number(n) === 0) : raw;
+      continue;
+    }
+    if (key.endsWith("*")) {
+      key = key.slice(0, -1);
+      params[key] = decode2231(raw, true);
+      continue;
+    }
+    params[key] ??= raw;
+  }
+  for (const [base, parts] of Object.entries(continued)) params[base] = parts.join("");
+  return { main: (head ?? "").trim().toLowerCase(), params };
+}
+var pendingCharset2231 = "utf-8";
+function decode2231(raw, first) {
+  let text = raw;
+  if (first) {
+    const m = /^([^']*)'[^']*'(.*)$/s.exec(raw);
+    if (m) {
+      pendingCharset2231 = m[1] || "utf-8";
+      text = m[2];
+    }
+  }
+  const bytes = bytesOfLatin1(text.replace(/%([0-9A-Fa-f]{2})/g, (_m, h) => String.fromCharCode(parseInt(h, 16))));
+  return decodeCharset(bytes, pendingCharset2231) ?? text;
+}
+function base64Bytes(text) {
+  return new Uint8Array(Buffer.from(text.replace(/[^A-Za-z0-9+/=]/g, ""), "base64"));
+}
+function quotedPrintableBytes(bytes) {
+  const out = [];
+  for (let i = 0; i < bytes.length; i++) {
+    const b = bytes[i];
+    if (b !== 61) {
+      out.push(b);
+      continue;
+    }
+    const a = bytes[i + 1];
+    const c = bytes[i + 2];
+    if (a === LF) {
+      i += 1;
+      continue;
+    }
+    if (a === CR && c === LF) {
+      i += 2;
+      continue;
+    }
+    if (a !== void 0 && c !== void 0 && isHex(a) && isHex(c)) {
+      out.push(parseInt(String.fromCharCode(a, c), 16));
+      i += 2;
+      continue;
+    }
+    out.push(b);
+  }
+  return new Uint8Array(out);
+}
+function isHex(b) {
+  return b >= 48 && b <= 57 || b >= 65 && b <= 70 || b >= 97 && b <= 102;
+}
+function transferDecode(body, encoding) {
+  switch ((encoding ?? "7bit").trim().toLowerCase()) {
+    case "base64":
+      return base64Bytes(latin1(body));
+    case "quoted-printable":
+      return quotedPrintableBytes(body);
+    default:
+      return body;
+  }
+}
+function decodeCharset(bytes, charset) {
+  switch (charset.trim().toLowerCase()) {
+    case "utf-8":
+    case "utf8":
+      return new TextDecoder("utf-8").decode(bytes);
+    case "us-ascii":
+    case "ascii":
+    case "iso-8859-1":
+    case "latin1":
+      return Buffer.from(bytes).toString("latin1");
+    case "windows-1252":
+    case "cp1252":
+      return new TextDecoder("windows-1252").decode(bytes);
+    case "iso-8859-15":
+    case "latin9":
+      return new TextDecoder("iso-8859-15").decode(bytes);
+    default:
+      return null;
+  }
+}
+function walk(bytes, entityHeaders, acc) {
+  const [headerEnd, bodyStart] = splitEntity(bytes);
+  const headers = entityHeaders ?? parseHeaders(latin1(bytes.subarray(0, headerEnd)));
+  const body = bytes.subarray(entityHeaders ? 0 : bodyStart);
+  const type = parseParams(header(headers, "content-type") ?? "text/plain");
+  if (type.main.startsWith("multipart/") && type.params.boundary) {
+    for (const child of splitMultipart(body, type.params.boundary)) walk(child, null, acc);
+    return;
+  }
+  const disposition = parseParams(header(headers, "content-disposition") ?? "");
+  const decoded = transferDecode(body, header(headers, "content-transfer-encoding"));
+  const declaredDisposition = disposition.main === "attachment" || disposition.main === "inline" ? disposition.main : null;
+  const filename = disposition.params.filename ?? type.params.name ?? null;
+  const contentId = header(headers, "content-id")?.replace(/^<|>$/g, "") ?? null;
+  const isText = type.main.startsWith("text/");
+  const isAttachment = declaredDisposition === "attachment" || !isText;
+  const part = {
+    index: acc.parts.length,
+    contentType: type.main,
+    charset: type.params.charset?.toLowerCase() ?? null,
+    disposition: declaredDisposition,
+    filename,
+    contentId,
+    size: decoded.length,
+    headers
+  };
+  acc.parts.push(part);
+  if (isAttachment) {
+    acc.attachments.push({ ...part, content: Buffer.from(decoded).toString("base64") });
+    return;
+  }
+  const text = decodeCharset(decoded, type.params.charset ?? "utf-8");
+  if (text === null) return;
+  if (type.main === "text/plain" && acc.text === null) acc.text = text;
+  if (type.main === "text/html" && acc.html === null) acc.html = text;
+}
+function splitMultipart(body, boundary) {
+  const delimiter = bytesOfLatin1(`--${boundary}`);
+  const children = [];
+  let partStart = -1;
+  for (let i = 0; i <= body.length - delimiter.length; i++) {
+    if (i !== 0 && body[i - 1] !== LF) continue;
+    if (!startsWith(body, i, delimiter)) continue;
+    let partEnd = i;
+    if (partEnd > 0 && body[partEnd - 1] === LF) partEnd -= 1;
+    if (partEnd > 0 && body[partEnd - 1] === CR) partEnd -= 1;
+    if (partStart >= 0) children.push(body.subarray(partStart, partEnd));
+    let j = i + delimiter.length;
+    const closing = body[j] === 45 && body[j + 1] === 45;
+    if (closing) return children;
+    while (j < body.length && body[j] !== LF) j++;
+    partStart = j + 1;
+    i = j;
+  }
+  if (partStart >= 0 && partStart <= body.length) children.push(body.subarray(partStart));
+  return children;
+}
+function startsWith(haystack, at, needle) {
+  for (let k = 0; k < needle.length; k++) if (haystack[at + k] !== needle[k]) return false;
+  return true;
+}
+function parseMime(raw) {
+  const bytes = typeof raw === "string" ? new Uint8Array(Buffer.from(raw, "utf8")) : raw;
+  const [headerEnd, bodyStart] = splitEntity(bytes);
+  const headers = parseHeaders(latin1(bytes.subarray(0, headerEnd)));
+  const body = bytes.subarray(bodyStart);
+  const acc = { parts: [], attachments: [], text: null, html: null };
+  const type = parseParams(header(headers, "content-type") ?? "text/plain");
+  if (type.main.startsWith("multipart/") && type.params.boundary) {
+    for (const child of splitMultipart(body, type.params.boundary)) walk(child, null, acc);
+  } else {
+    walk(body, headers.filter((h) => h.name.startsWith("content-")), acc);
+  }
+  return {
+    headers,
+    subject: header(headers, "subject"),
+    messageId: header(headers, "message-id"),
+    text: acc.text,
+    html: acc.html,
+    parts: acc.parts,
+    attachments: acc.attachments
+  };
+}
+
 // src/probe.ts
 async function probe(spec) {
   let response;
@@ -1374,7 +1725,53 @@ function constantTimeEquals(a, b) {
   for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
   return diff === 0;
 }
-function header(headers, name) {
+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)) {
     if (key.toLowerCase() !== wanted) continue;
@@ -1384,6 +1781,9 @@ function header(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) {
@@ -1392,9 +1792,12 @@ async function verifyDelivery(trigger, delivery, secret, now) {
       reason: `${trigger.service}.${trigger.operation} declares no signature scheme, so a delivery cannot be trusted.`
     };
   }
-  const rawHeader = header(delivery.headers, spec.signatureHeader);
+  if (isSharedTokenSpec(spec)) {
+    return verifySharedToken({ raw: delivery.raw, headers: delivery.headers, secret, scheme: spec.scheme });
+  }
+  const rawHeader = header2(delivery.headers, spec.signatureHeader);
   const parsed = spec.parse && rawHeader ? spec.parse(rawHeader) : { signature: rawHeader };
-  const timestamp = parsed.timestamp ?? (spec.timestampHeader ? header(delivery.headers, spec.timestampHeader) : void 0);
+  const timestamp = parsed.timestamp ?? (spec.timestampHeader ? header2(delivery.headers, spec.timestampHeader) : void 0);
   return verifyHmac({
     raw: delivery.raw,
     signature: parsed.signature,
@@ -1442,6 +1845,7 @@ function hasDelivery(value) {
   ConnectorUnreachable,
   DEFAULT_IDEMPOTENCY_WINDOW_SECONDS,
   DEFAULT_RETRY,
+  EXPIRES_AT_UNITS,
   FAKE_EPOCH,
   MAX_IDEMPOTENCY_KEY_LENGTH,
   NO_IDEMPOTENCY_KEY_WARNING,
@@ -1468,15 +1872,23 @@ function hasDelivery(value) {
   fakeValues,
   getConnectionHost,
   graphemes,
+  handshakeResponse,
   header,
   hmac,
   httpFailure,
   idempotencyKeyFor,
   isEmptyPayload,
   isRemote,
+  isSharedTokenScheme,
+  isSharedTokenSpec,
   isUnconditionallyRetryable,
+  leaseAction,
+  leaseFromResponse,
+  leaseRenewAt,
+  leaseState,
   linkRanges,
   measure,
+  parseMime,
   payloadHash,
   postChain,
   probe,
@@ -1501,11 +1913,13 @@ function hasDelivery(value) {
   shouldRetry,
   sliceByteRange,
   splitToFit,
+  subscriptionLease,
   triggerEvent,
   unchecked,
   utf8Length,
   verifyDelivery,
   verifyHmac,
+  verifySharedToken,
   withResolvedLimit
 });
 //# sourceMappingURL=index.cjs.map