Skip to content

A one-of-a-kind resume builder that keeps your privacy in mind. Completely secure, customizable, portable, open-source and free forever. Try it out today!

25.0 KB
Raw Blame
/**
 * The signed-in session: which server the app talks to and its OAuth tokens. Tokens live only in SecureStore
 * (Keychain / Keystore) and are never logged, rendered or written anywhere else.
 *
 * Sign-in (M3-T1) is OAuth 2.1 authorization code + PKCE (S256) in the system browser, against any server:
 * - Discovery from `<server>/.well-known/oauth-authorization-server`; dynamic client registration once per server,
 *   with `client_id` cached in SecureStore by server origin. Re-register only when the token endpoint answers
 *   `invalid_client`.
 * - Send `resource=<server origin>` (RFC 8707) on authorize, token and refresh requests. Without it the server issues
 *   an opaque access token that `/api/rpc` rejects.
 * - The redirect is `https://rxresu.me/auth/native-callback` for every server (the app's associated domain, through
 *   Universal Links / App Links); see `redirectUri` in oauth.ts. On iOS pass `preferUniversalLinks: true` to
 *   `promptAsync`.
 * - Mix-up defence: discovery must name the chosen origin as issuer and endpoint host (oauth.ts `discover`); the
 *   redirect must carry the request's `state` and, when the server advertises RFC 9207, its `iss`.
 * - Every session transition (sign-in commit, sign-out, refresh, expiry) runs through one queue, so none interleave.
 * - Refresh is single-flight. A refresh whose answer never arrived may have rotated the token on the server; sending
 *   the old one again would look like a replay and revoke the family. So it is never sent again: a persisted marker
 *   turns a lost answer (or a process kill) into `expired`.
 * - Each account (sign-in) gets a new identity number. Requests carry it; a 401 retry or refresh for an account that
 *   is no longer current fails instead of borrowing the new account's token.
 */
import { i18n } from "@lingui/core";
import * as AuthSession from "expo-auth-session";
import * as Network from "expo-network";
import * as SecureStore from "expo-secure-store";
import Storage from "expo-sqlite/kv-store";
import * as WebBrowser from "expo-web-browser";
import { useSyncExternalStore } from "react";
import { fnv1a } from "@reactive-resume/utils/string";
import {
	discover,
	forgetClient,
	getClientId,
	isAllowedServer,
	parseAuthorizationResponse,
	redirectUri,
	registerClient,
	scopes,
	storeKey,
} from "./oauth";

export const DEFAULT_SERVER = "https://rxresu.me";

/**
 * - `loading`: tokens are being read from SecureStore at launch.
 * - `signed-out`: no tokens for the current server.
 * - `signed-in`: an access token (or a refresh token to get one) is stored.
 * - `expired`: the refresh token was rejected; the user must sign in again. The server is kept.
 */
export type SessionStatus = "loading" | "signed-out" | "signed-in" | "expired";

export type Session = {
	status: SessionStatus;
	/** The server origin, for example `https://rxresu.me`. */
	server: string;
};

export type Tokens = {
	accessToken: string;
	refreshToken?: string | undefined;
	/** Unix seconds. */
	expiresAt?: number | undefined;
};

const serverKey = "server";
const tokensKey = (server: string) => storeKey("tokens", server);
// Set while a refresh request is out; holds a fingerprint of the refresh token it sent.
const refreshMarkerKey = (server: string) => storeKey("refreshing", server);
// Refresh this long before the access token expires, so a request never leaves with a token about to lapse.
const expirySkewSeconds = 60;
const refreshTimeout = 20_000;
const revokeTimeout = 5_000;

let session: Session = { status: "loading", server: DEFAULT_SERVER };
let tokens: Tokens | null = null;
// The signed-in account, `JSON.stringify([server, sub])` (the draft store's scope). Kept through `expired`, so signing
// out from there still clears that account's drafts; cleared on sign-out.
let accountScope: string | null = null;
// Changes whenever the account behind the tokens changes (sign-in, sign-out, expiry), never on a refresh.
let identity = 0;
let refreshing: { account: number; result: Promise<string | null> } | null = null;
let queue: Promise<unknown> = Promise.resolve();
// Counts sign-in attempts; sign-out bumps it too. An attempt commits only if it is still the latest.
let attempts = 0;
const listeners = new Set<() => void>();
const identityListeners = new Set<() => void>();

