@chipmobilesdk/rn-auth 0.2.0

package/src/core/authMachine.ts

@@ -0,0 +1,249 @@
+/**
+ * Auth state machine / orchestrator (FR-005, FR-022, R5, R7). Holds the single
+ * active session, wires the OidcAuthClient + SecureTokenStore ports, profile
+ * mapping, access-tier evaluation, per-resource tokens, restore, and sign-out.
+ */
+
+import { Platform } from 'react-native';
+import type {
+	Auth,
+	AuthConfig,
+	AuthState,
+	CreateAuthOptions,
+	DevicePlatform,
+	PremiumGateResult,
+	Profile,
+	ProviderId,
+} from '../config/types';
+import { validateConfig } from '../config/validateConfig';
+import { createAppAuthClient } from '../oidc/authClient';
+import {
+	availableProvidersForPlatform,
+	buildAdditionalParameters,
+	defaultProviderForPlatform,
+	resolveProvider,
+} from '../oidc/socialRouting';
+import { mapClaimsToProfile } from './profile';
+import { evaluateAccessTier, failClosedTier } from '../access/accessTier';
+import { restoreSession } from './session';
+import { AUTH_STORAGE_KEY } from '../tokens/secureStore';
+import { createAccessTokenManager } from '../tokens/accessToken';
+import { toAuthError } from '../diagnostics/errors';
+
+export function createAuthMachine(
+	config: AuthConfig,
+	options: CreateAuthOptions = {},
+): Auth {
+	// Throws AuthConfigError before anything else (FR-005, US4 scenario 2).
+	validateConfig(config);
+
+	const platform: DevicePlatform =
+		options.platform ?? ((Platform?.OS as DevicePlatform) ?? 'ios');
+	const secureStore = config.secureStore;
+	const authClient = config.authClient ?? createAppAuthClient();
+	const resources = config.resources ?? [];
+
+	let state: AuthState = { status: 'loading', restore: 'pending' };
+	let refreshToken: string | null = null;
+	const listeners = new Set<(state: AuthState) => void>();
+
+	const tokenManager = createAccessTokenManager({
+		authority: config.authority,
+		clientId: config.clientId,
+		redirectUrl: config.redirectUrl,
+		resources,
+		authClient,
+		getRefreshToken: () => refreshToken,
+		setRefreshToken: token => {
+			refreshToken = token;
+		},
+	});
+
+	function getState(): AuthState {
+		return { ...state };
+	}
+
+	function setState(patch: Partial<AuthState>): void {
+		state = { ...state, ...patch };
+		for (const listener of listeners) {
+			listener(getState());
+		}
+	}
+
+	async function persist(profile: Profile): Promise<void> {
+		if (!refreshToken) {
+			return;
+		}
+		await secureStore.setItem(
+			AUTH_STORAGE_KEY,
+			JSON.stringify({ refreshToken, profile }),
+		);
+	}
+
+	async function clearPersisted(): Promise<void> {
+		refreshToken = null;
+		tokenManager.clear();
+		await secureStore.removeItem(AUTH_STORAGE_KEY);
+	}
+
+	return {
+		getState,
+
+		subscribe(listener) {
+			listeners.add(listener);
+			return () => {
+				listeners.delete(listener);
+			};
+		},
+
+		async restore() {
+			setState({ status: 'loading', restore: 'pending', error: undefined });
+			const result = await restoreSession({
+				secureStore,
+				authority: config.authority,
+				clientId: config.clientId,
+				redirectUrl: config.redirectUrl,
+				scopes: config.scopes,
+				authClient,
+				mapping: config.accessTierMapping,
+			});
+
+			if (result.outcome === 'restored' && result.profile) {
+				refreshToken = result.refreshToken ?? null;
+				await persist(result.profile);
+				setState({
+					status: 'authenticated',
+					profile: result.profile,
+					accessTier: result.accessTier,
+					restore: 'restored',
+					error: undefined,
+				});
+			} else if (result.outcome === 'offline' && result.profile) {
+				refreshToken = result.refreshToken ?? null;
+				setState({
+					status: 'authenticated',
+					profile: result.profile,
+					accessTier: result.accessTier ?? failClosedTier(),
+					restore: 'offline',
+					error: undefined,
+				});
+			} else {
+				await clearPersisted();
+				setState({
+					status: 'signed-out',
+					profile: undefined,
+					accessTier: undefined,
+					restore: 'unavailable',
+					error: undefined,
+				});
+			}
+			return getState();
+		},
+
+		async signIn(providerId: ProviderId) {
+			setState({ status: 'authenticating', error: undefined });
+			let provider;
+			try {
+				provider = resolveProvider(config, providerId, platform);
+			} catch (error) {
+				setState({ status: 'error', error: toAuthError(error, 'configuration-error', 'auth.error.configuration') });
+				return getState();
+			}
+
+			try {
+				const tokens = await authClient.authorize({
+					authority: config.authority,
+					clientId: config.clientId,
+					redirectUrl: config.redirectUrl,
+					scopes: config.scopes,
+					additionalParameters: buildAdditionalParameters(provider),
+				});
+				// Single active account: a new sign-in replaces any prior session.
+				refreshToken = tokens.refreshToken;
+				tokenManager.clear();
+				const profile = mapClaimsToProfile(tokens.claims, providerId);
+				const accessTier = evaluateAccessTier(tokens.claims, config.accessTierMapping);
+				await persist(profile);
+				setState({
+					status: 'authenticated',
+					profile,
+					accessTier,
+					restore: 'restored',
+					error: undefined,
+				});
+			} catch (error) {
+				const authError = toAuthError(error);
+				if (authError.code === 'provider-cancelled') {
+					setState({ status: 'cancelled', error: authError });
+				} else {
+					setState({ status: 'error', error: authError });
+				}
+			}
+			return getState();
+		},
+
+		async signOut() {
+			await clearPersisted();
+			setState({
+				status: 'signed-out',
+				profile: undefined,
+				accessTier: undefined,
+				restore: 'unavailable',
+				error: undefined,
+			});
+		},
+
+		async signOutGlobal() {
+			try {
+				await authClient.endSession({
+					authority: config.authority,
+					clientId: config.clientId,
+					redirectUrl: config.redirectUrl,
+				});
+			} catch {
+				// End-session failure must not block clearing local state.
+			}
+			await clearPersisted();
+			setState({
+				status: 'signed-out',
+				profile: undefined,
+				accessTier: undefined,
+				restore: 'unavailable',
+				error: undefined,
+			});
+		},
+
+		async requestAccessToken(resourceKey) {
+			const wasAuthenticated = state.status === 'authenticated';
+			if (wasAuthenticated) {
+				setState({ status: 'token-refreshing' });
+			}
+			const result = await tokenManager.request(resourceKey);
+			if (wasAuthenticated) {
+				setState({ status: 'authenticated' });
+			}
+			return result;
+		},
+
+		getAccessTier() {
+			return state.accessTier ?? failClosedTier();
+		},
+
+		requirePremium(): PremiumGateResult {
+			const tier = state.accessTier ?? failClosedTier();
+			const allowed = tier.tier === 'premium' && tier.verification === 'verified';
+			if (!allowed) {
+				setState({ status: 'access-denied' });
+			}
+			return { allowed, tier };
+		},
+
+		getPlatformProvider() {
+			return defaultProviderForPlatform(config, platform);
+		},
+
+		getPlatformProviders() {
+			return availableProvidersForPlatform(config, platform);
+		},
+	};
+}

