@openparachute/vault 0.5.1 → 0.5.2-rc.1

package/core/src/types.ts

@@ -1,9 +1,9 @@
-import type { TagFieldSchema, TagRelationship, TagRecord } from "./tag-schemas.js";
+import type { TagFieldSchema, TagRelationship, TagRelationshipMap, TagRecord } from "./tag-schemas.js";
 import type { PrunedField } from "./indexed-fields.js";
 
 // ---- Re-exports ----
 
-export type { TagFieldSchema, TagRelationship, TagRecord } from "./tag-schemas.js";
+export type { TagFieldSchema, TagRelationship, TagRelationshipMap, TagRecord } from "./tag-schemas.js";
 export type { PrunedField } from "./indexed-fields.js";
 
 // ---- Note ----
@@ -25,6 +25,14 @@ export interface Note {
   updatedAt?: string;
   tags?: string[];
   links?: Link[];
+  /**
+   * Opt-in link degree (raw row count, both directions by default). Present
+   * only when the caller requests it via `include_link_count` (REST/MCP).
+   * Surfaced the same way `links`/`attachments` are — an extra key injected
+   * onto the response after the base shape. See `getLinkCounts` in links.ts
+   * for the exact degree semantics (self-loop = 2 under `both`).
+   */
+  linkCount?: number;
 }
 
 // ---- Link ----
@@ -59,6 +67,16 @@ export interface VaultStats {
   tagCount: number;
   attachmentCount: number;
   linkCount: number;
+  /**
+   * Total bytes of all note content, computed as the sum of the UTF-8 byte
+   * length of every note's `content`. The SQL uses `LENGTH(CAST(content AS
+   * BLOB))` deliberately: SQLite's bare `LENGTH(text)` returns the number of
+   * *characters*, not bytes, so a note full of multibyte UTF-8 (emoji, CJK,
+   * accents) would undercount its true on-disk/on-wire footprint. Casting to
+   * BLOB forces `LENGTH` to count raw bytes. This is the logical content size,
+   * not the physical DB-file size (see `usage.ts:dbBytes` for the latter).
+   */
+  contentBytes: number;
 }
 
 // ---- Query Options ----
@@ -115,6 +133,12 @@ export interface QueryOpts {
   // declared `indexed: true`; errors loudly otherwise. Direction is taken
   // from `sort` (default "asc") and `created_at` is appended as a stable
   // tiebreaker.
+  //
+  // The pseudo-field `link_count` is special-cased (no indexed-field
+  // declaration needed): it sorts by link DEGREE — the both-directions
+  // raw row count — using the same directional-sum definition as the
+  // `linkCount` response field, so the sort key equals the field value for
+  // every note (self-loops included). See `queryNotes`/`getLinkCounts`.
   orderBy?: string;
   limit?: number;
   offset?: number;
@@ -153,6 +177,8 @@ export interface NoteSummary {
   createdAt: string;
   updatedAt?: string;
   tags?: string[];
+  /** Opt-in link degree (see `Note.linkCount`). */
+  linkCount?: number;
 }
 
 /**
@@ -169,6 +195,8 @@ export interface NoteIndex {
   metadata?: Record<string, unknown>;
   byteSize: number;
   preview: string;
+  /** Opt-in link degree (see `Note.linkCount`). */
+  linkCount?: number;
 }
 
 /** Link with hydrated note summaries. */
@@ -313,7 +341,7 @@ export interface Store {
     patch: {
       description?: string | null;
       fields?: Record<string, TagFieldSchema> | null;
-      relationships?: Record<string, TagRelationship> | null;
+      relationships?: TagRelationshipMap | null;
       parent_names?: string[] | null;
     },
   ): Promise<TagRecord>;

package/package.json

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

package/src/auth.test.ts

@@ -26,7 +26,8 @@ import {
   hashKey,
 } from "./config.ts";
 import { getVaultStore, clearVaultStoreCache } from "./vault-store.ts";
