@kidd-cli/core 0.1.0

package/dist/middleware/auth.js

@@ -0,0 +1,759 @@
+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 { 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 { 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";
+
+//#region src/middleware/auth/constants.ts
+/**
+* Default filename for file-based credential storage.
+*/
+const DEFAULT_AUTH_FILENAME = "auth.json";
+/**
+* Suffix appended to the derived token environment variable name.
+*/
+const TOKEN_VAR_SUFFIX = "_TOKEN";
+/**
+* Derive the default environment variable name from a CLI name.
+*
+* Converts kebab-case to SCREAMING_SNAKE_CASE and appends `_TOKEN`.
+* Example: `my-app` → `MY_APP_TOKEN`
+*
+* @param cliName - The CLI name.
+* @returns The derived environment variable name.
+*/
+function deriveTokenVar(cliName) {
+	return `${cliName.replaceAll("-", "_").toUpperCase()}${TOKEN_VAR_SUFFIX}`;
+}
+
+//#endregion
+//#region src/middleware/auth/resolve-dotenv.ts
+/**
+* Resolve a bearer credential from a `.env` file without mutating `process.env`.
+*
+* Reads the file and parses it with `dotenv.parse`. If the target variable
+* is present, returns a bearer credential. Otherwise returns null.
+*
+* Skips a separate existence check to avoid a TOCTOU race — if the file
+* does not exist, `readFileSync` throws and `attempt` captures the error.
+*
+* @param options - Options with the env variable name and file path.
+* @returns A bearer credential if found, null otherwise.
+*/
+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"
+	};
+}
+
+//#endregion
+//#region src/middleware/auth/resolve-env.ts
+/**
+* Resolve a bearer credential from a process environment variable.
+*
+* @param options - Options containing the environment variable name.
+* @returns A bearer credential if the variable is set, null otherwise.
+*/
+function resolveFromEnv(options) {
+	const token = process.env[options.tokenVar];
+	if (!token) return null;
+	return {
+		token,
+		type: "bearer"
+	};
+}
+
+//#endregion
+//#region src/middleware/auth/schema.ts
+/**
+* Zod schema for bearer credentials.
+*/
+const bearerCredentialSchema = z.object({
+	token: z.string().min(1),
+	type: z.literal("bearer")
+});
+/**
+* Zod schema for basic auth credentials.
+*/
+const basicCredentialSchema = z.object({
+	password: z.string().min(1),
+	type: z.literal("basic"),
+	username: z.string().min(1)
+});
+/**
+* Zod schema for API key credentials.
+*/
+const apiKeyCredentialSchema = z.object({
+	headerName: z.string().min(1),
+	key: z.string().min(1),
+	type: z.literal("api-key")
+});
+/**
+* Zod schema for custom header credentials.
+*/
+const customCredentialSchema = z.object({
+	headers: z.record(z.string(), z.string()),
+	type: z.literal("custom")
+});
+/**
+* Zod discriminated union schema for validating auth.json credential payloads.
+* Validates against all four credential types using the `type` field as discriminator.
+*/
+const authCredentialSchema = z.discriminatedUnion("type", [
+	bearerCredentialSchema,
+	basicCredentialSchema,
+	apiKeyCredentialSchema,
+	customCredentialSchema
+]);
+
+//#endregion
+//#region src/middleware/auth/resolve-file.ts
+/**
+* Resolve credentials from a JSON file on disk.
+*
+* Uses the file-backed store with local-then-global resolution to find
+* the credentials file, then validates its contents against the auth
+* credential schema.
+*
+* @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
+	};
+}
+/**
+* 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.
+*
+* @private
+* @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.
+*
+* @private
+* @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();
+}
+/**
+* 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.
+*
+* @private
+* @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.
+*
+* @private
+* @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);
+		})
+	};
+}
+/**
+* Get the server port from a token listener.
+*
+* @private
+* @param listener - The token listener.
+* @returns The port number, or null if the server failed to start.
+*/
+async function getServerPort(listener) {
+	return listener.port;
+}
+/**
+* Extract a token from the POST body of an incoming HTTP request.
+*
+* 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.
+*
+* @private
+* @param req - The incoming request.
+* @param callbackPath - The expected callback path.
+* @param expectedState - The state nonce to validate against.
+* @param callback - Called with the extracted token or null.
+*/
+function extractTokenFromBody(req, callbackPath, expectedState, callback) {
+	if (new URL(req.url ?? "/", "http://localhost").pathname !== callbackPath) {
+		callback(null);
+		return;
+	}
+	if (req.method !== "POST") {
+		callback(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);
+	});
+}
+/**
+* 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.
+*
+* @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.
+*
+* @private
+* @param res - The server response object.
+*/
+function sendSuccessPage(res) {
+	res.writeHead(200, { "Content-Type": "text/html" });
+	res.end(CLOSE_PAGE_HTML);
+}
+/**
+* Open a URL in the user's default browser using a platform-specific command.
+*
+* 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.
+*
+* @private
+* @param url - The URL to open.
+*/
+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);
+}
+
+//#endregion
+//#region src/middleware/auth/resolve-prompt.ts
+/**
+* Resolve a bearer credential by interactively prompting the user.
+*
+* Uses `prompts.password()` to ask for an API key or token. Returns
+* null if the user cancels the prompt or provides an empty value.
+*
+* Should be placed last in the resolver chain as a fallback.
+*
+* @param options - Options with the prompt message and prompts instance.
+* @returns A bearer credential on input, null on cancellation.
+*/
+async function resolveFromPrompt(options) {
+	try {
+		const token = await options.prompts.password({ message: options.message });
+		if (!token) return null;
+		return {
+			token,
+			type: "bearer"
+		};
+	} 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;
+const DEFAULT_PROMPT_MESSAGE = "Enter your API key";
+/**
+* Chain credential resolvers, returning the first non-null result.
+*
+* Walks the resolver list in order, dispatching each config to the
+* appropriate resolver function via pattern matching. Short-circuits
+* on the first successful resolution.
+*
+* @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) {
+	const defaultTokenVar = deriveTokenVar(options.cliName);
+	return tryResolvers(options.resolvers, 0, defaultTokenVar, options);
+}
+/**
+* Recursively try resolvers until one returns a credential or the list is exhausted.
+*
+* @private
+* @param configs - The resolver configs.
+* @param index - The current index.
+* @param defaultTokenVar - The derived default token env var name.
+* @param context - The resolve options for prompts access.
+* @returns The first resolved credential, or null.
+*/
+async function tryResolvers(configs, index, defaultTokenVar, context) {
+	if (index >= configs.length) return null;
+	const config = configs[index];
+	if (config === void 0) return null;
+	const credential = await dispatchResolver(config, defaultTokenVar, context);
+	if (credential) return credential;
+	return tryResolvers(configs, index + 1, defaultTokenVar, context);
+}
+/**
+* Dispatch a single resolver config to its implementation.
+*
+* @private
+* @param config - The resolver config to dispatch.
+* @param defaultTokenVar - The derived default token env var name.
+* @param context - The resolve options for prompts access.
+* @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)
+	})).with({ source: "file" }, (c) => resolveFromFile({
+		dirName: resolveOptionalString(c.dirName, `.${context.cliName}`),
+		filename: resolveOptionalString(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),
+		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
+/**
+* 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.
+*
+* @param options - Factory options.
+* @returns An AuthContext instance.
+*/
+function createAuthContext(options) {
+	const { resolvers, cliName, prompts, resolveCredential } = options;
+	/**
+	* Resolve the current credential from passive sources (file, env).
+	*
+	* @private
+	* @returns The credential, or null when none exists.
+	*/
+	function credential() {
+		return resolveCredential();
+	}
+	/**
+	* Check whether a credential is available from passive sources.
+	*
+	* @private
+	* @returns True when a credential exists.
+	*/
+	function authenticated() {
+		return resolveCredential() !== null;
+	}
+	/**
+	* Run configured resolvers interactively and persist the credential.
+	*
+	* @private
+	* @returns A Result with the credential on success or a LoginError on failure.
+	*/
+	async function authenticate() {
+		const resolved = await resolveCredentials({
+			cliName,
+			prompts,
+			resolvers
+		});
+		if (resolved === null) return loginError({
+			message: "No credential resolved from any source",
+			type: "no_credential"
+		});
+		const [saveError] = createStore({ dirName: `.${cliName}` }).save(DEFAULT_AUTH_FILENAME, resolved);
+		if (saveError) return loginError({
+			message: `Failed to save credential: ${saveError.message}`,
+			type: "save_failed"
+		});
+		return ok(resolved);
+	}
+	return {
+		authenticate,
+		authenticated,
+		credential
+	};
+}
+/**
+* Construct a failure Result tuple with a {@link LoginError}.
+*
+* @private
+* @param error - The login error.
+* @returns A Result tuple `[LoginError, null]`.
+*/
+function loginError(error) {
+	return [error, null];
+}
+
+//#endregion
+//#region src/middleware/auth/auth.ts
+/**
+* Auth middleware factory.
+*
+* Decorates `ctx.auth` with functions to resolve credentials on demand
+* and run interactive authentication.
+*
+* @module
+*/
+/**
+* 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:
+* 1. File — `~/.cli-name/auth.json`
+* 2. Env — `CLI_NAME_TOKEN`
+*
+* Interactive resolvers (OAuth, prompt, custom) only run when the
+* command handler explicitly calls `ctx.auth.authenticate()`.
+*
+* @param options - Auth middleware configuration.
+* @returns A Middleware that decorates ctx.auth.
+*/
+function auth(options) {
+	const { resolvers } = options;
+	return middleware((ctx, next) => {
+		const cliName = ctx.meta.name;
+		decorateContext(ctx, "auth", createAuthContext({
+			cliName,
+			prompts: ctx.prompts,
+			resolveCredential: () => resolvePassive(cliName, resolvers),
+			resolvers
+		}));
+		return next();
+	});
+}
+/**
+* Attempt to resolve a credential from passive (non-interactive) sources.
+*
+* 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 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) {
+	const fileConfig = findResolverBySource(resolvers, "file");
+	const envConfig = findResolverBySource(resolvers, "env");
+	const fromFile = resolveFromFile({
+		dirName: resolveFileDir(fileConfig, cliName),
+		filename: resolveFileFilename(fileConfig)
+	});
+	if (fromFile) return fromFile;
+	return resolveFromEnv({ tokenVar: resolveEnvTokenVar(envConfig, cliName) });
+}
+/**
+* Find the first resolver config matching a given source type.
+*
+* @private
+* @param resolvers - The resolver config list.
+* @param source - The source type to find.
+* @returns The matching config, or undefined.
+*/
+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.
+*
+* @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.
+*
+* @private
+* @param config - The env resolver config, or undefined.
+* @param cliName - The CLI name for deriving the default.
+* @returns The token variable name.
+*/
+function resolveEnvTokenVar(config, cliName) {
+	if (config !== void 0 && config.tokenVar !== void 0) return config.tokenVar;
+	return deriveTokenVar(cliName);
+}
+
+//#endregion
+export { auth };
+//# sourceMappingURL=auth.js.map