@chipmobilesdk/rn-auth 0.3.1 → 0.5.0

package/src/core/authMachine.ts

@@ -9,7 +9,15 @@
  * 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 { AuthMessageMap } from '../diagnostics/messageKeys';
+import { resolveMessages } from '../diagnostics/messageKeys';
 import type {
 	Auth,
 	AuthConfig,
@@ -31,10 +39,10 @@ import {
 } from '../oidc/socialRouting';
 import { mapClaimsToProfile } from './profile';
 import { evaluateAccessTier, failClosedTier } from '../access/accessTier';
-import { restoreSession, type PersistedSession } from './session';
+import { restoreSession, sameSession, storedProfileFrom, type PersistedSession } from './session';
 import { AUTH_STORAGE_KEY } from '../tokens/secureStore';
 import { createAccessTokenManager } from '../tokens/accessToken';
-import { AuthError, toAuthError } from '../diagnostics/errors';
+import { AuthError, toAuthError, type AuthErrorCode } from '../diagnostics/errors';
 
 const SIGNED_OUT: Partial<AuthState> = {
 	status: 'signed-out',
@@ -48,17 +56,23 @@ 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 ?? [];
+	// Declared since 0.1.0 and read by nothing until now (AUTH-15).
+	const messages = resolveMessages(config.messages);
 
-	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
@@ -74,12 +88,29 @@ export function createAuthMachine(config: AuthConfig, options: CreateAuthOptions
 		return next;
 	};
 
-	const writeSession = (session: PersistedSession, epoch: number): Promise<void> =>
+	/** The artifact as last written or read, so an identical write is skipped. */
+	let storedSession: PersistedSession | null = null;
+
+	const writeSession = (
+		session: { refreshToken: string; profile: Profile; idToken?: string | undefined },
+		epoch: number,
+	): Promise<void> =>
 		enqueueStoreOp(async () => {
 			if (epoch !== sessionEpoch) {
 				return; // The session this belonged to has already ended.
 			}
-			await secureStore.setItem(AUTH_STORAGE_KEY, JSON.stringify(session));
+			const artifact: PersistedSession = {
+				refreshToken: session.refreshToken,
+				profile: storedProfileFrom(session.profile),
+				idToken: session.idToken,
+			};
+			// A restore that rotated nothing used to write the Keychain again on
+			// every launch, on the startup path (AUTH-23).
+			if (storedSession && sameSession(storedSession, artifact)) {
+				return;
+			}
+			await secureStore.setItem(AUTH_STORAGE_KEY, JSON.stringify(artifact));
+			storedSession = artifact;
 		});
 
 	const tokenManager = createAccessTokenManager({
@@ -114,21 +145,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. */
@@ -136,6 +176,7 @@ export function createAuthMachine(config: AuthConfig, options: CreateAuthOptions
 		sessionEpoch += 1;
 		refreshToken = null;
 		idToken = null;
+		storedSession = null;
 		tokenManager.clear();
 		await enqueueStoreOp(() => secureStore.removeItem(AUTH_STORAGE_KEY));
 	}
@@ -143,12 +184,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;
@@ -179,6 +215,8 @@ export function createAuthMachine(config: AuthConfig, options: CreateAuthOptions
 				return getState();
 			}
 
+			storedSession = result.persisted ?? null;
+
 			if (result.outcome === 'restored' && result.profile && result.refreshToken) {
 				refreshToken = result.refreshToken;
 				idToken = result.idToken ?? null;
@@ -320,16 +358,17 @@ export function createAuthMachine(config: AuthConfig, options: CreateAuthOptions
 			return result;
 		},
 
-		async requestAccessToken(resourceKey) {
+		async requestAccessToken(resourceKey, tokenOptions) {
 			const epoch = sessionEpoch;
 			// Only a real network refresh is a `token-refreshing` phase; a cache hit
 			// would otherwise flash every subscriber twice for nothing.
 			const refreshing =
-				state.status === 'authenticated' && !tokenManager.hasFreshToken(resourceKey);
+				state.status === 'authenticated' &&
+				(tokenOptions?.forceRefresh === true || !tokenManager.hasFreshToken(resourceKey));
 			if (refreshing) {
 				setState({ status: 'token-refreshing' });
 			}
-			const result = await tokenManager.request(resourceKey);
+			const result = await tokenManager.request(resourceKey, tokenOptions);
 			// Restored only if nothing else moved the session meanwhile: a sign-out
 			// during the refresh used to be overwritten back to `authenticated`.
 			if (refreshing && epoch === sessionEpoch && state.status === 'token-refreshing') {
@@ -342,6 +381,11 @@ export function createAuthMachine(config: AuthConfig, options: CreateAuthOptions
 			return state.accessTier ?? failClosedTier();
 		},
 
+		canAccessPremium(): PremiumGateResult {
+			const tier = state.accessTier ?? failClosedTier();
+			return { allowed: tier.tier === 'premium' && tier.verification === 'verified', tier };
+		},
+
 		requirePremium(): PremiumGateResult {
 			const tier = state.accessTier ?? failClosedTier();
 			const allowed = tier.tier === 'premium' && tier.verification === 'verified';
@@ -351,6 +395,10 @@ export function createAuthMachine(config: AuthConfig, options: CreateAuthOptions
 			return { allowed, tier };
 		},
 
+		getMessages(): AuthMessageMap {
+			return messages;
+		},
+
 		getPlatformProvider() {
 			return defaultProviderForPlatform(config, platform);
 		},
@@ -362,3 +410,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/profile.ts

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

package/src/core/session.ts

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

package/src/diagnostics/errors.ts

@@ -5,6 +5,10 @@
  * in logs or error objects (FR-014).
  */
 
+import { COMMON_PATTERNS, SdkError, redactPatterns } from '@chipmobilesdk/rn-core';
+
+import type { AuthMessageKey } from './messageKeys';
+
 export type AuthErrorCode =
 	| 'configuration-error'
 	| 'provider-cancelled'
@@ -12,53 +16,63 @@ export type AuthErrorCode =
 	| 'token-acquisition-failed'
 	| 'session-expired'
 	| 'consent-denied'
-	| 'entitlement-unverified'
 	| 'network-unavailable';
 
 export type AuthErrorAudience = 'user' | 'developer';
 
 export interface AuthErrorArgs {
 	code: AuthErrorCode;
-	messageKey: string;
+	/** A key of this package's catalogue: the copy an app shows for this error. */
+	messageKey: AuthMessageKey;
 	audience?: AuthErrorAudience;
-	detail?: string;
+	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 messageKey: AuthMessageKey;
+	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;
 	}
 }
 
 export class AuthConfigError extends AuthError {
-	constructor(messageKey: string, detail?: string) {
+	constructor(messageKey: AuthMessageKey, detail?: string) {
 		super({ code: 'configuration-error', messageKey, audience: 'developer', detail });
 		this.name = 'AuthConfigError';
 	}
@@ -72,7 +86,7 @@ export function isAuthError(value: unknown): value is AuthError {
 export function toAuthError(
 	value: unknown,
 	fallbackCode: AuthErrorCode = 'token-acquisition-failed',
-	fallbackMessageKey = 'auth.error.token',
+	fallbackMessageKey: AuthMessageKey = 'auth.error.token',
 ): AuthError {
 	if (isAuthError(value)) {
 		return value;

package/src/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

@@ -25,6 +25,7 @@ export type {
 	ProviderIdentity,
 	ProviderConfig,
 	ProviderId,
+	KnownProviderId,
 	DevicePlatform,
 	ResourceConfig,
 	ClaimMatcher,
@@ -37,11 +38,16 @@ export type {
 } from './config/types';
 
 // Ports + default adapters
+export { describeProviderIdentity, mapClaimsToProfile } from './core/profile';
+
+export type { AccessTokenRequestOptions } from './tokens/accessToken';
 export type { SecureTokenStore } from './tokens/secureStore';
 export { createKeychainSecureStore, AUTH_STORAGE_KEY } from './tokens/secureStore';
 export type {
 	OidcAuthClient,
 	OidcTokens,
+	OidcServiceConfiguration,
+	AppAuthClientOptions,
 	AuthorizeParams,
 	RefreshParams,
 	EndSessionParams,
@@ -54,14 +60,16 @@ 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,
+	useAuthMessages,
 	useProfile,
 	useAccessTier,
 	useAccessToken,

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';