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
20.5 KB
Raw Blame
/**
 * `o2b brain attest <keygen|sign|list|verify>` (delivery trust, Lane D
 * task D5).
 *
 * The operator surface over the attestation kernel. What these tests hold
 * the verb to:
 *
 *   - keygen prints paths only - never a byte of key material;
 *   - sign without keygen refuses by name (`attestation_key_missing`) and
 *     never mints a key;
 *   - the passphrase rides `--passphrase-from-env` or stdin, never argv,
 *     with the secret verb's blankness rule and exit code 2 for a broken
 *     route;
 *   - verify is the exit-code contract of `brain log verify`: 0 while the
 *     store is intact or merely appended, 1 on divergence or a bad
 *     signature, 2 on usage - because a check whose failure looks like
 *     its success is not a check;
 *   - `--json` carries the K4 shapes.
 *
 * Wrapped-key flows run in fresh subprocesses, the way a cron entry or a
 * script would reach the verb: one process holds an unlocked envelope,
 * the next does not.
 */

import { afterEach, beforeEach, expect, setDefaultTimeout, test } from "bun:test";
import {
  existsSync,
  mkdirSync,
  mkdtempSync,
  readFileSync,
  readdirSync,
  rmSync,
  writeFileSync,
} from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";

import { acquireLogLock, appendLogEvent } from "../../src/core/brain/log.ts";
import { brainDirs } from "../../src/core/brain/paths.ts";
import { attestationsDir } from "../../src/core/brain/attestation/record.ts";
import { writeVaultIdentity } from "../../src/core/brain/vault-identity.ts";
import { runCli as runCliRaw, type RunCliOptions } from "../helpers/run-cli.ts";

/**
 * keygen and sign read a passphrase from stdin when stdin is not a
 * terminal. Run in process they would read the test runner's own stdin,
 * which a runner started from a background shell holds open forever, so
 * every run here gets an explicit stdin: empty unless the test pipes one
 * (the operator who pipes nothing, the raw seed).
 */
const runCli = (args: ReadonlyArray<string>, opts: RunCliOptions = {}) =>
  runCliRaw(args, { stdin: "", ...opts });
import { CLI_SPAWN_BUDGET_MS } from "../helpers/cli-timeout.ts";
import { fakeCredential } from "../helpers/fake-credentials.ts";

// Every test here runs the CLI, most of them several times.
setDefaultTimeout(CLI_SPAWN_BUDGET_MS);

/**
 * Passphrases assembled at runtime so no source line carries a literal
 * shaped like a real credential (the fake-credentials doctrine); the
 * two stdin routes use distinct values the way two operators would.
 */
const STDIN_PASSPHRASE = fakeCredential("attest", "-passphrase-", "9137");
const STDIN_PASSPHRASE_ALT = fakeCredential("attest", "-passphrase-", "2468");
const ENV_ROUTE_PASSPHRASE = fakeCredential("env-route", "-pass-", "5150");

const DATE = "2026-06-03";

let tmp: string;
let vault: string;

beforeEach(() => {
  tmp = mkdtempSync(join(tmpdir(), "o2b-cli-attest-"));
  vault = join(tmp, "vault");
  mkdirSync(join(vault, "Brain", "log"), { recursive: true });
  writeFileSync(join(vault, "Brain", "_brain.yaml"), "schema_version: 1\n", "utf8");
  writeVaultIdentity(vault);
});

afterEach(() => {
  rmSync(tmp, { recursive: true, force: true });
});

function append(count: number, deviceId = ""): void {
  for (let i = 0; i < count; i++) {
    appendLogEvent(
      vault,
      {
        timestamp: `${DATE}T10:00:0${i}Z`,
        eventType: "note",
        body: { text: `event ${i}`, agent: "@tester" },
      },
      { deviceId },
    );
  }
}

function recordFiles(): string[] {
  const dir = attestationsDir(vault);
  return existsSync(dir) ? readdirSync(dir).toSorted() : [];
}

/** Edit one chained line in place: a forgery, not an append. */
function forgeLine(shardName: string): void {
  const path = join(vault, "Brain", "log", shardName);
  const rows = readFileSync(path, "utf8").trim().split("\n");
  const row = JSON.parse(rows[rows.length - 1]!);
  row.payload.text = "forged after the fact";
  rows[rows.length - 1] = JSON.stringify(row);
  writeFileSync(path, rows.join("\n") + "\n", "utf8");
}

