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
16.6 KB
Raw Blame
/**
 * The export boundary redacts (wiring-what-exists, unit C1).
 *
 * ## The defect
 *
 * Six paths hand vault bytes to a destination outside the vault. Five of
 * them never called the shared redactor: `brain bank-export`,
 * `brain graph-export`, `brain okf-export`, `brain export`, and
 * `export-config` - the last using a private copy that matched five
 * substrings against KEY NAMES only and never looked at a value. A vault
 * note carrying a pasted vendor key left the machine verbatim, and an
 * `export-config` snapshot carrying a credential under an innocuous key
 * name did the same.
 *
 * Three properties are pinned here, one per failure mode:
 *
 *   1. a vendor-prefixed key placed where each path actually carries it
 *      comes out redacted;
 *   2. a payload the redactor could only partially scan is REFUSED, with
 *      nothing written - an export that scanned half its bytes cannot
 *      honestly report success;
 *   3. an export with nothing to redact is byte-identical to what the
 *      unredacted exporter produces, proven by running both rather than
 *      by asserting it in prose.
 *
 * ## What it deliberately does not cover
 *
 * The `continuity export` verb, which redacts upstream in its read model
 * and is declared that way in the egress registry rather than re-scanned
 * here; the redactor's own detection rules, which have their own unit
 * coverage; and whether a redacted bundle still round-trips through
 * `bank-import` - a bundle whose secrets were removed is not the same
 * document, and pretending the round-trip is lossless is the claim this
 * unit exists to stop making.
 */

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

import { runCli } from "../helpers/run-cli.ts";
import { exportVaultGraph } from "../../src/core/brain/portability/graph.ts";
import { buildOkfBundle } from "../../src/core/brain/portability/okf.ts";
import { exportPreferencesLlmsTxt } from "../../src/core/brain/export.ts";
import { REDACTION_PLACEHOLDER } from "../../src/core/redactor.ts";
import { EGRESS_OUTCOME, redactForEgress } from "../../src/core/egress/guard.ts";
import { FAKE_VENDOR_KEY } from "../helpers/fake-credentials.ts";
import { CLI_SPAWN_BUDGET_MS } from "../helpers/cli-timeout.ts";

// Tests here spawn processes; see tests/helpers/cli-timeout.ts.
setDefaultTimeout(CLI_SPAWN_BUDGET_MS);

/** A vendor-prefixed credential token: caught by shape, not by a word list. */
const VENDOR_TOKEN = FAKE_VENDOR_KEY;

let tmp: string;
let vault: string;
let config: string;

beforeEach(() => {
  tmp = mkdtempSync(join(tmpdir(), "o2b-egress-"));
  vault = join(tmp, "vault");
  config = join(tmp, "config.yaml");
});
afterEach(() => rmSync(tmp, { recursive: true, force: true }));

const ENV = (): { env: Record<string, string> } => ({
  env: { OPEN_SECOND_BRAIN_CONFIG: config },
});

async function bootstrap(): Promise<void> {
  expect((await runCli(["init", "--vault", vault, "--name", "Egress"], ENV())).returncode).toBe(0);
  expect((await runCli(["brain", "init", "--vault", vault], ENV())).returncode).toBe(0);
}

/** A note whose title, alias and body each carry the same vendor token. */
function seedLeakyNote(): void {
  writeFileSync(
    join(vault, "Leaky.md"),
    `---\ntitle: ${VENDOR_TOKEN}\naliases:\n  - ${VENDOR_TOKEN}\nprovenance: ${VENDOR_TOKEN}\n---\n` +
      `api_key=${VENDOR_TOKEN}\n\nbare ${VENDOR_TOKEN} in prose.\n`,
  );
}

/** A clean note: nothing in it has the shape of a credential. */
function seedCleanNote(): void {
  writeFileSync(join(vault, "Clean.md"), "---\ntitle: Clean\n---\nlinks to [[Other]].\n");
}

async function seedPreference(slug: string, principle: string): Promise<void> {
  const r = await runCli(
    [
      "brain",
      "feedback",
      "--vault",
      vault,
      "--topic",
      slug,
      "--signal",
      "positive",
      "--principle",
      principle,
      "--scope",
      "writing",
      "--force-confirmed",
      "--agent",
      "claude",
    ],
    ENV(),
  );
  expect(r.returncode).toBe(0);
}

