Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Context validators + scope resolvers for the operations layer (pure move
* from src/core/operations.ts): upload/slug/filename validators, the
* subagent + bound-client slug fences, and the source-scope resolution
* ladder every read-side op routes through. Helpers that were file-private
* in operations.ts (enforceSubagentSlugFence, slugUnderSubagentFence,
* slugOutsideCallerFence, enforceClientSlugFence, BOUND_CLIENT_META_OPS,
* stampEvidenceSafe, maybeCaptureSearch) are exported HERE for future domain
* modules, but are deliberately NOT re-exported from operations.ts — they
* were never part of its public surface.
*/
import { lstatSync, realpathSync } from 'fs';
import { resolve, sep } from 'path';
import { OperationError, opError } from './contract.ts';
import { resolvedPrefixContained } from '../path-confine.ts';
import type { AuthInfo, Operation, OperationContext } from './contract.ts';
import type { Action } from '../agent-output.ts';
import { hostFix, invalidParam, paramUse, readFix } from './op-fix.ts';
import { CJK_SLUG_CHARS } from '../cjk.ts';
import { isOpPageSlug, OP_PAGE_SLUG_RE } from '../page-slug-grammar.ts';
import { validateSlug } from '../utils.ts';
import { ALL_SOURCES, NO_SOURCES, isValidSourceId } from '../source-id.ts';
import { encodeDeepResearchId } from '../deep-research-id.ts';
import { isSearchMode } from '../search/mode.ts';
import { stampEvidence, type EvidenceOpts } from '../search/evidence.ts';
import { captureEvalCandidate, isEvalCaptureEnabled, isEvalScrubEnabled } from '../eval-capture.ts';
import type { SearchResult, HybridSearchMeta, PageReadScope, PageReadPolicy } from '../types.ts';
import { resolveExcludePrivatePages, isPrivatePage } from '../search/private-visibility.ts';
import { assertMemberPageWriter, assertScopePageWriter } from '../access/member-facts.ts';
import { pageNotVisibleError, remoteTargetHidden } from '../persistence/page-visibility.ts';
// --- Agent-contract fixes shared by the op error sites ---
/**
* A slug that can sit in a fix's argv as a bare positional: it cannot read as
* a flag and needs no shell quoting. Any other printable slug goes after `--`
* (the op parser honours it since D6); see getPageFix.
*/
export function cliSafeSlug(slug: unknown): slug is string {
return typeof slug === 'string' && /^[a-z0-9][a-z0-9._/:-]{0,254}$/i.test(slug);
}
/** Read-only: the sources this caller can read (MCP sources_list is grant-confined). */
export function sourcesListFix(why: string): Action {
return readFix(why, { argv: ['gbrain', 'sources', 'list', '--json'], mcp: { tool: 'sources_list', arguments: {} } });
}
/** Read-only: one page by slug, scoped to a source when known. */
export function getPageFix(slug: string, why: string, opts: { sourceId?: string; includeDeleted?: boolean; fuzzy?: boolean } = {}): Action | undefined {
if (typeof slug !== 'string' || !slug || slug.length > 512 || /[\u0000-\u001f\u007f\u2028\u2029]/.test(slug)) return undefined;
const source = opts.sourceId !== undefined && isValidSourceId(opts.sourceId) ? opts.sourceId : undefined;
const flags = [...(opts.includeDeleted ? ['--include-deleted'] : []), ...(opts.fuzzy ? ['--fuzzy'] : []), ...(source ? ['--source', source] : [])];
return readFix(why, {
// A slug like `--yes` or one with shell metacharacters lands after `--`; shellQuote quotes it in `command`.
argv: cliSafeSlug(slug) ? ['gbrain', 'get', slug, ...flags] : ['gbrain', 'get', ...flags, '--', slug],
mcp: { tool: 'get_page', arguments: { slug, ...(opts.includeDeleted ? { include_deleted: true } : {}), ...(opts.fuzzy ? { fuzzy: true } : {}), ...(source ? { source_id: source } : {}) } },
});
}
/** opError options carrying a fix only when one could be built. */
export function withFix(fix: Action | undefined): { fix?: Action } {
return fix ? { fix } : {};
}
/**
* get_page's miss (#4516): where the slug lives when a trusted local probe
* found it in another source, otherwise the soft-delete / fuzzy check, as
* surface-correct prose plus the matching read.
*/
export function pageNotFoundError(
ctx: Pick<OperationContext, 'remote' | 'transport' | 'auth'>,
slug: string,
opts: { includeDeleted: boolean; sourceIdParam?: string; elsewhereSource?: string },
): OperationError {
// GBRA-585: a member's credential misses pages kept to other members too, and it reads the same for both, so it is
// sent neither after a deletion nor to the host CLI.
if (ctx.remote !== false && ctx.auth?.member) {
return opError('page_not_found', `Page not found: ${slug}`,
'This connection reads no page with this slug: it may not exist, or it may not be readable by this connection, since a page can be kept to other members. Do not create it to find out; ask the user whether the page exists and who can read it.');
}
const retry = opts.includeDeleted ? `Check the slug or use ${paramUse(ctx, 'fuzzy')}` : `Page may be soft-deleted; pass ${paramUse(ctx, 'include_deleted')} to verify`;
const where = opts.elsewhereSource;
const explicit = opts.sourceIdParam !== ALL_SOURCES ? opts.sourceIdParam : undefined;
return opError('page_not_found', `Page not found: ${slug}`,
where !== undefined ? `Page exists in source '${where}' — pass ${paramUse(ctx, 'source', where)}. ${retry}` : retry,
withFix(where !== undefined
? getPageFix(slug, `Reads the page from source ${where}, where it exists.`, { sourceId: where })
: getPageFix(slug, opts.includeDeleted ? 'Fuzzy-matches the slug.' : 'Shows the page if it is soft-deleted (deleted_at set).',
{ sourceId: explicit, ...(opts.includeDeleted ? { fuzzy: true } : { includeDeleted: true }) })));
}
const HTTP_HOST = { remote: true, transport: 'http' } as const;
const TOKEN_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
const CLIENT_ID_RE = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$/;
/** The OAuth client id when it is safe to name in a command. */
function safeClientId(auth: Pick<AuthInfo, 'clientId' | 'principal'> | undefined): string | undefined {
return auth?.principal?.kind === 'oauth_client' && CLIENT_ID_RE.test(auth.clientId) ? auth.clientId : undefined;
}
/**
* B5/B6: the brain host operator's grant change for this connection (token
* flags or client flags), or the grant listing when the principal cannot be
* named. Credential-bearing callers reach the server over HTTP.
*/
function grantFix(
auth: Pick<AuthInfo, 'clientId' | 'principal'> | undefined,
change: { token: string[]; client: string[] },
why: string,
inputs?: Action['inputs'],
): Action {
const principal = auth?.principal;
const clientId = safeClientId(auth);
const target = principal?.kind === 'legacy_token' && TOKEN_ID_RE.test(principal.id)
? ['rescope-token', '--id', principal.id, ...change.token]
: clientId ? ['rescope-client', clientId, ...change.client] : null;
if (!target) {
return hostFix(HTTP_HOST, principal?.kind === 'oauth_client' ? ['gbrain', 'auth', 'clients', '--json'] : ['gbrain', 'auth', 'list'],
'Lists the grants so the operator can find and widen this connection.');
}
return { ...hostFix(HTTP_HOST, ['gbrain', 'auth', ...target], why, { consent: ['credentials'] }), ...(inputs ? { inputs } : {}) };
}
/** Grant at least one readable source to this connection (value supplied by the user). */
function sourceGrantFix(auth: Pick<AuthInfo, 'clientId' | 'principal'> | undefined): Action {
return grantFix(auth, { token: ['--sources', '<sources>'], client: ['--federated-read', '<sources>'] },
'Grants this connection the sources it may read; only the brain host operator can change grants.',
[{ name: 'sources', how: 'Ask the user which source ids this connection should read (comma-separated; `gbrain sources list` on the brain host shows them).' }]);
}
/** Pending schema migrations on the brain host restore a degraded grant/fence projection. */
function migrationsFix(ctx: Pick<OperationContext, 'remote' | 'transport'>): Action {
return hostFix(ctx, ['gbrain', 'apply-migrations', '--yes', '--no-autopilot-install'],
'The oauth_clients projection predates the grant columns; applying the pending migrations lets the fence be evaluated again.');
}
// --- Upload validators (Fix 1 / B5 / H5 / M4) ---
/**
* Strict-mode containment over two realpaths. Separator-aware: `..drafts/` is an
* ordinary folder name, while `../`, another drive (Windows), a UNC share and a
* sibling sharing the root's name prefix all fall outside. The root itself is
* never an uploadable file. Pure, so tests can drive it with `path.win32` shapes.
*/
export function uploadPathInsideRoot(real: string, realRoot: string, sepChar: string): boolean {
return real !== realRoot && resolvedPrefixContained(real, realRoot, sepChar);
}
/**
* Validate an upload path. Two modes:
* - strict (remote=true): confines the resolved path to `root` and rejects symlinks.
* Used when the caller is untrusted (MCP over stdio/HTTP, agent-facing).
* - loose (remote=false): only verifies the file exists and is not a symlink whose
* target escapes the filesystem (no path traversal protection). Used for local CLI
* where the user owns the filesystem.
*
* Either way: symlinks in the final component are always rejected (prevents
* transparent redirection to a different file than the user typed).
*
* @param filePath caller-supplied path
* @param root confinement root (only used when strict=true)
* @param strict true → enforce cwd confinement (B5 + H1). false → allow any accessible path.
* @throws OperationError(invalid_params) on symlink escape, traversal, or missing file
*/
export function validateUploadPath(filePath: string, root: string, strict = true): string {
let real: string;
try {
real = realpathSync(resolve(filePath));
} catch (e: unknown) {
const msg = e instanceof Error ? e.message : String(e);
if (msg.includes('ENOENT')) {
throw opError('invalid_params', `File not found: ${filePath}`,
'Pass the path of an existing file; a relative path resolves against the working directory of the process running gbrain.');
}
throw opError('invalid_params', `Cannot resolve path: ${filePath}`,
'Pass a readable regular file: the path or one of its parent directories could not be resolved (permissions or a broken link).');
}
// Always reject final-component symlinks (basic safety for both modes).
try {
if (lstatSync(resolve(filePath)).isSymbolicLink()) {
throw opError('invalid_params', `Symlinks are not allowed for upload: ${filePath}`,
"Pass the link's real target path instead of the symlink (`realpath` prints it).");
}
} catch (e) {
if (e instanceof OperationError) throw e;
// lstat race with unlink — pass if realpath already succeeded.
}
if (!strict) return real;
// Strict mode: confine to root by realpath on both sides (catches parent-dir symlinks per B5).
let realRoot: string;
try {
realRoot = realpathSync(root);
} catch {
throw opError('invalid_params', `Confinement root not accessible: ${root}`,
"The upload root (the server's working directory) is unreadable on the brain host; tell the user so its operator can fix that directory.");
}
if (!uploadPathInsideRoot(real, realRoot, sep)) {
throw opError('invalid_params', `Upload path must be within the working directory: ${filePath}`,
"Copy the file under the server's working directory and pass that path; a symlinked parent that resolves outside it is refused too.");
}
return real;
}
/**
* Allowlist validator for page slugs. Rejects URL-encoded traversal, backslashes,
* control chars, RTL overrides, Unicode lookalikes — anything outside the allowlist.
* Format: alphanumeric parts (dot/underscore/hyphen continuation allowed),
* optionally colon-separated within segments; segments use single forward slashes.
*/
export function validatePageSlug(slug: string): void {
if (typeof slug !== 'string' || slug.length === 0) {
throw opError('invalid_params', 'page_slug must be a non-empty string', 'Pass a slug such as people/alice-example.');
}
if (slug.length > 255) {
throw opError('invalid_params', 'page_slug exceeds 255 characters', 'Shorten the slug to 255 characters or fewer.');
}
// #3417: letters/numbers from any script allowed in segments (u flag required
// for the \p{...} classes in OP_PAGE_SLUG_SEG). Shape rules (word-char lead,
// dot/underscore/hyphen continuation) preserved.
if (!OP_PAGE_SLUG_RE.test(slug)) {
throw opError('invalid_params', `Invalid page_slug: ${slug} (allowed: letters/numbers in any script, with '.', '_', '-' after the first character of a part, optional colon-separated namespace parts, and forward-slash separated segments)`,
'Use a slug shaped like people/alice-example or notes/v1.0.0: no spaces, backslashes, percent-encoding or dot-led segments.');
}
}
export { isOpPageSlug };
/**
* #6212: a slug an older gbrain stored that today's grammar refuses (a space,
* as in `people/jane doe`). Admitted only to delete or restore that exact
* existing row, and only if it still passes the storage guard (validateSlug:
* no traversal, leading `/`, backslash, control or bidi characters, or encoded
* separators). Such a row is published database-only (page-prepare.ts): its
* recorded file path may belong to another page.
*/
export function isLegacyStoredPageSlug(slug: string): boolean {
if (isOpPageSlug(slug) || typeof slug !== 'string' || slug.length > 255) return false;
try { validateSlug(slug); return true; } catch { return false; } // refused by the storage guard too: not a legacy slug
}
/**
* Match a slug against a list of allow-list prefix globs.
*
* Glob form: `<prefix>/*` matches any slug starting with `<prefix>/` and
* having at least one more segment (single or multi). Bare `<prefix>` (no
* trailing `/*`) matches that exact slug only. The `*` is intentionally
* permissive — depth is unbounded, so `wiki/originals/*` matches both
* `wiki/originals/idea-x` and `wiki/originals/ideas/2026-04-25-idea-y`.
*
* Used by the v0.23 dream-cycle trusted-workspace path. Order doesn't
* matter; the first match wins (returns true on any match).
*/
export function matchesSlugAllowList(slug: string, prefixes: readonly string[]): boolean {
for (const p of prefixes) {
if (p.endsWith('/*')) {
const base = p.slice(0, -2);
if (slug === base) continue;
if (slug.startsWith(base + '/')) return true;
} else if (p === slug) {
return true;
}
}
return false;
}
/**
* Subagent slug-fence enforcement, shared by every mutating op a subagent
* can reach (put_page, add_timeline_entry). FAIL-CLOSED: `viaSubagent=true`
* enforces the check even if the dispatcher forgot to populate `subagentId`.
*
* - Trusted-workspace path (ctx.allowedSlugPrefixes set by cycle.ts under
* PROTECTED_JOB_NAMES \u2014 MCP cannot reach it): slug must match the
* allow-list globs.
* - Legacy default: slug must live under `wiki/agents/<subagentId>/...`
* (anchored, slash-boundary \u2014 `wiki/agents/12evil/*` can't impersonate
* subagent 12).
*
* #5994: the one exception to the missing-`subagentId` refusal is the trusted
* local failed-writes replay of a stored restricted authority that recorded no
* job id (`replayedAllowList`); it still checks the slug against that list.
*/
export function enforceSubagentSlugFence(ctx: OperationContext, slug: string, opName: string): void {
if (ctx.viaSubagent !== true) return;
if ((typeof ctx.subagentId !== 'number' || Number.isNaN(ctx.subagentId)) && !replayedAllowList(ctx)) {
throw opError('permission_denied', `${opName} via subagent requires ctx.subagentId`,
'This is a gbrain dispatch fault, not a caller mistake: report it to the user instead of resubmitting the write.');
}
if (slugUnderSubagentFence(ctx, slug)) return;
const allowList = ctx.allowedSlugPrefixes;
const fenced = allowList && allowList.length > 0;
throw opError(
'permission_denied',
fenced
? `${opName} slug '${slug}' is not within the trusted-workspace allow-list (${allowList.join(', ')})`
: `${opName} via subagent must write under 'wiki/agents/${ctx.subagentId}/...'`,
fenced
? `Write to a slug matching one of: ${allowList.join(', ')}.`
: `Write under wiki/agents/${ctx.subagentId}/ (for example wiki/agents/${ctx.subagentId}/notes).`,
);
}
/** A failed-writes replay of a restricted authority, confined to exactly the stored, non-empty allow-list. */
function replayedAllowList(ctx: OperationContext): boolean {
const stored = ctx.replayAuthority;
const list = ctx.allowedSlugPrefixes;
return !!stored?.restrictedNamespace && !!list?.length && !!stored.delegatedPrefixes?.length
&& list.length === stored.delegatedPrefixes.length && list.every((prefix, i) => prefix === stored.delegatedPrefixes![i]);
}
/**
* The subagent fence's MATCH RULE, without the throwing. Split out so the
* resolved-slug re-check in put_page can ask the same question the entry
* fence asks, instead of re-deriving the namespace literal and drifting.
* Callers must have already established `ctx.viaSubagent === true`.
*/
export function slugUnderSubagentFence(ctx: OperationContext, slug: string): boolean {
const allowList = ctx.allowedSlugPrefixes;
if (allowList && allowList.length > 0) return matchesSlugAllowList(slug, allowList);
const prefix = `wiki/agents/${ctx.subagentId}/`;
return slug.startsWith(prefix) && slug.length > prefix.length;
}
/**
* Is `slug` outside whatever slug confinement THIS caller is under?
*
* A caller can be confined by EITHER mechanism, and the two arrive on
* different context fields: an OAuth binding lands on `ctx.auth
* .boundSlugPrefixes` (plain-prefix grammar), while a delegated subagent
* lands on `ctx.viaSubagent` + `ctx.allowedSlugPrefixes` (glob grammar).
* Its auth carries read scope, not the parent's direct-write fence. Testing
* only the OAuth field therefore lets
* a bound client that also holds `agent` scope re-open the path it is fenced
* out of simply by delegating the write through submit_agent — the same
* bypass shape the facts-backstop gate below is keyed against.
*
* Unconfined callers (local CLI, unbound client) match neither arm and are
* never fenced.
*/
export function slugOutsideCallerFence(ctx: OperationContext, slug: string): boolean {
const bound = ctx.auth?.boundSlugPrefixes;
if (bound && !slugUnderBoundPrefixes(bound, slug)) return true;
if (ctx.viaSubagent === true && !slugUnderSubagentFence(ctx, slug)) return true;
return false;
}
/**
* OAuth-client slug-fence enforcement (v0.42.72.0 — write-side isolation
* symmetry). When the authenticated client was registered with
* --bound-slug-prefixes, every direct slug-mutating write must target a
* slug under one of those prefixes. Shared by put_page, delete_page,
* restore_page, add_tag, remove_tag, add_link/remove_link (`from`
* endpoint), add_timeline_entry, revert_version, and put_raw_data; runs
* BEFORE each op's dry-run short-circuit so preview calls surface the
* same rejection.
*
* Semantics deliberately match submit_agent's bound_slug_prefixes check
* (plain startsWith, NOT the `/*` glob grammar of the subagent allow-list
* above): a non-null binding fences fail-closed (empty array = deny all
* writes), no binding / no auth = no fence (local CLI and unbound clients
* keep full-source write authority). Register prefixes with a trailing
* slash ('wiki/agents/alice/') — a bare 'notes' also admits
* 'notes-archive/...' by startsWith construction.
*/
export function enforceClientSlugFence(ctx: OperationContext, slug: string, opName: string): void {
assertMemberPageWriter(ctx, slug, opName);
assertScopePageWriter(ctx, slug, opName);
if (ctx.auth?.fenceProjectionDegraded) {
throw opError(
'permission_denied',
`${opName}: this brain's oauth_clients projection is missing bound_slug_prefixes, so the write fence cannot be evaluated. Refusing the write rather than running unfenced.`,
"The brain host's operator applies the pending migrations (command in fix); then repeat the write.",
{ fix: migrationsFix(ctx) },
);
}
const prefixes = ctx.auth?.boundSlugPrefixes;
if (!prefixes) return;
if (!slugUnderBoundPrefixes(prefixes, slug)) {
throw opError(
'permission_denied',
`${opName}: slug '${slug}' is not under any of client ${ctx.auth?.clientId ?? '(unknown)'}'s bound_slug_prefixes (${prefixes.join(', ')})`,
`Write to a slug under ${prefixes.join(', ') || 'a granted prefix'}; only the brain host's operator can change this client's binding.`,
);
}
}
/**
* The one place the fence's match rule lives. Exported so non-op write
* surfaces that never build an OperationContext (the `/ingest` route in
* serve-http.ts) enforce byte-identical semantics instead of re-deriving
* them.
*
* An empty-string prefix is IGNORED rather than honored: `startsWith('')`
* is true for every slug, so a stray `''` (an unset shell variable in a
* provisioning template) would silently turn a binding into a wildcard
* while still rendering as "fenced" to the operator. Registration now
* rejects empty prefixes outright; this is the second line of defence for
* rows already in the database.
*/
export function slugUnderBoundPrefixes(prefixes: readonly string[], slug: string): boolean {
// Compare against the CANONICAL slug. `validateSlug` lowercases before the
// row is written, so checking the caller's raw string let `EMP-ALICE/x`
// satisfy an `EMP-ALICE/` binding, commit as `emp-alice/x`, and only then
// trip the resolved-slug re-check — an error returned after the write had
// already landed. Registration rejects non-lowercase prefixes going
// forward; lowercasing both sides keeps pre-existing rows meaning what
// their operator intended.
const canonical = slug.toLowerCase();
return prefixes.some((bp) => {
const base = normalizeSlugPrefix(bp);
if (base === '') return false;
// Boundary-aware: a prefix must match whole SEGMENTS. Plain `startsWith`
// let a boundary-less `emp-alice` admit `emp-alice-2/onboarding` — and
// with the `emp-<slug>` naming this guide recommends, sibling collisions
// (`alice` vs `alice-2`) are the common case, not a corner case.
return base.endsWith('/')
? canonical.startsWith(base)
: canonical === base || canonical.startsWith(`${base}/`);
});
}
/**
* Canonical form of one stored prefix, lowercased. `oauth_clients.bound_slug_prefixes`
* predates this fence — migration v85 introduced it as submit_agent's binding,
* whose grammar is the `<prefix>/*` glob of `matchesSlugAllowList` — so both
* spellings have to mean the same span of slugs or upgrading silently changes
* what an existing client may write.
*/
export function normalizeSlugPrefix(prefix: string): string {
return (prefix.endsWith('/*') ? prefix.slice(0, -1) : prefix).toLowerCase();
}
/**
* Write ops a slug-bound client may call: every op that routes through
* `enforceClientSlugFence`, plus `think` (scope `read` for remote callers;
* it stays on this list because it is `mutating` locally, but remote callers
* cannot persist — `save`/`take` are forced false for `remote !== false`).
*
* This list is an ALLOW-list on purpose. The fence used to be enforced op
* by op, which made every unfenced write op a silent hole — `extract_entities`
* mutating `people/*` timelines, `forget_fact` rewriting another source's
* page by numeric id, `extract_facts` appending to any entity's fact fence.
* Enumerating what is SAFE fails closed instead: a write op added later is
* denied to bound clients until someone fences it and adds it here.
*/
export const CLIENT_FENCED_WRITE_OPS: ReadonlySet<string> = new Set([
'put_page', 'delete_page', 'restore_page', 'add_tag', 'remove_tag',
'add_link', 'remove_link', 'add_timeline_entry', 'revert_version',
// #5616: edit_page enforces the slug fence in its handler and submission.
'edit_page',
// Wave B: append_page is fenced on submission as edit_page is.
'append_page',
// #6007: put_pages fences every page as the put_page it is submitted as.
'put_pages',
'begin_page_upload', 'upload_page_part', 'get_page_upload', 'commit_page_upload', 'abort_page_upload',
'put_raw_data', 'think',
// submit_agent enforces bound_slug_prefixes itself (it is the op the column
// was introduced for — see its bound_* binding check), so denying it here
// would break the original feature for clients that legitimately hold both
// a binding and `agent` scope.
'submit_agent',
// CLI→MCP gap-closure wave: capture delegates to put_page with the same ctx
// (inheriting its enforceClientSlugFence) and [EV7] defaults its slug UNDER
// the caller's first bound prefix — the zero-config path exists for exactly
// the bound-agent audience. The takes write verbs each call
// enforceClientSlugFence themselves (their markdown mirror writes the
// page file under the slug), the same guarantee as add_tag/add_timeline_entry.
'capture',
// Own-principal receipt controls recheck original/current source + slug
// authority. They are not meta-op exemptions: degraded fences still deny.
'get_write_request', 'list_write_requests', 'cancel_write_request',
'takes_add', 'takes_update', 'takes_resolve', 'takes_supersede', 'takes_remove',
'put_skill', 'delete_skill',
// #5913: remember fences the one slug it writes (the caller's entity, or
// memory/unattributed) in planRememberTarget (persistence/memory-mutations.ts)
// before admission, so an inferred or unattributed target outside the
// prefixes is refused, and `replaces` is confined to the same entity and
// page (facts/single-prepare.ts decideReplacement). forget/forget_fact stay
// off the list: a withdrawal's write set (withdrawal-discovery.ts) reaches
// pages the fenced slug does not name, so they wait for a confined closure.
'remember',
]);
/**
* WP4 (D9) — discovery meta-ops exempt from the bound-client fence's
* LISTING/dispatch denial. `request_tools` is `mutating: true` (its persist
* branch writes oauth_clients.surface), which would otherwise hide discovery
* from every slug-bound client. The exemption is safe because the persist
* branch SELF-ENFORCES its own guards — server ceiling (D2), operator lock
* (amendment 19), OAuth scopes, and a per-client rate limit (D14.5) — and it
* never touches a slug. Lives here (not inline in the predicate) so the
* tools/list filter and the dispatch fence consume the identical carve-out
* (ENG-3 drift-proofing).
*/
export const BOUND_CLIENT_META_OPS: ReadonlySet<string> = new Set(['request_tools', 'join_brain', 'sync_brain_skills', 'leave_brain']);
/**
* Single source of truth for "may a slug-bound client use this op" (ENG-3).
* Consumed by BOTH the dispatch-time fence below AND the tools/list filter
* in serve-http, so the advertised catalog and the deny behavior cannot
* drift — a bound client is never shown an op that will fence-deny at call
* time. Gate on "mutates, or carries any non-read scope" rather than on the
* two literal scope strings 'write'/'admin': `sources_add`/`sources_remove`
* carry the bespoke `sources_admin` scope and are `mutating: true`, so a
* scope-string check let a bound client DROP AN ENTIRE SOURCE — every page
* in it, far outside any prefix. Anything that isn't a plain read must be
* explicitly allow-listed. A degraded projection (binding unreadable) denies
* every non-read op — the unfenceable ops must not stay reachable precisely
* when the fence is unreadable. Exception: BOUND_CLIENT_META_OPS (D9) stay
* allowed even degraded — they are slug-free discovery ops whose only write
* self-enforces ceiling+lock+scopes+rate-limit (and a degraded projection
* also dropped the surface columns, so that write fails 'migration pending'
* rather than running unguarded).
*/
export function opAllowedForBoundClient(
auth: Pick<AuthInfo, 'boundSlugPrefixes' | 'fenceProjectionDegraded' | 'allowedOperations' | 'grantProjectionDegraded'> | undefined,
op: Pick<Operation, 'name' | 'scope' | 'mutating'>,
): boolean {
if (auth?.grantProjectionDegraded) return false;
if (Array.isArray(auth?.allowedOperations) && !auth.allowedOperations.includes(op.name)) return false;
const degraded = auth?.fenceProjectionDegraded === true;
if (!degraded && !auth?.boundSlugPrefixes) return true;
const isRead = op.scope === 'read' && op.mutating !== true;
if (isRead) return true;
if (BOUND_CLIENT_META_OPS.has(op.name)) return op.name === 'request_tools' || !degraded;
if (degraded) return false;
return CLIENT_FENCED_WRITE_OPS.has(op.name);
}
/**
* The explicit no-source grant (`permissions.source_id: []`, written by
* `gbrain auth rescope-token <name> --sources none`) refuses every operation:
* it never falls back to the `default` floor for reads or writes.
*/
export function noSourceGrantError(operation?: string, auth?: Pick<AuthInfo, 'clientId' | 'principal'>): OperationError {
const fix = sourceGrantFix(auth);
const err = opError('permission_denied',
`${operation ? `${operation}: ` : ''}this token is granted no sources (its source grant is an explicit empty list).`,
fix.inputs
? "Ask the brain host's operator to grant this token at least one source (command in fix), then reconnect."
: "Ask the brain host's operator to find this token in the token list (command in fix) and grant it at least one source, then reconnect.",
{ docs: 'docs/mcp/ADMIN.md#legacy-token-grants', fix });
err.detail = 'fence=no_source_grant';
return err;
}
/**
* #8982 item 3: POST /ingest refuses a member-bound credential whose write source every credential without a source grant
* reads (GST-2051); the fix asks the operator to give it a write source of its own that is not federated.
*/
export function sharedWriteSourceMemberError(operation: string, auth: Pick<AuthInfo, 'clientId' | 'principal'>, sourceId: string): OperationError {
const fix = grantFix(auth, { token: ['--sources', '<sources>'], client: ['--source', '<source>'] },
'Gives this connection a write source of its own that is not federated; only the brain host operator can change grants.');
const input = fix.argv?.includes('<sources>')
? { name: 'sources', how: 'Ask the user for a source that is not federated, written first, then default (e.g. <private-source>,default; `gbrain sources list` on the brain host shows them).' }
: fix.argv?.includes('<source>') ? { name: 'source', how: 'Ask the user for a source that is not federated (`gbrain sources list` on the brain host shows them).' } : null;
return opError('permission_denied',
`${operation} is unavailable to a credential bound to a member whose write source is ${sourceId}, which every credential without a source grant reads: its pages would land where other members ` +
'and unbound credentials read. Write through the MCP put_page op, which keeps a new page to its member, ' +
'or ask the brain operator to grant this credential its own write source that is not federated (gbrain auth rescope --sources <private-source>,default).',
"Write through the MCP put_page op, or ask the brain host's operator to give this credential a write source that is not federated (command in fix).",
{ docs: 'docs/guides/multi-source-brains.md#lay-out-sources-by-who-may-read-them', fix: input ? { ...fix, inputs: [input] } : fix });
}
/**
* Fail-closed gate for slug-bound clients, applied at dispatch (the single
* choke point both MCP transports share) so it cannot be forgotten per op.
* Read ops are untouched — read scope is enforced by source federation.
* Allow/deny derives from `opAllowedForBoundClient`; this wrapper only owns
* the error envelopes.
*/
export function enforceBoundClientOpAllowList(
auth: AuthInfo | undefined,
op: Pick<Operation, 'name' | 'scope' | 'mutating'>,
): void {
if (auth?.sourceId === NO_SOURCES) throw noSourceGrantError(op.name, auth);
if (opAllowedForBoundClient(auth, op)) return;
if (auth?.grantProjectionDegraded || (Array.isArray(auth?.allowedOperations) && !auth.allowedOperations.includes(op.name))) {
const err = opError('permission_denied', `${op.name} is outside this client's approved operation snapshot.`,
"Ask the brain host's operator to explicitly regrant the required operation (command in fix); upgrading the server does not expand client grants.",
{ fix: auth?.grantProjectionDegraded ? migrationsFix(HTTP_HOST) : grantFix(auth, {
token: ['--refresh-operations', '--add', op.name],
client: ['--allowed-operations', [...new Set([...(auth?.allowedOperations ?? []), op.name])].join(',')],
}, `Adds ${op.name} to this connection's approved operations; only the brain host operator can change grants.`) });
err.detail = 'fence=operation_grant';
throw err;
}
const degraded = auth?.fenceProjectionDegraded === true;
if (degraded) {
const err = opError(
'permission_denied',
`${op.name}: this brain's oauth_clients projection is missing bound_slug_prefixes, so client write bindings cannot be evaluated. Refusing every non-read operation rather than running unfenced.`,
"The brain host's operator applies the pending migrations (command in fix); then repeat the call.",
{ fix: migrationsFix(HTTP_HOST) },
);
// Amendment 33 / D10: OP-level fence denial — the tools/list filter
// (opAllowedForBoundClient, the same predicate) should have hidden this
// op, so serve-http counts it toward the honest-catalog metric
// (status='denied_after_list'). key=value detail grammar (WP1).
err.detail = 'fence=op';
throw err;
}
const clientId = safeClientId(auth);
const err = opError(
'permission_denied',
`${op.name} is not available to slug-bound clients: it can write outside client ${auth?.clientId ?? '(unknown)'}'s bound_slug_prefixes (${(auth?.boundSlugPrefixes ?? []).join(', ')}).`,
`Use put_page / add_timeline_entry / add_link under your own prefixes, or ask the brain host's operator to clear the binding${clientId ? ` (gbrain auth rescope-client ${clientId} --bound-slug-prefixes none)` : ''}.`,
);
// Amendment 33 / D10: op-level, not argument-level — see above. The
// slug-prefix ARGUMENT denials (enforceClientSlugFence) deliberately do
// NOT carry this marker: a listed write op denying an out-of-fence slug
// is legitimate and excluded from the metric.
err.detail = 'fence=op';
throw err;
}
/**
* Allowlist validator for uploaded file basenames. Rejects control chars, backslashes,
* RTL overrides (\u202E), leading dot (hidden files) and leading dash (CLI flag confusion).
* Allows extension dots and underscores. Max 255 chars.
*/
export function validateFilename(name: string): void {
if (typeof name !== 'string' || name.length === 0) {
throw opError('invalid_params', 'Filename must be a non-empty string', 'Pass a file name such as report-2026.pdf.');
}
if (name.length > 255) {
throw opError('invalid_params', 'Filename exceeds 255 characters', 'Shorten the file name to 255 characters or fewer.');
}
// v0.32.7: CJK ranges (Han / Hiragana / Katakana / Hangul) allowed in filenames.
// Leading-dot / leading-dash rejection preserved.
const FILENAME_RE = new RegExp(`^[a-zA-Z0-9${CJK_SLUG_CHARS}][a-zA-Z0-9${CJK_SLUG_CHARS}._\\-]*$`);
if (!FILENAME_RE.test(name)) {
throw opError('invalid_params', `Invalid filename: ${name} (allowed: alphanumeric, CJK, dot, underscore, hyphen — no leading dot/dash, no control chars or backslash)`,
'Rename the file to letters, digits, CJK, dots, underscores and hyphens, starting with a letter or digit (e.g. report-2026.pdf).');
}
}
/**
* v0.34.1 (#861, D9 — P0 leak seal): resolve the source-scope filter for a
* read-side op handler. Returns an opts fragment ready to spread into the
* engine call.
*
* Precedence:
* 1. `ctx.auth?.allowedSources` (federated read, #876) → emits
* `{sourceIds: [...]}`. Federated semantics subsume the scalar case.
* 2. `ctx.sourceId` (scalar) → emits `{sourceId: '...'}`.
* 3. Neither set → emits `{}`. Local CLI callers (and tests that don't
* populate ctx) keep the pre-v0.34 unscoped behavior.
*
* Both fields default to the engine's "no filter" behavior individually,
* so unset values are safe — the engine sees the same shape it did
* pre-v0.34. The leak this guards against is an authenticated MCP client
* whose ctx.sourceId IS set but whose engine call was constructed without
* threading it (operations.ts:968/1076/1092/935/1469/1471/2241 pre-fix).
*
* Helper rather than inline so every read-side handler routes through the
* same precedence ladder — drift between sites is the bug class.
*/
export function sourceScopeOpts(ctx: OperationContext): { sourceId?: string; sourceIds?: string[] } {
if (ctx.sourceId === NO_SOURCES || ctx.auth?.sourceId === NO_SOURCES) throw noSourceGrantError(undefined, ctx.auth);
const allowed = ctx.auth?.allowedSources;
// Treat an empty `allowedSources: []` as "no federated read scope" — the
// op-handler defers to scalar `ctx.sourceId` below. An attacker-controlled
// value of `[]` MUST NOT widen scope to "all sources" by being interpreted
// as "no filter."
if (allowed && allowed.length > 0) return { sourceIds: allowed };
// #1712: the __all__ sentinel spans the brain — but ONLY for trusted local
// callers (strictly `remote === false`). For remote/untrusted callers the
// literal stays as-is: it can never match a real source id (underscores are
// rejected at creation), so the read fail-closes to empty rather than
// widening past the caller's grant. Do NOT "simplify" this to `{}`.
if (ctx.sourceId === ALL_SOURCES) {
return ctx.remote === false ? {} : { sourceId: ctx.sourceId };
}
if (ctx.sourceId) return { sourceId: ctx.sourceId };
if (ctx.remote !== false && allowed !== undefined) {
throw opError('permission_denied', 'No readable source is granted for this request.',
"This connection's grant names no readable source; ask the brain host's operator to grant one (command in fix).",
{ fix: sourceGrantFix(ctx.auth) });
}
return {};
}
/**
* Confine an explicitly named source id to the caller's resolved READ scope
* (#4433 wave-L posture; used by sources_status — the destructive
* sources_remove keys on `assertSourceInCallerWriteScope` below instead):
* EVERY untrusted caller (anything not strictly `remote === false`) may only
* name a source inside the canonical `sourceScopeOpts` ladder — federated
* grant > scalar bound source. An out-of-scope id answers `not_found`, exactly
* like a nonexistent source (anti-enumeration). The trusted local CLI passes
* unconditionally (full operator view). Returns void; throws otherwise.
*/
export function assertSourceInCallerScope(ctx: OperationContext, id: string): void {
if (ctx.remote === false) return;
const scope = sourceScopeOpts(ctx);
const allowed = scope.sourceIds ?? (scope.sourceId !== undefined ? [scope.sourceId] : null);
if (allowed && !allowed.includes(id)) {
throw opError('not_found', `Unknown source: ${id}`, 'Pass a source id from sources_list, which lists the sources this connection can read.',
{ fix: sourcesListFix('Lists the sources this connection can read.') });
}
}
/**
* WRITE-authority twin of `assertSourceInCallerScope`, for the DESTRUCTIVE
* source ops (`sources_remove`). Federation (`ctx.auth.allowedSources`) is READ
* authority by contract (contract.ts: "source ids this OAuth client may READ
* from") and confers no removal right, so this helper deliberately does NOT
* consult the `sourceScopeOpts` ladder — a client bound to write `alpha` with
* `federated_read: [alpha, beta]` may read `beta` but never cascade-delete it.
*
* Rules, in order:
* - trusted local CLI (`remote === false`) passes unconditionally;
* - an untrusted caller that is BOUND — carries a write source
* (`ctx.auth.sourceId`, falling back to `ctx.sourceId`; the same notion as
* delete_page/restore_page's write gate) and/or a federated grant — may
* name ONLY its write source; a bound caller with no write source (or the
* `__all__` sentinel as its source) may name nothing;
* - an UNBOUND untrusted caller (neither axis set — an operator-registered
* client with no source binding) keeps full authority, unchanged.
* Out-of-authority ids answer `not_found`, byte-identical to a nonexistent
* id (anti-enumeration; the same shape the read helper uses, so a caller
* cannot tell "hidden" from "absent"). Returns void; throws otherwise.
*/
export function assertSourceInCallerWriteScope(ctx: OperationContext, id: string): void {
if (ctx.remote === false) return;
const writeSource = ctx.auth?.sourceId ?? ctx.sourceId;
const bound = writeSource !== undefined || ctx.auth?.allowedSources !== undefined;
if (!bound) return;
if (writeSource === undefined || writeSource === ALL_SOURCES || id !== writeSource) {
throw opError('not_found', `Unknown source: ${id}`, "Name this connection's own write source; sources_list shows the sources it can read.",
{ fix: sourcesListFix('Lists the sources this connection can read.') });
}
}
/** Holder permissions are independent of the operator's page-visibility opt-out. */
export function readHolders(ctx: OperationContext): string[] | undefined {
return ctx.remote === false ? ctx.takesHoldersAllowList : ctx.takesHoldersAllowList ?? ['world'];
}
/** Resolve policy once at the operation boundary; callers may supply a canonical per-call scope. */
export async function readPolicyOpts(
ctx: OperationContext,
scope: PageReadScope = sourceScopeOpts(ctx),
): Promise<PageReadPolicy> {
return {
...scope,
excludePrivate: await resolveExcludePrivatePages(ctx.engine, ctx.remote),
requireSafeChunks: ctx.remote !== false,
takesHoldersAllowList: readHolders(ctx),
};
}
/** Map the operation-layer scope names onto runThink's public options. */
export function thinkSourceScopeOpts(ctx: OperationContext): {
sourceId?: string;
allowedSources?: string[];
} {
const scope = sourceScopeOpts(ctx);
return scope.sourceIds !== undefined
? { allowedSources: scope.sourceIds }
: scope.sourceId !== undefined
? { sourceId: scope.sourceId }
: {};
}
/**
* #2200: source scope for the LINK read ops (get_links / get_backlinks). A link
* row references three pages (from, to, origin); the engine's federated
* (`sourceIds[]`) branch scopes ALL THREE, but its scalar (`sourceId`) branch
* scopes only the near endpoint — by design, because trusted internal callers
* (reconcileLinks, back-link validators, enrich) call the engine directly with a
* scalar scope and need the cross-source view.
*
* An UNTRUSTED remote caller carrying only a scalar scope (a legacy bearer token
* or a pre-`federated_read` OAuth client) would otherwise hit that scalar branch
* and have a foreign far/origin slug disclosed. So for remote callers we promote a
* scalar scope to a single-element `sourceIds:[id]`, routing them through the
* all-endpoint branch. Trusted local CLI (`ctx.remote === false`) keeps the scalar
* cross-source view, and a federated array passes through unchanged. `scope`
* defaults to the ambient ladder; the link ops pass their resolved per-call
* scope (`federatedSearchScope`) so the same promotion applies to it.
*/
export function linkReadScopeOpts(
ctx: OperationContext,
scope: { sourceId?: string; sourceIds?: string[] } = sourceScopeOpts(ctx),
): { sourceId?: string; sourceIds?: string[] } {
if (ctx.remote !== false && scope.sourceId && !scope.sourceIds) {
return { sourceIds: [scope.sourceId] };
}
return scope;
}
/**
* Resolve a per-call requested source scope against the caller's trust + grant.
* FAIL-CLOSED: anything not strictly `ctx.remote === false` is untrusted.
*
* This is the SINGLE resolver for every read op that accepts a per-call
* `source_id` / `all_sources` parameter (query, code_callers, code_callees,
* get_page, search_by_image, code_blast, code_flow). Inlining the `__all__`
* branch per handler is the bug class that leaked cross-source reads (#1924,
* #1371): a remote client could pass `source_id: '__all__'` to opt out of its
* grant, or pass an explicit out-of-grant `source_id` that was never checked.
*
* - `__all__` / `all_sources`:
* trusted local (remote === false) → `{}` (spans the whole brain)
* remote → the caller's grant (sourceScopeOpts)
* - explicit `source_id`:
* remote, outside the caller's grant or scalar scope, and outside
* `explicitReads` (when passed) → permission_denied
* otherwise → `{ sourceId }`
* - neither → the caller's grant (sourceScopeOpts).
*
* `explicitReads` (#5081) is the explicit-read admission set; only
* `federatedSearchScope` passes it. The other callers (image, loops,
* code-intel) pass nothing and keep denying every id outside the scope, with
* the original hint.
*
* `code_traversal_cache_clear` is intentionally NOT a caller — it is localOnly
* and carries its own destructive D8 all_sources guard.
*/
export function resolveRequestedScope(
ctx: OperationContext,
sourceIdParam: string | undefined,
allSourcesParam = false,
explicitReads?: readonly string[],
): { sourceId?: string; sourceIds?: string[] } {
const wantsAll = allSourcesParam || sourceIdParam === ALL_SOURCES;
if (wantsAll) {
return ctx.remote === false ? {} : sourceScopeOpts(ctx);
}
if (sourceIdParam !== undefined) {
const scope = sourceScopeOpts(ctx);
const granted = scope.sourceIds !== undefined
? scope.sourceIds.includes(sourceIdParam)
: scope.sourceId === sourceIdParam;
if (ctx.remote !== false && !granted && !explicitReads?.includes(sourceIdParam)) {
throw opError(
'permission_denied',
'Requested source is outside your granted sources',
explicitReads === undefined
? 'Request access to this source, or omit source_id to search within your grant.'
: explicitReadDeniedHint(ctx, sourceIdParam),
explicitReads === undefined
? { fix: sourcesListFix('Lists the sources this connection can read; pass one of them as source_id, or omit it.') }
: { docs: EXPLICIT_READ_DOCS, fix: explicitReadDeniedFix(ctx, sourceIdParam) },
);
}
return { sourceId: sourceIdParam };
}
return sourceScopeOpts(ctx);
}
const EXPLICIT_READ_DOCS = 'docs/guides/multi-source-brains.md#explicit-reads-from-a-bound-agent-connection';
/**
* #5081 / DX-O6(c): why an explicit read was refused, with the exact command
* that would admit it. A granted token is told about its grant; a connection
* bound by GBRAIN_SOURCE or a .gbrain-source pin is told about the binding
* (its own opt-out, the target's opt-out, or a target that was never
* federated); an unbound connection is told the target is not federated.
*/
function explicitReadDeniedHint(ctx: OperationContext, id: string): string {
const auth = ctx.auth;
if (auth !== undefined && (auth.allowedSources !== undefined || auth.hasSourceGrant !== false)) {
const granted = auth.allowedSources ?? (auth.sourceId !== undefined ? [auth.sourceId] : []);
return auth.principal?.kind === 'oauth_client'
? `Your token is not granted ${id}; ask the brain owner to grant it ` +
`(gbrain auth rescope-client ${auth.principal.id} --federated-read ${[...granted, id].join(',')}).`
: `Your token is not granted ${id}; ask the brain owner to grant it.`;
}
const binding = ctx.explicitReadBinding;
if (binding === undefined) {
return `${id} is not federated; the brain owner can run \`gbrain sources federate ${id}\` on the brain host, ` +
'or omit source_id to read within this connection\'s sources.';
}
const bound = `This connection is bound to source ${binding.sourceId} (${binding.via}).`;
const unbind = binding.via === 'GBRAIN_SOURCE'
? 'start this connection without GBRAIN_SOURCE'
: 'start this connection outside the directory pinned by .gbrain-source';
if (binding.optedOut.includes(binding.sourceId)) {
return `${bound} ${binding.sourceId} opted out of federation (federated: false), so it reads no other source; ` +
`the brain owner can run \`gbrain sources federate ${binding.sourceId}\` on the brain host, or ${unbind}.`;
}
const reason = binding.optedOut.includes(id) ? 'opted out of federation (federated: false)' : 'is not federated';
return `${bound} ${id} ${reason}; the brain owner can run \`gbrain sources federate ${id}\` on the brain host, or ${unbind}.`;
}
/**
* The command behind explicitReadDeniedHint: widen the token's grant, or
* federate the source this connection's reads stop at (host-only either way).
*/
function explicitReadDeniedFix(ctx: OperationContext, id: string): Action | undefined {
const auth = ctx.auth;
if (auth !== undefined && (auth.allowedSources !== undefined || auth.hasSourceGrant !== false)) {
const granted = auth.allowedSources ?? (auth.sourceId !== undefined ? [auth.sourceId] : []);
const wanted = [...new Set([...granted, id])].join(',');
return grantFix(auth, { token: ['--sources', wanted], client: ['--federated-read', wanted] },
`Adds ${id} to this connection's readable sources; only the brain host operator can change grants.`);
}
const binding = ctx.explicitReadBinding;
const target = binding?.optedOut.includes(binding.sourceId) ? binding.sourceId : id;
if (!isValidSourceId(target)) return undefined;
return hostFix(ctx, ['gbrain', 'sources', 'federate', target],
`Lets unqualified and explicit reads from other connections include ${target}; only the trusted CLI on the brain host changes federation.`);
}
/**
* #5081: the sources an explicit `source_id` read may name beyond the scope.
* A grant (`ctx.auth.allowedSources`) governs alone. Otherwise a bound stdio
* connection uses its binding's set, and an unbound connection uses the set
* its unqualified reads already span (`localFederatedSourceIds`), so an
* explicit read there is never wider than an unqualified one.
*/
function explicitReadAdmission(ctx: OperationContext): readonly string[] {
if (ctx.auth?.allowedSources !== undefined) return [];
return ctx.explicitReadBinding?.sourceIds ?? ctx.localFederatedSourceIds ?? [];
}
/**
* #4329: parse a per-call `source_id` param. Pre-fix, get_page / delete_page /
* restore_page had NO source_id in their contracts, so an agent-passed
* source_id was SILENTLY dropped and the op acted on ctx.sourceId —
* soft-deleting the WRONG row on a multi-source brain while returning a
* success that named the requested slug. A caller-supplied value is either
* honored or rejected loudly — never ignored. `allowAll` admits the
* `__all__` sentinel for read ops (resolveRequestedScope collapses it per
* trust); destructive ops target exactly one source and reject it.
*/
export function parseSourceIdParam(
raw: unknown,
opName: string,
opts?: { allowAll?: boolean },
): string | undefined {
if (raw === undefined || raw === null) return undefined;
if (typeof raw === 'string') {
if (raw === ALL_SOURCES) {
if (opts?.allowAll === true) return raw;
throw opError(
'invalid_params',
`${opName}: source_id '${ALL_SOURCES}' is not a valid target — this op acts on exactly one source.`,
'Pass the single source_id of the row to target, or omit source_id to use the ambient source scope.',
{ fix: sourcesListFix('Lists the source ids this caller can name.') },
);
}
if (isValidSourceId(raw)) return raw;
}
throw opError(
'invalid_params',
`${opName}: invalid source_id ${JSON.stringify(raw)} — must be 1-32 lowercase alnum chars with optional interior hyphens.`,
'Pass a registered source id (sources_list shows them), or omit source_id to use the ambient source scope.',
{ fix: sourcesListFix('Lists the source ids this caller can name.') },
);
}
/**
* #2561 / #3242 — source scope for the page-visibility read ops (`search`,
* `query`, `get_page`, `list_pages`, `resolve_slugs`).
*
* Delegates to `resolveRequestedScope` (the single trust+grant resolver), then
* widens an UNQUALIFIED scalar scope to the transport-computed federated set
* (`ctx.localFederatedSourceIds`, resolved source first). This is what makes
* `sources add --federated` mean something: a federated source participates in
* unqualified reads (#3242 — pages ingested into a `federated: true` source
* were invisible to get_page/search/list_pages while resolve_slugs leaked them).
*
* An explicit per-call `source_id` is admitted inside the explicit-read set
* (#5081, `explicitReadAdmission`): the binding's set for a connection bound
* by GBRAIN_SOURCE or a .gbrain-source pin, otherwise the federated set.
*
* The expansion NEVER applies when:
* - a concrete per-call `source_id` was passed (explicit wins);
* - the resolver already produced a federated array (OAuth grant governs);
* - the transport didn't populate `localFederatedSourceIds` (see that
* field's doc: it is transport-computed and never derived from
* caller-controlled params — so trust stays fail-closed).
*
* The read-only `__all__` sentinel is equivalent to an unqualified read when
* it resolves to the caller's scalar floor. It may therefore use the same
* transport-computed federated set, but never widens an OAuth grant.
*
* Deliberately NOT inside `sourceScopeOpts`: code-intel ops collapse a
* multi-element scope to an error (`resolveCodeIntelScope`), and the remaining
* scalar reads (get_links, get_chunks, …) keep their long-standing behavior.
*/
export function federatedSearchScope(
ctx: OperationContext,
sourceIdParam?: string,
): { sourceId?: string; sourceIds?: string[] } {
const scope = resolveRequestedScope(ctx, sourceIdParam, false, explicitReadAdmission(ctx));
if (
(sourceIdParam === undefined || sourceIdParam === ALL_SOURCES) &&
ctx.auth?.allowedSources === undefined &&
scope.sourceId !== undefined &&
scope.sourceIds === undefined &&
ctx.localFederatedSourceIds !== undefined &&
ctx.localFederatedSourceIds.length > 1
) {
return { sourceIds: ctx.localFederatedSourceIds };
}
return scope;
}
/**
* #4620 — the #1712 rule on the op path: an EXPLICIT per-call `source_id`
* that names no live (unarchived) source fails loudly instead of silently
* scoping the read to a source with no rows (page_not_found with a
* soft-delete hint, or an empty list). Reachable because a federated_read
* grant / `.gbrain-source` dotfile has no FK and outlives `sources remove`.
* Call it AFTER `federatedSearchScope` so the grant check has already run —
* it can only name a source the caller was granted, never a cross-grant
* existence oracle. `__all__` and an omitted param skip it (nothing explicit
* to verify). Async on purpose: `resolveRequestedScope` stays sync for its
* ~10 engine-free call sites.
*/
export async function assertExplicitSourceLive(
ctx: OperationContext,
sourceIdParam: string | undefined,
): Promise<void> {
if (sourceIdParam === undefined || sourceIdParam === ALL_SOURCES) return;
// Point lookup, not listAllSources (wave review): this runs on every
// search/query/get_page/list_pages call that names a source, and the full
// enumeration hauled every row's config JSONB across the wire each time.
// Same liveness predicate as listAllSources' default filter.
const live = await ctx.engine.executeRaw<{ ok: number }>(
`SELECT 1 AS ok FROM sources WHERE id = $1 AND archived IS NOT TRUE LIMIT 1`,
[sourceIdParam],
);
if (live.length > 0) return;
const clientId = safeClientId(ctx.auth);
throw opError(
'unknown_source',
`source '${sourceIdParam}' does not exist (removed or archived)`,
'Omit source_id to read within your grant, or pick an id from sources_list. ' +
'If a .gbrain-source dotfile or a federated_read grant still names it, update them ' +
`(the brain host operator rescopes ${clientId ? `client ${clientId}'s` : 'the'} federated_read grant; gbrain doctor lists dangling grants).`,
{ fix: sourcesListFix('Lists the live sources this caller can read.') },
);
}
/**
* #4109 — preflight a page endpoint for a same-source graph mutation
* (add_link / add_timeline_entry).
*
* These ops intentionally write only to `ctx.sourceId`, while page reads may
* span the caller's federated visibility scope. When the requested slug
* exists only in another READABLE source, report that source boundary
* explicitly (`permission_denied`) instead of the misleading "not found" the
* engine's exact-source resolution emits — which surfaced over MCP as
* `internal_error` and made intentional source isolation look like data
* loss. Sources outside the caller's read grant remain indistinguishable
* from absence: the diagnostic lookup uses `federatedSearchScope`, the SAME
* visibility ladder as `get_page`, so this preflight can never become a
* cross-source existence oracle.
* Remote-owned subagents also require visibility of existing write targets;
* put_page allows creation only when no row exists, including soft-deleted rows.
*/
export async function requireWritablePage(
ctx: OperationContext,
slug: string,
operation: string,
endpoint: 'from' | 'to' | 'page',
allowCreate = false,
): Promise<void> {
const writeSource = ctx.sourceId || 'default';
// Graph rows may reference soft-deleted pages — includeDeleted preserves
// that engine mutation contract for the exact write source. The federated
// diagnostic lookup below intentionally stays active-page-only so a
// soft-deleted foreign page is never disclosed.
const writable = await ctx.engine.getPage(slug, {
sourceId: writeSource,
includeDeleted: true,
});
// GBRA-218 / GBRA-431: a page the remote caller cannot read answers exactly as a missing slug. A delegated subagent
// write keeps its own privacy refusal below.
const hidden = !!writable && await remoteTargetHidden(ctx.engine, ctx.remote, writeSource, slug, ctx.viaSubagent === true);
if (writable && !hidden) {
if (ctx.viaSubagent === true && ctx.auth && isPrivatePage(writable)
&& await resolveExcludePrivatePages(ctx.engine, ctx.remote)) {
throw opError('permission_denied', `${operation}: this page is outside your write visibility.`,
'The page is private and this delegated write cannot see it; choose a different slug, or report the refusal to the user.');
}
return;
}
if (allowCreate) {
if (hidden) throw pageNotVisibleError();
return;
}
const visibleScope = federatedSearchScope(ctx);
// GBRA-218: the diagnostic reads only the other sources, under the caller's read policy, so a page the caller cannot
// read there (or a hidden row in the write source) answers exactly as a missing slug.
const otherSources = (visibleScope.sourceIds ?? (visibleScope.sourceId !== undefined ? [visibleScope.sourceId] : [])).filter(id => id !== writeSource);
if (otherSources.length) {
const visible = await ctx.engine.getPage(slug, await readPolicyOpts(ctx, { sourceIds: otherSources }));
if (visible && !await remoteTargetHidden(ctx.engine, ctx.remote, visible.source_id, slug)) {
throw opError(
'permission_denied',
`${operation}${endpoint === 'page' ? '' : ` ${endpoint}`} page "${slug}" is readable from source "${visible.source_id}" but this client writes to source "${writeSource}".`,
'Graph mutations are same-source by design. Use a client whose write source owns the page, or import the page into your write source first.',
{ why: `The page lives in source "${visible.source_id}"; this connection writes only to "${writeSource}".` },
);
}
}
throw opError(
'page_not_found',
`${operation}${endpoint === 'page' ? '' : ` ${endpoint}`} page "${slug}" was not found in writable source "${writeSource}".`,
`Check the slug (fuzzy lookup in fix), or create the page in source "${writeSource}" with put_page first.`,
withFix(getPageFix(slug, `Looks the slug up in source ${writeSource} with fuzzy matching.`, { sourceId: writeSource, fuzzy: true })),
);
}
/**
* #4109 — reclassify a typed engine miss (PageMissingError) raised by the
* mutation itself, after `requireWritablePage` already passed: the page was
* hard-deleted between preflight and mutation. Re-running the preflight
* regenerates the same permission_denied / page_not_found envelope; if the
* page reappeared between those reads (restore race), fall through to a
* deterministic miss instead of leaking the raw engine error as
* internal_error.
*/
export async function reclassifyMutationTimePageMiss(
ctx: OperationContext,
slug: string,
operation: string,
endpoint: 'from' | 'to' | 'page',
): Promise<never> {
await requireWritablePage(ctx, slug, operation, endpoint);
const writeSource = ctx.sourceId || 'default';
throw opError(
'page_not_found',
`${operation}${endpoint === 'page' ? '' : ` ${endpoint}`} page "${slug}" was unavailable in writable source "${writeSource}" during the mutation.`,
'The page was deleted or restored while the write ran; read its current state (fix) before deciding whether to repeat the write.',
withFix(getPageFix(slug, 'Shows whether the page exists now, including a soft-deleted row.', { sourceId: writeSource, includeDeleted: true })),
);
}
/**
* Code-intel adapter for `resolveRequestedScope`. Graph traversal
* (code_callers/code_callees/code_blast/code_flow) is single-source by design —
* the engine APIs and the traversal cache key take ONE `sourceId` string, not a
* federated array. So this collapses the resolver's output to `{allSources,
* sourceId}`, fail-closed:
*
* - resolver → one source (scalar or single-element grant) → that source
* - resolver → multi-source grant (federated remote client) → reject: ask the
* caller to specify which granted source (we must not silently span all)
* - resolver → empty scope → `allSources` ONLY for trusted local callers; a
* remote caller with no source in scope is denied, never widened to all.
*/
export function resolveCodeIntelScope(
ctx: OperationContext,
sourceIdParam: string | undefined,
allSourcesParam = false,
opName = 'code_callers',
): { allSources: boolean; sourceId?: string } {
const scope = resolveRequestedScope(ctx, sourceIdParam, allSourcesParam);
if (scope.sourceId) return { allSources: false, sourceId: scope.sourceId };
if (scope.sourceIds && scope.sourceIds.length === 1) {
return { allSources: false, sourceId: scope.sourceIds[0] };
}
if (scope.sourceIds && scope.sourceIds.length > 1) {
throw invalidParam(ctx, opName, 'source_id',
'Code traversal runs against a single source. Specify source_id (one of your granted sources).',
{ choices: scope.sourceIds });
}
// Empty scope: span everything only for trusted local callers; a remote caller
// that reached here has no source in scope and must NOT get cross-source results.
if (ctx.remote === false) return { allSources: true, sourceId: undefined };
throw opError(
'permission_denied',
'No source in scope for this request.',
'Pass source_id naming one of your granted sources (sources_list shows them).',
{ fix: sourcesListFix('Lists the sources this connection can read.') },
);
}
/**
* Federated re-route for the graph four (code_callers / code_callees /
* code_blast / code_flow) — the #3242 sibling. An UNQUALIFIED graph query from
* a no-grant caller collapses to the scalar seed source (usually 'default'),
* which on vault+code brains holds no code — so the graph ops report
* `not_built` while code_def / code_refs (which widen across
* `ctx.localFederatedSourceIds`) answer fine. Graph traversal must stay
* single-source (engine API + cache key take ONE sourceId), so instead of
* widening we RE-ROUTE: when the collapsed source has no code chunks and
* exactly one source in the caller's federated read set does, traverse that
* one — the multi-source cousin of the CLI's `sole_non_default` tier (#1434).
*
* Fail-closed, in order: never fires when the caller passed `source_id` or
* `all_sources` (explicit wins), when the scope is already brain-wide, when a
* grant is present (`ctx.auth.allowedSources` governs — same guard as
* `federatedSearchScope`), when there is no federated read set (a granted
* token never widens), when the collapsed source itself has code, or when
* zero or 2+ federated sources have code (ambiguous → original scope stands
* and readiness reports honestly). Probe errors also keep the original scope.
*/
export async function routeCodeIntelScope(
ctx: OperationContext,
sourceIdParam: string | undefined,
allSourcesParam = false,
opName = 'code_callers',
): Promise<{ allSources: boolean; sourceId?: string }> {
const scope = resolveCodeIntelScope(ctx, sourceIdParam, allSourcesParam, opName);
if (
sourceIdParam !== undefined || allSourcesParam ||
scope.allSources || scope.sourceId === undefined ||
ctx.auth?.allowedSources !== undefined ||
!ctx.localFederatedSourceIds || ctx.localFederatedSourceIds.length < 2
) {
return scope;
}
try {
const { codeChunksExist } = await import('../code-graph-readiness.ts');
if (await codeChunksExist(ctx.engine, scope.sourceId)) return scope;
const withCode: string[] = [];
for (const id of ctx.localFederatedSourceIds) {
if (id === scope.sourceId) continue;
if (await codeChunksExist(ctx.engine, id)) withCode.push(id);
}
if (withCode.length === 1) return { allSources: false, sourceId: withCode[0] };
} catch { /* probe failure → original scope stands */ }
return scope;
}
/**
* T4/D5 — resolve a per-call search-mode override. Honored ONLY for trusted/
* local callers (ctx.remote === false) so a remote OAuth client can't escalate
* to the costly tokenmax bundle. Local + unknown mode → loud reject; remote +
* mode → silently ignored (server-configured mode wins). Returns undefined to
* mean "use the configured mode".
*/
export function resolvePerCallMode(ctx: OperationContext, raw: unknown, opName = 'query'): string | undefined {
if (typeof raw !== 'string' || raw.length === 0) return undefined;
if (ctx.remote !== false) return undefined; // remote can't select mode
if (!isSearchMode(raw)) {
throw invalidParam(ctx, opName, 'mode', `Unknown search mode '${raw}'. Valid: conservative, balanced, tokenmax.`,
{ choices: ['conservative', 'balanced', 'tokenmax'], example: 'balanced' });
}
return raw;
}
/** T4 — stamp evidence/create_safety on a result set, fail-soft. */
export function stampEvidenceSafe(results: SearchResult[], opts?: EvidenceOpts): void {
try { stampEvidence(results, opts); } catch { /* non-fatal */ }
}
export function stampDeepResearchIds(results: SearchResult[]): void {
// Large pages (T24): a hit past the page's first chunk names its chunk, so fetch can return that evidence from a page too
// large to send whole (the first window already holds chunk 0, whose id stays the plain page id).
for (const r of results) if (r.result_type !== 'fact') (r as SearchResult & { id?: string }).id = encodeDeepResearchId(r.source_id, r.slug,
Number.isSafeInteger(r.chunk_id) && r.chunk_id > 0 && r.chunk_index > 0 ? { chunkId: r.chunk_id } : undefined);
}
/** T4 — shared eval-capture for the `search` op (keyword-only + cheap-hybrid paths). */
export function maybeCaptureSearch(
ctx: OperationContext,
queryText: string,
results: SearchResult[],
latency_ms: number,
vectorEnabled: boolean,
meta?: HybridSearchMeta | null,
): void {
if (!isEvalCaptureEnabled(ctx.config)) return;
void captureEvalCandidate(
ctx.engine,
{
tool_name: 'search',
query: queryText,
results,
meta: meta ?? { vector_enabled: vectorEnabled, detail_resolved: null, expansion_applied: false },
latency_ms,
remote: ctx.remote ?? false,
expand_enabled: false,
detail: null,
job_id: ctx.jobId ?? null,
subagent_id: ctx.subagentId ?? null,
},
{ scrub_pii: isEvalScrubEnabled(ctx.config) },
);
}