@openparachute/vault 0.4.0 → 0.4.3

package/core/src/vault-projection.ts

@@ -0,0 +1,309 @@
+/**
+ * Vault projection — computes a comprehensive description of the vault
+ * (tags-with-schemas + effective inheritance + indexed-field catalog +
+ * query hints) shared by two consumers:
+ *
+ *   - `vault-info` MCP tool — returns the full projection as a JSON object
+ *     so an agent can request a refresh mid-session.
+ *   - `getServerInstruction` (MCP `initialize` response) — renders the
+ *     same projection as a terse markdown brief sent once at connect.
+ *
+ * The projection lives outside the per-note path: it describes what kinds
+ * of notes and queries are available, not the contents. Nothing here
+ * depends on auth/scopes — both consumers compose this with vault config
+ * (name/description) and any policy-driven framing on top.
+ *
+ * See vault#271 for design notes.
+ */
+
+import { Database } from "bun:sqlite";
+import {
+  loadSchemaConfig,
+  resolveNoteSchemas,
+  walkAncestors,
+  type ResolvedSchemas,
+  type SchemaField,
+} from "./schema-defaults.ts";
+import { listIndexedFields } from "./indexed-fields.ts";
+import {
+  listTagRecords,
+  type TagFieldSchema,
+  type TagRecord,
+} from "./tag-schemas.ts";
+import { DEFAULT_TAG_NAME } from "./tag-hierarchy.ts";
+import * as noteOps from "./notes.ts";
+import type { VaultStats } from "./types.ts";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface ProjectionTag {
+  name: string;
+  description: string | null;
+  /** Direct parents declared in `tags.parent_names` (verbatim, no walk). */
+  parents: string[];
+  /**
+   * Walk-order ancestor closure (parents → grandparents → …) including the
+   * implicit `_default` universal parent when present, with the tag itself
+   * excluded. Empty when the tag has no parents and no `_default` exists.
+   */
+  effective_parents: string[];
+  /**
+   * Own field declarations (verbatim from `tags.fields`). Carries the full
+   * `TagFieldSchema` shape — `type` (string), optional `description`,
+   * `enum`, `indexed`. Width matches the on-disk row.
+   */
+  fields: Record<string, TagFieldSchema> | null;
+  /**
+   * Merged field map = own ∪ inherited (first-in-walk wins, matching
+   * `resolveNoteSchemas`). Uses the `SchemaField` view returned by the
+   * resolver (narrower `type` enum). Empty when no ancestor — including
+   * the tag itself — declared anything.
+   */
+  effective_fields: Record<string, SchemaField>;
+  relationships: TagRecord["relationships"] | null;
+}
+
+export interface ProjectionIndexedField {
+  name: string;
+  /** User-facing field type ("string" | "integer" | "boolean") drawn from the first declarer. */
+  type: string;
+  tags: string[];
+}
+
+export interface VaultProjection {
+  tags: ProjectionTag[];
+  indexed_fields: ProjectionIndexedField[];
+  query_hints: string[];
+  /** Included when the caller requests stats; omitted otherwise. */
+  stats?: VaultStats;
+}
+
+// ---------------------------------------------------------------------------
+// Inheritance helpers (built on the #272 resolver)
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve a single tag's effective inheritance.
+ *
+ * Built on top of `resolveNoteSchemas({ tags: [tag] })` so the walk order
+ * and conflict precedence match the runtime validator exactly. Returns:
+ *
+ *   - `effective_parents`: walk-order ancestor list with the tag itself
+ *     excluded. Includes `_default` when a `_default` row exists, regardless
+ *     of whether the tag declares it (universal-parent semantics).
+ *   - `effective_fields`: merged field map (first-in-walk wins). When no
+ *     ancestor contributes, this equals the tag's own `fields`.
+ */
+export function resolveTagInheritance(
+  resolved: ResolvedSchemas,
+  tag: string,
+): { effective_parents: string[]; effective_fields: Record<string, SchemaField> } {
+  const resolution = resolveNoteSchemas(resolved, { tags: [tag] });
+
+  // resolveNoteSchemas returns effectiveTags (only fields-contributing tags).
+  // We need the full walk for effective_parents — replay using the same
+  // resolver helper so walk-order semantics stay in lockstep with #270.
+  const visited = new Set<string>();
+  const order: string[] = [];
+  walkAncestors(tag, resolved, visited, order);
+  if (resolved.allTags.has(DEFAULT_TAG_NAME) && !visited.has(DEFAULT_TAG_NAME)) {
+    walkAncestors(DEFAULT_TAG_NAME, resolved, visited, order);
+  }
+  const effective_parents = order.filter((t) => t !== tag);
+
+  const effective_fields: Record<string, SchemaField> = {};
+  for (const [field, { spec }] of resolution.mergedFields) {
+    effective_fields[field] = spec;
+  }
+
+  return { effective_parents, effective_fields };
+}
+
+// ---------------------------------------------------------------------------
+// Projection
+// ---------------------------------------------------------------------------
+
+/**
+ * Static query-hint catalog. Sent verbatim in both vault-info JSON and the
+ * connect-time markdown projection so an agent can self-orient without
+ * reading source. Edit here when query semantics change.
+ */
+export const QUERY_HINTS: readonly string[] = [
+  "query-notes { tag: \"X\" } — all notes with tag X (includes descendants per inheritance)",
+  "query-notes { tag: \"X\", metadata: { field: { op: value } } } — operator queries on indexed fields (eq/ne/gt/gte/lt/lte/in/not_in/exists)",
+  "query-notes { search: \"...\" } — full-text search across content",
+  "query-notes { near: { id: \"...\" }, depth: 2 } — graph neighborhood within N hops",
+  "query-notes { id: \"<note-id-or-path>\" } — fetch a single note by ID or path",
+] as const;
+
+/**
+ * Build the comprehensive vault projection. Pure read; no caches mutated.
+ *
+ * Shape rules:
+ *
+ *   - `tags`: only tags carrying their own `description` or `fields`. A
+ *     hierarchy-only tag (parent_names but no own schema) is omitted from
+ *     the catalog — its semantics live in whichever ancestor contributes
+ *     fields. `effective_fields` still surfaces the merged spec when the
+ *     tag *does* appear (because it has its own description/fields).
+ *
+ *   - `indexed_fields`: one entry per row in the `indexed_fields` table.
+ *     The user-facing `type` is drawn from the first declarer's spec —
+ *     declarers must agree on type (enforced at write time) so picking the
+ *     first is unambiguous. `tags` lists every declarer, sorted.
+ *
+ *   - `stats`: included when `opts.includeStats === true`. Uses the
+ *     existing `getVaultStats` shape unchanged — camelCase keys, full
+ *     monthly distribution.
+ */
+export function buildVaultProjection(
+  db: Database,
+  opts?: { includeStats?: boolean },
+): VaultProjection {
+  const resolved = loadSchemaConfig(db);
+  const records = listTagRecords(db);
+
+  const tags: ProjectionTag[] = [];
+  for (const r of records) {
+    const hasOwnSchema =
+      (r.description !== undefined && r.description !== null) ||
+      (r.fields !== undefined && r.fields !== null && Object.keys(r.fields).length > 0);
+    if (!hasOwnSchema) continue;
+
+    const { effective_parents, effective_fields } = resolveTagInheritance(resolved, r.tag);
+
+    tags.push({
+      name: r.tag,
+      description: r.description ?? null,
+      parents: r.parent_names ?? [],
+      effective_parents,
+      fields: r.fields ?? null,
+      effective_fields,
+      relationships: r.relationships ?? null,
+    });
+  }
+
+  const indexedRows = listIndexedFields(db);
+  const indexed_fields: ProjectionIndexedField[] = indexedRows.map((row) => {
+    const declarers = [...row.declarerTags].sort();
+    // Recover the user-facing type from the first declarer's spec. Falls
+    // back to a sqlite-derived label if the declarer's row is gone (race;
+    // shouldn't happen because release drops the indexed_fields row, but
+    // robust against drift).
+    let userType = sqliteToUserType(row.sqliteType);
+    for (const t of declarers) {
+      const fields = resolved.tagToFields.get(t);
+      const declared = fields?.[row.field]?.type;
+      if (typeof declared === "string" && declared.length > 0) {
+        userType = declared;
+        break;
+      }
+    }
+    return { name: row.field, type: userType, tags: declarers };
+  });
+
+  const projection: VaultProjection = {
+    tags,
+    indexed_fields,
+    query_hints: [...QUERY_HINTS],
+  };
+
+  if (opts?.includeStats) {
+    projection.stats = noteOps.getVaultStats(db);
+  }
+
+  return projection;
+}
+
+function sqliteToUserType(t: string): string {
+  if (t === "TEXT") return "string";
+  if (t === "INTEGER") return "integer";
+  return t.toLowerCase();
+}
+
+// ---------------------------------------------------------------------------
+// Markdown rendering — for getServerInstruction
+// ---------------------------------------------------------------------------
+
+/**
+ * Render a vault projection as a terse markdown brief for the MCP
+ * `initialize` response. Keep dense — agents see this once at connect, and
+ * the goal is "everything an agent needs to start using the vault sensibly,
+ * with explicit pointers for refresh."
+ *
+ * Token budget guideline: ~600 tokens for a small vault (Aaron's, ~4 tags-
+ * with-schemas) and under ~5K tokens at 50 tags-with-schemas. Listing all
+ * tags-with-schemas inline is the default; cap heuristics can be added if
+ * a real test shape demands it.
+ */
+export function projectionToMarkdown(args: {
+  vaultName: string;
+  description?: string | null;
+  projection: VaultProjection;
+}): string {
+  const { vaultName, description, projection } = args;
+  const stats = projection.stats;
+
+  const lines: string[] = [];
+  lines.push(`You are connected to Parachute Vault "${vaultName}".`);
+  if (description && description.trim().length > 0) {
+    lines.push("");
+    lines.push(description.trim());
+  }
+
+  lines.push("");
+  lines.push("## Quick orientation (call `vault-info` for full schema)");
+  lines.push("");
+
+  if (stats) {
+    // Two distinct counts surface here so an agent doesn't conflate
+    // them (vault#274): `tagCount` is "tags ANY note uses" — driven by
+    // note_tags rows. `projection.tags.length` is "tags carrying a
+    // schema declaration" — strictly smaller and the relevant denominator
+    // for the schema-bearing list a few lines down. Showing only one
+    // hid the gap (e.g., 100 tags but only 5 with schemas read as
+    // "100 tags with schemas").
+    const noteCount = stats.totalNotes;
+    const tagCount = stats.tagCount;
+    const withSchemas = projection.tags.length;
+    const noteLabel = noteCount === 1 ? "note" : "notes";
+    const tagLabel = tagCount === 1 ? "tag" : "tags";
+    const tagSuffix = withSchemas > 0 ? `, ${withSchemas} with schemas` : "";
+    lines.push(`- ${noteCount} ${noteLabel}, ${tagCount} ${tagLabel} total${tagSuffix}`);
+  } else {
+    lines.push(`- (call \`vault-info { include_stats: true }\` for note/tag counts)`);
+  }
+
+  if (projection.tags.length === 0) {
+    lines.push(`- No tag schemas declared yet — every note is freeform.`);
+  } else {
+    const names = projection.tags.map((t) => t.name).join(", ");
+    lines.push(`- ${projection.tags.length} tag${projection.tags.length === 1 ? "" : "s"} with schemas: ${names}`);
+  }
+
+  if (projection.indexed_fields.length > 0) {
+    lines.push(`- Indexed metadata fields (queryable with operators):`);
+    for (const f of projection.indexed_fields) {
+      const declarers = f.tags.map((t) => `#${t}`).join(", ");
+      lines.push(`  - ${f.name} (${f.type}; from ${declarers})`);
+    }
+  } else {
+    lines.push(`- No indexed metadata fields.`);
+  }
+
+  lines.push("");
+  lines.push("## Querying");
+  lines.push("");
+  for (const hint of projection.query_hints) {
+    lines.push(`- \`${hint}\``);
+  }
+
+  lines.push("");
+  lines.push("## Refreshing context");
+  lines.push("");
+  lines.push("If schema or tags change during this session, call `vault-info` to refresh the full projection. Call `list-tags { include_schema: true }` for tag-only details.");
+
+  return lines.join("\n");
+}

