Add CTX spend-api pubkey auth prototype

[j0ntz]

Technical Design Document

ctx-spend-pubkey-auth.md

CHANGELOG

Does this branch warrant an entry to the CHANGELOG?

• Yes
• No

Dependencies

none

Description

Asana: https://app.asana.com/0/1215088146871429/1216403654258326

CTX published a reference script for an anonymous secp256k1 register/login protocol against their spend-api (CTX-com/spend-api-pubkey-auth-demo). This is a prototype client for that protocol, wired into the existing EdgeSpend gift card plugin.

GET /me against CTX returns gift-card-scoped permissions (giftcard:create, giftcard:list, giftcard:redeem, merchant:list) and GET /merchants returns a 118-entry brand catalog, so CTX is a competing provider for what the Phaze plugin already does. The client is added alongside Phaze; the shipping purchase flow is untouched.

The design doc committed in this PR covers the protocol, the decisions, and the two places the reference script's crypto could not be ported verbatim: src/docs/ctx-spend-pubkey-auth.md.

What is here:

• ctxSpendPurchase.ts plus createGiftCard/getGiftCard — ordering a card and paying for it. POST /gift-cards returns the card already carrying a single-use payment address and a crypto amount quoted at rate; the client maps CTX's chain-and-network pair to an Edge currency plugin, converts the quote to native units with biggystring, and hands it to the ordinary send scene with the address, amount, and wallet tiles locked. The card is then polled until CTX credits the payment.

• ctxSpendCrypto.ts — the protocol wire format: sha256(uint64BE(nonce)) digest, the 65-byte recoverable signature ([27 + recoveryId + 4] || R || S), public key recovery, and JWT expiry parsing. No React Native imports, so it is unit tested in Node.

• ctxSpendAuth.ts — the keypair is the CTX account. It is generated on first use and kept in the Edge account's encrypted dataStore, so the same anonymous CTX user is recovered across launches and devices. The reference script deliberately discards its keypair; a real client cannot. Tokens are derived state and are never persisted.

• ctxSpendApi.ts — the confirmed read surface (/me, /merchants, /gift-cards), with one re-auth retry on a 401.

• PLUGIN_API_KEYS.ctxSpend (clientId, baseUrl). There is no API key; the client id is registered server-side and the keypair identifies the user.

• A CTX section on the existing developer-facing gift card account info scene, so the session can be driven in the app.

Two substitutions the runtime forced, both covered in the doc's Decisions:

• No BigInt in the uint64 encoding. index.ts shims BigInt with big-integer when it is missing, and DataView.setBigUint64 rejects that shim.
• Request URLs are built by string, not via URL. React Native's URL appends a trailing slash to any query-less path, and the spend-api routes /me/ and /merchants/ to 404.

No new npm dependency: @noble/curves and @noble/hashes were already present, and are the same libraries the reference script uses.

Not in scope: replacing Phaze, redemption, a merchant-browsing UI, a shared provider interface over both APIs, and identity rotation.

Test plan

• 13 new jest cases in src/__tests__/ctxSpendCrypto.test.ts. The load-bearing one recovers the signing public key from the signature, which is the same check the server performs, so the wire format is verified without a network round trip. Vectors were cross-checked against Buffer.writeBigUInt64BE and node:crypto.
• verify-repo.sh passes: eslint, npm run prepare, and the full 536-case suite.
• Driven in-app on an iOS 18.6 simulator against https://staging.spend.ctx.com. The app generated its own keypair, registered it, and read live data: 12 permissions, 118 merchants, company Edge. The server named the anonymous user Anon 032129df after the public key's own prefix.
• Persistence checked by a full app stop and relaunch: the same user id and public key came back, so the keypair is reloaded from the encrypted store rather than regenerated.

End-to-end purchase, driven in-app on the sim against staging: ordered an Amazon card for USD 0.01, paid the quoted 0.0000052 ETH from the account's Sepolia wallet through the normal send flow, and watched CTX move the card to paid. Card 5d2964f9-3641-450e-8d77-e9f178b5b1da.

Two notes on that run. Every staging quote is testnet (Monero on stagenet, Zcash/BTC/LTC/BCH/DASH/XLM/ZANO on theirs, ETH on Sepolia), and Sepolia is the only testnet Edge ships a wallet for, so ETH is the one rail the app can actually pay. And fulfilmentStatus reached ordered and stayed there for the rest of the run: merchant issuance is asynchronous and outside the client, so the polling stops at paid.

Screenshots in the test-evidence comments below.

Bugbot found 6 issues across three rounds, all fixed and re-tested on the sim. Four were in the first round: a dataStore read failure reading as "no identity" and silently minting a replacement keypair (the worst of them, since CTX has no recovery), malformed stored hex throwing past the replace path, a light-account status conflated with a failed write, and Connect not being retryable. The retry fix then surfaced two follow-ons it had created or exposed: an ungated button that could stack sessions, and the app-wide retry: 2 turning one failed connect into three login handshakes against a rate-limited API. Decision 8.6 in the design doc records the error-handling contract that came out of the first round.

Requirements

If you have made any visual changes to the GUI. Make sure you have:

• Tested on iOS device
• Tested on Android device
• Tested on small-screen device (iPod Touch)
• Tested on large-screen device (tablet)

---

Note

Medium Risk
Touches encrypted identity storage and real on-chain sends for test orders; prototype is developer-gated but mishandling keypair races or payment rounding could strand CTX users or underpay addresses.

Overview
Adds a prototype client for CTX’s spend-api alongside the existing Phaze gift card flow. Phaze purchase paths are unchanged; CTX is wired only when developer mode is on and PLUGIN_API_KEYS.ctxSpend is set.

Auth & persistence: New modules implement secp256k1 register/login (nonce signing, JWT refresh), persist the signing keypair in encrypted account.dataStore (Phaze-style layout), and gate light accounts that cannot store keys. Protocol crypto is isolated for Node unit tests.

API & purchase: HTTP client covers /me, /merchants, and gift-card create/read. A fixed staging test order maps chain/network to Edge wallets (e.g. ETH testnet → sepolia), converts quoted amounts with ceil via biggystring, opens the normal send scene with locked tiles, and polls until paymentStatus is paid.

UI: GiftCardAccountInfoScene gains Connect/Buy actions and readouts for session and card state (still reachable for Phaze help without developer mode).

Config & docs: envConfig adds optional ctxSpend; strings and changelog updated; design doc ctx-spend-pubkey-auth.md documents the protocol and decisions.

^{Reviewed by Cursor Bugbot for commit c35d4f3. Bugbot is set up for automated code reviews on this repo. Configure here.}

[j0ntz]

📸 Test evidence

ctx before connect

ctx authenticated

ctx persisted after relaunch

Captured by the agent's in-app test run (build-and-test).

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[j0ntz]

📸 Test evidence (after review fixes)

ctx persisted after relaunch

Captured by the agent's in-app test run (build-and-test).

[j0ntz]

📸 Test evidence: end-to-end gift card purchase (Amazon USD 0.01, paid on Sepolia)

ctx connected

ctx send prefilled

ctx card after payment

ctx card paid

Captured by the agent's in-app test run (build-and-test).

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 8d13b14. Configure here.}