@chipmobilesdk/rn-auth 0.3.1 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,146 @@
 # @chipmobilesdk/rn-auth
 
+## 0.5.0
+
+### Minor Changes
+
+- A restored session reports the provider the user signed in with. A refresh answers with the tenant's own `idp` (`google.com`), so after a restart the same session used to describe itself differently — `profile.provider` changed from `google` to `google.com`. ([#19](https://github.com/operationd8979/chip-mobile-sdk/pull/19))
+
+  `auth.canAccessPremium()` answers whether a premium path is open and changes nothing. `requirePremium()`, which also moves the whole controller to `access-denied` — a status every screen reading `state.status` then sees, and one only a sign-in or `restore()` leaves — is deprecated and will be removed in 0.5.0. Both are on `useAuth()`.
+
+  `ProviderId` is open (`KnownProviderId | (string & {})`), `labelKey` takes an app's own message key, and `ProviderConfig.additionalParameters` passes extra OIDC parameters such as `prompt`, so federating another identity provider is a change to an app's config rather than a release of this package. A provider's own parameters cannot override `domain_hint`.
+
+  `config.messages` is read at last: `auth.getMessages()` and `useAuthMessages()` return this package's copy with the app's overrides applied. Configuration validation refuses a plaintext `authority` (http is accepted only for localhost), a provider platform other than `ios`/`android`, and a provider with no `labelKey`. `createAppAuthClient({ serviceConfiguration })` takes the endpoints directly, so an authorize, refresh or sign-out no longer costs a `.well-known` round-trip. `mapClaimsToProfile` and `describeProviderIdentity` are exported, which is what the already-public `ProviderIdentity` type describes.
+
+  `useAccessToken(resourceKey)` drops a result that arrives after the component unmounted or moved to another resource, and starts from `idle` when the resource changes.
+
+  The stored session artifact holds an identity — tenant user id, display name, email, provider — and no longer the whole id-token claim set, group ids included; a restore that rotated nothing leaves the Keychain untouched. After an `offline` restore, `profile.claims` is empty and the tier fails closed, as before. The never-emitted `entitlement-unverified` error code is gone from `AuthErrorCode`, and `AuthError.messageKey` is typed as `AuthMessageKey` rather than `string`.
+
+- A 401 retry now gets a token the provider had to fetch again. `TokenProvider.requestAccessToken` takes `{ forceRefresh }`, which rn-auth implements by dropping the cached token for that resource, so the retry no longer re-sends the token the gateway had just refused — a cached token is still unexpired by the device's clock when the server rejects it. ([#19](https://github.com/operationd8979/chip-mobile-sdk/pull/19))
+
+  Failures an app can tell apart. `network` is a request that never arrived (no connection, a timeout, a dropped stream) and is retryable; `session-expired` is a session the user must renew. `AiError.cause` carries the code from the layer underneath — the gateway's own code, or rn-auth's — so a screen can explain *why*, and `retryAfterSeconds` is read from the `Retry-After` header when the body omits it. Both new codes have user copy, and the gateway's full code list is mapped rather than guessed from the status.
+
+  The remote behavior config is checked before it is trusted. `configUrl` and the document's `api.baseUrl` must be https (localhost excepted), the document must name the app it is for, its `schemaVersion` must be one this release understands, and `allowedHosts` pins where the client may send its bearer token. A broken TTL no longer means a revalidation on every request, and a retry count is bounded. A not-modified answer against a cache that is no longer there asks again without the ETag instead of reporting the 304 as a failure.
+
+  `configCacheFromKeyValue(port)` makes a durable config cache out of rn-core's `KeyValuePort`, so a second launch uses the last-good document instead of waiting for the network.
+
+  One quota figure: a chat's `done` event and `getQuota()` both record it on the client (`lastQuota()`), so `useAiQuota` and `useAiChat` cannot disagree, and a quota response that does not match the contract is refused rather than displayed. `getQuota()` recovers like a chat: a designated 404/410 reloads the configuration and retries, and a 401 retries once.
+
+  Streamed text reaches the screen on an interval (50 ms by default, `useAiChat(client, { flushIntervalMs })`) rather than once per token, and whatever arrived is flushed with the terminal state, so a half-answer stays on screen when a stream fails. A stream framed with CRLF is parsed incrementally, as the SSE specification allows. The transport seam is a published `StreamTransport` port instead of the internal reader's signature.
+
+## 0.4.0
+
+### Minor Changes
+
+- One diagnostic stream: install a sink with `installSdkSink` from
+  `@chipmobilesdk/rn-core` and it receives what every package observes (events,
+  failures, warnings) as `SdkDiagnostic`s, redacted. Listeners are notified through
+  rn-core, so a listener that throws no longer stops the others nor fails the call that
+  notified, and its error is reported rather than swallowed. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-ads: a banner's auto-refresh is a new cycle, so its `loaded` and `impression`
+    events are no longer deduplicated away; the dedupe memory is bounded. A throwing
+    status, consent or placement listener is reported as an `internal_error` event.
+  - rn-i18n: new `onDiagnostic` config receives every diagnostic (`I18nDiagnostic`,
+    with a stable `code`); without it, warnings go to `console.warn` in development
+    builds only. The warn-once memory is bounded.
+  - rn-chart: now depends on rn-core for its diagnostics.
+  - rn-payment: status, entitlement and pending listeners report a throw to the logger
+    instead of swallowing it.
+
+- The package's errors extend `SdkError` from the new `@chipmobilesdk/rn-core`
+  dependency: `isSdkError` recognises them alongside every other package's, and each
+  carries `pkg`, `code` and `retryable`. Names and codes are unchanged. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-ai and rn-camera: `retryable` is the new name of `recoverable`, which stays as a
+    deprecated alias.
+  - rn-auth: `retryable` is true for `network-unavailable`. `redact` also removes URLs,
+    e-mail addresses and UUIDs.
+  - rn-ads: `redact` also removes JWTs and e-mail addresses, and reduces an `AdsError`
+    to its code.
+  - rn-ai: an error message quoted from the gateway is pattern-redacted.
+  - rn-camera: `redact` also removes JWTs, e-mail addresses and UUIDs.
+  - rn-theme: `ThemeConfigError` has `code: 'invalid_config'` and `ThemeContrastError`
+    `code: 'contrast'` (new `ThemeErrorCode` type).
+  - rn-i18n: `I18nConfigError` has `code: 'invalid_config'` and `UnitConversionError`
+    `code: 'unit_conversion'` (new `I18nErrorCode` type).
+
+- Native peers load through `lazyPeer` from `@chipmobilesdk/rn-core`, on first use,
+  and a missing one is each package's own typed error. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-auth: creating `auth` no longer loads react-native-app-auth or
+    react-native-keychain; each loads on first use. New entrypoints
+    `@chipmobilesdk/rn-auth/app-auth` and `/keychain`. The default platform comes from
+    rn-core.
+  - rn-camera: a preview whose VisionCamera feed cannot load fails the session with
+    `cameraUnavailable` (new `controller.reportSurfaceUnavailable()`), instead of
+    showing black with no error. A missing VisionCamera module is `cameraUnavailable`.
+  - rn-notification: `createMmkvStore` reports a fallback to memory as
+    `STATE_STORE_DEGRADED` (to the SDK sinks and a new `onDegraded` option) and
+    exposes `durable`.
+  - rn-payment: an iOS app validates its catalog against the iOS product ids; the
+    default platform used to be Android everywhere. A missing react-native-iap is
+    `PAYMENT_UNAVAILABLE`.
+  - rn-theme: `buildThemes` runs without React Native (new `hairlineWidth` option) and
+    importing the package no longer loads Unistyles; `applyThemeMode` loads it on
+    first use.
+  - rn-ads, rn-local-db: the same loading, with the same error codes as before.
+
+- Hooks read through `useSyncExternalStore` (rn-core's `useExternalStore`) and
+  re-render only when what they return changes. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-auth: `useProfile` and `useAccessTier` no longer re-render for a status change,
+    and the provider's context no longer changes on every transition. New
+    `useAuthSelector`. `auth.getState()` returns the same frozen object until the state
+    changes, instead of a copy per call.
+  - rn-payment: `useEntitlement` re-renders only when its own entitlement changes; the
+    engine keeps unchanged entitlement objects across syncs and does not notify for a
+    sync that changed nothing.
+  - rn-ads: `usePlacementState` and `useAdsStatus` read tear-free; `useAdsEvents` keeps
+    one subscription when given an inline listener.
+  - rn-i18n: `useTranslation` returns the same `t` until the locale changes, and
+    `useLocale`'s `setLocale` is stable.
+  - rn-ai: new `useAiBehaviorState`, with `client.subscribe` and a stable
+    `client.getBehaviorState()`.
+
+- Every package's own copy is an rn-core message catalog that an app can translate. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-i18n: new `runtimeEntriesFromCatalog(catalog)` registers any SDK catalog in one
+    line, converting `{name}` variables to `{{name}}`.
+  - rn-ai: new `messageKeyForError(error)` gives the copy for every error code, and
+    `aiMessageSet`. The input placeholder default is neutral ("Type a message…"), and
+    two keys were added for errors that had none (`ai.error.signIn`, `ai.error.generic`).
+  - rn-auth: new `authMessages`, the catalog split into user and developer copy.
+  - rn-payment: new `paymentMessages`.
+  - rn-chart: summaries, announcements, adjustable-action labels, built-in state text
+    and legend hints come from `chartStrings`; pass `strings` to translate them. The
+    `accessibility.summaryFormatter` prop, declared before, now replaces the summary.
+
+- Port conformance suites: one list of checks that a package's fake and its real adapter
+  both pass, so a test written against the fake proves something about the device. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-core: `@chipmobilesdk/rn-core/testing` adds `runChecks`, `expectConformance`,
+    `ensure` and `createFaultRegistry` (deterministic fault injection by named point).
+  - rn-camera: a `./testing` entrypoint with `runPermissionPortConformance`,
+    `runCameraEngineConformance` and the test adapter, which stays on the main
+    entrypoint too until the next major. `createTestCamera(...).prompts()` counts system
+    prompts.
+  - rn-payment: `runProviderPortConformance` in `./testing`, passed by the fake store and
+    the Play adapter.
+  - rn-ads: `runAdsEngineConformance` in `./testing`, passed by the fake engine and the
+    AdMob adapter.
+  - rn-auth: a `./testing` entrypoint with `createMemorySecureStore`,
+    `runSecureTokenStoreConformance` and `runOidcAuthClientConformance`, passed by the
+    in-memory doubles and the keychain and app-auth adapters.
+
+### Patch Changes
+
+- Optional properties in the public types (`AuthState`, `Profile`, `UseAccessTokenResult`
+  and others) now accept an explicit `undefined`, so apps compiling with
+  `exactOptionalPropertyTypes` type-check against the package. No runtime change. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+- Updated dependencies ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17), [#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17), [#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17)):
+  - @chipmobilesdk/rn-core@0.1.0
+
 ## 0.3.1
 
 ### Patch Changes

package/README.md

@@ -74,11 +74,45 @@ export const App = () => (
 );
 ```
 
-Hooks: `useAuth()` (state + `signIn`/`signOut`/`signOutGlobal`/`restore`/`requirePremium`),
+Hooks: `useAuth()` (state + `signIn`/`signOut`/`signOutGlobal`/`restore`/`canAccessPremium`),
 `useProfile()`, `useAccessTier()`, `useAccessToken(resourceKey)`,
+`useAuthMessages()` (this package's copy, with your `messages` applied),
 `useSignInProviders()` (all platform providers, in config order — map to one
 button each) and `useSignInProvider()` (first available, for a single-button UI).
 
+### Gating a premium path
+
+```tsx
+const { canAccessPremium } = useAuth();
+const gate = canAccessPremium(); // { allowed, tier } — reads, changes nothing
+
+return gate.allowed ? <PremiumReport /> : <UpgradeNotice tier={gate.tier} />;
+```
+
+`canAccessPremium()` is a question. `requirePremium()`, which answers the same
+question *and* moves the whole controller to `access-denied` — a status every
+screen reading `state.status` then sees, and only a sign-in or `restore()`
+leaves — is deprecated and will go in 0.5.0.
+
+### Providers beyond the three with built-in copy
+
+A provider is a `domain_hint` and a label, so adding one the tenant federates is
+a change to this config and nothing else:
+
+```tsx
+providers: [
+  { id: 'microsoft', platforms: ['ios', 'android'], domainHint: 'live.com',
+    labelKey: 'app.action.continueMicrosoft',           // one of your own keys
+    additionalParameters: { prompt: 'select_account' }, // merged into authorize
+  },
+]
+```
+
+`ProviderId` is `KnownProviderId | (string & {})`: `'google' | 'apple' |
+'facebook'` stay in autocomplete, and any other id is accepted. A provider's
+`additionalParameters` cannot override `domain_hint`, so it can never route the
+flow to another IdP.
+
 ### Session lifecycle guarantees
 
 - **Restore deletes the stored session only when the provider rejects the refresh
@@ -91,6 +125,15 @@ button each) and `useSignInProvider()` (first available, for a single-button UI)
   `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.
+- **A restored profile reports the provider the user signed in with.** The stored
+  artifact carries it, because a refresh answers with the tenant's own `idp`
+  (`google.com`), which is not the id the app passed to `signIn`.
+- **The stored artifact holds an identity, not a token's claims:** the tenant user
+  id, display name, email and provider. After a restore that reached the provider,
+  `profile.claims` is the fresh id-token claim set; after an `offline` restore it is
+  empty, and the access tier fails closed. Read `state.restore` to tell them apart.
+- **An unchanged session is not rewritten.** A restore that rotated nothing leaves
+  the Keychain untouched, off the startup path.
 
 ## Configuration contract (LIB-010)
 
@@ -106,10 +149,15 @@ client secrets are configured in the External ID tenant, never in the app
 | 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) |
