@chipmobilesdk/rn-auth 0.3.0 → 0.4.0

package/src/core/authMachine.ts

@@ -1,364 +1,380 @@
-/**
- * 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';
-import type {
-	Auth,
-	AuthConfig,
-	AuthState,
-	CreateAuthOptions,
-	DevicePlatform,
-	GlobalSignOutResult,
-	PremiumGateResult,
-	Profile,
-	ProviderId,
-} from '../config/types';
-import { validateConfig } from '../config/validateConfig';
-import { createAppAuthClient } from '../oidc/authClient';
-import {
-	availableProvidersForPlatform,
-	buildAdditionalParameters,
-	defaultProviderForPlatform,
-	resolveProvider,
-} from '../oidc/socialRouting';
-import { mapClaimsToProfile } from './profile';
-import { evaluateAccessTier, failClosedTier } from '../access/accessTier';
-import { restoreSession, type PersistedSession } from './session';
-import { AUTH_STORAGE_KEY } from '../tokens/secureStore';
-import { createAccessTokenManager } from '../tokens/accessToken';
-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,
-	options: CreateAuthOptions = {},
-): Auth {
-	// Throws AuthConfigError before anything else (FR-005, US4 scenario 2).
-	validateConfig(config);
-
-	const platform: DevicePlatform =
-		options.platform ?? ((Platform?.OS as DevicePlatform) ?? 'ios');
-	const secureStore = config.secureStore;
-	const authClient = config.authClient ?? createAppAuthClient();
-	const resources = config.resources ?? [];
-
-	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,
-		clientId: config.clientId,
-		redirectUrl: config.redirectUrl,
-		resources,
-		authClient,
-		getRefreshToken: () => refreshToken,
-		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.
-			}
-		},
-	});
-
-	function getState(): AuthState {
-		return { ...state };
-	}
-
-	function setState(patch: Partial<AuthState>): void {
-		state = { ...state, ...patch };
-		// 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 */
-			}
-		}
-	}
-
-	/** 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 enqueueStoreOp(() => secureStore.removeItem(AUTH_STORAGE_KEY));
-	}
-
-	return {
-		getState,
-
-		subscribe(listener) {
-			listeners.add(listener);
-			return () => {
-				listeners.delete(listener);
-			};
-		},
-
-		async restore() {
-			sessionEpoch += 1;
-			const epoch = sessionEpoch;
-			setState({ status: 'loading', restore: 'pending', error: undefined });
-
-			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,
-					accessTier: result.accessTier,
-					restore: 'restored',
-					error: undefined,
-				});
-			} else if (result.outcome === 'offline' && result.profile) {
-				refreshToken = result.refreshToken ?? null;
-				idToken = result.idToken ?? null;
-				setState({
-					status: 'authenticated',
-					profile: result.profile,
-					accessTier: result.accessTier ?? failClosedTier(),
-					restore: 'offline',
-					error: undefined,
-				});
-			} else {
-				await clearPersisted();
-				setState(SIGNED_OUT);
-			}
-			return getState();
-		},
-
-		async signIn(providerId: ProviderId) {
-			sessionEpoch += 1;
-			const epoch = sessionEpoch;
-			setState({ status: 'authenticating', error: undefined });
-			let provider;
-			try {
-				provider = resolveProvider(config, providerId, platform);
-			} catch (error) {
-				setState({ status: 'error', error: toAuthError(error, 'configuration-error', 'auth.error.configuration') });
-				return getState();
-			}
-
-			try {
-				const tokens = await authClient.authorize({
-					authority: config.authority,
-					clientId: config.clientId,
-					redirectUrl: config.redirectUrl,
-					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();
-				setState({
-					status: 'authenticated',
-					profile,
-					accessTier,
-					restore: 'restored',
-					error: undefined,
-				});
-			} catch (error) {
-				if (epoch !== sessionEpoch) {
-					return getState();
-				}
-				const authError = toAuthError(error);
-				if (authError.code === 'provider-cancelled') {
-					setState({ status: 'cancelled', error: authError });
-				} else {
-					setState({ status: 'error', error: authError });
-				}
-			}
-			return getState();
-		},
-
-		async signOut() {
-			await clearPersisted();
-			setState(SIGNED_OUT);
-		},
-
-		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 (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(SIGNED_OUT);
-			return result;
-		},
-
-		async requestAccessToken(resourceKey) {
-			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);
-			// 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;
-		},
-
-		getAccessTier() {
-			return state.accessTier ?? failClosedTier();
-		},
-
-		requirePremium(): PremiumGateResult {
-			const tier = state.accessTier ?? failClosedTier();
-			const allowed = tier.tier === 'premium' && tier.verification === 'verified';
-			if (!allowed) {
-				setState({ status: 'access-denied' });
-			}
-			return { allowed, tier };
-		},
-
-		getPlatformProvider() {
-			return defaultProviderForPlatform(config, platform);
-		},
-
-		getPlatformProviders() {
-			return availableProvidersForPlatform(config, platform);
-		},
-	};
-}
-
-export type { Profile };
+/**
+ * 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 {
+	createDiagnosticChannel,
+	createListenerSet,
+	currentPlatform,
+	shallowEqual,
+} from '@chipmobilesdk/rn-core';
+
+import type {
+	Auth,
+	AuthConfig,
+	AuthState,
+	CreateAuthOptions,
+	DevicePlatform,
+	GlobalSignOutResult,
+	PremiumGateResult,
+	Profile,
+	ProviderId,
+} from '../config/types';
+import { validateConfig } from '../config/validateConfig';
+import { createAppAuthClient } from '../oidc/authClient';
+import {
+	availableProvidersForPlatform,
+	buildAdditionalParameters,
+	defaultProviderForPlatform,
+	resolveProvider,
+} from '../oidc/socialRouting';
+import { mapClaimsToProfile } from './profile';
+import { evaluateAccessTier, failClosedTier } from '../access/accessTier';
+import { restoreSession, type PersistedSession } from './session';
+import { AUTH_STORAGE_KEY } from '../tokens/secureStore';
+import { createAccessTokenManager } from '../tokens/accessToken';
+import { AuthError, toAuthError, type AuthErrorCode } from '../diagnostics/errors';
+
+const SIGNED_OUT: Partial<AuthState> = {
+	status: 'signed-out',
+	profile: undefined,
+	accessTier: undefined,
+	restore: 'unavailable',
+	error: undefined,
+};
+
+export function createAuthMachine(config: AuthConfig, options: CreateAuthOptions = {}): Auth {
+	// Throws AuthConfigError before anything else (FR-005, US4 scenario 2).
+	validateConfig(config);
+
+	// rn-core's one platform source (CORE-09). Outside Android and iOS (tests on
+	// Node, web) the providers are resolved as for iOS, as before.
+	const detected = currentPlatform();
+	const platform: DevicePlatform =
+		options.platform ?? (detected === 'unsupported' ? 'ios' : detected);
+	const secureStore = config.secureStore;
+	const authClient = config.authClient ?? createAppAuthClient();
+	const resources = config.resources ?? [];
+
+	let state: AuthState = Object.freeze({ 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 = createListenerSet<[AuthState]>();
+	/**
+	 * 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,
+		clientId: config.clientId,
+		redirectUrl: config.redirectUrl,
+		resources,
+		authClient,
+		getRefreshToken: () => refreshToken,
+		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.
+			}
+		},
+	});
+
+	/**
+	 * The current snapshot, the same object until the state changes, so React reads
+	 * it through `useSyncExternalStore` without re-rendering for nothing (PERF-02).
+	 * Frozen: a consumer cannot change the machine's state by mutating it.
+	 */
+	function getState(): AuthState {
+		return state;
+	}
+
+	function setState(patch: Partial<AuthState>): void {
+		const next = { ...state, ...patch };
+		// No change, no new snapshot and no notification.
+		if (shallowEqual(state, next)) return;
+		state = Object.freeze(next);
+		if (patch.error) {
+			// The code and audience only; `detail` is already redacted but stays local.
+			channel.emit(patch.error.code, patch.error.audience === 'user' ? 'info' : 'warn', {
+				status: state.status,
+				retryable: patch.error.retryable,
+			});
+		}
+		// Isolated: a subscriber that throws neither stops the others nor turns a
+		// completed sign-in into an error; rn-core reports it instead (CORE-03).
+		listeners.notify(getState());
+	}
+
+	/** 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 enqueueStoreOp(() => secureStore.removeItem(AUTH_STORAGE_KEY));
+	}
+
+	return {
+		getState,
+
+		subscribe: listener => listeners.add(listener),
+
+		async restore() {
+			sessionEpoch += 1;
+			const epoch = sessionEpoch;
+			setState({ status: 'loading', restore: 'pending', error: undefined });
+
+			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,
+					accessTier: result.accessTier,
+					restore: 'restored',
+					error: undefined,
+				});
+			} else if (result.outcome === 'offline' && result.profile) {
+				refreshToken = result.refreshToken ?? null;
+				idToken = result.idToken ?? null;
+				setState({
+					status: 'authenticated',
+					profile: result.profile,
+					accessTier: result.accessTier ?? failClosedTier(),
+					restore: 'offline',
+					error: undefined,
+				});
+			} else {
+				await clearPersisted();
+				setState(SIGNED_OUT);
+			}
+			return getState();
+		},
+
+		async signIn(providerId: ProviderId) {
+			sessionEpoch += 1;
+			const epoch = sessionEpoch;
+			setState({ status: 'authenticating', error: undefined });
+			let provider;
+			try {
+				provider = resolveProvider(config, providerId, platform);
+			} catch (error) {
+				setState({
+					status: 'error',
+					error: toAuthError(error, 'configuration-error', 'auth.error.configuration'),
+				});
+				return getState();
+			}
+
+			try {
+				const tokens = await authClient.authorize({
+					authority: config.authority,
+					clientId: config.clientId,
+					redirectUrl: config.redirectUrl,
+					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();
+				setState({
+					status: 'authenticated',
+					profile,
+					accessTier,
+					restore: 'restored',
+					error: undefined,
+				});
+			} catch (error) {
+				if (epoch !== sessionEpoch) {
+					return getState();
+				}
+				const authError = toAuthError(error);
+				if (authError.code === 'provider-cancelled') {
+					setState({ status: 'cancelled', error: authError });
+				} else {
+					setState({ status: 'error', error: authError });
+				}
+			}
+			return getState();
+		},
+
+		async signOut() {
+			await clearPersisted();
+			setState(SIGNED_OUT);
+		},
+
+		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 (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(SIGNED_OUT);
+			return result;
+		},
+
+		async requestAccessToken(resourceKey) {
+			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);
+			// 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;
+		},
+
+		getAccessTier() {
+			return state.accessTier ?? failClosedTier();
+		},
+
+		requirePremium(): PremiumGateResult {
+			const tier = state.accessTier ?? failClosedTier();
+			const allowed = tier.tier === 'premium' && tier.verification === 'verified';
+			if (!allowed) {
+				setState({ status: 'access-denied' });
+			}
+			return { allowed, tier };
+		},
+
+		getPlatformProvider() {
+			return defaultProviderForPlatform(config, platform);
+		},
+
+		getPlatformProviders() {
+			return availableProvidersForPlatform(config, platform);
+		},
+	};
+}
+
+export type { Profile };
+/** Every error the machine lands in also goes to the app's SDK sinks (CORE-08). */
+const channel = createDiagnosticChannel<AuthErrorCode>('rn-auth');