@saacms/stripe-bridge 0.1.0

package/README.md

@@ -0,0 +1,43 @@
+# @saacms/stripe-bridge
+
+The reusable Stripe-webhook → saacms-Collection seam. Productionises the
+commerce-bridge spike's GO verdict (`docs/spikes/commerce-bridge.md`) as a
+host-mountable handler.
+
+- **Zero runtime deps** beyond `@saacms/core`. No `stripe` SDK, no network.
+  Signature verification is Web Crypto HMAC-SHA256 only.
+- **Idempotency is ADR-0030 declarative `unique`** — the target collection
+  declares `unique: [["stripeEventId"]]`; a redelivered Stripe `event.id`
+  yields a runtime `409`, which this handler maps to a `200` ack (no
+  duplicate row, no second `afterChange`). The spike's host-side
+  filter-precheck workaround is **superseded** and not reproduced here.
+- **Pure** — the saacms runtime is injected as `opts.fetch` (the host passes
+  `app.fetch`) and the clock as `opts.now`, so the handler is fully
+  in-process testable.
+
+```ts
+import { createStripeWebhookHandler } from "@saacms/stripe-bridge"
+
+const handler = createStripeWebhookHandler({
+  fetch: app.fetch, // the saacms runtime
+  collectionSlug: "orders",
+  signingSecret: process.env.STRIPE_WEBHOOK_SECRET!,
+  mapEvent: (event) =>
+    event.type === "payment_intent.succeeded"
+      ? { collection: "orders", body: buildOrder(event) }
+      : null, // ignored event types → 200 ack, no write
+})
+
+// Mount at POST /api/stripe/webhook in any host (CF Worker, Next, Astro…).
+```
+
+## HTTP status contract (the load-bearing idempotency invariant)
+
+| Situation | Handler status |
+|---|---|
+| Signature missing/malformed/stale/mismatched | `400` (no write; Stripe must not retry) |
+| Validly signed but body not JSON / no string `id`+`type` | `400` (no write) |
+| `mapEvent` → `null` (unhandled event type) | `200` ack (no write) |
+| Runtime create `2xx` | `200` (created) |
+| Runtime create `409` (ADR-0030 redelivery) | `200` ack (duplicate — idempotent success) |
+| Any other runtime status (5xx / validation / …) | a `5xx` (transient → Stripe retries) |

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @saacms/stripe-bridge — the reusable Stripe-webhook → saacms-Collection seam.
+ *
+ * Productionises the commerce-bridge spike's GO verdict
+ * (`docs/spikes/commerce-bridge.md`) as a host-mountable handler. Idempotency
+ * is the ADR-0030 declarative-`unique` primitive (a redelivered Stripe
+ * `event.id` → runtime `409` → handler `200` ack), NOT the spike's superseded
+ * host-side filter pre-check.
+ *
+ * Zero runtime dependencies beyond `@saacms/core`: no `stripe` SDK, no network.
+ * Signature verification is Web Crypto HMAC-SHA256 only. The saacms runtime is
+ * injected (`opts.fetch` = `app.fetch`), so the whole handler is pure and
+ * fully in-process testable.
+ */
+export { createStripeWebhookHandler } from "./webhook-handler.ts";
+export type { StripeEventLike, MappedCreate, StripeWebhookOptions, WebhookOutcome, } from "./webhook-handler.ts";
+export { hmacSha256Hex, timingSafeEqualHex, signStripePayload, verifyStripeSignature, } from "./signature.ts";
+export type { SigFailure, SigResult } from "./signature.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,0BAA0B,EAAE,MAAM,sBAAsB,CAAA;AACjE,YAAY,EACV,eAAe,EACf,YAAY,EACZ,oBAAoB,EACpB,cAAc,GACf,MAAM,sBAAsB,CAAA;AAE7B,OAAO,EACL,aAAa,EACb,kBAAkB,EAClB,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,gBAAgB,CAAA;AACvB,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA"}

package/dist/index.js

