dsh-coding-subscription-oauth 0.6.4 → 0.7.0

package/src/auth.ts

@@ -1,67 +0,0 @@
-/**
- * Grok Build OAuth orchestration shared by the plugin and standalone CLI.
- * @module dsh-coding-subscription-oauth/auth
- */
-
-import type { AuthInteraction } from "@earendil-works/pi-ai";
-import { createModels } from "@earendil-works/pi-ai";
-import { xaiProvider } from "@earendil-works/pi-ai/providers/xai";
-import { importGrokAuth } from "./grok-import.ts";
-import { XAI_PI_PROVIDER } from "./ids.ts";
-import type { GrokBuildSession } from "./session.ts";
-import { GrokBuildCredentialStore } from "./store.ts";
-
-/** Non-secret login state shown by the launcher. */
-export interface GrokBuildAuthStatus {
-	authenticated: boolean;
-	expiresAt?: Date;
-}
-
-/**
- * Complete the xAI device-code OAuth flow and persist the credential.
- * The Grok Build backend accepts the same auth.x.ai tokens (scope
- * `grok-cli:access`); the PKCE authorization-code flow lands in a later
- * milestone as the primary path.
- */
-export async function loginGrokBuild(
-	interaction: AuthInteraction,
-	store: GrokBuildCredentialStore = new GrokBuildCredentialStore(),
-): Promise<void> {
-	const models = createModels({ credentials: store });
-	models.setProvider(xaiProvider());
-	await models.login(XAI_PI_PROVIDER, "oauth", interaction);
-}
-
-/** Copy ~/.grok/auth.json into the dsh store. Does not modify the Grok file. */
-export async function importGrokBuildFromGrok(
-	store: GrokBuildCredentialStore = new GrokBuildCredentialStore(),
-	filename?: string,
-): Promise<void> {
-	await importGrokAuth(store, filename);
-}
-
-/** Remove the stored Grok Build credential. */
-export async function logoutGrokBuild(store: GrokBuildCredentialStore = new GrokBuildCredentialStore()): Promise<void> {
-	await store.delete(XAI_PI_PROVIDER);
-}
-
-/** Read non-secret login state without refreshing the token. */
-export async function grokBuildAuthStatus(
-	store: GrokBuildCredentialStore = new GrokBuildCredentialStore(),
-): Promise<GrokBuildAuthStatus> {
-	const credential = await store.read(XAI_PI_PROVIDER);
-	return credential?.type === "oauth"
-		? { authenticated: true, expiresAt: new Date(credential.expires) }
-		: { authenticated: false };
-}
-
-/** Login then refresh the account model list when a session is available. */
-export async function loginGrokBuildSession(interaction: AuthInteraction, session: GrokBuildSession): Promise<void> {
-	await loginGrokBuild(interaction, session.store);
-	await session.refreshLiveCatalog();
-}
-
-export async function importGrokBuildSession(session: GrokBuildSession, filename?: string): Promise<void> {
-	await importGrokBuildFromGrok(session.store, filename);
-	await session.refreshLiveCatalog();
-}

package/src/bin.ts