describe("a vendor-prefixed key does not leave through any export path", () => {
  test("brain bank-export", async () => {
    await bootstrap();
    seedLeakyNote();
    await seedPreference("leak", `use ${VENDOR_TOKEN} for the call`);
    const r = await runCli(["brain", "bank-export", "--vault", vault], ENV());
    expect(r.returncode).toBe(0);
    expect(r.stdout).not.toContain(VENDOR_TOKEN);
    expect(r.stdout).toContain(REDACTION_PLACEHOLDER);
    // Still a bundle, not mangled bytes.
    expect((JSON.parse(r.stdout) as { schema: string }).schema).toBe("1");
  });

  test("brain graph-export", async () => {
    await bootstrap();
    seedLeakyNote();
    const r = await runCli(["brain", "graph-export", "--vault", vault], ENV());
    expect(r.returncode).toBe(0);
    expect(r.stdout).not.toContain(VENDOR_TOKEN);
    expect(Array.isArray((JSON.parse(r.stdout) as { nodes: unknown[] }).nodes)).toBe(true);
  });

  test("brain okf-export", async () => {
    await bootstrap();
    seedLeakyNote();
    const out = join(tmp, "okf");
    const r = await runCli(["brain", "okf-export", "--vault", vault, "--out", out], ENV());
    expect(r.returncode).toBe(0);
    const manifest = readFileSync(join(out, "okf.json"), "utf8");
    expect(manifest).not.toContain(VENDOR_TOKEN);
    // okf.json must still parse: redaction runs over the manifest tree
    // before serialisation, never over the serialised bytes.
    expect((JSON.parse(manifest) as { schema: string }).schema).toBe("1");
    const page = readFileSync(join(out, "concepts", "Leaky.md"), "utf8");
    expect(page).not.toContain(VENDOR_TOKEN);
    expect(page).toContain(REDACTION_PLACEHOLDER);

    // And it still PARSES. `toContain(PLACEHOLDER)` was the whole check
    // here, which an unquoted `***REDACTED***` passes while making the
    // frontmatter an unresolved YAML alias - rejected by Obsidian and by
    // every spec-compliant reader, accepted only by this repo's lenient
    // parser. Asserted with a strict parser for that reason.
    const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(page)?.[1];
    expect(typeof frontmatter).toBe("string");
    const parsed = (Bun as unknown as { YAML: { parse: (s: string) => unknown } }).YAML.parse(
      frontmatter!,
    ) as Record<string, unknown>;
    expect(parsed["title"]).toBe(REDACTION_PLACEHOLDER);
    expect(parsed["aliases"]).toEqual([REDACTION_PLACEHOLDER]);
  });

  test("brain export --format json", async () => {
    await bootstrap();
    await seedPreference("leak", `use ${VENDOR_TOKEN} for the call`);
    const r = await runCli(["brain", "export", "--vault", vault, "--format", "json"], ENV());
    expect(r.returncode).toBe(0);
    expect(r.stdout).not.toContain(VENDOR_TOKEN);
    expect((JSON.parse(r.stdout) as { schema: number }).schema).toBe(1);
  });

  test("brain export --format llms-txt", async () => {
    await bootstrap();
    await seedPreference("leak", `use ${VENDOR_TOKEN} for the call`);
    const r = await runCli(["brain", "export", "--vault", vault, "--format", "llms-txt"], ENV());
    expect(r.returncode).toBe(0);
    expect(r.stdout).not.toContain(VENDOR_TOKEN);
  });

  test("export-config redacts a credential hiding under an innocuous key name", async () => {
    // The defect the key-name-only copy could not see: `redactMapping`
    // matched five substrings against the KEY and never looked at the
    // value, so a token stored under a name it did not recognise was
    // written out verbatim.
    await bootstrap();
    writeFileSync(config, `vault_dir: ${vault}\nnotes_scratch: ${VENDOR_TOKEN}\napi_key: plain\n`);
    const out = join(tmp, "config.json");
    const r = await runCli(["export-config", "--config", config, "--output", out], ENV());
    expect(r.returncode).toBe(0);
    const text = readFileSync(out, "utf8");
    expect(text).not.toContain(VENDOR_TOKEN);
    const parsed = JSON.parse(text) as { config: Record<string, string> };
    // The key-name rule still fires, and now shares the redactor's placeholder.
    expect(parsed.config["api_key"]).toBe(REDACTION_PLACEHOLDER);
    expect(parsed.config["notes_scratch"]).toBe(REDACTION_PLACEHOLDER);
    expect(parsed.config["vault_dir"]).toBe(vault);
  });
});

