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

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/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/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.2",
+  "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

package/src/routing.test.ts

@@ -149,7 +149,12 @@ function reset(): void {
   // Default every test to the fixture hub origin so the hub-JWT mint path
   // resolves JWKS + validates `iss`. Describes that assert the loopback
   // default (OAuth discovery metadata) override this in their own beforeEach.
-  if (hubFixtureOrigin) process.env.PARACHUTE_HUB_ORIGIN = hubFixtureOrigin;
+  if (hubFixtureOrigin) {
+    process.env.PARACHUTE_HUB_ORIGIN = hubFixtureOrigin;
+    // Post-vault#464 the JWKS fetch origin resolves separately (loopback by
+    // default); point it at the fixture so the mint path's JWKS fetch resolves.
+    process.env.PARACHUTE_HUB_JWKS_ORIGIN = hubFixtureOrigin;
+  }
   resetJwksCache();
   resetRevocationCache();
 }
@@ -183,6 +188,7 @@ afterAll(() => {
   clearVaultStoreCache();
   hubServer?.stop(true);
   delete process.env.PARACHUTE_HUB_ORIGIN;
+  delete process.env.PARACHUTE_HUB_JWKS_ORIGIN;
   if (existsSync(testDir)) rmSync(testDir, { recursive: true, force: true });
 });