/** Runs session transitions one after another, in call order. */
function transition<T>(step: () => Promise<T>): Promise<T> {
	const run = queue.then(step, step);
	queue = run.catch(() => null);
	return run;
}

/** The `sub` claim of a JWT access token, read without verifying it (the server verifies). */
function subjectOf(accessToken: string): string | null {
	try {
		const encoded = accessToken.split(".")[1];
		if (!encoded) return null;
		const base64 = encoded.replaceAll("-", "+").replaceAll("_", "/");
		const payload = JSON.parse(atob(base64 + "=".repeat((4 - (base64.length % 4)) % 4))) as { sub?: unknown };
		return typeof payload.sub === "string" ? payload.sub : null;
	} catch {
		return null;
	}
}

const scopeOf = (server: string, accessToken: string | null | undefined) => {
	const subject = accessToken ? subjectOf(accessToken) : null;
	return subject ? JSON.stringify([server, subject]) : null;
};

// FNV-1a: tells two refresh tokens apart without storing one a second time.
const fingerprint = (value: string) => fnv1a(value).toString(16);

const setSession = (next: Session) => {
	session = next;
	for (const listener of listeners) listener();
};

/** A new account (or none) is behind the session: account-scoped caches must go before anything renders. */
const changeIdentity = () => {
	identity++;
	for (const listener of identityListeners) listener();
};

/** Calls `listener` synchronously on every session change (status or server). Returns the unsubscribe function. */
export function subscribeSession(listener: () => void): () => void {
	listeners.add(listener);
	return () => listeners.delete(listener);
}

/**
 * Calls `listener` synchronously when the account changes: sign-in, account or server switch, sign-out, expiry.
 * Not on a token refresh. Clear account-scoped caches here.
 */
export function subscribeIdentity(listener: () => void): () => void {
	identityListeners.add(listener);
	return () => identityListeners.delete(listener);
}

/** The current session, outside React. */
export function getSession(): Session {
	return session;
}

/** The current session. Re-renders when the status or server changes. */
export function useSession(): Session {
	return useSyncExternalStore(subscribeSession, () => session);
}

/** The server origin requests go to. */
export function getServer(): string {
	return session.server;
}

/**
 * The signed-in account as the draft store's scope, `JSON.stringify([server origin, user id])`, read from the stored
 * token without a network refresh, so drafts open offline. Null unless signed in.
 */
export function getAccountScope(): string | null {
	return session.status === "signed-in" ? accountScope : null;
}

/**
 * A server and the access token for it, read together. `scope` is the account the token belongs to; `account` is the
 * session identity the snapshot was taken from.
 */
export type Credentials = { server: string; accessToken: string | null; scope: string | null; account: number };

/**
 * The current server with its access token (refreshed first when it is about to expire), from one account. If the
 * account changes while a refresh runs, the token is null rather than the next account's.
 */
export async function getCredentials(): Promise<Credentials> {
	const { server } = session;
	const account = identity;
	const token = await getAccessToken();
	const accessToken = identity === account ? token : null;
	return { server, accessToken, scope: scopeOf(server, accessToken), account };
}

/**
 * The server answered 401 to `used`, although its token looked valid. Refreshes once (shared with any refresh in
 * flight) and returns the credentials to retry with, for the same account only; null when there is nothing to retry,
 * including when the account changed since `used` was taken.
 */
export async function recoverFromUnauthorized(used: Credentials): Promise<Credentials | null> {
	if (!used.accessToken || used.account !== identity || !tokens) return null;
	// Another request already refreshed this account: retry with the newer token.
	if (tokens.accessToken !== used.accessToken) return { ...used, accessToken: tokens.accessToken };
	if (refreshing?.account === used.account) {
		const accessToken = await refreshing.result;
		return accessToken && accessToken !== used.accessToken && used.account === identity
			? { ...used, accessToken }
			: null;
	}
	if (!tokens.refreshToken) {
		await transition(() => expire(used.account));
		return null;
	}
	const accessToken = await refreshOnce(used.account, tokens.refreshToken);
	if (!accessToken || accessToken === used.accessToken || used.account !== identity) return null;
	return { ...used, accessToken };
}

