Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
9.2 KB
Raw Blame
/**
 * GST-2484: the owner exemption covers privacy, never member access, on every read path.
 *
 * 1. Protects: a credential bound to the brain owner (gbrain access owner set) reads a member-restricted page (one that
 *    names readers with readable_by, or sits under a folder rule) only when its readers list the owner, on every read
 *    path: get_page, list_pages, search (hybrid and keyword, fields: full), query and recall. That is the boundary
 *    docs/guides/access-designations.md documents for a shared brain. visibility: private stays readable by the owner.
 *    Each member keeps reading its own pages and the unlabelled one, and nothing else.
 * 2. Fails when: any read path returns another member's page to the owner, hides a page whose readers list the owner,
 *    or changes what a member reads.
 * 3. Real seams: tokens minted by the token service and verified by the serve --http verifier, dispatched through MCP
 *    dispatch (remote: true, transport http), a folder rule through the access policy, on a repo-less brain (no
 *    checkout); embeddings stubbed. PGLite, and Postgres with DATABASE_URL.
 */
import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
import type { BrainEngine } from '../src/core/engine.ts';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { importFromContent } from '../src/core/import-file.ts';
import { configureGateway, resetGateway, __setEmbedTransportForTests } from '../src/core/ai/gateway.ts';
import { GBrainOAuthProvider } from '../src/core/oauth-provider.ts';
import { sqlQueryForEngine } from '../src/core/sql-query.ts';
import { mintLegacyToken } from '../src/core/token-mint.ts';
import { noGrantFederatedScope } from '../src/core/source-resolver.ts';
import { dispatchToolCall } from '../src/mcp/dispatch.ts';
import { __resetPrivateVisibilityCacheForTests } from '../src/core/search/private-visibility.ts';
import { setOwner } from '../src/core/access/owner.ts';
import { bindCredential } from '../src/core/access/members.ts';
import { proposeRevision } from '../src/core/access/policy.ts';
import type { AuthInfo } from '../src/core/ops/contract.ts';
import { testBackends } from './helpers/test-backends.ts';
import { isolatedPersistencePostgres } from './helpers/persistence-postgres.ts';

const DIMS = 1536;
function vectorFor(text: string): number[] {
  const v = new Array<number>(DIMS).fill(0);
  for (const w of text.toLowerCase().match(/[a-z]+/g) ?? []) {
    let h = 0;
    for (const ch of w) h = (h * 31 + ch.charCodeAt(0)) >>> 0;
    v[h % DIMS] += 1;
  }
  const n = Math.hypot(...v) || 1;
  return v.map(x => x / n);
}

const SRC = 'boundary-src';
const OWNER = 'owner-example';
const PAGES = {
  open: { slug: 'notes/open-example', canary: 'canarybndopen', fm: [] as string[] },
  private: { slug: 'notes/private-example', canary: 'canarybndprivate', fm: ['visibility: private'] },
  assistants: { slug: 'notes/assistants-example', canary: 'canarybndassist', fm: ['readable_by: [assistants-example]'] },
  shared: { slug: 'notes/shared-example', canary: 'canarybndshared', fm: [`readable_by: [assistants-example, ${OWNER}]`] },
  household: { slug: 'household/budget-example', canary: 'canarybndhouse', fm: [] as string[] },
  family: { slug: 'family/plan-example', canary: 'canarybndfamily', fm: [] as string[] },
} as const;
type PageKey = keyof typeof PAGES;
const KEYS = Object.keys(PAGES) as PageKey[];
const pageText = (title: string, canary: string, fm: readonly string[]) =>
  ['---', 'type: note', `title: ${title}`, ...fm, '---', `# ${title}`, '', `Harbor ledger planning notes ${canary} for the roadmap.`].join('\n');

/** Every read path, each with arguments every page answers. */
const READS: Array<[string, string, (slug: string) => Record<string, unknown>]> = [
  ['get_page', 'get_page', slug => ({ slug })],
  ['list_pages', 'list_pages', () => ({ limit: 100 })],
  ['search', 'search', () => ({ query: 'harbor ledger planning notes', fields: 'full', limit: 50 })],
  ['search keyword', 'search', () => ({ query: 'planning notes', match: 'keyword', fields: 'full', limit: 50 })],
  ['query', 'query', () => ({ query: 'harbor ledger planning notes', expand: false, fields: 'full', limit: 50 })],
  ['recall', 'recall', () => ({ query: 'harbor ledger planning notes' })],
];
/** What each caller must read on every path: list_pages names slugs, the others return the body. */
const EXPECTED: Record<string, PageKey[]> = {
  owner: ['open', 'private', 'shared', 'family'],
  assistants: ['open', 'assistants', 'shared'],
  household: ['open', 'household', 'family'],
};