test("keygen creates the key pair and prints paths only", async () => {
  const res = await runCli(["brain", "attest", "keygen", "--vault", vault]);
  expect(res.returncode).toBe(0);
  const privatePath = join(vault, ".open-second-brain", "keys", "attestation", "attestation.key");
  const publicPath = join(vault, ".open-second-brain", "keys", "attestation", "attestation.pub");
  expect(existsSync(privatePath)).toBe(true);
  expect(existsSync(publicPath)).toBe(true);
  expect(res.stdout).toContain(privatePath);
  expect(res.stdout).toContain(publicPath);
  // Paths only: no seed, no PEM body, nothing a screenshot could leak.
  expect(res.stdout).not.toMatch(/[0-9a-f]{64}/);
  expect(readFileSync(privatePath, "utf8").trim()).toMatch(/^[0-9a-f]{64}$/);
});

test("keygen twice refuses, and the refusal never replaces the key", async () => {
  await runCli(["brain", "attest", "keygen", "--vault", vault]);
  const before = readFileSync(
    join(vault, ".open-second-brain", "keys", "attestation", "attestation.key"),
    "utf8",
  );
  const res = await runCli(["brain", "attest", "keygen", "--vault", vault]);
  expect(res.returncode).toBe(1);
  expect(res.stderr).toContain("already exists");
  expect(
    readFileSync(
      join(vault, ".open-second-brain", "keys", "attestation", "attestation.key"),
      "utf8",
    ),
  ).toBe(before);
});

test("sign without keygen refuses by name and names the keygen remedy", async () => {
  append(2);
  const res = await runCli(["brain", "attest", "sign", "--vault", vault]);
  expect(res.returncode).toBe(1);
  expect(res.stderr).toContain("attestation_key_missing");
  expect(res.stderr).toContain("attest keygen");
  expect(recordFiles()).toEqual([]);
});

test("sign writes one file and list shows it with id, created_at and device", async () => {
  append(2);
  expect(await runCli(["brain", "attest", "keygen", "--vault", vault])).toMatchObject({
    returncode: 0,
  });
  const signed = await runCli(["brain", "attest", "sign", "--vault", vault]);
  expect(signed.returncode).toBe(0);
  expect(recordFiles()).toHaveLength(1);
  expect(recordFiles()[0]).toMatch(/^attest-\d{8}T\d{6}\d{3}Z\.json$/);

  const list = await runCli(["brain", "attest", "list", "--vault", vault]);
  expect(list.returncode).toBe(0);
  expect(list.stdout).toContain("attest-");
  expect(list.stdout).toMatch(/created/);
  expect(list.stdout).toMatch(/device/);
});

test("list is newest-first", async () => {
  append(1);
  await runCli(["brain", "attest", "keygen", "--vault", vault]);
  await runCli(["brain", "attest", "sign", "--vault", vault]);
  // A second sign lands a later instant; nudge the clock so the two
  // millisecond ids cannot collide.
  await new Promise((resolve) => setTimeout(resolve, 25));
  const second = await runCli(["brain", "attest", "sign", "--vault", vault]);
  expect(second.returncode).toBe(0);
  const list = await runCli(["brain", "attest", "list", "--vault", vault]);
  const ids = [...list.stdout.matchAll(/attest-\d{8}T\d{6}\d{3}Z/g)].map((m) => m[0]);
  expect(ids.length).toBeGreaterThanOrEqual(2);
  expect(ids[0]).toBe(recordFiles().at(-1)!.replace(".json", ""));
});

test("verify on an untouched vault exits zero with every shard intact", async () => {
  append(3);
  await runCli(["brain", "attest", "keygen", "--vault", vault]);
  await runCli(["brain", "attest", "sign", "--vault", vault]);
  const res = await runCli(["brain", "attest", "verify", "--vault", vault]);
  expect(res.returncode).toBe(0);
  expect(res.stdout).toContain("intact");
});

test("verify after a legitimate append exits zero naming the appended shard", async () => {
  append(3);
  await runCli(["brain", "attest", "keygen", "--vault", vault]);
  await runCli(["brain", "attest", "sign", "--vault", vault]);
  append(2);
  const res = await runCli(["brain", "attest", "verify", "--vault", vault]);
  expect(res.returncode).toBe(0);
  expect(res.stdout).toContain("appended");
});