package/package.json

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

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

@@ -10,13 +10,18 @@
  *   - broad `vault:<verb>` scope rejected (forced narrowing per #180)
  *   - `aud=vault.<other>` rejected (audience mismatch)
  *   - JWT path rejected at the global (cross-vault) entrypoint
+ *   - revoked jti rejected (revocation list integration; client-facing
+ *     message is sanitized so the jti doesn't leak)
+ *   - revocation list unavailable on cold start → fail-closed 401
  *
- * Each test owns a fresh `PARACHUTE_HOME` and JWKS fixture, like the auth.test
- * peer file. The JWKS fixture mirrors the one in hub-jwt.test.ts; duplicating
- * ~30 lines is cheaper than introducing a shared test-helper module.
+ * Each test owns a fresh `PARACHUTE_HOME` and a fake hub fixture that serves
+ * BOTH `/.well-known/jwks.json` and `/.well-known/parachute-revocation.json`.
+ * scope-guard's own unit suite covers the cache mechanics (TTL refresh,
+ * fail-open with last-good, single-flight); this file pins the vault-side
+ * wiring and the response-shape contract.
  */
 
-import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { describe, test, expect, beforeEach, afterEach, spyOn } from "bun:test";
 import { mkdirSync, rmSync, existsSync } from "fs";
 import { join } from "path";
 import { tmpdir } from "os";
@@ -24,7 +29,7 @@ import { generateKeyPair, exportJWK, SignJWT } from "jose";
 import { writeVaultConfig, readVaultConfig } from "./config.ts";
 import { getVaultStore, clearVaultStoreCache } from "./vault-store.ts";
 import { authenticateVaultRequest, authenticateGlobalRequest } from "./auth.ts";
-import { resetJwksCache } from "./hub-jwt.ts";
+import { resetJwksCache, resetRevocationCache } from "./hub-jwt.ts";
 
 interface Keypair {
   privateKey: CryptoKey;
@@ -42,24 +47,45 @@ async function makeKeypair(kid: string): Promise<Keypair> {
   };
 }
 
-interface JwksFixture {
+interface HubFixture {
   origin: string;
+  /** Drive the revocation list contents; cleared by default. */
+  setRevoked(jtis: string[]): void;
+  /** When true, the revocation endpoint returns 503 — exercises fail-closed. */
+  setRevocationFails(fails: boolean): void;
   stop: () => void;
 }
 
-function startJwksFixture(keys: Keypair[]): JwksFixture {
+function startHubFixture(keys: Keypair[]): HubFixture {
+  let revokedJtis: string[] = [];
+  let revocationFails = false;
   const server = Bun.serve({
     port: 0,
     fetch(req) {
       const url = new URL(req.url);
-      if (url.pathname !== "/.well-known/jwks.json") {
-        return new Response("not found", { status: 404 });
+      if (url.pathname === "/.well-known/jwks.json") {
+        return Response.json({ keys: keys.map((k) => k.publicJwk) });
       }
-      return Response.json({ keys: keys.map((k) => k.publicJwk) });
+      if (url.pathname === "/.well-known/parachute-revocation.json") {
+        if (revocationFails) {
+          return new Response("hub down", { status: 503 });
+        }
+        return Response.json({
+          generated_at: new Date().toISOString(),
+          jtis: revokedJtis,
+        });
+      }
+      return new Response("not found", { status: 404 });
     },
   });
   return {
     origin: `http://127.0.0.1:${server.port}`,
+    setRevoked: (jtis) => {
+      revokedJtis = jtis;
+    },
+    setRevocationFails: (fails) => {
+      revocationFails = fails;
+    },
     stop: () => server.stop(true),
   };
 }
@@ -70,6 +96,8 @@ interface SignOpts {
   scope: string;
   sub?: string;
   ttlSeconds?: number;
+  /** Override the random jti — needed when a test wants to revoke this exact token. */
+  jti?: string;
 }
 
 async function signJwt(kp: Keypair, opts: SignOpts): Promise<string> {
@@ -82,7 +110,7 @@ async function signJwt(kp: Keypair, opts: SignOpts): Promise<string> {
     .setAudience(opts.aud)
     .setIssuedAt(iat)
     .setExpirationTime(exp)
-    .setJti(`jti-${Math.random().toString(36).slice(2)}`)
+    .setJti(opts.jti ?? `jti-${Math.random().toString(36).slice(2)}`)
     .sign(kp.privateKey);
 }
 
@@ -95,7 +123,7 @@ function bearer(token: string): Request {
 let tmpHome: string;
 let prevHome: string | undefined;
 let prevHubOrigin: string | undefined;
-let fixture: JwksFixture;
+let fixture: HubFixture;
 let kp: Keypair;
 
 beforeEach(async () => {
@@ -109,10 +137,11 @@ beforeEach(async () => {
   clearVaultStoreCache();
 
   kp = await makeKeypair("k1");
-  fixture = startJwksFixture([kp]);
+  fixture = startHubFixture([kp]);
   prevHubOrigin = process.env.PARACHUTE_HUB_ORIGIN;
   process.env.PARACHUTE_HUB_ORIGIN = fixture.origin;
   resetJwksCache();
+  resetRevocationCache();
 });
 
 afterEach(() => {
@@ -228,4 +257,104 @@ describe("authenticateVaultRequest — hub JWT integration", () => {
       expect(body.message).toContain("/vault/<name>");
     }
   });
+
+  test("revoked jti → 401 sanitized; full diagnostic (with jti) routed to console.warn audit log", async () => {
+    seedVault("journal");
+    const revokedJti = "jti-revoked-by-operator";
+    fixture.setRevoked([revokedJti]);
+    const token = await signJwt(kp, {
+      iss: fixture.origin,
+      aud: "vault.journal",
+      scope: "vault:journal:read",
+      jti: revokedJti,
+    });
+    const config = readVaultConfig("journal")!;
+    const store = getVaultStore("journal");
+
+    // Spy + suppress so the assertion is the audit-trail invariant for
+    // this scenario, not a stderr inspection. Pattern carries to scribe/agent.
+    const warnSpy = spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      const result = await authenticateVaultRequest(bearer(token), config, store.db);
+      expect("error" in result).toBe(true);
+      if ("error" in result) {
+        expect(result.error.status).toBe(401);
+        const body = (await result.error.json()) as { error: string; message: string };
+        expect(body.error).toBe("Unauthorized");
+        // Client-facing message must NOT carry the jti — that's a server-side
+        // audit-log concern only. See the `code === "revoked"` branch in
+        // authenticateHubJwt for the sanitization.
+        expect(body.message).toBe("token has been revoked");
+        expect(body.message).not.toContain(revokedJti);
+      }
+      // Audit-log invariant: console.warn fires exactly once with a message
+      // that carries the jti, so an operator chasing a 401 in production logs
+      // can correlate to which token was retired.
+      expect(warnSpy).toHaveBeenCalledTimes(1);
+      const warnArg = warnSpy.mock.calls[0]![0] as string;
+      expect(warnArg).toContain(revokedJti);
+      expect(warnArg).toContain("revoked");
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  test("non-revoked jti against populated list → still honored (happy path with active revocations)", async () => {
+    seedVault("journal");
+    fixture.setRevoked(["some-other-revoked-jti"]);
+    const token = await signJwt(kp, {
+      iss: fixture.origin,
+      aud: "vault.journal",
+      scope: "vault:journal:write",
+      jti: "jti-still-good",
+    });
+    const config = readVaultConfig("journal")!;
+    const store = getVaultStore("journal");
+
+    const result = await authenticateVaultRequest(bearer(token), config, store.db);
+    expect("error" in result).toBe(false);
+    if (!("error" in result)) {
+      expect(result.permission).toBe("full");
+      expect(result.scopes).toEqual(["vault:journal:write"]);
+    }
+  });
+
+  test("revocation list unreachable on cold start → fail-closed 401 sanitized; full diagnostic routed to console.warn", async () => {
+    seedVault("journal");
+    // Hub is reachable for JWKS but the revocation endpoint 503s. Cold cache
+    // + first-fetch-fail = "unknown" outcome, surfaced as
+    // HubJwtError(code: "revocation_unavailable"). Client gets a code-shaped
+    // sentence; the implementation-detail phrasing ("no last-good cache")
+    // stays in the server-side audit log.
+    fixture.setRevocationFails(true);
+    const token = await signJwt(kp, {
+      iss: fixture.origin,
+      aud: "vault.journal",
+      scope: "vault:journal:read",
+    });
+    const config = readVaultConfig("journal")!;
+    const store = getVaultStore("journal");
+
+    const warnSpy = spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      const result = await authenticateVaultRequest(bearer(token), config, store.db);
+      expect("error" in result).toBe(true);
+      if ("error" in result) {
+        expect(result.error.status).toBe(401);
+        const body = (await result.error.json()) as { error: string; message: string };
+        // Client message: code-shaped, no internals.
+        expect(body.message).toBe("token cannot be validated: revocation list unavailable");
+        // The internal phrase "no last-good cache" is a scope-guard
+        // implementation detail and must not leak into the public response.
+        expect(body.message).not.toContain("last-good cache");
+      }
+      // Audit-log invariant: full diagnostic routed to console.warn so
+      // operators can distinguish cold-start from sustained outage.
+      expect(warnSpy).toHaveBeenCalledTimes(1);
+      const warnArg = warnSpy.mock.calls[0]![0] as string;
+      expect(warnArg).toContain("no last-good cache");
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
 });

package/src/auth.ts

@@ -275,6 +275,35 @@ async function authenticateHubJwt(
     return { permission, scopes: claims.scopes, legacyDerived: false, scoped_tags: null, vault_name: null };
   } catch (err) {
     if (err instanceof HubJwtError) {
+      // Revocation-related codes get sanitized client messages: server-side
+      // audit log carries the full diagnostic (jti for `revoked`,
+      // implementation-detail phrasing for `revocation_unavailable`); the
+      // unauthenticated caller gets a code-shaped sentence with no internals.
+      // This is the inheritable pattern across vault/scribe/agent — keep all
+      // revocation-related diagnostics server-side. Other HubJwtError codes
+      // (signature, audience, expired, etc.) carry generic messages and are
+      // forwarded as-is; the existing test suite pins those exact strings.
+      if (err.code === "revoked") {
+        console.warn(`[auth] hub JWT rejected: ${err.message}`);
+        return {
+          error: Response.json(
+            { error: "Unauthorized", message: "token has been revoked" },
+            { status: 401 },
+          ),
+        };
+      }
+      if (err.code === "revocation_unavailable") {
+        console.warn(`[auth] hub JWT rejected: ${err.message}`);
+        return {
+          error: Response.json(
+            {
+              error: "Unauthorized",
+              message: "token cannot be validated: revocation list unavailable",
+            },
+            { status: 401 },
+          ),
+        };
+      }
       return { error: Response.json({ error: "Unauthorized", message: err.message }, { status: 401 }) };
     }
     // Unknown failure shape — surface the message but stay 401.

package/src/hub-jwt.test.ts

@@ -14,7 +14,7 @@
  */
 import { describe, test, expect, beforeAll, afterAll, beforeEach } from "bun:test";
 import { generateKeyPair, exportJWK, SignJWT } from "jose";
-import { resetJwksCache, validateHubJwt, looksLikeJwt } from "./hub-jwt.ts";
+import { resetJwksCache, resetRevocationCache, validateHubJwt, looksLikeJwt } from "./hub-jwt.ts";
 
 interface Keypair {
   privateKey: CryptoKey;
@@ -53,11 +53,19 @@ function startJwksFixture(): JwksFixture {
     port: 0,
     fetch(req) {
       const url = new URL(req.url);
-      if (url.pathname !== "/.well-known/jwks.json") {
-        return new Response("not found", { status: 404 });
-      }
       if (down) return new Response("upstream down", { status: 503 });
-      return Response.json({ keys: keys.map((k) => k.publicJwk) });
+      if (url.pathname === "/.well-known/jwks.json") {
+        return Response.json({ keys: keys.map((k) => k.publicJwk) });
+      }
+      // scope-guard 0.2+ consults `/.well-known/parachute-revocation.json` on
+      // every JWT validation (when the token has a jti). Serve an empty list
+      // by default so unrelated tests in this file aren't fail-closed by a
+      // 404 on that endpoint. The integration tests (`auth-hub-jwt.test.ts`)
+      // own the revoked-jti / fail-closed cases separately.
+      if (url.pathname === "/.well-known/parachute-revocation.json") {
+        return Response.json({ generated_at: new Date().toISOString(), jtis: [] });
+      }
+      return new Response("not found", { status: 404 });
     },
   });
   return {
@@ -121,6 +129,9 @@ beforeEach(() => {
   fixture.setUnreachable(false);
   fixture.setKeys([kp]);
   resetJwksCache();
+  // Drop the per-process revocation cache so each test starts cold against
+  // the fixture (an empty list by default; tests opt into populated lists).
+  resetRevocationCache();
 });
 
 describe("looksLikeJwt", () => {

package/src/hub-jwt.ts

@@ -75,5 +75,14 @@ export function resetJwksCache(): void {
   guard.resetJwksCache();
 }
 
+/**
+ * Reset the cached revocation list. Tests use this to start from a clean
+ * fail-closed state between cases; production callers shouldn't need it
+ * (the cache refreshes itself on TTL expiry).
+ */
+export function resetRevocationCache(): void {
+  guard.resetRevocationCache();
+}
+
 export { HubJwtError, looksLikeJwt };
 export type { HubJwtClaims, ValidateHubJwtOptions };

package/src/mcp-http.ts

@@ -41,7 +41,6 @@ const TOOL_REQUIRED_VERB: Record<string, VaultVerb> = {
   "query-notes": "read",
   "list-tags": "read",
   "find-path": "read",
-  "synthesize-notes": "read",
   "vault-info": "read",
   "create-note": "write",
   "update-note": "write",
@@ -58,7 +57,10 @@ function requiredVerbForTool(toolName: string): VaultVerb {
 
 /** Handle scoped MCP at /vault/{name}/mcp (single vault). */
 export async function handleScopedMcp(req: Request, vaultName: string, auth: AuthResult): Promise<Response> {
-  const instruction = getServerInstruction(vaultName);
+  // Auth flows through to getServerInstruction so the connect-time
+  // markdown brief is filtered by `scoped_tags` — symmetric with the
+  // JSON `vault-info` wrapper.
+  const instruction = await getServerInstruction(vaultName, auth);
   return handleMcp(req, () => generateScopedMcpTools(vaultName, auth), `parachute-vault/${vaultName}`, vaultName, auth, instruction);
 }