Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
19.3 KB
Raw Blame
/**
 * #4352 — page-level `visibility: private` enforcement for untrusted callers.
 *
 * Pages have persisted `frontmatter.visibility` forever, but no read path
 * enforced it: a remote/MCP caller could pull a private page through search,
 * recall's query arm, entity cards, and context_pack. Pins:
 *   - buildVisibilityClause emits the predicate only when excludePrivate
 *   - engines (PGLite here; SQL identical in postgres-engine — parity pinned
 *     by the shared buildVisibilityClause builder) filter private pages on
 *     searchKeyword / searchTitles / searchKeywordChunks when the flag is set
 *   - resolveExcludePrivatePages: trust rules + config gate + env hatch
 *   - recall (query arm) as a remote ctx hides private pages; local sees them
 *   - buildEntityCard (entity/context_pack/delta) hides private cards remotely
 */

import { describe, test, expect, beforeAll, afterAll } from 'bun:test';
import { readFileSync } from 'node:fs';
import { join } from 'node:path';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { buildVisibilityClause } from '../src/core/search/sql-ranking.ts';
import {
  resolveExcludePrivatePages,
  __resetPrivateVisibilityCacheForTests,
  REMOTE_PRIVATE_PAGES_KEY,
} from '../src/core/search/private-visibility.ts';
import { buildEntityCard } from '../src/core/verbs/entity-card.ts';
import { operationsByName } from '../src/core/operations.ts';
import { withEnv } from './helpers/with-env.ts';
import { importFromContent } from '../src/core/import-file.ts';
import { serializeMarkdown } from '../src/core/markdown.ts';

let engine: PGLiteEngine;

beforeAll(async () => {
  engine = new PGLiteEngine();
  await engine.connect({});
  await engine.initSchema();
  // Real imports certify current chunks; these tests exercise page visibility,
  // independently of the separate block on old, unrebuilt chunk indexes.
  for (const [slug, title, body, frontmatter] of [
    ['notes/world-page', 'Zebra Widget World', 'zebra widget public knowledge body', { visibility: 'world' }],
    ['notes/private-page', 'Zebra Widget Private', 'zebra widget secret private knowledge body', { visibility: 'private' }],
    // No visibility key at all → defaults to world (visible everywhere).
    ['notes/unmarked-page', 'Zebra Widget Unmarked', 'zebra widget unmarked knowledge body', {}],
  ] as const) {
    const result = await importFromContent(engine, slug,
      serializeMarkdown(frontmatter, body, '', { type: 'concept', title, tags: [] }),
      { noEmbed: true, forceRechunk: true });
    expect(result.status).toBe('imported');
  }
});

afterAll(async () => {
  await engine.disconnect();
});

describe('buildVisibilityClause (#4352)', () => {
  test('default: no private predicate (pre-fix SQL preserved byte-for-byte)', () => {
    const clause = buildVisibilityClause('p', 's');
    expect(clause).not.toContain('visibility');
    expect(clause).toContain('p.deleted_at IS NULL');
  });

  test('excludePrivate: adds the COALESCE predicate', () => {
    const clause = buildVisibilityClause('p', 's', { excludePrivate: true });
    expect(clause).toContain(`COALESCE(p.frontmatter->>'visibility', CASE WHEN (p.type IN ('atom', 'question') OR (p.type = 'concept' AND p.frontmatter->>'synthesized_by' IS NOT NULL)) THEN 'private' ELSE 'world' END) <> 'private'`);
  });
});

describe('engine search paths honor excludePrivate (#4352)', () => {
  for (const method of ['searchKeyword', 'searchTitles', 'searchKeywordChunks'] as const) {
    test(`${method}: private page hidden with flag, visible without`, async () => {
      const withFlag = await engine[method]('zebra widget', { limit: 20, excludePrivate: true });
      const withoutFlag = await engine[method]('zebra widget', { limit: 20 });
      const slugsWith = withFlag.map((r) => r.slug);
      const slugsWithout = withoutFlag.map((r) => r.slug);
      expect(slugsWith).not.toContain('notes/private-page');
      expect(slugsWith).toContain('notes/world-page');
      // Absent visibility defaults to world — still visible under the flag.
      expect(slugsWith).toContain('notes/unmarked-page');
      // Trusted path unchanged: private page still retrievable.
      expect(slugsWithout).toContain('notes/private-page');
    });
  }
});

