@eventuras/fides-auth 0.14.1 → 0.15.0

package/dist/server/index.js

@@ -1,22 +1,258 @@
-import { ACCESS_TOKEN_COOKIE_NAME, CookieTooLargeError, ID_TOKEN_COOKIE_NAME, SESSION_COOKIE_NAME, assertCookieWithinLimit, defaultOAuthCookieOptions, defaultSessionCookieOptions } from "../cookies.js";
+import { ACCESS_TOKEN_COOKIE_NAME, CookieTooLargeError, ID_TOKEN_COOKIE_NAME, SESSION_COOKIE_NAME, SESSION_REF_COOKIE_NAME, assertCookieWithinLimit, defaultOAuthCookieOptions, defaultSessionCookieOptions } from "../cookies.js";
 import { createLogger } from "../logger.js";
 import { classifyRefreshFailure, getOAuthErrorLogContext } from "../oauth-logging.js";
 import { SESSION_EVENT, logSessionEvent } from "../session-events.js";
 import { buildOidcLogoutUrl, buildPKCEOptions, buildSessionFromTokens, discoverAndBuildAuthorizationUrl, exchangeAuthorizationCode, validateReturnUrl } from "../oauth.js";
 import { refreshSession } from "../session-refresh.js";
-import { getSessionSecret } from "../utils.js";
+import { createEncryptedJWT, decryptJWT, generateToken, hexToUint8Array, sha256 } from "../utils.js";
+import { isSession } from "../session-validation.js";
 import { decodeIdTokenCookie, encodeSessionCookies, tryDecodeSessionCookies } from "../session-cookies.js";
