reis-mobile 0.7.3 → 0.8.0

package/skills/mobile-performance/references/kotlin-multiplatform.md

@@ -0,0 +1,62 @@
+# Performance in Kotlin Multiplatform
+
+A KMP performance problem is either **shared Kotlin cost**, which shows up on both targets, or a **target-specific consequence** — the Kotlin/Native binary on iOS, the interop boundary, or the host UI. Deciding which comes first is the whole job: optimizing shared code that is not the bottleneck is wasted work, and so is profiling the Android host for a cost that lives in `commonMain`.
+
+Related material already in this plugin: [`mobile-kmp/references/build-performance.md`](../../mobile-kmp/references/build-performance.md) and [`source-sets.md`](../../mobile-kmp/references/source-sets.md).
+
+## 1. Split shared cost from host cost
+
+Run the same journey on both hosts and compare:
+
+| Observation | Where the cost lives |
+|---|---|
+| Slow on Android and iOS, similar magnitude | Shared Kotlin: algorithm, serialization, database access in `commonMain` |
+| Slow only on iOS | Kotlin/Native: memory management, the Swift/Kotlin bridge, a suspend function crossing into Swift, framework initialization |
+| Slow only on Android | The Android host: Compose recomposition, main-thread work in the ViewModel, `ContentProvider` initializers |
+| Both slow, different symptoms | Two problems. Fix them separately |
+
+Then profile with the host's own tools — there is no KMP profiler. Android Studio Profiler and Macrobenchmark for the Android host ([android.md](android.md)); Instruments for the iOS host ([ios.md](ios.md)), where Kotlin frames appear once the framework's dSYM is available to the trace.
+
+Benchmark the shared code directly where you can: `kotlinx-benchmark` runs the same benchmark on JVM and Native targets, which is the only way to compare the two compilers' output for your algorithm rather than guessing.
+
+## 2. The interop boundary
+
+Every call from Swift into the generated framework crosses a bridge. One call per frame is free; one call per list row per frame is not.
+
+- **Batch the crossing.** Return a whole page of prepared view state in one call instead of exposing a getter per field. The shared layer should expose data already shaped for the screen.
+- **Suspend functions and `Flow` become callbacks in Swift.** Each emission crosses the boundary and hops a dispatcher. A `Flow` that emits per keystroke from shared code into SwiftUI is a per-keystroke bridge crossing plus a SwiftUI update — debounce or conflate in shared code, not in Swift.
+- **Collections cross by conversion.** A Kotlin `List` handed to Swift is bridged; a large list converted on every access is a hidden O(n) per call. Hold the reference, do not re-fetch.
+- **Objective-C interop erases generics and sealed hierarchies**, which pushes Swift callers into exhaustive `switch`es over erased types and sometimes into defensive copies. Design a flat, explicitly-typed API surface at the boundary.
+
+## 3. Kotlin/Native specifics
+
+- The current Kotlin/Native memory manager removes the old freezing rules, so shared mutable state across threads is allowed — but objects still cross into Objective-C autorelease pools, and retain cycles between a Kotlin object and a Swift closure leak exactly like they do in pure Swift. Break them with `[weak self]` on the Swift side and explicit cancellation on the Kotlin side.
+- **Framework initialization is launch cost on iOS.** Anything in a Kotlin top-level property with an initializer, or in a Koin/DI module built at framework load, runs before your first screen. Keep it lazy.
+- **Framework size** counts against the app's download size. Check `isStatic`, dead-code elimination and whether you export more modules than the host actually calls (`export(...)` in the framework block pulls whole modules into the public API and prevents their elimination).
+- Release builds only. Kotlin/Native debug binaries are dramatically slower than release ones, and a "KMP is slow" report measured on a debug framework is a measurement bug.
+
+## 4. Shared code that is usually the bottleneck
+
+- **Serialization.** `kotlinx.serialization` over a large payload on the main dispatcher blocks both hosts. Parse on `Dispatchers.Default`, and parse once — not per screen.
+- **Database access.** SQLDelight queries on the calling thread; map rows lazily and do not materialize a whole table to display twenty rows.
+- **Flow operators.** An unconfined chain of `map`/`combine` re-running on every upstream emission multiplies work across the boundary. `distinctUntilChanged`, `conflate` and `stateIn` with a sharing policy bound to the host lifecycle keep it bounded.
+- **`expect`/`actual` asymmetry.** A cheap JVM implementation and an expensive Native one for the same declaration produces the "slow only on iOS" case above. Measure both actuals.
+
+## 5. Compose Multiplatform UI
+
+When the UI is shared, the Compose performance rules in [android.md](android.md) apply unchanged — stability of parameters, deferred state reads, lazy layouts, `derivedStateOf`. What changes is measurement: the Android host gives you Layout Inspector recomposition counts and composition tracing; on iOS you have Instruments' time profile with Kotlin frames and no recomposition counter, so validate recomposition behaviour on Android and confirm the frame result on iOS.
+
+## 6. Regression detection in CI
+
+- Macrobenchmark on the Android host guards startup and frame time for the shared stack ([android.md](android.md)).
+- `XCTApplicationLaunchMetric` on the iOS host guards framework initialization cost ([ios.md](ios.md)).
+- `kotlinx-benchmark` on JVM and Native guards the shared algorithms themselves, and is the only gate that fails for a shared-code regression before either host notices.
+- Track the produced framework size and the Android AAB size per build; an `export(...)` added to the framework block can move both without any UI change.
+
+## Official documentation
+
+- Kotlin Multiplatform documentation: https://kotlinlang.org/docs/multiplatform.html
+- Kotlin/Native memory management: https://kotlinlang.org/docs/native-memory-manager.html
+- Swift/Objective-C interop: https://kotlinlang.org/docs/native-objc-interop.html
+- kotlinx-benchmark: https://github.com/Kotlin/kotlinx-benchmark
+- Compose Multiplatform: https://www.jetbrains.com/help/kotlin-multiplatform-dev/compose-multiplatform-and-jetpack-compose.html