@@ -1,350 +0,0 @@
-#!/usr/bin/env node
-/** Standalone credential CLI for the coding-subscription bundle. */
-
-import { spawn } from "node:child_process";
-import { realpathSync } from "node:fs";
-import { createInterface } from "node:readline/promises";
-import { fileURLToPath } from "node:url";
-import type { AuthEvent, AuthPrompt } from "@earendil-works/pi-ai";
-import { grokBuildAuthStatus, importGrokBuildSession, loginGrokBuildSession } from "./auth.ts";
-import { GATEWAY_TOS_WARNING } from "./gateway.ts";
-import { GATEWAY_DEFAULT_BIND, GATEWAY_DEFAULT_PORT } from "./gateway-config.ts";
-import { grokAuthPath } from "./grok-import.ts";
-import { XAI_PI_PROVIDER } from "./ids.ts";
-import { loginGrokBuildPkce } from "./oauth.ts";
-import { oauthProviderDefinition, type SubscriptionLoginMethod } from "./oauth-providers.ts";
-import { OAuthProviderSession } from "./oauth-session.ts";
-import { codingOAuthProxyInEffect, ensureCodingOAuthProxy } from "./proxy.ts";
-import { redactProxyUrl, safeMessage } from "./redact.ts";
-import { GrokBuildSession } from "./session.ts";
-import { grokBuildAuthPath } from "./store.ts";
-
-export type CliAction = "login" | "logout" | "status" | "import";
-export type CliProvider = "all" | "grok" | "codex" | "kimi" | "claude";
-
-function openBrowser(rawUrl: string): void {
-	const url = new URL(rawUrl);
-	if (url.protocol !== "https:") throw new Error(`refusing to open non-HTTPS authorization URL from ${url.host}`);
-	const command =
-		process.platform === "win32"
-			? { file: "rundll32.exe", args: ["url.dll,FileProtocolHandler", url.href] }
-			: process.platform === "darwin"
-				? { file: "open", args: [url.href] }
-				: { file: "xdg-open", args: [url.href] };
-	try {
-		const child = spawn(command.file, command.args, {
-			detached: true,
-			stdio: "ignore",
-			windowsHide: true,
-		});
-		child.on("error", () => {});
-		child.unref();
-	} catch {
-		// The printed URL remains the manual fallback.
-	}
-}
-
-function notify(event: AuthEvent, useBrowser: boolean): void {
-	switch (event.type) {
-		case "auth_url":
-			process.stdout.write(`Open this URL to sign in:\n${event.url}\n`);
-			if (event.instructions !== undefined) process.stdout.write(`${event.instructions}\n`);
-			if (useBrowser) openBrowser(event.url);
-			break;
-		case "device_code":
-			process.stdout.write(`Open this URL to sign in:\n${event.verificationUri}\n`);
-			if (event.userCode.length > 0) process.stdout.write(`Enter code: ${event.userCode}\n`);
-			if (useBrowser) openBrowser(event.verificationUri);
-			break;
-		case "info":
-		case "progress":
-			process.stdout.write(`${event.message}\n`);
-			break;
-		default:
-			event satisfies never;
-	}
-}
-
-function selectLoginOption(prompt: Extract<AuthPrompt, { type: "select" }>, method?: SubscriptionLoginMethod): string {
-	if (method !== undefined) {
-		const exact = method === "device" ? ["device_code", "device-code", "device"] : ["browser", "browser_login"];
-		for (const id of exact) if (prompt.options.some((option) => option.id === id)) return id;
-		const label = method === "device" ? /device|headless/iu : /browser|pkce/iu;
-		const match = prompt.options.find((option) => label.test(option.label));
-		if (match !== undefined) return match.id;
-	}
-	const oauth = prompt.options.find((option) => option.id === "oauth" || option.id.includes("oauth"));
-	return oauth?.id ?? prompt.options[0]?.id ?? "";
-}
-
-async function answerPrompt(
-	prompt: AuthPrompt,
-	question: (text: string, options: { signal?: AbortSignal }) => Promise<string>,
-	method?: SubscriptionLoginMethod,
-): Promise<string> {
-	if (prompt.type === "select") return selectLoginOption(prompt, method);
-	const suffix = prompt.placeholder === undefined ? "" : ` (${prompt.placeholder})`;
-	return question(`${prompt.message}${suffix}: `, {
-		...(prompt.signal === undefined ? {} : { signal: prompt.signal }),
-	});
-}
-
-function printHelp(): void {
-	process.stdout.write(
-		[
-			"Usage: dsh-coding-oauth <login|logout|status|import> [provider] [options]",
-			"(legacy command name: dsh-grok-build)",
-			"",
-			"Providers: grok (default), codex, kimi, claude; status also accepts all.",
-			"",
-			"  login grok [--pkce|--device-auth]",
-			"  login codex [--device-auth|--browser]  (device code is the default)",
-			"  login kimi                              (device code)",
-			"  login claude [--browser]                (PKCE + redirect paste fallback)",
-			"  import [grok]                            import ~/.grok/auth.json only",
-			"  logout [provider]",
-			"  status [provider|all]",
-			"",
-			"Network: set CODING_OAUTH_PROXY, GROK_BUILD_PROXY, or HTTPS_PROXY.",
-			"Only audited subscription hosts use the proxy; Kimi stays direct by default.",
-			"",
-		].join("\n"),
-	);
-}
-
-function parseProvider(raw: string | undefined, action: CliAction): CliProvider {
-	if (raw === undefined || raw.startsWith("--")) return "grok";
-	if (raw === "all" && action === "status") return raw;
-	if (raw === "grok" || raw === "codex" || raw === "kimi" || raw === "claude") return raw;
-	throw new Error(`unknown provider ${JSON.stringify(raw)}`);
-}
-
-function loginMethod(provider: CliProvider, flags: readonly string[]): SubscriptionLoginMethod | undefined {
-	if (provider === "codex") return flags.includes("--browser") ? "browser" : "device";
-	if (provider === "kimi") return "device";
-	if (provider === "claude") return "browser";
-	return undefined;
-}
-
-function allowedFlags(action: CliAction, provider: CliProvider): readonly string[] {
-	if (action !== "login") return [];
-	if (provider === "grok") return ["--pkce", "--device-auth"];
-	if (provider === "codex") return ["--device-auth", "--browser"];
-	if (provider === "kimi") return ["--device-auth"];
-	if (provider === "claude") return ["--browser"];
-	return [];
-}
-
-async function subscriptionStatus(provider: Exclude<CliProvider, "all" | "grok">): Promise<boolean> {
-	const definition = oauthProviderDefinition(provider);
-	if (definition === undefined) throw new Error(`provider ${provider} is not configured`);
-	const session = new OAuthProviderSession(definition);
-	await session.loadCachedModels();
-	const status = await session.status();
-	if (!status.authenticated) {
-		process.stdout.write(`${definition.displayName} for dsh: signed out\n`);
-		return false;
-	}
-	const suffix =
-		status.expiresAt === undefined
-			? ""
-			: `; access token expires ${new Date(status.expiresAt).toISOString()} (refresh is automatic)`;
-	process.stdout.write(`${definition.displayName} for dsh: signed in${suffix}\n`);
-	process.stdout.write(
-		`models: ${session
-			.visibleModels()
-			.map((model) => model.id)
-			.join(", ")}\n`,
-	);
-	return true;
-}
-
-async function printGatewayWarning(): Promise<void> {
-	try {
-		const response = await fetch(`http://${GATEWAY_DEFAULT_BIND}:${String(GATEWAY_DEFAULT_PORT)}/healthz`, {
-			signal: AbortSignal.timeout(200),
-		});
-		if (!response.ok) return;
-		process.stdout.write(`WARNING: ${GATEWAY_TOS_WARNING}\n`);
-	} catch {
-		// Gateway is off or not on the default loopback port.
-	}
-}
-
-async function grokStatus(): Promise<boolean> {
-	const session = new GrokBuildSession();
-	await session.loadCachedCatalog();
-	const status = await grokBuildAuthStatus(session.store);
-	if (!status.authenticated) {
-		process.stdout.write("Grok Build for dsh: signed out\n");
-		return false;
-	}
-	await session.refreshLiveCatalog();
-	const expires = status.expiresAt;
-	const suffix =
-		expires === undefined || Number.isNaN(expires.valueOf())
-			? ""
-			: `; access token expires ${expires.toISOString()} (refresh is automatic)`;
-	process.stdout.write(`Grok Build for dsh: signed in${suffix}\n`);
-	process.stdout.write(
-		`models (${session.catalogSource}): ${session
-			.visibleModels()
-			.map((model) => model.id)
-			.join(", ")}\n`,
-	);
-	if (session.catalogError !== undefined) {
-		process.stderr.write(`dsh-coding-oauth: live models-v2 failed: ${session.catalogError}\n`);
-	}
-	return true;
-}
-
-async function loginSubscription(
-	provider: Exclude<CliProvider, "all" | "grok">,
-	flags: readonly string[],
-): Promise<void> {
-	const definition = oauthProviderDefinition(provider);
-	if (definition === undefined) throw new Error(`provider ${provider} is not configured`);
-	const method = loginMethod(provider, flags);
-	const session = new OAuthProviderSession(definition);
-	await session.loadCachedModels();
-	const readline = createInterface({ input: process.stdin, output: process.stdout });
-	try {
-		await session.login({
-			prompt: (prompt) => answerPrompt(prompt, (text, options) => readline.question(text, options), method),
-			notify: (event) => notify(event, true),
-		});
-	} finally {
-		readline.close();
-	}
-	process.stdout.write(
-		`${definition.displayName} for dsh: signed in; credentials saved to ${session.store.filename}\n`,
-	);
-	process.stdout.write(
-		`models: ${session
-			.visibleModels()
-			.map((model) => model.id)
-			.join(", ")}\n`,
-	);
-}
-
-async function loginGrok(flags: readonly string[]): Promise<void> {
-	const usePkce = flags.includes("--pkce");
-	const session = new GrokBuildSession();
-	const readline = createInterface({ input: process.stdin, output: process.stdout });
-	try {
-		if (usePkce) {
-			const credential = await loginGrokBuildPkce({
-				onAuthorizeUrl: (url) => {
-					process.stdout.write(`Open this URL to sign in:\n${url}\n`);
-					openBrowser(url);
-				},
-				awaitCode: (signal) =>
-					readline.question("After authorizing, paste the code or full redirect URL: ", { signal }),
-			});
-			const written = await session.store.modify(XAI_PI_PROVIDER, async () => credential);
-			if (written === undefined) throw new Error("credential store refused the login credential");
-			await session.refreshLiveCatalog();
-		} else {
-			await loginGrokBuildSession(
-				{
-					prompt: (prompt) => answerPrompt(prompt, (text, options) => readline.question(text, options)),
-					notify: (event) => notify(event, true),
-				},
-				session,
-			);
-		}
-	} finally {
-		readline.close();
-	}
-	process.stdout.write(`Grok Build for dsh: signed in; credentials saved to ${grokBuildAuthPath()}\n`);
-	process.stdout.write(
-		`models (${session.catalogSource}): ${session
-			.visibleModels()
-			.map((model) => model.id)
-			.join(", ")}\n`,
-	);
-}
-
-export async function run(argv: readonly string[]): Promise<number> {
-	ensureCodingOAuthProxy();
-	if (argv.length === 0 || argv[0] === "--help" || argv[0] === "-h") {
-		printHelp();
-		return 0;
-	}
-	const rawAction = argv[0];
-	if (rawAction !== "login" && rawAction !== "logout" && rawAction !== "status" && rawAction !== "import") {
-		process.stderr.write(
-			`dsh-coding-oauth: expected login, logout, status, or import; got ${JSON.stringify(rawAction)}\n`,
-		);
-		return 1;
-	}
-	const action: CliAction = rawAction;
-	try {
-		const provider = parseProvider(argv[1], action);
-		const flags = argv[1]?.startsWith("--") === true ? argv.slice(1) : argv.slice(2);
-		const allowed = allowedFlags(action, provider);
-		if (flags.some((flag) => !allowed.includes(flag))) {
-			throw new Error(`invalid options for ${action} ${provider}: ${flags.join(" ")}`);
-		}
-		if (action === "import" && provider !== "grok") throw new Error("import is supported only for Grok Build");
-		if (action !== "status" && provider === "all") throw new Error(`${action} does not accept provider all`);
-
-		if (action === "status") {
-			if (provider === "all") {
-				const results = await Promise.all([
-					grokStatus(),
-					subscriptionStatus("codex"),
-					subscriptionStatus("kimi"),
-					subscriptionStatus("claude"),
-				]);
-				await printGatewayWarning();
-				return results.some(Boolean) ? 0 : 1;
-			}
-			const signedIn = provider === "grok" ? await grokStatus() : await subscriptionStatus(provider);
-			await printGatewayWarning();
-			return signedIn ? 0 : 1;
-		}
-
-		if (action === "logout") {
-			if (provider === "grok") {
-				await new GrokBuildSession().logout();
-				process.stdout.write(`Grok Build for dsh: signed out; removed ${grokBuildAuthPath()}\n`);
-			} else {
-				const definition = oauthProviderDefinition(provider);
-				if (definition === undefined) throw new Error(`provider ${provider} is not configured`);
-				const session = new OAuthProviderSession(definition);
-				await session.logout();
-				process.stdout.write(`${definition.displayName} for dsh: signed out; removed ${session.store.filename}\n`);
-			}
-			return 0;
-		}
-
-		if (action === "import") {
-			const session = new GrokBuildSession();
-			await importGrokBuildSession(session);
-			process.stdout.write(`Grok Build for dsh: imported ${grokAuthPath()} into ${grokBuildAuthPath()}\n`);
-			process.stdout.write("The Grok CLI file was not modified. Later dsh refresh may rotate the token.\n");
-			process.stdout.write(
-				`models (${session.catalogSource}): ${session
-					.visibleModels()
-					.map((model) => model.id)
-					.join(", ")}\n`,
-			);
-			return 0;
-		}
-
-		const proxy = codingOAuthProxyInEffect();
-		if (proxy !== undefined) process.stdout.write(`Using scoped coding OAuth proxy ${redactProxyUrl(proxy)}\n`);
-		if (provider === "all") throw new Error("login does not accept provider all");
-		if (provider === "grok") await loginGrok(flags);
-		else await loginSubscription(provider, flags);
-		return 0;
-	} catch (error: unknown) {
-		process.stderr.write(`dsh-coding-oauth: ${action} failed: ${safeMessage(error)}\n`);
-		return 1;
-	}
-}
-
-if (process.argv[1] !== undefined && fileURLToPath(import.meta.url) === realpathSync(process.argv[1])) {
-	process.exitCode = await run(process.argv.slice(2));
-}

