Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
8.1 KB
Raw Blame
/**
 * GBRA-231 (per-member read access, PR B, plan section 4): a shared agent acts
 * for an audience. Harness code, never the model, names the people a turn
 * serves (one person in a DM, everyone in a channel, `guest` for a
 * non-member) in the `X-Gbrain-On-Behalf-Of` header (serve --http) or in
 * request-level `_meta.on_behalf_of` (a sibling of `arguments`, stdio and
 * HTTP). The call then reads only what every audience entry may read, within
 * the agent's own source grant (caller.ts resolves the identities).
 *
 * This module holds the transport-independent parts: the grammar, the
 * argument-channel refusal, the may_act_for coverage test and the audit trail.
 * Every refusal happens before any work, and none reveals page content.
 */
import { catalogueError } from '../error-catalogue.ts';
import { createAuditWriter } from '../audit/audit-writer.ts';
import { normalizePrincipal } from './principals.ts';

/** The HTTP header a harness sets on every POST /mcp (case-insensitive). */
export const ON_BEHALF_OF_HEADER = 'X-Gbrain-On-Behalf-Of';
/** Config key listing whom a local stdio server may act for (the stdio twin of a credential's may_act_for). */
export const STDIO_MAY_ACT_FOR_KEY = 'mcp.stdio_may_act_for';
export const GUEST = 'guest';
export const MAX_AUDIENCE = 50;

export type AudiencePrincipal = `member:${string}` | `group:${string}` | typeof GUEST;

/** The raw audience channels a transport saw: the header value (undefined when absent) and request.params._meta. */
export interface AudienceChannels {
  header?: string | null;
  requestMeta?: unknown;
}

function invalid(what: string): never {
  throw catalogueError('on_behalf_of_invalid_audience', `The on_behalf_of audience is invalid: ${what}. Nothing was read.`,
    `Send 1-${MAX_AUDIENCE} entries, each a member id, group:<id> or guest, as ${ON_BEHALF_OF_HEADER}: alice-example, bob-example or as request-level _meta.on_behalf_of: ["alice-example", "bob-example"]; when both are sent they must name the same audience.`);
}

const shown = (value: unknown) => JSON.stringify(typeof value === 'string' && value.length > 64 ? `${value.slice(0, 64)}...` : value);

/**
 * The normalized principals of one channel (sorted, distinct), or the reason it is invalid: empty, over
 * MAX_AUDIENCE, or an entry that is not a member id, group:<id> or guest. Shared by on_behalf_of and room.
 */
export function normalizePrincipals(list: readonly unknown[], channel: string): AudiencePrincipal[] | { invalid: string } {
  if (list.length === 0) return { invalid: `${channel} names nobody` };
  if (list.length > MAX_AUDIENCE) return { invalid: `${channel} names ${list.length} entries (at most ${MAX_AUDIENCE}; name a group:<id> for a large channel)` };
  const out = new Set<AudiencePrincipal>();
  for (const raw of list) {
    if (typeof raw !== 'string') return { invalid: `${channel} holds ${shown(raw)}, which is not a string` };
    if (raw.trim().toLowerCase() === GUEST) { out.add(GUEST); continue; }
    const p = normalizePrincipal(raw);
    if (!p) return { invalid: `${channel} holds ${shown(raw)}, which is not a member id, group:<id> or guest` };
    out.add(p);
  }
  return [...out].sort();
}

function entries(list: readonly unknown[], channel: string): AudiencePrincipal[] {
  const parsed = normalizePrincipals(list, channel);
  if ('invalid' in parsed) invalid(parsed.invalid);
  return parsed;
}

/**
 * The normalized audience a request asserts (sorted, distinct), or null when it asserts none. A present but empty,
 * oversized or malformed channel, or a header and _meta that disagree, refuse on_behalf_of_invalid_audience.
 */