/** Just over the redactor's 1 MiB scan window, in cheap-to-scan filler. */
function oversizedBody(): string {
  return "- item\n".repeat(Math.ceil((1024 * 1024) / 7) + 8);
}

describe("a partially-scanned payload is refused, not written", () => {
  test("okf-export refuses and writes nothing", async () => {
    await bootstrap();
    writeFileSync(join(vault, "Huge.md"), `---\ntitle: Huge\n---\n${oversizedBody()}`);
    const out = join(tmp, "okf-huge");
    const r = await runCli(["brain", "okf-export", "--vault", vault, "--out", out], ENV());
    expect(r.returncode).not.toBe(0);
    expect(r.stderr).toContain("scan window");
    expect(existsSync(join(out, "okf.json"))).toBe(false);
  });

  test("bank-export refuses rather than printing a partially-scanned bundle", async () => {
    await bootstrap();
    // The bank bundle carries no page body, so the oversized field is an
    // alias - the widest string a page contract does carry.
    writeFileSync(
      join(vault, "Huge.md"),
      `---\ntitle: Huge\naliases:\n  - "${"a".repeat(1024 * 1024 + 16)}"\n---\nbody\n`,
    );
    const r = await runCli(["brain", "bank-export", "--vault", vault], ENV());
    expect(r.returncode).not.toBe(0);
    expect(r.stderr).toContain("scan window");
    expect(r.stdout).toBe("");
  });

  test("the guard itself names the refusal rather than returning text", () => {
    const verdict = redactForEgress("brain-bank-export", { note: "x".repeat(1024 * 1024 + 1) });
    expect(verdict.outcome).toBe(EGRESS_OUTCOME.refusedScanTruncated);
  });

  test("a payload inside the window is released", () => {
    const verdict = redactForEgress("brain-bank-export", { note: "hello" });
    expect(verdict.outcome).toBe(EGRESS_OUTCOME.released);
    if (verdict.outcome !== EGRESS_OUTCOME.released) throw new Error("unreachable");
    expect(verdict.payload).toEqual({ note: "hello" });
    expect(verdict.redacted).toBe(false);
  });
});

