fix(settings): address PR review feedback for settings page

Record last_backup_at on export, document the provider SSRF carve-out,
add 401 auth tests for new routes, and polish settings UX/docs.

Author: mikkisguy

AGENTS.md

@@ -231,6 +231,16 @@ Test helper: `authedRequest(url, init)` in `src/db/test-utils.ts` signs a sessio
 - See the App Security Baseline design spec
   (docs/superpowers/specs/2026-06-19-app-security-baseline-design.md §7)
   for the full policy.
+- **Carve-out — admin-configured provider endpoints.** Chat-provider
+  connections in `src/lib/settings/provider-connection.ts` (Hermes,
+  OpenCode Go) intentionally do **not** use `validateFetchUrl`. The base
+  URLs are operator-only settings saved through the authenticated settings
+  route, and the defaults point at local services (e.g.
+  `http://localhost:8642/v1`) that the private-range guard would block by
+  design. These are trusted, admin-supplied destinations — not arbitrary
+  user input — so the SSRF guard does not apply. Any new fetch of a URL
+  that originates from an unauthenticated or non-admin source MUST still go
+  through `validateFetchUrl`.
 
 ## Frontend Guidelines
 

src/app/api/__tests__/settings.test.ts

@@ -10,6 +10,8 @@ import { GET, PATCH } from "@/app/api/settings/route";
 import { POST as POST_TEST } from "@/app/api/settings/test-connection/route";
 import { GET as GET_SYSTEM_INFO } from "@/app/api/settings/system-info/route";
 import { GET as GET_EXPORT } from "@/app/api/export/route";
+import { GET as GET_OPENROUTER_MODELS } from "@/app/api/settings/openrouter/models/route";
+import { GET as GET_PROVIDER_MODELS } from "@/app/api/settings/provider-models/route";
 
 describe("/api/settings", () => {
   beforeEach(() => {
@@ -140,4 +142,75 @@ describe("/api/settings", () => {
     const body = await res.text();
     expect(body.startsWith("[")).toBe(true);
   });
+
+  it("records last_backup_at on a successful export", async () => {
+    const res = await GET_EXPORT(
+      await authedGet("http://localhost/api/export?format=json")
+    );
+    expect(res.status).toBe(200);
+
+    const db = getDb();
+    const lastBackupAt = settings.get(db, "last_backup_at");
+    expect(lastBackupAt).not.toBeNull();
+    expect(() => new Date(lastBackupAt as string).toISOString()).not.toThrow();
+  });
+
+  describe("unauthenticated access", () => {
+    it("rejects GET /api/settings with 401", async () => {
+      const res = await GET(new Request("http://localhost/api/settings"));
+      expect(res.status).toBe(401);
+    });
+
+    it("rejects PATCH /api/settings with 401", async () => {
+      const res = await PATCH(
+        new Request("http://localhost/api/settings", {
+          method: "PATCH",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ ai_model: "openai/gpt-4" }),
+        })
+      );
+      expect(res.status).toBe(401);
+    });
+
+    it("rejects POST /api/settings/test-connection with 401", async () => {
+      const res = await POST_TEST(
+        new Request("http://localhost/api/settings/test-connection", {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ provider: "hermes" }),
+        })
+      );
+      expect(res.status).toBe(401);
+    });
+
+    it("rejects GET /api/settings/system-info with 401", async () => {
+      const res = await GET_SYSTEM_INFO(
+        new Request("http://localhost/api/settings/system-info")
+      );
+      expect(res.status).toBe(401);
+    });
+
+    it("rejects GET /api/settings/openrouter/models with 401", async () => {
+      const res = await GET_OPENROUTER_MODELS(
+        new Request("http://localhost/api/settings/openrouter/models")
+      );
+      expect(res.status).toBe(401);
+    });
+
+    it("rejects GET /api/settings/provider-models with 401", async () => {
+      const res = await GET_PROVIDER_MODELS(
+        new Request(
+          "http://localhost/api/settings/provider-models?provider=opencode-go"
+        )
+      );
+      expect(res.status).toBe(401);
+    });
+
+    it("rejects GET /api/export with 401", async () => {
+      const res = await GET_EXPORT(
+        new Request("http://localhost/api/export?format=json")
+      );
+      expect(res.status).toBe(401);
+    });
+  });
 });

src/app/api/export/route.ts

@@ -1,4 +1,4 @@
-import { getDb, contentItems } from "@/db/index";
+import { getDb, contentItems, settings } from "@/db/index";
 import { errorResponse, logServerError } from "@/lib/api";
 import { requireAuthenticated } from "@/lib/auth/guard";
 import { log } from "@/lib/logger";
@@ -42,7 +42,13 @@ export async function GET(request: Request) {
     }
 
     const items = listAllItems();