test("verify after a forged edit exits one naming the diverged shard", async () => {
  append(3);
  await runCli(["brain", "attest", "keygen", "--vault", vault]);
  await runCli(["brain", "attest", "sign", "--vault", vault]);
  // Forge an APPENDED row: the attested head itself is the anchor the
  // record signed, and integrity below it is `brain log verify`'s
  // question, not this one.
  append(2);
  forgeLine("2026-06-03.jsonl");
  const res = await runCli(["brain", "attest", "verify", "--vault", vault]);
  expect(res.returncode).toBe(1);
  expect(res.stdout).toContain("diverged");
  expect(res.stdout).toContain("2026-06-03.jsonl");
});

test("a shard created after signing is growth, not unexplained drift", async () => {
  append(2);
  await runCli(["brain", "attest", "keygen", "--vault", vault]);
  await runCli(["brain", "attest", "sign", "--vault", vault]);
  // The next write lands in a NEW day shard: it is not an attested
  // shard, so no verdict says appended - but its file joining the log
  // directory and its head joining the manifest is exactly the growth
  // the cron contract reads as progress.
  appendLogEvent(
    vault,
    {
      timestamp: "2026-06-04T10:00:00Z",
      eventType: "note",
      body: { text: "the next day's first event", agent: "@tester" },
    },
    { deviceId: "" },
  );
  const res = await runCli(["brain", "attest", "verify", "--vault", vault]);
  expect(res.returncode).toBe(0);
  // The digest differs and the report reads it as growth, not damage -
  // the new shard is not an attested row, so the prose names the growth
  // itself instead of pointing at shard verdicts that do not exist.
  expect(res.stdout).toContain("(growth since signing explains it)");
  expect(res.stdout).not.toContain("no shard above explains it");
});

test("an appended shard does not hide ledger drift elsewhere", async () => {
  append(2);
  await runCli(["brain", "attest", "keygen", "--vault", vault]);
  await runCli(["brain", "attest", "sign", "--vault", vault]);
  append(1);
  // Real drift in another inventoried directory, beside the append.
  mkdirSync(join(vault, "Brain", "metrics"), { recursive: true });
  writeFileSync(join(vault, "Brain", "metrics", "surface-a.tester.jsonl"), "{}\n", "utf8");
  const res = await runCli(["brain", "attest", "verify", "--vault", vault]);
  expect(res.returncode).toBe(1);
  expect(res.stdout).toContain("store digest differs");
});

test("a store-digest drift no appended shard explains exits one", async () => {
  append(3);
  await runCli(["brain", "attest", "keygen", "--vault", vault]);
  await runCli(["brain", "attest", "sign", "--vault", vault]);
  // An inventoried ledger directory gains a file the log shards know
  // nothing about: every shard stays intact, the signature stays valid,
  // and only the store digest moves - damage the shard report cannot
  // name, which is exactly what this exit code exists to report.
  mkdirSync(join(vault, "Brain", "metrics"), { recursive: true });
  writeFileSync(join(vault, "Brain", "metrics", "surface-a.tester.jsonl"), "{}\n", "utf8");
  const res = await runCli(["brain", "attest", "verify", "--vault", vault]);
  expect(res.returncode).toBe(1);
  expect(res.stdout).toContain("store digest differs");
  expect(res.stdout).toContain("no shard above explains it");
});

test("verify --public-key verifies against exactly the named exported half", async () => {
  append(3);
  await runCli(["brain", "attest", "keygen", "--vault", vault]);
  await runCli(["brain", "attest", "sign", "--vault", vault]);
  const exported = join(vault, ".open-second-brain", "keys", "attestation", "attestation.pub");
  const outside = join(tmp, "operator-copy.pub");
  writeFileSync(outside, readFileSync(exported, "utf8"), "utf8");
  rmSync(exported);

  // The named half verifies the record even though the vault no longer
  // carries an export.
  const named = await runCli([
    "brain",
    "attest",
    "verify",
    "--vault",
    vault,
    "--public-key",
    outside,
  ]);
  expect(named.returncode).toBe(0);

  // A named half that does not exist is an invalid signature, never a
  // silent fall back.
  const missing = await runCli([
    "brain",
    "attest",
    "verify",
    "--vault",
    vault,
    "--public-key",
    join(tmp, "never-was.pub"),
  ]);
  expect(missing.returncode).toBe(1);

  // The operator CLI's own run may still derive the public half from the
  // local seed when the export is lost - the operator's machine, the
  // operator's key.
  const local = await runCli(["brain", "attest", "verify", "--vault", vault]);
  expect(local.returncode).toBe(0);
});

