@weft-js/pay 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,16 @@
+MIT License
+
+Copyright (c) 2026 ravonus
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+documentation files (the "Software"), to deal in the Software without restriction, including without limitation the
+rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit
+persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the
+Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,9 @@
-# Temporary Holding Version
+# @weft-js/pay
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> **Early release (0.1.1).** APIs will change between minor versions.
+
+Products, one ledger for every rail, and entitlements. weft's reference plugin: read it to build your own.
+
+```bash
+npm install @weft-js/pay
+```

package/docs/pay.md

@@ -0,0 +1,118 @@
+# Payments
+
+This is a plugin, `@weft-js/pay`, and nothing in weft names it. `weft docs plugins` walks through how it is built.
+
+`weft add pay` needs a database and auth. It adds the Stripe rail to `plugins` and writes `src/pay/catalog.ts`,
+`src/pay.server.ts` and `src/server/pay.ts`, plus `src/db/pay.schema.ts` and placeholder keys. The keys go in `.env`
+with real test values before you run it. Nothing is called until a user checks out.
+
+App code names products, never a rail:
+
+```ts
+// src/pay/catalog.ts: reaches the client, so names and amounts only
+import { product } from '@weft-js/pay'
+
+export const pro = product({ id: 'pro', kind: 'subscription', use: 'digital',
+  plans: { month: { usd: 999 }, year: { usd: 7999, trialDays: 7 } }, grants: ['pro'] })
+```
+
+<!-- example: skip needs what `weft add pay` writes -->
+```tsx
+// a page
+import { price } from '@weft-js/pay'
+import { pro } from '#/pay/catalog'
+import { checkout, entitlements, portal } from '#/server/pay'
+
+export default function Pricing() {
+  const mine = entitlements.live()
+  return (
+    <section>
+      <button type="button" onClick={() => checkout({ product: 'pro', plan: 'year' })}>Go Pro · {price(pro, 'year').display}</button>
+      <button type="button" onClick={() => portal()}>Manage</button>
+      {mine.value?.includes('pro') && <p>You have Pro.</p>}
+    </section>
+  )
+}
+```
+
+`kind` is `subscription` (with `plans`), `one-time` or `consumable` (with `price`). Amounts are whole minor units with a
+currency (PAY008). `price(p, plan)` formats by the currency's exponent, for the reader's locale.
+
+**A grant comes only from a verified event.** `checkout` goes to the rail's hosted page and grants nothing (PAY004). The
+rail then posts `/_weft/x/pay/<rail>`, which is the URL to give it, and `/_weft/x/pay/stripe` for Stripe. Each delivery is
+verified on the exact bytes, applied to `purchases`, and pokes `entitlements:<user>`, so a `.live()` reader updates.
+Delivery is at least once and in any order: a repeat is a no-op, and an old event changes nothing, by the rail's own clock.
+A bad signature answers 400; a failure answers 500, so the rail delivers it again.
+
+**Enforce on the server.** What the client shows is decoration (PAY013):
+
+<!-- example: skip fragments of a server module -->
+```ts
+export const report = query({ auth: 'user', requires: ['pro'], run: ({ ctx }) => buildReport(ctx) })  // a typed 403: ENTITLEMENT_REQUIRED
+if (!(await ctx.entitlements.has('pro'))) redirect('/pricing')                                          // await it (PAY015)
+```
+
+`ctx.entitlements` has `has(id)` and `list()`, and works in any `query`, `mutation` or `load`. A query with `cache: { life }`
+needs `scope: 'user'` to read it. A query's `tags` can take `ctx`, which is how one user's tag is written.
+
+States are the same on every rail: `active`, `trial` and `grace` give access; `pending`, `billing-retry`, `paused`,
+`expired`, `refunded` and `revoked` don't. Access also ends `leeway` (3 days) after a paid period, if no renewal came.
+
+`definePay({ catalog, store, urls, user?, rail?, origin?, leeway? })`. `urls` are where a buyer returns, never from the
+client. `pay.checkout(ctx, input)`, `pay.portal(ctx)`, `pay.entitlements(userId)`, `pay.purchases(userId)` and
+`pay.refund(purchaseId)` are server calls. `store` is `drizzlePayStore(db, { purchases, payEvents })` from
+`@weft-js/pay/drizzle`, or five methods of your own (`PayStore`: `seen`, `mark`, `purchase`, `save`, `byUser`). `memoryPayStore()` is for tests: a production server
+refuses it (PAY016).
+
+**Another provider is one setting.** Replace `stripe()` in `plugins` with any plugin for the `pay.rail` slot; nothing else
+changes. A rail implements `PayRail` from `@weft-js/pay`: `checkout`, `portal`, `verify`, optionally `refund`, declared for the
+`server` side, and passes `payRailSuite` from `@weft-js/pay/test`. `verify` gets the exact body and throws
+`PayError('PAY011', …)` for anything it can't prove. An app with no `src/pay.server.ts` has no route and no code from any
+of this.
+
+`stripe({ prices?, api?, apiVersion?, tolerance?, shippingCountries? })` from `@weft-js/pay/stripe/plugin`. It reads
+`STRIPE_SECRET_KEY` and `STRIPE_WEBHOOK_SECRET` from the server env. Don't put a key in its options: they land in a
+generated file (PAY003).
+`prices` maps `'pro.month'` to a Stripe Price id; without it, amounts come from the catalog. Subscribe the webhook to
+`customer.subscription.*`, `checkout.session.*`, `charge.refunded` and `charge.dispute.*`. No page loads Stripe.js.
+
+## Testing
+
+`fakePay` from `@weft-js/pay/test` is a rail with no key and no network. Its events are signed and go through your own webhook and
+ledger, so a test sees what a user would:
+
+```tsx
+const fake = fakePay(pay)                     // your `definePay`, or fakePay({ catalog })
+net.context({ user: { id: 'u1' } })
+render(Paywall)
+await user.click(screen.getByRole('button', { name: /Go Pro/ }))
+await fake.complete()                          // the buyer finishes the hosted page
+expect(screen.getByLabelText('plan').textContent).toBe('Pro')
+await fake.simulate('renewal-failed')          // renewal, recovered, grace-expired, cancel, pause, resume, refund, revoke
+```
+
+`fake.buy(user, product, plan)` skips the page. `renewal` and `renewal-failed` move `clock` to the period's end when it's
+installed. `fake.redeliver()`, `fake.deliver(event, { forged: true })`, `fake.deliveries`, `fake.sessions`,
+`fake.entitlements(user)`.
+
+## Diagnostics
+
+| Code | Catches |
+|---|---|
+| PAY003 | A key in the source, or a server secret in client code |
+| PAY004 | Paid state written on the client after `checkout()` |
+| PAY005 | A price typed into a page that sells something (warning) |
+| PAY008 | A float or a currency-less amount in `product()` |
+| PAY010 | A checkout mutation without `auth: 'user'` |
+| PAY011 | A webhook left unverified, or no `STRIPE_WEBHOOK_SECRET` |
+| PAY012 | A rail's price or product id in client code |
+| PAY013 | An entitlement checked only on the client |
+| PAY014 | A rail bound with no `src/pay.server.ts` |
+| PAY015 | `ctx.entitlements.has()` tested without `await` |
+| PAY016 | `memoryPayStore()` in `src/pay.server.ts` (warning) |
+| PAY017 | `@weft-js/pay/server` or `/drizzle` imported in client code |
+| PAY018 | `src/pay.server.ts` with no `pay.rail` provider |
+| PAY031 | A live key in a test |
+
+At run time: PAY021 (not in the catalog), PAY022 (no rail chosen), PAY023 (already subscribed, 409), PAY024 (nothing to
+manage or refund), PAY030 (the rail refused). Native rails, store policy and `weft pay sync` aren't built.

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@weft-js/pay",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "@weft-js/pay: products, one ledger for every rail, and entitlements. weft's reference plugin: read it to build your own",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./server": "./src/server.ts",
+    "./drizzle": "./src/drizzle.ts",
+    "./test": "./src/test.ts",
+    "./plugin": "./plugin.mjs",
+    "./stripe": "./src/stripe.ts",
+    "./stripe/plugin": "./stripe-plugin.mjs"
+  },
+  "files": [
+    "src",
+    "docs",
+    "plugin.mjs",
+    "plugin.d.mts",
+    "stripe-plugin.mjs",
+    "stripe-plugin.d.mts",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "typescript": "6.0.3"
+  },
+  "peerDependencies": {
+    "@weft-js/start": "^0.1.1",
+    "drizzle-orm": "^0.45.0",
+    "@weft-js/core": "^0.1.1"
+  },
+  "peerDependenciesMeta": {
+    "drizzle-orm": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=26"
+  },
+  "keywords": [
+    "weft"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/plugin.d.mts

@@ -0,0 +1,5 @@
+import type { PluginInstance } from '@weft-js/core/plugin'
+
+declare const plugin: (options?: Record<string, never>) => PluginInstance<unknown>
+/** `pay()` for `weft.config.ts`: the `pay.rail` slot, the PAY checks and the ledger's route. Rails are plugins of their own. */
+export default plugin

package/plugin.mjs

@@ -0,0 +1,50 @@
+// pay() for weft.config.ts: start here to see how a plugin is put together (`weft docs plugins` walks through it). Everything
+// a plugin gives weft is in this one pure manifest: the server part as a slot provider, and its checks, docs, codes and
+// `weft add` steps as data. Heavy code stays behind `import()` and the slot's lazy `load()`, so a config load costs little
+// and a page costs nothing. A payment provider is a separate plugin: this one defines the ledger, and `pay.rail` is the seam.
+import { definePlugin, defineSlot, provide } from '@weft-js/core/plugin'
+import { setup } from './src/setup.mjs'
+
+const extension = defineSlot({ id: 'server.extension', version: 1, cardinality: 'keyed', sides: ['server'] })
+
+const diagnostics = [
+  ['PAY003', 'error', 'A Stripe secret, restricted or webhook key in the source, a server secret read in client code, or a key in plugin options', 'Move it to the server env (`src/env.server.ts`), and roll any real key that was committed'],
+  ['PAY004', 'error', "Paid state written on the client after `checkout()`, which only opens the rail's page", 'Read `entitlements` instead: a grant arrives from a verified event'],
+  ['PAY005', 'warning', 'A price typed into a page that sells something', '`price(product, plan).display`'],
+  ['PAY008', 'error', 'Money as a float, or with no currency, in `product()`', 'Whole minor units with a currency: `{ usd: 999 }`'],
+  ['PAY010', 'error', "A mutation that opens a checkout without `auth: 'user'`", "Add `auth: 'user'`: a purchase has to belong to someone"],
+  ['PAY011', 'error', 'A webhook left unverified: a handler of payment events with no signature check, a `PayRail` whose `verify` ignores `headers`, or no `STRIPE_WEBHOOK_SECRET`', 'Delete the handler: `/_weft/x/pay/<rail>` verifies. Give Stripe that URL, and set `STRIPE_WEBHOOK_SECRET`'],
+  ['PAY012', 'error', "A rail's price or product id in client code", "Name the catalog: `checkout({ product: 'pro', plan: 'month' })`. Map ids on the server: `stripe({ prices: { 'pro.month': … } })`"],
+  ['PAY013', 'error', 'An entitlement checked only on the client: nothing on the server enforces it', "`requires: ['pro']` on the query or mutation, or `await ctx.entitlements.has('pro')` in a `load`"],
+  ['PAY014', 'error', 'The plugin with no `src/pay.server.ts`: no webhook is mounted, so payments grant nothing', 'Default-export `definePay({ … })` from `src/pay.server.ts`'],
+  ['PAY015', 'error', '`ctx.entitlements.has()` tested without `await`: a promise is truthy, so everyone passes', 'Await it (`weft fix` does, in an `async` function)'],
+  ['PAY016', 'warning', '`memoryPayStore()` in `src/pay.server.ts`: a production server refuses to start with it', '`drizzlePayStore(db, { purchases, payEvents })`, or your own `PayStore`'],
+  ['PAY017', 'error', '`@weft-js/pay/server` or `/drizzle` imported in client code', 'Import them in a server module; the client gets `@weft-js/pay`'],
+  ['PAY018', 'error', '`src/pay.server.ts` with no `pay.rail` provider', 'Add a rail to `plugins`: `weft add pay-stripe`'],
+  ['PAY031', 'error', 'A live key in a test', '`fakePay` from `@weft-js/pay/test`'],
+].map(([code, severity, catches, fix]) => ({ code, severity, catches, fix }))
+
+export const pay = definePlugin({
+  name: '@weft-js/pay',
+  version: '0.1.0',
+  weft: '*',
+  namespace: 'PAY',
+  permissions: {},
+  contribute: () => ({
+    provides: [provide(extension, { key: 'pay', sides: { server: { module: '@weft-js/pay/server', export: 'extension' } } })],
+    diagnostics,
+    check: { include: ['src/**/*.{ts,tsx,js,jsx,mts,mjs}', 'test/**/*.{ts,tsx,js,mjs}', 'weft.config.*'], run: ctx => import('./src/checks.mjs').then(c => c.run(ctx)) },
+    docs: { topic: 'pay', summary: 'Payments: products, checkout, entitlements, webhooks, fakePay, another provider; PAY-codes', file: new URL('./docs/pay.md', import.meta.url).pathname },
+    setup,
+    agents: { title: 'Payments', text: 'Products are in `src/pay/catalog.ts`, in minor units. `checkout` and `entitlements` are in `src/server/pay.ts`. App code never names a rail or a price id, and `checkout` grants nothing: a verified webhook does. Enforce on the server, with `requires: [...]` or `await ctx.entitlements.has(...)`: a check only on the client protects nothing. Test with `fakePay` from `@weft-js/pay/test`. `weft docs pay`.' },
+    catalog: [
+      { name: 'product', import: '@weft-js/pay', summary: 'One thing you sell, in integer minor units' },
+      { name: 'price', import: '@weft-js/pay', summary: "A product's price, formatted for the reader" },
+      { name: 'definePay', import: '@weft-js/pay/server', summary: 'The ledger: src/pay.server.ts default-exports it' },
+      { name: 'fakePay', import: '@weft-js/pay/test', summary: 'A rail for tests: renewals, refunds and disputes on the clock' },
+    ],
+    map: [{ want: 'Sell something', call: 'add it to `src/pay/catalog.ts`, then `checkout({ product, plan })`', have: '`weft docs pay`' }],
+  }),
+})
+
+export default pay

package/src/checks.mjs

@@ -0,0 +1,230 @@
+// The PAY-codes (research 10 §7, 37): what `weft check` reports for this plugin, through the `check` hook any plugin has.
+// `run` gets the project through `ctx` and returns findings, and weft does the rest: spans, fixes, `weft fix`, `--json`.
+// TypeScript is loaded here, not in plugin.mjs, so a config load doesn't pay for it. A regex decides which files parse.
+//
+// The client is everything in `src` that isn't a server module. `src/pay/catalog.ts` is client code on purpose: it holds
+// names and amounts, which is why a rail's ids don't go there (PAY012).
+
+import ts from 'typescript'
+
+const isServer = rel => rel.startsWith('src/server/') || /\.server\.[cm]?[jt]sx?$/.test(rel)
+
+const KEY = /\b(?:(?:sk|rk)_(?:live|test)_[A-Za-z0-9]{6,}|whsec_[A-Za-z0-9]{6,})\b/g
+const PLACEHOLDER = /placeholder|example|your|xxxx/i
+const SERVER_ENV = /\b(?:process\.env|import\.meta\.env)\.\w*STRIPE_(?:SECRET_KEY|WEBHOOK_SECRET|RESTRICTED_KEY)\b/g
+const RAIL_ID = /^(?:price|prod|plink)_[A-Za-z0-9]{8,}$/
+const STRIPE_EVENT = /['"`](?:checkout\.session\.completed|customer\.subscription\.\w+|invoice\.paid|invoice\.payment_\w+|payment_intent\.succeeded|charge\.refunded)['"`]/
+const VERIFIED = /constructEvent|verifyWebhook|\.webhook\(|\.verify\(|stripe-signature/i
+const SECRET_OPTION = /\bstripe\(\s*\{[^}]*\b(?:secretKey|webhookSecret)\b/
+const PAID_NAME = /pro\b|paid|premium|entitle|purchas|subscri|unlock|grant|isPro|hasAccess/i
+const MONEY = /[$€£¥]\s?\d/
+
+const parse = (rel, text) => ts.createSourceFile(rel, text, ts.ScriptTarget.Latest, true, /\.[jt]sx$/.test(rel) ? ts.ScriptKind.TSX : ts.ScriptKind.TS)
+
+function walk(node, visit) {
+  visit(node)
+  ts.forEachChild(node, c => walk(c, visit))
+}
+
+const at = (sf, rel, node) => ({ file: rel, start: node.getStart(sf), end: node.getEnd() })
+const spanOf = (rel, index, length) => ({ file: rel, start: index, end: index + length })
+const isTest = rel => /\.(test|spec)\.[cm]?[jt]sx?$/.test(rel) || rel.startsWith('test/')
+const prop = (object, name) => object.properties.find(p => p.name?.getText() === name)
+const callee = node => (ts.isCallExpression(node) ? node.expression.getText() : '')
+const isFunction = n => ts.isArrowFunction(n) || ts.isFunctionExpression(n) || ts.isFunctionDeclaration(n) || ts.isMethodDeclaration(n)
+
+function enclosing(node) {
+  for (let n = node.parent; n; n = n.parent) if (isFunction(n)) return n
+  return undefined
+}
+
+/** PAY003: a key in the source, or a server secret read where the client can reach it. */
+function secrets(rel, text, server, out) {
+  for (const m of text.matchAll(KEY)) {
+    if (PLACEHOLDER.test(m[0])) continue
+    out.push(({ code: 'PAY003', ...spanOf(rel, m.index, m[0].length), why: `A key is in the source: \`${m[0].slice(0, 8)}…\`. Anyone who can read this can charge or refund as you, and it stays in git after you delete it.` }))
+  }
+  if (!server) for (const m of text.matchAll(SERVER_ENV)) out.push(({ code: 'PAY003', ...spanOf(rel, m.index, m[0].length), why: `\`${m[0]}\` is read in client code: a build inlines it, or it is undefined there.` }))
+}
+
+/** PAY012: a rail's own id where the client bundle gets it. */
+function railIds(rel, sf, out) {
+  walk(sf, n => {
+    if ((ts.isStringLiteral(n) || ts.isNoSubstitutionTemplateLiteral(n)) && RAIL_ID.test(n.text)) out.push(({ code: 'PAY012', ...at(sf, rel, n), why: `\`${n.text}\` is a rail's id in client code: the page now names a rail, and a client that sends a price picks its own.` }))
+  })
+}
+
+/** PAY008: a float or a bare number in `product({ … })`, with the integer as an edit for two-decimal currencies. */
+function money(rel, sf, out) {
+  const amounts = (object, path) => {
+    for (const p of object.properties) {
+      if (!ts.isPropertyAssignment(p) || !/^[a-z]{3}$/.test(p.name.getText())) continue
+      const v = p.initializer
+      if (!ts.isNumericLiteral(v) || Number.isInteger(Number(v.text))) continue
+      const fixed = String(Math.round(Number(v.text) * 100))
+      const place = at(sf, rel, v)
+      out.push(({ code: 'PAY008', ...place, why: `\`${path}.${p.name.getText()}\` is ${v.text}: money is whole minor units, and a float rounds differently on each rail.`, fix: { description: `Write ${fixed}, assuming a currency with two decimals`, safe: false, edits: [{ start: place.start, end: place.end, text: fixed }] } }))
+    }
+  }
+  walk(sf, n => {
+    if (callee(n) !== 'product' || !n.arguments[0] || !ts.isObjectLiteralExpression(n.arguments[0])) return
+    const def = n.arguments[0]
+    const id = prop(def, 'id')?.initializer?.text ?? 'product'
+    const price = prop(def, 'price')?.initializer
+    if (price && ts.isNumericLiteral(price)) out.push(({ code: 'PAY008', ...at(sf, rel, price), why: `\`${id}\`'s price has no currency: ${price.text} of what?` }))
+    if (price && ts.isObjectLiteralExpression(price)) amounts(price, `${id}.price`)
+    const plans = prop(def, 'plans')?.initializer
+    if (plans && ts.isObjectLiteralExpression(plans)) for (const p of plans.properties) if (ts.isPropertyAssignment(p) && ts.isObjectLiteralExpression(p.initializer)) amounts(p.initializer, `${id}.${p.name.getText()}`)
+  })
+}
+
+/** PAY004: paid state written on the client on the strength of `checkout()` returning. */
+function clientGrants(rel, sf, out) {
+  const writes = (scope, from) => {
+    walk(scope, n => {
+      if (n.getStart(sf) < from) return
+      const target = ts.isBinaryExpression(n) && n.operatorToken.kind === ts.SyntaxKind.EqualsToken ? n.left.getText() : ts.isCallExpression(n) && /(^|\.)(setItem|set)$/.test(callee(n)) ? `${callee(n)} ${n.arguments[0]?.getText() ?? ''}` : undefined
+      if (target && PAID_NAME.test(target)) out.push(({ code: 'PAY004', ...at(sf, rel, n), why: `\`${n.getText().slice(0, 60)}\` follows \`checkout()\`, which only opens the rail's page. Nobody has paid yet, and a refund would never undo this.` }))
+    })
+  }
+  walk(sf, n => {
+    if (callee(n) !== 'checkout') return
+    const up = n.parent
+    if (ts.isAwaitExpression(up)) {
+      const fn = enclosing(n)
+      if (fn?.body) writes(fn.body, n.getEnd())
+    }
+    if (ts.isPropertyAccessExpression(up) && up.name.text === 'then' && ts.isCallExpression(up.parent) && up.parent.arguments[0]) writes(up.parent.arguments[0], 0)
+  })
+}
+
+/** PAY005: a price typed into the page beside something sold. */
+function hardcoded(rel, sf, out) {
+  walk(sf, n => {
+    if (ts.isJsxText(n) && MONEY.test(n.text)) out.push(({ code: 'PAY005', ...at(sf, rel, n), why: `\`${n.text.trim().slice(0, 40)}\` is a price typed by hand: it drifts from what \`checkout\` charges.` }))
+  })
+}
+
+/** PAY015: `ctx.entitlements.has()` used as if it were a boolean. A promise is truthy, so this lets everyone in. */
+function unawaited(rel, sf, out) {
+  walk(sf, n => {
+    if (!/(^|\.)entitlements\.has$/.test(callee(n))) return
+    const up = n.parent
+    const tested = (ts.isIfStatement(up) && up.expression === n) || (ts.isConditionalExpression(up) && up.condition === n) || (ts.isPrefixUnaryExpression(up) && up.operator === ts.SyntaxKind.ExclamationToken) || (ts.isBinaryExpression(up) && [ts.SyntaxKind.AmpersandAmpersandToken, ts.SyntaxKind.BarBarToken].includes(up.operatorToken.kind))
+    if (!tested) return
+    const place = at(sf, rel, n)
+    const fn = enclosing(n)
+    const async = fn?.modifiers?.some(m => m.kind === ts.SyntaxKind.AsyncKeyword)
+    const edit = async && { fix: { description: 'Await it', safe: true, edits: [{ start: place.start, end: place.start, text: 'await ' }] } }
+    out.push(({ code: 'PAY015', ...place, why: `\`${n.getText()}\` isn't awaited: it is a promise, which is always truthy, so the check passes for everyone.`, ...edit }))
+  })
+}
+
+/** PAY010: a buyer no one has signed in. */
+function anonymous(rel, sf, out) {
+  walk(sf, n => {
+    if (callee(n) !== 'mutation' || !n.arguments[0] || !ts.isObjectLiteralExpression(n.arguments[0])) return
+    const def = n.arguments[0]
+    if (/\.checkout\(\s*ctx\b/.test(def.getText()) && !prop(def, 'auth')) out.push(({ code: 'PAY010', ...at(sf, rel, n), why: 'This mutation opens a checkout with no `auth: \'user\'`: a purchase with no owner can\'t be restored or granted.' }))
+  })
+}
+
+/** PAY011: a webhook that believes what it's sent. */
+function webhooks(rel, text, sf, out) {
+  if (STRIPE_EVENT.test(text) && /\.json\(\)|JSON\.parse/.test(text) && !VERIFIED.test(text)) {
+    const m = STRIPE_EVENT.exec(text)
+    out.push(({ code: 'PAY011', ...spanOf(rel, m.index, m[0].length), why: `This handles ${m[0]} without checking a signature: anyone who finds the URL can POST themselves a purchase.` }))
+  }
+  if (!/\bPayRail\b/.test(text)) return
+  walk(sf, n => {
+    if (!((ts.isMethodDeclaration(n) || ts.isPropertyAssignment(n)) && n.name.getText() === 'verify')) return
+    const fn = ts.isPropertyAssignment(n) ? n.initializer : n
+    if (!/\bheaders\b/.test(fn.getText())) out.push(({ code: 'PAY011', ...at(sf, rel, n.name), why: "This rail's `verify` never reads `headers`, so it can't be checking a signature." }))
+  })
+}
+
+/** Every id the server really enforces: `requires` and awaited `entitlements.has`, in server modules and route `load`s. */
+function enforced(rel, sf, ids) {
+  walk(sf, n => {
+    if (/(^|\.)entitlements\.has$/.test(callee(n)) && n.arguments[0]?.text) ids.add(n.arguments[0].text)
+    if (ts.isPropertyAssignment(n) && n.name.getText() === 'requires' && ts.isArrayLiteralExpression(n.initializer)) for (const e of n.initializer.elements) if (e.text) ids.add(e.text)
+  })
+}
+
+/** Client reads of `entitlements`: `mine.value?.includes('pro')`, wherever the file got that list from. */
+function clientReads(rel, sf, reads) {
+  if (!/\bentitlements\b/.test(sf.text)) return
+  walk(sf, n => {
+    if (!ts.isCallExpression(n) || !/\.(includes|has)$/.test(n.expression.getText()) || !n.arguments[0]?.text) return
+    reads.push({ rel, sf, node: n, id: n.arguments[0].text })
+  })
+}
+
+/** A server entry in the client graph: it would carry the ledger, and it can't run there. */
+function serverImports(rel, text, out) {
+  for (const m of text.matchAll(/from\s+['"](@weft-js\/pay\/(?:server|drizzle))['"]/g)) out.push({ code: 'PAY017', ...spanOf(rel, m.index, m[0].length), why: `\`${m[1]}\` is imported in client code: the ledger runs on the server only.` })
+}
+
+/** @param {import('@weft-js/core/plugin').CheckContext} ctx */
+export function run(ctx) {
+  const out = []
+  const rels = ctx.files.filter(r => r.startsWith('src/') && !isTest(r) && !r.endsWith('.d.ts'))
+  const rails = Object.entries(ctx.slots['pay.rail'] ?? {}).filter(([, name]) => name)
+  const payFile = ['ts', 'mts', 'js', 'mjs'].map(x => `src/pay.server.${x}`).find(rel => ctx.exists(rel))
+  const known = new Set()
+  const reads = []
+
+  for (const rel of rels) {
+    const text = ctx.read(rel)
+    const server = isServer(rel)
+    secrets(rel, text, server, out)
+    if (!server) serverImports(rel, text, out)
+    if (!(/@weft-js\/pay|entitlements|requires:|\bcheckout\b|\bproduct\(|PayRail|price_|prod_|plink_/.test(text) || STRIPE_EVENT.test(text))) continue
+    const sf = parse(rel, text)
+    webhooks(rel, text, sf, out)
+    money(rel, sf, out)
+    unawaited(rel, sf, out)
+    enforced(rel, sf, known)
+    if (server) anonymous(rel, sf, out)
+    else {
+      railIds(rel, sf, out)
+      if (/\bcheckout\b/.test(text)) {
+        clientGrants(rel, sf, out)
+        hardcoded(rel, sf, out)
+      }
+      clientReads(rel, sf, reads)
+    }
+  }
+
+  for (const r of reads) {
+    if (known.has(r.id)) continue
+    out.push({ code: 'PAY013', ...at(r.sf, r.rel, r.node), why: `\`${r.id}\` is checked only on the client: no \`requires\` or \`ctx.entitlements.has\` on the server names it, so a request made by hand gets the same thing as a paying user.`, help: `Add \`requires: ['${r.id}']\` to the query or mutation it protects, or check \`await ctx.entitlements.has('${r.id}')\` in the route's \`load\`` })
+  }
+
+  for (const rel of ctx.files.filter(r => r.startsWith('weft.config.'))) {
+    const text = ctx.read(rel)
+    secrets(rel, text, true, out)
+    const m = SECRET_OPTION.exec(text)
+    if (m) out.push({ code: 'PAY003', ...spanOf(rel, m.index, m[0].length), why: 'Plugin options are written into `.weft/slots/`, so a key given here sits in a generated file.' })
+  }
+
+  for (const rel of ctx.files.filter(isTest)) {
+    const text = ctx.read(rel)
+    for (const m of text.matchAll(/\b(?:sk|rk)_live_\w+/g)) out.push({ code: 'PAY031', ...spanOf(rel, m.index, m[0].length), why: 'A live key in a test: it charges real cards, and it is now in git.' })
+  }
+
+  const config = ctx.files.find(r => r.startsWith('weft.config.')) ?? 'weft.config.ts'
+  if (!payFile) {
+    out.push({ code: 'PAY014', file: config, why: 'This plugin is in `plugins`, but there is no `src/pay.server.ts`: no webhook is mounted, so a payment would grant nothing.' })
+    return out
+  }
+  if (!rails.length) out.push({ code: 'PAY018', file: payFile, why: '`src/pay.server.ts` needs a `pay.rail` provider, and nothing provides it: every checkout fails.' })
+  const text = ctx.read(payFile)
+  const m = /memoryPayStore\(/.exec(text)
+  if (m) out.push({ code: 'PAY016', ...spanOf(payFile, m.index, m[0].length - 1), why: 'The ledger is in memory: purchases are gone on restart, and a production server refuses to start with it.' })
+  if (rails.some(([key]) => key === 'stripe')) {
+    const env = ['.env.example', 'src/env.server.ts'].map(rel => ctx.read(rel)).join('\n')
+    if (!env.includes('STRIPE_WEBHOOK_SECRET')) out.push({ code: 'PAY011', file: payFile, why: 'Nothing declares `STRIPE_WEBHOOK_SECRET`. Without it the rail refuses every webhook, so no purchase ever lands.', help: 'Add `STRIPE_WEBHOOK_SECRET` to `.env.example` and `src/env.server.ts`' })
+  }
+  return out
+}

package/src/drizzle.ts

@@ -0,0 +1,38 @@
+// The ledger on a Drizzle client (research 10 §3): `purchases` and `pay_events`, in the app's schema so they're
+// inspectable and joinable like any other table. An entry of its own, so an app on another data layer needs no drizzle-orm.
+
+import { eq, getTableName, type AnyColumn, type SQL, type Table } from 'drizzle-orm'
+import type { DbHandle } from '@weft-js/start/db/core'
+import type { PayStore, Purchase } from './server'
+
+/** A Drizzle client as far as the ledger uses one: the dialects' builders share no type, so this names what they have in common. */
+interface LedgerClient {
+  select(fields?: Record<string, AnyColumn>): { from(table: Table): { where(on: SQL | undefined): Promise<Purchase[]> & { limit(n: number): Promise<Purchase[]> } } }
+  insert(table: Table): { values(row: object): Promise<unknown> & {
+    onDuplicateKeyUpdate(update: { set: object }): Promise<unknown>
+    onConflictDoNothing(): Promise<unknown>
+    onConflictDoUpdate(update: { target: AnyColumn; set: object }): Promise<unknown>
+  } }
+}
+
+/** A `PayStore` on the app's Drizzle tables, on Postgres, SQLite or MySQL. */
+export function drizzlePayStore(db: { $weft: DbHandle }, tables: { purchases: Table & { id: AnyColumn; user: AnyColumn }; payEvents: Table & { id: AnyColumn } }): PayStore {
+  const { purchases, payEvents } = tables
+  const client = db as unknown as LedgerClient
+  const mysql = db.$weft.dialect === 'mysql'
+  db.$weft.exempt.add(getTableName(purchases)).add(getTableName(payEvents)) // written by a webhook, not by a server function
+  return {
+    seen: async id => (await client.select({ id: payEvents.id }).from(payEvents).where(eq(payEvents.id, id)).limit(1)).length > 0,
+    async mark(id, at) {
+      const insert = client.insert(payEvents).values({ id, at })
+      await (mysql ? insert.onDuplicateKeyUpdate({ set: { id } }) : insert.onConflictDoNothing())
+    },
+    purchase: async id => (await client.select().from(purchases).where(eq(purchases.id, id)).limit(1))[0] ?? null,
+    async save(row: Purchase) {
+      const { id: _id, ...set } = row
+      const insert = client.insert(purchases).values(row)
+      await (mysql ? insert.onDuplicateKeyUpdate({ set }) : insert.onConflictDoUpdate({ target: purchases.id, set }))
+    },
+    byUser: user => client.select().from(purchases).where(eq(purchases.user, user)),
+  }
+}