apk-reverse/references/account-gates.md

# Account gates: sign-in walls, forced binding, guest mode

Load this when the task mentions "no login required", "don't force me to sign in", "skip phone
binding", "guest mode", or when a screen is unreachable without an account — and also **before**
promising that any account- or membership-derived feature will work offline.

This file is mostly about **telling apart two things that look identical in the UI and are completely
different in reality**:

- a **client-side gate** — code that refuses to proceed. Patchable.
- an **account-scoped resource** — the screen is empty because the server sent nothing, because the
  request was made without a valid identity. **Not** patchable.

Confusing the two is how a task ends up "done" while the user stares at an empty page.

## Step 1: classify what you are looking at

| Symptom | Most likely cause | Can a client patch help? |
|---|---|---|
| A dismissible dialog / bottom sheet asking to sign in, then the app works | client-side gate | **yes** |
| A full-screen wall with no dismiss, app unusable | client-side gate | **yes** |
| Screen renders its frame but the list is empty and a "log in to see" hint is drawn | **account-scoped data** | no — the data does not exist locally |
| A specific action (comment, favourite, follow, download) refuses | client-side gate | usually yes |
| The action succeeds locally but reverts on restart / never reaches the server | **server-side identity** | no |
| "Binding required" before an action | client-side gate | **yes** |
| An entitlement appears then disappears | server-side authority | no |

**The deciding question is never "is there a login screen?" — it is "does the thing I want exist
without an identity?"**

Ask it before patching:

- If the content is **fetched per-account** (subscriptions, favourites, reading history, purchased
  items), a patch changes the gate and nothing else. The list stays empty because the server was asked
  for *this account's* items and there is no account.
- If the content is **public** and merely hidden behind a prompt (a reader, a catalogue, a settings
  page), the patch is real and the feature becomes usable.

Reading the code tells you which: follow the "sign in" prompt to what it guards, then look at whether
that guarded path issues a request carrying a token, or touches only local state.

## Step 2: find the convergence point

Sign-in checks are usually concentrated, because a UI cannot meaningfully enforce login at thirty
call sites. Look for a small number of helpers with names in this family:

```
checkLogin*   ensureLogin*   requireLogin*   needLogin*   isLogined*   isLoggedIn*
checkBind*    ensureBind*    requireBind*    needBind*
showLogin*    openLogin*     loginSheet*     loginDialog*
```

and, on the state side, a **login-state field or stream** that every helper reads
(`isLogin`, `loginedStream`, an `Rx<bool>`, an auth-state enum, a credential store wrapper).

**Rule: patch the predicate, not the prompt.** Making the sheet not appear is cosmetic — the caller
still treats the answer as "not signed in" and takes its else-branch, which is usually where the real
feature got skipped. The durable fix is to make the *verdict* come back as "signed in / no sign-in
needed", so the caller takes its happy path.

Two useful shapes, both better than editing the dialog:

| Target | Change | Effect |
|---|---|---|
| the gate predicate used by many callers | return "ok / already signed in" unconditionally | every caller proceeds; no new code path |
| the "should I prompt?" decision inside the helper | return "nothing to do" | the prompt never appears and callers proceed |

Prefer the first when callers branch on the result; prefer the second when the helper is fire-and-forget.

**Count the callers before choosing** (`scripts/find_refs.py`). A predicate with one caller is a
surgical target; a predicate with forty callers is a behavioural change you must reason about — it will
also release flows you were not asked to touch (settings, purchase, upload). That may be fine, but it is
a decision, not a side effect.

### Forced binding specifically

Phone binding is the same pattern with its own helper and usually **two** state checks in series
(bound-phone? and email-or-other-recovery?), because either satisfies the requirement. Patch the
combined verdict, not the first condition — a patch that only satisfies one branch still prompts on the
other.

Watch for a **"skip"/"later" path the app already has**, and for **which actions the binding actually
gates**. Binding is often required for a subset (password change, deletion, payment) while the rest of
the app is unaffected; releasing it globally changes what the app believes about account safety.

