@chipmobilesdk/rn-auth 0.3.0 → 0.3.1

package/src/config/types.ts

@@ -1,154 +1,154 @@
-/**
- * Public type contracts for @chipmobilesdk/rn-auth. Shapes follow
- * specs/003-mobile-entra-auth/data-model.md.
- */
-
-import type { SecureTokenStore } from '../tokens/secureStore';
-import type { OidcAuthClient } from '../oidc/authClient';
-import type { AuthError, AuthErrorCode } from '../diagnostics/errors';
-import type { AuthMessageKey, AuthMessageMap } from '../diagnostics/messageKeys';
-
-export type ProviderId = 'google' | 'apple' | 'facebook';
-export type DevicePlatform = 'ios' | 'android';
-
-/** Provider Setup Configuration — non-secret public values only (FR-016/FR-017). */
-export interface ProviderConfig {
-	id: ProviderId;
-	platforms: DevicePlatform[];
-	/** External ID `domain_hint` routing the user flow to this IdP (R3). */
-	domainHint: string;
-	/** Message key for the button label (Continue with Google / Apple). */
-	labelKey: AuthMessageKey;
-	available?: boolean;
-}
-
-/** One configured protected resource for delegated token requests (FR-007). */
-export interface ResourceConfig {
-	key: string;
-	scopes: string[];
-	displayName?: string;
-}
-
-export interface ClaimMatcher {
-	claim: string;
-	equals: string | number | boolean;
-}
-
-/** App-specific mapping from tenant indicators to access tiers (FR-019/FR-020). */
-export interface AccessTierMapping {
-	/** Stable group object ids granting premium — authoritative (FR-020). */
-	premiumGroupObjectIds: string[];
-	premiumRoleNames?: string[];
-	premiumClaimMatchers?: ClaimMatcher[];
-	/** Diagnostics-only object-id → name map; never used for decisions (FR-020). */
-	groupDisplayNames?: Record<string, string>;
-}
-
-/** App-supplied, public-only setup input (FR-015/FR-016/FR-017). */
-export interface AuthConfig {
-	authority: string;
-	clientId: string;
-	redirectUrl: string;
-	scopes: string[];
-	providers: ProviderConfig[];
-	resources?: ResourceConfig[];
-	accessTierMapping: AccessTierMapping;
-	secureStore: SecureTokenStore;
-	authClient?: OidcAuthClient;
-	messages?: Partial<AuthMessageMap>;
-}
-
-/** Advanced/testing options. `platform` overrides the detected device platform. */
-export interface CreateAuthOptions {
-	platform?: DevicePlatform;
-}
-
-export type AuthStatus =
-	| 'loading'
-	| 'signed-out'
-	| 'authenticating'
-	| 'authenticated'
-	| 'token-refreshing'
-	| 'access-denied'
-	| 'cancelled'
-	| 'error';
-
-export type RestoreStatus = 'pending' | 'restored' | 'unavailable' | 'offline';
-
-/** Customer User / app-visible profile (FR-006). */
-export interface Profile {
-	tenantUserId: string;
-	displayName?: string;
-	email?: string;
-	provider: string;
-	claims: Record<string, unknown>;
-}
-
-export interface ProviderIdentity {
-	provider: string;
-	subject: string;
-	emailBehavior: 'direct' | 'private-relay' | 'none';
-}
-
-/** Access Tier — local interpretation of tenant indicators (FR-010). */
-export interface AccessTier {
-	tier: 'free' | 'premium';
-	source: 'group' | 'role' | 'claim' | 'default';
-	verification: 'verified' | 'unverified';
-	lastRefreshAt?: number;
-}
-
-export type AccessTokenStatus = 'success' | 'denied' | 'unavailable' | 'error';
-
-/** Access Token Request result (FR-007). */
-export interface AccessTokenResult {
-	resourceKey: string;
-	status: AccessTokenStatus;
-	token?: string;
-	expiresAt?: number;
-	errorCode?: AuthErrorCode;
-}
-
-/** Single active app-visible authenticated state (FR-005/FR-022). */
-export interface AuthState {
-	status: AuthStatus;
-	profile?: Profile;
-	accessTier?: AccessTier;
-	restore: RestoreStatus;
-	error?: AuthError;
-}
-
-/** Result of a premium-only gate check (US3). */
-export interface PremiumGateResult {
-	allowed: boolean;
-	tier: AccessTier;
-}
-
-/**
- * What `signOutGlobal` did beyond the device (added in 0.2.2). Local state is
- * cleared either way; `failed` means the tenant session may still be alive, so
- * the next interactive sign-in can complete without a password prompt.
- */
-export interface GlobalSignOutResult {
-	global: 'ended' | 'failed';
-	/** Present when `global` is `failed`. Redacted like every AuthError. */
-	error?: AuthError;
-}
-
-/** The auth controller returned by `createAuth` (single active account). */
-export interface Auth {
-	getState(): AuthState;
-	subscribe(listener: (state: AuthState) => void): () => void;
-	restore(): Promise<AuthState>;
-	signIn(providerId: ProviderId): Promise<AuthState>;
-	signOut(): Promise<void>;
-	signOutGlobal(): Promise<GlobalSignOutResult>;
-	requestAccessToken(resourceKey: string): Promise<AccessTokenResult>;
-	getAccessTier(): AccessTier;
-	/** Gate a premium-only path; enters `access-denied` when unverified (FR-011). */
-	requirePremium(): PremiumGateResult;
-	/** The first available provider to present on the current platform (UX-004), or undefined. */
-	getPlatformProvider(): ProviderConfig | undefined;
-	/** All available providers for the current platform, in configuration order (FR-003/FR-004). */
-	getPlatformProviders(): ProviderConfig[];
-}
+/**
+ * Public type contracts for @chipmobilesdk/rn-auth. Shapes follow
+ * specs/003-mobile-entra-auth/data-model.md.
+ */
+
+import type { SecureTokenStore } from '../tokens/secureStore';
+import type { OidcAuthClient } from '../oidc/authClient';
+import type { AuthError, AuthErrorCode } from '../diagnostics/errors';
+import type { AuthMessageKey, AuthMessageMap } from '../diagnostics/messageKeys';
+
+export type ProviderId = 'google' | 'apple' | 'facebook';
+export type DevicePlatform = 'ios' | 'android';
+
+/** Provider Setup Configuration — non-secret public values only (FR-016/FR-017). */
+export interface ProviderConfig {
+	id: ProviderId;
+	platforms: DevicePlatform[];
+	/** External ID `domain_hint` routing the user flow to this IdP (R3). */
+	domainHint: string;
+	/** Message key for the button label (Continue with Google / Apple). */
+	labelKey: AuthMessageKey;
+	available?: boolean;
+}
+
+/** One configured protected resource for delegated token requests (FR-007). */
+export interface ResourceConfig {
+	key: string;
+	scopes: string[];
+	displayName?: string;
+}
+
+export interface ClaimMatcher {
+	claim: string;
+	equals: string | number | boolean;
+}
+
+/** App-specific mapping from tenant indicators to access tiers (FR-019/FR-020). */
+export interface AccessTierMapping {
+	/** Stable group object ids granting premium — authoritative (FR-020). */
+	premiumGroupObjectIds: string[];
+	premiumRoleNames?: string[];
+	premiumClaimMatchers?: ClaimMatcher[];
+	/** Diagnostics-only object-id → name map; never used for decisions (FR-020). */
+	groupDisplayNames?: Record<string, string>;
+}
+
+/** App-supplied, public-only setup input (FR-015/FR-016/FR-017). */
+export interface AuthConfig {
+	authority: string;
+	clientId: string;
+	redirectUrl: string;
+	scopes: string[];
+	providers: ProviderConfig[];
+	resources?: ResourceConfig[];
+	accessTierMapping: AccessTierMapping;
+	secureStore: SecureTokenStore;
+	authClient?: OidcAuthClient;
+	messages?: Partial<AuthMessageMap>;
+}
+
+/** Advanced/testing options. `platform` overrides the detected device platform. */
+export interface CreateAuthOptions {
+	platform?: DevicePlatform;
+}
+
+export type AuthStatus =
+	| 'loading'
+	| 'signed-out'
+	| 'authenticating'
+	| 'authenticated'
+	| 'token-refreshing'
+	| 'access-denied'
+	| 'cancelled'
+	| 'error';
+
+export type RestoreStatus = 'pending' | 'restored' | 'unavailable' | 'offline';
+
+/** Customer User / app-visible profile (FR-006). */
+export interface Profile {
+	tenantUserId: string;
+	displayName?: string;
+	email?: string;
+	provider: string;
+	claims: Record<string, unknown>;
+}
+
+export interface ProviderIdentity {
+	provider: string;
+	subject: string;
+	emailBehavior: 'direct' | 'private-relay' | 'none';
+}
+
+/** Access Tier — local interpretation of tenant indicators (FR-010). */
+export interface AccessTier {
+	tier: 'free' | 'premium';
+	source: 'group' | 'role' | 'claim' | 'default';
+	verification: 'verified' | 'unverified';
+	lastRefreshAt?: number;
+}
+
+export type AccessTokenStatus = 'success' | 'denied' | 'unavailable' | 'error';
+
+/** Access Token Request result (FR-007). */
+export interface AccessTokenResult {
+	resourceKey: string;
+	status: AccessTokenStatus;
+	token?: string;
+	expiresAt?: number;
+	errorCode?: AuthErrorCode;
+}
+
+/** Single active app-visible authenticated state (FR-005/FR-022). */
+export interface AuthState {
+	status: AuthStatus;
+	profile?: Profile;
+	accessTier?: AccessTier;
+	restore: RestoreStatus;
+	error?: AuthError;
+}
+
+/** Result of a premium-only gate check (US3). */
+export interface PremiumGateResult {
+	allowed: boolean;
+	tier: AccessTier;
+}
+
+/**
+ * What `signOutGlobal` did beyond the device (added in 0.2.2). Local state is
+ * cleared either way; `failed` means the tenant session may still be alive, so
+ * the next interactive sign-in can complete without a password prompt.
+ */
+export interface GlobalSignOutResult {
+	global: 'ended' | 'failed';
+	/** Present when `global` is `failed`. Redacted like every AuthError. */
+	error?: AuthError;
+}
+
+/** The auth controller returned by `createAuth` (single active account). */
+export interface Auth {
+	getState(): AuthState;
+	subscribe(listener: (state: AuthState) => void): () => void;
+	restore(): Promise<AuthState>;
+	signIn(providerId: ProviderId): Promise<AuthState>;
+	signOut(): Promise<void>;
+	signOutGlobal(): Promise<GlobalSignOutResult>;
+	requestAccessToken(resourceKey: string): Promise<AccessTokenResult>;
+	getAccessTier(): AccessTier;
+	/** Gate a premium-only path; enters `access-denied` when unverified (FR-011). */
+	requirePremium(): PremiumGateResult;
+	/** The first available provider to present on the current platform (UX-004), or undefined. */
+	getPlatformProvider(): ProviderConfig | undefined;
+	/** All available providers for the current platform, in configuration order (FR-003/FR-004). */
+	getPlatformProviders(): ProviderConfig[];
+}

