@chipmobilesdk/rn-auth 0.2.0

package/src/oidc/authClient.ts

@@ -0,0 +1,224 @@
+/**
+ * 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);
+			}
+		},
+	};
+}

package/src/oidc/socialRouting.ts

@@ -0,0 +1,73 @@
+/**
+ * Social provider routing (FR-002/FR-003, R3). Google and Apple are federated
+ * inside the External ID tenant; the app presents the platform-correct action
+ * and starts the user flow with a per-provider `domain_hint`.
+ */
+
+import type {
+	AuthConfig,
+	DevicePlatform,
+	ProviderConfig,
+	ProviderId,
+} from '../config/types';
+import { AuthConfigError } from '../diagnostics/errors';
+
+/** Find the configured provider, ensuring it is enabled for the platform. */
+export function resolveProvider(
+	config: AuthConfig,
+	providerId: ProviderId,
+	platform: DevicePlatform,
+): ProviderConfig {
+	const provider = config.providers.find(candidate => candidate.id === providerId);
+	if (!provider) {
+		throw new AuthConfigError(
+			'auth.error.configuration',
+			`Provider "${providerId}" is not configured`,
+		);
+	}
+	if (!provider.platforms.includes(platform)) {
+		throw new AuthConfigError(
+			'auth.error.configuration',
+			`Provider "${providerId}" is not enabled for platform "${platform}"`,
+		);
+	}
+	if (provider.available === false) {
+		throw new AuthConfigError(
+			'auth.error.configuration',
+			`Provider "${providerId}" is marked unavailable`,
+		);
+	}
+	return provider;
+}
+
+/** Build the OIDC additional parameters that route to the chosen IdP. */
+export function buildAdditionalParameters(
+	provider: ProviderConfig,
+): Record<string, string> {
+	return { domain_hint: provider.domainHint };
+}
+
+/**
+ * All providers to present on a given platform, in configuration array order
+ * (FR-003/FR-004). Filtered to providers enabled for the platform and not marked
+ * unavailable.
+ */
+export function availableProvidersForPlatform(
+	config: AuthConfig,
+	platform: DevicePlatform,
+): ProviderConfig[] {
+	return config.providers.filter(
+		provider => provider.platforms.includes(platform) && provider.available !== false,
+	);
+}
+
+/**
+ * The first available provider for a platform (UX-004, back-compat). Equals
+ * `availableProvidersForPlatform(config, platform)[0]`.
+ */
+export function defaultProviderForPlatform(
+	config: AuthConfig,
+	platform: DevicePlatform,
+): ProviderConfig | undefined {
+	return availableProvidersForPlatform(config, platform)[0];
+}

package/src/react/AuthProvider.tsx

@@ -0,0 +1,47 @@
+/**
+ * React context boundary for the auth controller (LIB-002). Subscribes to the
+ * controller and re-renders consumers on every state change.
+ */
+
+import React, {
+	createContext,
+	useContext,
+	useEffect,
+	useMemo,
+	useState,
+} from 'react';
+import type { Auth, AuthState } from '../config/types';
+
+interface AuthContextValue {
+	auth: Auth;
+	state: AuthState;
+}
+
+const AuthContext = createContext<AuthContextValue | null>(null);
+
+export interface AuthProviderProps {
+	auth: Auth;
+	children: React.ReactNode;
+}
+
+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>;
+}
+
+export function useAuthContext(): AuthContextValue {
+	const value = useContext(AuthContext);
+	if (!value) {
+		throw new Error('useAuth must be used within an <AuthProvider>.');
+	}
+	return value;
+}

package/src/react/hooks.ts

@@ -0,0 +1,90 @@
+/**
+ * Public hooks (LIB-002). All read from the AuthProvider context so consumers
+ * re-render on state changes.
+ */
+
+import { useCallback, useState } from 'react';
+import { useAuthContext } from './AuthProvider';
+import type {
+	AccessTier,
+	AccessTokenResult,
+	AuthState,
+	PremiumGateResult,
+	Profile,
+	ProviderConfig,
+	ProviderId,
+} from '../config/types';
+import { failClosedTier } from '../access/accessTier';
+
+export interface UseAuthResult {
+	state: AuthState;
+	signIn(providerId: ProviderId): Promise<AuthState>;
+	signOut(): Promise<void>;
+	signOutGlobal(): Promise<void>;
+	restore(): Promise<AuthState>;
+	requirePremium(): PremiumGateResult;
+}
+
+export function useAuth(): UseAuthResult {
+	const { auth, state } = useAuthContext();
+	return {
+		state,
+		signIn: useCallback((providerId: ProviderId) => auth.signIn(providerId), [auth]),
+		signOut: useCallback(() => auth.signOut(), [auth]),
+		signOutGlobal: useCallback(() => auth.signOutGlobal(), [auth]),
+		restore: useCallback(() => auth.restore(), [auth]),
+		requirePremium: useCallback(() => auth.requirePremium(), [auth]),
+	};
+}
+
+export function useProfile(): Profile | undefined {
+	const { state } = useAuthContext();
+	return state.profile;
+}
+
+export function useAccessTier(): AccessTier {
+	const { state } = useAuthContext();
+	return state.accessTier ?? failClosedTier();
+}
+
+/** The first provider to present on the current platform (UX-004), or undefined. */
+export function useSignInProvider(): ProviderConfig | undefined {
+	const { auth } = useAuthContext();
+	return auth.getPlatformProvider();
+}
+
+/** All available providers for the current platform, in configuration order (FR-003/FR-004). */
+export function useSignInProviders(): ProviderConfig[] {
+	const { auth } = useAuthContext();
+	return auth.getPlatformProviders();
+}
+
+export type UseAccessTokenStatus =
+	| 'idle'
+	| 'loading'
+	| 'success'
+	| 'denied'
+	| 'unavailable'
+	| 'error';
+
+export interface UseAccessTokenResult {
+	status: UseAccessTokenStatus;
+	token?: string;
+	request(): Promise<AccessTokenResult>;
+}
+
+export function useAccessToken(resourceKey: string): UseAccessTokenResult {
+	const { auth } = useAuthContext();
+	const [status, setStatus] = useState<UseAccessTokenStatus>('idle');
+	const [token, setToken] = useState<string | undefined>(undefined);
+
+	const request = useCallback(async () => {
+		setStatus('loading');
+		const result = await auth.requestAccessToken(resourceKey);
+		setStatus(result.status);
+		setToken(result.token);
+		return result;
+	}, [auth, resourceKey]);
+
+	return { status, token, request };
+}

