@chipmobilesdk/rn-auth 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,71 @@
+# Changelog
+
+All notable changes to `@chipmobilesdk/rn-auth` are documented here. This project
+adheres to [Semantic Versioning](https://semver.org/).
+
+## [0.2.0] - 2026-06-30
+
+Add Facebook as a social sign-in provider (additive, backward compatible).
+
+### Added
+
+- `'facebook'` is now a valid `ProviderId`. Facebook is federated inside the
+  Entra External ID tenant like Google/Apple and routed with `domain_hint`
+  (`facebook.com`) — no native Facebook SDK and no new dependency.
+- `auth.action.continueFacebook` message key with English default
+  `'Continue with Facebook'`.
+- `Auth.getPlatformProviders()` and the `useSignInProviders()` hook return all
+  available providers for the current platform in configuration order, so a
+  platform can present multiple sign-in buttons (e.g. Google + Facebook).
+
+### Changed
+
+- `defaultProviderForPlatform` / `getPlatformProvider()` / `useSignInProvider()`
+  now return the first available provider in configuration order. Behavior is
+  unchanged for existing single-provider (Google/Apple-only) configurations.
+
+### Notes
+
+- Backward compatible: apps that do not configure Facebook observe no change.
+- Adoption: add `{ id: 'facebook', platforms: ['ios','android'], domainHint:
+  'facebook.com', labelKey: 'auth.action.continueFacebook' }` to `providers`,
+  federate Facebook in the tenant, and render `useSignInProviders()` for the
+  multi-button experience. See the README and
+  `specs/004-facebook-auth-provider/`.
+- iOS: offering Facebook (a third-party login) requires Sign in with Apple to
+  remain available (Apple guideline 4.8) — it does. Update Apple App Privacy and
+  Google Play Data Safety to add Facebook before release.
+
+## [0.1.0] - 2026-06-24
+
+Initial release of the reusable Microsoft Entra External ID auth library.
+
+### Added
+
+- `createAuth(config, options?)` controller with a single active account: sign-in,
+  session restore, local `signOut()` and global `signOutGlobal()`, per-resource
+  `requestAccessToken()`, `getAccessTier()`, and a `requirePremium()` gate.
+- `AuthProvider` plus `useAuth`, `useProfile`, `useAccessTier`, `useAccessToken`,
+  and `useSignInProvider` hooks.
+- Injectable ports `OidcAuthClient` and `SecureTokenStore`, with default adapters
+  `createAppAuthClient()` (react-native-app-auth, PKCE public client) and
+  `createKeychainSecureStore()` (react-native-keychain).
+- Social routing via per-provider `domain_hint` (Google on Android, Apple on iOS),
+  with Google/Apple federated inside the tenant — no native social SDK required.
+- Access-tier evaluation (`evaluateAccessTier`) that prefers stable group object
+  ids, ignores display names, and fails closed on missing/stale/overage claims.
+- Token + refresh persistence restricted to platform secure storage; access
+  tokens cached in memory with silent refresh.
+- Stable user-facing message keys with English defaults (`DEFAULT_MESSAGES`),
+  no i18n runtime dependency.
+- Diagnostics (`AuthError`/`AuthConfigError`) with secret/token redaction.
+
+### Notes
+
+- New package; no migration required. Adoption notes and the tenant/provider
+  prerequisite checklist are in the README.
+- Native redirect configuration and on-device provider flows must be validated
+  per `specs/003-mobile-entra-auth/contracts/native-setup.md` (the R8 spike).
+
+[0.2.0]: #
+[0.1.0]: #

package/README.md

@@ -0,0 +1,177 @@
+# @chipmobilesdk/rn-auth
+
+Reusable Microsoft Entra External ID authentication for ChipMobileSdk-family
+React Native apps. The library is a **public OAuth2/OIDC client** (Authorization
+Code + PKCE, **no backend, no client secret**). Android presents **Continue with
+Google**, iOS presents **Continue with Apple**, and either platform can also
+present **Continue with Facebook**; all start the same External ID
+sign-up/sign-in user flow, routed to the right social provider with a
+`domain_hint`. Google, Apple, and Facebook are federated **inside the External ID
+tenant**, so the app embeds no native social SDK and no Sign in with Apple
+entitlement. Each platform renders all of its configured providers as separate
+buttons in configuration order.
+
+> **License:** `UNLICENSED`. Published publicly for use by the owner's
+> applications; no open-source license is granted.
+
+- **Version**: `0.2.0`
+- **Entrypoint**: `@chipmobilesdk/rn-auth`
+
+- Single active account, session restore, local + global sign-out.
+- Per-resource delegated access tokens for Azure resources.
+- Group/role/claim access-tier evaluation that **fails closed**.
+- Tokens persist only in platform secure storage (Keychain / Keystore).
+- No i18n runtime dependency: user-facing copy is stable keys + English defaults.
+
+## Install (consuming app)
+
+```sh
+npm install @chipmobilesdk/rn-auth react-native-app-auth react-native-keychain
+cd ios && pod install
+```
+
+`react`, `react-native`, `react-native-app-auth`, and `react-native-keychain`
+are **peer dependencies**. The two native libraries are only required by the
+default adapters — an app injecting custom ports may omit them.
+
+See [native setup](../../specs/003-mobile-entra-auth/contracts/native-setup.md)
+for the iOS `Info.plist` URL scheme and the Android `appAuthRedirectScheme`
+Gradle placeholder.
+
+## Quick start
+
+```tsx
+import {
+  AuthProvider,
+  createAuth,
+  createAppAuthClient,
+  createKeychainSecureStore,
+  useAuth,
+  useSignInProvider,
+} from '@chipmobilesdk/rn-auth';
+
+const auth = createAuth({
+  authority: 'https://<tenant>.ciamlogin.com/<tenant>.onmicrosoft.com',
+  clientId: '<public-client-id>',
+  redirectUrl: 'com.yourapp://oauthredirect',
+  scopes: ['openid', 'profile', 'offline_access'],
+  providers: [
+    { id: 'google', platforms: ['android'], domainHint: 'google.com', labelKey: 'auth.action.continueGoogle' },
+    { id: 'apple', platforms: ['ios'], domainHint: 'apple.com', labelKey: 'auth.action.continueApple' },
+    // Optional third provider, shown on both platforms after the platform-native one:
+    { id: 'facebook', platforms: ['ios', 'android'], domainHint: 'facebook.com', labelKey: 'auth.action.continueFacebook' },
+  ],
+  resources: [{ key: 'storage', scopes: ['https://storage.azure.com/user_impersonation'] }],
+  accessTierMapping: { premiumGroupObjectIds: ['<premium-group-object-id>'] },
+  secureStore: createKeychainSecureStore(),
+  authClient: createAppAuthClient(),
+});
+
+export const App = () => (
+  <AuthProvider auth={auth}>
+    <Screen />
+  </AuthProvider>
+);
+```
+
+Hooks: `useAuth()` (state + `signIn`/`signOut`/`signOutGlobal`/`restore`/`requirePremium`),
+`useProfile()`, `useAccessTier()`, `useAccessToken(resourceKey)`,
+`useSignInProviders()` (all platform providers, in config order — map to one
+button each) and `useSignInProvider()` (first available, for a single-button UI).
+
+## Configuration contract (LIB-010)
+
+The library accepts **public values only**. Provider secrets, Apple keys, and
+client secrets are configured in the External ID tenant, never in the app
+([FR-017](../../specs/003-mobile-entra-auth/spec.md)).
+
+| Section | Keys |
+|---------|------|
+| A — Tenant / client | `authority`, `clientId`, `redirectUrl`, `scopes` (include `offline_access`) |
+| B — Android Google | `providers[google]`: `domainHint`, `platforms: ['android']`, `labelKey` |
+| C — iOS Apple | `providers[apple]`: `domainHint`, `platforms: ['ios']`, `labelKey` |
+| C2 — Facebook (optional) | `providers[facebook]`: `domainHint: 'facebook.com'`, `platforms: ['ios','android']`, `labelKey: 'auth.action.continueFacebook'`, optional `available` |
+| D — Resources | `resources[].key`, `resources[].scopes`, `resources[].displayName?` |
+| E — Access tier | `accessTierMapping.premiumGroupObjectIds` (+ optional role names / claim matchers; display names are diagnostics-only) |
+| F — Ports | `secureStore` (required), `authClient` (optional), `messages` (optional copy override) |
+
+Full contract: [auth-config.md](../../specs/003-mobile-entra-auth/contracts/auth-config.md)
+and [public-api.md](../../specs/003-mobile-entra-auth/contracts/public-api.md).
+
+## Tenant / provider prerequisite checklist (LIB-018)
+
+These are **external** prerequisites (FR-013/FR-018) completed before the library
+can sign users in:
+
+**External ID tenant**
+- [ ] Customer (CIAM) tenant created; sign-up/sign-in user flow configured.
+- [ ] App registration created as a **public client**; redirect URI added (must match the native scheme, e.g. `com.yourapp://oauthredirect`).
+- [ ] API permissions / scopes for each target Azure resource consented.
+- [ ] Premium group(s) created; record the **group object id** (not the name).
+- [ ] Groups (or roles) emitted in the token; plan for groups overage.
+
+**Google (federated in the tenant)**
+- [ ] Google Cloud OAuth client configured; client id/secret stored in the **tenant** IdP config (never in the app).
+- [ ] Google added as an identity provider in the External ID user flow.
+
+**Apple (federated in the tenant)**
+- [ ] Apple Services ID + Sign in with Apple key configured; stored in the **tenant** IdP config.
+- [ ] Apple added as an identity provider in the External ID user flow.
+- [ ] Note: Apple sign-in operational credentials expire on a schedule and must be rotated tenant-side.
+
+**Facebook (federated in the tenant — optional)**
+- [ ] Facebook app created in Meta for Developers; **App ID + App Secret** stored in the **tenant** IdP config (never in the app).
+- [ ] Facebook added as an identity provider in the External ID user flow; `domain_hint` confirmed (expected `facebook.com`).
+- [ ] Facebook app OAuth redirect / valid OAuth domains match the tenant federation redirect.
+- [ ] iOS: because Facebook is a third-party login, keep Sign in with Apple offered on iOS (Apple guideline 4.8).
+- [ ] Update Apple App Privacy and Google Play Data Safety to include Facebook as an identity provider before release.
+
+## Security & privacy
+
+- Tokens and refresh artifacts persist only in `SecureTokenStore` (Keychain /
+  Keystore). Access tokens are kept in memory only.
+- Access-tier decisions prefer stable group **object ids**; display names never
+  grant access; missing/overage claims fail closed.
+- Diagnostics (`AuthError`) never contain secrets or token values.
+- Authentication and profile data are collected and transmitted to the
+  identity providers and configured Azure resources — update Apple App Privacy
+  and Google Play Data Safety before release.
+
+## Public API
+
+Everything below is exported from `@chipmobilesdk/rn-auth`; deep imports into
+`config/`, `core/`, `tokens/`, `oidc/`, `access/`, `diagnostics/`, or `react/`
+are unsupported.
+
+- Controller and configuration: `createAuth`, `Auth`, `AuthConfig`,
+  `CreateAuthOptions`, `AuthState`, `AuthStatus`, `RestoreStatus`
+- Identity and access: `Profile`, `ProviderConfig`, `ProviderIdentity`,
+  `ResourceConfig`, `AccessTier`, `AccessTierMapping`, `AccessTokenResult`,
+  `PremiumGateResult`, `evaluateAccessTier`, `failClosedTier`
+- Ports and default adapters: `SecureTokenStore`, `createKeychainSecureStore`,
+  `AUTH_STORAGE_KEY`, `OidcAuthClient`, `createAppAuthClient` and the public OIDC
+  request/token types
+- React: `AuthProvider`, `useAuth`, `useProfile`, `useAccessTier`,
+  `useAccessToken`, `useSignInProvider`, `useSignInProviders`
+- Diagnostics and copy: `AuthError`, `AuthConfigError`, `isAuthError`, `redact`,
+  `DEFAULT_MESSAGES`, `resolveMessages` and their public code/message types
+
+## Compatibility and validation
+
+React ≥19 · React Native ≥0.85 · `react-native-app-auth` ≥8 ·
+`react-native-keychain` ≥10 · iOS + Android · Node ≥22.11 for tooling.
+
+The demo integration lives in `src/screens/AuthDemoScreen.tsx`. Run from the
+repository root:
+
+```bash
+npm run typecheck:auth
+npm run pack:auth
+npm run validate:auth
+```
+
+## Distribution and license
+
+Published as a public npm package (`publishConfig.access: public`) for use by
+the owner's applications. License: `UNLICENSED`; no open-source license is
+granted.

package/package.json

@@ -0,0 +1,53 @@
+{
+	"name": "@chipmobilesdk/rn-auth",
+	"version": "0.2.0",
+	"private": false,
+	"license": "UNLICENSED",
+	"main": "src/index.ts",
+	"types": "src/index.ts",
+	"exports": {
+		".": {
+			"types": "./src/index.ts",
+			"react-native": "./src/index.ts",
+			"default": "./src/index.ts"
+		}
+	},
+	"files": [
+		"src/index.ts",
+		"src/config",
+		"src/core",
+		"src/tokens",
+		"src/oidc",
+		"src/access",
+		"src/diagnostics",
+		"src/react",
+		"README.md",
+		"CHANGELOG.md"
+	],
+	"sideEffects": false,
+	"scripts": {
+		"typecheck": "tsc -p tsconfig.json --noEmit",
+		"pack:dry-run": "npm pack --dry-run"
+	},
+	"peerDependencies": {
+		"react": ">=19",
+		"react-native": ">=0.85",
+		"react-native-app-auth": ">=8",
+		"react-native-keychain": ">=10"
+	},
+	"peerDependenciesMeta": {
+		"react-native-app-auth": {
+			"optional": true
+		},
+		"react-native-keychain": {
+			"optional": true
+		}
+	},
+	"engines": {
+		"node": ">=22.11.0"
+	},
+	"publishConfig": {
+		"access": "public",
+		"registry": "https://registry.npmjs.org/"
+	}
+}

package/src/access/accessTier.ts

@@ -0,0 +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 };
+}

package/src/config/types.ts

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

package/src/config/validateConfig.ts

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