@sendoracloud/sdk-react-native 1.40.0 → 1.41.0

package/CHANGELOG.md

@@ -1,5 +1,91 @@
 # Changelog
 
+## 1.41.0 — sign-in no longer retires the guest: it is held on the device (ADR-033 wave 1)
+
+**Two semantic changes, both strictly less destructive than before; everything else is additive
+(MINOR under ADR-023 — no signature, storage key, event or status code removed).** Parity: web 3.24.0 /
+iOS 5.4.0 / Android 4.26.0. Law: `docs/decisions/033-sdk-auth-mechanism.md` ("One Slot, Two Verbs").
+
+1. **Sign-in no longer retires the guest — it is held on the device.** A sign-in from a guest session
+   (`signIn`, `loginSocial`, `signInWithGameCenter`/`PlayGames`, `challengeMfa`, `verifyMagicLink`,
+   `verifyEmailOtp`, `consumeSsoFragment`, `signInWith`) never sends `prevAnonRefreshToken`,
+   `linkAnonymous` or `onCredentialInUse` any more, so the server can never delete, adopt or remap the
+   guest as a side effect of a sign-in. Instead the guest's live tokens go into one of five fixed secure
+   slots on the device and the account is installed: `guest_held{userId,count,user}` then ONE
+   `signed_in{cause:'sign_in'}`, no `signed_out`. The guest's server row survives; `getHeldGuests()`
+   lists it; `onDeviceTakeover` / `getLastAnonRetirement()` keep working but no longer fire for this
+   SDK's own sign-ins (`anonRetirement` is `"none"`).
+2. **`link:true` over an identified session attaches or errors — it never switches.**
+   `signInWith*({link:true})` / `loginSocial({link:true})` from an identified session go to
+   `/me/link/*`: an identity already on the account resolves quietly (no event, no revoke, no step-up),
+   one owned elsewhere throws `CredentialInUseError` (or switches when `onCredentialInUse:"adopt"`,
+   holding a guest if there was one), a stale session throws `RECENT_AUTH_REQUIRED`. From a guest it is
+   the same-`sub` promotion it always was (and still emits the legacy `signed_in{cause:'link'}`,
+   §8-Q18); in `signed_out` it is a plain sign-in. `signUp()` from a guest now calls `/me/link/email`
+   (never `/upgrade`); over an identified session it throws `AlreadyIdentifiedError` locally.
+
+**New surface (all additive):**
+- `auth.status(): "unknown" | "signed_out" | "anonymous" | "identified" | "withheld"` and
+  `auth.authStateReady()` (resolves after hydrate, never waits on the network). ⚠ **`status()` is the only
+  way to tell `withheld` (and `unknown`) from `signed_out`** — `getUserSync()` is `null` and `isReady()` is
+  `true` in all three. ⚠ **Consumers MUST default-branch on `AuthStatus`**: a later value ships opt-in-gated
+  or in a MAJOR.
+- Events on `onAuthStateChanged`: `initial{status,user,withheld?}` (replayed once per subscriber, in every
+  status). With a live session (`anonymous` / `identified`) it is FOLLOWED by the same `signed_in{user}`
+  replay 1.28–1.40 sent (no `cause`) — kept, because removing an event is not a MINOR change (ADR-023);
+  `signed_out` / `unknown` / `withheld` get `initial` only,
+  `user_updated{user,cause}`, `guest_held`, `guest_released{userId,reason,endReason?}`,
+  `session_withheld`; `signed_in` gains `cause: 'mint'|'sign_in'|'restore'|'link'`;
+  `signed_out.reason` gains `revoked | evicted | deleted` (the server's own `endReason`).
+- Held guests: `getHeldGuests()`, `getHeldGuest()`, `claimHeldGuest(id?)` (merge INTO the current
+  account — OPTIONAL and destructive; never call it from a backend that does not act on
+  `auth.user_merged`), `restoreHeldGuest(id?)`, `discardHeldGuest(id?)` (a real server delete). `id` may be
+  omitted only when exactly one guest is held (`AMBIGUOUS_HELD_GUEST` otherwise). Errors
+  `HeldGuestLimitError` (the device holds 5 guests), `HeldGuestProjectMismatch`.
+- `init({ autoRestoreHeldGuest })` (default `true`): `ensureSession()` / `signInAnonymously()` in
+  `signed_out` restore the newest eligible held guest instead of minting — visibly
+  (`signed_in{cause:'restore'}` + `guest_released{restored}`); a dead slot is released and the next tried,
+  then it mints in the same call. `signInAnonymously({forceNew:true})` from a guest holds it; at the cap it
+  throws `HeldGuestLimitError` and mutates nothing.
+- `init({ expectedProjectId })` (opt-in project guard): a stored/refreshed/restored session whose JWT
+  `project` claim disagrees is `withheld` — zero storage writes, every verb rejects
+  `AuthError{kind:'config', code:'SESSION_WITHHELD'}`, `getAccessToken*()`/`getRefreshToken()` return
+  `null`; exits are `discardWithheld()` (local only; keeps held guests, the queue and `user_id`) or a
+  relaunch with the matching key. A fresh mint/sign-in that disagrees rejects
+  `AuthError{kind:'config', code:'PROJECT_MISMATCH'}` and revokes the minted token.
+  `getWithheld()`, `Sendora.onIdentityWithheld(cb)`. Absent claim = unknown (never match); explicit
+  `null` = mismatch.
+- Typed verbs: `auth.link(credential): LinkResult` (`done{upgraded,alreadyLinked}` |
+  `credential_in_use{provider,collision,switchAccount(),keepCurrent()}` | `recent_auth_required`) and
+  `auth.signInWith(credential): SignInResult` (`done{previous:{userId,isAnonymous,held},reactivated}` |
+  `mfa_required{verify(code)}`). `switchAccount()` is bound to the refused credential (same payload under
+  5 min; a Game Center credential is re-fetched after that and a changed player aborts
+  `CREDENTIAL_CHANGED`).
+- `deleteAccount({ alsoDiscardHeldGuests })` → `{ ..., heldGuests, discardFailed }`. By default held guests
+  SURVIVE on device and server with auto-restore suppressed (explicit `restoreHeldGuest(id)` only).
+- `Sendora.reset({ includeHeldGuests })`: `reset()` now KEEPS held guests (a guest's refresh token is its
+  only credential); the option releases them locally (`guest_released{reason:'reset'}`, no server delete).
+  The clear is an exact key list of the active namespace, no longer a `startsWith(prefix)` sweep.
+- `merge(token)` (deprecated) routes a token that matches a held slot to `claimHeldGuest()`; otherwise the
+  raw `/merge` as before. `getRefreshToken()` kept (null in `withheld`).
+- `POST /anonymous` carries a per-attempt `mintKey` (a retried mint after a crash returns the same guest).
+- Bearer verbs (`enrollMfa`, `disableMfa`, `listMySessions`, `revokeSession`, `revokeAllSessions`,
+  `sendVerificationEmail`) now refresh an expired access token first (parity with web).
+
+**On disk (additive, ADR-023):** the four frozen keys keep their format and are written on every install
+(a 1.40.0 downgrade reads a valid session; held slots are simply ignored). New keys: `auth_session`
+(single-record form, read first on hydrate, written forward from the frozen keys on the first 1.41 launch —
+no network, same status), `auth_held_0..auth_held_4` (literal names, in `SECURE_KEYS`, so they route through
+your `secureStorage` adapter), `auth_mint_key` (non-secret, removed on a successful mint).
+`sendora_schema_version` → `"2"` (never bumped in a withheld hydrate).
+The four frozen keys stay the authority on whether a session exists: if a downgraded 1.40.x signs out
+(it clears only the four keys), the next 1.41 launch discards the leftover `auth_session` instead of
+reinstalling it.
+
+Guards: `test/auth-machine-conformance.test.ts` replays the shared ADR-033 table (36 rows + 19 project-verdict
+cases from `packages/shared`); `test/held-guests.test.ts` (ADR §5 tests 1–13, the refresh-during-native-sheet
+interleaving, dual-write/downgrade, the B15 held report, `merge()` routing). Mutation record in `CLAUDE.md`.
+
 ## 1.40.0 — signInAnonymously() no longer replaces a signed-in account; CHANGELOG ships in the package
 
 **Behaviour change (reported by RopoLabs, verified against the shipped bundle).**

package/README.md

@@ -192,38 +192,90 @@ Full paste-ready recipes live in [`examples/links-share.tsx`](./examples/links-s
 
 `SendoraCloud.auth` covers anonymous sign-in, email + password, magic link, email OTP, TOTP MFA, recovery codes, OIDC / SAML SSO, Sign in with Apple, Google, Microsoft, LinkedIn, Facebook, Discord. See [auth quickstart](https://sendoracloud.com/docs/quickstart-react-native#auth).
 
-### Anonymous → identified lifecycle
+### Auth status — `status()` is the only way to tell `withheld` from `signed_out`
 
-The SDK creates an anonymous user on first `init()`. Every `track()` / `identify()` attaches to that `user_id` until the user signs up or signs in. Two transitions exist; both preserve analytics continuity, but the second one requires one extra line of code from your app:
+```ts
+await SendoraCloud.auth.authStateReady(); // resolves after the disk hydrate; never waits on the network
+switch (SendoraCloud.auth.status()) {
+  case "anonymous":  /* a guest session */ break;
+  case "identified": /* a signed-in account */ break;
+  case "signed_out": /* no session */ break;
+  case "unknown":    /* a refresh token exists but the user is not known yet */ break;
+  case "withheld":   /* the stored session belongs to another project — see below */ break;
+  default:           /* ⚠ REQUIRED: a later SDK may add a status (opt-in gated or in a MAJOR) */ break;
+}
+```
+
+`getUserSync()` is `null` and `isReady()` is `true` in `signed_out`, `unknown` AND `withheld` — only
+`status()` tells them apart. Always keep a `default` branch.
 
-**Case 1 — fresh signup.** `auth.signUp(email, password)` detects the anonymous refresh token and calls `/auth-service/upgrade` first, which flips `is_anonymous=false` + sets the password on the SAME row. The `user_id` is preserved — no funnel break. Falls back to a fresh `/signup` if the bound user is already identified (rare race).
+### Anonymous → identified (1.41.0, ADR-033 "One Slot, Two Verbs")
+
+The SDK creates an anonymous (guest) user on first `ensureSession()` / `signInAnonymously()`. From there
+there are exactly two verbs:
+
+**Link — the only upgrade (same `user.id`).** `signUp(email, password)` from a guest attaches the email to
+the SAME row (`/me/link/email`) — the id is preserved, no funnel break. `signInWith*({ link: true })`,
+`loginSocial({ link: true })`, `link*()` and the typed `auth.link(credential)` do the same for a social /
+Game Center / Play Games identity. Over an already-identified session `link:true` **attaches or errors —
+it never switches accounts**:
 
 ```ts
-const { user } = await SendoraCloud.auth.signUp(email, password);
-// user.id === the same id the anon user had. Done.
+const r = await SendoraCloud.auth.link({ kind: "gameCenter", ...payload });
+switch (r.status) {
+  case "done": /* r.upgraded (guest promoted) / r.alreadyLinked (nothing changed) */ break;
+  case "credential_in_use": // owned by another account — nothing changed
+    // await r.switchAccount()  → sign in to that account (bound to THIS credential); or r.keepCurrent()
+    break;
+  case "recent_auth_required": /* re-authenticate, then retry */ break;
+}
 ```
 
-**Case 2 — email already exists.** `signUp()` throws `EmailAlreadyTakenError` without consuming the anon refresh. You fall back to `signIn()` — but `signIn()` wipes the local anon identity, so anon events stay orphaned on the backend unless you transfer them with `auth.merge(anonRefresh)`. Capture the anon refresh BEFORE the signIn:
+`signUp()` over an identified session throws `AlreadyIdentifiedError` locally; an email already owned by
+another account throws `EmailAlreadyTakenError`.
 
-```ts
-try {
-  const { user } = await SendoraCloud.auth.signUp(email, password);
-} catch (err) {
-  if (!(err instanceof EmailAlreadyTakenError)) throw err;
+**Sign in — a switch that HOLDS the guest.** `signIn()`, `loginSocial()`, `signInWithGameCenter()` /
+`PlayGames()`, magic link, email OTP, SSO and `auth.signInWith(credential)` never delete, adopt or merge
+the guest any more. The guest's live tokens are **held on the device** (up to 5) and the account is
+installed: `guest_held{userId,count}` then ONE `signed_in{cause:'sign_in'}` (no `signed_out`). The guest's
+server row survives.
 
-  const anonRefresh = await SendoraCloud.auth.getRefreshToken();
-  const { user } = await SendoraCloud.auth.signIn(email, password);
+### Held guests
 
-  // Best-effort, silent-fail-tolerant — anon row may be already drained.
-  if (anonRefresh) {
-    SendoraCloud.auth.merge(anonRefresh).catch(() => undefined);
-  }
-}
+```ts
+const held = SendoraCloud.auth.getHeldGuests();      // newest first: [{ userId, heldAt, ... }]
+await SendoraCloud.auth.restoreHeldGuest(id);         // sign back in AS the guest (current account is held if it was a guest)
+await SendoraCloud.auth.discardHeldGuest(id);         // delete the guest server-side (real erasure)
+await SendoraCloud.auth.claimHeldGuest(id);           // OPTIONAL + destructive: merge the guest INTO the current account
 ```
 
-**Why merge isn't automatic on signIn.** Two people sharing a device (browser kiosk, family iPad) would silently get their anon-session events combined with a third party's real account. Forcing the merge call into your app keeps the data-mixing decision explicit. Wrap `signIn()` with the snippet above if you want auto behaviour.
+- `id` may be omitted only when exactly one guest is held (else `AMBIGUOUS_HELD_GUEST`).
+- `claimHeldGuest()` reassigns Sendora-side data and deletes the guest row (fires `auth.user_merged`); it
+  does not touch YOUR backend's data keyed on the guest id. **Never call it from an app whose backend does
+  not act on `auth.user_merged`** — most apps should restore or discard instead.
+- `init({ autoRestoreHeldGuest })` (default `true`): `ensureSession()` in `signed_out` restores the newest
+  held guest instead of minting, visibly (`signed_in{cause:'restore'}` + `guest_released{reason:'restored'}`).
+  A dead slot is released (`guest_released{reason:'dead'}`) and the next tried, then it mints.
+- `signInAnonymously({ forceNew: true })` from a guest holds it; with 5 held it throws `HeldGuestLimitError`.
+- `deleteAccount()` keeps held guests (never auto-restored afterwards);
+  `deleteAccount({ alsoDiscardHeldGuests: true })` deletes them too.
+- `SendoraCloud.reset()` keeps held guests (a guest's refresh token is its only credential);
+  `reset({ includeHeldGuests: true })` releases them locally (no server delete).
+- The deprecated `merge(token)` routes a token matching a held guest to `claimHeldGuest()`.
+
+### Project guard (`expectedProjectId`, opt-in)
+
+```ts
+await SendoraCloud.init({ apiKey, projectId: PROJECT_ID, expectedProjectId: PROJECT_ID });
+```
 
-Full reference + edge-case writeup: [/docs/quickstart-react-native#anon-existing-email](https://sendoracloud.com/docs/quickstart-react-native#anon-existing-email).
+A stored, refreshed or restored session whose JWT `project` claim names a different project is
+**`withheld`**: nothing is written to storage, every auth verb rejects
+`AuthError{ kind: 'config', code: 'SESSION_WITHHELD' }`, `getAccessToken()` returns `null`, and
+`auth.getWithheld()` says whose session it was. Exits: relaunch with the matching key, or
+`auth.discardWithheld()` (clears the session only — held guests, the event queue and the analytics id are
+kept). A freshly minted / signed-in session that disagrees is rejected with `PROJECT_MISMATCH` and revoked.
+Subscribe with `SendoraCloud.onIdentityWithheld(cb)` to record the old user id before discarding.
 
 ## Config
 
@@ -240,6 +292,8 @@ Full reference + edge-case writeup: [/docs/quickstart-react-native#anon-existing
   androidPackageName?: string;
   linkDomain?: string;          // Custom share host (e.g. "pulse.link"). Defaults to Sendora's.
   debug?: boolean;
+  expectedProjectId?: string;    // ADR-033 project guard (opt-in) — see "Project guard".
+  autoRestoreHeldGuest?: boolean; // Default true — see "Held guests".
 }
 ```
 
@@ -249,9 +303,9 @@ This SDK is on the **1.x line**. Patch bumps (1.x.y → 1.x.z) are backwards-com
 
 ### Auth state is a transition stream, not a health signal
 
-`auth.onAuthStateChanged()` reports confirmed transitions only — `signed_in`, `signed_out` (reason `user` | `session_expired` | `account_deleted`), `device_takeover`, `deletion_cancelled`. A transient failure of the background token refresh (offline, timeout, HTTP 429, 5xx) emits **nothing**: the stored refresh token is kept and the refresh retried with backoff, so no state changed. "No event" means "no confirmed transition", never "the session is fine". Only a server-rejected refresh token produces `signed_out(session_expired)`. For liveness, read `getAccessToken()` — `null` means no usable token right now.
+`auth.onAuthStateChanged()` reports confirmed transitions only — `signed_in` (`cause`: `mint` | `sign_in` | `restore` | `link`), `signed_out` (reason `user` | `session_expired` | `account_deleted` | `revoked` | `evicted` | `deleted`), `user_updated`, `guest_held`, `guest_released`, `session_withheld`, `device_takeover`, `deletion_cancelled`. Each subscriber first receives one `initial{status, user}` (1.41.0); with a live session it is followed by the same `signed_in{user}` replay 1.28–1.40 sent (no `cause`), so existing listeners keep working. New code: read `initial` and treat a cause-less `signed_in` right after it as the replay. A transient failure of the background token refresh (offline, timeout, HTTP 429, 5xx) emits **nothing**: the stored refresh token is kept and the refresh retried with backoff, so no state changed. "No event" means "no confirmed transition", never "the session is fine". Only a server-rejected refresh token produces `signed_out(session_expired)`. For liveness, read `getAccessToken()` — `null` means no usable token right now.
 
-`signInAnonymously()` returns the **current** session when one exists, anonymous or identified — it never replaces a signed-in account with a guest. Pass `forceNew: true` to deliberately abandon whatever session is current and mint a fresh anonymous one.
+`signInAnonymously()` returns the **current** session when one exists, anonymous or identified — it never replaces a signed-in account with a guest. Pass `forceNew: true` to deliberately leave the current session and mint a fresh anonymous one (a guest left this way is held, not lost).
 
 ## JWT verification (custom backend)