@chipmobilesdk/rn-auth 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # @chipmobilesdk/rn-auth
 
+## 0.5.0
+
+### Minor Changes
+
+- A restored session reports the provider the user signed in with. A refresh answers with the tenant's own `idp` (`google.com`), so after a restart the same session used to describe itself differently — `profile.provider` changed from `google` to `google.com`. ([#19](https://github.com/operationd8979/chip-mobile-sdk/pull/19))
+
+  `auth.canAccessPremium()` answers whether a premium path is open and changes nothing. `requirePremium()`, which also moves the whole controller to `access-denied` — a status every screen reading `state.status` then sees, and one only a sign-in or `restore()` leaves — is deprecated and will be removed in 0.5.0. Both are on `useAuth()`.
+
+  `ProviderId` is open (`KnownProviderId | (string & {})`), `labelKey` takes an app's own message key, and `ProviderConfig.additionalParameters` passes extra OIDC parameters such as `prompt`, so federating another identity provider is a change to an app's config rather than a release of this package. A provider's own parameters cannot override `domain_hint`.
+
+  `config.messages` is read at last: `auth.getMessages()` and `useAuthMessages()` return this package's copy with the app's overrides applied. Configuration validation refuses a plaintext `authority` (http is accepted only for localhost), a provider platform other than `ios`/`android`, and a provider with no `labelKey`. `createAppAuthClient({ serviceConfiguration })` takes the endpoints directly, so an authorize, refresh or sign-out no longer costs a `.well-known` round-trip. `mapClaimsToProfile` and `describeProviderIdentity` are exported, which is what the already-public `ProviderIdentity` type describes.
+
+  `useAccessToken(resourceKey)` drops a result that arrives after the component unmounted or moved to another resource, and starts from `idle` when the resource changes.
+
+  The stored session artifact holds an identity — tenant user id, display name, email, provider — and no longer the whole id-token claim set, group ids included; a restore that rotated nothing leaves the Keychain untouched. After an `offline` restore, `profile.claims` is empty and the tier fails closed, as before. The never-emitted `entitlement-unverified` error code is gone from `AuthErrorCode`, and `AuthError.messageKey` is typed as `AuthMessageKey` rather than `string`.
+
+- A 401 retry now gets a token the provider had to fetch again. `TokenProvider.requestAccessToken` takes `{ forceRefresh }`, which rn-auth implements by dropping the cached token for that resource, so the retry no longer re-sends the token the gateway had just refused — a cached token is still unexpired by the device's clock when the server rejects it. ([#19](https://github.com/operationd8979/chip-mobile-sdk/pull/19))
+
+  Failures an app can tell apart. `network` is a request that never arrived (no connection, a timeout, a dropped stream) and is retryable; `session-expired` is a session the user must renew. `AiError.cause` carries the code from the layer underneath — the gateway's own code, or rn-auth's — so a screen can explain *why*, and `retryAfterSeconds` is read from the `Retry-After` header when the body omits it. Both new codes have user copy, and the gateway's full code list is mapped rather than guessed from the status.
+
+  The remote behavior config is checked before it is trusted. `configUrl` and the document's `api.baseUrl` must be https (localhost excepted), the document must name the app it is for, its `schemaVersion` must be one this release understands, and `allowedHosts` pins where the client may send its bearer token. A broken TTL no longer means a revalidation on every request, and a retry count is bounded. A not-modified answer against a cache that is no longer there asks again without the ETag instead of reporting the 304 as a failure.
+
+  `configCacheFromKeyValue(port)` makes a durable config cache out of rn-core's `KeyValuePort`, so a second launch uses the last-good document instead of waiting for the network.
+
+  One quota figure: a chat's `done` event and `getQuota()` both record it on the client (`lastQuota()`), so `useAiQuota` and `useAiChat` cannot disagree, and a quota response that does not match the contract is refused rather than displayed. `getQuota()` recovers like a chat: a designated 404/410 reloads the configuration and retries, and a 401 retries once.
+
+  Streamed text reaches the screen on an interval (50 ms by default, `useAiChat(client, { flushIntervalMs })`) rather than once per token, and whatever arrived is flushed with the terminal state, so a half-answer stays on screen when a stream fails. A stream framed with CRLF is parsed incrementally, as the SSE specification allows. The transport seam is a published `StreamTransport` port instead of the internal reader's signature.
+
 ## 0.4.0
 
 ### Minor Changes

package/README.md

@@ -74,11 +74,45 @@ export const App = () => (
 );
 ```
 
-Hooks: `useAuth()` (state + `signIn`/`signOut`/`signOutGlobal`/`restore`/`requirePremium`),
+Hooks: `useAuth()` (state + `signIn`/`signOut`/`signOutGlobal`/`restore`/`canAccessPremium`),
 `useProfile()`, `useAccessTier()`, `useAccessToken(resourceKey)`,
+`useAuthMessages()` (this package's copy, with your `messages` applied),
 `useSignInProviders()` (all platform providers, in config order — map to one
 button each) and `useSignInProvider()` (first available, for a single-button UI).
 
+### Gating a premium path
+
+```tsx
+const { canAccessPremium } = useAuth();
+const gate = canAccessPremium(); // { allowed, tier } — reads, changes nothing
+
+return gate.allowed ? <PremiumReport /> : <UpgradeNotice tier={gate.tier} />;
+```
+
+`canAccessPremium()` is a question. `requirePremium()`, which answers the same
+question *and* moves the whole controller to `access-denied` — a status every
+screen reading `state.status` then sees, and only a sign-in or `restore()`
+leaves — is deprecated and will go in 0.5.0.
+
+### Providers beyond the three with built-in copy
+
+A provider is a `domain_hint` and a label, so adding one the tenant federates is
+a change to this config and nothing else:
+
+```tsx
+providers: [
+  { id: 'microsoft', platforms: ['ios', 'android'], domainHint: 'live.com',
+    labelKey: 'app.action.continueMicrosoft',           // one of your own keys
+    additionalParameters: { prompt: 'select_account' }, // merged into authorize
+  },
+]
+```
+
+`ProviderId` is `KnownProviderId | (string & {})`: `'google' | 'apple' |
+'facebook'` stay in autocomplete, and any other id is accepted. A provider's
+`additionalParameters` cannot override `domain_hint`, so it can never route the
+flow to another IdP.
+
 ### Session lifecycle guarantees
 
 - **Restore deletes the stored session only when the provider rejects the refresh
@@ -91,6 +125,15 @@ button each) and `useSignInProvider()` (first available, for a single-button UI)
   `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.
