@chipmobilesdk/rn-auth 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -3,6 +3,48 @@
 All notable changes to `@chipmobilesdk/rn-auth` are documented here. This project
 adheres to [Semantic Versioning](https://semver.org/).
 
+## [0.3.0] - 2026-11-01
+
+Minor release fixing session integrity. Two type changes can need a one-line code
+change (see Changed): `signOutGlobal()` resolves to a result instead of `void`, and
+`OidcTokens.refreshToken` / `idToken` are optional.
+
+### Fixed
+
+- **A sign-out during a token refresh no longer revives the session.** The refresh
+  wrote its refresh token back into memory and set the state to `authenticated`
+  after the sign-out. Every session start and end now bumps a session generation,
+  and work that crossed one is discarded.
+- **Rotated refresh tokens are persisted.** A rotation only reached memory, so a
+  restart came back with a token the provider may already have retired. Concurrent
+  `requestAccessToken` calls for one resource now share one network refresh, and a
+  cache hit no longer flashes `token-refreshing`.
+- **Restore deletes the stored session only on an `invalid_grant` verdict.** Any
+  error other than a recognised network failure used to delete it, so a timeout or a
+  5xx signed users out. Errors are classified by OAuth and AADSTS codes in an ordered
+  table (`oidc/classifyError.ts`) instead of loose substrings; unclassified errors
+  restore `offline`.
+- **Restore no longer stays `loading`** when the Keychain write fails, and keeps the
+  stored profile when a refresh returns no id token.
+- **Sign-in commits only what it stored.** A failed Keychain write left a refresh
+  token in memory under an `error` state; an authorize without a refresh token now
+  reports a developer-facing `configuration-error` instead of a session that never
+  survives a restart.
+- **`signOutGlobal()` sends the id token hint** and reports a failed end-session
+  instead of swallowing it.
+- **A throwing state listener no longer turns a completed sign-in into an error.**
+- **The development-only `console.warn` of the raw native error is removed.** It
+  bypassed redaction.
+
+### Changed
+
+- `signOutGlobal()` resolves to `GlobalSignOutResult` (`{ global: 'ended' | 'failed',
+  error? }`) instead of `void`.
+- `OidcTokens.refreshToken` and `OidcTokens.idToken` are optional; a provider that
+  omits them is reported as absent rather than as an empty string. The persisted
+  session artifact gains an optional `idToken`; artifacts written by 0.2.1 still
+  restore.
+
 ## [0.2.0] - 2026-06-30
 
 Add Facebook as a social sign-in provider (additive, backward compatible).

package/README.md

@@ -6,16 +6,16 @@ Code + PKCE, **no backend, no client secret**). Android presents **Continue with
 Google**, iOS presents **Continue with Apple**, and either platform can also
 present **Continue with Facebook**; all start the same External ID
 sign-up/sign-in user flow, routed to the right social provider with a
-`domain_hint`. Google, Apple, and Facebook are federated **inside the External ID
-tenant**, so the app embeds no native social SDK and no Sign in with Apple
-entitlement. Each platform renders all of its configured providers as separate
-buttons in configuration order.
-
-> **License:** `UNLICENSED`. Published publicly for use by the owner's
-> applications; no open-source license is granted.
-
-- **Version**: `0.2.0`
-- **Entrypoint**: `@chipmobilesdk/rn-auth`
+`domain_hint`. Google, Apple, and Facebook are federated **inside the External ID
+tenant**, so the app embeds no native social SDK and no Sign in with Apple
+entitlement. Each platform renders all of its configured providers as separate
+buttons in configuration order.
+
+> **License:** `UNLICENSED`. Published publicly for use by the owner's
+> applications; no open-source license is granted.
+
+- **Version**: `0.3.0`
+- **Entrypoint**: `@chipmobilesdk/rn-auth`
 
 - Single active account, session restore, local + global sign-out.
 - Per-resource delegated access tokens for Azure resources.
