Skip to content

Local-first 🧠 memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.

TypeScript
13.7 KB
Raw Blame
/**
 * Named per-agent MCP token store (write-side-trust, Task 3).
 *
 * Hash-at-rest: the store keeps sha256(tokenMaterial) beside a
 * non-secret prefix, and the minted material exists in plaintext only
 * for the moment the mint answer carries it - shown once, never
 * stored, never audited. Every credential-shaped literal here is
 * assembled by `fakeCredential`, so no source line carries a string
 * shaped like a real token.
 */

import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import {
  existsSync,
  mkdirSync,
  mkdtempSync,
  readdirSync,
  readFileSync,
  rmSync,
  statSync,
  writeFileSync,
} from "node:fs";
import { createHash } from "node:crypto";
import { tmpdir } from "node:os";
import { join } from "node:path";
import lockfile from "proper-lockfile";

import {
  MCP_TOKENS_SCHEMA_VERSION,
  ROTATION_GRACE_MS,
  TOKEN_PREFIX_LENGTH,
  listAgentTokens,
  mintAgentToken,
  resolveAgentForToken,
  revokeAgentToken,
  rotateAgentToken,
  setTokenStoreClock,
} from "../../../../src/core/brain/secrets/token-store.ts";
import {
  secretsDir,
  tokenStorePath,
  withSecretsLock,
} from "../../../../src/core/brain/secrets/store.ts";
import { fakeCredential } from "../../../helpers/fake-credentials.ts";
import { IS_WINDOWS } from "../../../helpers/platform.ts";

let tempRoot: string;
let vault: string;

beforeEach(() => {
  // A vault name with spaces and CJK characters: the store round-trips
  // vault paths no filesystem grammar should have to care about.
  tempRoot = mkdtempSync(join(tmpdir(), "o2b-token-store-"));
  vault = join(tempRoot, "brain vault 東");
  // A legacy Brain/ tree: an unswitched machine (a vault without one is store-only).
  mkdirSync(join(vault, "Brain"), { recursive: true });
});

afterEach(() => {
  // Tests that walk the rotation grace window substitute the store
  // clock; every test restores the real one on the way out.
  setTokenStoreClock(null);
  rmSync(tempRoot, { recursive: true, force: true });
});

/** sha256 hex, the at-rest form the store persists. */
function hashOf(material: string): string {
  return createHash("sha256").update(material).digest("hex");
}

function mint(name = "mcp_token_codex", agent = "codex") {
  return mintAgentToken(vault, name, agent);
}

function auditActions(): string[] {
  const auditDir = join(vault, "Brain", "log", "secret-custody");
  if (!existsSync(auditDir)) return [];
  return readdirSync(auditDir)
    .flatMap((f) => readFileSync(join(auditDir, f), "utf8").split("\n"))
    .filter((l) => l.trim().length > 0)
    .map((l) => (JSON.parse(l) as { action: string }).action);
}

function auditLines(): string[] {
  const auditDir = join(vault, "Brain", "log", "secret-custody");
  return readdirSync(auditDir)
    .flatMap((f) => readFileSync(join(auditDir, f), "utf8").split("\n"))
    .filter((l) => l.trim().length > 0);
}

describe("mintAgentToken", () => {
  test("returns material exactly once and persists only the hash plus a non-secret prefix", () => {
    const { tokenMaterial, record } = mint();
    expect(tokenMaterial).toMatch(/^osbt_/);
    expect(record).toMatchObject({
      name: "mcp_token_codex",
      agent: "codex",
      status: "active",
      token_hash: hashOf(tokenMaterial),
      created_at: expect.any(String),
    });
    // The prefix is a display aid, not a credential: a cut of the front
    // of the material, never the whole of it.
    expect(record.token_prefix).toBe(tokenMaterial.slice(0, TOKEN_PREFIX_LENGTH));
    expect(record.token_prefix.length).toBeLessThan(tokenMaterial.length);

    const raw = readFileSync(tokenStorePath(vault), "utf8");
    expect(raw).not.toContain(tokenMaterial);
    const parsed = JSON.parse(raw) as {
      version: number;
      tokens: Record<string, { token_hash: string }>;
    };
    expect(parsed.version).toBe(MCP_TOKENS_SCHEMA_VERSION);
    expect(parsed.tokens["mcp_token_codex"]?.token_hash).toBe(hashOf(tokenMaterial));
  });

  test("the store file is created 0600 on POSIX", () => {
    if (IS_WINDOWS) return; // access there is the owner ACL, pinned via custodyTargets
    mint();
    const mode = statSync(tokenStorePath(vault)).mode & 0o777;
    expect(mode).toBe(0o600);
  });

  test("a fresh vault keeps the store absent until the first mint", () => {
    expect(listAgentTokens(vault)).toEqual([]);
    expect(resolveAgentForToken(vault, fakeCredential("osbt_", "nothing-here"))).toBeNull();
    expect(existsSync(secretsDir(vault))).toBe(false);
  });

  test("names validate mcp_token_<slug> in the $secret: grammar", () => {
    expect(() => mint("codex")).toThrow(/name/);
    expect(() => mint("mcp_token_")).toThrow(/name/);
    expect(() => mint("MCP_TOKEN_CODEX")).toThrow(/name/);
    expect(() => mint("mcp-token-codex")).toThrow(/name/);
    expect(() => mint("mcp_token_codex", " ")).toThrow(/agent/);
  });

  test("an existing name refuses mint and names rotate", () => {
    mint();
    expect(() => mint()).toThrow(/rotate/);
  });

  test("writes serialize under the secrets store lock", () => {
    // The lock anchors on the secrets directory, which a first write
    // creates through the keyfile path; build it here so the held lock
    // describes the same directory a real writer would hold.
    mkdirSync(secretsDir(vault), { recursive: true });
    const release = lockfile.lockSync(secretsDir(vault), { stale: 10_000, realpath: false });
    try {
      expect(() => mint()).toThrow(/secrets store lock/);
    } finally {
      void release();
    }
    mint();
    expect(listAgentTokens(vault)).toHaveLength(1);
  });

  test("two named tokens coexist and land one mint audit record each", () => {
    mint("mcp_token_codex", "codex");
    mint("mcp_token_grok", "grok");
    expect(listAgentTokens(vault).map((t) => t.name)).toEqual([
      "mcp_token_codex",
      "mcp_token_grok",
    ]);
    expect(auditActions().filter((a) => a === "mcp_token_minted")).toHaveLength(2);
  });
});

