Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
32.4 KB
Raw Blame
/**
 * HTTP transport for `gbrain serve --http` (legacy bearer-auth path).
 *
 * Engine-aware via SqlQuery (works on both Postgres and PGLite as of the
 * v0.31 wave). The access_tokens and mcp_request_log tables exist on both
 * engines (see src/core/pglite-schema.ts:478,495 and src/schema.sql).
 *
 * Security model:
 *   - Every request must include `Authorization: Bearer <token>` (except /health)
 *   - Tokens are validated against SHA-256 hashes in the access_tokens table
 *   - Create/manage tokens with auth.ts (gbrain auth create/list/revoke)
 *   - No open OAuth, no client_credentials, no self-service tokens
 *
 * Hardening:
 *   - CORS default-deny: allowlist via GBRAIN_HTTP_CORS_ORIGIN (comma-separated)
 *   - Rate limit: per-IP pre-auth (protects DB from brute-force load) + per-token-id post-auth
 *     (limits runaway clients). Default 30 req/min per IP, 60 req/min per token. Bounded LRU
 *     so attacker-controlled keys can't grow memory unbounded.
 *   - Body cap: 1 MiB default (GBRAIN_HTTP_MAX_BODY_BYTES). Stream-counted, not buffered —
 *     chunked transfers without Content-Length are still capped.
 *   - last_used_at debounce: only one UPDATE per token per 60s (SQL-level WHERE clause).
 *   - mcp_request_log: one row per request with token_name + operation + status + latency.
 *
 * Replaces the standalone HTTP+OAuth wrapper that was vulnerable to unauthenticated
 * client registration (see SECURITY.md).
 */

import { createHash } from 'crypto';
import { hasScope, operationScopesAllowed } from '../core/scope.ts';
import { createSkillResources } from './skill-resources.ts';
import { CAPABILITIES_URI } from './capabilities.ts';
import { resolveAuthCapabilities } from '../core/harness/capabilities.ts';
import type { BrainEngine } from '../core/engine.ts';
import { buildToolDefs } from './tool-defs.ts';
import { MCP_SERVER_DESCRIPTION, readInstructionContent, resolveMcpInstructions } from './instructions.ts';
import { httpInstructionTools } from './initialize-context.ts';
import { ambientOptsFrom, writebackCaller } from '../core/facts/writeback-config.ts';
import { resolveAgentWriteback } from '../core/facts/writeback-settings.ts';
import { OWNER_MEMBER_KEY } from '../core/search/private-visibility.ts';
import { operations, operationsByName, opAllowedForBoundClient } from '../core/operations.ts';
import { scopeDeniedError } from '../core/ops/op-fix.ts';
import { ON_BEHALF_OF_HEADER } from '../core/access/audience.ts';
import { ROOM_HEADER } from '../core/access/room.ts';
import { GUEST_HEADER } from '../core/guests/admission.ts';
import { ACTOR_HEADER, QM_AUDIENCE_HEADER, withAttestRight } from '../core/access/actor-model.ts';
import { parseAgentLabel, AGENT_LABEL_HEADER } from '../core/persistence/attribution.ts';
import { qmMemoryToolResult } from '../core/ops/qm-memory.ts';
import { isCallable, publishGatesFromDisabled } from '../core/ops/callable.ts';
import type { AuthInfo } from '../core/operations.ts';
import { VERSION } from '../version.ts';
import { audienceRefusal, dispatchToolCall, requestLogStatusForResult, errorResult } from './dispatch.ts';
import { GBRAIN_CLIENT_HEADER, isGbrainThinClient, resolveResultRowsMode, resultRowsForRequest } from './result-rows.ts';
import { parseStrictParamsMode } from './validate-params.ts';
import { filterOpsForSurface, clampSurface, advertisedOps, resolveAdvertisedSurface, type McpSurface } from './surface.ts';
import { disabledOpsForPublishGates } from './publish-gates.ts';
import { loadServeConfigs } from './serve-config.ts';
import { buildDefaultLimiters, type RateLimiter } from './rate-limit.ts';
import { sqlQueryForEngine } from '../core/sql-query.ts';
import { degradedLastError, isEngineDegraded } from '../core/degraded-marker.ts';
import { classifyPgAccessError } from '../core/pg-access-classify.ts';
import { redactConnectionInfo } from '../core/audit/redact-connection-info.ts';
import { redactUrlsInText } from '../core/url-redact.ts';
import { authSourcesFromGrant, privatePagesAuth } from '../core/grants/model.ts';
import { resolveTokenGrant, touchTokenLastUsed } from '../core/grants/legacy-token.ts';
import { storedMinTrust } from '../core/trust/tier.ts';
import { tokenMemberBinding } from '../core/access/token-binding.ts';
export { parseLegacyTokenScope } from '../core/legacy-token-scope.ts';