+- **A restored profile reports the provider the user signed in with.** The stored
+  artifact carries it, because a refresh answers with the tenant's own `idp`
+  (`google.com`), which is not the id the app passed to `signIn`.
+- **The stored artifact holds an identity, not a token's claims:** the tenant user
+  id, display name, email and provider. After a restore that reached the provider,
+  `profile.claims` is the fresh id-token claim set; after an `offline` restore it is
+  empty, and the access tier fails closed. Read `state.restore` to tell them apart.
+- **An unchanged session is not rewritten.** A restore that rotated nothing leaves
+  the Keychain untouched, off the startup path.
 
 ## Configuration contract (LIB-010)
 
@@ -106,10 +149,15 @@ client secrets are configured in the External ID tenant, never in the app
 | C2 — Facebook (optional) | `providers[facebook]`: `domainHint: 'facebook.com'`, `platforms: ['ios','android']`, `labelKey: 'auth.action.continueFacebook'`, optional `available` |
 | D — Resources | `resources[].key`, `resources[].scopes`, `resources[].displayName?` |
 | E — Access tier | `accessTierMapping.premiumGroupObjectIds` (+ optional role names / claim matchers; display names are diagnostics-only) |
-| F — Ports | `secureStore` (required), `authClient` (optional), `messages` (optional copy override) |
+| F — Ports | `secureStore` (required), `authClient` (optional), `messages` (optional copy override, readable through `useAuthMessages()`) |
 
-Full contract: [auth-config.md](../../specs/003-mobile-entra-auth/contracts/auth-config.md)
-and [public-api.md](../../specs/003-mobile-entra-auth/contracts/public-api.md).
+`createAuth` throws `AuthConfigError` before any flow can start when: `authority`
+is missing, relative, or not `https` (plain `http` is accepted only for
+`localhost`); `redirectUrl` has no scheme; `offline_access` is absent from
+`scopes`; no provider is configured, or one repeats an id, or lacks a
+`domainHint` or `labelKey`, or declares a platform other than `ios`/`android`; a
+resource repeats a key or declares no scope; `accessTierMapping` names no premium
+indicator; or no `secureStore` is supplied.
 
 ## Tenant / provider prerequisite checklist (LIB-018)
 
@@ -160,19 +208,28 @@ 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`
+- Identity and access: `Profile`, `ProviderConfig`, `ProviderId`,
+  `KnownProviderId`, `ProviderIdentity`, `ResourceConfig`, `AccessTier`,
+  `AccessTierMapping`, `AccessTokenResult`, `PremiumGateResult`,
+  `evaluateAccessTier`, `failClosedTier`, `mapClaimsToProfile`,
+  `describeProviderIdentity` (what an address is: `direct`, Apple's
+  `private-relay`, or `none`)
 - Ports and default adapters: `SecureTokenStore`, `createKeychainSecureStore`,
   `AUTH_STORAGE_KEY`, `OidcAuthClient`, `createAppAuthClient` and the public OIDC
-  request/token types. The two default adapters also have their own entrypoints,
+  request/token types. `createAppAuthClient({ serviceConfiguration })` takes the
+  authorization, token and end-session endpoints directly; without them the native
+  module fetches `.well-known` on every authorize, refresh and sign-out, including
+  the refresh on the startup path. The two default adapters also have their own entrypoints,
   `@chipmobilesdk/rn-auth/app-auth` and `@chipmobilesdk/rn-auth/keychain`, so an app
   that injects its own client or store can skip them. Neither loads its native
   module until it is used: react-native-app-auth on the first sign-in, refresh or
   sign-out, react-native-keychain on the first read or write. Creating `auth` at
   startup loads neither. A missing module is an `AuthConfigError` at that moment.
 - React: `AuthProvider`, `useAuth`, `useProfile`, `useAccessTier`,
-  `useAccessToken`, `useSignInProvider`, `useSignInProviders`, `useAuthSelector`.
+  `useAccessToken`, `useAuthMessages`, `useSignInProvider`, `useSignInProviders`,
+  `useAuthSelector`. `useAccessToken(resourceKey)` starts from `idle` again when
+  the resource changes, and a result that arrives after the component unmounted
+  or moved on is dropped rather than applied.
   Each hook reads the state through `useSyncExternalStore` and re-renders only when
   what it returns changes: `useProfile` does not render for a status change. Use
   `useAuthSelector(state => …, isEqual?)` for any other slice. `auth.getState()`

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@chipmobilesdk/rn-auth",
-	"version": "0.4.0",
+	"version": "0.5.0",
 	"private": false,
 	"license": "UNLICENSED",
 	"main": "src/index.ts",

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

@@ -35,12 +35,27 @@ value.
 
 ## Public API
 
+`createAuth(config)` is the entry point: one controller, one active account, created at
+startup without loading any native module. Wrap the app in `<AuthProvider auth={auth}>`
+and read state through the hooks — never re-implement the orchestration.
+
 Runtime:
 
-- `createAppAuthClient(...)` — the OIDC client
+- `createAuth` — the controller: `getState`, `subscribe`, `restore`, `signIn(providerId)`,
+  `signOut`, `signOutGlobal`, `requestAccessToken(resourceKey)`, `getAccessTier`,
+  `canAccessPremium`, `getPlatformProvider(s)`, `getMessages`
+- Hooks: `useAuth`, `useProfile`, `useAccessTier`, `useAccessToken`, `useAuthMessages`,
+  `useSignInProvider`, `useSignInProviders`, `useAuthSelector`
+- `AuthProvider`
+- `createAppAuthClient(...)` — the OIDC client; pass `serviceConfiguration` to skip a
+  `.well-known` fetch on every call
 - `createKeychainSecureStore(...)` — token persistence; `AUTH_STORAGE_KEY`
-- `evaluateAccessTier(...)`, `failClosedTier` — feature gating
+- `evaluateAccessTier(...)`, `failClosedTier` — feature gating, denying when unknown
+- `mapClaimsToProfile`, `describeProviderIdentity` — claims to a profile, and whether an
+  address is direct, Apple's private relay, or absent
 - `AuthProvider` — React context provider
+- `AuthError`, `AuthConfigError`, `isAuthError`, `redact`, `authMessages`,
+  `resolveMessages`, `DEFAULT_MESSAGES`
 
 Testing (`@chipmobilesdk/rn-auth/testing`): `createMemorySecureStore`,
 `runSecureTokenStoreConformance`, `runOidcAuthClientConformance` — README `## Testing`.