-import { authenticateVaultRequest, authenticateGlobalRequest } from "./auth.ts";
+import { authenticateVaultRequest, authenticateGlobalRequest, warnLegacyGlobalApiKeys } from "./auth.ts";
+import type { StoredKey } from "./config.ts";
 
 let tmpHome: string;
 let prevHome: string | undefined;
@@ -442,3 +443,38 @@ describe("auth — VAULT_AUTH_TOKEN server-wide operator bearer", () => {
     expect("error" in result).toBe(true);
   });
 });
+
+// ---------------------------------------------------------------------------
+// Legacy GLOBAL api_keys boot warning (security review — multi-user
+// hardening). Cross-vault credentials in config.yaml must be surfaced loudly
+// at boot, but never altered. Pure-function unit tests (no server boot).
+// ---------------------------------------------------------------------------
+describe("warnLegacyGlobalApiKeys (legacy cross-vault key boot warning)", () => {
+  function key(id: string): StoredKey {
+    return {
+      id,
+      label: id,
+      key_hash: `sha256:${id}`,
+      scope: "full",
+      created_at: new Date().toISOString(),
+    };
+  }
+
+  test("warns when global api_keys are present", () => {
+    const msgs: string[] = [];
+    const count = warnLegacyGlobalApiKeys([key("a"), key("b")], (m) => msgs.push(m));
+    expect(count).toBe(2);
+    expect(msgs).toHaveLength(1);
+    expect(msgs[0]).toContain("legacy GLOBAL api_key");
+    expect(msgs[0]).toContain("CROSS-VAULT");
+    // Heads-up only — must signal it does NOT alter the keys.
+    expect(msgs[0]).toContain("remain active");
+  });
+
+  test("silent when there are no global api_keys", () => {
+    const msgs: string[] = [];
+    expect(warnLegacyGlobalApiKeys([], (m) => msgs.push(m))).toBe(0);
+    expect(warnLegacyGlobalApiKeys(undefined, (m) => msgs.push(m))).toBe(0);
+    expect(msgs).toHaveLength(0);
+  });
+});

package/src/auth.ts

@@ -171,6 +171,35 @@ export function warnLegacyOnce(cacheKey: string, context: string): void {
   );
 }
 