const DEFAULT_BODY_CAP = 1024 * 1024; // 1 MiB

/** #6007: what an agent does after a 413: nothing was processed; a batch goes smaller, a big page goes by file. */
function oversizeSuggestion(bodyCap: number): string {
  return `Nothing was processed: this transport reads at most ${bodyCap} bytes per request (GBRAIN_HTTP_MAX_BODY_BYTES on the brain host). Send put_pages as smaller batches, a new request_id per call. Do not split a page: one page over this limit goes by file instead, so ask the user to write it into the brain repository and run gbrain sync, or to run gbrain import <file> or gbrain put <slug> < file on the brain host.`;
}

function hashToken(token: string): string {
  return createHash('sha256').update(token).digest('hex');
}

function envInt(name: string, fallback: number): number {
  const v = process.env[name];
  if (!v) return fallback;
  const n = parseInt(v, 10);
  return Number.isFinite(n) && n > 0 ? n : fallback;
}

function parseCorsAllowlist(): Set<string> | null {
  const v = process.env.GBRAIN_HTTP_CORS_ORIGIN;
  if (!v) return null;
  return new Set(v.split(',').map(s => s.trim()).filter(Boolean));
}

interface HttpTransportOptions {
  port: number;
  engine: BrainEngine;
  /** Override limiters (for tests). Defaults to env-driven buildDefaultLimiters. */
  limiters?: { ip: RateLimiter; token: RateLimiter };
  /**
   * MEMORY_VERBS v1 [c1]: tool-surface mode for this transport (the SECOND
   * HTTP path — the OAuth path in serve-http.ts carries its own). 'verbs' =
   * exactly the seven protocol verbs; 'starter' (WP4) = the STARTER_OPS
   * daily-driver set; 'full' (default) = everything. Legacy bearer tokens
   * have no oauth_clients row, so there is no per-client surface here — the
   * transport surface (clamped by GBRAIN_MCP_FORCE_SURFACE, narrow-only)
   * applies to every caller.
   */
  surface?: McpSurface;
}

interface AuthResult {
  ok: boolean;
  /** GBRA-218: why a known token was refused (a member binding that cannot read). */
  code?: 'access_member_disabled';
  tokenId?: string;
  tokenName?: string;
  /** v0.28: per-token allow-list for takes.holder. Default ['world'] when permissions row absent. */
  takesHoldersAllowList?: string[];
  /**
   * v0.34.1 (#861, D13): source-isolation scope for the auth'd request.
   * Legacy bearer tokens here default to 'default' to match the v0.33
   * effective behavior (the now-removed serve-http.ts fallback chain).
   * Operators migrate to the full OAuth transport (gbrain serve --http)
   * for narrower scoping.
   */
  sourceId?: string;
  /**
   * #1336: AuthInfo carrying the legacy token's stored federated_read grant
   * (`permissions.source_id` array). Threaded so `sourceScopeOpts` can scope
   * read ops to the operator-granted sources instead of just scalar `sourceId`.
   * Bounded to the stored grant — never widened to "all".
   */
  auth?: AuthInfo;
  /**
   * #3242: true when the token row carries an operator-set
   * `permissions.source_id` (string OR array — even a malformed one, which
   * fails closed to 'default' without widening). false = the historical
   * no-grant 'default' floor; ONLY that case gets the federated read set
   * (config.federated sources) threaded as localFederatedSourceIds.
   */
  hasSourceGrant?: boolean;
}

/* Legacy token source-scope parsing lives in core/legacy-token-scope.ts and is
 * re-exported above so the legacy HTTP transport and OAuth provider cannot drift. */