describe('resolveExcludePrivatePages gate (#4352)', () => {
  test('trusted local (remote === false) never excludes', async () => {
    __resetPrivateVisibilityCacheForTests();
    expect(await resolveExcludePrivatePages(engine, false)).toBe(false);
  });

  test('remote/undefined excludes by default (fail-closed)', async () => {
    __resetPrivateVisibilityCacheForTests();
    expect(await resolveExcludePrivatePages(engine, true)).toBe(true);
    expect(await resolveExcludePrivatePages(engine, undefined)).toBe(true);
  });

  test('config opt-out disables enforcement', async () => {
    await engine.setConfig(REMOTE_PRIVATE_PAGES_KEY, 'visible');
    __resetPrivateVisibilityCacheForTests();
    expect(await resolveExcludePrivatePages(engine, true)).toBe(false);
    await engine.setConfig(REMOTE_PRIVATE_PAGES_KEY, '');
    __resetPrivateVisibilityCacheForTests();
    expect(await resolveExcludePrivatePages(engine, true)).toBe(true);
  });

  test('GBRAIN_REMOTE_PRIVATE_PAGES=1 env escape hatch disables enforcement', async () => {
    __resetPrivateVisibilityCacheForTests();
    await withEnv({ GBRAIN_REMOTE_PRIVATE_PAGES: '1' }, async () => {
      expect(await resolveExcludePrivatePages(engine, true)).toBe(false);
    });
  });
});

describe('recall query arm (#4352)', () => {
  function mkCtx(remote: boolean) {
    return {
      engine,
      config: { engine: 'pglite' },
      logger: { info() {}, warn() {}, error() {} },
      dryRun: false,
      remote,
      sourceId: 'default',
    } as never;
  }

  test('remote recall with query hides private pages; local sees them', async () => {
    __resetPrivateVisibilityCacheForTests();
    const op = operationsByName['recall'];
    // Test env strips provider keys → keyword-only search arm.
    const remoteOut = (await op.handler(mkCtx(true), { query: 'zebra widget' })) as {
      results: Array<{ slug: string }>;
    };
    const remoteSlugs = (remoteOut.results ?? []).map((r) => r.slug);
    expect(remoteSlugs).not.toContain('notes/private-page');
    expect(remoteSlugs).toContain('notes/world-page');

    const localOut = (await op.handler(mkCtx(false), { query: 'zebra widget' })) as {
      results: Array<{ slug: string }>;
    };
    const localSlugs = (localOut.results ?? []).map((r) => r.slug);
    expect(localSlugs).toContain('notes/private-page');
  });
});

describe('entity card (#4352 — covers entity/context_pack/delta)', () => {
  test('remote card lookup cannot resolve a private page', async () => {
    __resetPrivateVisibilityCacheForTests();
    const remoteRes = await buildEntityCard(engine, 'default', 'Zebra Widget Private', { remote: true });
    expect(remoteRes.found ? remoteRes.card?.entity.slug : null).not.toBe('notes/private-page');

    const localRes = await buildEntityCard(engine, 'default', 'Zebra Widget Private', { remote: false });
    expect(localRes.found).toBe(true);
    expect(localRes.card?.entity.slug).toBe('notes/private-page');
  });
});