package/src/tokens/accessToken.ts

@@ -0,0 +1,105 @@
+/**
+ * Per-resource delegated access-token acquisition with an in-memory cache and
+ * silent refresh (FR-007, PERF-003, R4). Access tokens are never persisted to
+ * disk (FR-021) — only kept in memory keyed by resource until expiry.
+ */
+
+import type {
+	AccessTokenResult,
+	ResourceConfig,
+} from '../config/types';
+import type { OidcAuthClient } from '../oidc/authClient';
+import { isAuthError } from '../diagnostics/errors';
+
+const EXPIRY_SKEW_MS = 60_000;
+
+interface CachedToken {
+	token: string;
+	expiresAt: number;
+	scopes: string[];
+}
+
+export interface AccessTokenManagerDeps {
+	authority: string;
+	clientId: string;
+	redirectUrl: string;
+	resources: ResourceConfig[];
+	authClient: OidcAuthClient;
+	getRefreshToken: () => string | null;
+	setRefreshToken: (token: string) => void;
+}
+
+export interface AccessTokenManager {
+	request(resourceKey: string): Promise<AccessTokenResult>;
+	clear(): void;
+}
+
+export function createAccessTokenManager(
+	deps: AccessTokenManagerDeps,
+): AccessTokenManager {
+	const cache = new Map<string, CachedToken>();
+
+	return {
+		clear() {
+			cache.clear();
+		},
+		async request(resourceKey): Promise<AccessTokenResult> {
+			const resource = deps.resources.find(entry => entry.key === resourceKey);
+			if (!resource) {
+				return { resourceKey, status: 'error', errorCode: 'configuration-error' };
+			}
+
+			const cached = cache.get(resourceKey);
+			if (cached && cached.expiresAt - EXPIRY_SKEW_MS > Date.now()) {
+				return {
+					resourceKey,
+					status: 'success',
+					token: cached.token,
+					expiresAt: cached.expiresAt,
+				};
+			}
+
+			const refreshToken = deps.getRefreshToken();
+			if (!refreshToken) {
+				return { resourceKey, status: 'unavailable', errorCode: 'session-expired' };
+			}
+
+			try {
+				const tokens = await deps.authClient.refresh({
+					authority: deps.authority,
+					clientId: deps.clientId,
+					redirectUrl: deps.redirectUrl,
+					refreshToken,
+					scopes: resource.scopes,
+				});
+				if (tokens.refreshToken) {
+					deps.setRefreshToken(tokens.refreshToken);
+				}
+				if (!tokens.accessToken) {
+					return { resourceKey, status: 'error', errorCode: 'token-acquisition-failed' };
+				}
+				const expiresAt = tokens.accessTokenExpiresAt ?? Date.now() + 3_600_000;
+				cache.set(resourceKey, {
+					token: tokens.accessToken,
+					expiresAt,
+					scopes: resource.scopes,
+				});
+				return { resourceKey, status: 'success', token: tokens.accessToken, expiresAt };
+			} catch (error) {
+				if (isAuthError(error)) {
+					if (error.code === 'consent-denied') {
+						return { resourceKey, status: 'denied', errorCode: error.code };
+					}
+					if (error.code === 'network-unavailable') {
+						return { resourceKey, status: 'unavailable', errorCode: error.code };
+					}
+					if (error.code === 'session-expired') {
+						return { resourceKey, status: 'unavailable', errorCode: error.code };
+					}
+					return { resourceKey, status: 'error', errorCode: error.code };
+				}
+				return { resourceKey, status: 'error', errorCode: 'token-acquisition-failed' };
+			}
+		},
+	};
+}

package/src/tokens/secureStore.ts

@@ -0,0 +1,52 @@
+/**
+ * SecureTokenStore port + default react-native-keychain adapter (FR-021, R2).
+ *
+ * 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.
+ */
+
+/** Single key under which the persisted session artifact is stored. */
+export const AUTH_STORAGE_KEY = '@chipmobilesdk/rn-auth/session';
+
+export interface SecureTokenStore {
+	getItem(key: string): Promise<string | null>;
+	setItem(key: string, value: string): Promise<void>;
+	removeItem(key: string): Promise<void>;
+}
+
+export interface KeychainSecureStoreOptions {
+	/** Optional Keychain access-control accessibility constant. */
+	accessible?: string;
+}
+
+/**
+ * Default secure store backed by react-native-keychain. Each logical key maps to
+ * a Keychain "service" so multiple keys can coexist. Validated on device.
+ */
+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;
+
+	return {
+		async getItem(key) {
+			const result = await Keychain.getGenericPassword({ service: key });
+			return result ? result.password : null;
+		},
+		async setItem(key, value) {
+			await Keychain.setGenericPassword('token', value, {
+				service: key,
+				accessible,
+			});
+		},
+		async removeItem(key) {
+			await Keychain.resetGenericPassword({ service: key });
+		},
+	};
+}