Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
10.4 KB
Raw Blame
#!/usr/bin/env bash
# v0.39 — CI guard against bypassing the localOnly filter on the HTTP MCP
# surface. Lives alongside check-jsonb-pattern.sh / check-progress-to-stdout.sh
# in the bun run verify chain.
#
# Background: serve-http.ts builds the HTTP MCP tools/list response from
# `operations.filter(op => !op.localOnly)`. That filter is the only thing
# keeping localOnly ops (sync_brain, file_upload, file_list, file_url —
# any admin op the user EXPLICITLY marked as CLI-only) off the wire.
#
# If a future HTTP-exposing module imports `operations` from
# core/operations.ts WITHOUT applying the filter, the localOnly contract
# silently breaks: a write-scoped OAuth client could submit `sync_brain`
# or `file_upload` over HTTP. Codex outside-voice review of the e2e-test-
# wave (CMT-3) flagged this exact bypass class.
#
# The guard works by:
#   1. Listing every file that imports `operations` from core/operations.ts.
#   2. Comparing against an explicit ALLOWLIST of known-safe importers
#      (each with a rationale below).
#   3. Failing if a new file is missing from the allowlist — forces the
#      author to either (a) join the allowlist with an explicit rationale,
#      or (b) apply the canonical filter at import.
#
# This is a structural defense. The runtime defense lives in
# test/operations-trust-boundary.test.ts (the canonical filter contract +
# handler-invocation cases for the historically-broken classes).
#
# To allow a new importer: add the relative path to ALLOWED below with a
# one-line comment explaining why localOnly isn't a concern there.
#
# Exit: 0 when no unknown importers, 1 when at least one is missing from
# the allowlist.
set -euo pipefail

ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
# Self-test seam: GBRAIN_GUARD_ROOT points at a fixture tree with its own src/.
ROOT="${GBRAIN_GUARD_ROOT:-$ROOT}"
cd "$ROOT"

# Files allowed to import `operations` directly. Each entry must be
# accompanied by a one-line rationale (the comment on the same line).
ALLOWED=(
  "src/core/grants/profiles.ts"                 # snapshots eligible remote ops with !op.localOnly; grant validation never exposes local-only operations
  "src/core/bootstrap/harness.ts"              # trusted owner provisioning; filters localOnly and scopes before minting explicit follow operation snapshots
  "src/core/token-mint.ts"                     # trusted token creation validates explicit snapshots against public scope-compatible operations
  "src/core/grants/legacy-token.ts"             # trusted local rescope-token; validates and refreshes snapshots against !op.localOnly scope-compatible operations
  "src/core/shared-skills/tool-access.ts"       # skill usability intersects locality, scopes, snapshots, source fences, surface and publication gates
  "src/mcp/skill-resources.ts"                  # resources map only catalog reads through equivalent scope/snapshot/surface/gate checks and shared dispatch
  "src/core/harness/capabilities.ts"            # introspection applies !op.localOnly plus effective surface, scope, fence, snapshot and publish-gate filters
  "src/cli/main.ts"                             # local CLI dispatcher (loaded by src/cli.ts); user owns the machine, no trust boundary
  "src/mcp/dispatch.ts"                         # shared dispatch; sets ctx.remote from caller, handlers self-gate
  "src/mcp/server.ts"                           # stdio MCP; local-trusted (binary on user's box)
  "src/mcp/http-transport.ts"                   # superseded by serve-http.ts; kept for back-compat tests
  "src/mcp/tool-defs.ts"                        # pure helper; takes ops as parameter, never exposes them
  "src/core/minions/tools/brain-allowlist.ts"   # subagent registry; has its own opt-in allowlist (separate from localOnly)
  "src/commands/capture.ts"                     # local CLI tool; not network-exposed
  "src/commands/recall.ts"                      # local CLI delegates forget through the frozen operation before acquiring an engine
  "src/commands/forget-purge.ts"                # local CLI runs the cliOnly purge_fact op as the trusted owner (remote: false) or over the 0600 owner socket
  "src/commands/pages-purges.ts"                # local CLI runs the cliOnly list_page_purges / unpurge_page ops as the trusted owner (remote: false)
  "src/commands/takes-mutation.ts"              # local CLI adapter; trusted execution or authenticated persistence IPC only
  "src/core/persistence/administration.ts"      # trusted-admin grant diagnostics; does not expose an operation transport
  "src/core/persistence/provider.ts"            # authenticated local registrations; shared dispatch enforces localOnly and the immutable trust lane
  "src/commands/enrich.ts"                       # local CLI tool; calls put_page handler with remote=false, not network-exposed
  "src/commands/import-calls.ts"                 # local CLI import --calls; calls the put_page handler with remote=false, not network-exposed
  "src/core/extract-takes-from-pages.ts"          # local CLI extraction calls put_page with remote=false; it does not expose operations to a transport
  "src/commands/book-mirror.ts"                 # local CLI tool; not network-exposed
  "src/commands/edge-proposals.ts"              # local CLI review of edge proposals; calls trusted handlers with remote=false, not network-exposed
  "src/core/cycle/edge-contradictions.ts"       # dream phase appends closure lines via add_timeline_entry with remote=false; never exposes operations
  "src/commands/tools-json.ts"                  # gbrain --tools-json introspection; full op list IS the purpose
  "src/mcp/publish-gates.ts"                    # reads op.publishGateKey/name only to compute gate-DISABLED sets and the gate key set; never lists/exposes ops
  "src/mcp/tool-catalog.ts"                     # docs/TOOL_CATALOG.md renderer; filters !op.localOnly at the boundary; never a transport surface
  "src/commands/serve-http.ts"                  # MUST APPLY .filter(op => !op.localOnly) — verified by grep below
  "src/core/ops/request-tools.ts"               # visibleOpsForCaller loads the assembled list lazily (verbs.ts house pattern) and applies (isLocal || !op.localOnly) + surface + gate filtering
  # The four below predate the widened specifier regex (they import via
  # '../operations.ts', invisible to the old 'core/operations.ts' pattern) —
  # all internal consumers, none a transport surface:
  "src/core/advisor/collect-mcp-client-fit.ts"  # advisor collector; uses op.localOnly names to SCORE client fit, never serves the list
  "src/core/bootstrap/verify.ts"                # bootstrap wiring verifier; finds ops by name to probe local wiring, remote=false context
  "src/core/skillopt/rollout.ts"                # skillopt internals; iterates op metadata for rollout planning, not exposed
  "src/core/skillopt/write-capture.ts"          # skillopt internals; iterates op params for capture schema, not exposed
)

