@chipmobilesdk/rn-auth 0.3.0 → 0.4.0

package/src/oidc/socialRouting.ts

@@ -1,73 +1,66 @@
-/**
- * Social provider routing (FR-002/FR-003, R3). Google and Apple are federated
- * inside the External ID tenant; the app presents the platform-correct action
- * and starts the user flow with a per-provider `domain_hint`.
- */
-
-import type {
-	AuthConfig,
-	DevicePlatform,
-	ProviderConfig,
-	ProviderId,
-} from '../config/types';
-import { AuthConfigError } from '../diagnostics/errors';
-
-/** Find the configured provider, ensuring it is enabled for the platform. */
-export function resolveProvider(
-	config: AuthConfig,
-	providerId: ProviderId,
-	platform: DevicePlatform,
-): ProviderConfig {
-	const provider = config.providers.find(candidate => candidate.id === providerId);
-	if (!provider) {
-		throw new AuthConfigError(
-			'auth.error.configuration',
-			`Provider "${providerId}" is not configured`,
-		);
-	}
-	if (!provider.platforms.includes(platform)) {
-		throw new AuthConfigError(
-			'auth.error.configuration',
-			`Provider "${providerId}" is not enabled for platform "${platform}"`,
-		);
-	}
-	if (provider.available === false) {
-		throw new AuthConfigError(
-			'auth.error.configuration',
-			`Provider "${providerId}" is marked unavailable`,
-		);
-	}
-	return provider;
-}
-
-/** Build the OIDC additional parameters that route to the chosen IdP. */
-export function buildAdditionalParameters(
-	provider: ProviderConfig,
-): Record<string, string> {
-	return { domain_hint: provider.domainHint };
-}
-
-/**
- * All providers to present on a given platform, in configuration array order
- * (FR-003/FR-004). Filtered to providers enabled for the platform and not marked
- * unavailable.
- */
-export function availableProvidersForPlatform(
-	config: AuthConfig,
-	platform: DevicePlatform,
-): ProviderConfig[] {
-	return config.providers.filter(
-		provider => provider.platforms.includes(platform) && provider.available !== false,
-	);
-}
-
-/**
- * The first available provider for a platform (UX-004, back-compat). Equals
- * `availableProvidersForPlatform(config, platform)[0]`.
- */
-export function defaultProviderForPlatform(
-	config: AuthConfig,
-	platform: DevicePlatform,
-): ProviderConfig | undefined {
-	return availableProvidersForPlatform(config, platform)[0];
-}
+/**
+ * Social provider routing (FR-002/FR-003, R3). Google and Apple are federated
+ * inside the External ID tenant; the app presents the platform-correct action
+ * and starts the user flow with a per-provider `domain_hint`.
+ */
+
+import type { AuthConfig, DevicePlatform, ProviderConfig, ProviderId } from '../config/types';
+import { AuthConfigError } from '../diagnostics/errors';
+
+/** Find the configured provider, ensuring it is enabled for the platform. */
+export function resolveProvider(
+	config: AuthConfig,
+	providerId: ProviderId,
+	platform: DevicePlatform,
+): ProviderConfig {
+	const provider = config.providers.find(candidate => candidate.id === providerId);
+	if (!provider) {
+		throw new AuthConfigError(
+			'auth.error.configuration',
+			`Provider "${providerId}" is not configured`,
+		);
+	}
+	if (!provider.platforms.includes(platform)) {
+		throw new AuthConfigError(
+			'auth.error.configuration',
+			`Provider "${providerId}" is not enabled for platform "${platform}"`,
+		);
+	}
+	if (provider.available === false) {
+		throw new AuthConfigError(
+			'auth.error.configuration',
+			`Provider "${providerId}" is marked unavailable`,
+		);
+	}
+	return provider;
+}
+
+/** Build the OIDC additional parameters that route to the chosen IdP. */
+export function buildAdditionalParameters(provider: ProviderConfig): Record<string, string> {
+	return { domain_hint: provider.domainHint };
+}
+
+/**
+ * All providers to present on a given platform, in configuration array order
+ * (FR-003/FR-004). Filtered to providers enabled for the platform and not marked
+ * unavailable.
+ */
+export function availableProvidersForPlatform(
+	config: AuthConfig,
+	platform: DevicePlatform,
+): ProviderConfig[] {
+	return config.providers.filter(
+		provider => provider.platforms.includes(platform) && provider.available !== false,
+	);
+}
+
+/**
+ * The first available provider for a platform (UX-004, back-compat). Equals
+ * `availableProvidersForPlatform(config, platform)[0]`.
+ */
+export function defaultProviderForPlatform(
+	config: AuthConfig,
+	platform: DevicePlatform,
+): ProviderConfig | undefined {
+	return availableProvidersForPlatform(config, platform)[0];
+}

