Keys section (auth/provider-keys wave): BYOK keys in the settings dialog

Owner-approved design (2026-09-20): a Keys section right after General,
two groups over the merged auth API (GET /api/keys masked statuses,
PUT/DELETE /api/keys/:id, immediate effect, shape-gated 400s):

- Model providers: OpenRouter pinned as an always-visible row (the
  app's lifeline — synthesized when absent so first boot shows it),
  stored provider keys render as they appear, and an Add-provider
  dropdown lists every pi-ai provider that takes an API key. The
  dropdown reads GET /api/keys' optional providers array — the
  Platform interlude (master-routed) derives it from pi-ai's own
  env-key table; until it lands the group shows a pending note
  (rolePins pattern — absent field, no drift, no guessed routes).
- Tools & services: the curated rows — Deepgram (dictation) and the
  Google pair (search key + CSE ID) — with description hints and docs
  links (external links route through the Electron shell to the real
  browser).
- Rows: always-visible paste inputs (owner choice; no reveal —
  plaintext never returns from the store), masked status line
  (…tail · chars · environment|saved), the shadowedByEnv explanation
  when a real env var owns the name, per-row inline 400 messages, Save
  on Enter/button, Delete when present (env-owned keys honestly keep
  their env status after a file delete).
- Unknown auth.json vars surface as read-only dimmed rows — preserved
  by the store, not editable through the curated surface.

classifyKeys/keyStatusLine pure exports drive the two-group
projection; tests: SSR loading state, first-boot synthesis, provider
row classification, addable filtering, unknown-var read-only status
line formatting. Nav grows to six sections (Keys second).

Live-verified: nav order, structure, bad-paste 400s inline, save
round-trip with env-shadow explanation, delete round-trip, env-owned
OpenRouter status stability. Gates: typecheck, lint, 748/748, build.

components/settings/keys-section.tsx

@@ -0,0 +1,379 @@
+"use client";
+/**
+ * The Keys section (auth/provider-keys wave, 2026-09-20): BYOK keys over
+ * the merged auth API — GET /api/keys (masked statuses, never plaintext),
+ * PUT /api/keys/:id (shape-gated 400s), DELETE /api/keys/:id. Saves take
+ * effect immediately (file + env reflection, no restart).
+ *
+ * Two groups (owner design):
+ *  - Model providers — free-form, pi-compatible. OpenRouter is pinned as
+ *    an always-visible row (the app's lifeline: every model call today),
+ *    other providers appear when stored, and an Add-provider dropdown
+ *    lists every pi-ai provider that takes an API key. The list arrives as
+ *    GET /api/keys' optional `providers` array (Platform interlude; the
+ *    rolePins pattern — absent = the dropdown waits, everything else
+ *    works). Provider ids/env vars come from pi-ai's own table, so this
+ *    UI cannot drift from what pi actually reads.
+ *  - Tools & services — the curated rows: Deepgram (dictation) and the
+ *    Google pair (search key + CSE ID), each with description + docs
+ *    link (opens in the real browser; the Electron shell routes it).
+ *
+ * Owner UX decisions: always-visible paste inputs (no reveal affordance —
+ * plaintext never returns from the store, masked tail + length only);
+ * bad pastes show the server's format message inline; a dev .env.local
+ * variable beats the saved file value and the row says so honestly.
+ *
+ * Unknown auth.json vars surface as read-only dimmed rows — preserved by
+ * the store (forward-compat), not editable through the curated surface.
+ */
+
+import { useEffect, useState } from "react";
+import { type AuthKeyStatus } from "@/src/core";
+import { SettingsGroup, SettingsRow } from "./controls.tsx";
+
+/** One pi-ai provider with plain API-key auth (the Platform seam). */
+export interface ProviderKeyInfo {
+	/** pi-ai provider id ("groq", "deepseek", …). */
+	id: string;
+	/** The env var / auth.json key a paste writes ("GROQ_API_KEY", …). */
+	envVar: string;
+	label: string;
+}
+
+/** GET /api/keys — merged shape plus the interlude's optional array. */
+interface KeysResponse {
+	keys: AuthKeyStatus[];
+	providers?: ProviderKeyInfo[];
+}
+
+/** The OpenRouter row survives its curated-catalog graduation: the label
+ *  is pinned here so the row reads correctly even when the catalog no
+ *  longer carries it (first boot: absent, not even a status row). */
+const OPENROUTER_ID = "OPENROUTER_API_KEY";
+const OPENROUTER_FALLBACK = {
+	label: "OpenRouter",
+	description: "The main model key — every teacher, prober and sub-agent call goes through it.",
+	docsUrl: "https://openrouter.ai/settings/keys",
+};
+
+/** The curated tools group, pinned by id (the catalog owns the copy;
+ *  these ids are the contract). */
+const TOOL_IDS = ["DEEPGRAM_API_KEY", "GOOGLE_SEARCH_API_KEY", "GOOGLE_CSE_ID"] as const;
+
+/** The classification that drives the section's two groups. Pure —
+ *  exported for tests. */
+export function classifyKeys(
+	statuses: readonly AuthKeyStatus[],
+	providers: readonly ProviderKeyInfo[] | undefined,
+): {
+	openrouter: AuthKeyStatus;
+	/** Stored non-OpenRouter provider keys, with their provider entry. */
+	providerRows: { status: AuthKeyStatus; provider?: ProviderKeyInfo }[];
+	/** The curated tools rows (synthesized when absent = first boot). */
+	toolRows: AuthKeyStatus[];
+	/** Unknown file vars — preserved, read-only. */
+	unknownRows: AuthKeyStatus[];
+	/** Providers without a stored key — the Add dropdown's options. */
+	addable: ProviderKeyInfo[];
+} {
+	const byId = new Map(statuses.map((s) => [s.id, s]));
+	const providerByEnv = new Map((providers ?? []).map((p) => [p.envVar, p]));
+	const synth = (id: string): AuthKeyStatus => ({
+		id,
+		info: null,
+		present: false,
+		masked: null,
+		source: "none",
+		shadowedByEnv: false,
+	});
+	const isTool = (id: string) => (TOOL_IDS as readonly string[]).includes(id);
+	const providerRows: { status: AuthKeyStatus; provider?: ProviderKeyInfo }[] = [];
+	const unknownRows: AuthKeyStatus[] = [];
+	for (const s of statuses) {
+		if (s.id === OPENROUTER_ID || isTool(s.id)) continue;
+		const provider = providerByEnv.get(s.id);
+		if (provider) providerRows.push({ status: s, provider });
+		else if (!s.info) unknownRows.push(s);
+		// a curated-but-present status outside the pinned ids: treat as a
+		// provider row (pre-interlude the catalog only has the pinned ids).
+		else providerRows.push({ status: s });
+	}
+	return {
+		openrouter: byId.get(OPENROUTER_ID) ?? synth(OPENROUTER_ID),
+		providerRows,
+		toolRows: TOOL_IDS.map((id) => byId.get(id) ?? synth(id)),
+		unknownRows,
+		addable: (providers ?? []).filter((p) => p.envVar !== OPENROUTER_ID && !byId.has(p.envVar)),
+	};
+}
+
+/** The masked status line, e.g. "…ab12 · 64 chars · saved" — the row's
+ *  at-a-glance state. Pure — tests. */
+export function keyStatusLine(status: AuthKeyStatus): string | null {
+	if (!status.present || !status.masked) return null;
+	const where = status.source === "env" ? "environment" : "saved";
+	return `${status.masked.replace(/ \(\d+ chars\)$/, "")} · ${status.masked.match(/\((\d+) chars\)$/)?.[1] ?? "?"} chars · ${where}`;
+}
+
+/** One editable key row: status + paste input + Save + (Delete when
+ *  present). The 400 message lands inline under the input. */
+function KeyEditorRow({
+	label,
+	hint,
+	docsUrl,
+	status,
+	onSave,
+	onDelete,
+	testid,
+}: {
+	label: string;
+	hint?: string;
+	docsUrl?: string;
+	status: AuthKeyStatus;
+	onSave: (value: string) => Promise<string | null>;
+	onDelete?: () => Promise<void>;
+	testid: string;
+}) {
+	const [value, setValue] = useState("");
+	const [error, setError] = useState<string | null>(null);
+	const [busy, setBusy] = useState(false);
+
+	const statusLine = keyStatusLine(status);
+
+	async function save() {
+		if (!value.trim() || busy) return;
+		setBusy(true);
+		setError(null);
+		const err = await onSave(value);
+		if (err) setError(err);
+		else setValue("");
+		setBusy(false);
+	}
+
+	return (
+		<div data-testid={testid}>
+			<SettingsRow label={label} hint={hint} testid={`${testid}-row`}>
+				{statusLine && (
+					<span
+						data-testid={`${testid}-status`}
+						className="font-mono text-[11px] text-muted-foreground"
+					>
+						{statusLine}
+						{status.shadowedByEnv && (
+							<span className="text-foreground"> — an environment variable owns this name; the saved value is stored but not live</span>
+						)}
+					</span>
+				)}
+				<a
+					href={docsUrl ?? "about:blank"}
+					target="_blank"
+					rel="noreferrer"
+					aria-disabled={!docsUrl}
+					onClick={docsUrl ? undefined : (e) => e.preventDefault()}
+					className={`text-[11px] underline-offset-2 hover:underline ${docsUrl ? "text-muted-foreground hover:text-foreground" : "invisible"}`}
+				>
+					Get a key ↗
+				</a>
+			</SettingsRow>
+			<div className="mt-1 flex items-center gap-2 pl-6">
+				<input
+					type="text"
+					value={value}
+					onChange={(e) => setValue(e.target.value)}
+					onKeyDown={(e) => {
+						if (e.key === "Enter") void save();
+					}}
+					placeholder="Paste key…"
+					aria-label={`${label} key`}
+					data-testid={`${testid}-input`}
+					disabled={busy}
+					className="h-7 w-72 rounded-sm border border-border bg-background px-1.5 font-mono text-xs text-foreground outline-none placeholder:text-muted-foreground/60 focus:border-muted-foreground/50"
+				/>
+				<button
+					type="button"
+					onClick={() => void save()}
+					disabled={busy || !value.trim()}
+					data-testid={`${testid}-save`}
+					className="text-xs text-foreground underline-offset-2 hover:underline disabled:text-muted-foreground/40 disabled:no-underline"
+				>
+					Save
+				</button>
+				{status.present && onDelete && (
+					<button
+						type="button"
+						onClick={() => void onDelete()}
+						disabled={busy}
+						data-testid={`${testid}-delete`}
+						className="text-xs text-muted-foreground/70 underline-offset-2 hover:text-red-500 hover:underline"
+					>
+						Delete
+					</button>
+				)}
+			</div>
+			{error && (
+				<p role="alert" data-testid={`${testid}-error`} className="mt-1 pl-6 text-xs text-red-500">
+					{error}
+				</p>
+			)}
+		</div>
+	);
+}
+
+export function KeysSection() {
+	const [statuses, setStatuses] = useState<AuthKeyStatus[] | null>(null);
+	const [providers, setProviders] = useState<ProviderKeyInfo[] | undefined>(undefined);
+	/** The provider chosen in the Add dropdown, if any. */
+	const [adding, setAdding] = useState<ProviderKeyInfo | null>(null);
+	const [loading, setLoading] = useState(true);
+
+	const reload = () =>
+		fetch("/api/keys")
+			.then((r) => r.json())
+			.then((body: KeysResponse) => {
+				setStatuses(body.keys ?? []);
+				if (body.providers) setProviders(body.providers);
+			})
+			.catch(() => setStatuses([]))
+			.finally(() => setLoading(false));
+
+	useEffect(() => {
+		void reload();
+	}, []);
+
+	async function saveKey(id: string, value: string): Promise<string | null> {
+		const res = await fetch(`/api/keys/${id}`, {
+			method: "PUT",
+			headers: { "content-type": "application/json" },
+			body: JSON.stringify({ value }),
+		});
+		if (!res.ok) {
+			const body = (await res.json().catch(() => ({}))) as { error?: string };
+			return body.error ?? `Save failed (${res.status})`;
+		}
+		await reload();
+		return null;
+	}
+
+	async function deleteKey(id: string): Promise<void> {
+		await fetch(`/api/keys/${id}`, { method: "DELETE" }).catch(() => undefined);
+		await reload();
+	}
+
+	if (loading || statuses === null) {
+		return <p className="px-6 py-5 text-xs text-muted-foreground/70">Loading keys…</p>;
+	}
+
+	const { openrouter, providerRows, toolRows, unknownRows, addable } = classifyKeys(statuses, providers);
+	const envWarning = openrouter.shadowedByEnv;
+
+	return (
+		<>
+			<SettingsGroup label="Model providers" testid="group-provider-keys">
+				<KeyEditorRow
+					label={openrouter.info?.label ?? OPENROUTER_FALLBACK.label}
+					hint={openrouter.info?.description ?? OPENROUTER_FALLBACK.description}
+					docsUrl={openrouter.info?.docsUrl ?? OPENROUTER_FALLBACK.docsUrl}
+					status={openrouter}
+					testid="key-openrouter"
+					onSave={(v) => saveKey(OPENROUTER_ID, v)}
+					onDelete={() => deleteKey(OPENROUTER_ID)}
+				/>
+				{providerRows.map(({ status, provider }) => (
+					<KeyEditorRow
+						key={status.id}
+						label={provider?.label ?? status.id}
+						hint={status.info?.description ?? provider?.id}
+						docsUrl={status.info?.docsUrl}
+						status={status}
+						testid={`key-${provider?.id ?? status.id.toLowerCase()}`}
+						onSave={(v) => saveKey(status.id, v)}
+						onDelete={() => deleteKey(status.id)}
+					/>
+				))}
+				{providers === undefined ? (
+					<p className="text-xs text-muted-foreground/60" data-testid="providers-pending">
+						The full provider list ships with the server update.
+					</p>
+				) : (
+					<div className="mt-1 pl-6" data-testid="add-provider">
+						<div className="flex items-center gap-2">
+							<span className="text-xs text-muted-foreground">Add provider key</span>
+							<select
+								aria-label="Add provider key"
+								data-testid="add-provider-select"
+								value={adding?.id ?? ""}
+								onChange={(e) => {
+									const next = addable.find((p) => p.id === e.target.value) ?? null;
+									setAdding(next);
+								}}
+								className="h-7 rounded-sm border border-border bg-background px-1.5 font-ui text-xs text-foreground outline-none"
+							>
+								<option value="">Choose a provider…</option>
+								{addable.map((p) => (
+									<option key={p.id} value={p.id}>
+										{p.label} ({p.envVar})
+									</option>
+								))}
+							</select>
+						</div>
+						{adding && (
+							<div className="mt-2">
+								<KeyEditorRow
+									label={adding.label}
+									hint={adding.id}
+									status={statuses.find((s) => s.id === adding.envVar) ?? {
+										id: adding.envVar,
+										info: null,
+										present: false,
+										masked: null,
+										source: "none" as const,
+										shadowedByEnv: false,
+									}}
+									testid={`key-${adding.id}`}
+									onSave={(v) => saveKey(adding.envVar, v)}
+									onDelete={() => deleteKey(adding.envVar)}
+								/>
+							</div>
+						)}
+					</div>
+				)}
+				{envWarning && (
+					<p className="text-xs text-foreground" data-testid="openrouter-shadowed">
+						The environment variable {OPENROUTER_ID} is set — it wins over any key saved here.
+					</p>
+				)}
+			</SettingsGroup>
+
+			<SettingsGroup label="Tools & services" testid="group-tool-keys">
+				{toolRows.map((status) => (
+					<KeyEditorRow
+						key={status.id}
+						label={status.info?.label ?? status.id}
+						hint={status.info?.description}
+						docsUrl={status.info?.docsUrl}
+						status={status}
+						testid={`key-${status.id.toLowerCase()}`}
+						onSave={(v) => saveKey(status.id, v)}
+						onDelete={() => deleteKey(status.id)}
+					/>
+				))}
+			</SettingsGroup>
+
+			{unknownRows.length > 0 && (
+				<SettingsGroup label="Other stored variables" testid="group-unknown-keys">
+					{unknownRows.map((status) => (
+						<SettingsRow
+							key={status.id}
+							label={status.id}
+							hint="preserved from auth.json — read-only"
+							testid={`unknown-${status.id}`}
+							dimmed
+						>
+							<span className="font-mono text-[11px] text-muted-foreground">{status.masked}</span>
+						</SettingsRow>
+					))}
+				</SettingsGroup>
+			)}
+		</>
+	);
+}

components/settings/settings-dialog.tsx

@@ -39,6 +39,7 @@ import {
 import { useAppearance } from "./appearance.tsx";
 import { SettingsSection, SettingsRow, Toggle } from "./controls.tsx";
 import { AgentSection } from "./agent-section.tsx";
+import { KeysSection } from "./keys-section.tsx";
 import { AppearanceSection, GraphSection } from "./appearance-section.tsx";
 import { KeyboardSection } from "./keyboard-section.tsx";
 
@@ -47,6 +48,7 @@ import { KeyboardSection } from "./keyboard-section.tsx";
  *  real question users ask). */
 const SECTIONS = [
 	{ id: "general", label: "General" },
+	{ id: "keys", label: "Keys" },
 	{ id: "agent", label: "Agent" },
 	{ id: "appearance", label: "Appearance" },
 	{ id: "graph", label: "Graph" },
@@ -257,6 +259,11 @@ export function SettingsDialogBody({ onClose }: { onClose: () => void }) {
 									</SettingsRow>
 								</SettingsSection>
 							)}
+							{active === "keys" && (
+								<SettingsSection title="Keys" testid="section-keys">
+									<KeysSection />
+								</SettingsSection>
+							)}
 							{active === "agent" && (
 								<SettingsSection
 									title="Agent"

tests/render-settings.test.tsx

@@ -14,6 +14,7 @@ import { describe, it } from "node:test";
 import { renderToStaticMarkup } from "react-dom/server";
 import { TOGGLE_TOOLS, AgentSection } from "../components/settings/agent-section.tsx";
 import { AppearanceSection, GraphSection } from "../components/settings/appearance-section.tsx";
+import { KeysSection } from "../components/settings/keys-section.tsx";
 import { KeyboardSection } from "../components/settings/keyboard-section.tsx";
 import { SettingsDialogBody, SettingsDialogProvider } from "../components/settings/settings-dialog.tsx";
 import { KEYBOARD_ACTIONS } from "../src/core/index.ts";
@@ -39,12 +40,12 @@ describe("SettingsDialog (the designed surface, SSR)", () => {
 		assert.ok(!html.includes("settings-dialog"));
 	});
 
-	it("the dialog frame: role=dialog + the ✕ + the five-section nav, General active", () => {
+	it("the dialog frame: role=dialog + the ✕ + the six-section nav, General active", () => {
 		const html = renderToStaticMarkup(<SettingsDialogBody onClose={() => {}} />);
 		assert.ok(html.includes('role="dialog"'));
 		assert.ok(html.includes('aria-modal="true"'));
 		assert.ok(html.includes('aria-label="Close settings"'));
-		for (const id of ["general", "agent", "appearance", "graph", "keyboard"]) {
+		for (const id of ["general", "keys", "agent", "appearance", "graph", "keyboard"]) {
 			assert.ok(html.includes(`data-testid="settings-nav-${id}"`), id);
 		}
 		// General is the landing section; the others are not current.
@@ -138,6 +139,13 @@ describe("GraphSection — the dependency ladder", () => {
 	});
 });
 
+describe("KeysSection (thin SSR)", () => {
+	it("SSR = the loading state (effects never fire)", () => {
+		const html = renderToStaticMarkup(<KeysSection />);
+		assert.ok(html.includes("Loading keys…"));
+	});
+});
+
 describe("AppearanceSection (thin SSR)", () => {
 	it("mode is rendered DISABLED — dark-only this wave, no lying control", () => {
 		const html = renderToStaticMarkup(<AppearanceSection appearance={undefined} onSectionChange={() => {}} />);

tests/settings-pure.test.ts

@@ -10,6 +10,8 @@ import { describe, it } from "node:test";
 import { appearanceVars, derivedPalette, resolveAppearance } from "../components/settings/appearance.tsx";
 import { composePromptSwitch, composeRoleModel, composeTool } from "../components/settings/agent-section.tsx";
 import { nextOverrides } from "../components/settings/keyboard-section.tsx";
+import { classifyKeys, keyStatusLine, type ProviderKeyInfo } from "../components/settings/keys-section.tsx";
+import type { AuthKeyStatus } from "../src/core";
 
 describe("resolveAppearance — delta over factory", () => {
 	it("absent everything = the factory view", () => {
@@ -136,4 +138,76 @@ describe("nextOverrides — the rebind persistence map", () => {
 		const next = nextOverrides({ "toggle-sidebar": "mod+b", find: "mod+f" }, "toggle-sidebar", null);
 		assert.deepEqual(next, { find: "mod+f" });
 	});
-});
+});
+
+describe("classifyKeys — the Keys section's two-group projection", () => {
+	const synth = (id: string, present = false): AuthKeyStatus => ({
+		id,
+		info: null,
+		present,
+		masked: present ? `…${id.slice(-4)} (32 chars)` : null,
+		source: present ? "file" : "none",
+		shadowedByEnv: false,
+	});
+	const providers: ProviderKeyInfo[] = [
+		{ id: "groq", envVar: "GROQ_API_KEY", label: "Groq" },
+		{ id: "deepseek", envVar: "DEEPSEEK_API_KEY", label: "DeepSeek" },
+		{ id: "openrouter", envVar: "OPENROUTER_API_KEY", label: "OpenRouter" },
+	];
+
+	it("OpenRouter is pinned: synthesized when absent (first boot), found when present", () => {
+		const none = classifyKeys([], providers);
+		assert.equal(none.openrouter.id, "OPENROUTER_API_KEY");
+		assert.ok(!none.openrouter.present);
+		const stored = classifyKeys([synth("OPENROUTER_API_KEY", true)], providers);
+		assert.ok(stored.openrouter.present);
+	});
+
+	it("stored provider keys land in providerRows with their provider entry", () => {
+		const out = classifyKeys([synth("GROQ_API_KEY", true)], providers);
+		assert.equal(out.providerRows.length, 1);
+		assert.equal(out.providerRows[0]!.provider?.id, "groq");
+		// the Add dropdown no longer offers groq
+		assert.ok(!out.addable.some((p) => p.id === "groq"));
+		assert.ok(out.addable.some((p) => p.id === "deepseek"));
+	});
+
+	it("curated tool ids always render (synthesized when absent)", () => {
+		const out = classifyKeys([synth("DEEPGRAM_API_KEY", true)], undefined);
+		assert.deepEqual(out.toolRows.map((r) => r.id), [
+			"DEEPGRAM_API_KEY",
+			"GOOGLE_SEARCH_API_KEY",
+			"GOOGLE_CSE_ID",
+		]);
+		assert.ok(out.toolRows[0]!.present);
+		assert.ok(!out.toolRows[1]!.present);
+	});
+
+	it("unknown file vars surface read-only, out of the provider rows", () => {
+		const out = classifyKeys([synth("PLANS_LOGIN_TOKEN", true)], providers);
+		assert.equal(out.unknownRows.length, 1);
+		assert.equal(out.providerRows.length, 0);
+	});
+
+	it("providers seam absent = addable empty, nothing crashes", () => {
+		const out = classifyKeys([], undefined);
+		assert.deepEqual(out.addable, []);
+	});
+});
+
+describe("keyStatusLine — the masked at-a-glance state", () => {
+	it("present file key: tail, chars, source", () => {
+		assert.equal(
+			keyStatusLine({ id: "X", info: null, present: true, masked: "…ab12 (64 chars)", source: "file", shadowedByEnv: false }),
+			"…ab12 · 64 chars · saved",
+		);
+	});
+
+	it("env-sourced key reads 'environment'", () => {
+		assert.ok(keyStatusLine({ id: "X", info: null, present: true, masked: "…ab12 (64 chars)", source: "env", shadowedByEnv: false })?.endsWith("environment"));
+	});
+
+	it("absent key has no line", () => {
+		assert.equal(keyStatusLine({ id: "X", info: null, present: false, masked: null, source: "none", shadowedByEnv: false }), null);
+	});
+});