@weft-js/pay 0.0.0-stage → 0.1.0

package/src/stripe.ts

@@ -0,0 +1,198 @@
+// `pay.rail@1` on Stripe (research 10 §5): hosted Checkout and the customer portal, over `fetch` with no SDK, and webhooks
+// checked here rather than left to the app. Nothing runs in the browser: `checkout` is a redirect, so a page needs neither
+// Stripe.js nor a publishable key.
+//
+// Stripe's signature is HMAC-SHA256 of `<t>.<raw body>`, in a header `t=…,v1=…` that can carry several `v1` while a secret
+// rolls. Stripe has no ordering guarantee, so each event carries the object's `created` or the event's own time, and the
+// ledger orders by that. A price is the catalog's unless `prices` maps `pro.month` to a Stripe id, on the server.
+
+import { PayError, type CheckoutRequest, type PayRail, type PurchaseState, type RailEvent } from './index'
+
+/** Options of `stripeRail()`. The keys default to the environment, which is where they belong. */
+export interface StripeOptions {
+  /** Stripe Price ids by `<product>.<plan>` or `<product>`, from your own config. Default: amounts from the catalog. */
+  prices?: Record<string, string>
+  /** The API's origin: point it at a local mock. */
+  api?: string
+  /** Pinned, so an account's default version can't reshape these calls. */
+  apiVersion?: string
+  /** Seconds a signed delivery stays acceptable. Default 300, Stripe's own. */
+  tolerance?: number
+  /** ISO countries a `shipping` product delivers to. Default US and CA. */
+  shippingCountries?: string[]
+  /** Default `process.env.STRIPE_SECRET_KEY`. */
+  secretKey?: string
+  /** Default `process.env.STRIPE_WEBHOOK_SECRET`. */
+  webhookSecret?: string
+  /** Default the global one. */
+  fetch?: typeof fetch
+}
+
+const STATES: Record<string, PurchaseState> = {
+  active: 'active', trialing: 'trial', past_due: 'grace', unpaid: 'billing-retry', paused: 'paused', canceled: 'expired', incomplete_expired: 'expired', incomplete: 'pending',
+}
+
+const API = 'https://api.stripe.com'
+const encoder = new TextEncoder()
+
+const fromHex = (s: string) => (/^[0-9a-f]{64}$/.test(s) ? Uint8Array.from(s.match(/../g)!, b => parseInt(b, 16)) : undefined)
+
+/** The runtime's own constant-time compare, in native code. A wasm build was measured against it: see research 38. */
+async function verified(secret: string, text: string, signatures: string[]) {
+  const key = await crypto.subtle.importKey('raw', encoder.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['verify'])
+  const message = encoder.encode(text)
+  let ok = false
+  for (const s of signatures) {
+    const bytes = fromHex(s)
+    if (bytes && await crypto.subtle.verify('HMAC', key, bytes, message)) ok = true
+  }
+  return ok
+}
+
+/** Stripe's form encoding: `a[b][0]=c`. */
+function form(body: Record<string, unknown>) {
+  const out = new URLSearchParams()
+  const put = (key: string, v: unknown) => {
+    if (v === undefined || v === null) return
+    if (Array.isArray(v)) v.forEach((x, i) => put(`${key}[${i}]`, x))
+    else if (typeof v === 'object') for (const [k, x] of Object.entries(v)) put(`${key}[${k}]`, x)
+    else out.append(key, `${v as string | number | boolean}`)
+  }
+  for (const [k, v] of Object.entries(body)) put(k, v)
+  return out
+}
+
+const seconds = (s?: number | null) => (s ? s * 1000 : undefined)
+/** The fields of a Stripe object that an event can carry, whichever kind of object it is. */
+interface StripeObject {
+  id: string
+  status: string
+  customer?: unknown
+  metadata?: Record<string, string> | null
+  mode?: string
+  payment_intent?: unknown
+  payment_status?: string
+  refunded?: boolean
+  current_period_end?: number | null
+  items?: { data?: { current_period_end?: number | null }[] } | null
+}
+interface StripeEvent { id?: string; type: string; created: number; data?: { object?: StripeObject } }
+
+/** A reference that Stripe expands into its object on some API versions. */
+const id = (x: unknown): string | undefined => (typeof x === 'string' ? x : (x as { id?: string } | null | undefined)?.id)
+const identity = (object: StripeObject) => {
+  const m = object?.metadata ?? {}
+  return { ...(m.weft_user && { user: m.weft_user }), ...(m.weft_product && { product: m.weft_product }), ...(m.weft_plan && { plan: m.weft_plan }) }
+}
+
+/** A subscription's paid-through time, which moved onto its items in 2025 API versions. */
+const periodEnd = (sub: StripeObject) => seconds(sub.current_period_end ?? sub.items?.data?.[0]?.current_period_end)
+
+/** One Stripe event as the ledger's, or null for one that says nothing about access. */
+function normalise(event: StripeEvent): RailEvent | null {
+  const object = event.data?.object
+  if (!event.id || !object) return null
+  const base = { id: event.id, at: event.created * 1000 }
+  const { type } = event
+  if (type.startsWith('customer.subscription.')) {
+    const state = STATES[object.status]
+    if (!state) return null
+    const customer = id(object.customer)
+    const expires = periodEnd(object)
+    return { ...base, purchase: object.id, state, ...identity(object), ...(customer && { customer }), ...(expires && { expires }) }
+  }
+  if (type === 'checkout.session.completed' || type === 'checkout.session.async_payment_succeeded' || type === 'checkout.session.async_payment_failed') {
+    if (object.mode !== 'payment') return null // `customer.subscription.*` says what a subscription is doing, trial included
+    const purchase = id(object.payment_intent)
+    if (!purchase) return null
+    const customer = id(object.customer)
+    const state: PurchaseState = type.endsWith('failed') ? 'expired' : object.payment_status === 'unpaid' ? 'pending' : 'active'
+    return { ...base, purchase, state, ...identity(object), ...(customer && { customer }) }
+  }
+  if (type === 'charge.refunded') {
+    const purchase = id(object.payment_intent)
+    return purchase && object.refunded ? { ...base, purchase, state: 'refunded', ...identity(object) } : null // `refunded` is whole: a part refund keeps what was bought
+  }
+  if (type === 'charge.dispute.created' || type === 'charge.dispute.closed') {
+    const purchase = id(object.payment_intent)
+    if (!purchase) return null
+    if (type.endsWith('created')) return { ...base, purchase, state: 'revoked' }
+    return object.status === 'won' ? { ...base, purchase, state: 'active' } : null
+  }
+  return null
+}
+
+/** The Stripe `pay.rail` provider: hosted Checkout, the customer portal, and webhooks verified here. */
+export function stripeRail(options: StripeOptions = {}): PayRail {
+  const { prices = {}, api = API, apiVersion = '2025-09-30.clover', tolerance = 300 } = options
+  const fetcher = options.fetch ?? ((...args: Parameters<typeof fetch>) => fetch(...args))
+  const secret = () => {
+    const key = options.secretKey ?? process.env.STRIPE_SECRET_KEY
+    if (!key) throw new PayError('PAY003', '`STRIPE_SECRET_KEY` is not set on the server', 500)
+    if (api === API && /placeholder/i.test(key)) throw new PayError('PAY003', '`STRIPE_SECRET_KEY` is still the placeholder `weft add pay` wrote: nothing was sent to Stripe', 500) // a mock may take one
+    return key
+  }
+
+  async function call(path: string, body: Record<string, unknown>, idempotencyKey?: string) {
+    const res = await fetcher(`${api}${path}`, {
+      method: 'POST',
+      headers: { authorization: `Bearer ${secret()}`, 'content-type': 'application/x-www-form-urlencoded', 'stripe-version': apiVersion, ...(idempotencyKey && { 'idempotency-key': idempotencyKey }) },
+      body: form(body),
+    })
+    const data = await res.json().catch(() => null) as { url?: string; error?: { message?: string } } | null
+    if (!res.ok) throw new PayError('PAY030', `Stripe refused ${path}: ${data?.error?.message ?? res.status}`, res.status === 429 ? 503 : 502)
+    return data
+  }
+
+  function lineItem({ line }: CheckoutRequest) {
+    const known = prices[line.plan ? `${line.product}.${line.plan}` : line.product]
+    if (known) return { price: known, quantity: line.quantity }
+    return {
+      quantity: line.quantity,
+      price_data: { currency: line.currency, unit_amount: line.amount, product_data: { name: line.name }, ...(line.interval && { recurring: { interval: line.interval } }) },
+    }
+  }
+
+  return {
+    id: 'stripe',
+    async checkout(request) {
+      const { line, user, customer } = request
+      const metadata = { weft_user: user, weft_product: line.product, ...(line.plan && { weft_plan: line.plan }) }
+      const session = await call('/v1/checkout/sessions', {
+        mode: line.mode,
+        line_items: [lineItem(request)],
+        success_url: request.successUrl,
+        cancel_url: request.cancelUrl,
+        client_reference_id: user,
+        customer,
+        metadata,
+        // What the later events carry: a charge and a subscription don't inherit the session's metadata.
+        ...(line.mode === 'subscription'
+          ? { subscription_data: { metadata, trial_period_days: line.trialDays } }
+          : { payment_intent_data: { metadata }, customer_creation: customer ? undefined : 'always', ...(line.shipping && { shipping_address_collection: { allowed_countries: options.shippingCountries ?? ['US', 'CA'] } }) }),
+      }, request.idempotencyKey)
+      if (typeof session?.url !== 'string') throw new PayError('PAY030', 'Stripe answered a session with no url', 502)
+      return { url: session.url }
+    },
+    async portal({ customer, returnUrl }) {
+      const session = await call('/v1/billing_portal/sessions', { customer, return_url: returnUrl })
+      return { url: session!.url! }
+    },
+    async verify({ body, headers }) {
+      const signing = options.webhookSecret ?? process.env.STRIPE_WEBHOOK_SECRET
+      if (!signing) throw new PayError('PAY011', '`STRIPE_WEBHOOK_SECRET` is not set: refusing every webhook rather than trusting one')
+      const parts = (headers.get('stripe-signature') ?? '').split(',').map(p => p.trim().split('='))
+      const t = Number(parts.find(([k]) => k === 't')?.[1])
+      const given = parts.filter(([k]) => k === 'v1').map(([, v]) => v ?? '')
+      if (!Number.isInteger(t) || !given.length) throw new PayError('PAY011', 'no `stripe-signature` to check')
+      if (!(await verified(signing, `${t}.${body}`, given))) throw new PayError('PAY011', 'the signature does not match this body')
+      if (Math.abs(Date.now() / 1000 - t) > tolerance) throw new PayError('PAY011', 'the signature is too old: a replay, or a clock adrift')
+      const event = normalise(JSON.parse(body) as StripeEvent)
+      return event ? [event] : []
+    },
+    async refund({ purchase }) {
+      if (!purchase.startsWith('pi_')) throw new PayError('PAY022', 'Only a one-time payment refunds here: a subscription is cancelled in the portal', 400)
+      await call('/v1/refunds', { payment_intent: purchase }, `refund:${purchase}`)
+    },
+  }
+}