describe('page read ops (#4352 remediation — list_pages / get_page / fetch)', () => {
  function mkCtx(remote: boolean) {
    return {
      engine,
      config: { engine: 'pglite' },
      logger: { info() {}, warn() {}, error() {} },
      dryRun: false,
      remote,
      sourceId: 'default',
    } as never;
  }

  test('list_pages: remote listing omits private pages; local enumerates them', async () => {
    __resetPrivateVisibilityCacheForTests();
    const op = operationsByName['list_pages'];
    const remoteRows = (await op.handler(mkCtx(true), { limit: 100 })) as Array<{ slug: string }>;
    const remoteSlugs = remoteRows.map((r) => r.slug);
    expect(remoteSlugs).not.toContain('notes/private-page');
    expect(remoteSlugs).toContain('notes/world-page');
    // Absent visibility defaults to world — still listed remotely.
    expect(remoteSlugs).toContain('notes/unmarked-page');

    const localRows = (await op.handler(mkCtx(false), { limit: 100 })) as Array<{ slug: string }>;
    expect(localRows.map((r) => r.slug)).toContain('notes/private-page');
  });

  test('get_page: remote read of a private page is page_not_found; local reads the body', async () => {
    __resetPrivateVisibilityCacheForTests();
    const op = operationsByName['get_page'];
    await expect(op.handler(mkCtx(true), { slug: 'notes/private-page' })).rejects.toThrow(/Page not found/);
    // No over-blocking: world pages stay readable remotely.
    const world = (await op.handler(mkCtx(true), { slug: 'notes/world-page' })) as { slug: string };
    expect(world.slug).toBe('notes/world-page');

    const local = (await op.handler(mkCtx(false), { slug: 'notes/private-page' })) as { compiled_truth: string };
    expect(local.compiled_truth).toContain('secret');
  });

  test('get_page fuzzy: remote fuzzy resolution cannot surface a private page; local can', async () => {
    __resetPrivateVisibilityCacheForTests();
    const op = operationsByName['get_page'];
    await expect(
      op.handler(mkCtx(true), { slug: 'notes/private-pag', fuzzy: true }),
    ).rejects.toThrow(/Page not found/);

    const local = (await op.handler(mkCtx(false), { slug: 'notes/private-pag', fuzzy: true })) as { slug: string };
    expect(local.slug).toBe('notes/private-page');
  });

  test('fetch: remote fetch of a private page is page_not_found; local returns full text', async () => {
    __resetPrivateVisibilityCacheForTests();
    const op = operationsByName['fetch'];
    await expect(op.handler(mkCtx(true), { id: 'notes/private-page' })).rejects.toThrow(/Page not found/);

    const local = (await op.handler(mkCtx(false), { id: 'notes/private-page' })) as { text: string };
    expect(local.text).toContain('secret');
  });

  test('config opt-out restores remote reads on all three ops', async () => {
    await engine.setConfig(REMOTE_PRIVATE_PAGES_KEY, 'visible');
    __resetPrivateVisibilityCacheForTests();
    try {
      const got = (await operationsByName['get_page'].handler(mkCtx(true), { slug: 'notes/private-page' })) as { slug: string };
      expect(got.slug).toBe('notes/private-page');
      const rows = (await operationsByName['list_pages'].handler(mkCtx(true), { limit: 100 })) as Array<{ slug: string }>;
      expect(rows.map((r) => r.slug)).toContain('notes/private-page');
      const fetched = (await operationsByName['fetch'].handler(mkCtx(true), { id: 'notes/private-page' })) as { id: string };
      expect(fetched.id).toBe('notes/private-page');
    } finally {
      await engine.setConfig(REMOTE_PRIVATE_PAGES_KEY, '');
      __resetPrivateVisibilityCacheForTests();
    }
  });
});

