Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
19.4 KB
Raw Blame
import { randomUUID } from 'node:crypto';
import { opError, type OperationContext } from '../ops/contract.ts';
import { readFix, scopeDeniedError } from '../ops/op-fix.ts';
import type { Action } from '../agent-output.ts';
import { policyFix } from './fixes.ts';
import { sourceScopeOpts } from '../ops/context.ts';
import { hasScope } from '../scope.ts';
import { currentVerifiedLocalWriter, type LocalGrant } from '../persistence/identity.ts';
import { normalizeTokenScopes } from '../legacy-token-scope.ts';
import { authSourcesFromGrant, grantFromTokenRow } from '../grants/model.ts';
import type { SqlEngine, WriteAuthority } from '../persistence/model.ts';
import { stringList } from './manifest.ts';
import type { SharedSkillPolicy, SkillFileClass, StoredSkillFile } from './model.ts';

const SOURCES_FIX = readFix('Lists the registered sources and whether each is archived.', {
  argv: ['gbrain', 'sources', 'list', '--json'], mcp: { tool: 'sources_list', arguments: {} },
});
/** The host-side grant listing for a principal kind: the local writer registrations, or the OAuth clients and tokens. */
function grantFix(kind: string | undefined, why: string): Action {
  const local = kind === 'local_stdio' || kind === 'local_cli';
  const argv = local ? ['gbrain', 'auth', 'local-writer', 'list', '--json'] : ['gbrain', 'auth', 'clients', '--json'];
  if (kind === 'local_cli') return readFix(why, { argv });
  return {
    argv, consent: [], actor: local ? 'user' : 'host_admin', why, requires_exclusive: false,
    user_message: local
      ? 'This gbrain connection is missing access it needs. Please review its registration by running the command shown in a terminal on this machine.'
      : 'This gbrain connection is missing access it needs. Please ask whoever runs the gbrain server to review its grant with the command shown.',
  };
}

