Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
5.3 KB
Raw Blame
/**
 * #8982: what federating a source exposes. A credential bound to a member writes to a source it was granted
 * without stamped readers (GST-2051 stamps only writes the no-grant floor reads), which is right while that source
 * is not federated. Federating it (`sources federate`, `sources restore`) adds it to the floor, so each such page
 * becomes readable by every connection with no source grant. This read names those pages so the operator sees them;
 * it writes nothing and never refuses the change.
 *
 * A page counts when it names no readers and no folder rule, the read paths' privacy rules (privacyPartSql: visibility,
 * aliases, pinned questions, lineage) do not hide it from a no-grant connection (#9068; the search.remote_private_pages
 * and GBRAIN_REMOTE_PRIVATE_PAGES opt-outs relax them here too), and the writer of its live revision or of any earlier
 * version (the write attribution columns) is a remote credential: a token or OAuth client, revoked or deleted since. No
 * record keeps which member a credential was bound to when it wrote, so a credential unbound or rebound since then
 * counts too, and each example names the member it is bound to now (null when none or deleted). A write that moves
 * the revision attribution without a version snapshot (a tag change) hides the earlier remote author from this read. The database is the record, so a
 * repo-less brain answers the same way.
 */
import { shellQuote } from '../agent-output.ts';
import type { BrainEngine } from '../engine.ts';
import { privacyPartSql, remotePrivacyRelaxed } from '../search/private-visibility.ts';
import { hintReaders } from './owner.ts';

export interface PagesExposed {
  count: number;
  examples: Array<{ slug: string; member: string | null }>;
  check: string;
  restrict: string;
}

/** The pages of `sourceId` a remote credential wrote that name no readers (the first five by slug), or null when there are none. */
export async function remotePagesFederationExposes(engine: BrainEngine, sourceId: string): Promise<PagesExposed | null> {
  const hidden = await remotePrivacyRelaxed(engine) ? '' : ` AND ${privacyPartSql('p')}`;
  const rows = await engine.executeRaw<{ slug: string; member: string | null; total: number }>(
    `WITH open AS (SELECT p.id, p.slug, p.revision_principal_kind, p.revision_principal_id FROM pages p
       WHERE p.source_id = $1 AND p.deleted_at IS NULL AND p.page_readers IS NULL AND p.folder_rule_ids IS NULL${hidden}),
     authored AS (
       SELECT slug, revision_principal_kind AS kind, revision_principal_id AS pid FROM open
       UNION ALL
       SELECT o.slug, v.write_principal_kind, v.write_principal_id FROM open o JOIN page_versions v ON v.page_id = o.id)
     SELECT a.slug, min(coalesce(t.member_id, c.member_id)) AS member, (count(*) OVER ())::int AS total
       FROM authored a
       LEFT JOIN access_tokens t ON a.kind = 'legacy_token' AND t.id::text = a.pid
       LEFT JOIN oauth_clients c ON a.kind = 'oauth_client' AND c.client_id = a.pid
      WHERE a.kind IN ('legacy_token', 'oauth_client')
      GROUP BY a.slug ORDER BY a.slug LIMIT 5`, [sourceId]);
  const first = rows[0];
  if (!first) return null;
  const bound = rows.find(r => r.member !== null && r.slug.includes('/'));
  return {
    count: Number(first.total),
    examples: rows.map(r => ({ slug: r.slug, member: r.member })),
    check: shellQuote(['gbrain', 'access', 'who-can-read', first.slug, '--source', sourceId]),
    restrict: bound
      ? shellQuote(['gbrain', 'access', 'rule', 'add', '--prefix', bound.slug.slice(0, bound.slug.lastIndexOf('/') + 1), '--readers', await hintReaders(engine, [bound.member!]), '--source', sourceId])
      : `gbrain access rule add --prefix <folder/> --readers <member> --source ${shellQuote([sourceId])}`,
  };
}

/**
 * remotePagesFederationExposes when `federating` (the change added the source to the no-grant floor), else null. A
 * failed read is reported on stderr and reads as null, so the check never changes whether or how the federation happens.
 */
export async function remotePagesFederationExposesOrWarn(engine: BrainEngine, sourceId: string, federating: boolean): Promise<PagesExposed | null> {
  if (!federating) return null;
  return remotePagesFederationExposes(engine, sourceId).catch((e: unknown) => {
    console.error(`Warning: could not check ${shellQuote([sourceId])} for remote-written pages without readers: ${e instanceof Error ? e.message : String(e)}`);
    return null;
  });
}

/** The operator lines for `exposed`, printed on stderr so a --json stdout stays one object. */
export function pagesExposedLines(sourceId: string, exposed: PagesExposed): string[] {
  const more = exposed.count - exposed.examples.length;
  return [
    `Warning: ${exposed.count} page(s) in ${shellQuote([sourceId])} were written by a remote token or OAuth client and name no readers; ` +
      'with the source federated, every connection with no source grant reads them:',
    ...exposed.examples.map(e => `  ${shellQuote([e.slug])} (${e.member ? `member ${e.member}` : 'credential bound to no member now'})`),
    ...(more > 0 ? [`  ... and ${more} more`] : []),
    `  Check one: ${exposed.check}`,
    `  Keep a folder to its member (previews the pages it covers; --yes applies): ${exposed.restrict}`,
    `  Or give a page readable_by: [<member>] in its frontmatter, or undo with: gbrain sources unfederate ${shellQuote([sourceId])}`,
  ];
}