@chipmobilesdk/rn-auth 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -1,113 +1,126 @@
-# Changelog
-
-All notable changes to `@chipmobilesdk/rn-auth` are documented here. This project
-adheres to [Semantic Versioning](https://semver.org/).
-
-## [0.3.0] - 2026-11-01
-
-Minor release fixing session integrity. Two type changes can need a one-line code
-change (see Changed): `signOutGlobal()` resolves to a result instead of `void`, and
-`OidcTokens.refreshToken` / `idToken` are optional.
-
-### Fixed
-
-- **A sign-out during a token refresh no longer revives the session.** The refresh
-  wrote its refresh token back into memory and set the state to `authenticated`
-  after the sign-out. Every session start and end now bumps a session generation,
-  and work that crossed one is discarded.
-- **Rotated refresh tokens are persisted.** A rotation only reached memory, so a
-  restart came back with a token the provider may already have retired. Concurrent
-  `requestAccessToken` calls for one resource now share one network refresh, and a
-  cache hit no longer flashes `token-refreshing`.
-- **Restore deletes the stored session only on an `invalid_grant` verdict.** Any
-  error other than a recognised network failure used to delete it, so a timeout or a
-  5xx signed users out. Errors are classified by OAuth and AADSTS codes in an ordered
-  table (`oidc/classifyError.ts`) instead of loose substrings; unclassified errors
-  restore `offline`.
-- **Restore no longer stays `loading`** when the Keychain write fails, and keeps the
-  stored profile when a refresh returns no id token.
-- **Sign-in commits only what it stored.** A failed Keychain write left a refresh
-  token in memory under an `error` state; an authorize without a refresh token now
-  reports a developer-facing `configuration-error` instead of a session that never
-  survives a restart.
-- **`signOutGlobal()` sends the id token hint** and reports a failed end-session
-  instead of swallowing it.
-- **A throwing state listener no longer turns a completed sign-in into an error.**
-- **The development-only `console.warn` of the raw native error is removed.** It
-  bypassed redaction.
-
-### Changed
-
-- `signOutGlobal()` resolves to `GlobalSignOutResult` (`{ global: 'ended' | 'failed',
-  error? }`) instead of `void`.
-- `OidcTokens.refreshToken` and `OidcTokens.idToken` are optional; a provider that
-  omits them is reported as absent rather than as an empty string. The persisted
-  session artifact gains an optional `idToken`; artifacts written by 0.2.1 still
-  restore.
-
-## [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]: #
+# @chipmobilesdk/rn-auth
+
+## 0.3.1
+
+### Patch Changes
+
+- Packaging only; no code change. The package no longer declares `engines.node`: a
+  React Native package does not run on Node, so the field only produced install
+  warnings in apps on another Node version. rn-i18n's command-line tooling does run
+  on Node; its README's compatibility table states the version it needs. ([#14](https://github.com/operationd8979/chip-mobile-sdk/pull/14))
+
+## [0.3.0] - 2026-11-01
+
+Minor release fixing session integrity. Two type changes can need a one-line code
+change (see Changed): `signOutGlobal()` resolves to a result instead of `void`, and
+`OidcTokens.refreshToken` / `idToken` are optional.
+
+### Fixed
+
+- **A sign-out during a token refresh no longer revives the session.** The refresh
+  wrote its refresh token back into memory and set the state to `authenticated`
+  after the sign-out. Every session start and end now bumps a session generation,
+  and work that crossed one is discarded.
+- **Rotated refresh tokens are persisted.** A rotation only reached memory, so a
+  restart came back with a token the provider may already have retired. Concurrent
+  `requestAccessToken` calls for one resource now share one network refresh, and a
+  cache hit no longer flashes `token-refreshing`.
+- **Restore deletes the stored session only on an `invalid_grant` verdict.** Any
+  error other than a recognised network failure used to delete it, so a timeout or a
+  5xx signed users out. Errors are classified by OAuth and AADSTS codes in an ordered
+  table (`oidc/classifyError.ts`) instead of loose substrings; unclassified errors
+  restore `offline`.
+- **Restore no longer stays `loading`** when the Keychain write fails, and keeps the
+  stored profile when a refresh returns no id token.
+- **Sign-in commits only what it stored.** A failed Keychain write left a refresh
+  token in memory under an `error` state; an authorize without a refresh token now
+  reports a developer-facing `configuration-error` instead of a session that never
+  survives a restart.
+- **`signOutGlobal()` sends the id token hint** and reports a failed end-session
+  instead of swallowing it.
+- **A throwing state listener no longer turns a completed sign-in into an error.**
+- **The development-only `console.warn` of the raw native error is removed.** It
+  bypassed redaction.
+
+### Changed
+
+- `signOutGlobal()` resolves to `GlobalSignOutResult` (`{ global: 'ended' | 'failed',
+  error? }`) instead of `void`.
+- `OidcTokens.refreshToken` and `OidcTokens.idToken` are optional; a provider that
+  omits them is reported as absent rather than as an empty string. The persisted
+  session artifact gains an optional `idToken`; artifacts written by 0.2.1 still
+  restore.
+
+## [0.2.1] - 2026-08-01
+
+### Changed
+
+- The package now ships its agent skill (`skills/`), which consuming apps
+  copy in with `scripts/sync-sdk-skills.mjs`. No code change.
+
+## [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

@@ -1,190 +1,190 @@
-# @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.3.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).
-
-### Session lifecycle guarantees
-
-- **Restore deletes the stored session only when the provider rejects the refresh
-  token** (`invalid_grant` and the equivalent AADSTS codes). A timeout, a 5xx or an
-  error the package cannot classify restores `offline`: cached profile, tier
-  unverified, retried on the next `restore()`.
-- **A sign-out wins.** A token refresh still in flight when the user signs out is
-  discarded; it cannot write a token back or return the state to `authenticated`.
-- **Rotated refresh tokens are persisted** as soon as they arrive, and concurrent
-  `requestAccessToken` calls for one resource share one network refresh.
-- **`signOutGlobal()` returns `{ global: 'ended' | 'failed', error? }`.** Local state
-  is cleared either way; `failed` means the tenant session may still be alive.
-
-## 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.
+# @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**: see [CHANGELOG](CHANGELOG.md)
+- **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).
+
+### Session lifecycle guarantees
+
+- **Restore deletes the stored session only when the provider rejects the refresh
+  token** (`invalid_grant` and the equivalent AADSTS codes). A timeout, a 5xx or an
+  error the package cannot classify restores `offline`: cached profile, tier
+  unverified, retried on the next `restore()`.
+- **A sign-out wins.** A token refresh still in flight when the user signs out is
+  discarded; it cannot write a token back or return the state to `authenticated`.
+- **Rotated refresh tokens are persisted** as soon as they arrive, and concurrent
+  `requestAccessToken` calls for one resource share one network refresh.
+- **`signOutGlobal()` returns `{ global: 'ended' | 'failed', error? }`.** Local state
+  is cleared either way; `failed` means the tenant session may still be alive.
+
+## 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 --workspace @chipmobilesdk/rn-auth
+npm run pack:check --workspace @chipmobilesdk/rn-auth
+npm run validate
+```
+
+## 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.