package/src/config/validateConfig.ts

@@ -1,108 +1,114 @@
-/**
- * Deterministic configuration validation (FR-005 → configuration-error).
- * Throws AuthConfigError before any provider flow can start (US4 scenario 2).
- * Covers the auth-config.md Section A–F rules.
- */
-
-import type { AuthConfig } from './types';
-import { AuthConfigError } from '../diagnostics/errors';
-
-function hasScheme(url: string): boolean {
-	return /^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(url);
-}
-
-export function validateConfig(config: AuthConfig): void {
-	// Section A — tenant/client settings
-	if (!config.authority || !config.authority.trim()) {
-		throw new AuthConfigError('auth.error.configuration', 'Missing "authority"');
-	}
-	if (!hasScheme(config.authority)) {
-		throw new AuthConfigError('auth.error.configuration', '"authority" must be an absolute URL');
-	}
-	if (!config.clientId || !config.clientId.trim()) {
-		throw new AuthConfigError('auth.error.configuration', 'Missing "clientId"');
-	}
-	if (!config.redirectUrl || !config.redirectUrl.trim()) {
-		throw new AuthConfigError('auth.error.configuration', 'Missing "redirectUrl"');
-	}
-	if (!hasScheme(config.redirectUrl)) {
-		throw new AuthConfigError(
-			'auth.error.redirectMismatch',
-			'"redirectUrl" must include a scheme matching the native redirect configuration',
-		);
-	}
-	if (!Array.isArray(config.scopes) || config.scopes.length === 0) {
-		throw new AuthConfigError('auth.error.configuration', 'At least one OIDC scope is required');
-	}
-	if (!config.scopes.includes('offline_access')) {
-		throw new AuthConfigError(
-			'auth.error.configuration',
-			'"offline_access" scope is required for session restore and silent refresh',
-		);
-	}
-
-	// Sections B/C — providers
-	if (!Array.isArray(config.providers) || config.providers.length === 0) {
-		throw new AuthConfigError('auth.error.configuration', 'At least one provider must be configured');
-	}
-	const providerIds = new Set<string>();
-	for (const provider of config.providers) {
-		if (providerIds.has(provider.id)) {
-			throw new AuthConfigError('auth.error.configuration', `Duplicate provider "${provider.id}"`);
-		}
-		providerIds.add(provider.id);
-		if (!provider.domainHint || !provider.domainHint.trim()) {
-			throw new AuthConfigError(
-				'auth.error.configuration',
-				`Provider "${provider.id}" is missing a domainHint`,
-			);
-		}
-		if (!Array.isArray(provider.platforms) || provider.platforms.length === 0) {
-			throw new AuthConfigError(
-				'auth.error.configuration',
-				`Provider "${provider.id}" must declare at least one platform`,
-			);
-		}
-	}
-
-	// Section D — resources
-	if (config.resources) {
-		const resourceKeys = new Set<string>();
-		for (const resource of config.resources) {
-			if (!resource.key || !resource.key.trim()) {
-				throw new AuthConfigError('auth.error.configuration', 'A resource is missing "key"');
-			}
-			if (resourceKeys.has(resource.key)) {
-				throw new AuthConfigError('auth.error.configuration', `Duplicate resource "${resource.key}"`);
-			}
-			resourceKeys.add(resource.key);
-			if (!Array.isArray(resource.scopes) || resource.scopes.length === 0) {
-				throw new AuthConfigError(
-					'auth.error.configuration',
-					`Resource "${resource.key}" must declare at least one scope`,
-				);
-			}
-		}
-	}
-
-	// Section E — access-tier mapping
-	const mapping = config.accessTierMapping;
-	if (!mapping) {
-		throw new AuthConfigError('auth.error.configuration', 'Missing "accessTierMapping"');
-	}
-	const hasPremiumIndicator =
-		(mapping.premiumGroupObjectIds?.length ?? 0) > 0 ||
-		(mapping.premiumRoleNames?.length ?? 0) > 0 ||
-		(mapping.premiumClaimMatchers?.length ?? 0) > 0;
-	if (!hasPremiumIndicator) {
-		throw new AuthConfigError(
-			'auth.error.configuration',
-			'accessTierMapping must define at least one premium group object id, role name, or claim matcher',
-		);
-	}
-
-	// Section F — injected ports
-	if (!config.secureStore) {
-		throw new AuthConfigError('auth.error.configuration', 'A secureStore is required (FR-021)');
-	}
-}
+/**
+ * Deterministic configuration validation (FR-005 → configuration-error).
+ * Throws AuthConfigError before any provider flow can start (US4 scenario 2).
+ * Covers the auth-config.md Section A–F rules.
+ */
+
+import type { AuthConfig } from './types';
+import { AuthConfigError } from '../diagnostics/errors';
+
+function hasScheme(url: string): boolean {
+	return /^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(url);
+}
+
+export function validateConfig(config: AuthConfig): void {
+	// Section A — tenant/client settings
+	if (!config.authority || !config.authority.trim()) {
+		throw new AuthConfigError('auth.error.configuration', 'Missing "authority"');
+	}
+	if (!hasScheme(config.authority)) {
+		throw new AuthConfigError('auth.error.configuration', '"authority" must be an absolute URL');
+	}
+	if (!config.clientId || !config.clientId.trim()) {
+		throw new AuthConfigError('auth.error.configuration', 'Missing "clientId"');
+	}
+	if (!config.redirectUrl || !config.redirectUrl.trim()) {
+		throw new AuthConfigError('auth.error.configuration', 'Missing "redirectUrl"');
+	}
+	if (!hasScheme(config.redirectUrl)) {
+		throw new AuthConfigError(
+			'auth.error.redirectMismatch',
+			'"redirectUrl" must include a scheme matching the native redirect configuration',
+		);
+	}
+	if (!Array.isArray(config.scopes) || config.scopes.length === 0) {
+		throw new AuthConfigError('auth.error.configuration', 'At least one OIDC scope is required');
+	}
+	if (!config.scopes.includes('offline_access')) {
+		throw new AuthConfigError(
+			'auth.error.configuration',
+			'"offline_access" scope is required for session restore and silent refresh',
+		);
+	}
+
+	// Sections B/C — providers
+	if (!Array.isArray(config.providers) || config.providers.length === 0) {
+		throw new AuthConfigError(
+			'auth.error.configuration',
+			'At least one provider must be configured',
+		);
+	}
+	const providerIds = new Set<string>();
+	for (const provider of config.providers) {
+		if (providerIds.has(provider.id)) {
+			throw new AuthConfigError('auth.error.configuration', `Duplicate provider "${provider.id}"`);
+		}
+		providerIds.add(provider.id);
+		if (!provider.domainHint || !provider.domainHint.trim()) {
+			throw new AuthConfigError(
+				'auth.error.configuration',
+				`Provider "${provider.id}" is missing a domainHint`,
+			);
+		}
+		if (!Array.isArray(provider.platforms) || provider.platforms.length === 0) {
+			throw new AuthConfigError(
+				'auth.error.configuration',
+				`Provider "${provider.id}" must declare at least one platform`,
+			);
+		}
+	}
+
+	// Section D — resources
+	if (config.resources) {
+		const resourceKeys = new Set<string>();
+		for (const resource of config.resources) {
+			if (!resource.key || !resource.key.trim()) {
+				throw new AuthConfigError('auth.error.configuration', 'A resource is missing "key"');
+			}
+			if (resourceKeys.has(resource.key)) {
+				throw new AuthConfigError(
+					'auth.error.configuration',
+					`Duplicate resource "${resource.key}"`,
+				);
+			}
+			resourceKeys.add(resource.key);
+			if (!Array.isArray(resource.scopes) || resource.scopes.length === 0) {
+				throw new AuthConfigError(
+					'auth.error.configuration',
+					`Resource "${resource.key}" must declare at least one scope`,
+				);
+			}
+		}
+	}
+
+	// Section E — access-tier mapping
+	const mapping = config.accessTierMapping;
+	if (!mapping) {
+		throw new AuthConfigError('auth.error.configuration', 'Missing "accessTierMapping"');
+	}
+	const hasPremiumIndicator =
+		(mapping.premiumGroupObjectIds?.length ?? 0) > 0 ||
+		(mapping.premiumRoleNames?.length ?? 0) > 0 ||
+		(mapping.premiumClaimMatchers?.length ?? 0) > 0;
+	if (!hasPremiumIndicator) {
+		throw new AuthConfigError(
+			'auth.error.configuration',
+			'accessTierMapping must define at least one premium group object id, role name, or claim matcher',
+		);
+	}
+
+	// Section F — injected ports
+	if (!config.secureStore) {
+		throw new AuthConfigError('auth.error.configuration', 'A secureStore is required (FR-021)');
+	}
+}