describe("an export with nothing to redact is byte-identical", () => {
  // Proven by running the unredacted exporter in-process and comparing
  // the bytes the CLI wrote, rather than by asserting the property.

  test("graph-export", async () => {
    await bootstrap();
    seedCleanNote();
    const r = await runCli(["brain", "graph-export", "--vault", vault], ENV());
    expect(r.returncode).toBe(0);
    expect(r.stdout).toBe(JSON.stringify(exportVaultGraph(vault), null, 2) + "\n");
  });

  test("okf-export page files and index", async () => {
    await bootstrap();
    seedCleanNote();
    const out = join(tmp, "okf-clean");
    const r = await runCli(["brain", "okf-export", "--vault", vault, "--out", out], ENV());
    expect(r.returncode).toBe(0);
    const expected = buildOkfBundle(vault);
    for (const file of expected.files) {
      // `okf.json` carries `generated_at`, which moves between runs.
      if (file.path === "okf.json") continue;
      // A page's `generated.at` is stamped to the second, and the CLI run
      // and this in-process build may fall on either side of one.
      const unstamped = (text: string): string =>
        text.replace(/^(generated: \{.*\bat: ")[^"]+(")/m, "$1<at>$2");
      expect(`${file.path}: ${unstamped(readFileSync(join(out, file.path), "utf8"))}`).toBe(
        `${file.path}: ${unstamped(file.contents)}`,
      );
    }
  });

  test("brain export --format llms-txt", async () => {
    await bootstrap();
    await seedPreference("alpha", "principle alpha");
    const r = await runCli(["brain", "export", "--vault", vault, "--format", "llms-txt"], ENV());
    expect(r.returncode).toBe(0);
    expect(r.stdout).toBe(exportPreferencesLlmsTxt(vault));
  });

  test("brain export --format json carries no omitted key when nothing is denied", async () => {
    // The json lane has no timestamp-free byte fixture to compare against,
    // so its byte-identity property is pinned through the envelope's
    // shape: the `omitted` field is absent-when-empty, which is what
    // keeps a reservation-free vault's bytes what they always were.
    await bootstrap();
    await seedPreference("alpha", "principle alpha");
    const r = await runCli(["brain", "export", "--vault", vault, "--format", "json"], ENV());
    expect(r.returncode).toBe(0);
    const payload = JSON.parse(r.stdout) as Record<string, unknown>;
    expect("omitted" in payload).toBe(false);
    // And nothing was withheld, so the omission notice is silent too.
    expect(r.stderr).not.toContain("left out");
  });

  test("the byte-identity fixtures are not empty", () => {
    // A comparison over nothing passes for the wrong reason.
    expect(VENDOR_TOKEN.length).toBeGreaterThan(16);
  });
});

describe("a visibility-reserved preference is left out and named by the shared lanes", () => {
  /** Hand-add an informal privacy marker, the way an operator does. */
  function stampPrefMarker(slug: string, line: string): void {
    const abs = join(vault, "Brain", "preferences", `pref-${slug}.md`);
    writeFileSync(abs, readFileSync(abs, "utf8").replace(/^---\n/, `---\n${line}\n`));
  }

  /** Hand-edit the frontmatter id the same way an operator does. */
  function stampPrefId(slug: string, id: string): void {
    const abs = join(vault, "Brain", "preferences", `pref-${slug}.md`);
    writeFileSync(abs, readFileSync(abs, "utf8").replace(/^id: .*$/m, `id: ${id}`));
  }

  test("a reserved preference whose id carries URL credentials is named scrubbed, never raw", async () => {
    // The frontmatter id is read verbatim, so a hand-edited one can carry
    // a credential. The egress guard scrubs the identifier inside the
    // payload it releases; the stderr notices must name the SAME scrubbed
    // form on every lane, never the raw secret the vault still holds.
    await bootstrap();
    await seedPreference("reserved", "principle reserved");
    stampPrefMarker("reserved", "access: private");
    stampPrefId("reserved", "pref-https://bert:[email protected]/ops");

    const bank = await runCli(["brain", "bank-export", "--vault", vault], ENV());
    expect(bank.returncode).toBe(0);
    const payload = JSON.parse(bank.stdout) as {
      preferences_omitted?: ReadonlyArray<{ id: string }>;
    };
    expect(payload.preferences_omitted?.[0]?.id).toBe(
      `pref-https://${REDACTION_PLACEHOLDER}@internal.example/ops`,
    );
    expect(bank.stderr).toContain(`${REDACTION_PLACEHOLDER}@internal.example/ops`);
    expect(bank.stderr).toContain("left out");
    expect(bank.stderr).not.toContain("hunter2");

    const txt = await runCli(["brain", "export", "--vault", vault, "--format", "llms-txt"], ENV());
    expect(txt.returncode).toBe(0);
    expect(txt.stderr).toContain(`${REDACTION_PLACEHOLDER}@internal.example/ops`);
    expect(txt.stderr).toContain("left out");
    expect(txt.stderr).not.toContain("hunter2");
    expect(txt.stdout).not.toContain("hunter2");
  });

  test("bank-export omits it from the bundle and names it on stderr", async () => {
    await bootstrap();
    await seedPreference("reserved", "principle reserved");
    stampPrefMarker("reserved", "access: private");

    const r = await runCli(["brain", "bank-export", "--vault", vault], ENV());
    expect(r.returncode).toBe(0);
    const payload = JSON.parse(r.stdout) as {
      preferences: ReadonlyArray<{ id: string }>;
      preferences_omitted?: ReadonlyArray<{
        id: string;
        reason: string;
        denied_by: string;
      }>;
    };
    expect(payload.preferences.map((p) => p.id)).toEqual([]);
    expect(payload.preferences_omitted).toEqual([
      { id: "pref-reserved", reason: "visibility", denied_by: "access" },
    ]);
    expect(r.stderr).toContain("pref-reserved");
    expect(r.stderr).toContain("left out");
    // stderr only: the bundle names the omission as data, not prose.
    expect(r.stdout).not.toContain("left out");
  });

  test("the bank bundle carries no preferences_omitted key when nothing is denied", async () => {
    // The bank bundle's byte-identity property, pinned through its shape:
    // the section-scoped omission field is absent-when-empty, so a vault
    // with no reservation serialises exactly the keys it always did.
    await bootstrap();
    await seedPreference("alpha", "principle alpha");

    const r = await runCli(["brain", "bank-export", "--vault", vault], ENV());
    expect(r.returncode).toBe(0);
    const payload = JSON.parse(r.stdout) as Record<string, unknown>;
    expect("preferences_omitted" in payload).toBe(false);
    expect(r.stderr).not.toContain("left out");
  });
});