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
/**
* The owner-write gate (write-side-trust, Task 8): one pure predicate
* deciding whether a caller-named owner may be written under.
*
* `integrity.owner_scope_writes` reads as the write-side sibling of
* `integrity.owner_scope_delivery`, and it is a sibling rather than a
* second mode on it because the two gates' `warn` semantics already
* differ: the delivery gate stamps under `warn`, this one allows and
* lets the caller log one decision-ledger row. An operator who wants
* read isolation but not write policing - or the reverse - needs them
* separable.
*
* The rule, stated once: a caller-named owner is a CLAIM, and under
* {@link GATE_MODE.fail} the resolved identity is authoritative, so the
* claim may only AGREE with it. A disagreement is refused by name -
* never silently substituted, because a caller whose owner was swapped
* behind its back would believe it had written what it asked to write,
* which is the quiet fallback this repository forbids. The read-side
* statement of the same rule is `src/mcp/owner-scope-refusal.ts`; the
* comparison here is the same {@link normalizeAgentScope} token
* normalisation that side compares with, because a second spelling of
* "the same owner" would be a second ownership rule.
*
* Composition with the permissions document is most-restrictive-wins in
* BOTH directions, and each direction is pinned by the gate-matrix suite:
*
* - the document can narrow what an `off` gate permits: an
* `owner_write` verdict of `deny` refuses the subject's owner writes
* whatever the gate says. An `ask` refuses too - this gate has no
* review lane to stage an owner write into, and letting the looser
* of two verdicts win would be most-restrictive-wins with an
* exception, which is to say without the rule.
* - the gate can narrow what the document permits: an `allow` verdict
* never talks a `fail` gate out of refusing a foreign owner.
*
* Under `warn` and `off` this predicate refuses nothing on the gate's
* own account: `off` is "this vault never opted in" and must be
* byte-identical, and `warn` exists precisely to let the cross-owner
* writes through that `fail` would refuse, with the caller logging the
* row that makes them visible.
*
* PURE LEAF like the resolver it consults: no I/O, no clock, no config.
* Callers resolve the gate mode, the document and the identity, and stay
* responsible for the warn-side ledger row.
*/
import { normalizeAgentArgument } from "../../agent-identity.ts";
import { normalizeAgentScope } from "../../graph/agent-scope.ts";
import { GATE_MODE, type GateMode } from "../../integrity/stamp.ts";
import type { PermissionsDocument } from "../permissions/document.ts";
import { resolvePermission, type PermissionSubject } from "../permissions/resolve.ts";
/** The operator key that makes the resolved identity authoritative for writes. */
export const OWNER_SCOPE_WRITES_KEY = "integrity.owner_scope_writes";
/** One caller's request to write under a named owner. */
export interface CrossOwnerWriteInput {
/**
* The owner token the caller named as an argument (the preference
* lane's explicit owner). Blank means "no owner named this way".
*/
readonly explicitOwner?: string;
/**
* The owner arriving inside caller-authored frontmatter (the note
* lane's `owner:` key). Blank means "no owner named this way". When
* both spellings name an owner, one that disagrees decides.
*/
readonly frontmatterOwner?: string;
/** The identity resolved for the caller by the process, not by the request. */
readonly resolvedIdentity: string;
/** The resolved `integrity.owner_scope_writes` mode. */
readonly gateMode: GateMode;
/** The vault's permissions document, or null when the vault has none. */
readonly document?: PermissionsDocument | null;
/** Who is asking, when the document is to be consulted. */
readonly subject?: PermissionSubject;
}
/**
* The verdict. The refused arm carries exactly one refusal token - this
* gate refuses one way only - and a reason naming both owner tokens, the
* deciding rule, and what would change the answer.
*/
export const OWNER_WRITE_REFUSAL = "owner-write-refused";
export type CrossOwnerWriteVerdict =
| { refused: false }
| { refused: true; token: typeof OWNER_WRITE_REFUSAL; reason: string };
const NOT_REFUSED: CrossOwnerWriteVerdict = Object.freeze({
refused: false,
}) as CrossOwnerWriteVerdict;
/** Normalise one caller-named owner token, or `null` for "none named". */
function namedOwner(value: string | undefined): string | null {
const trimmed = value?.trim();
if (trimmed === undefined || trimmed === "") return null;
return normalizeAgentScope(trimmed);
}
function refused(reason: string): CrossOwnerWriteVerdict {
return Object.freeze({ refused: true, token: OWNER_WRITE_REFUSAL, reason });
}
/**
* Decide whether a write naming `explicitOwner` and/or `frontmatterOwner`
* may proceed under `gateMode`, or must be refused. Document-first, then
* the gate: the document's `owner_write` verdict binds whatever the gate
* mode is, and the gate's own cross-owner check binds whatever the
* document allowed.
*/
export function refuseCrossOwnerWrite(input: CrossOwnerWriteInput): CrossOwnerWriteVerdict {
const explicit = namedOwner(input.explicitOwner);
const fromFrontmatter = namedOwner(input.frontmatterOwner);
if (explicit === null && fromFrontmatter === null) return NOT_REFUSED;
const named = explicit ?? fromFrontmatter!;
// The document verdict needs a subject; without one there is no rule to
// resolve and the gate alone decides.
const decision =
input.document && input.subject
? resolvePermission(input.document, input.subject, "owner_write")
: null;
if (decision !== null && decision.verdict !== "allow") {
const askNote =
decision.verdict === "ask"
? "; this gate has no review lane to stage an owner write into, so the ask " +
"refuses rather than passing"
: "";
return refused(
`write refused (owner-write-refused): the permissions document resolves ` +
`owner_write for ${JSON.stringify(input.subject!.agent)} to ` +
`${decision.verdict} via ${decision.source}, so this caller may not name an ` +
`owner${askNote}. ${OWNER_SCOPE_WRITES_KEY} is ${input.gateMode}; the document ` +
`and the gate compose most-restrictive-wins, so the document refusal stands.`,
);
}
if (input.gateMode !== GATE_MODE.fail) return NOT_REFUSED;
// "The caller has an identity" is the predicate every write surface
// already uses to reject a guessed name, so an unconfigured install
// cannot become an owner by asking for one.
const resolved = normalizeAgentScope(normalizeAgentArgument(input.resolvedIdentity) ?? undefined);
if (resolved === null) {
return refused(
`write refused (owner-write-refused): the caller named owner ` +
`${JSON.stringify(named)}, but the identity resolved for this caller ` +
`(${JSON.stringify(input.resolvedIdentity)}) does not reduce to one verifiable ` +
`ownership token - it is blank or a placeholder name - so the owner cannot be ` +
`shown to be the caller's own. ${OWNER_SCOPE_WRITES_KEY}=${GATE_MODE.fail} refuses ` +
`an owner it cannot verify rather than trusting it.`,
);
}
const crossExplicit = explicit !== null && explicit !== resolved;
const crossFrontmatter = fromFrontmatter !== null && fromFrontmatter !== resolved;
if (!crossExplicit && !crossFrontmatter) return NOT_REFUSED;
// Name the token that actually disagrees: when one spelling agrees and
// the other does not, the refusal must point at the foreign one.
const foreign = crossExplicit ? explicit! : fromFrontmatter!;
return refused(
`write refused (owner-write-refused): the caller-named owner ` +
`${JSON.stringify(foreign)} names an owner other than the identity resolved for ` +
`this caller, ${JSON.stringify(resolved)}. ${OWNER_SCOPE_WRITES_KEY}=${GATE_MODE.fail} ` +
`makes the resolved identity authoritative for writes, so the write is refused ` +
`rather than published under a foreign owner. Name ${JSON.stringify(resolved)}, ` +
`or write without an explicit owner.`,
);
}