@shware/security 7.1.1 → 8.0.1

package/dist/auth/index.mjs

@@ -1,20 +1,25 @@
-import { MAX_ATTRIBUTES_BYTES, attributesSize, bodyAttributes } from "./attributes.mjs";
-import { loginEmailSchema, sendEmailVerificationCodeSchema } from "../email/schema.mjs";
+import { AuthenticationError } from "./error.mjs";
 import { OAuth2Error, isKnownOAuth2ErrorType } from "../oauth2/error.mjs";
+import { errorResponse, invalidArgument, unauthenticated } from "./respond.mjs";
+import { MAX_ATTRIBUTES_BYTES, attributesSchema, attributesSize, bodyAttributes } from "./attributes.mjs";
+import { loginEmailSchema, sendEmailVerificationCodeSchema } from "../email/schema.mjs";
 import { OAuth2Client, googleOneTapSchema, oauth2RedirectQuerySchema } from "../oauth2/client.mjs";
 import { PRINCIPAL_NAME_INDEX_NAME } from "../session/common.mjs";
 import { deleteCookie, getCookie, param, query, setCookie } from "../utils/http.mjs";
 import { timing } from "../utils/timing.mjs";
-import { invalidArgument, resourceExhausted, valid, verifyTurnstileToken } from "../utils/valid.mjs";
-import { createHash, randomInt, randomUUID, timingSafeEqual } from "node:crypto";
+import { parse, readForm, readJson, verifyTurnstileToken } from "../utils/valid.mjs";
+import { DesktopCodes } from "./desktop-codes.mjs";
+import { EmailVerificationCodes } from "./email-codes.mjs";
+import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { invariant } from "@shware/utils";
+import { extend, literal, object, regex, string } from "zod/mini";
 // src/auth/index.ts
 const PKCE_FORMAT = /^[A-Za-z0-9_-]{43,128}$/;
 const CODE_VERIFIER_FORMAT = /^[A-Za-z0-9._~-]{43,128}$/;
