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
10.5 KB
Raw Blame
/**
 * The owner-write gate predicate (write-side-trust, Task 8).
 *
 * `integrity.owner_scope_writes` reads as a write-side sibling of
 * `owner_scope_delivery`, and until this module the explicit-owner arm of
 * every preference write was the inverse of a boundary: a caller named any
 * owner it wanted and the writer honoured it, so under a gate an operator
 * believed was closed, a caller could publish memories into another
 * agent's isolation scope by passing `owner: "someone-else"`. An owner a
 * request names is a claim, not a fact - the same rule
 * `src/mcp/owner-scope-refusal.ts` states for the read side, applied to
 * the write that CREATES the claim.
 *
 * This file pins the PURE predicate: no filesystem, no clock, no config.
 * The gate mode and the document arrive as arguments so the composition is
 * exhaustively testable, and the callers (the preference lane here, the
 * note lane in Task 13) stay thin wrappers that resolve those inputs.
 *
 * The composition is most-restrictive-wins in BOTH directions and the
 * matrix below pins every cell:
 *
 *   - the document can narrow what an `off` gate permits
 *     (`owner_write: deny` refuses even with the gate off), and
 *   - the gate can narrow what the document permits (an `allow` verdict
 *     cannot talk a `fail` gate out of refusing a foreign owner).
 *
 * `warn` refuses nothing by itself: it exists so an operator can watch
 * what `fail` would refuse, and the caller - not this predicate - logs the
 * one decision-ledger row that makes the watching possible.
 */

import { describe, expect, test } from "bun:test";

import type { PermissionsDocument } from "../../../../src/core/brain/permissions/document.ts";
import { resolvePermission } from "../../../../src/core/brain/permissions/resolve.ts";
import {
  OWNER_SCOPE_WRITES_KEY,
  refuseCrossOwnerWrite,
} from "../../../../src/core/brain/trust/owner-write-gate.ts";
import { GATE_MODE } from "../../../../src/core/integrity/stamp.ts";

const SELF = "agent-self";
const OTHER = "agent-other";

/** The gate key, spelled the way the config inventory pins it. */
test("the gate key is the integrity block's owner_scope_writes", () => {
  expect(OWNER_SCOPE_WRITES_KEY).toBe("integrity.owner_scope_writes");
});

/** A well-formed document with one overridable piece. */
function document(fields: Partial<PermissionsDocument>): PermissionsDocument {
  return {
    version: 1,
    default_action: "allow",
    roles: {},
    agents: {},
    entries: [],
    ...fields,
  };
}

const SUBJECT = { agent: SELF, via: "config" } as const;

describe("gate matrix: the gate mode alone", () => {
  test("off with no document refuses nothing and returns the bare verdict", () => {
    const verdict = refuseCrossOwnerWrite({
      explicitOwner: OTHER,
      resolvedIdentity: SELF,
      gateMode: GATE_MODE.off,
    });
    expect(verdict).toEqual({ refused: false });
    // Byte-identically: no extra fields a caller could branch on.
    expect(Object.keys(verdict)).toEqual(["refused"]);
  });

  test("off with no document and no named owner is inert at every mode", () => {
    for (const gateMode of ["off", "warn", "fail"] as const) {
      const verdict = refuseCrossOwnerWrite({
        resolvedIdentity: SELF,
        gateMode,
      });
      expect(verdict).toEqual({ refused: false });
    }
  });

  test("fail refuses a named owner other than the resolved identity, naming both tokens", () => {
    const verdict = refuseCrossOwnerWrite({
      explicitOwner: OTHER,
      resolvedIdentity: SELF,
      gateMode: GATE_MODE.fail,
    });
    expect(verdict.refused).toBe(true);
    if (!verdict.refused) return;
    expect(verdict.token).toBe("owner-write-refused");
    expect(verdict.reason).toContain("owner-write-refused");
    expect(verdict.reason).toContain(OTHER);
    expect(verdict.reason).toContain(SELF);
    expect(verdict.reason).toContain(OWNER_SCOPE_WRITES_KEY);
  });

  test("fail passes a named owner that agrees with the resolved identity", () => {
    // Agreement is judged on the same normalisation the read side compares
    // with, so a case or spacing difference is not a foreign owner.
    const verdict = refuseCrossOwnerWrite({
      explicitOwner: `  ${SELF.toUpperCase()}  `,
      resolvedIdentity: SELF,
      gateMode: GATE_MODE.fail,
    });
    expect(verdict).toEqual({ refused: false });
  });

  test("fail with an identity that cannot be verified refuses rather than trusts", () => {
    for (const unresolved of ["", "   ", "agent"]) {
      const verdict = refuseCrossOwnerWrite({
        explicitOwner: OTHER,
        resolvedIdentity: unresolved,
        gateMode: GATE_MODE.fail,
      });
      expect(verdict.refused).toBe(true);
      if (!verdict.refused) return;
      expect(verdict.token).toBe("owner-write-refused");
      expect(verdict.reason).toContain("owner-write-refused");
    }
  });

  test("warn allows a cross-owner write so the operator can watch what fail would refuse", () => {
    const verdict = refuseCrossOwnerWrite({
      explicitOwner: OTHER,
      resolvedIdentity: SELF,
      gateMode: GATE_MODE.warn,
    });
    expect(verdict).toEqual({ refused: false });
  });
});

