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
6.5 KB
Raw Blame
/**
 * Why a caller-supplied owner scope is REFUSED instead of honoured.
 *
 * `integrity.owner_scope_delivery: fail` reads as an isolation boundary,
 * and until this module it was the inverse of one. `coerceAgentScope`
 * returned the caller's `agent_scope` argument unconditionally and
 * `resolveOwnerScopeDelivery` enforced exactly that argument, so under
 * the gate a caller read ANY owner's private memories by naming that
 * owner - and the gate's presence implied a check nobody performed. An
 * identity that is echoed back from the request is not an identity.
 *
 * The rule stated here, once: under {@link GATE_MODE.fail} the
 * server-resolved identity is authoritative, and a caller-supplied scope
 * may only AGREE with it. A disagreement is refused by name. Silently
 * substituting the caller's own scope is deliberately not an option -
 * the caller would then believe it had read what it asked for, which is
 * the quiet fallback this repository forbids.
 *
 * Two things this module is careful about:
 *
 *   - The comparison is {@link normalizeAgentScope} on both sides, the
 *     same token normalisation {@link isOwnerVisible} compares with. A
 *     second spelling of "the same owner" would be a second ownership
 *     rule, and the release this module ships in exists because a rule
 *     with two spellings is a rule with none.
 *   - "The server has an identity" is {@link normalizeAgentArgument},
 *     the same predicate every write surface already uses to reject a
 *     guessed name. The bottom of the identity chain is the literal
 *     `"agent"`, which that predicate rejects, so an unconfigured
 *     install cannot silently become an owner.
 *
 * Scope of the refusal: every surface that ACCEPTS the argument, not
 * only the gated preference-delivery ones. The search-backed surfaces
 * are not narrowed by the gate today (see
 * `tests/mcp/agent-scope-matrix.test.ts`), so refusing a foreign scope
 * there closes nothing on its own - but an operator who set the gate has
 * declared owner scope a boundary rather than a filter, and leaving the
 * echo in place on half the surfaces is how it would be re-opened the
 * day those surfaces are gated.
 *
 * Under `warn` and `off` nothing is refused: neither mode withholds
 * anything, so a foreign scope cannot deliver what an absent one would
 * not, and refusing would break `warn`'s whole purpose - watching what
 * `fail` would do before turning it on.
 */

import { normalizeAgentArgument } from "../core/agent-identity.ts";
import { loadIntegrityConfigSafe } from "../core/brain/policy.ts";
import { normalizeAgentScope } from "../core/graph/agent-scope.ts";
import { GATE_MODE } from "../core/integrity/stamp.ts";

/** The operator key that makes the resolved identity authoritative. */
export const OWNER_SCOPE_GATE_KEY = "integrity.owner_scope_delivery";

/** The setting an operator changes to stop being refused. */
const IDENTITY_SETTINGS = "agent_name in the plugin config, or VAULT_AGENT_NAME";

export const OWNER_SCOPE_REFUSAL = Object.freeze({
  /** The request named an owner other than the caller's resolved identity. */
  foreignOwner: "foreign-owner",
  /**
   * The server resolved no usable identity, so no requested owner can be
   * shown to be the caller's own. Fail closed: an unverifiable scope is
   * refused rather than trusted.
   */
  unresolvedIdentity: "unresolved-identity",
} as const);

/** Closed union over {@link OWNER_SCOPE_REFUSAL}. */
export type OwnerScopeRefusal = (typeof OWNER_SCOPE_REFUSAL)[keyof typeof OWNER_SCOPE_REFUSAL];

/** Membership list, in the order the checks are made. */
export const OWNER_SCOPE_REFUSALS: ReadonlyArray<OwnerScopeRefusal> = Object.freeze([
  OWNER_SCOPE_REFUSAL.unresolvedIdentity,
  OWNER_SCOPE_REFUSAL.foreignOwner,
]);

/** Narrow a refusal token read back off a wire or a stored envelope. */
export function isOwnerScopeRefusal(value: unknown): value is OwnerScopeRefusal {
  return (
    typeof value === "string" && (OWNER_SCOPE_REFUSALS as ReadonlyArray<string>).includes(value)
  );
}

/** One caller's request to be answered under a named owner scope. */
export interface OwnerScopeRequest {
  /** The argument the scope arrived in, named in the refusal. */
  readonly argument: string;
  /** The owner the caller asked to be answered as, verbatim. */
  readonly requested: string;
  /** The identity this server resolved for the caller, if it has one. */
  readonly identity: string | undefined;
}

/** A refusal, with the sentence that diagnoses it. */
export interface OwnerScopeRefusalOutcome {
  readonly refusal: OwnerScopeRefusal;
  /** Names both owners, the gate, and what would change the answer. */
  readonly message: string;
}

/**
 * Decide whether `request` may be answered on `vault`, or must be
 * refused. `null` means the request stands: the gate is not `fail`, the
 * requested scope is blank (which narrows nothing), or the caller named
 * its own identity.
 *
 * The gate is read FIRST so a vault that never opted in pays neither the
 * config read's cost nor its verdict.
 */
export function refuseOwnerScopeRequest(
  vault: string,
  request: OwnerScopeRequest,
): OwnerScopeRefusalOutcome | null {
  if (loadIntegrityConfigSafe(vault).owner_scope_delivery !== GATE_MODE.fail) return null;

  const requested = normalizeAgentScope(request.requested);
  if (requested === null) return null;

  const resolved = normalizeAgentScope(normalizeAgentArgument(request.identity) ?? undefined);
  if (resolved === null) {
    return Object.freeze({
      refusal: OWNER_SCOPE_REFUSAL.unresolvedIdentity,
      message:
        `${request.argument} refused (${OWNER_SCOPE_REFUSAL.unresolvedIdentity}): ` +
        `${JSON.stringify(request.requested)} cannot be checked because this ` +
        `server resolved no agent identity, so no requested owner can be shown to be the ` +
        `caller's own. ${OWNER_SCOPE_GATE_KEY}=${GATE_MODE.fail} refuses an owner scope it ` +
        `cannot verify. Set ${IDENTITY_SETTINGS}.`,
    });
  }
  if (resolved === requested) return null;

  return Object.freeze({
    refusal: OWNER_SCOPE_REFUSAL.foreignOwner,
    message:
      `${request.argument} refused (${OWNER_SCOPE_REFUSAL.foreignOwner}): ` +
      `${JSON.stringify(request.requested)} names an owner other than the ` +
      `identity this server resolved for the caller, ${JSON.stringify(resolved)}. ` +
      `${OWNER_SCOPE_GATE_KEY}=${GATE_MODE.fail} makes the resolved identity authoritative, so ` +
      `the request is refused rather than answered as ${JSON.stringify(requested)} or narrowed ` +
      `to ${JSON.stringify(resolved)} behind the caller's back.`,
  });
}