@chipmobilesdk/rn-auth 0.3.1 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,118 @@
 # @chipmobilesdk/rn-auth
 
+## 0.4.0
+
+### Minor Changes
+
+- One diagnostic stream: install a sink with `installSdkSink` from
+  `@chipmobilesdk/rn-core` and it receives what every package observes (events,
+  failures, warnings) as `SdkDiagnostic`s, redacted. Listeners are notified through
+  rn-core, so a listener that throws no longer stops the others nor fails the call that
+  notified, and its error is reported rather than swallowed. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-ads: a banner's auto-refresh is a new cycle, so its `loaded` and `impression`
+    events are no longer deduplicated away; the dedupe memory is bounded. A throwing
+    status, consent or placement listener is reported as an `internal_error` event.
+  - rn-i18n: new `onDiagnostic` config receives every diagnostic (`I18nDiagnostic`,
+    with a stable `code`); without it, warnings go to `console.warn` in development
+    builds only. The warn-once memory is bounded.
+  - rn-chart: now depends on rn-core for its diagnostics.
+  - rn-payment: status, entitlement and pending listeners report a throw to the logger
+    instead of swallowing it.
+
+- The package's errors extend `SdkError` from the new `@chipmobilesdk/rn-core`
+  dependency: `isSdkError` recognises them alongside every other package's, and each
+  carries `pkg`, `code` and `retryable`. Names and codes are unchanged. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-ai and rn-camera: `retryable` is the new name of `recoverable`, which stays as a
+    deprecated alias.
+  - rn-auth: `retryable` is true for `network-unavailable`. `redact` also removes URLs,
+    e-mail addresses and UUIDs.
+  - rn-ads: `redact` also removes JWTs and e-mail addresses, and reduces an `AdsError`
+    to its code.
+  - rn-ai: an error message quoted from the gateway is pattern-redacted.
+  - rn-camera: `redact` also removes JWTs, e-mail addresses and UUIDs.
+  - rn-theme: `ThemeConfigError` has `code: 'invalid_config'` and `ThemeContrastError`
+    `code: 'contrast'` (new `ThemeErrorCode` type).
+  - rn-i18n: `I18nConfigError` has `code: 'invalid_config'` and `UnitConversionError`
+    `code: 'unit_conversion'` (new `I18nErrorCode` type).
+
+- Native peers load through `lazyPeer` from `@chipmobilesdk/rn-core`, on first use,
+  and a missing one is each package's own typed error. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-auth: creating `auth` no longer loads react-native-app-auth or
+    react-native-keychain; each loads on first use. New entrypoints
+    `@chipmobilesdk/rn-auth/app-auth` and `/keychain`. The default platform comes from
+    rn-core.
+  - rn-camera: a preview whose VisionCamera feed cannot load fails the session with
+    `cameraUnavailable` (new `controller.reportSurfaceUnavailable()`), instead of
+    showing black with no error. A missing VisionCamera module is `cameraUnavailable`.
+  - rn-notification: `createMmkvStore` reports a fallback to memory as
+    `STATE_STORE_DEGRADED` (to the SDK sinks and a new `onDegraded` option) and
+    exposes `durable`.
+  - rn-payment: an iOS app validates its catalog against the iOS product ids; the
+    default platform used to be Android everywhere. A missing react-native-iap is
+    `PAYMENT_UNAVAILABLE`.
+  - rn-theme: `buildThemes` runs without React Native (new `hairlineWidth` option) and
+    importing the package no longer loads Unistyles; `applyThemeMode` loads it on
+    first use.
+  - rn-ads, rn-local-db: the same loading, with the same error codes as before.
+
+- Hooks read through `useSyncExternalStore` (rn-core's `useExternalStore`) and
+  re-render only when what they return changes. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-auth: `useProfile` and `useAccessTier` no longer re-render for a status change,
+    and the provider's context no longer changes on every transition. New
+    `useAuthSelector`. `auth.getState()` returns the same frozen object until the state
+    changes, instead of a copy per call.
+  - rn-payment: `useEntitlement` re-renders only when its own entitlement changes; the
+    engine keeps unchanged entitlement objects across syncs and does not notify for a
+    sync that changed nothing.
+  - rn-ads: `usePlacementState` and `useAdsStatus` read tear-free; `useAdsEvents` keeps
+    one subscription when given an inline listener.
+  - rn-i18n: `useTranslation` returns the same `t` until the locale changes, and
+    `useLocale`'s `setLocale` is stable.
+  - rn-ai: new `useAiBehaviorState`, with `client.subscribe` and a stable
+    `client.getBehaviorState()`.
+
+- Every package's own copy is an rn-core message catalog that an app can translate. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-i18n: new `runtimeEntriesFromCatalog(catalog)` registers any SDK catalog in one
+    line, converting `{name}` variables to `{{name}}`.
+  - rn-ai: new `messageKeyForError(error)` gives the copy for every error code, and
+    `aiMessageSet`. The input placeholder default is neutral ("Type a message…"), and
+    two keys were added for errors that had none (`ai.error.signIn`, `ai.error.generic`).
+  - rn-auth: new `authMessages`, the catalog split into user and developer copy.
+  - rn-payment: new `paymentMessages`.
+  - rn-chart: summaries, announcements, adjustable-action labels, built-in state text
+    and legend hints come from `chartStrings`; pass `strings` to translate them. The
+    `accessibility.summaryFormatter` prop, declared before, now replaces the summary.
+
+- Port conformance suites: one list of checks that a package's fake and its real adapter
+  both pass, so a test written against the fake proves something about the device. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-core: `@chipmobilesdk/rn-core/testing` adds `runChecks`, `expectConformance`,
+    `ensure` and `createFaultRegistry` (deterministic fault injection by named point).
+  - rn-camera: a `./testing` entrypoint with `runPermissionPortConformance`,
+    `runCameraEngineConformance` and the test adapter, which stays on the main
+    entrypoint too until the next major. `createTestCamera(...).prompts()` counts system
+    prompts.
+  - rn-payment: `runProviderPortConformance` in `./testing`, passed by the fake store and
+    the Play adapter.
+  - rn-ads: `runAdsEngineConformance` in `./testing`, passed by the fake engine and the
+    AdMob adapter.
+  - rn-auth: a `./testing` entrypoint with `createMemorySecureStore`,
+    `runSecureTokenStoreConformance` and `runOidcAuthClientConformance`, passed by the
+    in-memory doubles and the keychain and app-auth adapters.
+
+### Patch Changes
+
+- Optional properties in the public types (`AuthState`, `Profile`, `UseAccessTokenResult`
+  and others) now accept an explicit `undefined`, so apps compiling with
+  `exactOptionalPropertyTypes` type-check against the package. No runtime change. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+- Updated dependencies ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17), [#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17), [#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17)):
+  - @chipmobilesdk/rn-core@0.1.0
+
 ## 0.3.1
 
 ### Patch Changes

package/README.md

@@ -145,7 +145,9 @@ can sign users in:
   Keystore). Access tokens are kept in memory only.
 - Access-tier decisions prefer stable group **object ids**; display names never
   grant access; missing/overage claims fail closed.
