@openparachute/vault 0.7.2 → 0.7.3-rc.10

package/README.md

@@ -30,7 +30,7 @@ For remote access from Claude Desktop or mobile apps, see [Deployment](#deployme
 
 A server on port 1940 with:
 
-- **MCP** — 9 tools for AI agents (notes, tags, graph, vault info)
+- **MCP** — tools for AI agents (notes, tags, graph, vault info, attachments)
 - **REST API** — Full CRUD for notes, tags, links, full-text search
 - **Wikilink auto-linking** — `[[wikilinks]]` in note content automatically create links in the graph
 - **Obsidian import/export** — Bidirectional interop with Obsidian vaults
@@ -252,12 +252,14 @@ parachute-vault backup --schedule daily        # hourly | daily | weekly | manua
 parachute-vault backup status                  # schedule, last run, destinations, next run
 ```
 
-## MCP tools (9)
+## MCP tools (13 core, + attachments + admin)
 
 **Notes**: `query-notes` (universal read — single by ID/path, filter, search, graph neighborhood), `create-note` (single or batch), `update-note` (single or batch — content, tags, links, metadata), `delete-note`
-**Tags**: `list-tags` (with optional schema detail), `update-tag` (upsert description + schema fields), `delete-tag`
+**Tags**: `list-tags` (with optional schema detail), `update-tag` (upsert description + schema fields), `delete-tag`, `rename-tag`, `merge-tags`
 **Graph**: `find-path` (BFS between two notes)
 **Vault**: `vault-info` (get/update description + stats)
+**Admin**: `prune-schema`, `doctor` (taxonomy/metadata integrity scan), `manage-token`
+**Attachments** (2, present when the door wires an attachment-ticket provider — always true on this server): `request-attachment-upload`, `request-attachment-download` — mint a short-lived, single-use ticket a runtime's shell spends directly at `/vault/{name}/tickets/{id}`; bytes never pass through the tool call. See [`docs/HTTP_API.md`](./docs/HTTP_API.md#attachment-tickets-vault611--wave-1-bun-only).
 
 ### Vault descriptions
 

package/core/src/attachment/policy.test.ts

@@ -0,0 +1,66 @@
+import { describe, test, expect } from "bun:test";
+import {
+  BLOCKED_ATTACHMENT_EXTENSIONS,
+  ATTACHMENT_MIME_TYPES,
+  sanitizeAttachmentExtension,
+  mimeForAttachmentExtension,
+} from "./policy.ts";
+
+describe("sanitizeAttachmentExtension", () => {
+  test("extracts a lowercased extension", () => {
+    expect(sanitizeAttachmentExtension("Photo.PNG")).toBe(".png");
+  });
+
+  test("strips trailing dots/whitespace before extracting — evil.html. can't slip past the blocklist as an empty extension", () => {
+    expect(sanitizeAttachmentExtension("evil.html.")).toBe(".html");
+    expect(sanitizeAttachmentExtension("evil.svg ")).toBe(".svg");
+  });
+
+  test("a dotfile with no real extension reports none", () => {
+    expect(sanitizeAttachmentExtension(".bashrc")).toBe("");
+  });
+
+  test("a filename with no dot reports none", () => {
+    expect(sanitizeAttachmentExtension("README")).toBe("");
+  });
+});
+
+describe("BLOCKED_ATTACHMENT_EXTENSIONS — active-content set", () => {
+  test("blocks the same-origin-XSS extensions", () => {
+    for (const ext of [".html", ".htm", ".xhtml", ".shtml", ".xht", ".svg", ".xml", ".js", ".mjs", ".cjs", ".css"]) {
+      expect(BLOCKED_ATTACHMENT_EXTENSIONS.has(ext)).toBe(true);
+    }
+  });
+
+  test("does not block ordinary document/media extensions", () => {
+    for (const ext of [".png", ".pdf", ".csv", ".epub", ".zip", ".mp3", ".docx"]) {
+      expect(BLOCKED_ATTACHMENT_EXTENSIONS.has(ext)).toBe(false);
+    }
+  });
+});
+
+describe("mimeForAttachmentExtension", () => {
+  test("resolves a curated extension", () => {
+    expect(mimeForAttachmentExtension(".png")).toBe("image/png");
+    expect(mimeForAttachmentExtension(".pdf")).toBe("application/pdf");
+  });
+
+  test("falls back to application/octet-stream for an uncurated extension", () => {
+    expect(mimeForAttachmentExtension(".azw3")).toBe("application/octet-stream");
+  });
+
+  test("no MIME entry maps to a browser-active type (INVARIANT)", () => {
+    const activeTypes = new Set([
+      "text/html",
+      "image/svg+xml",
+      "application/xhtml+xml",
+      "text/javascript",
+      "application/wasm",
+      "text/css",
+    ]);
+    for (const mime of Object.values(ATTACHMENT_MIME_TYPES)) {
+      const bare = mime.split(";")[0]!.trim();
+      expect(activeTypes.has(bare)).toBe(false);
+    }
+  });
+});

package/core/src/attachment/policy.ts

@@ -0,0 +1,131 @@
+/**
+ * Shared attachment upload policy — extension blocklist + MIME lookup.
+ *
+ * Canonical source for every upload path into this vault's attachment
+ * storage: the REST `POST /storage/upload` handler (`src/routes.ts`, which
+ * imports these constants rather than declaring its own) and the
+ * attachment-ticket mint/spend path (`core/src/mcp.ts`'s
+ * `request-attachment-upload` tool + `src/attachment-tickets.ts`'s spend
+ * route). One list, so a blocked extension can never diverge between the
+ * two upload doors into this vault (vault attachment-tickets design,
+ * "shared BLOCKED_EXTENSIONS").
+ *
+ * Deliberately dependency-free (no `node:path`) — this module is imported
+ * by `core/src/mcp.ts`, which a Cloudflare Worker (cloud's runtime) bundles
+ * directly; a hand-rolled `extname` keeps that bundle Node-compat-free.
+ */
+
+// 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.
+export const BLOCKED_ATTACHMENT_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_ATTACHMENT_EXTENSIONS).
+export const ATTACHMENT_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",
+};
+
+/** Node-`path`-free `extname`: lowercased, leading-dot dotfiles ("`.bashrc`") report no extension — same edge case Node's `path.extname` treats as extensionless. */
+function extnameOf(filename: string): string {
+  const idx = filename.lastIndexOf(".");
+  if (idx <= 0) return "";
+  return filename.slice(idx).toLowerCase();
+}
+
+/**
+ * Extract the sanitized, lowercased extension from a caller-supplied
+ * filename. Strips trailing dots/whitespace FIRST so `evil.html.` /
+ * `evil.svg ` can't slip past `BLOCKED_ATTACHMENT_EXTENSIONS`
+ * (`extname("evil.html.")` would otherwise be `"."`, not `.html`) — mirrors
+ * `src/routes.ts`'s upload-handler sanitization exactly.
+ */
+export function sanitizeAttachmentExtension(filename: string): string {
+  return extnameOf(filename.replace(/[.\s]+$/, ""));
+}
+
+/** MIME type for a (already-sanitized) extension, `application/octet-stream` when uncurated — never an active/executable type (see the INVARIANT above). */
+export function mimeForAttachmentExtension(ext: string): string {
+  return ATTACHMENT_MIME_TYPES[ext] ?? "application/octet-stream";
+}

package/core/src/attachment/tickets.test.ts

@@ -0,0 +1,45 @@
+import { describe, test, expect } from "bun:test";
+import { computeTicketTtlMs, generateTicketId, MAX_TICKET_UPLOAD_BYTES } from "./tickets.ts";
+
+describe("computeTicketTtlMs — Aaron-ratified TTL scaling (10 min base + 10s/MiB, 30 min cap)", () => {
+  test("no declared size → base TTL (10 minutes)", () => {
+    expect(computeTicketTtlMs()).toBe(10 * 60 * 1000);
+  });
+
+  test("zero or negative size → base TTL (fails safe, not zero-TTL)", () => {
+    expect(computeTicketTtlMs(0)).toBe(10 * 60 * 1000);
+    expect(computeTicketTtlMs(-5)).toBe(10 * 60 * 1000);
+  });
+
+  test("1 MiB declared → base + 10s", () => {
+    expect(computeTicketTtlMs(1024 * 1024)).toBe(10 * 60 * 1000 + 10 * 1000);
+  });
+
+  test("10 MiB declared → base + 100s", () => {
+    expect(computeTicketTtlMs(10 * 1024 * 1024)).toBe(10 * 60 * 1000 + 100 * 1000);
+  });
+
+  test("100 MiB declared (under the cap's crossover at 120 MiB) is base + 1000s, not yet capped", () => {
+    expect(computeTicketTtlMs(100 * 1024 * 1024)).toBe(10 * 60 * 1000 + 1000 * 1000);
+  });
+
+  test("a declared size past the crossover point (200 MiB) is capped at 30 minutes flat", () => {
+    expect(computeTicketTtlMs(200 * 1024 * 1024)).toBe(30 * 60 * 1000);
+  });
+});
+
+describe("generateTicketId", () => {
+  test("is a 64-char hex string (256 bits)", () => {
+    const id = generateTicketId();
+    expect(id).toMatch(/^[0-9a-f]{64}$/);
+  });
+
+  test("is unique across many calls (no Math.random-grade collisions)", () => {
+    const ids = new Set(Array.from({ length: 1000 }, () => generateTicketId()));
+    expect(ids.size).toBe(1000);
+  });
+});
+
+test("MAX_TICKET_UPLOAD_BYTES mirrors REST's 100 MiB upload ceiling", () => {
+  expect(MAX_TICKET_UPLOAD_BYTES).toBe(100 * 1024 * 1024);
+});

package/core/src/attachment/tickets.ts

@@ -0,0 +1,117 @@
+/**
+ * Attachment tickets — the runtime lane (Wave 1) of the two-lane
+ * attachments-for-agents design. Bytes never touch the MCP session:
+ * `request-attachment-upload` / `request-attachment-download`
+ * (`core/src/mcp.ts`) mint a short-lived, single-use, capability-in-URL
+ * ticket; a runtime with a shell (never the model) spends it directly
+ * against a bare HTTP endpoint outside the authed API tree.
+ *
+ * This module owns the wire-shape-defining pieces so both doors can't
+ * drift: the ticket record shape, TTL computation, and id generation. The
+ * `AttachmentTicketProvider` seam is deliberately dumb — a single-use KV,
+ * no policy — because ALL policy (note/attachment resolution, tag-scope,
+ * size cap, extension sanitize) runs at mint time in the MCP tools
+ * themselves, pinned here so a future cloud implementation can't drift on
+ * the wire shape or the error taxonomy.
+ */
+
+export type AttachmentTicketKind = "upload" | "download";
+
+/**
+ * A minted, not-yet-spent ticket. `sizeBytes` is the DECLARED size at mint
+ * — upload: caller-asserted (`request-attachment-upload`'s `size_bytes`,
+ * enforced as a hard cap at spend, see `MAX_TICKET_UPLOAD_BYTES`);
+ * download: best-effort from `attachments.metadata.size` when the row
+ * carries one (advisory only — never enforced, since a download ticket
+ * never writes bytes).
+ */
+export interface AttachmentTicket {
+  id: string;
+  kind: AttachmentTicketKind;
+  vaultName: string;
+  createdAt: number;
+  expiresAt: number;
+  mimeType?: string;
+  sizeBytes?: number;
+  /** Upload only. */
+  noteId?: string;
+  filename?: string;
+  transcribe?: boolean;
+  /** Download only. */
+  attachmentId?: string;
+}
+
+/**
+ * Storage seam for ticket state (D10 — "tools omitted when unwired"). A
+ * door that hasn't implemented this yet passes no `attachmentTickets` opt
+ * into `generateMcpTools` — `request-attachment-upload` /
+ * `request-attachment-download` are then ABSENT from the tool list
+ * entirely (not merely erroring on call), so an agent is never shown an
+ * affordance the runtime can't back.
+ *
+ * "State lives where the bytes live" (design decision): bun implements
+ * this as an in-process `Map` (`src/attachment-tickets.ts`) — a daemon
+ * restart drops every outstanding ticket, which is acceptable at a
+ * ≤30-minute TTL and is documented at that call site. A future cloud
+ * implementation persists ticket rows in the vault's Durable Object
+ * (`ctx.storage`, atomic delete-on-spend under `transactionSync`).
+ */
+export interface AttachmentTicketProvider {
+  /** Persist a freshly-minted ticket. */
+  put(ticket: AttachmentTicket): Promise<void>;
+  /**
+   * Atomic check-and-consume. Returns the ticket exactly once — a second
+   * call for the same id (already spent), an id past its `expiresAt`, or
+   * an id that never existed all return `null`. Collapsing all three into
+   * one shape is deliberate: the spend route gives an unguessable-URL
+   * adversary no oracle distinguishing "wrong id" from "right id, too
+   * late" — the caller still separately checks `expiresAt` against
+   * wall-clock (a `take` implementation MAY also drop expired entries
+   * opportunistically, but callers must not rely on that for correctness).
+   */
+  take(id: string): Promise<AttachmentTicket | null>;
+}
+
+/**
+ * Absolute REST upload ceiling (mirrors `MAX_UPLOAD_BYTES`,
+ * `src/routes.ts`) — a ticket can never promise more than REST itself
+ * accepts for the same bytes. Enforced at MINT (a `size_bytes` over this
+ * is rejected before a ticket is even created) — the ticket's own
+ * `sizeBytes` (always `<=` this) is the tighter, per-ticket cap the spend
+ * route actually enforces.
+ */
+export const MAX_TICKET_UPLOAD_BYTES = 100 * 1024 * 1024;
+
+const TICKET_TTL_BASE_MS = 10 * 60 * 1000; // 10 minutes
+const TICKET_TTL_PER_MIB_MS = 10 * 1000; // +10s per declared MiB
+const TICKET_TTL_MAX_MS = 30 * 60 * 1000; // hard cap, 30 minutes
+
+/**
+ * TTL for a minted ticket, in ms. 10 minutes base + 10 seconds per
+ * declared MiB (a slow tether on a large upload gets proportionally more
+ * room), hard-capped at 30 minutes regardless of size (Aaron-ratified
+ * amendment over the spec's original flat 120s). A size-less mint
+ * (download ticket for a row with no known size) gets the base TTL.
+ * Single-use is enforced separately and unconditionally by
+ * `AttachmentTicketProvider.take` — TTL only bounds how long an UNSPENT
+ * ticket stays valid, never how many times a spent one can be reused.
+ */
+export function computeTicketTtlMs(sizeBytes?: number): number {
+  if (!sizeBytes || sizeBytes <= 0) return TICKET_TTL_BASE_MS;
+  const mib = sizeBytes / (1024 * 1024);
+  return Math.min(TICKET_TTL_BASE_MS + mib * TICKET_TTL_PER_MIB_MS, TICKET_TTL_MAX_MS);
+}
+
+/**
+ * 256-bit random ticket id, hex-encoded (64 chars). Capability-in-URL — the
+ * ticket's entropy is the ONLY thing standing between "knows the URL" and
+ * "can spend it" (no auth beyond the ticket itself), so this is Web Crypto
+ * `getRandomValues`, never `Math.random()`. Global `crypto` — available in
+ * both Bun and the Cloudflare Workers runtime, so this module stays
+ * runtime-agnostic.
+ */
+export function generateTicketId(): string {
+  const bytes = new Uint8Array(32);
+  crypto.getRandomValues(bytes);
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}

package/core/src/attachment-tickets-tool.test.ts

@@ -0,0 +1,286 @@
+/**
+ * `request-attachment-upload` / `request-attachment-download` — the two
+ * MCP mint tools generated by `generateMcpTools` (see mcp.ts's
+ * `GenerateMcpToolsOpts.attachmentTickets`). Exercises the "tools omitted
+ * when unwired" contract (D10) and the mint-time policy (note/attachment
+ * resolution, tag-scope, size cap, extension blocklist) against a fake
+ * in-memory `AttachmentTicketProvider` — the spend side (actually writing
+ * bytes) is bun-only and covered in src/attachment-tickets.test.ts.
+ */
+
+import { describe, test, expect, beforeEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import { BunSqliteStore } from "./store.ts";
+import { generateMcpTools, type McpToolDef } from "./mcp.ts";
+import type { AttachmentTicket, AttachmentTicketProvider } from "./attachment/tickets.ts";
+import { MAX_TICKET_UPLOAD_BYTES } from "./attachment/tickets.ts";
+import type { Note } from "./types.ts";
+
+class FakeTicketProvider implements AttachmentTicketProvider {
+  tickets = new Map<string, AttachmentTicket>();
+  async put(t: AttachmentTicket): Promise<void> {
+    this.tickets.set(t.id, t);
+  }
+  async take(id: string): Promise<AttachmentTicket | null> {
+    const t = this.tickets.get(id);
+    if (!t) return null;
+    this.tickets.delete(id);
+    return t;
+  }
+}
+
+let store: BunSqliteStore;
+
+beforeEach(() => {
+  store = new BunSqliteStore(new Database(":memory:"));
+});
+
+function findTool(tools: McpToolDef[], name: string): McpToolDef {
+  const t = tools.find((x) => x.name === name);
+  if (!t) throw new Error(`tool "${name}" not found`);
+  return t;
+}
+
+async function callTool(tool: McpToolDef, params: Record<string, unknown>): Promise<any> {
+  return await tool.execute(params);
+}
+
+async function expectToolError(tool: McpToolDef, params: Record<string, unknown>): Promise<any> {
+  try {
+    await tool.execute(params);
+    throw new Error("expected the tool to throw");
+  } catch (err) {
+    return err as any;
+  }
+}
+
+describe("D10 — tools omitted when unwired", () => {
+  test("no attachmentTickets opt → neither ticket tool is generated", () => {
+    const tools = generateMcpTools(store);
+    expect(tools.find((t) => t.name === "request-attachment-upload")).toBeUndefined();
+    expect(tools.find((t) => t.name === "request-attachment-download")).toBeUndefined();
+  });
+
+  test("attachmentTickets opt provided → both ticket tools are generated with the right verbs", () => {
+    const provider = new FakeTicketProvider();
+    const tools = generateMcpTools(store, {
+      attachmentTickets: { provider, vaultName: "v1", urlBase: "https://host/vault/v1" },
+    });
+    const upload = findTool(tools, "request-attachment-upload");
+    const download = findTool(tools, "request-attachment-download");
+    expect(upload.requiredVerb).toBe("write");
+    expect(download.requiredVerb).toBe("read");
+  });
+});
+
+describe("request-attachment-upload — mint", () => {
+  test("happy path: returns the ticket envelope and stores a matching provider record", async () => {
+    const note = await store.createNote("# Target\n", { path: "target" });
+    const provider = new FakeTicketProvider();
+    const tools = generateMcpTools(store, {
+      attachmentTickets: { provider, vaultName: "v1", urlBase: "https://host/vault/v1" },
+    });
+    const tool = findTool(tools, "request-attachment-upload");
+
+    const before = Date.now();
+    const result = await callTool(tool, { note: note.id, filename: "photo.png", size_bytes: 1024 });
+    expect(result.method).toBe("PUT");
+    expect(result.url).toMatch(/^https:\/\/host\/vault\/v1\/tickets\/[0-9a-f]{64}$/);
+    expect(result.headers["content-type"]).toBe("image/png");
+    expect(result.max_bytes).toBe(1024);
+    expect(result.curl_example).toContain("curl -X PUT");
+    expect(result.curl_example).toContain(result.url);
+
+    const ticketId = result.url.split("/tickets/")[1] as string;
+    const stored = provider.tickets.get(ticketId)!;
+    expect(stored.kind).toBe("upload");
+    expect(stored.noteId).toBe(note.id);
+    expect(stored.filename).toBe("photo.png");
+    expect(stored.mimeType).toBe("image/png");
+    expect(stored.sizeBytes).toBe(1024);
+    expect(stored.vaultName).toBe("v1");
+    // TTL for a 1024-byte (<1 MiB) declared size is the 10-minute base.
+    expect(stored.expiresAt - before).toBeGreaterThanOrEqual(10 * 60 * 1000 - 1000);
+    expect(stored.expiresAt - before).toBeLessThanOrEqual(10 * 60 * 1000 + 5000);
+  });
+
+  test("mime_type is inferred from the filename extension when omitted", async () => {
+    const note = await store.createNote("# T\n", { path: "t2" });
+    const provider = new FakeTicketProvider();
+    const tools = generateMcpTools(store, {
+      attachmentTickets: { provider, vaultName: "v1", urlBase: "https://host/vault/v1" },
+    });
+    const result = await callTool(findTool(tools, "request-attachment-upload"), {
+      note: note.id,
+      filename: "notes.csv",
+      size_bytes: 10,
+    });
+    expect(result.headers["content-type"]).toBe("text/csv; charset=utf-8");
+  });
+
+  test("transcribe: true rides through to the stored ticket", async () => {
+    const note = await store.createNote("# T\n", { path: "t3" });
+    const provider = new FakeTicketProvider();
+    const tools = generateMcpTools(store, {
+      attachmentTickets: { provider, vaultName: "v1", urlBase: "https://host/vault/v1" },
+    });
+    const result = await callTool(findTool(tools, "request-attachment-upload"), {
+      note: note.id,
+      filename: "memo.wav",
+      size_bytes: 10,
+      transcribe: true,
+    });
+    const ticketId = result.url.split("/tickets/")[1] as string;
+    expect(provider.tickets.get(ticketId)!.transcribe).toBe(true);
+  });
+
+  test("missing note / filename / size_bytes → missing_required_field with how_to", async () => {
+    const provider = new FakeTicketProvider();
+    const tools = generateMcpTools(store, {
+      attachmentTickets: { provider, vaultName: "v1", urlBase: "https://host/vault/v1" },
+    });
+    const tool = findTool(tools, "request-attachment-upload");
+
+    const e1 = await expectToolError(tool, { filename: "a.png", size_bytes: 1 });
+    expect(e1.error_type).toBe("missing_required_field");
+    expect(e1.field).toBe("note");
+    expect(typeof e1.how_to).toBe("string");
+
+    const e2 = await expectToolError(tool, { note: "x", size_bytes: 1 });
+    expect(e2.error_type).toBe("missing_required_field");
+    expect(e2.field).toBe("filename");
+
+    const e3 = await expectToolError(tool, { note: "x", filename: "a.png" });
+    expect(e3.error_type).toBe("invalid_query");
+    expect(e3.field).toBe("size_bytes");
+  });
+
+  test("size_bytes over the 100 MiB cap → file_too_large with limit/got/how_to", async () => {
+    const note = await store.createNote("# T\n", { path: "t4" });
+    const provider = new FakeTicketProvider();
+    const tools = generateMcpTools(store, {
+      attachmentTickets: { provider, vaultName: "v1", urlBase: "https://host/vault/v1" },
+    });
+    const err = await expectToolError(findTool(tools, "request-attachment-upload"), {
+      note: note.id,
+      filename: "huge.zip",
+      size_bytes: MAX_TICKET_UPLOAD_BYTES + 1,
+    });
+    expect(err.error_type).toBe("file_too_large");
+    expect(err.limit).toBe(MAX_TICKET_UPLOAD_BYTES);
+    expect(err.got).toBe(MAX_TICKET_UPLOAD_BYTES + 1);
+    expect(typeof err.how_to).toBe("string");
+    expect(provider.tickets.size).toBe(0);
+  });
+
+  test("blocked (active-content) extension → blocked_upload_extension, no ticket minted", async () => {
+    const note = await store.createNote("# T\n", { path: "t5" });
+    const provider = new FakeTicketProvider();
+    const tools = generateMcpTools(store, {
+      attachmentTickets: { provider, vaultName: "v1", urlBase: "https://host/vault/v1" },
+    });
+    const err = await expectToolError(findTool(tools, "request-attachment-upload"), {
+      note: note.id,
+      filename: "evil.html",
+      size_bytes: 10,
+    });
+    expect(err.error_type).toBe("blocked_upload_extension");
+    expect(err.extension).toBe(".html");
+    expect(provider.tickets.size).toBe(0);
+  });
+
+  test("unknown note → not_found", async () => {
+    const provider = new FakeTicketProvider();
+    const tools = generateMcpTools(store, {
+      attachmentTickets: { provider, vaultName: "v1", urlBase: "https://host/vault/v1" },
+    });
+    const err = await expectToolError(findTool(tools, "request-attachment-upload"), {
+      note: "does-not-exist",
+      filename: "a.png",
+      size_bytes: 10,
+    });
+    expect(err.error_type).toBe("not_found");
+  });
+
+  test("tag-scoped noteVisible: false → uniform not_found (no existence oracle)", async () => {
+    const note = await store.createNote("# T\n", { path: "t6" });
+    const provider = new FakeTicketProvider();
+    const tools = generateMcpTools(store, {
+      attachmentTickets: {
+        provider,
+        vaultName: "v1",
+        urlBase: "https://host/vault/v1",
+        noteVisible: async (_n: Note) => false,
+      },
+    });
+    const err = await expectToolError(findTool(tools, "request-attachment-upload"), {
+      note: note.id,
+      filename: "a.png",
+      size_bytes: 10,
+    });
+    expect(err.error_type).toBe("not_found");
+    expect(provider.tickets.size).toBe(0);
+  });
+});
+
+describe("request-attachment-download — mint", () => {
+  test("happy path: returns the ticket envelope with mime_type + known size, stores a matching provider record", async () => {
+    const note = await store.createNote("# T\n", { path: "t7" });
+    const attachment = await store.addAttachment(note.id, "2026-07-17/x.png", "image/png", { size: 42 });
+    const provider = new FakeTicketProvider();
+    const tools = generateMcpTools(store, {
+      attachmentTickets: { provider, vaultName: "v1", urlBase: "https://host/vault/v1" },
+    });
+    const result = await callTool(findTool(tools, "request-attachment-download"), {
+      attachment_id: attachment.id,
+    });
+    expect(result.method).toBe("GET");
+    expect(result.mime_type).toBe("image/png");
+    expect(result.size_bytes).toBe(42);
+    expect(result.curl_example).toContain(result.url);
+
+    const ticketId = result.url.split("/tickets/")[1] as string;
+    const stored = provider.tickets.get(ticketId)!;
+    expect(stored.kind).toBe("download");
+    expect(stored.attachmentId).toBe(attachment.id);
+  });
+
+  test("missing attachment_id → missing_required_field", async () => {
+    const provider = new FakeTicketProvider();
+    const tools = generateMcpTools(store, {
+      attachmentTickets: { provider, vaultName: "v1", urlBase: "https://host/vault/v1" },
+    });
+    const err = await expectToolError(findTool(tools, "request-attachment-download"), {});
+    expect(err.error_type).toBe("missing_required_field");
+  });
+
+  test("unknown attachment → not_found", async () => {
+    const provider = new FakeTicketProvider();
+    const tools = generateMcpTools(store, {
+      attachmentTickets: { provider, vaultName: "v1", urlBase: "https://host/vault/v1" },
+    });
+    const err = await expectToolError(findTool(tools, "request-attachment-download"), {
+      attachment_id: "does-not-exist",
+    });
+    expect(err.error_type).toBe("not_found");
+  });
+
+  test("tag-scoped noteVisible: false on the owning note → not_found, same shape as unknown attachment", async () => {
+    const note = await store.createNote("# T\n", { path: "t8" });
+    const attachment = await store.addAttachment(note.id, "2026-07-17/y.png", "image/png");
+    const provider = new FakeTicketProvider();
+    const tools = generateMcpTools(store, {
+      attachmentTickets: {
+        provider,
+        vaultName: "v1",
+        urlBase: "https://host/vault/v1",
+        noteVisible: async (_n: Note) => false,
+      },
+    });
+    const err = await expectToolError(findTool(tools, "request-attachment-download"), {
+      attachment_id: attachment.id,
+    });
+    expect(err.error_type).toBe("not_found");
+    expect(provider.tickets.size).toBe(0);
+  });
+});