@chipmobilesdk/rn-auth 0.3.0 → 0.3.1

package/src/core/profile.ts

@@ -1,60 +1,57 @@
-/**
- * Claims → Profile mapping (FR-006). Tolerant of Apple private-relay emails and
- * missing display name / given name (edge cases).
- */
-
-import type { Profile, ProviderId, ProviderIdentity } from '../config/types';
-
-function asString(value: unknown): string | undefined {
-	return typeof value === 'string' && value.length > 0 ? value : undefined;
-}
-
-function looksLikeEmail(value: string | undefined): boolean {
-	return !!value && /.+@.+\..+/.test(value);
-}
-
-/** Map id-token claims to the app-visible Profile. */
-export function mapClaimsToProfile(
-	claims: Record<string, unknown>,
-	providerId?: ProviderId,
-): Profile {
-	const tenantUserId =
-		asString(claims.oid) ?? asString(claims.sub) ?? asString(claims.unique_name) ?? 'unknown';
-
-	const givenName = asString(claims.given_name);
-	const familyName = asString(claims.family_name);
-	const composedName = [givenName, familyName].filter(Boolean).join(' ') || undefined;
-	const displayName = asString(claims.name) ?? composedName;
-
-	const preferred = asString(claims.preferred_username);
-	const email =
-		asString(claims.email) ?? (looksLikeEmail(preferred) ? preferred : undefined);
-
-	const provider =
-		providerId ?? asString(claims.idp) ?? asString(claims.identityProvider) ?? 'unknown';
-
-	return {
-		tenantUserId,
-		displayName,
-		email,
-		provider,
-		claims,
-	};
-}
-
-/** Describe the external provider identity behind the profile (FR-004 edge cases). */
-export function describeProviderIdentity(
-	claims: Record<string, unknown>,
-	providerId?: ProviderId,
-): ProviderIdentity {
-	const provider = providerId ?? asString(claims.idp) ?? 'unknown';
-	const subject = asString(claims.sub) ?? asString(claims.oid) ?? 'unknown';
-	const email = asString(claims.email);
-	let emailBehavior: ProviderIdentity['emailBehavior'] = 'none';
-	if (email) {
-		emailBehavior = email.endsWith('@privaterelay.appleid.com')
-			? 'private-relay'
-			: 'direct';
-	}
-	return { provider, subject, emailBehavior };
-}
+/**
+ * Claims → Profile mapping (FR-006). Tolerant of Apple private-relay emails and
+ * missing display name / given name (edge cases).
+ */
+
+import type { Profile, ProviderId, ProviderIdentity } from '../config/types';
+
+function asString(value: unknown): string | undefined {
+	return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+
+function looksLikeEmail(value: string | undefined): boolean {
+	return !!value && /.+@.+\..+/.test(value);
+}
+
+/** Map id-token claims to the app-visible Profile. */
+export function mapClaimsToProfile(
+	claims: Record<string, unknown>,
+	providerId?: ProviderId,
+): Profile {
+	const tenantUserId =
+		asString(claims.oid) ?? asString(claims.sub) ?? asString(claims.unique_name) ?? 'unknown';
+
+	const givenName = asString(claims.given_name);
+	const familyName = asString(claims.family_name);
+	const composedName = [givenName, familyName].filter(Boolean).join(' ') || undefined;
+	const displayName = asString(claims.name) ?? composedName;
+
+	const preferred = asString(claims.preferred_username);
+	const email = asString(claims.email) ?? (looksLikeEmail(preferred) ? preferred : undefined);
+
+	const provider =
+		providerId ?? asString(claims.idp) ?? asString(claims.identityProvider) ?? 'unknown';
+
+	return {
+		tenantUserId,
+		displayName,
+		email,
+		provider,
+		claims,
+	};
+}
+
+/** Describe the external provider identity behind the profile (FR-004 edge cases). */
+export function describeProviderIdentity(
+	claims: Record<string, unknown>,
+	providerId?: ProviderId,
+): ProviderIdentity {
+	const provider = providerId ?? asString(claims.idp) ?? 'unknown';
+	const subject = asString(claims.sub) ?? asString(claims.oid) ?? 'unknown';
+	const email = asString(claims.email);
+	let emailBehavior: ProviderIdentity['emailBehavior'] = 'none';
+	if (email) {
+		emailBehavior = email.endsWith('@privaterelay.appleid.com') ? 'private-relay' : 'direct';
+	}
+	return { provider, subject, emailBehavior };
+}

package/src/core/session.ts

@@ -1,112 +1,105 @@
-/**
- * Session restoration (FR-008, R5). Reads the persisted artifact, attempts a
- * silent refresh, and classifies the outcome:
- *  - restored: fresh tokens + claims → authenticated
- *  - offline:  the refresh could not complete for any reason other than the
- *              session being invalid — no network, a timeout, a 5xx, an error we
- *              cannot classify → cached profile read-only, tier unverified (fail
- *              closed) — clarify Q3
- *  - unavailable: no artifact, or the provider said the refresh token is no
- *              longer valid → signed-out reauth
- *
- * Only `unavailable` deletes the stored session, so it is reserved for a verdict
- * the provider actually gave. Treating every unclassified error as expiry signed
- * users out whenever the token endpoint had a bad moment.
- */
-
-import type {
-	AccessTier,
-	AccessTierMapping,
-	Profile,
-	RestoreStatus,
-} from '../config/types';
-import type { OidcAuthClient } from '../oidc/authClient';
-import type { SecureTokenStore } from '../tokens/secureStore';
-import { AUTH_STORAGE_KEY } from '../tokens/secureStore';
-import { mapClaimsToProfile } from './profile';
-import { evaluateAccessTier, failClosedTier } from '../access/accessTier';
-import { isAuthError } from '../diagnostics/errors';
-
-export interface PersistedSession {
-	refreshToken: string;
-	profile: Profile;
-	/** The id token hint for end-session (AUTH-04). Absent in artifacts written before 0.2.2. */
-	idToken?: string;
-}
-
-export interface RestoreDeps {
-	secureStore: SecureTokenStore;
-	authority: string;
-	clientId: string;
-	redirectUrl: string;
-	scopes: string[];
-	authClient: OidcAuthClient;
-	mapping: AccessTierMapping;
-}
-
-export interface RestoreResult {
-	outcome: RestoreStatus;
-	profile?: Profile;
-	accessTier?: AccessTier;
-	refreshToken?: string;
-	idToken?: string;
-}
-
-export function parsePersistedSession(raw: string | null): PersistedSession | null {
-	if (!raw) {
-		return null;
-	}
-	try {
-		const parsed = JSON.parse(raw) as PersistedSession;
-		if (parsed && typeof parsed.refreshToken === 'string' && parsed.profile) {
-			return parsed;
-		}
-		return null;
-	} catch {
-		return null;
-	}
-}
-
-export async function restoreSession(deps: RestoreDeps): Promise<RestoreResult> {
-	const raw = await deps.secureStore.getItem(AUTH_STORAGE_KEY);
-	const persisted = parsePersistedSession(raw);
-	if (!persisted) {
-		return { outcome: 'unavailable' };
-	}
-
-	try {
-		const tokens = await deps.authClient.refresh({
-			authority: deps.authority,
-			clientId: deps.clientId,
-			redirectUrl: deps.redirectUrl,
-			refreshToken: persisted.refreshToken,
-			scopes: deps.scopes,
-		});
-		// A refresh response may carry no id token, and so no claims. The stored
-		// profile is then still the best identity there is; an empty one is not.
-		const hasClaims = Object.keys(tokens.claims).length > 0;
-		return {
-			outcome: 'restored',
-			profile: hasClaims ? mapClaimsToProfile(tokens.claims) : persisted.profile,
-			accessTier: hasClaims
-				? evaluateAccessTier(tokens.claims, deps.mapping)
-				: failClosedTier(),
-			refreshToken: tokens.refreshToken || persisted.refreshToken,
-			idToken: tokens.idToken || persisted.idToken,
-		};
-	} catch (error) {
-		if (isAuthError(error) && error.code === 'session-expired') {
-			// The provider rejected the refresh token: reauthentication is required.
-			return { outcome: 'unavailable' };
-		}
-		// Anything else is no verdict on the session. Keep the cached identity
-		// read-only and fail closed on entitlement; the next restore tries again.
-		return {
-			outcome: 'offline',
-			profile: persisted.profile,
-			accessTier: failClosedTier(),
-			refreshToken: persisted.refreshToken,
-			idToken: persisted.idToken,
-		};
-	}
-}
+/**
+ * Session restoration (FR-008, R5). Reads the persisted artifact, attempts a
+ * silent refresh, and classifies the outcome:
+ *  - restored: fresh tokens + claims → authenticated
+ *  - offline:  the refresh could not complete for any reason other than the
+ *              session being invalid — no network, a timeout, a 5xx, an error we
+ *              cannot classify → cached profile read-only, tier unverified (fail
+ *              closed) — clarify Q3
+ *  - unavailable: no artifact, or the provider said the refresh token is no
+ *              longer valid → signed-out reauth
+ *
+ * Only `unavailable` deletes the stored session, so it is reserved for a verdict
+ * the provider actually gave. Treating every unclassified error as expiry signed
+ * users out whenever the token endpoint had a bad moment.
+ */
+
+import type { AccessTier, AccessTierMapping, Profile, RestoreStatus } from '../config/types';
+import type { OidcAuthClient } from '../oidc/authClient';
+import type { SecureTokenStore } from '../tokens/secureStore';
+import { AUTH_STORAGE_KEY } from '../tokens/secureStore';
+import { mapClaimsToProfile } from './profile';
+import { evaluateAccessTier, failClosedTier } from '../access/accessTier';
+import { isAuthError } from '../diagnostics/errors';
+
+export interface PersistedSession {
+	refreshToken: string;
+	profile: Profile;
+	/** The id token hint for end-session (AUTH-04). Absent in artifacts written before 0.2.2. */
+	idToken?: string;
+}
+
+export interface RestoreDeps {
+	secureStore: SecureTokenStore;
+	authority: string;
+	clientId: string;
+	redirectUrl: string;
+	scopes: string[];
+	authClient: OidcAuthClient;
+	mapping: AccessTierMapping;
+}
+
+export interface RestoreResult {
+	outcome: RestoreStatus;
+	profile?: Profile;
+	accessTier?: AccessTier;
+	refreshToken?: string;
+	idToken?: string;
+}
+
+export function parsePersistedSession(raw: string | null): PersistedSession | null {
+	if (!raw) {
+		return null;
+	}
+	try {
+		const parsed = JSON.parse(raw) as PersistedSession;
+		if (parsed && typeof parsed.refreshToken === 'string' && parsed.profile) {
+			return parsed;
+		}
+		return null;
+	} catch {
+		return null;
+	}
+}
+
+export async function restoreSession(deps: RestoreDeps): Promise<RestoreResult> {
+	const raw = await deps.secureStore.getItem(AUTH_STORAGE_KEY);
+	const persisted = parsePersistedSession(raw);
+	if (!persisted) {
+		return { outcome: 'unavailable' };
+	}
+
+	try {
+		const tokens = await deps.authClient.refresh({
+			authority: deps.authority,
+			clientId: deps.clientId,
+			redirectUrl: deps.redirectUrl,
+			refreshToken: persisted.refreshToken,
+			scopes: deps.scopes,
+		});
+		// A refresh response may carry no id token, and so no claims. The stored
+		// profile is then still the best identity there is; an empty one is not.
+		const hasClaims = Object.keys(tokens.claims).length > 0;
+		return {
+			outcome: 'restored',
+			profile: hasClaims ? mapClaimsToProfile(tokens.claims) : persisted.profile,
+			accessTier: hasClaims ? evaluateAccessTier(tokens.claims, deps.mapping) : failClosedTier(),
+			refreshToken: tokens.refreshToken || persisted.refreshToken,
+			idToken: tokens.idToken || persisted.idToken,
+		};
+	} catch (error) {
+		if (isAuthError(error) && error.code === 'session-expired') {
+			// The provider rejected the refresh token: reauthentication is required.
+			return { outcome: 'unavailable' };
+		}
+		// Anything else is no verdict on the session. Keep the cached identity
+		// read-only and fail closed on entitlement; the next restore tries again.
+		return {
+			outcome: 'offline',
+			profile: persisted.profile,
+			accessTier: failClosedTier(),
+			refreshToken: persisted.refreshToken,
+			idToken: persisted.idToken,
+		};
+	}
+}

package/src/diagnostics/errors.ts

@@ -1,85 +1,87 @@
-/**
- * Developer-facing diagnostics. AuthError carries a stable machine-readable
- * code, an audience (user vs developer/tenant), and a localizable message key.
- * `detail` is always passed through `redact` so tokens and secrets never appear
- * in logs or error objects (FR-014).
- */
-
-export type AuthErrorCode =
-	| 'configuration-error'
-	| 'provider-cancelled'
-	| 'redirect-mismatch'
-	| 'token-acquisition-failed'
-	| 'session-expired'
-	| 'consent-denied'
-	| 'entitlement-unverified'
-	| 'network-unavailable';
-
-export type AuthErrorAudience = 'user' | 'developer';
-
-export interface AuthErrorArgs {
-	code: AuthErrorCode;
-	messageKey: string;
-	audience?: AuthErrorAudience;
-	detail?: string;
-}
-
-/**
- * Replace token-like substrings (long URL-safe base64 / JWT segments) with a
- * placeholder so diagnostics never leak secrets or token values (FR-014).
- */
-export function redact(value: string | undefined): string | undefined {
-	if (!value) {
-		return value;
-	}
-	return value
-		// JWT-shaped values: three base64url segments separated by dots.
-		.replace(/[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/g, '[redacted-token]')
-		// Any other long opaque token-like run.
-		.replace(/[A-Za-z0-9_-]{24,}/g, '[redacted]');
-}
-
-export class AuthError extends Error {
-	readonly code: AuthErrorCode;
-	readonly audience: AuthErrorAudience;
-	readonly messageKey: string;
-	readonly detail?: string;
-
-	constructor(args: AuthErrorArgs) {
-		super(args.messageKey);
-		this.name = 'AuthError';
-		this.code = args.code;
-		this.audience = args.audience ?? 'developer';
-		this.messageKey = args.messageKey;
-		this.detail = redact(args.detail);
-	}
-}
-
-export class AuthConfigError extends AuthError {
-	constructor(messageKey: string, detail?: string) {
-		super({ code: 'configuration-error', messageKey, audience: 'developer', detail });
-		this.name = 'AuthConfigError';
-	}
-}
-
-export function isAuthError(value: unknown): value is AuthError {
-	return value instanceof AuthError;
-}
-
-/** Normalize any thrown value into an AuthError without leaking secrets. */
-export function toAuthError(
-	value: unknown,
-	fallbackCode: AuthErrorCode = 'token-acquisition-failed',
-	fallbackMessageKey = 'auth.error.token',
-): AuthError {
-	if (isAuthError(value)) {
-		return value;
-	}
-	const message = value instanceof Error ? value.message : String(value);
-	return new AuthError({
-		code: fallbackCode,
-		messageKey: fallbackMessageKey,
-		audience: 'developer',
-		detail: message,
-	});
-}
+/**
+ * Developer-facing diagnostics. AuthError carries a stable machine-readable
+ * code, an audience (user vs developer/tenant), and a localizable message key.
+ * `detail` is always passed through `redact` so tokens and secrets never appear
+ * in logs or error objects (FR-014).
+ */
+
+export type AuthErrorCode =
+	| 'configuration-error'
+	| 'provider-cancelled'
+	| 'redirect-mismatch'
+	| 'token-acquisition-failed'
+	| 'session-expired'
+	| 'consent-denied'
+	| 'entitlement-unverified'
+	| 'network-unavailable';
+
+export type AuthErrorAudience = 'user' | 'developer';
+
+export interface AuthErrorArgs {
+	code: AuthErrorCode;
+	messageKey: string;
+	audience?: AuthErrorAudience;
+	detail?: string;
+}
+
+/**
+ * Replace token-like substrings (long URL-safe base64 / JWT segments) with a
+ * placeholder so diagnostics never leak secrets or token values (FR-014).
+ */
+export function redact(value: string | undefined): string | undefined {
+	if (!value) {
+		return value;
+	}
+	return (
+		value
+			// JWT-shaped values: three base64url segments separated by dots.
+			.replace(/[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/g, '[redacted-token]')
+			// Any other long opaque token-like run.
+			.replace(/[A-Za-z0-9_-]{24,}/g, '[redacted]')
+	);
+}
+
+export class AuthError extends Error {
+	readonly code: AuthErrorCode;
+	readonly audience: AuthErrorAudience;
+	readonly messageKey: string;
+	readonly detail?: string;
+
+	constructor(args: AuthErrorArgs) {
+		super(args.messageKey);
+		this.name = 'AuthError';
+		this.code = args.code;
+		this.audience = args.audience ?? 'developer';
+		this.messageKey = args.messageKey;
+		this.detail = redact(args.detail);
+	}
+}
+
+export class AuthConfigError extends AuthError {
+	constructor(messageKey: string, detail?: string) {
+		super({ code: 'configuration-error', messageKey, audience: 'developer', detail });
+		this.name = 'AuthConfigError';
+	}
+}
+
+export function isAuthError(value: unknown): value is AuthError {
+	return value instanceof AuthError;
+}
+
+/** Normalize any thrown value into an AuthError without leaking secrets. */
+export function toAuthError(
+	value: unknown,
+	fallbackCode: AuthErrorCode = 'token-acquisition-failed',
+	fallbackMessageKey = 'auth.error.token',
+): AuthError {
+	if (isAuthError(value)) {
+		return value;
+	}
+	const message = value instanceof Error ? value.message : String(value);
+	return new AuthError({
+		code: fallbackCode,
+		messageKey: fallbackMessageKey,
+		audience: 'developer',
+		detail: message,
+	});
+}

package/src/diagnostics/messageKeys.ts

@@ -1,61 +1,59 @@
-/**
- * Stable, localizable message keys with English default copy (UX-006 / LIB-011).
- * The library takes no i18n runtime dependency: consuming apps map these keys to
- * localized strings via their own i18n system. User-actionable copy and
- * developer/tenant-configuration copy are kept separate (UX-005).
- */
-
-export interface AuthMessageMap {
-	// User-facing actions and states
-	'auth.action.continueGoogle': string;
-	'auth.action.continueApple': string;
-	'auth.action.continueFacebook': string;
-	'auth.state.signedOut': string;
-	'auth.state.authenticating': string;
-	'auth.state.signedIn': string;
-	'auth.state.signingOut': string;
-	// Access tier (user-facing)
-	'auth.tier.free': string;
-	'auth.tier.premium': string;
-	'auth.tier.unverified': string;
-	// User-actionable errors
-	'auth.error.cancelled': string;
-	'auth.error.sessionExpired': string;
-	'auth.error.entitlement': string;
-	'auth.error.network': string;
-	// Developer / tenant-configuration errors
-	'auth.error.configuration': string;
-	'auth.error.redirectMismatch': string;
-	'auth.error.token': string;
-	'auth.error.consentDenied': string;
-}
-
-export type AuthMessageKey = keyof AuthMessageMap;
-
-export const DEFAULT_MESSAGES: AuthMessageMap = {
-	'auth.action.continueGoogle': 'Continue with Google',
-	'auth.action.continueApple': 'Continue with Apple',
-	'auth.action.continueFacebook': 'Continue with Facebook',
-	'auth.state.signedOut': 'Sign in to continue',
-	'auth.state.authenticating': 'Signing you in…',
-	'auth.state.signedIn': 'You are signed in',
-	'auth.state.signingOut': 'Signing out…',
-	'auth.tier.free': 'Free',
-	'auth.tier.premium': 'Premium',
-	'auth.tier.unverified': 'Membership could not be verified',
-	'auth.error.cancelled': 'Sign-in was cancelled. You can try again.',
-	'auth.error.sessionExpired': 'Your session expired. Please sign in again.',
-	'auth.error.entitlement': 'This feature requires a verified premium membership.',
-	'auth.error.network': 'No connection. Some features are limited until you reconnect.',
-	'auth.error.configuration': 'Authentication is not configured correctly.',
-	'auth.error.redirectMismatch': 'The sign-in redirect does not match the app configuration.',
-	'auth.error.token': 'We could not complete the request. Please try again.',
-	'auth.error.consentDenied': 'Access to this resource was denied.',
-};
-
-/** Resolve a message, preferring app overrides over the English defaults. */
-export function resolveMessages(
-	overrides?: Partial<AuthMessageMap>,
-): AuthMessageMap {
-	return { ...DEFAULT_MESSAGES, ...(overrides ?? {}) };
-}
+/**
+ * Stable, localizable message keys with English default copy (UX-006 / LIB-011).
+ * The library takes no i18n runtime dependency: consuming apps map these keys to
+ * localized strings via their own i18n system. User-actionable copy and
+ * developer/tenant-configuration copy are kept separate (UX-005).
+ */
+
+export interface AuthMessageMap {
+	// User-facing actions and states
+	'auth.action.continueGoogle': string;
+	'auth.action.continueApple': string;
+	'auth.action.continueFacebook': string;
+	'auth.state.signedOut': string;
+	'auth.state.authenticating': string;
+	'auth.state.signedIn': string;
+	'auth.state.signingOut': string;
+	// Access tier (user-facing)
+	'auth.tier.free': string;
+	'auth.tier.premium': string;
+	'auth.tier.unverified': string;
+	// User-actionable errors
+	'auth.error.cancelled': string;
+	'auth.error.sessionExpired': string;
+	'auth.error.entitlement': string;
+	'auth.error.network': string;
+	// Developer / tenant-configuration errors
+	'auth.error.configuration': string;
+	'auth.error.redirectMismatch': string;
+	'auth.error.token': string;
+	'auth.error.consentDenied': string;
+}
+
+export type AuthMessageKey = keyof AuthMessageMap;
+
+export const DEFAULT_MESSAGES: AuthMessageMap = {
+	'auth.action.continueGoogle': 'Continue with Google',
+	'auth.action.continueApple': 'Continue with Apple',
+	'auth.action.continueFacebook': 'Continue with Facebook',
+	'auth.state.signedOut': 'Sign in to continue',
+	'auth.state.authenticating': 'Signing you in…',
+	'auth.state.signedIn': 'You are signed in',
+	'auth.state.signingOut': 'Signing out…',
+	'auth.tier.free': 'Free',
+	'auth.tier.premium': 'Premium',
+	'auth.tier.unverified': 'Membership could not be verified',
+	'auth.error.cancelled': 'Sign-in was cancelled. You can try again.',
+	'auth.error.sessionExpired': 'Your session expired. Please sign in again.',
+	'auth.error.entitlement': 'This feature requires a verified premium membership.',
+	'auth.error.network': 'No connection. Some features are limited until you reconnect.',
+	'auth.error.configuration': 'Authentication is not configured correctly.',
+	'auth.error.redirectMismatch': 'The sign-in redirect does not match the app configuration.',
+	'auth.error.token': 'We could not complete the request. Please try again.',
+	'auth.error.consentDenied': 'Access to this resource was denied.',
+};
+
+/** Resolve a message, preferring app overrides over the English defaults. */
+export function resolveMessages(overrides?: Partial<AuthMessageMap>): AuthMessageMap {
+	return { ...DEFAULT_MESSAGES, ...(overrides ?? {}) };
+}