package/skills/mobile-performance/references/react-native.md

@@ -0,0 +1,85 @@
+# Performance in React Native and Expo
+
+A React Native frame crosses three execution contexts: the **JavaScript thread** (your React code), the **native UI thread**, and — with the New Architecture — the shadow tree and Fabric's rendering pipeline. A slow app is slow in one of them, and the fix differs. Identify the thread first.
+
+Related material already in this plugin: [`mobile-rn/references/performance-release.md`](../../mobile-rn/references/performance-release.md).
+
+## Measure
+
+**Release build, physical device, Hermes enabled.** A Metro dev build carries the dev bundle, React strict-mode double renders, and the bridge dev listeners; its numbers are not the shipped app's.
+
+```bash
+npx react-native run-android --mode=release
+npx expo run:ios --configuration Release
+```
+
+| Question | Tool |
+|---|---|
+| Which React components render, and why | React DevTools Profiler (React Native DevTools), "Highlight updates" |
+| JavaScript CPU time | Hermes sampling profiler via React Native DevTools → Performance, or `.cpuprofile` capture |
+| Frame drops and native thread cost | The platform tools: Perfetto/system trace on Android, Instruments on iOS (see [android.md](android.md) and [ios.md](ios.md)) |
+| Startup cost breakdown | `performance.now()` marks around module require and first render; on Android, `adb shell am start -W` for the whole process |
+| Bundle size and what is in it | `npx react-native bundle --platform android --dev false --sourcemap-output bundle.map` then a source-map explorer; `npx expo export` for Expo |
+
+Instrument your own spans, and keep them in release behind a flag, so the same marks exist in the field:
+
+```js
+const start = performance.now();
+const parsed = parseOrders(payload);
+track('parse_orders_ms', performance.now() - start);
+```
+
+## The JavaScript thread
+
+- **Re-renders are the default problem.** A context value recreated each render, an inline object/array/function prop, or a parent that re-renders on every keystroke will cascade. `React.memo` on the child plus `useCallback`/`useMemo` on the props, or moving the state down so the parent is not involved at all.
+- **Selectors, not whole stores.** Subscribing to an entire Zustand/Redux store re-renders on every change; subscribe to the slice. With React Query/TanStack Query, `select` narrows what a component observes.
+- **Never block JS.** JSON parsing of a large payload, sorting thousands of rows, crypto, image manipulation — these freeze every touch handler. Move them to the native side, a worklet, or chunk them across frames with `InteractionManager.runAfterInteractions` and batched state updates.
+- **Text input and animation state** should not live in React state when they change per frame. Use `Animated` with `useNativeDriver: true`, or Reanimated shared values, so the animation runs on the UI thread and never touches JS.
+
+## Lists
+
+`FlatList`/`SectionList` are virtualized but still render through React. The props that matter:
+
+| Prop | Why |
+|---|---|
+| `keyExtractor` | Stable keys; without them React remounts rows on any change |
+| `getItemLayout` | Skips measurement, enables instant `scrollToIndex` — only valid for fixed-height rows |
+| `initialNumToRender` | Keep it to what a screen actually shows; the default renders more |
+| `maxToRenderPerBatch` / `updateCellsBatchingPeriod` | Trade blank space during fast scrolls against JS work per batch |
+| `windowSize` | How many screens are kept mounted around the viewport |
+| `removeClippedSubviews` | Detaches offscreen native views; helps on Android, test it — it has edge cases with absolute positioning |
+
+Memoize the row component (`React.memo`) and make `renderItem` stable. If the list is long and rows are heavy, `@shopify/flash-list` recycles native views instead of mounting new ones and is usually a larger win than tuning the props above.
+
+## Images
+
+- Size the remote image on the server or CDN; downloading a 3000 px JPEG for a 120 px avatar costs bandwidth, decode time and memory on every row.
+- `expo-image` (or `react-native-fast-image` on bare projects) adds disk/memory caching and progressive loading that the core `Image` does not.
+- Set explicit `width`/`height` so layout does not reflow when the image resolves.
+
+## Startup
+
+- **Enable Hermes** (the default in current React Native). Hermes precompiles to bytecode, which removes JS parse time at launch.
+- **Enable the New Architecture** where the project's dependencies support it: Fabric and TurboModules remove the asynchronous bridge serialization, and TurboModules load lazily instead of all at startup.
+- **Audit top-level requires.** Every module imported at the entry point is evaluated at launch. Lazy-import screens through the navigator's lazy options, and defer SDK initialization until after the first screen.
+- **Native side still counts.** Time to first JS frame includes the Android `Application.onCreate` and the iOS `didFinishLaunching` path; see the native references.
+
+## Bundle and app size
+
+- Inspect the release source map with a source-map explorer to find the heavy dependency. Moment/lodash-style full imports, duplicated polyfills and an icon font shipped whole are the usual entries.
+- On Android, enable Proguard/R8 for the release variant and ship an App Bundle. On iOS, check the App Store Connect size report per device variant.
+- Expo: `expo-updates` OTA payloads are downloaded by every user — size matters there too, and an update that grows the bundle grows every launch that has to apply it.
+
+## Regression detection in CI
+
+- Wrap a scripted journey in Detox or Maestro on a pinned device/emulator, capture the platform's frame data (see [android.md](android.md) and [ios.md](ios.md)), and compare percentiles against a baseline.
+- Assert bundle size in CI: build the release bundle, read its byte size, fail past a percentage delta.
+- `react-native-performance` exposes native startup marks (`nativeLaunchStart`, `runJsBundleStart/End`) as `PerformanceEntry`s, which gives a startup number you can assert on and also report from production.
+
+## Official documentation
+
+- React Native performance overview: https://reactnative.dev/docs/performance
+- Optimizing FlatList configuration: https://reactnative.dev/docs/optimizing-flatlist-configuration
+- Profiling with Hermes and React Native DevTools: https://reactnative.dev/docs/react-native-devtools
+- The New Architecture: https://reactnative.dev/architecture/landing-page
+- Expo performance guidance: https://docs.expo.dev/guides/analyzing-bundles/

