@chipmobilesdk/rn-auth 0.2.1 → 0.3.1

package/src/index.ts

@@ -1,82 +1,71 @@
-/**
- * @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';
+/**
+ * @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,
+	GlobalSignOutResult,
+} 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';

package/src/oidc/authClient.ts

@@ -1,224 +1,195 @@
-/**
- * OidcAuthClient port + default react-native-app-auth adapter (R1).
- *
- * The port abstracts the Authorization Code + PKCE public-client flow so the
- * auth engine is testable without native code. The default adapter lazily
- * requires react-native-app-auth and is validated on device.
- */
-
-import { AuthError, type AuthErrorCode } from '../diagnostics/errors';
-
-export interface OidcTokens {
-	/** Resource/audience access token (present for authorize and resource refresh). */
-	accessToken?: string;
-	/** Refresh token used for silent acquisition and restore. */
-	refreshToken: string;
-	/** Raw id token (JWT). */
-	idToken: string;
-	/** 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;
-}
-
-export interface AuthorizeParams {
-	authority: string;
-	clientId: string;
-	redirectUrl: string;
-	scopes: string[];
-	/** Additional OIDC parameters, e.g. `domain_hint` for social routing. */
-	additionalParameters?: Record<string, string>;
-}
-
-export interface RefreshParams {
-	authority: string;
-	clientId: string;
-	redirectUrl: string;
-	refreshToken: string;
-	scopes: string[];
-}
-
-export interface EndSessionParams {
-	authority: string;
-	clientId: string;
-	redirectUrl: string;
-	idToken?: string;
-}
-
-export interface OidcAuthClient {
-	authorize(params: AuthorizeParams): Promise<OidcTokens>;
-	refresh(params: RefreshParams): Promise<OidcTokens>;
-	endSession(params: EndSessionParams): Promise<void>;
-}
-
-/** Decode the payload segment of a JWT without any dependency (device-safe). */
-export function decodeJwtClaims(jwt: string): Record<string, unknown> {
-	const parts = jwt.split('.');
-	if (parts.length < 2) {
-		return {};
-	}
-	try {
-		const json = base64UrlDecode(parts[1]);
-		return JSON.parse(json) as Record<string, unknown>;
-	} catch {
-		return {};
-	}
-}
-
-const BASE64_CHARS =
-	'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
-
-function base64UrlDecode(input: string): string {
-	let base64 = input.replace(/-/g, '+').replace(/_/g, '/');
-	while (base64.length % 4 !== 0) {
-		base64 += '=';
-	}
-	let bytes = '';
-	let buffer = 0;
-	let bits = 0;
-	for (const char of base64) {
-		if (char === '=') {
-			break;
-		}
-		const index = BASE64_CHARS.indexOf(char);
-		if (index === -1) {
-			continue;
-		}
-		// Standard base64 bit assembly; bitwise ops are intentional here.
-		// eslint-disable-next-line no-bitwise
-		buffer = (buffer << 6) | index;
-		bits += 6;
-		if (bits >= 8) {
-			bits -= 8;
-			// eslint-disable-next-line no-bitwise
-			bytes += String.fromCharCode((buffer >> bits) & 0xff);
-		}
-	}
-	// Interpret the byte string (each char is a 0–255 byte) as UTF-8 without
-	// relying on the deprecated global `escape`.
-	try {
-		const percentEncoded = Array.from(bytes)
-			.map(char => '%' + char.charCodeAt(0).toString(16).padStart(2, '0'))
-			.join('');
-		return decodeURIComponent(percentEncoded);
-	} catch {
-		return bytes;
-	}
-}
-
-/** Map a native app-auth error to a classified AuthError without leaking tokens. */
-function classifyAppAuthError(error: unknown): AuthError {
-	const message = error instanceof Error ? error.message : String(error);
-	// DEV-only: surface the RAW native error so the actual failure (AADSTS code,
-	// issuer/redirect mismatch, token-endpoint error) is visible while debugging.
-	// Remove before shipping — this intentionally bypasses redaction.
-	if (typeof __DEV__ !== 'undefined' && __DEV__) {
-		console.warn('[rn-auth] raw app-auth error:', {
-			message,
-			code: (error as { code?: unknown })?.code,
-			error,
-		});
-	}
-	const lower = message.toLowerCase();
-	let code: AuthErrorCode = 'token-acquisition-failed';
-	let messageKey = 'auth.error.token';
-	if (lower.includes('cancel')) {
-		code = 'provider-cancelled';
-		messageKey = 'auth.error.cancelled';
-	} else if (lower.includes('network') || lower.includes('connection') || lower.includes('offline')) {
-		code = 'network-unavailable';
-		messageKey = 'auth.error.network';
-	} else if (lower.includes('redirect')) {
-		code = 'redirect-mismatch';
-		messageKey = 'auth.error.redirectMismatch';
-	} else if (lower.includes('consent') || lower.includes('denied') || lower.includes('access_denied')) {
-		code = 'consent-denied';
-		messageKey = 'auth.error.consentDenied';
-	} else if (lower.includes('invalid_grant') || lower.includes('expired')) {
-		code = 'session-expired';
-		messageKey = 'auth.error.sessionExpired';
-	}
-	return new AuthError({ code, messageKey, audience: code === 'redirect-mismatch' ? 'developer' : 'user', detail: message });
-}
-
-export interface AppAuthClientOptions {
-	/** When true, the OIDC discovery document is fetched from `${authority}`. */
-	useDiscovery?: boolean;
-}
-
-/**
- * Default OidcAuthClient adapter wrapping react-native-app-auth (PKCE public
- * client). Lazily requires the native module. 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 = (
-		authority: string,
-		clientId: string,
-		redirectUrl: string,
-		scopes: string[],
-	) => ({
-		issuer: useDiscovery ? authority : undefined,
-		clientId,
-		redirectUrl,
-		scopes,
-	});
-
-	const toTokens = (result: {
-		accessToken?: string;
-		refreshToken?: string;
-		idToken: string;
-		accessTokenExpirationDate?: string;
-	}): OidcTokens => ({
-		accessToken: result.accessToken,
-		refreshToken: result.refreshToken ?? '',
-		idToken: result.idToken,
-		claims: decodeJwtClaims(result.idToken),
-		accessTokenExpiresAt: result.accessTokenExpirationDate
-			? new Date(result.accessTokenExpirationDate).getTime()
-			: undefined,
-	});
-
-	return {
-		async authorize(params) {
-			try {
-				const result = await AppAuth.authorize({
-					...baseConfig(params.authority, params.clientId, params.redirectUrl, params.scopes),
-					additionalParameters: params.additionalParameters,
-				});
-				return toTokens(result);
-			} catch (error) {
-				throw classifyAppAuthError(error);
-			}
-		},
-		async refresh(params) {
-			try {
-				const result = await AppAuth.refresh(
-					baseConfig(params.authority, params.clientId, params.redirectUrl, params.scopes),
-					{ refreshToken: params.refreshToken },
-				);
-				return toTokens(result);
-			} catch (error) {
-				throw classifyAppAuthError(error);
-			}
-		},
-		async endSession(params) {
-			try {
-				await AppAuth.logout(
-					baseConfig(params.authority, params.clientId, params.redirectUrl, []),
-					{
-						idToken: params.idToken ?? '',
-						postLogoutRedirectUrl: params.redirectUrl,
-					},
-				);
-			} catch (error) {
-				throw classifyAppAuthError(error);
-			}
-		},
-	};
-}
+/**
+ * OidcAuthClient port + default react-native-app-auth adapter (R1).
+ *
+ * The port abstracts the Authorization Code + PKCE public-client flow so the
+ * auth engine is testable without native code. The default adapter lazily
+ * requires react-native-app-auth and is validated on device.
+ */
+
+import { classifyAppAuthError } from './classifyError';
+
+export interface OidcTokens {
+	/** Resource/audience access token (present for authorize and resource refresh). */
+	accessToken?: string;
+	/**
+	 * 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;
+	/** Raw id token (JWT). Absent from a refresh requested without `openid`. */
+	idToken?: string;
+	/** 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;
+}
+
+export interface AuthorizeParams {
+	authority: string;
+	clientId: string;
+	redirectUrl: string;
+	scopes: string[];
+	/** Additional OIDC parameters, e.g. `domain_hint` for social routing. */
+	additionalParameters?: Record<string, string>;
+}
+
+export interface RefreshParams {
+	authority: string;
+	clientId: string;
+	redirectUrl: string;
+	refreshToken: string;
+	scopes: string[];
+}
+
+export interface EndSessionParams {
+	authority: string;
+	clientId: string;
+	redirectUrl: string;
+	idToken?: string;
+}
+
+export interface OidcAuthClient {
+	authorize(params: AuthorizeParams): Promise<OidcTokens>;
+	refresh(params: RefreshParams): Promise<OidcTokens>;
+	endSession(params: EndSessionParams): Promise<void>;
+}
+
+/** Decode the payload segment of a JWT without any dependency (device-safe). */
+export function decodeJwtClaims(jwt: string | null | undefined): Record<string, unknown> {
+	if (typeof jwt !== 'string') {
+		return {};
+	}
+	const parts = jwt.split('.');
+	if (parts.length < 2) {
+		return {};
+	}
+	try {
+		const json = base64UrlDecode(parts[1]);
+		return JSON.parse(json) as Record<string, unknown>;
+	} catch {
+		return {};
+	}
+}
+
+const BASE64_CHARS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+
+function base64UrlDecode(input: string): string {
+	let base64 = input.replace(/-/g, '+').replace(/_/g, '/');
+	while (base64.length % 4 !== 0) {
+		base64 += '=';
+	}
+	let bytes = '';
+	let buffer = 0;
+	let bits = 0;
+	for (const char of base64) {
+		if (char === '=') {
+			break;
+		}
+		const index = BASE64_CHARS.indexOf(char);
+		if (index === -1) {
+			continue;
+		}
+		// Standard base64 bit assembly; bitwise ops are intentional here.
+		// eslint-disable-next-line no-bitwise
+		buffer = (buffer << 6) | index;
+		bits += 6;
+		if (bits >= 8) {
+			bits -= 8;
+			// eslint-disable-next-line no-bitwise
+			bytes += String.fromCharCode((buffer >> bits) & 0xff);
+		}
+	}
+	// Interpret the byte string (each char is a 0–255 byte) as UTF-8 without
+	// relying on the deprecated global `escape`.
+	try {
+		const percentEncoded = Array.from(bytes)
+			.map(char => '%' + char.charCodeAt(0).toString(16).padStart(2, '0'))
+			.join('');
+		return decodeURIComponent(percentEncoded);
+	} catch {
+		return bytes;
+	}
+}
+
+export interface AppAuthClientOptions {
+	/** When true, the OIDC discovery document is fetched from `${authority}`. */
+	useDiscovery?: boolean;
+}
+
+/**
+ * Default OidcAuthClient adapter wrapping react-native-app-auth (PKCE public
+ * client). Lazily requires the native module. 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 = (
+		authority: string,
+		clientId: string,
+		redirectUrl: string,
+		scopes: string[],
+	) => ({
+		issuer: useDiscovery ? authority : undefined,
+		clientId,
+		redirectUrl,
+		scopes,
+	});
+
+	const toTokens = (result: {
+		accessToken?: string;
+		refreshToken?: string | null;
+		idToken?: string | null;
+		accessTokenExpirationDate?: string;
+	}): OidcTokens => ({
+		accessToken: result.accessToken,
+		// Absent stays absent: an empty string was indistinguishable from a real
+		// token by type, and silently disabled session persistence.
+		refreshToken: result.refreshToken || undefined,
+		idToken: result.idToken || undefined,
+		claims: decodeJwtClaims(result.idToken),
+		accessTokenExpiresAt: result.accessTokenExpirationDate
+			? new Date(result.accessTokenExpirationDate).getTime()
+			: undefined,
+	});
+
+	return {
+		async authorize(params) {
+			try {
+				const result = await AppAuth.authorize({
+					...baseConfig(params.authority, params.clientId, params.redirectUrl, params.scopes),
+					additionalParameters: params.additionalParameters,
+				});
+				return toTokens(result);
+			} catch (error) {
+				throw classifyAppAuthError(error);
+			}
+		},
+		async refresh(params) {
+			try {
+				const result = await AppAuth.refresh(
+					baseConfig(params.authority, params.clientId, params.redirectUrl, params.scopes),
+					{ refreshToken: params.refreshToken },
+				);
+				return toTokens(result);
+			} catch (error) {
+				throw classifyAppAuthError(error);
+			}
+		},
+		async endSession(params) {
+			try {
+				await AppAuth.logout(
+					baseConfig(params.authority, params.clientId, params.redirectUrl, []),
+					{
+						idToken: params.idToken ?? '',
+						postLogoutRedirectUrl: params.redirectUrl,
+					},
+				);
+			} catch (error) {
+				throw classifyAppAuthError(error);
+			}
+		},
+	};
+}

package/src/oidc/classifyError.ts

@@ -0,0 +1,76 @@
+/**
+ * Classifies a native OIDC error into an `AuthErrorCode`.
+ *
+ * The rules are an ordered table rather than a chain of substring checks, so a
+ * platform adapter (the iOS one, later) adds its own rows without touching the
+ * engine. Order matters: the first matching rule wins.
+ *
+ * The default is deliberately not "session expired". Restore clears the stored
+ * session only on `session-expired`, so anything this table cannot name — a
+ * timeout, a 5xx, a discovery failure, a localized message — must keep the
+ * session rather than sign the user out.
+ */
+
+import { AuthError, type AuthErrorCode } from '../diagnostics/errors';
+
+export interface ClassificationRule {
+	readonly code: AuthErrorCode;
+	readonly messageKey: string;
+	/** Matched against the native error's `code` and `message`, case-insensitively. */
+	readonly pattern: RegExp;
+}
+
+/**
+ * OAuth error codes (RFC 6749 §5.2, OIDC Core §3.1.2.6) and the Entra ID AADSTS
+ * codes that mean the same thing, plus the transport failures app-auth reports.
+ */
+export const DEFAULT_CLASSIFICATION_RULES: readonly ClassificationRule[] = [
+	{
+		code: 'provider-cancelled',
+		messageKey: 'auth.error.cancelled',
+		pattern: /cancel|user_cancel|authorization flow (was )?dismissed/i,
+	},
+	{
+		code: 'session-expired',
+		messageKey: 'auth.error.sessionExpired',
+		// invalid_grant is the refresh-token verdict; the AADSTS codes are Entra's
+		// expired, revoked, or inactive refresh token and password-changed cases.
+		pattern:
+			/\binvalid_grant\b|\binteraction_required\b|\blogin_required\b|AADSTS(700082|700084|50173|70043)\b/i,
+	},
+	{
+		code: 'redirect-mismatch',
+		messageKey: 'auth.error.redirectMismatch',
+		pattern: /redirect_uri|redirect uri|redirect_mismatch|AADSTS50011\b/i,
+	},
+	{
+		code: 'consent-denied',
+		messageKey: 'auth.error.consentDenied',
+		pattern: /\baccess_denied\b|\bconsent_required\b|AADSTS65001\b/i,
+	},
+	{
+		code: 'network-unavailable',
+		messageKey: 'auth.error.network',
+		pattern:
+			/network|connection|offline|timed? ?out|unable to resolve host|unreachable|\bserver_error\b|\btemporarily_unavailable\b|\b5\d\d\b/i,
+	},
+];
+
+/** Maps a native app-auth error to a classified AuthError without leaking tokens. */
+export function classifyAppAuthError(
+	error: unknown,
+	rules: readonly ClassificationRule[] = DEFAULT_CLASSIFICATION_RULES,
+): AuthError {
+	const message = error instanceof Error ? error.message : String(error);
+	const nativeCode = (error as { code?: unknown } | undefined)?.code;
+	const haystack = `${typeof nativeCode === 'string' ? nativeCode : ''} ${message}`;
+	const rule = rules.find(candidate => candidate.pattern.test(haystack));
+	const code = rule?.code ?? 'token-acquisition-failed';
+	return new AuthError({
+		code,
+		messageKey: rule?.messageKey ?? 'auth.error.token',
+		audience: code === 'redirect-mismatch' ? 'developer' : 'user',
+		// AuthError redacts `detail`, so token-shaped values never survive.
+		detail: message,
+	});
+}