+/**
+ * Boot-time warning for legacy GLOBAL `api_keys` in `config.yaml` (security
+ * review — multi-user hardening). Those keys are CROSS-VAULT credentials: a
+ * single key authenticates against EVERY vault on this server (see the global
+ * `api_keys` branch in `authenticate` ~L283). That predates per-vault keys +
+ * tag-scoped hub JWTs and is a confidentiality hazard once a server hosts
+ * multiple users' vaults — one user's global key reads another's vault.
+ *
+ * WARNING ONLY — never touches the keys (the operator owns them). The
+ * verification flagged 6 such keys on the live box; this surfaces them at
+ * boot so they're rotated/removed before multi-user sharing. Returns the
+ * count it warned about (0 = silent) so callers / tests can assert.
+ */
+export function warnLegacyGlobalApiKeys(
+  globalApiKeys: StoredKey[] | undefined,
+  warn: (msg: string) => void = console.warn,
+): number {
+  const count = globalApiKeys?.length ?? 0;
+  if (count === 0) return 0;
+  warn(
+    `[auth] WARNING: ${count} legacy GLOBAL api_key(s) found in config.yaml. ` +
+      "These are CROSS-VAULT credentials (each grants access to every vault on this server) " +
+      "and predate per-vault keys + tag-scoped hub JWTs. Before multi-user sharing, ROTATE or " +
+      "REMOVE them — a global key leaks one user's vault to another. They remain active (the " +
+      "operator owns them); this is a heads-up, not an automatic change.",
+  );
+  return count;
+}
+
 /** Read-only tools (the only tools allowed for "read" permission). */
 const READ_TOOLS = new Set([
   "query-notes",

package/src/cli.ts

@@ -102,6 +102,13 @@ import { listTokens, revokeToken, migrateVaultKeys } from "./token-store.ts";
 import { VAULT_SCOPES } from "./scopes.ts";
 import { validateVaultName, decideInitVaultName } from "./vault-name.ts";
 import { getVaultStore } from "./vault-store.ts";
+import {
+  defaultMirrorConfig,
+  resolveMirrorPath,
+  writeMirrorConfigForVault,
+  type MirrorConfig,
+} from "./mirror-config.ts";
+import { bootstrapInternalMirror } from "./mirror-manager.ts";
 import { selfRegister } from "./self-register.ts";
 import {
   hasOwnerPassword,
@@ -814,11 +821,15 @@ async function cmdCreate(args: string[]) {
   // POST /vaults shells out to this CLI and parses stdout). Errors still go
   // to stderr as plain text and exit nonzero — callers branch on exit code.
   const jsonMode = args.includes("--json");
+  // `--no-mirror` opts THIS create out of the default internal live mirror
+  // even when the server-wide `default_mirror` knob is `internal`. Parity for
+  // operators who want one bare vault without flipping the global default.
+  const noMirror = args.includes("--no-mirror");
   // Greedy strip of any `--*` token to recover the positional vault name.
-  // Today only `--json` is recognized; any other `--foo` is silently dropped.
-  // If a future flag (e.g. `--force`, `--dry-run`) is added, the parsing
-  // here needs to whitelist it — otherwise an invalid flag becomes a silent
-  // no-op rather than a usage error.
+  // `--json` and `--no-mirror` are recognized; any other `--foo` is silently
+  // dropped. If a future flag (e.g. `--force`, `--dry-run`) is added, the
+  // parsing here needs to whitelist it — otherwise an invalid flag becomes a
+  // silent no-op rather than a usage error.
   const positional = args.filter((a) => !a.startsWith("--"));
   const name = positional[0];
   if (!name) {
@@ -826,8 +837,14 @@ async function cmdCreate(args: string[]) {
     process.exit(1);
   }
 
-  if (!/^[a-zA-Z0-9_-]+$/.test(name)) {
-    console.error("Vault name must contain only letters, numbers, hyphens, and underscores.");
+  // Lowercase-only (security review — multi-user hardening). An uppercase
+  // vault name flips the audience case (`vault.<Name>` vs `vault.<name>`)
+  // and drifts from hub-side / init-path lowercasing, breaking JWT
+  // audience matching. `init` already enforces lowercase via
+  // `validateVaultName`; mirror that rule here so uppercase can't enter
+  // through `create` either.
+  if (!/^[a-z0-9_-]+$/.test(name)) {
+    console.error("Vault name must be lowercase alphanumeric with hyphens or underscores (no uppercase).");
     process.exit(1);
   }
   if (name === "list") {
@@ -846,7 +863,7 @@ async function cmdCreate(args: string[]) {
 
   ensureConfigDirSync();
   const wasFirst = listVaults().length === 0;
-  const credential = await createVault(name);
+  const credential = await createVault(name, noMirror ? { enableMirror: false } : {});
 
   // If this is the only vault now, make it the default so unscoped routes
   // (/mcp, /api/*, /oauth/*) target it. Avoids the "single vault named
@@ -3333,7 +3350,59 @@ async function mintBootstrapCredential(name: string): Promise<VaultCredential> {
  * is reachable — vault#282 Stage 2). The DB is created lazily via
  * `getVaultStore` so migrations + schema run; we no longer write any pvt_* row.
  */
-async function createVault(name: string): Promise<VaultCredential> {
+interface CreateVaultOptions {
+  /**
+   * Override the server-wide `default_mirror` knob for this one create.
+   * `--no-mirror` on `parachute-vault create` sets this to `false` so the
+   * vault is created with no mirror config even when the knob is `internal`.
+   * Unset → fall back to the `default_mirror` global config knob (default
+   * `internal`).
+   */
+  enableMirror?: boolean;
+  /**
+   * Test seam threaded straight into `bootstrapInternalMirror` (default
+   * `Bun.which`). Inject a fn returning `null` to exercise the
+   * git-not-installed best-effort path without uninstalling git from the
+   * test host.
+   */
+  which?: (cmd: string) => string | null;
+}
+
+/**
+ * The History / "Live Mirror" preset, written at create time when the
+ * `default_mirror` knob resolves to `internal`. Matches the History preset
+ * the admin SPA's VaultMirror page applies:
+ *   `{enabled:true, location:internal, sync_mode:events, auto_commit:true,
+ *    auto_push:false}`.
+ * Built on top of `defaultMirrorConfig()` so the non-preset fields
+ * (commit_template, safety_net_seconds) stay canonical.
+ */
+function historyPresetMirrorConfig(): MirrorConfig {
+  return {
+    ...defaultMirrorConfig(),
+    enabled: true,
+    location: "internal",
+    sync_mode: "events",
+    auto_commit: true,
+    auto_push: false,
+  };
+}
+
+/**
+ * Resolve whether a freshly created vault should get the internal mirror.
+ * Precedence: explicit per-create override (`--no-mirror`) → server-wide
+ * `default_mirror` knob (default `internal`).
+ */
+function shouldEnableCreateTimeMirror(opts: CreateVaultOptions): boolean {
+  if (opts.enableMirror !== undefined) return opts.enableMirror;
+  // Default to "internal" when the knob is unset — backup-on-by-default.
+  return (readGlobalConfig().default_mirror ?? "internal") === "internal";
+}
+
+async function createVault(
+  name: string,
+  opts: CreateVaultOptions = {},
+): Promise<VaultCredential> {
   const config: VaultConfig = {
     name,
     api_keys: [],
@@ -3344,6 +3413,47 @@ async function createVault(name: string): Promise<VaultCredential> {
   // Touch the store so the vault's SQLite DB + schema are created. No token
   // row is written — vault is a pure hub resource-server post-0.5.0.
   getVaultStore(name);
+
+  // Default new vaults to an internal live mirror (local git backup of the
+  // markdown projection). Backup-on-by-default; GitHub off-site backup is an
+  // opt-in upgrade layered on top later. Opt out via the `default_mirror: off`
+  // global knob (operators on git-less / disk-constrained / cloud boxes) or
+  // the `--no-mirror` flag (this one create only).
+  //
+  // BEST-EFFORT, NON-FATAL: write the mirror config first (so the operator's
+  // intent persists even if git is absent), then attempt the bootstrap. A
+  // git-less box leaves the config written but inactive + logs an actionable
+  // hint — it must NEVER fail the vault create. Create-time ONLY: existing
+  // vaults are never retroactively migrated.
+  if (shouldEnableCreateTimeMirror(opts)) {
+    const mirrorConfig = historyPresetMirrorConfig();
+    writeMirrorConfigForVault(name, mirrorConfig);
+    const mirrorPath = resolveMirrorPath(vaultDir(name), mirrorConfig);
+    if (mirrorPath) {
+      try {
+        const result = await bootstrapInternalMirror(mirrorPath, opts.which);
+        if (!result.ok) {
+          // git-not-installed (or refuse-to-clobber) — config stays written,
+          // mirror just isn't active yet. Surface an actionable line; the
+          // vault create succeeds regardless.
+          console.error(
+            `Note: local git backup configured but not yet active — ${result.error} ` +
+              `Install git to activate; the backup turns on automatically on the next vault restart.`,
+          );
+        }
+      } catch (err) {
+        // Defense-in-depth: bootstrapInternalMirror already converts the
+        // git-missing case into a non-throwing { ok:false } result, but a
+        // truly unexpected throw must still not fail the create.
+        console.error(
+          `Note: local git backup configured but bootstrap hit an unexpected error ` +
+            `(${(err as Error).message ?? err}). The vault was still created; ` +
+            `the backup will retry on the next vault restart.`,
+        );
+      }
+    }
+  }
+
   return mintBootstrapCredential(name);
 }
 
@@ -3448,7 +3558,13 @@ Setup:
   parachute --version                      Print the installed version (alias: -v, version)
 
 Vaults:
-  parachute-vault create <name> [--json]   Create a new vault (--json: emit { name, token, paths, set_as_default })
+  parachute-vault create <name> [--json] [--no-mirror]
+                                           Create a new vault (--json: emit { name, token, paths, set_as_default }).
+                                           New vaults default to an internal live mirror — a local git backup of
+                                           the markdown projection (backup on by default; GitHub off-site is an
+                                           opt-in upgrade). --no-mirror creates a bare vault with no mirror config.
+                                           Operators can flip the server-wide default with 'default_mirror: off' in
+                                           config.yaml (recommended for cloud / disk-constrained boxes).
   parachute-vault list                     List all vaults
   parachute-vault remove <name> [--yes]    Remove a vault
   parachute-vault mcp-install [--mint|--token <t>]

package/src/config.test.ts

@@ -250,6 +250,22 @@ describe("config", () => {
     writeGlobalConfig({ port: 1940, autostart: false });
     expect(readGlobalConfig().autostart).toBe(false);
   });
+
+  test("round-trips default_mirror: internal|off", () => {
+    // Absent: createVault falls back to the in-code default ("internal" —
+    // backup-on-by-default). The knob is only persisted when explicitly set.
+    writeGlobalConfig({ port: 1940 });
+    expect(readGlobalConfig().default_mirror).toBeUndefined();
+
+    // Explicit internal — new vaults get the History-preset local git mirror.
+    writeGlobalConfig({ port: 1940, default_mirror: "internal" });
+    expect(readGlobalConfig().default_mirror).toBe("internal");
+
+    // Explicit off — the opt-out operators set on git-less / disk-constrained
+    // / cloud boxes so new vaults are created with no mirror config.
+    writeGlobalConfig({ port: 1940, default_mirror: "off" });
+    expect(readGlobalConfig().default_mirror).toBe("off");
+  });
 });
 
 // ---------------------------------------------------------------------------

package/src/config.ts

@@ -115,6 +115,17 @@ export function vaultConfigPath(name: string): string {
   return join(vaultDir(name), "vault.yaml");
 }
 
+/**
+ * Per-vault attachments directory: `<vaultDir>/assets`, or the `ASSETS_DIR`
+ * env override when set (single-assets-root deployments). Lives here next to
+ * the other path helpers — neutral ground that both `routes.ts` (upload/serve)
+ * and `usage.ts` (footprint dir-walk) import without a cycle. `routes.ts`
+ * re-exports it for the existing callers (mirror-deps, server, triggers, …).
+ */
+export function assetsDir(name: string): string {
+  return process.env.ASSETS_DIR ?? join(vaultDir(name), "assets");
+}
+
 // ---------------------------------------------------------------------------
 // Types
 // ---------------------------------------------------------------------------
@@ -280,6 +291,29 @@ export interface GlobalConfig {
    * resolved path. See `./mirror-config.ts`.
    */
   mirror?: MirrorConfigType;
+  /**
+   * Server-wide DEFAULT for newly created vaults' backup posture. Decides
+   * whether `createVault` writes the History-preset internal mirror
+   * (local git backup of the markdown projection) at create time.
+   *
+   *   - `"internal"` (default) — new vaults get a local git mirror enabled
+   *     out of the box (backup-on-by-default). The History preset:
+   *     `{enabled:true, location:internal, sync_mode:events, auto_commit:true,
+   *     auto_push:false}`. GitHub off-site backup remains an opt-in upgrade.
+   *   - `"off"` — new vaults are created with no mirror config (the historical
+   *     pre-default behavior). The escape hatch for git-less / disk-constrained
+   *     boxes and cloud deploys, where doubling disk per vault is unwanted.
+   *     Cloud / container deploys SHOULD set this to `off`.
+   *
+   * Create-time ONLY — this knob does NOT retroactively enable mirrors on
+   * already-created vaults (that would ~double disk across every existing
+   * vault). Existing-vault opt-in is a separate, deliberate follow-up.
+   *
+   * The container/cloud first-boot auto-create path in `server.ts` does NOT
+   * funnel through `createVault`, so it is unaffected by this knob and stays
+   * mirror-off regardless — matching the recommended cloud posture.
+   */
+  default_mirror?: "internal" | "off";
   /**
    * Auto-transcribe configuration for the vault↔scribe handoff (vault#353,
    * design 2026-05-21 Part 2). When `enabled: true` AND scribe is discoverable
@@ -1162,6 +1196,7 @@ export function readGlobalConfig(): GlobalConfig {
       const totpSecretMatch = yaml.match(/^totp_secret:\s*"([^"]+)"/m);
       const discoveryMatch = yaml.match(/^discovery:\s*(enabled|disabled)/m);
       const autostartMatch = yaml.match(/^autostart:\s*(true|false)/m);
+      const defaultMirrorMatch = yaml.match(/^default_mirror:\s*(internal|off)/m);
       // auto_transcribe block — currently single boolean `enabled` (vault#353).
       // Parsed as a nested 2-space-indent block so future fields can grow under
       // it without breaking the regex; only `enabled` is read for v0.6.
@@ -1190,6 +1225,9 @@ export function readGlobalConfig(): GlobalConfig {
       if (autostartMatch) {
         config.autostart = autostartMatch[1]! === "true";
       }
+      if (defaultMirrorMatch) {
+        config.default_mirror = defaultMirrorMatch[1]! as "internal" | "off";
+      }
       if (autoTranscribeEnabled !== undefined) {
         config.auto_transcribe = { enabled: autoTranscribeEnabled };
       }
@@ -1259,6 +1297,7 @@ export function writeGlobalConfig(config: GlobalConfig): void {
   if (config.default_vault) lines.push(`default_vault: ${config.default_vault}`);
   if (config.discovery) lines.push(`discovery: ${config.discovery}`);
   if (config.autostart !== undefined) lines.push(`autostart: ${config.autostart}`);
+  if (config.default_mirror) lines.push(`default_mirror: ${config.default_mirror}`);
   if (config.owner_password_hash) {
     lines.push(`owner_password_hash: "${config.owner_password_hash}"`);
   }

package/src/mcp-tools.ts

@@ -7,6 +7,7 @@
 
 import { generateMcpTools } from "../core/src/mcp.ts";
 import type { McpToolDef } from "../core/src/mcp.ts";
+import type { Note } from "../core/src/types.ts";
 import {
   buildVaultProjection,
   projectionToMarkdown,
@@ -18,6 +19,7 @@ import { hasScopeForVault, parseScopes, validateMintedScopes } from "./scopes.ts
 import type { AuthResult } from "./auth.ts";
 import {
   expandTokenTagScope,
+  filterHydratedLinksByTagScope,
   noteWithinTagScope,
   tagsWithinScope,
 } from "./tag-scope.ts";
@@ -117,11 +119,30 @@ export function generateScopedMcpTools(
   callerBearer?: string | null,
 ): McpToolDef[] {
   const store = getVaultStore(vaultName);
-  const tools = generateMcpTools(store);
+
+  // Tag-scope confidentiality (security review): when the session is
+  // tag-scoped, build an expand-visibility predicate so `query-notes`'s
+  // `expand_links` inlining can't embed out-of-scope note content. The
+  // predicate reads from a SHARED holder that `applyTagScopeWrappers`
+  // populates with the resolved allowlist before core's execute runs the
+  // (synchronous) expansion — so by the time core calls `isVisible(note)`
+  // the allowlist is ready. Core stays scope-unaware: it only receives the
+  // plain closure. Unscoped sessions pass no predicate (unchanged path).
+  const scoped = Boolean(auth?.scoped_tags && auth.scoped_tags.length > 0);
+  const allowedHolder: { value: Set<string> | null } = { value: null };
+  const rawTags = scoped ? auth!.scoped_tags : null;
+  const expandVisibility = scoped
+    ? (note: Note) => noteWithinTagScope(note, allowedHolder.value, rawTags)
+    : undefined;
+
+  const tools = generateMcpTools(
+    store,
+    expandVisibility ? { expandVisibility } : undefined,
+  );
 
   overrideVaultInfo(tools, vaultName, auth);
   applyTagDependencyGuards(tools, vaultName);
-  applyTagScopeWrappers(tools, vaultName, auth);
+  applyTagScopeWrappers(tools, vaultName, auth, allowedHolder);
 
   // manage-token is server-only (needs token-store + auth context), so it
   // lives here rather than in core. Always appended to the surface; the
@@ -181,6 +202,7 @@ function applyTagScopeWrappers(
   tools: McpToolDef[],
   vaultName: string,
   auth: AuthResult | undefined,
+  allowedHolder?: { value: Set<string> | null },
 ): void {
   if (!auth || !auth.scoped_tags || auth.scoped_tags.length === 0) return;
   const store = getVaultStore(vaultName);
@@ -188,12 +210,40 @@ function applyTagScopeWrappers(
   let allowedPromise: Promise<Set<string> | null> | null = null;
   const getAllowed = (): Promise<Set<string> | null> => {
     if (!allowedPromise) {
-      allowedPromise = expandTokenTagScope(store, auth.scoped_tags);
+      allowedPromise = expandTokenTagScope(store, auth.scoped_tags).then((a) => {
+        // Publish the resolved allowlist into the shared holder so the
+        // expand-visibility predicate (wired in generateScopedMcpTools and
+        // baked into the query-notes expand context) sees the same set.
+        // The query-notes wrapper awaits getAllowed() before calling the
+        // core execute that runs expansion, so the holder is populated in
+        // time. Security review: closes the expand_links content leak.
+        if (allowedHolder) allowedHolder.value = a;
+        return a;
+      });
     }
     return allowedPromise;
   };
   const rawTags = auth.scoped_tags;
 
+  // Scrub a returned note's hydrated `links` array (present when the caller
+  // set `include_links`) so out-of-scope NEIGHBOR summaries (id/path/tags)
+  // don't leak — symmetric with the REST `include_links` fix. Mutates in
+  // place and returns the note for chaining. No-op when `links` is absent.
+  //
+  // Ordering invariant: reading `allowedHolder.value` here is safe ONLY
+  // because every wrapper that calls scrubNoteLinks first does
+  // `await getAllowed()` (which populates the holder) before `orig(params)`
+  // and before this scrub runs. So by the time we read `holder.value` it is
+  // the resolved allowlist, never the initial `null`. The `?? null` fallback
+  // is the unscoped/holder-absent path; `filterHydratedLinksByTagScope` then
+  // keys off `rawTags` (non-null here) for the actual scope check.
+  const scrubNoteLinks = (n: any): any => {
+    if (n && Array.isArray(n.links)) {
+      n.links = filterHydratedLinksByTagScope(n.links, allowedHolder?.value ?? null, rawTags);
+    }
+    return n;
+  };
+
   wrapReadTool(tools, "query-notes", async (orig, params) => {
     const allowed = await getAllowed();
     const result = await orig(params);
@@ -203,7 +253,9 @@ function applyTagScopeWrappers(
     //   - `{notes, next_cursor}` (cursor mode, vault#313)
     //   - `{...note}` with `id`+`tags` (single-note by id)
     if (Array.isArray(result)) {
-      return result.filter((n: any) => noteWithinTagScope(n, allowed, rawTags));
+      return result
+        .filter((n: any) => noteWithinTagScope(n, allowed, rawTags))
+        .map(scrubNoteLinks);
     }
     if (
       result &&
@@ -214,13 +266,15 @@ function applyTagScopeWrappers(
     ) {
       const r = result as { notes: any[]; next_cursor: string | null };
       return {
-        notes: r.notes.filter((n: any) => noteWithinTagScope(n, allowed, rawTags)),
+        notes: r.notes
+          .filter((n: any) => noteWithinTagScope(n, allowed, rawTags))
+          .map(scrubNoteLinks),
         next_cursor: r.next_cursor,
       };
     }
     if (result && typeof result === "object" && "id" in result && "tags" in result) {
       return noteWithinTagScope(result as any, allowed, rawTags)
-        ? result
+        ? scrubNoteLinks(result)
         : { error: "Note not found", id: (result as any).id };
     }
     return result;