@openparachute/vault 0.4.4-rc.14 → 0.4.6-rc.3

package/core/src/schema.ts

@@ -2,17 +2,25 @@ import { Database } from "bun:sqlite";
 import { normalizePath } from "./paths.js";
 import { rebuildIndexes } from "./indexed-fields.js";
 
-export const SCHEMA_VERSION = 17;
+export const SCHEMA_VERSION = 18;
 
 export const SCHEMA_SQL = `
--- Notes: the universal record
+-- Notes: the universal record.
+--
+-- extension (v18, vault#328) carries the file suffix the note should
+-- exhibit when serialized to disk — "md" by default, "csv"/"yaml"/"json"/
+-- "mdx"/etc. for non-markdown notes. Stored extension-less in the path
+-- column; on-disk uniqueness key is (path, extension). See
+-- core/src/portable-md.ts:supportsInlineFrontmatter for the
+-- frontmatter-vs-sidecar split.
 CREATE TABLE IF NOT EXISTS notes (
   id TEXT PRIMARY KEY,
   content TEXT DEFAULT '',
   path TEXT,
   metadata TEXT DEFAULT '{}',
   created_at TEXT NOT NULL,
-  updated_at TEXT
+  updated_at TEXT,
+  extension TEXT NOT NULL DEFAULT 'md'
 );
 
 -- Tags: first-class identity carrying schema, hierarchy, and typed-link
@@ -266,6 +274,11 @@ export function initSchema(db: Database): void {
   // as `tags.fields` if needed. See vault#267.
   migrateToV17(db);
 
+  // Migrate v17 → v18: add `notes.extension TEXT NOT NULL DEFAULT 'md'`.
+  // Backward-compat by construction — every existing row defaults to "md"
+  // (markdown), unchanged in meaning. See vault#328.
+  migrateToV18(db);
+
   // Rebuild any generated columns + indexes declared in indexed_fields.
   // No-op for a fresh vault; idempotent on existing vaults.
   rebuildIndexes(db);
@@ -793,6 +806,51 @@ function migrateToV17(db: Database): void {
   }
 }
 
+/**
+ * Migrate v17 → v18: add `notes.extension TEXT NOT NULL DEFAULT 'md'`
+ * (vault#328) AND widen the path-uniqueness index from `(path)` to
+ * `(path, extension)` so two notes can share a path differing only by
+ * extension (`Recipes/pasta` with both .md and .csv variants).
+ *
+ * Backward-compat by construction — every existing row defaults to "md",
+ * so the new composite-index uniqueness collapses to the v5
+ * "(path WHERE NOT NULL) is unique" behavior on existing data. Wrapped
+ * in BEGIN IMMEDIATE / COMMIT / ROLLBACK per the v14+ pattern.
+ */
+function migrateToV18(db: Database): void {
+  if (!hasTable(db, "notes")) return;
+
+  // Two responsibilities (column add + index swap) — both idempotent
+  // individually. Wrap in one transaction so an upgrading v17 vault
+  // ends up at exactly v17 or v18, never partial.
+  const needsColumn = !hasColumn(db, "notes", "extension");
+  const indexes = db.prepare(
+    "SELECT name FROM sqlite_master WHERE type='index' AND name IN ('idx_notes_path_unique', 'idx_notes_path_ext_unique')",
+  ).all() as { name: string }[];
+  const hasOldUnique = indexes.some((r) => r.name === "idx_notes_path_unique");
+  const hasNewUnique = indexes.some((r) => r.name === "idx_notes_path_ext_unique");
+  if (!needsColumn && hasNewUnique && !hasOldUnique) return;
+
+  db.exec("BEGIN IMMEDIATE");
+  try {
+    if (needsColumn) {
+      db.exec("ALTER TABLE notes ADD COLUMN extension TEXT NOT NULL DEFAULT 'md'");
+    }
+    if (hasOldUnique) {
+      db.exec("DROP INDEX idx_notes_path_unique");
+    }
+    if (!hasNewUnique) {
+      db.exec(
+        "CREATE UNIQUE INDEX idx_notes_path_ext_unique ON notes(path, extension) WHERE path IS NOT NULL",
+      );
+    }
+    db.exec("COMMIT");
+  } catch (err) {
+    db.exec("ROLLBACK");
+    throw err;
+  }
+}
+
 function hasTable(db: Database, name: string): boolean {
   const row = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name=?").get(name);
   return !!row;

package/core/src/store.ts

@@ -92,7 +92,7 @@ export class BunSqliteStore implements Store {
 
   // ---- Notes ----
 
-  async createNote(content: string, opts?: { id?: string; path?: string; tags?: string[]; metadata?: Record<string, unknown>; created_at?: string }): Promise<Note> {
+  async createNote(content: string, opts?: { id?: string; path?: string; tags?: string[]; metadata?: Record<string, unknown>; created_at?: string; extension?: string }): Promise<Note> {
     const note = noteOps.createNote(this.db, content, opts);
 
     if (content) {
@@ -113,8 +113,8 @@ export class BunSqliteStore implements Store {
     return noteOps.getNote(this.db, id);
   }
 
-  async getNoteByPath(path: string): Promise<Note | null> {
-    return noteOps.getNoteByPath(this.db, path);
+  async getNoteByPath(path: string, extension?: string): Promise<Note | null> {
+    return noteOps.getNoteByPath(this.db, path, extension);
   }
 
   async getNotes(ids: string[]): Promise<Note[]> {
@@ -128,6 +128,7 @@ export class BunSqliteStore implements Store {
       append?: string;
       prepend?: string;
       path?: string;
+      extension?: string;
       metadata?: Record<string, unknown>;
       created_at?: string;
       skipUpdatedAt?: boolean;
@@ -498,7 +499,7 @@ export class BunSqliteStore implements Store {
    * `syncAllWikilinks`, so adding the cache rebuild there is the natural
    * place.)
    */
-  async createNoteRaw(content: string, opts?: { id?: string; path?: string; tags?: string[]; metadata?: Record<string, unknown>; created_at?: string }): Promise<Note> {
+  async createNoteRaw(content: string, opts?: { id?: string; path?: string; tags?: string[]; metadata?: Record<string, unknown>; created_at?: string; extension?: string }): Promise<Note> {
     return noteOps.createNote(this.db, content, opts);
   }
 

package/core/src/types.ts

@@ -10,6 +10,14 @@ export interface Note {
   id: string;
   content: string;
   path?: string;
+  /**
+   * File extension (sans dot). Defaults to `"md"`. Controls the
+   * serialized file suffix on export — `.md`/`.mdx` carry frontmatter
+   * inline; `.csv`/`.yaml`/`.json`/etc. carry their metadata in a
+   * sidecar at `.parachute/notes-meta/<id>.yaml`. See vault#328 +
+   * `core/src/portable-md.ts:supportsInlineFrontmatter`.
+   */
+  extension?: string;
   metadata?: Record<string, unknown>;
   createdAt: string; // ISO-8601
   updatedAt?: string;
@@ -64,6 +72,13 @@ export interface QueryOpts {
   hasLinks?: boolean;
   path?: string;        // exact path match (case-insensitive)
   pathPrefix?: string;  // e.g., "Projects/Parachute" matches "Projects/Parachute/README"
+  /**
+   * Filter by file extension. Pass a single extension (e.g. `"csv"`) or
+   * an array (e.g. `["csv", "yaml", "json"]`). Extension is compared
+   * lower-case. Notes default to `"md"` so `extension: "md"` matches
+   * the existing markdown corpus. See vault#328.
+   */
+  extension?: string | string[];
   // Restrict results to a specific set of note IDs. The MCP `near` query uses
   // this to push graph-neighborhood scoping into the SQL WHERE clause so that
   // LIMIT and ORDER BY apply to the filtered set, not the whole notes table.
@@ -107,6 +122,7 @@ export interface QueryOpts {
 export interface NoteSummary {
   id: string;
   path?: string;
+  extension?: string;
   metadata?: Record<string, unknown>;
   createdAt: string;
   updatedAt?: string;
@@ -120,6 +136,7 @@ export interface NoteSummary {
 export interface NoteIndex {
   id: string;
   path?: string;
+  extension?: string;
   createdAt: string;
   updatedAt?: string;
   tags?: string[];
@@ -138,11 +155,18 @@ export interface HydratedLink extends Link {
 
 export interface Store {
   // Notes
-  createNote(content: string, opts?: { id?: string; path?: string; tags?: string[]; metadata?: Record<string, unknown>; created_at?: string }): Promise<Note>;
+  createNote(content: string, opts?: { id?: string; path?: string; tags?: string[]; metadata?: Record<string, unknown>; created_at?: string; extension?: string }): Promise<Note>;
   getNote(id: string): Promise<Note | null>;
-  getNoteByPath(path: string): Promise<Note | null>;
+  /**
+   * Look up a note by path. Pass `extension` to disambiguate when
+   * multiple notes share a path differing only by extension (post-
+   * vault#328). When omitted and >1 row matches, throws
+   * `AmbiguousPathError` instead of silently picking one. See
+   * vault#330 S1.
+   */
+  getNoteByPath(path: string, extension?: string): Promise<Note | null>;
   getNotes(ids: string[]): Promise<Note[]>;
-  updateNote(id: string, updates: { content?: string; append?: string; prepend?: string; path?: string; metadata?: Record<string, unknown>; created_at?: string; skipUpdatedAt?: boolean; if_updated_at?: string }): Promise<Note>;
+  updateNote(id: string, updates: { content?: string; append?: string; prepend?: string; path?: string; extension?: string; metadata?: Record<string, unknown>; created_at?: string; skipUpdatedAt?: boolean; if_updated_at?: string }): Promise<Note>;
   /**
    * Set a note's `created_at` and `updated_at` explicitly. Import-only:
    * used by the portable-md round-trip path to restore timestamps from

package/core/src/wikilinks.ts

@@ -110,19 +110,57 @@ function stripCode(content: string): string {
  * Resolve a wikilink target to a note ID.
  *
  * Resolution order:
- * 1. Exact path match (case-insensitive)
- * 2. Basename match — target matches the last segment of a path
- *    (e.g., "README" matches "Projects/Parachute/README")
- *    Only if there's exactly one match (ambiguous = unresolved)
+ * 1. **Explicit-extension target**: `[[Foo.csv]]` matches the note with
+ *    `path: "Foo"` AND `extension: "csv"` (vault#328). Lets a reader
+ *    disambiguate when multiple notes share a path differing only by
+ *    extension. The trailing `.<ext>` must match a known
+ *    alphanumeric pattern (1–16 chars) — otherwise the dot is treated
+ *    as part of the path string and falls through to the existing
+ *    rules.
+ * 2. Exact path match (case-insensitive) — multiple matches resolve to
+ *    a single note when only ONE extension is in play; if `Foo.md` and
+ *    `Foo.csv` both exist, the link refuses to resolve and the caller
+ *    sees an unresolved-wikilink entry (vault#328 ambiguity policy).
+ * 3. Basename match — target matches the last segment of a path
+ *    (e.g., "README" matches "Projects/Parachute/README"). Same
+ *    cross-extension ambiguity policy as #2.
  */
 export function resolveWikilink(db: Database, target: string): string | null {
-  // 1. Exact match (case-insensitive)
+  // 1. Explicit extension form: `[[path.ext]]` where `.ext` is a
+  // pattern-matching tail (lowercase alphanumeric, 1–16 chars).
+  // Mirrors EXTENSION_PATTERN in core/src/notes.ts so the wikilink
+  // parser and the API surface share the same notion of "this looks
+  // like an extension."
+  const extMatch = target.match(/^(.*)\.([a-z0-9]{1,16})$/i);
+  if (extMatch) {
+    const pathPart = extMatch[1]!;
+    const extPart = extMatch[2]!.toLowerCase();
+    const explicit = db.prepare(
+      "SELECT id FROM notes WHERE path = ? COLLATE NOCASE AND LOWER(extension) = ?",
+    ).get(pathPart, extPart) as { id: string } | undefined;
+    if (explicit) return explicit.id;
+    // No match for explicit (path, ext) — fall through to the looser
+    // rules so a literal note named `Recipe.v2` (where `v2` isn't an
+    // extension on a real note) can still resolve under exact-path
+    // match.
+  }
+
+  // 2. Exact match (case-insensitive). When multiple notes share a path
+  // (post-vault#328 this happens when `Foo.md` and `Foo.csv` both
+  // exist, since path is stored extension-less), refuse to resolve.
   const exact = db.prepare(
     "SELECT id FROM notes WHERE path = ? COLLATE NOCASE",
-  ).get(target) as { id: string } | undefined;
-  if (exact) return exact.id;
+  ).all(target) as { id: string }[];
+  if (exact.length === 1) return exact[0]!.id;
+  if (exact.length > 1) {
+    // Ambiguous — refuse-and-require-explicit-extension policy
+    // (vault#328). Returning null routes through the existing
+    // unresolved-wikilinks workflow, so the reader (or the indexer)
+    // sees the conflict.
+    return null;
+  }
 
-  // 2. Basename match — last path segment equals target
+  // 3. Basename match — last path segment equals target.
   // e.g., target "README" matches path "Projects/Parachute/README"
   const basename = db.prepare(`
     SELECT id FROM notes