# Pattern: any import that brings the `operations` VALUE in from core/operations.ts.
# Three shapes the value can enter through; each must be caught:
#   - destructured:    import { operations } from '...core/operations.ts'
#   - aliased:         import { operations as ops } from '...core/operations.ts'
#   - namespace:       import * as opsModule from '...core/operations.ts'
# The original narrow regex only matched the destructured form — codex caught
# the bypass class during /ship adversarial review (aliased + namespace forms
# slipped through). The broadened regex below specifically requires `operations`
# inside the destructured clause OR a namespace import (`* as X`); type-only
# imports of sibling exports like `sourceScopeOpts` / `OperationContext` are
# left alone (those don't expose the op list to a transport surface).
# Specifier: `core/operations.ts` from outside src/core, `../operations.ts`
# from inside (the ops/ module dir sits one level down post-peel), and the
# dynamic `import('...operations.ts')` house pattern — all three reach the
# assembled op list.
PATTERN='(import[[:space:]]+(\*[[:space:]]+as[[:space:]]+[a-zA-Z_$][a-zA-Z0-9_$]*|\{[^}]*\boperations\b[^}]*\})[[:space:]]+from[[:space:]]*['\''"][^'\''"]*(core/operations|\.\./operations)\.ts['\''"]|\{[^}]*\boperations\b[^}]*\}[[:space:]]*=[[:space:]]*await[[:space:]]+import\(['\''"][^'\''"]*operations\.ts['\''"]\))'

# Collect files that import `operations`. Use a while-loop over grep output
# instead of `mapfile` to stay compatible with macOS's default bash 3.2.
FOUND_FILES=""
while IFS= read -r f; do
  [ -n "$f" ] && FOUND_FILES="$FOUND_FILES$f"$'\n'
done < <(grep -rlE --include='*.ts' "$PATTERN" src 2>/dev/null | sort -u || true)

FAIL=0

# Check 1: every found file is in ALLOWED.
while IFS= read -r file; do
  [ -z "$file" ] && continue
  rel="${file#"$ROOT/"}"
  ok=0
  for allowed in "${ALLOWED[@]}"; do
    if [ "$rel" = "$allowed" ]; then
      ok=1
      break
    fi
  done
  if [ "$ok" -eq 0 ]; then
    echo "FAIL: $rel imports operations but is not in scripts/check-operations-filter-bypass.sh ALLOWED list."
    echo "      Either apply .filter(op => !op.localOnly) at the import boundary,"
    echo "      or add this file to ALLOWED with a one-line rationale."
    FAIL=1
  fi
done <<< "$FOUND_FILES"

# Check 2: the HTTP MCP surface MUST contain the canonical filter expression
# near its operations import. Without the filter, the entire HTTP MCP surface
# leaks localOnly ops. Refactor wave 1 moves the /mcp handler from
# serve-http.ts into serve-http-mcp.ts, so the filter may live in either file
# (a containment check over that two-file surface); a new serve-http-*.ts
# module that imports operations must still pass check 1's ALLOWED list.
SERVE_HTTP_SURFACE=()
for f in src/commands/serve-http.ts src/commands/serve-http-mcp.ts; do
  [ -f "$f" ] && SERVE_HTTP_SURFACE+=("$f")
done
if [ "${#SERVE_HTTP_SURFACE[@]}" -gt 0 ]; then
  # grep the files directly: `cat | grep -q` under pipefail fails with
  # SIGPIPE whenever grep exits on an early match.
  if ! grep -qE 'operations\.filter\(\s*op\s*=>\s*!op\.localOnly\s*\)' "${SERVE_HTTP_SURFACE[@]}"; then
    echo "FAIL: ${SERVE_HTTP_SURFACE[*]} no longer contain the canonical"
    echo "      operations.filter(op => !op.localOnly) expression. The HTTP MCP"
    echo "      surface depends on this filter to enforce localOnly. Restore"
    echo "      the filter or refactor the trust boundary explicitly."
    FAIL=1
  fi
fi

if [ "$FAIL" -eq 1 ]; then
  echo ""
  echo "Hint: see test/operations-trust-boundary.test.ts for the runtime contract."
  exit 1
fi

exit 0