/** The retry after a refresh was rejected too: the server no longer accepts this account's tokens. */
export function rejectCredentials(used: Credentials): Promise<void> {
	return transition(async () => {
		if (tokens?.accessToken === used.accessToken) await expire(used.account);
	});
}

let restoring: Promise<void> | null = null;

/**
 * Reads the last server and its tokens from SecureStore. Call once at launch. An unreadable store signs out. A refresh
 * that was still out when the app last stopped leaves the session `expired`: its token may already be rotated.
 *
 * The root layout and the cold-start link handler both call it; they share one restore, queued as a session
 * transition, so a sign-in that follows can never be overwritten by a slow read of the previous server.
 */
export function restoreSession(): Promise<void> {
	restoring ??= transition(readStoredSession);
	return restoring;
}

async function readStoredSession(): Promise<void> {
	try {
		const { clearAccountExportCache } = await import("@/features/settings/export-cache");
		clearAccountExportCache();
		const storedServer = await SecureStore.getItemAsync(serverKey);
		const server = storedServer && isAllowedServer(storedServer) ? storedServer : DEFAULT_SERVER;
		const stored = await SecureStore.getItemAsync(tokensKey(server));
		tokens = stored ? (JSON.parse(stored) as Tokens) : null;
		accountScope = scopeOf(server, tokens?.accessToken);
		// A refresh was sent and its outcome never fully landed on disk: whatever tokens are stored may be consumed.
		if (await SecureStore.getItemAsync(refreshMarkerKey(server))) {
			tokens = null;
			setSession({ status: "expired", server });
			await retireTokens(server);
			return;
		}
		setSession({ status: tokens ? "signed-in" : "signed-out", server });
	} catch {
		tokens = null;
		accountScope = null;
		setSession({ status: "signed-out", server: DEFAULT_SERVER });
	}
}

/** Development previews may install a local fixture only when no real account is present. */
export async function installDevelopmentSession(origin: string): Promise<void> {
	if (!__DEV__ || !["localhost", "127.0.0.1", "[::1]", "10.0.2.2"].includes(new URL(origin).hostname))
		throw new Error("Preview sessions require a local development server.");
	if (new URL(origin).origin !== origin) throw new Error("Expected a development server origin.");
	await restoreSession();
	return transition(async () => {
		if (
			session.status !== "signed-out" ||
			tokens ||
			accountScope ||
			(await SecureStore.getItemAsync(tokensKey(origin)))
		)
			throw new Error("Sign out before opening a development preview.");
		const next = { accessToken: `fixture.${btoa(JSON.stringify({ sub: "rr-M3T4-preview" }))}.fixture` };
		await SecureStore.setItemAsync(tokensKey(origin), JSON.stringify(next));
		await SecureStore.setItemAsync(serverKey, origin);
		tokens = next;
		accountScope = scopeOf(origin, next.accessToken);
		changeIdentity();
		setSession({ status: "signed-in", server: origin });
	});
}

/**
 * Signs in to `server` (an origin) in the system browser, then makes it the current server with its tokens in one
 * queued step. Until then nothing changes: a cancelled or failed sign-in leaves the current server and tokens as they
 * were. Resolves true when signed in and false when the user cancelled; throws on discovery, registration, redirect
 * or token errors.
 */