+| F — Ports | `secureStore` (required), `authClient` (optional), `messages` (optional copy override, readable through `useAuthMessages()`) |
 
-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).
+`createAuth` throws `AuthConfigError` before any flow can start when: `authority`
+is missing, relative, or not `https` (plain `http` is accepted only for
+`localhost`); `redirectUrl` has no scheme; `offline_access` is absent from
+`scopes`; no provider is configured, or one repeats an id, or lacks a
+`domainHint` or `labelKey`, or declares a platform other than `ios`/`android`; a
+resource repeats a key or declares no scope; `accessTierMapping` names no premium
+indicator; or no `secureStore` is supplied.
 
 ## Tenant / provider prerequisite checklist (LIB-018)
 
@@ -145,7 +193,9 @@ can sign users in:
   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.
+- Diagnostics (`AuthError`) never contain secrets or token values. `AuthError` extends
+  `SdkError` from `@chipmobilesdk/rn-core`: `isSdkError(error)` recognises it, `error.pkg`
+  is `rn-auth`, and `error.retryable` is true only for `network-unavailable`.
 - 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.
@@ -158,16 +208,54 @@ 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`
+- Identity and access: `Profile`, `ProviderConfig`, `ProviderId`,
+  `KnownProviderId`, `ProviderIdentity`, `ResourceConfig`, `AccessTier`,
+  `AccessTierMapping`, `AccessTokenResult`, `PremiumGateResult`,
+  `evaluateAccessTier`, `failClosedTier`, `mapClaimsToProfile`,
+  `describeProviderIdentity` (what an address is: `direct`, Apple's
+  `private-relay`, or `none`)
 - Ports and default adapters: `SecureTokenStore`, `createKeychainSecureStore`,
   `AUTH_STORAGE_KEY`, `OidcAuthClient`, `createAppAuthClient` and the public OIDC
-  request/token types
+  request/token types. `createAppAuthClient({ serviceConfiguration })` takes the
+  authorization, token and end-session endpoints directly; without them the native
+  module fetches `.well-known` on every authorize, refresh and sign-out, including
+  the refresh on the startup path. The two default adapters also have their own entrypoints,
+  `@chipmobilesdk/rn-auth/app-auth` and `@chipmobilesdk/rn-auth/keychain`, so an app
+  that injects its own client or store can skip them. Neither loads its native
+  module until it is used: react-native-app-auth on the first sign-in, refresh or
+  sign-out, react-native-keychain on the first read or write. Creating `auth` at
+  startup loads neither. A missing module is an `AuthConfigError` at that moment.
 - React: `AuthProvider`, `useAuth`, `useProfile`, `useAccessTier`,
-  `useAccessToken`, `useSignInProvider`, `useSignInProviders`
+  `useAccessToken`, `useAuthMessages`, `useSignInProvider`, `useSignInProviders`,
+  `useAuthSelector`. `useAccessToken(resourceKey)` starts from `idle` again when
+  the resource changes, and a result that arrives after the component unmounted
+  or moved on is dropped rather than applied.
+  Each hook reads the state through `useSyncExternalStore` and re-renders only when
+  what it returns changes: `useProfile` does not render for a status change. Use
+  `useAuthSelector(state => …, isEqual?)` for any other slice. `auth.getState()`
+  returns the same frozen object until the state changes.
 - Diagnostics and copy: `AuthError`, `AuthConfigError`, `isAuthError`, `redact`,
-  `DEFAULT_MESSAGES`, `resolveMessages` and their public code/message types
+  `DEFAULT_MESSAGES`, `resolveMessages` and their public code/message types, and
+  `authMessages`, the catalog split into `user` and `developer` copy. Register the user
+  copy with rn-i18n in one line: `runtimeEntriesFromCatalog(authMessages.user)`.
+
+## Testing
+
+```ts
+import { createAuth } from '@chipmobilesdk/rn-auth';
+import { createMemorySecureStore } from '@chipmobilesdk/rn-auth/testing';
+
+const auth = createAuth({ ...config, secureStore: createMemorySecureStore(), authClient });
+```
+
+`@chipmobilesdk/rn-auth/testing` is a separate entrypoint, so nothing in it reaches a
+production bundle. Besides `createMemorySecureStore(seed?)` it holds the checks every
+adapter must pass: `runSecureTokenStoreConformance` (null for an unknown key, last write
+wins, keys kept apart, safe removal, a long non-ASCII artifact intact) and
+`runOidcAuthClientConformance` (sign-in with claims and a future expiry, refresh, a
+closed sheet as `provider-cancelled`, a rejected refresh token as `session-expired`, and
+sign-out). The package runs them against its doubles and the keychain and app-auth
+adapters; run them against a store or client you inject.
 
 ## Compatibility and validation
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@chipmobilesdk/rn-auth",
-	"version": "0.3.1",
+	"version": "0.5.0",
 	"private": false,
 	"license": "UNLICENSED",
 	"main": "src/index.ts",
@@ -10,10 +10,27 @@
 			"types": "./src/index.ts",
 			"react-native": "./src/index.ts",
 			"default": "./src/index.ts"
+		},
+		"./app-auth": {
+			"types": "./src/app-auth.ts",
+			"react-native": "./src/app-auth.ts",
+			"default": "./src/app-auth.ts"
+		},
+		"./keychain": {
+			"types": "./src/keychain.ts",
+			"react-native": "./src/keychain.ts",
+			"default": "./src/keychain.ts"
+		},
+		"./testing": {
+			"types": "./src/testing/index.ts",
+			"react-native": "./src/testing/index.ts",
+			"default": "./src/testing/index.ts"
 		}
 	},
 	"files": [
 		"src/index.ts",
+		"src/app-auth.ts",
+		"src/keychain.ts",
 		"src/config",
 		"src/core",
 		"src/tokens",
@@ -21,15 +38,19 @@
 		"src/access",
 		"src/diagnostics",
 		"src/react",
+		"src/testing",
 		"skills",
 		"README.md",
 		"CHANGELOG.md"
 	],
 	"sideEffects": false,
 	"scripts": {
-		"typecheck": "tsc -p tsconfig.json --noEmit",
+		"typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.test.json",
 		"pack:check": "npm pack --dry-run"
 	},
+	"dependencies": {
+		"@chipmobilesdk/rn-core": "^0.1.0"
+	},
 	"peerDependencies": {
 		"react": ">=19",
 		"react-native": ">=0.85",

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

@@ -35,12 +35,30 @@ value.
 
 ## Public API
 
+`createAuth(config)` is the entry point: one controller, one active account, created at
+startup without loading any native module. Wrap the app in `<AuthProvider auth={auth}>`
+and read state through the hooks — never re-implement the orchestration.
+
 Runtime:
 
-- `createAppAuthClient(...)` — the OIDC client
+- `createAuth` — the controller: `getState`, `subscribe`, `restore`, `signIn(providerId)`,
+  `signOut`, `signOutGlobal`, `requestAccessToken(resourceKey)`, `getAccessTier`,
+  `canAccessPremium`, `getPlatformProvider(s)`, `getMessages`
+- Hooks: `useAuth`, `useProfile`, `useAccessTier`, `useAccessToken`, `useAuthMessages`,
+  `useSignInProvider`, `useSignInProviders`, `useAuthSelector`
+- `AuthProvider`
+- `createAppAuthClient(...)` — the OIDC client; pass `serviceConfiguration` to skip a
+  `.well-known` fetch on every call
 - `createKeychainSecureStore(...)` — token persistence; `AUTH_STORAGE_KEY`
-- `evaluateAccessTier(...)`, `failClosedTier` — feature gating
+- `evaluateAccessTier(...)`, `failClosedTier` — feature gating, denying when unknown
+- `mapClaimsToProfile`, `describeProviderIdentity` — claims to a profile, and whether an
+  address is direct, Apple's private relay, or absent
 - `AuthProvider` — React context provider
+- `AuthError`, `AuthConfigError`, `isAuthError`, `redact`, `authMessages`,
+  `resolveMessages`, `DEFAULT_MESSAGES`
+
+Testing (`@chipmobilesdk/rn-auth/testing`): `createMemorySecureStore`,
+`runSecureTokenStoreConformance`, `runOidcAuthClientConformance` — README `## Testing`.
 
 Types: `SecureTokenStore`, `AuthProviderProps`, `AuthErrorCode`, `AuthErrorAudience`,
 `AuthMessageMap`, `AuthMessageKey`
