@openparachute/vault 0.3.1 → 0.4.0

package/docs/auth-model.md

@@ -1,340 +0,0 @@
-# Auth model
-
-Reference for how Parachute Vault authenticates and authorizes requests. The
-**vault is auth-gated by default**: every route that touches vault data
-requires a credential. The narrow set of genuinely public routes (OAuth
-discovery, the service-info card, published notes) is listed explicitly in
-§2.
-
-This doc describes what the server does today. For the OAuth-issuer story
-that sits above this layer in the ecosystem, see
-[`design/2026-04-20-hub-as-portal-oauth-and-service-catalog.md`](../../parachute.computer/design/2026-04-20-hub-as-portal-oauth-and-service-catalog.md).
-
-## 1. Mechanisms
-
-Two first-class paths. Either works on its own; both can be active at once.
-A third, legacy path exists for back-compat.
-
-### OAuth 2.1 + PKCE + DCR
-
-The browser-based flow third-party clients use to connect. Implements:
-
-- **RFC 7591** Dynamic Client Registration — `POST /vault/<name>/oauth/register`
-- **RFC 6749 / OAuth 2.1** authorization code grant with **PKCE (S256 required)** —
-  `GET/POST /vault/<name>/oauth/authorize`, `POST /vault/<name>/oauth/token`
-- **RFC 8414** Authorization Server Metadata — `/.well-known/oauth-authorization-server`
-- **RFC 9728** Protected Resource Metadata — `/.well-known/oauth-protected-resource`
-
-Both path-append (`/vault/<name>/.well-known/<type>`) and path-insert
-(`/.well-known/<type>/vault/<name>`) discovery shapes are served; the
-path-insert form is what strict clients (e.g. Claude Code's MCP SDK) probe.
-
-**Clients that use this flow today:** claude.ai, ChatGPT, Claude Desktop,
-Claude Code, the Notes PWA.
-
-**Setup the owner must do first:**
-
-1. Run `parachute vault set-password` — bcrypt hash (cost 12) stored in
-   `~/.parachute/vault/config.yaml` as `owner_password_hash`. Minimum 12 chars.
-   Until this is set, the consent page falls back to legacy vault-token
-   auth (see §5).
-2. *(Optional)* Run `parachute vault 2fa enroll` — TOTP secret + backup codes
-   stored in the same global config. Requires an owner password to already
-   be set. After enrollment, the consent page additionally demands a TOTP
-   code or backup code.
-
-**Credential storage:**
-
-| Item | Location |
-|---|---|
-| Owner password hash | `~/.parachute/vault/config.yaml` (`owner_password_hash`) |
-| TOTP secret + backup codes | `~/.parachute/vault/config.yaml` (`totp_secret`, backup codes) |
-| Registered OAuth clients | Per-vault SQLite `oauth_clients` table |
-| Auth codes (10-min TTL, single-use) | Per-vault SQLite `oauth_codes` table, pinned to issuing vault |
-| Minted tokens | Per-vault SQLite `tokens` table (same table as API tokens) |
-
-**Token shape:** the successful `/oauth/token` exchange mints a standard
-`pvt_…` bearer token (see below) and returns it with `scope`, `vault`,
-`iss`, and a `services` catalog for ecosystem peers.
-
-**Rate limiting:** per-IP at the consent POST. 10 failed owner-auth
-attempts within 60 s triggers a 15-minute lockout (429 with `Retry-After`).
-In-memory; resets on process restart. Does not apply to the token endpoint
-or to bearer-auth attempts elsewhere.
-
-**Scopes the consent page offers:** `full` (maps to
-`vault:read vault:write vault:admin`) or `read` (maps to `vault:read`).
-The `scope=` query param is a hint — the user's radio-button selection wins.
-
-### API tokens (Bearer)
-
-Long-lived tokens for scripts, agents, and any client that won't drive a
-browser through consent.
-
-**Format:** `pvt_<32 base64url chars>`. Generated by
-`token-store.ts:generateToken`.
-
-**Storage:** per-vault SQLite `tokens` table. Only the SHA-256 hash
-(`sha256:…`) is stored; the plaintext token is shown once on creation.
-
-**Scopes** (persisted as a whitespace-separated string on the token row):
-
-- `vault:read` — GETs on `/api/*` and read-only MCP tools (`query-notes`,
-  `list-tags`, `find-path`, `vault-info`)
-- `vault:write` — all mutation routes and mutation MCP tools
-- `vault:admin` — `GET /.parachute/config`; inherits read + write
-
-Inheritance: `vault:admin ⊇ vault:write ⊇ vault:read`. The
-`vault:<name>:<verb>` shape is accepted as a synonym for `vault:<verb>`
-today (per-vault narrowing is a future phase).
-
-**Transport:** tokens are accepted in this priority order:
-
-1. `Authorization: Bearer <token>`
-2. `X-API-Key: <token>`
-3. `?key=<token>` query string (for MCP clients that can only carry a URL,
-   e.g. Claude Web)
-
-**CLI:**
-
-```
-parachute vault tokens create                         # full-access token, default vault
-parachute vault tokens create --read                  # vault:read only (shorthand for --scope vault:read)
-parachute vault tokens create --scope vault:write     # narrow to a specific scope
-parachute vault tokens create --scope vault:read,vault:write
-                                                      # comma-separated or repeated --scope
-parachute vault tokens create --vault <name>          # target a specific vault
-parachute vault tokens create --label <label>         # label for the `tokens list` output
-parachute vault tokens create --expires 30d           # optional TTL (h/d/w/m/y)
-parachute vault tokens list                           # list across all vaults (shows t_<prefix> IDs, never the plaintext)
-parachute vault tokens revoke <t_…>                   # delete by display ID or full hash
-```
-
-With no narrowing flag, a CLI-created token gets the full scope set
-(`vault:read vault:write vault:admin`) — unchanged for back-compat.
-`--scope` accepts any combination of `vault:read`, `vault:write`, and
-`vault:admin`; unrecognized scopes are rejected up front so a token is
-never minted with a scope the server can't enforce. `--scope` and
-`--read` cannot be combined (that ambiguity fails loudly rather than
-silently picking one).
-
-### Legacy: YAML `api_keys` and `X-API-Key`
-
-Older deployments stored keys as bcrypt hashes in
-`~/.parachute/vault/config.yaml` (`api_keys`) or per-vault in
-`~/.parachute/vault/<vault>/vault.yaml`. These keys had a `pvk_` prefix.
-
-Status: **still accepted for back-compat** and matched after the token-DB
-lookup fails. On `parachute vault init` they're migrated into each
-vault's `tokens` table. Each use logs a one-time deprecation warning
-(`[scopes] legacy permission-based auth used …`). Plan to remove one
-release after scope enforcement settles.
-
-The `X-API-Key` header itself is not legacy — it's still a supported
-transport for any `pvt_…` token.
-
-## 2. Endpoint-by-endpoint auth behavior
-
-Per-vault resources live under `/vault/<name>/…`. The table covers every
-route registered in `src/routing.ts`, `src/routes.ts`, and `src/mcp-http.ts`.
-
-### Cross-vault / origin-root
-
-| Path | Method | Auth required | Unauthenticated response | Notes |
-|---|---|---|---|---|
-| `/health` | GET | None (public by design) | `200 {"status":"ok"}` | With a valid bearer, additionally returns `vaults: […]`. Intentionally public so monitoring probes work without a secret. |
-| `/vaults/list` | GET | None (public by design) | `200 {"vaults":[…]}`, or `404` if `discovery: disabled` is set in global config | Leaks vault *names*. Opt out by setting `discovery: disabled` in `~/.parachute/vault/config.yaml`. |
-| `/vaults` | GET | Bearer (any scope) | `401 {"error":"Unauthorized", "message":"API key required"}` | Returns `{name, description, created_at}` per vault. |
-| `/.well-known/oauth-protected-resource/vault/<name>[/mcp]` | GET | None (RFC 9728 discovery) | `200 <metadata>` or `404` if vault not found | Public by spec — advertises where to authenticate. |
-| `/.well-known/oauth-authorization-server/vault/<name>[/mcp]` | GET | None (RFC 8414 discovery) | `200 <metadata>` or `404` if vault not found | Public by spec. |
-
-### Per-vault OAuth flow (`/vault/<name>/…`)
-
-These endpoints **are the auth**, so they cannot require auth themselves.
-
-| Path | Method | Auth required | Response |
-|---|---|---|---|
-| `/oauth/register` | POST | None (RFC 7591 DCR) | `201 {client_id, client_name, redirect_uris, …}` |
-| `/oauth/authorize` | GET | None (renders consent HTML) | `200 <consent page>` or `400 <error page>` |
-| `/oauth/authorize` | POST | Consent-form credentials (owner password or legacy vault token, plus TOTP/backup code if 2FA is on) | `302` to `redirect_uri?code=…` on success; re-renders consent on failure; `429` if rate-limited |
-| `/oauth/token` | POST | PKCE code_verifier + client_id + redirect_uri | `200 {access_token, token_type:"bearer", scope, vault, iss, services}` or `400 {error:"invalid_grant", …}` |
-| `/.well-known/oauth-protected-resource` | GET | None (discovery) | `200 <metadata>` |
-| `/.well-known/oauth-authorization-server` | GET | None (discovery) | `200 <metadata>` |
-
-### Per-vault service info + icon (hub integration)
-
-| Path | Method | Auth required | Response |
-|---|---|---|---|
-| `/vault/<name>/.parachute/info` | GET | None (public; `Access-Control-Allow-Origin: *`) | `200 {name, displayName, tagline, version, iconUrl, kind}` |
-| `/vault/<name>/.parachute/icon.svg` | GET | None (public; cached 1 h) | `200 <svg>` |
-| `/vault/<name>/.parachute/config/schema` | GET | None (public by design — schema is shape, not values) | `200 <JSON schema>` |
-| `/vault/<name>/.parachute/config` | GET | Bearer with `vault:admin` | `200 <config>`, `401` if no credential, `403 {error:"Forbidden", error_type:"insufficient_scope", required_scope:"vault:admin", granted_scopes:[…]}` otherwise |
-
-### Per-vault MCP + views + REST
-
-| Path | Method | Auth required | Unauthenticated response | Authenticated-but-underscoped response |
-|---|---|---|---|---|
-| `/vault/<name>/mcp[/…]` | any | Bearer (any vault scope) | `401 {error:"Unauthorized", …}` + `WWW-Authenticate: Bearer resource_metadata="…"` (RFC 9728 challenge) | Per-tool: read-only tools require `vault:read`; mutation tools require `vault:write`. Under-scoped `tools/call` returns `{isError:true, content:[…"requires the 'vault:write' scope"…]}`. Under-scoped tools are *also filtered out of `tools/list`*. |
-| `/vault/<name>/view/<idOrPath>` | GET | Auth-aware (see notes) | `404 Not Found` for private notes; `200 <html>` for published notes | — |
-| `/vault/<name>/public/<id>` | GET | Auth-aware (legacy alias) | `301` to `/vault/<name>/view/<id>` preserving `?key=…` | — |
-| `/vault/<name>` | GET | Bearer (any scope) | `401` | — |
-| `/vault/<name>/api/notes[/…]` | GET/HEAD | Bearer with `vault:read` | `401` | `403 {error:"Forbidden", error_type:"insufficient_scope", required_scope:"vault:read", granted_scopes:[…]}` |
-| `/vault/<name>/api/notes[/…]` | POST/PATCH/DELETE | Bearer with `vault:write` | `401` | `403` with `required_scope:"vault:write"` |
-| `/vault/<name>/api/tags[/…]` | GET | Bearer with `vault:read` | `401` | `403` |
-| `/vault/<name>/api/tags[/…]` | POST/PUT/DELETE | Bearer with `vault:write` | `401` | `403` |
-| `/vault/<name>/api/find-path` | GET | Bearer with `vault:read` | `401` | `403` |
-| `/vault/<name>/api/vault` | GET | Bearer with `vault:read` | `401` | `403` |
-| `/vault/<name>/api/vault` | PATCH | Bearer with `vault:write` | `401` | `403` |
-| `/vault/<name>/api/unresolved-wikilinks` | GET | Bearer with `vault:read` | `401` | `403` |
-| `/vault/<name>/api/storage/upload` | POST | Bearer with `vault:write` | `401` | `403` |
-| `/vault/<name>/api/storage/<path>` | GET | Bearer with `vault:read` | `401` | `403` |
-| `/vault/<name>/api/health` | GET | Bearer with `vault:read` | `401` | `403` |
-
-**`/view/<idOrPath>` notes:** always served over GET. Publication is
-determined by (a) the note carrying the `published_tag` from
-`vault.yaml` (default `publish`), or (b) `metadata.published === true`.
-An authenticated caller sees any note; an unauthenticated caller sees
-*only* published notes and gets `404` for everything else (same response
-shape as a missing note — we don't leak the existence of private notes).
-
-**Scope inheritance:** every `403` above resolves against
-`admin ⊇ write ⊇ read`. A token with `vault:admin` passes every scope
-gate; a `vault:write` token passes read gates; a `vault:read` token
-fails write gates.
-
-**MCP `tools/list` visibility:** tools the caller can't execute are
-hidden from the list, not just rejected on call. Read-only keys see
-`query-notes`, `list-tags`, `find-path`, `vault-info` and nothing else.
-
-## 3. What a user has to do
-
-Two setup paths. **Neither is a prerequisite for the other** — either
-works on its own, and running both is fine.
-
-### Path A: "I want humans (claude.ai, ChatGPT, Claude Desktop, …) to use this"
-
-```
-parachute vault set-password        # set the owner password
-parachute vault 2fa enroll          # (optional) add TOTP + backup codes
-```
-
-Then, in the client:
-
-- Add the vault's MCP URL (`https://…/vault/<name>/mcp`) as a connector.
-- The client does OAuth discovery → DCR → authorize → token exchange
-  automatically.
-- On the consent page, enter the owner password (and TOTP if enabled),
-  pick `Full access` or `Read-only access`, and click Authorize.
-- The client stores the minted `pvt_…` token and uses it from then on.
-
-### Path B: "I want a script or agent to use this"
-
-```
-parachute vault tokens create                            # full-access token in default vault
-parachute vault tokens create --read                     # read-only (shorthand for --scope vault:read)
-parachute vault tokens create --scope vault:write        # write-only token
-parachute vault tokens create --scope vault:read,vault:admin
-                                                         # combine scopes with a comma
-parachute vault tokens create --vault <name>             # specific vault
-parachute vault tokens create --expires 30d              # with TTL
-```
-
-The command prints the plaintext `pvt_…` once. Put it in the client's
-`Authorization: Bearer <token>` header (or `X-API-Key`, or `?key=`).
-Revoke with `parachute vault tokens revoke <t_…>`.
-
-The default (no narrowing flag) still mints a full-scope token. Pick a
-`--scope` to reduce blast radius; combining `--scope` with `--read` is
-an error (see §1 "API tokens").
-
-## 4. Default exposure posture
-
-The Bun server binds **`127.0.0.1`** by default (`src/server.ts`,
-resolved via `src/bind.ts`). The socket itself only accepts connections
-arriving on the loopback interface — LAN and public interfaces are not
-reachable unless the operator opts in. The startup log echoes the
-resolved hostname (`Parachute Vault server listening on
-http://127.0.0.1:1940`) so the bind is always visible.
-
-**Overriding the default**: set `VAULT_BIND` to bind a different
-interface. The two common reasons to override:
-
-- `VAULT_BIND=0.0.0.0` — accept traffic from every interface. Required
-  for **Docker bridge networking** (the container's virtual interface
-  isn't loopback from the server's perspective) and for intentional
-  **LAN setups** where another machine on the local network needs to
-  reach vault directly.
-- `VAULT_BIND=10.0.0.5` (or similar) — bind one specific interface IP
-  on a multi-homed host.
-
-Empty or whitespace-only `VAULT_BIND` is treated as unset.
-
-**Supported remote-access paths are unaffected by the loopback
-default.** `parachute expose tailnet` (Tailscale Serve) and `parachute
-expose public` (Cloudflare Tunnel) both proxy *from* loopback — they
-connect to `127.0.0.1:1940` on the local host and forward the decrypted
-traffic in. Neither needs `VAULT_BIND` set. The auth model does not
-change when you expose: those commands don't rewrite auth rules, they
-just change *which networks can attempt to reach* an already
-auth-gated server. Everything in §2 still applies — the bearer gate,
-the scope gate, the OAuth flow, the public-by-design endpoints. When
-you expose, the public-by-design endpoints (`/health`, `/vaults/list`,
-`/.well-known/*`, OAuth discovery, `/.parachute/info`,
-`/.parachute/icon.svg`, `/.parachute/config/schema`, published notes
-at `/view/…`) become reachable from wherever you exposed to. Treat
-that as part of the threat model, not as a bug.
-
-## 5. Known rough edges
-
-Honest list. Things a user might trip over, or that the launch copy
-should be careful about.
-
-- **OAuth does not strictly require an owner password.** If none is set,
-  the consent page falls back to asking for a `pvt_…` vault token as
-  proof of ownership. This works, but means the "launch flow" is still
-  operable without ever running `set-password`. Recommended: require the
-  password in docs, even though the server doesn't enforce it.
-- **CLI-created tokens still default to full scope.** `parachute vault
-  tokens create` with no flags produces a token with
-  `vault:read vault:write vault:admin`, unchanged for back-compat.
-  Narrowing is now available via `--scope vault:read`, `--scope
-  vault:read,vault:write`, etc. (see §1 "API tokens") — the scriptwriter
-  who only wants write can now mint exactly that. The *default* is still
-  a footgun for users who don't know to narrow it.
-- **Tokens are per-vault, not vault-wide.** A token lives in one vault's
-  SQLite DB. Exception: when presented to the unified `/mcp` endpoint
-  (no vault in the URL), auth scans every vault's token table, so an
-  OAuth-minted token still works there. A CLI-created token is only
-  valid against the vault it was created in.
-- **Rate limiting only applies to the OAuth consent POST.** Ten failed
-  owner-auth attempts in 60 s → 15-minute per-IP lockout. There is **no
-  bearer-token brute-force limit** — an attacker hammering
-  `/vault/<name>/api/notes` with random `pvt_…` guesses is not rate
-  limited. The guessing space (≈190 bits) makes this academic but worth
-  knowing when planning exposure.
-- **Public-by-design endpoints leak structural info.** `/health` (with
-  auth) and `/vaults/list` (by default, disable with `discovery:
-  disabled`) reveal which vaults exist. `/.well-known/oauth-*` reveals
-  that a vault exists at `/vault/<name>`. `/.parachute/info` reveals the
-  running version. All of these are intentional, but each is
-  discoverable by anyone who can reach the server.
-- **Published notes bypass auth by design.** `/vault/<name>/view/<id>`
-  serves any note tagged with `published_tag` (default `publish`) or
-  carrying `metadata.published: true` as HTML with no credential. If a
-  user inadvertently tags a private note `publish`, the whole internet
-  sees it once the vault is exposed.
-- **Legacy `pvk_` keys and `X-API-Key` keep working.** Pre-v0.3 users'
-  YAML-stored `pvk_` keys are accepted and migrated on init; each use
-  logs a one-time deprecation warning. Plan removal is "one release
-  after scope enforcement settles" (not yet scheduled).
-- **`WWW-Authenticate` challenges are only added on `/mcp` 401s.** The
-  REST API returns plain `401 {error:"Unauthorized"}` without an RFC
-  9728 challenge header. A generic HTTP client won't auto-discover the
-  authorization server from a REST 401 — that's fine (clients that care
-  use the MCP path), but REST API consumers must read the OAuth
-  metadata document explicitly.
-- **`TRUST_PROXY=1` is not the default.** Rate limiting uses the socket
-  peer IP unless `TRUST_PROXY` is set, in which case it honors
-  `X-Forwarded-For`. A deployment behind Cloudflare Tunnel / nginx
-  without `TRUST_PROXY=1` will rate-limit against the proxy's IP
-  (typically loopback), effectively disabling per-user lockout.

package/fly.toml

@@ -1,24 +0,0 @@
-app = "parachute-vault"
-primary_region = "iad"
-
-[build]
-  dockerfile = "Dockerfile"
-
-[env]
-  PORT = "1940"
-  PARACHUTE_HOME = "/data"
-
-[http_service]
-  internal_port = 1940
-  force_https = true
-  auto_stop_machines = "stop"
-  auto_start_machines = true
-  min_machines_running = 0
-
-[[vm]]
-  size = "shared-cpu-1x"
-  memory = "512mb"
-
-[[mounts]]
-  source = "vault_data"
-  destination = "/data"

package/package/package.json

@@ -1,32 +0,0 @@
-{
-  "name": "@openparachute/vault",
-  "version": "0.2.4",
-  "description": "Agent-native knowledge graph. Notes, tags, links over MCP.",
-  "module": "src/cli.ts",
-  "type": "module",
-  "bin": {
-    "parachute-vault": "src/cli.ts"
-  },
-  "scripts": {
-    "start": "bun src/server.ts",
-    "cli": "bun src/cli.ts",
-    "test": "bun test src/",
-    "test:core": "cd core && node --experimental-vm-modules node_modules/vitest/dist/cli.js run"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.12.1",
-    "otpauth": "^9.5.0",
-    "qrcode-terminal": "^0.12.0"
-  },
-  "devDependencies": {
-    "@types/bun": "latest"
-  },
-  "peerDependencies": {
-    "typescript": "^5"
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/ParachuteComputer/parachute-vault.git"
-  },
-  "license": "AGPL-3.0"
-}

package/railway.json

@@ -1,14 +0,0 @@
-{
-  "$schema": "https://railway.com/railway.schema.json",
-  "build": {
-    "builder": "DOCKERFILE",
-    "dockerfilePath": "Dockerfile"
-  },
-  "deploy": {
-    "startCommand": "bun src/server.ts",
-    "healthcheckPath": "/health",
-    "healthcheckTimeout": 5,
-    "restartPolicyType": "ON_FAILURE",
-    "restartPolicyMaxRetries": 3
-  }
-}

package/scripts/migrate-audio-to-opus.test.ts

@@ -1,237 +0,0 @@
-/**
- * Tests for scripts/migrate-audio-to-opus.ts.
- *
- * Spins up a temp vault layout under a fresh PARACHUTE_HOME, seeds a WAV
- * attachment, runs the script in dry-run then real mode, asserts the DB
- * row was rewritten, the .ogg file exists, and the original was unlinked.
- *
- * Uses the real ffmpeg binary (matches src/audio-encoding.test.ts).
- *
- * Requires `@openparachute/narrate` which is not a vault dependency.
- * Install manually (`bun add @openparachute/narrate`) to run these tests.
- */
-
-import { describe, test, expect, beforeEach, afterEach } from "bun:test";
-import { Database } from "bun:sqlite";
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "fs";
-import { join } from "path";
-import { tmpdir } from "os";
-import { SCHEMA_SQL } from "../core/src/schema.ts";
-
-// @openparachute/narrate is not a vault dependency — dynamically import
-// so the test file can at least be parsed without the optional package.
-let runMigration: typeof import("./migrate-audio-to-opus.ts").runMigration;
-let hasDep = false;
-try {
-  ({ runMigration } = await import("./migrate-audio-to-opus.ts"));
-  hasDep = true;
-} catch {
-  // dependency missing — tests will be skipped below
-}
-
-function buildSilentWav(samples: number): Buffer {
-  const sampleRate = 8000;
-  const numChannels = 1;
-  const bitsPerSample = 16;
-  const byteRate = (sampleRate * numChannels * bitsPerSample) / 8;
-  const blockAlign = (numChannels * bitsPerSample) / 8;
-  const dataSize = samples * blockAlign;
-  const chunkSize = 36 + dataSize;
-  const buf = Buffer.alloc(44 + dataSize);
-  let off = 0;
-  buf.write("RIFF", off); off += 4;
-  buf.writeUInt32LE(chunkSize, off); off += 4;
-  buf.write("WAVE", off); off += 4;
-  buf.write("fmt ", off); off += 4;
-  buf.writeUInt32LE(16, off); off += 4;
-  buf.writeUInt16LE(1, off); off += 2;
-  buf.writeUInt16LE(numChannels, off); off += 2;
-  buf.writeUInt32LE(sampleRate, off); off += 4;
-  buf.writeUInt32LE(byteRate, off); off += 4;
-  buf.writeUInt16LE(blockAlign, off); off += 2;
-  buf.writeUInt16LE(bitsPerSample, off); off += 2;
-  buf.write("data", off); off += 4;
-  buf.writeUInt32LE(dataSize, off); off += 4;
-  return buf;
-}
-
-let tmpHome: string;
-let prevHome: string | undefined;
-let prevAssets: string | undefined;
-
-beforeEach(() => {
-  tmpHome = join(
-    tmpdir(),
-    `migrate-test-${Date.now()}-${Math.random().toString(36).slice(2)}`,
-  );
-  mkdirSync(tmpHome, { recursive: true });
-  prevHome = process.env.PARACHUTE_HOME;
-  prevAssets = process.env.ASSETS_DIR;
-  process.env.PARACHUTE_HOME = tmpHome;
-  delete process.env.ASSETS_DIR; // use default per-vault assets dir
-});
-
-afterEach(() => {
-  if (prevHome === undefined) delete process.env.PARACHUTE_HOME;
-  else process.env.PARACHUTE_HOME = prevHome;
-  if (prevAssets === undefined) delete process.env.ASSETS_DIR;
-  else process.env.ASSETS_DIR = prevAssets;
-  try {
-    rmSync(tmpHome, { recursive: true, force: true });
-  } catch {
-    // ignore
-  }
-});
-
-interface SeedResult {
-  vault: string;
-  dbPath: string;
-  assetsBase: string;
-  noteId: string;
-  attachmentId: string;
-  relWavPath: string;
-  absWavPath: string;
-  relOggPath: string;
-  absOggPath: string;
-  noteUpdatedAt: string;
-}
-
-function seedVaultWithWav(vaultName: string): SeedResult {
-  const vaultDir = join(tmpHome, "vaults", vaultName);
-  mkdirSync(vaultDir, { recursive: true });
-  const dbPath = join(vaultDir, "vault.db");
-  const assetsBase = join(vaultDir, "assets");
-  mkdirSync(assetsBase, { recursive: true });
-
-  const db = new Database(dbPath);
-  db.exec(SCHEMA_SQL);
-
-  const noteId = "n_" + Math.random().toString(36).slice(2, 10);
-  const attachmentId = "a_" + Math.random().toString(36).slice(2, 10);
-  const now = new Date().toISOString();
-
-  db.prepare(
-    "INSERT INTO notes (id, content, path, metadata, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?)",
-  ).run(noteId, "hello reader", null, "{}", now, now);
-
-  const relWavPath = `tts/2026-04-08/${noteId}-123.wav`;
-  const absWavPath = join(assetsBase, relWavPath);
-  mkdirSync(join(assetsBase, "tts", "2026-04-08"), { recursive: true });
-  // Write ~1s of silence WAV. ffmpeg handles this fine.
-  writeFileSync(absWavPath, buildSilentWav(8000));
-
-  db.prepare(
-    "INSERT INTO attachments (id, note_id, path, mime_type, metadata, created_at) VALUES (?, ?, ?, ?, ?, ?)",
-  ).run(attachmentId, noteId, relWavPath, "audio/wav", "{}", now);
-
-  db.close();
-
-  return {
-    vault: vaultName,
-    dbPath,
-    assetsBase,
-    noteId,
-    attachmentId,
-    relWavPath,
-    absWavPath,
-    relOggPath: relWavPath.replace(/\.wav$/, ".ogg"),
-    absOggPath: absWavPath.replace(/\.wav$/, ".ogg"),
-    noteUpdatedAt: now,
-  };
-}
-
-describe.skipIf(!hasDep)("migrate-audio-to-opus", () => {
-  test("dry-run reports candidates without touching anything", async () => {
-    const seed = seedVaultWithWav("default");
-
-    const logs: string[] = [];
-    const origLog = console.log;
-    console.log = (...args: unknown[]) => {
-      logs.push(args.map((a) => String(a)).join(" "));
-    };
-    try {
-      const summaries = await runMigration(["--vault", "default", "--dry-run"]);
-      expect(summaries.length).toBe(1);
-      expect(summaries[0].dryRunCandidates).toBe(1);
-      expect(summaries[0].converted).toBe(0);
-      expect(summaries[0].errors).toBe(0);
-    } finally {
-      console.log = origLog;
-    }
-
-    expect(logs.some((l) => l.includes("DRY-RUN convert") && l.includes(seed.relWavPath))).toBe(
-      true,
-    );
-
-    // Nothing moved.
-    expect(existsSync(seed.absWavPath)).toBe(true);
-    expect(existsSync(seed.absOggPath)).toBe(false);
-
-    const db = new Database(seed.dbPath);
-    try {
-      const row = db
-        .prepare("SELECT path, mime_type FROM attachments WHERE id = ?")
-        .get(seed.attachmentId) as { path: string; mime_type: string };
-      expect(row.path).toBe(seed.relWavPath);
-      expect(row.mime_type).toBe("audio/wav");
-    } finally {
-      db.close();
-    }
-  });
-
-  test("full run converts WAV to Opus, updates DB, unlinks original, no updated_at bump", async () => {
-    const seed = seedVaultWithWav("default");
-
-    const origLog = console.log;
-    console.log = () => {};
-    try {
-      const summaries = await runMigration(["--vault", "default"]);
-      expect(summaries[0].converted).toBe(1);
-      expect(summaries[0].errors).toBe(0);
-      expect(summaries[0].bytesAfter).toBeGreaterThan(0);
-    } finally {
-      console.log = origLog;
-    }
-
-    // Original .wav removed, .ogg exists and has OggS magic bytes.
-    expect(existsSync(seed.absWavPath)).toBe(false);
-    expect(existsSync(seed.absOggPath)).toBe(true);
-    const oggBytes = readFileSync(seed.absOggPath);
-    expect(oggBytes.toString("ascii", 0, 4)).toBe("OggS");
-
-    // DB row rewritten.
-    const db = new Database(seed.dbPath);
-    try {
-      const row = db
-        .prepare("SELECT path, mime_type FROM attachments WHERE id = ?")
-        .get(seed.attachmentId) as { path: string; mime_type: string };
-      expect(row.path).toBe(seed.relOggPath);
-      expect(row.mime_type).toBe("audio/ogg");
-
-      // Note's updated_at must NOT have changed — this is a storage
-      // migration, not a content edit.
-      const note = db
-        .prepare("SELECT updated_at FROM notes WHERE id = ?")
-        .get(seed.noteId) as { updated_at: string };
-      expect(note.updated_at).toBe(seed.noteUpdatedAt);
-    } finally {
-      db.close();
-    }
-  });
-
-  test("re-running after a successful migration is a no-op (idempotent)", async () => {
-    seedVaultWithWav("default");
-
-    const origLog = console.log;
-    console.log = () => {};
-    try {
-      await runMigration(["--vault", "default"]);
-      const second = await runMigration(["--vault", "default"]);
-      expect(second[0].converted).toBe(0);
-      expect(second[0].skipped).toBe(1);
-      expect(second[0].errors).toBe(0);
-    } finally {
-      console.log = origLog;
-    }
-  });
-});