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
/**
 * The permissions document as a shared setting (design D14 item 3, review
 * finding F461): `permissions.document` holds the YAML text
 * `Brain/_permissions.yaml` held. Only the operator sets it; every gate
 * reads it, with no vault too; an unswitched machine with no setting still
 * reads the legacy file; and doctor warns when deny rules sit in a legacy
 * file no gate reads.
 */
import { afterEach, describe, expect, test } from "bun:test";
import { chmodSync, rmSync, writeFileSync } from "node:fs";
import { join } from "node:path";

import type {
  DoctorCheckContext,
  DoctorFindings,
} from "../../../../src/core/brain/doctor/check.ts";
import {
  PERMISSIONS_LEGACY_ONLY_CODE,
  PERMISSIONS_UNREADABLE_CODE,
  permissionsDocumentCheck,
  permissionsLegacyOnlyCheck,
} from "../../../../src/core/brain/doctor/permissions-check.ts";
import {
  PERMISSIONS_DOCUMENT_SETTING,
  PermissionsDocumentError,
} from "../../../../src/core/brain/permissions/document.ts";
import {
  loadPermissionsDocumentFor,
  PERMISSIONS_SETTING_LABEL,
} from "../../../../src/core/brain/permissions/document-source.ts";
import {
  BrainSettingError,
  setBrainSetting,
} from "../../../../src/core/brain/policy/settings-write.ts";
import {
  resolveWriteDisposition,
  WriteRefusedError,
} from "../../../../src/core/brain/write-disposition.ts";
import { appendRecord } from "../../../../src/core/store/appender.ts";
import { AUTHORITY_FIELD, SETTING_SET_KIND } from "../../../../src/core/store/constants.ts";
import { openStore } from "../../../../src/core/store/store-open.ts";
import { CHMOD_CANNOT_DENY } from "../../../helpers/platform.ts";
import { makeStoreEnv, type StoreEnv } from "../../store/fixtures/store-env.ts";
import { partitionRecords, switchDevice } from "../store-only/fixtures.ts";

const DENY_ALL = "version: 1\ndefault_action: deny\n";
const ALLOW_ALL = "version: 1\ndefault_action: allow\n";

let env: StoreEnv | null = null;
afterEach(() => {
  env?.cleanup();
  env = null;
});

const human = (vault: string) => ({ vault, authority: "human" as const, agent: "o" });
const agent = (vault: string) => ({ vault, authority: "agent" as const, agent: "a" });

function writeLegacy(vault: string, text: string): void {
  writeFileSync(join(vault, "Brain", "_permissions.yaml"), text, "utf8");
}

function refusal(fn: () => unknown): string {
  try {
    fn();
  } catch (err) {
    if (err instanceof WriteRefusedError || err instanceof BrainSettingError) {
      return err.constructor.name;
    }
    throw err;
  }
  return "none";
}

