fix: verify payment server-side before redeeming pay codes (C1)

[sbddesign]

Security fix: C1 — Paid usernames redeemable without payment (CRITICAL)

redeemPayCode was a publicProcedure that flipped a PENDING pay code to ACTIVE and published its Cloudflare DNS record with no server-side payment verification. The only "control" was a comment claiming the client-side MDK hook useCheckoutSuccess() handled it — but that runs in the attacker's browser.

Exploit: call createPayCode (public, returns payCodeId), then call redeemPayCode({ payCodeId }) directly. Result: a paid-tier username registered for free. Root cause: the MDK checkout was created client-side with a client-supplied amount, so the server never had a checkout id to verify.

Approach

Move checkout creation to the server and verify payment before activating (server-created checkout).

• createPayCode now creates the MDK checkout server-side with a server-owned price (PAY_CODE_PRICE_SATS = 5000), stores the checkout id on the pay code row, and returns the checkoutUrl. If the MDK call fails it cleans up the just-created PENDING row; if the id can't be persisted it fails rather than handing back an unverifiable URL.
• redeemPayCode keeps its { payCodeId } signature but now fetches the stored checkout from MDK and requires it to be paid (PAYMENT_RECEIVED and amountSatsReceived >= 5000) before the DNS transaction. Unpaid → PRECONDITION_FAILED, no DNS published. Verification runs before the transaction so the MDK network call can't blow the transaction timeout.
• The PENDING → ACTIVE flip is now an atomic conditional updateMany — a concurrent redeem loses the row-lock race and gets CONFLICT, preventing a double DNS publish (also fixes H2).
• The outer transaction .catch now preserves typed TRPCErrors instead of masking them as 500s.
• Client (NewPayCodeForm.tsx) drops its own useCheckout() call and the hardcoded price, and just redirects to the server-returned checkoutUrl.
• Added checkoutId String? @unique to PayCode; new src/server/mdk.ts server helper (createMdkCheckout / getMdkCheckout / a pure, unit-tested isCheckoutPaid predicate) mirroring the existing ws-bufferutil bundling guard; deleted the dead checkPayment procedure; updated README/AGENTS.

Files

• src/server/mdk.ts — server-side MDK create/verify + pure paid predicate
• src/server/api/routers/payCode.ts — createPayCode, redeemPayCode, delete checkPayment
• prisma/schema.prisma — checkoutId column
• src/lib/util/constant.ts — PAY_CODE_PRICE_SATS
• src/app/features/NewPayCodeForm.tsx — redirect to server checkout URL
• src/server/mdk.test.ts — predicate unit tests
• package.json / pnpm-lock.yaml — @moneydevkit/core promoted to a direct dependency (was transitive-only; getCheckout/createCheckout are only on its root export)
• README.md, AGENTS.md — docs

Verification