-    const exportedAt = new Date().toISOString().slice(0, 10);
+    const now = new Date();
+    const exportedAt = now.toISOString().slice(0, 10);
+
+    // A successful export is the closest thing to a backup the app
+    // performs today, so record it as the last backup timestamp. The
+    // System info card surfaces this value.
+    settings.set(getDb(), "last_backup_at", now.toISOString());
 
     log("info", "content exported", {
       event: "export.content",

src/app/api/settings/route.ts

@@ -13,6 +13,9 @@ import { toPublicSettings } from "@/lib/settings/public";
 
 const secretPatchValue = z.union([z.string(), z.null()]);
 
+// Keep in sync with `SettingsDraft` in `src/app/settings/types.ts` and
+// `DRAFT_KEYS` in `src/app/settings/dirty.ts` when adding or removing a
+// setting. `.strict()` rejects any key not listed here.
 const patchSchema = z
   .object({
     openrouter_api_key: secretPatchValue.optional(),
@@ -70,6 +73,10 @@ export async function PATCH(request: Request) {
       return errorResponse("VALIDATION_ERROR", "No settings to update", 400);
     }
 
+    // Defense-in-depth against schema drift: `patchSchema` is `.strict()`
+    // and only lists writable keys, so a parsed body can't currently carry
+    // an unknown or read-only key. These guards fail closed if someone later
+    // adds a read-only key (e.g. `last_backup_at`) to the schema by mistake.
     for (const [key] of entries) {
       if (!isSettingsKey(key)) {
         return errorResponse("VALIDATION_ERROR", "Invalid input", 400, {

src/app/api/settings/system-info/route.ts

@@ -7,7 +7,9 @@ import { log } from "@/lib/logger";
 function formatBytes(bytes: number): string {
   if (bytes < 1024) return `${bytes} B`;
   if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
-  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+  if (bytes < 1024 * 1024 * 1024)
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+  return `${(bytes / (1024 * 1024 * 1024)).toFixed(1)} GB`;
 }
 
 export async function GET(request: Request) {

src/app/settings/dirty.ts

@@ -1,5 +1,7 @@
 import type { SettingsDraft, SettingsSnapshot } from "./types";
 
+// Keep in sync with `SettingsDraft` in `./types.ts` and `patchSchema` in
+// `src/app/api/settings/route.ts` when adding or removing a setting.
 const DRAFT_KEYS: Array<keyof SettingsDraft> = [
   "openrouter_api_key",
   "ai_model",

src/app/settings/settings-page.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { useMemo, useState } from "react";
+import { useEffect, useMemo, useState } from "react";
 
 import { Button } from "@/components/ui/button";
 import { AiFeaturesSection } from "./ai-features-section";
@@ -34,6 +34,13 @@ export function SettingsPage() {
     return isSettingsDirty(saved, draft, clearedSecrets);
   }, [saved, draft, clearedSecrets]);
 
+  // Auto-dismiss the "Settings saved." confirmation so it doesn't linger.
+  useEffect(() => {
+    if (!saveMessage) return;
+    const timer = setTimeout(() => setSaveMessage(null), 4000);
+    return () => clearTimeout(timer);
+  }, [saveMessage]);
+
   async function handleSave() {
     if (!saved || !draft) return;
     setSaving(true);

src/app/settings/types.ts

@@ -1,5 +1,10 @@
 import type { PublicSettings } from "@/lib/settings/public";
 
+// The writable settings shape is mirrored in three places that must stay in
+// sync when a setting is added or removed:
+//   1. `SettingsDraft` below (the client draft shape),
+//   2. `DRAFT_KEYS` / `SECRET_KEYS` in `./dirty.ts` (dirty-tracking + patch),
+//   3. `patchSchema` in `src/app/api/settings/route.ts` (server validation).
 export type SettingsDraft = {
   openrouter_api_key: string;
   ai_model: string;

src/lib/settings/provider-connection.ts

@@ -1,6 +1,15 @@
 import type Database from "better-sqlite3";
 import { getSettingValue } from "@/lib/settings/public";
 
+// NOTE: SSRF policy exemption. The fetches below intentionally do NOT run
+// through `validateFetchUrl` (src/lib/ssrf.ts). The target base URLs are
+// admin-only chat-provider endpoints saved via the authenticated settings
+// route, and the defaults point at local services (e.g. Hermes at
+// `http://localhost:8642/v1`) that `validateFetchUrl` would block by design.
+// These are trusted, operator-configured destinations — not arbitrary
+// user-supplied URLs — so the private-range guard does not apply. See
+// AGENTS.md (SSRF Protection) for the carve-out.
+
 export type ChatProvider = "hermes" | "opencode-go";
 
 export type ProviderConnectionResult =