@@ -0,0 +1,112 @@
+// src/signature.ts
+async function hmacSha256Hex(secret, message) {
+  const key = await crypto.subtle.importKey("raw", new TextEncoder().encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+  const sig = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(message));
+  return [...new Uint8Array(sig)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+function timingSafeEqualHex(a, b) {
+  if (a.length !== b.length)
+    return false;
+  let diff = 0;
+  for (let i = 0;i < a.length; i++) {
+    diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  }
+  return diff === 0;
+}
+async function signStripePayload(rawBody, secret, timestampSeconds) {
+  const mac = await hmacSha256Hex(secret, `${timestampSeconds}.${rawBody}`);
+  return `t=${timestampSeconds},v1=${mac}`;
+}
+async function verifyStripeSignature(rawBody, header, secret, nowSeconds, toleranceSeconds = 300) {
+  if (header == null || header.trim() === "") {
+    return { ok: false, reason: "missing-signature-header" };
+  }
+  let t;
+  let v1;
+  for (const part of header.split(",")) {
+    const [k, val] = part.split("=", 2);
+    if (k === "t" && val != null)
+      t = Number(val);
+    if (k === "v1" && val != null)
+      v1 = val;
+  }
+  if (t == null || Number.isNaN(t) || v1 == null) {
+    return { ok: false, reason: "malformed-signature-header" };
+  }
+  if (Math.abs(nowSeconds - t) > toleranceSeconds) {
+    return { ok: false, reason: "timestamp-out-of-tolerance" };
+  }
+  const expected = await hmacSha256Hex(secret, `${t}.${rawBody}`);
+  if (!timingSafeEqualHex(expected, v1)) {
+    return { ok: false, reason: "signature-mismatch" };
+  }
+  return { ok: true };
+}
+
+// src/webhook-handler.ts
+var PATH_PREFIX = "/api/saacms/v1/";
+var INTERNAL_ORIGIN = "http://saacms.internal";
+function reply(status, outcome, detail) {
+  return new Response(JSON.stringify({ ok: status < 400, outcome, detail }), {
+    status,
+    headers: { "Content-Type": "application/json" }
+  });
+}
+function createStripeWebhookHandler(opts) {
+  const tolerance = opts.toleranceSeconds ?? 300;
+  const clock = opts.now ?? (() => Math.floor(Date.now() / 1000));
+  return async function handleStripeWebhook(req) {
+    const rawBody = await req.text();
+    const sigHeader = req.headers.get("Stripe-Signature") ?? undefined;
+    const verified = await verifyStripeSignature(rawBody, sigHeader, opts.signingSecret, clock(), tolerance);
+    if (!verified.ok) {
+      const reason = verified.reason;
+      return reply(400, "signature-invalid", reason);
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(rawBody);
+    } catch {
+      return reply(400, "malformed-event", "body is not valid JSON");
+    }
+    const ev = parsed;
+    if (typeof ev.id !== "string" || typeof ev.type !== "string") {
+      return reply(400, "malformed-event", "missing string id/type");
+    }
+    const event = parsed;
+    const mapped = opts.mapEvent(event);
+    if (mapped == null) {
+      return reply(200, "ignored", `unhandled event type: ${event.type}`);
+    }
+    const body = { ...mapped.body };
+    if (body["stripeEventId"] == null)
+      body["stripeEventId"] = event.id;
+    const collection = mapped.collection || opts.collectionSlug;
+    const createReq = new Request(`${INTERNAL_ORIGIN}${PATH_PREFIX}${collection}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body)
+    });
+    let createRes;
+    try {
+      createRes = await opts.fetch(createReq);
+    } catch {
+      return reply(502, "upstream-error", "runtime fetch threw");
+    }
+    if (createRes.status >= 200 && createRes.status < 300) {
+      return reply(200, "created");
+    }
+    if (createRes.status === 409) {
+      return reply(200, "duplicate");
+    }
+    const status = createRes.status >= 500 ? createRes.status : 502;
+    return reply(status, "upstream-error", `runtime status ${createRes.status}`);
+  };
+}
+export {
+  verifyStripeSignature,
+  timingSafeEqualHex,
+  signStripePayload,
+  hmacSha256Hex,
+  createStripeWebhookHandler
+};

package/dist/signature.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Stripe `Stripe-Signature` verification — Web Crypto only.
+ *
+ * Lifted verbatim (where sound) from the proven commerce-bridge spike
+ * (`examples/astro-cf-demo/src/__tests__/spike/commerce-bridge.spike.test.ts`).
+ *
+ * Stripe's scheme: the header is `t=<unix-seconds>,v1=<hex-hmac>`; the signed
+ * payload is `${t}.${rawBody}`; the MAC is HMAC-SHA256 hex with the endpoint
+ * secret. A correct verifier also rejects timestamps outside a tolerance
+ * window (Stripe's default is 300s) — that is replay protection, so it is
+ * implemented here. No `stripe` SDK, no network: this is exactly the code a
+ * host adapter mounts in front of the saacms runtime.
+ */
+/** HMAC-SHA256 of `message` under `secret`, lowercase hex. */
+export declare function hmacSha256Hex(secret: string, message: string): Promise<string>;
+/** Length-checked constant-time hex compare (no early-out on first mismatch). */
+export declare function timingSafeEqualHex(a: string, b: string): boolean;
+/** Build a real `Stripe-Signature` header value for a raw body. */
+export declare function signStripePayload(rawBody: string, secret: string, timestampSeconds: number): Promise<string>;
+export type SigFailure = "missing-signature-header" | "malformed-signature-header" | "timestamp-out-of-tolerance" | "signature-mismatch";
+export type SigResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: SigFailure;
+};
+export declare function verifyStripeSignature(rawBody: string, header: string | undefined, secret: string, nowSeconds: number, toleranceSeconds?: number): Promise<SigResult>;
+//# sourceMappingURL=signature.d.ts.map

package/dist/signature.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signature.d.ts","sourceRoot":"","sources":["../src/signature.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,8DAA8D;AAC9D,wBAAsB,aAAa,CACjC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,MAAM,CAAC,CAgBjB;AAED,iFAAiF;AACjF,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAOhE;AAED,mEAAmE;AACnE,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,gBAAgB,EAAE,MAAM,GACvB,OAAO,CAAC,MAAM,CAAC,CAGjB;AAED,MAAM,MAAM,UAAU,GAClB,0BAA0B,GAC1B,4BAA4B,GAC5B,4BAA4B,GAC5B,oBAAoB,CAAA;AAExB,MAAM,MAAM,SAAS,GAAG;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,UAAU,CAAA;CAAE,CAAA;AAExE,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,gBAAgB,SAAM,GACrB,OAAO,CAAC,SAAS,CAAC,CAsBpB"}

package/dist/webhook-handler.d.ts

@@ -0,0 +1,88 @@
+/**
+ * `createStripeWebhookHandler` — the reusable, host-mountable Stripe webhook
+ * handler that drives a saacms Collection create through the runtime.
+ *
+ * This productionises the commerce-bridge spike's proven seam
+ * (`docs/spikes/commerce-bridge.md`, GO verdict). The one spike CAVEAT — a
+ * non-atomic, host-side `?filter[stripeEventId]=` dedup pre-check — is
+ * **superseded** here: idempotency is now the ADR-0030 declarative-`unique`
+ * primitive (the target collection declares `unique: [["stripeEventId"]]`,
+ * the runtime returns `409` on a redelivery, this handler maps that to a
+ * `200` ack). There is no read-then-write pre-check anywhere in this module.
+ *
+ * Purity: the handler touches no global and opens no socket. The saacms
+ * runtime is injected as `opts.fetch` (the host passes `app.fetch`); the clock
+ * is injected as `opts.now`. It is therefore fully in-process testable.
+ */
+/**
+ * The minimal structural shape this handler needs from a parsed Stripe event.
+ * Deliberately not the full `Stripe.Event` — no `stripe` SDK dependency. A
+ * real event carries far more; `mapEvent` reads whatever it needs off
+ * `data.object`.
+ */
+export interface StripeEventLike {
+    readonly id: string;
+    readonly type: string;
+    readonly data?: {
+        readonly object?: Record<string, unknown>;
+    };
+}
+/** What `mapEvent` returns to drive a create — or `null` to ignore the event. */
+export interface MappedCreate {
+    /** Target collection slug. Falls back to `opts.collectionSlug` if empty. */
+    readonly collection: string;
+    /**
+     * The create body. MUST carry `stripeEventId` (Stripe's `event.id`) — the
+     * natural idempotency key the target collection declares
+     * `unique: [["stripeEventId"]]` on. If absent, the handler defensively
+     * injects `event.id`.
+     */
+    readonly body: Record<string, unknown>;
+}
+export interface StripeWebhookOptions {
+    /**
+     * The injected saacms runtime. The host passes `app.fetch` from
+     * `createSaacmsRuntime(...)`. The handler never reaches the network itself.
+     */
+    readonly fetch: (req: Request) => Promise<Response> | Response;
+    /** Conventional target collection slug (used when `mapEvent` returns no `collection`). */
+    readonly collectionSlug: string;
+    /** The Stripe endpoint signing secret (`whsec_...`). */
+    readonly signingSecret: string;
+    /**
+     * Map a verified, parsed Stripe event to a create. Return `null` for event
+     * types this endpoint does not handle (Stripe sends many types to one URL).
+     */
+    readonly mapEvent: (event: StripeEventLike) => MappedCreate | null;
+    /** Replay/tolerance window in seconds. Stripe default is 300. */
+    readonly toleranceSeconds?: number;
+    /** Injected clock (unix seconds). Defaults to wallclock — override in tests. */
+    readonly now?: () => number;
+}
+/**
+ * The handler's own outcome tag — surfaced in the JSON response body purely
+ * for host observability. Stripe itself only reads the HTTP status code.
+ */
+export type WebhookOutcome = "created" | "duplicate" | "ignored" | "signature-invalid" | "malformed-event" | "upstream-error";
+/**
+ * Build the host-mountable `(Request) => Promise<Response>`.
+ *
+ * ── The load-bearing HTTP status contract (idempotency lives here) ──────────
+ *
+ *   • Signature missing/malformed/stale/mismatched   → **400** (no fetch, no
+ *     write). A signature failure is permanent; Stripe must NOT retry.
+ *   • Validly-signed body that is not JSON, or has no
+ *     string `id`/`type`                              → **400** (no write).
+ *   • `mapEvent` returns `null` (unhandled type)      → **200** ack, no write
+ *     (so Stripe stops retrying an event we ignore).
+ *   • Runtime create returns 2xx                      → **200** (created).
+ *   • Runtime create returns **409** (ADR-0030
+ *     declarative-`unique` redelivery)                → **200** ack
+ *     ("duplicate"). The order already exists ⇒ this redelivery is an
+ *     idempotent success ⇒ Stripe must NOT retry-storm. NO second row, NO
+ *     second `afterChange` (the runtime never ran the event phase on 409).
+ *   • Any other runtime status (5xx, validation, …)   → a **5xx** so Stripe
+ *     DOES retry (treated as transient). Distinct from the 409→200 path.
+ */
+export declare function createStripeWebhookHandler(opts: StripeWebhookOptions): (req: Request) => Promise<Response>;
+//# sourceMappingURL=webhook-handler.d.ts.map

package/dist/webhook-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-handler.d.ts","sourceRoot":"","sources":["../src/webhook-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAOH;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAA;CAC9D;AAED,iFAAiF;AACjF,MAAM,WAAW,YAAY;IAC3B,4EAA4E;IAC5E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACvC;AAED,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,GAAG,QAAQ,CAAA;IAC9D,0FAA0F;IAC1F,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B,wDAAwD;IACxD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,YAAY,GAAG,IAAI,CAAA;IAClE,iEAAiE;IACjE,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;IAClC,gFAAgF;IAChF,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CAC5B;AAED;;;GAGG;AACH,MAAM,MAAM,cAAc,GACtB,SAAS,GACT,WAAW,GACX,SAAS,GACT,mBAAmB,GACnB,iBAAiB,GACjB,gBAAgB,CAAA;AAcpB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,oBAAoB,GACzB,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAgFrC"}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@saacms/stripe-bridge",
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc --build",
+    "typecheck": "tsc --build --noEmit",
+    "prepack": "cp package.json package.json.pack-bak && bun run ../../scripts/prepack-pkg.ts",
+    "postpack": "mv package.json.pack-bak package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@saacms/core": "workspace:*"
+  },
+  "devDependencies": {
+    "@saacms/storage-libsql": "workspace:*",
+    "@types/bun": "latest",
+    "effect": "^3.10.0",
+    "typescript": "^5.7.0"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts"
+}