export async function signIn(server: string): Promise<boolean> {
	const origin = new URL(server).origin;
	if (!isAllowedServer(origin)) throw new Error("The app needs an https server.");
	const attempt = ++attempts;
	// A cancelled or superseded attempt resolves false, even if its discovery or exchange failed meanwhile.
	const next = await authorize(origin, attempt).catch((error: unknown) => {
		if (attempt !== attempts) return null;
		throw error;
	});
	if (!next) return false;
	return transition(async () => {
		// Sign-out (or a newer sign-in) started after this attempt: its tokens must not bring the session back.
		if (attempt !== attempts) {
			await revoke(origin, next.refreshToken);
			return false;
		}
		const { clearAccountExportCache } = await import("@/features/settings/export-cache");
		clearAccountExportCache();
		await SecureStore.setItemAsync(tokensKey(origin), JSON.stringify(next));
		await SecureStore.setItemAsync(serverKey, origin);
		await SecureStore.deleteItemAsync(refreshMarkerKey(origin));
		tokens = next;
		accountScope = scopeOf(origin, next.accessToken);
		changeIdentity();
		setSession({ status: "signed-in", server: origin });
		return true;
	});
}

/** A sign-in that failed at the redirect, with the OAuth error code `messages.ts` maps. */
class SignInError extends Error {
	constructor(readonly code: string) {
		super(code);
		this.name = "SignInError";
	}
}

/** Discovery, DCR, PKCE in the system browser and the code exchange. Null when the user cancels or `attempt` is stale. */
async function authorize(origin: string, attempt: number): Promise<Tokens | null> {
	const discovery = await discover(origin);
	const clientId = await registerClient(origin, discovery);
	const request = new AuthSession.AuthRequest({
		clientId,
		redirectUri: redirectUri(origin),
		scopes,
		usePKCE: true,
		// OpenID's `ui_locales`: the browser's sign-in pages open in the app's language, and a new account (with its
		// verification email) starts in it. Servers that don't read it ignore it.
		extraParams: { resource: origin, ui_locales: i18n.locale },
	});
	await request.makeAuthUrlAsync(discovery);
	// This attempt, bound to its state: only a redirect carrying the same state (and issuer) may use its verifier.
	const pending = {
		state: request.state,
		issuer: discovery.issuer,
		verifier: request.codeVerifier ?? "",
		redirect: request.redirectUri,
	};
	// Cancelled (or superseded) during discovery or registration: never open the browser.
	if (attempt !== attempts) return null;
	// iOS 17.4+: an https redirect completes through ASWebAuthenticationSession's `.https` callback.
	const result = await request.promptAsync(discovery, { preferUniversalLinks: true });
	if (result.type === "cancel" || result.type === "dismiss" || attempt !== attempts) return null;
	if (result.type !== "success" && result.type !== "error") throw new SignInError(`authorization_${result.type}`);

	// Parsed here, by hand and from the query only, rather than trusting expo-auth-session's URL parsing.
	let params: Record<string, string>;
	try {
		params = parseAuthorizationResponse(result.url);
	} catch {
		throw new SignInError("invalid_response");
	}
	if (params.state !== pending.state) throw new SignInError("state_mismatch");
	// RFC 9207. Better Auth 1.7.7 advertises `authorization_response_iss_parameter_supported` and adds `iss` to code and
	// error redirects; a server that does not advertise it must at least not name another issuer.
	if (
		discovery.issParameterSupported
			? params.iss !== pending.issuer
			: params.iss !== undefined && params.iss !== pending.issuer
	)
		throw new SignInError("issuer_mismatch");
	if (params.error) throw new SignInError(params.error);
	if (!params.code) throw new SignInError("no_code");

	try {
		const response = await AuthSession.exchangeCodeAsync(
			{
				clientId,
				code: params.code,
				redirectUri: pending.redirect,
				extraParams: { code_verifier: pending.verifier, resource: origin },
			},
			discovery,
		);
		return toTokens(response);
	} catch (error) {
		if (error instanceof AuthSession.TokenError && error.code === "invalid_client")
			await forgetClient(origin).catch(() => null);
		throw error;
	}
}

const toTokens = (response: AuthSession.TokenResponse, previousRefreshToken?: string): Tokens => ({
	accessToken: response.accessToken,
	refreshToken: response.refreshToken ?? previousRefreshToken,
	expiresAt: response.expiresIn ? response.issuedAt + response.expiresIn : undefined,
});

/** Cancels the sign-in in progress: closes its browser and invalidates the attempt; `signIn` then resolves false. */
export function cancelSignIn(): void {
	attempts++;
	WebBrowser.dismissAuthSession();
}

