@chipmobilesdk/rn-auth 0.3.1 → 0.5.0

package/src/oidc/authClient.ts

@@ -6,23 +6,27 @@
  * requires react-native-app-auth and is validated on device.
  */
 
+import { lazyPeer } from '@chipmobilesdk/rn-core';
+
+import { AuthConfigError } from '../diagnostics/errors';
+
 import { classifyAppAuthError } from './classifyError';
 
 export interface OidcTokens {
 	/** Resource/audience access token (present for authorize and resource refresh). */
-	accessToken?: string;
+	accessToken?: string | undefined;
 	/**
 	 * 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;
+	refreshToken?: string | undefined;
 	/** Raw id token (JWT). Absent from a refresh requested without `openid`. */
-	idToken?: string;
+	idToken?: string | undefined;
 	/** Decoded id-token (or access-token) claims used for profile + access tier. */
 	claims: Record<string, unknown>;
 	/** Access-token expiry in epoch milliseconds, when available. */
-	accessTokenExpiresAt?: number;
+	accessTokenExpiresAt?: number | undefined;
 }
 
 export interface AuthorizeParams {
@@ -46,7 +50,7 @@ export interface EndSessionParams {
 	authority: string;
 	clientId: string;
 	redirectUrl: string;
-	idToken?: string;
+	idToken?: string | undefined;
 }
 
 export interface OidcAuthClient {
@@ -60,12 +64,12 @@ export function decodeJwtClaims(jwt: string | null | undefined): Record<string,
 	if (typeof jwt !== 'string') {
 		return {};
 	}
-	const parts = jwt.split('.');
-	if (parts.length < 2) {
+	const [, payload] = jwt.split('.');
+	if (payload === undefined) {
 		return {};
 	}
 	try {
-		const json = base64UrlDecode(parts[1]);
+		const json = base64UrlDecode(payload);
 		return JSON.parse(json) as Record<string, unknown>;
 	} catch {
 		return {};
@@ -112,19 +116,73 @@ 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 {
+	authorize(config: Record<string, unknown>): Promise<Record<string, unknown>>;
+	refresh(
+		config: Record<string, unknown>,
+		params: { refreshToken: string },
+	): Promise<Record<string, unknown>>;
+	logout(config: Record<string, unknown>, params: Record<string, unknown>): Promise<unknown>;
 }
 
+/**
+ * Loaded on the first sign-in, refresh or sign-out, never at startup (PERF-05):
+ * creating the client, or the whole auth instance, loads no native code.
+ */
+const appAuthPeer = lazyPeer('react-native-app-auth', () => {
+	// Inside `try`, so Metro bundles an app that leaves this optional peer out.
+	try {
+		return require('react-native-app-auth') as AppAuthModule;
+	} catch (cause) {
+		throw cause;
+	}
+});
+
+function appAuth(): AppAuthModule {
+	return appAuthPeer.require(
+		peer =>
+			new AuthConfigError(
+				'auth.error.configuration',
+				`${peer} is not installed or its native module is not linked`,
+			),
+	);
+}
+
+/** The module's calls, resolved only when one is made. */
+const AppAuth: AppAuthModule = {
+	authorize: config => appAuth().authorize(config),
+	refresh: (config, params) => appAuth().refresh(config, params),
+	logout: (config, params) => appAuth().logout(config, params),
+};
+
 /**
  * Default OidcAuthClient adapter wrapping react-native-app-auth (PKCE public
- * client). Lazily requires the native module. Validated on device (R8).
+ * client). Validated on device (R8).
  */
 export function createAppAuthClient(options: AppAuthClientOptions = {}): OidcAuthClient {
-	// Lazy require so injecting a fake client never loads native code.
-	const AppAuth = require('react-native-app-auth');
-	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,
@@ -133,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/AuthProvider.tsx

@@ -1,17 +1,16 @@
 /**
- * React context boundary for the auth controller (LIB-002). Subscribes to the
- * controller and re-renders consumers on every state change.
+ * 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, useEffect, useMemo, useState } from 'react';
-import type { Auth, AuthState } from '../config/types';
+import React, { createContext, useContext } from 'react';
+import type { Auth } from '../config/types';
 
-interface AuthContextValue {
-	auth: Auth;
-	state: AuthState;
-}
-
-const AuthContext = createContext<AuthContextValue | null>(null);
+const AuthContext = createContext<Auth | null>(null);
 
 export interface AuthProviderProps {
 	auth: Auth;
@@ -19,23 +18,13 @@ export interface AuthProviderProps {
 }
 
 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>;
+	return <AuthContext.Provider value={auth}>{children}</AuthContext.Provider>;
 }
 
-export function useAuthContext(): AuthContextValue {
-	const value = useContext(AuthContext);
-	if (!value) {
+export function useAuthInstance(): Auth {
+	const auth = useContext(AuthContext);
+	if (!auth) {
 		throw new Error('useAuth must be used within an <AuthProvider>.');
 	}
-	return value;
+	return auth;
 }

package/src/react/hooks.ts

@@ -1,10 +1,12 @@
 /**
- * Public hooks (LIB-002). All read from the AuthProvider context so consumers
- * re-render on state changes.
+ * 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 { useCallback, useState } from 'react';
-import { useAuthContext } from './AuthProvider';
+import { useExternalStore } from '@chipmobilesdk/rn-core/react';
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { useAuthInstance } from './AuthProvider';
 import type {
 	AccessTier,
 	AccessTokenResult,
@@ -16,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;
@@ -23,40 +27,64 @@ 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;
 }
 
+/**
+ * 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, state } = useAuthContext();
+	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]),
+		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 {
-	const { state } = useAuthContext();
-	return state.profile;
+	return useAuthSelector(selectProfile);
 }
 
 export function useAccessTier(): AccessTier {
-	const { state } = useAuthContext();
-	return state.accessTier ?? failClosedTier();
+	return useAuthSelector(selectAccessTier) ?? failClosedTier();
 }
 
 /** The first provider to present on the current platform (UX-004), or undefined. */
 export function useSignInProvider(): ProviderConfig | undefined {
-	const { auth } = useAuthContext();
+	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 } = useAuthContext();
+	const auth = useAuthInstance();
 	return auth.getPlatformProviders();
 }
 
@@ -65,22 +93,50 @@ export type UseAccessTokenStatus =
 
 export interface UseAccessTokenResult {
 	status: UseAccessTokenStatus;
-	token?: string;
-	request(): Promise<AccessTokenResult>;
+	token?: string | undefined;
+	/** `{ forceRefresh: true }` after a server refused the token this returned. */
+	request(options?: AccessTokenRequestOptions): 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 };
+	const auth = useAuthInstance();
+	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/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';

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,