@chipmobilesdk/rn-auth 0.4.0 → 0.6.0

package/src/core/profile.ts

@@ -41,7 +41,12 @@ export function mapClaimsToProfile(
 	};
 }
 
-/** Describe the external provider identity behind the profile (FR-004 edge cases). */
+/**
+ * Describe the external provider identity behind the profile (FR-004 edge
+ * cases). `emailBehavior` is what a screen needs to explain an address the user
+ * did not choose: Apple's private relay forwards mail and is not the address
+ * they type anywhere else.
+ */
 export function describeProviderIdentity(
 	claims: Record<string, unknown>,
 	providerId?: ProviderId,

package/src/core/session.ts

@@ -22,13 +22,50 @@ import { mapClaimsToProfile } from './profile';
 import { evaluateAccessTier, failClosedTier } from '../access/accessTier';
 import { isAuthError } from '../diagnostics/errors';
 
+/**
+ * The identity in the stored artifact: who, not what the token said.
+ *
+ * The whole claim set used to be written to the Keychain on every launch — all
+ * of it, groups included — for a value nothing reads back: the access tier is
+ * recomputed from fresh claims, and a restore that cannot reach the provider
+ * fails closed anyway (AUTH-23).
+ */
+export type StoredProfile = Omit<Profile, 'claims'>;
+
 export interface PersistedSession {
 	refreshToken: string;
-	profile: Profile;
+	profile: StoredProfile;
 	/** The id token hint for end-session (AUTH-04). Absent in artifacts written before 0.2.2. */
 	idToken?: string | undefined;
 }
 
+/** The artifact's identity as a profile. Artifacts written before 0.4.0 carry claims; they are kept. */
+export function profileFromStored(stored: StoredProfile | Profile): Profile {
+	return { ...stored, claims: 'claims' in stored ? (stored.claims ?? {}) : {} };
+}
+
+/** What goes to the store: everything but the claims. */
+export function storedProfileFrom(profile: Profile): StoredProfile {
+	return {
+		tenantUserId: profile.tenantUserId,
+		displayName: profile.displayName,
+		email: profile.email,
+		provider: profile.provider,
+	};
+}
+
+/** True when the artifact would be byte-identical, so the write can be skipped. */
+export function sameSession(a: PersistedSession, b: PersistedSession): boolean {
+	return (
+		a.refreshToken === b.refreshToken &&
+		a.idToken === b.idToken &&
+		a.profile.tenantUserId === b.profile.tenantUserId &&
+		a.profile.displayName === b.profile.displayName &&
+		a.profile.email === b.profile.email &&
+		a.profile.provider === b.profile.provider
+	);
+}
+
 export interface RestoreDeps {
 	secureStore: SecureTokenStore;
 	authority: string;
@@ -42,6 +79,8 @@ export interface RestoreDeps {
 export interface RestoreResult {
 	outcome: RestoreStatus;
 	profile?: Profile;
+	/** The artifact this restore read, so a rewrite that changes nothing can be skipped. */
+	persisted?: PersistedSession;
 	accessTier?: AccessTier;
 	refreshToken?: string;
 	idToken?: string | undefined;
@@ -82,7 +121,13 @@ export async function restoreSession(deps: RestoreDeps): Promise<RestoreResult>
 		const hasClaims = Object.keys(tokens.claims).length > 0;
 		return {
 			outcome: 'restored',
-			profile: hasClaims ? mapClaimsToProfile(tokens.claims) : persisted.profile,
+			persisted,
+			// The provider id came from the sign-in and is not in the claims: a
+			// refresh answered `idp: 'google.com'`, so a restored profile used to
+			// report a different provider than the same session did before (AUTH-10).
+			profile: hasClaims
+				? mapClaimsToProfile(tokens.claims, persisted.profile.provider)
+				: profileFromStored(persisted.profile),
 			accessTier: hasClaims ? evaluateAccessTier(tokens.claims, deps.mapping) : failClosedTier(),
 			refreshToken: tokens.refreshToken || persisted.refreshToken,
 			idToken: tokens.idToken || persisted.idToken,
@@ -96,7 +141,8 @@ export async function restoreSession(deps: RestoreDeps): Promise<RestoreResult>
 		// read-only and fail closed on entitlement; the next restore tries again.
 		return {
 			outcome: 'offline',
-			profile: persisted.profile,
+			persisted,
+			profile: profileFromStored(persisted.profile),
 			accessTier: failClosedTier(),
 			refreshToken: persisted.refreshToken,
 			idToken: persisted.idToken,

package/src/diagnostics/errors.ts

@@ -7,6 +7,8 @@
 
 import { COMMON_PATTERNS, SdkError, redactPatterns } from '@chipmobilesdk/rn-core';
 
+import type { AuthMessageKey } from './messageKeys';
+
 export type AuthErrorCode =
 	| 'configuration-error'
 	| 'provider-cancelled'
@@ -14,14 +16,14 @@ export type AuthErrorCode =
 	| 'token-acquisition-failed'
 	| 'session-expired'
 	| 'consent-denied'
-	| 'entitlement-unverified'
 	| 'network-unavailable';
 
 export type AuthErrorAudience = 'user' | 'developer';
 
 export interface AuthErrorArgs {
 	code: AuthErrorCode;
-	messageKey: string;
+	/** A key of this package's catalogue: the copy an app shows for this error. */
+	messageKey: AuthMessageKey;
 	audience?: AuthErrorAudience;
 	detail?: string | undefined;
 }
@@ -52,7 +54,7 @@ const RETRYABLE: ReadonlySet<AuthErrorCode> = new Set<AuthErrorCode>(['network-u
 /** The package's error; an `SdkError` (`@chipmobilesdk/rn-core`) with `pkg: 'rn-auth'`. */
 export class AuthError extends SdkError<AuthErrorCode> {
 	readonly audience: AuthErrorAudience;
-	readonly messageKey: string;
+	readonly messageKey: AuthMessageKey;
 	readonly detail?: string | undefined;
 
 	constructor(args: AuthErrorArgs) {
@@ -70,7 +72,7 @@ export class AuthError extends SdkError<AuthErrorCode> {
 }
 
 export class AuthConfigError extends AuthError {
-	constructor(messageKey: string, detail?: string) {
+	constructor(messageKey: AuthMessageKey, detail?: string) {
 		super({ code: 'configuration-error', messageKey, audience: 'developer', detail });
 		this.name = 'AuthConfigError';
 	}
@@ -84,7 +86,7 @@ export function isAuthError(value: unknown): value is AuthError {
 export function toAuthError(
 	value: unknown,
 	fallbackCode: AuthErrorCode = 'token-acquisition-failed',
-	fallbackMessageKey = 'auth.error.token',
+	fallbackMessageKey: AuthMessageKey = 'auth.error.token',
 ): AuthError {
 	if (isAuthError(value)) {
 		return value;

package/src/index.ts

@@ -25,6 +25,7 @@ export type {
 	ProviderIdentity,
 	ProviderConfig,
 	ProviderId,
+	KnownProviderId,
 	DevicePlatform,
 	ResourceConfig,
 	ClaimMatcher,
@@ -37,11 +38,16 @@ export type {
 } from './config/types';
 
 // Ports + default adapters
+export { describeProviderIdentity, mapClaimsToProfile } from './core/profile';
+
+export type { AccessTokenRequestOptions } from './tokens/accessToken';
 export type { SecureTokenStore } from './tokens/secureStore';
 export { createKeychainSecureStore, AUTH_STORAGE_KEY } from './tokens/secureStore';
 export type {
 	OidcAuthClient,
 	OidcTokens,
+	OidcServiceConfiguration,
+	AppAuthClientOptions,
 	AuthorizeParams,
 	RefreshParams,
 	EndSessionParams,
@@ -63,6 +69,7 @@ export { useAuthSelector } from './react/hooks';
 export type { AuthProviderProps } from './react/AuthProvider';
 export {
 	useAuth,
+	useAuthMessages,
 	useProfile,
 	useAccessTier,
 	useAccessToken,

package/src/oidc/authClient.ts

@@ -116,9 +116,24 @@ function base64UrlDecode(input: string): string {
 	}
 }
 
+/** The endpoints discovery would have returned, when an app already knows them. */
+export interface OidcServiceConfiguration {
+	authorizationEndpoint: string;
+	tokenEndpoint: string;
+	endSessionEndpoint?: string;
+	revocationEndpoint?: string;
+	registrationEndpoint?: string;
+}
+
 export interface AppAuthClientOptions {
 	/** When true, the OIDC discovery document is fetched from `${authority}`. */
 	useDiscovery?: boolean;
+	/**
+	 * Static endpoints, used instead of discovery. Every authorize, refresh and
+	 * sign-out otherwise costs the native module one `.well-known` round-trip,
+	 * including the refresh on the startup path (AUTH-08).
+	 */
+	serviceConfiguration?: OidcServiceConfiguration;
 }
 
 interface AppAuthModule {
@@ -165,7 +180,9 @@ const AppAuth: AppAuthModule = {
  * client). Validated on device (R8).
  */
 export function createAppAuthClient(options: AppAuthClientOptions = {}): OidcAuthClient {
-	const useDiscovery = options.useDiscovery ?? true;
+	const serviceConfiguration = options.serviceConfiguration;
+	// Discovery is pointless once the endpoints are given, whatever was asked for.
+	const useDiscovery = serviceConfiguration ? false : (options.useDiscovery ?? true);
 
 	const baseConfig = (
 		authority: string,
@@ -174,6 +191,7 @@ export function createAppAuthClient(options: AppAuthClientOptions = {}): OidcAut
 		scopes: string[],
 	) => ({
 		issuer: useDiscovery ? authority : undefined,
+		...(serviceConfiguration ? { serviceConfiguration } : {}),
 		clientId,
 		redirectUrl,
 		scopes,

package/src/oidc/classifyError.ts

@@ -12,10 +12,11 @@
  */
 
 import { AuthError, type AuthErrorCode } from '../diagnostics/errors';
+import type { AuthMessageKey } from '../diagnostics/messageKeys';
 
 export interface ClassificationRule {
 	readonly code: AuthErrorCode;
-	readonly messageKey: string;
+	readonly messageKey: AuthMessageKey;
 	/** Matched against the native error's `code` and `message`, case-insensitively. */
 	readonly pattern: RegExp;
 }

package/src/oidc/socialRouting.ts

@@ -37,7 +37,9 @@ export function resolveProvider(
 
 /** Build the OIDC additional parameters that route to the chosen IdP. */
 export function buildAdditionalParameters(provider: ProviderConfig): Record<string, string> {
-	return { domain_hint: provider.domainHint };
+	// The routing hint last: a provider's own parameters cannot redirect the flow
+	// to a different IdP than the one the user tapped.
+	return { ...provider.additionalParameters, domain_hint: provider.domainHint };
 }
 
 /**

package/src/react/hooks.ts

@@ -5,7 +5,7 @@
  */
 
 import { useExternalStore } from '@chipmobilesdk/rn-core/react';
-import { useCallback, useState } from 'react';
+import { useCallback, useEffect, useRef, useState } from 'react';
 import { useAuthInstance } from './AuthProvider';
 import type {
 	AccessTier,
@@ -18,6 +18,8 @@ import type {
 	ProviderId,
 } from '../config/types';
 import { failClosedTier } from '../access/accessTier';
+import type { AccessTokenRequestOptions } from '../tokens/accessToken';
+import type { AuthMessageMap } from '../diagnostics/messageKeys';
 
 export interface UseAuthResult {
 	state: AuthState;
@@ -25,6 +27,9 @@ export interface UseAuthResult {
 	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;
 }
 
@@ -53,10 +58,16 @@ export function useAuth(): UseAuthResult {
 		signOut: useCallback(() => auth.signOut(), [auth]),
 		signOutGlobal: useCallback(() => auth.signOutGlobal(), [auth]),
 		restore: useCallback(() => auth.restore(), [auth]),
+		canAccessPremium: useCallback(() => auth.canAccessPremium(), [auth]),
 		requirePremium: useCallback(() => auth.requirePremium(), [auth]),
 	};
 }
 
+/** This package's copy, with the app's `messages` overrides applied. */
+export function useAuthMessages(): AuthMessageMap {
+	return useAuthInstance().getMessages();
+}
+
 export function useProfile(): Profile | undefined {
 	return useAuthSelector(selectProfile);
 }
@@ -83,21 +94,49 @@ export type UseAccessTokenStatus =
 export interface UseAccessTokenResult {
 	status: UseAccessTokenStatus;
 	token?: string | undefined;
-	request(): Promise<AccessTokenResult>;
+	/** `{ forceRefresh: true }` after a server refused the token this returned. */
+	request(options?: AccessTokenRequestOptions): Promise<AccessTokenResult>;
 }
 
 export function useAccessToken(resourceKey: string): UseAccessTokenResult {
 	const auth = useAuthInstance();
-	const [status, setStatus] = useState<UseAccessTokenStatus>('idle');
-	const [token, setToken] = useState<string | undefined>(undefined);
-
-	const request = useCallback(async () => {
-		setStatus('loading');
-		const result = await auth.requestAccessToken(resourceKey);
-		setStatus(result.status);
-		setToken(result.token);
-		return result;
-	}, [auth, resourceKey]);
-
-	return { status, token, request };
+	const [state, setState] = useState<{
+		status: UseAccessTokenStatus;
+		token?: string | undefined;
+		resourceKey: string;
+	}>({ status: 'idle', resourceKey });
+
+	// Which request may still write. A result for a resource the component has
+	// moved on from, or for an unmounted one, is dropped rather than applied
+	// (AUTH-17, standard VII).
+	const live = useRef(0);
+	useEffect(
+		() => () => {
+			live.current += 1;
+		},
+		[],
+	);
+
+	const request = useCallback(
+		async (options?: AccessTokenRequestOptions) => {
+			live.current += 1;
+			const id = live.current;
+			setState({ status: 'loading', resourceKey });
+			const result = await auth.requestAccessToken(resourceKey, options);
+			if (id === live.current) {
+				setState({ status: result.status, token: result.token, resourceKey });
+			}
+			return result;
+		},
+		[auth, resourceKey],
+	);
+
+	// A new resource starts from `idle`, not from the previous resource's token.
+	if (state.resourceKey !== resourceKey) {
+		live.current += 1;
+		setState({ status: 'idle', resourceKey });
+		return { status: 'idle', token: undefined, request };
+	}
+
+	return { status: state.status, token: state.token, request };
 }

package/src/tokens/accessToken.ts

@@ -13,7 +13,6 @@ const EXPIRY_SKEW_MS = 60_000;
 interface CachedToken {
 	token: string;
 	expiresAt: number;
-	scopes: string[];
 }
 
 export interface AccessTokenManagerDeps {
@@ -37,8 +36,19 @@ export interface AccessTokenManagerDeps {
 	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): Promise<AccessTokenResult>;
+	request(resourceKey: string, options?: AccessTokenRequestOptions): Promise<AccessTokenResult>;
 	/** Whether `request` would answer from the cache, without touching the network. */
 	hasFreshToken(resourceKey: string): boolean;
 	clear(): void;
@@ -94,11 +104,7 @@ export function createAccessTokenManager(deps: AccessTokenManagerDeps): AccessTo
 				return { resourceKey, status: 'error', errorCode: 'token-acquisition-failed' };
 			}
 			const expiresAt = tokens.accessTokenExpiresAt ?? Date.now() + 3_600_000;
-			cache.set(resourceKey, {
-				token: tokens.accessToken,
-				expiresAt,
-				scopes: resource.scopes,
-			});
+			cache.set(resourceKey, { token: tokens.accessToken, expiresAt });
 			return { resourceKey, status: 'success', token: tokens.accessToken, expiresAt };
 		} catch (error) {
 			if (isAuthError(error)) {
@@ -127,13 +133,18 @@ export function createAccessTokenManager(deps: AccessTokenManagerDeps): AccessTo
 			return fresh(resourceKey) !== undefined;
 		},
 
-		request(resourceKey): Promise<AccessTokenResult> {
+		request(resourceKey, options = {}): Promise<AccessTokenResult> {
 			const resource = deps.resources.find(entry => entry.key === resourceKey);
 			if (!resource) {
 				return Promise.resolve({ resourceKey, status: 'error', errorCode: 'configuration-error' });
 			}
 
-			const cached = fresh(resourceKey);
+			if (options.forceRefresh === true) {
+				// Dropped, not just skipped: the token is known bad, so no later
+				// caller should be handed it either.
+				cache.delete(resourceKey);
+			}
+			const cached = options.forceRefresh === true ? undefined : fresh(resourceKey);
 			if (cached) {
 				return Promise.resolve({
 					resourceKey,