• ✅ tsc --noEmit — clean (validates new code against the regenerated Prisma client + MDK types)
• ✅ next build — compiles, types valid, 14/14 pages generated, and /api/trpc bundles @moneydevkit/core with no module-not-found or native-binary errors (confirms the bundling hazard is handled)
• ✅ jest — 32/32 pass (25 existing + 7 new predicate tests, incl. underpayment and fail-closed cases)
• MDK API assumptions verified against the installed @moneydevkit/core@0.18.0 (getCheckout/createCheckout signatures, Result shape, invoice.amountSatsReceived; predicate matches MDK's own isCheckoutPaidStatus plus an amount floor)

Not verifiable in CI without secrets

• Migration: run pnpm db:push to add the checkoutId column (Prisma Client already regenerated with the field).
• Live exploit reproduction / happy path need real MDK_ACCESS_TOKEN/MDK_MNEMONIC + CF_TOKEN. After the fix, the direct redeemPayCode exploit returns PRECONDITION_FAILED and publishes no DNS record.

Note for reviewers

Legacy PENDING rows with a null checkoutId now fail redemption with a "create it again" message (fail-closed — payment can't be proven). Re-creating is free and the name stays unclaimed, since only ACTIVE rows reserve a name.

🤖 Generated with Claude Code

---

Review round 2 — changes after adversarial review

Three follow-up commits address the review. This now contains a breaking change.

1. Retire POST /record (breaking)

The review's main blocker: this PR locked the front door while /record left an equivalent side door open. That route was public, unauthenticated, took a caller-supplied localPart + bolt12, and wrote the TXT record straight to Cloudflare — no payment check, and no database row at all, so the name did not even register as taken.

Per the product decision, it is removed rather than carved out for one wallet. A shared secret shipped inside a public wallet binary is not a control.

• Deleted src/app/record/route.ts. Nothing in this app called it.
• Dropped DOMAIN and CF_DOMAIN_ID from .env.sample — that route was their only consumer.
• Docs updated. The AGENTS.md API reference documented a POST /v2/record path that never existed; it now describes the actual tRPC procedures.

Follow-up needed outside this repo: Zeus still POSTs to https://twelve.cash/record on master and will break when this deploys. Zeus can move to payCode.createRandomPayCode for a free name, or the paid create/redeem flow for a chosen one.

2. Make custom name reservations atomic

Only ACTIVE rows counted as taking a name, so two callers could each create a PENDING row for the same username, each pay their own 5,000-sat checkout, and only the first to redeem would get it. The second buyer paid and got nothing.

• A partial unique index on (lower(userName), lower(domain)) WHERE status IN ('PENDING','ACTIVE') serializes racing inserts. The preflight findFirst is kept only for a fast, friendly CONFLICT and is explicitly not treated as a lock; a P2002 from the index maps to the same CONFLICT.
• Reservations are a lease, not a permanent hold. reservationExpiresAt starts as a short window covering the MDK call, then aligns to the checkout's own expiresAt plus a grace period for users who paid but did not immediately return to the success page. A stale lease is expired in the same transaction that claims the name, so an abandoned checkout cannot hold a name hostage.
• createRandomPayCode honors live reservations and retries a P2002 with a fresh name instead of surfacing a 500.
• redeemPayCode also checks that the checkout MDK returned is the one bound to this row before trusting its paid status.

3. Explicit migration instead of "run db:push manually"

Prisma 5 cannot express a partial expression index, and this database predates a checked-in migration history, so the index ships as an idempotent SQL expand migration rather than an invented prisma/migrations baseline.

pnpm db:manual-migrations   # run BEFORE deploying this code

It refuses to guess: it aborts if live rows already collide case-insensitively, or if a partially deployed row has a checkout id but no lease. See prisma/manual-migrations/README.md. Local dev needs it too — db:push alone leaves the index missing and the reservation non-atomic.

4. Fix the failing Vercel check

The red check was a real bug, not flaky infra:

./src/server/mdk.ts
43:5  Error: Definition for rule '@typescript-eslint/no-var-requires' was not found.

The lazy require() carried an eslint-disable-next-line for a rule this repo never loads — .eslintrc.json extends only next/core-web-vitals. ESLint errors on the disable comment itself and next build exits 1. Removed the comment.

Note for anyone verifying locally: next.config.mjs sets eslint: { ignoreDuringBuilds: !process.env.CI }, so a plain pnpm build skips linting entirely and cannot reproduce this. Use CI=1 pnpm build.

Verification (at 0d7c6c1, clean worktree)

• ✅ jest — 39/39 pass
• ✅ tsc --noEmit — clean
• ✅ prisma validate — schema valid
• ✅ CI=1 pnpm build — lint ran (warnings only), 13/13 pages. 13 not 14 because /record is gone.
• ✅ git diff --check — clean

New tests sit at the router boundary — reservation races, checkout binding, unpaid redemption — not just the pure predicate. Each was checked by mutation: disabling the payment check, the checkout-id check, or the P2002 handling each fails exactly one test.

Still not verifiable without secrets

Live exploit reproduction and the happy path need real MDK_ACCESS_TOKEN/MDK_MNEMONIC + CF_TOKEN.

Known, deliberately out of scope

Cloudflare writes still happen inside the database transaction, so Cloudflare can succeed while the commit fails. That is pre-existing and unchanged here, but paid fulfillment makes recovery matter more — worth its own issue.

---

Review round 3 — never resell a name whose checkout may still be paid

Round 2's reservation lease had two ways for a buyer to pay and get nothing.

An expired lease did not mean the name was free. The release path expired any PENDING row past its lease without asking whether its bound checkout had been paid. A buyer who paid and came back after the grace window lost the name and the 5,000 sats. The 24-hour grace was also wrong in the other direction — a free hold anyone could renew by calling the public createPayCode again.

The grace period is gone. A lease now ends exactly at the checkout's own expiry, and releasing an expired reservation requires MDK to confirm the checkout is dead:

• Release only on the terminal EXPIRED status with the full-payment predicate false. "Not paid yet" is not "cannot be paid" — UNCONFIRMED, CONFIRMED and PENDING_PAYMENT are all live states whose invoice may still settle, and our clock running ahead of MDK's is not authority to kill a checkout. Paid, live, or unverifiable all keep the name reserved.
• Verify the returned checkout id matches the row before trusting its status — the same binding rule redemption already applies.
• MDK failure fails closed. The reservation stands and this caller is refused. Refusing a create is recoverable; reselling a paid name is not.

The release write re-asserts everything it judged. The sweep runs outside the transaction (network calls must not hold one open), so each candidate carries its observed state and the release requires all of it — status, lease, and the observed checkoutId including null. Expiring on row id alone let a slow createPayCode finalize the row with a real checkout in the gap and then receive a payable URL for a reservation someone else had just expired. A zero-count release is not treated as success; the partial unique index arbitrates.

Checkout finalization is likewise conditional on the row still being PENDING with its original lease, so a caller never gets a payable URL for a reservation that no longer exists.

createRandomPayCode no longer releases anything. It cannot distinguish a paid reservation from an abandoned one without an MDK round trip and does not need to — it just generates another name.

The migration's legacy sweep now requires both checkoutId and reservationExpiresAt to be NULL. Matching checkoutId alone also matched the live interim state of a createPayCode waiting on MDK, so a rerun against a live database expired an in-flight reservation.

Verified against a disposable PostgreSQL 16

Scenario	Result
Genuine legacy row (both fields NULL)	expired ✅
In-flight row (lease set, checkoutId NULL)	untouched, first run and rerun ✅
Paid reservation	untouched ✅
Case-insensitive collision on a live name	rejected by PayCode_live_name_key ✅
Same name after the live row is EXPIRED	insert allowed ✅
prisma db push afterwards	index preserved ✅

The old predicate was confirmed broken on the same database before the fix — it selected both in-flight rows.

Verification at afd639d (clean worktree)

• ✅ jest — 55/55
• ✅ tsc --noEmit, git diff --check
• ✅ CI=1 pnpm build — lint ran, 13/13 pages, only the four pre-existing React Hook warnings

Mutation-checked: a status-only paid predicate, releasing on merely-not-paid, releasing without re-asserting observed state, and unconditional finalization each fail tests. Note the paid-reservation path fails closed through more than one branch, so removing any single one still refuses — the predicate's own guard is pinned by a unit test rather than the router test.

Known and deliberately out of scope

A caller can still hold a name for free for the checkout's own lifetime. That is inherent to any reserve-then-pay flow; the real fix is rate-limiting the public unauthenticated createPayCode, which is separate work. Likewise, a checkout that never reaches a terminal state holds its name until it does — the safe direction, but it argues for a reconciliation job.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
twelvecash	Ready	Preview	Aug 9, 2026 6:01pm