test("list reports a record that cannot be read on its own row and still lists the rest", async () => {
  append(2);
  await runCli(["brain", "attest", "keygen", "--vault", vault]);
  await runCli(["brain", "attest", "sign", "--vault", vault]);
  writeFileSync(
    join(vault, ".open-second-brain", "attestations", "attest-20990101T000000000Z.json"),
    "{not json at all",
    "utf8",
  );
  const list = await runCli(["brain", "attest", "list", "--vault", vault]);
  expect(list.returncode).toBe(0);
  expect(list.stdout).toContain("UNREADABLE");
  expect(list.stdout).toContain("attest-20990101T000000000Z.json");
  expect(list.stdout).toContain("corrupted JSON");

  const asJson = await runCli(["brain", "attest", "list", "--vault", vault, "--json"]);
  expect(asJson.returncode).toBe(0);
  const parsed = JSON.parse(asJson.stdout) as {
    attestations: unknown[];
    unreadable: Array<Record<string, string>>;
  };
  expect(parsed.attestations).toHaveLength(1);
  expect(parsed.unreadable).toHaveLength(1);
  expect(parsed.unreadable[0]!["reason"]).toContain("corrupted JSON");
});

test("verify with nothing signed says so and exits zero", async () => {
  append(1);
  const res = await runCli(["brain", "attest", "verify", "--vault", vault]);
  expect(res.returncode).toBe(0);
  expect(res.stdout).toMatch(/no attestation|nothing to verify/i);
});

test("a store that cannot be measured reads as its own fact, not as damage", async () => {
  append(3);
  await runCli(["brain", "attest", "keygen", "--vault", vault]);
  await runCli(["brain", "attest", "sign", "--vault", vault]);
  // A log lock held past the collector's bounded retry: the manifest
  // cannot be recomputed. The shard walk and the signature still ran,
  // so the report names what it knows and words the unknown as unknown.
  const release = acquireLogLock(brainDirs(vault).log);
  try {
    const res = await runCli(["brain", "attest", "verify", "--vault", vault]);
    expect(res.returncode).toBe(1);
    expect(res.stdout).toContain("could not be measured");
    expect(res.stdout).toContain("re-run");
    expect(res.stdout).not.toContain("diverged");
    // No digest reading exists for a run that measured nothing: neither
    // the match line nor a growth explanation may print beside the
    // unknown.
    expect(res.stdout).not.toContain("store digest");
    expect(res.stdout).not.toContain("log growth");
  } finally {
    release();
  }
}, 30_000);

test("a twin that predates its JSONL, and a JSONL whose twin never lands, are both growth", async () => {
  append(2);
  // A markdown day file with no JSONL yet (a legacy md-only day): it
  // joins the attested inventory with no chain head to attest.
  writeFileSync(join(vault, "Brain", "log", "2026-06-04.md"), "a markdown-only day\n", "utf8");
  await runCli(["brain", "attest", "keygen", "--vault", vault]);
  await runCli(["brain", "attest", "sign", "--vault", vault]);
  // The day then gains its JSONL: a new attested shard whose twin was
  // already in the inventory - the set reading, not a doubled list.
  appendLogEvent(
    vault,
    {
      timestamp: "2026-06-04T10:00:00Z",
      eventType: "note",
      body: { text: "the md-only day gains its sidecar", agent: "@tester" },
    },
    { deviceId: "" },
  );
  const lateTwin = await runCli(["brain", "attest", "verify", "--vault", vault]);
  expect(lateTwin.returncode).toBe(0);

  // A new JSONL shard whose markdown twin never landed (the appender's
  // own partial-failure shape): growth with a missing twin is not drift.
  appendLogEvent(
    vault,
    {
      timestamp: "2026-06-05T10:00:00Z",
      eventType: "note",
      body: { text: "the next day", agent: "@tester" },
    },
    { deviceId: "" },
  );
  rmSync(join(vault, "Brain", "log", "2026-06-05.md"));
  const noTwin = await runCli(["brain", "attest", "verify", "--vault", vault]);
  expect(noTwin.returncode).toBe(0);
});

test("usage errors exit two and the usage line names every verb", async () => {
  const bare = await runCli(["brain", "attest"]);
  expect(bare.returncode).toBe(2);
  expect(bare.stdout).toContain("keygen");
  expect(bare.stdout).toContain("verify");
  const unknown = await runCli(["brain", "attest", "frobnicate", "--vault", vault]);
  expect(unknown.returncode).toBe(2);
  expect(unknown.stderr).toContain("frobnicate");
  expect(unknown.stderr).toContain("keygen");
  // `brain attest --help` is answered by the shared VERB_HELP table, not
  // by this dispatcher, and is the help surface's row to pin.
});

