@openparachute/vault 0.6.4-rc.8 → 0.6.4

package/src/routes.ts

@@ -12,7 +12,7 @@
  */
 
 import type { Store, Note, QueryOpts } from "../core/src/types.ts";
-import { TAG_EXPAND_MODES, type TagExpandMode } from "../core/src/tag-hierarchy.ts";
+import { TAG_EXPAND_MODES, stripTagHash, type TagExpandMode } from "../core/src/tag-hierarchy.ts";
 import { listUnresolvedWikilinks } from "../core/src/wikilinks.ts";
 import { getNote, getNotes, getNoteTags, toNoteIndex, filterMetadata, mergeMetadata, MAX_BATCH_SIZE, validateExtension, ExtensionValidationError } from "../core/src/notes.ts";
 import {
@@ -27,6 +27,8 @@ import { logStrictBypass } from "./scopes.ts";
 import * as linkOps from "../core/src/links.ts";
 import * as tagSchemaOps from "../core/src/tag-schemas.ts";
 import { IndexedFieldError } from "../core/src/indexed-fields.ts";
+import { buildVaultProjection, resolveTagInheritance } from "../core/src/vault-projection.ts";
+import { loadSchemaConfig } from "../core/src/schema-defaults.ts";
 import {
   buildExpandVisibility,
   filterHydratedLinksByTagScope,
@@ -1997,6 +1999,64 @@ export async function handleTags(
     return json(result);
   }
 
+  // POST /tags/:name/conformance — count existing notes that would VIOLATE a
+  // proposed field spec for the tag (vault#283 tightening warning). Read-only
+  // (POST because it carries a proposed `fields` body). Must precede the
+  // /:name matcher so "conformance" isn't read as a tag name.
+  const conformanceMatch = subpath.match(/^\/([^/]+)\/conformance$/);
+  if (conformanceMatch) {
+    if (req.method !== "POST") return json({ error: "Method not allowed" }, 405);
+    const cTag = decodeURIComponent(conformanceMatch[1]!);
+    if (tagScope.allowed && !tagScope.allowed.has(cTag)) {
+      return json({ error: "Tag not found", tag: cTag }, 404);
+    }
+    const body = (await req.json().catch(() => null)) as
+      | { fields?: Record<string, unknown> | null }
+      | null;
+    if (!body) return json({ error: "Invalid JSON body" }, 400);
+    // The proposed fields the operator intends to save. Sanitized through the
+    // same parse the resolver uses (drop non-object specs). Empty/absent →
+    // nothing to enforce → zero violations.
+    const proposed: Record<string, tagSchemaOps.TagFieldSchema> = {};
+    if (body.fields && typeof body.fields === "object" && !Array.isArray(body.fields)) {
+      for (const [k, v] of Object.entries(body.fields)) {
+        if (v && typeof v === "object" && !Array.isArray(v)) {
+          proposed[k] = v as tagSchemaOps.TagFieldSchema;
+        }
+      }
+    }
+    const report = await store.countTagConformance(cTag, proposed);
+    return json(report);
+  }
+
+  // GET /tags/:name/effective — the tag's effective (own ∪ inherited) fields +
+  // direct/effective parents + schema-conflict info, drawn from the same
+  // projection vault-info exposes. Read-only inheritance preview for the
+  // Schema editor (vault#283). Must precede the /:name matcher.
+  const effectiveMatch = subpath.match(/^\/([^/]+)\/effective$/);
+  if (effectiveMatch) {
+    if (req.method !== "GET") return json({ error: "Method not allowed" }, 405);
+    const eTag = decodeURIComponent(effectiveMatch[1]!);
+    if (tagScope.allowed && !tagScope.allowed.has(eTag)) {
+      return json({ error: "Tag not found", tag: eTag }, 404);
+    }
+    const projection = buildVaultProjection(store.db);
+    const record = await store.getTagRecord(eTag);
+    // Resolve inheritance directly (not via projection.tags, which omits
+    // hierarchy-only tags carrying no own schema) so the editor's preview
+    // works even for a tag the operator is just starting to give fields.
+    const resolved = loadSchemaConfig(store.db);
+    const { effective_parents, effective_fields } = resolveTagInheritance(resolved, eTag);
+    return json({
+      name: eTag,
+      parents: record?.parent_names ?? [],
+      effective_parents,
+      fields: record?.fields ?? null,
+      effective_fields,
+      indexed_fields: projection.indexed_fields,
+    });
+  }
+
   // Routes with tag name
   const nameMatch = subpath.match(/^\/([^/]+)$/);
   if (!nameMatch) return json({ error: "Not found" }, 404);
@@ -2026,7 +2086,15 @@ export async function handleTags(
   // of { description, fields, relationships, parent_names }; omitted keys
   // are preserved, explicit null clears. See patterns/tag-data-model.md.
   if (req.method === "PUT") {
-    if (tagScope.allowed && !tagScope.allowed.has(tagName)) {
+    // Canonical-bare-tag guard (vault#XXX): normalize the upserted tag NAME so
+    // the existing-field merge read (store.getTagSchema below) and the upsert
+    // both target the bare row. store.upsertTagRecord re-normalizes (idempotent)
+    // for the write; this keeps the partial-merge read correct for a
+    // `#`-decorated PUT path. (GET/DELETE/rename keep their literal lookups —
+    // rename's source-name must still match a `#`-prefixed legacy row so the
+    // data migration can rename it away.)
+    const putTagName = stripTagHash(tagName);
+    if (tagScope.allowed && !tagScope.allowed.has(putTagName)) {
       return tagScopeForbidden(tagScope.raw ?? []);
     }
     const body = (await req.json()) as {
@@ -2034,7 +2102,18 @@ export async function handleTags(
       fields?: Record<string, unknown> | null;
       relationships?: Record<string, unknown> | null;
       parent_names?: unknown;
+      /**
+       * When true, `fields` is treated as the FULL intended field map for the
+       * tag — fields absent from the payload are DROPPED (a replace, not a
+       * merge). Default false preserves the historical partial-update merge
+       * the MCP `update-tag` tool relies on (omitted keys preserved). The
+       * Schema editor (vault#283) sends the full map + `replace_fields: true`
+       * so removing a field row actually deletes the field. See
+       * patterns/tag-data-model.md.
+       */
+      replace_fields?: unknown;
     };
+    const replaceFields = body.replace_fields === true;
 
     // Validate the relationships payload up front so a bad payload returns
     // 400, not a thrown 500. `relationships` is an opaque vocabulary map
@@ -2071,7 +2150,10 @@ export async function handleTags(
     }
 
     // Field merge mirrors MCP update-tag — preserves prior keys when the
-    // payload only declares new ones.
+    // payload only declares new ones. UNLESS `replace_fields: true`, in which
+    // case `fields` is the full intended map and absent keys are dropped (the
+    // Schema editor's full-replacement save — vault#283; without this a
+    // removed field row is silently resurrected by the merge).
     let fieldsPatch:
       | Record<string, tagSchemaOps.TagFieldSchema>
       | null
@@ -2079,12 +2161,17 @@ export async function handleTags(
     if (body.fields === null) {
       fieldsPatch = null;
     } else if (body.fields !== undefined) {
-      const existing = await store.getTagSchema(tagName);
-      const merged: Record<string, tagSchemaOps.TagFieldSchema> = {
-        ...(existing?.fields ?? {}),
-        ...(body.fields as Record<string, tagSchemaOps.TagFieldSchema>),
-      };
-      fieldsPatch = Object.keys(merged).length > 0 ? merged : null;
+      if (replaceFields) {
+        const full = body.fields as Record<string, tagSchemaOps.TagFieldSchema>;
+        fieldsPatch = Object.keys(full).length > 0 ? full : null;
+      } else {
+        const existing = await store.getTagSchema(putTagName);
+        const merged: Record<string, tagSchemaOps.TagFieldSchema> = {
+          ...(existing?.fields ?? {}),
+          ...(body.fields as Record<string, tagSchemaOps.TagFieldSchema>),
+        };
+        fieldsPatch = Object.keys(merged).length > 0 ? merged : null;
+      }
     }
 
     // A bad indexed-field name (or an unindexable type, or a cross-tag type
@@ -2093,7 +2180,7 @@ export async function handleTags(
     // unchanged on failure (no orphan/lying index). vault#478.
     let result;
     try {
-      result = await store.upsertTagRecord(tagName, {
+      result = await store.upsertTagRecord(putTagName, {
         ...(body.description !== undefined ? { description: body.description } : {}),
         ...(fieldsPatch !== undefined ? { fields: fieldsPatch } : {}),
         ...(relationshipsPatch !== undefined ? { relationships: relationshipsPatch } : {}),
@@ -2821,32 +2908,96 @@ async function handleRetryLegacyInBody(
 
 const MAX_UPLOAD_BYTES = 100 * 1024 * 1024; // 100MB
 
-// Storage allowlist policy:
-//   - audio + image + .pdf (knowledge-vault content: papers, scans, receipts)
-//     + .mp4 (mobile capture default; iOS records mp4, not webm).
-//   - .svg and .html are deliberately excluded — both can embed `<script>`
-//     tags, which would turn an upload into a same-origin XSS vector when
-//     the asset is served back from /storage/. If a future use case needs
-//     SVG, sanitize on read (strip <script>/<foreignObject>) and revisit.
-const ALLOWED_EXTENSIONS = new Set([
-  ".wav", ".mp3", ".m4a", ".ogg", ".webm",
-  ".png", ".jpg", ".jpeg", ".gif", ".webp",
-  ".pdf", ".mp4",
+// 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",
-  ".pdf": "application/pdf",
+  ".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",
 };
 
 export async function handleStorage(
@@ -2867,9 +3018,17 @@ export async function handleStorage(
     if (file.size > MAX_UPLOAD_BYTES) {
       return json({ error: `File too large (${Math.round(file.size / 1024 / 1024)}MB). Max: 100MB` }, 413);
     }
-    const ext = extname(file.name).toLowerCase();
-    if (!ALLOWED_EXTENSIONS.has(ext)) {
-      return json({ error: `File type ${ext} not allowed` }, 400);
+    // Strip trailing dots/whitespace before extracting the extension so a
+    // `evil.html.` / `evil.svg ` can't slip past the blocklist
+    // (extname("evil.html.") === "."). The blocklist is belt-and-suspenders;
+    // anything that still gets through serves as octet-stream + nosniff anyway.
+    const ext = extname(file.name.replace(/[.\s]+$/, "")).toLowerCase();
+    if (BLOCKED_EXTENSIONS.has(ext)) {
+      // Active-content types only — blocked because they execute as script when
+      // served same-origin from /storage/ (see BLOCKED_EXTENSIONS). Everything
+      // else (incl. unknown/arbitrary files) is accepted and served as a
+      // download (octet-stream + nosniff).
+      return json({ error: `File type ${ext} not allowed (active/executable content)` }, 400);
     }
 
     const date = new Date().toISOString().split("T")[0]!;
@@ -2970,6 +3129,12 @@ export async function handleStorage(
       headers: {
         "Content-Type": contentType,
         "Content-Length": String(stat.size),
+        // Defense-in-depth: never let a browser MIME-sniff a stored asset into
+        // an active type (e.g. an octet-stream body sniffed as text/html).
+        // Combined with the upload blocklist (no .svg/.html) this closes the
+        // same-origin XSS surface for served attachments. Mirrors routing.ts's
+        // SPA-asset stance.
+        "X-Content-Type-Options": "nosniff",
       },
     });
   }

package/src/routing.test.ts

@@ -1956,6 +1956,131 @@ describe("scope enforcement on /api/*", () => {
     expect(res.status).toBe(200);
   });
 
+  // ----- vault#283: Schema editor read endpoints -------------------------
+
+  test("POST /api/tags/:name/conformance → counts notes violating a proposed spec", async () => {
+    createVault("journal");
+    const store = getVaultStore("journal");
+    await store.createNote("ok", { tags: ["task"], metadata: { status: "open" } });
+    await store.createNote("missing", { tags: ["task"], metadata: {} });
+    const admin = await createAdminToken("journal");
+
+    const path = "/vault/journal/api/tags/task/conformance";
+    const res = await route(
+      new Request(`http://localhost:1940${path}`, {
+        method: "POST",
+        headers: { authorization: `Bearer ${admin}`, "content-type": "application/json" },
+        body: JSON.stringify({ fields: { status: { type: "string", required: true } } }),
+      }),
+      path,
+    );
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as {
+      tag: string;
+      total_notes: number;
+      violating_notes: number;
+      checked_fields: string[];
+    };
+    expect(body.tag).toBe("task");
+    expect(body.total_notes).toBe(2);
+    expect(body.violating_notes).toBe(1);
+    expect(body.checked_fields).toEqual(["status"]);
+  });
+
+  test("POST /api/tags/:name/conformance is read-only — a read token may run it", async () => {
+    createVault("journal");
+    const store = getVaultStore("journal");
+    await store.createNote("missing", { tags: ["task"], metadata: {} });
+    const readToken = await mintToken("journal", {
+      permission: "read",
+      scopes: ["vault:read"],
+    });
+
+    const path = "/vault/journal/api/tags/task/conformance";
+    const res = await route(
+      new Request(`http://localhost:1940${path}`, {
+        method: "POST",
+        headers: { authorization: `Bearer ${readToken}`, "content-type": "application/json" },
+        body: JSON.stringify({ fields: { status: { type: "string", required: true } } }),
+      }),
+      path,
+    );
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { violating_notes: number };
+    expect(body.violating_notes).toBe(1);
+  });
+
+  test("PUT /api/tags/:name with replace_fields drops omitted fields (no merge resurrection)", async () => {
+    createVault("journal");
+    const store = getVaultStore("journal");
+    await store.upsertTagRecord("task", {
+      fields: { status: { type: "string" }, due: { type: "string" } },
+    });
+    const admin = await createAdminToken("journal");
+
+    const path = "/vault/journal/api/tags/task";
+    // Send only `status` WITH replace_fields → `due` must be dropped.
+    const res = await route(
+      new Request(`http://localhost:1940${path}`, {
+        method: "PUT",
+        headers: { authorization: `Bearer ${admin}`, "content-type": "application/json" },
+        body: JSON.stringify({ fields: { status: { type: "string" } }, replace_fields: true }),
+      }),
+      path,
+    );
+    expect(res.status).toBe(200);
+    const rec = await store.getTagRecord("task");
+    expect(Object.keys(rec?.fields ?? {})).toEqual(["status"]);
+    expect(rec?.fields?.due).toBeUndefined();
+  });
+
+  test("PUT /api/tags/:name WITHOUT replace_fields preserves omitted fields (merge — MCP contract)", async () => {
+    createVault("journal");
+    const store = getVaultStore("journal");
+    await store.upsertTagRecord("task", {
+      fields: { status: { type: "string" }, due: { type: "string" } },
+    });
+    const admin = await createAdminToken("journal");
+
+    const path = "/vault/journal/api/tags/task";
+    // Send only `status` WITHOUT the flag → `due` preserved (partial update).
+    const res = await route(
+      new Request(`http://localhost:1940${path}`, {
+        method: "PUT",
+        headers: { authorization: `Bearer ${admin}`, "content-type": "application/json" },
+        body: JSON.stringify({ fields: { status: { type: "string", enum: ["a"] } } }),
+      }),
+      path,
+    );
+    expect(res.status).toBe(200);
+    const rec = await store.getTagRecord("task");
+    expect(Object.keys(rec?.fields ?? {}).sort()).toEqual(["due", "status"]);
+  });
+
+  test("GET /api/tags/:name/effective → surfaces inherited fields + parents", async () => {
+    createVault("journal");
+    const store = getVaultStore("journal");
+    // dev declares a field; dev/log inherits it via parent_names.
+    await store.upsertTagRecord("dev", {
+      fields: { area: { type: "string" } },
+    });
+    await store.upsertTagRecord("dev/log", { parent_names: ["dev"] });
+    const admin = await createAdminToken("journal");
+
+    const path = "/vault/journal/api/tags/dev%2Flog/effective";
+    const res = await route(authed(admin, "GET", path), path);
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as {
+      name: string;
+      parents: string[];
+      effective_parents: string[];
+      effective_fields: Record<string, { type?: string }>;
+    };
+    expect(body.parents).toEqual(["dev"]);
+    expect(body.effective_parents).toContain("dev");
+    expect(body.effective_fields.area?.type).toBe("string");
+  });
+
   test("POST /api/tags/:name/rename → 200 cascades token allowlists (vault#240)", async () => {
     createVault("journal");
     const store = getVaultStore("journal");

package/src/routing.ts

@@ -831,9 +831,17 @@ export async function route(
   // and the broad-vs-narrowed shape (`vault:<verb>` from pvt_*, or
   // `vault:<vaultName>:<verb>` from hub JWTs) are handled by
   // `hasScopeForVault`.
-  const requiredVerb = verbForMethod(req.method);
+  //
+  // Read-only POST carve-out (vault#283): the conformance check is a POST
+  // (it carries a proposed-fields body) but mutates nothing — it counts
+  // notes. Gate it on `read`, not `write`, so a read-scoped caller can
+  // preview a schema tightening without holding a write credential.
+  const apiSubpath = apiMatch[1] ?? "";
+  const isReadOnlyPost =
+    req.method === "POST" && /^\/tags\/[^/]+\/conformance$/.test(apiSubpath);
+  const requiredVerb = isReadOnlyPost ? "read" : verbForMethod(req.method);
   if (!hasScopeForVault(auth.scopes, vaultName, requiredVerb)) {
-    const requiredApiScope = scopeForMethod(req.method);
+    const requiredApiScope = isReadOnlyPost ? SCOPE_READ : scopeForMethod(req.method);
     return Response.json(
       {
         error: "Forbidden",

package/src/self-register.test.ts

@@ -61,20 +61,18 @@ function captureLogs(): {
 }
 
 describe("self-register", () => {
-  test("buildVaultServicePaths — no vaults yet → manifest fallback", () => {
-    expect(buildVaultServicePaths(undefined, [], ["/vault/default"])).toEqual([
-      "/vault/default",
-    ]);
+  test("buildVaultServicePaths — no vaults yet → empty paths (no phantom /vault/default, #478)", () => {
+    expect(buildVaultServicePaths(undefined, [])).toEqual([]);
   });
 
   test("buildVaultServicePaths — default vault sorts first", () => {
     expect(
-      buildVaultServicePaths("default", ["alpha", "default", "beta"], ["/"]),
+      buildVaultServicePaths("default", ["alpha", "default", "beta"]),
     ).toEqual(["/vault/default", "/vault/alpha", "/vault/beta"]);
   });
 
   test("buildVaultServicePaths — no default → map by listed order", () => {
-    expect(buildVaultServicePaths(undefined, ["alpha", "beta"], ["/"])).toEqual([
+    expect(buildVaultServicePaths(undefined, ["alpha", "beta"])).toEqual([
       "/vault/alpha",
       "/vault/beta",
     ]);
@@ -82,7 +80,7 @@ describe("self-register", () => {
 
   test("buildVaultServicePaths — default points to missing vault → ignore default", () => {
     expect(
-      buildVaultServicePaths("missing", ["alpha", "beta"], ["/"]),
+      buildVaultServicePaths("missing", ["alpha", "beta"]),
     ).toEqual(["/vault/alpha", "/vault/beta"]);
   });
 
@@ -108,7 +106,9 @@ describe("self-register", () => {
       const row = parsed.services[0] as Record<string, unknown>;
       expect(row.name).toBe("parachute-vault");
       expect(row.port).toBe(1940);
-      expect(row.paths).toEqual(["/vault/default"]);
+      // Zero vaults → paths: [] (no phantom /vault/default, #478).
+      // Health still well-formed: paths[0] ?? "/vault/default" fallback.
+      expect(row.paths).toEqual([]);
       expect(row.health).toBe("/vault/default/health");
       expect(row.version).toBe("0.4.8-rc.3");
       expect(row.installDir).toBe("/fake/install/dir");

package/src/self-register.ts

@@ -56,17 +56,21 @@ import { listVaults, readGlobalConfig, DEFAULT_PORT } from "./config.ts";
  *
  * Mirrors `buildVaultServicePaths` in `cli.ts` so the self-register pass
  * produces the same multi-vault path advertisement as `parachute-vault
- * init` / `vault create`. With no vaults yet, falls back to the manifest's
- * canonical `paths[0]` so early-boot registration is still well-formed.
+ * init` / `vault create`.
+ *
+ * At zero vaults, returns an empty array (`paths: []`). The row remains
+ * present in services.json (name, port, health, version, installDir intact
+ * — so the module is still detected as installed), but it advertises no
+ * `/vault/<name>` path and the hub must not resolve it to a phantom
+ * `/vault/default`. Closes #478.
  *
  * Exported for tests; not part of the public module surface.
  */
 export function buildVaultServicePaths(
   defaultVault: string | undefined,
   vaults: readonly string[],
-  fallbackFromManifest: readonly string[],
 ): string[] {
-  if (vaults.length === 0) return [...fallbackFromManifest];
+  if (vaults.length === 0) return [];
   if (defaultVault && vaults.includes(defaultVault)) {
     return [
       `/vault/${defaultVault}`,
@@ -160,7 +164,7 @@ export function selfRegister(deps: SelfRegisterDeps): SelfRegisterResult {
     return { status: "failed", reason: msg };
   }
 
-  const paths = buildVaultServicePaths(globalConfig.default_vault, vaults, manifest.paths);
+  const paths = buildVaultServicePaths(globalConfig.default_vault, vaults);
   const port = globalConfig.port ?? DEFAULT_PORT;
 
   // Derive the health path from the primary path (paths[0]) rather than