describe("permissions.document setting", () => {
  test("an agent cannot set it on either kind of machine; the operator can", () => {
    env = makeStoreEnv("osb-perm-src-op-");
    const unswitched = (() => {
      try {
        setBrainSetting(agent(env!.vault), PERMISSIONS_DOCUMENT_SETTING, ALLOW_ALL);
      } catch (err) {
        return err instanceof BrainSettingError ? err.code : String(err);
      }
      return "written";
    })();
    expect(unswitched).toBe("operator_only_setting");
    switchDevice(env.storeRoot);
    expect(() =>
      setBrainSetting(agent(env!.vault), PERMISSIONS_DOCUMENT_SETTING, ALLOW_ALL),
    ).toThrow(BrainSettingError);
    expect(partitionRecords(env.storeRoot, "shared").some((r) => r.kind === "setting-set")).toBe(
      false,
    );
    expect(setBrainSetting(human(env.vault), PERMISSIONS_DOCUMENT_SETTING, DENY_ALL).changed).toBe(
      true,
    );
  });

  test("a value that is not a valid document is refused", () => {
    env = makeStoreEnv("osb-perm-src-invalid-");
    let code = "written";
    try {
      setBrainSetting(human(env.vault), PERMISSIONS_DOCUMENT_SETTING, "version: 2\n");
    } catch (err) {
      code = err instanceof BrainSettingError ? err.code : String(err);
    }
    expect(code).toBe("invalid_setting_value");
  });

  test("a switched machine enforces the setting and ignores the legacy file", () => {
    env = makeStoreEnv("osb-perm-src-switched-");
    writeLegacy(env.vault, ALLOW_ALL);
    switchDevice(env.storeRoot);
    expect(loadPermissionsDocumentFor(env.vault).document).toBeNull();
    expect(refusal(() => resolveWriteDisposition(env!.vault, "notes"))).toBe("none");
    setBrainSetting(human(env.vault), PERMISSIONS_DOCUMENT_SETTING, DENY_ALL);
    const loaded = loadPermissionsDocumentFor(env.vault);
    expect(loaded.path).toBe(PERMISSIONS_SETTING_LABEL);
    expect(loaded.document?.default_action).toBe("deny");
    expect(refusal(() => resolveWriteDisposition(env!.vault, "notes"))).toBe("WriteRefusedError");
  });

  test("a lost private partition stays out of the write gate's refusal text", () => {
    env = makeStoreEnv("osb-perm-src-lost-private-");
    switchDevice(env.storeRoot);
    // A read on the switched machine records the partitions it holds.
    expect(loadPermissionsDocumentFor(env.vault).document).toBeNull();
    rmSync(join(env.storeRoot, "private", "store.json"));
    let caught: unknown = null;
    try {
      resolveWriteDisposition(env.vault, "notes");
    } catch (err) {
      caught = err;
    }
    expect(caught).toBeInstanceOf(PermissionsDocumentError);
    const err = caught as PermissionsDocumentError;
    expect(err.message).toContain(PERMISSIONS_SETTING_LABEL);
    expect(err.message).not.toContain("private/");
    expect(err.message).not.toContain("partition leave");
    // The raw cause rides along for the operator's own doctor.
    expect((err.cause as Error).message).toContain("private/store.json");
  });

  test("with no vault the deny still holds", () => {
    env = makeStoreEnv("osb-perm-src-novault-", { legacyTree: false, configureVault: false });
    expect(refusal(() => resolveWriteDisposition(null, "signals"))).toBe("none");
    appendRecord(openStore({ root: env.storeRoot, device: "dev-a" }), {
      partition: "shared",
      stream: "settings",
      kind: SETTING_SET_KIND,
      agent: "o",
      body: { [AUTHORITY_FIELD]: "human", key: PERMISSIONS_DOCUMENT_SETTING, value: DENY_ALL },
    });
    expect(refusal(() => resolveWriteDisposition(null, "signals"))).toBe("WriteRefusedError");
  });

  test("an unswitched machine reads the legacy file until the setting is set", () => {
    env = makeStoreEnv("osb-perm-src-legacy-");
    writeLegacy(env.vault, DENY_ALL);
    const fromFile = loadPermissionsDocumentFor(env.vault);
    expect(fromFile.path).toBe(join(env.vault, "Brain", "_permissions.yaml"));
    expect(refusal(() => resolveWriteDisposition(env!.vault, "notes"))).toBe("WriteRefusedError");
    setBrainSetting(human(env.vault), PERMISSIONS_DOCUMENT_SETTING, ALLOW_ALL);
    expect(loadPermissionsDocumentFor(env.vault).path).toBe(PERMISSIONS_SETTING_LABEL);
    expect(refusal(() => resolveWriteDisposition(env!.vault, "notes"))).toBe("none");
  });

  test("a value won by agent authority is not a policy", () => {
    env = makeStoreEnv("osb-perm-src-agent-record-");
    switchDevice(env.storeRoot);
    appendRecord(openStore({ root: env.storeRoot, device: "dev-a" }), {
      partition: "shared",
      stream: "settings",
      kind: SETTING_SET_KIND,
      agent: "a",
      body: { [AUTHORITY_FIELD]: "agent", key: PERMISSIONS_DOCUMENT_SETTING, value: ALLOW_ALL },
    });
    expect(loadPermissionsDocumentFor(env.vault).document).toBeNull();
  });

  test("an operator value that does not parse fails closed", () => {
    env = makeStoreEnv("osb-perm-src-broken-");
    switchDevice(env.storeRoot);
    appendRecord(openStore({ root: env.storeRoot, device: "dev-a" }), {
      partition: "shared",
      stream: "settings",
      kind: SETTING_SET_KIND,
      agent: "o",
      body: {
        [AUTHORITY_FIELD]: "human",
        key: PERMISSIONS_DOCUMENT_SETTING,
        value: "version: 9\n",
      },
    });
    expect(() => loadPermissionsDocumentFor(env!.vault)).toThrow(PermissionsDocumentError);
  });

  // POSIX modes only, and root reads a 0000 folder anyway.
  test.skipIf(CHMOD_CANNOT_DENY)(
    "a settings stream that cannot be read fails closed, not open",
    () => {
      env = makeStoreEnv("osb-perm-src-unreadable-");
      switchDevice(env.storeRoot);
      setBrainSetting(human(env.vault), PERMISSIONS_DOCUMENT_SETTING, DENY_ALL);
      expect(refusal(() => resolveWriteDisposition(env!.vault, "notes"))).toBe("WriteRefusedError");
      const settings = join(env.storeRoot, "shared", "settings");
      chmodSync(settings, 0o000);
      try {
        expect(() => loadPermissionsDocumentFor(env!.vault)).toThrow(PermissionsDocumentError);
        expect(() => resolveWriteDisposition(env!.vault, "notes")).toThrow();
        const out: DoctorFindings = { issues: [], uncertain: [] };
        permissionsDocumentCheck.run(doctorContext(env!), out);
        expect(out.issues.map((i) => i.code)).toEqual([PERMISSIONS_UNREADABLE_CODE]);
        expect(legacyOnlyFindings(env!)).toEqual([]);
      } finally {
        chmodSync(settings, 0o755);
      }
    },
  );

  test("the shard of the operator's deny gone since this machine read it: still refused", () => {
    env = makeStoreEnv("osb-perm-src-gone-");
    switchDevice(env.storeRoot);
    // The sole permissions.document record sits in a peer's settings shard.
    const shard = appendRecord(openStore({ root: env.storeRoot, device: "dev-b" }), {
      partition: "shared",
      stream: "settings",
      kind: SETTING_SET_KIND,
      agent: "o",
      body: { [AUTHORITY_FIELD]: "human", key: PERMISSIONS_DOCUMENT_SETTING, value: DENY_ALL },
    }).path;
    expect(refusal(() => resolveWriteDisposition(env!.vault, "notes"))).toBe("WriteRefusedError");
    // Taken away mid-sync, `shared/store.json` left in place.
    rmSync(shard);
    expect(() => loadPermissionsDocumentFor(env!.vault)).toThrow(PermissionsDocumentError);
    expect(() => resolveWriteDisposition(env!.vault, "notes")).toThrow();
    const out: DoctorFindings = { issues: [], uncertain: [] };
    permissionsDocumentCheck.run(doctorContext(env), out);
    expect(out.issues.map((i) => i.code)).toEqual([PERMISSIONS_UNREADABLE_CODE]);
    expect(out.issues[0]!.message).toContain("shared/settings/dev-b/");
  });
});