package/src/core/profile.ts

@@ -0,0 +1,60 @@
+/**
+ * Claims → Profile mapping (FR-006). Tolerant of Apple private-relay emails and
+ * missing display name / given name (edge cases).
+ */
+
+import type { Profile, ProviderId, ProviderIdentity } from '../config/types';
+
+function asString(value: unknown): string | undefined {
+	return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+
+function looksLikeEmail(value: string | undefined): boolean {
+	return !!value && /.+@.+\..+/.test(value);
+}
+
+/** Map id-token claims to the app-visible Profile. */
+export function mapClaimsToProfile(
+	claims: Record<string, unknown>,
+	providerId?: ProviderId,
+): Profile {
+	const tenantUserId =
+		asString(claims.oid) ?? asString(claims.sub) ?? asString(claims.unique_name) ?? 'unknown';
+
+	const givenName = asString(claims.given_name);
+	const familyName = asString(claims.family_name);
+	const composedName = [givenName, familyName].filter(Boolean).join(' ') || undefined;
+	const displayName = asString(claims.name) ?? composedName;
+
+	const preferred = asString(claims.preferred_username);
+	const email =
+		asString(claims.email) ?? (looksLikeEmail(preferred) ? preferred : undefined);
+
+	const provider =
+		providerId ?? asString(claims.idp) ?? asString(claims.identityProvider) ?? 'unknown';
+
+	return {
+		tenantUserId,
+		displayName,
+		email,
+		provider,
+		claims,
+	};
+}
+
+/** Describe the external provider identity behind the profile (FR-004 edge cases). */
+export function describeProviderIdentity(
+	claims: Record<string, unknown>,
+	providerId?: ProviderId,
+): ProviderIdentity {
+	const provider = providerId ?? asString(claims.idp) ?? 'unknown';
+	const subject = asString(claims.sub) ?? asString(claims.oid) ?? 'unknown';
+	const email = asString(claims.email);
+	let emailBehavior: ProviderIdentity['emailBehavior'] = 'none';
+	if (email) {
+		emailBehavior = email.endsWith('@privaterelay.appleid.com')
+			? 'private-relay'
+			: 'direct';
+	}
+	return { provider, subject, emailBehavior };
+}

package/src/core/session.ts

@@ -0,0 +1,96 @@
+/**
+ * Session restoration (FR-008, R5). Reads the persisted artifact, attempts a
+ * silent refresh, and classifies the outcome:
+ *  - restored: fresh tokens + claims → authenticated
+ *  - offline:  network unavailable → cached profile read-only, tier unverified
+ *              (fail closed) — clarify Q3
+ *  - unavailable: no artifact or invalid/expired refresh → signed-out reauth
+ */
+
+import type {
+	AccessTier,
+	AccessTierMapping,
+	Profile,
+	RestoreStatus,
+} from '../config/types';
+import type { OidcAuthClient } from '../oidc/authClient';
+import type { SecureTokenStore } from '../tokens/secureStore';
+import { AUTH_STORAGE_KEY } from '../tokens/secureStore';
+import { mapClaimsToProfile } from './profile';
+import { evaluateAccessTier, failClosedTier } from '../access/accessTier';
+import { isAuthError } from '../diagnostics/errors';
+
+export interface PersistedSession {
+	refreshToken: string;
+	profile: Profile;
+}
+
+export interface RestoreDeps {
+	secureStore: SecureTokenStore;
+	authority: string;
+	clientId: string;
+	redirectUrl: string;
+	scopes: string[];
+	authClient: OidcAuthClient;
+	mapping: AccessTierMapping;
+}
+
+export interface RestoreResult {
+	outcome: RestoreStatus;
+	profile?: Profile;
+	accessTier?: AccessTier;
+	refreshToken?: string;
+}
+
+export function parsePersistedSession(raw: string | null): PersistedSession | null {
+	if (!raw) {
+		return null;
+	}
+	try {
+		const parsed = JSON.parse(raw) as PersistedSession;
+		if (parsed && typeof parsed.refreshToken === 'string' && parsed.profile) {
+			return parsed;
+		}
+		return null;
+	} catch {
+		return null;
+	}
+}
+
+export async function restoreSession(deps: RestoreDeps): Promise<RestoreResult> {
+	const raw = await deps.secureStore.getItem(AUTH_STORAGE_KEY);
+	const persisted = parsePersistedSession(raw);
+	if (!persisted) {
+		return { outcome: 'unavailable' };
+	}
+
+	try {
+		const tokens = await deps.authClient.refresh({
+			authority: deps.authority,
+			clientId: deps.clientId,
+			redirectUrl: deps.redirectUrl,
+			refreshToken: persisted.refreshToken,
+			scopes: deps.scopes,
+		});
+		const profile = mapClaimsToProfile(tokens.claims);
+		const accessTier = evaluateAccessTier(tokens.claims, deps.mapping);
+		return {
+			outcome: 'restored',
+			profile,
+			accessTier,
+			refreshToken: tokens.refreshToken || persisted.refreshToken,
+		};
+	} catch (error) {
+		// Offline: keep the cached identity read-only, fail closed on entitlement.
+		if (isAuthError(error) && error.code === 'network-unavailable') {
+			return {
+				outcome: 'offline',
+				profile: persisted.profile,
+				accessTier: failClosedTier(),
+				refreshToken: persisted.refreshToken,
+			};
+		}
+		// Invalid/expired refresh → require reauthentication.
+		return { outcome: 'unavailable' };
+	}
+}

package/src/diagnostics/errors.ts

@@ -0,0 +1,85 @@
+/**
+ * Developer-facing diagnostics. AuthError carries a stable machine-readable
+ * code, an audience (user vs developer/tenant), and a localizable message key.
+ * `detail` is always passed through `redact` so tokens and secrets never appear
+ * in logs or error objects (FR-014).
+ */
+
+export type AuthErrorCode =
+	| 'configuration-error'
+	| 'provider-cancelled'
+	| 'redirect-mismatch'
+	| 'token-acquisition-failed'
+	| 'session-expired'
+	| 'consent-denied'
+	| 'entitlement-unverified'
+	| 'network-unavailable';
+
+export type AuthErrorAudience = 'user' | 'developer';
+
+export interface AuthErrorArgs {
+	code: AuthErrorCode;
+	messageKey: string;
+	audience?: AuthErrorAudience;
+	detail?: string;
+}
+
+/**
+ * Replace token-like substrings (long URL-safe base64 / JWT segments) with a
+ * placeholder so diagnostics never leak secrets or token values (FR-014).
+ */
+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]');
+}
+
+export class AuthError extends Error {
+	readonly code: AuthErrorCode;
+	readonly audience: AuthErrorAudience;
+	readonly messageKey: string;
+	readonly detail?: string;
+
+	constructor(args: AuthErrorArgs) {
+		super(args.messageKey);
+		this.name = 'AuthError';
+		this.code = args.code;
+		this.audience = args.audience ?? 'developer';
+		this.messageKey = args.messageKey;
+		this.detail = redact(args.detail);
+	}
+}
+
+export class AuthConfigError extends AuthError {
+	constructor(messageKey: string, detail?: string) {
+		super({ code: 'configuration-error', messageKey, audience: 'developer', detail });
+		this.name = 'AuthConfigError';
+	}
+}
+
+export function isAuthError(value: unknown): value is AuthError {
+	return value instanceof AuthError;
+}
+
+/** Normalize any thrown value into an AuthError without leaking secrets. */
+export function toAuthError(
+	value: unknown,
+	fallbackCode: AuthErrorCode = 'token-acquisition-failed',
+	fallbackMessageKey = 'auth.error.token',
+): AuthError {
+	if (isAuthError(value)) {
+		return value;
+	}
+	const message = value instanceof Error ? value.message : String(value);
+	return new AuthError({
+		code: fallbackCode,
+		messageKey: fallbackMessageKey,
+		audience: 'developer',
+		detail: message,
+	});
+}

