@kidd-cli/core 0.1.1 → 0.2.0

package/dist/middleware/auth.js

@@ -1,18 +1,40 @@
-import { n as decorateContext, t as middleware } from "../middleware-D3psyhYo.js";
-import "../project-NPtYX2ZX.js";
-import { t as createStore } from "../create-store-BQUX0tAn.js";
+import { n as decorateContext, t as middleware } from "../middleware-BFBKNSPQ.js";
+import "../project-DuXgjaa_.js";
+import { t as createStore } from "../create-store-D-fQpCql.js";
+import { t as createHttpClient } from "../create-http-client-tZJWlWp1.js";
 import { join } from "node:path";
 import { ok } from "@kidd-cli/utils/fp";
 import { match as match$1 } from "ts-pattern";
 import { platform } from "node:os";
 import { readFileSync } from "node:fs";
+import { Buffer } from "node:buffer";
+import { execFile } from "node:child_process";
+import { createServer } from "node:http";
 import { parse } from "dotenv";
 import { attempt as attempt$1 } from "es-toolkit";
 import { z } from "zod";
-import { execFile } from "node:child_process";
-import { randomBytes } from "node:crypto";
-import { createServer } from "node:http";
+import { createHash, randomBytes } from "node:crypto";
+
+//#region src/middleware/http/build-auth-headers.ts
+/**
+* Convert auth credentials into HTTP headers.
+*
+* Uses exhaustive pattern matching to map each credential variant to
+* the appropriate header format.
+*
+* @module
+*/
+/**
+* Convert an auth credential into HTTP headers.
+*
+* @param credential - The credential to convert.
+* @returns A record of header name to header value.
+*/
+function buildAuthHeaders(credential) {
+	return match$1(credential).with({ type: "bearer" }, (c) => ({ Authorization: `Bearer ${c.token}` })).with({ type: "basic" }, (c) => ({ Authorization: `Basic ${Buffer.from(`${c.username}:${c.password}`).toString("base64")}` })).with({ type: "api-key" }, (c) => ({ [c.headerName]: c.key })).with({ type: "custom" }, (c) => ({ ...c.headers })).exhaustive();
+}
 
