@chipmobilesdk/rn-auth 0.4.0 → 0.6.0

package/lib/typescript/module/react/hooks.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Public hooks (LIB-002). Each reads the controller's state through
+ * `useSyncExternalStore` (rn-core's `useExternalStore`), selecting only what it
+ * returns, so `useProfile` does not re-render when only the status changes.
+ */
+import type { AccessTier, AccessTokenResult, AuthState, GlobalSignOutResult, PremiumGateResult, Profile, ProviderConfig, ProviderId } from '../config/types.js';
+import type { AccessTokenRequestOptions } from '../tokens/accessToken.js';
+import type { AuthMessageMap } from '../diagnostics/messageKeys.js';
+export interface UseAuthResult {
+    state: AuthState;
+    signIn(providerId: ProviderId): Promise<AuthState>;
+    signOut(): Promise<void>;
+    signOutGlobal(): Promise<GlobalSignOutResult>;
+    restore(): Promise<AuthState>;
+    /** Whether a premium-only path is open. Changes nothing: show the denial where it happened. */
+    canAccessPremium(): PremiumGateResult;
+    /** @deprecated Use `canAccessPremium`; this moves the whole controller to `access-denied` (AUTH-12). */
+    requirePremium(): PremiumGateResult;
+}
+/**
+ * Any slice of the auth state; the component re-renders only when the slice
+ * changes by `isEqual` (default `Object.is`).
+ */
+export declare function useAuthSelector<Selected>(select: (state: AuthState) => Selected, isEqual?: (a: Selected, b: Selected) => boolean): Selected;
+export declare function useAuth(): UseAuthResult;
+/** This package's copy, with the app's `messages` overrides applied. */
+export declare function useAuthMessages(): AuthMessageMap;
+export declare function useProfile(): Profile | undefined;
+export declare function useAccessTier(): AccessTier;
+/** The first provider to present on the current platform (UX-004), or undefined. */
+export declare function useSignInProvider(): ProviderConfig | undefined;
+/** All available providers for the current platform, in configuration order (FR-003/FR-004). */
+export declare function useSignInProviders(): ProviderConfig[];
+export type UseAccessTokenStatus = 'idle' | 'loading' | 'success' | 'denied' | 'unavailable' | 'error';
+export interface UseAccessTokenResult {
+    status: UseAccessTokenStatus;
+    token?: string | undefined;
+    /** `{ forceRefresh: true }` after a server refused the token this returned. */
+    request(options?: AccessTokenRequestOptions): Promise<AccessTokenResult>;
+}
+export declare function useAccessToken(resourceKey: string): UseAccessTokenResult;
+//# sourceMappingURL=hooks.d.ts.map

package/lib/typescript/module/react/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../../../src/react/hooks.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,KAAK,EACX,UAAU,EACV,iBAAiB,EACjB,SAAS,EACT,mBAAmB,EACnB,iBAAiB,EACjB,OAAO,EACP,cAAc,EACd,UAAU,EACV,MAAM,oBAAiB,CAAC;AAEzB,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,0BAAuB,CAAC;AACvE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+BAA4B,CAAC;AAEjE,MAAM,WAAW,aAAa;IAC7B,KAAK,EAAE,SAAS,CAAC;IACjB,MAAM,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IACnD,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,aAAa,IAAI,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAC9C,OAAO,IAAI,OAAO,CAAC,SAAS,CAAC,CAAC;IAC9B,+FAA+F;IAC/F,gBAAgB,IAAI,iBAAiB,CAAC;IACtC,wGAAwG;IACxG,cAAc,IAAI,iBAAiB,CAAC;CACpC;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EACvC,MAAM,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,QAAQ,EACtC,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,KAAK,OAAO,GAC7C,QAAQ,CAGV;AAMD,wBAAgB,OAAO,IAAI,aAAa,CAYvC;AAED,wEAAwE;AACxE,wBAAgB,eAAe,IAAI,cAAc,CAEhD;AAED,wBAAgB,UAAU,IAAI,OAAO,GAAG,SAAS,CAEhD;AAED,wBAAgB,aAAa,IAAI,UAAU,CAE1C;AAED,oFAAoF;AACpF,wBAAgB,iBAAiB,IAAI,cAAc,GAAG,SAAS,CAG9D;AAED,gGAAgG;AAChG,wBAAgB,kBAAkB,IAAI,cAAc,EAAE,CAGrD;AAED,MAAM,MAAM,oBAAoB,GAC/B,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,GAAG,aAAa,GAAG,OAAO,CAAC;AAErE,MAAM,WAAW,oBAAoB;IACpC,MAAM,EAAE,oBAAoB,CAAC;IAC7B,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,+EAA+E;IAC/E,OAAO,CAAC,OAAO,CAAC,EAAE,yBAAyB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;CACzE;AAED,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,oBAAoB,CAyCxE"}

package/lib/typescript/module/testing/conformance.d.ts

@@ -0,0 +1,32 @@
+/**
+ * What any `SecureTokenStore` and `OidcAuthClient` must do (IOS-12, AUTH-13).
+ *
+ * The same checks run against the in-memory doubles and against the keychain and
+ * app-auth adapters (native modules mocked in Jest, or for real from a demo
+ * screen on a device), so a test that drives a double proves something about the
+ * device path. Each check builds its own subject through a harness.
+ */
+import { type Check, type ConformanceReport } from '@chipmobilesdk/rn-core/testing';
+import type { OidcAuthClient } from '../oidc/authClient.js';
+import type { SecureTokenStore } from '../tokens/secureStore.js';
+export interface SecureStoreHarness {
+    /** An empty store. */
+    create(): SecureTokenStore;
+}
+export interface OidcSubject {
+    readonly client: OidcAuthClient;
+    /** The identity provider answers sign-in and refresh with tokens for these claims. */
+    issues(claims: Record<string, unknown>): void;
+    /** The user closes the sign-in sheet. */
+    userCancels(): void;
+    /** The provider no longer accepts the refresh token. */
+    rejectsRefresh(): void;
+}
+export interface OidcHarness {
+    create(): OidcSubject;
+}
+export declare const secureTokenStoreChecks: readonly Check<SecureStoreHarness>[];
+export declare const oidcAuthClientChecks: readonly Check<OidcHarness>[];
+export declare function runSecureTokenStoreConformance(harness: SecureStoreHarness): Promise<ConformanceReport>;
+export declare function runOidcAuthClientConformance(harness: OidcHarness): Promise<ConformanceReport>;
+//# sourceMappingURL=conformance.d.ts.map

package/lib/typescript/module/testing/conformance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conformance.d.ts","sourceRoot":"","sources":["../../../../src/testing/conformance.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAGN,KAAK,KAAK,EACV,KAAK,iBAAiB,EACtB,MAAM,gCAAgC,CAAC;AAExC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAoB,CAAC;AACzD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAAuB,CAAC;AAE9D,MAAM,WAAW,kBAAkB;IAClC,sBAAsB;IACtB,MAAM,IAAI,gBAAgB,CAAC;CAC3B;AAED,MAAM,WAAW,WAAW;IAC3B,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,sFAAsF;IACtF,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC9C,yCAAyC;IACzC,WAAW,IAAI,IAAI,CAAC;IACpB,wDAAwD;IACxD,cAAc,IAAI,IAAI,CAAC;CACvB;AAED,MAAM,WAAW,WAAW;IAC3B,MAAM,IAAI,WAAW,CAAC;CACtB;AAKD,eAAO,MAAM,sBAAsB,EAAE,SAAS,KAAK,CAAC,kBAAkB,CAAC,EA+CtE,CAAC;AAaF,eAAO,MAAM,oBAAoB,EAAE,SAAS,KAAK,CAAC,WAAW,CAAC,EAkE7D,CAAC;AAEF,wBAAgB,8BAA8B,CAC7C,OAAO,EAAE,kBAAkB,GACzB,OAAO,CAAC,iBAAiB,CAAC,CAE5B;AAED,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAE7F"}

package/lib/typescript/module/testing/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `@chipmobilesdk/rn-auth/testing`: test doubles and the port conformance suites.
+ *
+ * A separate entrypoint so neither can reach a production bundle.
+ */
+import type { SecureTokenStore } from '../tokens/secureStore.js';
+/** A `SecureTokenStore` held in memory, for tests and for the conformance suite. */
+export declare function createMemorySecureStore(seed?: Record<string, string>): SecureTokenStore;
+export { oidcAuthClientChecks, runOidcAuthClientConformance, runSecureTokenStoreConformance, secureTokenStoreChecks, } from './conformance.js';
+export type { OidcHarness, OidcSubject, SecureStoreHarness } from './conformance.js';
+//# sourceMappingURL=index.d.ts.map

package/lib/typescript/module/testing/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/testing/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAAuB,CAAC;AAE9D,oFAAoF;AACpF,wBAAgB,uBAAuB,CAAC,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GAAG,gBAAgB,CAa3F;AAED,OAAO,EACN,oBAAoB,EACpB,4BAA4B,EAC5B,8BAA8B,EAC9B,sBAAsB,GACtB,MAAM,kBAAe,CAAC;AACvB,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,kBAAe,CAAC"}

package/lib/typescript/module/tokens/accessToken.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Per-resource delegated access-token acquisition with an in-memory cache and
+ * silent refresh (FR-007, PERF-003, R4). Access tokens are never persisted to
+ * disk (FR-021) — only kept in memory keyed by resource until expiry.
+ */
+import type { AccessTokenResult, ResourceConfig } from '../config/types.js';
+import type { OidcAuthClient } from '../oidc/authClient.js';
+export interface AccessTokenManagerDeps {
+    authority: string;
+    clientId: string;
+    redirectUrl: string;
+    resources: ResourceConfig[];
+    authClient: OidcAuthClient;
+    getRefreshToken: () => string | null;
+    /**
+     * The session generation, bumped by every sign-in, sign-out and restore. A
+     * refresh that started under one generation and finished under another
+     * belongs to a session that no longer exists, so its result is discarded.
+     */
+    sessionEpoch: () => number;
+    /**
+     * The provider rotated the refresh token. Resolves once the new token is
+     * live, and persisted where it can be: the old one may already be dead, so a
+     * restart must not come back with it.
+     */
+    onRefreshTokenRotated: (token: string, epoch: number) => Promise<void>;
+}
+export interface AccessTokenRequestOptions {
+    /**
+     * Ignore the cached token and ask the provider for a new one.
+     *
+     * For the caller that just had one rejected: a token the server refused is
+     * still unexpired by this device's clock, so asking again without this
+     * returns the same token and the retry is the same request (AI-01).
+     */
+    forceRefresh?: boolean;
+}
+export interface AccessTokenManager {
+    request(resourceKey: string, options?: AccessTokenRequestOptions): Promise<AccessTokenResult>;
+    /** Whether `request` would answer from the cache, without touching the network. */
+    hasFreshToken(resourceKey: string): boolean;
+    clear(): void;
+}
+export declare function createAccessTokenManager(deps: AccessTokenManagerDeps): AccessTokenManager;
+//# sourceMappingURL=accessToken.d.ts.map

package/lib/typescript/module/tokens/accessToken.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"accessToken.d.ts","sourceRoot":"","sources":["../../../../src/tokens/accessToken.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,oBAAiB,CAAC;AACzE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAoB,CAAC;AAUzD,MAAM,WAAW,sBAAsB;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,cAAc,EAAE,CAAC;IAC5B,UAAU,EAAE,cAAc,CAAC;IAC3B,eAAe,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;IACrC;;;;OAIG;IACH,YAAY,EAAE,MAAM,MAAM,CAAC;IAC3B;;;;OAIG;IACH,qBAAqB,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACvE;AAED,MAAM,WAAW,yBAAyB;IACzC;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,kBAAkB;IAClC,OAAO,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,yBAAyB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAC9F,mFAAmF;IACnF,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC;IAC5C,KAAK,IAAI,IAAI,CAAC;CACd;AAOD,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,sBAAsB,GAAG,kBAAkB,CA4GzF"}

package/lib/typescript/module/tokens/secureStore.d.ts

@@ -0,0 +1,26 @@
+/**
+ * SecureTokenStore port + default react-native-keychain adapter (FR-021, R2).
+ *
+ * Refresh tokens and the session-restore artifact persist ONLY through this
+ * port, backed by platform secure storage (iOS Keychain / Android Keystore).
+ * Access tokens are never written here — they stay in memory (see accessToken).
+ * The default adapter loads the native module on its first read or write, so
+ * creating it, and unit tests that inject a fake, load no native code.
+ */
+/** Single key under which the persisted session artifact is stored. */
+export declare const AUTH_STORAGE_KEY = "@chipmobilesdk/rn-auth/session";
+export interface SecureTokenStore {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+}
+export interface KeychainSecureStoreOptions {
+    /** Optional Keychain access-control accessibility constant. */
+    accessible?: string;
+}
+/**
+ * Default secure store backed by react-native-keychain. Each logical key maps to
+ * a Keychain "service" so multiple keys can coexist. Validated on device.
+ */
+export declare function createKeychainSecureStore(options?: KeychainSecureStoreOptions): SecureTokenStore;
+//# sourceMappingURL=secureStore.d.ts.map

package/lib/typescript/module/tokens/secureStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secureStore.d.ts","sourceRoot":"","sources":["../../../../src/tokens/secureStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,uEAAuE;AACvE,eAAO,MAAM,gBAAgB,mCAAmC,CAAC;AAEjE,MAAM,WAAW,gBAAgB;IAChC,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC7C,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC;AAED,MAAM,WAAW,0BAA0B;IAC1C,+DAA+D;IAC/D,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CACxC,OAAO,GAAE,0BAA+B,GACtC,gBAAgB,CAoBlB"}

package/package.json

@@ -1,30 +1,56 @@
 {
 	"name": "@chipmobilesdk/rn-auth",
-	"version": "0.4.0",
+	"version": "0.6.0",
 	"private": false,
 	"license": "UNLICENSED",
-	"main": "src/index.ts",
-	"types": "src/index.ts",
+	"source": "./src/index.ts",
+	"main": "./lib/commonjs/index.js",
+	"module": "./lib/module/index.js",
+	"types": "./lib/typescript/commonjs/index.d.ts",
 	"exports": {
 		".": {
-			"types": "./src/index.ts",
-			"react-native": "./src/index.ts",
-			"default": "./src/index.ts"
+			"chipmobilesdk-source": "./src/index.ts",
+			"import": {
+				"types": "./lib/typescript/module/index.d.ts",
+				"default": "./lib/module/index.js"
+			},
+			"require": {
+				"types": "./lib/typescript/commonjs/index.d.ts",
+				"default": "./lib/commonjs/index.js"
+			}
 		},
 		"./app-auth": {
-			"types": "./src/app-auth.ts",
-			"react-native": "./src/app-auth.ts",
-			"default": "./src/app-auth.ts"
+			"chipmobilesdk-source": "./src/app-auth.ts",
+			"import": {
+				"types": "./lib/typescript/module/app-auth.d.ts",
+				"default": "./lib/module/app-auth.js"
+			},
+			"require": {
+				"types": "./lib/typescript/commonjs/app-auth.d.ts",
+				"default": "./lib/commonjs/app-auth.js"
+			}
 		},
 		"./keychain": {
-			"types": "./src/keychain.ts",
-			"react-native": "./src/keychain.ts",
-			"default": "./src/keychain.ts"
+			"chipmobilesdk-source": "./src/keychain.ts",
+			"import": {
+				"types": "./lib/typescript/module/keychain.d.ts",
+				"default": "./lib/module/keychain.js"
+			},
+			"require": {
+				"types": "./lib/typescript/commonjs/keychain.d.ts",
+				"default": "./lib/commonjs/keychain.js"
+			}
 		},
 		"./testing": {
-			"types": "./src/testing/index.ts",
-			"react-native": "./src/testing/index.ts",
-			"default": "./src/testing/index.ts"
+			"chipmobilesdk-source": "./src/testing/index.ts",
+			"import": {
+				"types": "./lib/typescript/module/testing/index.d.ts",
+				"default": "./lib/module/testing/index.js"
+			},
+			"require": {
+				"types": "./lib/typescript/commonjs/testing/index.d.ts",
+				"default": "./lib/commonjs/testing/index.js"
+			}
 		}
 	},
 	"files": [
@@ -41,21 +67,23 @@
 		"src/testing",
 		"skills",
 		"README.md",
-		"CHANGELOG.md"
+		"CHANGELOG.md",
+		"lib"
 	],
 	"sideEffects": false,
 	"scripts": {
+		"build": "bob build",
 		"typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.test.json",
-		"pack:check": "npm pack --dry-run"
+		"pack:check": "npm pack --dry-run",
+		"prepack": "npm run build"
 	},
 	"dependencies": {
-		"@chipmobilesdk/rn-core": "^0.1.0"
+		"@chipmobilesdk/rn-core": "^0.2.0"
 	},
 	"peerDependencies": {
 		"react": ">=19",
-		"react-native": ">=0.85",
-		"react-native-app-auth": ">=8",
-		"react-native-keychain": ">=10"
+		"react-native-app-auth": "^8.0.0",
+		"react-native-keychain": "^10.0.0"
 	},
 	"peerDependenciesMeta": {
 		"react-native-app-auth": {
@@ -68,5 +96,24 @@
 	"publishConfig": {
 		"access": "public",
 		"registry": "https://registry.npmjs.org/"
+	},
+	"react-native-builder-bob": {
+		"source": "src",
+		"output": "lib",
+		"targets": [
+			[
+				"commonjs",
+				{
+					"esm": true
+				}
+			],
+			[
+				"module",
+				{
+					"esm": true
+				}
+			],
+			"typescript"
+		]
 	}
 }

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

@@ -35,12 +35,27 @@ 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`.
@@ -51,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/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>;
 }
 
@@ -81,6 +107,11 @@ export interface Profile {
 	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>;
 }
 
@@ -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

package/src/core/authMachine.ts

@@ -16,6 +16,8 @@ import {
 	shallowEqual,
 } from '@chipmobilesdk/rn-core';
 
+import type { AuthMessageMap } from '../diagnostics/messageKeys';
+import { resolveMessages } from '../diagnostics/messageKeys';
 import type {
 	Auth,
 	AuthConfig,
@@ -37,7 +39,7 @@ import {
 } from '../oidc/socialRouting';
 import { mapClaimsToProfile } from './profile';
 import { evaluateAccessTier, failClosedTier } from '../access/accessTier';
-import { restoreSession, type PersistedSession } from './session';
+import { restoreSession, sameSession, storedProfileFrom, type PersistedSession } from './session';
 import { AUTH_STORAGE_KEY } from '../tokens/secureStore';
 import { createAccessTokenManager } from '../tokens/accessToken';
 import { AuthError, toAuthError, type AuthErrorCode } from '../diagnostics/errors';
@@ -62,6 +64,8 @@ export function createAuthMachine(config: AuthConfig, options: CreateAuthOptions
 	const secureStore = config.secureStore;
 	const authClient = config.authClient ?? createAppAuthClient();
 	const resources = config.resources ?? [];
+	// Declared since 0.1.0 and read by nothing until now (AUTH-15).
+	const messages = resolveMessages(config.messages);
 
 	let state: AuthState = Object.freeze({ status: 'loading', restore: 'pending' });
 	let refreshToken: string | null = null;
@@ -84,12 +88,29 @@ export function createAuthMachine(config: AuthConfig, options: CreateAuthOptions
 		return next;
 	};
 
-	const writeSession = (session: PersistedSession, epoch: number): Promise<void> =>
+	/** The artifact as last written or read, so an identical write is skipped. */
+	let storedSession: PersistedSession | null = null;
+
+	const writeSession = (
+		session: { refreshToken: string; profile: Profile; idToken?: string | undefined },
+		epoch: number,
+	): Promise<void> =>
 		enqueueStoreOp(async () => {
 			if (epoch !== sessionEpoch) {
 				return; // The session this belonged to has already ended.
 			}
-			await secureStore.setItem(AUTH_STORAGE_KEY, JSON.stringify(session));
+			const artifact: PersistedSession = {
+				refreshToken: session.refreshToken,
+				profile: storedProfileFrom(session.profile),
+				idToken: session.idToken,
+			};
+			// A restore that rotated nothing used to write the Keychain again on
+			// every launch, on the startup path (AUTH-23).
+			if (storedSession && sameSession(storedSession, artifact)) {
+				return;
+			}
+			await secureStore.setItem(AUTH_STORAGE_KEY, JSON.stringify(artifact));
+			storedSession = artifact;
 		});
 
 	const tokenManager = createAccessTokenManager({
@@ -155,6 +176,7 @@ export function createAuthMachine(config: AuthConfig, options: CreateAuthOptions
 		sessionEpoch += 1;
 		refreshToken = null;
 		idToken = null;
+		storedSession = null;
 		tokenManager.clear();
 		await enqueueStoreOp(() => secureStore.removeItem(AUTH_STORAGE_KEY));
 	}
@@ -193,6 +215,8 @@ export function createAuthMachine(config: AuthConfig, options: CreateAuthOptions
 				return getState();
 			}
 
+			storedSession = result.persisted ?? null;
+
 			if (result.outcome === 'restored' && result.profile && result.refreshToken) {
 				refreshToken = result.refreshToken;
 				idToken = result.idToken ?? null;
@@ -334,16 +358,17 @@ export function createAuthMachine(config: AuthConfig, options: CreateAuthOptions
 			return result;
 		},
 
-		async requestAccessToken(resourceKey) {
+		async requestAccessToken(resourceKey, tokenOptions) {
 			const epoch = sessionEpoch;
 			// Only a real network refresh is a `token-refreshing` phase; a cache hit
 			// would otherwise flash every subscriber twice for nothing.
 			const refreshing =
-				state.status === 'authenticated' && !tokenManager.hasFreshToken(resourceKey);
+				state.status === 'authenticated' &&
+				(tokenOptions?.forceRefresh === true || !tokenManager.hasFreshToken(resourceKey));
 			if (refreshing) {
 				setState({ status: 'token-refreshing' });
 			}
-			const result = await tokenManager.request(resourceKey);
+			const result = await tokenManager.request(resourceKey, tokenOptions);
 			// Restored only if nothing else moved the session meanwhile: a sign-out
 			// during the refresh used to be overwritten back to `authenticated`.
 			if (refreshing && epoch === sessionEpoch && state.status === 'token-refreshing') {
@@ -356,6 +381,11 @@ export function createAuthMachine(config: AuthConfig, options: CreateAuthOptions
 			return state.accessTier ?? failClosedTier();
 		},
 
+		canAccessPremium(): PremiumGateResult {
+			const tier = state.accessTier ?? failClosedTier();
+			return { allowed: tier.tier === 'premium' && tier.verification === 'verified', tier };
+		},
+
 		requirePremium(): PremiumGateResult {
 			const tier = state.accessTier ?? failClosedTier();
 			const allowed = tier.tier === 'premium' && tier.verification === 'verified';
@@ -365,6 +395,10 @@ export function createAuthMachine(config: AuthConfig, options: CreateAuthOptions
 			return { allowed, tier };
 		},
 
+		getMessages(): AuthMessageMap {
+			return messages;
+		},
+
 		getPlatformProvider() {
 			return defaultProviderForPlatform(config, platform);
 		},