@chipmobilesdk/rn-auth 0.2.1 → 0.3.1

package/src/access/accessTier.ts

@@ -1,88 +1,88 @@
-/**
- * Access-tier evaluation (FR-010/FR-011/FR-019/FR-020, R6).
- *
- * Pure function over the authenticated token's claims and the app-specific
- * mapping. Object ids are authoritative; display names never grant access.
- * Missing, stale, ambiguous, or group-overage claims fail closed (premium
- * denied, verification = 'unverified').
- */
-
-import type { AccessTier, AccessTierMapping, ClaimMatcher } from '../config/types';
-
-/** The fail-closed default: free + unverified. */
-export function failClosedTier(): AccessTier {
-	return { tier: 'free', source: 'default', verification: 'unverified' };
-}
-
-function toStringArray(value: unknown): string[] {
-	if (Array.isArray(value)) {
-		return value.filter((entry): entry is string => typeof entry === 'string');
-	}
-	if (typeof value === 'string') {
-		return [value];
-	}
-	return [];
-}
-
-/**
- * Entra emits a groups overage indicator (`_claim_names.groups` or `hasgroups`)
- * instead of inline groups when the list is too large. Reading the full list
- * would require Graph (out of scope, FR-012), so overage fails closed.
- */
-function hasGroupOverage(claims: Record<string, unknown>): boolean {
-	if (claims.hasgroups === true) {
-		return true;
-	}
-	const claimNames = claims._claim_names as Record<string, unknown> | undefined;
-	if (claimNames && typeof claimNames === 'object' && 'groups' in claimNames) {
-		return true;
-	}
-	return false;
-}
-
-function matchesClaim(claims: Record<string, unknown>, matcher: ClaimMatcher): boolean {
-	const value = claims[matcher.claim];
-	if (Array.isArray(value)) {
-		return value.includes(matcher.equals);
-	}
-	return value === matcher.equals;
-}
-
-/** Evaluate the access tier, failing closed when entitlement is unverifiable. */
-export function evaluateAccessTier(
-	claims: Record<string, unknown>,
-	mapping: AccessTierMapping,
-	now: number = Date.now(),
-): AccessTier {
-	// Object ids first (authoritative). Display names are never consulted.
-	const groups = toStringArray(claims.groups);
-	if (
-		mapping.premiumGroupObjectIds.length > 0 &&
-		groups.some(group => mapping.premiumGroupObjectIds.includes(group))
-	) {
-		return { tier: 'premium', source: 'group', verification: 'verified', lastRefreshAt: now };
-	}
-
-	// Roles next.
-	const roles = toStringArray(claims.roles);
-	if (
-		mapping.premiumRoleNames?.length &&
-		roles.some(role => mapping.premiumRoleNames!.includes(role))
-	) {
-		return { tier: 'premium', source: 'role', verification: 'verified', lastRefreshAt: now };
-	}
-
-	// Custom claim matchers last.
-	if (mapping.premiumClaimMatchers?.some(matcher => matchesClaim(claims, matcher))) {
-		return { tier: 'premium', source: 'claim', verification: 'verified', lastRefreshAt: now };
-	}
-
-	// No premium indicator matched. If group claims are unavailable due to
-	// overage and premium depends on groups, we cannot verify → fail closed.
-	if (mapping.premiumGroupObjectIds.length > 0 && hasGroupOverage(claims)) {
-		return { tier: 'free', source: 'default', verification: 'unverified', lastRefreshAt: now };
-	}
-
-	// Verified free: claims were present and simply did not grant premium.
-	return { tier: 'free', source: 'default', verification: 'verified', lastRefreshAt: now };
-}
+/**
+ * Access-tier evaluation (FR-010/FR-011/FR-019/FR-020, R6).
+ *
+ * Pure function over the authenticated token's claims and the app-specific
+ * mapping. Object ids are authoritative; display names never grant access.
+ * Missing, stale, ambiguous, or group-overage claims fail closed (premium
+ * denied, verification = 'unverified').
+ */
+
+import type { AccessTier, AccessTierMapping, ClaimMatcher } from '../config/types';
+
+/** The fail-closed default: free + unverified. */
+export function failClosedTier(): AccessTier {
+	return { tier: 'free', source: 'default', verification: 'unverified' };
+}
+
+function toStringArray(value: unknown): string[] {
+	if (Array.isArray(value)) {
+		return value.filter((entry): entry is string => typeof entry === 'string');
+	}
+	if (typeof value === 'string') {
+		return [value];
+	}
+	return [];
+}
+
+/**
+ * Entra emits a groups overage indicator (`_claim_names.groups` or `hasgroups`)
+ * instead of inline groups when the list is too large. Reading the full list
+ * would require Graph (out of scope, FR-012), so overage fails closed.
+ */
+function hasGroupOverage(claims: Record<string, unknown>): boolean {
+	if (claims.hasgroups === true) {
+		return true;
+	}
+	const claimNames = claims._claim_names as Record<string, unknown> | undefined;
+	if (claimNames && typeof claimNames === 'object' && 'groups' in claimNames) {
+		return true;
+	}
+	return false;
+}
+
+function matchesClaim(claims: Record<string, unknown>, matcher: ClaimMatcher): boolean {
+	const value = claims[matcher.claim];
+	if (Array.isArray(value)) {
+		return value.includes(matcher.equals);
+	}
+	return value === matcher.equals;
+}
+
+/** Evaluate the access tier, failing closed when entitlement is unverifiable. */
+export function evaluateAccessTier(
+	claims: Record<string, unknown>,
+	mapping: AccessTierMapping,
+	now: number = Date.now(),
+): AccessTier {
+	// Object ids first (authoritative). Display names are never consulted.
+	const groups = toStringArray(claims.groups);
+	if (
+		mapping.premiumGroupObjectIds.length > 0 &&
+		groups.some(group => mapping.premiumGroupObjectIds.includes(group))
+	) {
+		return { tier: 'premium', source: 'group', verification: 'verified', lastRefreshAt: now };
+	}
+
+	// Roles next.
+	const roles = toStringArray(claims.roles);
+	if (
+		mapping.premiumRoleNames?.length &&
+		roles.some(role => mapping.premiumRoleNames!.includes(role))
+	) {
+		return { tier: 'premium', source: 'role', verification: 'verified', lastRefreshAt: now };
+	}
+
+	// Custom claim matchers last.
+	if (mapping.premiumClaimMatchers?.some(matcher => matchesClaim(claims, matcher))) {
+		return { tier: 'premium', source: 'claim', verification: 'verified', lastRefreshAt: now };
+	}
+
+	// No premium indicator matched. If group claims are unavailable due to
+	// overage and premium depends on groups, we cannot verify → fail closed.
+	if (mapping.premiumGroupObjectIds.length > 0 && hasGroupOverage(claims)) {
+		return { tier: 'free', source: 'default', verification: 'unverified', lastRefreshAt: now };
+	}
+
+	// Verified free: claims were present and simply did not grant premium.
+	return { tier: 'free', source: 'default', verification: 'verified', lastRefreshAt: now };
+}

package/src/config/types.ts

@@ -1,143 +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;
-}
-
-/** 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<void>;
-	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[];
+}