-- Diagnostics (`AuthError`) never contain secrets or token values.
+- Diagnostics (`AuthError`) never contain secrets or token values. `AuthError` extends
+  `SdkError` from `@chipmobilesdk/rn-core`: `isSdkError(error)` recognises it, `error.pkg`
+  is `rn-auth`, and `error.retryable` is true only for `network-unavailable`.
 - Authentication and profile data are collected and transmitted to the
   identity providers and configured Azure resources — update Apple App Privacy
   and Google Play Data Safety before release.
@@ -163,11 +165,40 @@ are unsupported.
   `PremiumGateResult`, `evaluateAccessTier`, `failClosedTier`
 - Ports and default adapters: `SecureTokenStore`, `createKeychainSecureStore`,
   `AUTH_STORAGE_KEY`, `OidcAuthClient`, `createAppAuthClient` and the public OIDC
-  request/token types
+  request/token types. 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`
+  `useAccessToken`, `useSignInProvider`, `useSignInProviders`, `useAuthSelector`.
+  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()`
+  returns the same frozen object until the state changes.
 - Diagnostics and copy: `AuthError`, `AuthConfigError`, `isAuthError`, `redact`,
-  `DEFAULT_MESSAGES`, `resolveMessages` and their public code/message types
+  `DEFAULT_MESSAGES`, `resolveMessages` and their public code/message types, and
+  `authMessages`, the catalog split into `user` and `developer` copy. Register the user
+  copy with rn-i18n in one line: `runtimeEntriesFromCatalog(authMessages.user)`.
+
+## Testing
+
+```ts
+import { createAuth } from '@chipmobilesdk/rn-auth';
+import { createMemorySecureStore } from '@chipmobilesdk/rn-auth/testing';
+
+const auth = createAuth({ ...config, secureStore: createMemorySecureStore(), authClient });
+```
+
+`@chipmobilesdk/rn-auth/testing` is a separate entrypoint, so nothing in it reaches a
+production bundle. Besides `createMemorySecureStore(seed?)` it holds the checks every
+adapter must pass: `runSecureTokenStoreConformance` (null for an unknown key, last write
+wins, keys kept apart, safe removal, a long non-ASCII artifact intact) and
+`runOidcAuthClientConformance` (sign-in with claims and a future expiry, refresh, a
+closed sheet as `provider-cancelled`, a rejected refresh token as `session-expired`, and
+sign-out). The package runs them against its doubles and the keychain and app-auth
+adapters; run them against a store or client you inject.
 
 ## Compatibility and validation
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@chipmobilesdk/rn-auth",
-	"version": "0.3.1",
+	"version": "0.4.0",
 	"private": false,
 	"license": "UNLICENSED",
 	"main": "src/index.ts",