package/src/react/AuthProvider.tsx

@@ -1,47 +1,30 @@
-/**
- * React context boundary for the auth controller (LIB-002). Subscribes to the
- * controller and re-renders consumers on every state change.
- */
-
-import React, {
-	createContext,
-	useContext,
-	useEffect,
-	useMemo,
-	useState,
-} from 'react';
-import type { Auth, AuthState } from '../config/types';
-
-interface AuthContextValue {
-	auth: Auth;
-	state: AuthState;
-}
-
-const AuthContext = createContext<AuthContextValue | null>(null);
-
-export interface AuthProviderProps {
-	auth: Auth;
-	children: React.ReactNode;
-}
-
-export function AuthProvider({ auth, children }: AuthProviderProps) {
-	const [state, setState] = useState<AuthState>(() => auth.getState());
-
-	useEffect(() => {
-		// Sync immediately in case state changed between render and subscribe.
-		setState(auth.getState());
-		return auth.subscribe(setState);
-	}, [auth]);
-
-	const value = useMemo<AuthContextValue>(() => ({ auth, state }), [auth, state]);
-
-	return <AuthContext.Provider value={value}>{children}</AuthContext.Provider>;
-}
-
-export function useAuthContext(): AuthContextValue {
-	const value = useContext(AuthContext);
-	if (!value) {
-		throw new Error('useAuth must be used within an <AuthProvider>.');
-	}
-	return value;
-}
+/**
+ * React context boundary for the auth controller (LIB-002).
+ *
+ * The context carries the controller only, never its state: a context value that
+ * changed on every transition re-rendered every consumer on every transition
+ * (PERF-02). Hooks read the state through `useSyncExternalStore` with a selector,
+ * so a component re-renders only when the part it reads changes.
+ */
+
+import React, { createContext, useContext } from 'react';
+import type { Auth } from '../config/types';
+
+const AuthContext = createContext<Auth | null>(null);
+
+export interface AuthProviderProps {
+	auth: Auth;
+	children: React.ReactNode;
+}
+
+export function AuthProvider({ auth, children }: AuthProviderProps) {
+	return <AuthContext.Provider value={auth}>{children}</AuthContext.Provider>;
+}
+
+export function useAuthInstance(): Auth {
+	const auth = useContext(AuthContext);
+	if (!auth) {
+		throw new Error('useAuth must be used within an <AuthProvider>.');
+	}
+	return auth;
+}

package/src/react/hooks.ts