+//#endregion
 //#region src/middleware/auth/constants.ts
 /**
 * Default filename for file-based credential storage.
@@ -23,6 +45,26 @@ const DEFAULT_AUTH_FILENAME = "auth.json";
 */
 const TOKEN_VAR_SUFFIX = "_TOKEN";
 /**
+* Default port for the local OAuth callback server (`0` = ephemeral).
+*/
+const DEFAULT_OAUTH_PORT = 0;
+/**
+* Default callback path for the local OAuth server.
+*/
+const DEFAULT_OAUTH_CALLBACK_PATH = "/callback";
+/**
+* Default timeout for the OAuth PKCE flow in milliseconds (2 minutes).
+*/
+const DEFAULT_OAUTH_TIMEOUT = 12e4;
+/**
+* Default poll interval for the device code flow in milliseconds (5 seconds).
+*/
+const DEFAULT_DEVICE_CODE_POLL_INTERVAL = 5e3;
+/**
+* Default timeout for the device code flow in milliseconds (5 minutes).
+*/
+const DEFAULT_DEVICE_CODE_TIMEOUT = 3e5;
+/**
 * Derive the default environment variable name from a CLI name.
 *
 * Converts kebab-case to SCREAMING_SNAKE_CASE and appends `_TOKEN`.
@@ -36,7 +78,503 @@ function deriveTokenVar(cliName) {
 }
 
 //#endregion
-//#region src/middleware/auth/resolve-dotenv.ts
+//#region src/middleware/auth/credential.ts
+/**
+* Check whether a token string is a non-empty, non-whitespace value.
+*
+* Acts as a type guard: when it returns true, TypeScript narrows the
+* token to `string`. Consolidates the repeated `!token || token.trim() === ''`
+* guard found across strategy resolvers.
+*
+* @param token - The token string to check.
+* @returns True when the token is a non-empty string.
+*/
+function isValidToken(token) {
+	if (!token) return false;
+	if (token.trim() === "") return false;
+	return true;
+}
+/**
+* Construct a bearer credential from a raw token string.
+*
+* @param token - The access token value.
+* @returns A BearerCredential with `type: 'bearer'`.
+*/
+function createBearerCredential(token) {
+	return {
+		token,
+		type: "bearer"
+	};
+}
+/**
+* POST form-encoded parameters to a URL.
+*
+* Wraps the duplicated `fetch` call with `Content-Type: application/x-www-form-urlencoded`
+* found in the OAuth and device code strategies. Returns null on network or
+* request failure instead of throwing.
+*
+* @param url - The endpoint URL.
+* @param params - The URL-encoded form parameters.
+* @param signal - Optional AbortSignal for timeout/cancellation.
+* @returns The fetch Response on success, null on failure.
+*/
+async function postFormEncoded(url, params, signal) {
+	try {
+		return await fetch(url, {
+			body: params.toString(),
+			headers: { "Content-Type": "application/x-www-form-urlencoded" },
+			method: "POST",
+			signal
+		});
+	} catch {
+		return null;
+	}
+}
+
+//#endregion
+//#region src/middleware/auth/oauth-server.ts
+/**
+* Shared utilities for OAuth-based auth resolvers.
+*
+* Extracted from the local HTTP server, browser-launch, and
+* lifecycle patterns shared by the PKCE and device-code flows.
+*
+* @module
+*/
+const CLOSE_PAGE_HTML = [
+	"<!DOCTYPE html>",
+	"<html>",
+	"<body><p>Authentication complete. You can close this tab.</p></body>",
+	"</html>"
+].join("\n");
+/**
+* Create a deferred promise with externally accessible resolve.
+*
+* Uses a mutable state container to capture the promise resolver --
+* this is an intentional exception to immutability rules because the
+* Promise constructor API requires synchronous resolver capture.
+*
+* @returns A deferred object with promise and resolve.
+*/
+function createDeferred() {
+	const state = { resolve: null };
+	return {
+		promise: new Promise((resolve) => {
+			state.resolve = resolve;
+		}),
+		resolve: (value) => {
+			if (state.resolve) state.resolve(value);
+		}
+	};
+}
+/**
+* Create a clearable timeout.
+*
+* Returns a promise that resolves after `ms` milliseconds and a `clear`
+* function that cancels the timer so it does not hold the event loop open.
+*
+* Uses a mutable state container to capture the timer id -- this is an
+* intentional exception to immutability rules because `setTimeout`
+* returns an opaque handle that must be stored for later cancellation.
+*
+* @param ms - Duration in milliseconds.
+* @returns A Timeout with `promise` and `clear`.
+*/
+function createTimeout(ms) {
+	const state = { id: null };
+	return {
+		clear: () => {
+			if (state.id !== null) {
+				clearTimeout(state.id);
+				state.id = null;
+			}
+		},
+		promise: new Promise((resolve) => {
+			state.id = setTimeout(resolve, ms);
+		})
+	};
+}
+/**
+* Track socket connections on a server so they can be destroyed on close.
+*
+* Mutates the provided socket set -- this is an intentional exception to
+* immutability rules because the HTTP server API is inherently stateful.
+*
+* @param server - The HTTP server.
+* @param sockets - The set to track sockets in.
+*/
+function trackConnections(server, sockets) {
+	server.on("connection", (socket) => {
+		sockets.add(socket);
+		socket.on("close", () => {
+			sockets.delete(socket);
+		});
+	});
+}
+/**
+* Close a server and destroy all active connections immediately.
+*
+* `server.close()` only stops accepting new connections -- existing
+* keep-alive connections hold the event loop open. This helper
+* destroys every tracked socket so the process can exit cleanly.
+*
+* @param server - The HTTP server to close.
+* @param sockets - The set of tracked sockets.
+*/
+function destroyServer(server, sockets) {
+	server.close();
+	Array.from(sockets, (socket) => socket.destroy());
+	sockets.clear();
+}
+/**
+* Send an HTML success page and end the response.
+*
+* @param res - The server response object.
+*/
+function sendSuccessPage(res) {
+	res.writeHead(200, { "Content-Type": "text/html" });
+	res.end(CLOSE_PAGE_HTML);
+}
+/**
+* Check whether a URL is safe for use as an OAuth endpoint.
+*
+* Requires HTTPS for all URLs except loopback addresses, where
+* HTTP is permitted per RFC 8252 §8.3 (native app redirect URIs).
+*
+* @param url - The URL string to validate.
+* @returns True when the URL uses HTTPS or HTTP on a loopback address.
+*/
+function isSecureAuthUrl(url) {
+	try {
+		const parsed = new URL(url);
+		if (parsed.protocol === "https:") return true;
+		if (parsed.protocol !== "http:") return false;
+		return isLoopbackHost(parsed.hostname);
+	} catch {
+		return false;
+	}
+}
+/**
+* Open a URL in the user's default browser using a platform-specific command.
+*
+* Validates that the URL uses the HTTP or HTTPS protocol before opening
+* to prevent dangerous schemes like `javascript:` or `data:`. Silently
+* returns if the URL is invalid.
+*
+* On Windows, `start` is a `cmd.exe` built-in -- not a standalone executable --
+* so it must be invoked via `cmd /c start "" <url>`. The empty string argument
+* prevents `cmd` from interpreting the URL as a window title.
+*
+* @param url - The URL to open (must use http: or https: protocol).
+*/
+function openBrowser(url) {
+	if (!isHttpUrl(url)) return;
+	const { command, args } = match$1(platform()).with("darwin", () => ({
+		args: [url],
+		command: "open"
+	})).with("win32", () => ({
+		args: [
+			"/c",
+			"start",
+			"",
+			escapeCmdMeta(url)
+		],
+		command: "cmd"
+	})).otherwise(() => ({
+		args: [url],
+		command: "xdg-open"
+	}));
+	execFile(command, args).on("error", () => void 0);
+}
+/**
+* Start a local HTTP server on `127.0.0.1` with socket tracking.
+*
+* Returns a handle containing the server, tracked sockets, and a port
+* promise that resolves once the server is listening.
+*
+* @param options - Server configuration.
+* @returns A LocalServerHandle with port, server, and sockets.
+*/
+function startLocalServer(options) {
+	const portDeferred = createDeferred();
+	const sockets = /* @__PURE__ */ new Set();
+	const server = createServer(options.onRequest);
+	trackConnections(server, sockets);
+	server.on("error", () => {
+		destroyServer(server, sockets);
+		portDeferred.resolve(null);
+	});
+	server.listen(options.port, "127.0.0.1", () => {
+		const addr = server.address();
+		if (addr === null || typeof addr === "string") {
+			destroyServer(server, sockets);
+			portDeferred.resolve(null);
+			return;
+		}
+		portDeferred.resolve(addr.port);
+	});
+	return {
+		port: portDeferred.promise,
+		server,
+		sockets
+	};
+}
+/**
+* Check whether a URL uses the HTTP or HTTPS protocol.
+*
+* Rejects dangerous schemes like `javascript:`, `data:`, and `file:`
+* to prevent browser-based attacks when opening untrusted URLs.
+*
+* @private
+* @param url - The URL string to validate.
+* @returns True when the URL uses http: or https: protocol.
+*/
+function isHttpUrl(url) {
+	try {
+		const parsed = new URL(url);
+		return parsed.protocol === "https:" || parsed.protocol === "http:";
+	} catch {
+		return false;
+	}
+}
+/**
+* Check whether a hostname is a loopback address.
+*
+* RFC 8252 §8.3 permits HTTP for loopback interfaces during
+* native app authorization flows.
+*
+* @private
+* @param hostname - The hostname to check.
+* @returns True when the hostname is a loopback address.
+*/
+function isLoopbackHost(hostname) {
+	return hostname === "127.0.0.1" || hostname === "[::1]" || hostname === "localhost";
+}
+/**
+* Escape `cmd.exe` metacharacters in a URL string.
+*
+* Characters like `&`, `|`, `<`, `>`, and `^` are interpreted as
+* command separators or redirectors by `cmd.exe`. Prefixing each
+* with `^` neutralises the special meaning.
+*
+* @private
+* @param url - The URL to escape.
+* @returns The escaped URL string.
+*/
+function escapeCmdMeta(url) {
+	return url.replaceAll(/[&|<>^]/g, "^$&");
+}
+
+//#endregion
+//#region src/middleware/auth/strategies/device-code.ts
+/**
+* OAuth 2.0 Device Authorization Grant resolver (RFC 8628).
+*
+* Requests a device code, displays the verification URL and user code,
+* and polls the token endpoint until the user completes authorization
+* or the flow times out.
+*
+* @module
+*/
+/**
+* RFC 8628 slow_down backoff increment in milliseconds.
+*/
+const SLOW_DOWN_INCREMENT = 5e3;
+/**
+* RFC 8628 device code grant type URN.
+*/
+const DEVICE_CODE_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:device_code";
+/**
+* Resolve a bearer credential via OAuth 2.0 Device Authorization Grant.
+*
+* 1. POSTs to the device authorization endpoint to obtain a device code
+* 2. Displays the verification URL and user code via prompts
+* 3. Optionally opens the verification URL in the browser
+* 4. Polls the token endpoint until authorization completes or times out
+*
+* @param options - Device code flow configuration.
+* @returns A bearer credential on success, null on failure or timeout.
+*/
+async function resolveFromDeviceCode(options) {
+	if (!isSecureAuthUrl(options.deviceAuthUrl)) return null;
+	if (!isSecureAuthUrl(options.tokenUrl)) return null;
+	const deadline = Date.now() + options.timeout;
+	const signal = AbortSignal.timeout(options.timeout);
+	const authResponse = await requestDeviceAuth({
+		clientId: options.clientId,
+		deviceAuthUrl: options.deviceAuthUrl,
+		scopes: options.scopes,
+		signal
+	});
+	if (!authResponse) return null;
+	await displayUserCode(options.prompts, authResponse.verificationUri, authResponse.userCode);
+	if (options.openBrowserOnStart !== false) openBrowser(authResponse.verificationUri);
+	const interval = resolveInterval(authResponse.interval, options.pollInterval);
+	return pollForToken({
+		clientId: options.clientId,
+		deadline,
+		deviceCode: authResponse.deviceCode,
+		interval,
+		signal,
+		tokenUrl: options.tokenUrl
+	});
+}
+/**
+* Request a device code from the authorization server.
+*
+* @private
+* @param options - Device auth request parameters.
+* @returns The parsed device auth response, or null on failure.
+*/
+async function requestDeviceAuth(options) {
+	const body = new URLSearchParams({ client_id: options.clientId });
+	if (options.scopes.length > 0) body.set("scope", options.scopes.join(" "));
+	const response = await postFormEncoded(options.deviceAuthUrl, body, options.signal);
+	if (!response) return null;
+	if (!response.ok) return null;
+	try {
+		return parseDeviceAuthResponse(await response.json());
+	} catch {
+		return null;
+	}
+}
+/**
+* Parse a device authorization response body.
+*
+* @private
+* @param data - The raw response data.
+* @returns The parsed response, or null if required fields are missing.
+*/
+function parseDeviceAuthResponse(data) {
+	if (typeof data !== "object" || data === null) return null;
+	const record = data;
+	if (typeof record.device_code !== "string" || record.device_code === "") return null;
+	if (typeof record.user_code !== "string" || record.user_code === "") return null;
+	if (typeof record.verification_uri !== "string" || record.verification_uri === "") return null;
+	const interval = resolveServerInterval(record.interval);
+	return {
+		deviceCode: record.device_code,
+		interval,
+		userCode: record.user_code,
+		verificationUri: record.verification_uri
+	};
+}
+/**
+* Display the verification URL and user code to the user.
+*
+* Uses `prompts.text()` to show the information and wait for
+* the user to press Enter to acknowledge.
+*
+* @private
+* @param prompts - The prompts instance.
+* @param verificationUri - The URL the user should visit.
+* @param userCode - The code the user should enter.
+*/
+async function displayUserCode(prompts, verificationUri, userCode) {
+	try {
+		await prompts.text({
+			defaultValue: "",
+			message: `Open ${verificationUri} and enter code: ${userCode} (press Enter to continue)`
+		});
+	} catch {}
+}
+/**
+* Resolve the poll interval, preferring server-provided value.
+*
+* @private
+* @param serverInterval - The interval from the server response (in ms), or null.
+* @param configInterval - The configured default interval.
+* @returns The resolved interval in milliseconds.
+*/
+function resolveInterval(serverInterval, configInterval) {
+	if (serverInterval !== null) return serverInterval;
+	return configInterval;
+}
+/**
+* Poll the token endpoint for an access token using recursive tail-call style.
+*
+* Handles RFC 8628 error codes:
+* - `authorization_pending` -- continue polling
+* - `slow_down` -- increase interval by 5 seconds, continue
+* - `expired_token` -- return null
+* - `access_denied` -- return null
+*
+* @private
+* @param options - Polling parameters.
+* @returns A bearer credential on success, null on failure or timeout.
+*/
+async function pollForToken(options) {
+	if (Date.now() >= options.deadline) return null;
+	await sleep(options.interval);
+	if (Date.now() >= options.deadline) return null;
+	return match$1(await requestToken({
+		clientId: options.clientId,
+		deviceCode: options.deviceCode,
+		signal: options.signal,
+		tokenUrl: options.tokenUrl
+	})).with({ status: "success" }, (r) => r.credential).with({ status: "pending" }, () => pollForToken(options)).with({ status: "slow_down" }, () => pollForToken({
+		...options,
+		interval: options.interval + SLOW_DOWN_INCREMENT
+	})).with({ status: "denied" }, () => null).with({ status: "expired" }, () => null).with({ status: "error" }, () => null).exhaustive();
+}
+/**
+* Convert a server-provided interval value to milliseconds.
+*
+* @private
+* @param value - The raw interval value from the server response.
+* @returns The interval in milliseconds, or null if not a number.
+*/
+function resolveServerInterval(value) {
+	if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) return null;
+	return Math.max(1e3, Math.min(value * 1e3, 6e4));
+}
+/**
+* Sleep for a given duration.
+*
+* @private
+* @param ms - Duration in milliseconds.
+* @returns A promise that resolves after the delay.
+*/
+function sleep(ms) {
+	return new Promise((resolve) => {
+		setTimeout(resolve, ms);
+	});
+}
+/**
+* Request an access token from the token endpoint.
+*
+* @private
+* @param options - Token request parameters.
+* @returns A discriminated result indicating the outcome.
+*/
+async function requestToken(options) {
+	const body = new URLSearchParams({
+		client_id: options.clientId,
+		device_code: options.deviceCode,
+		grant_type: DEVICE_CODE_GRANT_TYPE
+	});
+	const response = await postFormEncoded(options.tokenUrl, body, options.signal);
+	if (!response) return { status: "error" };
+	try {
+		const data = await response.json();
+		if (typeof data !== "object" || data === null) return { status: "error" };
+		const record = data;
+		if (response.ok && typeof record.access_token === "string" && record.access_token !== "") {
+			if (typeof record.token_type === "string" && record.token_type.toLowerCase() !== "bearer") return { status: "error" };
+			return {
+				credential: createBearerCredential(record.access_token),
+				status: "success"
+			};
+		}
+		if (typeof record.error !== "string") return { status: "error" };
+		return match$1(record.error).with("authorization_pending", () => ({ status: "pending" })).with("slow_down", () => ({ status: "slow_down" })).with("expired_token", () => ({ status: "expired" })).with("access_denied", () => ({ status: "denied" })).otherwise(() => ({ status: "error" }));
+	} catch {
+		return { status: "error" };
+	}
+}
+
+//#endregion
+//#region src/middleware/auth/strategies/dotenv.ts
 /**
 * Resolve a bearer credential from a `.env` file without mutating `process.env`.
 *
@@ -53,15 +591,12 @@ function resolveFromDotenv(options) {
 	const [readError, content] = attempt$1(() => readFileSync(options.path, "utf8"));
 	if (readError || content === null) return null;
 	const token = parse(content)[options.tokenVar];
-	if (!token) return null;
-	return {
-		token,
-		type: "bearer"
-	};
+	if (!isValidToken(token)) return null;
+	return createBearerCredential(token);
 }
 
 //#endregion
-//#region src/middleware/auth/resolve-env.ts
+//#region src/middleware/auth/strategies/env.ts
 /**
 * Resolve a bearer credential from a process environment variable.
 *
@@ -70,11 +605,8 @@ function resolveFromDotenv(options) {
 */
 function resolveFromEnv(options) {
 	const token = process.env[options.tokenVar];
-	if (!token) return null;
-	return {
-		token,
-		type: "bearer"
-	};
+	if (!isValidToken(token)) return null;
+	return createBearerCredential(token);
 }
 
 //#endregion