/** A switched machine whose operator denies note writes in the setting. */
function switchedWithDeny(prefix: string): StoreEnv {
  const e = makeStoreEnv(prefix);
  writeLegacy(e.vault, ALLOW_ALL);
  switchDevice(e.storeRoot);
  setBrainSetting(human(e.vault), PERMISSIONS_DOCUMENT_SETTING, DENY_ALL);
  // The gate reads the setting, which also records the sticky switch.
  expect(refusal(() => resolveWriteDisposition(e.vault, "notes"))).toBe("WriteRefusedError");
  return e;
}

const identity = (e: StoreEnv, partition: string): string =>
  join(e.storeRoot, partition, "store.json");

describe("a switched machine whose store cannot be opened", () => {
  const cases: ReadonlyArray<[string, (e: StoreEnv) => void]> = [
    [
      "every store.json gone",
      (e) => {
        rmSync(identity(e, "shared"));
        rmSync(identity(e, "private"));
      },
    ],
    ["shared/store.json corrupt", (e) => writeFileSync(identity(e, "shared"), "{ not json")],
    ["only shared/store.json gone", (e) => rmSync(identity(e, "shared"))],
    [
      "only private/store.json gone (a partition this machine held)",
      (e) => rmSync(identity(e, "private")),
    ],
  ];

  for (const [name, breakStore] of cases) {
    test(`${name}: the operator's deny still refuses a note write`, () => {
      env = switchedWithDeny("osb-perm-src-nostore-");
      breakStore(env);
      expect(() => loadPermissionsDocumentFor(env!.vault)).toThrow(PermissionsDocumentError);
      expect(() => resolveWriteDisposition(env!.vault, "notes")).toThrow();
      const out: DoctorFindings = { issues: [], uncertain: [] };
      permissionsDocumentCheck.run(doctorContext(env), out);
      expect(out.issues.map((i) => i.code)).toEqual([PERMISSIONS_UNREADABLE_CODE]);
    });
  }

  test("an unswitched machine with no store still reads its legacy file", () => {
    env = makeStoreEnv("osb-perm-src-nostore-legacy-");
    writeLegacy(env.vault, DENY_ALL);
    rmSync(identity(env, "shared"));
    rmSync(identity(env, "private"));
    expect(loadPermissionsDocumentFor(env.vault).document?.default_action).toBe("deny");
  });
});

