Duolith docs

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

  1. 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) gains idToken?: string; in that case codeVerifier is "" 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 returned state (E0225).
  2. An endpoint or redirect written as a path is a screen of the app. authorizationEndpoint: "/mock-provider" and redirectUri: "/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.
  3. 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 no Math.random fallback: without the bridge, sign-in fails.
  4. 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 in permissions.yaml declares any other permission an app asks for by name (decision 0102).
  5. Declarations grow entitlements and removals. A catalogue declaration may carry iOS entitlements: aps-environment for push, and com.apple.developer.applesignin for 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 to native/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 exported FirebaseInstanceIdReceiver; Credential Manager's exported RevocationBoundService; 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 as tools:node="remove". Only what is marked is ever removed: ACCESS_NETWORK_STATE stays for push (Firebase needs it) and for connection, which lists it itself.
  6. **Push on Android needs google-services.json at 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's dev.duolith.shell until the app manifest of decision 0141 gives it its own), it fails with E0401.
  7. 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 call openLink yet (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, and signIn.configure for apple, or with a non-path authorizationEndpoint); one the text does not show fails with E0402 on the phone before anything opens (EffectsBridge.receivesLinks is false). Google through Credential Manager, a password, and a provider at a path of the app are unaffected. The refusal ends once the shells call openLink and set receivesLinks (SHELLS_DELIVER_LINKS in emit-native).
  8. 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.playLicenceKey Gradle property, or a PurchaseVerifier of 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

OptionWhy not
Run PKCE through the provider's page for Apple and Google on every platformUsers 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.randomPredictable verifiers and states defeat PKCE and CSRF protection
Keep a "photos" permission for apps that read the library themselvesNothing 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 workThe 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 setThe app would unlock what anyone can fake; iOS grants only verified transactions
The Google Services Gradle pluginOne 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 checkThe 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-effects fixture (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 openLink and lifts E0402.
  • A backend for a real app must accept an ID token (idToken, with an empty codeVerifier) as well as a code.