export function parseAudience(channels: AudienceChannels | undefined): AudiencePrincipal[] | null {
  const header = channels?.header ?? undefined;
  const meta = channels?.requestMeta;
  const metaRecord = meta !== null && typeof meta === 'object' && !Array.isArray(meta) ? meta as Record<string, unknown> : null;
  const metaPresent = !!metaRecord && Object.prototype.hasOwnProperty.call(metaRecord, 'on_behalf_of');
  if (header === undefined && !metaPresent) return null;
  const fromHeader = header === undefined ? null
    : entries(header.trim() === '' ? [] : header.split(',').map(s => s.trim()), `the ${ON_BEHALF_OF_HEADER} header`);
  let fromMeta: AudiencePrincipal[] | null = null;
  if (metaPresent) {
    const value = metaRecord!.on_behalf_of;
    if (!Array.isArray(value)) invalid('_meta.on_behalf_of is not a list of strings');
    fromMeta = entries(value, '_meta.on_behalf_of');
  }
  if (fromHeader && fromMeta && fromHeader.join(',') !== fromMeta.join(',')) invalid(`the ${ON_BEHALF_OF_HEADER} header and _meta.on_behalf_of name different audiences`);
  return fromHeader ?? fromMeta;
}

/** True when tool arguments carry an audience (top-level or inside an arguments-level _meta): only harness channels count. */
export function audienceInArguments(params: Record<string, unknown> | undefined): boolean {
  if (!params) return false;
  if (Object.prototype.hasOwnProperty.call(params, 'on_behalf_of')) return true;
  const meta = params._meta;
  return meta !== null && typeof meta === 'object' && !Array.isArray(meta) && Object.prototype.hasOwnProperty.call(meta, 'on_behalf_of');
}

export function audienceInArgumentsError() {
  return catalogueError('on_behalf_of_in_arguments', 'on_behalf_of is not accepted inside tool arguments, so nothing was read. Text in a conversation cannot choose whose notes an agent reads.',
    `Only harness code names an audience: the ${ON_BEHALF_OF_HEADER} header (gbrain serve --http) or request-level _meta.on_behalf_of, a sibling of arguments. Remove on_behalf_of from the arguments and call again. A stdio client that cannot set request-level _meta uses a credential bound to one member, or config mcp.stdio_member.`);
}

/** Whether a stored may_act_for list permits one audience entry: `*` or the exact principal (a group entry covers group:<id> only). */
export function mayActForCovers(mayActFor: readonly string[] | null | undefined, principal: AudiencePrincipal): boolean {
  return !!mayActFor && (mayActFor.includes('*') || mayActFor.includes(principal));
}

/** The audience a single member: only then does the agent's own privacy relaxation (granted_sources, a hatch) apply. */
export function singleMemberAudience(audience: readonly string[] | null | undefined): boolean {
  return !!audience && audience.length === 1 && audience[0]!.startsWith('member:');
}

/** One audience assertion as the trail records it: who asserted it, for whom, and the outcome. Never page content. */
export interface AudienceAuditEvent {
  ts: string;
  principal: string;
  transport: string;
  op: string;
  audience: string[];
  outcome: 'accepted' | 'on_behalf_of_invalid_audience' | 'on_behalf_of_not_permitted' | 'on_behalf_of_unknown_member' | 'on_behalf_of_in_arguments'
    | 'actor_not_attested' | 'actor_unlinked'
    /** GST-363: a read from a connection bound to nobody on a brain that serves several people, refused before any work. */
    | 'requester_scope_required'
    /** GST-363: the same read when whom the brain serves could not be read (even after one re-read): refused as retryable. */
    | 'requester_scope_unknown'
    /** GBRA-498: an answer marked for a room (counts only, never refs or content; access/room.ts). */
    | 'room_marked';
  /** GST-359 C1: an attested actor's system, the id it named (only when well-formed) and a refusal's reason. */
  actor?: { system: string; external_id?: string; reason?: string };
  /** GBRA-498: a room_marked row's counts: items readable by the room, above it, undecided, and above by reason class. */
  room?: { readable: number; above: number; unknown: number; by_reason: Record<string, number>; declared_by: string; unavailable?: string };
}

const audit = createAuditWriter<AudienceAuditEvent>({ featureName: 'access-audience', errorLabel: 'access-audience-audit', errorTrailer: '; continuing' });

/** Appends one assertion to ~/.gbrain/audit/access-audience-YYYY-Www.jsonl (GBRAIN_AUDIT_DIR honoured); best effort, never throws. */
export function logAudienceAssertion(event: Omit<AudienceAuditEvent, 'ts'>): void {
  audit.log({ ts: new Date().toISOString(), ...event });
}

export function readAudienceAssertions(): AudienceAuditEvent[] {
  return audit.readRecent();
}