@@ -48,6 +66,24 @@ Types: `SecureTokenStore`, `AuthProviderProps`, `AuthErrorCode`, `AuthErrorAudie
 `AuthErrorAudience` distinguishes what may be shown to a user from what is diagnostic
 only — never render a diagnostic-audience message in the UI.
 
+## Three things that bite
+
+- **`signOutGlobal()` can report `{ global: 'failed' }`.** Local state is cleared either
+  way, but the tenant session may still be alive, so the next sign-in can complete with
+  no password prompt. Say so in the UI rather than claiming the user is fully signed out.
+- **`requestAccessToken(resourceKey)` answers with a status, not a throw.** Handle
+  `denied` and `unavailable` as states; only `success` carries a token. `useAccessToken`
+  starts from `idle` again when the resource key changes.
+- **iOS needs the native redirect set up** (URL scheme matching `redirectUrl`, and the
+  Apple provider configured in the tenant). A `redirect-mismatch` error is that, not a
+  code fault — see the prerequisite checklist.
+
+## A premium gate is a question
+
+Use `canAccessPremium()` and render the denial where it happened.
+`requirePremium()` is deprecated: it also moves the whole controller to
+`access-denied`, which every screen reading `state.status` then sees.
+
 ## Where the detail lives
 
 Read one section of `node_modules/@chipmobilesdk/rn-auth/README.md`:

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

@@ -3,23 +3,44 @@
  * specs/003-mobile-entra-auth/data-model.md.
  */
 
+import type { AccessTokenRequestOptions } from '../tokens/accessToken';
 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';
+/** The providers this package has copy for out of the box. */
+export type KnownProviderId = 'google' | 'apple' | 'facebook';
+
+/**
+ * A provider id. Open on purpose: routing is `domain_hint` and nothing else, so
+ * adding an IdP the tenant federates — Microsoft account, an email one-time
+ * code — is a change to an app's config, not a release of this package
+ * (AUTH-14). `KnownProviderId` keeps the three familiar ones in autocomplete.
+ */
+export type ProviderId = KnownProviderId | (string & {});
 export type DevicePlatform = 'ios' | 'android';
 
+export const DEVICE_PLATFORMS: readonly 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;
+	/**
+	 * Message key for the button label (Continue with Google / Apple). A key of
+	 * this package's catalogue, or one of the app's own for a provider it added.
+	 */
+	labelKey: AuthMessageKey | (string & {});
 	available?: boolean;
+	/**
+	 * Extra OIDC authorize parameters for this provider, merged after
+	 * `domain_hint` — `prompt`, `login_hint`, whatever the tenant's user flow
+	 * expects. `domain_hint` itself cannot be overridden here.
+	 */
+	additionalParameters?: Record<string, string>;
 }
 
 /** One configured protected resource for delegated token requests (FR-007). */
@@ -55,6 +76,11 @@ export interface AuthConfig {
 	accessTierMapping: AccessTierMapping;
 	secureStore: SecureTokenStore;
 	authClient?: OidcAuthClient;
+	/**
+	 * Copy overrides for this package's own message keys, resolved over the
+	 * English defaults and readable through `auth.getMessages()` and
+	 * `useAuthMessages()`.
+	 */
 	messages?: Partial<AuthMessageMap>;
 }
 
@@ -78,9 +104,14 @@ export type RestoreStatus = 'pending' | 'restored' | 'unavailable' | 'offline';
 /** Customer User / app-visible profile (FR-006). */
 export interface Profile {
 	tenantUserId: string;
-	displayName?: string;
-	email?: string;
+	displayName?: string | undefined;
+	email?: string | undefined;
 	provider: string;
+	/**
+	 * The id-token claims this profile was mapped from. Empty after a restore
+	 * that could not reach the provider: the stored artifact holds the identity,
+	 * not the token (AUTH-23). Read `restore` on the state to tell the two apart.
+	 */
 	claims: Record<string, unknown>;
 }
 
@@ -112,10 +143,10 @@ export interface AccessTokenResult {
 /** Single active app-visible authenticated state (FR-005/FR-022). */
 export interface AuthState {
 	status: AuthStatus;
-	profile?: Profile;
-	accessTier?: AccessTier;
+	profile?: Profile | undefined;
+	accessTier?: AccessTier | undefined;
 	restore: RestoreStatus;
-	error?: AuthError;
+	error?: AuthError | undefined;
 }
 
 /** Result of a premium-only gate check (US3). */
@@ -143,10 +174,27 @@ export interface Auth {
 	signIn(providerId: ProviderId): Promise<AuthState>;
 	signOut(): Promise<void>;
 	signOutGlobal(): Promise<GlobalSignOutResult>;
-	requestAccessToken(resourceKey: string): Promise<AccessTokenResult>;
+	/**
+	 * A delegated token for one configured resource. Answers from the in-memory
+	 * cache while the token is unexpired; `forceRefresh` skips and drops that
+	 * cache, which is what a caller whose token was just rejected needs.
+	 */
+	requestAccessToken(
+		resourceKey: string,
+		options?: AccessTokenRequestOptions,
+	): Promise<AccessTokenResult>;
 	getAccessTier(): AccessTier;
-	/** Gate a premium-only path; enters `access-denied` when unverified (FR-011). */
+	/** Whether a premium-only path is open, and the tier behind the answer. Reads nothing else and changes nothing (FR-011). */
+	canAccessPremium(): PremiumGateResult;
+	/**
+	 * @deprecated Use `canAccessPremium` and show the denial where it happened.
+	 * This also moves the whole controller to `access-denied`, which every screen
+	 * reading `status` then sees, and only a `restore` or a sign-in leaves
+	 * (AUTH-12). Kept for 0.4.x.
+	 */
 	requirePremium(): PremiumGateResult;
+	/** This package's copy: the English defaults with the app's `messages` over them. */
+	getMessages(): AuthMessageMap;
 	/** 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). */

package/src/config/validateConfig.ts

@@ -4,13 +4,21 @@
  * Covers the auth-config.md Section A–F rules.
  */
 
-import type { AuthConfig } from './types';
+import { DEVICE_PLATFORMS, type AuthConfig } from './types';
 import { AuthConfigError } from '../diagnostics/errors';
 
 function hasScheme(url: string): boolean {
 	return /^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(url);
 }
 
+/** https, or http on a development machine. */
+function isSecureAuthority(url: string): boolean {
+	if (/^https:/i.test(url)) {
+		return true;
+	}
+	return /^http:\/\/(localhost|127\.0\.0\.1|\[::1\])(:\d+)?(\/|$)/i.test(url);
+}
+
 export function validateConfig(config: AuthConfig): void {
 	// Section A — tenant/client settings
 	if (!config.authority || !config.authority.trim()) {
@@ -19,6 +27,14 @@ export function validateConfig(config: AuthConfig): void {
 	if (!hasScheme(config.authority)) {
 		throw new AuthConfigError('auth.error.configuration', '"authority" must be an absolute URL');
 	}
+	// Tokens travel over this. A tenant reachable over plaintext http is a
+	// configuration mistake, not a deployment choice — except on a dev machine.
+	if (!isSecureAuthority(config.authority)) {
+		throw new AuthConfigError(
+			'auth.error.configuration',
+			'"authority" must use https (http is accepted only for localhost)',
+		);
+	}
 	if (!config.clientId || !config.clientId.trim()) {
 		throw new AuthConfigError('auth.error.configuration', 'Missing "clientId"');
 	}
@@ -66,6 +82,21 @@ export function validateConfig(config: AuthConfig): void {
 				`Provider "${provider.id}" must declare at least one platform`,
 			);
 		}
+		for (const platform of provider.platforms) {
+			if (!DEVICE_PLATFORMS.includes(platform)) {
+				// A typo here hides the provider on every device rather than failing.
+				throw new AuthConfigError(
+					'auth.error.configuration',
+					`Provider "${provider.id}" declares unknown platform "${String(platform)}"`,
+				);
+			}
+		}
+		if (typeof provider.labelKey !== 'string' || !provider.labelKey.trim()) {
+			throw new AuthConfigError(
+				'auth.error.configuration',
+				`Provider "${provider.id}" is missing a labelKey`,
+			);
+		}
 	}
 
 	// Section D — resources