describe("listAgentTokens", () => {
  test("sorted by name, never carrying the material", () => {
    const grok = mint("mcp_token_grok", "grok");
    const codex = mint("mcp_token_codex", "codex");
    const listed = listAgentTokens(vault);
    expect(listed.map((t) => t.name)).toEqual(["mcp_token_codex", "mcp_token_grok"]);
    expect(JSON.stringify(listed)).not.toContain(codex.tokenMaterial);
    expect(JSON.stringify(listed)).not.toContain(grok.tokenMaterial);
  });
});

describe("resolveAgentForToken", () => {
  test("matches the presented material by hash; unknown material answers null", () => {
    const { tokenMaterial } = mint();
    expect(resolveAgentForToken(vault, tokenMaterial)).toEqual({
      agent: "codex",
      name: "mcp_token_codex",
    });
    expect(resolveAgentForToken(vault, fakeCredential("osbt_", "unknown-material"))).toBeNull();
    expect(resolveAgentForToken(vault, "")).toBeNull();
    expect(resolveAgentForToken(vault, tokenMaterial.slice(0, 8))).toBeNull();
  });

  test("a revoked token answers null, exactly like an unknown one", () => {
    const { tokenMaterial } = mint();
    expect(revokeAgentToken(vault, "mcp_token_codex")).toBe(true);
    expect(resolveAgentForToken(vault, tokenMaterial)).toBeNull();
    expect(listAgentTokens(vault)[0]?.status).toBe("revoked");
  });

  test("a rotation takes effect on the next call without any restart, with the previous material alive through the grace window", () => {
    const first = mint();
    expect(resolveAgentForToken(vault, first.tokenMaterial)?.agent).toBe("codex");
    const second = rotateAgentToken(vault, "mcp_token_codex");
    expect(second.record.status).toBe("active");
    expect(second.record.rotated_at).toEqual(expect.any(String));
    // The store records the hash it replaced, so the old material can
    // stay resolvable for a bounded window.
    expect(second.record.rotated_from_hash).toBe(first.record.token_hash);

    // No restart: the new material authenticates on the very next
    // resolve - and the old one keeps authenticating beside it, so the
    // caller holding it does not fail while the new one is placed.
    expect(resolveAgentForToken(vault, second.tokenMaterial)).toEqual({
      agent: "codex",
      name: "mcp_token_codex",
    });
    expect(resolveAgentForToken(vault, first.tokenMaterial)).toEqual({
      agent: "codex",
      name: "mcp_token_codex",
    });

    // The window is bounded: past rotated_at + ROTATION_GRACE_MS the old
    // material resolves exactly like an unknown one, and the new one is
    // untouched.
    setTokenStoreClock(() => Date.now() + ROTATION_GRACE_MS + 1_000);
    expect(resolveAgentForToken(vault, first.tokenMaterial)).toBeNull();
    expect(resolveAgentForToken(vault, second.tokenMaterial)).toEqual({
      agent: "codex",
      name: "mcp_token_codex",
    });
  });

  test("a second rotation moves the grace to the newest replaced hash; the older material dies at once", () => {
    const first = mint();
    const second = rotateAgentToken(vault, "mcp_token_codex");
    const third = rotateAgentToken(vault, "mcp_token_codex");
    expect(third.record.rotated_from_hash).toBe(second.record.token_hash);
    // Only the PREVIOUS hash is kept: the first material, already two
    // generations old, resolves like an unknown one immediately.
    expect(resolveAgentForToken(vault, first.tokenMaterial)).toBeNull();
    expect(resolveAgentForToken(vault, second.tokenMaterial)?.agent).toBe("codex");
    expect(resolveAgentForToken(vault, third.tokenMaterial)?.agent).toBe("codex");
  });

  test("revocation stays immediate across a rotation's grace window", () => {
    const first = mint();
    const second = rotateAgentToken(vault, "mcp_token_codex");
    expect(revokeAgentToken(vault, "mcp_token_codex")).toBe(true);
    expect(resolveAgentForToken(vault, first.tokenMaterial)).toBeNull();
    expect(resolveAgentForToken(vault, second.tokenMaterial)).toBeNull();
  });

  test("a store rewritten by another process is picked up through the mtime cache", () => {
    // Simulate a rotation performed by a different process (the CLI)
    // while a long-lived server holds its read cache: rewrite the store
    // file out from under the cache and resolve again.
    const stale = mint();
    expect(resolveAgentForToken(vault, stale.tokenMaterial)?.agent).toBe("codex");
    const elsewhere = fakeCredential("osbt_", "rotated-elsewhere-9c22");
    const file = JSON.parse(readFileSync(tokenStorePath(vault), "utf8")) as {
      version: number;
      tokens: Record<string, unknown>;
    };
    file.tokens["mcp_token_codex"] = {
      name: "mcp_token_codex",
      agent: "codex",
      status: "active",
      token_hash: hashOf(elsewhere),
      token_prefix: elsewhere.slice(0, TOKEN_PREFIX_LENGTH),
      created_at: "2026-06-05T10:00:00Z",
    };
    writeFileSync(tokenStorePath(vault), JSON.stringify(file, null, 2) + "\n", { mode: 0o600 });
    expect(resolveAgentForToken(vault, stale.tokenMaterial)).toBeNull();
    expect(resolveAgentForToken(vault, elsewhere)?.agent).toBe("codex");
  });
});

