@farthershore/backend 0.20.0 → 0.21.0

package/dist/webhooks/index.js

@@ -0,0 +1,498 @@
+import { createRequire as __createRequire } from "node:module";const require=__createRequire(import.meta.url);
+
+// ../contracts/dist/webhooks/standard-webhooks.js
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+var WEBHOOK_ID_HEADER = "webhook-id";
+var WEBHOOK_TIMESTAMP_HEADER = "webhook-timestamp";
+var WEBHOOK_SIGNATURE_HEADER = "webhook-signature";
+var WEBHOOK_SIGNATURE_VERSION = "v1";
+var WEBHOOK_TIMESTAMP_TOLERANCE_SECONDS = 300;
+var WEBHOOK_SECRET_PREFIX = "fswh_";
+function webhookSecretKeyBytes(secret) {
+  const key = secret.startsWith(WEBHOOK_SECRET_PREFIX) ? Buffer.from(secret.slice(WEBHOOK_SECRET_PREFIX.length), "base64") : secret.startsWith("whsec_") ? Buffer.from(secret.slice("whsec_".length), "base64") : Buffer.from(secret, "utf8");
+  if (key.length === 0) {
+    throw new Error("webhook secret resolves to an empty signing key \u2014 the configured secret must be a non-empty fswh_ value");
+  }
+  return key;
+}
+function webhookSignedContent(id, timestamp, body) {
+  return `${id}.${timestamp}.${body}`;
+}
+function readHeader(headers, name) {
+  if (typeof headers.get === "function") {
+    return headers.get(name) ?? void 0;
+  }
+  const record = headers;
+  const direct = record[name] ?? record[name.toLowerCase()];
+  if (direct !== void 0)
+    return Array.isArray(direct) ? direct[0] : direct;
+  const lower = name.toLowerCase();
+  for (const key of Object.keys(record)) {
+    if (key.toLowerCase() === lower) {
+      const value = record[key];
+      return Array.isArray(value) ? value[0] : value;
+    }
+  }
+  return void 0;
+}
+function parseWebhookSignatureHeader(header) {
+  const macs = [];
+  for (const entry of header.split(" ")) {
+    if (entry.length === 0)
+      continue;
+    const comma = entry.indexOf(",");
+    if (comma <= 0)
+      continue;
+    if (entry.slice(0, comma) !== WEBHOOK_SIGNATURE_VERSION)
+      continue;
+    macs.push(entry.slice(comma + 1));
+  }
+  return macs;
+}
+function verifyWebhook(input) {
+  const id = readHeader(input.headers, WEBHOOK_ID_HEADER);
+  const timestampRaw = readHeader(input.headers, WEBHOOK_TIMESTAMP_HEADER);
+  const signatureRaw = readHeader(input.headers, WEBHOOK_SIGNATURE_HEADER);
+  if (!id || !timestampRaw || !signatureRaw) {
+    return { ok: false, reason: "missing_headers" };
+  }
+  if (!/^\d{1,12}$/.test(timestampRaw)) {
+    return { ok: false, reason: "invalid_timestamp" };
+  }
+  const timestamp = Number(timestampRaw);
+  const nowSeconds = Math.floor((input.now ?? Date.now)() / 1e3);
+  const tolerance = input.toleranceSeconds ?? WEBHOOK_TIMESTAMP_TOLERANCE_SECONDS;
+  if (Math.abs(nowSeconds - timestamp) > tolerance) {
+    return { ok: false, reason: "timestamp_out_of_tolerance" };
+  }
+  const body = typeof input.body === "string" ? input.body : Buffer.from(input.body).toString("utf8");
+  const presented = parseWebhookSignatureHeader(signatureRaw).map((mac) => Buffer.from(mac, "base64"));
+  for (const secret of input.secrets) {
+    let keyBytes;
+    try {
+      keyBytes = webhookSecretKeyBytes(secret);
+    } catch {
+      continue;
+    }
+    const expected = Buffer.from(createHmac("sha256", keyBytes).update(webhookSignedContent(id, timestamp, body)).digest("base64"), "base64");
+    for (const candidate of presented) {
+      if (candidate.length === expected.length && timingSafeEqual(candidate, expected)) {
+        return { ok: true, id, timestamp };
+      }
+    }
+  }
+  return { ok: false, reason: "no_matching_signature" };
+}
+
+// src/webhooks/types.ts
+var WEBHOOK_EVENT_NAMES = [
+  "subscription.created",
+  "subscription.updated",
+  "subscription.canceled",
+  "payment.succeeded",
+  "payment.failed",
+  "entitlement.changed",
+  "usage.threshold_reached"
+];
+var WEBHOOK_TEST_EVENT = "webhook.test";
+var WEBHOOK_ID_HEADER2 = "webhook-id";
+var WEBHOOK_TIMESTAMP_HEADER2 = "webhook-timestamp";
+var WEBHOOK_SIGNATURE_HEADER2 = "webhook-signature";
+var WEBHOOK_EVENT_HEADER = "x-fs-webhook-event";
+var WEBHOOK_TIMESTAMP_TOLERANCE_SECONDS2 = 300;
+var WEBHOOK_SECRET_PREFIX2 = "fswh_";
+
+// src/webhooks/index.ts
+function verifyWebhook2(input) {
+  return verifyWebhook(input);
+}
+var ENVELOPE_TYPES = /* @__PURE__ */ new Set([
+  ...WEBHOOK_EVENT_NAMES,
+  WEBHOOK_TEST_EVENT
+]);
+function isWebhookEnvelopeType(value) {
+  return typeof value === "string" && ENVELOPE_TYPES.has(value);
+}
+var WEBHOOK_DEDUPE_MAX_ENTRIES = 25e4;
+var WEBHOOK_INFLIGHT_LEASE_MS = 5 * 60 * 1e3;
+var MemoryWebhookNonceStore = class {
+  constructor(options = {}) {
+    this.options = options;
+  }
+  options;
+  seen = /* @__PURE__ */ new Map();
+  tokenSeq = 0;
+  horizonFor(state) {
+    return state === "processed" ? this.options.ttlMs ?? WEBHOOK_DEDUPE_TTL_MS : this.options.leaseMs ?? WEBHOOK_INFLIGHT_LEASE_MS;
+  }
+  claim(id) {
+    const now = (this.options.now ?? Date.now)();
+    const max = this.options.maxEntries ?? WEBHOOK_DEDUPE_MAX_ENTRIES;
+    const existing = this.seen.get(id);
+    if (existing && now - existing.at < this.horizonFor(existing.state)) {
+      return { outcome: existing.state };
+    }
+    if (existing) this.seen.delete(id);
+    for (const [key, entry] of this.seen) {
+      if (now - entry.at >= this.horizonFor(entry.state)) this.seen.delete(key);
+      else break;
+    }
+    if (this.seen.size >= max) {
+      for (const [key, entry] of this.seen) {
+        if (now - entry.at >= this.horizonFor(entry.state))
+          this.seen.delete(key);
+      }
+      if (this.seen.size >= max) return { outcome: "saturated" };
+    }
+    const token = String(++this.tokenSeq);
+    this.seen.set(id, { state: "in_flight", at: now, token });
+    return { outcome: "fresh", token };
+  }
+  settle(id, token, outcome) {
+    const entry = this.seen.get(id);
+    if (!entry || entry.token !== token) return;
+    if (outcome === "release") {
+      this.seen.delete(id);
+      return;
+    }
+    this.seen.set(id, {
+      state: "processed",
+      at: (this.options.now ?? Date.now)(),
+      token
+    });
+  }
+  get size() {
+    return this.seen.size;
+  }
+};
+var WEBHOOK_DEDUPE_TTL_MS = 60 * 60 * 1e3;
+var WEBHOOK_MAX_BODY_BYTES = 1024 * 1024;
+function statusBodyFor(outcome) {
+  switch (outcome.kind) {
+    case "rejected":
+      return { error: outcome.rejection.reason };
+    case "handler_error":
+      return { error: "handler_error", id: outcome.id };
+    case "store_unavailable":
+      return { error: "store_unavailable", id: outcome.id };
+    case "in_flight":
+      return { error: "in_flight", id: outcome.id };
+    default:
+      return { ok: true, kind: outcome.kind, id: outcome.id };
+  }
+}
+async function readBoundedRequestBody(request, limit) {
+  const declared = request.headers.get("content-length");
+  if (declared !== null && /^\d+$/.test(declared) && Number(declared) > limit) {
+    return null;
+  }
+  if (!request.body) return new Uint8Array(0);
+  const reader = request.body.getReader();
+  const chunks = [];
+  let total = 0;
+  try {
+    for (; ; ) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      if (!value) continue;
+      total += value.byteLength;
+      if (total > limit) {
+        await reader.cancel().catch(() => void 0);
+        return null;
+      }
+      chunks.push(value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    out.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return out;
+}
+function readRawBody(req) {
+  const raw = req.rawBody;
+  if (raw !== void 0) return raw;
+  if (typeof req.body === "string") return req.body;
+  if (req.body instanceof Uint8Array) return req.body;
+  return null;
+}
+function createWebhookHandler(options) {
+  const secrets = [
+    ...options.secret ? [options.secret] : [],
+    ...options.secrets ?? []
+  ];
+  if (secrets.length === 0) {
+    throw new Error(
+      "createWebhookHandler: pass `secret` (or `secrets`) \u2014 the endpoint's fswh_ signing secret"
+    );
+  }
+  for (const secret of secrets) {
+    try {
+      webhookSecretKeyBytes(secret);
+    } catch {
+      throw new Error(
+        "createWebhookHandler: a configured signing secret is empty or malformed \u2014 expected a non-empty fswh_ secret"
+      );
+    }
+  }
+  const now = options.now ?? (() => Date.now());
+  const store = options.nonceStore ?? new MemoryWebhookNonceStore({ ttlMs: WEBHOOK_DEDUPE_TTL_MS, now });
+  const maxBodyBytes = options.maxBodyBytes ?? WEBHOOK_MAX_BODY_BYTES;
+  const runObserver = (fn, arg) => {
+    if (!fn) return;
+    try {
+      const result = fn(arg);
+      if (result != null && typeof result.then === "function") {
+        void result.catch(() => {
+        });
+      }
+    } catch {
+    }
+  };
+  const notifyRejected = (rejection) => runObserver(options.onRejected, rejection);
+  async function handle(input) {
+    const size = typeof input.body === "string" ? Buffer.byteLength(input.body, "utf8") : input.body.byteLength;
+    if (size > maxBodyBytes) {
+      const rejection = {
+        reason: "payload_too_large",
+        limitBytes: maxBodyBytes
+      };
+      notifyRejected(rejection);
+      return { status: 413, kind: "rejected", rejection };
+    }
+    const verified = verifyWebhook({
+      body: input.body,
+      headers: input.headers,
+      secrets,
+      now
+    });
+    if (!verified.ok) {
+      const rejection = { reason: verified.reason };
+      notifyRejected(rejection);
+      return {
+        status: verified.reason === "missing_headers" ? 400 : 401,
+        kind: "rejected",
+        rejection
+      };
+    }
+    const text = typeof input.body === "string" ? input.body : new TextDecoder().decode(input.body);
+    let parsed;
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      const rejection = { reason: "invalid_json" };
+      notifyRejected(rejection);
+      return { status: 400, kind: "rejected", rejection };
+    }
+    const envelope = parsed;
+    if (!envelope || typeof envelope !== "object" || typeof envelope.id !== "string" || typeof envelope.type !== "string") {
+      const rejection = {
+        reason: "invalid_envelope",
+        detail: "body must be an object with string `id` and `type`"
+      };
+      notifyRejected(rejection);
+      return { status: 400, kind: "rejected", rejection };
+    }
+    if (envelope.id !== verified.id) {
+      const rejection = {
+        reason: "invalid_envelope",
+        detail: "body `id` does not match the signed webhook-id header"
+      };
+      notifyRejected(rejection);
+      return { status: 400, kind: "rejected", rejection };
+    }
+    const type = envelope.type;
+    const id = envelope.id;
+    if (isWebhookEnvelopeType(type)) {
+      const problem = envelopeShapeProblem(envelope);
+      if (problem) {
+        const rejection = {
+          reason: "invalid_envelope",
+          detail: problem
+        };
+        notifyRejected(rejection);
+        return { status: 400, kind: "rejected", rejection };
+      }
+    }
+    let claim;
+    try {
+      claim = await store.claim(id);
+    } catch {
+      return { status: 503, kind: "store_unavailable", id, type };
+    }
+    if (claim.outcome === "processed") {
+      runObserver(options.onDuplicate, { id, type });
+      return { status: 200, kind: "duplicate", id, type };
+    }
+    if (claim.outcome === "in_flight") {
+      return { status: 503, kind: "in_flight", id, type };
+    }
+    const token = claim.outcome === "fresh" && typeof claim.token === "string" ? claim.token : void 0;
+    const settle = async (outcome) => {
+      if (token === void 0) return;
+      try {
+        await store.settle(id, token, outcome);
+      } catch {
+      }
+    };
+    if (!isWebhookEnvelopeType(type)) {
+      try {
+        await options.onUnknown?.({ id, type, body: parsed });
+      } catch {
+      }
+      await settle("processed");
+      return { status: 200, kind: "unknown_type", id, type };
+    }
+    const handler = options.on[type];
+    if (!handler) {
+      await settle("processed");
+      return { status: 200, kind: "ignored", id, type };
+    }
+    try {
+      await handler(envelope);
+    } catch (error) {
+      await settle("release");
+      return { status: 500, kind: "handler_error", id, type, error };
+    }
+    await settle("processed");
+    return { status: 200, kind: "handled", id, type };
+  }
+  return {
+    handle,
+    async fetch(request) {
+      const body = await readBoundedRequestBody(request, maxBodyBytes);
+      if (body === null) {
+        const rejection = {
+          reason: "payload_too_large",
+          limitBytes: maxBodyBytes
+        };
+        notifyRejected(rejection);
+        return new Response(JSON.stringify({ error: rejection.reason }), {
+          status: 413,
+          headers: { "content-type": "application/json" }
+        });
+      }
+      const outcome = await handle({ body, headers: request.headers });
+      return new Response(JSON.stringify(statusBodyFor(outcome)), {
+        status: outcome.status,
+        headers: { "content-type": "application/json" }
+      });
+    },
+    express() {
+      return async (req, res) => {
+        const body = readRawBody(req);
+        if (body === null) {
+          const rejection = {
+            reason: "invalid_envelope",
+            detail: "raw body unavailable \u2014 mount express.raw({ type: '*/*' }) before this handler or set req.rawBody"
+          };
+          notifyRejected(rejection);
+          res.status(400).json({ error: rejection.reason, detail: rejection.detail });
+          return;
+        }
+        const outcome = await handle({ body, headers: req.headers });
+        res.status(outcome.status).json(statusBodyFor(outcome));
+      };
+    }
+  };
+}
+function envelopeShapeProblem(envelope) {
+  if (typeof envelope.createdAt !== "string" || envelope.createdAt.length === 0) {
+    return "`createdAt` must be an ISO-8601 string";
+  }
+  if (Number.isNaN(Date.parse(envelope.createdAt))) {
+    return "`createdAt` is not a parseable timestamp";
+  }
+  if (typeof envelope.businessId !== "string" || envelope.businessId.length === 0) {
+    return "`businessId` must be a non-empty string";
+  }
+  if (envelope.environmentId !== null && typeof envelope.environmentId !== "string") {
+    return "`environmentId` must be a string or null";
+  }
+  if (typeof envelope.data !== "object" || envelope.data === null || Array.isArray(envelope.data)) {
+    return "`data` must be an object";
+  }
+  const data = envelope.data;
+  if (envelope.type === WEBHOOK_TEST_EVENT) {
+    if (typeof data.businessId !== "string" || typeof data.sentAt !== "string") {
+      return "`webhook.test` data must carry `businessId` and `sentAt`";
+    }
+    return null;
+  }
+  const expected = DATA_FIELD_TYPES[envelope.type];
+  for (const [key, kind] of Object.entries(expected)) {
+    const value = data[key];
+    if (value === void 0) continue;
+    const ok = kind === "string" ? typeof value === "string" : kind === "number" ? typeof value === "number" && Number.isFinite(value) : kind === "string|null" ? value === null || typeof value === "string" : value === null || typeof value === "number" && Number.isFinite(value);
+    if (!ok) return `\`data.${key}\` must be ${kind}`;
+  }
+  return null;
+}
+var DATA_FIELD_TYPES = {
+  "subscription.created": {
+    subscriptionId: "string",
+    compiledPlanId: "string"
+  },
+  "subscription.updated": {
+    subscriptionId: "string",
+    reason: "string",
+    lifecycle: "string",
+    compiledPlanId: "string"
+  },
+  "subscription.canceled": {
+    subscriptionId: "string",
+    reason: "string",
+    lifecycle: "string"
+  },
+  "payment.succeeded": {
+    subscriptionId: "string",
+    invoiceId: "string",
+    amount: "number|null",
+    currency: "string|null",
+    reason: "string"
+  },
+  "payment.failed": {
+    subscriptionId: "string",
+    invoiceId: "string",
+    amount: "number|null",
+    currency: "string|null",
+    reason: "string"
+  },
+  "entitlement.changed": {
+    compiledPlanId: "string",
+    lineageId: "string",
+    status: "string"
+  },
+  "usage.threshold_reached": {
+    subscriptionId: "string",
+    subscriberId: "string",
+    limitId: "string",
+    threshold: "number",
+    windowStartMs: "number",
+    windowEndMs: "number"
+  }
+};
+export {
+  DATA_FIELD_TYPES,
+  MemoryWebhookNonceStore,
+  WEBHOOK_DEDUPE_MAX_ENTRIES,
+  WEBHOOK_DEDUPE_TTL_MS,
+  WEBHOOK_EVENT_HEADER,
+  WEBHOOK_EVENT_NAMES,
+  WEBHOOK_ID_HEADER2 as WEBHOOK_ID_HEADER,
+  WEBHOOK_INFLIGHT_LEASE_MS,
+  WEBHOOK_MAX_BODY_BYTES,
+  WEBHOOK_SECRET_PREFIX2 as WEBHOOK_SECRET_PREFIX,
+  WEBHOOK_SIGNATURE_HEADER2 as WEBHOOK_SIGNATURE_HEADER,
+  WEBHOOK_TEST_EVENT,
+  WEBHOOK_TIMESTAMP_HEADER2 as WEBHOOK_TIMESTAMP_HEADER,
+  WEBHOOK_TIMESTAMP_TOLERANCE_SECONDS2 as WEBHOOK_TIMESTAMP_TOLERANCE_SECONDS,
+  createWebhookHandler,
+  isWebhookEnvelopeType,
+  readBoundedRequestBody,
+  verifyWebhook2 as verifyWebhook
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@farthershore/backend",
-  "version": "0.20.0",
-  "description": "Farther Shore backend SDK for builder upstreams: signed response usage, fail-closed gateway request verification, health, and lifecycle from FS_RUNTIME_TOKEN",
+  "version": "0.21.0",
+  "description": "Farther Shore backend SDK for builder upstreams: signed response usage, fail-closed gateway request verification, first-class webhook consumption, health, and lifecycle from FS_RUNTIME_TOKEN",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -26,6 +26,14 @@
     "./testing": {
       "types": "./dist/types/testing/index.d.ts",
       "import": "./dist/testing/index.js"
+    },
+    "./webhooks": {
+      "types": "./dist/types/webhooks/index.d.ts",
+      "import": "./dist/webhooks/index.js"
+    },
+    "./internal": {
+      "types": "./dist/types/internal/index.d.ts",
+      "import": "./dist/internal/index.js"
     }
   },
   "files": [
@@ -37,8 +45,8 @@
     "access": "public"
   },
   "optionalDependencies": {
-    "@farthershore/cloudflared-darwin-arm64": "0.0.0",
     "@farthershore/cloudflared-darwin-x64": "0.0.0",
+    "@farthershore/cloudflared-darwin-arm64": "0.0.0",
     "@farthershore/cloudflared-linux-arm64": "0.0.0",
     "@farthershore/cloudflared-linux-x64": "0.0.0"
   },
@@ -55,6 +63,7 @@
     "esbuild": "^0.28.1",
     "eslint": "^9.39.5",
     "eslint-plugin-sonarjs": "^4.2.0",
+    "standardwebhooks": "1.0.0",
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.66.0",
     "vitest": "^4.1.10",

package/dist/types/core/metering.d.ts

@@ -1,68 +0,0 @@
-import type { RuntimeMeteringConfig } from "../runtime-types.js";
-export type MeterOptions = {
-    requestId?: string;
-    routeId?: string;
-    /** Subscription to attribute the usage to (billing identity). Pass the
-     *  verified request context's `signedContext.subscriptionId` when metering
-     *  inside a request handler. Without it (and without `requestId`, which core
-     *  can resolve back to the served gateway request), core persists the event
-     *  UNBILLED and flags it unattributable. */
-    subscriptionId?: string;
-    /** Override event_id (idempotency key). Defaults to a random uuid. */
-    eventId?: string;
-    /** Override the timestamp (ISO-8601). Defaults to now. */
-    timestamp?: string;
-};
-export type MeteringClientOptions = {
-    config: RuntimeMeteringConfig;
-    businessId: string;
-    backendId: string;
-    /** Core base URL when the config endpoint is a relative path. */
-    coreUrl?: string;
-    fetchImpl?: typeof fetch;
-    /** Max retry attempts per flush before re-buffering. */
-    maxRetries?: number;
-    /** Base for the exponential inter-attempt backoff (ms). Default 200. */
-    baseDelayMs?: number;
-    /** Ceiling on any single inter-attempt wait (ms) — caps both backoff and a
-     *  `Retry-After` hint. Default 10000. */
-    maxDelayMs?: number;
-    /** Injectable delay primitive (tests pass a no-op; default is a timer). */
-    sleep?: (ms: number) => Promise<void>;
-    /** Injectable uniform random in [0,1) for the backoff jitter (tests pin it). */
-    random?: () => number;
-    /** Injectable id generator (tests). */
-    newId?: () => string;
-    now?: () => Date;
-};
-/**
- * Buffers + flushes metering events. `meter()` validates and enqueues; `flush()`
- * drains the buffer (re-buffering on failure for at-least-once delivery).
- */
-export declare class MeteringClient {
-    private readonly config;
-    private readonly endpoint;
-    private readonly businessId;
-    private readonly backendId;
-    private readonly fetchImpl;
-    private readonly maxRetries;
-    private readonly baseDelayMs;
-    private readonly maxDelayMs;
-    private readonly sleep;
-    private readonly random;
-    private readonly newId;
-    private readonly now;
-    private readonly buffer;
-    constructor(options: MeteringClientOptions);
-    /**
-     * Record `qty` of `meter`. Enforces meter-key shape, non-negative finite qty,
-     * the bootstrap allowedMeters/allowedRoutes scope, and the per-event sanity
-     * max, then enqueues and flushes (best-effort; failures stay buffered).
-     */
-    meter(meter: string, qty: number, options?: MeterOptions): Promise<void>;
-    /** Drain the buffer. Events that fail all retries stay buffered (at-least-once). */
-    flush(): Promise<void>;
-    /** Buffered-but-unsent count (observability/tests). */
-    get pending(): number;
-    private sendWithRetry;
-}