package/src/capability-routes.ts

@@ -1,279 +0,0 @@
-/**
- * Plugin-owned same-origin Web routes for the capability-settings namespace.
- * Arbitrary Host settings namespaces are not remotely exposed, so this plugin
- * publishes only the secret-free snapshot and the two optional read surfaces.
- * @module dsh-coding-subscription-oauth/capability-routes
- */
-
-import type { IncomingMessage, ServerResponse } from "node:http";
-import {
-	assertCapabilitySettingsPatch,
-	type CapabilitySettings,
-	type CapabilitySettingsPatch,
-	type CapabilitySettingsSnapshot,
-	isCapabilitySettingsConflictError,
-	isCapabilitySettingsReadOnlyError,
-	normalizeCapabilitySettingsPatch,
-} from "./capability-settings.ts";
-import { readJsonRequest, requestErrorStatus } from "./http-json.ts";
-import { CAPABILITY_SETTINGS_PATH, CODEX_USAGE_PATH, IMAGINE_CREDENTIAL_STATUS_PATH } from "./ids.ts";
-import { safeMessage } from "./redact.ts";
-import { LOOPBACK_OWNER_REQUEST_POLICY, type OwnerRequestPolicy } from "./web-origin.ts";
-import { registerWebRouteSetupAtomically } from "./web-routes.ts";
-
-export { CAPABILITY_SETTINGS_PATH, CODEX_USAGE_PATH, IMAGINE_CREDENTIAL_STATUS_PATH } from "./ids.ts";
-
-/** Structural `ctx.webServer` + `ctx.effect` surface used by the registrar. */
-export interface CapabilityRouteContext {
-	readonly webServer: {
-		register(route: {
-			kind: "exact" | "prefix";
-			path: string;
-			handler: (req: IncomingMessage, res: ServerResponse) => void | Promise<void>;
-		}): () => void;
-	};
-	effect(callback: () => () => void | Promise<void>, label?: string): unknown;
-}
-
-/** Owner-facing subset of {@link import("./capability-settings.ts").CapabilitySettingsController}. */
-export interface CapabilityRouteController {
-	snapshot(): CapabilitySettingsSnapshot;
-	current(): CapabilitySettings;
-	patch(patch: CapabilitySettingsPatch, expectedRevision: number): Promise<CapabilitySettingsSnapshot>;
-	replace(section: CapabilitySettingsPatch, expectedRevision: number): Promise<CapabilitySettingsSnapshot>;
-}
-
-/** Secret-free Imagine credential probe returned on the optional status route. */
-export interface ImagineCredentialStatus {
-	readonly configured: boolean;
-	readonly source: string;
-	readonly writable: boolean;
-}
-
-export interface CapabilityRouteOptions {
-	readonly controller: CapabilityRouteController;
-	readonly usage?: () => unknown | Promise<unknown>;
-	readonly credentialInfo?: () => unknown | Promise<unknown>;
-	readonly ownerRequestPolicy?: OwnerRequestPolicy;
-}
-
-class CapabilityRouteRequestError extends Error {
-	readonly statusCode: number;
-
-	constructor(statusCode: number, message: string) {
-		super(message);
-		this.name = "CapabilityRouteRequestError";
-		this.statusCode = statusCode;
-	}
-}
-
-/** Register the plugin-owned capability routes. Owns and returns the route disposer. */
-export function registerCapabilityRoutes(ctx: CapabilityRouteContext, options: CapabilityRouteOptions): () => void {
-	const { controller, usage, credentialInfo } = options;
-	const ownerRequestPolicy = options.ownerRequestPolicy ?? LOOPBACK_OWNER_REQUEST_POLICY;
-	let dispose = (): void => undefined;
-	ctx.effect(() => {
-		dispose = registerWebRouteSetupAtomically(ctx.webServer, (webServer) => {
-			webServer.register({
-				kind: "exact",
-				path: CAPABILITY_SETTINGS_PATH,
-				handler: (req, res) => handleCapabilities(req, res, controller, ownerRequestPolicy),
-			});
-			if (usage !== undefined) {
-				webServer.register({
-					kind: "exact",
-					path: CODEX_USAGE_PATH,
-					handler: (req, res) => handleUsage(req, res, controller, usage, ownerRequestPolicy),
-				});
-			}
-			if (credentialInfo !== undefined) {
-				webServer.register({
-					kind: "exact",
-					path: IMAGINE_CREDENTIAL_STATUS_PATH,
-					handler: (req, res) => handleCredentialStatus(req, res, credentialInfo, ownerRequestPolicy),
-				});
-			}
-		});
-		return dispose;
-	}, "dsh-coding-subscription-oauth: capability routes");
-	return () => dispose();
-}
-
-async function handleCapabilities(
-	req: IncomingMessage,
-	res: ServerResponse,
-	controller: CapabilityRouteController,
-	ownerRequestPolicy: OwnerRequestPolicy,
-): Promise<void> {
-	const method = req.method ?? "";
-	if (method !== "GET" && method !== "PATCH" && method !== "PUT") {
-		json(res, 405, { error: "method not allowed" });
-		return;
-	}
-	if (!ownerRequestPolicy.authorize(req).authorized) {
-		json(res, 403, { error: "forbidden" });
-		return;
-	}
-	try {
-		if (method === "GET") {
-			json(res, 200, controller.snapshot());
-			return;
-		}
-		const body = await readJsonRequest(req);
-		if (method === "PATCH") {
-			const { expectedRevision, payload } = readWriteEnvelope(body, "patch");
-			json(res, 200, await controller.patch(admitCapabilitySection(payload, "patch"), expectedRevision));
-			return;
-		}
-		const { expectedRevision, payload } = readWriteEnvelope(body, "value");
-		json(res, 200, await controller.replace(admitCapabilitySection(payload, "value"), expectedRevision));
-	} catch (error: unknown) {
-		const status = statusFor(error);
-		json(res, status, errorBody(error, status));
-	}
-}
-
-async function handleUsage(
-	req: IncomingMessage,
-	res: ServerResponse,
-	controller: CapabilityRouteController,
-	usage: () => unknown | Promise<unknown>,
-	ownerRequestPolicy: OwnerRequestPolicy,
-): Promise<void> {
-	if (req.method !== "GET") {
-		json(res, 405, { error: "method not allowed" });
-		return;
-	}
-	if (!ownerRequestPolicy.authorize(req).authorized) {
-		json(res, 403, { error: "forbidden" });
-		return;
-	}
-	try {
-		if (controller.current().codexUsage !== true) {
-			json(res, 404, { error: "disabled" });
-			return;
-		}
-		json(res, 200, await usage());
-	} catch (error: unknown) {
-		const status = statusFor(error);
-		json(res, status, errorBody(error, status));
-	}
-}
-
-async function handleCredentialStatus(
-	req: IncomingMessage,
-	res: ServerResponse,
-	credentialInfo: () => unknown | Promise<unknown>,
-	ownerRequestPolicy: OwnerRequestPolicy,
-): Promise<void> {
-	if (req.method !== "GET") {
-		json(res, 405, { error: "method not allowed" });
-		return;
-	}
-	if (!ownerRequestPolicy.authorize(req).authorized) {
-		json(res, 403, { error: "forbidden" });
-		return;
-	}
-	try {
-		json(res, 200, publicCredentialStatus(await credentialInfo()));
-	} catch (error: unknown) {
-		const status = statusFor(error);
-		json(res, status, errorBody(error, status));
-	}
-}
-
-function readWriteEnvelope(
-	body: unknown,
-	payloadKey: "patch" | "value",
-): { expectedRevision: number; payload: Record<string, unknown> } {
-	if (!isPlainObject(body)) {
-		throw new CapabilityRouteRequestError(400, "request body must be a JSON object");
-	}
-	const expectedRevision = body["expectedRevision"];
-	if (typeof expectedRevision !== "number" || !Number.isInteger(expectedRevision) || expectedRevision < 0) {
-		throw new CapabilityRouteRequestError(400, "expectedRevision must be a nonnegative integer");
-	}
-	const payload = body[payloadKey];
-	if (!isPlainObject(payload)) {
-		throw new CapabilityRouteRequestError(400, `${payloadKey} must be a JSON object`);
-	}
-	return { expectedRevision, payload };
-}
-
-/** Admit a wire section without silently coercing, truncating, or clamping it. */
-function admitCapabilitySection(input: Record<string, unknown>, label: string): CapabilitySettingsPatch {
-	try {
-		assertCapabilitySettingsPatch(input, label);
-	} catch (error) {
-		throw new CapabilityRouteRequestError(400, safeMessage(error));
-	}
-	return normalizeCapabilitySettingsPatch(input);
-}
-
-function publicCredentialStatus(info: unknown): ImagineCredentialStatus {
-	const record = isPlainObject(info) ? info : {};
-	const source = record["source"];
-	return {
-		configured: record["configured"] === true,
-		source: typeof source === "string" && source.length <= 40 && /^[a-z0-9._-]+$/iu.test(source) ? source : "unknown",
-		writable: record["writable"] === true,
-	};
-}
-
-function statusFor(error: unknown): number {
-	if (error instanceof CapabilityRouteRequestError) return error.statusCode;
-	const jsonStatus = requestErrorStatus(error, 0);
-	if (jsonStatus !== 0) return jsonStatus;
-	if (conflictInfo(error) !== undefined) return 409;
-	if (isCapabilitySettingsReadOnlyError(error)) {
-		return error.reason === "read-only" ? 403 : 503;
-	}
-	if (typeof error === "object" && error !== null) {
-		const code = (error as { code?: unknown }).code;
-		if (code === "SETTINGS_READ_ONLY") return 403;
-		if (code === "SETTINGS_PROVIDER_ABSENT" || code === "SETTINGS_DISPOSED") return 503;
-	}
-	if (error instanceof TypeError) return 400;
-	return 500;
-}
-
-function errorBody(error: unknown, status: number): Record<string, unknown> {
-	const body: Record<string, unknown> = { error: status >= 500 ? "request failed" : safeMessage(error) };
-	const conflict = conflictInfo(error);
-	if (conflict !== undefined) {
-		body["code"] = "SETTINGS_CONFLICT";
-		body["expected"] = conflict.expected;
-		body["actual"] = conflict.actual;
-		return body;
-	}
-	if (isCapabilitySettingsReadOnlyError(error)) {
-		body["code"] = error.code;
-	}
-	return body;
-}
-
-function conflictInfo(error: unknown): { expected: number; actual: number } | undefined {
-	if (isCapabilitySettingsConflictError(error)) {
-		return { expected: error.expected, actual: error.actual };
-	}
-	if (typeof error !== "object" || error === null) return undefined;
-	const candidate = error as { code?: unknown; expected?: unknown; actual?: unknown };
-	if (candidate.code !== "SETTINGS_CONFLICT") return undefined;
-	if (typeof candidate.expected !== "number" || typeof candidate.actual !== "number") return undefined;
-	return { expected: candidate.expected, actual: candidate.actual };
-}
-
-function isPlainObject(value: unknown): value is Record<string, unknown> {
-	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
-	const proto = Object.getPrototypeOf(value);
-	return proto === Object.prototype || proto === null;
-}
-
-function json(res: ServerResponse, status: number, value: unknown): void {
-	res.writeHead(status, {
-		"content-type": "application/json; charset=utf-8",
-		"cache-control": "no-store",
-		"x-content-type-options": "nosniff",
-	});
-	res.end(JSON.stringify(value));
-}