Vault browsing: fail-closed by kind + public-only hackathon mode

packages/app/docs/adr/0003-context-tree-top-panel.md

@@ -68,7 +68,10 @@ Entry points: a titlebar vault button (both titlebar variants), the command pale
 - Vault contents are proprietary knowledge, so browsing is a **local-researcher
   capability, not a server API**: the routes refuse on any non-loopback bind (same
   signal as the credential-mutation guard; `AMICO_VAULT_BROWSER=1` opts a shared
-  deployment in, `=0` forces off), and a mount can go fully dark with
-  `browse = false` in its `.amico-vault.toml` — the agent's read grants are unaffected.
+  deployment in, `=0` forces off, `=public` serves only public vaults — the
+  hackathon-box mode). Per-mount browsability is **fail-closed by kind** (Aaron
+  2026-07-27): personal and public browse by default; team/project/engagement —
+  and unknown kinds — ship dark until their marker says `browse = true`;
+  `browse = false` darkens any kind. The agent's read grants are unaffected.
 - Keyboard reachability of individual canvas nodes is an open follow-up; every action the
   canvas offers also exists via keyboard-reachable surfaces (file tree, Vault panel).

packages/opencode/src/server/amicode/vault-browser.ts

@@ -33,30 +33,63 @@ const err = (code: string, detail: string) => JSON.stringify({ ok: false, error:
  *  results); browsing is a LOCAL-researcher capability, not a server API. Same
  *  loopback family + bind signal as the credential-mutation guard
  *  (connections.ts) — a 0.0.0.0 / LAN-bound server refuses these routes even
- *  to authed callers, unless AMICO_VAULT_BROWSER=1 explicitly opts a shared
- *  deployment in (=0 forces off everywhere). */
+ *  to authed callers, unless AMICO_VAULT_BROWSER explicitly opts the
+ *  deployment in: =1 opens the deployment gate (per-mount rules still apply),
+ *  =0 forces off everywhere, =public serves ONLY kind="public" mounts
+ *  regardless of markers (the hackathon-box mode — Aaron 2026-07-27). */
 export function browseAllowed(env: Record<string, string | undefined> = process.env): boolean {
   const flag = env.AMICO_VAULT_BROWSER
-  if (flag === "1" || flag === "true") return true
+  if (flag === "1" || flag === "true" || flag === "public") return true
   if (flag === "0" || flag === "false") return false
   return isLoopbackHostname(getBindHostname())
 }
 
 const browseRefusal = () =>
   err("forbidden", "vault browsing serves loopback servers only (set AMICO_VAULT_BROWSER=1 to override)")
 
-/** A vault opts out of the browser entirely with `browse = false` in its
- *  .amico-vault.toml marker — the agent's read grants are unaffected, but the
- *  panel will not list or serve a byte of it. */
-export function browseOptedOut(dir: string): boolean {
+/** The mount's marker taxonomy: kind plus the explicit browse override. */
+export function mountMeta(dir: string): { kind: string; browse: boolean | undefined } {
   try {
-    return /^\s*browse\s*=\s*false\s*$/m.test(readFileSync(path.join(dir, ".amico-vault.toml"), "utf8"))
+    const text = readFileSync(path.join(dir, ".amico-vault.toml"), "utf8")
+    const kind = text.match(/^\s*kind\s*=\s*"([^"]*)"/m)?.[1] ?? ""
+    const browse = /^\s*browse\s*=\s*false\s*$/m.test(text)
+      ? false
+      : /^\s*browse\s*=\s*true\s*$/m.test(text)
+        ? true
+        : undefined
+    return { kind, browse }
   } catch {
-    return false
+    return { kind: "", browse: undefined }
   }
 }
 
-const optOutRefusal = (mountId: string) => err("forbidden", `vault "${mountId}" opts out of browsing (browse = false)`)
+/** Browsability is FAIL-CLOSED BY KIND (Aaron 2026-07-27): the marker already
+ *  carries the taxonomy, so team/project/engagement/restricted — and anything
+ *  with an unknown kind — ship dark by default; `browse = true` is the
+ *  deliberate opt-in. Personal stays browsable (it is the operator's own
+ *  machine) and public is browsable by definition. `browse = false` darkens
+ *  any kind. Under AMICO_VAULT_BROWSER=public, ONLY public mounts serve,
+ *  markers ignored. Returns a refusal body, or undefined when browsable.
+ *  The agent's read grants are unaffected either way. */
+export function mountBrowseRefusal(
+  mountId: string,
+  dir: string,
+  env: Record<string, string | undefined> = process.env,
+): string | undefined {
+  const meta = mountMeta(dir)
+  if (env.AMICO_VAULT_BROWSER === "public") {
+    if (meta.kind !== "public")
+      return err("forbidden", `vault "${mountId}" is not public — this deployment serves public vaults only`)
+    return undefined
+  }
+  if (meta.browse === false) return err("forbidden", `vault "${mountId}" opts out of browsing (browse = false)`)
+  if (meta.browse === true) return undefined
+  if (meta.kind === "personal" || meta.kind === "public") return undefined
+  return err(
+    "forbidden",
+    `vault "${mountId}" is kind "${meta.kind || "unknown"}" — browsing is opt-in for shared vaults (browse = true in its marker)`,
+  )
+}
 
 export function isTextFile(name: string): boolean {
   const ext = path.extname(name).toLowerCase()
@@ -102,7 +135,8 @@ export function vaultFilesBody(mountId: string | undefined, root: string = vault
   if (!mountId) return err("bad_request", "mount is required")
   const dir = mountDir(mountId, root)
   if (!dir) return err("not_found", `no attached vault named "${mountId}"`)
-  if (browseOptedOut(dir)) return optOutRefusal(mountId)
+  const refusal = mountBrowseRefusal(mountId, dir)
+  if (refusal) return refusal
   let realRoot: string
   try {
     realRoot = realpathSync(dir)
@@ -164,7 +198,8 @@ export function vaultFileBody(mountId: string | undefined, relPath: string | und
   if (!relPath) return err("bad_request", "path is required")
   const dir = mountDir(mountId, root)
   if (!dir) return err("not_found", `no attached vault named "${mountId}"`)
-  if (browseOptedOut(dir)) return optOutRefusal(mountId)
+  const refusal = mountBrowseRefusal(mountId, dir)
+  if (refusal) return refusal
   let realRoot: string
   let realTarget: string
   try {

packages/opencode/test/server/amicode-vault-browser.test.ts

@@ -2,7 +2,7 @@ import { afterEach, describe, expect, test } from "bun:test"
 import { mkdirSync, mkdtempSync, symlinkSync, writeFileSync } from "node:fs"
 import { tmpdir } from "node:os"
 import path from "node:path"
-import { browseAllowed, browseOptedOut, isTextFile, mountDir, vaultFileBody, vaultFilesBody } from "@/server/amicode/vault-browser"
+import { browseAllowed, mountBrowseRefusal, mountMeta, isTextFile, mountDir, vaultFileBody, vaultFilesBody } from "@/server/amicode/vault-browser"
 import { setBindHostname } from "@/server/amicode/connections"
 
 // The suite runs with no listener bound (bindHostname undefined = in-process,
@@ -50,13 +50,48 @@ describe("browse gates (proprietary vaults never serve off-box)", () => {
   })
   test("browse = false in the marker darkens the mount for listing AND reads", () => {
     const { root, mount } = fixtureRoot()
-    writeFileSync(path.join(mount, ".amico-vault.toml"), 'kind = "team"\nname = "armonia-test"\nbrowse = false\n')
-    expect(browseOptedOut(mount)).toBe(true)
+    writeFileSync(path.join(mount, ".amico-vault.toml"), 'kind = "personal"\nname = "armonia-test"\nbrowse = false\n')
+    expect(mountMeta(mount).browse).toBe(false)
     expect(JSON.parse(vaultFilesBody("armonia-test", root)).error).toMatch(/^forbidden: vault "armonia-test" opts out/)
     expect(JSON.parse(vaultFileBody("armonia-test", "STRATEGY.md", root)).error).toMatch(/^forbidden:/)
   })
 })
 
+describe("fail-closed by kind (Aaron 2026-07-27): shared vaults ship dark", () => {
+  const marker = (mount: string, body: string) => writeFileSync(path.join(mount, ".amico-vault.toml"), body)
+  test("team/project/engagement/unknown kinds refuse by default; browse = true is the opt-in", () => {
+    const { root, mount } = fixtureRoot()
+    for (const kind of ["team", "project", "engagement", "restricted", ""]) {
+      marker(mount, `kind = "${kind}"\nname = "armonia-test"\n`)
+      const out = JSON.parse(vaultFilesBody("armonia-test", root))
+      expect(out.ok).toBe(false)
+      expect(out.error).toMatch(/browsing is opt-in for shared vaults/)
+    }
+    marker(mount, 'kind = "team"\nname = "armonia-test"\nbrowse = true\n')
+    expect(JSON.parse(vaultFilesBody("armonia-test", root)).ok).toBe(true)
+  })
+  test("personal and public stay browsable by default", () => {
+    const { root, mount } = fixtureRoot()
+    for (const kind of ["personal", "public"]) {
+      marker(mount, `kind = "${kind}"\nname = "armonia-test"\n`)
+      expect(JSON.parse(vaultFilesBody("armonia-test", root)).ok).toBe(true)
+    }
+  })
+  test("AMICO_VAULT_BROWSER=public serves ONLY public mounts, markers ignored (hackathon boxes)", () => {
+    const { mount } = fixtureRoot()
+    const env = { AMICO_VAULT_BROWSER: "public" }
+    marker(mount, 'kind = "team"\nname = "armonia-test"\nbrowse = true\n')
+    expect(mountBrowseRefusal("armonia-test", mount, env)).toMatch(/serves public vaults only/)
+    marker(mount, 'kind = "personal"\nname = "armonia-test"\n')
+    expect(mountBrowseRefusal("armonia-test", mount, env)).toMatch(/serves public vaults only/)
+    marker(mount, 'kind = "public"\nname = "armonia-test"\n')
+    expect(mountBrowseRefusal("armonia-test", mount, env)).toBeUndefined()
+    // and =public also opens the deployment gate (the boxes are exposed binds)
+    setBindHostname("0.0.0.0")
+    expect(browseAllowed(env)).toBe(true)
+  })
+})
+
 describe("isTextFile", () => {
   test("markdown and source are text; binaries are not", () => {
     expect(isTextFile("note.md")).toBe(true)