// kv-store prefixes other features keep per account (`<prefix><scope>:<id>`): application notes (M5-T2) and Career
// workspace drafts (M6-T2). Resume and letter drafts are cleared by the draft runtime.
const scopedStoragePrefixes = ["reactive-resume:application-notes:", "reactive-resume:career-draft:"];

/** Best-effort revocation of a refresh token on `server`, given up after `revokeTimeout`. */
async function revoke(server: string, refreshToken: string | undefined): Promise<void> {
	if (!refreshToken) return;
	await Promise.race([
		Promise.all([discover(server), getClientId(server)]).then(([discovery, clientId]) => {
			if (!clientId || !discovery.revocationEndpoint) return;
			return AuthSession.revokeAsync(
				{ clientId, token: refreshToken, tokenTypeHint: AuthSession.TokenTypeHint.RefreshToken },
				discovery,
			);
		}),
		// A revocation endpoint that never answers must not hold sign-out (and the transition queue).
		new Promise<void>((resolve) => setTimeout(resolve, revokeTimeout)),
	]).catch(() => null);
}

/** Sign-out finished, but some of the account's data on this device could not be removed. */
export class SignOutCleanupError extends AggregateError {
	constructor(errors: unknown[]) {
		super(errors, "Signed out, but some local data could not be removed.");
		this.name = "SignOutCleanupError";
	}
}

/**
 * Signs out the current account, after any queued refresh, and invalidates every sign-in still in the browser.
 * Against a snapshot of that account only: revokes its refresh token (best effort, bounded), clears its local data
 * (drafts, application notes, Career drafts) and every stored library thumbnail, then deletes its tokens. The server and its registered
 * client are kept. Access tokens already issued stay valid until they expire (at most an hour).
 * Credentials are always removed and the session always ends signed out; a cleanup that fails does not stop the others
 * and is reported afterwards as a `SignOutCleanupError`.
 */
export function signOut(): Promise<void> {
	attempts++;
	return transition(async () => {
		const departing = { server: session.server, tokens, scope: accountScope, account: identity };
		const errors: unknown[] = [];
		const attempt = async (step: () => unknown) => {
			try {
				await step();
			} catch (error) {
				errors.push(error);
			}
		};

		await revoke(departing.server, departing.tokens?.refreshToken);
		await attempt(async () => {
			// Imported here, like the draft runtime below, to keep this module free of feature imports.
			const { clearStoredThumbnails } = await import("@/features/documents/thumbnail-store");
			await clearStoredThumbnails();
		});
		await attempt(async () => {
			const { clearAccountExportCache } = await import("@/features/settings/export-cache");
			clearAccountExportCache();
		});
		const { scope } = departing;
		if (scope) {
			await attempt(async () => {
				// Imported here: the draft runtime imports the API client, which imports this module.
				const { clearDraftsFor } = await import("@/draft/runtime");
				clearDraftsFor(scope);
			});
			await attempt(() => {
				const prefixes = [
					...scopedStoragePrefixes.map((prefix) => `${prefix}${scope}:`),
					`letter-draft:${departing.server}:${scope}:`,
				];
				for (const key of Storage.getAllKeysSync())
					if (prefixes.some((prefix) => key.startsWith(prefix))) Storage.removeItemSync(key);
			});
		}

		try {
			await SecureStore.deleteItemAsync(tokensKey(departing.server));
			await SecureStore.deleteItemAsync(refreshMarkerKey(departing.server));
		} catch (error) {
			errors.push(error);
			// The tokens may still be on disk: a marker makes the next launch expire them instead of signing back in.
			await SecureStore.setItemAsync(refreshMarkerKey(departing.server), "signed-out").catch(() => null);
		}
		if (identity === departing.account) {
			tokens = null;
			accountScope = null;
			changeIdentity();
			setSession({ status: "signed-out", server: departing.server });
		}
		if (errors.length > 0) throw new SignOutCleanupError(errors);
	});
}

/**
 * A valid access token for the current account, or null when signed out. Refreshes first when the token is about to
 * expire; concurrent callers share one refresh.
 */
