Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* GST-359 C1 (GBRA-218): the attested actor. A trusted system's credential (only `qm` today) names the person a call
* serves in the `x-qm-actor` header: an opaque canonical id (a Slack id, an email principal, `oidc:<hash>:<subject>`),
* 1-256 visible ASCII characters, compared exactly. gbrain maps it through `access_member_links` to one enabled member
* and reads and writes as that member, never relaxing privacy.
*
* Two facts must both hold, re-read on every call and at every later publication or job tool call (actorCoverage):
* - the credential holds the attest right for the system: `attest_actor` on a legacy token bound to no member, or on
* an OAuth client bound to no member whose token came from the client-credentials grant (the verifier checks the
* grant that issued the token; a stored principal checks the client's registration);
* - the id is linked to an enabled member.
* Everything lives in the database, so a repo-less brain gets it unchanged.
*/
import type { BrainEngine } from '../engine.ts';
import type { AuthInfo } from '../ops/contract.ts';
import { opError, type OperationError } from '../ops/contract.ts';
import { hostOnlyError } from '../ops/op-fix.ts';
import { catalogueError, ERROR_CATALOGUE } from '../error-catalogue.ts';
import { schemaVersionNow, type CallerAccess } from '../search/private-visibility.ts';
import { identityFor } from './principals.ts';
import { isMissingSchemaObject } from '../utils.ts';
import { memberByEmail, memberIdentity } from './members.ts';
import { folderAccessFor, memberIdentityFor } from './caller.ts';
import { labelledOnlyFor } from './labelled-only.ts';
import { markedScopeSources, sourceNotAttested } from './attest-sources.ts';
import { ACTOR_ARGUMENT, ACTOR_DEFERRED_OPS, ACTOR_HEADER, attestRightFrom, DEFAULT_ATTEST_OPS, EXTERNAL_ID_RE, QM_AUDIENCE_HEADER, type AttestedActor, type AttestRight } from './actor-model.ts';
export * from './actor-model.ts';
const ATTESTABLE_SCOPES = new Set(['read', 'write', 'agent']);
export type ActorReason = 'no_attest_right' | 'op_not_attested' | 'argument_mismatch' | 'argument_without_attestation' | 'invalid_actor_id' | 'actor_required' | 'audience_not_supported';
/** The operation metadata attestability reads (a subset of Operation, so this module never imports the registry). */
export interface AttestableOpShape { scope?: string; requiredScopes?: readonly string[]; localOnly?: boolean; cliOnly?: unknown }
type Principal = { kind: string; id: string };
export interface ActorCaller {
auth?: Pick<AuthInfo, 'attest' | 'member' | 'clientName'> & { principal?: Principal };
principal?: Principal;
}
/** The caller's live attest right: the verifier's on a live call, else a row lookup from the stored principal. */
export async function attestRightOf(engine: Pick<BrainEngine, 'executeRaw'>, caller: ActorCaller): Promise<AttestRight | null> {
if (caller.auth?.attest !== undefined) return caller.auth.attest ?? null;
const principal = caller.auth?.principal ?? caller.principal;
try {
if (principal?.kind === 'legacy_token') {
const [row] = await engine.executeRaw<Record<string, unknown>>(
`SELECT attest_actor, attest_ops, to_jsonb(access_tokens)->'attest_sources' AS attest_sources, to_jsonb(access_tokens)->>'attest_read' AS attest_read, member_id FROM access_tokens WHERE id::text = $1 AND revoked_at IS NULL`, [principal.id]);
return attestRightFrom(row, 'legacy', row?.member_id);
}
if (principal?.kind === 'oauth_client') {
const [row] = await engine.executeRaw<Record<string, unknown>>(
`SELECT attest_actor, attest_ops, to_jsonb(oauth_clients)->'attest_sources' AS attest_sources, to_jsonb(oauth_clients)->>'attest_read' AS attest_read, member_id, grant_types, client_secret_hash IS NOT NULL AS confidential FROM oauth_clients
WHERE client_id = $1 AND (to_jsonb(oauth_clients)->>'deleted_at') IS NULL`, [principal.id]);
const cc = Array.isArray(row?.grant_types) && (row!.grant_types as unknown[]).includes('client_credentials') && row!.confidential === true;
return attestRightFrom(row, cc ? 'client_credentials' : null, row?.member_id);
}
} catch (e) {
// A schema before the attest columns has no right. Any other failure (a lock timeout, an aborted transaction) is
// rethrown: read as "no right" it would refuse a stored write for good instead of letting it retry.
if (!isMissingSchemaObject(e, 'column', ['attest_actor', 'attest_ops', 'member_id'])) throw e;
}
return null;
}
/** Whether an operation may ever run under an attested actor: the reserved memory pair or a read, write or agent op. */
export function attestableOp(name: string, op: AttestableOpShape | undefined): boolean {
if (ACTOR_DEFERRED_OPS.has(name)) return false;
if (DEFAULT_ATTEST_OPS.includes(name)) return true;
if (!op || op.localOnly || op.cliOnly) return false;
return ATTESTABLE_SCOPES.has(op.scope ?? 'read') && !(op.requiredScopes ?? []).some(s => !ATTESTABLE_SCOPES.has(s));
}
/** A `--attest-ops` value: distinct operation names, each attestable; admin and membership ops are refused. */
export function parseAttestOps(raw: string, lookup: (name: string) => AttestableOpShape | undefined): string[] {
const ops = [...new Set(raw.split(',').map(s => s.trim()).filter(Boolean))];
if (!ops.length) throw opError('invalid_params', '--attest-ops needs at least one operation.', `Pass a comma-separated list, for example ${DEFAULT_ATTEST_OPS.join(',')}.`);
const deferred = ops.filter(op => ACTOR_DEFERRED_OPS.has(op));
if (deferred.length) {
throw opError('invalid_params', `--attest-ops names ${deferred.join(', ')}, which an attested actor cannot run yet: what they read or write is not yet kept to the person.`,
`Leave ${deferred.join(', ')} out. Not attestable yet: ${[...ACTOR_DEFERRED_OPS].join(', ')}.`,
{ why: 'An attested call must never return or record one person\'s memory where another person reads it.' });
}
const refused = ops.filter(op => !/^[a-z][a-z0-9_]{0,63}$/.test(op) || !attestableOp(op, lookup(op)));
if (refused.length) {
throw opError('invalid_params', `--attest-ops names ${refused.join(', ')}, which an attested actor can never run.`,
`Name read, write or agent operations (gbrain --tools-json lists them) or the memory pair ${DEFAULT_ATTEST_OPS.join(',')}; admin, membership and local-only operations are never attestable.`,
{ why: 'An attested call runs as a person the trusted system names; it never carries operator authority.' });
}
return ops.sort();
}
function credentialArgv(caller: ActorCaller): string[] {
const principal = caller.auth?.principal ?? caller.principal;
if (principal?.kind === 'oauth_client') return ['--client', principal.id];
return caller.auth?.clientName ? ['--token', caller.auth.clientName] : ['--id', principal?.id ?? '<token id>'];
}
const transportOf = (transport?: string) => ({ remote: true, transport: transport === 'stdio' ? 'stdio' as const : 'http' as const });
/** actor_not_attested with its reason, remedy and (where the operator can fix it) the rescope command. */
export function actorNotAttested(reason: ActorReason, caller: ActorCaller, ctx: { op: string; transport?: string; right?: AttestRight | null; reissue?: boolean; memberBound?: boolean; missing?: Array<'attest_right' | 'x-qm-actor'> }): OperationError {
const docs = ERROR_CATALOGUE.actor_not_attested.docs;
const rescope = (extra: string[]) => ['gbrain', 'auth', 'rescope', ...credentialArgv(caller), ...extra];
const hostOnly = (message: string, argv: string[], why: string, suggestion: string) =>
Object.assign(hostOnlyError(transportOf(ctx.transport), 'actor_not_attested', message, argv, why, { reason, suggestion }), { docs });
switch (reason) {
case 'no_attest_right':
if (ctx.reissue) {
return opError('actor_not_attested', `This client holds the attest right, but this access token was not issued by the client-credentials grant since the upgrade, so it may not name the person it acts for (${ACTOR_HEADER}). Nothing was read or written.`,
'Request a new token with grant_type=client_credentials (POST /token) and retry with it. Tokens issued before the upgrade, or by another grant, never attest.', { reason, docs });
}
return hostOnly(`This connection may not name the person it acts for (${ACTOR_HEADER}), so nothing was read or written.`, rescope(['--attest-actor', 'qm']),
'Grants this client-credentials client (or member-less legacy token) the right to name the person a QM call serves. Trusting a system to name people is the brain operator\'s decision.',
'Only a credential the brain operator granted the attest right may send the actor header. Call without it, or ask the operator to run the command in fix.');
case 'op_not_attested':
if (ACTOR_DEFERRED_OPS.has(ctx.op)) {
return opError('actor_not_attested', `${ctx.op} cannot run as an attested person yet: what it reads or writes is not yet kept to the person. Nothing was read or written.`,
`Call it without ${ACTOR_HEADER}, or use an attestable operation. Not attestable yet: ${[...ACTOR_DEFERRED_OPS].join(', ')}.`, { reason, docs });
}
return hostOnly(`${ctx.op} is not in this connection's attested operations, so nothing was read or written.`,
rescope(['--attest-actor', 'qm', '--attest-ops', [...new Set([...(ctx.right?.ops ?? DEFAULT_ATTEST_OPS), ctx.op])].sort().join(',')]),
'Lets an attested call run this operation as the person it names. Widening what a trusted system may do as a person is the brain operator\'s decision.',
`An attested call runs only the operations the operator listed (default ${DEFAULT_ATTEST_OPS.join(', ')}); admin and membership operations never.`);
case 'argument_mismatch':
if (ctx.memberBound) {
return opError('actor_not_attested', `The ${ACTOR_ARGUMENT} argument names someone other than this credential's member, so nothing was read or written.`,
`Leave ${ACTOR_ARGUMENT} out, or send this credential's own member id or a canonical id linked to it. A credential bound to a member reads only as that member; text in a conversation never chooses whose notes are read.`, { reason, docs });
}
return opError('actor_not_attested', `The ${ACTOR_ARGUMENT} argument names someone other than the ${ACTOR_HEADER} header, so nothing was read or written.`,
`The header decides whom the call serves; send ${ACTOR_ARGUMENT} equal to it, or leave it out. Text in a conversation never chooses whose notes are read.`, { reason, docs });
case 'argument_without_attestation': {
const missing = ctx.missing ?? ['attest_right', ACTOR_HEADER];
const lacks = missing.map(m => (m === 'attest_right' ? 'the attest right on this credential' : `the ${ACTOR_HEADER} header`)).join(' and ');
return opError('actor_not_attested', `The ${ACTOR_ARGUMENT} argument is accepted only on an attested call, and this call lacks ${lacks}, so nothing was read or written.`,
`Remove ${ACTOR_ARGUMENT} from the arguments. A trusted system names the person in the ${ACTOR_HEADER} header from a credential holding the attest right (gbrain auth rescope ... --attest-actor qm on the brain host).`, { reason, docs, detail: `missing=${missing.join(',')}` });
}
case 'actor_required':
if (ctx.right?.read === 'scope') {
return opError('actor_not_attested', `This credential reads and writes only for an attested person (--attest-read scope), and this call names none (no ${ACTOR_HEADER} header), so nothing was read or written.`,
`Send ${ACTOR_HEADER} with the person's canonical id on every call from this credential. A call that serves nobody in particular uses a credential without the attest right.`, { reason, docs });
}
return opError('actor_not_attested', `${ctx.op} writes only as an attested person, and this call names none (no ${ACTOR_HEADER} header on a credential holding the attest right), so nothing was written.`,
`Send ${ACTOR_HEADER} with the person's canonical id from a credential the brain operator granted the attest right (${rescope(['--attest-actor', 'qm']).join(' ')}). To save a fact as yourself, call remember.`, { reason, docs });
case 'audience_not_supported':
return opError('actor_not_attested', `This request carries ${QM_AUDIENCE_HEADER} (a channel audience), which this brain does not serve yet, so nothing was read or written.`,
`Send the call without ${QM_AUDIENCE_HEADER}. Channel turns are refused until wave 2; a call for one person sends ${ACTOR_HEADER} alone.`, { reason, docs });
case 'invalid_actor_id':
return opError('actor_not_attested', `The ${ACTOR_HEADER} header or the ${ACTOR_ARGUMENT} argument is not a canonical person id (1-256 visible ASCII characters), so nothing was read or written.`,
'Fix the harness code that sets the header: send the canonical id unchanged, with no spaces or control characters.', { reason, docs });
}
}
/** actor_unlinked: the operator links the id to a member. dispatch's actorRefusal is the one place a recall tool may turn it into an empty result. */
export function actorUnlinked(externalId: string, transport?: string): OperationError {
return Object.assign(hostOnlyError(transportOf(transport), 'actor_unlinked',
'The person this call names is not linked to an enabled member of this brain, so nothing was read or written.',
['gbrain', 'access', 'member', 'link', '<member>', '--qm', externalId],
'Links the canonical id to the member it belongs to; an unlinked id, or one linked to a disabled member, reads nothing. Who a person is on this brain is the operator\'s decision.',
{ suggestion: 'Ask the brain operator to link this person to their member (gbrain access member link <member> --qm <id>), or to enable the member if it is disabled.' }),
{ docs: ERROR_CATALOGUE.actor_unlinked.docs });
}
/** The enabled member linked to (system, external_id), with its identity; null when unlinked, disabled or the link tables are missing. */
export async function linkedMember(engine: Pick<BrainEngine, 'executeRaw'>, system: string, externalId: string): Promise<{ member: string; groups: string[]; identity: string[] } | null> {
try {
const [row] = await engine.executeRaw<{ id: string; groups: string[] | null }>(
`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_member_links l JOIN access_members m ON m.id = l.member_id LEFT JOIN access_group_members g ON g.member_id = m.id
WHERE l.system = $1 AND l.external_id = $2 AND m.disabled_at IS NULL AND m.tombstoned_at IS NULL GROUP BY m.id`, [system, externalId]);
if (!row) return null;
const groups = row.groups ?? [];
return { member: row.id, groups, identity: identityFor(row.id, groups) };
} catch (e) {
// GST-359 D: only a schema before the link tables reads as unlinked. A database failure (an aborted transaction under
// a concurrent publication, a lock timeout) is rethrown, so a stored write retries instead of failing as actor_unlinked.
if (!isMissingSchemaObject(e, 'table', ['access_member_links', 'access_members', 'access_group_members'])) throw e;
return null;
}
}
/**
* The one coverage test for an attested actor, used by dispatch, write publication and job tool calls: the caller's
* live attest right for the system, and a live link from the id to an enabled member. Returns that member's identity;
* throws actor_not_attested (no_attest_right) or actor_unlinked.
*/
export async function actorCoverage(engine: Pick<BrainEngine, 'executeRaw'>, caller: ActorCaller, actor: { system: string; external_id: string }, transport?: string, op?: string, source?: string):
Promise<{ member: string; groups: string[]; identity: string[] }> {
const right = await attestRightOf(engine, caller);
if (!right || right.system !== actor.system) throw actorNotAttested('no_attest_right', caller, { op: op ?? 'stored', transport });
if (op !== undefined && (!right.ops.includes(op) || ACTOR_DEFERRED_OPS.has(op))) throw actorNotAttested('op_not_attested', caller, { op, transport, right });
// GST-1113: a write accepted for a per-call scope source needs the live right to still list it.
if (source !== undefined && (!right.sources?.includes(source) || !(await markedScopeSources(engine as BrainEngine, [source])).has(source))) throw sourceNotAttested(source);
const linked = EXTERNAL_ID_RE.test(actor.external_id) ? await linkedMember(engine, actor.system, actor.external_id) : null;
if (!linked) throw actorUnlinked(actor.external_id, transport);
return linked;
}
/**
* A stored attested authority (a queued write, an agent job) re-resolved through actorCoverage: the same member must
* still be covered and, when `op` is given (publication, a job tool call), the operation must still be attested.
*/
export async function storedActorIdentity(engine: Pick<BrainEngine, 'executeRaw'>, principal: Principal, actor: AttestedActor, op?: string, source?: string): Promise<string[]> {
const covered = await actorCoverage(engine, { principal }, actor, undefined, op, source);
if (covered.member !== actor.member) throw actorUnlinked(actor.external_id);
return covered.identity;
}
/**
* The caller-access record of an attested call: a one-member audience of the linked member with privacy never relaxed
* (no granted_sources, no operator hatch), whatever the attest credential's own grants say. An explicit mode, not B's
* may_act_for path, which relaxes privacy for a one-member audience.
*/
export async function attestedCallerAccess(engine: Pick<BrainEngine, 'executeRaw'>, actor: AttestedActor, identity: string[]): Promise<Partial<CallerAccess>> {
return {
identity,
audience: [`member:${actor.member}`],
audienceIdentities: [],
actor: { ...actor },
...await folderAccessFor(engine, identity),
privateReadableSources: [],
hidePrivate: true,
labelledOnly: await labelledOnlyFor(engine, [identity]),
applyRemoteReadPolicy: false,
restricted: true,
remotePolicy: { privacyRelaxed: false, restricted: true, ...await schemaVersionNow(engine) },
};
}
/** The actor channel a transport read from the request: the header value, undefined when absent. Never tool arguments. */
/** The headers the HTTP transport read: x-qm-actor, and x-qm-audience (refused on every call while it is not served). */
export interface ActorChannels { header?: string | null; audience?: string | null }
/**
* The attested-actor decision for one remote call, made before any work. Null when the call names no actor (no header,
* no argument): the caller's own identity or B's audience applies; GST-1158 F4: a credential whose attest right says
* `attest_read = 'scope'` is refused there instead (actor_required), so it never reads as itself. Otherwise the access record and the arguments with
* `acting_user` stripped, or a refusal: actor_not_attested with its reason, actor_unlinked, or B's
* on_behalf_of_invalid_audience when an on_behalf_of audience is asserted too.
*/
export async function resolveAttestedActor(engine: Pick<BrainEngine, 'executeRaw'>, input: {
channels?: ActorChannels; params: Record<string, unknown> | undefined; op: string; opShape: AttestableOpShape | undefined;
auth?: ActorCaller['auth']; transport?: string; audienceAsserted: boolean;
}): Promise<{ actor?: AttestedActor; access?: Partial<CallerAccess>; params: Record<string, unknown>; read?: AttestRight['read'] } | null> {
const header = input.channels?.header ?? undefined;
const hasArgument = !!input.params && Object.prototype.hasOwnProperty.call(input.params, ACTOR_ARGUMENT);
const caller: ActorCaller = { auth: input.auth };
if (input.channels?.audience != null) throw actorNotAttested('audience_not_supported', caller, { op: input.op, transport: input.transport });
if (header === undefined && !hasArgument) {
if (input.transport !== 'stdio' && input.auth?.attest?.read === 'scope') throw actorNotAttested('actor_required', caller, { op: input.op, transport: input.transport, right: input.auth.attest });
return null;
}
const ctx = { op: input.op, transport: input.transport };
const argument = hasArgument ? input.params![ACTOR_ARGUMENT] : undefined;
if ((header !== undefined && !EXTERNAL_ID_RE.test(header)) || (hasArgument && (typeof argument !== 'string' || !EXTERNAL_ID_RE.test(argument)))) {
throw actorNotAttested('invalid_actor_id', caller, ctx);
}
if (header === undefined) return ownMemberArgument(engine, input, argument as string, caller, ctx);
if (input.audienceAsserted) {
throw catalogueError('on_behalf_of_invalid_audience', `The call names its person twice (${ACTOR_HEADER} and an on_behalf_of audience). Nothing was read.`,
`Send one: ${ACTOR_HEADER} from an attest credential, or X-Gbrain-On-Behalf-Of / request-level _meta.on_behalf_of from a shared agent.`);
}
const right = input.transport === 'stdio' ? null : await attestRightOf(engine, caller);
if (!right || right.system !== 'qm') {
const principal = input.auth?.principal;
const reissue = !hasArgument && !right && principal?.kind === 'oauth_client' && !!await attestRightOf(engine, { principal });
throw actorNotAttested(hasArgument ? 'argument_without_attestation' : 'no_attest_right', caller, { ...ctx, reissue, missing: ['attest_right'] });
}
if (!right.ops.includes(input.op) || !attestableOp(input.op, input.opShape)) throw actorNotAttested('op_not_attested', caller, { ...ctx, right });
if (hasArgument && argument !== header) throw actorNotAttested('argument_mismatch', caller, ctx);
const covered = await actorCoverage(engine, caller, { system: right.system, external_id: header }, input.transport);
const actor: AttestedActor = { system: right.system, external_id: header, member: covered.member };
const { [ACTOR_ARGUMENT]: _stripped, ...params } = input.params ?? {};
return { actor, access: await attestedCallerAccess(engine, actor, covered.identity), params, ...(right.read ? { read: right.read } : {}) };
}
/**
* GST-900: acting_user with no header, on a credential bound to a member (no stdio, no on_behalf_of audience). The
* member id, or a canonical id linked to it, is stripped and the call runs exactly as the credential; any other value
* is argument_mismatch, so the argument never widens or switches whose notes are read, and never tells an existing id
* from an unknown one. Every other caller is refused argument_without_attestation as before.
*/
async function ownMemberArgument(engine: Pick<BrainEngine, 'executeRaw'>, input: { params?: Record<string, unknown>; auth?: ActorCaller['auth']; transport?: string; audienceAsserted: boolean },
argument: string, caller: ActorCaller, ctx: { op: string; transport?: string }): Promise<{ params: Record<string, unknown> }> {
const own = input.transport === 'stdio' || input.audienceAsserted || !input.auth ? null
: (await memberIdentityFor(engine, input.auth)).find(p => p.startsWith('member:'))?.slice('member:'.length) ?? null;
if (!own) {
const right = input.transport === 'stdio' ? null : await attestRightOf(engine, caller);
throw actorNotAttested('argument_without_attestation', caller, { ...ctx, missing: right?.system === 'qm' ? [ACTOR_HEADER] : ['attest_right', ACTOR_HEADER] });
}
if (argument !== own && (await linkedMember(engine, 'qm', argument))?.member !== own) throw actorNotAttested('argument_mismatch', caller, { ...ctx, memberBound: true });
const { [ACTOR_ARGUMENT]: _stripped, ...params } = input.params ?? {};
return { params };
}
export interface MemberLink { system: string; external_id: string; member_id: string; created_at: string | null }
function linkInvalid(message: string, reason: string, suggestion: string): OperationError {
return opError('access_member_invalid', message, suggestion, { reason, why: 'A link decides whose notes a trusted system reads for a person, so it is matched exactly and never guessed.' });
}
function assertExternalId(raw: unknown): string {
if (typeof raw === 'string' && EXTERNAL_ID_RE.test(raw)) return raw;
throw linkInvalid('The --qm id is not a canonical person id.', 'invalid_external_id',
'Pass the id exactly as QM sends it in x-qm-actor: 1-256 visible ASCII characters, no spaces (for example U0ALICE or oidc:3f2a:alice-example).');
}
const iso = (v: unknown) => v == null ? null : v instanceof Date ? v.toISOString() : String(v);
const toLink = (r: Record<string, unknown>): MemberLink => ({ system: String(r.system), external_id: String(r.external_id), member_id: String(r.member_id), created_at: iso(r.created_at) });
async function linkRow(engine: Pick<BrainEngine, 'executeRaw'>, system: string, externalId: string): Promise<MemberLink | null> {
const [row] = await engine.executeRaw<Record<string, unknown>>('SELECT system, external_id, member_id, created_at FROM access_member_links WHERE system = $1 AND external_id = $2', [system, externalId]);
return row ? toLink(row) : null;
}
/** Links a canonical id to an enabled member; refuses an invalid id, a member that is not enabled and an id already linked. */
export async function linkMember(engine: BrainEngine, rawMember: unknown, system: string, rawId: unknown, opts: { dryRun?: boolean } = {}): Promise<{ link: MemberLink; applied: boolean }> {
const externalId = assertExternalId(rawId);
const { member } = await memberIdentity(engine, rawMember);
const existing = await linkRow(engine, system, externalId);
if (existing) {
throw linkInvalid(`That ${system} id is already linked to member "${existing.member_id}".`, 'link_exists',
existing.member_id === member ? 'Nothing to do: the link exists.' : `Unlink it first (gbrain access member unlink --${system} <id>), then link it to ${member}.`);
}
if (opts.dryRun) return { link: { system, external_id: externalId, member_id: member, created_at: null }, applied: false };
await engine.executeRaw('INSERT INTO access_member_links (system, external_id, member_id) VALUES ($1, $2, $3)', [system, externalId, member]);
return { link: (await linkRow(engine, system, externalId))!, applied: true };
}
/** GST-1158: the operator names the member by its declared email (memberByEmail); the link is then exactly linkMember's. */
export async function linkMemberByEmail(engine: BrainEngine, rawEmail: unknown, system: string, rawId: unknown, opts: { dryRun?: boolean } = {}): Promise<{ link: MemberLink; applied: boolean }> {
return linkMember(engine, (await memberByEmail(engine, rawEmail)).id, system, rawId, opts);
}
/** Removes one link; the next attested call naming the id is refused (actor_unlinked). */
export async function unlinkMember(engine: BrainEngine, system: string, rawId: unknown, opts: { dryRun?: boolean } = {}): Promise<{ link: MemberLink; applied: boolean }> {
const externalId = assertExternalId(rawId);
const existing = await linkRow(engine, system, externalId);
if (!existing) throw linkInvalid(`That ${system} id is not linked to any member.`, 'unknown_link', 'List the links with gbrain access member links.');
if (!opts.dryRun) await engine.executeRaw('DELETE FROM access_member_links WHERE system = $1 AND external_id = $2', [system, externalId]);
return { link: existing, applied: !opts.dryRun };
}
export async function listMemberLinks(engine: BrainEngine, opts: { member?: string } = {}): Promise<MemberLink[]> {
const rows = await engine.executeRaw<Record<string, unknown>>(
`SELECT system, external_id, member_id, created_at FROM access_member_links${opts.member ? ' WHERE member_id = $1' : ''} ORDER BY member_id, system, external_id`,
opts.member ? [opts.member] : []);
return rows.map(toLink);
}