## Step 3: what NOT to do

These are the tempting moves that produce a worse artifact than doing nothing:

- **Do not fabricate a session.** Writing a dummy token, a fake credential blob, or a placeholder
  identity into the credential store makes the client *believe* it is signed in. It then calls
  identity-scoped endpoints with garbage, and the app enters a state that is **worse than signed out**:
  screens show an authentication-failure message, or silently return empty data with no explanation.
  A signed-out app that says "please sign in" is better than one that claims a session and fails.
  *(If you touch stored credentials at all, keep a backup and expect to have to restore it.)*
- **Do not delete the sign-in UI.** Removing the entry point does not change the verdict; it only makes
  the failure unexplainable when a caller does branch on it. Keep the entry point working — it is
  normally an explicit requirement ("signing in must still be possible").
- **Do not release gates that protect server-side operations.** If the action's result is an
  entitlement the server must grant (a purchase, a quota, a subscription), releasing the client gate
  only lies to the UI. See `references/membership-and-limits.md`.
- **Do not assume "guest can browse" means "guest can do everything".** Establish per feature which of
  the three states you are in: public, gate-only, or identity-required.

## Step 4: the session-loss problem (this one is unavoidable)

Any change to the signing identity — including a plain reinstall of *your own* build — can invalidate
stored credentials, because they may be sealed with a key held by the platform keystore rather than by
the app.

**What you observe:** the app opens fine, then one subsystem reports it cannot decrypt or unwrap
something, or the user is silently signed out.

**What it means:** the app's private data was carried across an uninstall/reinstall (or restored from a
backup), but the encryption key was destroyed with the app. The ciphertext is now unopenable by anyone.

**What to do:** treat "the user signs in once on the new build" as the expected, documented outcome — not
as a defect to fix. Put it in the delivery notes in one line, together with the fact that a later
upgrade over the *same* signing key can be installed without uninstalling, and therefore will not lose
the session.

**Do not** chase this into the keystore. Restoring the old key is not part of packaging a patched build,
and any workaround that keeps the *old* ciphertext alive while the key is gone is a dead end.

Related and worth knowing: an app may keep the same logical account in **two places** — a plain
preference blob and a sealed store. After a reinstall the plain one survives and the sealed one does
not, which shows up as an account that is half-present (identity fields populated, token empty). That
half-state is a useful diagnostic: it tells you the app reads its identity from the sealed store, which
is exactly the thing you must not try to forge.

## Step 5: verify

The claim to support is narrow and should be stated narrowly.

1. **The prompt does not appear** on a cold start and on the screens that used to show it.
2. **The feature behind it actually works**, not merely "no longer blocked": open the reader, the
   catalogue, the settings page — whatever the gate guarded — and confirm real content or real function.
3. **The sign-in entry still exists and is usable.** Signing in with a real account must still work; that
   is usually part of the request, and it is the thing that proves you patched a gate rather than broke
   authentication.
4. **Signed-in behaviour still works** for a real account, so you can tell the difference between
   "released the gate" and "broke the auth path".
5. **No fake-session artefact is left behind** — check that you did not write anything into the
   credential store or preferences. If you did, remove it and re-verify from a clean install.

State the result as: *"the gate no longer blocks X, from a signed-out state; **the content behind it is
public / the content behind it is per-account and therefore still empty when signed out**."* That second
clause is what stops a client patch from being mistaken for an account.

## Reporting template

```
Gate:             <sign-in sheet | binding prompt | action-scoped check>
Class:            client-side gate  /  account-scoped data (not patchable)
Patch:            <predicate or decision, not the prompt>
Signed-out state: <what works now, per screen>
Signed-in state:  <still works, listing what still requires an account>
Not achievable:   <per-account lists, entitlements — with the reason>
Session note:     sign in once after install; upgrade over the same key keeps the session
```