/** Read up to `cap` bytes off req.body. Returns null if cap exceeded. */
async function readBodyWithCap(req: Request, cap: number): Promise<string | null> {
  const cl = req.headers.get('content-length');
  if (cl) {
    const n = parseInt(cl, 10);
    if (Number.isFinite(n) && n > cap) return null;
  }
  const reader = req.body?.getReader();
  if (!reader) return '';
  const chunks: Uint8Array[] = [];
  let total = 0;
  while (true) {
    const { value, done } = await reader.read();
    if (done) break;
    if (!value) continue;
    total += value.byteLength;
    if (total > cap) {
      try { await reader.cancel(); } catch { /* noop */ }
      return null;
    }
    chunks.push(value);
  }
  // Concatenate without Buffer to keep this Node-vs-Bun-portable.
  const merged = new Uint8Array(total);
  let offset = 0;
  for (const c of chunks) {
    merged.set(c, offset);
    offset += c.byteLength;
  }
  return new TextDecoder().decode(merged);
}

/** Resolve client IP. Honors X-Forwarded-For only when GBRAIN_HTTP_TRUST_PROXY=1. */
function resolveClientIp(req: Request, server: { requestIP: (r: Request) => { address: string } | null }): string {
  if (process.env.GBRAIN_HTTP_TRUST_PROXY === '1') {
    const xff = req.headers.get('x-forwarded-for');
    if (xff) {
      const first = xff.split(',')[0]?.trim();
      if (first) return first;
    }
    const xRealIp = req.headers.get('x-real-ip');
    if (xRealIp) return xRealIp.trim();
  }
  const sock = server.requestIP(req);
  return sock?.address || 'unknown';
}

/** The 401 body for a refused bearer token; GBRA-218 names a member binding that cannot read. */
function authFailureBody(code: AuthResult['code']): Record<string, string> {
  return code === 'access_member_disabled'
    ? { error: 'invalid_token', code, message: 'This token is bound to a member who is disabled, removed or missing. Ask the brain operator to enable the member or rebind the token (gbrain auth rescope --token <name> --member <id>|none).' }
    : { error: 'invalid_token', message: 'Bearer token required. Create one: gbrain auth create <name>' };
}

/**
 * GST-359 D: a request carrying x-qm-audience (QM's channel audience, not served yet) is refused before any work on
 * every method that reads or runs a tool: tools/call gets the refusal result, the others a JSON-RPC error. Null otherwise.
 */
function qmAudienceRefusal(req: Request, body: { method?: string; params?: any; id?: any }, auth: AuthInfo): { log: string; body: Record<string, unknown> } | null {
  const { method, params, id } = body;
  if (req.headers.get(QM_AUDIENCE_HEADER) === null || !['tools/list', 'tools/call', 'resources/list', 'resources/read'].includes(method ?? '')) return null;
  const op = method === 'tools/call' ? String(params?.name ?? 'unknown') : method!;
  const refused = audienceRefusal(op, { auth, transport: 'http' });
  return method === 'tools/call' ? { log: `tools/call:${op}`, body: { jsonrpc: '2.0', id, result: refused.result } } : { log: op, body: { jsonrpc: '2.0', id, error: refused.rpc } };
}