package/src/diagnostics/messageKeys.ts

@@ -0,0 +1,61 @@
+/**
+ * Stable, localizable message keys with English default copy (UX-006 / LIB-011).
+ * The library takes no i18n runtime dependency: consuming apps map these keys to
+ * localized strings via their own i18n system. User-actionable copy and
+ * developer/tenant-configuration copy are kept separate (UX-005).
+ */
+
+export interface AuthMessageMap {
+	// User-facing actions and states
+	'auth.action.continueGoogle': string;
+	'auth.action.continueApple': string;
+	'auth.action.continueFacebook': string;
+	'auth.state.signedOut': string;
+	'auth.state.authenticating': string;
+	'auth.state.signedIn': string;
+	'auth.state.signingOut': string;
+	// Access tier (user-facing)
+	'auth.tier.free': string;
+	'auth.tier.premium': string;
+	'auth.tier.unverified': string;
+	// User-actionable errors
+	'auth.error.cancelled': string;
+	'auth.error.sessionExpired': string;
+	'auth.error.entitlement': string;
+	'auth.error.network': string;
+	// Developer / tenant-configuration errors
+	'auth.error.configuration': string;
+	'auth.error.redirectMismatch': string;
+	'auth.error.token': string;
+	'auth.error.consentDenied': string;
+}
+
+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.',
+};
+
+/** Resolve a message, preferring app overrides over the English defaults. */
+export function resolveMessages(
+	overrides?: Partial<AuthMessageMap>,
+): AuthMessageMap {
+	return { ...DEFAULT_MESSAGES, ...(overrides ?? {}) };
+}