package/src/test.ts

@@ -0,0 +1,169 @@
+// fakePay (research 10 §8): a second `pay.rail` provider, which keeps a rail's state machine in memory. Every event goes the
+// way a real one does, signed, through the app's own `webhook`, ledger and tag pokes, so a test asserts what the user sees
+// and what the server grants. It holds no key and opens no connection, and it reaches @weft-js/core/test only through `net` and
+// `clock`, which any plugin can use. `payRailSuite` is what a rail, this one included, is held to.
+
+import { createHmac, timingSafeEqual } from 'node:crypto'
+import { clock, net } from '@weft-js/core/test'
+import { definePay, memoryPayStore, type Pay, type PayOptions, type Purchase } from './server'
+import { PayError, type CheckoutRequest, type Interval, type PayRail, type Product, type PurchaseState, type RailEvent } from './index'
+
+const DAY = 86_400_000
+const PERIOD: Record<Interval, number> = { day: DAY, week: 7 * DAY, month: 30 * DAY, year: 365 * DAY }
+const TERMS = { 'renewal-failed': 'grace', 'grace-expired': 'expired', recovered: 'active', cancel: 'expired', pause: 'paused', resume: 'active', refund: 'refunded', revoke: 'revoked' } as const
+
+/** What `simulate` can make the rail do next. */
+export type PayScenario = 'renewal' | keyof typeof TERMS
+
+interface Bought { id: string; user: string; product: string; plan?: string; interval?: Interval; state: PurchaseState; expires?: number; customer: string }
+
+/** A rail in memory and the handles a test drives it by, as `fakePay` returns them. */
+export interface FakePay {
+  readonly pay: Pay
+  readonly rail: PayRail
+  /** Every checkout opened, newest last. */
+  readonly sessions: CheckoutRequest[]
+  /** Every delivery and how the app answered. */
+  readonly deliveries: { event: RailEvent; status: number }[]
+  /** The buyer finishes the hosted page: the newest open session, or the one for `user`. */
+  complete(user?: string): Promise<string>
+  /** The buyer closes the page. Nothing happens, as nothing does on a real rail. */
+  abandon(user?: string): void
+  /** A whole purchase, with no checkout screen in the way. */
+  buy(user: string, product: string, plan?: string): Promise<string>
+  /**
+   * What the rail does next: `renewal` moves a clock to the period's end first. `purchase` defaults to the newest.
+   * `renewal-failed`, `grace-expired`, `recovered`, `cancel`, `pause`, `resume`, `refund`, `revoke`.
+   */
+  simulate(what: PayScenario, purchase?: string): Promise<void>
+  /** The last event again: a redelivery. */
+  redeliver(): Promise<number>
+  /** An event by hand, in any order. `{ forged: true }` signs it with the wrong key. */
+  deliver(event: RailEvent, options?: { forged?: boolean }): Promise<number>
+  entitlements(user: string): Promise<string[]>
+  purchases(user: string): Promise<Purchase[]>
+}
+
+const sign = (secret: string, t: number, body: string) => createHmac('sha256', secret).update(`${t}.${body}`).digest('hex')
+const SECRET = 'fake-pay-signing-key'
+
+/** `fakePay(pay)` with the app's own `definePay`, or `fakePay({ catalog })`. It backs `ctx.entitlements` for this test. */
+export function fakePay(app: Pay | (Pick<PayOptions<Product>, 'catalog'> & Partial<PayOptions<Product>>)): FakePay {
+  const sessions: CheckoutRequest[] = [], deliveries: FakePay['deliveries'] = []
+  const purchases = new Map<string, Bought>()
+  let seq = 0, last: RailEvent | undefined
+  const next = (prefix: string) => `${prefix}_${++seq}`
+
+  const rail: PayRail = {
+    id: 'fake',
+    checkout(request) {
+      sessions.push(request)
+      return Promise.resolve({ url: `https://fake-pay.test/checkout/${next('cs')}` })
+    },
+    portal: ({ customer }) => Promise.resolve({ url: `https://fake-pay.test/portal/${customer}` }),
+    verify({ body, headers }) {
+      const [t, v1] = (headers.get('x-fake-signature') ?? '').split(',')
+      const want = Buffer.from(sign(SECRET, Number(t), body)), got = Buffer.from(v1 ?? '')
+      if (want.length !== got.length || !timingSafeEqual(want, got)) throw new PayError('PAY011', 'no valid fake signature')
+      return JSON.parse(body)
+    },
+    async refund({ purchase }) {
+      await simulate('refund', purchase)
+    },
+  }
+
+  const pay: Pay = 'webhook' in app ? app : definePay({ store: memoryPayStore(), urls: { success: '/', cancel: '/' }, ...app })
+  pay.use(rail)
+  net.extension(pay)
+
+  async function post(event: RailEvent, secret: string) {
+    const body = JSON.stringify([event]), t = Date.now()
+    const request = new Request('http://localhost/_weft/pay/fake', { method: 'POST', body, headers: { 'x-fake-signature': `${t},${sign(secret, t, body)}` } })
+    const { response, tags } = await pay.webhook('fake', request)
+    deliveries.push({ event, status: response.status })
+    if (tags.length && net.subscriptions().length) await net.poke(...tags)
+    return response.status
+  }
+  const deliver: FakePay['deliver'] = (event, options) => { if (!options?.forged) last = event; return post(event, options?.forged ? 'not-the-key' : SECRET) }
+
+  const event = (b: Bought): RailEvent => ({ id: next('evt'), at: Date.now(), purchase: b.id, state: b.state, user: b.user, product: b.product, ...(b.plan && { plan: b.plan }), customer: b.customer, ...(b.expires !== undefined && { expires: b.expires }) })
+
+  async function open(s: CheckoutRequest) {
+    const { line, user } = s
+    const b: Bought = { id: next(line.mode === 'subscription' ? 'sub' : 'pay'), user, product: line.product, state: line.trialDays ? 'trial' : 'active', customer: s.customer ?? next('cus'), ...(line.plan && { plan: line.plan }), ...(line.interval && { interval: line.interval }) }
+    if (b.interval) b.expires = Date.now() + (line.trialDays ? line.trialDays * DAY : PERIOD[b.interval])
+    purchases.set(b.id, b)
+    await deliver(event(b))
+    return b.id
+  }
+
+  const take = (user?: string) => {
+    const i = user ? sessions.findLastIndex(s => s.user === user) : sessions.length - 1
+    if (i < 0) throw new Error(`fakePay: no open checkout${user ? ` for ${user}` : ''}: call \`checkout\` first`)
+    return sessions.splice(i, 1)[0]!
+  }
+
+  async function simulate(what: PayScenario, id?: string) {
+    const b = id ? purchases.get(id) : [...purchases.values()].at(-1)
+    if (!b) throw new Error(`fakePay: no purchase${id ? ` \`${id}\`` : ' yet'} to ${what}`)
+    if (what === 'renewal' || what === 'renewal-failed') {
+      if (!b.interval) throw new Error(`fakePay: \`${b.id}\` is one payment: only a subscription renews`)
+      if (clock.installed) await clock.advance(Math.max(0, b.expires! - Date.now()))
+    }
+    if (what === 'renewal') Object.assign(b, { state: 'active', expires: b.expires! + PERIOD[b.interval!] })
+    else b.state = TERMS[what]
+    await deliver(event(b))
+  }
+
+  return {
+    pay, rail, sessions, deliveries, deliver, simulate,
+    complete: user => open(take(user)),
+    abandon: user => void take(user),
+    async buy(user, product, plan) {
+      await pay.checkout({ user: { id: user }, request: { url: 'http://localhost/' } }, { product, ...(plan && { plan }) })
+      return open(take(user))
+    },
+    redeliver() {
+      if (!last) throw new Error('fakePay: nothing delivered yet')
+      return post(last, SECRET)
+    },
+    entitlements: user => pay.entitlements(user).list(),
+    purchases: user => pay.purchases(user),
+  }
+}
+
+/** One requirement of a suite, and how the rail did. */
+export interface Check { name: string; ok: boolean; detail: string }
+
+/** What `payRailSuite` needs: the rail, and a way to make a delivery it would accept. */
+export interface PayRailSuiteOptions {
+  rail: PayRail
+  /** A delivery the rail would accept, `age` ms old, for a purchase event. Omit `age` for one just sent. */
+  delivery: (age?: number) => { body: string; headers: Headers }
+  /** How old a delivery may be before a rail refuses it as a replay. Without it the replay check isn't run. */
+  tolerance?: number
+}
+
+/** One Check per requirement of `pay.rail@1`, against whatever `fetch` the rail was given. Any `ok: false` is P119. */
+export async function payRailSuite({ rail, delivery, tolerance }: PayRailSuiteOptions): Promise<Check[]> {
+  const out: Check[] = []
+  const check = (name: string, ok: boolean, detail = '') => void out.push({ name, ok, detail })
+  const refused = async (d: { body: string; headers: Headers }) => {
+    try { await rail.verify(d); return false } catch (e) { return (e as { code?: string } | null)?.code === 'PAY011' }
+  }
+  const good = delivery()
+  const events = await rail.verify(good)
+  const e = events[0]
+  check('a genuine delivery verifies', events.length > 0, `${events.length} events`)
+  check('an event has an id, a time in ms and a purchase', !!e && typeof e.id === 'string' && e.id !== '' && e.at > 1e11 && typeof e.purchase === 'string', JSON.stringify(e))
+  check('the same delivery gives the same id, so a repeat is a no-op', (await rail.verify(good))[0]?.id === e?.id)
+  check('a changed byte is refused', await refused({ body: `${good.body} `, headers: good.headers }))
+  check('no signature is refused', await refused({ body: good.body, headers: new Headers() }))
+  if (tolerance) check('an old delivery is refused as a replay', await refused(delivery(tolerance + 60_000)))
+  const line = { product: 'pro', name: 'Pro', amount: 999, currency: 'usd', mode: 'subscription', plan: 'month', interval: 'month', quantity: 1 } as const
+  const { url } = await rail.checkout({ user: 'u1', line, successUrl: 'https://app.test/ok', cancelUrl: 'https://app.test/no', idempotencyKey: 'k1' })
+  check('`checkout` answers an absolute URL', /^https?:\/\//.test(url), url)
+  const portal = await rail.portal({ customer: 'c1', returnUrl: 'https://app.test/account' })
+  check('`portal` answers an absolute URL', /^https?:\/\//.test(portal.url), portal.url)
+  return out
+}

package/stripe-plugin.d.mts

@@ -0,0 +1,5 @@
+import type { PluginInstance } from '@weft-js/core/plugin'
+
+declare const plugin: (options?: { prices?: Record<string, string>; api?: string; apiVersion?: string; tolerance?: number }) => PluginInstance<unknown>
+/** `stripe()` for `weft.config.ts`: Stripe as a `pay.rail` provider. Keys stay in the environment. */
+export default plugin

package/stripe-plugin.mjs

@@ -0,0 +1,19 @@
+// stripe() for weft.config.ts: this package as the `pay.rail` provider for the web. Options are in the generated slot
+// module, so they name env vars and never hold a key (PAY003). Another provider is this one line swapped for another.
+import { definePlugin, defineSlot, provide } from '@weft-js/core/plugin'
+
+const slot = defineSlot({ id: 'pay.rail', version: 1, cardinality: 'keyed', sides: ['server', 'client', 'native'] })
+
+export const stripe = definePlugin({
+  name: '@weft-js/pay/stripe',
+  version: '0.0.0',
+  weft: '*',
+  permissions: { net: ['api.stripe.com'], env: ['STRIPE_SECRET_KEY', 'STRIPE_WEBHOOK_SECRET'] },
+  contribute: options => ({
+    provides: [provide(slot, { key: 'stripe', sides: { server: { module: '@weft-js/pay/stripe', export: 'stripeRail', options } } })],
+    agents: { title: 'Pay rail: Stripe', text: 'Stripe Checkout, server side only: `STRIPE_SECRET_KEY`, and `STRIPE_WEBHOOK_SECRET` for `/_weft/x/pay/stripe`, the webhook URL to give Stripe.' },
+    map: [{ want: 'Change the payment provider', call: 'replace this plugin in `plugins`: app code stays', have: 'Stripe Checkout' }],
+  }),
+})
+
+export default stripe