@chipmobilesdk/rn-auth 0.3.0 → 0.3.1

package/src/index.ts

@@ -1,83 +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,
-	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';
+/**
+ * @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,199 +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 { 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);
-			}
-		},
-	};
-}
+/**
+ * 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);
+			}
+		},
+	};
+}