@@ -1,91 +1,103 @@
-/**
- * Public hooks (LIB-002). All read from the AuthProvider context so consumers
- * re-render on state changes.
- */
-
-import { useCallback, useState } from 'react';
-import { useAuthContext } from './AuthProvider';
-import type {
-	AccessTier,
-	AccessTokenResult,
-	AuthState,
-	GlobalSignOutResult,
-	PremiumGateResult,
-	Profile,
-	ProviderConfig,
-	ProviderId,
-} from '../config/types';
-import { failClosedTier } from '../access/accessTier';
-
-export interface UseAuthResult {
-	state: AuthState;
-	signIn(providerId: ProviderId): Promise<AuthState>;
-	signOut(): Promise<void>;
-	signOutGlobal(): Promise<GlobalSignOutResult>;
-	restore(): Promise<AuthState>;
-	requirePremium(): PremiumGateResult;
-}
-
-export function useAuth(): UseAuthResult {
-	const { auth, state } = useAuthContext();
-	return {
-		state,
-		signIn: useCallback((providerId: ProviderId) => auth.signIn(providerId), [auth]),
-		signOut: useCallback(() => auth.signOut(), [auth]),
-		signOutGlobal: useCallback(() => auth.signOutGlobal(), [auth]),
-		restore: useCallback(() => auth.restore(), [auth]),
-		requirePremium: useCallback(() => auth.requirePremium(), [auth]),
-	};
-}
-
-export function useProfile(): Profile | undefined {
-	const { state } = useAuthContext();
-	return state.profile;
-}
-
-export function useAccessTier(): AccessTier {
-	const { state } = useAuthContext();
-	return state.accessTier ?? failClosedTier();
-}
-
-/** The first provider to present on the current platform (UX-004), or undefined. */
-export function useSignInProvider(): ProviderConfig | undefined {
-	const { auth } = useAuthContext();
-	return auth.getPlatformProvider();
-}
-
-/** All available providers for the current platform, in configuration order (FR-003/FR-004). */
-export function useSignInProviders(): ProviderConfig[] {
-	const { auth } = useAuthContext();
-	return auth.getPlatformProviders();
-}
-
-export type UseAccessTokenStatus =
-	| 'idle'
-	| 'loading'
-	| 'success'
-	| 'denied'
-	| 'unavailable'
-	| 'error';
-
-export interface UseAccessTokenResult {
-	status: UseAccessTokenStatus;
-	token?: string;
-	request(): Promise<AccessTokenResult>;
-}
-
-export function useAccessToken(resourceKey: string): UseAccessTokenResult {
-	const { auth } = useAuthContext();
-	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 };
-}
+/**
+ * Public hooks (LIB-002). Each reads the controller's state through
+ * `useSyncExternalStore` (rn-core's `useExternalStore`), selecting only what it
+ * returns, so `useProfile` does not re-render when only the status changes.
+ */
+
+import { useExternalStore } from '@chipmobilesdk/rn-core/react';
+import { useCallback, useState } from 'react';
+import { useAuthInstance } from './AuthProvider';
+import type {
+	AccessTier,
+	AccessTokenResult,
+	AuthState,
+	GlobalSignOutResult,
+	PremiumGateResult,
+	Profile,
+	ProviderConfig,
+	ProviderId,
+} from '../config/types';
+import { failClosedTier } from '../access/accessTier';
+
+export interface UseAuthResult {
+	state: AuthState;
+	signIn(providerId: ProviderId): Promise<AuthState>;
+	signOut(): Promise<void>;
+	signOutGlobal(): Promise<GlobalSignOutResult>;
+	restore(): Promise<AuthState>;
+	requirePremium(): PremiumGateResult;
+}
+
+/**
+ * Any slice of the auth state; the component re-renders only when the slice
+ * changes by `isEqual` (default `Object.is`).
+ */
+export function useAuthSelector<Selected>(
+	select: (state: AuthState) => Selected,
+	isEqual?: (a: Selected, b: Selected) => boolean,
+): Selected {
+	const auth = useAuthInstance();
+	return useExternalStore(auth.subscribe, auth.getState, select, isEqual);
+}
+
+const selectState = (state: AuthState) => state;
+const selectProfile = (state: AuthState) => state.profile;
+const selectAccessTier = (state: AuthState) => state.accessTier;
+
+export function useAuth(): UseAuthResult {
+	const auth = useAuthInstance();
+	const state = useAuthSelector(selectState);
+	return {
+		state,
+		signIn: useCallback((providerId: ProviderId) => auth.signIn(providerId), [auth]),
+		signOut: useCallback(() => auth.signOut(), [auth]),
+		signOutGlobal: useCallback(() => auth.signOutGlobal(), [auth]),
+		restore: useCallback(() => auth.restore(), [auth]),
+		requirePremium: useCallback(() => auth.requirePremium(), [auth]),
+	};
+}
+
+export function useProfile(): Profile | undefined {
+	return useAuthSelector(selectProfile);
+}
+
+export function useAccessTier(): AccessTier {
+	return useAuthSelector(selectAccessTier) ?? failClosedTier();
+}
+
+/** The first provider to present on the current platform (UX-004), or undefined. */
+export function useSignInProvider(): ProviderConfig | undefined {
+	const auth = useAuthInstance();
+	return auth.getPlatformProvider();
+}
+
+/** All available providers for the current platform, in configuration order (FR-003/FR-004). */
+export function useSignInProviders(): ProviderConfig[] {
+	const auth = useAuthInstance();
+	return auth.getPlatformProviders();
+}
+
+export type UseAccessTokenStatus =
+	'idle' | 'loading' | 'success' | 'denied' | 'unavailable' | 'error';
+
+export interface UseAccessTokenResult {
+	status: UseAccessTokenStatus;
+	token?: string | undefined;
+	request(): 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 };
+}

