@openparachute/vault 0.7.3-rc.5 → 0.7.3-rc.7

package/src/attachment-tickets.ts

@@ -0,0 +1,264 @@
+/**
+ * Attachment tickets — bun's runtime-lane implementation (Wave 1).
+ *
+ * `InProcessAttachmentTicketProvider` is the process-wide (not per-vault)
+ * ticket store — a plain `Map` keyed by the 256-bit ticket id, which is
+ * already globally unguessable, so there's no need to shard by vault. A
+ * daemon restart drops every outstanding ticket: acceptable given the
+ * ≤30-minute TTL (a caller mid-upload across a restart just re-mints), and
+ * simpler than persisting single-use, short-lived state to disk. Cloud's
+ * future mirror persists to the vault's Durable Object instead — see
+ * `AttachmentTicketProvider`'s doc comment (`core/src/attachment/tickets.ts`).
+ *
+ * `handleTicketSpend` is the bare (no auth beyond the ticket itself) HTTP
+ * handler `src/routing.ts` dispatches to for `/vault/<name>/tickets/<id>`
+ * — BEFORE `authenticateVaultRequest` runs, deliberately: the ticket IS
+ * the credential, and a bearer-less shell (curl) must be able to spend it.
+ */
+
+import { mkdirSync, writeFileSync, existsSync, readFileSync, statSync } from "fs";
+import { join, normalize } from "path";
+import type { Store } from "../core/src/types.ts";
+import type { AttachmentTicket, AttachmentTicketProvider } from "../core/src/attachment/tickets.ts";
+import { sanitizeAttachmentExtension } from "../core/src/attachment/policy.ts";
+import { assetsDir, readVaultConfig } from "./config.ts";
+import { shouldAutoTranscribe } from "./auto-transcribe.ts";
+import { invalidateUsageCache } from "./usage.ts";
+
+function json(data: unknown, status = 200): Response {
+  return Response.json(data, { status });
+}
+
+/**
+ * Process-wide, in-memory ticket store (see module doc comment for the
+ * restart-drops-tickets tradeoff). `take` deletes unconditionally on
+ * lookup — single-use is enforced by the delete itself, not by a separate
+ * expiry check; `takeValidTicket` below still checks `expiresAt` after
+ * `take` returns, collapsing "expired" into the same null as "spent" /
+ * "unknown" so the HTTP layer can give a uniform 404 (no oracle).
+ */
+class InProcessAttachmentTicketProvider implements AttachmentTicketProvider {
+  private readonly tickets = new Map<string, AttachmentTicket>();
+
+  async put(ticket: AttachmentTicket): Promise<void> {
+    this.tickets.set(ticket.id, ticket);
+  }
+
+  async take(id: string): Promise<AttachmentTicket | null> {
+    const ticket = this.tickets.get(id);
+    if (!ticket) return null;
+    this.tickets.delete(id);
+    return ticket;
+  }
+}
+
+let sharedProvider: InProcessAttachmentTicketProvider | undefined;
+
+/** The one shared ticket provider for this process (see class doc comment above). */
+export function getSharedAttachmentTicketProvider(): AttachmentTicketProvider {
+  if (!sharedProvider) sharedProvider = new InProcessAttachmentTicketProvider();
+  return sharedProvider;
+}
+
+/** Test-only: force a fresh provider so ticket state doesn't leak between test files. */
+export function resetSharedAttachmentTicketProviderForTests(): void {
+  sharedProvider = undefined;
+}
+
+/**
+ * Take + validate a ticket against the URL's vault name and the spend
+ * route's expected kind (a GET must not spend an upload ticket, etc.).
+ * Collapses spent / expired / unknown / wrong-vault / wrong-kind into the
+ * SAME `null` — the uniform-404 no-oracle posture the design calls for
+ * (an adversary probing an unguessable URL learns nothing about WHY it
+ * failed).
+ */
+async function takeValidTicket(
+  provider: AttachmentTicketProvider,
+  id: string,
+  vaultName: string,
+  kind: AttachmentTicket["kind"],
+): Promise<AttachmentTicket | null> {
+  const ticket = await provider.take(id);
+  if (!ticket) return null;
+  if (ticket.kind !== kind || ticket.vaultName !== vaultName || ticket.expiresAt < Date.now()) {
+    return null;
+  }
+  return ticket;
+}
+
+function ticketNotFound(): Response {
+  return json(
+    {
+      error: "Not found",
+      error_type: "not_found",
+      how_to:
+        "tickets are single-use and short-lived — mint a new one with request-attachment-upload / request-attachment-download",
+    },
+    404,
+  );
+}
+
+/**
+ * Dispatch a ticket spend request for `/vault/<name>/tickets/<id>`. PUT or
+ * POST spends an upload ticket (the mint tool advertises PUT; POST is
+ * accepted too for runtimes/proxies that rewrite methods); GET spends a
+ * download ticket. Any other method, or a method that doesn't match the
+ * ticket's own kind, collapses to the same 404 `takeValidTicket` uses —
+ * no oracle on which kind a given id was minted for.
+ */
+export async function handleTicketSpend(
+  req: Request,
+  ticketId: string,
+  vaultName: string,
+  store: Store,
+): Promise<Response> {
+  const provider = getSharedAttachmentTicketProvider();
+
+  if (req.method === "PUT" || req.method === "POST") {
+    return handleUploadSpend(req, ticketId, vaultName, store, provider);
+  }
+  if (req.method === "GET") {
+    return handleDownloadSpend(ticketId, vaultName, store, provider);
+  }
+  return ticketNotFound();
+}
+
+async function handleUploadSpend(
+  req: Request,
+  ticketId: string,
+  vaultName: string,
+  store: Store,
+  provider: AttachmentTicketProvider,
+): Promise<Response> {
+  const ticket = await takeValidTicket(provider, ticketId, vaultName, "upload");
+  if (!ticket || !ticket.noteId || !ticket.filename || !ticket.mimeType) return ticketNotFound();
+
+  // Declared size at mint IS the enforced cap here — tighter than the flat
+  // REST ceiling, per the ticket's own promise (`max_bytes` in the mint
+  // response). A ticket somehow minted with no declared size fails closed
+  // (0 bytes allowed) rather than falling back to the flat 100 MiB cap.
+  const declaredMax = ticket.sizeBytes ?? 0;
+
+  const contentLengthHeader = req.headers.get("content-length");
+  if (contentLengthHeader) {
+    const declared = Number(contentLengthHeader);
+    if (Number.isFinite(declared) && declared > declaredMax) {
+      return json(
+        {
+          error: `Upload exceeds the ticket's declared size (${declaredMax} bytes)`,
+          error_type: "file_too_large",
+          limit: declaredMax,
+          got: declared,
+          how_to: "mint a new ticket with an accurate size_bytes",
+        },
+        413,
+      );
+    }
+  }
+
+  const buffer = Buffer.from(await req.arrayBuffer());
+  if (buffer.length > declaredMax) {
+    return json(
+      {
+        error: `Upload exceeds the ticket's declared size (${declaredMax} bytes)`,
+        error_type: "file_too_large",
+        limit: declaredMax,
+        got: buffer.length,
+        how_to: "mint a new ticket with an accurate size_bytes",
+      },
+      413,
+    );
+  }
+
+  // Same on-disk write discipline as REST's POST /storage/upload
+  // (src/routes.ts) — server-generated path, never caller-controlled.
+  const ext = sanitizeAttachmentExtension(ticket.filename);
+  const date = new Date().toISOString().split("T")[0]!;
+  const dir = join(assetsDir(vaultName), date);
+  mkdirSync(dir, { recursive: true });
+  const filename = `${Date.now()}-${crypto.randomUUID()}${ext}`;
+  writeFileSync(join(dir, filename), buffer);
+  const relativePath = `${date}/${filename}`;
+
+  invalidateUsageCache(vaultName);
+
+  // Mirrors the REST POST /notes/:id/attachments transcribe decision
+  // exactly (src/routes.ts): explicit opt-in (here, `transcribe: true` at
+  // mint) wins; otherwise infer from mime-type + the owning vault's
+  // auto-transcribe toggle.
+  const explicitOptIn = ticket.transcribe === true;
+  const perVaultEnabled = readVaultConfig(vaultName)?.auto_transcribe?.enabled;
+  const autoOptIn = !explicitOptIn && shouldAutoTranscribe(ticket.mimeType, { perVaultEnabled });
+  const attMeta: Record<string, unknown> = {
+    original_name: ticket.filename,
+    size: buffer.length,
+  };
+  if (explicitOptIn || autoOptIn) {
+    attMeta.transcribe_status = "pending";
+    attMeta.transcribe_requested_at = new Date().toISOString();
+    attMeta.transcribe_origin = explicitOptIn ? "legacy" : "auto";
+  }
+
+  const attachment = await store.addAttachment(ticket.noteId, relativePath, ticket.mimeType, attMeta);
+
+  if (explicitOptIn) {
+    const note = await store.getNote(ticket.noteId);
+    if (note) {
+      const noteMeta = (note.metadata as Record<string, unknown> | undefined) ?? {};
+      if (noteMeta.transcribe_stub !== true) {
+        await store.updateNote(ticket.noteId, {
+          metadata: { ...noteMeta, transcribe_stub: true },
+          skipUpdatedAt: true,
+        });
+      }
+    }
+  }
+
+  // Ticket mint + register in one shot (vs REST's two-step upload-then-
+  // attach) — the spend response is the attachment row itself, so the
+  // runtime can hand the id straight back to the model.
+  return json(attachment, 201);
+}
+
+async function handleDownloadSpend(
+  ticketId: string,
+  vaultName: string,
+  store: Store,
+  provider: AttachmentTicketProvider,
+): Promise<Response> {
+  const ticket = await takeValidTicket(provider, ticketId, vaultName, "download");
+  if (!ticket || !ticket.attachmentId) return ticketNotFound();
+
+  // The row can vanish between mint and spend (rare — a delete racing a
+  // slow curl); fold that into the same uniform 404 rather than a 500.
+  const attachment = await store.getAttachment(ticket.attachmentId);
+  if (!attachment) return ticketNotFound();
+
+  const assets = assetsDir(vaultName);
+  const filePath = normalize(join(assets, attachment.path));
+  if (!filePath.startsWith(normalize(assets)) || !existsSync(filePath)) {
+    return json(
+      {
+        error: "Not found",
+        error_type: "attachment_binary_missing",
+        how_to: "the attachment row exists but its bytes are gone — this ticket can't be re-spent",
+      },
+      404,
+    );
+  }
+
+  const stat = statSync(filePath);
+  const fileBuffer = readFileSync(filePath);
+  return new Response(fileBuffer, {
+    status: 200,
+    headers: {
+      "Content-Type": attachment.mimeType || "application/octet-stream",
+      "Content-Length": String(stat.size),
+      // Same defense-in-depth as the existing GET /storage/<path> byte-serve
+      // (src/routes.ts) — never let a browser MIME-sniff a stored asset into
+      // an active type.
+      "X-Content-Type-Options": "nosniff",
+    },
+  });
+}