export function skillPrincipal(ctx: OperationContext): string {
  const p = ctx.auth?.principal ?? currentVerifiedLocalWriter()?.principal;
  if (p) return `${p.kind}:${p.id}`;
  if (ctx.remote === false) return 'local_cli';
  throw opError('permission_denied', 'A verified principal is required for shared skills.',
    'Connect through an authenticated MCP client (OAuth client or access token), or use the gbrain CLI on the brain host; shared skills apply per-principal grants, so anonymous connections are refused.');
}
function intersect(original: string[], live: string[]): string[] { return original.filter(v => live.includes(v)); }
export async function authorizeSkillRead(ctx: OperationContext, operation: string): Promise<OperationContext> {
  if (ctx.remote === false) return ctx;
  const auth = ctx.auth;
  const verified = currentVerifiedLocalWriter();
  if (!auth?.principal && verified) {
    const [row] = await ctx.engine.executeRaw<{ revoked_at: unknown; grant_ceiling: LocalGrant }>(
      'SELECT revoked_at,grant_ceiling FROM persistence_local_writers WHERE id=$1::uuid', [verified.principal.id]);
    if (!verified.remote || !row || row.revoked_at != null || auth && (auth.clientId !== verified.principal.id ||
      auth.grantProjectionDegraded || auth.fenceProjectionDegraded || auth.sourceActive === false ||
      auth.effectiveSurface === 'verbs' || !hasScope(auth.scopes, 'read') ||
      auth.allowedOperations != null && !auth.allowedOperations.includes(operation)) ||
      [verified.grant, row.grant_ceiling].some(grant => !hasScope(grant.scopes, 'read') ||
        grant.operations !== null && !grant.operations.includes(operation))) {
      throw opError('permission_denied', 'The local reader grant excludes this operation.',
        `This local connection's registration no longer allows ${operation} (it needs read scope and the operation in its grant). The user reviews the registration in a terminal on this machine.`,
        { fix: grantFix('local_stdio', `Shows the local writer registrations and their grants; ${operation} needs read scope and the operation listed.`) });
    }
    const scope = sourceScopeOpts(ctx);
    let ids = scope.sourceIds ?? (scope.sourceId ? [scope.sourceId] : null);
    let operations = auth?.allowedOperations ?? null;
    for (const grant of [verified.grant, row.grant_ceiling]) {
      if (!grant.sourceIds.includes('*')) ids = ids === null ? grant.sourceIds : intersect(ids, grant.sourceIds);
      if (grant.operations !== null) operations = operations === null ? grant.operations : intersect(operations, grant.operations);
    }
    const scopes = (auth?.scopes ?? verified.grant.scopes).filter(value =>
      hasScope(verified.grant.scopes, value) && hasScope(row.grant_ceiling.scopes, value));
    return { ...ctx, ...(ids === null ? {} : { sourceId: ids[0] ?? '__denied__' }), auth: {
      token: '', clientId: verified.principal.id, ...auth, scopes, allowedOperations: operations,
      ...(ids === null ? {} : { allowedSources: ids }),
    } };
  }
  if (!auth || !auth.principal || auth.grantProjectionDegraded || auth.fenceProjectionDegraded || !hasScope(auth.scopes, 'read') ||
    auth.allowedOperations != null && !auth.allowedOperations.includes(operation) || auth.effectiveSurface === 'verbs') {
    throw opError('permission_denied', 'The current grant does not permit shared skill discovery.',
      `${operation} needs read scope, the operation in this connection's allowed list and the full tool surface (not verbs). Ask the brain host's operator to review this connection's grant.`,
      { fix: grantFix(auth?.principal?.kind, `Shows each client's scopes and allowed operations; ${operation} needs read scope and the operation listed.`) });
  }
  let liveSources: string[];
  let liveScopes = auth.scopes;
  let liveOperations = auth.allowedOperations;
  let grantRevision = auth.grantRevision;
  if (auth.principal.kind === 'oauth_client') {
    const [row] = await ctx.engine.executeRaw<{ scope: string; source_id: string; federated_read: string[] | null; allowed_operations: string[] | null; grant_revision: number }>(
      'SELECT scope,source_id,federated_read,allowed_operations,grant_revision FROM oauth_clients WHERE client_id=$1 AND deleted_at IS NULL', [auth.principal.id]);
    if (!row || !hasScope(row.scope.split(/\s+/), 'read') || row.allowed_operations != null && !row.allowed_operations.includes(operation)) {
      throw opError('permission_denied', 'The shared skill reader grant was revoked or narrowed.',
        `Client ${auth.principal.id} was deleted or no longer allows ${operation}. Ask the brain host's operator to restore its grant, then reconnect.`,
        { fix: grantFix('oauth_client', `Shows whether client ${auth.principal.id} still exists and which operations it allows.`) });
    }
    liveSources = [...new Set([row.source_id, ...(row.federated_read ?? [])])].filter(Boolean);
    liveScopes = auth.scopes.filter(scope => hasScope(row.scope.split(/\s+/), scope));
    liveOperations = auth.allowedOperations == null ? row.allowed_operations : row.allowed_operations == null ? auth.allowedOperations : intersect(auth.allowedOperations, row.allowed_operations);
    grantRevision = row.grant_revision;
  } else {
    const [row] = await ctx.engine.executeRaw<Record<string, unknown>>(
      'SELECT * FROM access_tokens WHERE id=$1 AND revoked_at IS NULL', [auth.principal.id]);
    const tokenGrant = row ? grantFromTokenRow(row) : undefined;
    if (!tokenGrant || !hasScope(tokenGrant.scopes, 'read')) {
      throw opError('permission_denied', 'The shared skill reader token was revoked.',
        'This access token was revoked or lost read scope. Ask the brain host\'s operator for a current token, then reconnect with it.',
        { fix: grantFix('legacy_token', 'Shows the active tokens and clients with their scopes.') });
    }
    if (tokenGrant.permissionsMalformed) {
      throw opError('permission_denied', 'Invalid reader projection.',
        'This access token\'s stored permissions are malformed, so gbrain will not guess which sources it may read. Ask the brain host\'s operator to reissue the token.',
        { fix: grantFix('legacy_token', 'Shows the active tokens and clients so the operator can reissue this one.') });
    }
    const parsed = authSourcesFromGrant(tokenGrant);
    const currentOperations = tokenGrant.allowedOperations;
    if (currentOperations != null && !currentOperations.includes(operation)) {
      throw opError('permission_denied', 'The current legacy operation grant excludes this read.',
        `This access token's allowed operations exclude ${operation}. Ask the brain host's operator to allow it, or connect with a token that does.`,
        { fix: grantFix('legacy_token', `Shows each token's allowed operations; ${operation} must be listed.`) });
    }
    liveScopes = auth.scopes.filter(scope => hasScope(tokenGrant.scopes, scope));
    liveOperations = auth.allowedOperations == null ? currentOperations : currentOperations == null ? auth.allowedOperations : intersect(auth.allowedOperations, currentOperations);
    liveSources = parsed.allowedSources ?? [parsed.sourceId];
  }
  const scope = sourceScopeOpts(ctx);
  const allowed = intersect(scope.sourceIds ?? (scope.sourceId ? [scope.sourceId] : []), liveSources);
  return { ...ctx, sourceId: allowed[0] ?? '__denied__', auth: { ...auth, allowedSources: allowed, scopes: liveScopes, allowedOperations: liveOperations, grantRevision } };
}
export function assertSkillCapability(ctx: OperationContext, capability: 'skill_editor' | 'skill_publisher', operation: string): void {
  if (ctx.remote === false) return;
  const auth = ctx.auth;
  const local = currentVerifiedLocalWriter()?.grant;
  const scopes = auth?.scopes ?? local?.scopes ?? [];
  const operations = auth?.allowedOperations ?? local?.operations;
  if (auth?.grantProjectionDegraded || auth?.fenceProjectionDegraded || !scopes.includes(capability) ||
    !hasScope(scopes, capability === 'skill_publisher' ? 'admin' : 'write') || !operations?.includes(operation)) {
    throw scopeDeniedError({ op: operation, required: [capability, capability === 'skill_publisher' ? 'admin' : 'write'], auth,
      transport: ctx.transport === 'http' ? 'http' : 'stdio', legacy_error: 'permission_denied',
      message: `This operation requires explicit ${capability} authority and an operation grant.` });
  }
}
export async function assertStoredSkillCapability(engine: SqlEngine, authority: WriteAuthority, capability: 'skill_editor' | 'skill_publisher', lock = false): Promise<void> {
  if (!authority.remote && authority.principal.kind === 'local_cli') return;
  if (!authority.scopes.includes(capability)) {
    throw opError('permission_denied', `The accepted request lacks ${capability}.`,
      `This request was accepted without ${capability}, so it cannot publish. Ask the brain host's operator to grant ${capability} to this connection, then submit a new request.`,
      { fix: grantFix(authority.principal.kind, `Shows the grant of the principal that submitted the request; it needs ${capability}.`) });
  }
  const suffix = lock ? ' FOR SHARE' : '';
  let scopes: string[] = [];
  if (authority.principal.kind === 'oauth_client') {
    const [row] = await engine.executeRaw<{ scope: string }>(`SELECT scope FROM oauth_clients WHERE client_id=$1 AND deleted_at IS NULL${suffix}`, [authority.principal.id]);
    scopes = row?.scope?.split(/\s+/) ?? [];
  } else if (authority.principal.kind === 'legacy_token') {
    const [row] = await engine.executeRaw<{ scopes: unknown }>(`SELECT scopes FROM access_tokens WHERE id=$1 AND revoked_at IS NULL${suffix}`, [authority.principal.id]);
    scopes = normalizeTokenScopes(row?.scopes) ?? [];
  } else if (authority.principal.kind === 'local_stdio') {
    const [row] = await engine.executeRaw<{ grant_ceiling: { scopes: string[] } }>(`SELECT grant_ceiling FROM persistence_local_writers WHERE id=$1::uuid AND revoked_at IS NULL${suffix}`, [authority.principal.id]);
    scopes = row?.grant_ceiling?.scopes ?? [];
  }
  if (!scopes.includes(capability) || !hasScope(scopes, capability === 'skill_publisher' ? 'admin' : 'write')) {
    throw opError('permission_denied', `The current grant lacks ${capability} or its base scope.`,
      `The principal that submitted this request no longer holds ${capability} with ${capability === 'skill_publisher' ? 'admin' : 'write'} scope (it was revoked or narrowed). Ask the brain host's operator to restore the grant, then submit a new request.`,
      { fix: grantFix(authority.principal.kind, `Shows the submitting principal's current grant; it needs ${capability}.`) });
  }
}
export async function publicationEnabled(ctx: OperationContext): Promise<boolean> {
  const value = await ctx.engine.getConfig('mcp.publish_skills');
  return value == null ? ctx.config?.mcp?.publish_skills === true : value === 'true';
}
export function normalizePolicy(value: unknown): SharedSkillPolicy {
  const p = value as SharedSkillPolicy;
  const classes = stringList(p?.classes, 'classes');
  if (!p || p.version !== 1 || typeof p.enabled !== 'boolean' || typeof p.allow_follow !== 'boolean' ||
    classes.some(c => !['prose', 'reference', 'asset', 'script'].includes(c)) || p.enabled && !classes.includes('prose')) {
    throw opError('invalid_params', 'A version 1 publication policy with explicit consent is required.',
      'Pass policy as {"version": 1, "enabled": true or false, "allow_follow": true or false, "classes": a subset of prose, reference, asset and script (including prose when enabled), "audiences": [...], "requirements": [...]}.');
  }
  return { version: 1, enabled: p.enabled, allow_follow: p.allow_follow, classes: classes as SkillFileClass[],
    audiences: stringList(p.audiences, 'audiences'), requirements: stringList(p.requirements, 'requirements') };
}
export async function readSharedSkillPolicy(engine: SqlEngine, sourceId: string, incarnation: string, legacyEnabled: boolean, lock = false): Promise<{ epoch: string; policy: SharedSkillPolicy }> {
  const [row] = await engine.executeRaw<{ epoch: string; policy: SharedSkillPolicy }>(
    `SELECT epoch,policy FROM shared_skill_policies WHERE source_id=$1 AND source_incarnation=$2::uuid${lock ? ' FOR SHARE' : ''}`, [sourceId, incarnation]);
  if (row) return { epoch: row.epoch, policy: normalizePolicy(row.policy) };
  return legacySharedSkillPolicy(legacyEnabled);
}
export function legacySharedSkillPolicy(legacyEnabled: boolean): { epoch: string; policy: SharedSkillPolicy } {
  return { epoch: legacyEnabled ? 'legacy-prose' : 'consent-required', policy: { version: 1, enabled: legacyEnabled,
    classes: ['prose'], audiences: ['readers'], requirements: [], allow_follow: false } };
}
export function approvedFiles(files: StoredSkillFile[], policy: SharedSkillPolicy, principal: string): StoredSkillFile[] {
  if (!policy.enabled) return [];
  const audience = (value: string) => (value === 'readers' || value === principal) && policy.audiences.includes(value);
  return files.filter(f => policy.classes.includes(f.file_class) && f.audience.some(audience));
}
export async function setSharedSkillPolicy(ctx: OperationContext, sourceId: string, input: SharedSkillPolicy, expectedEpoch?: string | null): Promise<{ policy_epoch: string }> {
  assertSkillCapability(ctx, 'skill_publisher', 'set_skill_policy');
  const policy = normalizePolicy(input);
  const { submissionAuthority } = await import('../persistence/authority.ts');
  const { initializeLocalPersistence } = await import('../persistence/page-mutations.ts');
  await initializeLocalPersistence(ctx);
  return ctx.engine.transaction(async tx => {
    const [source] = await tx.executeRaw<{ incarnation: string; archived: boolean }>('SELECT incarnation,archived FROM sources WHERE id=$1 FOR UPDATE', [sourceId]);
    if (!source || source.archived) {
      throw opError('source_changed', 'Publication requires an active source.',
        `Source ${sourceId} is archived or not registered; approve a policy for an active source.`, { fix: SOURCES_FIX });
    }
    const authority = await submissionAuthority({ ...ctx, engine: tx }, 'set_skill_policy', sourceId, source.incarnation, 'skills');
    await assertStoredSkillCapability(tx, authority, 'skill_publisher', true);
    const existing = await readSharedSkillPolicy(tx, sourceId, source.incarnation, await publicationEnabled({ ...ctx, engine: tx }), true);
    if (!['legacy-prose', 'consent-required'].includes(existing.epoch) && expectedEpoch === undefined) {
      throw opError('revision_required', 'Review the current policy and supply its expected_policy_epoch before changing disclosure.',
        `Read source ${sourceId}'s current policy, review the change with the user, then pass its policy_epoch as expected_policy_epoch.`,
        { fix: policyFix(sourceId) });
    }
    if (expectedEpoch !== undefined && expectedEpoch !== existing.epoch && !(expectedEpoch === null && existing.epoch.startsWith('legacy-')) && !(expectedEpoch === null && existing.epoch === 'consent-required')) {
      throw opError('revision_conflict', 'Publication policy changed; review its current disclosure before approving.',
        `Source ${sourceId}'s policy changed since it was reviewed. Read it again, review the difference with the user, and pass the new policy_epoch.`,
        { fix: policyFix(sourceId) });
    }
    const epoch = randomUUID();
    await tx.executeRaw(`INSERT INTO shared_skill_policies(source_id,source_incarnation,epoch,policy) VALUES($1,$2::uuid,$3::uuid,$4::text::jsonb)
      ON CONFLICT(source_id,source_incarnation) DO UPDATE SET epoch=excluded.epoch,policy=excluded.policy,updated_at=now()`,
    [sourceId, source.incarnation, epoch, JSON.stringify(policy)]);
    await tx.executeRaw(`INSERT INTO shared_skill_policy_audit(source_id,source_incarnation,principal_kind,principal_id,previous_epoch,epoch,policy)
      VALUES($1,$2::uuid,$3,$4,$5,$6::uuid,$7::text::jsonb)`,
    [sourceId, source.incarnation, authority.principal.kind, authority.principal.id, existing.epoch, epoch, JSON.stringify(policy)]);
    return { policy_epoch: epoch };
  });
}

