reis-mobile 0.7.3 → 0.9.0

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