function doctorContext(e: StoreEnv): DoctorCheckContext {
  return {
    vault: e.vault,
    now: new Date("2026-11-08T12:00:00Z"),
    config: undefined,
    dbPath: undefined,
    configPath: e.configPath,
    knownBasenames: new Set(),
    idIndex: new Map(),
    preferences: [],
    logs: [],
  };
}

function legacyOnlyFindings(e: StoreEnv): string[] {
  const out: DoctorFindings = { issues: [], uncertain: [] };
  permissionsLegacyOnlyCheck.run(doctorContext(e), out);
  return out.issues.map((i) => i.code);
}

describe("doctor: deny rules only in a legacy permissions file", () => {
  test("a switched machine with the deny rules not in the setting warns", () => {
    env = makeStoreEnv("osb-perm-src-doc-warn-");
    writeLegacy(env.vault, DENY_ALL);
    switchDevice(env.storeRoot);
    expect(legacyOnlyFindings(env)).toEqual([PERMISSIONS_LEGACY_ONLY_CODE]);
    setBrainSetting(human(env.vault), PERMISSIONS_DOCUMENT_SETTING, ALLOW_ALL);
    expect(legacyOnlyFindings(env)).toEqual([PERMISSIONS_LEGACY_ONLY_CODE]);
  });

  test("silent once the setting holds the same rules, whatever the layout", () => {
    env = makeStoreEnv("osb-perm-src-doc-same-");
    writeLegacy(env.vault, DENY_ALL);
    switchDevice(env.storeRoot);
    // What `$(cat file)` hands the CLI: the trailing newline is gone.
    setBrainSetting(human(env.vault), PERMISSIONS_DOCUMENT_SETTING, DENY_ALL.trimEnd());
    expect(legacyOnlyFindings(env)).toEqual([]);
  });

  test("silent where the gates read the file, and for a file with no deny", () => {
    env = makeStoreEnv("osb-perm-src-doc-silent-");
    writeLegacy(env.vault, DENY_ALL);
    expect(legacyOnlyFindings(env)).toEqual([]);
    writeLegacy(env.vault, ALLOW_ALL);
    switchDevice(env.storeRoot);
    expect(legacyOnlyFindings(env)).toEqual([]);
  });
});