@openparachute/vault 0.7.3-rc.1 → 0.7.3-rc.11

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/bytes-provider.ts

@@ -0,0 +1,65 @@
+/**
+ * `AttachmentBytesProvider` — the model-lane (Wave 2) byte-access seam.
+ * Mirrors `AttachmentTicketProvider` (`./tickets.ts`): a per-door
+ * implementation binds this to its own storage (bun: local fs, see
+ * `src/attachment-bytes.ts`; a future cloud implementation: ranged R2 GETs
+ * through the vault DO). Core stays storage-unaware — the `read-attachment`
+ * tool (`core/src/mcp.ts`) calls only through this interface, so bun and a
+ * future cloud implementation can never drift on the read contract.
+ *
+ * Deliberately narrow: stat + a bounded positional read, plus one optional
+ * hook for the audio transcript pointer. All POLICY (mime-family dispatch,
+ * size caps, range validation, tag-scope) lives in the `read-attachment`
+ * tool itself — same division as the ticket seam (`GenerateMcpToolsOpts`'s
+ * doc comment in `core/src/mcp.ts`).
+ *
+ * D10 (attachments-for-agents design): "tools omitted when unwired" — a
+ * door that hasn't wired this seam simply never passes `attachmentBytes` to
+ * `generateMcpTools`, so `read-attachment` is absent from `tools/list`
+ * entirely, not merely erroring on call.
+ */
+
+import type { Attachment } from "../types.js";
+
+/**
+ * 4 MiB raw-bytes cap on the image branch of `read-attachment` (D3): the
+ * largest honest budget under Claude's ~5 MB image API limit, with room for
+ * base64 blow-up (~5.6 MiB on the wire) and DO-transient headroom on a
+ * future cloud implementation. Enforced BEFORE a read is attempted — the
+ * tool calls `stat()` first and refuses over-cap without ever calling
+ * `readRange()`.
+ */
+export const MAX_ATTACHMENT_IMAGE_BYTES = 4 * 1024 * 1024;
+
+export interface AttachmentBytesProvider {
+  /**
+   * Byte size of the attachment's stored bytes, or `null` when the row
+   * exists but its bytes don't — e.g. an `audio_retention` eviction after a
+   * successful transcription (`src/transcription-worker.ts` unlinks the
+   * file on `until_transcribed` / `never` retention), or any other
+   * out-of-band loss. Drives the `attachment_binary_missing` refusal.
+   */
+  stat(attachment: Attachment): Promise<{ size: number } | null>;
+  /**
+   * Read the half-open byte range `[start, end)`. Bounded by construction —
+   * callers never ask for the whole file when only a window is needed (the
+   * text path); the image path DOES read start-to-end, but only after
+   * `stat()` has already confirmed the file is under
+   * {@link MAX_ATTACHMENT_IMAGE_BYTES}. `start`/`end` are always within
+   * `[0, size]` as reported by a prior `stat()` call on the same attachment
+   * — implementations don't need to re-clamp defensively, though doing so
+   * costs nothing.
+   */
+  readRange(attachment: Attachment, start: number, end: number): Promise<Uint8Array>;
+  /**
+   * OPTIONAL: resolve the sibling transcript note for a completed
+   * audio/video transcription (bun: `<attachment-path>.transcript`, see
+   * `transcriptPathFor` in `src/transcript-note.ts`). Omitted by a door
+   * whose transcript instead lives in the owning note's body (the design's
+   * cloud path, D... — no separate sibling note to point at) — the
+   * `read-attachment` audio branch falls back to `note_id` alone (the
+   * owning note) in that case, per the design's "on cloud the transcript
+   * lives in the owning note's body, so `note_id` is the pointer."
+   */
+  resolveTranscriptNote?(attachment: Attachment): Promise<{ id: string; path: string } | null>;
+}

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("");
+}