Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
9.1 KB
Raw Blame
/**
 * GBRA-156: `whois`, the exact identity lookup, on PGLite.
 *
 * Protects: an email or name resolves only on an exact match (email, title or
 * declared alias, ignoring case, accents, width forms and surrounding quotes),
 * never on a fuzzy, nickname, typo or partial one; ambiguity and an empty
 * result are explicit; and a remote caller never sees a page in an ungranted
 * source, a private or quarantined page, a deleted page or an archived source.
 * The Postgres twin is test/e2e/whois-postgres.test.ts.
 */
import { describe, test, expect, beforeAll, afterAll, beforeEach } from 'bun:test';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { resetPgliteState } from './helpers/reset-pglite.ts';
import { operationsByName, type OperationContext } from '../src/core/operations.ts';
import { OperationError } from '../src/core/ops/contract.ts';
import { __resetPrivateVisibilityCacheForTests } from '../src/core/search/private-visibility.ts';
import { seedWhoisFixture, whoisCandidatePlan } from './helpers/whois-fixture.ts';

let engine: PGLiteEngine;

beforeAll(async () => {
  engine = new PGLiteEngine();
  await engine.connect({});
  await engine.initSchema();
});

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

beforeEach(async () => {
  await resetPgliteState(engine);
  __resetPrivateVisibilityCacheForTests();
  await seedWhoisFixture(engine);
});

function ctxOf(overrides: Partial<OperationContext> = {}): OperationContext {
  return {
    engine: engine as never,
    config: {} as never,
    logger: { info: () => {}, warn: () => {}, error: () => {} } as never,
    dryRun: false,
    remote: false,
    ...overrides,
  } as OperationContext;
}
const local = () => ctxOf();
const remote = () => ctxOf({ remote: true, transport: 'stdio', sourceId: 'source-a', auth: { allowedSources: ['source-a'] } as never });

interface Match { slug: string; source_id: string; title: string; type: string; match: string }
interface Result { query_kind: string; matches: Match[]; ambiguous: boolean; types_status: string; note?: string }
const whois = async (ctx: OperationContext, params: Record<string, unknown>) =>
  await operationsByName['whois']!.handler(ctx, params) as Result;
const hits = (r: Result) => r.matches.map(m => `${m.source_id}:${m.slug}:${m.match}`);

describe('whois matches exactly, ignoring case, accents, width and quotes', () => {
  test.each([
    ['unaccented query, accented title', 'Jose Example', 'source-a:people/jose-example:title'],
    ['accented query, unaccented title', 'José Sample', 'source-a:people/jose-sample:title'],
    ['upper case', 'JOSÉ EXAMPLE', 'source-a:people/jose-example:title'],
    ['mixed case', 'jOsE eXaMpLe', 'source-a:people/jose-example:title'],
    ['full-width forms and an ideographic space', 'Jose\u3000Example', 'source-a:people/jose-example:title'],
    ['surrounding quotes and whitespace', '  "José Example"  ', 'source-a:people/jose-example:title'],
    ['typographic quotes', '\u201cJose Example\u201d', 'source-a:people/jose-example:title'],
    ['decomposed accent in the query', 'Jose\u0301 Example', 'source-a:people/jose-example:title'],
    ['stroke letter', 'Lukasz Example', 'source-a:people/lukasz-example:title'],
  ])('%s', async (_label, query, expected) => {
    const res = await whois(local(), { query });
    expect(res.query_kind).toBe('name');
    expect(hits(res)).toEqual([expected]);
    expect(res.ambiguous).toBe(false);
  });

  test.each([
    ['frontmatter email, query in another case', '[email protected]', 'source-a:people/alice-example:email'],
    ['second address of an emails list', '[email protected]', 'source-a:people/bob-example:email'],
    ['angle brackets around the address', '<[email protected]>', 'source-a:people/alice-example:email'],
    ['mixed-case stored address declared as an alias (contact shape)', '[email protected]', 'source-a:contacts/contact-0001:email'],
  ])('email: %s', async (_label, query, expected) => {
    const res = await whois(local(), { query });
    expect(res.query_kind).toBe('email');
    expect(hits(res)).toEqual([expected]);
  });

  test('a declared alias matches and is labeled alias; titles rank before aliases; ambiguity is explicit', async () => {
    const res = await whois(local(), { query: 'erin example' });
    expect(hits(res)).toEqual([
      'source-a:people/erin-example:title',
      'source-b:people/erin-example:title',
      'source-a:people/e-example:alias',
    ]);
    expect(res.ambiguous).toBe(true);
  });

  test('an email match ranks before an alias holding the same address', async () => {
    const res = await whois(local(), { query: '[email protected]', source_id: 'source-a' });
    expect(hits(res)).toEqual(['source-a:people/erin-example:email', 'source-a:people/e-example:alias']);
    expect(res.ambiguous).toBe(true);
  });

  test('source_id narrows the lookup to one source', async () => {
    expect(hits(await whois(local(), { query: 'Erin Example', source_id: 'source-b' }))).toEqual(['source-b:people/erin-example:title']);
  });
});

