feat(vault): POST /api/internal/destroy — vault erasure (cloud#226 PR-1)

[unforced]

Summary

PR-1 of the vault-delete train (#226). Builds the piece that actually erases data: POST /vault/<name>/api/internal/destroy. Independently useful today — with it, an operator bearer can tear down a vault via API instead of hand-written SQL (yesterday's staging reclamation needed exactly this).

Scope: workers/vault only. No identity changes, nothing user-facing.

What it does (in order)

1. Closes every hibernatable WebSocket with code 1001 (Going Away) — live-query sockets die now instead of lingering to TTL.
2. Purges every R2 object under vault-<name>/ — one prefix pass covers all three families (attachments/, snapshots/, exports/), via a new purgePrefix generalized from the existing purgeAttachments. The trailing slash is load-bearing (vault-foo/ must not match vault-foobar/) — pinned by a dedicated test.
3. ctx.storage.deleteAlarm() then ctx.storage.deleteAll() — in that order, since deleteAll() does not clear a pending alarm, and this DO arms transcription/embedding alarms that must not fire against a destroyed vault.
4. Sets an in-memory destroyed flag. Every later request on this warm instance answers 410 and writes nothing.
5. Responds { destroyed: true, r2_objects_deleted: n }.

Authorization

Unchanged — the pre-existing internalForbidden gate (first-party client_id + admin scope, or the VAULT_AUTH_TOKEN operator bearer). No new scheme. confirm:"<vault name>" (exact match, lowercased) in the body is defense-in-depth at the internal seam, not the primary guard.

A deliberate dispatch-ordering choice

/api/internal/destroy is dispatched at the very top of fetch(), before ensureState() — not inside the normal /api/internal/* block. This is required, not stylistic: ensureState()'s maybeArmEmbeddingBackfill re-arms the embedding alarm on every wake unless the backfill is already known-done, which would re-fire the very alarm this endpoint just cleared. Running the destroy route (including idempotent retries) ahead of ensureState() is what keeps a warm-but-destroyed instance from resurrecting any state. Every other route on an already-destroyed warm instance also short-circuits to 410 ahead of ensureState(), for the same reason.

What residue remains (said explicitly, not implied away)

The DO's idFromName mapping is permanent — a later stray request re-materializes an empty-schema DO (~KB, zero tenant data). That's the same property any never-created vault name already has; this PR does not (and cannot, from the vault worker alone) erase the identity-side ownership record or D1 rows. That's later PRs in the train.

Tests (workerd, workers/vault/test/destroy.test.ts, 6 new tests)

Seeded a vault with a note, an attachment, a snapshot, and an export so all three R2 prefixes are populated:

1. Destroy with a first-party token → 200; all R2 objects under vault-<name>/ gone, count matches.
2. Prefix-boundary pin: an object under vault-<name>x/ survives — the test most likely to be skipped, included deliberately.
3. Warm-instance follow-up (read AND write shaped) → 410; ground-truth-verified via runInDurableObject that DO storage is empty and no alarm got re-armed.
4. A tenant-shaped OAuth admin token (non-first-party client_id) → the existing internal_config_forbidden 403.
5. Confirm mismatch / missing confirm → 400.
6. Second destroy → 200 no-op, idempotent (the identity-side cascade retries this).

Each of the 6 tests was verified red on a stubbed-out version of the fix (documented failure per test, then restored) before being trusted green.

Gates

• bun run typecheck (root + workers/vault): clean.
• cd workers/vault && bun x vitest run: 27 files, 408 passed, 1 todo (pre-existing todo, unrelated).
• No orphaned workerd processes left running.
• bun scripts/smoke-staging.ts was not run (per instructions — it creates live staging debris).

🤖 Generated with Claude Code

https://claude.ai/code/session_01XLZtmuSs1RirWGMGyCB1QB