orders.serve(app): the human-present checkout, wired in one call (#97)

[dzuluaga]

In plain terms

An AI agent that wants to buy something for you — say a bottle of wine — can now do it through
a real, tested checkout, not a throwaway demo. The agent starts the order and gets back a
link; it hands you the link; you open it, prove what's required (being 21+ for the wine) and
pay; the order is marked paid. This PR turns that flow into actual library code you can ship:
credentagent.orders.

The headline is how little you write. Two lines run once at startup (wire the checkout,
subscribe to completion); orders.create() runs per purchase, inside a request handler:

// ── once, at startup ──────────────────────────────────────
credentagent.orders.serve(app);                              // wire the whole checkout onto your app
credentagent.on("order.settled", ({ id }) => fulfill(id));   // fires when ANY order is paid

// ── per purchase — inside a request handler ───────────────
app.post("/buy-wine", async (_req, res) => {
  const { approveUrl } = await credentagent.orders.create({ order, policy });
  res.json({ approveUrl });                                   // hand the link to the human
});

What you're approving

• New code only — nothing existing changes. No one using the SDK has to touch anything; this
  adds credentagent.orders alongside what's already there.
• What ships: a runnable checkout example (examples/orders-checkout/) you can boot and click
  through, plus the library API behind it.
• Worst case if it's wrong: a checkout page or the "order paid" step misbehaves. The one thing
  that must never break — a wine order can't be completed without actually proving you're 21+ — is
  locked down by a test that fails the moment that check is removed (I verified it goes red).
• What stays safe: no real money moves. The trust level is presence-only-demo — the
  cryptography is real, but there's no issuer trust anchor yet, so this is a flow demo, not a safety
  control. And the price is always recomputed on the server, never trusted from the link.

How to test

npm run build && npm test                    # gate: 328 pass · storefront: 86 pass
node examples/orders-checkout/smoke.mjs       # → ALL SMOKE CHECKS PASSED (8/8), no browser needed
node examples/orders-checkout/server.mjs      # boots on http://localhost:4000
#   curl -X POST http://localhost:4000/buy-wine   → { id, approveUrl }
#   open the approveUrl in a browser             → the checkout page (wine + a 21+ gate)
#   curl http://localhost:4000/orders/<id>       → { ok: true } once it settles

---

For reviewers — the detail

Graduates the orders prototype from #95 (the two demo programs that stood in for the API) into
library code, per #97 (which is a sub-issue of epic #12 — Human-Not-Present delegation). Grants
(the human-not-present half) is the next increment; this PR is the human-present checkout only.

The commits, additive (plus review-round fixes — awaited create() persistence, an idempotent demo place path, dollar amounts everywhere, and the unwired Money helper removed):

1. credentagent.orders.* — await orders.create({ order, policy }) → { id, approveUrl, manifest } (async: it awaits persistence before handing out the link); orders.retrieve(id) →
   the one result door (ok | pending + approveUrl | code); on("order.settled") —
   the in-process completion event.
2. orders.serve(app) — binds the existing, proven pieces (mountCeremony for the rails,
   completeOrder for the shared fail-closed completion, renderRequirements for the one checkout
   page) over the created-order store. There is no second enforcement surface — it reuses the
   same completion path every other rail uses.
3. The runnable example + README/API-surface docs.

Files: orders.ts, orders-serve.ts (new); client.ts, types.ts, index.ts
(wiring/exports); orders.test.ts, orders-serve.test.ts (new); examples/orders-checkout/.

Security invariants held (spelled out):

• docs+ci: ROADMAP, LICENSE, deployment guide, gated Claude review workflow #2 — never trust the order token. The stored order (written server-side by orders.create) is
  the price + age authority; the catalog re-derives amount and age threshold from the stored
  lines, never from the link.
• feat(attesto-gate): signed Cart Mandate (ap2.CartMandate) — core + enforcement #1 — enforce gates on every completion path. A gated order (age / payment) completes only
  through the fail-closed wallet rails. The instant-demo "Complete purchase" path is refused (403)
  for gated orders, server-side — hiding the button is not enforcement. This is the load-bearing
  bypass test in orders-serve.test.ts (proven RED when the guard is removed).
• example: gate-any-action — identity-first, non-commerce gating (no checkout) #4 — per-order state. Both order stores are keyed by order id; completing one never unlocks
  another (a dedicated test).
• Add Claude Code GitHub Workflow #5 — explicit positive claims. Enforced by the existing gates the rails already run.

Honesty: trust_level is presence-only-demo throughout — no overclaim; the instant-demo
completion is a convenience for ungated orders only, so the flow is clickable without a wallet.

Tests: orders.test.ts (6) + orders-serve.test.ts (8) — each security test verified to fail
when its control is deleted. Full suite green: gate 326, storefront 86.

Refs #97 · epic #12 · design #95 (spec 009-ap2-mandate-chain-dx)

🤖 Generated with Claude Code

https://claude.ai/code/session_01Harfquzhqg5SCCURyYRbHD

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
credentagent-demo	Ready	Preview, Comment	Jul 23, 2026 4:35pm

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e2b7e7bc00

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[TheBlackBit]

LGTM