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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
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.mdindex 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.2credit 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'sterms. Requesting a permission the app never uses is itself a rejection, sodo 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.