@suluk/stripe 0.1.5 → 0.1.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suluk/stripe",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "First-class Stripe via a swappable PaymentProvider: usage-based billing (Billing Meters + meter events), customers, metered prices, subscriptions, webhooks — and a bridge from @suluk/cost to Stripe usage. Other processors follow Stripe. CANDIDATE tooling.",
   "publishConfig": {
   "access": "public"

package/src/index.ts

@@ -31,3 +31,7 @@ export {
   type StripeCheckoutLike, type PaymentMethodLike, type PaymentIntentLike,
 } from "./checkout";
 export { webhookRouter, STRIPE_EVENTS, type WebhookRouter, type WebhookHandler, type HandleResult } from "./webhook";
+// SDK-free edge webhook verification (Web Crypto) — one verifier for dev + Workers prod, no `stripe` SDK.
+export { verifyStripeSignature, timingSafeHexEqual, type VerifyOptions } from "./webhook-verify";
+// the StripeLike fetch impl (Workers-safe) + read surface for webhook PI→order resolution + refund checks.
+export { restStripe, toForm, stripeGet, retrievePaymentIntent, type RestStripeOptions } from "./rest";

package/src/rest.ts

@@ -0,0 +1,76 @@
+/**
+ * A {@link StripeLike} client over the Stripe REST API (fetch only — no SDK), so the @suluk/stripe helpers
+ * (setupUsageBilling / stripeProvider / reportCostUsage / subscriptions) run on a Cloudflare Worker or any fetch
+ * runtime. Stripe's API is form-encoded with bracket notation for nested params; {@link toForm} flattens the param
+ * objects the helpers build. Plus the read surface ({@link stripeGet} / {@link retrievePaymentIntent}) the edge needs
+ * for webhook PaymentIntent→order resolution and refund-state checks. `fetch` is injectable for testing.
+ */
+import type { StripeLike } from "./types";
+
+type FetchLike = typeof fetch;
+export interface RestStripeOptions { fetch?: FetchLike }
+
+/** Flatten a params object into Stripe's bracket form-encoding (recurse objects + arrays). */
+export function toForm(obj: Record<string, unknown>, prefix = "", form = new URLSearchParams()): URLSearchParams {
+  for (const [k, v] of Object.entries(obj)) {
+    if (v == null) continue;
+    const key = prefix ? `${prefix}[${k}]` : k;
+    if (Array.isArray(v)) {
+      v.forEach((item, i) => {
+        if (item && typeof item === "object") toForm(item as Record<string, unknown>, `${key}[${i}]`, form);
+        else form.append(`${key}[${i}]`, String(item));
+      });
+    } else if (typeof v === "object") {
+      toForm(v as Record<string, unknown>, key, form);
+    } else {
+      form.append(key, String(v));
+    }
+  }
+  return form;
+}
+
+/** A duck-typed Stripe client backed by the REST API. `key` is the secret key. */
+export function restStripe(key: string, opts: RestStripeOptions = {}): StripeLike {
+  const f = opts.fetch ?? fetch;
+  const post = async (path: string, params: Record<string, unknown>): Promise<any> => { // eslint-disable-line @typescript-eslint/no-explicit-any
+    const res = await f(`https://api.stripe.com/v1/${path}`, {
+      method: "POST",
+      headers: { authorization: `Bearer ${key}`, "content-type": "application/x-www-form-urlencoded" },
+      body: toForm(params).toString(),
+    });
+    const json = await res.json().catch(() => ({}));
+    if (!res.ok) throw new Error((json as { error?: { message?: string } })?.error?.message ?? `Stripe ${path} failed (${res.status})`);
+    return json;
+  };
+  return {
+    customers: { create: (p) => post("customers", p) },
+    products: { create: (p) => post("products", p) },
+    prices: { create: (p) => post("prices", p) },
+    subscriptions: { create: (p) => post("subscriptions", p) },
+    billing: {
+      meters: { create: (p) => post("billing/meters", p) },
+      meterEvents: { create: (p) => post("billing/meter_events", p) },
+    },
+    billingPortal: { sessions: { create: (p) => post("billing_portal/sessions", p) } },
+    // verifyWebhook isn't used by the REST adapter (the edge uses verifyStripeSignature) — stub to satisfy the type.
+    webhooks: { constructEvent: () => { throw new Error("constructEvent not supported by the REST adapter; use verifyStripeSignature"); } },
+  } as StripeLike;
+}
+
+/** Low-level authenticated GET → parsed JSON (null on non-OK / parse error). */
+export async function stripeGet<T = unknown>(key: string, path: string, opts: RestStripeOptions = {}): Promise<T | null> {
+  if (!key) return null;
+  const f = opts.fetch ?? fetch;
+  try {
+    const r = await f(`https://api.stripe.com/v1/${path}`, { headers: { authorization: `Bearer ${key}` } });
+    if (!r.ok) return null;
+    return (await r.json().catch(() => null)) as T | null;
+  } catch { return null; }
+}
+
+/** Retrieve a PaymentIntent, optionally expanding fields (e.g. `latest_charge`). Returns null if unresolvable. */
+export async function retrievePaymentIntent<T = Record<string, unknown>>(key: string, id: string, opts: RestStripeOptions & { expand?: string[] } = {}): Promise<T | null> {
+  if (!id) return null;
+  const q = (opts.expand ?? []).map((e) => `expand[]=${encodeURIComponent(e)}`).join("&");
+  return stripeGet<T>(key, `payment_intents/${encodeURIComponent(id)}${q ? "?" + q : ""}`, opts);
+}

package/src/webhook-verify.ts

@@ -0,0 +1,40 @@
+/**
+ * SDK-free Stripe webhook signature verification (Web Crypto HMAC-SHA256) — runs on Workers / Bun / Node 18+ with
+ * NO `stripe` SDK. The edge leaf: prove a webhook payload is authentic AND fresh before dispatching it (e.g. via
+ * {@link webhookRouter}). `stripeProvider.verifyWebhook` (the SDK's constructEvent) stays for SDK callers; this is
+ * the binding-free path, so a dev server and a Workers prod runtime can share ONE verifier instead of diverging.
+ */
+
+/** Constant-time hex-string compare (no early-out) — guards the signature check against timing oracles. */
+export function timingSafeHexEqual(a: string, b: string): boolean {
+  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;
+}
+
+export interface VerifyOptions {
+  /** current unix seconds (default `Date.now()/1000`) — injectable for tests + replay-window tuning. */
+  now?: () => number;
+  /** reject events whose timestamp is older than this many seconds (default 300 — Stripe's window). */
+  toleranceSec?: number;
+}
+
+/**
+ * Verify a Stripe `stripe-signature` header against the raw request body + the endpoint signing secret.
+ * Returns true iff a v1 signature matches the HMAC of `${t}.${rawBody}` AND the timestamp is within tolerance.
+ * Pass the RAW (unparsed) body — re-serializing JSON changes the bytes and breaks the HMAC.
+ */
+export async function verifyStripeSignature(rawBody: string, sigHeader: string, secret: string, opts: VerifyOptions = {}): Promise<boolean> {
+  if (!rawBody || !sigHeader || !secret) return false;
+  const parts: Record<string, string> = {};
+  for (const p of sigHeader.split(",")) { const i = p.indexOf("="); if (i > 0 && !(p.slice(0, i) in parts)) parts[p.slice(0, i)] = p.slice(i + 1); } // split on the FIRST '=' only
+  const ts = Number(parts.t);
+  if (!parts.t || !parts.v1 || !Number.isFinite(ts)) return false;
+  const now = (opts.now ?? (() => Date.now() / 1000))();
+  if (Math.abs(now - ts) > (opts.toleranceSec ?? 300)) return false; // reject stale/replayed events (Stripe's 5-min window)
+  const keyData = await crypto.subtle.importKey("raw", new TextEncoder().encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+  const mac = await crypto.subtle.sign("HMAC", keyData, new TextEncoder().encode(`${ts}.${rawBody}`));
+  const expected = [...new Uint8Array(mac)].map((b) => b.toString(16).padStart(2, "0")).join("");
+  return timingSafeHexEqual(expected, parts.v1);
+}

package/src/webhook.ts

@@ -41,9 +41,12 @@ export function webhookRouter(handlers: Record<string, WebhookHandler> = {}): We
 
 /** The common Stripe checkout/billing event types (for discoverability + typo-safe registration). */
 export const STRIPE_EVENTS = {
+  checkoutCompleted: "checkout.session.completed",
+  checkoutExpired: "checkout.session.expired",
   paymentSucceeded: "payment_intent.succeeded",
   paymentFailed: "payment_intent.payment_failed",
   chargeRefunded: "charge.refunded",
+  disputeClosed: "charge.dispute.closed",
   setupSucceeded: "setup_intent.succeeded",
   subscriptionUpdated: "customer.subscription.updated",
   subscriptionDeleted: "customer.subscription.deleted",

package/test/rest.test.ts

@@ -0,0 +1,47 @@
+/**
+ * rest.ts — the Workers-safe StripeLike fetch impl. Pins toForm's bracket encoding (the load-bearing form-encoder
+ * the helpers rely on) + the read surface (retrievePaymentIntent) over an injected fetch.
+ */
+import { test, expect, describe } from "bun:test";
+import { toForm, restStripe, retrievePaymentIntent, stripeGet } from "../src/index";
+
+describe("toForm", () => {
+  test("flattens scalars, nested objects, and arrays into Stripe bracket notation", () => {
+    const f = toForm({ email: "a@b.com", metadata: { orderId: 7 }, items: [{ price: "p_1", qty: 2 }] });
+    expect(f.get("email")).toBe("a@b.com");
+    expect(f.get("metadata[orderId]")).toBe("7");
+    expect(f.get("items[0][price]")).toBe("p_1");
+    expect(f.get("items[0][qty]")).toBe("2");
+  });
+  test("drops null/undefined", () => {
+    const f = toForm({ a: 1, b: null, c: undefined });
+    expect(f.has("b")).toBe(false);
+    expect(f.has("c")).toBe(false);
+    expect(f.get("a")).toBe("1");
+  });
+});
+
+describe("rest read surface (injected fetch)", () => {
+  const mockFetch = (status: number, body: unknown) => (async () => new Response(JSON.stringify(body), { status })) as unknown as typeof fetch;
+
+  test("retrievePaymentIntent returns the parsed PI + builds the expand query", async () => {
+    let seenUrl = "";
+    const fetch = (async (url: string) => { seenUrl = url; return new Response(JSON.stringify({ id: "pi_1", metadata: { orderId: "42" } }), { status: 200 }); }) as unknown as typeof fetch;
+    const pi = await retrievePaymentIntent<{ metadata?: { orderId?: string } }>("sk_test", "pi_1", { expand: ["latest_charge"], fetch });
+    expect(pi?.metadata?.orderId).toBe("42");
+    expect(seenUrl).toContain("/payment_intents/pi_1");
+    expect(seenUrl).toContain("expand[]=latest_charge");
+  });
+
+  test("stripeGet returns null on non-OK", async () => {
+    expect(await stripeGet("sk_test", "payment_intents/x", { fetch: mockFetch(404, { error: {} }) })).toBeNull();
+  });
+
+  test("restStripe.customers.create posts form-encoded + parses the result", async () => {
+    let body = "";
+    const fetch = (async (_url: string, init: RequestInit) => { body = String(init.body); return new Response(JSON.stringify({ id: "cus_1" }), { status: 200 }); }) as unknown as typeof fetch;
+    const r = await restStripe("sk_test", { fetch }).customers.create({ email: "a@b.com" });
+    expect((r as { id: string }).id).toBe("cus_1");
+    expect(body).toContain("email=a%40b.com");
+  });
+});

package/test/webhook-verify.test.ts

@@ -0,0 +1,58 @@
+/**
+ * verifyStripeSignature — the SDK-free Web-Crypto webhook verifier. Pins a known-good signature (computed with the
+ * same HMAC the verifier checks), a stale-timestamp rejection, and a tampered-body rejection. The constant-time
+ * compare must have no early-out. These pin the behavior BEFORE dev + prod adopt this one verifier.
+ */
+import { test, expect, describe } from "bun:test";
+import { verifyStripeSignature, timingSafeHexEqual } from "../src/index";
+
+const SECRET = "whsec_test_secret";
+const BODY = JSON.stringify({ id: "evt_1", type: "checkout.session.completed", data: { object: { id: "cs_1" } } });
+
+/** Build a valid `stripe-signature` header (t=<ts>,v1=<HMAC-SHA256(`${ts}.${body}`)>) the way Stripe does. */
+async function sign(body: string, secret: string, ts: number): Promise<string> {
+  const key = await crypto.subtle.importKey("raw", new TextEncoder().encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+  const mac = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(`${ts}.${body}`));
+  const v1 = [...new Uint8Array(mac)].map((b) => b.toString(16).padStart(2, "0")).join("");
+  return `t=${ts},v1=${v1}`;
+}
+
+describe("verifyStripeSignature", () => {
+  const now = () => 1_700_000_000; // fixed clock
+
+  test("accepts a fresh, correctly-signed payload", async () => {
+    const sig = await sign(BODY, SECRET, 1_700_000_000);
+    expect(await verifyStripeSignature(BODY, sig, SECRET, { now })).toBe(true);
+  });
+
+  test("rejects a stale timestamp beyond tolerance (replay)", async () => {
+    const sig = await sign(BODY, SECRET, 1_700_000_000 - 600); // 10 min old, tolerance 300
+    expect(await verifyStripeSignature(BODY, sig, SECRET, { now })).toBe(false);
+  });
+
+  test("rejects a tampered body (HMAC mismatch)", async () => {
+    const sig = await sign(BODY, SECRET, 1_700_000_000);
+    expect(await verifyStripeSignature(BODY + " ", sig, SECRET, { now })).toBe(false);
+  });
+
+  test("rejects a wrong secret, a missing v1, and empty inputs", async () => {
+    const sig = await sign(BODY, SECRET, 1_700_000_000);
+    expect(await verifyStripeSignature(BODY, sig, "whsec_wrong", { now })).toBe(false);
+    expect(await verifyStripeSignature(BODY, "t=1700000000", SECRET, { now })).toBe(false);
+    expect(await verifyStripeSignature("", sig, SECRET, { now })).toBe(false);
+  });
+
+  test("honors an injected tolerance window", async () => {
+    const sig = await sign(BODY, SECRET, 1_700_000_000 - 60);
+    expect(await verifyStripeSignature(BODY, sig, SECRET, { now, toleranceSec: 30 })).toBe(false);
+    expect(await verifyStripeSignature(BODY, sig, SECRET, { now, toleranceSec: 120 })).toBe(true);
+  });
+});
+
+describe("timingSafeHexEqual", () => {
+  test("true on equal, false on differing same-length and differing-length", () => {
+    expect(timingSafeHexEqual("deadbeef", "deadbeef")).toBe(true);
+    expect(timingSafeHexEqual("deadbeef", "deadbef0")).toBe(false);
+    expect(timingSafeHexEqual("dead", "deadbeef")).toBe(false);
+  });
+});