export async function startHttpTransport(opts: HttpTransportOptions) {
  const { port, engine } = opts;

  // Engine-aware: route SQL through the active BrainEngine. Both Postgres
  // and PGLite carry access_tokens + mcp_request_log in their schemas
  // (pglite-schema.ts:478,495 and schema.sql), so the legacy bearer-auth
  // path works on either engine without a postgres.js singleton.
  const sql = sqlQueryForEngine(engine);

  // Classified reason for the /health degraded payload — read-only on the
  // stored startup error, wrapped so a classifier bug degrades to a generic
  // token rather than failing the health endpoint.
  const degradedHealthReason = (): string => {
    try {
      const err = degradedLastError(engine);
      return err === undefined ? 'startup_connect_failed' : classifyPgAccessError(err, {}).reason;
    } catch {
      return 'startup_connect_failed';
    }
  };

  const limiters = opts.limiters || buildDefaultLimiters();
  const bodyCap = envInt('GBRAIN_HTTP_MAX_BODY_BYTES', DEFAULT_BODY_CAP);
  const corsAllowlist = parseCorsAllowlist();
  // MEMORY_VERBS v1 [c1]: surface filter applies to THIS transport too —
  // the advertised list AND dispatch (allowedOps), fail-closed. WP4: the
  // GBRAIN_MCP_FORCE_SURFACE kill switch min()s in (narrow-only, FOV-6a);
  // resolved once at startup — this transport builds its tool list once.
  const surface = clampSurface(opts.surface ?? 'full');
  // WP1/D7: this is a network transport — localOnly ops (operator-filesystem
  // reach) never appear in its catalog, matching serve-http's filter. The
  // dispatch-layer backstop denies them even if a caller guesses the name.
  const surfacedOps = filterOpsForSurface(operations.filter(op => !op.localOnly), surface);
  const surfaceAllowedOps: ReadonlySet<string> | undefined =
    surface === 'full' ? undefined : new Set(surfacedOps.map(o => o.name));
  // WP3: strict-params schema emission resolved ONCE at startup from the FILE
  // config plane — this transport builds its tool list once, so a
  // `mcp.strict_params` flip needs a restart here (deliberate; the OAuth
  // serve-http path re-reads dual-plane per request). Dispatch-side
  // enforcement still resolves per call. mcp.advertised_surface (file plane) narrows the tool list only.
  const { fileConfig, operationConfig } = await loadServeConfigs(engine); // #6589: operations see file + env over the DB plane
  const strictParams = parseStrictParamsMode(fileConfig?.mcp?.strict_params) === 'reject';
  const tools = buildToolDefs(advertisedOps(surfacedOps, surface, await resolveAdvertisedSurface(null, fileConfig)), { strictParams });

  /**
   * v0.41.3 (T6): single consolidated CORS header builder. Pre-fix there were
   * two parallel functions (`corsHeaders` for actual requests, `corsPreflightHeaders`
   * for OPTIONS) — the preflight variant unconditionally emitted
   * `Access-Control-Allow-Methods` + `Access-Control-Allow-Headers` to EVERY
   * Origin, leaking the API surface to attackers probing the preflight. The
   * actual-request path was correctly default-deny.
   *
   * One function, one allowlist gate. Methods/Headers only emit when
   * preflight=true AND origin is allowlisted. Allow-Origin emits only when
   * origin is allowlisted (unchanged). `Vary: Origin` pairs with Allow-Origin
   * so caches don't serve allowlisted responses to non-allowlisted requests.
   *
   * `extra` is for response-specific headers (Retry-After, etc.) and is
   * never gated by the allowlist.
   */
  interface CorsHeaderOpts {
    preflight?: boolean;
    extra?: Record<string, string>;
  }
  function corsHeaders(origin: string | null, opts: CorsHeaderOpts = {}): Record<string, string> {
    const { preflight = false, extra = {} } = opts;
    const headers: Record<string, string> = { ...extra };
    const allowed = corsAllowlist && origin && corsAllowlist.has(origin);
    if (allowed) {
      headers['Access-Control-Allow-Origin'] = origin;
      headers['Vary'] = 'Origin';
      if (preflight) {
        headers['Access-Control-Allow-Methods'] = 'POST, OPTIONS';
        headers['Access-Control-Allow-Headers'] = `Content-Type, Authorization, Accept, ${AGENT_LABEL_HEADER}, ${GBRAIN_CLIENT_HEADER}`;
      }
    }
    return headers;
  }

  async function validateToken(authHeader: string | null): Promise<AuthResult> {
    if (!authHeader?.startsWith('Bearer ')) return { ok: false };
    const token = authHeader.slice(7);
    const hash = hashToken(token);
    try {
      // SELECT * reads every schema generation (pre-F3 rows lack the grant columns).
      const [row] = await sql`
        SELECT * FROM access_tokens
        WHERE token_hash = ${hash} AND revoked_at IS NULL
      `;
      if (!row) return { ok: false };
      const rowId = row.id as string;
      const rowName = row.name as string;
      // Debounced fire-and-forget last_used_at update, shared with the OAuth provider.
      void touchTokenLastUsed(sql, row);
      // One grant shape (grants/model.ts) shared with the OAuth provider
      // behind `serve --http`, so the two transports cannot drift; a row still
      // on the legacy shape is converted on this read. Takes holders fail safe
      // to ['world']; #1336 honors the stored source grant.
      const grant = await resolveTokenGrant(sql, row);
      const binding = await tokenMemberBinding(sql, row, row.created_at).catch(() => null); // GBRA-218 verify join
      if (!binding) return { ok: false, code: 'access_member_disabled' };
      const allowList = grant.takesHolders ?? ['world'];
      const { sourceId, allowedSources, hasSourceGrant } = authSourcesFromGrant(grant);
      const auth: AuthInfo = {
        token,
        clientId: rowId,
        principal: { kind: 'legacy_token', id: rowId },
        ...withAttestRight(binding, row, 'legacy'),
        clientName: rowName,
        scopes: grant.scopes,
        sourceId,
        ...(grant.allowedOperations === null ? {} : { allowedOperations: grant.allowedOperations }),
        ...(allowedSources ? { allowedSources } : {}), ...privatePagesAuth(grant),
        ...(storedMinTrust(row.min_trust) ? { minTrust: storedMinTrust(row.min_trust) } : {}),
      };
      return {
        ok: true,
        tokenId: rowId,
        tokenName: rowName,
        takesHoldersAllowList: allowList,
        // v0.34.1 (#861, D13): legacy bearer tokens default to 'default'
        // source unless the token carries an explicit grant (#1336 above).
        sourceId,
        auth,
        // #3242: distinguish "operator granted a scope" from "historical
        // no-grant floor" — only the latter widens to federated sources.
        hasSourceGrant,
      };
    } catch {
      return { ok: false };
    }
  }

  function logRequest(tokenName: string | null, operation: string, status: string, latencyMs: number) {
    sql`INSERT INTO mcp_request_log (token_name, operation, latency_ms, status)
        VALUES (${tokenName}, ${operation}, ${latencyMs}, ${status})`
      .catch(() => { /* best-effort */ });
  }

  const server = Bun.serve({
    port,
    async fetch(req, server) {
      const startedMs = Date.now();
      const url = new URL(req.url);
      const path = url.pathname;
      const origin = req.headers.get('origin');

      // CORS preflight
      if (req.method === 'OPTIONS') {
        return new Response(null, { headers: corsHeaders(origin, { preflight: true }) });
      }

      // Health check — no auth, no rate limit. Probes the DB so orchestration
      // doesn't see "ok" while clients are getting misleading 401s during a DB outage.
      if (path === '/health') {
        // Startup-degraded serve (db-availability 4c): report the classified
        // state WITHOUT touching the engine — a health poller must never
        // consume (or storm) the one lazy reconnect attempt.
        if (isEngineDegraded(engine)) {
          return Response.json(
            { status: 'degraded', version: VERSION, transport: 'http', db: 'unreachable', reason: degradedHealthReason() },
            { status: 503, headers: corsHeaders(origin) },
          );
        }
        try {
          await sql`SELECT 1`;
          return Response.json(
            { status: 'ok', version: VERSION, transport: 'http', db: 'ok' },
            { headers: corsHeaders(origin) },
          );
        } catch (e: any) {
          // Redacted: a driver message can embed the full DSN, and /health is
          // unauthenticated by design.
          const safe = redactUrlsInText(redactConnectionInfo(e?.message ?? 'unknown'));
          return Response.json(
            { status: 'unhealthy', version: VERSION, transport: 'http', db: 'unreachable', error: safe },
            { status: 503, headers: corsHeaders(origin) },
          );
        }
      }

      if (path !== '/mcp') {
        return Response.json({ error: 'not_found' }, { status: 404, headers: corsHeaders(origin) });
      }
      if (req.method !== 'POST') {
        return Response.json({ error: 'method_not_allowed' }, { status: 405, headers: corsHeaders(origin) });
      }

      const ip = resolveClientIp(req, server);

      // Pre-auth IP rate limit. Fires BEFORE the DB lookup so we actually limit brute-force load.
      const ipCheck = limiters.ip.check(ip);
      if (!ipCheck.allowed) {
        logRequest(null, 'unknown', 'rate_limited', Date.now() - startedMs);
        return Response.json(
          { error: 'rate_limited', message: 'Too many requests' },
          {
            status: 429,
            headers: corsHeaders(origin, { extra: { 'Retry-After': String(ipCheck.retryAfter ?? 60) } }),
          },
        );
      }

      // Body cap (stream-counted; chunked transfers caught here, not at req.json).
      const bodyText = await readBodyWithCap(req, bodyCap);
      if (bodyText === null) {
        logRequest(null, 'unknown', 'body_too_large', Date.now() - startedMs);
        return Response.json(
          { error: 'payload_too_large', message: `Request body exceeds ${bodyCap} bytes`, suggestion: oversizeSuggestion(bodyCap) },
          { status: 413, headers: corsHeaders(origin) },
        );
      }

      // Auth.
      const auth = await validateToken(req.headers.get('Authorization'));
      if (!auth.ok) {
        logRequest(null, 'unknown', 'auth_failed', Date.now() - startedMs);
        return Response.json(authFailureBody(auth.code), { status: 401, headers: corsHeaders(origin) });
      }

      // Post-auth token-id rate limit. Limits runaway authed clients.
      const tokCheck = limiters.token.check(auth.tokenId!);
      if (!tokCheck.allowed) {
        logRequest(auth.tokenName!, 'unknown', 'rate_limited', Date.now() - startedMs);
        return Response.json(
          { error: 'rate_limited', message: 'Too many requests for this token' },
          {
            status: 429,
            headers: corsHeaders(origin, { extra: { 'Retry-After': String(tokCheck.retryAfter ?? 60) } }),
          },
        );
      }

      // Parse JSON-RPC body.
      let body: { method?: string; params?: any; id?: any };
      try {
        body = JSON.parse(bodyText);
      } catch (e: any) {
        logRequest(auth.tokenName!, 'unknown', 'parse_error', Date.now() - startedMs);
        return Response.json(
          { error: 'parse_error', message: e?.message ?? 'invalid JSON' },
          { status: 400, headers: corsHeaders(origin) },
        );
      }

      const { method, params, id } = body;
      const audienceRefused = qmAudienceRefusal(req, body, auth.auth!); if (audienceRefused) { logRequest(auth.tokenName!, audienceRefused.log, 'error', Date.now() - startedMs); return Response.json(audienceRefused.body, { headers: corsHeaders(origin) }); }
      // initialize
      if (method === 'initialize') {
        logRequest(auth.tokenName!, 'initialize', 'success', Date.now() - startedMs);
        // Ambient writeback (opt-in, default off): resolved per initialize —
        // fail-closed with a per-engine last-known-good bundle, so a config
        // read failure serves the previous bundle (or the base string), never
        // a wrong posture. The advertised writeback also respects token scopes —
        // extract_facts is advertised only when the resolved surface can
        // actually call it (OV2-14; a verbs/starter-pinned serve must not
        // order agents to call a tool dispatch will deny).
        const writeback = (await resolveAgentWriteback(engine, fileConfig)).bundle;
        const canWriteOp = (name: string) => hasScope(auth.auth!.scopes, 'write') && (!surfaceAllowedOps || surfaceAllowedOps.has(name));
        return Response.json(
          {
            result: {
              protocolVersion: '2025-03-26',
              serverInfo: { name: 'gbrain', version: VERSION, description: MCP_SERVER_DESCRIPTION },
              capabilities: { tools: {}, resources: {} },
              // #4748: contract (+ opt-in writeback section) + deployment identity.
              instructions: resolveMcpInstructions(fileConfig, process.env, {
                writeback: ambientOptsFrom(writeback, { remember: canWriteOp('remember'), extractFacts: canWriteOp('extract_facts'), ...writebackCaller(auth.auth, writeback.enabled ? await engine.getConfig(OWNER_MEMBER_KEY).catch(() => null) : null) }),
                tools: await httpInstructionTools(engine, fileConfig, { ops: surfacedOps, surface, auth: auth.auth!, allowedOps: surfaceAllowedOps }), // F1
                ...await readInstructionContent(engine),
              }),
            },
            jsonrpc: '2.0',
            id,
          },
          { headers: corsHeaders(origin) },
        );
      }

      // notifications/initialized — acknowledge with 204
      if (method === 'notifications/initialized') {
        return new Response(null, { status: 204, headers: corsHeaders(origin) });
      }

      if (method === 'resources/list' || method === 'resources/read') {
        const resources = createSkillResources(engine, async () => ({ remote: true, transport: 'http',
          auth: auth.auth!, sourceId: auth.sourceId ?? 'default', allowedOps: surfaceAllowedOps, surface, config: operationConfig }));
        try {
          const result = method === 'resources/list'
            ? { resources: [{ uri: CAPABILITIES_URI, name: 'GBrain capabilities', mimeType: 'application/json' }, ...await resources.list()] }
            : params?.uri === CAPABILITIES_URI
              ? { contents: [{ uri: CAPABILITIES_URI, mimeType: 'application/json', text: JSON.stringify(await resolveAuthCapabilities(auth.auth!, engine, fileConfig ?? { engine: engine.kind })) }] }
              : await resources.read(params?.uri);
          logRequest(auth.tokenName!, method, 'success', Date.now() - startedMs);
          return Response.json({ jsonrpc: '2.0', id, result }, { headers: corsHeaders(origin) });
        } catch {
          logRequest(auth.tokenName!, method, 'error', Date.now() - startedMs);
          return Response.json({ jsonrpc: '2.0', id, error: { code: -32602, message: 'Unknown or unavailable resource' } }, { headers: corsHeaders(origin) });
        }
      }

      // tools/list
      if (method === 'tools/list') {
        // WP1/E5 truthful catalog on THIS transport too: publish-gated ops
        // (`Operation.publishGateKey`) are hidden while their gate resolves
        // off. Read per request (dual-plane, DB > file > false) so a
        // `gbrain config set mcp.publish_skills true` takes effect on the
        // next list with no restart — matching the OAuth transport. The
        // resolver never throws (read failure = hidden, the fail-closed
        // consent posture); the in-handler gates stay as the call-time
        // backstop. Pre-fix this transport listed the gated ops
        // unconditionally, so gates-off served the exact listed-but-denied
        // catalog lie E5 (test/truthful-catalog.e2e-lite.test.ts) pins out.
        const gateDisabled = await disabledOpsForPublishGates(engine, fileConfig);
        const publishGates = publishGatesFromDisabled(surfacedOps, gateDisabled); // A2: one callability predicate + bound-client fence
        const visibleTools = tools.filter(t => {
          const op = operationsByName[t.name];
          return op && isCallable(op, { transport: 'http', surface, scopes: auth.auth!.scopes, publishGates, allowedOps: surfaceAllowedOps })
            && opAllowedForBoundClient(auth.auth!, op);
        });
        logRequest(auth.tokenName!, 'tools/list', 'success', Date.now() - startedMs);
        return Response.json(
          { result: { tools: visibleTools }, jsonrpc: '2.0', id },
          { headers: corsHeaders(origin) },
        );
      }

      // tools/call — dispatch through shared dispatch.ts (parity with stdio)
      if (method === 'tools/call') {
        const toolName: string = params?.name ?? 'unknown';
        const args: Record<string, unknown> = params?.arguments ?? {};
        const op = operationsByName[toolName];
        // #5575: cliOnly ops reach the dispatcher's trusted_local_only refusal (the host command), never a grant-widening scope fix.
        if (op && !op.localOnly && !op.cliOnly && !operationScopesAllowed(auth.auth!.scopes, op)) {
          logRequest(auth.tokenName!, `tools/call:${toolName}`, 'denied_after_list', Date.now() - startedMs);
          // Frozen v1 pair: `error: permission_denied` stays; `code: insufficient_scope`.
          const denial = scopeDeniedError({ op: toolName, required: [op.scope ?? 'read', ...(op.requiredScopes ?? [])], auth: auth.auth,
            transport: 'http', message: `Tool requires ${op.scope ?? 'read'} scope`, legacy_error: 'permission_denied' });
          return Response.json({ jsonrpc: '2.0', id, result: qmMemoryToolResult(toolName, errorResult(denial, { remote: true, transport: 'http', auth: auth.auth }, { op: toolName }), req.headers.get(ACTOR_HEADER) != null) },
            { headers: corsHeaders(origin) });
        }
        // v0.28: thread per-token takes-holder allow-list so takes_list /
        // takes_search / query (when it returns takes) can server-side filter.
        // v0.34.1 (#861): thread source-isolation scope. Legacy access_tokens
        // path defaults to 'default' per AuthResult.sourceId above.
        // #3242: a token with NO operator-set source grant reads across the
        // federated set (config.federated sources), not just the scalar
        // 'default' floor. Granted tokens (hasSourceGrant) never widen.
        let localFederated: string[] | undefined;
        if (auth.hasSourceGrant === false && auth.sourceId) {
          try {
            const { localFederatedSourceIds } = await import('../core/source-resolver.ts');
            localFederated = await localFederatedSourceIds(engine, auth.sourceId, 'seed_default');
          } catch { /* scalar scope stands */ }
        }
        const result = await dispatchToolCall(engine, toolName, args, {
          remote: true,
          admissionOrigin: 'interactive', config: operationConfig,
          // WP1/D7: network transport — the dispatch-layer localOnly
          // backstop keys off this marker.
          transport: 'http', inboundFrameBytes: bodyCap,
          takesHoldersAllowList: auth.takesHoldersAllowList,
          sourceId: auth.sourceId, agentLabel: parseAgentLabel(req.headers.get(AGENT_LABEL_HEADER)),
          ...(localFederated ? { localFederatedSourceIds: localFederated } : {}), onBehalfOf: { header: req.headers.get(ON_BEHALF_OF_HEADER) ?? undefined, requestMeta: params?._meta }, room: { header: req.headers.get(ROOM_HEADER) ?? undefined, requestMeta: params?._meta }, guest: { header: req.headers.get(GUEST_HEADER) ?? undefined, requestMeta: params?._meta }, mcpCaller: { client: auth.auth?.clientName, userAgent: req.headers.get('user-agent') ?? undefined, meta: params?._meta },
          actor: { header: req.headers.get(ACTOR_HEADER) ?? undefined, audience: req.headers.get(QM_AUDIENCE_HEADER) ?? undefined }, // #1336: thread the token's federated_read grant so read ops scope
          // to the operator-granted sources via sourceScopeOpts.
          auth: auth.auth,
          // MEMORY_VERBS v1 [c1/c2]: fail-closed surface enforcement here too.
          ...(surfaceAllowedOps ? { allowedOps: surfaceAllowedOps } : {}),
          surface,
          // WP4 (D2): this transport has no per-client rows, so its surface
          // IS the ceiling request_tools bounds catalog + persist by.
          surfaceCeiling: surface,
          resultRows: resultRowsForRequest(req.headers.get(GBRAIN_CLIENT_HEADER), await resolveResultRowsMode(engine, fileConfig)), // C1; row shape only, never authority
          ...(isGbrainThinClient(req.headers.get(GBRAIN_CLIENT_HEADER)) ? { thinClient: true } : {}), // large pages: default body mode only, never authority
        });
        // Same status taxonomy as the OAuth transport (denied_after_list /
        // success_with_warnings feed the amendment-33 metric + E4 usage).
        const status = requestLogStatusForResult(result);
        logRequest(auth.tokenName!, `tools/call:${toolName}`, status, Date.now() - startedMs);
        return Response.json(
          { result, jsonrpc: '2.0', id },
          { headers: corsHeaders(origin) },
        );
      }

      logRequest(auth.tokenName!, method ?? 'unknown', 'unknown_method', Date.now() - startedMs);
      return Response.json(
        { error: 'unknown_method', message: `Unknown method: ${method}` },
        { status: 400, headers: corsHeaders(origin) },
      );
    },
  });

  console.error(`GBrain HTTP MCP server running on port ${port}`);
  console.error(`  Health: http://localhost:${port}/health`);
  console.error(`  MCP:    http://localhost:${port}/mcp`);
  console.error(`  Auth:   Bearer token required (create with: gbrain auth create <name>)`);
  if (!corsAllowlist) {
    console.error('  CORS:   default-deny. Set GBRAIN_HTTP_CORS_ORIGIN=https://your.app to allow browser clients.');
  } else {
    console.error(`  CORS:   allowlist = ${[...corsAllowlist].join(', ')}`);
  }
  console.error('');
  console.error('⚠️  Do NOT use open OAuth registration for remote MCP access.');
  console.error('   Tokens are managed via: gbrain auth create/list/revoke');

  return server;
}