Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* GBRA-218: the caller-access record of one remote MCP operation. The
* credential's verifier-derived principal (never a display name or request
* data) names the token or OAuth client; its bound member, when the member is
* live, plus that member's groups form the identity readers are checked
* against. The verifiers (src/core/oauth-provider.ts, src/mcp/http-transport.ts)
* join the binding once and carry it on AuthInfo.member, so dispatch costs no
* query; an AuthInfo no verifier built (member undefined) is looked up from
* its principal. A local stdio server reads its binding from its own
* `gbrain serve --stdio-member <id>` (the harness's MCP entry, so one
* registration on one machine), else from config `mcp.stdio_member` set by
* hand. A remote read or write on a brain with no member-access restriction
* and no owner never looks a binding up. An empty identity means the
* credential is unbound or its member is unknown, disabled or removed; it
* reads no restricted page. A lookup that fails never reads as unbound, which
* would open every unlabelled page to a labelled-only member. A statement the
* database rejected (a SQLSTATE) throws access_identity_unavailable, which is
* retryable, unless the persistence consumer's transientDatabaseFailure or
* transientInterruption classifies it (a dropped connection, a lock or
* statement timeout, a stale plan, a publication past its ceiling); that, and
* every failure that is not a statement error (a preparation deadline, an
* abort, a coded refusal), is rethrown unchanged, so a stored write keeps its
* consumer's release, retry and deadline handling. The one failure that stays
* empty is a schema older than the member tables (v282), whose lookup misses
* access_members, access_group_members or the member_id column; no member,
* labelled-only (v308) or not, can exist there, and every owner caller there
* is unbound.
*/
import type { BrainEngine } from '../engine.ts';
import type { AuthInfo } from '../ops/contract.ts';
import { remotePrivacyRelaxed, requestRemotePolicy, type CallerAccess, type FolderCoverage, type RemotePolicy } from '../search/private-visibility.ts';
import { ACCESS_ID_RE, identityFor, normalizePrincipal } from './principals.ts';
import { catalogueError } from '../error-catalogue.ts';
import type { Action } from '../agent-output.ts';
import { markNotAdmitted, OperationError, opError } from '../ops/contract.ts';
import { hostOnlyError } from '../ops/op-fix.ts';
import { currentCallerAccess } from '../search/private-visibility.ts';
import { edgeTrimSql } from '../edge-whitespace.ts';
import { GUEST, STDIO_MAY_ACT_FOR_KEY, mayActForCovers, singleMemberAudience, type AudiencePrincipal } from './audience.ts';
import { audienceMemberIds, parseMayActFor } from './members.ts';
import { stdioBindRoute } from './stdio-bind-route.ts';
import { labelledOnlyFor } from './labelled-only.ts';
import { isMissingSchemaObject } from '../utils.ts';
import { transientDatabaseFailure, transientInterruption } from '../persistence/transient-retry.ts';
/** Config key binding a local stdio MCP server to one member. */
export const STDIO_MEMBER_KEY = 'mcp.stdio_member';
const MEMBERS_WHERE_SQL = (predicate: string) => `SELECT m.id, COALESCE(array_agg(g.group_id ORDER BY g.group_id) FILTER (WHERE g.group_id IS NOT NULL), '{}') AS groups
FROM access_members m LEFT JOIN access_group_members g ON g.member_id = m.id
WHERE ${predicate} AND m.disabled_at IS NULL AND m.tombstoned_at IS NULL
GROUP BY m.id`;
const MEMBER_SQL = (member: string) => MEMBERS_WHERE_SQL(`m.id = (${member})`);
/** The objects v282 added that the lookup reads: a schema without them predates the member tables. */
const MEMBER_TABLES = ['access_members', 'access_group_members'];
const MEMBER_COLUMN = 'member_id';
const SQLSTATE_RE = /^[0-9A-Z]{5}$/;
const IDENTITY_RETRY_AFTER_MS = 2_000;
const WHOAMI: NonNullable<Action['verify']> = { argv: ['gbrain', 'whoami', '--json'], mcp: { tool: 'whoami', arguments: {} } };
function identityUnavailable(): OperationError {
return opError('access_identity_unavailable', 'The member this connection is bound to could not be looked up, so nothing was read or written.',
'Retry the same request in a few seconds (a write with the same request_id); if it keeps failing, ask the brain operator to run gbrain doctor --json on the brain host.', {
why: 'Reading the credential\'s member binding failed with a database error. Reading the connection as unbound instead would open pages its member may not read, so the request stops here.',
detail: `retry_after_ms=${IDENTITY_RETRY_AFTER_MS}`,
fix: { ...WHOAMI, consent: [], actor: 'provider', requires_exclusive: false, verify: WHOAMI,
why: 'After a few seconds whoami reads the binding again and shows the member this connection reads as; then repeat the original request.' },
});
}
/**
* Marks a transient failure liveIdentity rethrew unchanged (a non-enumerable property, so the error still reads the
* same to the persistence consumer), so the dispatch boundary can tell it from other statements' failures.
*/
const TRANSIENT_LOOKUP_FAILURE = Symbol('gbrain.transientIdentityLookupFailure');
/**
* At the MCP dispatch boundary: access_identity_unavailable (retryable, not admitted) when `error`, or an error it was
* wrapped in, is a transient failure of a member-identity lookup; else null. A request that fails this way at
* submission has written nothing, so the same request_id can be sent again. The persistence consumer never sees the
* mapping: its lookups keep the original error, which it releases and retries.
*/
export function identityLookupUnavailable(error: unknown): OperationError | null {
for (let e = error, depth = 0; e && typeof e === 'object' && depth < 8; e = (e as { cause?: unknown }).cause, depth++) {
if ((e as { [TRANSIENT_LOOKUP_FAILURE]?: true })[TRANSIENT_LOOKUP_FAILURE] === true) return markNotAdmitted(identityUnavailable());
}
return null;
}
async function liveIdentity(engine: Pick<BrainEngine, 'executeRaw'>, memberSql: string, param: string): Promise<string[]> {
let row: { id: string; groups: string[] } | undefined;
try {
[row] = await engine.executeRaw<{ id: string; groups: string[] }>(MEMBER_SQL(memberSql), [param]);
} catch (error) {
if (isMissingSchemaObject(error, 'table', MEMBER_TABLES) || isMissingSchemaObject(error, 'column', MEMBER_COLUMN)) return [];
if (error && typeof error === 'object' && (transientDatabaseFailure(error) || transientInterruption(error))) {
if (Object.isExtensible(error)) Object.defineProperty(error, TRANSIENT_LOOKUP_FAILURE, { value: true });
throw error;
}
const code = (error as { code?: unknown } | null)?.code;
if (typeof code !== 'string' || !SQLSTATE_RE.test(code)) throw error;
throw identityUnavailable();
}
if (!row || normalizePrincipal(`member:${row.id}`) !== `member:${row.id}`) return [];
const groups = (row.groups ?? []).filter(g => normalizePrincipal(`group:${g}`) === `group:${g}`);
return identityFor(row.id, groups);
}
/**
* The member identity bound to `auth`: the verifier's join when present, else a lookup from its principal (a local
* stdio principal reads the member its serve was started with, stamped as `stdioMember` on a stored write, else
* config mcp.stdio_member, as stdio reads do); empty when unbound or the member is unknown or not enabled; a lookup
* that fails throws (liveIdentity: a transient database failure unchanged, else access_identity_unavailable). A write's publication passes only its stored
* principal, so a member disabled or a binding removed after submission takes effect.
*/
export async function memberIdentityFor(engine: Pick<BrainEngine, 'executeRaw'>, auth: Pick<AuthInfo, 'member'> & { principal?: { kind: string; id: string }; stdioMember?: string } | undefined): Promise<string[]> {
if (auth?.member !== undefined) return auth.member ? identityFor(auth.member.id, auth.member.groups) : [];
const principal = auth?.principal;
if (principal?.kind === 'local_stdio') return auth?.stdioMember !== undefined ? liveIdentity(engine, '$1', auth.stdioMember)
: liveIdentity(engine, `SELECT ${edgeTrimSql('value')} FROM config WHERE key = $1`, STDIO_MEMBER_KEY);
if (!principal || (principal.kind !== 'legacy_token' && principal.kind !== 'oauth_client')) return [];
return liveIdentity(engine, principal.kind === 'legacy_token'
? 'SELECT member_id FROM access_tokens WHERE id::text = $1 AND revoked_at IS NULL'
: 'SELECT member_id FROM oauth_clients WHERE client_id = $1 AND deleted_at IS NULL', principal.id);
}
/** The member a local stdio server is bound to (config mcp.stdio_member), or null when unset or ill-formed. */
export async function stdioMemberId(engine: BrainEngine): Promise<string | null> {
try {
const raw = (await engine.getConfig(STDIO_MEMBER_KEY))?.trim();
return raw && ACCESS_ID_RE.test(raw) ? raw : null;
} catch {
return null;
}
}
/**
* The identity of a local stdio server: the live member its serve was started with (--stdio-member), else the live
* member config mcp.stdio_member names, else empty. A named member that is disabled or unknown reads as nobody and
* never falls back to the config key; a lookup that fails throws (liveIdentity). With no member named it runs no
* query.
*/
export async function stdioMemberIdentity(engine: BrainEngine, registered?: string): Promise<string[]> {
const member = registered ?? await stdioMemberId(engine);
return member ? liveIdentity(engine, '$1', member) : [];
}
/**
* GBRA-218 (A2): the folder-rule part of a caller's record, read live from the applied rulebook: the
* source-qualified ids of the rules `identity` satisfies, and every prefix that reads as nobody (a narrowing being
* stamped, an invalid policy file). An unreadable rulebook satisfies nothing and covers everything (fail closed), and so
* does one row-level security hides from this database role.
*/
export async function folderAccessFor(engine: Pick<BrainEngine, 'executeRaw'>, identity: readonly string[]): Promise<{ satisfiedRuleIds: string[]; folderCoverage: FolderCoverage[] }> {
return folderAccessForAll(engine, [identity]);
}
/**
* GBRA-231: folderAccessFor for an audience. A rule is satisfied only when every identity meets its readers, so the
* satisfied set is the intersection of each entry's set (empty when any entry, a guest included, meets none).
*/
export async function folderAccessForAll(engine: Pick<BrainEngine, 'executeRaw'>, identities: readonly (readonly string[])[]): Promise<{ satisfiedRuleIds: string[]; folderCoverage: FolderCoverage[] }> {
try {
const union = [...new Set(identities.flat())];
const rules = union.length && identities.length && identities.every(id => id.length > 0)
? await engine.executeRaw<{ source_id: string; rule_id: string; readable_by: string[] }>('SELECT source_id, rule_id, readable_by FROM access_rules WHERE readable_by && $1::text[]', [union])
: [];
const satisfied = rules.filter(r => identities.every(id => (r.readable_by ?? []).some(reader => id.includes(reader))));
const coverage = await engine.executeRaw<{ source_id: string; prefix: string }>(`SELECT * FROM (SELECT DISTINCT source_id, prefix FROM access_pending_coverage
UNION ALL SELECT '!unreadable', '' WHERE gbrain_access_state_unreadable()) c ORDER BY source_id, prefix`);
return { satisfiedRuleIds: satisfied.map(r => `${r.source_id}:${r.rule_id}`).sort(), folderCoverage: coverage.map(c => ({ source_id: c.source_id, prefix: c.prefix })) };
} catch {
return { satisfiedRuleIds: [], folderCoverage: [{ source_id: '!unreadable', prefix: '' }] };
}
}
/** Who asserts an audience: a verified credential (live call), a stored principal (a queued write or job), or a stdio server. */
export interface AudienceCaller {
auth?: Pick<AuthInfo, 'member' | 'mayActFor' | 'clientId' | 'clientName'> & { principal?: { kind: string; id: string } };
principal?: { kind: string; id: string };
transport?: string;
}
/**
* The may_act_for list that bounds `caller`: the verifier's join on a live call (read on every request), else a live
* lookup from the stored principal (a revoked token or deleted client permits nothing), else for a stdio server
* config mcp.stdio_may_act_for. Unreadable or ill-formed values permit nothing.
*/
async function mayActForOf(engine: Pick<BrainEngine, 'executeRaw'>, caller: AudienceCaller): Promise<string[] | null> {
const auth = caller.auth;
if (auth?.member !== undefined) return auth.mayActFor ?? null;
const principal = auth?.principal ?? caller.principal;
try {
if (principal?.kind === 'legacy_token') {
const [row] = await engine.executeRaw<{ may_act_for: unknown }>('SELECT may_act_for FROM access_tokens WHERE id::text = $1 AND revoked_at IS NULL', [principal.id]);
return Array.isArray(row?.may_act_for) ? row!.may_act_for as string[] : null;
}
if (principal?.kind === 'oauth_client') {
const [row] = await engine.executeRaw<{ may_act_for: unknown }>('SELECT may_act_for FROM oauth_clients WHERE client_id = $1 AND deleted_at IS NULL', [principal.id]);
return Array.isArray(row?.may_act_for) ? row!.may_act_for as string[] : null;
}
if (principal?.kind === 'local_stdio' || (!auth && !principal && caller.transport === 'stdio')) {
const [row] = await engine.executeRaw<{ value: string | null }>('SELECT value FROM config WHERE key = $1', [STDIO_MAY_ACT_FOR_KEY]);
const raw = row?.value?.trim();
return raw ? parseMayActFor(raw) : null;
}
} catch { /* unreadable: permits nothing */ }
return null;
}
function audienceNotPermitted(caller: AudienceCaller, audience: readonly AudiencePrincipal[], mayActFor: readonly string[] | null, missing: readonly string[]) {
const principal = caller.auth?.principal ?? caller.principal;
const list = [...new Set([...(mayActFor ?? []), ...audience])].sort().join(',');
const target = principal?.kind === 'legacy_token' ? { handle: `token ${caller.auth?.clientName ?? principal.id}`, argv: ['gbrain', 'auth', 'rescope', ...(caller.auth?.clientName ? ['--token', caller.auth.clientName] : ['--id', principal.id]), '--may-act-for', list] }
: principal?.kind === 'oauth_client' ? { handle: `OAuth client ${principal.id}`, argv: ['gbrain', 'auth', 'rescope', '--client', principal.id, '--may-act-for', list] }
: { handle: 'this stdio server', argv: ['gbrain', 'config', 'set', STDIO_MAY_ACT_FOR_KEY, list] };
return hostOnlyError({ remote: true, transport: caller.transport === 'stdio' || target.handle === 'this stdio server' ? 'stdio' : 'http' }, 'on_behalf_of_not_permitted',
`This connection (${target.handle}) may not act for ${missing.join(', ')}, so nothing was read.`,
target.argv,
'Lets this credential act for the whole audience. Widening whose notes a shared agent may read is the brain operator\'s decision, never the agent\'s.',
{ suggestion: `A shared agent acts only for the people its credential lists in may_act_for. The brain operator decides whether to approve the audience ${audience.join(', ')} by running the command in fix on the brain host; until then, call without the audience.` });
}
function audienceUnknown(principal: string) {
const group = principal.startsWith('group:');
return catalogueError('on_behalf_of_unknown_member', `The audience names ${principal}, which is not ${group ? 'a group' : 'an enabled member'} on this brain, so nothing was read.`,
`Name enabled members and existing groups only; a person who is not a member joins the audience as guest. The brain operator checks the ids with gbrain access ${group ? 'group' : 'member'} list${group ? '' : ' --all'}.`);
}
/**
* GBRA-231: the identities of an asserted audience, in order: a member's live identity (itself and its groups), a
* group as itself, a guest as the empty identity. Every entry must be in the caller's live may_act_for
* (on_behalf_of_not_permitted, checked first so it never confirms whether an id exists) and name an enabled member
* or an existing group (on_behalf_of_unknown_member). Read on every call, so a revoked permission or a disabled
* member takes effect at once.
*/
export async function resolveAudienceIdentities(engine: Pick<BrainEngine, 'executeRaw'>, caller: AudienceCaller, audience: readonly AudiencePrincipal[],
opts: { mayActFor?: 'enforce' | 'owner_room_assessment' } = {}): Promise<string[][]> {
// GBRA-498: only room.ts passes owner_room_assessment, after it checked that the caller reads as the brain owner or is
// the trusted local CLI; it marks results for a room and never reads as the room, so neither needs may_act_for for it.
if (opts.mayActFor !== 'owner_room_assessment') {
const mayActFor = await mayActForOf(engine, caller);
const missing = audience.filter(p => !mayActForCovers(mayActFor, p));
if (missing.length) throw audienceNotPermitted(caller, audience, mayActFor, missing);
}
const memberIds = audience.filter(p => p.startsWith('member:')).map(p => p.slice('member:'.length));
const groupIds = audience.filter(p => p.startsWith('group:')).map(p => p.slice('group:'.length));
const members = new Map<string, string[]>();
const groups = new Set<string>();
try {
if (memberIds.length) {
for (const row of await engine.executeRaw<{ id: string; groups: string[] }>(MEMBERS_WHERE_SQL('m.id = ANY($1::text[])'), [memberIds])) {
members.set(row.id, (row.groups ?? []).filter(g => normalizePrincipal(`group:${g}`) === `group:${g}`));
}
}
if (groupIds.length) for (const row of await engine.executeRaw<{ id: string }>('SELECT id FROM access_groups WHERE id = ANY($1::text[])', [groupIds])) groups.add(row.id);
} catch { /* unreadable: every entry reads as unknown below */ }
return audience.map(p => {
if (p === GUEST) return [];
if (p.startsWith('group:')) { if (!groups.has(p.slice(6))) throw audienceUnknown(p); return [p]; }
const id = p.slice('member:'.length);
const memberGroups = members.get(id);
if (!memberGroups) throw audienceUnknown(p);
return identityFor(id, memberGroups);
});
}
/**
* The CallerAccess fields for a remote operation (identity, privacy relaxation and the GBRA-156 private-readable set).
* GBRA-231: with an asserted `audience` the identities are the audience's (resolveAudienceIdentities, which refuses
* an entry outside may_act_for or naming no member), the source grant stays the caller's, and the caller's privacy
* relaxation (granted_sources, an operator hatch) applies only when the audience is exactly one member: a channel
* (several entries, a group or a guest) sees no visibility: private page.
* GST-2059: a caller bound to the brain owner (config access.owner_member) reads with its privacy relaxed in every
* source its grant reads (owner), with no audience or an audience of the owner alone; member access stays.
* GST-363: `stdioMember` is the member an unauthenticated stdio server was started with (serve --stdio-member).
* GST-2490: `readOnly` (a non-mutating operation) gives an owner read the owner's lineage (a derivative of origins it
* reads) and, under access.owner_reads_restricted, the opt-in; a write's checks keep the every-caller rule, so its
* pre-check and its publication agree.
* GBRA-108: under access.members_read_lineage a read by any other member speaking for itself (no audience, or an
* audience of that one member) gets the same lineage (design 3), and an owner read carries the audience members
* (design 2). Never an audience of several, a group or a guest, and never an unbound credential (no member identity).
* GBRA-108 design 1: a read or write whose bound member, or any member of its audience, is labelled-only reads only
* pages that name it (labelledOnly); never the owner.
*/
export async function remoteCallerAccess(engine: BrainEngine, auth: AuthInfo | undefined, privateSources: readonly string[] | undefined, transport?: string, audience?: readonly AudiencePrincipal[] | null, stdioMember?: string, readOnly = false): Promise<Partial<CallerAccess>> {
const [relaxed, remotePolicy] = await Promise.all([remotePrivacyRelaxed(engine), requestRemotePolicy(engine)]);
const restricted = remotePolicy.restricted;
if (audience?.length) return audienceCallerAccess(engine, auth, privateSources, transport, audience, await resolveAudienceIdentities(engine, { auth, transport }, audience), stdioMember, readOnly, relaxed, remotePolicy);
const identity = restricted || remotePolicy.ownerMember ? await boundIdentity(engine, auth, transport, stdioMember) : [];
const owner = isOwner(identity, remotePolicy);
const lineage = readOnly && identity.some(p => p.startsWith('member:')) && (owner || remotePolicy.membersReadLineage === true);
return {
identity,
audience: null,
audienceIdentities: [],
...(restricted ? await folderAccessFor(engine, identity) : { satisfiedRuleIds: [], folderCoverage: [] }),
privateReadableSources: privateSources ?? [],
hidePrivate: !relaxed && !owner,
owner,
lineage,
ownerReadsRestricted: owner && lineage && remotePolicy.ownerReadsRestricted === true,
audienceKindMembers: owner && lineage ? await audienceMemberIds(engine) : [],
labelledOnly: !owner && restricted && await labelledOnlyFor(engine, [identity]),
applyRemoteReadPolicy: false,
restricted,
remotePolicy,
};
}
/**
* GBRA-231: the access record of an audience whose identities resolveAudienceIdentities resolved. GBRA-498: room.ts
* builds a room's record with it, so a room mark and an on_behalf_of read of the same audience judge pages alike.
*/
export async function audienceCallerAccess(engine: BrainEngine, auth: AuthInfo | undefined, privateSources: readonly string[] | undefined, transport: string | undefined,
audience: readonly AudiencePrincipal[], identities: string[][], stdioMember?: string, readOnly = false,
relaxed?: boolean, policy?: RemotePolicy): Promise<Partial<CallerAccess>> {
const remotePolicy = policy ?? await requestRemotePolicy(engine);
const restricted = remotePolicy.restricted;
if (relaxed === undefined) relaxed = await remotePrivacyRelaxed(engine);
const single = singleMemberAudience(audience);
const owner = single && audience[0] === `member:${remotePolicy.ownerMember}`
&& isOwner(await boundIdentity(engine, auth, transport, stdioMember), remotePolicy);
const lineage = readOnly && single && identities.length === 1 && (owner || remotePolicy.membersReadLineage === true);
return {
identity: identities.length === 1 ? identities[0]! : [],
audience: [...audience],
audienceIdentities: identities.length > 1 ? identities : [],
...(restricted ? await folderAccessForAll(engine, identities) : { satisfiedRuleIds: [], folderCoverage: [] }),
privateReadableSources: single ? privateSources ?? [] : [],
hidePrivate: single ? !relaxed && !owner : true,
owner,
lineage,
ownerReadsRestricted: owner && lineage && remotePolicy.ownerReadsRestricted === true,
audienceKindMembers: owner && lineage ? await audienceMemberIds(engine) : [],
labelledOnly: !owner && restricted && await labelledOnlyFor(engine, [...identities, await boundIdentity(engine, auth, transport, stdioMember)]),
applyRemoteReadPolicy: false,
restricted,
remotePolicy,
};
}
/** The member identity a remote caller's credential (or, unauthenticated over stdio, serve --stdio-member, else config mcp.stdio_member) is bound to. */
async function boundIdentity(engine: BrainEngine, auth: AuthInfo | undefined, transport?: string, stdioMember?: string): Promise<string[]> {
return !auth && transport === 'stdio' ? stdioMemberIdentity(engine, stdioMember) : memberIdentityFor(engine, auth);
}
/** GST-2059: the live identity is the brain owner's (config access.owner_member). Only a live, enabled member has an identity. */
function isOwner(identity: readonly string[], policy: RemotePolicy): boolean {
return !!policy.ownerMember && identity.includes(`member:${policy.ownerMember}`);
}
/**
* GBRA-231: the view a remote call was answered under, as `_meta.access` on every remote response and `access.applied`
* in whoami: the member and groups it read as (none for an audience of several entries), the asserted audience, the
* applied folder-rule revision of each source the credential is granted (every source for an unauthenticated stdio
* server; null on a brain with no restriction) and the privacy relaxation in force.
*/
export interface AppliedAccess {
member: string | null;
groups: string[];
audience: string[] | null;
/** GST-359 C1: present on an attested call (the system that named the person; the id is not echoed). */
actor?: { system: string };
policy_rev: Record<string, number> | null;
relaxation: 'none' | 'granted_sources' | 'operator' | 'owner';
}
export async function appliedAccessSummary(engine: Pick<BrainEngine, 'executeRaw'>, auth?: AuthInfo, sourceIds: readonly (string | undefined)[] = []): Promise<AppliedAccess> {
const access = currentCallerAccess();
const member = access.identity.find(p => p.startsWith('member:'))?.slice('member:'.length) ?? null;
let policyRev: Record<string, number> | null = null;
if (access.restricted) {
try {
const rows = await engine.executeRaw<{ source_id: string; rev: number | string | null }>(
`SELECT s.source_id, (SELECT r.revision FROM access_policy_revisions r WHERE r.source_id = s.source_id AND r.applied_at IS NOT NULL
ORDER BY r.revision DESC LIMIT 1) AS rev FROM access_policy_state s ORDER BY s.source_id`);
const visible = auth ? new Set([auth.sourceId, ...(auth.allowedSources ?? []), ...sourceIds].filter(Boolean)) : null;
policyRev = Object.fromEntries(rows.filter(r => r.rev !== null && (!visible || visible.has(r.source_id))).map(r => [r.source_id, Number(r.rev)]));
} catch { policyRev = null; }
}
return {
member,
groups: access.identity.filter(p => p.startsWith('group:')).map(p => p.slice('group:'.length)),
audience: access.audience ? [...access.audience] : null,
...(access.actor ? { actor: { system: access.actor.system } } : {}),
policy_rev: policyRev,
relaxation: access.owner ? 'owner' : !access.hidePrivate ? 'operator' : access.privateReadableSources.length ? 'granted_sources' : 'none',
};
}
/** What whoami and grant_diagnosis report about the caller's member identity. */
export interface CallerAccessView {
member: string | null;
groups: string[];
may_act_for: string[] | null;
bound_by: 'credential' | 'stdio_registration' | 'stdio_config' | 'as' | 'none';
note?: string;
}
export function accessView(identity: readonly string[], boundBy: CallerAccessView['bound_by'], mayActFor: string[] | null = null, note?: string): CallerAccessView {
const member = identity.find(p => p.startsWith('member:'))?.slice('member:'.length) ?? null;
return {
member,
groups: identity.filter(p => p.startsWith('group:')).map(p => p.slice('group:'.length)),
may_act_for: mayActFor,
bound_by: member ? boundBy : 'none',
...(note ? { note } : {}),
};
}
const UNBOUND_NOTE = 'Bound to no member: pages that name readers (readable_by) are hidden from this caller, and a not_found may be such a page.';
/** The access view of an authenticated credential (the verifier's join, else a principal lookup). */
export async function credentialAccessView(engine: BrainEngine, auth: AuthInfo): Promise<CallerAccessView> {
const identity = await memberIdentityFor(engine, auth);
return accessView(identity, 'credential', auth.mayActFor ?? null, identity.length ? undefined : UNBOUND_NOTE);
}
/** The access view of a local stdio server: serve --stdio-member (`registered`) when it was started with one, else config mcp.stdio_member. */
export async function stdioAccessView(engine: BrainEngine, registered?: string): Promise<CallerAccessView> {
const [configured, identity] = await Promise.all([stdioMemberId(engine), stdioMemberIdentity(engine, registered)]);
if (registered !== undefined) {
const ignored = configured && configured !== registered ? ` config mcp.stdio_member names "${configured}", which this server ignores: its own --stdio-member wins.` : '';
if (identity.length) return accessView(identity, 'stdio_registration', null, ignored.trim() || undefined);
return accessView([], 'none', null, `This server was started with --stdio-member ${registered}, which is not an enabled member, so it reads no page that names readers.${ignored}`);
}
if (identity.length) return accessView(identity, 'stdio_config');
return accessView([], 'none', null, configured
? `mcp.stdio_member names "${configured}", which is not an enabled member, so this server reads no page that names readers.`
: `${UNBOUND_NOTE} ${stdioBindRoute().text}`);
}