package/src/index.ts

@@ -0,0 +1,82 @@
+/**
+ * @chipmobilesdk/rn-auth — reusable Microsoft Entra External ID authentication
+ * for ChipMobileSdk-family React Native apps (public OIDC/PKCE client, no
+ * backend). This is the single public entrypoint (LIB-003); modules under
+ * `core/`, `tokens/`, `oidc/`, `access/`, and `diagnostics/` are private.
+ */
+
+import { createAuthMachine } from './core/authMachine';
+import type { Auth, AuthConfig, CreateAuthOptions } from './config/types';
+
+/** Create the auth controller. Throws AuthConfigError on invalid config (FR-005). */
+export function createAuth(config: AuthConfig, options?: CreateAuthOptions): Auth {
+	return createAuthMachine(config, options);
+}
+
+// Public types
+export type {
+	Auth,
+	AuthConfig,
+	CreateAuthOptions,
+	AuthState,
+	AuthStatus,
+	RestoreStatus,
+	Profile,
+	ProviderIdentity,
+	ProviderConfig,
+	ProviderId,
+	DevicePlatform,
+	ResourceConfig,
+	ClaimMatcher,
+	AccessTierMapping,
+	AccessTier,
+	AccessTokenResult,
+	AccessTokenStatus,
+	PremiumGateResult,
+} from './config/types';
+
+// Ports + default adapters
+export type { SecureTokenStore } from './tokens/secureStore';
+export { createKeychainSecureStore, AUTH_STORAGE_KEY } from './tokens/secureStore';
+export type {
+	OidcAuthClient,
+	OidcTokens,
+	AuthorizeParams,
+	RefreshParams,
+	EndSessionParams,
+} from './oidc/authClient';
+export { createAppAuthClient } from './oidc/authClient';
+
+// Access-tier evaluation (also exported for app-side reuse/testing)
+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 type { AuthMessageMap, AuthMessageKey } from './diagnostics/messageKeys';
+
+// React bindings
+export { AuthProvider } from './react/AuthProvider';
+export type { AuthProviderProps } from './react/AuthProvider';
+export {
+	useAuth,
+	useProfile,
+	useAccessTier,
+	useAccessToken,
+	useSignInProvider,
+	useSignInProviders,
+} from './react/hooks';
+export type {
+	UseAuthResult,
+	UseAccessTokenResult,
+	UseAccessTokenStatus,
+} from './react/hooks';