package/skills/mobile-release/SKILL.md

@@ -19,10 +19,11 @@ One release process for every mobile stack. This file holds the process and what
 | Native iOS, or the iOS build of any app | [references/ios.md](references/ios.md) |
 | React Native or Expo app | [references/react-native.md](references/react-native.md) |
 | Kotlin Multiplatform shared module and both host apps | [references/kotlin-multiplatform.md](references/kotlin-multiplatform.md) |
+| In-app purchases and subscription lifecycle | [references/billing.md](references/billing.md) |
 | Release notes and store listing text | [references/store-copy.md](references/store-copy.md) |
 | A CI/CD pipeline that builds, signs and uploads | [references/ci-cd.md](references/ci-cd.md) |
 
-Flutter and React Native apps also need the Android and iOS references for signing and store details. Deeper platform guides live in the platform skills: Google Play policy and Play Billing in `mobile-android`, TestFlight and App Store Connect in `mobile-ios`, EAS in `mobile-rn`. Security hardening before release is in `mobile-security`.
+Flutter and React Native apps also need the Android and iOS references for signing and store details. Deeper platform guides live in the platform skills: Google Play policy and Play Billing in `mobile-android`, TestFlight and App Store Connect in `mobile-ios`, EAS in `mobile-rn`. Security hardening before release is in `mobile-security`, and production crash, error and release-health signals are in [mobile-observability](../mobile-observability/SKILL.md).
 
 ## 2. Readiness checklist
 

