Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* 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;
}