@eminuckan/spine 0.3.8 → 0.3.10

package/dist/{server-C3_iNZfj.mjs → server-BJTz5-BE.mjs}

@@ -1,5 +1,5 @@
 import { logger } from "./logging/index.mjs";
-import { S as updateAuthSession, a as createOAuthState, d as destroyAuthSessionsBySid, f as destroyAuthSessionsForUser, g as getOAuthState, i as createAuthSession, l as destroyAuthSessionsByIdentitySession, o as deleteOAuthState, p as getAuthSession, s as destroyAuthSession, t as AUTH_ERROR_COOKIE_PREFIX, v as listAuthSessionDataForUser } from "./redis-session-storage.server-n0lWWyoh.mjs";
+import { D as OAUTH_RECOVERY_TTL_SECONDS, E as OAUTH_RECOVERY_TTL_MS, O as OAUTH_STATE_TTL_MS, T as updateAuthSession, a as createAuthSession, c as deleteOAuthRecoveryRecord, f as destroyAuthSessionsByIdentitySession, g as getAuthSession, h as destroyAuthSessionsForUser, i as consumeOAuthRecoveryRecord, k as OAUTH_STATE_TTL_SECONDS, l as deleteOAuthState, m as destroyAuthSessionsBySid, o as createOAuthRecoveryRecord, s as createOAuthState, t as AUTH_ERROR_COOKIE_PREFIX, u as destroyAuthSession, x as listAuthSessionDataForUser, y as getOAuthState } from "./redis-session-storage.server-DLJ0B7-C.mjs";
 import * as oidc from "openid-client";
 import { createRemoteJWKSet, errors, jwtVerify } from "jose";
 //#region src/http/response.ts
@@ -132,6 +132,268 @@ function serializeTemporaryAuthCookie(name, value, options) {
 	return segments.join("; ");
 }
 //#endregion