package/skills/mobile-release/references/billing.md

@@ -0,0 +1,92 @@
+# In-app purchases and subscription lifecycle
+
+Applies to every stack. Billing bugs are expensive in a way other mobile bugs are not: a user who paid and did not receive the entitlement files a store complaint, a chargeback, and a one-star review, and the store holds *you* responsible for the reconciliation. The design that avoids this is the same on both platforms.
+
+## The rule everything follows from
+
+**The client never decides entitlement.** The app's job is to start a purchase and to hand the resulting receipt/token to your backend. The backend verifies it with the store's server, records the entitlement, and answers "what does this user own?". Every screen reads that answer.
+
+An app that grants a feature because a local purchase callback returned success can be defeated with a patched binary, and — more commonly — simply gets it wrong: the callback is missed because the app was killed mid-purchase, or the subscription was cancelled from the store's settings and the app never hears about it.
+
+```
+app ──buy──▶ store ──token/receipt──▶ app ──▶ your backend ──verify──▶ store server
+                                                   │
+ app ◀────── entitlement state ─────────────────────┘
+                                   ▲
+ store server ──server notifications──┘   (renewals, cancellations, refunds, billing retries)
+```
+
+## Server notifications are not optional
+
+The purchase callback covers the moment of purchase. Everything afterwards — a renewal at 3am, a cancellation, a refund, a failed payment entering a retry window, an upgrade, a family-sharing change — happens with the app closed and reaches you only through the store's server-to-server notifications:
+
+- **Google Play:** Real-time developer notifications (Pub/Sub), plus the Google Play Developer API for the authoritative subscription state.
+- **Apple:** App Store Server Notifications V2, plus the App Store Server API and signed transactions.
+
+Without them, a cancelled subscription keeps working until the app next happens to check, and a refunded purchase is never revoked. "We poll on app launch" is not equivalent: the user who cancelled may not open the app for weeks, and a refunded purchase must be revoked immediately.
+
+## The states to model
+
+A subscription is not a boolean. At minimum, entitlement must distinguish:
+
+| State | Behaviour |
+|---|---|
+| Active | Full access |
+| Active, cancelled (will not renew) | Full access until the period ends; a good place to ask why |
+| In a billing retry / grace period | **Keep access** and prompt the user to fix payment — revoking here loses users who would have paid |
+| On hold / suspended | Access revoked, recoverable if payment succeeds |
+| Paused (Android) | Access revoked, scheduled to resume |
+| Expired | No access |
+| Refunded / revoked | Access removed immediately, on the notification |
+| Trial / introductory offer | Active, but the eligibility rules differ and are per-account, not per-device |
+
+Treating anything other than "active" as "no access" is the standard way to break grace periods and lose revenue.
+
+## Purchase acknowledgement
+
+Both stores require the purchase to be consumed or acknowledged, and both **refund automatically** if you do not.
+
+- **Google Play:** a purchase not acknowledged (or consumed, for consumables) within three days is automatically refunded and revoked. Acknowledge only **after** your backend has recorded the entitlement, so a failure to record cannot produce a user who paid and owns nothing.
+- **Apple:** a transaction that is not finished is re-delivered on every launch. Finish it only after the entitlement is recorded — the re-delivery is the recovery mechanism, and finishing early discards it.
+
+The crash-in-the-middle case is the one to test: purchase succeeds, the app is killed before the backend call. On the next launch, the pending purchase must still be visible, sent, recorded and only then acknowledged.
+
+## Restore and multi-device
+
+- A **restore** path is mandatory on iOS (App Review rejects apps without one for non-consumables and subscriptions) and expected everywhere. It must be reachable without being logged in to *your* account if the purchase is tied to the store account.
+- Entitlement follows the **store account**, but your product follows **your** user account. Decide explicitly what happens when they disagree: one store account buying for two of your users, or one of your users signing in on a device with a different store account. This is where fraud and support tickets concentrate; the backend must own the mapping, and it must be enforced there.
+- Prices, currencies and availability come from the store per region. Never hard-code a price string; read it from the product query and display the localized formatted price the store returns.
+
+## Testing
+
+- **Google Play:** licence testers with test payment methods, internal testing track, and shortened subscription periods for renewal testing. Purchases must come from a build uploaded to a track with the same package name and signing key.
+- **Apple:** StoreKit Testing in Xcode (a local `.storekit` configuration file, with time acceleration and error injection — the only practical way to test renewals, billing retry and refunds) and Sandbox accounts for the end-to-end path with real server notifications.
+- Test on the backend, not only in the app: replay a server notification payload and assert the entitlement change. That is the code that actually decides access.
+- Cases worth a test each: purchase interrupted by process death; a refund notification; a cancellation followed by a resubscribe; a user who already owns the product buying again; an expired subscription that renews after a grace period.
+
+## Per-stack notes
+
+| Stack | Client library |
+|---|---|
+| Native Android | Google Play Billing Library — the deep migration and version material is in [`mobile-android/references/play.md`](../../mobile-android/references/play.md) |
+| Native iOS | StoreKit 2 (`Product`, `Transaction`, `Transaction.updates`, `Transaction.currentEntitlements`) — the `Transaction.updates` listener must be started at launch, or transactions completed outside the app are missed |
+| Flutter | `in_app_purchase` (federated, both stores) or a vendor SDK; the purchase stream must be subscribed before the first purchase and on every launch |
+| React Native / Expo | `react-native-iap`, `expo-in-app-purchases` where available, or a vendor SDK; Expo managed projects need a development build — in-app purchases do not work in Expo Go |
+| Kotlin Multiplatform | Billing is host-specific. Keep the entitlement *model* and the backend calls in `commonMain`, and the store client in each host |
+
+A subscription infrastructure vendor (RevenueCat, Adapty and similar) exists precisely because the server-side half above is substantial. Using one is a legitimate decision; it does not remove the need to decide entitlement on a server rather than in the app — it moves that server.
+
+## Store policy
+
+Both stores require that digital content consumed in the app is sold through their billing system, with a narrow and changing set of exceptions that vary by region and by court ruling. Alternative payment links have specific, enforced requirements. Before designing anything that bypasses store billing, read the current policy for the target markets — this is the most volatile area of store policy and the most expensive one to get wrong, since the penalty is removal.
+
+Release-time checks for the store submission itself are in [readiness.md](readiness.md).
+
+## Official documentation
+
+- Google Play Billing: https://developer.android.com/google/play/billing
+- Real-time developer notifications: https://developer.android.com/google/play/billing/getting-ready#configure-rtdn
+- Google Play Developer API, subscriptions: https://developers.google.com/android-publisher/api-ref/rest/v3/purchases.subscriptionsv2
+- StoreKit: https://developer.apple.com/documentation/storekit
+- App Store Server Notifications V2: https://developer.apple.com/documentation/appstoreservernotifications
+- Testing in-app purchases with StoreKit Test: https://developer.apple.com/documentation/xcode/setting-up-storekit-testing-in-xcode

