@chipmobilesdk/rn-auth 0.3.0 → 0.4.0

package/skills/sdk-rn-auth/SKILL.md

@@ -1,63 +1,65 @@
----
-name: sdk-rn-auth
-description: "Authentication via @chipmobilesdk/rn-auth: OIDC/AppAuth login, keychain token storage, access tiers, auth error handling. Use when wiring sign-in, storing tokens securely, gating features by tier, or configuring a tenant/provider."
-metadata:
-  package: "@chipmobilesdk/rn-auth"
-  packageVersion: "0.2.0"
-user-invocable: true
-disable-model-invocation: false
----
-
-# @chipmobilesdk/rn-auth
-
-OIDC authentication with secure token storage and an access-tier model for
-feature gating.
-
-## Use this when
-
-- Wiring sign-in / sign-out
-- Persisting tokens (must be keychain, never plain storage)
-- Gating a feature on the user's access tier
-- Mapping an auth failure to a user-facing message
-- Onboarding a new tenant or identity provider
-
-## Configuration is a contract, not options
-
-Tenant and provider setup has prerequisites that fail at runtime, not at build time.
-Before configuring anything, walk `## Configuration contract (LIB-010)` and
-`## Tenant / provider prerequisite checklist (LIB-018)` in the README. Skipping the
-checklist is the usual cause of "login works locally, fails in the new environment".
-
-## Fail closed
-
-`failClosedTier` exists because an unknown tier must deny access, not grant it. When
-tier evaluation is unavailable, deny. Never default an unresolved tier to a permissive
-value.
-
-## Public API (v0.3.0)
-
-Runtime:
-
-- `createAppAuthClient(...)` — the OIDC client
-- `createKeychainSecureStore(...)` — token persistence; `AUTH_STORAGE_KEY`
-- `evaluateAccessTier(...)`, `failClosedTier` — feature gating
-- `AuthProvider` — React context provider
-
-Types: `SecureTokenStore`, `AuthProviderProps`, `AuthErrorCode`, `AuthErrorAudience`,
-`AuthMessageMap`, `AuthMessageKey`
-
-`AuthErrorAudience` distinguishes what may be shown to a user from what is diagnostic
-only — never render a diagnostic-audience message in the UI.
-
-## Where the detail lives
-
-Read one section of `node_modules/@chipmobilesdk/rn-auth/README.md`:
-
-| Need | Section |
-|---|---|
-| First integration | `## Install (consuming app)`, `## Quick start` |
-| Required config fields | `## Configuration contract (LIB-010)` |
-| New tenant or IdP | `## Tenant / provider prerequisite checklist (LIB-018)` |
-| Token handling, logging rules | `## Security & privacy` |
-| Full export list | `## Public API` |
-| Version/peer constraints | `## Compatibility and validation` |
+---
+name: sdk-rn-auth
+description: "Authentication via @chipmobilesdk/rn-auth: OIDC/AppAuth login, keychain token storage, access tiers, auth error handling. Use when wiring sign-in, storing tokens securely, gating features by tier, or configuring a tenant/provider."
+metadata:
+  package: "@chipmobilesdk/rn-auth"
+user-invocable: true
+disable-model-invocation: false
+---
+
+# @chipmobilesdk/rn-auth
+
+OIDC authentication with secure token storage and an access-tier model for
+feature gating.
+
+## Use this when
+
+- Wiring sign-in / sign-out
+- Persisting tokens (must be keychain, never plain storage)
+- Gating a feature on the user's access tier
+- Mapping an auth failure to a user-facing message
+- Onboarding a new tenant or identity provider
+
+## Configuration is a contract, not options
+
+Tenant and provider setup has prerequisites that fail at runtime, not at build time.
+Before configuring anything, walk `## Configuration contract (LIB-010)` and
+`## Tenant / provider prerequisite checklist (LIB-018)` in the README. Skipping the
+checklist is the usual cause of "login works locally, fails in the new environment".
+
+## Fail closed
+
+`failClosedTier` exists because an unknown tier must deny access, not grant it. When
+tier evaluation is unavailable, deny. Never default an unresolved tier to a permissive
+value.
+
+## Public API
+
+Runtime:
+
+- `createAppAuthClient(...)` — the OIDC client
+- `createKeychainSecureStore(...)` — token persistence; `AUTH_STORAGE_KEY`
+- `evaluateAccessTier(...)`, `failClosedTier` — feature gating
+- `AuthProvider` — React context provider
+
+Testing (`@chipmobilesdk/rn-auth/testing`): `createMemorySecureStore`,
+`runSecureTokenStoreConformance`, `runOidcAuthClientConformance` — README `## Testing`.
+
+Types: `SecureTokenStore`, `AuthProviderProps`, `AuthErrorCode`, `AuthErrorAudience`,
+`AuthMessageMap`, `AuthMessageKey`
+
+`AuthErrorAudience` distinguishes what may be shown to a user from what is diagnostic
+only — never render a diagnostic-audience message in the UI.
+
+## Where the detail lives
+
+Read one section of `node_modules/@chipmobilesdk/rn-auth/README.md`:
+
+| Need | Section |
+|---|---|
+| First integration | `## Install (consuming app)`, `## Quick start` |
+| Required config fields | `## Configuration contract (LIB-010)` |
+| New tenant or IdP | `## Tenant / provider prerequisite checklist (LIB-018)` |
+| Token handling, logging rules | `## Security & privacy` |
+| Full export list | `## Public API` |
+| Version/peer constraints | `## Compatibility and validation` |

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/app-auth.ts

@@ -0,0 +1,6 @@
+/**
+ * `@chipmobilesdk/rn-auth/app-auth`: the default OIDC client over
+ * react-native-app-auth (AUTH-09). Its own entrypoint, so an app that injects its
+ * own client never reaches this module.
+ */
+export { createAppAuthClient, type AppAuthClientOptions } from './oidc/authClient';

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 | undefined;
+	email?: string | undefined;
+	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 | undefined;
+	accessTier?: AccessTier | undefined;
+	restore: RestoreStatus;
+	error?: AuthError | undefined;
+}
+
+/** 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[];
+}