describe('whois never matches a near name', () => {
  test.each([
    ['short given name', 'Matt Example'],
    ['nickname', 'Rob Example'],
    ['typo', 'Jose Exampel'],
    ['surname alone', 'Example'],
    ['given name alone', 'José'],
    ['reordered name', 'Example, José'],
    ['first word of a title', 'Matthew'],
    ['the slug basename but not the title', 'Kim Example'],
    ['different address', '[email protected]'],
    ['address local part only', 'alice'],
  ])('%s: explicit empty result, not an error', async (_label, query) => {
    const res = await whois(local(), { query });
    expect(res.matches).toEqual([]);
    expect(res.ambiguous).toBe(false);
  });

  test('a page whose body or longer title mentions the name is not a match', async () => {
    expect(hits(await whois(local(), { query: 'Matt Example', types: ['note', 'person'] }))).toEqual([]);
  });
});

describe('whois type filter', () => {
  test('defaults to the schema pack entity types; types widens or narrows it', async () => {
    expect(hits(await whois(local(), { query: 'Jose Example' }))).toEqual(['source-a:people/jose-example:title']);
    expect(hits(await whois(local(), { query: 'Jose Example', types: ['note'] }))).toEqual(['source-a:notes/jose-example:title']);
    const both = await whois(local(), { query: 'Jose Example', types: ['person', 'note'] });
    expect(hits(both)).toEqual(['source-a:notes/jose-example:title', 'source-a:people/jose-example:title']);
    expect(both.ambiguous).toBe(true);
  });

  test('invalid parameters are refused', async () => {
    for (const params of [{ query: '' }, { query: '  ""  ' }, { query: 'x'.repeat(321) }, { query: 'Jose Example', types: [] }, { query: 'Jose Example', types: ['bad type'] }]) {
      await expect(whois(local(), params)).rejects.toBeInstanceOf(OperationError);
    }
  });
});

describe('whois candidate read', () => {
  test('every probe is served by an index: no sequential scan of pages or page_aliases', async () => {
    const plan = await whoisCandidatePlan(engine);
    expect(plan).not.toMatch(/Seq Scan on (pages|page_aliases)\b/);
    for (const index of ['idx_pages_source_title_lower', 'idx_pages_slug_basename', 'idx_pages_frontmatter']) expect(plan).toContain(index);
    expect(plan).toMatch(/(on|using) page_aliases_\w+/);
  });
});

describe('whois read safety', () => {
  test('a local caller sees every live page; deleted pages and archived sources never match', async () => {
    expect(hits(await whois(local(), { query: '[email protected]' }))).toEqual(['source-b:people/frank-example:email']);
    expect(hits(await whois(local(), { query: '[email protected]' }))).toEqual(['source-a:people/grace-example:email']);
    expect(hits(await whois(local(), { query: 'Heidi Example' }))).toEqual(['source-a:people/heidi-example:title']);
    expect(hits(await whois(local(), { query: '[email protected]' }))).toEqual([]);
    expect(hits(await whois(local(), { query: 'Judy Example' }))).toEqual([]);
  });

  test('a remote caller never sees a page in an ungranted source', async () => {
    expect(hits(await whois(remote(), { query: '[email protected]' }))).toEqual([]);
    expect(hits(await whois(remote(), { query: 'Frank Example', source_id: '__all__' }))).toEqual([]);
    expect(hits(await whois(remote(), { query: 'Erin Example' }))).toEqual(['source-a:people/erin-example:title', 'source-a:people/e-example:alias']);
    await expect(whois(remote(), { query: 'Frank Example', source_id: 'source-b' })).rejects.toMatchObject({ code: 'permission_denied' });
    const scalar = ctxOf({ remote: true, transport: 'stdio', sourceId: 'source-a' });
    expect(hits(await whois(scalar, { query: 'Frank Example' }))).toEqual([]);
  });

  test('a remote caller never sees a private or quarantined page, by email, title or alias', async () => {
    for (const query of ['[email protected]', 'Grace Example', '[email protected]', 'Heidi Example']) {
      const res = await whois(remote(), { query });
      expect(res.matches).toEqual([]);
      expect(JSON.stringify(res)).not.toContain('people/grace-example');
      expect(JSON.stringify(res)).not.toContain('people/heidi-example');
    }
  });
});