package/skills/mobile-security/SKILL.md

@@ -18,6 +18,7 @@ Organized by the OWASP MASVS categories. Apply the general checks below, then th
 | Native iOS (Swift/Objective-C), or `ios/` in any app | [references/ios.md](references/ios.md) |
 | React Native or Expo | [references/react-native.md](references/react-native.md) |
 | Kotlin Multiplatform shared code and platform implementations | [references/kotlin-multiplatform.md](references/kotlin-multiplatform.md) |
+| OAuth 2.0 / OIDC login, PKCE, tokens and biometric gating, on any stack | [references/auth.md](references/auth.md) |
 
 Firebase-specific protection (security rules, App Check) is covered by `mobile-firebase`.
 
@@ -44,6 +45,8 @@ Every finding needs evidence in the code or configuration at `file:line`. Severi
 - [ ] Sessions without expiration, or refresh tokens never invalidated on logout.
 - [ ] Biometrics used only as a local boolean, without unlocking a key in the Keychain or Keystore.
 
+For anything involving a login flow — OAuth 2.0, OpenID Connect, PKCE, redirect URIs, token rotation or biometric-gated keys — read [references/auth.md](references/auth.md) before reviewing the stack reference.
+
 **MASVS-NETWORK**
 - [ ] `http://` URLs for APIs.
 - [ ] Certificate validation disabled or overridden to accept everything.