@@ -51,6 +66,24 @@ Types: `SecureTokenStore`, `AuthProviderProps`, `AuthErrorCode`, `AuthErrorAudie
 `AuthErrorAudience` distinguishes what may be shown to a user from what is diagnostic
 only — never render a diagnostic-audience message in the UI.
 
+## Three things that bite
+
+- **`signOutGlobal()` can report `{ global: 'failed' }`.** Local state is cleared either
+  way, but the tenant session may still be alive, so the next sign-in can complete with
+  no password prompt. Say so in the UI rather than claiming the user is fully signed out.
+- **`requestAccessToken(resourceKey)` answers with a status, not a throw.** Handle
+  `denied` and `unavailable` as states; only `success` carries a token. `useAccessToken`
+  starts from `idle` again when the resource key changes.
+- **iOS needs the native redirect set up** (URL scheme matching `redirectUrl`, and the
+  Apple provider configured in the tenant). A `redirect-mismatch` error is that, not a
+  code fault — see the prerequisite checklist.
+
+## A premium gate is a question
+
+Use `canAccessPremium()` and render the denial where it happened.
+`requirePremium()` is deprecated: it also moves the whole controller to
+`access-denied`, which every screen reading `state.status` then sees.
+
 ## Where the detail lives
 
 Read one section of `node_modules/@chipmobilesdk/rn-auth/README.md`:

package/src/config/types.ts

@@ -3,23 +3,44 @@
  * specs/003-mobile-entra-auth/data-model.md.
  */
 
+import type { AccessTokenRequestOptions } from '../tokens/accessToken';
 import type { SecureTokenStore } from '../tokens/secureStore';
 import type { OidcAuthClient } from '../oidc/authClient';
 import type { AuthError, AuthErrorCode } from '../diagnostics/errors';
 import type { AuthMessageKey, AuthMessageMap } from '../diagnostics/messageKeys';
 
-export type ProviderId = 'google' | 'apple' | 'facebook';
+/** The providers this package has copy for out of the box. */
+export type KnownProviderId = 'google' | 'apple' | 'facebook';
+
+/**
+ * A provider id. Open on purpose: routing is `domain_hint` and nothing else, so
+ * adding an IdP the tenant federates — Microsoft account, an email one-time
+ * code — is a change to an app's config, not a release of this package
+ * (AUTH-14). `KnownProviderId` keeps the three familiar ones in autocomplete.
+ */
+export type ProviderId = KnownProviderId | (string & {});
 export type DevicePlatform = 'ios' | 'android';
 
+export const DEVICE_PLATFORMS: readonly DevicePlatform[] = ['ios', 'android'];
+
 /** Provider Setup Configuration — non-secret public values only (FR-016/FR-017). */
 export interface ProviderConfig {
 	id: ProviderId;
 	platforms: DevicePlatform[];
 	/** External ID `domain_hint` routing the user flow to this IdP (R3). */
 	domainHint: string;
-	/** Message key for the button label (Continue with Google / Apple). */
-	labelKey: AuthMessageKey;
+	/**
+	 * Message key for the button label (Continue with Google / Apple). A key of
+	 * this package's catalogue, or one of the app's own for a provider it added.
+	 */
+	labelKey: AuthMessageKey | (string & {});
 	available?: boolean;
+	/**
+	 * Extra OIDC authorize parameters for this provider, merged after
+	 * `domain_hint` — `prompt`, `login_hint`, whatever the tenant's user flow
+	 * expects. `domain_hint` itself cannot be overridden here.
+	 */
+	additionalParameters?: Record<string, string>;
 }
 
 /** One configured protected resource for delegated token requests (FR-007). */
@@ -55,6 +76,11 @@ export interface AuthConfig {
 	accessTierMapping: AccessTierMapping;
 	secureStore: SecureTokenStore;
 	authClient?: OidcAuthClient;
+	/**
+	 * Copy overrides for this package's own message keys, resolved over the
+	 * English defaults and readable through `auth.getMessages()` and
+	 * `useAuthMessages()`.
+	 */
 	messages?: Partial<AuthMessageMap>;
 }
 
@@ -81,6 +107,11 @@ export interface Profile {
 	displayName?: string | undefined;
 	email?: string | undefined;
 	provider: string;
+	/**
+	 * The id-token claims this profile was mapped from. Empty after a restore
+	 * that could not reach the provider: the stored artifact holds the identity,
+	 * not the token (AUTH-23). Read `restore` on the state to tell the two apart.
+	 */
 	claims: Record<string, unknown>;
 }
 
@@ -143,10 +174,27 @@ export interface Auth {
 	signIn(providerId: ProviderId): Promise<AuthState>;
 	signOut(): Promise<void>;
 	signOutGlobal(): Promise<GlobalSignOutResult>;
-	requestAccessToken(resourceKey: string): Promise<AccessTokenResult>;
+	/**
+	 * A delegated token for one configured resource. Answers from the in-memory
+	 * cache while the token is unexpired; `forceRefresh` skips and drops that
+	 * cache, which is what a caller whose token was just rejected needs.
+	 */
+	requestAccessToken(
+		resourceKey: string,
+		options?: AccessTokenRequestOptions,
+	): Promise<AccessTokenResult>;
 	getAccessTier(): AccessTier;
-	/** Gate a premium-only path; enters `access-denied` when unverified (FR-011). */
+	/** Whether a premium-only path is open, and the tier behind the answer. Reads nothing else and changes nothing (FR-011). */
+	canAccessPremium(): PremiumGateResult;
+	/**
+	 * @deprecated Use `canAccessPremium` and show the denial where it happened.
+	 * This also moves the whole controller to `access-denied`, which every screen
+	 * reading `status` then sees, and only a `restore` or a sign-in leaves
+	 * (AUTH-12). Kept for 0.4.x.
+	 */
 	requirePremium(): PremiumGateResult;
+	/** This package's copy: the English defaults with the app's `messages` over them. */
+	getMessages(): AuthMessageMap;
 	/** The first available provider to present on the current platform (UX-004), or undefined. */
 	getPlatformProvider(): ProviderConfig | undefined;
 	/** All available providers for the current platform, in configuration order (FR-003/FR-004). */

package/src/config/validateConfig.ts

@@ -4,13 +4,21 @@
  * Covers the auth-config.md Section A–F rules.
  */
 
-import type { AuthConfig } from './types';
+import { DEVICE_PLATFORMS, type AuthConfig } from './types';
 import { AuthConfigError } from '../diagnostics/errors';
 
 function hasScheme(url: string): boolean {
 	return /^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(url);
 }
 
+/** https, or http on a development machine. */
+function isSecureAuthority(url: string): boolean {
+	if (/^https:/i.test(url)) {
+		return true;
+	}
+	return /^http:\/\/(localhost|127\.0\.0\.1|\[::1\])(:\d+)?(\/|$)/i.test(url);
+}
+
 export function validateConfig(config: AuthConfig): void {
 	// Section A — tenant/client settings
 	if (!config.authority || !config.authority.trim()) {
@@ -19,6 +27,14 @@ export function validateConfig(config: AuthConfig): void {
 	if (!hasScheme(config.authority)) {
 		throw new AuthConfigError('auth.error.configuration', '"authority" must be an absolute URL');
 	}
+	// Tokens travel over this. A tenant reachable over plaintext http is a
+	// configuration mistake, not a deployment choice — except on a dev machine.
+	if (!isSecureAuthority(config.authority)) {
+		throw new AuthConfigError(
+			'auth.error.configuration',
+			'"authority" must use https (http is accepted only for localhost)',
+		);
+	}
 	if (!config.clientId || !config.clientId.trim()) {
 		throw new AuthConfigError('auth.error.configuration', 'Missing "clientId"');
 	}
@@ -66,6 +82,21 @@ export function validateConfig(config: AuthConfig): void {
 				`Provider "${provider.id}" must declare at least one platform`,
 			);
 		}
+		for (const platform of provider.platforms) {
+			if (!DEVICE_PLATFORMS.includes(platform)) {
+				// A typo here hides the provider on every device rather than failing.
+				throw new AuthConfigError(
+					'auth.error.configuration',
+					`Provider "${provider.id}" declares unknown platform "${String(platform)}"`,
+				);
+			}
+		}
+		if (typeof provider.labelKey !== 'string' || !provider.labelKey.trim()) {
+			throw new AuthConfigError(
+				'auth.error.configuration',
+				`Provider "${provider.id}" is missing a labelKey`,
+			);
+		}
 	}
 
 	// Section D — resources

package/src/core/authMachine.ts

@@ -16,6 +16,8 @@ import {
 	shallowEqual,
 } from '@chipmobilesdk/rn-core';
 
+import type { AuthMessageMap } from '../diagnostics/messageKeys';
+import { resolveMessages } from '../diagnostics/messageKeys';
 import type {
 	Auth,
 	AuthConfig,
@@ -37,7 +39,7 @@ import {
 } from '../oidc/socialRouting';
 import { mapClaimsToProfile } from './profile';
 import { evaluateAccessTier, failClosedTier } from '../access/accessTier';
-import { restoreSession, type PersistedSession } from './session';
+import { restoreSession, sameSession, storedProfileFrom, type PersistedSession } from './session';
 import { AUTH_STORAGE_KEY } from '../tokens/secureStore';
 import { createAccessTokenManager } from '../tokens/accessToken';
 import { AuthError, toAuthError, type AuthErrorCode } from '../diagnostics/errors';
@@ -62,6 +64,8 @@ export function createAuthMachine(config: AuthConfig, options: CreateAuthOptions
 	const secureStore = config.secureStore;
 	const authClient = config.authClient ?? createAppAuthClient();
 	const resources = config.resources ?? [];
+	// Declared since 0.1.0 and read by nothing until now (AUTH-15).
+	const messages = resolveMessages(config.messages);
 
 	let state: AuthState = Object.freeze({ status: 'loading', restore: 'pending' });
 	let refreshToken: string | null = null;
@@ -84,12 +88,29 @@ export function createAuthMachine(config: AuthConfig, options: CreateAuthOptions
 		return next;
 	};
 
-	const writeSession = (session: PersistedSession, epoch: number): Promise<void> =>
+	/** The artifact as last written or read, so an identical write is skipped. */
+	let storedSession: PersistedSession | null = null;
+
+	const writeSession = (
+		session: { refreshToken: string; profile: Profile; idToken?: string | undefined },
+		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 artifact: PersistedSession = {
+				refreshToken: session.refreshToken,
+				profile: storedProfileFrom(session.profile),
+				idToken: session.idToken,
+			};
+			// A restore that rotated nothing used to write the Keychain again on
+			// every launch, on the startup path (AUTH-23).
+			if (storedSession && sameSession(storedSession, artifact)) {
+				return;
+			}
+			await secureStore.setItem(AUTH_STORAGE_KEY, JSON.stringify(artifact));
+			storedSession = artifact;
 		});
 
 	const tokenManager = createAccessTokenManager({
@@ -155,6 +176,7 @@ export function createAuthMachine(config: AuthConfig, options: CreateAuthOptions
 		sessionEpoch += 1;
 		refreshToken = null;
 		idToken = null;
+		storedSession = null;
 		tokenManager.clear();
 		await enqueueStoreOp(() => secureStore.removeItem(AUTH_STORAGE_KEY));
 	}
@@ -193,6 +215,8 @@ export function createAuthMachine(config: AuthConfig, options: CreateAuthOptions
 				return getState();
 			}
 
+			storedSession = result.persisted ?? null;
+
 			if (result.outcome === 'restored' && result.profile && result.refreshToken) {
 				refreshToken = result.refreshToken;
 				idToken = result.idToken ?? null;
@@ -334,16 +358,17 @@ export function createAuthMachine(config: AuthConfig, options: CreateAuthOptions
 			return result;
 		},
 
-		async requestAccessToken(resourceKey) {
+		async requestAccessToken(resourceKey, tokenOptions) {
 			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);
+				state.status === 'authenticated' &&
+				(tokenOptions?.forceRefresh === true || !tokenManager.hasFreshToken(resourceKey));
 			if (refreshing) {
 				setState({ status: 'token-refreshing' });
 			}
-			const result = await tokenManager.request(resourceKey);
+			const result = await tokenManager.request(resourceKey, tokenOptions);
 			// 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') {
@@ -356,6 +381,11 @@ export function createAuthMachine(config: AuthConfig, options: CreateAuthOptions
 			return state.accessTier ?? failClosedTier();
 		},
 
+		canAccessPremium(): PremiumGateResult {
+			const tier = state.accessTier ?? failClosedTier();
+			return { allowed: tier.tier === 'premium' && tier.verification === 'verified', tier };
+		},
+
 		requirePremium(): PremiumGateResult {
 			const tier = state.accessTier ?? failClosedTier();
 			const allowed = tier.tier === 'premium' && tier.verification === 'verified';
@@ -365,6 +395,10 @@ export function createAuthMachine(config: AuthConfig, options: CreateAuthOptions
 			return { allowed, tier };
 		},
 
+		getMessages(): AuthMessageMap {
+			return messages;
+		},
+
 		getPlatformProvider() {
 			return defaultProviderForPlatform(config, platform);
 		},

package/src/core/profile.ts

@@ -41,7 +41,12 @@ export function mapClaimsToProfile(
 	};
 }
 
-/** Describe the external provider identity behind the profile (FR-004 edge cases). */
+/**
+ * Describe the external provider identity behind the profile (FR-004 edge
+ * cases). `emailBehavior` is what a screen needs to explain an address the user
+ * did not choose: Apple's private relay forwards mail and is not the address
+ * they type anywhere else.
+ */
 export function describeProviderIdentity(
 	claims: Record<string, unknown>,
 	providerId?: ProviderId,

package/src/core/session.ts

@@ -22,13 +22,50 @@ import { mapClaimsToProfile } from './profile';
 import { evaluateAccessTier, failClosedTier } from '../access/accessTier';
 import { isAuthError } from '../diagnostics/errors';
 
+/**
+ * The identity in the stored artifact: who, not what the token said.
+ *
+ * The whole claim set used to be written to the Keychain on every launch — all
+ * of it, groups included — for a value nothing reads back: the access tier is
+ * recomputed from fresh claims, and a restore that cannot reach the provider
+ * fails closed anyway (AUTH-23).
+ */
+export type StoredProfile = Omit<Profile, 'claims'>;
+
 export interface PersistedSession {
 	refreshToken: string;
-	profile: Profile;
+	profile: StoredProfile;
 	/** The id token hint for end-session (AUTH-04). Absent in artifacts written before 0.2.2. */
 	idToken?: string | undefined;
 }
 
+/** The artifact's identity as a profile. Artifacts written before 0.4.0 carry claims; they are kept. */
+export function profileFromStored(stored: StoredProfile | Profile): Profile {
+	return { ...stored, claims: 'claims' in stored ? (stored.claims ?? {}) : {} };
+}
+
+/** What goes to the store: everything but the claims. */
+export function storedProfileFrom(profile: Profile): StoredProfile {
+	return {
+		tenantUserId: profile.tenantUserId,
+		displayName: profile.displayName,
+		email: profile.email,
+		provider: profile.provider,
+	};
+}
+
+/** True when the artifact would be byte-identical, so the write can be skipped. */
+export function sameSession(a: PersistedSession, b: PersistedSession): boolean {
+	return (
+		a.refreshToken === b.refreshToken &&
+		a.idToken === b.idToken &&
+		a.profile.tenantUserId === b.profile.tenantUserId &&
+		a.profile.displayName === b.profile.displayName &&
+		a.profile.email === b.profile.email &&
+		a.profile.provider === b.profile.provider
+	);
+}
+
 export interface RestoreDeps {
 	secureStore: SecureTokenStore;
 	authority: string;
@@ -42,6 +79,8 @@ export interface RestoreDeps {
 export interface RestoreResult {
 	outcome: RestoreStatus;
 	profile?: Profile;
+	/** The artifact this restore read, so a rewrite that changes nothing can be skipped. */
+	persisted?: PersistedSession;
 	accessTier?: AccessTier;
 	refreshToken?: string;
 	idToken?: string | undefined;
@@ -82,7 +121,13 @@ export async function restoreSession(deps: RestoreDeps): Promise<RestoreResult>
 		const hasClaims = Object.keys(tokens.claims).length > 0;
 		return {
 			outcome: 'restored',
-			profile: hasClaims ? mapClaimsToProfile(tokens.claims) : persisted.profile,
+			persisted,
+			// The provider id came from the sign-in and is not in the claims: a
+			// refresh answered `idp: 'google.com'`, so a restored profile used to
+			// report a different provider than the same session did before (AUTH-10).
+			profile: hasClaims
+				? mapClaimsToProfile(tokens.claims, persisted.profile.provider)
+				: profileFromStored(persisted.profile),
 			accessTier: hasClaims ? evaluateAccessTier(tokens.claims, deps.mapping) : failClosedTier(),
 			refreshToken: tokens.refreshToken || persisted.refreshToken,
 			idToken: tokens.idToken || persisted.idToken,
@@ -96,7 +141,8 @@ export async function restoreSession(deps: RestoreDeps): Promise<RestoreResult>
 		// read-only and fail closed on entitlement; the next restore tries again.
 		return {
 			outcome: 'offline',
-			profile: persisted.profile,
+			persisted,
+			profile: profileFromStored(persisted.profile),
 			accessTier: failClosedTier(),
 			refreshToken: persisted.refreshToken,
 			idToken: persisted.idToken,

package/src/diagnostics/errors.ts

@@ -7,6 +7,8 @@
 
 import { COMMON_PATTERNS, SdkError, redactPatterns } from '@chipmobilesdk/rn-core';
 
+import type { AuthMessageKey } from './messageKeys';
+
 export type AuthErrorCode =
 	| 'configuration-error'
 	| 'provider-cancelled'
@@ -14,14 +16,14 @@ export type AuthErrorCode =
 	| 'token-acquisition-failed'
 	| 'session-expired'
 	| 'consent-denied'
-	| 'entitlement-unverified'
 	| 'network-unavailable';
 
 export type AuthErrorAudience = 'user' | 'developer';
 
 export interface AuthErrorArgs {
 	code: AuthErrorCode;
-	messageKey: string;
+	/** A key of this package's catalogue: the copy an app shows for this error. */
+	messageKey: AuthMessageKey;
 	audience?: AuthErrorAudience;
 	detail?: string | undefined;
 }
@@ -52,7 +54,7 @@ const RETRYABLE: ReadonlySet<AuthErrorCode> = new Set<AuthErrorCode>(['network-u
 /** The package's error; an `SdkError` (`@chipmobilesdk/rn-core`) with `pkg: 'rn-auth'`. */
 export class AuthError extends SdkError<AuthErrorCode> {
 	readonly audience: AuthErrorAudience;
-	readonly messageKey: string;
+	readonly messageKey: AuthMessageKey;
 	readonly detail?: string | undefined;
 
 	constructor(args: AuthErrorArgs) {
@@ -70,7 +72,7 @@ export class AuthError extends SdkError<AuthErrorCode> {
 }
 
 export class AuthConfigError extends AuthError {
-	constructor(messageKey: string, detail?: string) {
+	constructor(messageKey: AuthMessageKey, detail?: string) {
 		super({ code: 'configuration-error', messageKey, audience: 'developer', detail });
 		this.name = 'AuthConfigError';
 	}
@@ -84,7 +86,7 @@ export function isAuthError(value: unknown): value is AuthError {
 export function toAuthError(
 	value: unknown,
 	fallbackCode: AuthErrorCode = 'token-acquisition-failed',
-	fallbackMessageKey = 'auth.error.token',
+	fallbackMessageKey: AuthMessageKey = 'auth.error.token',
 ): AuthError {
 	if (isAuthError(value)) {
 		return value;

package/src/index.ts

@@ -25,6 +25,7 @@ export type {
 	ProviderIdentity,
 	ProviderConfig,
 	ProviderId,
+	KnownProviderId,
 	DevicePlatform,
 	ResourceConfig,
 	ClaimMatcher,
@@ -37,11 +38,16 @@ export type {
 } from './config/types';
 
 // Ports + default adapters
+export { describeProviderIdentity, mapClaimsToProfile } from './core/profile';
+
+export type { AccessTokenRequestOptions } from './tokens/accessToken';
 export type { SecureTokenStore } from './tokens/secureStore';
 export { createKeychainSecureStore, AUTH_STORAGE_KEY } from './tokens/secureStore';
 export type {
 	OidcAuthClient,
 	OidcTokens,
+	OidcServiceConfiguration,
+	AppAuthClientOptions,
 	AuthorizeParams,
 	RefreshParams,
 	EndSessionParams,
@@ -63,6 +69,7 @@ export { useAuthSelector } from './react/hooks';
 export type { AuthProviderProps } from './react/AuthProvider';
 export {
 	useAuth,
+	useAuthMessages,
 	useProfile,
 	useAccessTier,
 	useAccessToken,

package/src/oidc/authClient.ts

@@ -116,9 +116,24 @@ function base64UrlDecode(input: string): string {
 	}
 }
 
+/** The endpoints discovery would have returned, when an app already knows them. */
+export interface OidcServiceConfiguration {
+	authorizationEndpoint: string;
+	tokenEndpoint: string;
+	endSessionEndpoint?: string;
+	revocationEndpoint?: string;
+	registrationEndpoint?: string;
+}
+
 export interface AppAuthClientOptions {
 	/** When true, the OIDC discovery document is fetched from `${authority}`. */
 	useDiscovery?: boolean;
+	/**
+	 * Static endpoints, used instead of discovery. Every authorize, refresh and
+	 * sign-out otherwise costs the native module one `.well-known` round-trip,
+	 * including the refresh on the startup path (AUTH-08).
+	 */
+	serviceConfiguration?: OidcServiceConfiguration;
 }
 
 interface AppAuthModule {
@@ -165,7 +180,9 @@ const AppAuth: AppAuthModule = {
  * client). Validated on device (R8).
  */
 export function createAppAuthClient(options: AppAuthClientOptions = {}): OidcAuthClient {
-	const useDiscovery = options.useDiscovery ?? true;
+	const serviceConfiguration = options.serviceConfiguration;
+	// Discovery is pointless once the endpoints are given, whatever was asked for.
+	const useDiscovery = serviceConfiguration ? false : (options.useDiscovery ?? true);
 
 	const baseConfig = (
 		authority: string,
@@ -174,6 +191,7 @@ export function createAppAuthClient(options: AppAuthClientOptions = {}): OidcAut
 		scopes: string[],
 	) => ({
 		issuer: useDiscovery ? authority : undefined,
+		...(serviceConfiguration ? { serviceConfiguration } : {}),
 		clientId,
 		redirectUrl,
 		scopes,

package/src/oidc/classifyError.ts

@@ -12,10 +12,11 @@
  */
 
 import { AuthError, type AuthErrorCode } from '../diagnostics/errors';
+import type { AuthMessageKey } from '../diagnostics/messageKeys';
 
 export interface ClassificationRule {
 	readonly code: AuthErrorCode;
-	readonly messageKey: string;
+	readonly messageKey: AuthMessageKey;
 	/** Matched against the native error's `code` and `message`, case-insensitively. */
 	readonly pattern: RegExp;
 }

package/src/oidc/socialRouting.ts

@@ -37,7 +37,9 @@ export function resolveProvider(
 
 /** Build the OIDC additional parameters that route to the chosen IdP. */
 export function buildAdditionalParameters(provider: ProviderConfig): Record<string, string> {
-	return { domain_hint: provider.domainHint };
+	// The routing hint last: a provider's own parameters cannot redirect the flow
+	// to a different IdP than the one the user tapped.
+	return { ...provider.additionalParameters, domain_hint: provider.domainHint };
 }
 
 /**

package/src/react/hooks.ts

@@ -5,7 +5,7 @@
  */
 
 import { useExternalStore } from '@chipmobilesdk/rn-core/react';
-import { useCallback, useState } from 'react';
+import { useCallback, useEffect, useRef, useState } from 'react';
 import { useAuthInstance } from './AuthProvider';
 import type {
 	AccessTier,
@@ -18,6 +18,8 @@ import type {
 	ProviderId,
 } from '../config/types';
 import { failClosedTier } from '../access/accessTier';
+import type { AccessTokenRequestOptions } from '../tokens/accessToken';
+import type { AuthMessageMap } from '../diagnostics/messageKeys';
 
 export interface UseAuthResult {
 	state: AuthState;
@@ -25,6 +27,9 @@ export interface UseAuthResult {
 	signOut(): Promise<void>;
 	signOutGlobal(): Promise<GlobalSignOutResult>;
 	restore(): Promise<AuthState>;
+	/** Whether a premium-only path is open. Changes nothing: show the denial where it happened. */
+	canAccessPremium(): PremiumGateResult;
+	/** @deprecated Use `canAccessPremium`; this moves the whole controller to `access-denied` (AUTH-12). */
 	requirePremium(): PremiumGateResult;
 }
 
@@ -53,10 +58,16 @@ export function useAuth(): UseAuthResult {
 		signOut: useCallback(() => auth.signOut(), [auth]),
 		signOutGlobal: useCallback(() => auth.signOutGlobal(), [auth]),
 		restore: useCallback(() => auth.restore(), [auth]),
+		canAccessPremium: useCallback(() => auth.canAccessPremium(), [auth]),
 		requirePremium: useCallback(() => auth.requirePremium(), [auth]),
 	};
 }
 
+/** This package's copy, with the app's `messages` overrides applied. */
+export function useAuthMessages(): AuthMessageMap {
+	return useAuthInstance().getMessages();
+}
+
 export function useProfile(): Profile | undefined {
 	return useAuthSelector(selectProfile);
 }
@@ -83,21 +94,49 @@ export type UseAccessTokenStatus =
 export interface UseAccessTokenResult {
 	status: UseAccessTokenStatus;
 	token?: string | undefined;
-	request(): Promise<AccessTokenResult>;
+	/** `{ forceRefresh: true }` after a server refused the token this returned. */
+	request(options?: AccessTokenRequestOptions): Promise<AccessTokenResult>;
 }
 
 export function useAccessToken(resourceKey: string): UseAccessTokenResult {
 	const auth = useAuthInstance();
-	const [status, setStatus] = useState<UseAccessTokenStatus>('idle');
-	const [token, setToken] = useState<string | undefined>(undefined);
-
-	const request = useCallback(async () => {
-		setStatus('loading');
-		const result = await auth.requestAccessToken(resourceKey);
-		setStatus(result.status);
-		setToken(result.token);
-		return result;
-	}, [auth, resourceKey]);
-
-	return { status, token, request };
+	const [state, setState] = useState<{
+		status: UseAccessTokenStatus;
+		token?: string | undefined;
+		resourceKey: string;
+	}>({ status: 'idle', resourceKey });
+
+	// Which request may still write. A result for a resource the component has
+	// moved on from, or for an unmounted one, is dropped rather than applied
+	// (AUTH-17, standard VII).
+	const live = useRef(0);
+	useEffect(
+		() => () => {
+			live.current += 1;
+		},
+		[],
+	);
+
+	const request = useCallback(
+		async (options?: AccessTokenRequestOptions) => {
+			live.current += 1;
+			const id = live.current;
+			setState({ status: 'loading', resourceKey });
+			const result = await auth.requestAccessToken(resourceKey, options);
+			if (id === live.current) {
+				setState({ status: result.status, token: result.token, resourceKey });
+			}
+			return result;
+		},
+		[auth, resourceKey],
+	);
+
+	// A new resource starts from `idle`, not from the previous resource's token.
+	if (state.resourceKey !== resourceKey) {
+		live.current += 1;
+		setState({ status: 'idle', resourceKey });
+		return { status: 'idle', token: undefined, request };
+	}
+
+	return { status: state.status, token: state.token, request };
 }

package/src/tokens/accessToken.ts

@@ -13,7 +13,6 @@ const EXPIRY_SKEW_MS = 60_000;
 interface CachedToken {
 	token: string;
 	expiresAt: number;
-	scopes: string[];
 }
 
 export interface AccessTokenManagerDeps {
@@ -37,8 +36,19 @@ export interface AccessTokenManagerDeps {
 	onRefreshTokenRotated: (token: string, epoch: number) => Promise<void>;
 }
 
+export interface AccessTokenRequestOptions {
+	/**
+	 * Ignore the cached token and ask the provider for a new one.
+	 *
+	 * For the caller that just had one rejected: a token the server refused is
+	 * still unexpired by this device's clock, so asking again without this
+	 * returns the same token and the retry is the same request (AI-01).
+	 */
+	forceRefresh?: boolean;
+}
+
 export interface AccessTokenManager {
-	request(resourceKey: string): Promise<AccessTokenResult>;
+	request(resourceKey: string, options?: AccessTokenRequestOptions): Promise<AccessTokenResult>;
 	/** Whether `request` would answer from the cache, without touching the network. */
 	hasFreshToken(resourceKey: string): boolean;
 	clear(): void;
@@ -94,11 +104,7 @@ export function createAccessTokenManager(deps: AccessTokenManagerDeps): AccessTo
 				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,
-			});
+			cache.set(resourceKey, { token: tokens.accessToken, expiresAt });
 			return { resourceKey, status: 'success', token: tokens.accessToken, expiresAt };
 		} catch (error) {
 			if (isAuthError(error)) {
@@ -127,13 +133,18 @@ export function createAccessTokenManager(deps: AccessTokenManagerDeps): AccessTo
 			return fresh(resourceKey) !== undefined;
 		},
 
-		request(resourceKey): Promise<AccessTokenResult> {
+		request(resourceKey, options = {}): Promise<AccessTokenResult> {
 			const resource = deps.resources.find(entry => entry.key === resourceKey);
 			if (!resource) {
 				return Promise.resolve({ resourceKey, status: 'error', errorCode: 'configuration-error' });
 			}
 
-			const cached = fresh(resourceKey);
+			if (options.forceRefresh === true) {
+				// Dropped, not just skipped: the token is known bad, so no later
+				// caller should be handed it either.
+				cache.delete(resourceKey);
+			}
+			const cached = options.forceRefresh === true ? undefined : fresh(resourceKey);
 			if (cached) {
 				return Promise.resolve({
 					resourceKey,