describe("rotateAgentToken", () => {
  test("re-mints under the same name and keeps created_at", () => {
    const first = mint();
    const second = rotateAgentToken(vault, "mcp_token_codex");
    expect(second.record.created_at).toBe(first.record.created_at);
    expect(second.record.token_hash).not.toBe(first.record.token_hash);
    expect(listAgentTokens(vault)).toHaveLength(1);
  });

  test("an unknown name refuses by name; a revoked one stays revoked", () => {
    expect(() => rotateAgentToken(vault, "mcp_token_ghost")).toThrow(/unknown token/);
    mint();
    revokeAgentToken(vault, "mcp_token_codex");
    expect(() => rotateAgentToken(vault, "mcp_token_codex")).toThrow(/revoked/);
  });

  test("revoke then revoke again answers true then false, one audit record", () => {
    mint();
    expect(revokeAgentToken(vault, "mcp_token_codex")).toBe(true);
    expect(revokeAgentToken(vault, "mcp_token_codex")).toBe(false);
    expect(auditActions().filter((a) => a === "mcp_token_revoked")).toHaveLength(1);
  });
});

describe("custody audit", () => {
  test("mint, rotate and revoke land no-values records; material never appears", () => {
    const minted = mint();
    rotateAgentToken(vault, "mcp_token_codex");
    revokeAgentToken(vault, "mcp_token_codex");
    const actions = auditActions();
    expect(actions).toContain("mcp_token_minted");
    expect(actions).toContain("mcp_token_rotated");
    expect(actions).toContain("mcp_token_revoked");
    const everything = auditLines().join("\n");
    expect(everything).not.toContain(minted.tokenMaterial);
    expect(everything).not.toContain(minted.record.token_hash);
  });

  test("the rotation audit row carries replaced: true", () => {
    mint();
    rotateAgentToken(vault, "mcp_token_codex");
    const auditDir = join(vault, "Brain", "log", "secret-custody");
    const rows = readdirSync(auditDir)
      .flatMap((f) => readFileSync(join(auditDir, f), "utf8").split("\n"))
      .filter((l) => l.trim().length > 0)
      .map((l) => JSON.parse(l) as { action: string; details?: Record<string, unknown> });
    const rotated = rows.filter((r) => r.action === "mcp_token_rotated");
    expect(rotated).toHaveLength(1);
    expect(rotated[0]?.details).toMatchObject({ replaced: true, agent: "codex" });
  });
});

describe("the Windows custody ACL covers the token store", () => {
  test("an existing mcp-tokens.json joins custodyTargets", () => {
    mint();
    const { custodyTargets } = require("../../../../src/core/brain/secrets/store.ts") as {
      custodyTargets: (v: string) => ReadonlyArray<readonly [string, string]>;
    };
    expect(custodyTargets(vault).map(([p]) => p)).toContain(tokenStorePath(vault));
  });
});

describe("the store lock stays with the store module", () => {
  test("withSecretsLock serialises a token write the same as a custody write", () => {
    let ran = false;
    withSecretsLock(vault, () => {
      ran = true;
    });
    expect(ran);
  });
});