for (const kind of testBackends()) {
  describe(`owner and member access (${kind}, repo-less)`, () => {
    let engine: BrainEngine;
    let close: () => Promise<void>;
    const tokens: Record<string, string> = {};
    const provider = () => new GBrainOAuthProvider({ sql: sqlQueryForEngine(engine), transaction: fn => engine.transaction(tx => fn(sqlQueryForEngine(tx))) });

    async function call(who: string, op: string, params: Record<string, unknown>): Promise<string> {
      const auth = await provider().verifyAccessToken(tokens[who]!) as unknown as AuthInfo;
      const sourceId = auth.sourceId ?? 'default';
      const localFederated = await noGrantFederatedScope(engine, auth.hasSourceGrant, sourceId);
      const out = await dispatchToolCall(engine, op, { ...params }, {
        remote: true, transport: 'http', auth, sourceId, takesHoldersAllowList: auth.takesHoldersAllowList ?? ['world'],
        ...(localFederated ? { localFederatedSourceIds: localFederated } : {}),
      });
      return out.content.map(c => c.text).join('\n');
    }

    /** The pages `who` reads on each path. */
    async function seenBy(who: string): Promise<Record<string, PageKey[]>> {
      const out: Record<string, PageKey[]> = {};
      for (const [label, op, params] of READS) {
        const seen = new Set<PageKey>();
        if (op === 'get_page') {
          for (const key of KEYS) if ((await call(who, op, params(PAGES[key].slug))).includes(PAGES[key].canary)) seen.add(key);
        } else {
          const text = await call(who, op, params(''));
          for (const key of KEYS) if (text.includes(op === 'list_pages' ? PAGES[key].slug : PAGES[key].canary)) seen.add(key);
        }
        out[label] = KEYS.filter(key => seen.has(key));
      }
      return out;
    }
    const everywhere = (keys: PageKey[]) => Object.fromEntries(READS.map(([label]) => [label, KEYS.filter(key => keys.includes(key))]));

    beforeAll(async () => {
      configureGateway({ embedding_model: 'openai:text-embedding-3-small', embedding_dimensions: DIMS, env: { OPENAI_API_KEY: 'test' } });
      __setEmbedTransportForTests((async ({ values }: { values: string[] }) => ({ embeddings: values.map(vectorFor) })) as never);
      if (kind === 'postgres') ({ engine, close } = await isolatedPersistencePostgres(process.env.DATABASE_URL!));
      else { engine = new PGLiteEngine(); await engine.connect({ engine: 'pglite' } as never); await engine.initSchema(); close = () => engine.disconnect(); }
      __resetPrivateVisibilityCacheForTests();
      await engine.executeRaw('INSERT INTO sources (id, name) VALUES ($1, $1) ON CONFLICT (id) DO NOTHING', [SRC]);
      for (const key of KEYS) await importFromContent(engine, PAGES[key].slug, pageText(`${key} plan`, PAGES[key].canary, PAGES[key].fm), { sourceId: SRC });
      for (const id of [OWNER, 'assistants-example', 'household-example']) await engine.executeRaw('INSERT INTO access_members (id) VALUES ($1)', [id]);
      await proposeRevision(engine, SRC, [
        { id: 'household', prefix: 'household/', readable_by: ['member:household-example'] },
        { id: 'family', prefix: 'family/', readable_by: ['member:household-example', `member:${OWNER}`] },
      ], { origin: 'cli', store: 'database' });
      for (const [name, member] of [['owner', OWNER], ['assistants', 'assistants-example'], ['household', 'household-example']] as const) {
        const minted = await mintLegacyToken(engine, { name, scopes: ['read'], takesHolders: ['world'], sourceGrant: [SRC] });
        tokens[name] = minted.token;
        await bindCredential(engine, { kind: 'token', id: minted.id }, { member });
      }
      await setOwner(engine, OWNER);
    }, 240_000);

    afterAll(async () => {
      __setEmbedTransportForTests(null);
      resetGateway();
      await close?.();
    }, 60_000);

    test('fixture control: a trusted local caller reads every page', async () => {
      for (const key of KEYS) {
        const out = await dispatchToolCall(engine, 'get_page', { slug: PAGES[key].slug }, { remote: false, sourceId: SRC });
        expect({ key, seen: out.content.map(c => c.text).join('\n').includes(PAGES[key].canary) }).toEqual({ key, seen: true });
      }
    });

    test('the owner reads private pages and pages whose readers list it, and no other member\'s page, on every read path', async () => {
      expect(await seenBy('owner')).toEqual(everywhere(EXPECTED.owner!));
    }, 240_000);

    test('each member reads its own pages and the unlabelled one, and nothing else, on every read path', async () => {
      expect(await seenBy('assistants')).toEqual(everywhere(EXPECTED.assistants!));
      expect(await seenBy('household')).toEqual(everywhere(EXPECTED.household!));
    }, 240_000);
  });
}