@@ -10,10 +10,27 @@
 			"types": "./src/index.ts",
 			"react-native": "./src/index.ts",
 			"default": "./src/index.ts"
+		},
+		"./app-auth": {
+			"types": "./src/app-auth.ts",
+			"react-native": "./src/app-auth.ts",
+			"default": "./src/app-auth.ts"
+		},
+		"./keychain": {
+			"types": "./src/keychain.ts",
+			"react-native": "./src/keychain.ts",
+			"default": "./src/keychain.ts"
+		},
+		"./testing": {
+			"types": "./src/testing/index.ts",
+			"react-native": "./src/testing/index.ts",
+			"default": "./src/testing/index.ts"
 		}
 	},
 	"files": [
 		"src/index.ts",
+		"src/app-auth.ts",
+		"src/keychain.ts",
 		"src/config",
 		"src/core",
 		"src/tokens",
@@ -21,15 +38,19 @@
 		"src/access",
 		"src/diagnostics",
 		"src/react",
+		"src/testing",
 		"skills",
 		"README.md",
 		"CHANGELOG.md"
 	],
 	"sideEffects": false,
 	"scripts": {
-		"typecheck": "tsc -p tsconfig.json --noEmit",
+		"typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.test.json",
 		"pack:check": "npm pack --dry-run"
 	},
