credentagent.grants: approve a spending limit once, spend while the human is away (#104)

[dzuluaga]

In plain terms

You're heads-down for a week and want your AI agent to keep you in coffee — without tapping
"approve" for every cup, and without giving the agent a blank check. This PR ships that:
the human approves one spending limit ("up to $15 per purchase, $50 total, at this café")
on a link the agent hands them, and the agent then buys against it while they're away —
like a prepaid card with rules. It's the second half of the orders work that merged in #98:
orders need the human every time; a grant needs them once.

const grant = await credentagent.grants.create({ merchant: "corner-cafe", budget: usd.dollars(50), perSpend: usd.dollars(15), policy: [] });
sendToUser(grant.approveUrl);                    // the ONE human step

// later, unattended:
const g = await credentagent.grants.retrieve(grantId);
const s = await g.spend({ idempotencyKey: purchaseId, items: [{ sku: "coffee" }] });
// → { ok: true, remaining } · { ok: false, code: "budget-exceeded" | "per-spend-exceeded" | "revoked" | … }

What you're approving

• New code only — nothing existing changes. credentagent.grants lands alongside orders;
  no current caller has to touch anything.
• The four decisions from issue Grants — approve a spending limit once, let the agent buy against it later (spec 009, human-not-present half) #104, implemented as accepted:
  1. a network retry with the same idempotencyKey is answered once-charged (replayed: true) — no double-buying;
  2. Money is back and wired (usd.dollars(50)) — the caller never sees a raw number, so the unit confusion from the orders.serve(app): the human-present checkout, wired in one call (#97) #98 review can't recur;
  3. spends run in-process on your server — no signing key is handed to the agent over the network;
  4. the existing, already-merged checking engine is reused, not duplicated (the draft-PR cleanup is a separate follow-up).
• Worst case if it's wrong: an unattended purchase mis-refuses or mis-completes — but no real
  money moves anywhere (trust level server-issued-demo, stated on the page and in the types), and
  the caps/refusals are pinned by tests that go red when their checks are deleted (verified, listed below).
• What's fenced, honestly: a grant whose policy needs a credential (say, proof of being 21+)
  renders its requirements but cannot be approved from the demo button (403) — wallet-ceremony
  approval is the next increment. And age-restricted items never complete on autopilot — a
  spend on wine refuses with "a live human must approve this" no matter what the grant allows.

How to test

npm run build && npm test                        # gate 376 + storefront 86 = 462 pass
node examples/grants-preapproved/smoke.mjs       # → ALL SMOKE CHECKS PASSED (13 checks, no browser)
node examples/grants-preapproved/server.mjs      # then:
#   curl -X POST localhost:4000/setup-coffee-fund                → { id, approveUrl }
#   open the approveUrl → "Approve this limit"                   (the one human step)
#   curl -X POST localhost:4000/buy/<id> -H 'content-type: application/json' -d '{"purchaseId":"p1","sku":"coffee"}'
#   curl -X DELETE localhost:4000/grants/<id>                    → revoked; next buy refuses

---

For reviewers — the detail

Shape: grants.ts + grants-serve.ts mirror orders.ts + orders-serve.ts (spec 009's
two symmetric resources). The grant is the durable authority (status pending → authorized | denied, * → revoked); the AP2 Intent Mandate is the artifact it carries
(grant.intentMandate), dev-sealed at approve time — the wallet-custody increment swaps its
internals to real key-signing without changing this surface.

Engine reuse (#104 decision 4): spends run through the already-merged delegated-draw seams —
sealIntent / signDraw / completeOrder / the revocation + committed-draw ledger. The shared
completion seam is what refuses age-restricted and custom-gated items on autopilot (step-up) —
this PR pins that from the grants surface rather than re-implementing it. Spend completions route
through orders._complete, so order.settled and the #102 webhook fan-out fire for delegated
spends exactly as for human-present orders.

One deliberate deviation from the plan: rails-backed approval for policy-gated grants was
descoped (recorded in docs/superpowers/plans/2026-07-23-grants.md). A second mountCeremony
would collide with orders' rail routes on the same app; the composite mount belongs to the
wallet-custody increment. Until then the gated approve path is fail-closed (403) and bypass-tested.

Key custody note: unlike DelegatedGate (in-process, non-extractable key), a grant must
rehydrate in a worker process, so the delegate private key is stored in the grant store
(DelegatePrivateJwk, documented) — exactly what server-issued-demo claims. Inject a shared
grantStore / revocationStore for multi-instance; in-memory defaults otherwise.

Bypass tests — each verified RED with its control deleted:

• pending grant refuses to spend (status gate deleted → red)
• same-key retry replays once-charged (replay pre-read deleted → red)
• revoke: spend refusal + status (both writes deleted → red) · never-resurrect (_authorize pending-only guard deleted → red)
• policy-gated grant refused on demo approve (isGated fence deleted → red)
• budget / per-spend / age-step-up pinned end-to-end (engine checks, re-asserted from this surface)

Files: new money.ts (+test), grants.ts, grants-serve.ts (+tests), examples/grants-preapproved/;
modified client.ts (opts catalog/grantStore/revocationStore, grants wiring), types.ts,
index.ts, delegated.ts (exports buildCatalog — no behavior change), orders-serve.ts (exports
isGated — no behavior change), READMEs.

Closes #104 · under #97 · epic #12 · spec 009

🤖 Generated with Claude Code

https://claude.ai/code/session_014MphtihdwkALRVgLhhW3dm

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
credentagent-demo	Ready	Preview, Comment	Jul 24, 2026 12:36pm

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 19d8078c8a

ℹ️ 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".

[chatgpt-codex-connector]

Isolate grant replay records from ordinary orders

completedStore is shared with orders, while orders.create() permits caller-supplied IDs. If an ordinary completed order has an ID equal to ${grant.id}-${idempotencyKey}, this pre-read treats it as a completed grant spend and returns ok: true, replayed: true without creating a draw or reducing the grant ledger. Use a grant-specific completion namespace/store or validate that the stored completion is a delegated draw for this grant before accepting it as a replay.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Keep grant bounds in minor units during spend checks

This converts the cent-exact public budget to a binary floating-point dollar amount, and catalog prices use the same representation. For example, with budget/perSpend of $0.30 and a catalog item priced at $0.10, the third valid spend reaches 0.30000000000000004; checkDraw and commitDraw compare that value directly to 0.3 and reject it as over-total. Preserve integer minor units (or normalize every catalog total and ledger comparison) at this seam so exact-budget purchases are not spuriously refused.

Useful? React with 👍 / 👎.

[dzuluaga]

Review addressed (a7af2c7)

Ran a multi-agent, ergonomics-first review over this branch; 29 findings survived adversarial verification. Fixed the blocking + important tier. Two security bugs I reproduced before fixing (both new in this PR's multi-item spend path):

• Below-cost settlement via quantity. qty: 0.1 of a $40 item settled at $4; a [espresso×1, coffee×−20] cart netted to a hidden $20 discount and committed a draw. Now: spend() validates each quantity as a positive integer → invalid-quantity. Bypass-tested (red when the guard is deleted).
• Lifecycle TOCTOU. revoke() ∥ _authorize() could end authorized-and-spendable (kill switch resurrects), and a concurrent double-approve rebound the ledger to an empty budget (allowed $60 on a $40 grant). Now: a per-grant mutex serializes every lifecycle + spend transition; concurrent same-key spends collapse to one charge with a clean replay (pins the mutex).

Also fixed: integer-cents math end-to-end (no float drift at the Money↔dollars seam; exact-boundary spends pass), replay checked before the lifecycle gates (a settled spend replays even after revoke — history isn't rewritten), same-key/different-items → idempotency-conflict, create() validates budget/perSpend, the ambiguous bare-callable usd(n) is gone (unit always explicit), trustLevel/spend code are closed unions, and the not-found handle never throws. README: runnable snippet, full door (remaining/retryable), a Grants-vs-DelegatedGate chooser, Webhooks promoted to its own section.

Tests: +18 (quantity, exact-boundary money, idempotency, concurrency, denied-terminal, the revoke-ledger mutation gap, not-found). Gate 391 + storefront 86 = 477 pass; all three example smokes pass. Six new controls each verified red when deleted.

Deliberately deferred (unchanged from the plan's recorded scope): rails-backed approval of policy-gated grants (fenced 403), agent-held signing key, real key-signed mandates — all wallet-custody-increment work. Cross-process lifecycle serialization (the mutex is in-process) is noted as a follow-up; cross-process budget safety already rides on the engine's atomic single-use consume.