-const INVALID_CODE_VERIFIER = {
-	error: "invalid_request",
-	error_description: "code_verifier must be 43-128 characters from [A-Za-z0-9-._~]"
-};
+/** The header a session id travels in besides the cookie, with `session.header` on. */
+const SESSION_HEADER = "X-Auth-Token";
+/** Seconds an OAuth2 state or nonce may be used within. */
+const OAUTH2_PARAMETER_TTL = 600;
 const MAX_ERROR_DESCRIPTION_LENGTH = 256;
 /** An error code safe to put on errorUri: a registered one as is, anything else as `fallback`. */
 function safeErrorType(error, fallback) {
@@ -41,14 +46,20 @@ function authorizationAttributes(attributes) {
 	return defined;
 }
 /** Sign in with Apple answers with `response_mode=form_post`; a charset parameter may follow. */
-const INVALID_ATTRIBUTES = {
-	error: "invalid_request",
-	error_description: `attributes must map strings to strings, at most ${MAX_ATTRIBUTES_BYTES} bytes`
-};
 function isFormPost(request) {
 	const contentType = request.headers.get("content-type")?.toLowerCase();
 	return request.method === "POST" && !!contentType?.startsWith("application/x-www-form-urlencoded");
 }
+/** Google's own form post carries no attributes; an app posting JSON may add them. */
+const oneTapBodySchema = extend(googleOneTapSchema, { attributes: attributesSchema });
+const desktopAuthorizeSchema = object({
+	code_challenge: string().check(regex(PKCE_FORMAT)),
+	code_challenge_method: literal("S256")
+});
+const desktopExchangeSchema = object({
+	code: string(),
+	code_verifier: string().check(regex(PKCE_FORMAT))
+});
 const PATH = {
 	CSRF: "/csrf",
 	LOGOUT: "/logout",
@@ -60,15 +71,18 @@ const PATH = {
 	LOGIN_OAUTH2_NATIVE: "/login/oauth2/native/:provider",
 	LOGIN_OAUTH2_ONETAP: "/login/oauth2/onetap/google",
 	LOGIN_EMAIL: "/login/email",
-	LOGIN_PHONE: "/login/phone",
 	SEND_EMAIL_VERIFICATION_CODE: "/auth/sendEmailVerificationCode",
-	SEND_PHONE_VERIFICATION_CODE: "/auth/sendPhoneVerificationCode",
 	DESKTOP_AUTHORIZE: "/auth/desktop/authorize",
 	DESKTOP_EXCHANGE: "/auth/desktop/exchange",
 	CLEANUP_EXPIRED_SESSIONS: "/sessions/expired/cleanup"
 };
-/** Seconds an email verification code, and its attempt counter, stay valid. */
-const EMAIL_VERIFICATION_CODE_TTL = 600;
+/**
+* The login routes and session helpers. Every route is one straight line: read and validate the
+* request, check the credential, call the host's `onAuthorized`, sign in. Failures are thrown and
+* answered in one place per kind of route: a JSON route runs under `guard`, which maps a
+* `RequestError`, an `AuthenticationError` or an `OAuth2Error` to its google.rpc body (see
+* `respond.ts`); the redirect callback maps the same errors to `errorUri` parameters (`redirect`).
+*/
 var Auth = class {
 	timing;
 	cookieName;
@@ -76,21 +90,27 @@ var Auth = class {
 	kv;
 	repository;
 	turnstileSecretKey;
-	maxVerificationAttempts;
-	verificationResendCooldown;
+	emailCodes;
+	desktopCodes;
 	oauth2Client;
 	onetapRequireNonce;
 	touchInterval;
+	sessionHeader;
 	ATTR_OAUTH2_AUTHORIZATION_REQUEST = "oauth2AuthorizationRequest";
 	constructor({ sessionRepository, kvRepository, turnstileSecretKey, verificationCode, oauth2, cookie, session, timing }) {
 		this.timing = timing ?? false;
 		this.kv = kvRepository;
 		this.repository = sessionRepository;
 		this.turnstileSecretKey = turnstileSecretKey;
-		this.maxVerificationAttempts = verificationCode?.maxAttempts ?? 5;
-		this.verificationResendCooldown = verificationCode?.resendCooldown ?? 60;
-		invariant(this.maxVerificationAttempts >= 1, "verificationCode.maxAttempts must be at least 1");
-		invariant(this.verificationResendCooldown >= 1, "verificationCode.resendCooldown must be at least 1 second");
+		const maxAttempts = verificationCode?.maxAttempts ?? 5;
+		const resendCooldown = verificationCode?.resendCooldown ?? 60;
+		invariant(maxAttempts >= 1, "verificationCode.maxAttempts must be at least 1");
+		invariant(resendCooldown >= 1, "verificationCode.resendCooldown must be at least 1 second");
+		this.emailCodes = new EmailVerificationCodes(kvRepository, {
+			maxAttempts,
+			resendCooldown
+		});
+		this.desktopCodes = new DesktopCodes(kvRepository);
 		const { name, ...cookieOptions } = cookie ?? {};
 		this.cookieName = name ?? "SESSION";
 		this.cookieOptions = {
@@ -103,14 +123,76 @@ var Auth = class {
 		this.oauth2Client = oauth2?.client ? new OAuth2Client(oauth2.client) : null;
 		this.onetapRequireNonce = oauth2?.onetap?.requireNonce ?? true;
 		this.touchInterval = (session?.touchInterval ?? 3600) * 1e3;
+		this.sessionHeader = session?.header ?? false;
 		invariant(this.touchInterval >= 0, "session.touchInterval must not be negative");
 	}
 	getSessionId(request) {
-		let sessionId;
-		const header = request.headers.get("Authorization");
-		if (header?.startsWith("Bearer ")) sessionId = header.replace("Bearer ", "");
-		if (!sessionId) sessionId = getCookie(request, this.cookieName);
-		return sessionId;
+		const fromCookie = getCookie(request, this.cookieName);
+		if (fromCookie) return fromCookie;
+		return this.sessionHeader && request.headers.get(SESSION_HEADER) || void 0;
+	}
+	/** The session the request carries, if it exists. */
+	async loadSession(request) {
+		const sessionId = this.getSessionId(request);
+		return sessionId ? this.repository.findById(sessionId) : null;
+	}
+	/** The signed-in principal of a session, if any. */
+	principalOf(session) {
+		const name = session.getAttribute(PRINCIPAL_NAME_INDEX_NAME);
+		return name ? { name: String(name) } : null;
+	}
+	/**
+	* A new session signed in as `principal`. With `carryOver`, what the host kept in the pre-login
+	* session moves to the new one; the authorization request (state, PKCE verifier, flow
+	* attributes) is single-use and was consumed, and a principal left there from an earlier
+	* sign-in is replaced. The new id is never the one the browser brought, which may have been
+	* planted by an attacker who started the flow (session fixation).
+	*/
+	async signIn(principal, carryOver) {
+		const session = this.repository.createSession();
+		for (const attribute of carryOver?.getAttributeNames() ?? []) {
+			if (attribute === this.ATTR_OAUTH2_AUTHORIZATION_REQUEST) continue;
+			if (attribute === "principalName") continue;
+			const value = carryOver?.getAttribute(attribute);
+			if (value !== null && value !== void 0) session.setAttribute(attribute, value);
+		}
+		session.setAttribute(PRINCIPAL_NAME_INDEX_NAME, principal.name);
+		await this.repository.save(session);
+		return session;
+	}
+	/**
+	* `response` carrying `session`: its cookie, renewed for the whole inactive interval, and with
+	* `session.header` on, the `X-Auth-Token` header a client without a cookie jar reads.
+	*/
+	withSession(response, session, cookie) {
+		const maxAge = session.getMaxInactiveInterval();
+		setCookie(response, this.cookieName, session.getId(), {
+			...this.cookieOptions,
+			...cookie,
+			maxAge
+		});
+		if (this.sessionHeader) response.headers.set(SESSION_HEADER, session.getId());
+		return response;
+	}
+	/** Runs a JSON route: a failure it knows is its response, anything else is the host's. */
+	async guard(run) {
+		try {
+			return await run();
+		} catch (error) {
+			const response = errorResponse(error);
+			if (response) return response;
+			throw error;
+		}
+	}
+	/** The error redirect of the callback flow; `refusal`'s reason and metadata ride along. */
+	redirect(error, description, refusal) {
+		invariant(this.oauth2Client, "oauth2Client is not initialized");
+		const uri = new URL(this.oauth2Client.errorUri);
+		for (const [key, value] of Object.entries(refusal?.metadata ?? {})) if (!uri.searchParams.has(key)) uri.searchParams.set(key, value);
+		uri.searchParams.set("error", error);
+		if (description) uri.searchParams.set("error_description", description.slice(0, MAX_ERROR_DESCRIPTION_LENGTH));
+		if (refusal) uri.searchParams.set("reason", refusal.reason);
+		return Response.redirect(uri.href, 302);
 	}
 	csrf = async (_request) => {
 		const token = randomUUID();
@@ -136,24 +218,16 @@ var Auth = class {
 		return response;
 	};
 	logged = async (request, onLogged) => {
-		const sessionId = this.getSessionId(request);
-		if (!sessionId) return Response.json({ data: false });
-		const session = await this.repository.findById(sessionId);
+		const session = await this.loadSession(request);
 		if (!session) return Response.json({ data: false });
-		const name = session.getAttribute(PRINCIPAL_NAME_INDEX_NAME);
 		session.setLastAccessedTime(Date.now());
 		await this.repository.save(session);
-		if (name !== null) await onLogged?.({ name: String(name) });
-		const response = Response.json({ data: name !== null });
-		const maxAge = session.getMaxInactiveInterval();
-		setCookie(response, this.cookieName, session.getId(), {
-			...this.cookieOptions,
-			maxAge
-		});
-		return response;
+		const principal = this.principalOf(session);
+		if (principal) await onLogged?.(principal);
+		return this.withSession(Response.json({ data: principal !== null }), session);
 	};
 	createPkceParameters() {
-		const code_verifier = randomUUID();
+		const code_verifier = randomBytes(32).toString("base64url");
 		return {
 			code_verifier,
 			code_challenge: createHash("sha256").update(code_verifier).digest().toString("base64url"),
@@ -166,34 +240,29 @@ var Auth = class {
 	getOauth2NonceKey(nonce) {
 		return `oauth2:nonce:${nonce}`;
 	}
-	getEmailVerificationCodeKey(email) {
-		return `email:verification:${email}`;
-	}
-	getEmailVerificationAttemptsKey(email) {
-		return `email:verification-attempts:${email}`;
-	}
-	getEmailVerificationCooldownKey(email) {
-		return `email:verification-cooldown:${email}`;
-	}
-	getPhoneVerificationCodeKey(phone) {
-		return `phone:verification:${phone}`;
-	}
-	getDesktopCodeKey(code) {
-		return `desktop:code:${code}`;
+	/**
+	* Spends a nonce `oauth2Nonce` issued for `provider`: `NONCE_MISMATCH` for one that was not,
+	* or was used already. An id token is replayable until it expires; the nonce it carries makes
+	* it sign in once.
+	*/
+	async consumeNonce(nonce, provider) {
+		const key = this.getOauth2NonceKey(nonce);
+		if (await this.kv.getItem(key) !== provider) throw new AuthenticationError("NONCE_MISMATCH");
+		await this.kv.removeItem(key);
 	}
 	oauth2State = async (request) => {
 		const { provider } = param(request, PATH.OAUTH2_STATE);
 		const state = randomUUID();
-		await this.kv.setItem(this.getOauth2StateKey(state), provider, 600);
+		await this.kv.setItem(this.getOauth2StateKey(state), provider, OAUTH2_PARAMETER_TTL);
 		return Response.json({ state });
 	};
 	oauth2Nonce = async (request) => {
 		const { provider } = param(request, PATH.OAUTH2_NONCE);
 		const nonce = randomUUID();
-		await this.kv.setItem(this.getOauth2NonceKey(nonce), provider, 600);
+		await this.kv.setItem(this.getOauth2NonceKey(nonce), provider, OAUTH2_PARAMETER_TTL);
 		return Response.json({ nonce });
 	};
-	oauth2Authorization = async (request, options) => {
+	oauth2Authorization = (request, options) => this.guard(async () => {
 		invariant(this.oauth2Client, "oauth2Client is not initialized");
 		const attributes = authorizationAttributes(options?.attributes);
 		const { mark, setTiming } = timing({ enabled: this.timing });
@@ -205,8 +274,11 @@ var Auth = class {
 			state,
 			pkce
 		});
-		const sessionId = this.getSessionId(request);
-		const session = sessionId ? await this.repository.findById(sessionId) ?? this.repository.createSession() : this.repository.createSession();
+		let session = await this.loadSession(request);
+		if (!session) {
+			session = this.repository.createSession();
+			session.setMaxInactiveInterval(OAUTH2_PARAMETER_TTL);
+		}
 		mark("fetch_session");
 		const authorizationRequest = {
 			state,
@@ -215,56 +287,38 @@ var Auth = class {
 			additionalParameters: pkce,
 			...attributes ? { attributes } : {}
 		};
-		const value = JSON.stringify(authorizationRequest);
-		session.setAttribute(this.ATTR_OAUTH2_AUTHORIZATION_REQUEST, value);
+		session.setAttribute(this.ATTR_OAUTH2_AUTHORIZATION_REQUEST, JSON.stringify(authorizationRequest));
 		await this.repository.save(session);
 		mark("save_session");
 		const response = new Response(null, {
 			status: 302,
 			headers: { location: uri.href }
 		});
-		const maxAge = session.getMaxInactiveInterval();
-		setCookie(response, this.cookieName, session.getId(), {
-			...this.cookieOptions,
-			maxAge
-		});
 		setTiming(response);
-		return response;
-	};
-	redirect = (error, description) => {
-		invariant(this.oauth2Client, "oauth2Client is not initialized");
-		const uri = new URL(this.oauth2Client.errorUri);
-		uri.searchParams.set("error", error);
-		if (description) uri.searchParams.set("error_description", description.slice(0, MAX_ERROR_DESCRIPTION_LENGTH));
-		return Response.redirect(uri.href, 302);
-	};
+		return this.withSession(response, session);
+	});
 	loginOAuth2Code = async (request, handler) => {
 		invariant(this.oauth2Client, "oauth2Client is not initialized");
 		const { mark, setTiming } = timing({ enabled: this.timing });
-		const sessionId = this.getSessionId(request);
-		const session = sessionId ? await this.repository.findById(sessionId) : null;
+		const session = await this.loadSession(request);
 		if (!session) return this.redirect("invalid_request", "session not found");
 		mark("load_session");
 		const json = session.getAttribute(this.ATTR_OAUTH2_AUTHORIZATION_REQUEST);
 		if (!json) return this.redirect("invalid_request", "authorization request not found");
 		const cached = JSON.parse(json);
 		const { provider } = param(request, PATH.LOGIN_OAUTH2_CODE);
-		let data;
-		if (isFormPost(request)) {
-			const params = new URLSearchParams(await request.text());
-			data = Object.fromEntries(params.entries());
-		} else data = query(request);
+		const data = isFormPost(request) ? Object.fromEntries(new URLSearchParams(await request.text())) : query(request);
 		const parsed = oauth2RedirectQuerySchema.safeParse(data);
 		if (!parsed.success) return this.redirect("invalid_request", "invalid redirect query");
 		if (parsed.data.error) {
 			if (parsed.data.state && parsed.data.state !== cached.state) return this.redirect("invalid_request", "redirect state mismatch");
 			return this.redirect(safeErrorType(parsed.data.error, "server_error"), parsed.data.error_description);
 		}
-		if (!parsed.data.code || !parsed.data.state) return this.redirect("invalid_request", "invalid redirect query");
-		if (parsed.data.state !== cached.state) return this.redirect("invalid_request", "redirect state mismatch");
+		const { code, state, user } = parsed.data;
+		if (!code || !state) return this.redirect("invalid_request", "invalid redirect query");
+		if (state !== cached.state) return this.redirect("invalid_request", "redirect state mismatch");
 		if (provider !== cached.provider) return this.redirect("invalid_request", "redirect provider mismatch");
 		mark("validate_session");
-		const { code, user } = parsed.data;
 		let signedIn;
 		try {
 			const { clientId, token } = await this.oauth2Client.exchangeAuthorizationCode({
@@ -287,8 +341,7 @@ var Auth = class {
 				attributes: cached.attributes ?? {}
 			});
 			mark("save_principal");
-			signedIn = this.signedInSession(session, principal.name);
-			await this.repository.save(signedIn);
+			signedIn = await this.signIn(principal, session);
 			await this.repository.deleteById(session.getId());
 			mark("update_session");
 		} catch (error) {
@@ -297,6 +350,10 @@ var Auth = class {
 				const type = CALLBACK_ERROR_TYPES.has(error.error) ? error.error : "server_error";
 				return this.redirect(type);
 			}
+			if (error instanceof AuthenticationError) {
+				console.warn("OAuth2 sign-in refused", error.reason, error.metadata);
+				return this.redirect("access_denied", void 0, error);
+			}
 			console.error("OAuth2 callback failed", error);
 			return this.redirect("server_error");
 		}
@@ -307,328 +364,157 @@ var Auth = class {
 			status: 302,
 			headers: { location: uri.href }
 		});
-		const maxAge = signedIn.getMaxInactiveInterval();
-		setCookie(response, this.cookieName, signedIn.getId(), {
-			...this.cookieOptions,
-			maxAge
-		});
 		setTiming(response);
-		return response;
+		return this.withSession(response, signedIn);
 	};
-	/**
-	* A fresh session for `name`, carrying over what the host kept in the pre-login one. The
-	* authorization request (state, PKCE verifier, flow attributes) is single-use and was consumed
-	* by this callback, and a principal left there from an earlier sign-in is replaced.
-	*/
-	signedInSession(previous, name) {
-		const session = this.repository.createSession();
-		for (const attribute of previous.getAttributeNames()) {
-			if (attribute === this.ATTR_OAUTH2_AUTHORIZATION_REQUEST) continue;
-			if (attribute === "org.springframework.session.FindByIndexNameSessionRepository.PRINCIPAL_NAME_INDEX_NAME") continue;
-			const value = previous.getAttribute(attribute);
-			if (value !== null) session.setAttribute(attribute, value);
-		}
-		session.setAttribute(PRINCIPAL_NAME_INDEX_NAME, name);
-		return session;
+	/** The shared tail of the JSON login routes: the host's handler, then a signed-in session. */
+	async authorize(request, handler, authorization, setTiming) {
+		const principal = await handler(request, authorization);
+		const session = await this.signIn(principal);
+		const response = Response.json(principal);
+		setTiming(response);
+		return this.withSession(response, session);
 	}
-	loginOAuth2Native = async (request, handler) => {
+	loginOAuth2Native = (request, handler) => this.guard(async () => {
 		invariant(this.oauth2Client, "oauth2Client is not initialized");
 		const { mark, setTiming } = timing({ enabled: this.timing });
 		const { provider } = param(request, PATH.LOGIN_OAUTH2_NATIVE);
-		const body = await request.json();
+		const body = await readJson(request);
 		const attributes = bodyAttributes(body);
-		if (!attributes) return Response.json(INVALID_ATTRIBUTES, { status: 400 });
 		const { attributes: _, ...credentials } = body;
 		const { code_verifier } = credentials;
-		if (code_verifier !== void 0 && (typeof code_verifier !== "string" || !CODE_VERIFIER_FORMAT.test(code_verifier))) return Response.json(INVALID_CODE_VERIFIER, { status: 400 });
+		if (code_verifier !== void 0 && (typeof code_verifier !== "string" || !CODE_VERIFIER_FORMAT.test(code_verifier))) throw invalidArgument("INVALID_CODE_VERIFIER", "code_verifier must be 43-128 characters from [A-Za-z0-9-._~]");
 		const { clientId, userInfo, token } = await this.oauth2Client.loginOAuth2Native({
 			provider,
 			credentials
 		});
 		mark("login_oauth2_native");
 		const { nonce } = userInfo.data;
-		if (nonce) {
-			if (await this.kv.getItem(this.getOauth2NonceKey(nonce)) !== provider) return Response.json({
-				error: "invalid_request",
-				error_description: "nonce mismatch"
-			}, { status: 400 });
-			await this.kv.removeItem(this.getOauth2NonceKey(nonce));
+		if (typeof nonce === "string" && nonce) {
+			await this.consumeNonce(nonce, provider);
 			mark("check_nonce");
 		}
-		const principal = await handler(request, {
+		return this.authorize(request, handler, {
 			provider,
 			clientId,
 			userInfo,
 			token,
 			attributes
-		});
-		mark("save_principal");
-		const session = this.repository.createSession();
-		session.setAttribute(PRINCIPAL_NAME_INDEX_NAME, principal.name);
-		await this.repository.save(session);
-		const response = new Response(JSON.stringify(principal), {
-			status: 200,
-			headers: { "Content-Type": "application/json" }
-		});
-		const maxAge = session.getMaxInactiveInterval();
-		setCookie(response, this.cookieName, session.getId(), {
-			...this.cookieOptions,
-			maxAge
-		});
-		setTiming(response);
-		return response;
-	};
-	loginOAuth2Onetap = async (request, handler, provider = "google") => {
+		}, setTiming);
+	});
+	loginOAuth2Onetap = (request, handler, provider = "google") => this.guard(async () => {
 		invariant(this.oauth2Client, "oauth2Client is not initialized");
 		const { mark, setTiming } = timing({ enabled: this.timing });
-		let body;
-		let attributes = {};
-		if (request.headers.get("Content-Type")?.includes("application/x-www-form-urlencoded")) {
-			const text = await request.text();
-			body = Object.fromEntries(new URLSearchParams(text));
-		} else if (request.headers.get("Content-Type")?.includes("application/json")) {
-			const json = await request.json();
-			attributes = bodyAttributes(json);
-			body = json;
-		} else return Response.json({
-			error: "invalid_request",
-			error_description: "invalid content type"
-		}, { status: 400 });
-		if (!attributes) return Response.json(INVALID_ATTRIBUTES, { status: 400 });
-		const parsed = googleOneTapSchema.parse(body);
-		let principal;
+		const body = (request.headers.get("content-type") ?? "").includes("application/json") ? await readJson(request) : await readForm(request);
+		const { attributes = {}, ...parsed } = parse(oneTapBodySchema, body);
+		let clientId;
+		let token;
+		let userInfo;
 		if (parsed.credential) {
-			const { clientId, token, userInfo } = await this.oauth2Client.getTokenInfo({
+			({clientId, token, userInfo} = await this.oauth2Client.getTokenInfo({
 				provider,
 				credential: parsed.credential
-			});
+			}));
 			mark("verify_credential");
 			const { nonce } = userInfo.data;
 			if (typeof nonce === "string" && nonce) {
-				if (await this.kv.getItem(this.getOauth2NonceKey(nonce)) !== provider) return Response.json({
-					error: "invalid_request",
-					error_description: "nonce mismatch"
-				}, { status: 401 });
-				await this.kv.removeItem(this.getOauth2NonceKey(nonce));
+				await this.consumeNonce(nonce, provider);
 				mark("check_nonce");
-			} else if (this.onetapRequireNonce) return Response.json({
-				error: "invalid_request",
-				error_description: "nonce missing"
-			}, { status: 401 });
-			principal = await handler(request, {
-				provider,
-				clientId,
-				userInfo,
-				token,
-				attributes
-			});
+			} else if (this.onetapRequireNonce) throw new AuthenticationError("NONCE_MISSING");
 		} else if (parsed.code) {
-			const { clientId, token } = await this.oauth2Client.exchangeAuthorizationCode({
+			({clientId, token} = await this.oauth2Client.exchangeAuthorizationCode({
 				provider,
 				code: parsed.code
-			});
-			principal = await handler(request, {
+			}));
+			userInfo = await this.oauth2Client.getUserInfo({
 				provider,
 				clientId,
-				userInfo: await this.oauth2Client.getUserInfo({
-					provider,
-					clientId,
-					token
-				}),
-				token,
-				attributes
+				token
 			});
-		} else throw new Error("invalid request");
-		mark("save_principal");
-		const session = this.repository.createSession();
-		session.setAttribute(PRINCIPAL_NAME_INDEX_NAME, principal.name);
-		await this.repository.save(session);
-		const response = new Response(JSON.stringify(principal), {
-			status: 200,
-			headers: { "Content-Type": "application/json" }
-		});
-		const maxAge = session.getMaxInactiveInterval();
-		setCookie(response, this.cookieName, session.getId(), {
-			...this.cookieOptions,
-			maxAge
-		});
-		setTiming(response);
-		return response;
-	};
-	sendEmailVerificationCode = async (request, sender) => {
+		} else throw invalidArgument("INVALID_ARGUMENT", "credential or code is required");
+		return this.authorize(request, handler, {
+			provider,
+			clientId,
+			userInfo,
+			token,
+			attributes
+		}, setTiming);
+	});
+	sendEmailVerificationCode = (request, sender) => this.guard(async () => {
 		invariant(this.turnstileSecretKey, "turnstileSecretKey is not configured");
-		const { data, error } = valid(sendEmailVerificationCodeSchema, await request.json());
-		if (error) return Response.json(error, { status: error.error.code });
-		const { email, turnstileToken } = data;
-		const result = await verifyTurnstileToken(this.turnstileSecretKey, turnstileToken);
-		if (result.error) return Response.json(result.error, { status: result.error.error.code });
-		const cooldownKey = this.getEmailVerificationCooldownKey(email);
-		if (await this.kv.increment(cooldownKey, this.verificationResendCooldown) > 1) {
-			const error = resourceExhausted("VERIFICATION_CODE_RESEND_TOO_SOON", "Verification code was sent recently");
-			return Response.json(error, { status: error.error.code });
-		}
-		try {
-			const verificationCode = randomInt(1e6).toString().padStart(6, "0");
-			await sender({
-				email,
-				verificationCode
-			});
-			await this.kv.removeItem(this.getEmailVerificationAttemptsKey(email));
-			await this.kv.setItem(this.getEmailVerificationCodeKey(email), verificationCode, EMAIL_VERIFICATION_CODE_TTL);
-			return Response.json({});
-		} catch (e) {
-			console.error("Failed to send email verification code", e);
-			await this.kv.removeItem(cooldownKey);
-			return Response.json(invalidArgument("EMAIL_DELIVERY_FAILED"), { status: 400 });
-		}
-	};
-	loginEmail = async (request, handler) => {
-		const { data, error } = valid(loginEmailSchema, await request.json());
-		if (error) return Response.json(error, { status: error.error.code });
-		const { email, verificationCode, attributes } = data;
-		const key = this.getEmailVerificationCodeKey(email);
-		const attemptsKey = this.getEmailVerificationAttemptsKey(email);
-		const stored = await this.kv.getItem(key);
-		if (typeof stored !== "string") return Response.json(invalidArgument("INVALID_VERIFICATION_CODE"), { status: 400 });
-		if (await this.kv.increment(attemptsKey, EMAIL_VERIFICATION_CODE_TTL) > this.maxVerificationAttempts) {
-			await this.kv.removeItem(key);
-			const error = invalidArgument("VERIFICATION_CODE_ATTEMPTS_EXCEEDED");
-			return Response.json(error, { status: error.error.code });
-		}
-		if (stored.length !== verificationCode.length || !timingSafeEqual(Buffer.from(stored), Buffer.from(verificationCode))) return Response.json(invalidArgument("INVALID_VERIFICATION_CODE"), { status: 400 });
-		await this.kv.removeItem(key);
-		await this.kv.removeItem(attemptsKey);
-		const principal = await handler(request, {
+		const { email, turnstileToken } = parse(sendEmailVerificationCodeSchema, await readJson(request));
+		await verifyTurnstileToken(this.turnstileSecretKey, turnstileToken);
+		await this.emailCodes.send(email, sender);
+		return Response.json({});
+	});
+	verifyEmailCode = (email, verificationCode) => this.emailCodes.verify(email, verificationCode);
+	loginEmail = (request, handler) => this.guard(async () => {
+		const { setTiming } = timing({ enabled: this.timing });
+		const { email, verificationCode, attributes = {} } = parse(loginEmailSchema, await readJson(request));
+		await this.emailCodes.verify(email, verificationCode);
+		const claims = {
+			sub: email,
+			email,
+			email_verified: true
+		};
+		return this.authorize(request, handler, {
 			provider: "EMAIL",
 			userInfo: {
-				claims: {
-					sub: email,
-					email,
-					email_verified: true
-				},
+				claims,
 				data: {}
 			},
-			attributes: attributes ?? {}
-		});
-		const session = this.repository.createSession();
-		session.setAttribute(PRINCIPAL_NAME_INDEX_NAME, principal.name);
-		await this.repository.save(session);
-		const response = new Response(JSON.stringify(principal), {
-			status: 200,
-			headers: { "Content-Type": "application/json" }
-		});
-		const maxAge = session.getMaxInactiveInterval();
-		setCookie(response, this.cookieName, session.getId(), {
-			...this.cookieOptions,
-			maxAge
-		});
-		return response;
-	};
+			attributes
+		}, setTiming);
+	});
 	/**
-	* Step 1 of the desktop / native app sign-in handshake. The caller already
-	* completed normal sign-in on the web (so a cookie session exists); this
-	* issues a 5-minute single-use code that the web page hands off to the
-	* desktop client via a loopback redirect.
+	* Step 1 of the desktop / native app sign-in handshake. The caller already completed normal
+	* sign-in on the web (so a cookie session exists); this issues a 5-minute single-use code that
+	* the web page hands off to the desktop client via a loopback redirect.
 	*
-	* PKCE (RFC 7636, S256 only): the desktop generates a random `code_verifier`
-	* before opening the browser, derives `code_challenge = base64url(sha256(verifier))`,
-	* and threads the challenge through the URL → web page → here. We pin
-	* the challenge to the code in KV; `desktopExchange` enforces that the
-	* caller knows the matching verifier. This blocks an attacker who only
-	* intercepts the auth code (browser history, malicious extension, packet
-	* capture on loopback) from exchanging it.
+	* PKCE (RFC 7636, S256 only): the desktop generates a random `code_verifier` before opening the
+	* browser, derives `code_challenge = base64url(sha256(verifier))`, and threads the challenge
+	* through the URL → web page → here. The challenge is pinned to the code; `desktopExchange`
+	* enforces that the caller knows the matching verifier. This blocks an attacker who only
+	* intercepts the auth code (browser history, malicious extension, packet capture on loopback)
+	* from exchanging it.
 	*
-	* Requires an authenticated cookie session — anonymous callers get 401.
-	* Throttling / abuse protection on this endpoint is the API layer's job
-	* (rate-limit per principal); the SDK doesn't gate it because the
-	* upstream sign-in flow already passed CAPTCHA / OAuth / verification.
+	* Requires an authenticated cookie session: anonymous callers get 401. Throttling / abuse
+	* protection on this endpoint is the API layer's job (rate-limit per principal); the SDK does
+	* not gate it because the upstream sign-in flow already passed CAPTCHA / OAuth / verification.
 	*/
-	desktopAuthorize = async (request) => {
+	desktopAuthorize = (request) => this.guard(async () => {
 		const principal = await this.getPrincipal(request);
-		if (!principal) return Response.json({ error: {
-			code: 401,
-			status: "UNAUTHENTICATED",
-			message: "sign in first",
-			details: []
-		} }, { status: 401 });
-		let body;
-		try {
-			body = await request.json();
-		} catch {
-			return Response.json(invalidArgument("INVALID_ARGUMENT"), { status: 400 });
-		}
-		const codeChallenge = typeof body.code_challenge === "string" ? body.code_challenge : null;
-		if (!codeChallenge || body.code_challenge_method !== "S256" || !PKCE_FORMAT.test(codeChallenge)) return Response.json(invalidArgument("INVALID_ARGUMENT"), { status: 400 });
-		const code = randomUUID();
-		const record = {
-			name: principal.name,
-			cc: codeChallenge
-		};
-		await this.kv.setItem(this.getDesktopCodeKey(code), JSON.stringify(record), 300);
+		if (!principal) throw unauthenticated("Sign in first");
+		const { code_challenge } = parse(desktopAuthorizeSchema, await readJson(request));
+		const code = await this.desktopCodes.issue(principal, code_challenge);
 		return Response.json({ code });
-	};
+	});
 	/**
-	* Step 2 of the desktop / native app sign-in handshake. The desktop
-	* client hands back the auth code it received via the loopback callback,
-	* and we mint a fresh session for it — independent of the web cookie
-	* session that originally `authorize`'d the code, so logging out on
-	* either side doesn't cascade to the other.
+	* Step 2 of the desktop / native app sign-in handshake. The desktop client hands back the auth
+	* code it received via the loopback callback, and we mint a fresh session for it, independent
+	* of the web cookie session that originally authorized the code, so logging out on either side
+	* does not cascade to the other.
 	*
-	* Cookie attributes: defaults to `SameSite=None; Secure` so the cookie
-	* survives cross-site fetches from the desktop renderer's `file://` /
-	* `app://` origin. The configured base `cookieOptions` provide
-	* everything else (`domain`, `path`, `httpOnly`, `maxAge`); the override
-	* is targeted at the SameSite/Secure pair only. In a non-HTTPS dev
-	* backend this combination is rejected by Chromium — see the desktop
-	* sign-in PRD for workarounds.
+	* Cookie attributes: `SameSite=None; Secure` so the cookie survives cross-site fetches from the
+	* desktop renderer's `file://` / `app://` origin. The configured `cookieOptions` provide
+	* everything else (`domain`, `path`, `httpOnly`); the override is targeted at the
+	* SameSite/Secure pair only. In a non-HTTPS dev backend this combination is rejected by
+	* Chromium, see the desktop sign-in PRD for workarounds.
 	*
-	* No CSRF check needed — the request carries no cookie, the auth code
-	* itself is the credential, and KV's single-use removal blocks replay.
+	* No CSRF check needed: the request carries no cookie, the auth code itself is the credential,
+	* and the code's single-use removal blocks replay.
 	*/
-	desktopExchange = async (request) => {
-		let body;
-		try {
-			body = await request.json();
-		} catch {
-			return Response.json(invalidArgument("INVALID_ARGUMENT"), { status: 400 });
-		}
-		const code = typeof body.code === "string" ? body.code : null;
-		const verifier = typeof body.code_verifier === "string" ? body.code_verifier : null;
-		if (!code || !verifier || !PKCE_FORMAT.test(verifier)) return Response.json(invalidArgument("INVALID_ARGUMENT"), { status: 400 });
-		const key = this.getDesktopCodeKey(code);
-		const raw = await this.kv.getItem(key);
-		if (typeof raw !== "string") return Response.json(invalidArgument("INVALID_DESKTOP_CODE"), { status: 400 });
-		let record;
-		try {
-			record = JSON.parse(raw);
-		} catch {
-			await this.kv.removeItem(key);
-			return Response.json(invalidArgument("INVALID_DESKTOP_CODE"), { status: 400 });
-		}
-		const computed = createHash("sha256").update(verifier).digest();
-		const stored = Buffer.from(record.cc, "base64url");
-		if (stored.length !== computed.length || !timingSafeEqual(computed, stored)) return Response.json(invalidArgument("INVALID_DESKTOP_CODE"), { status: 400 });
-		await this.kv.removeItem(key);
-		const session = this.repository.createSession();
-		session.setAttribute(PRINCIPAL_NAME_INDEX_NAME, record.name);
+	desktopExchange = (request) => this.guard(async () => {
+		const { code, code_verifier } = parse(desktopExchangeSchema, await readJson(request));
+		const principal = await this.desktopCodes.redeem(code, code_verifier);
+		const session = await this.signIn(principal);
 		session.setAttribute("client_type", "desktop");
 		await this.repository.save(session);
-		const response = Response.json({ ok: true });
-		const maxAge = session.getMaxInactiveInterval();
-		setCookie(response, this.cookieName, session.getId(), {
-			...this.cookieOptions,
+		return this.withSession(Response.json({ ok: true }), session, {
 			sameSite: "none",
-			secure: true,
-			maxAge
+			secure: true
 		});
-		return response;
-	};
-	sendPhoneVerificationCode = async (_request, _sender) => {
-		return Response.json({ error: "not_implemented" }, { status: 501 });
-	};
-	loginPhone = async (_request, _handler) => {
-		return Response.json({ error: "not_implemented" }, { status: 501 });
-	};
+	});
 	kick = async (principal) => {
 		const sessions = await this.repository.findByPrincipalName(principal.name);
 		for (const sessionId of sessions.keys()) await this.repository.deleteById(sessionId);
@@ -646,47 +532,26 @@ var Auth = class {
 		session.setLastAccessedTime(now);
 		await this.repository.save(session);
 	}
-	isAuthenticated = async (request) => {
-		const sessionId = this.getSessionId(request);
-		if (!sessionId) return false;
-		const session = await this.repository.findById(sessionId);
-		if (!session) return false;
-		if (!session.getAttribute("org.springframework.session.FindByIndexNameSessionRepository.PRINCIPAL_NAME_INDEX_NAME")) return false;
+	getPrincipal = async (request) => {
+		const session = await this.loadSession(request);
+		const principal = session && this.principalOf(session);
+		if (!principal) return null;
 		await this.touch(session);
-		return true;
+		return principal;
+	};
+	isAuthenticated = async (request) => {
+		return await this.getPrincipal(request) !== null;
 	};
 	getSession = async (request, create) => {
-		const sessionId = this.getSessionId(request);
-		if (!sessionId) {
-			if (create) {
-				const session = this.repository.createSession();
-				await this.repository.save(session);
-				return session;
-			} else return null;
-		}
-		const session = await this.repository.findById(sessionId);
-		if (!session) {
-			if (create) {
-				const session = this.repository.createSession();
-				await this.repository.save(session);
-				return session;
-			} else return null;
-		}
-		return session;
+		const session = await this.loadSession(request);
+		if (session || !create) return session;
+		const created = this.repository.createSession();
+		await this.repository.save(created);
+		return created;
 	};
 	deleteSession = async (sessionId) => {
 		await this.repository.deleteById(sessionId);
 	};
-	getPrincipal = async (request) => {
-		const sessionId = this.getSessionId(request);
-		if (!sessionId) return null;
-		const session = await this.repository.findById(sessionId);
-		if (!session) return null;
-		const name = session.getAttribute(PRINCIPAL_NAME_INDEX_NAME);
-		if (!name) return null;
-		await this.touch(session);
-		return { name: String(name) };
-	};
 	listSessions = async (principal) => {
 		const sessions = await this.repository.findByPrincipalName(principal.name);
 		return Array.from(sessions.values());