test("json shapes: keygen paths, sign record, list rows, verify K4", async () => {
  append(2);
  const keygen = await runCli(["brain", "attest", "keygen", "--vault", vault, "--json"]);
  expect(keygen.returncode).toBe(0);
  const keygenJson = JSON.parse(keygen.stdout);
  expect(keygenJson.private_path).toContain("attestation.key");
  expect(keygenJson.public_path).toContain("attestation.pub");

  const signed = await runCli(["brain", "attest", "sign", "--vault", vault, "--json"]);
  expect(signed.returncode).toBe(0);
  const signJson = JSON.parse(signed.stdout);
  expect(signJson.id).toMatch(/^attest-\d{8}T\d{6}\d{3}Z$/);
  expect(signJson.path).toContain("attestations");
  expect(typeof signJson.store_digest).toBe("string");

  const list = await runCli(["brain", "attest", "list", "--vault", vault, "--json"]);
  const listJson = JSON.parse(list.stdout);
  expect(listJson.attestations).toHaveLength(1);
  expect(listJson.attestations[0].id).toBe(signJson.id);
  expect(typeof listJson.attestations[0].created_at).toBe("string");

  const verified = await runCli(["brain", "attest", "verify", "--vault", vault, "--json"]);
  expect(verified.returncode).toBe(0);
  const verifyJson = JSON.parse(verified.stdout);
  // The K4 AttestationVerification shape, field for field.
  expect(verifyJson.recordId).toBe(signJson.id);
  expect(verifyJson.signatureValid).toBe(true);
  expect(Array.isArray(verifyJson.shards)).toBe(true);
  expect(verifyJson.shards[0].shardId).toBe("2026-06-03.jsonl");
  expect(verifyJson.shards[0].state).toBe("intact");
  expect(verifyJson.storeDigestMatches).toBe(true);
});

test("passphrase ladder: wrap at keygen, sign from stdin in a fresh process", async () => {
  append(1);
  const first = await runCli(["brain", "attest", "keygen", "--vault", vault], {
    stdin: `${STDIN_PASSPHRASE}\n`,
    subprocess: true,
  });
  expect(first.returncode).toBe(0);
  const keyBytes = readFileSync(
    join(vault, ".open-second-brain", "keys", "attestation", "attestation.key"),
    "utf8",
  );
  expect(keyBytes).not.toMatch(/^[0-9a-f]{64}\s*$/); // wrapped, not raw seed

  const signed = await runCli(["brain", "attest", "sign", "--vault", vault], {
    stdin: `${STDIN_PASSPHRASE}\n`,
    subprocess: true,
  });
  expect(signed.returncode).toBe(0);
  expect(recordFiles()).toHaveLength(1);
});

test("passphrase ladder: a wrapped key with no source refuses by name", async () => {
  append(1);
  await runCli(["brain", "attest", "keygen", "--vault", vault], {
    stdin: `${STDIN_PASSPHRASE_ALT}\n`,
    subprocess: true,
  });
  const res = await runCli(["brain", "attest", "sign", "--vault", vault], { subprocess: true });
  expect(res.returncode).toBe(1);
  expect(res.stderr).toContain("passphrase");
  expect(recordFiles()).toEqual([]);
});

test("passphrase ladder: --passphrase-from-env with an unset variable exits two", async () => {
  const res = await runCli(
    ["brain", "attest", "keygen", "--vault", vault, "--passphrase-from-env", "O2B_ATTEST_MISSING"],
    {
      env: { O2B_ATTEST_MISSING: "" },
      subprocess: true,
    },
  );
  expect(res.returncode).toBe(2);
  expect(res.stderr).toContain("O2B_ATTEST_MISSING");
  expect(res.stderr).toContain("stdin");
});

test("passphrase ladder: --passphrase-from-env with a set variable wraps and signs", async () => {
  append(1);
  const keygen = await runCli(
    ["brain", "attest", "keygen", "--vault", vault, "--passphrase-from-env", "O2B_ATTEST_PASS"],
    { env: { O2B_ATTEST_PASS: ENV_ROUTE_PASSPHRASE }, subprocess: true },
  );
  expect(keygen.returncode).toBe(0);
  const signed = await runCli(
    ["brain", "attest", "sign", "--vault", vault, "--passphrase-from-env", "O2B_ATTEST_PASS"],
    { env: { O2B_ATTEST_PASS: ENV_ROUTE_PASSPHRASE }, subprocess: true },
  );
  expect(signed.returncode).toBe(0);
  expect(recordFiles()).toHaveLength(1);
});