describe("gate matrix: the document composes most-restrictive-wins, both ways", () => {
  test("a document owner_write deny refuses even when the gate mode is off", () => {
    const verdict = refuseCrossOwnerWrite({
      explicitOwner: OTHER,
      resolvedIdentity: SELF,
      gateMode: GATE_MODE.off,
      document: document({ default_action: "deny" }),
      subject: SUBJECT,
    });
    expect(verdict.refused).toBe(true);
    if (!verdict.refused) return;
    expect(verdict.token).toBe("owner-write-refused");
    expect(verdict.reason).toContain("owner-write-refused");
    expect(verdict.reason).toContain("default");
  });

  test("a document allow cannot override gate fail", () => {
    const verdict = refuseCrossOwnerWrite({
      explicitOwner: OTHER,
      resolvedIdentity: SELF,
      gateMode: GATE_MODE.fail,
      document: document({ agents: { [SELF]: { owner_write: "allow" } } }),
      subject: SUBJECT,
    });
    expect(verdict.refused).toBe(true);
    if (!verdict.refused) return;
    expect(verdict.reason).toContain(OTHER);
    expect(verdict.reason).toContain(SELF);
  });

  test("a document allow with the gate off leaves the cross-owner write alone", () => {
    const verdict = refuseCrossOwnerWrite({
      explicitOwner: OTHER,
      resolvedIdentity: SELF,
      gateMode: GATE_MODE.off,
      document: document({ agents: { [SELF]: { owner_write: "allow" } } }),
      subject: SUBJECT,
    });
    expect(verdict).toEqual({ refused: false });
  });

  test("a document ask refuses: this gate has no review lane to stage an owner write into", () => {
    const verdict = refuseCrossOwnerWrite({
      explicitOwner: OTHER,
      resolvedIdentity: SELF,
      gateMode: GATE_MODE.off,
      document: document({ default_action: "ask" }),
      subject: SUBJECT,
    });
    expect(verdict.refused).toBe(true);
    if (!verdict.refused) return;
    expect(verdict.reason).toContain("ask");
  });

  test("a document deny binds every owner write this subject attempts, its own token included", () => {
    // The action the document gates is "naming an owner at all", not
    // "naming a foreign one": most-restrictive-wins means the operator's
    // deny is not demoted to a cross-owner-only rule.
    const verdict = refuseCrossOwnerWrite({
      explicitOwner: SELF,
      resolvedIdentity: SELF,
      gateMode: GATE_MODE.off,
      document: document({ default_action: "deny" }),
      subject: SUBJECT,
    });
    expect(verdict.refused).toBe(true);
  });

  test("the document speaks only when the subject names who is asking", () => {
    const verdict = refuseCrossOwnerWrite({
      explicitOwner: OTHER,
      resolvedIdentity: SELF,
      gateMode: GATE_MODE.off,
      document: document({ default_action: "deny" }),
    });
    expect(verdict).toEqual({ refused: false });
  });

  test("a target-scoped entry outranks a lenient default for this subject", () => {
    const verdict = refuseCrossOwnerWrite({
      explicitOwner: OTHER,
      resolvedIdentity: SELF,
      gateMode: GATE_MODE.off,
      document: document({
        default_action: "deny",
        entries: [
          {
            id: "self-may-own",
            agent: SELF,
            action: "owner_write",
            verdict: "allow",
          },
        ],
      }),
      subject: SUBJECT,
    });
    expect(verdict).toEqual({ refused: false });
  });

  test("the resolved decision the matrix relies on is the shared resolver's", () => {
    // Guard against this suite drifting from the resolver's precedence
    // table: the document cases above assume entry > agent override.
    const decision = resolvePermission(
      document({
        default_action: "deny",
        agents: { [SELF]: { owner_write: "deny" } },
        entries: [{ id: "allow-self", agent: SELF, action: "owner_write", verdict: "allow" }],
      }),
      SUBJECT,
      "owner_write",
    );
    expect(decision.source).toBe("entry:allow-self");
  });
});

describe("gate matrix: the frontmatter spelling rides the same rule", () => {
  test("a frontmatter owner the gate would refuse refuses like an explicit one", () => {
    const verdict = refuseCrossOwnerWrite({
      frontmatterOwner: OTHER,
      resolvedIdentity: SELF,
      gateMode: GATE_MODE.fail,
    });
    expect(verdict.refused).toBe(true);
    if (!verdict.refused) return;
    expect(verdict.token).toBe("owner-write-refused");
    expect(verdict.reason).toContain(OTHER);
  });

  test("a frontmatter owner matching the resolved identity passes under fail", () => {
    const verdict = refuseCrossOwnerWrite({
      frontmatterOwner: SELF,
      resolvedIdentity: SELF,
      gateMode: GATE_MODE.fail,
    });
    expect(verdict).toEqual({ refused: false });
  });

  test("when both spellings name an owner, one that disagrees decides", () => {
    const agreesExplicit = refuseCrossOwnerWrite({
      explicitOwner: SELF,
      frontmatterOwner: OTHER,
      resolvedIdentity: SELF,
      gateMode: GATE_MODE.fail,
    });
    expect(agreesExplicit.refused).toBe(true);

    const agreesFrontmatter = refuseCrossOwnerWrite({
      explicitOwner: OTHER,
      frontmatterOwner: SELF,
      resolvedIdentity: SELF,
      gateMode: GATE_MODE.fail,
    });
    expect(agreesFrontmatter.refused).toBe(true);
  });

  test("a blank owner spelling is no owner at all", () => {
    const verdict = refuseCrossOwnerWrite({
      explicitOwner: "   ",
      frontmatterOwner: "",
      resolvedIdentity: SELF,
      gateMode: GATE_MODE.fail,
    });
    expect(verdict).toEqual({ refused: false });
  });
});