Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
9.1 KB
Raw Blame
/**
 * GST-363 follow-up (GBRA-108 ruling on Train A): the unscoped_multi_user_token
 * warning applies only to a brain that serves several people (access.serves,
 * src/core/access/serves.ts). On a one-person brain every credential reads that
 * person's own pages, so the doctor check is not applicable and the install
 * routes stay silent, including a bot harness on the owner's brain (R94). On a
 * brain that serves several people the fix leads with binding the credential
 * to a member; a source rescope is named only as a narrowing that leaves the
 * token unbound. Repo-less PGLite brains throughout.
 */
import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
import { chmodSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { insertUnifiedToken } from '../src/core/token-mint.ts';
import { sharedTokenNotice } from '../src/core/grants/shared-exposure.ts';
import { unscopedMultiUserTokenEntry } from '../src/commands/doctor/checks/unscoped-multi-user-token.ts';
import { __resetPrivateVisibilityCacheForTests } from '../src/core/search/private-visibility.ts';
import { withEnv } from './helpers/with-env.ts';
import { runCli } from './helpers/cli-spawn.ts';
import type { DoctorContext } from '../src/commands/doctor/context.ts';

const CODE = 'unscoped_multi_user_token';
let engine: PGLiteEngine;
const roots: string[] = [];
const tmp = () => { const d = mkdtempSync(join(tmpdir(), 'gbrain-exposure-serves-')); roots.push(d); return d; };

beforeAll(async () => {
  engine = new PGLiteEngine();
  await engine.connect({});
  await engine.initSchema();
}, 60_000);
afterAll(async () => { if (engine) await engine.disconnect(); for (const r of roots) rmSync(r, { recursive: true, force: true }); }, 60_000);

async function brainWithTwoChannels(serves: 'one' | 'several' | null) {
  await engine.executeRaw('DELETE FROM pages');
  await engine.executeRaw('DELETE FROM access_tokens');
  await engine.executeRaw('DELETE FROM access_members');
  if (serves) await engine.setConfig('access.serves', serves); else await engine.executeRaw("DELETE FROM config WHERE key = 'access.serves'");
  await engine.setConfig('search.remote_private_pages', 'hidden');
  __resetPrivateVisibilityCacheForTests();
  for (const [slug, title] of [['chats/a', '#alpha, Jul 2'], ['chats/b', '#beta, Jul 2']]) {
    await engine.putPage(slug!, { type: 'slack' as any, title: title!, compiled_truth: 'hello', frontmatter: {} });
  }
  await insertUnifiedToken(engine, { name: 'team-bot', tokenHash: 'hash-team-bot', grant: { sources: { kind: 'default' }, takesHolders: ['world'], allowedOperations: null } });
}
const doctor = async (home = tmp()) => withEnv({ GBRAIN_HOME: home, HOME: home, CLAUDE_CONFIG_DIR: join(home, '.claude') }, async () =>
  (await unscopedMultiUserTokenEntry.run({ engine, args: [] } as unknown as DoctorContext) as any[])[0]);
const census = { sources: ['default'], chat_pages: 2, channels: 2, chat_sources: ['default'] };
const across = { sources: ['a', 'b'], chat_pages: 2, channels: 2, chat_sources: ['a', 'b'] };

describe('one-person brain', () => {
  test('doctor: not applicable when the member count says one person', async () => {
    await brainWithTwoChannels(null);
    await engine.executeRaw("INSERT INTO access_members (id) VALUES ('owner-example')");
    const check = await doctor();
    expect(check).toMatchObject({ name: CODE, status: 'ok', readiness_state: 'not_applicable' });
    expect(check.message).toContain('serves one person');
    expect(check.fix).toBeUndefined();
  });

  test('doctor: not applicable when access.serves is one, even with a wired bot harness (R94)', async () => {
    await brainWithTwoChannels('one');
    await engine.executeRaw("INSERT INTO access_members (id) VALUES ('owner-example'), ('bob-example')");
    const home = tmp();
    mkdirSync(join(home, '.gbrain'), { recursive: true });
    writeFileSync(join(home, '.gbrain', 'agent-instructions.json'), JSON.stringify({ entries: [{ harness: 'openclaw', path: join(home, 'SOUL.md'), status: 'installed', block_version: 1, access: { kind: 'mcp', server: 'gbrain' }, writer: 'gbrain setup openclaw' }] }));
    const check = await doctor(home);
    expect(check).toMatchObject({ status: 'ok', readiness_state: 'not_applicable' });
    expect(check.message).toContain('config access.serves is one');
  });

  test('the notice is silent for every subject when the brain serves one person', () => {
    expect(sharedTokenNotice({ kind: 'legacy_token', name: 'team-bot' }, { census, serves: 'one' })).toBeNull();
    expect(sharedTokenNotice({ kind: 'oauth_client', id: 'c1' }, { census, serves: 'one' })).toBeNull();
    expect(sharedTokenNotice({ kind: 'stdio', harness: 'openclaw' }, { harness: 'openclaw', serves: 'one' })).toBeNull();
  });
});

describe('brain that serves several people', () => {
  test('doctor warns and its fix binds the credential to a member', async () => {
    await brainWithTwoChannels('several');
    const check = await doctor();
    expect(check.status).toBe('warn');
    expect(check.fix).toMatchObject({ ask_user: true, argv: ['gbrain', 'auth', 'rescope', '--token', 'team-bot', '--member', '<member>'] });
  });

  test('the fix text leads with binding and names a source rescope only as an unbound narrowing', () => {
    for (const c of [census, across]) {
      const n = sharedTokenNotice({ kind: 'legacy_token', name: 'team-bot' }, { census: c, serves: 'several' })!;
      const fix = n.why.slice(n.why.indexOf('Fix: '));
      expect(fix.startsWith('Fix: bind the credential to the person who uses this agent (gbrain auth rescope --token team-bot --member <id>)')).toBe(true);
      expect(fix).toContain('gbrain auth rescope --token team-bot --may-act-for <members>');
      expect(fix.indexOf('--member <id>')).toBeLessThan(fix.indexOf('--may-act-for'));
      if (c === across) {
        expect(fix).toContain('narrowing only, which leaves the token unbound: gbrain auth rescope --token team-bot --sources <source>');
        expect(fix.indexOf('--may-act-for')).toBeLessThan(fix.indexOf('--sources'));
      } else {
        expect(fix).not.toContain('--sources');
      }
      expect(n.fix!.argv).toEqual(['gbrain', 'auth', 'rescope', '--token', 'team-bot', '--member', '<member>']);
    }
    const client = sharedTokenNotice({ kind: 'oauth_client', id: 'c1' }, { census, serves: 'several' })!;
    expect(client.fix!.argv).toEqual(['gbrain', 'auth', 'rescope', '--client', 'c1', '--member', '<member>']);
    const bot = sharedTokenNotice({ kind: 'stdio', harness: 'openclaw' }, { harness: 'openclaw', serves: 'several' })!;
    expect(bot.why).toContain('Fix: label each person and bind this harness\'s server (gbrain setup openclaw --serves several --members <id,...>');
  });
});

describe('install routes on a one-person brain', () => {
  const page = (title: string) => '---\ntitle: "' + title + '"\ntype: slack\n---\nhello\n';
  function box() {
    const root = tmp();
    const home = join(root, 'home');
    mkdirSync(home, { recursive: true });
    const env = { HOME: home, GBRAIN_HOME: home, CLAUDE_CONFIG_DIR: join(home, '.claude'), HERMES_HOME: undefined, OPENCLAW_STATE_DIR: undefined,
      OPENCLAW_WORKSPACE_DIR: undefined, OPENCLAW_PROFILE: undefined, GBRAIN_SOURCE: undefined, GBRAIN_AGENT_INSTRUCTIONS: undefined };
    const bin = join(root, 'gbrain');
    writeFileSync(bin, '#!/bin/sh\nexec \'' + process.execPath + '\' \'' + join(import.meta.dir, '..', 'src', 'cli.ts') + '\' "$@"\n');
    chmodSync(bin, 0o755);
    return { root, home, env, bin };
  }

  test('auth create and setup openclaw (a bot harness on the owner brain, R94) stay silent', async () => {
    const b = box();
    expect((await runCli(['init', '--pglite', '--no-embedding', '--non-interactive'], { env: b.env, cwd: b.root, timeoutMs: 120_000 })).exitCode).toBe(0);
    for (const [i, title] of ['#alpha-team, Jul 2', '#beta-team, Jul 3'].entries()) {
      const file = join(b.root, 'p' + i + '.md');
      writeFileSync(file, page(title));
      const put = Bun.spawnSync(['sh', '-c', '\'' + b.bin + '\' put chats/p' + i + ' < \'' + file + '\''], { env: Object.fromEntries(Object.entries({ ...process.env, ...b.env }).filter(([, v]) => v !== undefined)) as Record<string, string> });
      expect(put.exitCode).toBe(0);
    }
    const token = await runCli(['auth', 'create', 'owner-bot'], { env: b.env, cwd: b.root });
    expect(token.stdout).toMatch(/gbrain_[0-9a-f]+/);
    expect(token.stderr).not.toContain(CODE);
    const ws = join(b.home, '.openclaw', 'workspace');
    mkdirSync(ws, { recursive: true });
    const setup = JSON.parse((await runCli(['setup', 'openclaw', '--workspace', ws, '--gbrain-bin', b.bin, '--dry-run', '--json'], { env: b.env, cwd: b.root })).stdout);
    expect((setup.notices ?? []).map((n: any) => n.code)).not.toContain(CODE);
    const several = await runCli(['config', 'set', 'access.serves', 'several'], { env: b.env, cwd: b.root });
    expect(several.exitCode).toBe(0);
    expect((await runCli(['auth', 'create', 'shared-bot', '--reads-unscoped', '--yes'], { env: b.env, cwd: b.root })).stderr).toContain(CODE);
  }, 240_000);
});