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

package/dist/index.js

@@ -595,21 +595,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) => {
@@ -913,6 +913,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));
@@ -1007,6 +1108,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;
@@ -1266,7 +1606,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;
@@ -1276,6 +1662,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) {
@@ -1284,9 +1673,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,
@@ -1333,6 +1725,7 @@ export {
   ConnectorUnreachable,
   DEFAULT_IDEMPOTENCY_WINDOW_SECONDS,
   DEFAULT_RETRY,
+  EXPIRES_AT_UNITS,
   FAKE_EPOCH,
   MAX_IDEMPOTENCY_KEY_LENGTH,
   NO_IDEMPOTENCY_KEY_WARNING,
@@ -1359,15 +1752,23 @@ export {
   fakeValues,
   getConnectionHost,
   graphemes,
-  header,
+  handshakeResponse,
+  header2 as header,
   hmac,
   httpFailure,
   idempotencyKeyFor,
   isEmptyPayload,
   isRemote,
+  isSharedTokenScheme,
+  isSharedTokenSpec,
   isUnconditionallyRetryable,
+  leaseAction,
+  leaseFromResponse,
+  leaseRenewAt,
+  leaseState,
   linkRanges,
   measure,
+  parseMime,
   payloadHash,
   postChain,
   probe,
@@ -1392,11 +1793,13 @@ export {
   shouldRetry,
   sliceByteRange,
   splitToFit,
+  subscriptionLease,
   triggerEvent,
   unchecked,
   utf8Length,
   verifyDelivery,
   verifyHmac,
+  verifySharedToken,
   withResolvedLimit
 };
 //# sourceMappingURL=index.js.map