@spreadspace/embed 0.1.0

package/dist/webhooks.cjs

@@ -0,0 +1,141 @@
+'use strict';
+
+var crypto = require('crypto');
+
+// src/webhook-signature.ts
+var DEFAULT_FRESHNESS_TOLERANCE_SECONDS = 5 * 60;
+var VERSION_1_PREFIX = "v1";
+function verifyWebhookSignature(rawBody, signature, secret, options) {
+  if (typeof signature !== "string" || signature.length === 0) {
+    throw new WebhookSignatureError("SpreadSpace-Signature header is missing or empty.");
+  }
+  if (typeof secret !== "string" || secret.length === 0) {
+    throw new WebhookSignatureError("Webhook signing secret is missing or empty.");
+  }
+  if (rawBody === null || rawBody === void 0) {
+    throw new WebhookSignatureError("Webhook raw body is missing.");
+  }
+  const parsed = parseSignatureHeader(signature);
+  if (!parsed) {
+    throw new WebhookSignatureError("Webhook signature header is malformed.");
+  }
+  const { timestamp, hex } = parsed;
+  const bodyString = bodyToString(rawBody);
+  const expectedHex = computeHmacHex(secret, `${timestamp}.${bodyString}`);
+  if (!hexEquals(expectedHex, hex)) {
+    throw new WebhookSignatureError("Webhook signature does not match.");
+  }
+  const tolerance = options?.freshnessTolerance ?? DEFAULT_FRESHNESS_TOLERANCE_SECONDS;
+  const now = options?.currentTimestamp ?? Math.floor(Date.now() / 1e3);
+  const age = now - timestamp;
+  if (age > tolerance || age < -tolerance) {
+    throw new WebhookSignatureError(
+      `Webhook timestamp is outside the freshness window of ${tolerance}s.`
+    );
+  }
+  return true;
+}
+function verifyAndParseWebhook(rawBody, signature, secret, options) {
+  verifyWebhookSignature(rawBody, signature, secret, options);
+  const bodyString = bodyToString(rawBody);
+  let parsed;
+  try {
+    parsed = JSON.parse(bodyString);
+  } catch (cause) {
+    throw new WebhookSignatureError("Webhook body is not valid JSON.", cause);
+  }
+  if (!isPlainObject(parsed)) {
+    throw new WebhookSignatureError("Webhook body is not a JSON object.");
+  }
+  const candidate = parsed;
+  if (typeof candidate.type !== "string" || candidate.type.length === 0) {
+    throw new WebhookSignatureError("Webhook body is missing a `type` field.");
+  }
+  if (typeof candidate.id !== "string" || candidate.id.length === 0) {
+    throw new WebhookSignatureError("Webhook body is missing an `id` field.");
+  }
+  if (typeof candidate.created !== "number") {
+    throw new WebhookSignatureError("Webhook body is missing a numeric `created` field.");
+  }
+  if (typeof candidate.tenant_id !== "string" || candidate.tenant_id.length === 0) {
+    throw new WebhookSignatureError("Webhook body is missing a `tenant_id` field.");
+  }
+  if (!isPlainObject(candidate.data)) {
+    throw new WebhookSignatureError("Webhook body is missing a `data` object.");
+  }
+  return parsed;
+}
+var WebhookSignatureError = class _WebhookSignatureError extends Error {
+  cause;
+  constructor(message, cause) {
+    super(message);
+    this.name = "WebhookSignatureError";
+    this.cause = cause;
+    Object.setPrototypeOf(this, _WebhookSignatureError.prototype);
+  }
+};
+function parseSignatureHeader(header) {
+  const segments = header.split(",").filter((s) => s.length > 0);
+  if (segments.length < 2) return null;
+  let parsedTs = null;
+  let parsedV1 = null;
+  for (const raw of segments) {
+    const segment = raw.trim();
+    const eq = segment.indexOf("=");
+    if (eq <= 0 || eq === segment.length - 1) {
+      return null;
+    }
+    const key = segment.slice(0, eq).trim();
+    const value = segment.slice(eq + 1).trim();
+    if (key === "t") {
+      if (parsedTs !== null) return null;
+      if (!/^-?\d+$/.test(value)) return null;
+      const ts = Number(value);
+      if (!Number.isFinite(ts) || !Number.isInteger(ts)) return null;
+      parsedTs = ts;
+    } else if (key === VERSION_1_PREFIX) {
+      if (parsedV1 !== null) return null;
+      if (value.length === 0) return null;
+      parsedV1 = value;
+    }
+  }
+  if (parsedTs === null || parsedV1 === null) return null;
+  return { timestamp: parsedTs, hex: parsedV1 };
+}
+function computeHmacHex(secret, signedPayload) {
+  const hmac = crypto.createHmac("sha256", Buffer.from(secret, "utf-8"));
+  hmac.update(Buffer.from(signedPayload, "utf-8"));
+  return hmac.digest("hex");
+}
+function hexEquals(expectedHex, providedHex) {
+  if (expectedHex.length !== providedHex.length) return false;
+  let expectedBytes;
+  let providedBytes;
+  try {
+    expectedBytes = Buffer.from(expectedHex, "hex");
+    providedBytes = Buffer.from(providedHex, "hex");
+  } catch {
+    return false;
+  }
+  if (expectedBytes.length !== providedBytes.length) return false;
+  if (expectedBytes.length * 2 !== expectedHex.length) return false;
+  if (providedBytes.length * 2 !== providedHex.length) return false;
+  return crypto.timingSafeEqual(
+    new Uint8Array(expectedBytes.buffer, expectedBytes.byteOffset, expectedBytes.byteLength),
+    new Uint8Array(providedBytes.buffer, providedBytes.byteOffset, providedBytes.byteLength)
+  );
+}
+function bodyToString(body) {
+  if (typeof body === "string") return body;
+  if (Buffer.isBuffer(body)) return body.toString("utf-8");
+  return Buffer.from(body).toString("utf-8");
+}
+function isPlainObject(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+exports.WebhookSignatureError = WebhookSignatureError;
+exports.verifyAndParseWebhook = verifyAndParseWebhook;
+exports.verifyWebhookSignature = verifyWebhookSignature;
+//# sourceMappingURL=webhooks.cjs.map
+//# sourceMappingURL=webhooks.cjs.map

package/dist/webhooks.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/webhook-signature.ts"],"names":["createHmac","timingSafeEqual"],"mappings":"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","file":"webhooks.cjs","sourcesContent":["import { createHmac, timingSafeEqual } from 'node:crypto';\n\nimport type { VerifyAndParseResult, WebhookEvent } from './types.js';\n\n/**\n * Webhook signature verifier — byte-for-byte compatible with\n * `api/src/Webhooks/WebhookSigner.cs` on the API side.\n *\n * Wire format (mirrors Stripe's `Stripe-Signature`):\n *\n *   SpreadSpace-Signature: t=<unix_seconds>,v1=<hex_hmac_sha256(secret, \"{t}.{body}\")>\n *\n * The verifier:\n *   1. Parses `t=...` and `v1=...` tokens (tolerant of additional unrecognized\n *      pairs to stay forward-compatible with future schemes).\n *   2. Recomputes HMAC-SHA256 over `\"{timestamp}.{rawBody}\"` with the secret.\n *   3. Compares with `crypto.timingSafeEqual` on raw bytes (never on hex\n *      strings — string `===` short-circuits and leaks prefix info via timing).\n *   4. Two-sided freshness check: rejects timestamps too far in the past\n *      (replay protection) AND too far in the future (attacker-controlled\n *      timestamps that would extend the replay window).\n *\n * Verification order matches the C# side: HMAC first, then freshness. That\n * way a forged-but-fresh request and a real-but-stale request fail\n * indistinguishably from the timing perspective.\n */\n\n/** Default freshness tolerance — matches `WebhookSignatureFormat.DefaultFreshnessTolerance`. */\nconst DEFAULT_FRESHNESS_TOLERANCE_SECONDS = 5 * 60;\n\n/** Wire constant for the v1 HMAC-SHA256 scheme. */\nconst VERSION_1_PREFIX = 'v1';\n\nexport interface VerifyOptions {\n  /**\n   * Maximum age (and maximum future skew) of the timestamp before the\n   * signature is rejected as stale. Symmetric — `Math.abs(now - t)` must be\n   * ≤ this value.\n   *\n   * Default: 300 seconds (5 minutes).\n   */\n  freshnessTolerance?: number;\n\n  /**\n   * Override the \"current time\" used for the freshness check. Useful in\n   * tests; otherwise leave undefined and the verifier reads\n   * `Date.now() / 1000`.\n   */\n  currentTimestamp?: number;\n}\n\n/**\n * Verify a `SpreadSpace-Signature` header against a body and signing\n * secret. Throws on any failure (invalid format, bad HMAC, stale timestamp,\n * wrong secret); returns `true` on success.\n *\n * @param rawBody  The exact request body received on the wire — bytes, not\n *   re-serialized JSON. Any byte-level transformation between receipt and\n *   verification (re-stringification, gzip decode, encoding change) will\n *   invalidate the signature.\n * @param signature  Contents of the `SpreadSpace-Signature` HTTP header.\n * @param secret  The plaintext signing secret (`whsec_...`) issued at\n *   webhook endpoint creation. Never log this.\n * @param options  Optional overrides — freshness window and clock injection.\n */\nexport function verifyWebhookSignature(\n  rawBody: string | Buffer | Uint8Array,\n  signature: string,\n  secret: string,\n  options?: VerifyOptions,\n): true {\n  if (typeof signature !== 'string' || signature.length === 0) {\n    throw new WebhookSignatureError('SpreadSpace-Signature header is missing or empty.');\n  }\n  if (typeof secret !== 'string' || secret.length === 0) {\n    throw new WebhookSignatureError('Webhook signing secret is missing or empty.');\n  }\n  if (rawBody === null || rawBody === undefined) {\n    throw new WebhookSignatureError('Webhook raw body is missing.');\n  }\n\n  const parsed = parseSignatureHeader(signature);\n  if (!parsed) {\n    throw new WebhookSignatureError('Webhook signature header is malformed.');\n  }\n  const { timestamp, hex } = parsed;\n\n  // HMAC FIRST. We never want to leak (via differential timing or distinct\n  // error message text) whether a request was a forged signature vs. a real\n  // one that aged out — both should be indistinguishable failures.\n  const bodyString = bodyToString(rawBody);\n  const expectedHex = computeHmacHex(secret, `${timestamp}.${bodyString}`);\n\n  if (!hexEquals(expectedHex, hex)) {\n    throw new WebhookSignatureError('Webhook signature does not match.');\n  }\n\n  // Then freshness. Two-sided check: too old OR too far in the future.\n  const tolerance = options?.freshnessTolerance ?? DEFAULT_FRESHNESS_TOLERANCE_SECONDS;\n  const now = options?.currentTimestamp ?? Math.floor(Date.now() / 1000);\n  const age = now - timestamp;\n  if (age > tolerance || age < -tolerance) {\n    throw new WebhookSignatureError(\n      `Webhook timestamp is outside the freshness window of ${tolerance}s.`,\n    );\n  }\n\n  return true;\n}\n\n/**\n * Verify a webhook signature and JSON-parse the body into a typed\n * `WebhookEvent` envelope. Throws on signature failure or invalid JSON.\n *\n * The returned value is a discriminated union over `type` — switch on\n * `event.type` to narrow `event.data` to the matching payload.\n */\nexport function verifyAndParseWebhook(\n  rawBody: string | Buffer | Uint8Array,\n  signature: string,\n  secret: string,\n  options?: VerifyOptions,\n): VerifyAndParseResult {\n  verifyWebhookSignature(rawBody, signature, secret, options);\n\n  const bodyString = bodyToString(rawBody);\n\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(bodyString);\n  } catch (cause) {\n    throw new WebhookSignatureError('Webhook body is not valid JSON.', cause);\n  }\n\n  if (!isPlainObject(parsed)) {\n    throw new WebhookSignatureError('Webhook body is not a JSON object.');\n  }\n  const candidate = parsed as Partial<WebhookEvent>;\n  if (typeof candidate.type !== 'string' || candidate.type.length === 0) {\n    throw new WebhookSignatureError('Webhook body is missing a `type` field.');\n  }\n  if (typeof candidate.id !== 'string' || candidate.id.length === 0) {\n    throw new WebhookSignatureError('Webhook body is missing an `id` field.');\n  }\n  if (typeof candidate.created !== 'number') {\n    throw new WebhookSignatureError('Webhook body is missing a numeric `created` field.');\n  }\n  if (typeof candidate.tenant_id !== 'string' || candidate.tenant_id.length === 0) {\n    throw new WebhookSignatureError('Webhook body is missing a `tenant_id` field.');\n  }\n  if (!isPlainObject(candidate.data)) {\n    throw new WebhookSignatureError('Webhook body is missing a `data` object.');\n  }\n\n  return parsed as VerifyAndParseResult;\n}\n\n/**\n * Thrown when a webhook signature fails verification or the envelope is\n * structurally malformed. Distinct from `SpreadSpaceError` because webhook\n * verification is a self-contained primitive — verifiers don't need the\n * full request/response error machinery, just a single failure type they\n * can reject against.\n */\nexport class WebhookSignatureError extends Error {\n  public readonly cause?: unknown;\n\n  constructor(message: string, cause?: unknown) {\n    super(message);\n    this.name = 'WebhookSignatureError';\n    this.cause = cause;\n    Object.setPrototypeOf(this, WebhookSignatureError.prototype);\n  }\n}\n\n// ────────────────────────────────────────────────────────────────────────────\n// Internals\n// ────────────────────────────────────────────────────────────────────────────\n\ninterface ParsedSignature {\n  timestamp: number;\n  hex: string;\n}\n\n/**\n * Parse a header in the form `t=<long>,v1=<hex>`. Tolerant of whitespace\n * between segments and of additional unrecognized pairs (e.g. a future\n * `v2=...`) — those are silently ignored, not treated as parse errors, so\n * this verifier remains forward-compatible with new schemes.\n */\nfunction parseSignatureHeader(header: string): ParsedSignature | null {\n  const segments = header.split(',').filter((s) => s.length > 0);\n  if (segments.length < 2) return null;\n\n  let parsedTs: number | null = null;\n  let parsedV1: string | null = null;\n\n  for (const raw of segments) {\n    const segment = raw.trim();\n    const eq = segment.indexOf('=');\n    if (eq <= 0 || eq === segment.length - 1) {\n      // Missing key, missing value, or `=` at the very end (`v1=`).\n      return null;\n    }\n\n    const key = segment.slice(0, eq).trim();\n    const value = segment.slice(eq + 1).trim();\n\n    if (key === 't') {\n      if (parsedTs !== null) return null; // Duplicate `t=`.\n      // Strict integer parse — reject `1.5`, `1e3`, leading `+`, etc. The C#\n      // verifier uses `long.TryParse(NumberStyles.Integer, Invariant)`,\n      // which accepts an optional leading `-` and digits only. We mirror that.\n      if (!/^-?\\d+$/.test(value)) return null;\n      const ts = Number(value);\n      if (!Number.isFinite(ts) || !Number.isInteger(ts)) return null;\n      parsedTs = ts;\n    } else if (key === VERSION_1_PREFIX) {\n      if (parsedV1 !== null) return null; // Duplicate `v1=`.\n      if (value.length === 0) return null;\n      parsedV1 = value;\n    }\n    // Any other key — silently ignored for forward compatibility.\n  }\n\n  if (parsedTs === null || parsedV1 === null) return null;\n  return { timestamp: parsedTs, hex: parsedV1 };\n}\n\n/**\n * Compute lowercase hex HMAC-SHA256 digest. Matches the C# side's\n * `Convert.ToHexStringLower(hmac.ComputeHash(...))` exactly.\n */\nfunction computeHmacHex(secret: string, signedPayload: string): string {\n  const hmac = createHmac('sha256', Buffer.from(secret, 'utf-8'));\n  hmac.update(Buffer.from(signedPayload, 'utf-8'));\n  return hmac.digest('hex'); // Node default is lowercase.\n}\n\n/**\n * Constant-time compare of two hex strings. We decode both sides to bytes\n * before calling `timingSafeEqual` — it requires equal-length inputs and\n * we want a length mismatch to fail fast (length is not timing-sensitive\n * since both ends know SHA-256 emits 64 hex chars).\n */\nfunction hexEquals(expectedHex: string, providedHex: string): boolean {\n  if (expectedHex.length !== providedHex.length) return false;\n\n  let expectedBytes: Buffer;\n  let providedBytes: Buffer;\n  try {\n    expectedBytes = Buffer.from(expectedHex, 'hex');\n    providedBytes = Buffer.from(providedHex, 'hex');\n  } catch {\n    return false;\n  }\n\n  // `Buffer.from(..., 'hex')` silently stops at the first non-hex character,\n  // producing a shorter buffer — guard explicitly against that to avoid a\n  // false equality when the provided hex has invalid characters that happen\n  // to truncate to an empty buffer the receiver also produced.\n  if (expectedBytes.length !== providedBytes.length) return false;\n  if (expectedBytes.length * 2 !== expectedHex.length) return false;\n  if (providedBytes.length * 2 !== providedHex.length) return false;\n\n  return timingSafeEqual(\n    new Uint8Array(expectedBytes.buffer, expectedBytes.byteOffset, expectedBytes.byteLength),\n    new Uint8Array(providedBytes.buffer, providedBytes.byteOffset, providedBytes.byteLength),\n  );\n}\n\nfunction bodyToString(body: string | Buffer | Uint8Array): string {\n  if (typeof body === 'string') return body;\n  if (Buffer.isBuffer(body)) return body.toString('utf-8');\n  return Buffer.from(body).toString('utf-8');\n}\n\nfunction isPlainObject(v: unknown): v is Record<string, unknown> {\n  return typeof v === 'object' && v !== null && !Array.isArray(v);\n}\n"]}

package/dist/webhooks.d.cts

@@ -0,0 +1 @@
+export { D as DocumentFailedPayload, b as DocumentProcessedPayload, E as ExtractionReadyPayload, J as JobCompletedPayload, L as LoanClassifiedPayload, V as VerifyAndParseResult, c as VerifyOptions, W as WebhookEvent, d as WebhookEventType, e as WebhookSignatureError, a as verifyAndParseWebhook, v as verifyWebhookSignature } from './webhooks-D6PW9fcE.cjs';

package/dist/webhooks.d.ts

@@ -0,0 +1 @@
+export { D as DocumentFailedPayload, b as DocumentProcessedPayload, E as ExtractionReadyPayload, J as JobCompletedPayload, L as LoanClassifiedPayload, V as VerifyAndParseResult, c as VerifyOptions, W as WebhookEvent, d as WebhookEventType, e as WebhookSignatureError, a as verifyAndParseWebhook, v as verifyWebhookSignature } from './webhooks-D6PW9fcE.js';

package/dist/webhooks.js

@@ -0,0 +1,137 @@
+import { createHmac, timingSafeEqual } from 'crypto';
+
+// src/webhook-signature.ts
+var DEFAULT_FRESHNESS_TOLERANCE_SECONDS = 5 * 60;
+var VERSION_1_PREFIX = "v1";
+function verifyWebhookSignature(rawBody, signature, secret, options) {
+  if (typeof signature !== "string" || signature.length === 0) {
+    throw new WebhookSignatureError("SpreadSpace-Signature header is missing or empty.");
+  }
+  if (typeof secret !== "string" || secret.length === 0) {
+    throw new WebhookSignatureError("Webhook signing secret is missing or empty.");
+  }
+  if (rawBody === null || rawBody === void 0) {
+    throw new WebhookSignatureError("Webhook raw body is missing.");
+  }
+  const parsed = parseSignatureHeader(signature);
+  if (!parsed) {
+    throw new WebhookSignatureError("Webhook signature header is malformed.");
+  }
+  const { timestamp, hex } = parsed;
+  const bodyString = bodyToString(rawBody);
+  const expectedHex = computeHmacHex(secret, `${timestamp}.${bodyString}`);
+  if (!hexEquals(expectedHex, hex)) {
+    throw new WebhookSignatureError("Webhook signature does not match.");
+  }
+  const tolerance = options?.freshnessTolerance ?? DEFAULT_FRESHNESS_TOLERANCE_SECONDS;
+  const now = options?.currentTimestamp ?? Math.floor(Date.now() / 1e3);
+  const age = now - timestamp;
+  if (age > tolerance || age < -tolerance) {
+    throw new WebhookSignatureError(
+      `Webhook timestamp is outside the freshness window of ${tolerance}s.`
+    );
+  }
+  return true;
+}
+function verifyAndParseWebhook(rawBody, signature, secret, options) {
+  verifyWebhookSignature(rawBody, signature, secret, options);
+  const bodyString = bodyToString(rawBody);
+  let parsed;
+  try {
+    parsed = JSON.parse(bodyString);
+  } catch (cause) {
+    throw new WebhookSignatureError("Webhook body is not valid JSON.", cause);
+  }
+  if (!isPlainObject(parsed)) {
+    throw new WebhookSignatureError("Webhook body is not a JSON object.");
+  }
+  const candidate = parsed;
+  if (typeof candidate.type !== "string" || candidate.type.length === 0) {
+    throw new WebhookSignatureError("Webhook body is missing a `type` field.");
+  }
+  if (typeof candidate.id !== "string" || candidate.id.length === 0) {
+    throw new WebhookSignatureError("Webhook body is missing an `id` field.");
+  }
+  if (typeof candidate.created !== "number") {
+    throw new WebhookSignatureError("Webhook body is missing a numeric `created` field.");
+  }
+  if (typeof candidate.tenant_id !== "string" || candidate.tenant_id.length === 0) {
+    throw new WebhookSignatureError("Webhook body is missing a `tenant_id` field.");
+  }
+  if (!isPlainObject(candidate.data)) {
+    throw new WebhookSignatureError("Webhook body is missing a `data` object.");
+  }
+  return parsed;
+}
+var WebhookSignatureError = class _WebhookSignatureError extends Error {
+  cause;
+  constructor(message, cause) {
+    super(message);
+    this.name = "WebhookSignatureError";
+    this.cause = cause;
+    Object.setPrototypeOf(this, _WebhookSignatureError.prototype);
+  }
+};
+function parseSignatureHeader(header) {
+  const segments = header.split(",").filter((s) => s.length > 0);
+  if (segments.length < 2) return null;
+  let parsedTs = null;
+  let parsedV1 = null;
+  for (const raw of segments) {
+    const segment = raw.trim();
+    const eq = segment.indexOf("=");
+    if (eq <= 0 || eq === segment.length - 1) {
+      return null;
+    }
+    const key = segment.slice(0, eq).trim();
+    const value = segment.slice(eq + 1).trim();
+    if (key === "t") {
+      if (parsedTs !== null) return null;
+      if (!/^-?\d+$/.test(value)) return null;
+      const ts = Number(value);
+      if (!Number.isFinite(ts) || !Number.isInteger(ts)) return null;
+      parsedTs = ts;
+    } else if (key === VERSION_1_PREFIX) {
+      if (parsedV1 !== null) return null;
+      if (value.length === 0) return null;
+      parsedV1 = value;
+    }
+  }
+  if (parsedTs === null || parsedV1 === null) return null;
+  return { timestamp: parsedTs, hex: parsedV1 };
+}
+function computeHmacHex(secret, signedPayload) {
+  const hmac = createHmac("sha256", Buffer.from(secret, "utf-8"));
+  hmac.update(Buffer.from(signedPayload, "utf-8"));
+  return hmac.digest("hex");
+}
+function hexEquals(expectedHex, providedHex) {
+  if (expectedHex.length !== providedHex.length) return false;
+  let expectedBytes;
+  let providedBytes;
+  try {
+    expectedBytes = Buffer.from(expectedHex, "hex");
+    providedBytes = Buffer.from(providedHex, "hex");
+  } catch {
+    return false;
+  }
+  if (expectedBytes.length !== providedBytes.length) return false;
+  if (expectedBytes.length * 2 !== expectedHex.length) return false;
+  if (providedBytes.length * 2 !== providedHex.length) return false;
+  return timingSafeEqual(
+    new Uint8Array(expectedBytes.buffer, expectedBytes.byteOffset, expectedBytes.byteLength),
+    new Uint8Array(providedBytes.buffer, providedBytes.byteOffset, providedBytes.byteLength)
+  );
+}
+function bodyToString(body) {
+  if (typeof body === "string") return body;
+  if (Buffer.isBuffer(body)) return body.toString("utf-8");
+  return Buffer.from(body).toString("utf-8");
+}
+function isPlainObject(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+export { WebhookSignatureError, verifyAndParseWebhook, verifyWebhookSignature };
+//# sourceMappingURL=webhooks.js.map
+//# sourceMappingURL=webhooks.js.map

package/dist/webhooks.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/webhook-signature.ts"],"names":[],"mappings":"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","file":"webhooks.js","sourcesContent":["import { createHmac, timingSafeEqual } from 'node:crypto';\n\nimport type { VerifyAndParseResult, WebhookEvent } from './types.js';\n\n/**\n * Webhook signature verifier — byte-for-byte compatible with\n * `api/src/Webhooks/WebhookSigner.cs` on the API side.\n *\n * Wire format (mirrors Stripe's `Stripe-Signature`):\n *\n *   SpreadSpace-Signature: t=<unix_seconds>,v1=<hex_hmac_sha256(secret, \"{t}.{body}\")>\n *\n * The verifier:\n *   1. Parses `t=...` and `v1=...` tokens (tolerant of additional unrecognized\n *      pairs to stay forward-compatible with future schemes).\n *   2. Recomputes HMAC-SHA256 over `\"{timestamp}.{rawBody}\"` with the secret.\n *   3. Compares with `crypto.timingSafeEqual` on raw bytes (never on hex\n *      strings — string `===` short-circuits and leaks prefix info via timing).\n *   4. Two-sided freshness check: rejects timestamps too far in the past\n *      (replay protection) AND too far in the future (attacker-controlled\n *      timestamps that would extend the replay window).\n *\n * Verification order matches the C# side: HMAC first, then freshness. That\n * way a forged-but-fresh request and a real-but-stale request fail\n * indistinguishably from the timing perspective.\n */\n\n/** Default freshness tolerance — matches `WebhookSignatureFormat.DefaultFreshnessTolerance`. */\nconst DEFAULT_FRESHNESS_TOLERANCE_SECONDS = 5 * 60;\n\n/** Wire constant for the v1 HMAC-SHA256 scheme. */\nconst VERSION_1_PREFIX = 'v1';\n\nexport interface VerifyOptions {\n  /**\n   * Maximum age (and maximum future skew) of the timestamp before the\n   * signature is rejected as stale. Symmetric — `Math.abs(now - t)` must be\n   * ≤ this value.\n   *\n   * Default: 300 seconds (5 minutes).\n   */\n  freshnessTolerance?: number;\n\n  /**\n   * Override the \"current time\" used for the freshness check. Useful in\n   * tests; otherwise leave undefined and the verifier reads\n   * `Date.now() / 1000`.\n   */\n  currentTimestamp?: number;\n}\n\n/**\n * Verify a `SpreadSpace-Signature` header against a body and signing\n * secret. Throws on any failure (invalid format, bad HMAC, stale timestamp,\n * wrong secret); returns `true` on success.\n *\n * @param rawBody  The exact request body received on the wire — bytes, not\n *   re-serialized JSON. Any byte-level transformation between receipt and\n *   verification (re-stringification, gzip decode, encoding change) will\n *   invalidate the signature.\n * @param signature  Contents of the `SpreadSpace-Signature` HTTP header.\n * @param secret  The plaintext signing secret (`whsec_...`) issued at\n *   webhook endpoint creation. Never log this.\n * @param options  Optional overrides — freshness window and clock injection.\n */\nexport function verifyWebhookSignature(\n  rawBody: string | Buffer | Uint8Array,\n  signature: string,\n  secret: string,\n  options?: VerifyOptions,\n): true {\n  if (typeof signature !== 'string' || signature.length === 0) {\n    throw new WebhookSignatureError('SpreadSpace-Signature header is missing or empty.');\n  }\n  if (typeof secret !== 'string' || secret.length === 0) {\n    throw new WebhookSignatureError('Webhook signing secret is missing or empty.');\n  }\n  if (rawBody === null || rawBody === undefined) {\n    throw new WebhookSignatureError('Webhook raw body is missing.');\n  }\n\n  const parsed = parseSignatureHeader(signature);\n  if (!parsed) {\n    throw new WebhookSignatureError('Webhook signature header is malformed.');\n  }\n  const { timestamp, hex } = parsed;\n\n  // HMAC FIRST. We never want to leak (via differential timing or distinct\n  // error message text) whether a request was a forged signature vs. a real\n  // one that aged out — both should be indistinguishable failures.\n  const bodyString = bodyToString(rawBody);\n  const expectedHex = computeHmacHex(secret, `${timestamp}.${bodyString}`);\n\n  if (!hexEquals(expectedHex, hex)) {\n    throw new WebhookSignatureError('Webhook signature does not match.');\n  }\n\n  // Then freshness. Two-sided check: too old OR too far in the future.\n  const tolerance = options?.freshnessTolerance ?? DEFAULT_FRESHNESS_TOLERANCE_SECONDS;\n  const now = options?.currentTimestamp ?? Math.floor(Date.now() / 1000);\n  const age = now - timestamp;\n  if (age > tolerance || age < -tolerance) {\n    throw new WebhookSignatureError(\n      `Webhook timestamp is outside the freshness window of ${tolerance}s.`,\n    );\n  }\n\n  return true;\n}\n\n/**\n * Verify a webhook signature and JSON-parse the body into a typed\n * `WebhookEvent` envelope. Throws on signature failure or invalid JSON.\n *\n * The returned value is a discriminated union over `type` — switch on\n * `event.type` to narrow `event.data` to the matching payload.\n */\nexport function verifyAndParseWebhook(\n  rawBody: string | Buffer | Uint8Array,\n  signature: string,\n  secret: string,\n  options?: VerifyOptions,\n): VerifyAndParseResult {\n  verifyWebhookSignature(rawBody, signature, secret, options);\n\n  const bodyString = bodyToString(rawBody);\n\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(bodyString);\n  } catch (cause) {\n    throw new WebhookSignatureError('Webhook body is not valid JSON.', cause);\n  }\n\n  if (!isPlainObject(parsed)) {\n    throw new WebhookSignatureError('Webhook body is not a JSON object.');\n  }\n  const candidate = parsed as Partial<WebhookEvent>;\n  if (typeof candidate.type !== 'string' || candidate.type.length === 0) {\n    throw new WebhookSignatureError('Webhook body is missing a `type` field.');\n  }\n  if (typeof candidate.id !== 'string' || candidate.id.length === 0) {\n    throw new WebhookSignatureError('Webhook body is missing an `id` field.');\n  }\n  if (typeof candidate.created !== 'number') {\n    throw new WebhookSignatureError('Webhook body is missing a numeric `created` field.');\n  }\n  if (typeof candidate.tenant_id !== 'string' || candidate.tenant_id.length === 0) {\n    throw new WebhookSignatureError('Webhook body is missing a `tenant_id` field.');\n  }\n  if (!isPlainObject(candidate.data)) {\n    throw new WebhookSignatureError('Webhook body is missing a `data` object.');\n  }\n\n  return parsed as VerifyAndParseResult;\n}\n\n/**\n * Thrown when a webhook signature fails verification or the envelope is\n * structurally malformed. Distinct from `SpreadSpaceError` because webhook\n * verification is a self-contained primitive — verifiers don't need the\n * full request/response error machinery, just a single failure type they\n * can reject against.\n */\nexport class WebhookSignatureError extends Error {\n  public readonly cause?: unknown;\n\n  constructor(message: string, cause?: unknown) {\n    super(message);\n    this.name = 'WebhookSignatureError';\n    this.cause = cause;\n    Object.setPrototypeOf(this, WebhookSignatureError.prototype);\n  }\n}\n\n// ────────────────────────────────────────────────────────────────────────────\n// Internals\n// ────────────────────────────────────────────────────────────────────────────\n\ninterface ParsedSignature {\n  timestamp: number;\n  hex: string;\n}\n\n/**\n * Parse a header in the form `t=<long>,v1=<hex>`. Tolerant of whitespace\n * between segments and of additional unrecognized pairs (e.g. a future\n * `v2=...`) — those are silently ignored, not treated as parse errors, so\n * this verifier remains forward-compatible with new schemes.\n */\nfunction parseSignatureHeader(header: string): ParsedSignature | null {\n  const segments = header.split(',').filter((s) => s.length > 0);\n  if (segments.length < 2) return null;\n\n  let parsedTs: number | null = null;\n  let parsedV1: string | null = null;\n\n  for (const raw of segments) {\n    const segment = raw.trim();\n    const eq = segment.indexOf('=');\n    if (eq <= 0 || eq === segment.length - 1) {\n      // Missing key, missing value, or `=` at the very end (`v1=`).\n      return null;\n    }\n\n    const key = segment.slice(0, eq).trim();\n    const value = segment.slice(eq + 1).trim();\n\n    if (key === 't') {\n      if (parsedTs !== null) return null; // Duplicate `t=`.\n      // Strict integer parse — reject `1.5`, `1e3`, leading `+`, etc. The C#\n      // verifier uses `long.TryParse(NumberStyles.Integer, Invariant)`,\n      // which accepts an optional leading `-` and digits only. We mirror that.\n      if (!/^-?\\d+$/.test(value)) return null;\n      const ts = Number(value);\n      if (!Number.isFinite(ts) || !Number.isInteger(ts)) return null;\n      parsedTs = ts;\n    } else if (key === VERSION_1_PREFIX) {\n      if (parsedV1 !== null) return null; // Duplicate `v1=`.\n      if (value.length === 0) return null;\n      parsedV1 = value;\n    }\n    // Any other key — silently ignored for forward compatibility.\n  }\n\n  if (parsedTs === null || parsedV1 === null) return null;\n  return { timestamp: parsedTs, hex: parsedV1 };\n}\n\n/**\n * Compute lowercase hex HMAC-SHA256 digest. Matches the C# side's\n * `Convert.ToHexStringLower(hmac.ComputeHash(...))` exactly.\n */\nfunction computeHmacHex(secret: string, signedPayload: string): string {\n  const hmac = createHmac('sha256', Buffer.from(secret, 'utf-8'));\n  hmac.update(Buffer.from(signedPayload, 'utf-8'));\n  return hmac.digest('hex'); // Node default is lowercase.\n}\n\n/**\n * Constant-time compare of two hex strings. We decode both sides to bytes\n * before calling `timingSafeEqual` — it requires equal-length inputs and\n * we want a length mismatch to fail fast (length is not timing-sensitive\n * since both ends know SHA-256 emits 64 hex chars).\n */\nfunction hexEquals(expectedHex: string, providedHex: string): boolean {\n  if (expectedHex.length !== providedHex.length) return false;\n\n  let expectedBytes: Buffer;\n  let providedBytes: Buffer;\n  try {\n    expectedBytes = Buffer.from(expectedHex, 'hex');\n    providedBytes = Buffer.from(providedHex, 'hex');\n  } catch {\n    return false;\n  }\n\n  // `Buffer.from(..., 'hex')` silently stops at the first non-hex character,\n  // producing a shorter buffer — guard explicitly against that to avoid a\n  // false equality when the provided hex has invalid characters that happen\n  // to truncate to an empty buffer the receiver also produced.\n  if (expectedBytes.length !== providedBytes.length) return false;\n  if (expectedBytes.length * 2 !== expectedHex.length) return false;\n  if (providedBytes.length * 2 !== providedHex.length) return false;\n\n  return timingSafeEqual(\n    new Uint8Array(expectedBytes.buffer, expectedBytes.byteOffset, expectedBytes.byteLength),\n    new Uint8Array(providedBytes.buffer, providedBytes.byteOffset, providedBytes.byteLength),\n  );\n}\n\nfunction bodyToString(body: string | Buffer | Uint8Array): string {\n  if (typeof body === 'string') return body;\n  if (Buffer.isBuffer(body)) return body.toString('utf-8');\n  return Buffer.from(body).toString('utf-8');\n}\n\nfunction isPlainObject(v: unknown): v is Record<string, unknown> {\n  return typeof v === 'object' && v !== null && !Array.isArray(v);\n}\n"]}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@spreadspace/embed",
+  "version": "0.1.0",
+  "description": "Server-side Node.js SDK for SpreadSpace embeds — mint embed sessions and verify webhooks.",
+  "license": "MIT",
+  "sideEffects": false,
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./webhooks": {
+      "types": "./dist/webhooks.d.ts",
+      "import": "./dist/webhooks.js",
+      "require": "./dist/webhooks.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^25.8.0",
+    "@typescript-eslint/eslint-plugin": "^8.59.3",
+    "@typescript-eslint/parser": "^8.59.3",
+    "eslint": "^10.4.0",
+    "openapi-typescript": "^7.4.4",
+    "rimraf": "^6.0.1",
+    "tsup": "^8.3.5",
+    "typescript": "^6.0.3",
+    "vitest": "^3.2.6"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "spreadspace",
+    "api",
+    "sdk",
+    "typescript",
+    "lending",
+    "documents"
+  ],
+  "scripts": {
+    "codegen": "bash ../../fern/build-public-spec.sh && openapi-typescript ../../fern/api-public.json -o src/generated/api-types.ts && pnpm run check:no-internal-paths",
+    "check:no-internal-paths": "node scripts/check-no-internal-paths.mjs",
+    "clean": "rimraf dist",
+    "build": "pnpm run clean && tsup && node scripts/check-no-internal-paths.mjs --dist",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint \"src/**/*.ts\" \"test/**/*.ts\"",
+    "typecheck": "tsc --noEmit"
+  }
+}