export async function getSharedSkillPolicy(ctx: OperationContext, sourceId: string) {
  assertSkillCapability(ctx, 'skill_publisher', 'get_skill_policy');
  const active = await authorizeSkillRead(ctx, 'get_skill_policy');
  const scope = sourceScopeOpts(active);
  if (scope.sourceIds ? !scope.sourceIds.includes(sourceId) : scope.sourceId && scope.sourceId !== sourceId) {
    throw opError('permission_denied', 'The publication policy source is outside this grant.',
      `This connection's grant does not cover source ${sourceId}. Read the policy of a granted source, or ask the brain host's operator to extend the grant.`,
      { fix: grantFix(ctx.auth?.principal?.kind ?? (ctx.remote === false ? 'local_cli' : undefined), `Shows this connection's granted sources; ${sourceId} must be among them.`) });
  }
  const [source] = await ctx.engine.executeRaw<{ incarnation: string }>('SELECT incarnation FROM sources WHERE id=$1 AND NOT archived', [sourceId]);
  if (!source) {
    throw opError('source_changed', 'The publication policy source is not active.',
      `Source ${sourceId} is archived or not registered.`, { fix: SOURCES_FIX });
  }
  if (ctx.remote !== false) {
    const { submissionAuthority } = await import('../persistence/authority.ts');
    const authority = await submissionAuthority(ctx, 'get_skill_policy', sourceId, source.incarnation, 'skills');
    await assertStoredSkillCapability(ctx.engine, authority, 'skill_publisher');
  }
  const enabled = await publicationEnabled(ctx);
  const current = await readSharedSkillPolicy(ctx.engine, sourceId, source.incarnation, enabled);
  return { schema_version: 2 as const, source_id: sourceId, source_incarnation: source.incarnation,
    publication_enabled: enabled, policy_epoch: current.epoch, policy: current.policy };
}