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): document the TestFlight release, the Safari payment handoff and the App Store privacy answers

nirholas9561352d516a
diff --git a/STRUCTURE.md b/STRUCTURE.md
index 4f27542ec..fd838384d 100644
--- a/STRUCTURE.md
+++ b/STRUCTURE.md
@@ -307,7 +307,7 @@ bottom.
| BNB Chain live block race | [pages/bnb-latency.html](pages/bnb-latency.html) + [src/bnb-latency.js](src/bnb-latency.js) `→ /bnb-latency`, pure helpers [src/bnb-latency-helpers.js](src/bnb-latency-helpers.js), live multi-chain API [api/bnb/latency.js](api/bnb/latency.js) over [api/_lib/bnb/latency-lanes.js](api/_lib/bnb/latency-lanes.js) (reuses `probeBlockTime` from [api/_lib/bnb/chains.js](api/_lib/bnb/chains.js) for BNB, adds Base/Ethereum/Solana lanes) | In-repo · shipped | Standalone, shareable proof page: four lanes (BNB Chain, Base, Ethereum, Solana) polled every 5s, each showing a freshly measured average block/slot time and a rolling sparkline — no hardcoded numbers, a down RPC shows "reconnecting" on just that lane. Headline strip shows BNB's live average plus its honest measured-vs-measured speedup over Base/Ethereum. Linked from the [/bnb](pages/bnb.html) hub's "real-time on-chain world" card, which auto-lights-up now that this route resolves. |
| BNB Chain payments (MPP, x402↔MPP bridge, gasless) | Accept [api/_lib/bnb/mpp-server.js](api/_lib/bnb/mpp-server.js) (`mppRequirements`/`mppChallenge`/`mppVerify`/`mppSettle`), pay [api/_lib/bnb/mpp-buyer.js](api/_lib/bnb/mpp-buyer.js) (`mppFetch`, re-exported from [api/_lib/x402-buyer-fetch.js](api/_lib/x402-buyer-fetch.js)), gasless rail [api/_lib/bnb/megafuel.js](api/_lib/bnb/megafuel.js), pilot dual-protocol endpoint [api/x402/three-intel.js](api/x402/three-intel.js) | In-repo · shipped, settlement needs merchant creds | three.ws speaks MPP (BNB Chain's Machine Payments Protocol) additively alongside x402: MPP's `b402` layer is x402 v2 byte-for-byte (same `X-PAYMENT`/`X-PAYMENT-RESPONSE`, same EIP-3009 credential), so a dual-protocol endpoint just advertises an extra BNB (`eip155:56`/`97`) accept entry and routes BNB-network payments to the b402 facilitator while Solana/Base traffic stays on the untouched x402 path. Verify (off-chain, free, replay-guarded via Redis `SET NX PX`) always runs before settle; without `B402_*` merchant credentials, settle fails closed with `mpp_not_configured` (503) rather than fabricating a receipt. Guide: [docs/bnb-payments.md](docs/bnb-payments.md). Wire contract: [specs/x402-mpp-bridge.md](specs/x402-mpp-bridge.md). Tests: [tests/bnb-mpp-server.test.js](tests/bnb-mpp-server.test.js), [tests/bnb-mpp-buyer.test.js](tests/bnb-mpp-buyer.test.js). |
| Seeker / Saga dApp Store app | [solana-mobile/](solana-mobile): TWA wrapper [solana-mobile/twa/](solana-mobile/twa), Publisher Portal listing copy [solana-mobile/publish/](solana-mobile/publish), MWA wallet + Seeker detection [solana-mobile/src/](solana-mobile/src) | Live · v1.0.0 on the Solana dApp Store (submitted 2026-08-28, approved 2026-09-01) | Everything needed to package three.ws as a Solana Mobile app and publish it to the on-chain dApp Store. Targets Seeker first; compatible with Saga Gen 1 and Gen 2. Docs: [solana-mobile/README.md](solana-mobile/README.md) |
-| iOS App Store app | [ios/](ios): Capacitor shell + config [ios/capacitor.config.ts](ios/capacitor.config.ts), Xcode project [ios/native/App/](ios/native/App), web-side native bridge [ios/src/native-bridge.js](ios/src/native-bridge.js), offline shell [ios/shell/](ios/shell), listing copy [ios/publish/](ios/publish), app association handler in [api/wk.js](api/wk.js) | In-repo · project builds and the web half ships on every deploy · awaiting an Apple Developer organization account | three.ws as a native iOS app (`ws.three.app`). A Capacitor 8 shell whose WKWebView runs the live `https://three.ws`, so the app is never a version behind the site; what makes it an app is the native layer around it. `ios/src/native-bridge.js` ships with the SITE, not the .ipa (Capacitor injects its bridge into the remote page, so `window.Capacitor` exists on three.ws only inside the app): it supplies the `navigator.share` WKWebView does not have, routes off-site links to an in-app Safari sheet instead of stranding the app's only WebView, handles universal links and `threews://` wallet returns, holds the launch screen until the first real frame, marks `html.ios-app`, routes a tapped push to its page and keeps the app icon badge equal to the inbox's unread count. Beyond the Android app it has **push notifications over APNs** (device registry [api/push/device.js](api/push/device.js), sender [api/_lib/apns.js](api/_lib/apns.js), fanned out beside Web Push in [api/_lib/notify.js](api/_lib/notify.js), client in [src/push-notifications.js](src/push-notifications.js); live once `APNS_KEY_ID`/`APNS_AUTH_KEY` are set), a **share extension** ([ios/native/App/ShareExtension/](ios/native/App/ShareExtension), `ws.three.app.share`) that takes one to three photos into `/create/selfie` or a `.glb` into `/create` through the App Group and the app's own `ThreeWsApp` plugin ([ThreeWsAppPlugin.swift](ios/native/App/App/ThreeWsAppPlugin.swift)), and four **home screen quick actions** ([QuickActions.swift](ios/native/App/App/QuickActions.swift)). `npm run check:ios-app` ([scripts/check-ios-app.mjs](scripts/check-ios-app.mjs)) holds the Swift half to its web callers, since no Linux machine can compile it. The `three-ws-ios-native-bridge` plugin in [vite.config.js](vite.config.js) copies it into `dist/` content-hashed and injects it into every built page except the third-party embed entries (671 pages, `/viewer` and `/ar` included, which a `transformIndexHtml` could not reach because they are copied verbatim from `public/`). `GET /.well-known/apple-app-site-association` is served from the API rather than a static file because Apple demands an exact path, a JSON content type and no redirect; it answers `503 not_configured` until `APPLE_TEAM_ID` is set rather than publishing an association that would fail silently on device. The app also carries the **CarPlay** scene for three.ws Drive: `CarPlaySceneDelegate` renders the car screen's templates while `DriveLink` bridges them to `/drive` in the WebView, gated behind the `com.apple.developer.carplay-voice-based-conversation` entitlement, which is inert until Apple grants it. Docs: [ios/README.md](ios/README.md), [docs/ios-app.md](docs/ios-app.md), App Review posture [ios/docs/REVIEW-RISK.md](ios/docs/REVIEW-RISK.md), submission [ios/docs/SUBMISSION.md](ios/docs/SUBMISSION.md), CarPlay [ios/docs/CARPLAY.md](ios/docs/CARPLAY.md). The project also carries the **Agent glance** WidgetKit extension (`ws.three.app.glance`, iOS 17+), whose sources live in [apple/](apple/README.md) and are shared byte for byte with the Mac app. |
+| iOS App Store app | [ios/](ios): Capacitor shell + config [ios/capacitor.config.ts](ios/capacitor.config.ts), Xcode project [ios/native/App/](ios/native/App), web-side native bridge [ios/src/native-bridge.js](ios/src/native-bridge.js), offline shell [ios/shell/](ios/shell), listing copy [ios/publish/](ios/publish), app association handler in [api/wk.js](api/wk.js) | In-repo · project builds and the web half ships on every deploy · awaiting an Apple Developer organization account | three.ws as a native iOS app (`ws.three.app`). A Capacitor 8 shell whose WKWebView runs the live `https://three.ws`, so the app is never a version behind the site; what makes it an app is the native layer around it. `ios/src/native-bridge.js` ships with the SITE, not the .ipa (Capacitor injects its bridge into the remote page, so `window.Capacitor` exists on three.ws only inside the app): it supplies the `navigator.share` WKWebView does not have, routes off-site links to an in-app Safari sheet instead of stranding the app's only WebView, handles universal links and `threews://` wallet returns, holds the launch screen until the first real frame, marks `html.ios-app`, routes a tapped push to its page and keeps the app icon badge equal to the inbox's unread count. Beyond the Android app it has **push notifications over APNs** (device registry [api/push/device.js](api/push/device.js), sender [api/_lib/apns.js](api/_lib/apns.js), fanned out beside Web Push in [api/_lib/notify.js](api/_lib/notify.js), client in [src/push-notifications.js](src/push-notifications.js); live once `APNS_KEY_ID`/`APNS_AUTH_KEY` are set), a **share extension** ([ios/native/App/ShareExtension/](ios/native/App/ShareExtension), `ws.three.app.share`) that takes one to three photos into `/create/selfie` or a `.glb` into `/create` through the App Group and the app's own `ThreeWsApp` plugin ([ThreeWsAppPlugin.swift](ios/native/App/App/ThreeWsAppPlugin.swift)), and four **home screen quick actions** ([QuickActions.swift](ios/native/App/App/QuickActions.swift)). `npm run check:ios-app` ([scripts/check-ios-app.mjs](scripts/check-ios-app.mjs)) holds the Swift half to its web callers, since no Linux machine can compile it. The `three-ws-ios-native-bridge` plugin in [vite.config.js](vite.config.js) copies it into `dist/` content-hashed and injects it into every built page except the third-party embed entries (671 pages, `/viewer` and `/ar` included, which a `transformIndexHtml` could not reach because they are copied verbatim from `public/`). `GET /.well-known/apple-app-site-association` is served from the API rather than a static file because Apple demands an exact path, a JSON content type and no redirect; it answers `503 not_configured` until `APPLE_TEAM_ID` is set rather than publishing an association that would fail silently on device. In the app, every step that spends money (buying, launching, trading, paying) hands off to real Safari on the same page, signed in through a single-use code from [api/auth/handoff.js](api/auth/handoff.js), because App Review forbids those flows in-app outside IAP; paid flows opt in with `leaveAppForPayment()` from [src/shared/native-handoff.js](src/shared/native-handoff.js) and the agreements gate hands off every non-custody context. Releases are one command, `npm run ios:release` ([ios/scripts/release.mjs](ios/scripts/release.mjs): structural check, `cap sync`, archive, upload to TestFlight), or Xcode Cloud through [ios/native/App/ci_scripts/](ios/native/App/ci_scripts); both targets bundle a privacy manifest. The app also carries the **CarPlay** scene for three.ws Drive: `CarPlaySceneDelegate` renders the car screen's templates while `DriveLink` bridges them to `/drive` in the WebView, gated behind the `com.apple.developer.carplay-voice-based-conversation` entitlement, which only `--carplay` releases sign in (`App-CarPlay.entitlements`), so builds archive before Apple grants it. Docs: [ios/README.md](ios/README.md), [docs/ios-app.md](docs/ios-app.md), App Review posture [ios/docs/REVIEW-RISK.md](ios/docs/REVIEW-RISK.md), submission [ios/docs/SUBMISSION.md](ios/docs/SUBMISSION.md), CarPlay [ios/docs/CARPLAY.md](ios/docs/CARPLAY.md). The project also carries the **Agent glance** WidgetKit extension (`ws.three.app.glance`, iOS 17+), whose sources live in [apple/](apple/README.md) and are shared byte for byte with the Mac app. |
| three.ws Glance for Mac | [apple/](apple/README.md): shared sources [apple/GlanceKit/](apple/GlanceKit), WidgetKit extension [apple/GlanceWidget/](apple/GlanceWidget), menu bar host app [apple/macos/](apple/macos) (XcodeGen spec [apple/macos/project.yml](apple/macos/project.yml)), icon [apple/scripts/make-macos-icon.mjs](apple/scripts/make-macos-icon.mjs) | In-repo · builds with XcodeGen and a Development Team · Developer ID distribution, so it needs no App Store review | The agent in a Mac's Notification Centre, and the same extension on iPhone. A menu bar app whose whole job is to hold a revocable widget token and prove it works: the Mac never sees a password, because signing in happens on three.ws and the page hands back the token through `threews://glance/link` or as a code to paste. The widget fetches `GET /api/glance/mine?format=png` on the system timeline, in both themes so it follows the reader's appearance, caches the last card in the shared App Group container so an offline Mac shows yesterday's card with the time on it, and opens the agent on click. One set of sources builds for both platforms; only the project differs, because an App Group identifier on a Developer ID Mac must carry the team prefix that the same group on iPhone must not. Guard: [scripts/check-apple-widget.mjs](scripts/check-apple-widget.mjs) (`npm run check:apple-widget`, in `npm run gate`) proves both Xcode projects and the client-to-server contract on a machine with no Xcode. Docs: [apple/README.md](apple/README.md), [docs/native-widgets.md](docs/native-widgets.md). |
| Walk Avatar browser extension | [extensions/walk-avatar/](extensions/walk-avatar) — MV3 `manifest.json`, `background.js` | In-repo · Chrome Web Store release checklist staged ([RELEASE.md](extensions/walk-avatar/RELEASE.md)) | Walks your three.ws avatar across any site and reads pages aloud — a browsing companion built on the same rig as the [walk-sdk](walk-sdk). Ships its own store-required [PRIVACY.md](extensions/walk-avatar/PRIVACY.md), [PERMISSIONS.md](extensions/walk-avatar/PERMISSIONS.md), and [TERMS.md](extensions/walk-avatar/TERMS.md). |
| Checkout companion browser extension | [extensions/checkout-companion/](extensions/checkout-companion) (MV3: [extract.js](extensions/checkout-companion/extract.js), [content.js](extensions/checkout-companion/content.js), [panel.js](extensions/checkout-companion/panel.js), [background.js](extensions/checkout-companion/background.js)), analysis [api/_lib/companion/checkout.js](api/_lib/companion/checkout.js), endpoint [api/companion/checkout.js](api/companion/checkout.js) | In-repo | The companion at the moment money moves: on a checkout page it reports the total against the price you were shown, money the page did not itemise, fees named and summed, whether the charge repeats, and the cancellation terms. **Arithmetic is never the model's job** (integer minor units, computed server-side) and **no finding is ever a legal verdict** (`sanitizeModelFindings()` drops any that claims an amount or calls something illegal). With no model reachable the arithmetic findings still stand. The extension **never reads an input**: `collectText`/`collectAmounts` refuse form fields, iframes and editable regions structurally, and redaction runs in the browser before anything is sent; only the hostname travels and nothing about the page is stored. Docs: [docs/checkout-companion.md](docs/checkout-companion.md). Tests: [tests/companion-checkout.test.js](tests/companion-checkout.test.js), [tests/checkout-extract.test.js](tests/checkout-extract.test.js) |
diff --git a/data/changelog.json b/data/changelog.json
index 6c37f2c7f..9e66ee0fd 100644
--- a/data/changelog.json
+++ b/data/changelog.json
@@ -1,6 +1,15 @@
{
"$comment": "Curated changelog entries for three.ws, the editorial layer of the public changelog. New PAGE launches are tracked automatically via the `added` field in data/pages.json; this file is for everything else holders care about: improvements, fixes, SDK releases, trading/payments capabilities, security work. scripts/build-page-index.mjs merges both sources into CHANGELOG.md, public/changelog.json, and public/changelog.xml. Newest first. Allowed tags: feature, improvement, fix, sdk, infra, docs, security, desktop (desktop entries become the desktop app's release notes). `link` is optional and must be a live three.ws path.",
"entries": [
+ {
+ "date": "2026-10-09",
+ "title": "The iPhone app is ready for TestFlight",
+ "summary": "The three.ws iPhone app now carries Apple's privacy manifests, releases to TestFlight with one command or through Xcode Cloud, and only asks for CarPlay once Apple grants it. Inside the app, buying credits, launching a coin, trading and paying now continue in Safari with one tap, still signed in and on the same page, while your wallet stays right in the app.",
+ "tags": [
+ "feature",
+ "improvement"
+ ]
+ },
{
"date": "2026-10-09",
"title": "Forge Workflows: chain 3D tools into one run",
diff --git a/docs/api-reference.md b/docs/api-reference.md
index a9ce1d58b..4453b8fa4 100644
--- a/docs/api-reference.md
+++ b/docs/api-reference.md
@@ -4267,6 +4267,50 @@ Authentication is covered in detail in the [Authentication documentation](authen
| `/api/auth/privy/verify` | POST | Verify a Privy auth token, create session |
| `/api/auth/wallets` | GET | List wallets linked to current user |
| `/api/auth/wallets` | POST | Link a new wallet |
+| `/api/auth/handoff` | POST | Mint a single-use code that signs Safari in as this session (iOS app) |
+| `/api/auth/handoff` | GET | Exchange that code in Safari for a session cookie and land on the page |
+
+### Session handoff to Safari (iOS app)
+
+The three.ws iOS app opens payments, coin launches and trading in Safari rather
+than in its WebView (see [`ios/docs/REVIEW-RISK.md`](../ios/docs/REVIEW-RISK.md)).
+Safari has its own cookie jar, so the app carries the session across with a
+short-lived code.
+
+```
+POST /api/auth/handoff
+Content-Type: application/json
+
+{ "next": "/launch?mint=..." }
+```
+
+Requires a browser session and a same-site `Origin`. `next` must be a path on
+three.ws (it starts with `/`, is not `//`, carries no backslash or control
+character, and is at most 2048 characters). Rate limited to 30 codes per user
+per 10 minutes.
+
+```json
+{
+ "url": "https://three.ws/api/auth/handoff?code=Qm9...&next=%2Flaunch%3Fmint%3D...",
+ "expires_at": "2026-10-09T19:01:00.000Z"
+}
+```
+
+The code is single-use and expires after 60 seconds; only its SHA-256 is
+stored. Errors: `401 unauthenticated`, `403` (cross-site origin),
+`400 invalid_next`, `429`.
+
+```
+GET /api/auth/handoff?code=<code>&next=<path>
+```
+
+Opened by Safari, never called with `fetch`. On a valid code it consumes it,
+replaces any session Safari already had with one for the code's user, and
+answers `302` to the path stored at mint time. A used, expired or malformed code
+redirects to `/login?error=handoff_expired&next=<path>`, so the visitor signs in
+and still lands where they were going. Without `code` it is a plain `302` to
+`next`: the app always opens Safari through this endpoint, because universal
+links would route a bare `https://three.ws/...` URL straight back into the app.
---
diff --git a/docs/ios-app.md b/docs/ios-app.md
index 6dca60aa9..e9aed6809 100644
--- a/docs/ios-app.md
+++ b/docs/ios-app.md
@@ -121,6 +121,18 @@ The `applinks` components hand every path to the app except `/api/*` (OAuth and
x402 callbacks must finish in the browser that started them) and the `/embed*`
and `/widget*` entries (they exist to render inside someone else's page).
+## Payments open in Safari
+
+App Review does not allow buying digital goods, launching coins or trading
+inside an iOS app outside In-App Purchase (guidelines 3.1.1 and 3.1.5). So in
+the app, every step that spends money shows a **Continue in Safari** sheet, and
+Open in Safari carries the visitor to the same page in real Safari, still
+signed in, through a 60-second single-use code
+([`/api/auth/handoff`](./api-reference.md#session-handoff-to-safari-ios-app)).
+Wallet custody (viewing, depositing, withdrawing, claiming) stays in the app.
+Which surfaces leave, and why, is in
+[`ios/docs/REVIEW-RISK.md`](../ios/docs/REVIEW-RISK.md).
+
## What is missing
- **`APPLE_TEAM_ID`**, which needs an Apple Developer Program account enrolled
@@ -135,11 +147,11 @@ and `/widget*` entries (they exist to render inside someone else's page).
- **Listing screenshots**, which have to be captured on a real device. The icon
and launch images are generated from the brand mark (`npm run ios:icons`) and
a guard keeps them from drifting (`npm run check:ios-icons`).
-- **The App Review posture on crypto surfaces**, which is a product decision
- and not a code one, and which costs a session handoff rather than a config
- flag: `SFSafariViewController` does not share the app WebView's cookie jar, so
- a surface routed to Safari arrives signed out. Written up in
- [`ios/docs/REVIEW-RISK.md`](../ios/docs/REVIEW-RISK.md).
+- **A signed build.** Everything up to signing is in place: privacy manifests
+ for the app and the share extension, a shared scheme, Xcode Cloud's
+ `ci_scripts/`, and `npm run ios:release`, which archives with automatic
+ signing and uploads to TestFlight in one command once `APPLE_TEAM_ID` exists.
+ Steps in [`ios/docs/SUBMISSION.md`](../ios/docs/SUBMISSION.md).
- **Service workers**, which `WKWebView` runs only for app-bound domains. The
app declares none, so the site's offline caching and share-target worker do
not run inside it; the native offline screen covers the case that matters.
diff --git a/ios/README.md b/ios/README.md
index e3c66f6fd..7c4b260b0 100644
--- a/ios/README.md
+++ b/ios/README.md
@@ -21,20 +21,24 @@ ios/
├── shell/ # local bundle: bootstrap + the designed offline screen
├── src/native-bridge.js # web-side half; ships with the SITE, not the .ipa
├── scripts/make-icons.mjs # derives the icon + launch images from the brand mark
+├── scripts/release.mjs # archive + upload to TestFlight (npm run ios:release)
├── native/App/ # the generated Xcode project (committed)
│ ├── App.xcodeproj
│ ├── App/SceneDelegate.swift # roots MainViewController, quick actions, share pickup
│ ├── App/AppDelegate.swift # APNs token forwarding, stale share sweep
│ ├── App/MainViewController.swift # swipe-back, dark chrome, edge-to-edge insets, open(path:)
│ ├── App/QuickActions.swift # home screen quick action types -> pages
-│ ├── App/ThreeWsAppPlugin.swift # the app's own plugin: takeShare, setBadge
+│ ├── App/ThreeWsAppPlugin.swift # the app's own plugin: takeShare, setBadge, openInSafari
│ ├── App/CarPlaySceneDelegate.swift # the car screen: templates + voice control
│ ├── App/DriveLink.swift # CarPlay <-> /drive channel + audio session
│ ├── App/Info.plist # usage strings, URL scheme, quick actions, .glb type, scenes
-│ ├── App/App.entitlements # associated domains + APNs + CarPlay + App Group
+│ ├── App/App.entitlements # associated domains + APNs + App Group
+│ ├── App/App-CarPlay.entitlements # the same plus CarPlay, signed only with --carplay
+│ ├── App/PrivacyInfo.xcprivacy # privacy manifest: required-reason APIs, collected data
│ ├── ShareExtension/ # the share sheet entry (ws.three.app.share)
│ │ ├── ShareViewController.swift # copies photos (as JPEG) or a .glb out of the sender
│ │ └── SharedInbox.swift # App Group hand-off, compiled into app and extension
+│ ├── ci_scripts/ci_post_clone.sh # Xcode Cloud: Node, structural check, cap sync
│ └── CapApp-SPM/ # Swift Package Manager plugin graph
└── docs/ # SUBMISSION.md, REVIEW-RISK.md, ASSETS.md, CARPLAY.md
```
@@ -115,6 +119,8 @@ phone's WebView runs `/drive` with the actual agent in it. The two are joined by
It is inert without the `com.apple.developer.carplay-voice-based-conversation` entitlement,
which Apple grants per app on request, so nothing about the phone app changes before then.
+Builds leave the key out unless released with `--carplay`, because signing fails on a key
+the provisioning profile does not carry.
Read [`docs/CARPLAY.md`](docs/CARPLAY.md) before touching any of it, and
[`../docs/carplay.md`](../docs/carplay.md) for why the architecture is shaped this way.
@@ -159,6 +165,20 @@ What it installs, and the breakage each one fixes:
| Haptics on primary actions | No tactile feedback anywhere |
| Status-bar padding on the sticky header | The nav renders under the system clock: the site's own compensation is behind `@media (display-mode: standalone)`, which a WKWebView loading a remote URL never matches |
| 16px minimum on form fields | iOS zooms the page on focus and never zooms back out |
+| Safari handoff for payments (`window.threeWsNative`) | Buying, launching, trading and paying run inside the app, which App Review rejects under guideline 3.1.1 |
+
+### Payments open in Safari
+
+Inside the app, anything that spends money hands off to Safari, signed in, on the
+same page. A link to a payment page (`/launch`, `/credits`, `/pay` and the rest of
+`HANDOFF_EXACT`), the agreements gate for a trade or launch, and every paid flow that
+calls `leaveAppForPayment()` from
+[`../src/shared/native-handoff.js`](../src/shared/native-handoff.js) show a
+**Continue in Safari** sheet instead. Open in Safari mints a 60-second single-use code
+at `POST /api/auth/handoff` and opens `GET /api/auth/handoff?code=...` in real Safari,
+which signs Safari in and lands on the page. Wallet custody (deposit, withdraw,
+claim) stays in the app. The policy, and how to add a surface, is in
+[`docs/REVIEW-RISK.md`](docs/REVIEW-RISK.md).
## The native half
@@ -216,11 +236,16 @@ wired into `npm run gate`) is what a Linux machine can prove about the Swift
half: every source is a member of a target, the share extension is embedded and
versioned with the app, the extension and the app agree on the App Group and
the `.glb` type, every quick action routes to a live page, the `ThreeWsApp`
-plugin's methods match their web callers, and push is wired from the app
+plugin's methods match their web callers, both targets bundle a privacy
+manifest covering every required-reason API they call, CarPlay stays out of
+the default entitlements, every target shares one build number, and push is wired from the app
delegate to the notification fan-out. It is a structural check, not a build.
The web half is unit tested: `tests/ios-native-*.test.js`,
`tests/push-notifications-native.test.js`, `tests/share-target.test.js`,
-`tests/apns.test.js` and `tests/push-device-endpoint.test.js`.
+`tests/apns.test.js`, `tests/push-device-endpoint.test.js`,
+`tests/ios-safari-handoff.test.js` and `tests/auth-handoff.test.js`. The release
+script's planning is tested in `tests/ios-release.test.js`, and
+`npm run ios:release:dry` prints the exact commands a release would run.
## What is not wired yet
@@ -235,7 +260,9 @@ them at submission time:
- **The APNs key.** Push is built end to end and dormant until `APNS_KEY_ID`
and `APNS_AUTH_KEY` are set; see "Push notifications" above and
[`docs/SUBMISSION.md`](docs/SUBMISSION.md).
-- **Signing.** No team, no provisioning profile, no `ExportOptions.plist`. See
+- **Signing.** The team. Once it exists, `APPLE_TEAM_ID=<id> npm run ios:release`
+ archives with automatic signing and uploads to TestFlight; Xcode Cloud works
+ from the checked-in shared scheme and `ci_scripts/`. See
[`docs/SUBMISSION.md`](docs/SUBMISSION.md).
- **Screenshots** for the listing, which have to be captured on a real device.
Specs in [`docs/ASSETS.md`](docs/ASSETS.md).
@@ -244,8 +271,7 @@ Two findings that are decisions rather than missing work, both written up in
[`docs/REVIEW-RISK.md`](docs/REVIEW-RISK.md): the app currently has no service
workers (`limitsNavigationsToAppBoundDomains: false` disables them in
`WKWebView`, which is why the offline screen is native rather than the site's
-own), and routing a surface to the Safari sheet signs the visitor out, because
-`SFSafariViewController` does not share the app WebView's cookie jar.
+own), and the set of surfaces that leave the app for Safari.
## Related
diff --git a/ios/docs/CARPLAY.md b/ios/docs/CARPLAY.md
index a98979145..8fc9b6634 100644
--- a/ios/docs/CARPLAY.md
+++ b/ios/docs/CARPLAY.md
@@ -24,7 +24,7 @@ channel keeps the two in step. Nothing about the phone app changes when CarPlay
| `native/App/App/AppDelegate.swift` | Routes a `carTemplateApplication` scene session to `CarPlaySceneDelegate`. |
| `native/App/App/MainViewController.swift` | Attaches `DriveLink` to the Capacitor WebView on load. Inert until a CarPlay scene connects. |
| `native/App/App/Info.plist` | `UIApplicationSupportsMultipleScenes` is now `true` (CarPlay is a second scene), plus the `CPTemplateApplicationSceneSessionRoleApplication` configuration. |
-| `native/App/App/App.entitlements` | `com.apple.developer.carplay-voice-based-conversation`. |
+| `native/App/App/App-CarPlay.entitlements` | The app's entitlements plus `com.apple.developer.carplay-voice-based-conversation`. Signed in only when a release asks for it; the default `App.entitlements` leaves the key out. |
| `../../src/drive/bridge.js` | The web half of the same protocol. Change one side, change both. |
## The protocol
@@ -69,12 +69,18 @@ approved. Each is met in code, not by intention:
2. The request asks what the app does in the car. The honest answer is the pitch: a
conversational assistant with a persistent identity, launched by hand, voice in and voice
out, no navigation and no wake word.
-3. On approval, enable the capability for bundle ID `ws.three.app` in the Developer portal
- and regenerate the provisioning profile. The entitlement key is already in
- `App.entitlements`, so no code changes.
-
-Until then the key is harmless: a build signed without the grant simply never receives a
-CarPlay scene, and the phone app behaves exactly as it does today.
+3. On approval, enable the capability for bundle ID `ws.three.app` in the Developer portal.
+ No code changes: release with `npm run ios:release -- --carplay`, or set
+ `THREEWS_CARPLAY=1` on the Xcode Cloud workflow. Either signs with
+ `App/App-CarPlay.entitlements`, and automatic signing fetches a profile that carries the
+ grant.
+
+Until then every build signs with `App/App.entitlements`, which leaves the key out. That is
+not optional tidiness: codesign refuses an archive whose entitlements name a capability the
+provisioning profile lacks, so shipping the key before the grant would block every TestFlight
+upload. Without the key the app simply never receives a CarPlay scene, and the phone app
+behaves exactly as it does today. The switch is the `THREEWS_APP_ENTITLEMENTS` build setting,
+and `npm run check:ios-app` fails if the CarPlay key ever creeps back into the default file.
## Testing it
diff --git a/ios/docs/SUBMISSION.md b/ios/docs/SUBMISSION.md
index 54896311a..19820774a 100644
--- a/ios/docs/SUBMISSION.md
+++ b/ios/docs/SUBMISSION.md
@@ -37,8 +37,13 @@ step 3 is blocked on it.
create the group `group.ws.three.app`.
3. Fill the listing from [`../publish/listing.md`](../publish/listing.md).
4. Answer the content rights, age rating, and privacy questionnaires. The
- privacy answers must match what the app actually collects; the camera,
- photos, location and identifiers sections all apply.
+ privacy answers must match the app's privacy manifest row for row; the table
+ in [`../publish/listing.md`](../publish/listing.md) is the manifest, already
+ translated into App Store Connect's categories.
+5. Under App Review Information, Sign-In Information, give the reviewer an
+ account made for review alone: register it on `/register`, keep it empty of
+ real funds, and never reuse the production QA login, which other tooling
+ signs into. Paste the reviewer notes from the listing.
## 3. Wire the Team ID into production
diff --git a/ios/publish/listing.md b/ios/publish/listing.md
index 2dda22211..c6ef4efed 100644
--- a/ios/publish/listing.md
+++ b/ios/publish/listing.md
@@ -75,11 +75,11 @@ https://three.ws
## Privacy policy URL
```
-https://three.ws/privacy
+https://three.ws/legal/privacy
```
-Verify this route resolves before submitting; a 404 here is an automatic
-rejection.
+Not `/privacy`, which is a 404. A dead privacy URL is an automatic rejection;
+`curl -sI https://three.ws/legal/privacy` must answer `200`.
## Category
@@ -97,28 +97,49 @@ sexual content. Answer the questionnaire from the product, not from this note.
## App Privacy (data collection disclosure)
-Declare what the app actually collects and how it is used. At minimum:
+These answers must match the privacy manifest compiled into the app,
+[`../native/App/App/PrivacyInfo.xcprivacy`](../native/App/App/PrivacyInfo.xcprivacy).
+App Store Connect compares the two, and a mismatch is a rejection. Change both
+together.
-| Data type | Collected | Linked to identity | Used for |
-|---|---|---|---|
-| Email address | Yes | Yes | App functionality (account) |
-| User content (photos, models, prompts) | Yes | Yes | App functionality |
-| Coarse location | Yes | Yes | App functionality (IRL pins) |
-| Identifiers (user ID) | Yes | Yes | App functionality, analytics |
-| Usage data | Yes | Yes | Analytics, product improvement |
-| Purchases / wallet activity | Review before answering | | |
+**Tracking: No.** three.ws does not link app data with third-party data for
+advertising and does not share it with data brokers. No tracking domains.
-The last row needs a real answer from whoever knows the current wallet and
-payments surfaces; do not guess it on the form.
+| App Store Connect category | Data type | Linked to the user | Purposes |
+|---|---|---|---|
+| Contact Info | Email Address | Yes | App Functionality |
+| Identifiers | User ID | Yes | App Functionality, Analytics |
+| User Content | Photos or Videos | Yes | App Functionality |
+| User Content | Audio Data | Yes | App Functionality |
+| User Content | Other User Content (prompts, models, agent settings) | Yes | App Functionality |
+| Location | Precise Location | Yes | App Functionality |
+| Purchases | Purchase History | Yes | App Functionality |
+| Usage Data | Product Interaction | Yes | Analytics, Product Personalization |
+| Diagnostics | Other Diagnostic Data | Yes | App Functionality, Analytics |
+
+Why each row is there: email is the account; photos come from the camera,
+selfie and share sheet flows and are stored with the generation; audio is talk
+mode and `/drive`; precise location is IRL pins, which place an agent at a real
+spot; purchase history is the record of credits, skills and subscriptions
+bought on three.ws (in Safari) that the app displays; product interaction and
+diagnostics are first-party usage and error events.
## Notes for the reviewer
```
three.ws is a 3D content creation tool. A reviewer can exercise the whole core product without an account: open Create, type a prompt, and a 3D model is generated and rendered. Placing a model in AR needs camera access on a physical device.
-Demo account (if one is wanted): supplied separately in App Store Connect.
+Demo account: supplied in the Sign-In Information fields of this submission.
+
+Things only the app does, worth a look:
+- Share sheet: in Photos, share any photo and pick three.ws. It opens in Create, ready to become a 3D avatar. A .glb file shared from Files goes into the library.
+- Home screen widget: long-press the home screen, add the three.ws widget, and your agent appears.
+- Quick actions: long-press the app icon.
+- Notifications: sales, follows and remixes arrive as push notifications and badge the icon.
+
+On blockchain functionality: three.ws is published by an organization account. The app shows 3D characters that creators may have registered on a public blockchain, and lets a signed-in user view their wallet, deposit to it, withdraw from it and claim from it. Nothing is bought, sold, traded or launched inside the app. Buying credits, skills or a subscription, launching a coin, trading and paying for services all open in Safari: the app explains this in a sheet, and Safari continues signed in on the same page.
-On blockchain functionality: the app displays 3D characters that creators may optionally have registered on a public blockchain, and shows read-only wallet and ownership information. Transactional surfaces are not offered inside the app; they open in Safari.
+Account deletion: Settings, Danger Zone, Delete my account.
```
Keep that last paragraph true. If the app ships with in-app transactional