package/src/testing/conformance.ts

@@ -0,0 +1,177 @@
+/**
+ * What any `SecureTokenStore` and `OidcAuthClient` must do (IOS-12, AUTH-13).
+ *
+ * The same checks run against the in-memory doubles and against the keychain and
+ * app-auth adapters (native modules mocked in Jest, or for real from a demo
+ * screen on a device), so a test that drives a double proves something about the
+ * device path. Each check builds its own subject through a harness.
+ */
+import {
+	ensure,
+	runChecks,
+	type Check,
+	type ConformanceReport,
+} from '@chipmobilesdk/rn-core/testing';
+
+import type { OidcAuthClient } from '../oidc/authClient';
+import type { SecureTokenStore } from '../tokens/secureStore';
+
+export interface SecureStoreHarness {
+	/** An empty store. */
+	create(): SecureTokenStore;
+}
+
+export interface OidcSubject {
+	readonly client: OidcAuthClient;
+	/** The identity provider answers sign-in and refresh with tokens for these claims. */
+	issues(claims: Record<string, unknown>): void;
+	/** The user closes the sign-in sheet. */
+	userCancels(): void;
+	/** The provider no longer accepts the refresh token. */
+	rejectsRefresh(): void;
+}
+
+export interface OidcHarness {
+	create(): OidcSubject;
+}
+
+const KEY = '@chipmobilesdk/rn-auth/conformance';
+const OTHER_KEY = '@chipmobilesdk/rn-auth/conformance-other';
+
+export const secureTokenStoreChecks: readonly Check<SecureStoreHarness>[] = [
+	{
+		name: 'reads nothing for a key never written',
+		async run(harness) {
+			const value = await harness.create().getItem(KEY);
+			ensure(value === null, `expected null, got ${JSON.stringify(value)}`);
+		},
+	},
+	{
+		name: 'reads back the last value written',
+		async run(harness) {
+			const store = harness.create();
+			await store.setItem(KEY, 'first');
+			await store.setItem(KEY, 'second');
+			const value = await store.getItem(KEY);
+			ensure(value === 'second', `expected the last write, got ${JSON.stringify(value)}`);
+		},
+	},
+	{
+		name: 'keeps keys apart',
+		async run(harness) {
+			const store = harness.create();
+			await store.setItem(KEY, 'one');
+			await store.setItem(OTHER_KEY, 'two');
+			await store.removeItem(OTHER_KEY);
+			ensure((await store.getItem(KEY)) === 'one', 'removing one key touched another');
+		},
+	},
+	{
+		name: 'forgets a removed key, and removes a missing key safely',
+		async run(harness) {
+			const store = harness.create();
+			await store.removeItem(KEY);
+			await store.setItem(KEY, 'value');
+			await store.removeItem(KEY);
+			ensure((await store.getItem(KEY)) === null, 'a removed key still reads back');
+		},
+	},
+	{
+		name: 'keeps a long session artifact with non-ASCII text intact',
+		async run(harness) {
+			const store = harness.create();
+			const artifact = JSON.stringify({ name: 'Nguyễn Ánh', pad: 'x'.repeat(4096) });
+			await store.setItem(KEY, artifact);
+			ensure((await store.getItem(KEY)) === artifact, 'the artifact changed on the way back');
+		},
+	},
+];
+
+const SIGN_IN = {
+	authority: 'https://login.example.com/tenant/v2.0',
+	clientId: 'conformance-client',
+	redirectUrl: 'com.example.app://auth',
+	scopes: ['openid', 'offline_access'],
+};
+
+function codeOf(error: unknown): unknown {
+	return (error as { code?: unknown } | null)?.code;
+}
+
+export const oidcAuthClientChecks: readonly Check<OidcHarness>[] = [
+	{
+		name: 'signs in with an access token, the id-token claims and a future expiry',
+		async run(harness) {
+			const subject = harness.create();
+			subject.issues({ oid: 'user-1', name: 'Ada' });
+			const before = Date.now();
+			const tokens = await subject.client.authorize(SIGN_IN);
+			ensure(
+				typeof tokens.accessToken === 'string' && tokens.accessToken !== '',
+				'no access token',
+			);
+			ensure(tokens.claims.oid === 'user-1', `claims ${JSON.stringify(tokens.claims)}`);
+			ensure(
+				tokens.accessTokenExpiresAt === undefined || tokens.accessTokenExpiresAt > before,
+				'the access token expires in the past',
+			);
+		},
+	},
+	{
+		name: 'refreshes with a refresh token',
+		async run(harness) {
+			const subject = harness.create();
+			subject.issues({ oid: 'user-1' });
+			const tokens = await subject.client.refresh({ ...SIGN_IN, refreshToken: 'refresh-1' });
+			ensure(
+				typeof tokens.accessToken === 'string' && tokens.accessToken !== '',
+				'no access token',
+			);
+		},
+	},
+	{
+		name: 'reports a closed sign-in sheet as provider-cancelled',
+		async run(harness) {
+			const subject = harness.create();
+			subject.userCancels();
+			let code: unknown;
+			try {
+				await subject.client.authorize(SIGN_IN);
+			} catch (error) {
+				code = codeOf(error);
+			}
+			ensure(code === 'provider-cancelled', `expected provider-cancelled, got ${String(code)}`);
+		},
+	},
+	{
+		name: 'reports a rejected refresh token as session-expired',
+		async run(harness) {
+			const subject = harness.create();
+			subject.rejectsRefresh();
+			let code: unknown;
+			try {
+				await subject.client.refresh({ ...SIGN_IN, refreshToken: 'revoked' });
+			} catch (error) {
+				code = codeOf(error);
+			}
+			ensure(code === 'session-expired', `expected session-expired, got ${String(code)}`);
+		},
+	},
+	{
+		name: 'ends the session',
+		async run(harness) {
+			const subject = harness.create();
+			await subject.client.endSession({ ...SIGN_IN, idToken: undefined });
+		},
+	},
+];
+
+export function runSecureTokenStoreConformance(
+	harness: SecureStoreHarness,
+): Promise<ConformanceReport> {
+	return runChecks(() => harness, secureTokenStoreChecks);
+}
+
+export function runOidcAuthClientConformance(harness: OidcHarness): Promise<ConformanceReport> {
+	return runChecks(() => harness, oidcAuthClientChecks);
+}

package/src/testing/index.ts

@@ -0,0 +1,30 @@
+/**
+ * `@chipmobilesdk/rn-auth/testing`: test doubles and the port conformance suites.
+ *
+ * A separate entrypoint so neither can reach a production bundle.
+ */
+import type { SecureTokenStore } from '../tokens/secureStore';
+
+/** A `SecureTokenStore` held in memory, for tests and for the conformance suite. */
+export function createMemorySecureStore(seed: Record<string, string> = {}): SecureTokenStore {
+	const values = new Map<string, string>(Object.entries(seed));
+	return {
+		async getItem(key) {
+			return values.get(key) ?? null;
+		},
+		async setItem(key, value) {
+			values.set(key, value);
+		},
+		async removeItem(key) {
+			values.delete(key);
+		},
+	};
+}
+
+export {
+	oidcAuthClientChecks,
+	runOidcAuthClientConformance,
+	runSecureTokenStoreConformance,
+	secureTokenStoreChecks,
+} from './conformance';
+export type { OidcHarness, OidcSubject, SecureStoreHarness } from './conformance';