@@ -150,17 +188,39 @@ export interface WikilinkResolution {
 
 /**
  * Resolve a wikilink target with full detail — single match, ambiguous, or unresolved.
+ * Mirrors `resolveWikilink`'s resolution order, including the explicit-
+ * extension form `[[Foo.csv]]` introduced by vault#328.
  */
 export function resolveWikilinkDetailed(db: Database, target: string): WikilinkResolution {
-  // 1. Exact match (case-insensitive)
+  // 1. Explicit-extension form: `[[path.ext]]`.
+  const extMatch = target.match(/^(.*)\.([a-z0-9]{1,16})$/i);
+  if (extMatch) {
+    const pathPart = extMatch[1]!;
+    const extPart = extMatch[2]!.toLowerCase();
+    const explicit = db.prepare(
+      "SELECT id, path FROM notes WHERE path = ? COLLATE NOCASE AND LOWER(extension) = ?",
+    ).get(pathPart, extPart) as { id: string; path: string } | undefined;
+    if (explicit) {
+      return { resolved: true, note_id: explicit.id, path: explicit.path, candidates: [] };
+    }
+  }
+
+  // 2. Exact path match (case-insensitive). Multiple matches → ambiguous.
   const exact = db.prepare(
-    "SELECT id, path FROM notes WHERE path = ? COLLATE NOCASE",
-  ).get(target) as { id: string; path: string } | undefined;
-  if (exact) {
-    return { resolved: true, note_id: exact.id, path: exact.path, candidates: [] };
+    "SELECT id, path, extension FROM notes WHERE path = ? COLLATE NOCASE",
+  ).all(target) as { id: string; path: string; extension: string }[];
+  if (exact.length === 1) {
+    return { resolved: true, note_id: exact[0]!.id, path: exact[0]!.path, candidates: [] };
+  }
+  if (exact.length > 1) {
+    return {
+      resolved: false,
+      ambiguous: true,
+      candidates: exact.map((r) => ({ note_id: r.id, path: r.path })),
+    };
   }
 
-  // 2. Basename match
+  // 3. Basename match
   const basename = db.prepare(`
     SELECT id, path FROM notes
     WHERE path IS NOT NULL

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/vault",
-  "version": "0.4.4-rc.14",
+  "version": "0.4.6-rc.3",
   "description": "Agent-native knowledge graph. Notes, tags, links over MCP.",
   "module": "src/cli.ts",
   "type": "module",

package/src/auth.test.ts

@@ -398,3 +398,238 @@ describe("auth — legacy global YAML keys honor declared scope", () => {
     }
   });
 });
+
+// ---------------------------------------------------------------------------
+// VAULT_AUTH_TOKEN — server-wide operator bearer (vault#339)
+//
+// The container-shape auth gate. When the env var is set, a request whose
+// `Authorization: Bearer <value>` matches authenticates as full/admin
+// against any vault on the server — the operator-channel path for sibling
+// services on Render where vault and hub run as separate containers and
+// hub needs a stable shared bearer to call vault.
+//
+// Semantic confirmed for the loopback/non-loopback split (auth gate is
+// orthogonal to socket-level loopback): when VAULT_AUTH_TOKEN is unset,
+// vault's existing token surface (per-vault DB tokens + hub JWTs + legacy
+// YAML keys) is the ONLY auth surface. The bind socket defaults to
+// 127.0.0.1 (`VAULT_BIND` in bind.ts), but no implicit loopback trust
+// exists at the auth layer — a request from 127.0.0.1 still has to
+// present a valid bearer. This matches docs/auth-model.md §1.
+// ---------------------------------------------------------------------------
+
+describe("auth — VAULT_AUTH_TOKEN server-wide operator bearer", () => {
+  const TOKEN = "test-operator-token-deadbeef0123456789abcdef";
+  let prevToken: string | undefined;
+
+  beforeEach(() => {
+    prevToken = process.env.VAULT_AUTH_TOKEN;
+  });
+
+  afterEach(() => {
+    if (prevToken === undefined) delete process.env.VAULT_AUTH_TOKEN;
+    else process.env.VAULT_AUTH_TOKEN = prevToken;
+  });
+
+  test("env set + matching bearer → 200 on vault auth, full permission, admin scopes", async () => {
+    process.env.VAULT_AUTH_TOKEN = TOKEN;
+    seedVault("journal");
+    const journalConfig = readVaultConfig("journal")!;
+    const journalStore = getVaultStore("journal");
+
+    const result = await authenticateVaultRequest(
+      bearer(TOKEN),
+      journalConfig,
+      journalStore.db,
+    );
+
+    expect("error" in result).toBe(false);
+    if (!("error" in result)) {
+      expect(result.permission).toBe("full");
+      expect(result.scopes).toContain("vault:admin");
+      expect(result.legacyDerived).toBe(false);
+      expect(result.scoped_tags).toBeNull();
+    }
+  });
+
+  test("env set + matching bearer authenticates against ANY vault on the server", async () => {
+    // Server-wide → not tied to any one vault's DB. Same bearer works
+    // for journal and work without minting a per-vault token in either.
+    process.env.VAULT_AUTH_TOKEN = TOKEN;
+    seedVault("journal");
+    seedVault("work");
+    const journalConfig = readVaultConfig("journal")!;
+    const journalStore = getVaultStore("journal");
+    const workConfig = readVaultConfig("work")!;
+    const workStore = getVaultStore("work");
+
+    const j = await authenticateVaultRequest(bearer(TOKEN), journalConfig, journalStore.db);
+    const w = await authenticateVaultRequest(bearer(TOKEN), workConfig, workStore.db);
+
+    expect("error" in j).toBe(false);
+    expect("error" in w).toBe(false);
+  });
+
+  test("env set + missing bearer → 401 (no implicit auth)", async () => {
+    process.env.VAULT_AUTH_TOKEN = TOKEN;
+    seedVault("journal");
+    const journalConfig = readVaultConfig("journal")!;
+    const journalStore = getVaultStore("journal");
+
+    // No Authorization header at all.
+    const noBearer = new Request("https://vault.test/x");
+    const result = await authenticateVaultRequest(noBearer, journalConfig, journalStore.db);
+
+    expect("error" in result).toBe(true);
+    if ("error" in result) {
+      expect(result.error.status).toBe(401);
+    }
+  });
+
+  test("env set + wrong bearer → 401", async () => {
+    process.env.VAULT_AUTH_TOKEN = TOKEN;
+    seedVault("journal");
+    const journalConfig = readVaultConfig("journal")!;
+    const journalStore = getVaultStore("journal");
+
+    const result = await authenticateVaultRequest(
+      bearer("wrong-token-doesnotmatch"),
+      journalConfig,
+      journalStore.db,
+    );
+
+    expect("error" in result).toBe(true);
+    if ("error" in result) {
+      expect(result.error.status).toBe(401);
+    }
+  });
+
+  test("env set + bearer that matches a vault token still resolves (server-wide first, but per-vault unchanged)", async () => {
+    // Per-vault tokens keep working even when the server-wide bearer is
+    // set. The server-wide check is a fast-path lookup before token DB
+    // resolution — a per-vault token doesn't match the env var so it
+    // falls through to the existing path.
+    process.env.VAULT_AUTH_TOKEN = TOKEN;
+    seedVault("journal");
+    const perVaultToken = mintTokenInVault("journal");
+    const journalConfig = readVaultConfig("journal")!;
+    const journalStore = getVaultStore("journal");
+
+    const result = await authenticateVaultRequest(
+      bearer(perVaultToken),
+      journalConfig,
+      journalStore.db,
+    );
+
+    expect("error" in result).toBe(false);
+  });
+
+  test("env unset + valid per-vault bearer → 200 (existing behavior preserved)", async () => {
+    delete process.env.VAULT_AUTH_TOKEN;
+    seedVault("journal");
+    const token = mintTokenInVault("journal");
+    const journalConfig = readVaultConfig("journal")!;
+    const journalStore = getVaultStore("journal");
+
+    const result = await authenticateVaultRequest(bearer(token), journalConfig, journalStore.db);
+    expect("error" in result).toBe(false);
+  });
+
+  test("env unset + missing bearer → 401 (existing behavior preserved)", async () => {
+    delete process.env.VAULT_AUTH_TOKEN;
+    seedVault("journal");
+    const journalConfig = readVaultConfig("journal")!;
+    const journalStore = getVaultStore("journal");
+
+    const noBearer = new Request("https://vault.test/x");
+    const result = await authenticateVaultRequest(noBearer, journalConfig, journalStore.db);
+    expect("error" in result).toBe(true);
+    if ("error" in result) {
+      expect(result.error.status).toBe(401);
+    }
+  });
+
+  test("env unset + non-loopback simulated via X-Forwarded-For → still 401 without bearer", async () => {
+    // Doc note: vault has NO implicit loopback trust at the auth layer.
+    // The X-Forwarded-For shape (set by hub / Cloudflare Tunnel / etc.)
+    // doesn't affect the auth gate; tokens are required regardless of
+    // socket origin. The `bind.ts` 127.0.0.1 default is a socket-level
+    // listen-restriction, not a trust-asymmetric auth bypass.
+    delete process.env.VAULT_AUTH_TOKEN;
+    seedVault("journal");
+    const journalConfig = readVaultConfig("journal")!;
+    const journalStore = getVaultStore("journal");
+
+    const remote = new Request("https://vault.test/x", {
+      headers: { "X-Forwarded-For": "203.0.113.7" },
+    });
+    const result = await authenticateVaultRequest(remote, journalConfig, journalStore.db);
+    expect("error" in result).toBe(true);
+    if ("error" in result) {
+      expect(result.error.status).toBe(401);
+    }
+  });
+
+  test("env set with whitespace-only value → treated as unset", async () => {
+    process.env.VAULT_AUTH_TOKEN = "   ";
+    seedVault("journal");
+    const journalConfig = readVaultConfig("journal")!;
+    const journalStore = getVaultStore("journal");
+
+    // An empty/whitespace VAULT_AUTH_TOKEN must NOT allow any bearer to
+    // pass — the operator either commits to bearer auth or doesn't.
+    const result = await authenticateVaultRequest(
+      bearer(""),
+      journalConfig,
+      journalStore.db,
+    );
+    expect("error" in result).toBe(true);
+  });
+
+  test("env set + matching bearer also works on the global auth surface", async () => {
+    // /vaults metadata listing + /health vault names go through
+    // authenticateGlobalRequest. The server-wide bearer must work there
+    // too — otherwise hub couldn't enumerate vaults using the operator
+    // channel.
+    process.env.VAULT_AUTH_TOKEN = TOKEN;
+    seedVault("journal");
+
+    const result = await authenticateGlobalRequest(bearer(TOKEN));
+    expect("error" in result).toBe(false);
+    if (!("error" in result)) {
+      expect(result.permission).toBe("full");
+    }
+  });
+
+  test("env set + wrong bearer on global auth surface → 401", async () => {
+    process.env.VAULT_AUTH_TOKEN = TOKEN;
+    seedVault("journal");
+
+    const result = await authenticateGlobalRequest(bearer("wrong-token"));
+    expect("error" in result).toBe(true);
+    if ("error" in result) {
+      expect(result.error.status).toBe(401);
+    }
+  });
+
+  test("near-miss bearer (one-char difference, same length) → 401 (constant-time compare)", async () => {
+    // Defensive: the server-wide compare uses crypto.timingSafeEqual so
+    // a one-char-off bearer that matches length-wise still rejects.
+    // We can't measure timing in a unit test, but we can pin the
+    // correctness side: a same-length near-miss must still reject.
+    process.env.VAULT_AUTH_TOKEN = TOKEN;
+    seedVault("journal");
+    const journalConfig = readVaultConfig("journal")!;
+    const journalStore = getVaultStore("journal");
+
+    const nearMiss = TOKEN.slice(0, -1) + "x";
+    expect(nearMiss).not.toBe(TOKEN);
+    expect(nearMiss.length).toBe(TOKEN.length);
+
+    const result = await authenticateVaultRequest(
+      bearer(nearMiss),
+      journalConfig,
+      journalStore.db,
+    );
+    expect("error" in result).toBe(true);
+  });
+});

package/src/auth.ts

@@ -20,6 +20,7 @@ import type { VaultConfig, StoredKey } from "./config.ts";
 import { resolveToken } from "./token-store.ts";
 import type { TokenPermission } from "./token-store.ts";
 import type { Database } from "bun:sqlite";
+import crypto from "node:crypto";
 import { getVaultStore } from "./vault-store.ts";
 import {
   findBroadVaultScopes,
@@ -32,6 +33,66 @@ import {
 } from "./scopes.ts";
 import { HubJwtError, looksLikeJwt, validateHubJwt } from "./hub-jwt.ts";
 
+/**
+ * Server-wide operator bearer token, sourced from the `VAULT_AUTH_TOKEN`
+ * environment variable.
+ *
+ * Read dynamically per request (not cached at import time) so test seams
+ * that mutate `process.env.VAULT_AUTH_TOKEN` work without re-importing.
+ * In production the env var is set at container start and doesn't change.
+ *
+ * Empty / whitespace-only values are treated as unset — the operator
+ * either commits to bearer auth or doesn't, no degraded "empty token
+ * always matches" failure mode.
+ */
+function getServerWideAuthToken(env: NodeJS.ProcessEnv = process.env): string | null {
+  const raw = env.VAULT_AUTH_TOKEN;
+  if (typeof raw !== "string") return null;
+  const trimmed = raw.trim();
+  return trimmed.length === 0 ? null : trimmed;
+}
+
+/**
+ * Constant-time string equality. Returns false when lengths differ
+ * (timingSafeEqual throws on length mismatch; we want a quiet false).
+ */
+function constantTimeEquals(a: string, b: string): boolean {
+  const aBuf = Buffer.from(a, "utf8");
+  const bBuf = Buffer.from(b, "utf8");
+  if (aBuf.length !== bBuf.length) return false;
+  return crypto.timingSafeEqual(aBuf, bBuf);
+}
+
+/**
+ * If `VAULT_AUTH_TOKEN` is set and the provided bearer matches it
+ * (constant-time), return a full-admin AuthResult that's accepted by
+ * every vault on the server.
+ *
+ * The operator-channel auth shape for non-loopback deploys (Render,
+ * sibling-container setups, vault#339). Hub uses this to call vault
+ * across a container boundary; end-user OAuth tokens still take the
+ * per-vault hub-JWT / pvt_* paths below. See `docs/auth-model.md` §2.
+ *
+ * Scope set is broad (`vault:admin`) — the env-var bearer is an
+ * operator credential, not a user credential. Tag-scoping doesn't
+ * apply; we represent it as unscoped (`scoped_tags: null`).
+ */
+function tryServerWideAuth(
+  providedKey: string,
+  env: NodeJS.ProcessEnv = process.env,
+): AuthResult | null {
+  const configured = getServerWideAuthToken(env);
+  if (configured === null) return null;
+  if (!constantTimeEquals(providedKey, configured)) return null;
+  return {
+    permission: "full",
+    scopes: [SCOPE_ADMIN, SCOPE_WRITE, SCOPE_READ],
+    legacyDerived: false,
+    scoped_tags: null,
+    vault_name: null,
+  };
+}
+
 /** Result of a successful auth check. */
 export interface AuthResult {
   permission: TokenPermission;
@@ -168,6 +229,15 @@ export async function authenticateVaultRequest(
     return { error: Response.json({ error: "Unauthorized", message: "API key required" }, { status: 401 }) };
   }
 
+  // Server-wide operator token (vault#339). When VAULT_AUTH_TOKEN is set,
+  // a matching bearer authenticates as full/admin against any vault. This
+  // is the cross-container path for Render / sibling-service deployments
+  // where hub talks to vault over HTTP. Checked first so it short-circuits
+  // both JWT validation and per-vault DB lookups — the operator token is
+  // a credential the operator opts into, not one we'd ever fall through.
+  const serverWide = tryServerWideAuth(key);
+  if (serverWide !== null) return serverWide;
+
   // JWT path: hub-issued tokens. Trust pinned to the hub origin via `iss`
   // verification inside validateHubJwt; signature checked against hub's JWKS.
   // Audience strict-checked against `vault.<name>` so a token stamped for
@@ -326,6 +396,14 @@ export async function authenticateGlobalRequest(
     return { error: Response.json({ error: "Unauthorized", message: "API key required" }, { status: 401 }) };
   }
 
+  // Server-wide operator token (vault#339). When VAULT_AUTH_TOKEN is set,
+  // a matching bearer authenticates as full/admin on cross-vault routes
+  // (/vaults metadata listing, /health detail). Checked first so a
+  // container-host operator-channel call doesn't depend on any per-vault
+  // DB lookup.
+  const serverWide = tryServerWideAuth(key);
+  if (serverWide !== null) return serverWide;
+
   // Hub-issued JWTs are always vault-bound (aud=vault.<name>). The unified
   // /vaults / /health surface spans every vault and has no single audience to
   // strict-check against, so JWTs aren't accepted here. Cross-vault listing