Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

docs(ios): update the App Review risk notes for the Safari payment handoff and release flow

nirholas5dcbc8e1aa18
diff --git a/ios/docs/REVIEW-RISK.md b/ios/docs/REVIEW-RISK.md
index 2ee894192..4379c9987 100644
--- a/ios/docs/REVIEW-RISK.md
+++ b/ios/docs/REVIEW-RISK.md
@@ -39,36 +39,74 @@ route the value-moving surfaces to Safari rather than removing them:
| Ships in the app | Opens in Safari |
|---|---|
-| `/create`, the forge, avatar and model generation | `/trade`, swaps, bridges |
-| `/ar`, `/ar/studio`, `/irl`, the viewer, Quick Look | pump.fun launching |
-| Agent profiles, `/marketplace` browsing, `/community`, `/feed` | Buying credits or paid generations |
-| Talk mode, animation, rigging, exports | Wallet funding and withdrawal |
-| Read-only wallet and portfolio views | x402 payment flows |
-
-**This is not a one-line change, and the reason matters.**
-`src/native-bridge.js` already sends every *off-site* link to an in-app Safari
-sheet, so routing a same-origin surface there looks like adding five paths to a
-list. It is not: `SFSafariViewController` runs on Safari's cookie jar, and the
-session cookie that authenticates the visitor was set in the app's `WKWebView`,
-which does not share it. Route `/pay` to the sheet as it stands and the visitor
-arrives signed out, on a page that exists to spend their money.
-
-Doing it properly needs a session handoff: the app mints a short-lived,
-single-use code against the live session and the Safari URL carries it, which
-the site exchanges for a cookie on first load. The closest existing thing is
-`POST /api/auth/extension-token` ([`../../api/auth/extension-token.js`](../../api/auth/extension-token.js)),
-which solves the same shape of problem for the browser extension but mints a
-scoped Bearer token, and a Bearer token cannot authenticate a page load. So this
-is a real, small feature, not a config flag. Size it before promising a date.
-
-The surfaces the list should hold, read off `data/pages.json` rather than
-guessed: `/launch`, `/launcher` and `/pumpfun` (they mint and trade),
-`/pay` and `/payments` (they spend). Deliberately NOT `/wallet` or
-`/agent-wallet`: Apple permits wallet storage and viewing from an organization
-account, and pushing the two most-used surfaces out to Safari would cost far
-more than it buys. Also not `/agent-trade`, `/coin3d`, `/launch-studio` or
-`/pay/simulator`, which read as transactional and are a visualisation, a
-visualisation, a catalogue and a dry run.
+| `/create`, the forge, avatar and model generation | Trading, swaps, bridges |
+| `/ar`, `/ar/studio`, `/irl`, the viewer, Quick Look | Coin launching |
+| Agent profiles, `/marketplace` browsing, `/community`, `/feed` | Buying credits, paid generations, skills and assets |
+| Talk mode, animation, rigging, exports, free trials | Subscriptions and the Pro plan |
+| Wallet and portfolio views, deposits, withdrawals, claims | x402 payment flows, tips, donations |
+
+**How the app does it: a signed-in hop to real Safari.** Implemented in
+[`../src/native-bridge.js`](../src/native-bridge.js) (the client),
+[`../../api/auth/handoff.js`](../../api/auth/handoff.js) (the server) and
+`openInSafari` in
+[`../native/App/App/ThreeWsAppPlugin.swift`](../native/App/App/ThreeWsAppPlugin.swift).
+
+1. A value-moving step starts in the app: a link to a payment page, a Buy or
+ Launch button, the agreements gate for a trade.
+2. The app shows a sheet, "Continue in Safari", that says why. Nothing has
+ been spent.
+3. On **Open in Safari**, the app asks `POST /api/auth/handoff` for a code
+ bound to the current session and the page the visitor was on. The code is
+ single-use, lives 60 seconds, and only its SHA-256 is stored.
+4. The app opens `https://three.ws/api/auth/handoff?code=...` in **Safari
+ itself** (`UIApplication.shared.open`), not an in-app sheet. The exchange
+ consumes the code in the same statement that checks it, sets a fresh
+ session cookie in Safari's jar, and redirects to the original page.
+
+Two details are load-bearing:
+
+- **Real Safari, not `SFSafariViewController`.** Guideline 3.1.1 is about where
+ the purchase happens. A Safari sheet presented over the app is still the app
+ to a reviewer; leaving for Safari is the documented pattern.
+- **The hop always goes through `/api/auth/handoff`, even signed out.** The
+ apple-app-site-association claims every three.ws path except `/api/*`, so
+ opening a plain `https://three.ws/launch` from the app would be routed
+ straight back into the app by universal links. The code-less form of the URL
+ is a plain redirect to the page, and the Swift side refuses any URL that is
+ not that endpoint.
+
+**What leaves the app**, decided in one place each:
+
+| Where | Rule |
+|---|---|
+| Links to a payment page | `HANDOFF_EXACT` and `HANDOFF_SUBTREES` in `native-bridge.js`: `/launch` and everything under it, `/launcher`, `/launchpad`, `/three-launchpad`, `/launch-studio`, `/pay`, `/payments`, `/credits`, `/vault`, `/vaults`, `/autopilot`, `/markets/robinhood/desk`. Opening one directly (a deep link, a push) shows the sheet with **Go back**. |
+| The agreements gate (`ensureRiskAck`) | Every context hands off except the wallet custody steps that guideline 3.1.5(b) allows an organization app to offer: `withdraw`, `deposit`, `claim`, `fund-agent`, `master-send`, plus the agreements page itself. Trading, launching, swaps, x402 payments, onramp, donations (guideline 3.2.2) and any context added later hand off by default. |
+| Purchases that skip the gate | `leaveAppForPayment()` in [`../../src/shared/native-handoff.js`](../../src/shared/native-handoff.js), called first thing by skill, asset, time-pass and subscription purchases, credit deposits, forge pay-per-use, agent tips, coin buys in the game, x402 payments, and the Pro upgrade on `/pricing` and `/x-pricing`. |
+
+Deliberately NOT handed off: `/wallet` and `/agent-wallet` (wallet storage and
+viewing are allowed from an organization account, and they are the two
+most-used surfaces), `/launches` (a directory that only shows launches), and
+`/pay/simulator` (a dry run that spends nothing). Free actions, such as a skill
+trial, stay in the app.
+
+To add a surface: a new payment page goes in `HANDOFF_EXACT`; a new paid flow
+calls `leaveAppForPayment()` before it does anything else; a new risk-ack
+context hands off automatically unless it is added to `IN_APP_CONTEXTS`, which
+should only ever hold custody steps. `tests/ios-safari-handoff.test.js` and
+`tests/auth-handoff.test.js` pin both halves.
+
+**Residual risks, stated plainly.**
+
+- **Linking out to buy a subscription.** Since the 2025 US court ruling, apps on
+ the **US storefront** may link to an external purchase without the External
+ Purchase Link Entitlement. Outside the US the rules are per-region and
+ stricter. Release version 1 on the US storefront first and add regions after
+ reading the current rules for each.
+- **Token-gated features.** `ensureFeatureAccess` in `src/three/access.js`
+ (unlocking features by holding $THREE) has no callers today. If it is ever
+ wired to a surface inside the app, it is a 3.1.1 problem: unlocking app
+ features with crypto is prohibited. Route it through `requireSafari` or keep
+ it web-only.
## 2. Guideline 4.2: minimum functionality.
@@ -85,18 +123,22 @@ first minute of use. What is already in place:
- A designed offline screen that recovers on its own.
- Haptics.
-That is a defensible 4.2 position and not a certain one. The two additions that
-move it from defensible to comfortable, in order of effect per unit of work:
+Beyond those, the app now carries the native features that move 4.2 from
+defensible to comfortable, each one something the website cannot do:
-1. **A Share Extension.** Share a photo from Photos or a GLB from Files
- straight into avatar creation. The Android app already has this through the
- web manifest `share_target`; iOS needs a real extension target. It is the
- single most convincing "this is an app" feature available here.
-2. **A WidgetKit widget.** Your agents on the home screen, refreshed from the
- API. Nothing about it is possible on the web.
+1. **A Share Extension** (`ws.three.app.share`). Share a photo from Photos or a
+ GLB from Files and it lands in avatar creation or the library.
+2. **A WidgetKit widget** (`ws.three.app.glance`). Your agent on the home
+ screen in three sizes, refreshed from the API.
+3. **Push notifications**, from the app delegate through the device endpoint
+ to the notification fan-out, with the icon badge kept in sync. They go live
+ the moment the APNs key in `SUBMISSION.md` step 3b is set.
+4. **Home screen quick actions** that land on live pages.
-Push notifications count for 4.2 as well and are half-wired (entitlement and
-background mode present, APNs key and token endpoint absent).
+`npm run check:ios-app` verifies every one of them is wired end to end. Point
+the reviewer at the share sheet and the widget in the review notes
+([`../publish/listing.md`](../publish/listing.md)); a reviewer who never sees
+them judges the app as a WebView.
Edge-swipe back navigation, added in `MainViewController.swift`, is not a 4.2
credit on its own, but its absence is a reliable rejection *and* a reliable
@@ -109,13 +151,31 @@ except killing it.
- Every usage string in `Info.plist` says what the data is for in the user's
terms. Requesting a permission the app never uses is itself a rejection, so
do not add usage strings speculatively.
-- **Account deletion must be reachable in-app.** Apps that support account
- creation must offer account deletion. Verify the existing account settings
- path exposes it before submitting; this one is checked mechanically by
- reviewers and is a common, avoidable rejection.
-- Sign in with Apple is required only if the app offers third-party social
- login as the *only* sign-in option. Confirm which providers the login sheet
- offers before assuming it is not needed.
+- **Account deletion is reachable in-app.** `/settings`, Danger Zone tab,
+ **Delete my account**, confirmed by typing the phrase (`DELETE /api/auth/me`).
+ From the user's side it is final: every avatar, agent and widget is taken
+ down, the handle is released, every session and refresh token is revoked,
+ household access is removed, and no sign-in path (password, wallet, SSO)
+ will open the account again. The user row itself is kept as a tombstone with
+ its email, so a wallet or SSO sign-in answers `account_deleted` instead of
+ quietly creating a fresh account for the same person. Guideline 5.1.1(v)
+ allows keeping data for a stated reason. The privacy policy
+ (`/legal/privacy`, section 5) promises deleted accounts are purged after 30
+ days, and no job does that purge today (`api/cron/db-retention.js` does not
+ touch `users`). Close that gap before submitting, either with a purge job or
+ by rewording section 5 to describe the tombstone, because a policy that
+ promises a deletion the system never performs is the finding to avoid.
+ Reviewers test deletion by hand; walk it on the review build with a
+ throwaway account.
+- **Sign in with Apple (guideline 4.8).** The login page offers GitHub and X
+ next to three.ws's own email sign-in. 4.8 asks an app that uses a third-party
+ login to also offer one that limits collection to name and email, lets the
+ user keep their email private, and does no ad tracking. three.ws's own email
+ account is the equivalent we point to: it asks for an email and a password
+ and nothing else, and three.ws does no ad tracking. If a reviewer reads email
+ sign-in as not meeting the "keep your email private" part, the remedy is
+ adding Sign in with Apple to `/login`, which needs a Services ID from the
+ same Developer account and is a small, contained change.
## 4. Guideline 2.5.1 and 4.7: WebView posture.