Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* v0.39 trust-boundary contract test (GAP 3 of the e2e-test-wave audit).
*
* Hybrid design (D7 — pure + targeted handler invocation):
*
* - Pure assertions over ALL operations (~74 ops): scope annotations
* present + correct; localOnly ops are filtered out of the canonical
* mcpOperations list; hasScope semantics work for the standard tiers.
*
* - Handler-invocation cases for ops that are NOT localOnly but DO
* enforce remote/scope at the handler layer (defense-in-depth where
* it actually fires in production):
*
* * submit_job — name='shell' + ctx.remote=true MUST reject
* (the HTTP MCP shell-job RCE class, F7b)
* * search_by_image — image_path + ctx.remote=true MUST reject
* (D18 P0 source-isolation leak class)
*
* `file_upload` and `sync_brain` are intentionally NOT in the
* handler-invocation set — both are localOnly, so the canonical
* filter removes them from mcpOperations and the HTTP path never
* reaches their handlers. Calling their handlers with remote=true
* tests an impossible production path (codex CMT-3). The defense-
* in-depth strict-mode checks inside those handlers still exist;
* they're proven by the localOnly-filtered-out contract here.
*
* Criterion for the curated sensitive-ops list:
* ops whose HANDLER (not transport) has been broken historically.
* Add an op here when a real exploit class is fixed at the handler
* level; remove only when the handler-level defense becomes
* structurally unreachable (e.g., the op becomes localOnly).
*
* Companion guard at scripts/check-operations-filter-bypass.sh enforces
* the canonical filter site so a future HTTP route can't bypass it.
*
* Dynamic sibling: test/remote-privacy-sweep.test.ts — a corpus-seeded
* sweep of EVERY non-localOnly op through dispatchToolCall asserting no
* private-sentinel leakage (the #4546/#4549 read-leak class). This file
* pins the static contract + curated handler probes; the sweep catches
* leaks in ops neither file has heard of yet. Same doctrine, two layers.
*/
import { describe, test, expect, beforeAll, afterAll, beforeEach } from 'bun:test';
import { readdirSync, readFileSync } from 'node:fs';
import { join } from 'node:path';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { resetPgliteState } from './helpers/reset-pglite.ts';
import { operations, type OperationContext } from '../src/core/operations.ts';
import { verbOperations } from '../src/core/verbs.ts';
import { MinionQueue } from '../src/core/minions/queue.ts';
import { hasScope, operationScopesAllowed } from '../src/core/scope.ts';
import { disposePersistenceConsumer } from '../src/core/persistence/service.ts';
let engine: PGLiteEngine;
beforeAll(async () => {
engine = new PGLiteEngine();
await engine.connect({});
await engine.initSchema();
}, 60_000);
afterAll(async () => {
await disposePersistenceConsumer(engine);
await engine.disconnect();
});
beforeEach(async () => {
await disposePersistenceConsumer(engine);
await resetPgliteState(engine);
});
// Minimal context factory — every test that invokes a handler builds
// one of these. Defaults to remote=true (untrusted) because that's the
// trust posture the bug-class regressions live in; tests opt back to
// local trust by overriding remote=false.
function makeContext(overrides: Partial<OperationContext> = {}): OperationContext {
return {
engine: engine as any,
config: { engine: 'pglite', embedding_disabled: true },
logger: console as any,
dryRun: false,
remote: true,
sourceId: 'default',
...overrides,
};
}
describe('operations contract — every op has scope + correct mutability shape', () => {
test('every op declares a scope annotation', () => {
for (const op of operations) {
expect(op.scope, `op "${op.name}" missing scope annotation`).toBeDefined();
}
});
test('every mutating op has a write-class scope (not "read")', () => {
const WRITE_CLASS_SCOPES = new Set([
'write',
'admin',
'sources_admin',
'users_admin',
'agent',
]);
// Remote-gated exception (#2598, same allowlist as test/oauth.test.ts):
// `think` is read-scoped for OAuth/MCP because its handler forces
// save/take OFF for remote callers before persistence — pinned by
// test/takes-mcp-allowlist.test.ts. Local CLI can still persist.
// WP4/D9: request_tools is read-scoped + mutating — its only write (the
// {surface} persist branch) self-enforces the D2 ceiling, the operator
// lock, and a per-client rate limit (test/request-tools.test.ts pins all
// three); read scope keeps discovery available to every token class.
const REMOTE_READ_ONLY_MUTATING_OPS = new Set(['think', 'request_tools']);
for (const op of operations) {
if (op.mutating === true) {
if (['join_brain', 'sync_brain_skills', 'leave_brain'].includes(op.name)) {
expect(op.scope).toBe('read');
expect(op.requiredScopes).toEqual(['skills_member_self']);
expect(operationScopesAllowed(['read'], op)).toBe(false);
expect(operationScopesAllowed(['admin'], op)).toBe(false);
expect(operationScopesAllowed(['read', 'skills_member_self'], op)).toBe(true);
continue;
}
if (REMOTE_READ_ONLY_MUTATING_OPS.has(op.name)) {
expect(op.scope, `remote-gated mutating op "${op.name}" should be read-scoped`).toBe('read');
continue;
}
expect(
WRITE_CLASS_SCOPES.has(op.scope ?? 'read'),
`mutating op "${op.name}" has read-tier scope "${op.scope}"; expected one of ${[...WRITE_CLASS_SCOPES].join('/')}`,
).toBe(true);
}
}
});
test('scope is one of the documented enum values', () => {
const KNOWN_SCOPES = new Set([
'read',
'write',
'admin',
'sources_admin',
'users_admin',
'agent',
]);
for (const op of operations) {
expect(
KNOWN_SCOPES.has(op.scope!),
`op "${op.name}" has unknown scope "${op.scope}"`,
).toBe(true);
}
});
test('state-changing job controls declare mutating metadata', () => {
for (const name of ['pause_job', 'resume_job', 'replay_job', 'send_job_message']) {
const op = operations.find(candidate => candidate.name === name);
expect(op, `expected canonical op "${name}" to exist`).toBeDefined();
expect(op!.mutating, `state-changing op "${name}" must declare mutating`).toBe(true);
}
});
});
describe('job-control operations — dry run never changes queue state', () => {
test('pause_job previews without pausing, then a real call pauses', async () => {
await engine.setConfig('version', '130');
const queue = new MinionQueue(engine);
const job = await queue.add('sync', {});
const op = operations.find(candidate => candidate.name === 'pause_job')!;
const preview = await op.handler(makeContext({ remote: false, dryRun: true }), { id: job.id });
expect(preview).toEqual({ dry_run: true, action: 'pause_job', id: job.id });
expect((await queue.getJob(job.id))!.status).toBe('waiting');
const result = await op.handler(makeContext({ remote: false }), { id: job.id });
expect(result).toEqual({ id: job.id, status: 'paused' });
expect((await queue.getJob(job.id))!.status).toBe('paused');
});
test('resume_job previews without resuming, then a real call resumes', async () => {
await engine.setConfig('version', '130');
const queue = new MinionQueue(engine);
const job = await queue.add('sync', {});
await queue.pauseJob(job.id);
const op = operations.find(candidate => candidate.name === 'resume_job')!;
const preview = await op.handler(makeContext({ remote: false, dryRun: true }), { id: job.id });
expect(preview).toEqual({ dry_run: true, action: 'resume_job', id: job.id });
expect((await queue.getJob(job.id))!.status).toBe('paused');
const result = await op.handler(makeContext({ remote: false }), { id: job.id });
expect(result).toEqual({ id: job.id, status: 'waiting' });
expect((await queue.getJob(job.id))!.status).toBe('waiting');
});
});
describe('mcpOperations filter — localOnly ops are excluded from the HTTP-exposed surface', () => {
// This filter is what serve-http.ts uses to build the tools/list response:
// const mcpOperations = operations.filter(op => !op.localOnly);
// A localOnly op that leaks into mcpOperations is exposed via HTTP MCP
// and bypasses the trust boundary. Pin the filter contract here so a
// regression surfaces as a structural test failure.
test('the canonical filter excludes every localOnly op', () => {
const mcpOps = operations.filter(op => !op.localOnly);
const mcpNames = new Set(mcpOps.map(op => op.name));
const localOnlyOps = operations.filter(op => op.localOnly === true);
expect(localOnlyOps.length).toBeGreaterThan(0);
for (const op of localOnlyOps) {
expect(
mcpNames.has(op.name),
`localOnly op "${op.name}" leaked into the HTTP MCP surface`,
).toBe(false);
}
});
test('localOnly snapshot — derived list matches the pinned literal exactly', () => {
// B3 (missing-test-coverage plan): replaces the old hand-rolled
// KNOWN_LOCAL_ONLY array, which only caught DROPPED flags (a new
// localOnly op could ship without ever being pinned — the original
// 4-name list missed purge_deleted_pages, get_recent_transcripts, and
// code_traversal_cache_clear for exactly that reason). Deriving the
// list from the canonical op surface and pinning it against a sorted
// literal catches BOTH directions:
// - an op silently sheds its localOnly flag → missing from derived;
// - a new localOnly op appears → extra in derived → the author must
// consciously add it here (and think about why it's localOnly).
// When this fails: verify the change is intentional, then update the
// literal in the same commit.
const LOCAL_ONLY_SNAPSHOT = [
'chronicle_backfill',
'code_traversal_cache_clear',
// v0.46.31.0 chat-connectors wave: both drive local connector CLIs +
// filesystem state; remote callers get them via the CLI only.
'connector_sync',
'connectors_status',
// v0.46.x identity wave: link/unlink rewrite identity rows brain-wide.
'entity_identity_link',
'entity_identity_unlink',
'extraction_review',
'file_list',
'file_register',
'file_upload',
'file_url',
'file_verify',
'get_recent_transcripts',
'get_skill_retention',
'import_skill_proposal',
'migrate_embeddings',
'prune_skill_revisions',
'purge_deleted_pages',
'retain_skill_revision',
'sources_inspect',
// GST-1943: the storage manifest's writers run from the trusted local CLI only.
'storage_register',
'storage_update',
'sync_brain',
// W9F item 8: the CLI delegates rebuild to a resident owner over IPC.
'takes_rebuild',
'takes_remove',
];
const derived = operations.filter(o => o.localOnly).map(o => o.name).sort();
expect(derived).toEqual(LOCAL_ONLY_SNAPSHOT);
// Keep the old per-name consumption working: every pinned op still
// exists in the canonical surface and still carries localOnly === true
// (strict boolean — the filter above accepts truthy, the contract is
// the literal `true`).
const lookup = new Map(operations.map(op => [op.name, op] as const));
for (const name of LOCAL_ONLY_SNAPSHOT) {
const op = lookup.get(name);
expect(op, `expected canonical op "${name}" to still exist`).toBeDefined();
expect(op!.localOnly, `"${name}" must stay localOnly`).toBe(true);
}
});
});
describe('hasScope — read-only token cannot satisfy write or admin scopes', () => {
// The HTTP path computes `requiredScope = op.scope || 'read'` and gates
// every call on `hasScope(authInfo.scopes, requiredScope)`. Pin the
// semantics here so a refactor of the IMPLIES table can't silently
// grant admin via a read-class token.
test('read scope does NOT satisfy write', () => {
expect(hasScope(['read'], 'write')).toBe(false);
});
test('read scope does NOT satisfy admin', () => {
expect(hasScope(['read'], 'admin')).toBe(false);
});
test('write scope satisfies write AND read', () => {
expect(hasScope(['write'], 'write')).toBe(true);
expect(hasScope(['write'], 'read')).toBe(true);
});
test('admin scope satisfies admin, write, AND read (umbrella implies)', () => {
expect(hasScope(['admin'], 'admin')).toBe(true);
expect(hasScope(['admin'], 'write')).toBe(true);
expect(hasScope(['admin'], 'read')).toBe(true);
});
test('unknown scope strings are ignored, do not satisfy anything', () => {
expect(hasScope(['bogus'], 'read')).toBe(false);
expect(hasScope(['bogus'], 'write')).toBe(false);
});
test('every read-scope op accepts a read-only token; every write-scope op rejects it', () => {
// Walk the op surface and assert that a synthetic read-only token
// satisfies every read-scope op but no write/admin op.
const READ_TOKEN_SCOPES = ['read'] as const;
for (const op of operations) {
const required = op.scope ?? 'read';
const accepted = hasScope(READ_TOKEN_SCOPES, required);
if (required === 'read') {
expect(accepted, `read op "${op.name}" should accept read-only token`).toBe(true);
} else {
expect(accepted, `${required} op "${op.name}" must reject read-only token`).toBe(false);
}
}
});
});
describe('handler invocation — historically-broken trust-boundary classes', () => {
// The two non-localOnly ops whose handler-level defense fires in
// production and has been broken historically (F7b HTTP MCP shell-job
// RCE; D18 P0 image_path remote-leak). file_upload and sync_brain are
// omitted because they're localOnly (codex CMT-3 — testing their
// handlers with remote=true tests an impossible production path).
test('submit_job rejects shell with ctx.remote=true (HTTP MCP shell-job RCE class)', async () => {
const submitJob = operations.find(op => op.name === 'submit_job');
expect(submitJob).toBeDefined();
const ctx = makeContext({ remote: true });
await expect(submitJob!.handler(ctx, { name: 'shell', data: { cmd: 'echo hi' } })).rejects.toMatchObject({
code: 'permission_denied',
// Bounded diagnostics identify the supported alternatives, without
// echoing caller-controlled job names or payloads.
message: expect.stringContaining('only sync, import, lint and lint-fix'),
});
});
test('submit_job allows shell when ctx.remote=false (local CLI is trusted)', async () => {
// The flip side of the trust boundary: a local trusted caller with
// explicit remote=false MUST be allowed to submit shell jobs (that's
// how the CLI works in production). We don't actually want to run the
// job — pass dryRun so the op short-circuits.
const submitJob = operations.find(op => op.name === 'submit_job');
const ctx = makeContext({ remote: false, dryRun: true });
const result = await submitJob!.handler(ctx, { name: 'shell', data: { cmd: 'echo hi' } });
expect(result).toMatchObject({ dry_run: true, action: 'submit_job', name: 'shell' });
});
test('search_by_image rejects image_path with ctx.remote=true (D18 P0)', async () => {
const searchByImage = operations.find(op => op.name === 'search_by_image');
expect(searchByImage).toBeDefined();
const ctx = makeContext({ remote: true });
let threw = false;
let message = '';
try {
await searchByImage!.handler(ctx, { image_path: '/tmp/some-image.png' });
} catch (e) {
threw = true;
message = e instanceof Error ? e.message : String(e);
}
expect(threw, 'search_by_image(image_path) with remote=true MUST reject').toBe(true);
expect(message.toLowerCase()).toContain('image_path');
expect(message.toLowerCase()).toContain('permission_denied');
});
test('find_orphans / get_recent_salience / find_anomalies hide private pages from remote callers (read-leak class)', async () => {
// Admission per the curated-list criterion: a real exploit class fixed
// at the handler level — remote callers received private page
// slugs/titles/metadata through these list arms (found by the
// remote-privacy-sweep on its first run; same class as the delta page
// arm). Local trusted callers keep the unfiltered view.
//
// Two extra WORLD person pages make the corpus 3 same-type pages today:
// enough for the anomaly type-cohort to FIRE (count > mean + 1 over an
// empty baseline), so the find_anomalies assertions below are proven
// non-vacuous by a LOCAL positive control instead of leaning on an
// empty result.
const put = operations.find(op => op.name === 'put_page')!;
const local = makeContext({ remote: false });
await put.handler(local, {
slug: 'people/tb-priv-example',
content: '---\ntitle: TB_PRIVATE_TITLE_PROOF\ntype: person\nvisibility: private\n---\n\n# TB_PRIVATE_TITLE_PROOF\n\nprivate body\n',
});
await put.handler(local, {
slug: 'people/tb-world-a',
content: '---\ntitle: TB World A\ntype: person\n---\n\n# TB World A\n\nworld body\n',
});
await put.handler(local, {
slug: 'people/tb-world-b',
content: '---\ntitle: TB World B\ntype: person\n---\n\n# TB World B\n\nworld body\n',
});
const remote = makeContext({ remote: true });
type OrphanCounts = {
orphans: { slug: string }[];
total_orphans: number;
total_pages: number;
total_linkable: number;
excluded: number;
};
const orphans = operations.find(op => op.name === 'find_orphans')!;
const orphanResult = (await orphans.handler(remote, {})) as OrphanCounts;
const orphanRes = JSON.stringify(orphanResult);
expect(orphanRes).not.toContain('people/tb-priv-example');
expect(orphanRes).not.toContain('TB_PRIVATE_TITLE_PROOF');
// Count self-consistency after filtering: total_orphans mirrors the
// filtered list (a stale unfiltered total is a hidden-page count oracle).
expect(orphanResult.total_orphans).toBe(orphanResult.orphans.length);
const orphanLocalResult = (await orphans.handler(local, {})) as OrphanCounts;
const orphanLocal = JSON.stringify(orphanLocalResult);
expect(orphanLocal).toContain('people/tb-priv-example');
// Hidden orphans VANISH from every published counter: both denominators
// shrink by the one hidden page and `excluded` is untouched — folding
// hidden rows into `excluded` would be an exact one-call oracle, since
// the unfiltered op guarantees excluded counts only pseudo-pages.
expect(orphanLocalResult.total_pages - orphanResult.total_pages).toBe(1);
expect(orphanLocalResult.total_linkable - orphanResult.total_linkable).toBe(1);
expect(orphanResult.excluded).toBe(orphanLocalResult.excluded);
const salience = operations.find(op => op.name === 'get_recent_salience')!;
const salienceRes = JSON.stringify(await salience.handler(remote, {}));
expect(salienceRes).not.toContain('people/tb-priv-example');
expect(salienceRes).not.toContain('TB_PRIVATE_TITLE_PROOF');
const salienceLocal = JSON.stringify(await salience.handler(local, {}));
expect(salienceLocal).toContain('people/tb-priv-example');
const anomalies = operations.find(op => op.name === 'find_anomalies')!;
// LOCAL positive control: the person-type cohort anomaly fires and
// names the private slug — proving the remote assertions below are
// exercising a real filter, not an empty list.
const anomaliesLocal = JSON.stringify(await anomalies.handler(local, {}));
expect(anomaliesLocal).toContain('people/tb-priv-example');
const anomalyRows = (await anomalies.handler(remote, {})) as {
count: number;
page_slugs: string[];
}[];
const anomaliesRes = JSON.stringify(anomalyRows);
expect(anomaliesRes).not.toContain('people/tb-priv-example');
expect(anomaliesRes).toContain('people/tb-world-a'); // non-empty proof
for (const row of anomalyRows) {
// No empty-row oracle, and for this sub-cap corpus the adjusted count
// (original minus removed private slugs) equals the visible list —
// a stale unadjusted count would read 3 here and leak the hidden
// page's existence.
expect(row.page_slugs.length).toBeGreaterThan(0);
expect(row.count).toBe(row.page_slugs.length);
}
// find_experts: query the private page's OWN title so the expertise
// scorer must rank it if it can see it — a remote caller gets nothing,
// a local caller gets the row (deterministic, unlike fuzzy-threshold
// sweep topics).
const experts = operations.find(op => op.name === 'find_experts')!;
const expertsRes = JSON.stringify(
await experts.handler(remote, { topic: 'TB_PRIVATE_TITLE_PROOF' }),
);
expect(expertsRes).not.toContain('people/tb-priv-example');
expect(expertsRes).not.toContain('TB_PRIVATE_TITLE_PROOF');
const expertsLocal = JSON.stringify(
await experts.handler(local, { topic: 'TB_PRIVATE_TITLE_PROOF' }),
);
expect(expertsLocal).toContain('people/tb-priv-example');
// Soft-delete bypass (fail-closed probe): the raw salience/anomaly
// queries carry no deleted_at predicate, so a soft-deleted private page
// still reaches the handler rows — the post-filter must classify it
// private-only via includeDeleted:true or it slips through.
const del = operations.find(op => op.name === 'delete_page')!;
const beforeDelete = (await engine.readPageSnapshot('people/tb-priv-example', { sourceId: 'default' }))!;
await del.handler(local, { slug: beforeDelete.page.slug, expected_revision: beforeDelete.revision });
const salienceAfterDelete = JSON.stringify(await salience.handler(remote, {}));
expect(salienceAfterDelete).not.toContain('people/tb-priv-example');
expect(salienceAfterDelete).not.toContain('TB_PRIVATE_TITLE_PROOF');
const anomaliesAfterDelete = JSON.stringify(await anomalies.handler(remote, {}));
expect(anomaliesAfterDelete).not.toContain('people/tb-priv-example');
});
});
describe('ops-module system-access containment — top-level fs/child_process importers only contribute localOnly ops', () => {
// B3 inverse assertion: an ops module that statically imports the
// filesystem or process-spawning APIs is a module whose op handlers can
// plausibly touch the host — those ops must not be reachable over the
// remote MCP surface unless someone consciously exempts them.
//
// GRANULARITY (the closest enforceable version of the file→ops mapping):
// - DETECTION is per-FILE and text-based: a static top-level ESM
// import/re-export of 'fs' / 'fs/promises' / 'child_process' (with or
// without the node: prefix), or of src/core/spawn.ts, the seam every
// src/ subprocess launch goes through. Static import statements are
// top-level by ESM grammar, so matching the `from '<specifier>'`
// clause is exact.
// Lazy dynamic `await import('node:fs')` INSIDE a handler is
// deliberately out of scope (schema-packs.ts and skillopt.ts use that
// form today) — it is runtime-gated per call site, the same doctrine
// as the engine-dynamic-import rule in CLAUDE.md.
// - ENFORCEMENT is per-OP: every canonical op a flagged file exports
// must be localOnly === true or appear in EXEMPT below. A mixed file
// (fs import serving one localOnly op alongside safe remote ops) is
// therefore judged op by op, not condemned wholesale.
// - EXEMPTION is keyed by op NAME, not (file, op) pair. Op names are
// globally unique in the canonical surface (operationsByName), so this
// is equivalent in practice and survives ops moving between modules.
// - A flagged HELPER module that exports no ops (context.ts today: its
// lstatSync/realpathSync import backs validateUploadPath, whose strict
// confinement serves the localOnly file_upload path) passes vacuously —
// the enforcement unit is the contributed op, and a helper contributes
// none.
//
// EXEMPT allowlist — op name → one-line rationale. Seeded from today's
// scan, which flags only context.ts (zero contributed ops), so the seed is
// EMPTY. Adding an entry is a conscious security decision: verify the op's
// handler never lets a remote caller reach the fs/child_process surface
// before exempting it.
const EXEMPT: ReadonlyMap<string, string> = new Map<string, string>([
// (empty today — no flagged module contributes a non-localOnly op)
]);
const OPS_DIR = join(import.meta.dir, '..', 'src', 'core', 'ops');
const opsFiles = readdirSync(OPS_DIR).filter(f => f.endsWith('.ts')).sort();
// Matches static top-level `import ... from 'fs'` / `export ... from
// 'node:child_process'` / side-effect `import 'node:fs'` forms. Does NOT
// match dynamic `await import('node:fs')` (no `from` clause, no leading
// import keyword at a line start) or commented-out imports (`//` and `*`
// are not whitespace, so the line-start anchor excludes them).
const SYSTEM_IMPORT_RE =
/(?:^|\n)\s*(?:import|export)\s+(?:[^;]*?\bfrom\s+)?['"](?:(?:node:)?(?:fs|fs\/promises|child_process)|\.\.\/spawn\.ts)['"]/;
/**
* Canonical ops contributed by one ops module: import it, walk every
* export (flattening exported Operation[] arrays and individual Operation
* exports like insights.ts's), keep objects shaped like an Operation whose
* name is in the canonical `operations` list.
*/
async function contributedOps(file: string): Promise<string[]> {
const canonical = new Set(operations.map(o => o.name));
const mod = await import(join(OPS_DIR, file));
const found = new Set<string>();
for (const value of Object.values(mod as Record<string, unknown>)) {
const candidates = Array.isArray(value) ? value : [value];
for (const c of candidates) {
if (
c !== null &&
typeof c === 'object' &&
typeof (c as { name?: unknown }).name === 'string' &&
typeof (c as { handler?: unknown }).handler === 'function' &&
canonical.has((c as { name: string }).name)
) {
found.add((c as { name: string }).name);
}
}
}
return [...found].sort();
}
test('detector self-test — static top-level forms match, dynamic/commented forms do not', () => {
// Guards the main test against a vacuous pass if the regex rots.
expect(SYSTEM_IMPORT_RE.test(`import { readFileSync } from 'node:fs';`)).toBe(true);
expect(SYSTEM_IMPORT_RE.test(`import { lstatSync, realpathSync } from 'fs';`)).toBe(true);
expect(SYSTEM_IMPORT_RE.test(`import cp from 'child_process';`)).toBe(true);
expect(SYSTEM_IMPORT_RE.test(`import {\n readFileSync,\n writeFileSync,\n} from 'fs/promises';`)).toBe(true);
expect(SYSTEM_IMPORT_RE.test(`import 'node:fs';`)).toBe(true);
expect(SYSTEM_IMPORT_RE.test(`export { execSync } from 'node:child_process';`)).toBe(true);
expect(SYSTEM_IMPORT_RE.test(`import { execFileSync } from '../spawn.ts';`)).toBe(true);
expect(SYSTEM_IMPORT_RE.test(`import { buildSpawnInvocation } from '../minions/spawn-helpers.ts';`)).toBe(false);
expect(SYSTEM_IMPORT_RE.test(`const nodeFs = await import('node:fs');`)).toBe(false);
expect(SYSTEM_IMPORT_RE.test(`import { resolve } from 'node:path';`)).toBe(false);
expect(SYSTEM_IMPORT_RE.test(`code();\n// import { x } from 'node:fs'`)).toBe(false);
expect(SYSTEM_IMPORT_RE.test(`import { x } from './fs-helpers.ts';`)).toBe(false);
});
test('export walk attributes the full canonical surface (guard against a vacuous pass)', async () => {
// If the Operation-shape walk silently broke (returned nothing), the
// containment test below would pass vacuously. Pin the mechanism: every
// canonical op is either exported by some src/core/ops/*.ts module or is
// one of the memory verbs from src/core/verbs.ts — nothing else.
expect(opsFiles).toContain('files.ts');
expect(opsFiles).toContain('jobs.ts');
expect(await contributedOps('files.ts')).toEqual(['file_list', 'file_register', 'file_upload', 'file_url', 'file_verify']);
expect(await contributedOps('jobs.ts')).toContain('submit_job');
const attributed = new Set<string>(verbOperations.map(op => op.name));
for (const file of opsFiles) {
for (const name of await contributedOps(file)) attributed.add(name);
}
expect([...attributed].sort()).toEqual(operations.map(o => o.name).sort());
});
test('every op contributed by a flagged module is localOnly or explicitly exempt', async () => {
const byName = new Map(operations.map(op => [op.name, op] as const));
const flagged = opsFiles.filter(f =>
SYSTEM_IMPORT_RE.test(readFileSync(join(OPS_DIR, f), 'utf8')),
);
for (const file of flagged) {
for (const opName of await contributedOps(file)) {
const op = byName.get(opName)!;
if (op.localOnly === true) continue;
expect(
EXEMPT.has(opName),
`src/core/ops/${file} has a top-level fs/child_process import but contributes ` +
`non-localOnly op "${opName}" — make the op localOnly, move the system import ` +
`behind a lazy per-call dynamic import, or add an EXEMPT entry with a rationale ` +
`after verifying remote callers cannot reach the fs/child_process surface`,
).toBe(true);
}
}
// Exempt-list hygiene, fail-closed both ways: an entry for an op that no
// longer exists (or is now localOnly, making the exemption dead) must be
// removed so the allowlist stays small and every entry stays load-bearing.
for (const [name] of EXEMPT) {
const op = byName.get(name);
expect(op, `EXEMPT entry "${name}" names an op that no longer exists — remove it`).toBeDefined();
expect(
op!.localOnly !== true,
`EXEMPT entry "${name}" is now localOnly — the exemption is dead, remove it`,
).toBe(true);
}
});
});