@@ -121,7 +653,7 @@ const authCredentialSchema = z.discriminatedUnion("type", [
 ]);
 
 //#endregion
-//#region src/middleware/auth/resolve-file.ts
+//#region src/middleware/auth/strategies/file.ts
 /**
 * Resolve credentials from a JSON file on disk.
 *
@@ -131,337 +663,224 @@ const authCredentialSchema = z.discriminatedUnion("type", [
 *
 * @param options - Options with the filename and directory name.
 * @returns A validated auth credential, or null if not found or invalid.
-*/
-function resolveFromFile(options) {
-	const data = createStore({ dirName: options.dirName }).load(options.filename);
-	if (data === null) return null;
-	const result = authCredentialSchema.safeParse(data);
-	if (!result.success) return null;
-	return result.data;
-}
-
-//#endregion
-//#region src/middleware/auth/resolve-oauth.ts
-/**
-* Maximum request body size in bytes (16 KB).
-*
-* Limits memory consumption from the local OAuth callback server
-* to prevent resource exhaustion from oversized payloads.
-*
-* @private
-*/
-const MAX_BODY_BYTES = 16384;
-const CLOSE_PAGE_HTML = [
-	"<!DOCTYPE html>",
-	"<html>",
-	"<body><p>Authentication complete. You can close this tab.</p></body>",
-	"</html>"
-].join("\n");
-/**
-* Resolve a bearer credential via an OAuth browser flow.
-*
-* Starts a minimal HTTP server on a local port, opens the user's browser
-* to the auth URL with a callback parameter, and waits for the token
-* to arrive via POST body.
-*
-* Only POST requests with a JSON body containing a `token` field are
-* accepted. Query-string tokens are rejected to avoid leaking credentials
-* in server logs, browser history, and referrer headers.
-*
-* @param options - OAuth flow configuration.
-* @returns A bearer credential on success, null on timeout.
-*/
-async function resolveFromOAuth(options) {
-	const controller = new AbortController();
-	const state = randomBytes(32).toString("hex");
-	const timeout = createTimeout(options.timeout);
-	const tokenPromise = listenForToken({
-		callbackPath: options.callbackPath,
-		port: options.port,
-		signal: controller.signal,
-		state
-	});
-	const timeoutPromise = timeout.promise.then(() => {
-		controller.abort();
-		return null;
-	});
-	const serverPort = await getServerPort(tokenPromise);
-	if (serverPort === null) {
-		controller.abort();
-		timeout.clear();
-		return null;
-	}
-	const callbackUrl = `http://127.0.0.1:${String(serverPort)}${options.callbackPath}`;
-	openBrowser(`${options.authUrl}?callback_url=${encodeURIComponent(callbackUrl)}&state=${encodeURIComponent(state)}`);
-	const result = await Promise.race([tokenPromise.result, timeoutPromise]);
-	timeout.clear();
-	controller.abort();
-	return result;
-}
-/**
-* Start an HTTP server that listens for an OAuth callback token.
-*
-* The server accepts POST requests with a JSON body `{ "token": "..." }`
-* on the configured callback path. All other requests receive a 400.
-*
-* @private
-* @param options - Listener configuration.
-* @returns A TokenListener with port and result promises.
-*/
-function listenForToken(options) {
-	const portResolvers = createDeferred();
-	const resultResolvers = createDeferred();
-	const sockets = /* @__PURE__ */ new Set();
-	const server = createServer((req, res) => {
-		extractTokenFromBody(req, options.callbackPath, options.state, (token) => {
-			if (!token) {
-				res.writeHead(400);
-				res.end();
-				return;
-			}
-			sendSuccessPage(res);
-			destroyServer(server, sockets);
-			resultResolvers.resolve({
-				token,
-				type: "bearer"
-			});
-		});
-	});
-	trackConnections(server, sockets);
-	server.on("error", () => {
-		destroyServer(server, sockets);
-		portResolvers.resolve(null);
-		resultResolvers.resolve(null);
-	});
-	options.signal.addEventListener("abort", () => {
-		destroyServer(server, sockets);
-		resultResolvers.resolve(null);
-	});
-	server.listen(options.port, "127.0.0.1", () => {
-		const addr = server.address();
-		if (addr === null || typeof addr === "string") {
-			destroyServer(server, sockets);
-			portResolvers.resolve(null);
-			resultResolvers.resolve(null);
-			return;
-		}
-		portResolvers.resolve(addr.port);
-	});
-	return {
-		port: portResolvers.promise,
-		result: resultResolvers.promise
-	};
+*/
+function resolveFromFile(options) {
+	const data = createStore({ dirName: options.dirName }).load(options.filename);
+	if (data === null) return null;
+	const result = authCredentialSchema.safeParse(data);
+	if (!result.success) return null;
+	return result.data;
 }
+
+//#endregion
+//#region src/middleware/auth/strategies/oauth.ts
 /**
-* Track socket connections on a server so they can be destroyed on close.
+* OAuth 2.0 Authorization Code + PKCE resolver (RFC 7636 + RFC 8252).
 *
-* Mutates the provided socket set — this is an intentional exception to
-* immutability rules because the HTTP server API is inherently stateful.
+* Opens the user's browser to the authorization URL with a PKCE challenge,
+* listens for a GET redirect with an authorization code on a local server,
+* and exchanges the code at the token endpoint with the code verifier.
 *
-* @private
-* @param server - The HTTP server.
-* @param sockets - The set to track sockets in.
+* @module
 */
-function trackConnections(server, sockets) {
-	server.on("connection", (socket) => {
-		sockets.add(socket);
-		socket.on("close", () => {
-			sockets.delete(socket);
-		});
-	});
-}
 /**
-* Close a server and destroy all active connections immediately.
+* Resolve a bearer credential via OAuth 2.0 Authorization Code + PKCE.
 *
-* `server.close()` only stops accepting new connections — existing
-* keep-alive connections hold the event loop open. This helper
-* destroys every tracked socket so the process can exit cleanly.
+* 1. Generates a `code_verifier` and derives the `code_challenge`
+* 2. Starts a local HTTP server on `127.0.0.1`
+* 3. Opens the browser to the authorization URL with PKCE params
+* 4. Receives the authorization code via GET redirect
+* 5. Exchanges the code at the token endpoint with the verifier
+* 6. Returns the access token as a bearer credential
 *
-* @private
-* @param server - The HTTP server to close.
-* @param sockets - The set of tracked sockets.
+* @param options - PKCE flow configuration.
+* @returns A bearer credential on success, null on failure or timeout.
 */
-function destroyServer(server, sockets) {
-	server.close();
-	Array.from(sockets, (socket) => socket.destroy());
-	sockets.clear();
+async function resolveFromOAuth(options) {
+	if (!isSecureAuthUrl(options.authUrl)) return null;
+	if (!isSecureAuthUrl(options.tokenUrl)) return null;
+	const codeVerifier = generateCodeVerifier();
+	const codeChallenge = deriveCodeChallenge(codeVerifier);
+	const state = randomBytes(32).toString("hex");
+	const timeout = createTimeout(options.timeout);
+	const codeDeferred = createDeferred();
+	const handle = startLocalServer({
+		onRequest: (req, res) => {
+			handleCallback(req, res, options.callbackPath, state, codeDeferred.resolve);
+		},
+		port: options.port
+	});
+	const serverPort = await handle.port;
+	if (serverPort === null) {
+		timeout.clear();
+		return null;
+	}
+	const redirectUri = `http://127.0.0.1:${String(serverPort)}${options.callbackPath}`;
+	openBrowser(buildAuthUrl({
+		authUrl: options.authUrl,
+		clientId: options.clientId,
+		codeChallenge,
+		redirectUri,
+		scopes: options.scopes,
+		state
+	}));
+	const timeoutPromise = timeout.promise.then(() => {
+		codeDeferred.resolve(null);
+		destroyServer(handle.server, handle.sockets);
+		return null;
+	});
+	const code = await Promise.race([codeDeferred.promise, timeoutPromise]);
+	timeout.clear();
+	if (!code) {
+		destroyServer(handle.server, handle.sockets);
+		return null;
+	}
+	destroyServer(handle.server, handle.sockets);
+	return await exchangeCodeForToken({
+		clientId: options.clientId,
+		code,
+		codeVerifier,
+		redirectUri,
+		tokenUrl: options.tokenUrl
+	});
 }
 /**
-* Create a deferred promise with externally accessible resolve.
-*
-* Uses a mutable state container to capture the promise resolver —
-* this is an intentional exception to immutability rules because the
-* Promise constructor API requires synchronous resolver capture.
+* Generate a cryptographically random code verifier for PKCE.
 *
 * @private
-* @returns A deferred object with promise and resolve.
+* @returns A base64url-encoded random string.
 */
-function createDeferred() {
-	const state = { resolve: null };
-	return {
-		promise: new Promise((resolve) => {
-			state.resolve = resolve;
-		}),
-		resolve: (value) => {
-			if (state.resolve) state.resolve(value);
-		}
-	};
+function generateCodeVerifier() {
+	return randomBytes(32).toString("base64url");
 }
 /**
-* Create a clearable timeout.
-*
-* Returns a promise that resolves after `ms` milliseconds and a `clear`
-* function that cancels the timer so it does not hold the event loop open.
-*
-* Uses a mutable state container to capture the timer id — this is an
-* intentional exception to immutability rules because `setTimeout`
-* returns an opaque handle that must be stored for later cancellation.
+* Derive a S256 code challenge from a code verifier.
 *
 * @private
-* @param ms - Duration in milliseconds.
-* @returns A Timeout with `promise` and `clear`.
+* @param verifier - The code verifier string.
+* @returns The base64url-encoded SHA-256 hash.
 */
-function createTimeout(ms) {
-	const state = { id: null };
-	return {
-		clear: () => {
-			if (state.id !== null) {
-				clearTimeout(state.id);
-				state.id = null;
-			}
-		},
-		promise: new Promise((resolve) => {
-			state.id = setTimeout(resolve, ms);
-		})
-	};
+function deriveCodeChallenge(verifier) {
+	return createHash("sha256").update(verifier).digest("base64url");
 }
 /**
-* Get the server port from a token listener.
+* Build the full authorization URL with PKCE query parameters.
 *
 * @private
-* @param listener - The token listener.
-* @returns The port number, or null if the server failed to start.
+* @param options - Authorization URL components.
+* @returns The complete authorization URL string.
 */
-async function getServerPort(listener) {
-	return listener.port;
+function buildAuthUrl(options) {
+	const url = new URL(options.authUrl);
+	url.searchParams.set("response_type", "code");
+	url.searchParams.set("client_id", options.clientId);
+	url.searchParams.set("redirect_uri", options.redirectUri);
+	url.searchParams.set("code_challenge", options.codeChallenge);
+	url.searchParams.set("code_challenge_method", "S256");
+	url.searchParams.set("state", options.state);
+	if (options.scopes.length > 0) url.searchParams.set("scope", options.scopes.join(" "));
+	return url.toString();
 }
 /**
-* Extract a token from the POST body of an incoming HTTP request.
+* Handle an incoming HTTP request on the callback server.
 *
-* Only POST requests to the callback path with `application/json`
-* Content-Type and a JSON body containing `token` and matching `state`
-* fields are accepted. Query-string tokens are intentionally rejected
-* to prevent credential leakage through browser history, server logs,
-* and referrer headers.
-*
-* The `Content-Type` check prevents CORS-safelisted simple requests
-* (which skip preflight) from delivering forged payloads — `text/plain`
-* is safelisted, but `application/json` is not (Fetch Standard §2.2.2).
-*
-* Body size is capped at {@link MAX_BODY_BYTES} to prevent resource
-* exhaustion from oversized payloads.
+* Accepts GET requests to the callback path with `code` and `state`
+* query parameters. Validates the state nonce and resolves the
+* authorization code.
 *
 * @private
-* @param req - The incoming request.
+* @param req - The incoming HTTP request.
+* @param res - The server response.
 * @param callbackPath - The expected callback path.
-* @param expectedState - The state nonce to validate against.
-* @param callback - Called with the extracted token or null.
+* @param expectedState - The state nonce to validate.
+* @param resolve - Callback to deliver the authorization code.
 */
-function extractTokenFromBody(req, callbackPath, expectedState, callback) {
-	if (new URL(req.url ?? "/", "http://localhost").pathname !== callbackPath) {
-		callback(null);
-		return;
-	}
-	if (req.method !== "POST") {
-		callback(null);
+function handleCallback(req, res, callbackPath, expectedState, resolve) {
+	const result = extractCodeFromUrl(req.url, callbackPath, expectedState);
+	if (!result.ok) {
+		res.writeHead(400);
+		res.end();
+		if (result.isOAuthError) resolve(null);
 		return;
 	}
-	if (!(req.headers["content-type"] ?? "").startsWith("application/json")) {
-		callback(null);
-		return;
-	}
-	const chunks = [];
-	const received = { bytes: 0 };
-	req.on("data", (chunk) => {
-		received.bytes += chunk.length;
-		if (received.bytes > MAX_BODY_BYTES) {
-			req.destroy();
-			callback(null);
-			return;
-		}
-		chunks.push(chunk);
-	});
-	req.on("end", () => {
-		callback(parseTokenFromJson(Buffer.concat(chunks).toString("utf8"), expectedState));
-	});
-	req.on("error", () => {
-		callback(null);
-	});
+	sendSuccessPage(res);
+	resolve(result.code);
 }
 /**
-* Parse a token string from a JSON body and validate the state nonce.
-*
-* Expects `{ "token": "<value>", "state": "<value>" }`. Returns null
-* for invalid JSON, missing/empty token fields, or mismatched state.
+* Extract an authorization code from a request URL.
 *
-* @private
-* @param body - The raw request body string.
-* @param expectedState - The state nonce that must match.
-* @returns The token string or null.
-*/
-function parseTokenFromJson(body, expectedState) {
-	try {
-		const parsed = JSON.parse(body);
-		if (typeof parsed !== "object" || parsed === null) return null;
-		const record = parsed;
-		if (typeof record.token !== "string" || record.token === "") return null;
-		if (record.state !== expectedState) return null;
-		return record.token;
-	} catch {
-		return null;
-	}
-}
-/**
-* Send an HTML success page and end the response.
+* Validates that the request path matches the callback path,
+* the `state` parameter matches the expected nonce, and a
+* `code` parameter is present. Detects OAuth error responses
+* (e.g. `?error=access_denied`) and flags them so the caller
+* can resolve immediately instead of waiting for the timeout.
 *
 * @private
-* @param res - The server response object.
+* @param reqUrl - The raw request URL string.
+* @param callbackPath - The expected callback path.
+* @param expectedState - The state nonce to validate.
+* @returns An extraction result with the code or error flag.
 */
-function sendSuccessPage(res) {
-	res.writeHead(200, { "Content-Type": "text/html" });
-	res.end(CLOSE_PAGE_HTML);
+function extractCodeFromUrl(reqUrl, callbackPath, expectedState) {
+	const url = new URL(reqUrl ?? "/", "http://localhost");
+	if (url.pathname !== callbackPath) return {
+		isOAuthError: false,
+		ok: false
+	};
+	if (url.searchParams.get("state") !== expectedState) return {
+		isOAuthError: false,
+		ok: false
+	};
+	if (url.searchParams.get("error")) return {
+		isOAuthError: true,
+		ok: false
+	};
+	const code = url.searchParams.get("code");
+	if (!code) return {
+		isOAuthError: false,
+		ok: false
+	};
+	return {
+		code,
+		ok: true
+	};
 }
 /**
-* Open a URL in the user's default browser using a platform-specific command.
+* Exchange an authorization code for an access token at the token endpoint.
 *
-* On Windows, `start` is a `cmd.exe` built-in — not a standalone executable —
-* so it must be invoked via `cmd /c start "" <url>`. The empty string argument
-* prevents `cmd` from interpreting the URL as a window title.
+* Sends a POST request with `application/x-www-form-urlencoded` body
+* containing the authorization code, redirect URI, client ID, and
+* PKCE code verifier.
 *
 * @private
-* @param url - The URL to open.
+* @param options - Token exchange parameters.
+* @returns A bearer credential on success, null on failure.
 */
-function openBrowser(url) {
-	const { command, args } = match$1(platform()).with("darwin", () => ({
-		args: [url],
-		command: "open"
-	})).with("win32", () => ({
-		args: [
-			"/c",
-			"start",
-			"",
-			url
-		],
-		command: "cmd"
-	})).otherwise(() => ({
-		args: [url],
-		command: "xdg-open"
-	}));
-	execFile(command, args);
+async function exchangeCodeForToken(options) {
+	const body = new URLSearchParams({
+		client_id: options.clientId,
+		code: options.code,
+		code_verifier: options.codeVerifier,
+		grant_type: "authorization_code",
+		redirect_uri: options.redirectUri
+	});
+	const response = await postFormEncoded(options.tokenUrl, body);
+	if (!response) return null;
+	if (!response.ok) return null;
+	try {
+		const data = await response.json();
+		if (typeof data !== "object" || data === null) return null;
+		const record = data;
+		if (typeof record.access_token !== "string" || record.access_token === "") return null;
+		if (typeof record.token_type === "string" && record.token_type.toLowerCase() !== "bearer") return null;
+		return createBearerCredential(record.access_token);
+	} catch {
+		return null;
+	}
 }
 
 //#endregion
-//#region src/middleware/auth/resolve-prompt.ts
+//#region src/middleware/auth/strategies/token.ts
 /**
 * Resolve a bearer credential by interactively prompting the user.
 *
@@ -473,24 +892,18 @@ function openBrowser(url) {
 * @param options - Options with the prompt message and prompts instance.
 * @returns A bearer credential on input, null on cancellation.
 */
-async function resolveFromPrompt(options) {
+async function resolveFromToken(options) {
 	try {
 		const token = await options.prompts.password({ message: options.message });
-		if (!token) return null;
-		return {
-			token,
-			type: "bearer"
-		};
+		if (!isValidToken(token)) return null;
+		return createBearerCredential(token);
 	} catch {
 		return null;
 	}
 }
 
 //#endregion
-//#region src/middleware/auth/resolve-credentials.ts
-const DEFAULT_OAUTH_PORT = 0;
-const DEFAULT_OAUTH_CALLBACK_PATH = "/callback";
-const DEFAULT_OAUTH_TIMEOUT = 12e4;
+//#region src/middleware/auth/chain.ts
 const DEFAULT_PROMPT_MESSAGE = "Enter your API key";
 /**
 * Chain credential resolvers, returning the first non-null result.
@@ -502,11 +915,22 @@ const DEFAULT_PROMPT_MESSAGE = "Enter your API key";
 * @param options - Options with resolvers, CLI name, and prompts instance.
 * @returns The first resolved credential, or null if all resolvers fail.
 */
-async function resolveCredentials(options) {
+async function runStrategyChain(options) {
 	const defaultTokenVar = deriveTokenVar(options.cliName);
 	return tryResolvers(options.resolvers, 0, defaultTokenVar, options);
 }
 /**
+* Return the given value when defined, otherwise the fallback.
+*
+* @param value - The optional value.
+* @param fallback - The default value.
+* @returns The resolved value.
+*/
+function withDefault(value, fallback) {
+	if (value !== void 0) return value;
+	return fallback;
+}
+/**
 * Recursively try resolvers until one returns a credential or the list is exhausted.
 *
 * @private
@@ -534,56 +958,44 @@ async function tryResolvers(configs, index, defaultTokenVar, context) {
 * @returns The resolved credential, or null.
 */
 async function dispatchResolver(config, defaultTokenVar, context) {
-	return match$1(config).with({ source: "env" }, (c) => resolveFromEnv({ tokenVar: resolveOptionalString(c.tokenVar, defaultTokenVar) })).with({ source: "dotenv" }, (c) => resolveFromDotenv({
-		path: resolveOptionalString(c.path, join(process.cwd(), ".env")),
-		tokenVar: resolveOptionalString(c.tokenVar, defaultTokenVar)
+	return match$1(config).with({ source: "env" }, (c) => resolveFromEnv({ tokenVar: withDefault(c.tokenVar, defaultTokenVar) })).with({ source: "dotenv" }, (c) => resolveFromDotenv({
+		path: withDefault(c.path, join(process.cwd(), ".env")),
+		tokenVar: withDefault(c.tokenVar, defaultTokenVar)
 	})).with({ source: "file" }, (c) => resolveFromFile({
-		dirName: resolveOptionalString(c.dirName, `.${context.cliName}`),
-		filename: resolveOptionalString(c.filename, DEFAULT_AUTH_FILENAME)
+		dirName: withDefault(c.dirName, `.${context.cliName}`),
+		filename: withDefault(c.filename, DEFAULT_AUTH_FILENAME)
 	})).with({ source: "oauth" }, (c) => resolveFromOAuth({
 		authUrl: c.authUrl,
-		callbackPath: resolveOptionalString(c.callbackPath, DEFAULT_OAUTH_CALLBACK_PATH),
-		port: resolveOptionalNumber(c.port, DEFAULT_OAUTH_PORT),
-		timeout: resolveOptionalNumber(c.timeout, DEFAULT_OAUTH_TIMEOUT)
-	})).with({ source: "prompt" }, (c) => resolveFromPrompt({
-		message: resolveOptionalString(c.message, DEFAULT_PROMPT_MESSAGE),
+		callbackPath: withDefault(c.callbackPath, DEFAULT_OAUTH_CALLBACK_PATH),
+		clientId: c.clientId,
+		port: withDefault(c.port, DEFAULT_OAUTH_PORT),
+		scopes: withDefault(c.scopes, []),
+		timeout: withDefault(c.timeout, DEFAULT_OAUTH_TIMEOUT),
+		tokenUrl: c.tokenUrl
+	})).with({ source: "device-code" }, (c) => resolveFromDeviceCode({
+		clientId: c.clientId,
+		deviceAuthUrl: c.deviceAuthUrl,
+		openBrowserOnStart: withDefault(c.openBrowser, true),
+		pollInterval: withDefault(c.pollInterval, DEFAULT_DEVICE_CODE_POLL_INTERVAL),
+		prompts: context.prompts,
+		scopes: withDefault(c.scopes, []),
+		timeout: withDefault(c.timeout, DEFAULT_DEVICE_CODE_TIMEOUT),
+		tokenUrl: c.tokenUrl
+	})).with({ source: "token" }, (c) => resolveFromToken({
+		message: withDefault(c.message, DEFAULT_PROMPT_MESSAGE),
 		prompts: context.prompts
 	})).with({ source: "custom" }, (c) => c.resolver()).exhaustive();
 }
-/**
-* Resolve an optional string value, falling back to a default.
-*
-* @private
-* @param value - The optional value.
-* @param fallback - The default value.
-* @returns The resolved string.
-*/
-function resolveOptionalString(value, fallback) {
-	if (value !== void 0) return value;
-	return fallback;
-}
-/**
-* Resolve an optional number value, falling back to a default.
-*
-* @private
-* @param value - The optional value.
-* @param fallback - The default value.
-* @returns The resolved number.
-*/
-function resolveOptionalNumber(value, fallback) {
-	if (value !== void 0) return value;
-	return fallback;
-}
 
 //#endregion
-//#region src/middleware/auth/create-auth-context.ts
+//#region src/middleware/auth/context.ts
 /**
 * Create an {@link AuthContext} value for `ctx.auth`.
 *
 * No credential data is stored on the returned object. `credential()`
 * resolves passively on every call, `authenticated()` checks existence,
-* and `authenticate()` runs the configured interactive resolvers, saves
-* the credential to the global file store, and returns a Result.
+* `login()` runs the configured interactive resolvers, saves the
+* credential to the global file store, and `logout()` removes it.
 *
 * @param options - Factory options.
 * @returns An AuthContext instance.
@@ -612,49 +1024,65 @@ function createAuthContext(options) {
 	* Run configured resolvers interactively and persist the credential.
 	*
 	* @private
-	* @returns A Result with the credential on success or a LoginError on failure.
+	* @returns A Result with the credential on success or an AuthError on failure.
 	*/
-	async function authenticate() {
-		const resolved = await resolveCredentials({
+	async function login() {
+		const resolved = await runStrategyChain({
 			cliName,
 			prompts,
 			resolvers
 		});
-		if (resolved === null) return loginError({
+		if (resolved === null) return authError({
 			message: "No credential resolved from any source",
 			type: "no_credential"
 		});
 		const [saveError] = createStore({ dirName: `.${cliName}` }).save(DEFAULT_AUTH_FILENAME, resolved);
-		if (saveError) return loginError({
+		if (saveError) return authError({
 			message: `Failed to save credential: ${saveError.message}`,
 			type: "save_failed"
 		});
 		return ok(resolved);
 	}
+	/**
+	* Remove the stored credential from disk.
+	*
+	* @private
+	* @returns A Result with the removed file path on success or an AuthError on failure.
+	*/
+	async function logout() {
+		const [removeError, filePath] = createStore({ dirName: `.${cliName}` }).remove(DEFAULT_AUTH_FILENAME);
+		if (removeError) return authError({
+			message: `Failed to remove credential: ${removeError.message}`,
+			type: "remove_failed"
+		});
+		return ok(filePath);
+	}
 	return {
-		authenticate,
 		authenticated,
-		credential
+		credential,
+		login,
+		logout
 	};
 }
 /**
-* Construct a failure Result tuple with a {@link LoginError}.
+* Construct a failure Result tuple with an {@link AuthError}.
 *
 * @private
-* @param error - The login error.
-* @returns A Result tuple `[LoginError, null]`.
+* @param error - The auth error.
+* @returns A Result tuple `[AuthError, null]`.
 */
-function loginError(error) {
+function authError(error) {
 	return [error, null];
 }
 
 //#endregion
 //#region src/middleware/auth/auth.ts
 /**
-* Auth middleware factory.
+* Auth middleware factory with resolver builder functions.
 *
 * Decorates `ctx.auth` with functions to resolve credentials on demand
-* and run interactive authentication.
+* and run interactive authentication. Also supports creating authenticated
+* HTTP clients via the `http` option.
 *
 * @module
 */
@@ -662,50 +1090,207 @@ function loginError(error) {
 * Create an auth middleware that decorates `ctx.auth`.
 *
 * No credential data is stored on the context. `ctx.auth.credential()`
-* resolves passively from two sources on every call:
+* resolves passively from three sources on every call:
 * 1. File — `~/.cli-name/auth.json`
-* 2. Env — `CLI_NAME_TOKEN`
+* 2. Dotenv — `.env` file (when configured)
+* 3. Env — `CLI_NAME_TOKEN`
 *
 * Interactive resolvers (OAuth, prompt, custom) only run when the
-* command handler explicitly calls `ctx.auth.authenticate()`.
+* command handler explicitly calls `ctx.auth.login()`.
+*
+* When `options.http` is provided, the middleware also creates HTTP
+* client(s) with automatic credential header injection and decorates
+* them onto `ctx[namespace]`.
 *
 * @param options - Auth middleware configuration.
-* @returns A Middleware that decorates ctx.auth.
+* @returns A Middleware that decorates ctx.auth (and optionally HTTP clients).
 */
-function auth(options) {
+function createAuth(options) {
 	const { resolvers } = options;
 	return middleware((ctx, next) => {
 		const cliName = ctx.meta.name;
-		decorateContext(ctx, "auth", createAuthContext({
+		const authContext = createAuthContext({
 			cliName,
 			prompts: ctx.prompts,
-			resolveCredential: () => resolvePassive(cliName, resolvers),
+			resolveCredential: () => resolveStoredCredential(cliName, resolvers),
 			resolvers
-		}));
+		});
+		decorateContext(ctx, "auth", authContext);
+		if (options.http !== void 0) normalizeHttpOptions(options.http).reduce((context, httpConfig) => {
+			const client = createHttpClient({
+				baseUrl: httpConfig.baseUrl,
+				defaultHeaders: httpConfig.headers,
+				resolveHeaders: () => credentialToHeaders(authContext.credential())
+			});
+			return decorateContext(context, httpConfig.namespace, client);
+		}, ctx);
 		return next();
 	});
 }
 /**
-* Attempt to resolve a credential from passive (non-interactive) sources.
+* Auth middleware factory with resolver builder methods.
+*
+* Use as `auth({ resolvers: [...] })` to create middleware, or use
+* the builder methods (`auth.env()`, `auth.oauth()`, etc.) to construct
+* resolver configs with a cleaner API.
+*/
+const auth = Object.assign(createAuth, {
+	apiKey: buildToken,
+	custom: buildCustom,
+	deviceCode: buildDeviceCode,
+	dotenv: buildDotenv,
+	env: buildEnv,
+	file: buildFile,
+	oauth: buildOAuth,
+	token: buildToken
+});
+/**
+* Build an env resolver config.
+*
+* @private
+* @param options - Optional env resolver options.
+* @returns An EnvSourceConfig with `source: 'env'`.
+*/
+function buildEnv(options) {
+	return {
+		source: "env",
+		...options
+	};
+}
+/**
+* Build a dotenv resolver config.
 *
-* Checks the file store first, then falls back to the environment variable.
-* Scans the resolver list for `env` and `file` source configs to respect
-* user-configured overrides (e.g. a custom `tokenVar` or `dirName`).
+* @private
+* @param options - Optional dotenv resolver options.
+* @returns A DotenvSourceConfig with `source: 'dotenv'`.
+*/
+function buildDotenv(options) {
+	return {
+		source: "dotenv",
+		...options
+	};
+}
+/**
+* Build a file resolver config.
+*
+* @private
+* @param options - Optional file resolver options.
+* @returns A FileSourceConfig with `source: 'file'`.
+*/
+function buildFile(options) {
+	return {
+		source: "file",
+		...options
+	};
+}
+/**
+* Build an OAuth resolver config.
+*
+* @private
+* @param options - OAuth resolver options (clientId, authUrl, tokenUrl required).
+* @returns An OAuthSourceConfig with `source: 'oauth'`.
+*/
+function buildOAuth(options) {
+	return {
+		source: "oauth",
+		...options
+	};
+}
+/**
+* Build a device code resolver config.
+*
+* @private
+* @param options - Device code resolver options (clientId, deviceAuthUrl, tokenUrl required).
+* @returns A DeviceCodeSourceConfig with `source: 'device-code'`.
+*/
+function buildDeviceCode(options) {
+	return {
+		source: "device-code",
+		...options
+	};
+}
+/**
+* Build a token resolver config.
+*
+* Prompts the user for a token interactively. Aliased as `auth.apiKey()`.
+*
+* @private
+* @param options - Optional token resolver options.
+* @returns A TokenSourceConfig with `source: 'token'`.
+*/
+function buildToken(options) {
+	return {
+		source: "token",
+		...options
+	};
+}
+/**
+* Build a custom resolver config from a resolver function.
+*
+* @private
+* @param resolver - The custom resolver function.
+* @returns A CustomSourceConfig with `source: 'custom'`.
+*/
+function buildCustom(resolver) {
+	return {
+		resolver,
+		source: "custom"
+	};
+}
+/**
+* Normalize the `http` option into an array of configs.
+*
+* @private
+* @param http - A single config or array of configs.
+* @returns An array of AuthHttpOptions.
+*/
+function normalizeHttpOptions(http) {
+	if ("baseUrl" in http) return [http];
+	return http;
+}
+/**
+* Convert a credential into auth headers, returning an empty record
+* when no credential is available.
+*
+* @private
+* @param credential - The credential or null.
+* @returns A record of auth headers.
+*/
+function credentialToHeaders(credential) {
+	if (credential === null) return {};
+	return buildAuthHeaders(credential);
+}
+/**
+* Attempt to resolve a credential from stored (non-interactive) sources.
+*
+* Checks the file store first, then dotenv, then falls back to the
+* environment variable. Scans the resolver list for `file`, `dotenv`,
+* and `env` source configs to respect user-configured overrides
+* (e.g. a custom `tokenVar`, `dirName`, or dotenv `path`).
 *
 * @private
 * @param cliName - The CLI name, used to derive paths and env var names.
 * @param resolvers - The configured resolver list for extracting overrides.
 * @returns The resolved credential, or null.
 */
-function resolvePassive(cliName, resolvers) {
+function resolveStoredCredential(cliName, resolvers) {
 	const fileConfig = findResolverBySource(resolvers, "file");
+	const dotenvConfig = findResolverBySource(resolvers, "dotenv");
 	const envConfig = findResolverBySource(resolvers, "env");
+	const defaultTokenVar = deriveTokenVar(cliName);
 	const fromFile = resolveFromFile({
-		dirName: resolveFileDir(fileConfig, cliName),
-		filename: resolveFileFilename(fileConfig)
+		dirName: withDefault(extractProp(fileConfig, "dirName"), `.${cliName}`),
+		filename: withDefault(extractProp(fileConfig, "filename"), DEFAULT_AUTH_FILENAME)
 	});
 	if (fromFile) return fromFile;
-	return resolveFromEnv({ tokenVar: resolveEnvTokenVar(envConfig, cliName) });
+	if (dotenvConfig !== void 0) {
+		const fromDotenv = resolveFromDotenv({
+			path: withDefault(extractProp(dotenvConfig, "path"), join(process.cwd(), ".env")),
+			tokenVar: withDefault(extractProp(dotenvConfig, "tokenVar"), defaultTokenVar)
+		});
+		if (fromDotenv) return fromDotenv;
+	}
+	return resolveFromEnv({ tokenVar: withDefault(extractProp(envConfig, "tokenVar"), defaultTokenVar) });
 }
 /**
 * Find the first resolver config matching a given source type.
@@ -719,39 +1304,19 @@ function findResolverBySource(resolvers, source) {
 	return resolvers.find((r) => r.source === source);
 }
 /**
-* Resolve the file store directory name from a file resolver config.
-*
-* @private
-* @param config - The file resolver config, or undefined.
-* @param cliName - The CLI name for deriving the default.
-* @returns The directory name.
-*/
-function resolveFileDir(config, cliName) {
-	if (config !== void 0 && config.dirName !== void 0) return config.dirName;
-	return `.${cliName}`;
-}
-/**
-* Resolve the file store filename from a file resolver config.
+* Safely extract a property from an optional config object.
 *
-* @private
-* @param config - The file resolver config, or undefined.
-* @returns The filename.
-*/
-function resolveFileFilename(config) {
-	if (config !== void 0 && config.filename !== void 0) return config.filename;
-	return DEFAULT_AUTH_FILENAME;
-}
-/**
-* Resolve the environment variable name from an env resolver config.
+* Returns the property value when the config is defined, or undefined
+* when the config itself is undefined.
 *
 * @private
-* @param config - The env resolver config, or undefined.
-* @param cliName - The CLI name for deriving the default.
-* @returns The token variable name.
+* @param config - The config object, or undefined.
+* @param key - The property key to extract.
+* @returns The property value, or undefined.
 */
-function resolveEnvTokenVar(config, cliName) {
-	if (config !== void 0 && config.tokenVar !== void 0) return config.tokenVar;
-	return deriveTokenVar(cliName);
+function extractProp(config, key) {
+	if (config === void 0) return;
+	return config[key];
 }
 
 //#endregion