@chipmobilesdk/rn-auth 0.3.0 → 0.4.0

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 | undefined;
+}
+
+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 | undefined;
+}
+
+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,99 @@
-/**
- * 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).
+ */
+
+import { COMMON_PATTERNS, SdkError, redactPatterns } from '@chipmobilesdk/rn-core';
+
+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 | undefined;
+}
+
+/** JWT-shaped values: three base64url segments separated by dots. */
+const JWT_PATTERN = /[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/g;
+/** Any other long opaque token-like run; shorter than rn-core's payload run on purpose. */
+const TOKEN_PATTERN = /[A-Za-z0-9_-]{24,}/g;
+
+/**
+ * Replace token-like substrings with a placeholder so diagnostics never leak
+ * secrets or token values (FR-014): JWTs become `[redacted-token]`; URLs, e-mail
+ * addresses, UUIDs and other opaque runs become `[redacted]` (rn-core's patterns).
+ */
+export function redact(value: string | undefined): string | undefined {
+	if (!value) {
+		return value;
+	}
+	return redactPatterns(value.replace(JWT_PATTERN, '[redacted-token]'), [
+		...COMMON_PATTERNS,
+		TOKEN_PATTERN,
+	]);
+}
+
+/** Retrying can only help when the network was the problem. */
+const RETRYABLE: ReadonlySet<AuthErrorCode> = new Set<AuthErrorCode>(['network-unavailable']);
+
+/** 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 detail?: string | undefined;
+
+	constructor(args: AuthErrorArgs) {
+		const detail = redact(args.detail);
+		super('rn-auth', args.code, {
+			message: args.messageKey,
+			retryable: RETRYABLE.has(args.code),
+			redactedCause: detail,
+		});
+		this.name = 'AuthError';
+		this.audience = args.audience ?? 'developer';
+		this.messageKey = args.messageKey;
+		this.detail = 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,
+	});
+}