export function getAccessToken(): Promise<string | null> {
	if (!tokens) return Promise.resolve(null);
	// The refresh token is retired while its refresh is out; wait for that refresh.
	if (refreshing?.account === identity) return refreshing.result;
	const expiresSoon = tokens.expiresAt !== undefined && tokens.expiresAt - expirySkewSeconds <= Date.now() / 1000;
	if (!expiresSoon) return Promise.resolve(tokens.accessToken);
	if (!tokens.refreshToken) return Promise.resolve(null);
	return refreshOnce(identity, tokens.refreshToken);
}

/** Single flight through the transition queue: every caller shares the refresh in progress. */
function refreshOnce(account: number, refreshToken: string): Promise<string | null> {
	if (refreshing?.account === account) return refreshing.result;
	const current = {
		account,
		result: transition(() => refreshAccessToken(account, refreshToken)).finally(() => {
			if (refreshing === current) refreshing = null;
		}),
	};
	refreshing = current;
	return current.result;
}

async function refreshAccessToken(account: number, refreshToken: string): Promise<string | null> {
	if (identity !== account || !tokens) return null;
	// A refresh queued earlier already rotated this account's token.
	if (tokens.refreshToken !== refreshToken) return tokens.accessToken;
	const { server } = session;
	const stale = tokens;

	// Offline: nothing would reach the server, so keep the old token and let the request fail on its own.
	const network = await Network.getNetworkStateAsync().catch(() => null);
	if (network && (network.isConnected === false || network.isInternetReachable === false)) return stale.accessToken;

	const [discovery, clientId] = await Promise.all([discover(server), getClientId(server)]).catch(() => [null, null]);
	if (!discovery) return stale.accessToken;
	if (!clientId) {
		await expire(account);
		return null;
	}

	await SecureStore.setItemAsync(refreshMarkerKey(server), fingerprint(refreshToken));
	// From here the token counts as spent: whatever happens, it is never sent again.
	tokens = { ...stale, refreshToken: undefined };
	try {
		const response = await Promise.race([
			AuthSession.refreshAsync({ clientId, refreshToken, extraParams: { resource: server } }, discovery),
			// A request that never answers would hold the transition queue (and sign-out) forever.
			new Promise<never>((_, reject) => setTimeout(() => reject(new Error("Refresh timed out.")), refreshTimeout)),
		]);
		const next = toTokens(response, undefined);
		// The marker goes only once the new tokens are durably stored.
		await SecureStore.setItemAsync(tokensKey(server), JSON.stringify(next));
		await SecureStore.deleteItemAsync(refreshMarkerKey(server));
		if (identity !== account) return null;
		tokens = next;
		accountScope = scopeOf(server, next.accessToken) ?? accountScope;
		return next.accessToken;
	} catch (error) {
		// No answer, an error answer, or a store that would not keep the result: fail closed and ask for a new sign-in.
		try {
			if (error instanceof AuthSession.TokenError && error.code === "invalid_client") await forgetClient(server);
		} catch {
			// Re-registration then waits for the next invalid_client; the session must still end.
		} finally {
			await expire(account);
		}
		return null;
	}
}

/**
 * The account's refresh token is gone, rejected or possibly spent. Drops the tokens and marks the session `expired`,
 * which keeps the user on the current screen with a prompt to sign in again. Runs inside the transition queue.
 */
async function expire(account: number): Promise<void> {
	if (identity !== account) return;
	const { server } = session;
	tokens = null;
	changeIdentity();
	setSession({ status: "expired", server });
	try {
		const { clearAccountExportCache } = await import("@/features/settings/export-cache");
		clearAccountExportCache();
	} finally {
		await retireTokens(server);
	}
}

/**
 * Deletes the stored tokens, then the refresh marker. The marker stays if the tokens could not be deleted, so the next
 * launch expires the session instead of sending a possibly spent token.
 */
async function retireTokens(server: string): Promise<void> {
	try {
		await SecureStore.deleteItemAsync(tokensKey(server));
	} catch {
		return;
	}
	await SecureStore.deleteItemAsync(refreshMarkerKey(server)).catch(() => null);
}