-//#region src/server/session.ts
-var logger$4 = createLogger({ namespace: "fides-auth:server:session" });
+// src/server/session-store.ts
+/**
+* In-memory store for tests and single-instance development. Sessions do not
+* survive a restart, and expired records are dropped on read.
+*/
+function createMemorySessionStore() {
+	const records = /* @__PURE__ */ new Map();
+	const locks = /* @__PURE__ */ new Map();
+	return {
+		get(key) {
+			const record = records.get(key);
+			if (!record) return null;
+			if (!(Date.parse(record.expiresAt) > Date.now())) {
+				records.delete(key);
+				return null;
+			}
+			return record;
+		},
+		set(key, record) {
+			records.set(key, record);
+		},
+		delete(key) {
+			records.delete(key);
+		},
+		withLock(key, fn) {
+			const run = (locks.get(key) ?? Promise.resolve()).then(fn);
+			const settled = run.then(() => void 0, () => void 0);
+			locks.set(key, settled);
+			settled.then(() => {
+				if (locks.get(key) === settled) locks.delete(key);
+			});
+			return run;
+		}
+	};
+}
+// src/server/session-persistence.ts
+var logger$7 = createLogger({ namespace: "fides-auth:server:session-persistence" });
+/** A missing or malformed session secret: a configuration error, never a bad cookie. */
+var SessionSecretError = class extends TypeError {
+	name = "SessionSecretError";
+};
+/** Throws unless `secret` is the 32 bytes A256GCM needs. Never echoes the secret. */
+function assertSessionSecret(secret) {
+	if (!secret || secret.length === 0) throw new SessionSecretError("fides-auth: session secret is missing or empty");
+	if (!(secret instanceof Uint8Array ? secret.length === 32 : typeof secret === "string" && /^[0-9a-fA-F]{64}$/.test(secret))) throw new SessionSecretError("fides-auth: session secret must be 32 bytes (64 hex characters or a Uint8Array)");
+}
+/** Accepts the pre-0.15 bare secret wherever a persistence is expected. */
+function resolvePersistence(value) {
+	return typeof value === "object" && value !== null && !(value instanceof Uint8Array) ? value : cookiePersistence(value);
+}
+/** The configured `persistence`, else the bare `secret`. */
+function persistenceFrom(config) {
+	if (config.secret === void 0) return config.persistence;
+	return config.persistence ?? config.secret;
+}
+var SPLIT_COOKIE_NAMES = [
+	SESSION_COOKIE_NAME,
+	ACCESS_TOKEN_COOKIE_NAME,
+	ID_TOKEN_COOKIE_NAME
+];
+/** Deletes the `session`, `session_at` and `session_it` cookies. */
+async function clearSessionCookies(cookies) {
+	for (const name of SPLIT_COOKIE_NAMES) await cookies.delete(name);
+}
 /** Applies the browser size guard to one cookie value; logs as it nears the limit. */
 function checkSize(name, value) {
 	const size = assertCookieWithinLimit(name, value);
-	if (size >= 3500) logger$4.info({
+	if (size >= 3500) logger$7.info({
 		cookieName: name,
 		size
 	}, "Cookie approaching browser size limit");
 	return size;
 }
+/**
+* The default: the session encrypted into the `session`, `session_at` and
+* `session_it` cookies.
+*/
+function cookiePersistence(secret) {
+	return {
+		mode: "cookie",
+		async write(cookies, session) {
+			assertSessionSecret(secret);
+			const encoded = await encodeSessionCookies(session, secret);
+			const values = [
+				[SESSION_COOKIE_NAME, encoded.session],
+				[ACCESS_TOKEN_COOKIE_NAME, encoded.accessToken],
+				[ID_TOKEN_COOKIE_NAME, encoded.idToken]
+			];
+			let cookieBytes = 0;
+			for (const [name, value] of values) if (value) cookieBytes += checkSize(name, value);
+			for (const [name, value] of values) if (value) await cookies.set(name, value, defaultSessionCookieOptions);
+			else await cookies.delete(name);
+			return {
+				cookieValue: encoded.session,
+				cookieBytes
+			};
+		},
+		async read(cookies) {
+			assertSessionSecret(secret);
+			return tryDecodeSessionCookies({
+				session: await cookies.get("session") ?? null,
+				accessToken: await cookies.get("session_at") ?? null,
+				idToken: await cookies.get("session_it") ?? null
+			}, secret);
+		},
+		async readIdToken(cookies) {
+			assertSessionSecret(secret);
+			const raw = await cookies.get(ID_TOKEN_COOKIE_NAME);
+			return raw ? decodeIdTokenCookie(raw, secret) : void 0;
+		},
+		async clear(cookies) {
+			assertSessionSecret(secret);
+			await clearSessionCookies(cookies);
+		}
+	};
+}
+/**
+* The session in a {@link SessionStore}; the browser holds only a random
+* 256-bit handle. The store is keyed by `SHA-256(handle)`, so neither a store
+* dump nor a logged key can be replayed as a cookie, and the record is
+* encrypted under `secret`, so a dump alone yields no tokens.
+*/
+function serverPersistence(options) {
+	const { store, secret, cookieName = SESSION_REF_COOKIE_NAME, sessionDurationDays = 30 } = options;
+	const maxAge = sessionDurationDays * 24 * 60 * 60;
+	const inflight = /* @__PURE__ */ new Map();
+	/** The handle the request carries and the store key it maps to. */
+	async function locate(cookies) {
+		const handle = await cookies.get(cookieName);
+		return handle ? {
+			handle,
+			key: await sha256(handle)
+		} : null;
+	}
+	/** Drops split cookies left behind by cookie persistence, when there are any. */
+	async function clearSplitCookies(cookies) {
+		for (const name of SPLIT_COOKIE_NAMES) if (await cookies.get(name)) await cookies.delete(name);
+	}
+	async function readRecord(key) {
+		const record = await store.get(key);
+		if (!record) return {
+			session: null,
+			reason: "session_not_found"
+		};
+		if (!(Date.parse(record.expiresAt) > Date.now())) {
+			await store.delete(key);
+			return {
+				session: null,
+				reason: "session_not_found"
+			};
+		}
+		let payload;
+		try {
+			payload = await decryptJWT(record.data, secret);
+		} catch (error) {
+			logger$7.warn({
+				error,
+				sid: record.sid
+			}, "Stored session would not decrypt");
+			return {
+				session: null,
+				reason: "unreadable_session"
+			};
+		}
+		if (!isSession(payload)) {
+			logger$7.warn({ sid: record.sid }, "Stored session has the wrong shape");
+			return {
+				session: null,
+				reason: "unreadable_session"
+			};
+		}
+		return { session: payload };
+	}
+	return {
+		mode: "server",
+		async write(cookies, session, { continuation = false } = {}) {
+			assertSessionSecret(secret);
+			if (!isSession(session)) throw new TypeError("A session needs a tokens or user object");
+			const current = await locate(cookies);
+			await clearSplitCookies(cookies);
+			const data = await createEncryptedJWT(session, secret);
+			if (continuation && current) {
+				const existing = await store.get(current.key);
+				if (existing) await store.set(current.key, {
+					data,
+					expiresAt: existing.expiresAt,
+					sid: session.sid
+				});
+				else logger$7.info({ sid: session.sid }, "Session ended during refresh; not persisted");
+				return { cookieValue: current.handle };
+			}
+			if (current) await store.delete(current.key);
+			const handle = generateToken(32);
+			const key = await sha256(handle);
+			const expiresAt = new Date(Date.now() + maxAge * 1e3).toISOString();
+			await store.set(key, {
+				data,
+				expiresAt,
+				sid: session.sid
+			});
+			await cookies.set(cookieName, handle, {
+				...defaultSessionCookieOptions,
+				maxAge
+			});
+			return { cookieValue: handle };
+		},
+		async read(cookies) {
+			assertSessionSecret(secret);
+			const current = await locate(cookies);
+			if (!current) return {
+				session: null,
+				reason: await cookies.get("session") ? "stale_legacy_session" : "no_session_cookie"
+			};
+			return readRecord(current.key);
+		},
+		async readIdToken(cookies) {
+			assertSessionSecret(secret);
+			const current = await locate(cookies);
+			if (!current) return void 0;
+			return (await readRecord(current.key)).session?.tokens?.idToken;
+		},
+		async clear(cookies) {
+			assertSessionSecret(secret);
+			const current = await locate(cookies);
+			if (current) {
+				await store.delete(current.key);
+				await cookies.delete(cookieName);
+			}
+			await clearSplitCookies(cookies);
+		},
+		async exclusive(cookies, fn) {
+			assertSessionSecret(secret);
+			const current = await locate(cookies);
+			if (!current) return fn();
+			const running = inflight.get(current.key);
+			if (running) return running;
+			const run = (store.withLock ? store.withLock(current.key, fn) : fn()).finally(() => {
+				inflight.delete(current.key);
+			});
+			inflight.set(current.key, run);
+			return run;
+		}
+	};
+}
+// src/server/session.ts
+var logger$6 = createLogger({ namespace: "fides-auth:server:session" });
 /** Seconds until the access token expires, for the `expiresIn` log field. */
 function expiresInSeconds(session) {
 	const at = session.tokens?.accessTokenExpiresAt;
@@ -25,38 +261,36 @@ function expiresInSeconds(session) {
 	return Number.isFinite(ms) ? Math.round((ms - Date.now()) / 1e3) : void 0;
 }
 /**
-* Encrypts a session and writes it across the "session", "session_at" and
-* "session_it" cookies, clearing the split-out cookies the session has no token for.
+* Persists a session and raises its lifecycle event.
 *
-* @returns The encrypted JWT stored in the main "session" cookie.
+* With a secret, or {@link cookiePersistence}, the session is encrypted across
+* the "session", "session_at" and "session_it" cookies. With
+* {@link serverPersistence} it goes to the store and the browser gets a handle.
+*
+* @returns The value written to the main session cookie: the encrypted session,
+* or the handle. Either is a bearer secret.
 */
-async function persistSession(store, session, secret, options = {}) {
-	const encoded = await encodeSessionCookies(session, secret);
-	const values = [
-		[SESSION_COOKIE_NAME, encoded.session],
-		[ACCESS_TOKEN_COOKIE_NAME, encoded.accessToken],
-		[ID_TOKEN_COOKIE_NAME, encoded.idToken]
-	];
-	let cookieBytes = 0;
-	for (const [name, value] of values) if (value) cookieBytes += checkSize(name, value);
-	for (const [name, value] of values) if (value) await store.set(name, value, defaultSessionCookieOptions);
-	else await store.delete(name);
-	if (options.event === SESSION_EVENT.CREATED) logSessionEvent(logger$4, {
+async function persistSession(store, session, persistence, options = {}) {
+	const target = resolvePersistence(persistence);
+	const written = await target.write(store, session, { continuation: options.event === SESSION_EVENT.REFRESHED });
+	if (options.event === SESSION_EVENT.CREATED) logSessionEvent(logger$6, {
 		event: SESSION_EVENT.CREATED,
 		sid: session.sid,
 		hasRefreshToken: !!session.tokens?.refreshToken,
 		scopes: session.scopes,
 		expiresIn: expiresInSeconds(session),
-		cookieBytes
+		cookieBytes: written.cookieBytes,
+		persistence: target.mode
 	});
-	else if (options.event === SESSION_EVENT.REFRESHED) logSessionEvent(logger$4, {
+	else if (options.event === SESSION_EVENT.REFRESHED) logSessionEvent(logger$6, {
 		event: SESSION_EVENT.REFRESHED,
 		sid: session.sid,
 		expiresIn: expiresInSeconds(session),
 		rotatedRefreshToken: options.rotatedRefreshToken ?? false,
-		cookieBytes
+		cookieBytes: written.cookieBytes,
+		persistence: target.mode
 	});
-	return encoded.session;
+	return written.cookieValue;
 }
 /**
 * Reads and reassembles the current session, reporting why when there isn't one.
@@ -66,16 +300,13 @@ async function persistSession(store, session, secret, options = {}) {
 * endpoint logs. Does not log on its own — the caller owns the request context
 * and decides whether a missing session is worth a line.
 */
-async function tryReadSession(store, secret) {
+async function tryReadSession(store, persistence) {
 	try {
-		return await tryDecodeSessionCookies({
-			session: await store.get("session") ?? null,
-			accessToken: await store.get("session_at") ?? null,
-			idToken: await store.get("session_it") ?? null
-		}, secret);
+		return await resolvePersistence(persistence).read(store);
 	} catch (error) {
-		if (error instanceof Error && error.message.includes("worker")) logger$4.error({ error }, "Worker thread error reading session");
-		else logger$4.error({ error }, "Unexpected error reading session");
+		if (error instanceof SessionSecretError) throw error;
+		if (error instanceof Error && error.message.includes("worker")) logger$6.error({ error }, "Worker thread error reading session");
+		else logger$6.error({ error }, "Unexpected error reading session");
 		return {
 			session: null,
 			reason: "unreadable_session"
@@ -83,14 +314,13 @@ async function tryReadSession(store, secret) {
 	}
 }
 /**
-* Reads and reassembles the current session from the cookie store, or null when
-* there is none. Decode/validation rules live in `decodeSessionCookies`;
-* the returned session may carry an expired access token.
+* Reads and reassembles the current session, or null when there is none. The
+* returned session may carry an expired access token.
 *
 * Prefer {@link tryReadSession} when you want to log *why* there is no session.
 */
-async function readSession(store, secret) {
-	return (await tryReadSession(store, secret)).session;
+async function readSession(store, persistence) {
+	return (await tryReadSession(store, persistence)).session;
 }
 /**
 * Refreshes the stored session and persists the result, reporting why on failure.
@@ -100,14 +330,50 @@ async function readSession(store, secret) {
 * provider" into the same `null`, and a caller that logs the user out on both
 * ends sessions that were never actually invalid. Only `invalid_grant` is
 * terminal — see {@link classifyRefreshFailure}.
+*
+* Under server persistence, refreshes of one session are serialized: concurrent
+* callers get the first refresh's result rather than each spending the refresh
+* token, which with rotation would leave all but one holding a dead one.
 */
-async function tryRefreshSessionInStore(store, config, secret, options = {}) {
-	const read = await tryReadSession(store, secret);
+async function tryRefreshSessionInStore(store, config, persistence, options = {}) {
+	const target = resolvePersistence(persistence);
+	const read = await tryReadSession(store, target);
 	const current = read.session;
 	if (!current) return {
 		ok: false,
 		reason: read.reason
 	};
+	if (!current.tokens?.refreshToken) return {
+		ok: false,
+		reason: "no_refresh_token",
+		sid: current.sid
+	};
+	if (!target.exclusive) return refreshNow(store, target, config, current, options);
+	return target.exclusive(store, async () => {
+		const latest = await tryReadSession(store, target);
+		if (!latest.session) return {
+			ok: false,
+			reason: latest.reason,
+			sid: current.sid
+		};
+		if (refreshedSince(current, latest.session)) return alreadyRefreshed(current, latest.session);
+		return refreshNow(store, target, config, latest.session, options);
+	});
+}
+/** Whether `after` carries tokens `before` did not — someone refreshed in between. */
+function refreshedSince(before, after) {
+	return after.tokens?.accessToken !== before.tokens?.accessToken || after.tokens?.refreshToken !== before.tokens?.refreshToken;
+}
+function alreadyRefreshed(before, after) {
+	logger$6.debug({ sid: after.sid }, "Session already refreshed by a concurrent request");
+	return {
+		ok: true,
+		session: after,
+		rotatedRefreshToken: after.tokens?.refreshToken !== before.tokens?.refreshToken
+	};
+}
+/** The refresh itself: exchange, persist, classify. */
+async function refreshNow(store, target, config, current, options) {
 	if (!current.tokens?.refreshToken) return {
 		ok: false,
 		reason: "no_refresh_token",
@@ -116,7 +382,7 @@ async function tryRefreshSessionInStore(store, config, secret, options = {}) {
 	try {
 		const updated = await refreshSession(current, config, options);
 		if (!updated) {
-			logSessionEvent(logger$4, {
+			logSessionEvent(logger$6, {
 				event: SESSION_EVENT.REFRESH_FAILED,
 				sid: current.sid,
 				cause: "idp_error",
@@ -130,7 +396,7 @@ async function tryRefreshSessionInStore(store, config, secret, options = {}) {
 			};
 		}
 		const rotatedRefreshToken = updated.tokens?.refreshToken !== current.tokens.refreshToken;
-		await persistSession(store, updated, secret, {
+		await persistSession(store, updated, target, {
 			event: SESSION_EVENT.REFRESHED,
 			rotatedRefreshToken
 		});
@@ -141,7 +407,11 @@ async function tryRefreshSessionInStore(store, config, secret, options = {}) {
 		};
 	} catch (error) {
 		const cause = classifyRefreshFailure(error);
-		logSessionEvent(logger$4, {
+		if (cause === "invalid_grant" && target.exclusive) {
+			const latest = await tryReadSession(store, target);
+			if (latest.session && refreshedSince(current, latest.session)) return alreadyRefreshed(current, latest.session);
+		}
+		logSessionEvent(logger$6, {
 			event: SESSION_EVENT.REFRESH_FAILED,
 			sid: current.sid,
 			cause,
@@ -166,94 +436,445 @@ async function tryRefreshSessionInStore(store, config, secret, options = {}) {
 * refresh token apart from an unreachable provider, and treating the two alike
 * logs out users whose sessions are still valid.
 */
-async function refreshSessionInStore(store, config, secret, options = {}) {
-	const result = await tryRefreshSessionInStore(store, config, secret, options);
+async function refreshSessionInStore(store, config, persistence, options = {}) {
+	const result = await tryRefreshSessionInStore(store, config, persistence, options);
 	return result.ok ? result.session : null;
 }
 /**
-* Reads the raw ID token independently of the session cookies — logout needs
-* the hint even when {@link readSession} returns null.
+* Reads the raw ID token independently of session validity — logout needs the
+* hint even when {@link readSession} returns null.
 */
-async function readIdToken(store, secret) {
+async function readIdToken(store, persistence) {
 	try {
-		const raw = await store.get(ID_TOKEN_COOKIE_NAME);
-		return raw ? await decodeIdTokenCookie(raw, secret) : void 0;
+		return await resolvePersistence(persistence).readIdToken(store);
 	} catch (error) {
-		logger$4.error({ error }, "Unexpected error reading ID token");
+		if (error instanceof SessionSecretError) throw error;
+		logger$6.error({ error }, "Unexpected error reading ID token");
 		return;
 	}
 }
-/** Deletes all session cookies. */
+/** Ends the session: deletes the cookies and, under server persistence, the record. */
 async function clearSession(store, options = {}) {
-	await store.delete(SESSION_COOKIE_NAME);
-	await store.delete(ACCESS_TOKEN_COOKIE_NAME);
-	await store.delete(ID_TOKEN_COOKIE_NAME);
-	if (options.trigger) logSessionEvent(logger$4, {
+	if (options.persistence) await resolvePersistence(options.persistence).clear(store);
+	else await clearSessionCookies(store);
+	if (options.trigger) logSessionEvent(logger$6, {
 		event: SESSION_EVENT.CLEARED,
 		sid: options.sid,
 		trigger: options.trigger
 	});
 }
-//#endregion
-//#region src/server/oidc-login.ts
+// src/server/login-transaction.ts
+var logger$5 = createLogger({ namespace: "fides-auth:server:login-transaction" });
+var COOKIE_NAME = "oauth_tx_";
+var HOST_PREFIX = "__Host-";
+/** Live logins per browser. Another login evicts the oldest. */
+var MAX_TRANSACTIONS = 3;
+/**
+* A longer returnTo is dropped, not stored in a cookie sent with every request.
+* Measured as serialized: JSON escaping grows a control character sixfold.
+*/
+var MAX_RETURN_TO_BYTES = 1024;
+var DEFAULT_MAX_AGE_MS = 6e5;
+var KEY_INFO = "fides-auth login-tx";
+var CallbackValidationError = class extends Error {
+	reason;
+	idpError;
+	idpErrorDescription;
+	constructor(reason, idpError, idpErrorDescription) {
+		super(`OIDC callback rejected: ${reason}`);
+		this.reason = reason;
+		this.idpError = idpError;
+		this.idpErrorDescription = idpErrorDescription;
+		this.name = "CallbackValidationError";
+	}
+};
+/** Starts a login transaction from the PKCE parameters sent to the authorize endpoint. */
+function createTransaction(pkce, { returnTo } = {}) {
+	let kept = returnTo || void 0;
+	if (kept && new TextEncoder().encode(JSON.stringify(kept)).length > MAX_RETURN_TO_BYTES) {
+		logger$5.warn({ length: kept.length }, "returnTo too long, dropped");
+		kept = void 0;
+	}
+	return {
+		state: pkce.state,
+		codeVerifier: pkce.code_verifier,
+		...kept ? { returnTo: kept } : {},
+		createdAt: Date.now()
+	};
+}
+/**
+* Seals the transaction into a random free `__Host-oauth_tx_<n>` slot, or the
+* oldest login's. Throws `CookieTooLargeError` if it would not fit in a cookie.
+*/
+async function persistTransaction(cookies, transaction, secret, { secure = true } = {}) {
+	const key = await transactionKey(secret);
+	const slots = await readSlots(cookies, key, secure);
+	const free = slots.filter((candidate) => !candidate.transaction);
+	const slot = free[Math.floor(Math.random() * free.length)] ?? slots.reduce((oldest, candidate) => (candidate.transaction?.createdAt ?? 0) < (oldest.transaction?.createdAt ?? 0) ? candidate : oldest);
+	const value = await createEncryptedJWT(transaction, key);
+	assertCookieWithinLimit(slot.name, value);
+	await cookies.set(slot.name, value, {
+		...defaultOAuthCookieOptions,
+		secure
+	});
+}
+/** The transaction for `state`, or null when none is stored or it does not open under `secret`. */
+async function readTransaction(cookies, state, secret, { secure = true } = {}) {
+	const slots = await readSlots(cookies, await transactionKey(secret), secure);
+	const match = findSlot(slots, state);
+	if (match) return match.transaction;
+	if (slots.some((slot) => slot.value && !slot.transaction)) logger$5.warn("Unreadable login transaction cookie");
+	return null;
+}
+/** Deletes the transaction cookie for `state`, leaving other logins alone. */
+async function clearTransaction(cookies, state, secret, { secure = true } = {}) {
+	const match = findSlot(await readSlots(cookies, await transactionKey(secret), secure), state);
+	if (!match) return;
+	if (secure) await cookies.set(match.name, "", {
+		...defaultOAuthCookieOptions,
+		secure,
+		maxAge: 0
+	});
+	else await cookies.delete(match.name);
+}
+/** What the handlers use: Secure and `__Host-` unless the callback is plain http. */
+function transactionCookieOptions(redirectUri) {
+	return { secure: !/^http:/i.test(redirectUri) };
+}
+/**
+* Checks the callback query against its transaction and returns the authorization
+* code. Throws {@link CallbackValidationError}.
+*/
+function validateCallback(query, transaction, { maxAgeMs = DEFAULT_MAX_AGE_MS } = {}) {
+	if (!timingSafeEqual(query.get("state") ?? "", transaction.state)) throw new CallbackValidationError("state_mismatch");
+	if (Date.now() - transaction.createdAt > maxAgeMs) throw new CallbackValidationError("transaction_expired");
+	const error = query.get("error");
+	if (error !== null) throw new CallbackValidationError("idp_error", error, query.get("error_description") ?? void 0);
+	const code = query.get("code");
+	if (!code) throw new CallbackValidationError("missing_code");
+	return code;
+}
+/** HKDF-SHA-256 of the secret, so a transaction and a session never share a key. */
+async function transactionKey(secret) {
+	assertSessionSecret(secret);
+	const ikm = typeof secret === "string" ? hexToUint8Array(secret) : secret;
+	const base = await crypto.subtle.importKey("raw", ikm, "HKDF", false, ["deriveBits"]);
+	const bits = await crypto.subtle.deriveBits({
+		name: "HKDF",
+		hash: "SHA-256",
+		salt: /* @__PURE__ */ new Uint8Array(),
+		info: new TextEncoder().encode(KEY_INFO)
+	}, base, 256);
+	return new Uint8Array(bits);
+}
+async function readSlots(cookies, key, secure) {
+	const prefix = secure ? HOST_PREFIX : "";
+	const names = Array.from({ length: MAX_TRANSACTIONS }, (_, i) => `${prefix}${COOKIE_NAME}${i}`);
+	return Promise.all(names.map(async (name) => {
+		const value = await cookies.get(name);
+		return {
+			name,
+			value,
+			transaction: value ? await open(value, key) : null
+		};
+	}));
+}
+function findSlot(slots, state) {
+	for (const { name, transaction } of slots) if (transaction && timingSafeEqual(state, transaction.state)) return {
+		name,
+		transaction
+	};
+}
+/** The sealed transaction, or null when the value is forged, malformed or under another key. */
+async function open(value, key) {
+	try {
+		const sealed = await decryptJWT(value, key);
+		if (typeof sealed.state === "string" && typeof sealed.codeVerifier === "string" && typeof sealed.createdAt === "number" && (sealed.returnTo === void 0 || typeof sealed.returnTo === "string")) return {
+			state: sealed.state,
+			codeVerifier: sealed.codeVerifier,
+			returnTo: sealed.returnTo,
+			createdAt: sealed.createdAt
+		};
+	} catch {}
+	return null;
+}
+/** Compares in time that depends only on the expected value's length. */
+function timingSafeEqual(received, expected) {
+	const encoder = new TextEncoder();
+	const a = encoder.encode(received);
+	const b = encoder.encode(expected);
+	let diff = a.length ^ b.length;
+	for (let i = 0; i < b.length; i++) diff |= (a[i] ?? 0) ^ (b[i] ?? 0);
+	return diff === 0;
+}
+// src/server/authorized-fetch.ts
+var logger$4 = createLogger({ namespace: "fides-auth:server:authorized-fetch" });
+var DEFAULT_TIMEOUT_MS = 1e4;
+/** A failed {@link authorizedFetch}. Never carries the token or the query string. */
+var AuthorizedFetchError = class extends Error {
+	reason;
+	/** HTTP status, for `http_error` and `refresh_failed`. */
+	status;
+	method;
+	/** Origin and path only. */
+	url;
+	/** Why the refresh failed. Only `cause: 'invalid_grant'` means the user must log in again. */
+	refreshFailure;
+	constructor(reason, details = {}) {
+		const { status, method, url, refreshFailure, response, cause } = details;
+		const target = url ? ` for ${method ?? "GET"} ${url}` : "";
+		super(`authorizedFetch ${reason}${status ? ` (${status})` : ""}${target}`, cause === void 0 ? void 0 : { cause });
+		this.name = "AuthorizedFetchError";
+		this.reason = reason;
+		this.status = status;
+		this.method = method;
+		this.url = url;
+		this.refreshFailure = refreshFailure;
+		Object.defineProperty(this, "response", {
+			value: response,
+			enumerable: false
+		});
+	}
+};
+/**
+* Calls an API with the session's access token.
+*
+* @throws {AuthorizedFetchError} on a disallowed URL, non-2xx, timeout, network error or failed refresh.
+* @throws {TypeError} when `allowedBase` is not an http(s) URL without credentials.
+*/
+async function authorizedFetch(session, url, options) {
+	const { allowedBase, parse, timeoutMs = DEFAULT_TIMEOUT_MS, refresh, ...init } = options;
+	const target = resolveAllowedUrl(url, allowedBase);
+	const request = {
+		method: (init.method ?? "GET").toUpperCase(),
+		url: redactUrl(target)
+	};
+	let current = session;
+	let attempt = await send(current, target, init, timeoutMs, request);
+	let refreshed = false;
+	if (attempt.response.status === 401 && refresh) {
+		await attempt.response.body?.cancel().catch(() => void 0);
+		attempt.unlink();
+		logger$4.debug(request, "Got 401, refreshing the session once");
+		current = await refreshOnce(refresh, request);
+		refreshed = true;
+		attempt = await send(current, target, init, timeoutMs, request);
+	}
+	const { response, timeout, unlink } = attempt;
+	if (!response.ok) throw new AuthorizedFetchError("http_error", {
+		...request,
+		status: response.status,
+		response
+	});
+	try {
+		const data = parse ? await parse(response) : void 0;
+		if (!response.body || response.bodyUsed) unlink();
+		return {
+			response,
+			data,
+			session: current,
+			refreshed
+		};
+	} catch (error) {
+		unlink();
+		if (init.signal?.aborted) throw error;
+		throw new AuthorizedFetchError(error === timeout.reason ? "timeout" : "parse_failed", {
+			...request,
+			status: response.status,
+			cause: error
+		});
+	}
+}
+/** Resolves `url` against the base and throws unless it stays under it. */
+function resolveAllowedUrl(url, allowedBase) {
+	const base = new URL(allowedBase);
+	if (base.protocol !== "https:" && base.protocol !== "http:") throw new TypeError("authorizedFetch: allowedBase must be an http(s) URL");
+	if (base.username || base.password) throw new TypeError("authorizedFetch: allowedBase must not carry credentials");
+	if (!base.pathname.endsWith("/")) base.pathname += "/";
+	let target;
+	try {
+		target = new URL(url, base);
+	} catch {
+		throw new AuthorizedFetchError("url_not_allowed");
+	}
+	const underBase = target.pathname.startsWith(base.pathname) || `${target.pathname}/` === base.pathname;
+	if (target.username || target.password || target.origin !== base.origin || !underBase) {
+		logger$4.warn({
+			url: redactUrl(target),
+			allowedBase: redactUrl(base)
+		}, "Refused to send the access token outside allowedBase");
+		throw new AuthorizedFetchError("url_not_allowed", { url: redactUrl(target) });
+	}
+	return target;
+}
+async function send(session, target, init, timeoutMs, request) {
+	const token = session.tokens?.accessToken;
+	if (!token) throw new AuthorizedFetchError("no_access_token", request);
+	const headers = new Headers(init.headers);
+	headers.set("Authorization", `Bearer ${token}`);
+	const timeout = AbortSignal.timeout(timeoutMs);
+	const { signal, unlink } = linkSignals(timeout, init.signal);
+	try {
+		return {
+			response: await fetch(target, {
+				...init,
+				headers,
+				signal,
+				redirect: "error"
+			}),
+			timeout,
+			unlink
+		};
+	} catch (error) {
+		unlink();
+		if (init.signal?.aborted) throw error;
+		throw new AuthorizedFetchError(timeout.aborted ? "timeout" : "network_error", {
+			...request,
+			cause: error
+		});
+	}
+}
+/**
+* A signal that aborts when the timeout or the caller's signal does, with that signal's
+* reason, and `unlink` to remove the listeners. `AbortSignal.any` would need Node 18.17.
+*/
+function linkSignals(timeout, caller) {
+	if (!caller) return {
+		signal: timeout,
+		unlink: () => void 0
+	};
+	const sources = [caller, timeout];
+	const controller = new AbortController();
+	const unlink = () => {
+		for (const source of sources) source.removeEventListener("abort", onAbort);
+	};
+	const onAbort = () => {
+		unlink();
+		controller.abort(sources.find((source) => source.aborted)?.reason);
+	};
+	if (sources.some((source) => source.aborted)) onAbort();
+	else for (const source of sources) source.addEventListener("abort", onAbort);
+	return {
+		signal: controller.signal,
+		unlink
+	};
+}
+async function refreshOnce(refresh, request) {
+	let result;
+	try {
+		result = toRefreshResult(await refresh());
+	} catch (error) {
+		throw new AuthorizedFetchError("refresh_failed", {
+			...request,
+			status: 401,
+			cause: error
+		});
+	}
+	if (!result.ok) {
+		const refreshFailure = {
+			reason: result.reason,
+			cause: result.cause
+		};
+		throw new AuthorizedFetchError("refresh_failed", {
+			...request,
+			status: 401,
+			refreshFailure
+		});
+	}
+	return result.session;
+}
+/** Accepts both `tryRefreshSessionInStore` and `refreshSessionInStore` results. */
+function toRefreshResult(value) {
+	if (!value) return {
+		ok: false,
+		reason: "refresh_failed"
+	};
+	if ("ok" in value) return value;
+	return {
+		ok: true,
+		session: value,
+		rotatedRefreshToken: false
+	};
+}
+/** Origin and path: never credentials, query or fragment. */
+function redactUrl(url) {
+	return `${url.origin}${url.pathname}`;
+}
+// src/server/oidc-login.ts
 var logger$3 = createLogger({ namespace: "fides-auth:server:oidc-login" });
-var defaultValidateReturnTo = (raw) => /^\/(?!\/)/.test(raw) ? raw : null;
+var defaultValidateReturnTo = (raw) => /^\/(?!\/)[\x20-\x7e]*$/.test(raw) ? raw : null;
 /**
-* Handles OIDC login initiation: rate-limit, build PKCE, persist it, and redirect
-* to the authorization endpoint.
+* Handles OIDC login initiation: rate-limit, build PKCE, seal it into a login
+* transaction, and redirect to the authorization endpoint.
 */
 async function handleOidcLogin(request, config) {
 	const { oauthConfig, cookies, rateLimit, validateReturnTo = defaultValidateReturnTo } = config;
+	assertSessionSecret(config.secret);
 	if (rateLimit && !await rateLimit()) {
 		logger$3.warn("Rate limit exceeded");
 		return new Response("Too many requests", { status: 429 });
 	}
 	const rawReturnTo = new URL(request.url).searchParams.get("returnTo");
 	const returnTo = rawReturnTo ? validateReturnTo(rawReturnTo) : null;
-	const pkce = await buildPKCEOptions(oauthConfig);
+	const parameters = await config.authorizationParameters?.(request);
+	const pkce = await buildPKCEOptions(oauthConfig, { parameters });
 	const authorizationUrl = await discoverAndBuildAuthorizationUrl(oauthConfig, pkce);
+	const transaction = createTransaction(pkce, { returnTo });
+	const secret = config.secret;
+	const cookieOptions = transactionCookieOptions(oauthConfig.redirect_uri);
+	try {
+		await persistTransaction(cookies, transaction, secret, cookieOptions);
+	} catch (error) {
+		if (!(error instanceof CookieTooLargeError) || !transaction.returnTo) throw error;
+		logger$3.warn({ size: error.size }, "Login transaction too large; dropped returnTo");
+		await persistTransaction(cookies, {
+			...transaction,
+			returnTo: void 0
+		}, secret, cookieOptions);
+	}
 	logger$3.info("Redirecting to OIDC provider for login");
-	await cookies.set("oauth_state", pkce.state, defaultOAuthCookieOptions);
-	await cookies.set("oauth_code_verifier", pkce.code_verifier, defaultOAuthCookieOptions);
-	if (returnTo) await cookies.set("returnTo", returnTo, defaultOAuthCookieOptions);
-	else await cookies.delete("returnTo");
 	return new Response(null, {
 		status: 302,
 		headers: { Location: authorizationUrl.toString() }
 	});
 }
-//#endregion
-//#region src/server/oidc-callback.ts
+// src/server/oidc-callback.ts
 var logger$2 = createLogger({ namespace: "fides-auth:server:oidc-callback" });
+var IDP_ERROR_CODE = /^[a-z0-9_]{1,64}$/;
 /**
 * Handles the OIDC callback: rate-limit, exchange the code for tokens, persist the
 * session across the cookie store, and redirect to a validated returnTo.
 */
 async function handleOidcCallback(request, config) {
-	const { oauthConfig, applicationUrl, cookies, rateLimit, secret = getSessionSecret(), rolesClaim = "roles", defaultRedirectPath = "/", validateReturnTo } = config;
+	const { oauthConfig, applicationUrl, cookies, secret, rateLimit, rolesClaim = "roles", mapSession, defaultRedirectPath = "/", validateReturnTo } = config;
+	assertSessionSecret(secret);
+	const persistence = config.persistence ?? secret;
+	const txCookie = transactionCookieOptions(oauthConfig.redirect_uri);
 	if (rateLimit && !await rateLimit()) {
 		logger$2.warn("Rate limit exceeded");
 		return new Response("Too many requests", { status: 429 });
 	}
+	const currentUrl = new URL(request.url);
+	const state = currentUrl.searchParams.get("state");
+	const idpError = currentUrl.searchParams.get("error") ?? void 0;
+	const loginEnded = () => idpError === void 0 ? new Response("Please restart the login process.", { status: 400 }) : loginErrorRedirect(applicationUrl, defaultRedirectPath, "login_expired");
 	try {
-		const currentUrl = new URL(request.url);
 		const publicUrl = new URL(applicationUrl);
 		publicUrl.pathname = currentUrl.pathname;
 		publicUrl.search = currentUrl.search;
-		const storedState = await cookies.get("oauth_state");
-		const storedCodeVerifier = await cookies.get("oauth_code_verifier");
-		if (!storedState || !storedCodeVerifier) {
-			logger$2.warn("Missing state or code verifier");
-			return new Response("Please restart the login process.", { status: 400 });
+		const transaction = state ? await readTransaction(cookies, state, secret, txCookie) : null;
+		if (!transaction) {
+			logger$2.warn({ error: idpError }, "Missing login transaction");
+			return loginEnded();
 		}
-		const tokens = await exchangeAuthorizationCode(oauthConfig, publicUrl, storedCodeVerifier, storedState);
-		const session = buildSessionFromTokens(tokens, rolesClaim);
-		await persistSession(cookies, session, secret, { event: SESSION_EVENT.CREATED });
-		const returnTo = await cookies.get("returnTo");
-		await cookies.delete("oauth_state");
-		await cookies.delete("oauth_code_verifier");
-		await cookies.delete("returnTo");
-		const redirectUrl = validateReturnUrl(returnTo ?? null, applicationUrl, defaultRedirectPath, validateReturnTo);
+		validateCallback(currentUrl.searchParams, transaction);
+		const tokens = await exchangeAuthorizationCode(oauthConfig, publicUrl, transaction.codeVerifier, transaction.state);
+		const session = buildSessionFromTokens(tokens, {
+			rolesClaim,
+			mapSession
+		});
+		await persistSession(cookies, session, persistence, { event: SESSION_EVENT.CREATED });
+		const redirectUrl = validateReturnUrl(transaction.returnTo ?? null, applicationUrl, defaultRedirectPath, validateReturnTo);
 		redirectUrl.searchParams.set("login", "success");
 		logger$2.info({
 			sid: session.sid,
@@ -264,6 +885,22 @@ async function handleOidcCallback(request, config) {
 			headers: { Location: redirectUrl.toString() }
 		});
 	} catch (error) {
+		if (error instanceof CallbackValidationError) {
+			if (error.reason === "idp_error") {
+				logger$2.warn({
+					reason: error.reason,
+					error: error.idpError,
+					errorDescription: error.idpErrorDescription
+				}, "Identity provider returned an error");
+				const code = error.idpError ?? "";
+				return loginErrorRedirect(applicationUrl, defaultRedirectPath, IDP_ERROR_CODE.test(code) ? code : "idp_error");
+			}
+			logger$2.warn({
+				reason: error.reason,
+				error: idpError
+			}, "Rejected OIDC callback");
+			return error.reason === "transaction_expired" ? loginEnded() : new Response("Please restart the login process.", { status: 400 });
+		}
 		if (error instanceof CookieTooLargeError) {
 			logger$2.error({
 				error,
@@ -274,10 +911,21 @@ async function handleOidcCallback(request, config) {
 		}
 		logger$2.error({ error }, "OIDC callback error");
 		return new Response("An unexpected error occurred. Please restart the login process.", { status: 500 });
+	} finally {
+		if (state) await clearTransaction(cookies, state, secret, txCookie);
 	}
 }
-//#endregion
-//#region src/server/oidc-logout.ts
+/** Redirects to the default path with `login=error` and a safe error code, never a description. */
+function loginErrorRedirect(applicationUrl, defaultRedirectPath, code) {
+	const redirectUrl = new URL(defaultRedirectPath, applicationUrl);
+	redirectUrl.searchParams.set("login", "error");
+	redirectUrl.searchParams.set("error", code);
+	return new Response(null, {
+		status: 302,
+		headers: { Location: redirectUrl.toString() }
+	});
+}
+// src/server/oidc-logout.ts
 var logger$1 = createLogger({ namespace: "fides-auth:server:oidc-logout" });
 /**
 * Whether the request came from the application itself. POST alone is no defence:
@@ -304,7 +952,8 @@ function isSameOrigin(request, applicationUrl) {
 * unavailable, so the user is always logged out of this application.
 */
 async function handleOidcLogout(request, config) {
-	const { oauthConfig, cookies, postLogoutRedirectUri, secret = getSessionSecret(), rateLimit, state, logoutHint, includeClientId, fallbackRedirectUri = postLogoutRedirectUri, allowedMethods = ["POST"], applicationUrl } = config;
+	const { oauthConfig, cookies, postLogoutRedirectUri, rateLimit, state, logoutHint, includeClientId, fallbackRedirectUri = postLogoutRedirectUri, allowedMethods = ["POST"], applicationUrl } = config;
+	const persistence = persistenceFrom(config);
 	if (!allowedMethods.includes(request.method)) return new Response(null, {
 		status: 405,
 		headers: { Allow: allowedMethods.join(", ") }
@@ -320,12 +969,14 @@ async function handleOidcLogout(request, config) {
 		logger$1.warn("Rate limit exceeded");
 		return new Response("Too many requests", { status: 429 });
 	}
-	const idTokenHint = await readIdToken(cookies, secret);
-	const sid = (await tryReadSession(cookies, secret)).session?.sid;
+	const read = await tryReadSession(cookies, persistence);
+	const idTokenHint = read.session?.tokens?.idToken ?? await readIdToken(cookies, persistence);
+	const sid = read.session?.sid;
 	try {
 		await clearSession(cookies, {
 			trigger: "logout",
-			sid
+			sid,
+			persistence
 		});
 	} catch (error) {
 		logger$1.error({ error }, "Failed to clear session cookies");
@@ -351,8 +1002,7 @@ async function handleOidcLogout(request, config) {
 		headers: { Location: logoutUrl.toString() }
 	});
 }
-//#endregion
-//#region src/server/heartbeat-handler.ts
+// src/server/heartbeat-handler.ts
 var logger = createLogger({ namespace: "fides-auth:server:heartbeat" });
 /**
 * Handles a heartbeat request — refresh the active session if there is one.
@@ -369,7 +1019,8 @@ var logger = createLogger({ namespace: "fides-auth:server:heartbeat" });
 * failures with backoff.
 */
 async function handleHeartbeat(request, config) {
-	const { oauthConfig, cookies, rateLimit, secret = getSessionSecret() } = config;
+	const { oauthConfig, cookies, rateLimit } = config;
+	const persistence = persistenceFrom(config);
 	if (request.method !== "POST") return new Response(null, {
 		status: 405,
 		headers: { Allow: "POST" }
@@ -378,7 +1029,7 @@ async function handleHeartbeat(request, config) {
 		logger.warn("Heartbeat rate limit exceeded");
 		return new Response(null, { status: 429 });
 	}
-	const result = await tryRefreshSessionInStore(cookies, oauthConfig, secret);
+	const result = await tryRefreshSessionInStore(cookies, oauthConfig, persistence);
 	if (result.ok) {
 		logger.debug({ sid: result.session.sid }, "Heartbeat refresh succeeded");
 		return Response.json({ accessTokenExpiresAt: result.session.tokens?.accessTokenExpiresAt ?? null }, { headers: { "Cache-Control": "private, no-store" } });
@@ -415,7 +1066,6 @@ function unauthorized(reason) {
 		headers: { "Cache-Control": "private, no-store" }
 	});
 }
-//#endregion
-export { clearSession, handleHeartbeat, handleOidcCallback, handleOidcLogin, handleOidcLogout, persistSession, readIdToken, readSession, refreshSessionInStore, tryReadSession, tryRefreshSessionInStore };
+export { AuthorizedFetchError, CallbackValidationError, authorizedFetch, clearSession, clearTransaction, cookiePersistence, createMemorySessionStore, createTransaction, handleHeartbeat, handleOidcCallback, handleOidcLogin, handleOidcLogout, persistSession, persistTransaction, readIdToken, readSession, readTransaction, refreshSessionInStore, serverPersistence, transactionCookieOptions, tryReadSession, tryRefreshSessionInStore, validateCallback };
 
 //# sourceMappingURL=index.js.map