@openparachute/vault 0.2.4 → 0.3.0-rc.1

package/src/oauth.ts

@@ -4,10 +4,10 @@
  * Implements the subset of OAuth 2.1 needed for MCP clients (Claude Web,
  * Claude Desktop, etc.) to connect via the standard browser-based flow:
  *
- *   1. Dynamic Client Registration (RFC 7591)  — POST /oauth/register
- *   2. Authorization endpoint (PKCE required)   — GET/POST /oauth/authorize
- *   3. Token endpoint (code exchange)           — POST /oauth/token
- *   4. Discovery endpoints                      — GET /.well-known/*
+ *   1. Dynamic Client Registration (RFC 7591)  — POST /vault/<name>/oauth/register
+ *   2. Authorization endpoint (PKCE required)   — GET/POST /vault/<name>/oauth/authorize
+ *   3. Token endpoint (code exchange)           — POST /vault/<name>/oauth/token
+ *   4. Discovery endpoints                      — GET /vault/<name>/.well-known/*
  *
  * The flow produces a standard `pvt_` token stored in the vault's tokens table.
  * After the OAuth handshake, all requests use the same Bearer token auth path.
@@ -19,6 +19,8 @@ import { generateToken, createToken, resolveToken } from "./token-store.ts";
 import type { TokenPermission } from "./token-store.ts";
 import { verifyOwnerPassword, authorizeRateLimit, type RateLimiter } from "./owner-auth.ts";
 import { verifyTotpCode, verifyAndConsumeBackupCode } from "./two-factor.ts";
+import { readManifest, ServicesManifestError } from "./services-manifest.ts";
+import { legacyPermissionToScopes, SCOPE_READ, serializeScopes } from "./scopes.ts";
 
 /** Options for handleAuthorizePost. */
 export interface AuthorizePostOptions {
@@ -63,6 +65,96 @@ export function getBaseUrl(req: Request): string {
   return url.origin;
 }
 
+/**
+ * Public origin the client reached vault through. When `PARACHUTE_HUB_ORIGIN`
+ * is set AND matches the incoming request's base URL, returns the hub; else
+ * returns the request base. This is the RFC 8414 compliance hinge: discovery
+ * metadata's `issuer`, token `iss` claims, and the service catalog all stem
+ * from this, so the issuer view is always self-consistent with the origin the
+ * client is actually talking to.
+ */
+function resolvePublicOrigin(req: Request): string {
+  const hub = process.env.PARACHUTE_HUB_ORIGIN?.replace(/\/$/, "");
+  const base = getBaseUrl(req);
+  return hub && base === hub ? hub : base;
+}
+
+/**
+ * OAuth endpoint coordinates. Hub-rooted when the request came in through the
+ * hub origin (`PARACHUTE_HUB_ORIGIN` set AND matches the incoming base URL),
+ * vault-path-rooted otherwise. The same vault exposes both views concurrently:
+ * a loopback client gets `issuer = http://127.0.0.1:<port>/vault/<name>`; a
+ * client reaching vault via the hub reverse proxy gets `issuer = <hub>`.
+ *
+ * This is how vault stays RFC 8414 compliant while a single process serves
+ * both origins — discovery always returns the issuer matching the client's
+ * origin.
+ */
+export function resolveOAuthCoordinates(
+  req: Request,
+  vaultName: string,
+): {
+  issuer: string;
+  authorizationEndpoint: string;
+  tokenEndpoint: string;
+  registrationEndpoint: string;
+} {
+  const origin = resolvePublicOrigin(req);
+  const hub = process.env.PARACHUTE_HUB_ORIGIN?.replace(/\/$/, "");
+  if (hub && origin === hub) {
+    return {
+      issuer: hub,
+      authorizationEndpoint: `${hub}/oauth/authorize`,
+      tokenEndpoint: `${hub}/oauth/token`,
+      registrationEndpoint: `${hub}/oauth/register`,
+    };
+  }
+  const prefix = `/vault/${vaultName}`;
+  return {
+    issuer: `${origin}${prefix}`,
+    authorizationEndpoint: `${origin}${prefix}/oauth/authorize`,
+    tokenEndpoint: `${origin}${prefix}/oauth/token`,
+    registrationEndpoint: `${origin}${prefix}/oauth/register`,
+  };
+}
+
+/**
+ * Ecosystem service catalog for the token response (Phase 1 of the
+ * hub-as-OAuth-issuer design). Reads `~/.parachute/services.json` — the same
+ * manifest the CLI maintains — and rewrites each entry's canonical path into
+ * an absolute URL rooted at the origin the client reached vault through. A
+ * client that came in via the hub gets hub-rooted URLs; a loopback client
+ * gets loopback URLs. Same vault, same manifest, origin-consistent.
+ *
+ * Failure to read the manifest is non-fatal: we log and return an empty
+ * catalog rather than refusing to issue the token. The token response shape
+ * is additive — clients that don't expect `services` ignore it.
+ */
+export function buildServiceCatalog(
+  req: Request,
+): Record<string, { url: string; version: string }> {
+  let entries: ReturnType<typeof readManifest>["services"];
+  try {
+    entries = readManifest().services;
+  } catch (err) {
+    if (err instanceof ServicesManifestError) {
+      console.warn(`[parachute-vault] services.json unreadable: ${err.message}`);
+      return {};
+    }
+    throw err;
+  }
+  const origin = resolvePublicOrigin(req);
+  const catalog: Record<string, { url: string; version: string }> = {};
+  for (const entry of entries) {
+    const path = entry.paths[0] ?? "/";
+    catalog[entry.name] = {
+      url: `${origin}${path}`,
+      version: entry.version,
+    };
+  }
+  return catalog;
+}
+
 function escapeHtml(s: string): string {
   return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
 }
@@ -74,49 +166,61 @@ function escapeHtml(s: string): string {
 /**
  * OAuth 2.0 Protected Resource Metadata (RFC 9728).
  *
- * @param mcpPath       — the resource URL (e.g. `/mcp` or `/vaults/X/mcp`).
- * @param authServerPrefix — path prefix for the authorization server issuer
- *                           (e.g. `""` for global, `/vaults/X` for scoped).
- *                           The client discovers the AS metadata at
- *                           `{base}{prefix}/.well-known/oauth-authorization-server`.
+ * @param vaultName — the vault whose MCP endpoint is the protected resource.
+ *                    The metadata advertises `resource: {base}/vault/{name}/mcp`
+ *                    and the vault's authorization server at
+ *                    `{base}/vault/{name}`. Clients discover the AS metadata
+ *                    at `{base}/vault/{name}/.well-known/oauth-authorization-server`.
  */
-export function handleProtectedResource(
-  req: Request,
-  mcpPath = "/mcp",
-  authServerPrefix = "",
-): Response {
+export function handleProtectedResource(req: Request, vaultName: string): Response {
+  const { issuer } = resolveOAuthCoordinates(req, vaultName);
   const base = getBaseUrl(req);
+  const prefix = `/vault/${vaultName}`;
   return Response.json({
-    resource: `${base}${mcpPath}`,
-    authorization_servers: [`${base}${authServerPrefix}`],
-    scopes_supported: ["full", "read"],
+    resource: `${base}${prefix}/mcp`,
+    // `authorization_servers` points clients at the AS metadata doc. When the
+    // hub is the issuer (Phase 0), the AS metadata still lives on the vault
+    // itself — it's the document that tells clients where the hub endpoints
+    // are. So we use the issuer as the AS locator when set, otherwise the
+    // vault origin.
+    authorization_servers: [issuer],
+    scopes_supported: SCOPES_SUPPORTED,
     bearer_methods_supported: ["header"],
   });
 }
 
 /**
- * OAuth 2.0 Authorization Server Metadata (RFC 8414).
- *
- * @param vaultName — when provided, returns vault-scoped endpoints
- *                    (`/vaults/<name>/oauth/*`) and issuer. Tokens minted
- *                    via these endpoints are scoped to the named vault's DB.
+ * OAuth 2.0 Authorization Server Metadata (RFC 8414). Endpoint URLs and
+ * `issuer` honor `PARACHUTE_HUB_ORIGIN` when set — see
+ * `resolveOAuthCoordinates` for the hub-vs-standalone contract.
  */
-export function handleAuthorizationServer(req: Request, vaultName?: string): Response {
-  const base = getBaseUrl(req);
-  const prefix = vaultName ? `/vaults/${vaultName}` : "";
+export function handleAuthorizationServer(req: Request, vaultName: string): Response {
+  const coord = resolveOAuthCoordinates(req, vaultName);
   return Response.json({
-    issuer: `${base}${prefix}`,
-    authorization_endpoint: `${base}${prefix}/oauth/authorize`,
-    token_endpoint: `${base}${prefix}/oauth/token`,
-    registration_endpoint: `${base}${prefix}/oauth/register`,
+    issuer: coord.issuer,
+    authorization_endpoint: coord.authorizationEndpoint,
+    token_endpoint: coord.tokenEndpoint,
+    registration_endpoint: coord.registrationEndpoint,
     response_types_supported: ["code"],
     code_challenge_methods_supported: ["S256"],
     grant_types_supported: ["authorization_code"],
     token_endpoint_auth_methods_supported: ["none"],
-    scopes_supported: ["full", "read"],
+    scopes_supported: SCOPES_SUPPORTED,
   });
 }
 
+/**
+ * Scopes published in OAuth discovery. Phase 2 enforces these at request time
+ * (`vault:admin` ⊇ `vault:write` ⊇ `vault:read`). `vault:<name>:*` refinements
+ * are documented as future shape; the scope parser accepts them as synonyms
+ * for `vault:*` today.
+ *
+ * Legacy `full`/`read` remain in the list for back-compat with 0.2.x clients
+ * that hardcoded those names — they're translated into `vault:*` scopes on the
+ * way in and out.
+ */
+const SCOPES_SUPPORTED = ["vault:read", "vault:write", "vault:admin", "full", "read"];
+
 // ---------------------------------------------------------------------------
 // Dynamic Client Registration (RFC 7591)
 // ---------------------------------------------------------------------------
@@ -486,8 +590,8 @@ export async function handleToken(
   }
 
   // Validate the code was issued for the same vault this token endpoint
-  // serves. Without this, a code issued under /vaults/A/oauth/authorize
-  // could be presented to /vaults/B/oauth/token and the token would be
+  // serves. Without this, a code issued under /vault/A/oauth/authorize
+  // could be presented to /vault/B/oauth/token and the token would be
   // minted into B's DB — privilege escalation across vault boundaries.
   if (authCode.vault_name !== vaultName) {
     return Response.json({ error: "invalid_grant", error_description: "vault mismatch" }, { status: 400 });
@@ -506,19 +610,35 @@ export async function handleToken(
   // Mark code as used
   db.prepare("UPDATE oauth_codes SET used = 1 WHERE code = ?").run(code);
 
-  // Create a real pvt_ token
+  // Translate the consent-time selected scope into both the legacy permission
+  // column and the OAuth-standard scope list we now persist on the token row.
+  // The consent page only offers read vs full today; full becomes the
+  // admin-inheriting scope set so hub admin operations keep working.
   const permission: TokenPermission = authCode.scope === "read" ? "read" : "full";
+  const scopes = legacyPermissionToScopes(permission);
+  const scopeString = serializeScopes(scopes);
+
   const { fullToken } = generateToken();
   createToken(db, fullToken, {
     label: `oauth:${clientId.slice(0, 8)}`,
     permission,
+    scopes,
   });
 
+  const { issuer } = resolveOAuthCoordinates(req, vaultName);
   return Response.json({
     access_token: fullToken,
     token_type: "bearer",
-    scope: permission,
+    // RFC 6749 §5.1: scope is an OAuth-standard whitespace-separated string.
+    scope: scopeString,
     vault: vaultName,
+    // Phase 0: identify the issuer so tokens validated by downstream services
+    // can pin trust on the hub-origin URL, not vault's internal address.
+    iss: issuer,
+    // Phase 1: bundle the ecosystem service catalog so Notes/clients learn
+    // all sibling service URLs from the token response and don't need to
+    // prompt the user for each one. Additive field — older clients ignore.
+    services: buildServiceCatalog(req),
   });
 }
 
@@ -708,7 +828,7 @@ function renderConsentPage(p: ConsentParams): string {
 <div class="card">
   <h1>Authorize access</h1>
   <p><span class="client">${escapeHtml(p.clientName)}</span> wants to access your <strong>${escapeHtml(p.vaultName)}</strong> vault.</p>
-  <form method="POST" action="/oauth/authorize">
+  <form method="POST" action="">
     <input type="hidden" name="client_id" value="${escapeHtml(p.clientId)}">
     <input type="hidden" name="redirect_uri" value="${escapeHtml(p.redirectUri)}">
     <input type="hidden" name="code_challenge" value="${escapeHtml(p.codeChallenge)}">

package/src/published.test.ts

@@ -25,8 +25,8 @@ describe("/public → /view redirect", () => {
   });
 
   it("works for vault-scoped paths", () => {
-    const url = buildRedirectUrl("http://localhost:1940/vaults/work/public/abc?key=pvk_x", "abc", "/vaults/work");
-    expect(url).toBe("http://localhost:1940/vaults/work/view/abc?key=pvk_x");
+    const url = buildRedirectUrl("http://localhost:1940/vault/work/public/abc?key=pvk_x", "abc", "/vault/work");
+    expect(url).toBe("http://localhost:1940/vault/work/view/abc?key=pvk_x");
   });
 });
 

package/src/routes.ts

@@ -24,7 +24,7 @@ import {
   type ExpandMode,
 } from "../core/src/expand.ts";
 import { join, extname, normalize } from "path";
-import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "fs";
+import { existsSync, mkdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from "fs";
 import { vaultDir } from "./config.ts";
 
 // ---------------------------------------------------------------------------
@@ -40,6 +40,13 @@ function parseBool(val: string | null, defaultVal: boolean): boolean {
   return val === "true" || val === "1";
 }
 
+function parseBoolOrUndef(val: string | null): boolean | undefined {
+  if (val === null) return undefined;
+  if (val === "true" || val === "1") return true;
+  if (val === "false" || val === "0") return false;
+  return undefined;
+}
+
 function parseQuery(url: URL, key: string): string | null {
   return url.searchParams.get(key);
 }
@@ -124,6 +131,7 @@ export async function handleNotes(
   req: Request,
   store: Store,
   subpath: string,
+  vault?: string,
 ): Promise<Response> {
   const url = new URL(req.url);
   const method = req.method;
@@ -182,19 +190,33 @@ export async function handleNotes(
 
       // Structured query
       const tags = parseQueryList(url, "tag");
-      let results: Note[] = await store.queryNotes({
-        tags,
-        tagMatch: (parseQuery(url, "tag_match") as "all" | "any") ?? (tags && tags.length > 1 ? "any" : undefined),
-        excludeTags: parseQueryList(url, "exclude_tag"),
-        path: parseQuery(url, "path") ?? undefined,
-        pathPrefix: parseQuery(url, "path_prefix") ?? undefined,
-        metadata: undefined, // metadata filter not practical in query params
-        dateFrom: parseQuery(url, "date_from") ?? undefined,
-        dateTo: parseQuery(url, "date_to") ?? undefined,
-        sort: (parseQuery(url, "sort") as "asc" | "desc") ?? undefined,
-        limit: parseInt10(parseQuery(url, "limit")) ?? 50,
-        offset: parseInt10(parseQuery(url, "offset")),
-      });
+      let results: Note[];
+      try {
+        results = await store.queryNotes({
+          tags,
+          tagMatch: (parseQuery(url, "tag_match") as "all" | "any") ?? (tags && tags.length > 1 ? "any" : undefined),
+          excludeTags: parseQueryList(url, "exclude_tag"),
+          hasTags: parseBoolOrUndef(parseQuery(url, "has_tags")),
+          hasLinks: parseBoolOrUndef(parseQuery(url, "has_links")),
+          path: parseQuery(url, "path") ?? undefined,
+          pathPrefix: parseQuery(url, "path_prefix") ?? undefined,
+          metadata: undefined, // metadata filter not practical in query params
+          dateFrom: parseQuery(url, "date_from") ?? undefined,
+          dateTo: parseQuery(url, "date_to") ?? undefined,
+          sort: (parseQuery(url, "sort") as "asc" | "desc") ?? undefined,
+          orderBy: parseQuery(url, "order_by") ?? undefined,
+          limit: parseInt10(parseQuery(url, "limit")) ?? 50,
+          offset: parseInt10(parseQuery(url, "offset")),
+        });
+      } catch (e: any) {
+        // QueryError (non-indexed order_by, unknown operator, ...) surfaces
+        // here. Duck-type on `name` + `code` — core is a separate module, so
+        // `instanceof` is fragile across bundling boundaries.
+        if (e && e.name === "QueryError") {
+          return json({ error: e.message, code: e.code ?? "INVALID_QUERY" }, 400);
+        }
+        throw e;
+      }
 
       // Near-scope filter (graph neighborhood)
       const nearNoteId = parseQuery(url, "near[note_id]");
@@ -309,9 +331,32 @@ export async function handleNotes(
     if (method === "POST") {
       const note = await resolveNote(store, idOrPath);
       if (!note) return json({ error: "Not found" }, 404);
-      const body = await req.json() as { path: string; mimeType: string };
+      const body = await req.json() as { path: string; mimeType: string; transcribe?: boolean };
       if (!body.path || !body.mimeType) return json({ error: "path and mimeType are required" }, 400);
-      return json(await store.addAttachment(note.id, body.path, body.mimeType), 201);
+
+      // `transcribe: true` asks the transcription worker to read this audio
+      // file and replace the note's content with the transcript. The caller
+      // is declaring "overwrite my current content when the transcript lands"
+      // — we persist that as `transcribe_stub: true` on the note so a later
+      // user edit (which clears the marker) can opt out before the worker
+      // runs.
+      const attMeta = body.transcribe
+        ? { transcribe_status: "pending" as const, transcribe_requested_at: new Date().toISOString() }
+        : undefined;
+
+      const attachment = await store.addAttachment(note.id, body.path, body.mimeType, attMeta);
+
+      if (body.transcribe) {
+        const noteMeta = (note.metadata as Record<string, unknown> | undefined) ?? {};
+        if (noteMeta.transcribe_stub !== true) {
+          await store.updateNote(note.id, {
+            metadata: { ...noteMeta, transcribe_stub: true },
+            skipUpdatedAt: true,
+          });
+        }
+      }
+
+      return json(attachment, 201);
     }
     if (method === "GET") {
       const note = await resolveNote(store, idOrPath);
@@ -321,6 +366,29 @@ export async function handleNotes(
     return json({ error: "Method not allowed" }, 405);
   }
 
+  const attMatch = sub.match(/^\/attachments\/([^/]+)$/);
+  if (attMatch) {
+    const attId = decodeURIComponent(attMatch[1]!);
+    if (method === "DELETE") {
+      const note = await resolveNote(store, idOrPath);
+      if (!note) return json({ error: "Not found" }, 404);
+      const result = await store.deleteAttachment(note.id, attId);
+      if (!result.deleted) return json({ error: "Not found" }, 404);
+      // Unlink the storage file only if no other attachment still references
+      // the same path. Best-effort: the row is already gone, so a missing
+      // file or unlink error should not flip the DELETE to an error.
+      if (vault && result.path && result.orphaned) {
+        const assets = assetsDir(vault);
+        const filePath = normalize(join(assets, result.path));
+        if (filePath.startsWith(normalize(assets)) && existsSync(filePath)) {
+          try { unlinkSync(filePath); } catch {}
+        }
+      }
+      return new Response(null, { status: 204 });
+    }
+    return json({ error: "Method not allowed" }, 405);
+  }
+
   if (sub !== "") return json({ error: "Not found" }, 404);
 
   // GET /notes/:idOrPath — single note
@@ -351,6 +419,24 @@ export async function handleNotes(
       if (!note) throw new NotFoundError(`Note not found: "${idOrPath}"`);
       const body = await req.json() as any;
 
+      // --- Safety-by-default: refuse mutations without a precondition ---
+      // Mirror the MCP tool: require `if_updated_at` unless the caller
+      // explicitly sets `force: true`. 428 Precondition Required is the
+      // RFC 6585 status for exactly this case.
+      if (body.if_updated_at === undefined && body.force !== true) {
+        return json(
+          {
+            error_type: "precondition_required",
+            error: "precondition_required",
+            message:
+              "update requires `if_updated_at` (the note's last-seen updated_at) or `force: true`.",
+            note_id: note.id,
+            path: note.path ?? null,
+          },
+          428,
+        );
+      }
+
       // --- Plan bracket cleanup for wikilink removals (no DB writes yet) ---
       // The actual link deletions happen only after the core UPDATE succeeds,
       // so a conflict leaves the note untouched.
@@ -420,10 +506,16 @@ export async function handleNotes(
       if (e && e.code === "CONFLICT") {
         return json(
           {
-            error: "conflict",
-            message: e.message,
-            note_id: e.note_id,
+            // New structured shape — what agents should key on.
+            error_type: "conflict",
             current_updated_at: e.current_updated_at ?? null,
+            your_updated_at: e.expected_updated_at,
+            path: e.note_path ?? null,
+            note_id: e.note_id,
+            message: e.message,
+            // Legacy fields — kept for the lens VaultConflictError shim and
+            // any other pre-launch callers. Safe to drop post-launch.
+            error: "conflict",
             expected_updated_at: e.expected_updated_at,
           },
           409,
@@ -445,7 +537,8 @@ export async function handleNotes(
 }
 
 // ---------------------------------------------------------------------------
-// Tags — GET/PUT/DELETE /api/tags[/:name]
+// Tags — GET/PUT/DELETE /api/tags[/:name], POST /api/tags/merge,
+//        POST /api/tags/:name/rename
 // ---------------------------------------------------------------------------
 
 export async function handleTags(req: Request, store: Store, subpath = ""): Promise<Response> {
@@ -479,6 +572,54 @@ export async function handleTags(req: Request, store: Store, subpath = ""): Prom
     return json(tags);
   }
 
+  // POST /tags/merge — atomic multi-source merge into a target tag.
+  // Must come before the /:name matcher so "merge" isn't read as a tag name.
+  if (subpath === "/merge") {
+    if (req.method !== "POST") return json({ error: "Method not allowed" }, 405);
+    const body = (await req.json().catch(() => null)) as
+      | { sources?: unknown; target?: unknown }
+      | null;
+    if (!body) return json({ error: "Invalid JSON body" }, 400);
+    const sources = body.sources;
+    const target = body.target;
+    if (!Array.isArray(sources) || !sources.every((s) => typeof s === "string" && s.length > 0)) {
+      return json({ error: "sources must be a non-empty array of strings" }, 400);
+    }
+    if (typeof target !== "string" || target.length === 0) {
+      return json({ error: "target must be a non-empty string" }, 400);
+    }
+    const result = await store.mergeTags(sources, target);
+    return json(result);
+  }
+
+  // POST /tags/:name/rename — atomic rename across tags + note_tags + schema
+  const renameMatch = subpath.match(/^\/([^/]+)\/rename$/);
+  if (renameMatch) {
+    if (req.method !== "POST") return json({ error: "Method not allowed" }, 405);
+    const oldName = decodeURIComponent(renameMatch[1]);
+    const body = (await req.json().catch(() => null)) as { new_name?: unknown } | null;
+    if (!body) return json({ error: "Invalid JSON body" }, 400);
+    const newName = body.new_name;
+    if (typeof newName !== "string" || newName.length === 0) {
+      return json({ error: "new_name must be a non-empty string" }, 400);
+    }
+    const result = await store.renameTag(oldName, newName);
+    if ("error" in result) {
+      if (result.error === "not_found") return json({ error: "not_found", tag: oldName }, 404);
+      if (result.error === "target_exists") {
+        return json(
+          {
+            error: "target_exists",
+            target: newName,
+            message: "Target tag already exists; use POST /api/tags/merge to combine them.",
+          },
+          409,
+        );
+      }
+    }
+    return json(result);
+  }
+
   // Routes with tag name
   const nameMatch = subpath.match(/^\/([^/]+)$/);
   if (!nameMatch) return json({ error: "Not found" }, 404);
@@ -550,19 +691,34 @@ export async function handleFindPath(req: Request, store: Store): Promise<Respon
 // Vault info — GET/PATCH /api/vault
 // ---------------------------------------------------------------------------
 
+type VaultConfigLike = {
+  name: string;
+  description?: string;
+  audio_retention?: "keep" | "until_transcribed" | "never";
+};
+
+const VALID_AUDIO_RETENTION = ["keep", "until_transcribed", "never"] as const;
+
+function vaultResponse(vaultConfig: VaultConfigLike): Record<string, unknown> {
+  return {
+    name: vaultConfig.name,
+    description: vaultConfig.description ?? null,
+    config: {
+      audio_retention: vaultConfig.audio_retention ?? "keep",
+    },
+  };
+}
+
 export async function handleVault(
   req: Request,
   store: Store,
-  vaultConfig: { name: string; description?: string },
-  updateDescription?: (description: string) => void,
+  vaultConfig: VaultConfigLike,
+  persist?: () => void,
 ): Promise<Response> {
   const url = new URL(req.url);
 
   if (req.method === "GET") {
-    const result: any = {
-      name: vaultConfig.name,
-      description: vaultConfig.description ?? null,
-    };
+    const result: Record<string, unknown> = vaultResponse(vaultConfig);
     if (parseBool(parseQuery(url, "include_stats"), false)) {
       result.stats = await store.getVaultStats();
     }
@@ -570,14 +726,34 @@ export async function handleVault(
   }
 
   if (req.method === "PATCH") {
-    const body = await req.json() as { description?: string };
-    if (body.description !== undefined && updateDescription) {
-      updateDescription(body.description);
+    const body = await req.json() as {
+      description?: string;
+      config?: { audio_retention?: string };
+    };
+    let dirty = false;
+
+    if (body.description !== undefined) {
+      vaultConfig.description = body.description;
+      dirty = true;
     }
-    return json({
-      name: vaultConfig.name,
-      description: body.description ?? vaultConfig.description ?? null,
-    });
+
+    if (body.config?.audio_retention !== undefined) {
+      const v = body.config.audio_retention;
+      if (!VALID_AUDIO_RETENTION.includes(v as typeof VALID_AUDIO_RETENTION[number])) {
+        return json(
+          {
+            error: "invalid_audio_retention",
+            message: `audio_retention must be one of: ${VALID_AUDIO_RETENTION.join(", ")}`,
+          },
+          400,
+        );
+      }
+      vaultConfig.audio_retention = v as typeof VALID_AUDIO_RETENTION[number];
+      dirty = true;
+    }
+
+    if (dirty && persist) persist();
+    return json(vaultResponse(vaultConfig));
   }
 
   return json({ error: "Method not allowed" }, 405);