+	"dependencies": {
+		"@chipmobilesdk/rn-core": "^0.1.0"
+	},
 	"peerDependencies": {
 		"react": ">=19",
 		"react-native": ">=0.85",

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

@@ -42,6 +42,9 @@ Runtime:
 - `evaluateAccessTier(...)`, `failClosedTier` — feature gating
 - `AuthProvider` — React context provider
 
+Testing (`@chipmobilesdk/rn-auth/testing`): `createMemorySecureStore`,
+`runSecureTokenStoreConformance`, `runOidcAuthClientConformance` — README `## Testing`.
+
 Types: `SecureTokenStore`, `AuthProviderProps`, `AuthErrorCode`, `AuthErrorAudience`,
 `AuthMessageMap`, `AuthMessageKey`
 

package/src/app-auth.ts

@@ -0,0 +1,6 @@
+/**
+ * `@chipmobilesdk/rn-auth/app-auth`: the default OIDC client over
+ * react-native-app-auth (AUTH-09). Its own entrypoint, so an app that injects its
+ * own client never reaches this module.
+ */
+export { createAppAuthClient, type AppAuthClientOptions } from './oidc/authClient';

package/src/config/types.ts

@@ -78,8 +78,8 @@ export type RestoreStatus = 'pending' | 'restored' | 'unavailable' | 'offline';
 /** Customer User / app-visible profile (FR-006). */
 export interface Profile {
 	tenantUserId: string;
-	displayName?: string;
-	email?: string;
+	displayName?: string | undefined;
+	email?: string | undefined;
 	provider: string;
 	claims: Record<string, unknown>;
 }
@@ -112,10 +112,10 @@ export interface AccessTokenResult {
 /** Single active app-visible authenticated state (FR-005/FR-022). */
 export interface AuthState {
 	status: AuthStatus;
-	profile?: Profile;
-	accessTier?: AccessTier;
+	profile?: Profile | undefined;
+	accessTier?: AccessTier | undefined;
 	restore: RestoreStatus;
-	error?: AuthError;
+	error?: AuthError | undefined;
 }
 
 /** Result of a premium-only gate check (US3). */

package/src/core/authMachine.ts

@@ -9,7 +9,13 @@
  * can never be undone by a request that was already in flight.
  */
 
-import { Platform } from 'react-native';
+import {
+	createDiagnosticChannel,
+	createListenerSet,
+	currentPlatform,
+	shallowEqual,
+} from '@chipmobilesdk/rn-core';
+
 import type {
 	Auth,
 	AuthConfig,
@@ -34,7 +40,7 @@ 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';
+import { AuthError, toAuthError, type AuthErrorCode } from '../diagnostics/errors';
 
 const SIGNED_OUT: Partial<AuthState> = {
 	status: 'signed-out',
@@ -48,17 +54,21 @@ export function createAuthMachine(config: AuthConfig, options: CreateAuthOptions
 	// Throws AuthConfigError before anything else (FR-005, US4 scenario 2).
 	validateConfig(config);
 
-	const platform: DevicePlatform = options.platform ?? (Platform?.OS as DevicePlatform) ?? 'ios';
+	// 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 = { status: 'loading', restore: 'pending' };
+	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 = new Set<(state: AuthState) => void>();
+	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
@@ -114,21 +124,30 @@ export function createAuthMachine(config: AuthConfig, options: CreateAuthOptions
 		},
 	});
 
+	/**
+	 * 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 };
+		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 */
-			}
+		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. */
@@ -143,12 +162,7 @@ export function createAuthMachine(config: AuthConfig, options: CreateAuthOptions
 	return {
 		getState,
 
-		subscribe(listener) {
-			listeners.add(listener);
-			return () => {
-				listeners.delete(listener);
-			};
-		},
+		subscribe: listener => listeners.add(listener),
 
 		async restore() {
 			sessionEpoch += 1;
@@ -362,3 +376,5 @@ export function createAuthMachine(config: AuthConfig, options: CreateAuthOptions
 }
 
 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');

package/src/core/session.ts

@@ -26,7 +26,7 @@ export interface PersistedSession {
 	refreshToken: string;
 	profile: Profile;
 	/** The id token hint for end-session (AUTH-04). Absent in artifacts written before 0.2.2. */
-	idToken?: string;
+	idToken?: string | undefined;
 }
 
 export interface RestoreDeps {
@@ -44,7 +44,7 @@ export interface RestoreResult {
 	profile?: Profile;
 	accessTier?: AccessTier;
 	refreshToken?: string;
-	idToken?: string;
+	idToken?: string | undefined;
 }
 
 export function parsePersistedSession(raw: string | null): PersistedSession | null {

package/src/diagnostics/errors.ts

@@ -5,6 +5,8 @@
  * in logs or error objects (FR-014).
  */
 
+import { COMMON_PATTERNS, SdkError, redactPatterns } from '@chipmobilesdk/rn-core';
+
 export type AuthErrorCode =
 	| 'configuration-error'
 	| 'provider-cancelled'
@@ -21,39 +23,49 @@ export interface AuthErrorArgs {
 	code: AuthErrorCode;
 	messageKey: string;
 	audience?: AuthErrorAudience;
-	detail?: string;
+	detail?: string | undefined;
 }
 
+/** JWT-shaped values: three base64url segments separated by dots. */
+const JWT_PATTERN = /[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/g;
+/** Any other long opaque token-like run; shorter than rn-core's payload run on purpose. */
+const TOKEN_PATTERN = /[A-Za-z0-9_-]{24,}/g;
+
 /**
- * Replace token-like substrings (long URL-safe base64 / JWT segments) with a
- * placeholder so diagnostics never leak secrets or token values (FR-014).
+ * Replace token-like substrings with a placeholder so diagnostics never leak
+ * secrets or token values (FR-014): JWTs become `[redacted-token]`; URLs, e-mail
+ * addresses, UUIDs and other opaque runs become `[redacted]` (rn-core's patterns).
  */
 export function redact(value: string | undefined): string | undefined {
 	if (!value) {
 		return value;
 	}
-	return (
-		value
-			// JWT-shaped values: three base64url segments separated by dots.
-			.replace(/[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/g, '[redacted-token]')
-			// Any other long opaque token-like run.
-			.replace(/[A-Za-z0-9_-]{24,}/g, '[redacted]')
-	);
+	return redactPatterns(value.replace(JWT_PATTERN, '[redacted-token]'), [
+		...COMMON_PATTERNS,
+		TOKEN_PATTERN,
+	]);
 }
 
-export class AuthError extends Error {
-	readonly code: AuthErrorCode;
+/** Retrying can only help when the network was the problem. */
+const RETRYABLE: ReadonlySet<AuthErrorCode> = new Set<AuthErrorCode>(['network-unavailable']);
+
+/** 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 detail?: string;
+	readonly detail?: string | undefined;
 
 	constructor(args: AuthErrorArgs) {
-		super(args.messageKey);
+		const detail = redact(args.detail);
+		super('rn-auth', args.code, {
+			message: args.messageKey,
+			retryable: RETRYABLE.has(args.code),
+			redactedCause: detail,
+		});
 		this.name = 'AuthError';
-		this.code = args.code;
 		this.audience = args.audience ?? 'developer';
 		this.messageKey = args.messageKey;
-		this.detail = redact(args.detail);
+		this.detail = detail;
 	}
 }
 

package/src/diagnostics/messageKeys.ts

@@ -5,6 +5,8 @@
  * developer/tenant-configuration copy are kept separate (UX-005).
  */
 
+import { defineMessages } from '@chipmobilesdk/rn-core';
+
 export interface AuthMessageMap {
 	// User-facing actions and states
 	'auth.action.continueGoogle': string;
@@ -32,28 +34,39 @@ export interface AuthMessageMap {
 
 export type AuthMessageKey = keyof AuthMessageMap;
 
-export const DEFAULT_MESSAGES: AuthMessageMap = {
-	'auth.action.continueGoogle': 'Continue with Google',
-	'auth.action.continueApple': 'Continue with Apple',
-	'auth.action.continueFacebook': 'Continue with Facebook',
-	'auth.state.signedOut': 'Sign in to continue',
-	'auth.state.authenticating': 'Signing you in…',
-	'auth.state.signedIn': 'You are signed in',
-	'auth.state.signingOut': 'Signing out…',
-	'auth.tier.free': 'Free',
-	'auth.tier.premium': 'Premium',
-	'auth.tier.unverified': 'Membership could not be verified',
-	'auth.error.cancelled': 'Sign-in was cancelled. You can try again.',
-	'auth.error.sessionExpired': 'Your session expired. Please sign in again.',
-	'auth.error.entitlement': 'This feature requires a verified premium membership.',
-	'auth.error.network': 'No connection. Some features are limited until you reconnect.',
-	'auth.error.configuration': 'Authentication is not configured correctly.',
-	'auth.error.redirectMismatch': 'The sign-in redirect does not match the app configuration.',
-	'auth.error.token': 'We could not complete the request. Please try again.',
-	'auth.error.consentDenied': 'Access to this resource was denied.',
-};
+/**
+ * The catalog, as an rn-core message set: `user` copy may reach an end user,
+ * `developer` copy describes a tenant or configuration fault (UX-005). Register
+ * `authMessages.user` with rn-i18n to translate it like app copy.
+ */
+export const authMessages = defineMessages({
+	user: {
+		'auth.action.continueGoogle': 'Continue with Google',
+		'auth.action.continueApple': 'Continue with Apple',
+		'auth.action.continueFacebook': 'Continue with Facebook',
+		'auth.state.signedOut': 'Sign in to continue',
+		'auth.state.authenticating': 'Signing you in…',
+		'auth.state.signedIn': 'You are signed in',
+		'auth.state.signingOut': 'Signing out…',
+		'auth.tier.free': 'Free',
+		'auth.tier.premium': 'Premium',
+		'auth.tier.unverified': 'Membership could not be verified',
+		'auth.error.cancelled': 'Sign-in was cancelled. You can try again.',
+		'auth.error.sessionExpired': 'Your session expired. Please sign in again.',
+		'auth.error.entitlement': 'This feature requires a verified premium membership.',
+		'auth.error.network': 'No connection. Some features are limited until you reconnect.',
+	},
+	developer: {
+		'auth.error.configuration': 'Authentication is not configured correctly.',
+		'auth.error.redirectMismatch': 'The sign-in redirect does not match the app configuration.',
+		'auth.error.token': 'We could not complete the request. Please try again.',
+		'auth.error.consentDenied': 'Access to this resource was denied.',
+	},
+});
+
+export const DEFAULT_MESSAGES: AuthMessageMap = authMessages.defaults;
 
 /** Resolve a message, preferring app overrides over the English defaults. */
 export function resolveMessages(overrides?: Partial<AuthMessageMap>): AuthMessageMap {
-	return { ...DEFAULT_MESSAGES, ...(overrides ?? {}) };
+	return authMessages.resolve(overrides);
 }

package/src/index.ts

@@ -54,11 +54,12 @@ export { evaluateAccessTier, failClosedTier } from './access/accessTier';
 // Diagnostics
 export { AuthError, AuthConfigError, isAuthError, redact } from './diagnostics/errors';
 export type { AuthErrorCode, AuthErrorAudience } from './diagnostics/errors';
-export { DEFAULT_MESSAGES, resolveMessages } from './diagnostics/messageKeys';
+export { DEFAULT_MESSAGES, authMessages, resolveMessages } from './diagnostics/messageKeys';
 export type { AuthMessageMap, AuthMessageKey } from './diagnostics/messageKeys';
 
 // React bindings
 export { AuthProvider } from './react/AuthProvider';
+export { useAuthSelector } from './react/hooks';
 export type { AuthProviderProps } from './react/AuthProvider';
 export {
 	useAuth,

package/src/keychain.ts

@@ -0,0 +1,6 @@
+/**
+ * `@chipmobilesdk/rn-auth/keychain`: the default secure token store over
+ * react-native-keychain (AUTH-09). Its own entrypoint, so an app with its own
+ * secure storage never reaches this module.
+ */
+export { createKeychainSecureStore, type KeychainSecureStoreOptions } from './tokens/secureStore';

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 {};
@@ -117,13 +121,50 @@ export interface AppAuthClientOptions {
 	useDiscovery?: boolean;
 }
 
+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 baseConfig = (

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 { useExternalStore } from '@chipmobilesdk/rn-core/react';
 import { useCallback, useState } from 'react';
-import { useAuthContext } from './AuthProvider';
+import { useAuthInstance } from './AuthProvider';
 import type {
 	AccessTier,
 	AccessTokenResult,
@@ -26,8 +28,25 @@ export interface UseAuthResult {
 	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]),
@@ -39,24 +58,22 @@ export function useAuth(): UseAuthResult {
 }
 
 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,12 +82,12 @@ export type UseAccessTokenStatus =
 
 export interface UseAccessTokenResult {
 	status: UseAccessTokenStatus;
-	token?: string;
+	token?: string | undefined;
 	request(): Promise<AccessTokenResult>;
 }
 
 export function useAccessToken(resourceKey: string): UseAccessTokenResult {
-	const { auth } = useAuthContext();
+	const auth = useAuthInstance();
 	const [status, setStatus] = useState<UseAccessTokenStatus>('idle');
 	const [token, setToken] = useState<string | undefined>(undefined);
 

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/secureStore.ts

@@ -4,10 +4,14 @@
  * Refresh tokens and the session-restore artifact persist ONLY through this
  * port, backed by platform secure storage (iOS Keychain / Android Keystore).
  * Access tokens are never written here — they stay in memory (see accessToken).
- * The default adapter lazily requires the native module so unit tests that
- * inject a fake never load native code.
+ * The default adapter loads the native module on its first read or write, so
+ * creating it, and unit tests that inject a fake, load no native code.
  */
 
+import { lazyPeer } from '@chipmobilesdk/rn-core';
+
+import { AuthConfigError } from '../diagnostics/errors';
+
 /** Single key under which the persisted session artifact is stored. */
 export const AUTH_STORAGE_KEY = '@chipmobilesdk/rn-auth/session';
 
@@ -29,23 +33,53 @@ export interface KeychainSecureStoreOptions {
 export function createKeychainSecureStore(
 	options: KeychainSecureStoreOptions = {},
 ): SecureTokenStore {
-	// Lazy require: only loaded when the default adapter is actually used.
-	const Keychain = require('react-native-keychain');
-	const accessible = options.accessible ?? Keychain.ACCESSIBLE?.WHEN_UNLOCKED_THIS_DEVICE_ONLY;
+	// The native module loads on the first read or write, never at startup (PERF-05).
+	const accessible = () =>
+		options.accessible ?? keychain().ACCESSIBLE?.WHEN_UNLOCKED_THIS_DEVICE_ONLY;
 
 	return {
 		async getItem(key) {
-			const result = await Keychain.getGenericPassword({ service: key });
+			const result = await keychain().getGenericPassword({ service: key });
 			return result ? result.password : null;
 		},
 		async setItem(key, value) {
-			await Keychain.setGenericPassword('token', value, {
+			await keychain().setGenericPassword('token', value, {
 				service: key,
-				accessible,
+				accessible: accessible(),
 			});
 		},
 		async removeItem(key) {
-			await Keychain.resetGenericPassword({ service: key });
+			await keychain().resetGenericPassword({ service: key });
 		},
 	};
 }
+
+interface KeychainModule {
+	ACCESSIBLE?: { WHEN_UNLOCKED_THIS_DEVICE_ONLY?: string };
+	getGenericPassword(options: { service: string }): Promise<false | { password: string }>;
+	setGenericPassword(
+		username: string,
+		password: string,
+		options: { service: string; accessible: string | undefined },
+	): Promise<unknown>;
+	resetGenericPassword(options: { service: string }): Promise<unknown>;
+}
+
+const keychainPeer = lazyPeer('react-native-keychain', () => {
+	// Inside `try`, so Metro bundles an app that leaves this optional peer out.
+	try {
+		return require('react-native-keychain') as KeychainModule;
+	} catch (cause) {
+		throw cause;
+	}
+});
+
+function keychain(): KeychainModule {
+	return keychainPeer.require(
+		peer =>
+			new AuthConfigError(
+				'auth.error.configuration',
+				`${peer} is not installed or its native module is not linked`,
+			),
+	);
+}