package/skills/mobile-security/references/auth.md

@@ -0,0 +1,92 @@
+# OAuth 2.0, OIDC and PKCE in mobile apps
+
+Applies to every stack. A mobile app is a **public client**: it cannot keep a secret, because anything shipped in the binary can be extracted. Every rule here follows from that one fact, and the authoritative source is **RFC 8252, "OAuth 2.0 for Native Apps"**, which the major identity providers implement and enforce.
+
+## The three rules that decide whether the flow is correct
+
+1. **Authorization Code flow with PKCE. Nothing else.** The Implicit flow and the Resource Owner Password Credentials flow are both disallowed for native apps — implicit returns tokens in a redirect where they leak, and ROPC makes the app handle the password, defeats federated login and blocks MFA. If the code sends a username and password to a `/token` endpoint, that is the finding.
+2. **No client secret in the app.** A "confidential" client registration used by a mobile binary is a published secret. Register the app as a public client; PKCE is what replaces the secret.
+3. **The authorization request runs in the system browser, not in a WebView.** RFC 8252 requires an external user-agent — `ASWebAuthenticationSession` on iOS, Custom Tabs on Android — because it shares the system's session (so SSO works), shows the real URL and certificate to the user (so phishing is detectable), and keeps the app out of the credential entry. An embedded `WebView` on the login page gives the app access to the user's typed password and is rejected by most identity providers.
+
+## PKCE, concretely
+
+PKCE (RFC 7636) stops an attacker who intercepts the redirect — a malicious app that registered the same custom scheme, or a log that captured the URL — from exchanging the authorization code.
+
+```
+verifier  = 43–128 chars from [A-Z a-z 0-9 - . _ ~], from a cryptographic RNG
+challenge = BASE64URL( SHA256( verifier ) )     ← method "S256"
+
+/authorize?...&code_challenge=<challenge>&code_challenge_method=S256
+/token     ...&code=<code>&code_verifier=<verifier>
+```
+
+What to check in review:
+
+- [ ] `code_challenge_method` is `S256`. The `plain` method provides no protection and exists only for constrained clients.
+- [ ] The verifier comes from a **cryptographic** random source — `SecureRandom`, `SecRandomCopyBytes`, `Random.secure()`, `crypto.getRandomValues` — never `Math.random()`, a timestamp or a UUID v4 from a non-crypto source.
+- [ ] A fresh verifier per authorization request, held only in memory, discarded after the exchange.
+- [ ] The `state` parameter is present, random, and **verified** on the callback. `state` is CSRF protection and is separate from PKCE; PKCE does not replace it.
+- [ ] With OIDC, the `nonce` is sent and checked against the `nonce` claim in the ID token.
+
+## Redirects
+
+The redirect URI is how the code gets back to the app, and it is the weak point.
+
+- **Prefer verified app links**: `https` App Links on Android (with `assetlinks.json` on the domain) and Universal Links on iOS (with `apple-app-site-association`). These are the only redirect types the OS ties to a domain you own; another app cannot claim them.
+- **Custom schemes are claimable** by any installed app. If one is used, it must be app-specific and unguessable-ish (the reverse-DNS form providers recommend, e.g. `com.example.app:/oauth2redirect`), and PKCE must be present — with PKCE, a stolen code is useless.
+- **Loopback redirects** (`http://127.0.0.1:<port>`) are the desktop pattern and are not appropriate on mobile.
+- Validate the callback: correct `state`, expected issuer, and no code reuse.
+
+## Tokens
+
+- **Storage:** the Keychain on iOS and Keystore-backed storage on Android — never `UserDefaults`, `SharedPreferences`, `AsyncStorage`, a plain file, `localStorage` in a WebView, or the JavaScript bundle. Per-stack APIs are in the platform references of this skill.
+- **Access tokens are short-lived** (minutes to an hour). A long-lived access token is a finding by itself.
+- **Refresh tokens must rotate.** Each refresh returns a new refresh token and invalidates the old one; a reused old token means theft, and the server must revoke the whole family. Rotation with reuse detection is the mobile standard because a public client cannot prove its identity any other way.
+- **Never put a token in a URL**, a log line, an analytics event, a crash-report attribute or a breadcrumb — see [mobile-observability](../../mobile-observability/SKILL.md).
+- **Validate the ID token** if the client uses its claims: signature against the provider's JWKS, `iss`, `aud`, `exp`, and `nonce`. An ID token is proof of authentication for the client; it is **not** an access token and must never be sent to your API as one.
+- **Authorization is the backend's decision.** Claims decoded on the device decide what to render, never what is allowed. A client that reads `role: admin` from a token and unlocks a feature is a client-side authorization finding regardless of how well the token is stored.
+- **Logout** must revoke the refresh token at the provider (`revocation_endpoint`), clear the token store, and end the browser session where the provider supports RP-initiated logout. Deleting the local copy alone leaves a valid session on the server.
+
+## Biometrics do not authenticate to your server
+
+A biometric prompt that returns `true` and unlocks a screen proves nothing to the backend and can be bypassed on a compromised device. Biometrics are correct when they **gate access to a key**: the token or a key that decrypts it is stored with biometric-backed access control (`kSecAccessControlBiometryCurrentSet` on iOS, `setUserAuthenticationRequired` on an Android Keystore key), so failing the prompt makes the data undecryptable rather than just hiding a screen.
+
+Invalidate on enrolment change: adding a fingerprint or face must invalidate the key, or a coerced enrolment grants access.
+
+## Use the platform libraries
+
+Hand-written OAuth is where these mistakes accumulate. Prefer a maintained implementation that already does RFC 8252 correctly, and keep the verifier, `state` and browser handling out of your own code:
+
+| Stack | Typical choice |
+|---|---|
+| Android | AppAuth for Android, or the identity provider's own SDK; Custom Tabs for the browser |
+| iOS | AppAuth for iOS, or the provider's SDK; `ASWebAuthenticationSession` for the browser |
+| Flutter | `flutter_appauth`, or the provider's Flutter SDK; secure storage for tokens |
+| React Native / Expo | `react-native-app-auth`, or `expo-auth-session` (which implements PKCE); never a `WebView` |
+| Kotlin Multiplatform | The host apps own the browser flow; keep only token *use* and refresh scheduling in shared code |
+
+Check what the chosen library defaults to. Some have an option to use an embedded WebView or to disable PKCE for legacy providers — both turn a compliant flow into a non-compliant one silently.
+
+## Review checklist
+
+- [ ] Authorization Code + PKCE (`S256`); no implicit, no password grant.
+- [ ] No client secret in the app, the repository, or the CI configuration that builds it.
+- [ ] System browser (`ASWebAuthenticationSession` / Custom Tabs), not a `WebView`.
+- [ ] Cryptographic RNG for the verifier and `state`; `state` and `nonce` verified.
+- [ ] Redirect URI is an App Link / Universal Link, or an app-specific scheme with PKCE.
+- [ ] Tokens in Keychain/Keystore-backed storage, short-lived access token, rotating refresh token with reuse detection.
+- [ ] No token in logs, URLs, analytics or crash reports.
+- [ ] ID token validated if used; never sent as an access token.
+- [ ] Authorization enforced by the backend on every request.
+- [ ] Logout revokes server-side.
+- [ ] Biometrics gate a key, not a boolean; enrolment changes invalidate it.
+
+## Official documentation
+
+- RFC 8252, OAuth 2.0 for Native Apps: https://datatracker.ietf.org/doc/html/rfc8252
+- RFC 7636, Proof Key for Code Exchange: https://datatracker.ietf.org/doc/html/rfc7636
+- OAuth 2.0 Security Best Current Practice: https://datatracker.ietf.org/doc/html/draft-ietf-oauth-security-topics
+- OpenID Connect Core: https://openid.net/specs/openid-connect-core-1_0.html
+- OWASP MASVS, authentication and session management: https://mas.owasp.org/MASVS/05-MASVS-AUTH/
+- ASWebAuthenticationSession: https://developer.apple.com/documentation/authenticationservices/aswebauthenticationsession
+- Android Custom Tabs: https://developer.chrome.com/docs/android/custom-tabs