0110. Every effect is built for native: sign-in, push, purchases and camera on iOS and Android
- Status: Accepted (Mik, 16 Nov 2026)
- Date: 2026-11-14
- Decided by: wave 5, domain A (native effects)
- Planning item: WP11 (platform effects); sub-briefs wp11-1 to wp11-4
Context
Before this change, a native build of an app that imported signIn, push, purchases, camera or their mocks failed with E0202, so examples/effects could not run on a phone. Mik asked for every feature to either work on native or be refused loudly. These four now have Kotlin and Swift halves behind the bridge of decision 0048. Building them raised choices that change the contracts, the catalogue or the build, recorded here.
Decision
- The platform's own sign-in returns an ID token. Sign in with Apple on iOS (ASAuthorizationController) and Google on Android (Credential Manager) do not run PKCE. They hand back an ID token bound to the sign-in's nonce.
Authorization(spec/effects/sign-in.ts) gainsidToken?: string; in that casecodeVerifieris "" and the backend checks the ID token and nonce instead. Apple is sent the SHA-256 of the nonce, as Apple asks, so the answer carries the hash as its nonce. Every other flow uses the provider's page in ASWebAuthenticationSession or a Custom Tab, with PKCE as on the web. The TypeScript half checks the returnedstate(E0225). - An endpoint or redirect written as a path is a screen of the app.
authorizationEndpoint: "/mock-provider"andredirectUri: "/callback"resolve against the app's own address on the web and navigate inside the app on native. That lets examples/effects use one pretend provider on every target, with no network. - The JavaScript engine on native has no WebCrypto. Random bytes come from the platform (
signIn.randomBytes, SecureRandom or SecRandomCopyBytes). SHA-256 is pure TypeScript (packages/effects/src/native/sha256.ts, checked against FIPS vectors and WebCrypto). There is noMath.randomfallback: without the bridge, sign-in fails. - No "photos" permission: the photo library is the picker's. An earlier draft added a "photos" permission name (NSPhotoLibraryUsageDescription, READ_MEDIA_IMAGES). Nothing read the library with it, and Play restricts READ_MEDIA_IMAGES, so it is gone: a photo from the library comes through
picker(decision 0101), which runs outside the app and needs no permission. A reason inpermissions.yamldeclares any other permission an app asks for by name (decision 0102). - Declarations grow entitlements and removals. A catalogue declaration may carry iOS entitlements:
aps-environmentfor push, andcom.apple.developer.applesigninfor Sign in with Apple, which the build writes only when a page configures the apple provider with Apple's own sheet (signing an app with it needs the capability on its App ID). The build writes them tonative/ios/Entitlements.plist, which the app signs with. Some Android permissions and components arrive with an effect's library: Play Billing's BILLING; Firebase's RECEIVE, POST_NOTIFICATIONS, WAKE_LOCK, ACCESS_NETWORK_STATE and its exportedFirebaseInstanceIdReceiver; Credential Manager's exportedRevocationBoundService; androidx.biometric's USE_BIOMETRIC and USE_FINGERPRINT. The catalogue marks them (android.brought,android.components), and when no declaration of the app keeps one, the build writes it astools:node="remove". Only what is marked is ever removed: ACCESS_NETWORK_STATE stays for push (Firebase needs it) and forconnection, which lists it itself. - **Push on Android needs
google-services.jsonat the project's root.** The build turns it into string resources, so there is no Google Services Gradle plugin. When the file is missing, a native build fails with E0400 at each push import. When the file is not Firebase's, or has no Android app whose package name is the app's application id (the shell'sdev.duolith.shelluntil the app manifest of decision 0141 gives it its own), it fails with E0401. - Links that open the app reach the effects through the bridge, and until the shells deliver them, what needs one is refused.
EffectsBridge.openLink(address)lets the sign-in under way take its provider's return; every other link goes to the app (links), and a magic link for the screen it was sent from completes sign-in. Taps and links are held until the app takes them. The shells do not callopenLinkyet (decision 0141 adds their link delivery), so a magic link, Apple on Android and any provider at an endpoint of its own could never finish. A native build therefore fails with E0402 at each such sign-in its pages' text shows (signIn.sendMagicLink,completeMagicLink,confirmMagicLink, andsignIn.configurefor apple, or with a non-pathauthorizationEndpoint); one the text does not show fails with E0402 on the phone before anything opens (EffectsBridge.receivesLinksis false). Google through Credential Manager, a password, and a provider at a path of the app are unaffected. The refusal ends once the shells callopenLinkand setreceivesLinks(SHELLS_DELIVER_LINKSin emit-native). - A purchase is granted only once it is checked. On Android a purchase counts as bought only when its signature matches the app's Google Play licence key (the
duolith.playLicenceKeyGradle property, or aPurchaseVerifierof the app's own, such as its server) and Play has acknowledged it. Without a key or a verifier, purchases are unavailable and say why. "Already owned" is checked against Play's list of purchases, and one purchase runs at a time. iOS grants only verified StoreKit 2 transactions.
Alternatives considered
| Option | Why not |
|---|---|
| Run PKCE through the provider's page for Apple and Google on every platform | Users expect the system sheets, and Apple's review asks for Sign in with Apple's native button on iOS |
A fake crypto.getRandomValues from Math.random | Predictable verifiers and states defeat PKCE and CSRF protection |
| Keep a "photos" permission for apps that read the library themselves | Nothing in Duolith reads the library, Play restricts the permission, and the picker gives the user's choice with no permission |
| Ship browser-return sign-in and magic links on native now, noted as later shell work | The sign-in would never finish on a phone, with nothing at build time saying so; the owner's rule is to fail loudly |
| Grant a Play purchase without a signature check when no key is set | The app would unlock what anyone can fake; iOS grants only verified transactions |
| The Google Services Gradle plugin | One more plugin, and it fails the Gradle build late with its own message, instead of Duolith's build failing early with a code |
| Keep refusing these effects with E0202 until a device check | The owner asked for everything to work. The device checks are listed in native/DEVICE-CHECKLIST.md |
Consequences
- examples/effects signs in by magic link and imports two mocks, so its native build fails with E0402 and E0432 until the shells deliver links; the
native-effectsfixture (Credential Manager, no mock) builds and runs in Lynx for Web. - The Swift halves have not been compiled; a macOS job must build them.
- Every native behaviour is listed as a device check. The magic-link return, and Apple's on Android, wait on the shells' link delivery (decision 0141), after which a small follow-up calls
openLinkand lifts E0402. - A backend for a real app must accept an ID token (
idToken, with an emptycodeVerifier) as well as a code.