@openparachute/vault 0.5.3-rc.1 → 0.5.3-rc.3

package/core/src/core.test.ts

@@ -2067,6 +2067,41 @@ describe("MCP tools", async () => {
     expect(result[1].tags).toContain("doc");
   });
 
+  // vault#316 — the create-note tool re-reads each note AFTER
+  // `applySchemaDefaults` runs, so the response reflects the post-defaults
+  // on-disk state (matching the update-note path). Before the fix the
+  // response mapped over the pre-defaults in-memory objects, so a
+  // schema-default-filled field was missing from the returned note even
+  // though it had just been written to disk.
+  it("create-note response reflects post-applySchemaDefaults state (vault#316)", async () => {
+    await store.upsertTagSchema("task", {
+      fields: { priority: { type: "string", enum: ["high", "low"] } },
+    });
+    const tools = generateMcpTools(store);
+    const createNote = tools.find((t) => t.name === "create-note")!;
+
+    // Single: default lands in the returned metadata.
+    const single = await createNote.execute({
+      content: "do the thing",
+      path: "Inbox/task-1",
+      tags: ["task"],
+    }) as any;
+    expect(single.metadata?.priority).toBe("high"); // first enum value
+    // Disk and response agree.
+    const onDisk = await store.getNoteByPath("Inbox/task-1");
+    expect((onDisk!.metadata as any)?.priority).toBe("high");
+
+    // Batch: each entry is re-read post-defaults too.
+    const batch = await createNote.execute({
+      notes: [
+        { content: "a", path: "Inbox/task-2", tags: ["task"] },
+        { content: "b", path: "Inbox/task-3", tags: ["task"] },
+      ],
+    }) as any[];
+    expect(batch[0].metadata?.priority).toBe("high");
+    expect(batch[1].metadata?.priority).toBe("high");
+  });
+
   it("create-note accepts extension field (vault#328)", async () => {
     const tools = generateMcpTools(store);
     const createNote = tools.find((t) => t.name === "create-note")!;

package/core/src/indexed-fields.ts

@@ -101,7 +101,7 @@ export function listIndexedFields(db: Database): IndexedField[] {
 export function getIndexedField(db: Database, field: string): IndexedField | null {
   const row = db
     .prepare("SELECT field, sqlite_type, declarer_tags FROM indexed_fields WHERE field = ?")
-    .get(field) as IndexedFieldRow | undefined;
+    .get(field) as IndexedFieldRow | null;
   return row ? rowToField(row) : null;
 }
 

package/core/src/links.ts

@@ -106,7 +106,7 @@ function parseMetadata(raw: string | null): Record<string, unknown> | undefined
 function getNoteSummary(db: Database, noteId: string): NoteSummary | undefined {
   const row = db.prepare(
     "SELECT id, path, metadata, created_at, updated_at FROM notes WHERE id = ?",
-  ).get(noteId) as SummaryRow | undefined;
+  ).get(noteId) as SummaryRow | null;
   if (!row) return undefined;
   return {
     id: row.id,

package/core/src/mcp.ts

@@ -131,7 +131,7 @@ export interface GenerateMcpToolsOpts {
  * delete-tag, find-path, vault-info, prune-schema (admin).
  */
 export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): McpToolDef[] {
-  const db: Database = (store as any).db;
+  const db: Database = store.db;
   const expandVisibility = opts?.expandVisibility;
   const nearTraversable = opts?.nearTraversable;
 
@@ -591,17 +591,35 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
           throw e;
         }
 
-        // Apply tag schema effects
+        // Apply tag schema effects, then re-read the notes whose metadata was
+        // actually default-filled so the response reflects the final on-disk
+        // state (the `created` entries were read before `applySchemaDefaults`
+        // ran, so default-filled metadata isn't on them yet). This mirrors the
+        // update-note path, which already re-reads post-defaults. The re-read
+        // is batched (`getNotes` = one `WHERE id IN (...)`) and skipped
+        // entirely when no defaults were applied, so the common no-defaults
+        // path adds zero extra reads.
+        const mutatedIds = new Set<string>();
         for (const note of created) {
           if (note.tags && note.tags.length > 0) {
-            await applySchemaDefaults(store, db, [note.id], note.tags);
+            for (const id of await applySchemaDefaults(store, db, [note.id], note.tags)) {
+              mutatedIds.add(id);
+            }
           }
         }
-
-        // Re-read after schema-default population so the response reflects the
-        // final on-disk state, then attach `validation_status` from any
-        // tag's `fields` declaration that applies to this note.
-        const final = created.map((n) => attachValidationStatus(store, db, n));
+        const refreshed =
+          mutatedIds.size === 0
+            ? created
+            : (() => {
+                const byId = new Map(
+                  noteOps.getNotes(db, [...mutatedIds]).map((n) => [n.id, n]),
+                );
+                return created.map((n) => byId.get(n.id) ?? n);
+              })();
+
+        // Attach `validation_status` from any tag's `fields` declaration that
+        // applies to this note, against the post-defaults state.
+        const final = refreshed.map((n) => attachValidationStatus(store, db, n));
         return batch ? final : final[0];
       },
     },
@@ -1406,9 +1424,16 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
 // Tag schema effects — auto-populate defaults when tags are applied
 // ---------------------------------------------------------------------------
 
-async function applySchemaDefaults(store: Store, db: Database, noteIds: string[], tags: string[]): Promise<void> {
+/**
+ * Fill schema-declared default values into the metadata of the given notes
+ * for any field they omitted. Returns the IDs of the notes whose metadata was
+ * actually written — callers use this to re-read ONLY the mutated notes (and
+ * to skip the re-read entirely when nothing changed). The common no-schema /
+ * no-defaults path returns an empty array.
+ */
+async function applySchemaDefaults(store: Store, db: Database, noteIds: string[], tags: string[]): Promise<string[]> {
   const schemas = tagSchemaOps.getTagSchemaMap(db);
-  if (Object.keys(schemas).length === 0) return;
+  if (Object.keys(schemas).length === 0) return [];
 
   const defaults: Record<string, unknown> = {};
   for (const tag of tags) {
@@ -1420,8 +1445,9 @@ async function applySchemaDefaults(store: Store, db: Database, noteIds: string[]
       }
     }
   }
-  if (Object.keys(defaults).length === 0) return;
+  if (Object.keys(defaults).length === 0) return [];
 
+  const mutated: string[] = [];
   for (const noteId of noteIds) {
     const note = noteOps.getNote(db, noteId);
     if (!note) continue;
@@ -1437,7 +1463,9 @@ async function applySchemaDefaults(store: Store, db: Database, noteIds: string[]
       metadata: { ...existing, ...missing },
       skipUpdatedAt: true,
     });
+    mutated.push(noteId);
   }
+  return mutated;
 }
 
 function defaultForField(field: { type: string; enum?: string[] }): unknown {

package/core/src/notes.ts

@@ -83,7 +83,7 @@ export function createNote(
 }
 
 export function getNote(db: Database, id: string): Note | null {
-  const row = db.prepare("SELECT * FROM notes WHERE id = ?").get(id) as NoteRow | undefined;
+  const row = db.prepare("SELECT * FROM notes WHERE id = ?").get(id) as NoteRow | null;
   if (!row) return null;
 
   const note = rowToNote(row);
@@ -111,7 +111,7 @@ export function getNoteByPath(db: Database, path: string, extension?: string): N
   if (extension !== undefined) {
     const row = db.prepare(
       "SELECT * FROM notes WHERE path = ? COLLATE NOCASE AND LOWER(extension) = ?",
-    ).get(path, extension.toLowerCase()) as NoteRow | undefined;
+    ).get(path, extension.toLowerCase()) as NoteRow | null;
     if (!row) return null;
     const note = rowToNote(row);
     note.tags = getNoteTags(db, note.id);
@@ -459,7 +459,7 @@ export function updateNote(
     if (isPathUniqueError(err)) {
       const conflictPath = updates.path !== undefined
         ? (normalizePath(updates.path) ?? updates.path)
-        : ((db.prepare("SELECT path FROM notes WHERE id = ?").get(id) as { path: string | null } | undefined)?.path ?? "<unknown>");
+        : ((db.prepare("SELECT path FROM notes WHERE id = ?").get(id) as { path: string | null } | null)?.path ?? "<unknown>");
       throw new PathConflictError(conflictPath);
     }
     throw err;
@@ -475,7 +475,7 @@ export function updateNote(
 function throwConflictOrMissing(db: Database, id: string, expected: string): never {
   const row = db.prepare("SELECT updated_at, path FROM notes WHERE id = ?").get(id) as
     | { updated_at: string | null; path: string | null }
-    | undefined;
+    | null;
   if (!row) {
     throw new Error(`Note not found: "${id}"`);
   }
@@ -972,7 +972,7 @@ export function listTags(db: Database): { name: string; count: number }[] {
 export function deleteTag(db: Database, name: string): { deleted: boolean; notes_untagged: number } {
   const row = db.prepare("SELECT fields FROM tags WHERE name = ?").get(name) as
     | { fields: string | null }
-    | undefined;
+    | null;
   if (!row) return { deleted: false, notes_untagged: 0 };
 
   const countRow = db.prepare("SELECT COUNT(*) as c FROM note_tags WHERE tag_name = ?").get(name) as { c: number };
@@ -1133,7 +1133,7 @@ export function renameTag(db: Database, oldName: string, newName: string): Renam
     for (const { from, to } of renames) {
       const old = readStmt.get(from) as
         | { description: string | null; fields: string | null; relationships: string | null; parent_names: string | null; created_at: string | null }
-        | undefined;
+        | null;
       insertStmt.run(
         to,
         old?.description ?? null,
@@ -1548,11 +1548,11 @@ export function getVaultStats(
 
   const earliestRow = db.prepare(
     "SELECT id, created_at FROM notes ORDER BY created_at ASC, id ASC LIMIT 1",
-  ).get() as { id: string; created_at: string } | undefined;
+  ).get() as { id: string; created_at: string } | null;
 
   const latestRow = db.prepare(
     "SELECT id, created_at FROM notes ORDER BY created_at DESC, id DESC LIMIT 1",
-  ).get() as { id: string; created_at: string } | undefined;
+  ).get() as { id: string; created_at: string } | null;
 
   const monthRows = db.prepare(`
     SELECT strftime('%Y-%m', created_at) AS month, COUNT(*) AS count

package/core/src/schema.ts

@@ -797,7 +797,7 @@ function migrateToV15(db: Database): void {
     // 2. Copy `_schema_defaults` note → schema_mappings.
     const mappingNote = db.prepare(
       "SELECT metadata FROM notes WHERE path = '_schema_defaults'",
-    ).get() as { metadata: string | null } | undefined;
+    ).get() as { metadata: string | null } | null;
     if (mappingNote?.metadata) {
       const insertMapping = db.prepare(
         "INSERT OR IGNORE INTO schema_mappings (schema_name, match_kind, match_value) VALUES (?, ?, ?)",

package/core/src/store.ts

@@ -730,7 +730,7 @@ export class BunSqliteStore implements Store {
     // Scope by noteId so a token authorized for note A can't delete note B's attachments.
     const row = this.db.prepare(
       "SELECT path FROM attachments WHERE id = ? AND note_id = ?",
-    ).get(attachmentId, noteId) as { path: string } | undefined;
+    ).get(attachmentId, noteId) as { path: string } | null;
     if (!row) return { deleted: false, path: null, orphaned: false };
 
     this.db.prepare("DELETE FROM attachments WHERE id = ? AND note_id = ?").run(attachmentId, noteId);
@@ -756,7 +756,7 @@ export class BunSqliteStore implements Store {
   async getAttachment(attachmentId: string): Promise<Attachment | null> {
     const row = this.db.prepare(
       "SELECT * FROM attachments WHERE id = ?",
-    ).get(attachmentId) as { id: string; note_id: string; path: string; mime_type: string; metadata: string | null; created_at: string } | undefined;
+    ).get(attachmentId) as { id: string; note_id: string; path: string; mime_type: string; metadata: string | null; created_at: string } | null;
     if (!row) return null;
     let metadata: Record<string, unknown> | undefined;
     if (row.metadata && row.metadata !== "{}") {

package/core/src/tag-schemas.ts

@@ -115,7 +115,7 @@ export function listTagRecords(db: Database): TagRecord[] {
 export function getTagRecord(db: Database, tag: string): TagRecord | null {
   const row = db.prepare(
     "SELECT name, description, fields, relationships, parent_names, created_at, updated_at FROM tags WHERE name = ?",
-  ).get(tag) as TagRow | undefined;
+  ).get(tag) as TagRow | null;
   return row ? rowToRecord(row) : null;
 }
 
@@ -189,7 +189,7 @@ export function listTagSchemas(db: Database): TagSchema[] {
 export function getTagSchema(db: Database, tag: string): TagSchema | null {
   const row = db.prepare(
     "SELECT name, description, fields FROM tags WHERE name = ?",
-  ).get(tag) as { name: string; description: string | null; fields: string | null } | undefined;
+  ).get(tag) as { name: string; description: string | null; fields: string | null } | null;
   if (!row) return null;
   if (row.description === null && row.fields === null) return null;
   return {

package/core/src/types.ts

@@ -1,3 +1,4 @@
+import type { Database } from "bun:sqlite";
 import type { TagFieldSchema, TagRelationship, TagRelationshipMap, TagRecord } from "./tag-schemas.js";
 import type { PrunedField } from "./indexed-fields.js";
 
@@ -208,6 +209,15 @@ export interface HydratedLink extends Link {
 // ---- Store Interface ----
 
 export interface Store {
+  /**
+   * The underlying `bun:sqlite` handle. Exposed (read-only) so callers that
+   * need to run a raw query the Store interface doesn't surface — e.g. the
+   * token-table reverse-lookups in routes.ts and MCP tool generation in
+   * mcp.ts — can reach it without an `(store as any).db` cast. The concrete
+   * `Store` class declares this as `public readonly db: Database`. See vault#242.
+   */
+  readonly db: Database;
+
   // Notes
   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>;

package/core/src/wikilinks.ts

@@ -137,7 +137,7 @@ export function resolveWikilink(db: Database, target: string): string | null {
     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;
+    ).get(pathPart, extPart) as { id: string } | null;
     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
@@ -199,7 +199,7 @@ export function resolveWikilinkDetailed(db: Database, target: string): WikilinkR
     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;
+    ).get(pathPart, extPart) as { id: string; path: string } | null;
     if (explicit) {
       return { resolved: true, note_id: explicit.id, path: explicit.path, candidates: [] };
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/vault",
-  "version": "0.5.3-rc.1",
+  "version": "0.5.3-rc.3",
   "description": "Agent-native knowledge graph. Notes, tags, links over MCP.",
   "module": "src/cli.ts",
   "type": "module",
@@ -26,7 +26,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.1",
-    "@openparachute/scope-guard": "^0.4.0",
+    "@openparachute/scope-guard": "^0.4.1-rc.1",
     "jose": "^6.2.2",
     "otpauth": "^9.5.0",
     "qrcode-terminal": "^0.12.0"

package/src/auth-hub-jwt.test.ts

@@ -143,6 +143,7 @@ function bearer(token: string): Request {
 let tmpHome: string;
 let prevHome: string | undefined;
 let prevHubOrigin: string | undefined;
+let prevJwksOrigin: string | undefined;
 let fixture: HubFixture;
 let kp: Keypair;
 
@@ -159,7 +160,11 @@ beforeEach(async () => {
   kp = await makeKeypair("k1");
   fixture = startHubFixture([kp]);
   prevHubOrigin = process.env.PARACHUTE_HUB_ORIGIN;
+  prevJwksOrigin = process.env.PARACHUTE_HUB_JWKS_ORIGIN;
   process.env.PARACHUTE_HUB_ORIGIN = fixture.origin;
+  // Post-vault#464 the JWKS fetch origin resolves separately (loopback by
+  // default); point it at the fixture so keys are reachable in-test.
+  process.env.PARACHUTE_HUB_JWKS_ORIGIN = fixture.origin;
   resetJwksCache();
   resetRevocationCache();
 });
@@ -171,6 +176,8 @@ afterEach(() => {
   else process.env.PARACHUTE_HOME = prevHome;
   if (prevHubOrigin === undefined) delete process.env.PARACHUTE_HUB_ORIGIN;
   else process.env.PARACHUTE_HUB_ORIGIN = prevHubOrigin;
+  if (prevJwksOrigin === undefined) delete process.env.PARACHUTE_HUB_JWKS_ORIGIN;
+  else process.env.PARACHUTE_HUB_JWKS_ORIGIN = prevJwksOrigin;
   if (existsSync(tmpHome)) rmSync(tmpHome, { recursive: true, force: true });
 });
 

package/src/hub-jwt.test.ts

@@ -14,7 +14,14 @@
  */
 import { describe, test, expect, beforeAll, afterAll, beforeEach } from "bun:test";
 import { generateKeyPair, exportJWK, SignJWT } from "jose";
-import { resetJwksCache, resetRevocationCache, validateHubJwt, looksLikeJwt } from "./hub-jwt.ts";
+import {
+  resetJwksCache,
+  resetRevocationCache,
+  validateHubJwt,
+  looksLikeJwt,
+  getHubOrigin,
+  getJwksOrigin,
+} from "./hub-jwt.ts";
 
 interface Keypair {
   privateKey: CryptoKey;
@@ -113,6 +120,7 @@ async function signJwt(kp: Keypair, opts: SignOpts): Promise<string> {
 let fixture: JwksFixture;
 let kp: Keypair;
 let prevHubOrigin: string | undefined;
+let prevJwksOrigin: string | undefined;
 
 beforeAll(async () => {
   fixture = startJwksFixture();
@@ -124,12 +132,19 @@ afterAll(() => {
   fixture.stop();
   if (prevHubOrigin === undefined) delete process.env.PARACHUTE_HUB_ORIGIN;
   else process.env.PARACHUTE_HUB_ORIGIN = prevHubOrigin;
+  if (prevJwksOrigin === undefined) delete process.env.PARACHUTE_HUB_JWKS_ORIGIN;
+  else process.env.PARACHUTE_HUB_JWKS_ORIGIN = prevJwksOrigin;
 });
 
 beforeEach(() => {
-  // Each test sets its own origin for clarity.
+  // Each test sets its own origin for clarity. Post-vault#464 the JWKS *fetch*
+  // origin is resolved separately from the iss-validation origin, so point the
+  // JWKS fetch at the fixture too — otherwise the guard would read keys from
+  // the loopback default (no JWKS server there) and every case would fail.
   prevHubOrigin = process.env.PARACHUTE_HUB_ORIGIN;
+  prevJwksOrigin = process.env.PARACHUTE_HUB_JWKS_ORIGIN;
   process.env.PARACHUTE_HUB_ORIGIN = fixture.origin;
+  process.env.PARACHUTE_HUB_JWKS_ORIGIN = fixture.origin;
   fixture.setUnreachable(false);
   fixture.setKeys([kp]);
   resetJwksCache();
@@ -153,6 +168,64 @@ describe("looksLikeJwt", () => {
   });
 });
 
+describe("origin resolvers — iss/jwks split (vault#464)", () => {
+  test("getHubOrigin honors PARACHUTE_HUB_ORIGIN (iss-validation origin)", () => {
+    process.env.PARACHUTE_HUB_ORIGIN = "https://vault.example.com/";
+    expect(getHubOrigin()).toBe("https://vault.example.com");
+  });
+
+  test("getHubOrigin falls back to loopback when unset", () => {
+    delete process.env.PARACHUTE_HUB_ORIGIN;
+    expect(getHubOrigin()).toBe("http://127.0.0.1:1939");
+  });
+
+  test("getJwksOrigin defaults to loopback (no env override)", () => {
+    delete process.env.PARACHUTE_HUB_JWKS_ORIGIN;
+    expect(getJwksOrigin()).toBe("http://127.0.0.1:1939");
+  });
+
+  test("getJwksOrigin honors PARACHUTE_HUB_JWKS_ORIGIN and strips trailing slash", () => {
+    process.env.PARACHUTE_HUB_JWKS_ORIGIN = "http://10.0.0.5:1939/";
+    expect(getJwksOrigin()).toBe("http://10.0.0.5:1939");
+  });
+
+  test("jwks fetch is decoupled from the iss origin: keys served ONLY at the jwks origin still validate a token whose iss is the (separate) public origin", async () => {
+    // Mirrors the vault#464 deploy shape: iss + revocation live at the public
+    // origin (the default `fixture` here), while the JWKS is reachable only at
+    // a SEPARATE jwks origin (a second fixture standing in for loopback). The
+    // guard must fetch keys from the jwks origin, not the iss origin.
+    const jwksOnly = startJwksFixture();
+    jwksOnly.setKeys([kp]);
+    // The public iss origin (default fixture) serves revocation but NOT keys —
+    // if the guard fetched JWKS from here, verification would fail "no key".
+    fixture.setKeys([]);
+    try {
+      process.env.PARACHUTE_HUB_ORIGIN = fixture.origin; // iss + revocation
+      process.env.PARACHUTE_HUB_JWKS_ORIGIN = jwksOnly.origin; // keys only
+      resetJwksCache();
+      const token = await signJwt(kp, { iss: fixture.origin });
+      const claims = await validateHubJwt(token);
+      expect(claims.sub).toBe("user-1");
+    } finally {
+      jwksOnly.stop();
+    }
+  });
+
+  test("token whose iss does NOT match the iss origin is rejected even when keys resolve at the jwks origin", async () => {
+    const jwksOnly = startJwksFixture();
+    jwksOnly.setKeys([kp]);
+    try {
+      process.env.PARACHUTE_HUB_ORIGIN = fixture.origin;
+      process.env.PARACHUTE_HUB_JWKS_ORIGIN = jwksOnly.origin;
+      resetJwksCache();
+      const token = await signJwt(kp, { iss: "https://attacker.example" });
+      await expect(validateHubJwt(token)).rejects.toThrow(/verification failed/);
+    } finally {
+      jwksOnly.stop();
+    }
+  });
+});
+
 describe("validateHubJwt — happy path", () => {
   test("valid JWT with correct iss → claims surface", async () => {
     const token = await signJwt(kp, { iss: fixture.origin, scope: "vault:work:read vault:work:write" });

package/src/hub-jwt.ts

@@ -23,13 +23,18 @@ import {
 const DEFAULT_HUB_LOOPBACK = "http://127.0.0.1:1939";
 
 /**
- * Resolve the hub origin used to fetch JWKS and validate `iss`. Strips a
+ * Resolve the hub origin used to validate the token's `iss` claim. Strips a
  * trailing slash so we get a single canonical form.
  *
  * Order: env var → loopback fallback. We deliberately don't read
  * `~/.parachute/services.json` — the hub is the dispatcher, not a registered
  * service in that file. If a deployment exposes the hub on a non-default
  * origin, the env var is the contract.
+ *
+ * `parachute expose` pins `PARACHUTE_HUB_ORIGIN` to the PUBLIC FQDN so the
+ * `iss` we validate against matches what the hub stamps on the tokens it
+ * mints — keep using this origin for iss-validation. The JWKS *fetch* origin
+ * is resolved separately by `getJwksOrigin()`; see vault#464.
  */
 export function getHubOrigin(): string {
   const env = process.env.PARACHUTE_HUB_ORIGIN?.replace(/\/$/, "");
@@ -37,12 +42,44 @@ export function getHubOrigin(): string {
   return DEFAULT_HUB_LOOPBACK;
 }
 
+/**
+ * Resolve the origin used to FETCH the hub's JWKS — kept distinct from
+ * `getHubOrigin()` (the iss-validation origin) per vault#464.
+ *
+ * Vault is co-located with its hub (the hub supervises vault on the same box,
+ * the common deploy). After `parachute expose --cloudflare`, `getHubOrigin()`
+ * is the public Cloudflare FQDN. If we fetched JWKS from that public origin we
+ * would hairpin out through the tunnel and back to the same box — a round-trip
+ * that times out (hard fail under Docker NAT-loopback, slow/flaky on a real
+ * VPS) and 401s the first MCP connect after expose. So we always read keys
+ * from the LOCAL hub on loopback instead.
+ *
+ * Order: `PARACHUTE_HUB_JWKS_ORIGIN` override → loopback default. The override
+ * exists for the rare non-co-located case — a vault running on a DIFFERENT box
+ * than its hub sets `PARACHUTE_HUB_JWKS_ORIGIN` to the hub's reachable
+ * internal address. Trailing-slash-stripped, matching `getHubOrigin()`.
+ */
+export function getJwksOrigin(): string {
+  const env = process.env.PARACHUTE_HUB_JWKS_ORIGIN?.replace(/\/$/, "");
+  if (env && env.length > 0) return env;
+  return DEFAULT_HUB_LOOPBACK;
+}
+
 // Process-wide guard. The resolver form lets tests flip
-// `PARACHUTE_HUB_ORIGIN` between cases — the lib re-resolves on every
-// `validateHubJwt` and `resetJwksCache` call so the env-var change picks up
-// without a server restart. JWKS cache (5min/30s defaults) lives inside the
-// guard, shared across requests.
-const guard = createScopeGuard({ hubOrigin: () => getHubOrigin() });
+// `PARACHUTE_HUB_ORIGIN` / `PARACHUTE_HUB_JWKS_ORIGIN` between cases — the lib
+// re-resolves on every `validateHubJwt` and `resetJwksCache` call so the
+// env-var change picks up without a server restart. JWKS cache (5min/30s
+// defaults) lives inside the guard, shared across requests.
+//
+// The iss/jwks split (vault#464): `hubOrigin` validates the token's `iss`
+// (public FQDN post-expose, via PARACHUTE_HUB_ORIGIN); `jwksOrigin` fetches
+// the keys from the local hub (loopback by default, via
+// PARACHUTE_HUB_JWKS_ORIGIN). Co-located vault never egresses to read its own
+// hub's keys, so no tunnel hairpin.
+const guard = createScopeGuard({
+  hubOrigin: () => getHubOrigin(),
+  jwksOrigin: () => getJwksOrigin(),
+});
 
 /**
  * Verify a presented JWT against the hub's JWKS. Throws `HubJwtError` on any