describe('sibling read ops (#4352 remediation — no bypass around get_page)', () => {
  function mkCtx(remote: boolean) {
    return {
      engine,
      config: { engine: 'pglite' },
      logger: { info() {}, warn() {}, error() {} },
      dryRun: false,
      remote,
      sourceId: 'default',
    } as never;
  }

  beforeAll(async () => {
    // Edges in both directions so get_links / get_backlinks / traverse_graph
    // each have a private endpoint to leak.
    await engine.addLink('notes/world-page', 'notes/private-page', 'seen with', 'related_to');
    await engine.addLink('notes/private-page', 'notes/world-page', 'refers to', 'related_to');
    await engine.addLink('notes/world-page', 'notes/unmarked-page', 'also', 'related_to');
    await engine.addTimelineEntry('notes/private-page', {
      date: '2026-08-01', source: 'test', summary: 'secret meeting happened',
    });
    await engine.createVersion('notes/private-page');
    await engine.putRawData('notes/private-page', 'crustdata', { secret: true });
  });

  test('get_chunks: private page reads as missing ([]) remotely; local + world unaffected', async () => {
    __resetPrivateVisibilityCacheForTests();
    const op = operationsByName['get_chunks'];
    expect((await op.handler(mkCtx(true), { slug: 'notes/private-page' })) as unknown[]).toEqual([]);
    expect(((await op.handler(mkCtx(true), { slug: 'notes/world-page' })) as unknown[]).length).toBeGreaterThan(0);
    expect(((await op.handler(mkCtx(false), { slug: 'notes/private-page' })) as unknown[]).length).toBeGreaterThan(0);
  });

  test('get_versions: private page history reads as missing ([]) remotely; local sees it', async () => {
    __resetPrivateVisibilityCacheForTests();
    const op = operationsByName['get_versions'];
    expect((await op.handler(mkCtx(true), { slug: 'notes/private-page' })) as unknown[]).toEqual([]);
    expect(((await op.handler(mkCtx(false), { slug: 'notes/private-page' })) as unknown[]).length).toBeGreaterThan(0);
  });

  test('get_timeline: private page timeline reads as missing ([]) remotely; local sees it', async () => {
    __resetPrivateVisibilityCacheForTests();
    const op = operationsByName['get_timeline'];
    expect((await op.handler(mkCtx(true), { slug: 'notes/private-page' })) as unknown[]).toEqual([]);
    const local = (await op.handler(mkCtx(false), { slug: 'notes/private-page' })) as Array<{ summary: string }>;
    expect(local.map((e) => e.summary)).toContain('secret meeting happened');
  });

  test('get_raw_data: private page raw data reads as missing ([]) remotely; local sees it', async () => {
    __resetPrivateVisibilityCacheForTests();
    const op = operationsByName['get_raw_data'];
    expect((await op.handler(mkCtx(true), { slug: 'notes/private-page' })) as unknown[]).toEqual([]);
    expect(((await op.handler(mkCtx(false), { slug: 'notes/private-page' })) as unknown[]).length).toBeGreaterThan(0);
  });

  test('resolve_slugs: remote resolution never returns a private slug; local does', async () => {
    __resetPrivateVisibilityCacheForTests();
    const op = operationsByName['resolve_slugs'];
    // Exact-slug arm: the strongest oracle — must read as no-match remotely.
    expect((await op.handler(mkCtx(true), { partial: 'notes/private-page' })) as string[]).toEqual([]);
    expect((await op.handler(mkCtx(false), { partial: 'notes/private-page' })) as string[]).toEqual(['notes/private-page']);
    // Fuzzy arm: private slugs must not be enumerable via trigram candidates.
    const fuzzy = (await op.handler(mkCtx(true), { partial: 'Zebra Widget' })) as string[];
    expect(fuzzy).not.toContain('notes/private-page');
    expect(fuzzy).toContain('notes/world-page');
  });

  test('get_links: edges to a private endpoint are dropped remotely; a private page reads as missing', async () => {
    __resetPrivateVisibilityCacheForTests();
    const op = operationsByName['get_links'];
    const remote = (await op.handler(mkCtx(true), { slug: 'notes/world-page' })) as Array<{ to_slug: string }>;
    expect(remote.map((l) => l.to_slug)).not.toContain('notes/private-page');
    expect(remote.map((l) => l.to_slug)).toContain('notes/unmarked-page');
    expect((await op.handler(mkCtx(true), { slug: 'notes/private-page' })) as unknown[]).toEqual([]);
    const local = (await op.handler(mkCtx(false), { slug: 'notes/world-page' })) as Array<{ to_slug: string }>;
    expect(local.map((l) => l.to_slug)).toContain('notes/private-page');
  });

  test('get_backlinks: edges from a private page are dropped remotely; world backlinks survive', async () => {
    __resetPrivateVisibilityCacheForTests();
    const op = operationsByName['get_backlinks'];
    const remote = (await op.handler(mkCtx(true), { slug: 'notes/world-page' })) as Array<{ from_slug: string }>;
    expect(remote.map((l) => l.from_slug)).not.toContain('notes/private-page');
    const unmarked = (await op.handler(mkCtx(true), { slug: 'notes/unmarked-page' })) as Array<{ from_slug: string }>;
    expect(unmarked.map((l) => l.from_slug)).toContain('notes/world-page');
    const local = (await op.handler(mkCtx(false), { slug: 'notes/world-page' })) as Array<{ from_slug: string }>;
    expect(local.map((l) => l.from_slug)).toContain('notes/private-page');
  });

  test('traverse_graph (remote default path shape, #4666): private nodes + edges to them are stripped remotely', async () => {
    __resetPrivateVisibilityCacheForTests();
    const op = operationsByName['traverse_graph'];
    // Remote no-filter callers now default to direction=both GraphPath[].
    const remote = (await op.handler(mkCtx(true), { slug: 'notes/world-page' })) as Array<{
      from_slug: string; to_slug: string;
    }>;
    const touched = remote.flatMap((e) => [e.from_slug, e.to_slug]);
    expect(touched).not.toContain('notes/private-page');
    expect(touched).toContain('notes/unmarked-page');
    // Trusted local no-filter callers keep the legacy GraphNode[] shape.
    const local = (await op.handler(mkCtx(false), { slug: 'notes/world-page' })) as Array<{ slug: string }>;
    expect(local.map((n) => n.slug)).toContain('notes/private-page');
  });

  test('traverse_graph: a private start page reads as missing ([]) remotely', async () => {
    __resetPrivateVisibilityCacheForTests();
    const op = operationsByName['traverse_graph'];
    expect((await op.handler(mkCtx(true), { slug: 'notes/private-page' })) as unknown[]).toEqual([]);
    expect(((await op.handler(mkCtx(false), { slug: 'notes/private-page' })) as unknown[]).length).toBeGreaterThan(0);
  });

  test('traverse_graph (path shape): paths touching a private slug are dropped remotely', async () => {
    __resetPrivateVisibilityCacheForTests();
    const op = operationsByName['traverse_graph'];
    const remote = (await op.handler(mkCtx(true), { slug: 'notes/world-page', direction: 'out' })) as Array<{
      from_slug: string; to_slug: string;
    }>;
    const touched = remote.flatMap((e) => [e.from_slug, e.to_slug]);
    expect(touched).not.toContain('notes/private-page');
    expect(touched).toContain('notes/unmarked-page');
    const local = (await op.handler(mkCtx(false), { slug: 'notes/world-page', direction: 'out' })) as Array<{
      from_slug: string; to_slug: string;
    }>;
    expect(local.flatMap((e) => [e.from_slug, e.to_slug])).toContain('notes/private-page');
  });

  test('config opt-out restores remote reads on the sibling ops', async () => {
    await engine.setConfig(REMOTE_PRIVATE_PAGES_KEY, 'visible');
    __resetPrivateVisibilityCacheForTests();
    try {
      const chunks = (await operationsByName['get_chunks'].handler(mkCtx(true), { slug: 'notes/private-page' })) as unknown[];
      expect(chunks.length).toBeGreaterThan(0);
      const resolved = (await operationsByName['resolve_slugs'].handler(mkCtx(true), { partial: 'notes/private-page' })) as string[];
      expect(resolved).toEqual(['notes/private-page']);
    } finally {
      await engine.setConfig(REMOTE_PRIVATE_PAGES_KEY, '');
      __resetPrivateVisibilityCacheForTests();
    }
  });
});

describe('shared private predicate lives once (#4352 remediation)', () => {
  test('entity-card composes privatePagesFilterFragment instead of hand-rolling the predicate', () => {
    // test-reads-source-ok[trust-boundary]: structural "lives ONCE" guard — a duplicated predicate behaves identically until visibility semantics drift, so only the text can catch it (#4352)
    const src = readFileSync(join(import.meta.dir, '../src/core/verbs/entity-card.ts'), 'utf8');
    expect(src).toMatch(/privatePagesFilter(Fragment|ForCaller)\(/);
    // The predicate TEXT must not be duplicated — silent drift risk if
    // visibility semantics ever change (sql-ranking.ts's "lives ONCE" claim).
    expect(src).not.toMatch(/frontmatter->>\s*'visibility'/);
  });
});