package/src/mcp-http.ts

@@ -109,7 +109,7 @@ export async function handleScopedMcp(
   const instruction = await getServerInstruction(vaultName, auth);
   return handleMcp(
     req,
-    () => generateScopedMcpTools(vaultName, auth, callerBearer ?? null),
+    () => generateScopedMcpTools(vaultName, auth, callerBearer ?? null, req),
     `parachute-vault/${vaultName}`,
     vaultName,
     auth,
@@ -229,6 +229,8 @@ export async function handleMcp(
         tag?: string;
         cycle?: unknown;
         referencing_tags?: unknown;
+        /** Attachment-tickets design (§2c "errors as JIT docs") — a short, imperative next-step, distinct from the older free-form `hint`. */
+        how_to?: string;
       };
       // Honest-queries validation errors (vault#550) — `limit`/`offset`/date
       // values that are structurally invalid rather than merely "no
@@ -399,6 +401,16 @@ export async function handleMcp(
           error_type: e.error_type,
           field: e.field,
           hint: e.hint,
+          // Forwarded when present (undefined keys are fine — JSON-RPC
+          // `data` just omits them) so a `structuredError()` call site that
+          // stamps extra fields — `limit`/`got`/`extension` (size/type
+          // refusals) or `how_to` (attachment-tickets' JIT-docs field, §2c)
+          // — isn't silently truncated down to error_type/field/hint by
+          // this backstop.
+          ...(e.limit !== undefined ? { limit: e.limit } : {}),
+          ...(e.got !== undefined ? { got: e.got } : {}),
+          ...(e.extension !== undefined ? { extension: e.extension } : {}),
+          ...(e.how_to !== undefined ? { how_to: e.how_to } : {}),
         });
       }
       return {

package/src/mcp-tools.ts

@@ -43,6 +43,8 @@ import {
 import { chooseHubOrigin, mintHubJwt, revokeHubJwt } from "./mcp-install.ts";
 import { looksLikeJwt } from "./hub-jwt.ts";
 import { readGlobalConfig, DEFAULT_PORT } from "./config.ts";
+import { getBaseUrl } from "./oauth-discovery.ts";
+import { getSharedAttachmentTicketProvider } from "./attachment-tickets.ts";
 
 /**
  * Filter a vault projection to entries an in-scope tag contributes to.
@@ -110,6 +112,10 @@ export async function getServerInstruction(
     description: config?.description ?? null,
     projection,
     coordinates: resolveVaultCoordinates(),
+    // Bun always wires an in-process AttachmentTicketProvider (see
+    // `generateScopedMcpTools` below) — the connect-time brief can
+    // unconditionally teach the ticket tools on this door.
+    attachments: { ticketsEnabled: true },
   });
 }
 
@@ -143,6 +149,16 @@ export function generateScopedMcpTools(
   vaultName: string,
   auth?: AuthResult,
   callerBearer?: string | null,
+  /**
+   * The incoming MCP request, when available (omitted by the many
+   * test-only call sites that construct tools without a live request).
+   * Threaded through ONLY so the attachment-ticket tools can resolve a
+   * request-accurate `urlBase` (honoring `X-Forwarded-Host`/proto, same as
+   * `getBaseUrl`) — falls back to `resolveVaultCoordinates()`'s configured/
+   * expose-state origin when omitted, so ticket tools are still present
+   * (just less precisely origined) in that case.
+   */
+  req?: Request,
 ): McpToolDef[] {
   const store = getVaultStore(vaultName);
 
@@ -225,20 +241,39 @@ export function generateScopedMcpTools(
     ? (info) => logStrictBypass(info)
     : undefined;
 
-  const tools = generateMcpTools(
-    store,
-    expandVisibility || nearTraversable || ifExistsVisible || aggregateVisibility || writeContext || strictBypass
-      ? {
-          ...(expandVisibility ? { expandVisibility } : {}),
-          ...(nearTraversable ? { nearTraversable } : {}),
-          ...(ifExistsVisible ? { ifExistsVisible } : {}),
-          ...(aggregateVisibility ? { aggregateVisibility } : {}),
-          ...(writeContext ? { writeContext } : {}),
-          ...(strictBypass ? { strictBypass } : {}),
-          ...(onStrictBypass ? { onStrictBypass } : {}),
-        }
-      : undefined,
-  );
+  // Attachment tickets (Wave 1): bun always wires the in-process provider
+  // (see src/attachment-tickets.ts) — unlike the tag-scope predicates
+  // above, this isn't conditional on `scoped` because the tools should be
+  // listed for every session, scoped or not. Tag-scope confidentiality is
+  // still enforced (`noteVisible`, awaited inline inside the ticket tools'
+  // own async execute — see its doc comment in generateMcpTools for why
+  // this doesn't need the shared allowedHolder machinery the OTHER
+  // predicates above do).
+  const ticketNoteVisible = scoped
+    ? async (note: Note) => {
+        const allowed = await expandTokenTagScope(store, rawTags);
+        return noteWithinTagScope(note, allowed, rawTags);
+      }
+    : undefined;
+  const ticketUrlBase = req
+    ? `${getBaseUrl(req).replace(/\/$/, "")}/vault/${vaultName}`
+    : `${resolveVaultCoordinates().hubOrigin.replace(/\/$/, "")}/vault/${vaultName}`;
+
+  const tools = generateMcpTools(store, {
+    ...(expandVisibility ? { expandVisibility } : {}),
+    ...(nearTraversable ? { nearTraversable } : {}),
+    ...(ifExistsVisible ? { ifExistsVisible } : {}),
+    ...(aggregateVisibility ? { aggregateVisibility } : {}),
+    ...(writeContext ? { writeContext } : {}),
+    ...(strictBypass ? { strictBypass } : {}),
+    ...(onStrictBypass ? { onStrictBypass } : {}),
+    attachmentTickets: {
+      provider: getSharedAttachmentTicketProvider(),
+      vaultName,
+      urlBase: ticketUrlBase,
+      ...(ticketNoteVisible ? { noteVisible: ticketNoteVisible } : {}),
+    },
+  });
 
   overrideVaultInfo(tools, vaultName, auth);
   applyTagDependencyGuards(tools, vaultName);

package/src/routes.ts

@@ -42,6 +42,10 @@ import {
   type ContentRange,
 } from "../core/src/content-range.ts";
 import { attachValidationStatus, enforceStrictWrite, applySchemaDefaults } from "../core/src/mcp.ts";
+import {
+  BLOCKED_ATTACHMENT_EXTENSIONS,
+  ATTACHMENT_MIME_TYPES,
+} from "../core/src/attachment/policy.ts";
 import type { ValidationWarning } from "../core/src/schema-defaults.ts";
 import { logStrictBypass } from "./scopes.ts";
 import * as linkOps from "../core/src/links.ts";
@@ -4440,97 +4444,14 @@ export const MAX_UPLOAD_BYTES = 100 * 1024 * 1024; // 100MB
  */
 export const MAX_REQUEST_BODY_BYTES = MAX_UPLOAD_BYTES + 20 * 1024 * 1024; // 120MB
 
-// Storage upload policy: DENY-LIST (vault#517). A knowledge vault stores
-// arbitrary files — ebooks, office docs, datasets, archives, binaries — so we
-// accept ANY upload EXCEPT the handful of types a browser can execute as
-// active content in our origin when served back from /storage/. (The prior
-// allowlist rejected the long tail: .epub/.csv/.zip/… all came back "File type
-// not allowed".)
-//
-// BLOCKED — same-origin-XSS / active-content set:
-//   .html/.htm/.xhtml/.shtml/.xht  HTML — embeds <script>
-//   .svg                           XML image — embeds <script>
-//   .xml                           can carry XSLT / be parsed as XHTML
-//   .js/.mjs/.cjs                  JavaScript
-//   .css                           style-injection / UI-redress vector
-//
-// Two independent guards keep every STORED file inert when served:
-//   1. Only the curated MIME_TYPES below map to a real (always passive) type;
-//      every other extension serves as application/octet-stream — a download,
-//      never rendered.
-//   2. The GET byte-serve response pins `X-Content-Type-Options: nosniff`, so
-//      a browser can't sniff an octet-stream body into an executable type.
-// The blocklist is belt-and-suspenders on top of those: even if a future MIME
-// entry or an upstream proxy weakened (1) or (2), these extensions still never
-// land on disk. If a future use case needs SVG, sanitize on read (strip
-// <script>/<foreignObject>) and revisit.
-const BLOCKED_EXTENSIONS = new Set([
-  ".html", ".htm", ".xhtml", ".shtml", ".xht",
-  ".svg",
-  ".xml",
-  ".js", ".mjs", ".cjs",
-  ".css",
-]);
-
-// Explicit MIME types for the commonly-previewed formats. Anything accepted
-// but absent here serves as application/octet-stream — a download, never
-// rendered (e.g. .pages/.key/.numbers/.azw3/.exe/arbitrary binaries). None of
-// these map to an active type (text/html, image/svg+xml), so a served asset
-// can't execute script; `nosniff` on the GET response makes that ironclad.
-//
-// INVARIANT: never add an entry that maps to a browser-active type —
-// text/html, image/svg+xml, application/xhtml+xml, text/javascript,
-// application/wasm, text/css. Doing so re-enables same-origin execution for
-// that extension (and would mean it must also join BLOCKED_EXTENSIONS).
-const MIME_TYPES: Record<string, string> = {
-  // Audio
-  ".wav": "audio/wav",
-  ".mp3": "audio/mpeg",
-  ".m4a": "audio/mp4",
-  ".ogg": "audio/ogg",
-  ".oga": "audio/ogg",
-  ".opus": "audio/opus",
-  ".aac": "audio/aac",
-  ".flac": "audio/flac",
-  ".webm": "audio/webm",
-  // Image
-  ".png": "image/png",
-  ".jpg": "image/jpeg",
-  ".jpeg": "image/jpeg",
-  ".gif": "image/gif",
-  ".webp": "image/webp",
-  ".bmp": "image/bmp",
-  ".tiff": "image/tiff",
-  ".tif": "image/tiff",
-  ".heic": "image/heic",
-  ".heif": "image/heif",
-  ".avif": "image/avif",
-  // Video
-  ".mp4": "video/mp4",
-  ".m4v": "video/x-m4v",
-  ".mov": "video/quicktime",
-  // Documents / ebooks / data
-  ".pdf": "application/pdf",
-  ".epub": "application/epub+zip",
-  ".mobi": "application/x-mobipocket-ebook",
-  ".txt": "text/plain; charset=utf-8",
-  ".md": "text/markdown; charset=utf-8",
-  ".markdown": "text/markdown; charset=utf-8",
-  ".rtf": "application/rtf",
-  ".csv": "text/csv; charset=utf-8",
-  ".tsv": "text/tab-separated-values; charset=utf-8",
-  ".json": "application/json; charset=utf-8",
-  ".doc": "application/msword",
-  ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
-  ".ppt": "application/vnd.ms-powerpoint",
-  ".pptx": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
-  ".xls": "application/vnd.ms-excel",
-  ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
-  ".odt": "application/vnd.oasis.opendocument.text",
-  ".ods": "application/vnd.oasis.opendocument.spreadsheet",
-  ".odp": "application/vnd.oasis.opendocument.presentation",
-  ".zip": "application/zip",
-};
+// Storage upload policy (extension blocklist + MIME lookup) now lives in
+// core/src/attachment/policy.ts — the canonical source shared with the
+// attachment-ticket mint/spend path (vault attachment-tickets design,
+// "shared BLOCKED_EXTENSIONS"), so a blocked extension can never diverge
+// between REST and tickets. See that module's doc comment for the full
+// same-origin-XSS rationale and the MIME curation invariant.
+const BLOCKED_EXTENSIONS = BLOCKED_ATTACHMENT_EXTENSIONS;
+const MIME_TYPES = ATTACHMENT_MIME_TYPES;
 
 export async function handleStorage(
   req: Request,

package/src/routing.ts

@@ -103,6 +103,7 @@ import {
 } from "./mirror-routes.ts";
 import { getMirrorManager } from "./mirror-registry.ts";
 import { buildUsageReport } from "./usage.ts";
+import { handleTicketSpend } from "./attachment-tickets.ts";
 
 /**
  * Decorate a 401 response from the MCP endpoint with the RFC 9728 challenge
@@ -490,6 +491,22 @@ export async function route(
     return handleAuthorizationServer(req, vaultName);
   }
 
+  // Attachment ticket spend (attachment-tickets design, Wave 1) — no auth
+  // beyond the ticket itself; the ticket IS the credential (single-use,
+  // short TTL, scoped to exactly one upload slot or one attachment's
+  // bytes). Deliberately placed BEFORE `authenticateVaultRequest` below —
+  // a bearer-less runtime (a bare `curl`) must be able to spend a ticket
+  // without ever holding this vault's API key. The path segment
+  // (`/tickets/<id>`) is outside the authed `/api` tree and outside
+  // `/mcp` on purpose — see `request-attachment-upload`/`-download`
+  // (core/src/mcp.ts) for where tickets are minted.
+  const vaultTicketMatch = subpath.match(/^\/tickets\/([^/]+)$/);
+  if (vaultTicketMatch) {
+    const ticketId = decodeURIComponent(vaultTicketMatch[1]!);
+    const store = getVaultStore(vaultName);
+    return handleTicketSpend(req, ticketId, vaultName, store);
+  }
+
   // ---------------------------------------------------------------------
   // Authenticated surface
   // ---------------------------------------------------------------------

package/src/vault.test.ts

@@ -2139,6 +2139,22 @@ describe("HTTP /notes", async () => {
     expect(body[0]).not.toHaveProperty("content");
     expect(body[0]).toHaveProperty("byteSize");
     expect(body[0]).toHaveProperty("preview");
+    expect(body[0]).toHaveProperty("displayTitle");
+  });
+
+  // Title axis (ratified 2026-07-17) — displayTitle on the REST lean shape.
+  test("GET /notes lean shape carries the computed displayTitle", async () => {
+    await store.createNote("# Meeting Notes\nagenda: budget", { path: "meeting" });
+    const res = await handleNotes(mkReq("GET", "/notes"), store, "");
+    const body = await res.json() as any[];
+    expect(body[0].displayTitle).toBe("Meeting Notes");
+  });
+
+  test("GET /notes lean shape reports null displayTitle for an empty note", async () => {
+    await store.createNote("", { path: "empty" });
+    const res = await handleNotes(mkReq("GET", "/notes"), store, "");
+    const body = await res.json() as any[];
+    expect(body[0].displayTitle).toBeNull();
   });
 
   test("GET /notes?include_content=true returns full notes", async () => {
@@ -6609,8 +6625,12 @@ describe("stateless MCP transport", async () => {
     expect(toolNames).not.toContain("merge-tags");
     // Admin tools (vault#376) are hidden too
     expect(toolNames).not.toContain("manage-token");
-    // Read tier is exactly 5 tools (doctor added by the re-tier).
-    expect(toolNames.length).toBe(5);
+    // request-attachment-download is read-tier (upload is write-tier).
+    expect(toolNames).toContain("request-attachment-download");
+    expect(toolNames).not.toContain("request-attachment-upload");
+    // Read tier is exactly 6 tools (doctor added by the re-tier;
+    // request-attachment-download added by the attachment-tickets design).
+    expect(toolNames.length).toBe(6);
 
     closeAllStores();
   });
@@ -6891,15 +6911,15 @@ describe("MCP tools/list scope tiers (vault#376)", () => {
     return names;
   }
 
-  test("vault:read sees exactly the 5 read tools (doctor moved admin → read)", async () => {
+  test("vault:read sees exactly the 6 read tools (doctor moved admin → read; request-attachment-download is read-tier)", async () => {
     const names = await listToolNames(["vault:read"]);
     expect(new Set(names)).toEqual(
-      new Set(["query-notes", "list-tags", "find-path", "vault-info", "doctor"]),
+      new Set(["query-notes", "list-tags", "find-path", "vault-info", "doctor", "request-attachment-download"]),
     );
-    expect(names.length).toBe(5);
+    expect(names.length).toBe(6);
   });
 
-  test("vault:read + vault:write sees the 8 read+write tools (tag-schema tools moved write → admin)", async () => {
+  test("vault:read + vault:write sees the 10 read+write tools (tag-schema tools moved write → admin; request-attachment-upload is write-tier)", async () => {
     const names = await listToolNames(["vault:read", "vault:write"]);
     expect(new Set(names)).toEqual(
       new Set([
@@ -6911,9 +6931,11 @@ describe("MCP tools/list scope tiers (vault#376)", () => {
         "create-note",
         "update-note",
         "delete-note",
+        "request-attachment-upload",
+        "request-attachment-download",
       ]),
     );
-    expect(names.length).toBe(8);
+    expect(names.length).toBe(10);
     expect(names).not.toContain("manage-token");
     // Re-tier (this PR): update-tag/delete-tag/rename-tag/merge-tags are now
     // admin-tier — structure/taxonomy curation, not content authorship.
@@ -6925,7 +6947,7 @@ describe("MCP tools/list scope tiers (vault#376)", () => {
     expect(names).toContain("delete-note");
   });
 
-  test("vault:admin sees all 14 tools including manage-token + prune-schema + the tag-schema tools", async () => {
+  test("vault:admin sees all 16 tools including manage-token + prune-schema + the tag-schema tools + both attachment-ticket tools", async () => {
     const names = await listToolNames(["vault:read", "vault:write", "vault:admin"]);
     expect(names).toContain("manage-token");
     expect(names).toContain("prune-schema");
@@ -6934,10 +6956,12 @@ describe("MCP tools/list scope tiers (vault#376)", () => {
     expect(names).toContain("delete-tag");
     expect(names).toContain("rename-tag");
     expect(names).toContain("merge-tags");
-    expect(names.length).toBe(14);
+    expect(names).toContain("request-attachment-upload");
+    expect(names).toContain("request-attachment-download");
+    expect(names.length).toBe(16);
   });
 
-  test("legacy-derived full token sees all 14 tools (back-compat)", async () => {
+  test("legacy-derived full token sees all 16 tools (back-compat)", async () => {
     const { handleScopedMcp } = await import("./mcp-http.ts");
     const { writeVaultConfig } = await import("./config.ts");
     const { closeAllStores } = await import("./vault-store.ts");
@@ -6970,7 +6994,7 @@ describe("MCP tools/list scope tiers (vault#376)", () => {
     } as any);
     const body = await res.json() as any;
     const names: string[] = body.result.tools.map((t: any) => t.name);
-    expect(names.length).toBe(14);
+    expect(names.length).toBe(16);
     expect(names).toContain("manage-token");
     expect(names).toContain("prune-schema");
     expect(names).toContain("doctor");