@openparachute/vault 0.5.1 → 0.5.2-rc.2

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