@@ -79,6 +79,19 @@ Hooks: `useAuth()` (state + `signIn`/`signOut`/`signOutGlobal`/`restore`/`requir
 `useSignInProviders()` (all platform providers, in config order — map to one
 button each) and `useSignInProvider()` (first available, for a single-button UI).
 
+### Session lifecycle guarantees
+
+- **Restore deletes the stored session only when the provider rejects the refresh
+  token** (`invalid_grant` and the equivalent AADSTS codes). A timeout, a 5xx or an
+  error the package cannot classify restores `offline`: cached profile, tier
+  unverified, retried on the next `restore()`.
+- **A sign-out wins.** A token refresh still in flight when the user signs out is
+  discarded; it cannot write a token back or return the state to `authenticated`.
+- **Rotated refresh tokens are persisted** as soon as they arrive, and concurrent
+  `requestAccessToken` calls for one resource share one network refresh.
+- **`signOutGlobal()` returns `{ global: 'ended' | 'failed', error? }`.** Local state
+  is cleared either way; `failed` means the tenant session may still be alive.
+
 ## Configuration contract (LIB-010)
 
 The library accepts **public values only**. Provider secrets, Apple keys, and
@@ -126,7 +139,7 @@ can sign users in:
 - [ ] iOS: because Facebook is a third-party login, keep Sign in with Apple offered on iOS (Apple guideline 4.8).
 - [ ] Update Apple App Privacy and Google Play Data Safety to include Facebook as an identity provider before release.
 
-## Security & privacy
+## Security & privacy
 
 - Tokens and refresh artifacts persist only in `SecureTokenStore` (Keychain /
   Keystore). Access tokens are kept in memory only.
@@ -135,43 +148,43 @@ can sign users in:
 - Diagnostics (`AuthError`) never contain secrets or token values.
 - Authentication and profile data are collected and transmitted to the
   identity providers and configured Azure resources — update Apple App Privacy
-  and Google Play Data Safety before release.
-
-## Public API
-
-Everything below is exported from `@chipmobilesdk/rn-auth`; deep imports into
-`config/`, `core/`, `tokens/`, `oidc/`, `access/`, `diagnostics/`, or `react/`
-are unsupported.
-
-- Controller and configuration: `createAuth`, `Auth`, `AuthConfig`,
-  `CreateAuthOptions`, `AuthState`, `AuthStatus`, `RestoreStatus`
-- Identity and access: `Profile`, `ProviderConfig`, `ProviderIdentity`,
-  `ResourceConfig`, `AccessTier`, `AccessTierMapping`, `AccessTokenResult`,
-  `PremiumGateResult`, `evaluateAccessTier`, `failClosedTier`
-- Ports and default adapters: `SecureTokenStore`, `createKeychainSecureStore`,
-  `AUTH_STORAGE_KEY`, `OidcAuthClient`, `createAppAuthClient` and the public OIDC
-  request/token types
-- React: `AuthProvider`, `useAuth`, `useProfile`, `useAccessTier`,
-  `useAccessToken`, `useSignInProvider`, `useSignInProviders`
-- Diagnostics and copy: `AuthError`, `AuthConfigError`, `isAuthError`, `redact`,
-  `DEFAULT_MESSAGES`, `resolveMessages` and their public code/message types
-
-## Compatibility and validation
-
-React ≥19 · React Native ≥0.85 · `react-native-app-auth` ≥8 ·
-`react-native-keychain` ≥10 · iOS + Android · Node ≥22.11 for tooling.
-
-The demo integration lives in `src/screens/AuthDemoScreen.tsx`. Run from the
-repository root:
-
-```bash
-npm run typecheck:auth
-npm run pack:auth
-npm run validate:auth
-```
-
-## Distribution and license
-
-Published as a public npm package (`publishConfig.access: public`) for use by
-the owner's applications. License: `UNLICENSED`; no open-source license is
-granted.
+  and Google Play Data Safety before release.
+
+## Public API
+
+Everything below is exported from `@chipmobilesdk/rn-auth`; deep imports into
+`config/`, `core/`, `tokens/`, `oidc/`, `access/`, `diagnostics/`, or `react/`
+are unsupported.
+
+- Controller and configuration: `createAuth`, `Auth`, `AuthConfig`,
+  `CreateAuthOptions`, `AuthState`, `AuthStatus`, `RestoreStatus`
+- Identity and access: `Profile`, `ProviderConfig`, `ProviderIdentity`,
+  `ResourceConfig`, `AccessTier`, `AccessTierMapping`, `AccessTokenResult`,
+  `PremiumGateResult`, `evaluateAccessTier`, `failClosedTier`
+- Ports and default adapters: `SecureTokenStore`, `createKeychainSecureStore`,
+  `AUTH_STORAGE_KEY`, `OidcAuthClient`, `createAppAuthClient` and the public OIDC
+  request/token types
+- React: `AuthProvider`, `useAuth`, `useProfile`, `useAccessTier`,
+  `useAccessToken`, `useSignInProvider`, `useSignInProviders`
+- Diagnostics and copy: `AuthError`, `AuthConfigError`, `isAuthError`, `redact`,
+  `DEFAULT_MESSAGES`, `resolveMessages` and their public code/message types
+
+## Compatibility and validation
+
+React ≥19 · React Native ≥0.85 · `react-native-app-auth` ≥8 ·
+`react-native-keychain` ≥10 · iOS + Android · Node ≥22.11 for tooling.
+
+The demo integration lives in `src/screens/AuthDemoScreen.tsx`. Run from the
+repository root:
+
+```bash
+npm run typecheck:auth
+npm run pack:auth
+npm run validate:auth
+```
+
+## Distribution and license
+
+Published as a public npm package (`publishConfig.access: public`) for use by
+the owner's applications. License: `UNLICENSED`; no open-source license is
+granted.

package/package.json

@@ -1,9 +1,9 @@
 {
 	"name": "@chipmobilesdk/rn-auth",
-	"version": "0.2.0",
-	"private": false,
-	"license": "UNLICENSED",
-	"main": "src/index.ts",
+	"version": "0.3.0",
+	"private": false,
+	"license": "UNLICENSED",
+	"main": "src/index.ts",
 	"types": "src/index.ts",
 	"exports": {
 		".": {
@@ -21,6 +21,7 @@
 		"src/access",
 		"src/diagnostics",
 		"src/react",
+		"skills",
 		"README.md",
 		"CHANGELOG.md"
 	],
@@ -46,8 +47,8 @@
 	"engines": {
 		"node": ">=22.11.0"
 	},
-	"publishConfig": {
-		"access": "public",
-		"registry": "https://registry.npmjs.org/"
-	}
-}
+	"publishConfig": {
+		"access": "public",
+		"registry": "https://registry.npmjs.org/"
+	}
+}

package/skills/sdk-rn-auth/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: sdk-rn-auth
+description: "Authentication via @chipmobilesdk/rn-auth: OIDC/AppAuth login, keychain token storage, access tiers, auth error handling. Use when wiring sign-in, storing tokens securely, gating features by tier, or configuring a tenant/provider."
+metadata:
+  package: "@chipmobilesdk/rn-auth"
+  packageVersion: "0.2.0"
+user-invocable: true
+disable-model-invocation: false
+---
+
+# @chipmobilesdk/rn-auth
+
+OIDC authentication with secure token storage and an access-tier model for
+feature gating.
+
+## Use this when
+
+- Wiring sign-in / sign-out
+- Persisting tokens (must be keychain, never plain storage)
+- Gating a feature on the user's access tier
+- Mapping an auth failure to a user-facing message
+- Onboarding a new tenant or identity provider
+
+## Configuration is a contract, not options
+
+Tenant and provider setup has prerequisites that fail at runtime, not at build time.
+Before configuring anything, walk `## Configuration contract (LIB-010)` and
+`## Tenant / provider prerequisite checklist (LIB-018)` in the README. Skipping the
+checklist is the usual cause of "login works locally, fails in the new environment".
+
+## Fail closed
+
+`failClosedTier` exists because an unknown tier must deny access, not grant it. When
+tier evaluation is unavailable, deny. Never default an unresolved tier to a permissive
+value.
+
+## Public API (v0.3.0)
+
+Runtime:
+
+- `createAppAuthClient(...)` — the OIDC client
+- `createKeychainSecureStore(...)` — token persistence; `AUTH_STORAGE_KEY`
+- `evaluateAccessTier(...)`, `failClosedTier` — feature gating
+- `AuthProvider` — React context provider
+
+Types: `SecureTokenStore`, `AuthProviderProps`, `AuthErrorCode`, `AuthErrorAudience`,
+`AuthMessageMap`, `AuthMessageKey`
+
+`AuthErrorAudience` distinguishes what may be shown to a user from what is diagnostic
+only — never render a diagnostic-audience message in the UI.
+
+## Where the detail lives
+
+Read one section of `node_modules/@chipmobilesdk/rn-auth/README.md`:
+
+| Need | Section |
+|---|---|
+| First integration | `## Install (consuming app)`, `## Quick start` |
+| Required config fields | `## Configuration contract (LIB-010)` |
+| New tenant or IdP | `## Tenant / provider prerequisite checklist (LIB-018)` |
+| Token handling, logging rules | `## Security & privacy` |
+| Full export list | `## Public API` |
+| Version/peer constraints | `## Compatibility and validation` |

package/src/config/types.ts

@@ -124,6 +124,17 @@ export interface PremiumGateResult {
 	tier: AccessTier;
 }
 
+/**
+ * What `signOutGlobal` did beyond the device (added in 0.2.2). Local state is
+ * cleared either way; `failed` means the tenant session may still be alive, so
+ * the next interactive sign-in can complete without a password prompt.
+ */
+export interface GlobalSignOutResult {
+	global: 'ended' | 'failed';
+	/** Present when `global` is `failed`. Redacted like every AuthError. */
+	error?: AuthError;
+}
+
 /** The auth controller returned by `createAuth` (single active account). */
 export interface Auth {
 	getState(): AuthState;
@@ -131,7 +142,7 @@ export interface Auth {
 	restore(): Promise<AuthState>;
 	signIn(providerId: ProviderId): Promise<AuthState>;
 	signOut(): Promise<void>;
-	signOutGlobal(): Promise<void>;
+	signOutGlobal(): Promise<GlobalSignOutResult>;
 	requestAccessToken(resourceKey: string): Promise<AccessTokenResult>;
 	getAccessTier(): AccessTier;
 	/** Gate a premium-only path; enters `access-denied` when unverified (FR-011). */

package/src/core/authMachine.ts

@@ -2,6 +2,11 @@
  * Auth state machine / orchestrator (FR-005, FR-022, R5, R7). Holds the single
  * active session, wires the OidcAuthClient + SecureTokenStore ports, profile
  * mapping, access-tier evaluation, per-resource tokens, restore, and sign-out.
+ *
+ * Every operation that starts or ends a session bumps `sessionEpoch`. Work that
+ * awaited across such a change — a token refresh, a restore, an authorize —
+ * compares the epoch it started with before writing anything back, so a sign-out
+ * can never be undone by a request that was already in flight.
  */
 
 import { Platform } from 'react-native';
@@ -11,6 +16,7 @@ import type {
 	AuthState,
 	CreateAuthOptions,
 	DevicePlatform,
+	GlobalSignOutResult,
 	PremiumGateResult,
 	Profile,
 	ProviderId,
@@ -25,10 +31,18 @@ import {
 } from '../oidc/socialRouting';
 import { mapClaimsToProfile } from './profile';
 import { evaluateAccessTier, failClosedTier } from '../access/accessTier';
-import { restoreSession } from './session';
+import { restoreSession, type PersistedSession } from './session';
 import { AUTH_STORAGE_KEY } from '../tokens/secureStore';
 import { createAccessTokenManager } from '../tokens/accessToken';
-import { toAuthError } from '../diagnostics/errors';
+import { AuthError, toAuthError } from '../diagnostics/errors';
+
+const SIGNED_OUT: Partial<AuthState> = {
+	status: 'signed-out',
+	profile: undefined,
+	accessTier: undefined,
+	restore: 'unavailable',
+	error: undefined,
+};
 
 export function createAuthMachine(
 	config: AuthConfig,
@@ -45,7 +59,32 @@ export function createAuthMachine(
 
 	let state: AuthState = { status: 'loading', restore: 'pending' };
 	let refreshToken: string | null = null;
+	/** Kept for the end-session `id_token_hint`; without it a global sign-out is a no-op. */
+	let idToken: string | null = null;
+	let sessionEpoch = 0;
 	const listeners = new Set<(state: AuthState) => void>();
+	/**
+	 * Every Keychain write and delete, in order. A rotation persisted while a
+	 * sign-out runs must not land after the sign-out's delete and resurrect the
+	 * session on the next launch.
+	 */
+	let storeQueue: Promise<void> = Promise.resolve();
+
+	const enqueueStoreOp = (op: () => Promise<void>): Promise<void> => {
+		const next = storeQueue.then(op);
+		// The queue itself never rejects, so one failed write does not poison the
+		// writes after it; the caller still sees its own failure through `next`.
+		storeQueue = next.catch(() => undefined);
+		return next;
+	};
+
+	const writeSession = (session: PersistedSession, epoch: number): Promise<void> =>
+		enqueueStoreOp(async () => {
+			if (epoch !== sessionEpoch) {
+				return; // The session this belonged to has already ended.
+			}
+			await secureStore.setItem(AUTH_STORAGE_KEY, JSON.stringify(session));
+		});
 
 	const tokenManager = createAccessTokenManager({
 		authority: config.authority,
@@ -54,8 +93,28 @@ export function createAuthMachine(
 		resources,
 		authClient,
 		getRefreshToken: () => refreshToken,
-		setRefreshToken: token => {
+		sessionEpoch: () => sessionEpoch,
+		async onRefreshTokenRotated(token, epoch) {
+			if (epoch !== sessionEpoch) {
+				return;
+			}
+			// Live immediately whatever happens to the write: the provider may
+			// already have retired the old token, so memory must not keep using it.
 			refreshToken = token;
+			if (!state.profile) {
+				return;
+			}
+			try {
+				await writeSession(
+					{ refreshToken: token, profile: state.profile, idToken: idToken ?? undefined },
+					epoch,
+				);
+			} catch {
+				// The session stays usable in memory. The stored artifact keeps the
+				// previous token until the next successful write; a restart before
+				// then restores through it if the provider still accepts it, and
+				// otherwise lands on sign-in — never on a corrupted state.
+			}
 		},
 	});
 
@@ -65,25 +124,24 @@ export function createAuthMachine(
 
 	function setState(patch: Partial<AuthState>): void {
 		state = { ...state, ...patch };
-		for (const listener of listeners) {
-			listener(getState());
-		}
-	}
-
-	async function persist(profile: Profile): Promise<void> {
-		if (!refreshToken) {
-			return;
+		// Snapshot, and isolate each listener: a subscriber that throws must not
+		// stop the others or turn a completed sign-in into an error (CORE-03).
+		for (const listener of [...listeners]) {
+			try {
+				listener(getState());
+			} catch {
+				/* consumer bug; the state transition itself already happened */
+			}
 		}
-		await secureStore.setItem(
-			AUTH_STORAGE_KEY,
-			JSON.stringify({ refreshToken, profile }),
-		);
 	}
 
+	/** Ends the local session: memory, cached access tokens, and the stored artifact. */
 	async function clearPersisted(): Promise<void> {
+		sessionEpoch += 1;
 		refreshToken = null;
+		idToken = null;
 		tokenManager.clear();
-		await secureStore.removeItem(AUTH_STORAGE_KEY);
+		await enqueueStoreOp(() => secureStore.removeItem(AUTH_STORAGE_KEY));
 	}
 
 	return {
@@ -97,20 +155,49 @@ export function createAuthMachine(
 		},
 
 		async restore() {
+			sessionEpoch += 1;
+			const epoch = sessionEpoch;
 			setState({ status: 'loading', restore: 'pending', error: undefined });
-			const result = await restoreSession({
-				secureStore,
-				authority: config.authority,
-				clientId: config.clientId,
-				redirectUrl: config.redirectUrl,
-				scopes: config.scopes,
-				authClient,
-				mapping: config.accessTierMapping,
-			});
-
-			if (result.outcome === 'restored' && result.profile) {
-				refreshToken = result.refreshToken ?? null;
-				await persist(result.profile);
+
+			let result;
+			try {
+				result = await restoreSession({
+					secureStore,
+					authority: config.authority,
+					clientId: config.clientId,
+					redirectUrl: config.redirectUrl,
+					scopes: config.scopes,
+					authClient,
+					mapping: config.accessTierMapping,
+				});
+			} catch (error) {
+				// The store could not be read. Nothing is known, nothing is deleted.
+				if (epoch === sessionEpoch) {
+					setState({ ...SIGNED_OUT, status: 'error', error: toAuthError(error) });
+				}
+				return getState();
+			}
+
+			if (epoch !== sessionEpoch) {
+				// A sign-in or sign-out ran meanwhile; its outcome stands.
+				return getState();
+			}
+
+			if (result.outcome === 'restored' && result.profile && result.refreshToken) {
+				refreshToken = result.refreshToken;
+				idToken = result.idToken ?? null;
+				try {
+					await writeSession(
+						{ refreshToken: result.refreshToken, profile: result.profile, idToken: result.idToken },
+						epoch,
+					);
+				} catch {
+					// The refresh succeeded, so the user is signed in for this run. Only
+					// the next launch is affected, and it falls back to sign-in.
+				}
+				if (epoch !== sessionEpoch) {
+					return getState();
+				}
 				setState({
 					status: 'authenticated',
 					profile: result.profile,
@@ -120,6 +207,7 @@ export function createAuthMachine(
 				});
 			} else if (result.outcome === 'offline' && result.profile) {
 				refreshToken = result.refreshToken ?? null;
+				idToken = result.idToken ?? null;
 				setState({
 					status: 'authenticated',
 					profile: result.profile,
@@ -129,18 +217,14 @@ export function createAuthMachine(
 				});
 			} else {
 				await clearPersisted();
-				setState({
-					status: 'signed-out',
-					profile: undefined,
-					accessTier: undefined,
-					restore: 'unavailable',
-					error: undefined,
-				});
+				setState(SIGNED_OUT);
 			}
 			return getState();
 		},
 
 		async signIn(providerId: ProviderId) {
+			sessionEpoch += 1;
+			const epoch = sessionEpoch;
 			setState({ status: 'authenticating', error: undefined });
 			let provider;
 			try {
@@ -158,12 +242,39 @@ export function createAuthMachine(
 					scopes: config.scopes,
 					additionalParameters: buildAdditionalParameters(provider),
 				});
+				if (epoch !== sessionEpoch) {
+					return getState();
+				}
+				if (!tokens.refreshToken) {
+					// `offline_access` is required by configuration, so its absence is the
+					// tenant's doing. Signing in anyway would give a session that silently
+					// never survives a restart.
+					setState({
+						status: 'error',
+						error: new AuthError({
+							code: 'configuration-error',
+							messageKey: 'auth.error.configuration',
+							audience: 'developer',
+							detail: 'authorize returned no refresh token; check that the app registration grants offline_access',
+						}),
+					});
+					return getState();
+				}
+				const profile = mapClaimsToProfile(tokens.claims, providerId);
+				const accessTier = evaluateAccessTier(tokens.claims, config.accessTierMapping);
+				// Written first, committed to memory second: a failed write leaves no
+				// half-signed-in session holding a refresh token that was never stored.
+				await writeSession(
+					{ refreshToken: tokens.refreshToken, profile, idToken: tokens.idToken },
+					epoch,
+				);
+				if (epoch !== sessionEpoch) {
+					return getState();
+				}
 				// Single active account: a new sign-in replaces any prior session.
 				refreshToken = tokens.refreshToken;
+				idToken = tokens.idToken ?? null;
 				tokenManager.clear();
-				const profile = mapClaimsToProfile(tokens.claims, providerId);
-				const accessTier = evaluateAccessTier(tokens.claims, config.accessTierMapping);
-				await persist(profile);
 				setState({
 					status: 'authenticated',
 					profile,
@@ -172,6 +283,9 @@ export function createAuthMachine(
 					error: undefined,
 				});
 			} catch (error) {
+				if (epoch !== sessionEpoch) {
+					return getState();
+				}
 				const authError = toAuthError(error);
 				if (authError.code === 'provider-cancelled') {
 					setState({ status: 'cancelled', error: authError });
@@ -184,42 +298,41 @@ export function createAuthMachine(
 
 		async signOut() {
 			await clearPersisted();
-			setState({
-				status: 'signed-out',
-				profile: undefined,
-				accessTier: undefined,
-				restore: 'unavailable',
-				error: undefined,
-			});
+			setState(SIGNED_OUT);
 		},
 
-		async signOutGlobal() {
+		async signOutGlobal(): Promise<GlobalSignOutResult> {
+			let result: GlobalSignOutResult = { global: 'ended' };
 			try {
 				await authClient.endSession({
 					authority: config.authority,
 					clientId: config.clientId,
 					redirectUrl: config.redirectUrl,
+					idToken: idToken ?? undefined,
 				});
-			} catch {
-				// End-session failure must not block clearing local state.
+			} catch (error) {
+				// Reported, not swallowed: the tenant session may still be alive. It
+				// still must not block clearing local state.
+				result = { global: 'failed', error: toAuthError(error) };
 			}
 			await clearPersisted();
-			setState({
-				status: 'signed-out',
-				profile: undefined,
-				accessTier: undefined,
-				restore: 'unavailable',
-				error: undefined,
-			});
+			setState(SIGNED_OUT);
+			return result;
 		},
 
 		async requestAccessToken(resourceKey) {
-			const wasAuthenticated = state.status === 'authenticated';
-			if (wasAuthenticated) {
+			const epoch = sessionEpoch;
+			// Only a real network refresh is a `token-refreshing` phase; a cache hit
+			// would otherwise flash every subscriber twice for nothing.
+			const refreshing =
+				state.status === 'authenticated' && !tokenManager.hasFreshToken(resourceKey);
+			if (refreshing) {
 				setState({ status: 'token-refreshing' });
 			}
 			const result = await tokenManager.request(resourceKey);
-			if (wasAuthenticated) {
+			// Restored only if nothing else moved the session meanwhile: a sign-out
+			// during the refresh used to be overwritten back to `authenticated`.
+			if (refreshing && epoch === sessionEpoch && state.status === 'token-refreshing') {
 				setState({ status: 'authenticated' });
 			}
 			return result;
@@ -247,3 +360,5 @@ export function createAuthMachine(
 		},
 	};
 }
+
+export type { Profile };

package/src/core/session.ts

@@ -2,9 +2,16 @@
  * Session restoration (FR-008, R5). Reads the persisted artifact, attempts a
  * silent refresh, and classifies the outcome:
  *  - restored: fresh tokens + claims → authenticated
- *  - offline:  network unavailable → cached profile read-only, tier unverified
- *              (fail closed) — clarify Q3
- *  - unavailable: no artifact or invalid/expired refresh → signed-out reauth
+ *  - offline:  the refresh could not complete for any reason other than the
+ *              session being invalid — no network, a timeout, a 5xx, an error we
+ *              cannot classify → cached profile read-only, tier unverified (fail
+ *              closed) — clarify Q3
+ *  - unavailable: no artifact, or the provider said the refresh token is no
+ *              longer valid → signed-out reauth
+ *
+ * Only `unavailable` deletes the stored session, so it is reserved for a verdict
+ * the provider actually gave. Treating every unclassified error as expiry signed
+ * users out whenever the token endpoint had a bad moment.
  */
 
 import type {
@@ -23,6 +30,8 @@ import { isAuthError } from '../diagnostics/errors';
 export interface PersistedSession {
 	refreshToken: string;
 	profile: Profile;
+	/** The id token hint for end-session (AUTH-04). Absent in artifacts written before 0.2.2. */
+	idToken?: string;
 }
 
 export interface RestoreDeps {
@@ -40,6 +49,7 @@ export interface RestoreResult {
 	profile?: Profile;
 	accessTier?: AccessTier;
 	refreshToken?: string;
+	idToken?: string;
 }
 
 export function parsePersistedSession(raw: string | null): PersistedSession | null {
@@ -72,25 +82,31 @@ export async function restoreSession(deps: RestoreDeps): Promise<RestoreResult>
 			refreshToken: persisted.refreshToken,
 			scopes: deps.scopes,
 		});
-		const profile = mapClaimsToProfile(tokens.claims);
-		const accessTier = evaluateAccessTier(tokens.claims, deps.mapping);
+		// A refresh response may carry no id token, and so no claims. The stored
+		// profile is then still the best identity there is; an empty one is not.
+		const hasClaims = Object.keys(tokens.claims).length > 0;
 		return {
 			outcome: 'restored',
-			profile,
-			accessTier,
+			profile: hasClaims ? mapClaimsToProfile(tokens.claims) : persisted.profile,
+			accessTier: hasClaims
+				? evaluateAccessTier(tokens.claims, deps.mapping)
+				: failClosedTier(),
 			refreshToken: tokens.refreshToken || persisted.refreshToken,
+			idToken: tokens.idToken || persisted.idToken,
 		};
 	} catch (error) {
-		// Offline: keep the cached identity read-only, fail closed on entitlement.
-		if (isAuthError(error) && error.code === 'network-unavailable') {
-			return {
-				outcome: 'offline',
-				profile: persisted.profile,
-				accessTier: failClosedTier(),
-				refreshToken: persisted.refreshToken,
-			};
+		if (isAuthError(error) && error.code === 'session-expired') {
+			// The provider rejected the refresh token: reauthentication is required.
+			return { outcome: 'unavailable' };
 		}
-		// Invalid/expired refresh → require reauthentication.
-		return { outcome: 'unavailable' };
+		// Anything else is no verdict on the session. Keep the cached identity
+		// read-only and fail closed on entitlement; the next restore tries again.
+		return {
+			outcome: 'offline',
+			profile: persisted.profile,
+			accessTier: failClosedTier(),
+			refreshToken: persisted.refreshToken,
+			idToken: persisted.idToken,
+		};
 	}
 }

package/src/index.ts

@@ -33,6 +33,7 @@ export type {
 	AccessTokenResult,
 	AccessTokenStatus,
 	PremiumGateResult,
+	GlobalSignOutResult,
 } from './config/types';
 
 // Ports + default adapters

package/src/oidc/authClient.ts

@@ -6,15 +6,19 @@
  * requires react-native-app-auth and is validated on device.
  */
 
-import { AuthError, type AuthErrorCode } from '../diagnostics/errors';
+import { classifyAppAuthError } from './classifyError';
 
 export interface OidcTokens {
 	/** Resource/audience access token (present for authorize and resource refresh). */
 	accessToken?: string;
-	/** Refresh token used for silent acquisition and restore. */
-	refreshToken: string;
-	/** Raw id token (JWT). */
-	idToken: string;
+	/**
+	 * Refresh token used for silent acquisition and restore. Absent when the
+	 * provider issued none — a refresh that does not rotate, or an authorize the
+	 * tenant answered without `offline_access`.
+	 */
+	refreshToken?: string;
+	/** Raw id token (JWT). Absent from a refresh requested without `openid`. */
+	idToken?: string;
 	/** Decoded id-token (or access-token) claims used for profile + access tier. */
 	claims: Record<string, unknown>;
 	/** Access-token expiry in epoch milliseconds, when available. */
@@ -52,7 +56,10 @@ export interface OidcAuthClient {
 }
 
 /** Decode the payload segment of a JWT without any dependency (device-safe). */
-export function decodeJwtClaims(jwt: string): Record<string, unknown> {
+export function decodeJwtClaims(jwt: string | null | undefined): Record<string, unknown> {
+	if (typeof jwt !== 'string') {
+		return {};
+	}
 	const parts = jwt.split('.');
 	if (parts.length < 2) {
 		return {};
@@ -106,40 +113,6 @@ function base64UrlDecode(input: string): string {
 	}
 }
 
-/** Map a native app-auth error to a classified AuthError without leaking tokens. */
-function classifyAppAuthError(error: unknown): AuthError {
-	const message = error instanceof Error ? error.message : String(error);
-	// DEV-only: surface the RAW native error so the actual failure (AADSTS code,
-	// issuer/redirect mismatch, token-endpoint error) is visible while debugging.
-	// Remove before shipping — this intentionally bypasses redaction.
-	if (typeof __DEV__ !== 'undefined' && __DEV__) {
-		console.warn('[rn-auth] raw app-auth error:', {
-			message,
-			code: (error as { code?: unknown })?.code,
-			error,
-		});
-	}
-	const lower = message.toLowerCase();
-	let code: AuthErrorCode = 'token-acquisition-failed';
-	let messageKey = 'auth.error.token';
-	if (lower.includes('cancel')) {
-		code = 'provider-cancelled';
-		messageKey = 'auth.error.cancelled';
-	} else if (lower.includes('network') || lower.includes('connection') || lower.includes('offline')) {
-		code = 'network-unavailable';
-		messageKey = 'auth.error.network';
-	} else if (lower.includes('redirect')) {
-		code = 'redirect-mismatch';
-		messageKey = 'auth.error.redirectMismatch';
-	} else if (lower.includes('consent') || lower.includes('denied') || lower.includes('access_denied')) {
-		code = 'consent-denied';
-		messageKey = 'auth.error.consentDenied';
-	} else if (lower.includes('invalid_grant') || lower.includes('expired')) {
-		code = 'session-expired';
-		messageKey = 'auth.error.sessionExpired';
-	}
-	return new AuthError({ code, messageKey, audience: code === 'redirect-mismatch' ? 'developer' : 'user', detail: message });
-}
 
 export interface AppAuthClientOptions {
 	/** When true, the OIDC discovery document is fetched from `${authority}`. */
@@ -171,13 +144,15 @@ export function createAppAuthClient(
 
 	const toTokens = (result: {
 		accessToken?: string;
-		refreshToken?: string;
-		idToken: string;
+		refreshToken?: string | null;
+		idToken?: string | null;
 		accessTokenExpirationDate?: string;
 	}): OidcTokens => ({
 		accessToken: result.accessToken,
-		refreshToken: result.refreshToken ?? '',
-		idToken: result.idToken,
+		// Absent stays absent: an empty string was indistinguishable from a real
+		// token by type, and silently disabled session persistence.
+		refreshToken: result.refreshToken || undefined,
+		idToken: result.idToken || undefined,
 		claims: decodeJwtClaims(result.idToken),
 		accessTokenExpiresAt: result.accessTokenExpirationDate
 			? new Date(result.accessTokenExpirationDate).getTime()

package/src/oidc/classifyError.ts

@@ -0,0 +1,76 @@
+/**
+ * Classifies a native OIDC error into an `AuthErrorCode`.
+ *
+ * The rules are an ordered table rather than a chain of substring checks, so a
+ * platform adapter (the iOS one, later) adds its own rows without touching the
+ * engine. Order matters: the first matching rule wins.
+ *
+ * The default is deliberately not "session expired". Restore clears the stored
+ * session only on `session-expired`, so anything this table cannot name — a
+ * timeout, a 5xx, a discovery failure, a localized message — must keep the
+ * session rather than sign the user out.
+ */
+
+import { AuthError, type AuthErrorCode } from '../diagnostics/errors';
+
+export interface ClassificationRule {
+	readonly code: AuthErrorCode;
+	readonly messageKey: string;
+	/** Matched against the native error's `code` and `message`, case-insensitively. */
+	readonly pattern: RegExp;
+}
+
+/**
+ * OAuth error codes (RFC 6749 §5.2, OIDC Core §3.1.2.6) and the Entra ID AADSTS
+ * codes that mean the same thing, plus the transport failures app-auth reports.
+ */
+export const DEFAULT_CLASSIFICATION_RULES: readonly ClassificationRule[] = [
+	{
+		code: 'provider-cancelled',
+		messageKey: 'auth.error.cancelled',
+		pattern: /cancel|user_cancel|authorization flow (was )?dismissed/i,
+	},
+	{
+		code: 'session-expired',
+		messageKey: 'auth.error.sessionExpired',
+		// invalid_grant is the refresh-token verdict; the AADSTS codes are Entra's
+		// expired, revoked, or inactive refresh token and password-changed cases.
+		pattern:
+			/\binvalid_grant\b|\binteraction_required\b|\blogin_required\b|AADSTS(700082|700084|50173|70043)\b/i,
+	},
+	{
+		code: 'redirect-mismatch',
+		messageKey: 'auth.error.redirectMismatch',
+		pattern: /redirect_uri|redirect uri|redirect_mismatch|AADSTS50011\b/i,
+	},
+	{
+		code: 'consent-denied',
+		messageKey: 'auth.error.consentDenied',
+		pattern: /\baccess_denied\b|\bconsent_required\b|AADSTS65001\b/i,
+	},
+	{
+		code: 'network-unavailable',
+		messageKey: 'auth.error.network',
+		pattern:
+			/network|connection|offline|timed? ?out|unable to resolve host|unreachable|\bserver_error\b|\btemporarily_unavailable\b|\b5\d\d\b/i,
+	},
+];
+
+/** Maps a native app-auth error to a classified AuthError without leaking tokens. */
+export function classifyAppAuthError(
+	error: unknown,
+	rules: readonly ClassificationRule[] = DEFAULT_CLASSIFICATION_RULES,
+): AuthError {
+	const message = error instanceof Error ? error.message : String(error);
+	const nativeCode = (error as { code?: unknown } | undefined)?.code;
+	const haystack = `${typeof nativeCode === 'string' ? nativeCode : ''} ${message}`;
+	const rule = rules.find(candidate => candidate.pattern.test(haystack));
+	const code = rule?.code ?? 'token-acquisition-failed';
+	return new AuthError({
+		code,
+		messageKey: rule?.messageKey ?? 'auth.error.token',
+		audience: code === 'redirect-mismatch' ? 'developer' : 'user',
+		// AuthError redacts `detail`, so token-shaped values never survive.
+		detail: message,
+	});
+}

package/src/react/hooks.ts

@@ -9,6 +9,7 @@ import type {
 	AccessTier,
 	AccessTokenResult,
 	AuthState,
+	GlobalSignOutResult,
 	PremiumGateResult,
 	Profile,
 	ProviderConfig,
@@ -20,7 +21,7 @@ export interface UseAuthResult {
 	state: AuthState;
 	signIn(providerId: ProviderId): Promise<AuthState>;
 	signOut(): Promise<void>;
-	signOutGlobal(): Promise<void>;
+	signOutGlobal(): Promise<GlobalSignOutResult>;
 	restore(): Promise<AuthState>;
 	requirePremium(): PremiumGateResult;
 }

package/src/tokens/accessToken.ts

@@ -26,80 +26,139 @@ export interface AccessTokenManagerDeps {
 	resources: ResourceConfig[];
 	authClient: OidcAuthClient;
 	getRefreshToken: () => string | null;
-	setRefreshToken: (token: string) => void;
+	/**
+	 * The session generation, bumped by every sign-in, sign-out and restore. A
+	 * refresh that started under one generation and finished under another
+	 * belongs to a session that no longer exists, so its result is discarded.
+	 */
+	sessionEpoch: () => number;
+	/**
+	 * The provider rotated the refresh token. Resolves once the new token is
+	 * live, and persisted where it can be: the old one may already be dead, so a
+	 * restart must not come back with it.
+	 */
+	onRefreshTokenRotated: (token: string, epoch: number) => Promise<void>;
 }
 
 export interface AccessTokenManager {
 	request(resourceKey: string): Promise<AccessTokenResult>;
+	/** Whether `request` would answer from the cache, without touching the network. */
+	hasFreshToken(resourceKey: string): boolean;
 	clear(): void;
 }
 
+const SESSION_ENDED: Omit<AccessTokenResult, 'resourceKey'> = {
+	status: 'unavailable',
+	errorCode: 'session-expired',
+};
+
 export function createAccessTokenManager(
 	deps: AccessTokenManagerDeps,
 ): AccessTokenManager {
 	const cache = new Map<string, CachedToken>();
+	/**
+	 * Refreshes in progress, by resource. Concurrent callers for one resource
+	 * share a single network call; with a rotating refresh token, a second call
+	 * would race the first with a token the first may have just retired.
+	 */
+	const inFlight = new Map<string, Promise<AccessTokenResult>>();
+
+	const fresh = (resourceKey: string): CachedToken | undefined => {
+		const cached = cache.get(resourceKey);
+		return cached && cached.expiresAt - EXPIRY_SKEW_MS > Date.now() ? cached : undefined;
+	};
+
+	const refresh = async (resource: ResourceConfig): Promise<AccessTokenResult> => {
+		const resourceKey = resource.key;
+		const epoch = deps.sessionEpoch();
+		const refreshToken = deps.getRefreshToken();
+		if (!refreshToken) {
+			return { resourceKey, ...SESSION_ENDED };
+		}
+
+		try {
+			const tokens = await deps.authClient.refresh({
+				authority: deps.authority,
+				clientId: deps.clientId,
+				redirectUrl: deps.redirectUrl,
+				refreshToken,
+				scopes: resource.scopes,
+			});
+			// Signed out, or signed in as someone else, while this was in flight:
+			// nothing from it may be written back, and its token is not handed out.
+			if (deps.sessionEpoch() !== epoch) {
+				return { resourceKey, ...SESSION_ENDED };
+			}
+			if (tokens.refreshToken && tokens.refreshToken !== refreshToken) {
+				await deps.onRefreshTokenRotated(tokens.refreshToken, epoch);
+				if (deps.sessionEpoch() !== epoch) {
+					return { resourceKey, ...SESSION_ENDED };
+				}
+			}
+			if (!tokens.accessToken) {
+				return { resourceKey, status: 'error', errorCode: 'token-acquisition-failed' };
+			}
+			const expiresAt = tokens.accessTokenExpiresAt ?? Date.now() + 3_600_000;
+			cache.set(resourceKey, {
+				token: tokens.accessToken,
+				expiresAt,
+				scopes: resource.scopes,
+			});
+			return { resourceKey, status: 'success', token: tokens.accessToken, expiresAt };
+		} catch (error) {
+			if (isAuthError(error)) {
+				if (error.code === 'consent-denied') {
+					return { resourceKey, status: 'denied', errorCode: error.code };
+				}
+				if (error.code === 'network-unavailable') {
+					return { resourceKey, status: 'unavailable', errorCode: error.code };
+				}
+				if (error.code === 'session-expired') {
+					return { resourceKey, status: 'unavailable', errorCode: error.code };
+				}
+				return { resourceKey, status: 'error', errorCode: error.code };
+			}
+			return { resourceKey, status: 'error', errorCode: 'token-acquisition-failed' };
+		}
+	};
 
 	return {
 		clear() {
 			cache.clear();
+			inFlight.clear();
+		},
+
+		hasFreshToken(resourceKey) {
+			return fresh(resourceKey) !== undefined;
 		},
-		async request(resourceKey): Promise<AccessTokenResult> {
+
+		request(resourceKey): Promise<AccessTokenResult> {
 			const resource = deps.resources.find(entry => entry.key === resourceKey);
 			if (!resource) {
-				return { resourceKey, status: 'error', errorCode: 'configuration-error' };
+				return Promise.resolve({ resourceKey, status: 'error', errorCode: 'configuration-error' });
 			}
 
-			const cached = cache.get(resourceKey);
-			if (cached && cached.expiresAt - EXPIRY_SKEW_MS > Date.now()) {
-				return {
+			const cached = fresh(resourceKey);
+			if (cached) {
+				return Promise.resolve({
 					resourceKey,
 					status: 'success',
 					token: cached.token,
 					expiresAt: cached.expiresAt,
-				};
+				});
 			}
 
-			const refreshToken = deps.getRefreshToken();
-			if (!refreshToken) {
-				return { resourceKey, status: 'unavailable', errorCode: 'session-expired' };
+			const running = inFlight.get(resourceKey);
+			if (running) {
+				return running;
 			}
-
-			try {
-				const tokens = await deps.authClient.refresh({
-					authority: deps.authority,
-					clientId: deps.clientId,
-					redirectUrl: deps.redirectUrl,
-					refreshToken,
-					scopes: resource.scopes,
-				});
-				if (tokens.refreshToken) {
-					deps.setRefreshToken(tokens.refreshToken);
-				}
-				if (!tokens.accessToken) {
-					return { resourceKey, status: 'error', errorCode: 'token-acquisition-failed' };
-				}
-				const expiresAt = tokens.accessTokenExpiresAt ?? Date.now() + 3_600_000;
-				cache.set(resourceKey, {
-					token: tokens.accessToken,
-					expiresAt,
-					scopes: resource.scopes,
-				});
-				return { resourceKey, status: 'success', token: tokens.accessToken, expiresAt };
-			} catch (error) {
-				if (isAuthError(error)) {
-					if (error.code === 'consent-denied') {
-						return { resourceKey, status: 'denied', errorCode: error.code };
-					}
-					if (error.code === 'network-unavailable') {
-						return { resourceKey, status: 'unavailable', errorCode: error.code };
-					}
-					if (error.code === 'session-expired') {
-						return { resourceKey, status: 'unavailable', errorCode: error.code };
-					}
-					return { resourceKey, status: 'error', errorCode: error.code };
+			const flight = refresh(resource).finally(() => {
+				if (inFlight.get(resourceKey) === flight) {
+					inFlight.delete(resourceKey);
 				}
-				return { resourceKey, status: 'error', errorCode: 'token-acquisition-failed' };
-			}
+			});
+			inFlight.set(resourceKey, flight);
+			return flight;
 		},
 	};
 }