+//#region src/auth/callback-errors.ts
+const OAuthCallbackFailureCodes = {
+	StaleTransaction: "stale_transaction",
+	StateMismatch: "state_mismatch",
+	MalformedCallback: "malformed_callback",
+	ApplicationActionFailed: "application_action_failed",
+	TokenExchangeFailed: "token_exchange_failed",
+	SessionCreationFailed: "session_creation_failed",
+	StorageError: "storage_error",
+	ConfigurationError: "configuration_error"
+};
+const OAUTH_CALLBACK_ERROR_BRAND = Symbol.for("@eminuckan/spine/OAuthCallbackError");
+function isOAuthCallbackFailureCode(value) {
+	return typeof value === "string" && Object.values(OAuthCallbackFailureCodes).includes(value);
+}
+function isHeadersLike(value) {
+	return value !== null && typeof value === "object" && typeof value.get === "function" && typeof value.append === "function";
+}
+function getSetCookieValues$1(headers) {
+	const getSetCookie = headers.getSetCookie;
+	if (getSetCookie) return getSetCookie.call(headers);
+	return Array.from(headers).reduce((cookies, [name, value]) => {
+		if (name.toLowerCase() === "set-cookie") cookies.push(value);
+		return cookies;
+	}, []);
+}
+/**
+* A callback failure that consumers can classify without parsing messages.
+*
+* The message is intentionally constant.  Consumers should branch on
+* `code`, not on `message`, and should merge `cleanupHeaders` (or the
+* lossless `cleanupSetCookies` values) with any response they create using
+* repeated `Set-Cookie` appends.
+*/
+var OAuthCallbackError = class extends Error {
+	code;
+	cleanupHeaders;
+	cleanupSetCookies;
+	constructor(code, cleanupHeaders = {}) {
+		super("Authentication failed");
+		this.name = "OAuthCallbackError";
+		this.code = code;
+		this.cleanupHeaders = new Headers(cleanupHeaders);
+		this.cleanupSetCookies = getSetCookieValues$1(this.cleanupHeaders);
+		Object.defineProperty(this, OAUTH_CALLBACK_ERROR_BRAND, {
+			configurable: false,
+			enumerable: false,
+			value: true,
+			writable: false
+		});
+	}
+};
+/**
+* Cross-package-copy safe type guard for callback failures.
+*/
+function isOAuthCallbackError(error) {
+	if (error instanceof OAuthCallbackError) return true;
+	if (error === null || typeof error !== "object") return false;
+	const candidate = error;
+	return candidate[OAUTH_CALLBACK_ERROR_BRAND] === true && isOAuthCallbackFailureCode(candidate.code) && isHeadersLike(candidate.cleanupHeaders);
+}
+/**
+* Only a normal authorization callback whose local transaction is absent or
+* expired may be retried.  All other callback failures fail closed.
+*/
+function isRecoverableOAuthCallbackError(error) {
+	return isOAuthCallbackError(error) && error.code === "stale_transaction";
+}
+//#endregion
+//#region src/auth/oauth-recovery.server.ts
+/**
+* Server-only recovery intent for stale OAuth callbacks.
+*
+* A recovery intent is an opaque, HttpOnly cookie backed by a separate Redis
+* record. Consumers must atomically consume it with the typed stale callback
+* error; the client never supplies a boolean budget or a return URL.
+*/
+const OAUTH_RECOVERY_COOKIE_NAME = `${AUTH_ERROR_COOKIE_PREFIX}_oauth_recovery`;
+function escapeRegExp$1(value) {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function getCookieValue(request) {
+	const cookies = request.headers.get("Cookie");
+	if (!cookies) return null;
+	const cookieRegex = new RegExp(`(?:^|;\\s*)${escapeRegExp$1(OAUTH_RECOVERY_COOKIE_NAME)}=([^;]*)`);
+	const rawValue = cookies.match(cookieRegex)?.[1];
+	if (!rawValue) return null;
+	try {
+		const value = decodeURIComponent(rawValue);
+		return value.length > 0 ? value : null;
+	} catch {
+		return null;
+	}
+}
+function hasCookie(request) {
+	const cookies = request.headers.get("Cookie");
+	if (!cookies) return false;
+	return cookies.split(";").some((part) => {
+		const separator = part.indexOf("=");
+		return separator > 0 && part.slice(0, separator).trim() === OAUTH_RECOVERY_COOKIE_NAME;
+	});
+}
+const SAFE_FALLBACK_COOKIE_PATH = "/";
+function normalizeCookiePath(pathname) {
+	const candidate = pathname.trim();
+	const hasUnsafeCharacter = Array.from(candidate).some((character) => {
+		const code = character.charCodeAt(0);
+		return code <= 31 || code === 127 || character === ";";
+	});
+	if (candidate.length === 0 || !candidate.startsWith("/") || candidate.startsWith("//") || hasUnsafeCharacter) return SAFE_FALLBACK_COOKIE_PATH;
+	return candidate;
+}
+/**
+* Resolve the callback cookie path from a configured redirect URI or the
+* actual callback request. Unsafe path values fall back to `/` rather than
+* being interpolated into a Set-Cookie header.
+*/
+function getOAuthRecoveryCookiePath(source) {
+	try {
+		return normalizeCookiePath((source instanceof Request ? new URL(source.url) : source instanceof URL ? source : new URL(source, source.startsWith("/") ? "http://spine.local" : void 0)).pathname);
+	} catch {
+		return SAFE_FALLBACK_COOKIE_PATH;
+	}
+}
+function serializeRecoveryCookie(ticket, maxAge, callbackPath) {
+	const segments = [
+		`${OAUTH_RECOVERY_COOKIE_NAME}=${encodeURIComponent(ticket)}`,
+		`Path=${callbackPath}`,
+		"HttpOnly",
+		"SameSite=Lax",
+		`Max-Age=${maxAge}`
+	];
+	if (process.env.NODE_ENV === "production") segments.push("Secure");
+	return segments.join("; ");
+}
+function appendRecoveryCookieClear(headers, callbackPath) {
+	headers.append("Set-Cookie", serializeRecoveryCookie("", 0, callbackPath));
+}
+function getSetCookieValues(headers) {
+	const getSetCookie = headers.getSetCookie;
+	if (getSetCookie) return getSetCookie.call(headers);
+	return Array.from(headers).filter(([name]) => name.toLowerCase() === "set-cookie").map(([, value]) => value);
+}
+/**
+* Build a lossless ticket-clear header using a callback request, URL, or
+* configured redirect URI as the cookie-path source.
+*/
+function clearOAuthRecoveryIntentHeaders(source) {
+	const headers = new Headers();
+	appendRecoveryCookieClear(headers, getOAuthRecoveryCookiePath(source));
+	return headers;
+}
+function hasNonEmptyParam(url, name) {
+	return url.searchParams.get(name)?.trim().length ? true : false;
+}
+/**
+* This check is intentionally stricter than the callback error code.  It
+* prevents recovery for provider errors, malformed callbacks, and account
+* actions even if an adapter accidentally calls the consume helper there.
+*/
+function isOAuthRecoveryEligibleCallback(request) {
+	const url = new URL(request.url);
+	return hasNonEmptyParam(url, "code") && hasNonEmptyParam(url, "state") && !url.searchParams.has("error") && !url.searchParams.has("kc_action") && !url.searchParams.has("kc_action_status");
+}
+function isRecoveryRecord(value) {
+	if (value === null || typeof value !== "object") return false;
+	const record = value;
+	return typeof record.state === "string" && record.state.length > 0 && typeof record.returnUrl === "string" && typeof record.createdAt === "number" && Number.isFinite(record.createdAt);
+}
+function getCallbackState(request) {
+	const value = new URL(request.url).searchParams.get("state");
+	return value && value.trim().length > 0 ? value : null;
+}
+/**
+* Create the opaque ticket cookie for an ordinary login transaction.
+* Application-action transactions deliberately do not receive a recovery
+* ticket and therefore cannot enter the automatic recovery path.
+*/
+async function createOAuthRecoveryForLogin(request, state, redirectUri) {
+	const returnUrl = sanitizeOAuthReturnUrl(state.returnUrl, request) ?? "/";
+	const callbackPath = getOAuthRecoveryCookiePath(redirectUri);
+	const ticket = await createOAuthRecoveryRecord({
+		state: state.state,
+		returnUrl,
+		createdAt: Date.now()
+	});
+	return {
+		ticket,
+		cookie: serializeRecoveryCookie(ticket, OAUTH_RECOVERY_TTL_SECONDS, callbackPath)
+	};
+}
+/**
+* Delete an unconsumed ticket during terminal/successful callback cleanup.
+* The caller owns error classification and should still clear the browser
+* cookie if deletion fails.
+*/
+async function discardOAuthRecoveryForRequest(request) {
+	const ticket = getCookieValue(request);
+	const headers = new Headers();
+	if (!hasCookie(request)) return headers;
+	if (ticket) await deleteOAuthRecoveryRecord(ticket);
+	appendRecoveryCookieClear(headers, getOAuthRecoveryCookiePath(request));
+	return headers;
+}
+/**
+* Atomically consume a stale-flow recovery intent.
+*
+* The typed error and the callback shape are both checked server-side.  Redis
+* compares the callback state and deletes only on an exact match, so a
+* mismatch cannot burn a valid ticket while a replay or concurrent loser
+* cannot retry.
+*/
+async function consumeOAuthRecoveryIntent(request, callbackError) {
+	const cleanupHeaders = clearOAuthRecoveryIntentHeaders(request);
+	const cleanupSetCookies = getSetCookieValues(cleanupHeaders);
+	if (!isRecoverableOAuthCallbackError(callbackError) || !isOAuthRecoveryEligibleCallback(request)) return {
+		intent: null,
+		cleanupHeaders,
+		cleanupSetCookies
+	};
+	const ticket = getCookieValue(request);
+	const callbackState = getCallbackState(request);
+	if (!ticket || !callbackState) return {
+		intent: null,
+		cleanupHeaders,
+		cleanupSetCookies
+	};
+	let record;
+	try {
+		record = await consumeOAuthRecoveryRecord(ticket, callbackState);
+	} catch (error) {
+		logger.warn("OAuth recovery record could not be consumed", { errorType: error instanceof Error ? error.name : "UnknownError" });
+		return {
+			intent: null,
+			cleanupHeaders,
+			cleanupSetCookies
+		};
+	}
+	if (!isRecoveryRecord(record)) return {
+		intent: null,
+		cleanupHeaders,
+		cleanupSetCookies
+	};
+	const age = Date.now() - record.createdAt;
+	if (age < 0 || age > OAUTH_RECOVERY_TTL_MS) return {
+		intent: null,
+		cleanupHeaders,
+		cleanupSetCookies
+	};
+	const returnUrl = sanitizeOAuthReturnUrl(record.returnUrl, request);
+	if (!returnUrl) return {
+		intent: null,
+		cleanupHeaders,
+		cleanupSetCookies
+	};
+	return {
+		intent: { returnUrl },
+		cleanupHeaders,
+		cleanupSetCookies
+	};
+}
+//#endregion
 //#region src/auth/auth.server.ts
 /**
 * OpenID Connect Authentication Server Module
@@ -384,11 +646,12 @@ async function getOAuthConfig() {
 		});
 		return configuration;
 	} catch (error) {
-		logger.error("OIDC discovery failed", error instanceof Error ? error : void 0, {
+		logger.error("OIDC discovery failed", void 0, {
 			authority: config.authority,
-			clientId: config.clientId
+			clientId: config.clientId,
+			errorType: error instanceof Error ? error.name : "UnknownError"
 		});
-		throw new Error(`OIDC discovery failed: ${getOAuthErrorMessage(error)}`);
+		throw new Error("OIDC discovery failed");
 	}
 }
 function getJwks(jwksUri) {
@@ -661,6 +924,81 @@ function clearAuthErrorHeaders() {
 function hasAuthError(request) {
 	return request.headers.get("Cookie")?.includes(`${AUTH_ERROR_COOKIE}=`) ?? false;
 }
+function escapeRegExp(value) {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function getOAuthStateIdFromRequest(request) {
+	const cookies = request.headers.get("Cookie");
+	if (!cookies) return null;
+	const cookieRegex = new RegExp(`(?:^|;\\s*)${escapeRegExp(OAUTH_STATE_COOKIE)}=([^;]*)`);
+	const cookieValue = cookies.match(cookieRegex)?.[1];
+	if (!cookieValue) return null;
+	try {
+		const stateId = decodeURIComponent(cookieValue);
+		return stateId.length > 0 ? stateId : null;
+	} catch {
+		return null;
+	}
+}
+function hasNonEmptyCallbackValue(value) {
+	return value !== null && value.trim().length > 0;
+}
+function appendHeadersPreservingSetCookie(target, source) {
+	const sourceHeaders = new Headers(source);
+	const setCookies = sourceHeaders.getSetCookie?.call(sourceHeaders) ?? Array.from(sourceHeaders).filter(([name]) => name.toLowerCase() === "set-cookie").map(([, value]) => value);
+	if (setCookies.length > 0) for (const cookie of setCookies) target.append("Set-Cookie", cookie);
+	else {
+		const setCookie = sourceHeaders.get("Set-Cookie");
+		if (setCookie) target.append("Set-Cookie", setCookie);
+	}
+	for (const [name, value] of sourceHeaders) if (name.toLowerCase() !== "set-cookie") target.set(name, value);
+}
+function appendOAuthStateCookieClear(headers) {
+	headers.append("Set-Cookie", serializeTemporaryAuthCookie(OAUTH_STATE_COOKIE, "", { maxAge: 0 }));
+}
+function isUsableOAuthState(state, requireNonce) {
+	return state !== null && typeof state.state === "string" && state.state.length > 0 && typeof state.codeVerifier === "string" && state.codeVerifier.length > 0 && (state.nonce === void 0 ? !requireNonce : typeof state.nonce === "string" && state.nonce.length > 0) && typeof state.createdAt === "number" && Number.isFinite(state.createdAt) && (state.returnUrl === void 0 || typeof state.returnUrl === "string") && (state.kcAction === void 0 || typeof state.kcAction === "string");
+}
+function getCallbackFailureCode(error, stage) {
+	if (isOAuthCallbackError(error)) return error.code;
+	switch (stage) {
+		case "configuration": return OAuthCallbackFailureCodes.ConfigurationError;
+		case "state":
+		case "storage": return OAuthCallbackFailureCodes.StorageError;
+		case "application_action": return OAuthCallbackFailureCodes.ApplicationActionFailed;
+		case "token_exchange": return OAuthCallbackFailureCodes.TokenExchangeFailed;
+		case "session_creation": return OAuthCallbackFailureCodes.SessionCreationFailed;
+		default: return OAuthCallbackFailureCodes.StorageError;
+	}
+}
+async function createOAuthCallbackFailure(request, stateId, failureCode) {
+	const cleanupHeaders = new Headers();
+	let cleanupError;
+	const preserveRecoveryTicket = failureCode === OAuthCallbackFailureCodes.StaleTransaction && isOAuthRecoveryEligibleCallback(request);
+	if (stateId) try {
+		await deleteOAuthState(stateId);
+	} catch (error) {
+		cleanupError = error;
+	}
+	try {
+		appendHeadersPreservingSetCookie(cleanupHeaders, await destroyAuthSession(request));
+	} catch (error) {
+		cleanupError ??= error;
+	}
+	if (!preserveRecoveryTicket || cleanupError) try {
+		appendHeadersPreservingSetCookie(cleanupHeaders, await discardOAuthRecoveryForRequest(request));
+	} catch (error) {
+		cleanupError ??= error;
+		appendHeadersPreservingSetCookie(cleanupHeaders, clearOAuthRecoveryIntentHeaders(request));
+	}
+	appendOAuthStateCookieClear(cleanupHeaders);
+	const effectiveFailureCode = cleanupError ? OAuthCallbackFailureCodes.StorageError : failureCode;
+	if (cleanupError) logger.warn("OAuth callback cleanup failed", {
+		failureCode: effectiveFailureCode,
+		errorType: cleanupError instanceof Error ? cleanupError.name : "UnknownError"
+	});
+	return new OAuthCallbackError(effectiveFailureCode, cleanupHeaders);
+}
 /**
 * Initiate OAuth login flow
 * 
@@ -668,6 +1006,9 @@ function hasAuthError(request) {
 * @param returnUrlOrOptions - Either a return URL string or LoginOptions object
 */
 async function login(request, returnUrlOrOptions) {
+	let oauthStateId = null;
+	let recoveryTicket = null;
+	let recoveryCookie = null;
 	try {
 		const config = getAuthConfig();
 		const options = typeof returnUrlOrOptions === "string" ? { returnUrl: returnUrlOrOptions } : returnUrlOrOptions || {};
@@ -699,7 +1040,15 @@ async function login(request, returnUrlOrOptions) {
 			hasKcAction: Boolean(options.kcAction),
 			extraAuthParamKeys: Object.keys(extraAuthParams)
 		});
-		const stateId = await createOAuthState(oauthState);
+		oauthStateId = await createOAuthState(oauthState);
+		if (!options.kcAction) {
+			const recovery = await createOAuthRecoveryForLogin(request, {
+				state,
+				returnUrl
+			}, config.redirectUri);
+			recoveryTicket = recovery.ticket;
+			recoveryCookie = recovery.cookie;
+		}
 		const authorizationParameters = {
 			redirect_uri: config.redirectUri,
 			scope: config.scope,
@@ -713,7 +1062,8 @@ async function login(request, returnUrlOrOptions) {
 		if (options.kcAction) authorizationParameters.kc_action = options.kcAction;
 		const authorizationUrl = oidc.buildAuthorizationUrl(oidcConfig, authorizationParameters);
 		const headers = new Headers();
-		headers.append("Set-Cookie", serializeTemporaryAuthCookie(OAUTH_STATE_COOKIE, stateId, { maxAge: 600 }));
+		headers.append("Set-Cookie", serializeTemporaryAuthCookie(OAUTH_STATE_COOKIE, oauthStateId, { maxAge: OAUTH_STATE_TTL_SECONDS }));
+		if (recoveryCookie) headers.append("Set-Cookie", recoveryCookie);
 		logger.info("OIDC authorization flow initiated", {
 			clientId: config.clientId,
 			redirectUri: config.redirectUri,
@@ -725,6 +1075,16 @@ async function login(request, returnUrlOrOptions) {
 		});
 		return createRedirectResponse(authorizationUrl.toString(), { headers });
 	} catch (error) {
+		if (oauthStateId) try {
+			await deleteOAuthState(oauthStateId);
+		} catch (cleanupError) {
+			logger.warn("OAuth login state cleanup failed", { errorType: cleanupError instanceof Error ? cleanupError.name : "UnknownError" });
+		}
+		if (recoveryTicket) try {
+			await deleteOAuthRecoveryRecord(recoveryTicket);
+		} catch (cleanupError) {
+			logger.warn("OAuth recovery intent cleanup failed", { errorType: cleanupError instanceof Error ? cleanupError.name : "UnknownError" });
+		}
 		logger.error("Failed to initiate OAuth login", void 0, { errorType: error instanceof Error ? error.name : "UnknownError" });
 		throw new Error("Login failed");
 	}
@@ -742,9 +1102,13 @@ async function login(request, returnUrlOrOptions) {
 *   - Redirect to home to start fresh login
 */
 async function handleCallback(request) {
+	let stateId = null;
+	let callbackStage = "configuration";
 	try {
+		stateId = getOAuthStateIdFromRequest(request);
 		const config = getAuthConfig();
 		const hasLandingPage = getEffectiveHasLandingPage(config);
+		const requiresNonce = config.scope.split(/\s+/).includes("openid");
 		const url = new URL(request.url);
 		const code = url.searchParams.get("code");
 		const state = url.searchParams.get("state");
@@ -752,28 +1116,33 @@ async function handleCallback(request) {
 		const errorDescription = url.searchParams.get("error_description");
 		const kcAction = url.searchParams.get("kc_action");
 		const kcActionStatus = url.searchParams.get("kc_action_status");
+		const hasCode = hasNonEmptyCallbackValue(code);
+		const hasState = hasNonEmptyCallbackValue(state);
+		const hasApplicationAction = Boolean(hasNonEmptyCallbackValue(kcAction) || hasNonEmptyCallbackValue(kcActionStatus));
 		logger.info("OIDC callback received", {
-			hasCode: !!code,
-			hasState: !!state,
+			hasCode,
+			hasState,
 			hasError: Boolean(error),
 			hasErrorDescription: Boolean(errorDescription),
-			hasKcAction: Boolean(kcAction),
-			hasKcActionStatus: Boolean(kcActionStatus),
+			hasKcAction: hasNonEmptyCallbackValue(kcAction),
+			hasKcActionStatus: hasNonEmptyCallbackValue(kcActionStatus),
 			clientId: config.clientId,
 			redirectUri: config.redirectUri
 		});
 		if (error) {
-			if (kcActionStatus && state) {
-				const cookies = request.headers.get("Cookie");
-				const oauthStateRegex = new RegExp(`${OAUTH_STATE_COOKIE}=([^;]+)`);
-				const stateId = (cookies?.match(oauthStateRegex))?.[1];
+			if (kcActionStatus && hasState) {
+				callbackStage = "state";
 				if (stateId) {
-					const oauthState = await getOAuthState(stateId);
+					const oauthState = await getOAuthState(stateId, { throwOnMalformed: true });
 					const stateAge = oauthState ? Date.now() - oauthState.createdAt : Number.POSITIVE_INFINITY;
-					if (oauthState && oauthState.state === state && stateAge <= 600 * 1e3) {
+					if (oauthState && isUsableOAuthState(oauthState, requiresNonce) && oauthState.state === state && stateAge <= OAUTH_STATE_TTL_MS) {
+						callbackStage = "storage";
 						await deleteOAuthState(stateId);
+						const recoveryHeaders = await discardOAuthRecoveryForRequest(request);
+						callbackStage = "application_action";
 						const headers = new Headers();
-						headers.append("Set-Cookie", serializeTemporaryAuthCookie(OAUTH_STATE_COOKIE, "", { maxAge: 0 }));
+						appendOAuthStateCookieClear(headers);
+						appendHeadersPreservingSetCookie(headers, recoveryHeaders);
 						const redirectUrl = appendApplicationInitiatedActionResult(sanitizeOAuthReturnUrl(oauthState.returnUrl, request) ?? "/", kcAction || oauthState.kcAction, kcActionStatus);
 						logger.info("Application initiated action returned with OAuth error", {
 							hasError: Boolean(error),
@@ -794,9 +1163,13 @@ async function handleCallback(request) {
 			});
 			if (error === "access_denied") {
 				logger.warn("Access denied for this application", { clientId: config.clientId });
+				callbackStage = "storage";
+				if (stateId) await deleteOAuthState(stateId);
 				const headers = await destroyAuthSession(request);
+				appendOAuthStateCookieClear(headers);
+				appendHeadersPreservingSetCookie(headers, await discardOAuthRecoveryForRequest(request));
 				headers.append("Set-Cookie", serializeTemporaryAuthCookie(AUTH_ERROR_COOKIE, "access_denied", { maxAge: 300 }));
-				headers.append("Set-Cookie", serializeTemporaryAuthCookie(AUTH_ERROR_DESC_COOKIE, errorDescription || "You do not have access to this application.", { maxAge: 300 }));
+				headers.append("Set-Cookie", serializeTemporaryAuthCookie(AUTH_ERROR_DESC_COOKIE, "You do not have access to this application.", { maxAge: 300 }));
 				const baseUrl = new URL(config.redirectUri).origin;
 				logger.info("Redirecting to /auth/login to show access_denied error", {
 					hasLandingPage,
@@ -807,30 +1180,51 @@ async function handleCallback(request) {
 			}
 			if (error === "login_required") {
 				logger.info("Login required, user session may have expired");
+				callbackStage = "storage";
+				if (stateId) await deleteOAuthState(stateId);
 				const headers = await destroyAuthSession(request);
+				appendOAuthStateCookieClear(headers);
+				appendHeadersPreservingSetCookie(headers, await discardOAuthRecoveryForRequest(request));
 				const baseUrl = new URL(config.redirectUri).origin;
 				return createRedirectResponse(baseUrl, { headers });
 			}
+			callbackStage = "storage";
+			if (stateId) await deleteOAuthState(stateId);
 			const headers = await destroyAuthSession(request);
+			appendOAuthStateCookieClear(headers);
+			appendHeadersPreservingSetCookie(headers, await discardOAuthRecoveryForRequest(request));
 			headers.append("Set-Cookie", serializeTemporaryAuthCookie(AUTH_ERROR_COOKIE, error, { maxAge: 300 }));
-			if (errorDescription) headers.append("Set-Cookie", serializeTemporaryAuthCookie(AUTH_ERROR_DESC_COOKIE, errorDescription, { maxAge: 300 }));
 			const baseUrl = new URL(config.redirectUri).origin;
 			return createRedirectResponse(baseUrl, { headers });
 		}
-		const cookies = request.headers.get("Cookie");
-		const oauthStateRegex = new RegExp(`${OAUTH_STATE_COOKIE}=([^;]+)`);
-		const stateId = (cookies?.match(oauthStateRegex))?.[1];
-		if (!stateId) throw new Error("OAuth state ID not found in cookie");
-		const oauthState = await getOAuthState(stateId);
-		if (!oauthState) throw new Error("No OAuth state found - state may have expired");
-		if (!state) throw new Error("Missing required callback state parameter");
-		if (oauthState.state !== state) throw new Error(`OAuth state mismatch`);
-		if (Date.now() - oauthState.createdAt > 600 * 1e3) throw new Error("OAuth state expired");
-		if (!code) {
+		if (!hasState) {
+			callbackStage = hasApplicationAction ? "application_action" : "state";
+			throw new OAuthCallbackError(hasApplicationAction ? OAuthCallbackFailureCodes.ApplicationActionFailed : OAuthCallbackFailureCodes.MalformedCallback);
+		}
+		if (!hasCode && !hasApplicationAction) {
+			callbackStage = "state";
+			throw new OAuthCallbackError(OAuthCallbackFailureCodes.MalformedCallback);
+		}
+		if (!stateId) {
+			callbackStage = hasApplicationAction ? "application_action" : "state";
+			throw new OAuthCallbackError(hasApplicationAction ? OAuthCallbackFailureCodes.ApplicationActionFailed : OAuthCallbackFailureCodes.StaleTransaction);
+		}
+		callbackStage = "state";
+		const oauthState = await getOAuthState(stateId, { throwOnMalformed: true });
+		if (!oauthState) throw new OAuthCallbackError(hasApplicationAction ? OAuthCallbackFailureCodes.ApplicationActionFailed : OAuthCallbackFailureCodes.StaleTransaction);
+		if (!isUsableOAuthState(oauthState, requiresNonce)) throw new OAuthCallbackError(OAuthCallbackFailureCodes.StorageError);
+		if (oauthState.state !== state) throw new OAuthCallbackError(OAuthCallbackFailureCodes.StateMismatch);
+		const isApplicationAction = Boolean(hasApplicationAction || oauthState.kcAction);
+		if (Date.now() - oauthState.createdAt > OAUTH_STATE_TTL_MS) throw new OAuthCallbackError(isApplicationAction ? OAuthCallbackFailureCodes.ApplicationActionFailed : OAuthCallbackFailureCodes.StaleTransaction);
+		if (!hasCode) {
 			if (kcActionStatus) {
+				callbackStage = "storage";
 				await deleteOAuthState(stateId);
+				const recoveryHeaders = await discardOAuthRecoveryForRequest(request);
+				callbackStage = "application_action";
 				const headers = new Headers();
-				headers.append("Set-Cookie", serializeTemporaryAuthCookie(OAUTH_STATE_COOKIE, "", { maxAge: 0 }));
+				appendOAuthStateCookieClear(headers);
+				appendHeadersPreservingSetCookie(headers, recoveryHeaders);
 				const redirectUrl = appendApplicationInitiatedActionResult(sanitizeOAuthReturnUrl(oauthState.returnUrl, request) ?? "/", kcAction || oauthState.kcAction, kcActionStatus);
 				logger.info("Application initiated action returned without authorization code", {
 					hasKcAction: Boolean(kcAction || oauthState.kcAction),
@@ -838,11 +1232,13 @@ async function handleCallback(request) {
 				});
 				return createRedirectResponse(redirectUrl, { headers });
 			}
-			throw new Error("Missing required callback code parameter");
+			throw new OAuthCallbackError(isApplicationAction ? OAuthCallbackFailureCodes.ApplicationActionFailed : OAuthCallbackFailureCodes.MalformedCallback);
 		}
 		logger.info("Initiating token exchange");
+		callbackStage = "configuration";
 		const oidcConfig = await getOAuthConfig();
 		const authorizationResponseUrl = createAuthorizationResponseUrl(request.url, config.redirectUri);
+		callbackStage = "token_exchange";
 		const tokenResult = await oidc.authorizationCodeGrant(oidcConfig, authorizationResponseUrl, {
 			pkceCodeVerifier: oauthState.codeVerifier,
 			expectedState: oauthState.state,
@@ -850,22 +1246,26 @@ async function handleCallback(request) {
 			idTokenExpected: config.scope.split(/\s+/).includes("openid")
 		});
 		logger.info("Token exchange completed successfully");
-		const sessionHeaders = await createAuthSession(request, await createSessionData(tokenResult, getClaimsFromTokenResponse(tokenResult)));
+		callbackStage = "session_creation";
+		const newSessionData = await createSessionData(tokenResult, getClaimsFromTokenResponse(tokenResult));
+		callbackStage = "session_creation";
+		const sessionHeaders = await createAuthSession(request, newSessionData);
+		callbackStage = "storage";
 		await deleteOAuthState(stateId);
-		const headers = new Headers(sessionHeaders);
-		headers.append("Set-Cookie", serializeTemporaryAuthCookie(OAUTH_STATE_COOKIE, "", { maxAge: 0 }));
+		const recoveryHeaders = await discardOAuthRecoveryForRequest(request);
+		const headers = new Headers();
+		appendHeadersPreservingSetCookie(headers, sessionHeaders);
+		appendOAuthStateCookieClear(headers);
+		appendHeadersPreservingSetCookie(headers, recoveryHeaders);
 		logger.info("OAuth callback processed successfully");
 		return createRedirectResponse(appendApplicationInitiatedActionResult(sanitizeOAuthReturnUrl(oauthState.returnUrl, request) ?? "/", kcAction || oauthState.kcAction, kcActionStatus), { headers });
 	} catch (error) {
-		logger.error("OAuth callback failed", void 0, { errorType: error instanceof Error ? error.name : "UnknownError" });
-		try {
-			const cookies = request.headers.get("Cookie");
-			const oauthStateRegex = new RegExp(`${OAUTH_STATE_COOKIE}=([^;]+)`);
-			const stateId = (cookies?.match(oauthStateRegex))?.[1];
-			if (stateId) await deleteOAuthState(stateId);
-		} catch {}
-		await destroyAuthSession(request);
-		throw new Error("Authentication failed");
+		const failureCode = getCallbackFailureCode(error, callbackStage);
+		logger.error("OAuth callback failed", void 0, {
+			failureCode,
+			errorType: error instanceof Error ? error.name : "UnknownError"
+		});
+		throw await createOAuthCallbackFailure(request, stateId, failureCode);
 	}
 }
 /**
@@ -1439,6 +1839,6 @@ function shouldAttemptTokenRefresh(response, hasAuth) {
 	return hasAuth && isTokenExpiredResponse(response);
 }
 //#endregion
-export { resetAuthClaimMapping as A, handleCallback as C, logout as D, login as E, refreshTokens as O, handleBackChannelLogout as S, hasAuthError as T, createAuthorizationResponseUrl as _, configureRouteProtection as a, getAuthError as b, protectRoute as c, resetRouteProtectionConfig as d, shouldRefreshToken as f, configureAuthClaimMapping as g, clearAuthServerCache as h, authRoute as i, requireAuth as k, protectedRoute as l, clearAuthErrorHeaders as m, isTokenExpiredResponse as n, onboardingRoute as o, subscriptionRoute as p, shouldAttemptTokenRefresh as r, policyRoute as s, attemptTokenRefresh as t, publicRoute as u, extractUserInfo as v, handleFrontChannelLogout as w, getUser as x, getAccessToken as y };
+export { resetAuthClaimMapping as A, handleCallback as C, logout as D, login as E, OAuthCallbackError as F, OAuthCallbackFailureCodes as I, isOAuthCallbackError as L, clearOAuthRecoveryIntentHeaders as M, consumeOAuthRecoveryIntent as N, refreshTokens as O, getOAuthRecoveryCookiePath as P, isRecoverableOAuthCallbackError as R, handleBackChannelLogout as S, hasAuthError as T, createAuthorizationResponseUrl as _, configureRouteProtection as a, getAuthError as b, protectRoute as c, resetRouteProtectionConfig as d, shouldRefreshToken as f, configureAuthClaimMapping as g, clearAuthServerCache as h, authRoute as i, OAUTH_RECOVERY_COOKIE_NAME as j, requireAuth as k, protectedRoute as l, clearAuthErrorHeaders as m, isTokenExpiredResponse as n, onboardingRoute as o, subscriptionRoute as p, shouldAttemptTokenRefresh as r, policyRoute as s, attemptTokenRefresh as t, publicRoute as u, extractUserInfo as v, handleFrontChannelLogout as w, getUser as x, getAccessToken as y };
 
-//# sourceMappingURL=server-C3_iNZfj.mjs.map
+//# sourceMappingURL=server-BJTz5-BE.mjs.map