Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* GBrain HTTP MCP server with OAuth 2.1.
*
* Combines:
* - MCP SDK's mcpAuthRouter (OAuth endpoints: /authorize, /token, /register, /revoke)
* - Custom client_credentials handler (SDK doesn't support CC grant)
* - MCP tool calls at /mcp with bearer auth + scope enforcement
* - Admin dashboard at /admin with cookie auth
* - SSE live activity feed at /admin/events
* - Health check at /health
*
* buildServeHttpApp builds the shared ServeHttpContext and mounts the
* serve-http-<area>.ts modules in registration order; runServeHttp listens.
* This file stays the import surface: every symbol the modules took with them
* is re-exported below.
*/
import { listenOrRefuse, type AdoptableServer } from './serve-http-listen.ts';
import express from 'express';
import type { Socket } from 'net';
import type { Request, RequestHandler, CookieOptions } from 'express';
import cookieParser from 'cookie-parser';
import rateLimit from 'express-rate-limit';
import { randomBytes, createHash } from 'crypto';
import { createMetricsCounters, metricsTrackingMiddleware, mountHealth, mountMetrics, type MetricsCounters } from './serve-http-metrics.ts';
import { ADMIN_TOKEN_SHAPE } from '../core/serve-service.ts';
import { getOAuthProtectedResourceMetadataUrl } from '@modelcontextprotocol/sdk/server/auth/router.js';
import { InvalidTokenError } from '@modelcontextprotocol/sdk/server/auth/errors.js';
import type { OAuthTokenVerifier } from '@modelcontextprotocol/sdk/server/auth/provider.js';
import { createAdminLimiters } from './serve-http-admin-limits.ts';
import { mountOAuth, mountOAuthConsent, mountOwnerLoginLinks } from './serve-http-oauth.ts';
import { createRequireAdmin, mountAdminApi, mountAdminLogin } from './serve-http-admin-api.ts';
import { mountSpa } from './serve-http-spa.ts';
import { mountMcp } from './serve-http-mcp.ts';
import { createWebhookLimiters, mountWebhooks } from './serve-http-webhooks.ts';
import type { BrainEngine } from '../core/engine.ts';
import { operations, type Operation } from '../core/operations.ts';
import {
GBrainOAuthProvider,
DEFAULT_DCR_TTL_MIN_SECONDS,
} from '../core/oauth-provider.ts';
import { canonicalOAuthResource } from '../core/oauth-grants.ts';
import type { McpSurface } from '../mcp/surface.ts';
import { bindResolveIpcForServe } from '../mcp/resolve-ipc-binding.ts';
import { createPersistenceIpcProvider, residentPersistenceConfig } from '../core/persistence/provider.ts';
import { resolveMcpStdioSourceScope } from '../mcp/server.ts';
import { type GBrainConfig } from '../core/config.ts';
import { loadServeConfigs } from '../mcp/serve-config.ts';
import { buildError } from '../core/errors.ts';
import * as db from '../core/db.ts';
import { sqlQueryForEngine, type SqlQuery } from '../core/sql-query.ts';
import { isUndefinedColumnError } from '../core/utils.ts';
import { registerCleanup } from '../core/process-cleanup.ts';
import { VERSION } from '../version.ts';
import { NoticeLedger } from '../core/notice-ledger.ts';
import { createReadinessCache, type ReadinessCache } from '../core/readiness.ts';
import { withLocalScope } from '../core/engine-scope-store.ts';
export { extractGitHubItemRef, githubKindCoversRepo, selectGitHubItemSources } from './serve-http-webhooks.ts';
export { HEALTH_TIMEOUT_MS, probeHealth, probeLiveness, type ProbeHealthResult } from './serve-http-metrics.ts';
export { openAdminSseStream, queryAgentClientSpend, type AgentClientSpend } from './serve-http-admin-api.ts';
export { parseCorsAllowlistOAuth, resolveCorsOrigin, mountOAuthCorsGate } from './serve-http-oauth.ts';
/**
* The narrowest contract this module actually consumes: subscribe, unsubscribe.
* Every return value is discarded, so it is `unknown` rather than `this` — a
* `Pick<>` of the full Node types would demand a fidelity no caller needs and
* no test double can honestly provide.
*/
type EventSubscriber = {
once(event: string, listener: (...args: any[]) => void): unknown;
off(event: string, listener: (...args: any[]) => void): unknown;
};
/**
* Only what socket teardown needs. This one IS a `Pick` of the real type, on
* purpose: no typechecked test double has to satisfy it (fakes reach it through
* `emit`, which is untyped), so binding it to `net.Socket` costs nothing and
* buys drift detection. A hand-written structural shape here would be an
* unchecked assertion — method parameters are bivariant, so annotating the
* listener param would match our own declaration whatever a real socket does.
*/
type TrackedSocket = Pick<Socket, 'destroy' | 'once'>;
type HttpServerLifecycle = EventSubscriber & {
readonly listening: boolean;
close(callback?: (error?: Error) => void): unknown;
// Narrowed to the one event this module subscribes with `on`, so the listener
// parameter is genuinely checked against TrackedSocket. A `(...args: any[])`
// signature here would make the annotation at the call site an unchecked
// assertion — the same defect this file was just cleaned of.
on(event: 'connection', listener: (socket: TrackedSocket) => void): unknown;
};
type SignalSource = EventSubscriber;
type CleanupRegistrar = typeof registerCleanup;
/** How long `server.close()` may hold shutdown before the lifecycle gives up on it. */
const CLOSE_TIMEOUT_MS = 5_000;
/** Live-connection bookkeeping for `waitForHttpServerLifecycle`'s teardown. */
export interface SocketTracker {
/** Sockets currently tracked (live or not yet observed as gone). */
size(): number;
/** Sever every tracked connection so `server.close()` cannot block on them. */
destroyAll(): void;
}
/**
* Track accepted connections so shutdown can sever them.
*
* `close()` stops the listener and then waits for every open connection to
* drain. One attached admin-SSE EventSource — or any keep-alive socket —
* holds it open forever, so shutdown has to sever them itself. Bun 1.3.x
* ships `closeAllConnections()`/`closeIdleConnections()` as no-op stubs, so
* tracking is the only portable teardown.
*/
export function trackServerSockets(server: Pick<HttpServerLifecycle, 'on'>): SocketTracker {
// Hold sockets WEAKLY. Bun's node:http never emits 'close' (nor 'end'/'error')
// on server-side sockets and keeps reporting them open after the peer is
// gone, so no event or state flag can evict a dead connection — a strong Set
// grew by one socket per request forever (each health probe is a fresh TCP
// connection). A dead socket does become unreachable once the runtime drops
// it, so a WeakRef lets it go; a live one stays reachable from the server
// and keeps being tracked. Node does emit 'close' — honor it so the
// bookkeeping stays exact there, and prune collected refs as we go so the
// ref set itself stays bounded by live connections.
const refs = new Set<WeakRef<TrackedSocket>>();
const live = (): TrackedSocket[] => {
const out: TrackedSocket[] = [];
for (const ref of refs) {
const socket = ref.deref();
if (socket === undefined) refs.delete(ref);
else out.push(socket);
}
return out;
};
server.on('connection', (socket: TrackedSocket) => {
live();
const ref = new WeakRef(socket);
refs.add(ref);
socket.once('close', () => refs.delete(ref));
});
return {
size: () => live().length,
destroyAll: () => { for (const socket of live()) socket.destroy(); },
};
}
/**
* Keep the HTTP server strongly referenced and make the daemon lifetime
* explicit instead of relying on runtime-specific event-loop behavior for an
* unobserved `app.listen()` return value. The shared abnormal-termination
* cleanup pass closes it before process exit.
*/
export function waitForHttpServerLifecycle(
server: HttpServerLifecycle,
options: {
signals?: SignalSource;
register?: CleanupRegistrar;
/** Upper bound on how long `close()` may keep shutdown waiting. */
closeTimeoutMs?: number;
log?: (msg: string) => void;
} = {},
): Promise<void> {
const signals = options.signals ?? process;
const register = options.register ?? registerCleanup;
const closeTimeoutMs = options.closeTimeoutMs ?? CLOSE_TIMEOUT_MS;
const log = options.log ?? ((msg: string) => console.error(msg));
const sockets = trackServerSockets(server);
return new Promise<void>((resolve, reject) => {
let settled = false;
let closePromise: Promise<void> | null = null;
const closeServer = (): Promise<void> => {
if (closePromise) return closePromise;
closePromise = new Promise<void>((closeResolve, closeReject) => {
if (!server.listening) {
closeResolve();
return;
}
// Backstop for what the tracker cannot reach: sockets are held weakly,
// so an idle keep-alive wrapper the runtime already collected leaves a
// native handle that close() still waits on. Bound the wait instead
// of hanging the daemon; process exit releases the handle.
// The process still exits: the serve lane's own finishHttpServe
// (serve.ts) disconnects the engine and calls process.exit once the
// lifecycle resolves, so a leaked handle cannot outlive teardown.
let timedOut = false;
const deadline = setTimeout(() => {
timedOut = true;
log(`GBrain HTTP server: close() still waiting after ${closeTimeoutMs}ms — shutting down anyway`);
closeResolve();
}, closeTimeoutMs);
deadline.unref?.();
server.close((error?: Error) => {
clearTimeout(deadline);
if (timedOut) {
// Settled already — a late failure must be seen, not swallowed.
if (error) log(`GBrain HTTP server: close() failed after the deadline: ${error.message}`);
return;
}
if (error) closeReject(error);
else closeResolve();
});
// After close() so the listener stops accepting first, then in-flight
// connections are severed rather than waited on.
sockets.destroyAll();
});
return closePromise;
};
const deregister = register('http-server', closeServer);
const finish = (error?: Error) => {
if (settled) return;
settled = true;
server.off('close', onClose);
server.off('error', onError);
signals.off('SIGINT', onSigint);
deregister();
if (error) reject(error);
else resolve();
};
const onClose = () => finish();
const onError = (error: Error) => finish(error);
const onSigint = () => {
// A close() that reports done — or that the deadline gave up on — ends
// the lifecycle even when the server never emits 'close'.
void closeServer().then(() => finish(), onError);
};
server.once('close', onClose);
server.once('error', onError);
signals.once('SIGINT', onSigint);
});
}
/**
* v0.36.1.x #1024: bootstrap token resolution.
*
* Pure helper (no side effects, no process.exit) so the rule is unit-testable.
* Two outcomes:
* - `ok`: caller proceeds with `{token, fromEnv}`. When the env value is
* undefined, a fresh 32-byte hex token is generated.
* - `error`: caller refuses to start. We require 32+ chars matching
* `[A-Za-z0-9_-]+` for env-supplied tokens — fail-closed beats silently
* accepting a weak admin secret.
*
* `randomBytesHex` is parameterized so tests can inject a deterministic
* fallback without monkey-patching `crypto.randomBytes`.
*/
export type BootstrapTokenResolution =
| { kind: 'ok'; token: string; fromEnv: boolean }
| { kind: 'error'; message: string };
export function resolveBootstrapToken(
envValue: string | undefined,
randomBytesHex: () => string = () => randomBytes(32).toString('hex'),
): BootstrapTokenResolution {
if (envValue === undefined) {
return { kind: 'ok', token: randomBytesHex(), fromEnv: false };
}
const trimmed = envValue.trim();
if (!ADMIN_TOKEN_SHAPE.test(trimmed)) {
return {
kind: 'error',
message:
'GBRAIN_ADMIN_BOOTSTRAP_TOKEN must be at least 32 chars and match [A-Za-z0-9_-]+.\n' +
' Refusing to start with a weak admin bootstrap token. Generate one with:\n' +
' head -c 32 /dev/urandom | base64 | tr -d "+/=" | head -c 48',
};
}
return { kind: 'ok', token: trimmed, fromEnv: true };
}
/**
* #2624: decide whether the generated admin bootstrap token is hidden from
* the startup banner. Fail-safe default: a generated token is NOT printed
* unless stderr is an interactive TTY, so containerized (non-TTY) deploys
* never ship the secret to centralized log storage. Env-sourced tokens are
* always hidden (operator already holds them). Explicit --suppress hides
* everything; --print-admin-token forces the raw value even on a non-TTY.
*/
export function shouldSuppressBootstrapPrint(opts: {
suppress: boolean;
fromEnv: boolean;
forcePrint: boolean;
isTty: boolean;
}): boolean {
if (opts.suppress) return true;
if (opts.fromEnv) return true;
if (opts.forcePrint) return false;
return !opts.isTty;
}
export type OAuthTokenRateLimitConfig = {
windowMs: number;
max: number;
};
function parsePositiveIntEnv(value: string | undefined, fallback: number): number {
if (value === undefined) return fallback;
const parsed = Number.parseInt(value, 10);
return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
}
export function resolveOAuthTokenRateLimit(env: NodeJS.ProcessEnv = process.env): OAuthTokenRateLimitConfig {
return {
windowMs: parsePositiveIntEnv(env.GBRAIN_OAUTH_TOKEN_RATE_LIMIT_WINDOW_MS, 15 * 60 * 1000),
max: parsePositiveIntEnv(env.GBRAIN_OAUTH_TOKEN_RATE_LIMIT_MAX, 50),
};
}
/**
* Resolve `GBRAIN_HTTP_TRUST_PROXY` into a value Express's `app.set('trust
* proxy', ...)` accepts. Pure function so the test surface is one place,
* not the whole Express stack.
*
* Mapping:
* - unset / empty → 'loopback' (pre-v0.41.3 default; trusts only
* 127.0.0.1, ::1, ::ffff:127.0.0.1, fc00::/7)
* - '0' / 'false' → false (trust nothing; req.ip is socket peer regardless
* of X-Forwarded-For)
* - '1' / 'true' → 1 (trust exactly one hop; safe for Fly.io / Render /
* single-layer reverse proxy; matches the legacy transport's '==1' check)
* - other numeric → parseInt (trust N hops)
* - any other string → pass through verbatim (Express accepts named modes
* like 'uniquelocal', 'linklocal', and CIDR/IP lists)
*
* SECURITY: only set GBRAIN_HTTP_TRUST_PROXY when BOTH (a) gbrain is
* reachable only via a trusted reverse proxy, AND (b) the proxy strips
* client-supplied X-Forwarded-For headers before re-emitting its own.
* Otherwise clients can spoof their IP and defeat the pre-auth IP rate
* limit. See SECURITY.md "Reverse-proxy trust" for the full contract.
*/
export function resolveTrustProxy(env: string | undefined): string | number | boolean {
if (env === undefined || env === '') return 'loopback';
if (env === '0' || env === 'false') return false;
if (env === '1' || env === 'true') return 1;
if (/^\d+$/.test(env)) return parseInt(env, 10);
return env;
}
interface ServeHttpOptions {
port: number;
tokenTtl: number;
enableDcr: boolean;
/**
* #1353: allow the consent-bypassing client_credentials grant on the DCR path.
* Off by default; DCR clients default to authorization_code. Implies enableDcr.
*/
enableDcrInsecure?: boolean;
/**
* Public URL the server is reachable at (e.g., https://brain.example.com).
* Used as the OAuth issuer in discovery metadata. Defaults to
* http://localhost:{port} when unset. Required for production deployments
* behind reverse proxies, ngrok tunnels, or any non-loopback URL — the
* issuer claim in tokens MUST match the discovery URL clients hit.
*/
publicUrl?: string;
/**
* When true, write raw request payloads to mcp_request_log + the admin SSE
* feed. Default false: payloads are summarized via dispatch.summarizeMcpParams
* (declared keys only, no values, no attacker-controlled key names).
*
* Operators running gbrain on their own laptop and debugging agent behavior
* can flip this on with `--log-full-params`. The flag prints a loud warning
* at startup so the privacy posture change is visible.
*/
logFullParams?: boolean;
/**
* Network interface(s) to bind. Defaults to `127.0.0.1` (loopback only) in
* v0.34.1+ — gbrain's primary use case is a personal-knowledge brain on a
* laptop, and the pre-v0.34 default of `0.0.0.0` made it one accidental
* `--http` invocation away from publishing the brain to a LAN.
*
* Server operators who DO want to accept remote connections pass
* `--bind 0.0.0.0` (or a specific interface IP). When `--public-url` is
* set but `--bind` is unset, a stderr WARN fires at startup recommending
* the explicit flag — defaulting to loopback while declaring a public URL
* is almost always a misconfiguration.
*/
bind?: string;
/**
* v0.36.x #1024: suppress the printed admin bootstrap token line on
* startup. Combined with `GBRAIN_ADMIN_BOOTSTRAP_TOKEN`, lets long-lived
* production deployments avoid leaking the token into log aggregators on
* every supervisor-managed restart. When the env var is NOT set, this
* flag still suppresses the print — operators take responsibility for
* tracking the regenerated value through other means.
*/
suppressBootstrapToken?: boolean;
/**
* MEMORY_VERBS v1 + WP4: tool-surface mode. 'verbs' = exactly the seven
* protocol verbs; 'starter' = the STARTER_OPS daily-driver set; 'full'
* (default) = every non-localOnly operation. Enforced on the tool list AND
* in dispatch (fail-closed). WP4/D2: this is the server CEILING — each
* request resolves min(ceiling, client row surface ?? config default),
* so per-client rows can narrow below it but never widen past it.
*/
surface?: McpSurface;
/** --advertise: the surface tools/list shows to clients without their own surface (callable set unchanged). */
advertise?: McpSurface;
/**
* #2624: force-print the generated admin bootstrap token even on a
* non-TTY (containerized) start. By default the raw token is only printed
* when stderr is an interactive TTY, so it never lands in centralized log
* storage for headless deploys. Set this when you genuinely need the value
* captured to a non-interactive log and accept the leak.
*/
printAdminToken?: boolean;
/** A status-only serve's bound listener: recovery swaps its handler to this app instead of binding (serve-http-listen.ts). */
adoptServer?: AdoptableServer;
}
/**
* Skill-publishing status for the startup banner + operator nudge. When OFF,
* connected agents (Codex / Claude Code / Perplexity / Cowork) cannot call
* `list_skills` / `get_skill`, so the host's skill catalog is INVISIBLE to them
* — the core tools (search / query / get_page / put_page / capture / think /
* find_experts) still work. Pure so the banner value + nudge copy are
* unit-tested without standing up a server. See `readMcpPublishSkills`
* (skill-catalog.ts) for the config resolution this status reflects.
*/
export function skillPublishStatus(publishSkills: boolean): { bannerValue: string; nudge: string | null } {
if (publishSkills) return { bannerValue: 'published', nudge: null };
return {
bannerValue: 'not published',
nudge:
"[serve-http] NOTE: skill publishing is OFF — connected agents can't call " +
'list_skills / get_skill, so this brain’s skill catalog is invisible to them ' +
'(core tools like search / query / think still work). Enable it with: ' +
'gbrain config set mcp.publish_skills true',
};
}
/**
* #1196: startup embedding-width guard for stateless host deployments.
*
* `embedding_model` / `embedding_dimensions` are file/env-plane only, so a
* container booted WITHOUT a config.json (stateless host) resolves the
* compiled-in default embedding width. Against an existing brain whose
* `content_chunks.embedding` is a different `vector(N)`, every write then
* fails with an opaque dim mismatch. Run doctor's existing
* embedding_width_consistency check at serve startup and return a loud
* banner (with the paste-ready recipe) when it isn't ok. Fail-open: a check
* error never blocks serving read traffic.
*/
export async function embeddingWidthStartupWarning(engine: BrainEngine): Promise<string | null> {
try {
const { checkEmbeddingWidthConsistency } = await import('./doctor.ts');
const check = await checkEmbeddingWidthConsistency(engine);
if (check.status === 'ok') return null;
return (
`[serve-http] WARNING: embedding width check failed — writes that embed will fail until fixed.\n` +
`${check.message}\n` +
`Stateless hosts: embedding_model/embedding_dimensions resolve from env/config.json only — ` +
`set GBRAIN_EMBEDDING_MODEL / GBRAIN_EMBEDDING_DIMENSIONS (or mount config.json) to match the brain's schema.`
);
} catch {
return null;
}
}
/**
* Per-server state shared by every `mount<Area>(app, ctx)` module. Built once
* by buildServeHttpApp; modules destructure what they use and never construct
* their own limiter, session map, nonce store or event fan-out (a second
* instance would silently split a rate limit or a session).
*/
export interface ServeHttpContext {
engine: BrainEngine;
noticeLedger?: NoticeLedger; // A6: notice dedupe/coaching budget keyed by principal + session (HTTP is stateless)
readinessCache?: ReadinessCache; // A7/F1/F2: probed readiness (60 s, single-flight) for initialize tails and gbrain://capabilities
config: GBrainConfig | (Partial<GBrainConfig> & { engine: 'pglite' });
sql: SqlQuery;
bind: string;
enableDcr: boolean;
logFullParams: boolean | undefined;
/** --surface: the server tool-surface ceiling. */
surface: McpSurface | undefined;
/** --advertise: what tools/list shows; null leaves it to mcp.advertised_surface. */
advertise?: McpSurface | null;
/** Every non-localOnly operation: the only op list the network surface sees. */
mcpOperationsBase: Operation[];
issuerUrl: URL;
mcpResourceUrl: URL;
resourceMetadataUrl: string;
oauthProvider: GBrainOAuthProvider;
/** Access-token verifier that also rejects tokens bound to a different resource. */
resourceVerifier: OAuthTokenVerifier;
bootstrapHash: string;
/** Admin cookie sessions: sessionId -> expiresAt. */
adminSessions: Map<string, number>;
adminCookie: (req: Request, maxAge: number) => CookieOptions;
/** Magic-link nonces: nonce -> expiresAt. */
magicLinkNonces: Map<string, number>;
consumedNonces: Set<string>;
requireAdmin: RequestHandler;
adminLimits: ReturnType<typeof createAdminLimiters>;
ccRateLimiter: RequestHandler;
ingestRateLimiter: RequestHandler;
githubWebhookLimiter: RequestHandler;
metricsCounters: MetricsCounters;
sseClients: Set<express.Response>;
broadcastEvent: (event: Record<string, unknown>) => void;
}
/**
* Startup stderr notices, in order: --log-full-params, --public-url without
* --bind, embedding width, skill publishing, brain-resident skillpacks.
* Returns the banner's skill-publishing status.
*/
async function logServeHttpStartup(engine: BrainEngine, options: ServeHttpOptions, config: ServeHttpContext['config']) {
const { publicUrl, logFullParams } = options;
if (logFullParams) {
console.error(
'[serve-http] WARNING: --log-full-params writes raw request payloads to mcp_request_log + SSE feed. Disable for shared dashboards or production.',
);
}
if (publicUrl && options.bind === undefined) {
console.error(
'[serve-http] WARNING: --public-url is set but --bind is not. Default bind changed to 127.0.0.1 in v0.34.1; remote clients reaching the public URL will be refused. Pass --bind 0.0.0.0 to accept all interfaces.',
);
}
// #1196: fail-loud at startup when the resolved embedding width diverges
// from the brain's actual vector(N) column (stateless containers falling
// through to the compiled-in default). Non-fatal: reads still work.
{
const widthWarn = await embeddingWidthStartupWarning(engine);
if (widthWarn) console.error(widthWarn);
}
// Skill-publishing status for the banner + nudge. Mirrors readMcpPublishSkills
// (skill-catalog.ts): the DB plane (`gbrain config set`) wins over the file
// plane. When OFF, a connected coding agent can't see the host's skill
// catalog — surface that to the operator at startup rather than letting them
// discover it via an empty list_skills on the agent side.
let publishSkills = false;
try {
const dbVal = await engine.getConfig('mcp.publish_skills');
publishSkills = dbVal != null ? dbVal === 'true' : config?.mcp?.publish_skills === true;
} catch {
publishSkills = config?.mcp?.publish_skills === true;
}
const skillStatus = skillPublishStatus(publishSkills);
if (skillStatus.nudge) console.error(skillStatus.nudge);
// Note when this brain ships a brain-resident pack so the operator knows
// connecting harnesses will be offered it (only meaningful when publishing
// is on — list_brain_skillpack is gated by the same flag). Fail-open.
if (publishSkills) {
try {
const { loadAllSources } = await import('../core/sources-load.ts');
const { loadSkillpackManifest } = await import('../core/skillpack/manifest-v1.ts');
const { existsSync } = await import('fs');
const { join } = await import('path');
const srcs = await loadAllSources(engine);
let n = 0;
for (const s of srcs) {
if (!s.local_path || !existsSync(join(s.local_path, 'skillpack.json'))) continue;
try {
if (loadSkillpackManifest(s.local_path).brain_resident === true) n++;
} catch {
/* malformed pack → ignore */
}
}
if (n > 0) {
console.error(
`[serve-http] NOTE: ${n} source${n === 1 ? '' : 's'} ship a brain-resident skillpack — ` +
'connecting harnesses can discover it via list_brain_skillpack and will be offered to install it.',
);
}
} catch {
/* fail-open: banner is cosmetic */
}
}
return skillStatus;
}
async function resolveDcrTtlWindow(engine: BrainEngine, tokenTtl: number): Promise<{ dcrTtlMinSeconds: number; dcrTtlMaxSeconds: number }> {
const parseDcrTtlBound = (raw: unknown, fallback: number): number => {
const n = Number(raw);
return raw != null && Number.isFinite(n) && n >= 1 ? Math.floor(n) : fallback;
};
let dcrTtlMinSeconds = DEFAULT_DCR_TTL_MIN_SECONDS;
let dcrTtlMaxSeconds = Math.max(tokenTtl, dcrTtlMinSeconds);
try {
dcrTtlMinSeconds = parseDcrTtlBound(await engine.getConfig('oauth.dcr_ttl_min_seconds'), DEFAULT_DCR_TTL_MIN_SECONDS);
dcrTtlMaxSeconds = parseDcrTtlBound(await engine.getConfig('oauth.dcr_ttl_max_seconds'), Math.max(tokenTtl, dcrTtlMinSeconds));
} catch {
// Config read is best-effort; the fail-closed defaults stand.
dcrTtlMaxSeconds = Math.max(tokenTtl, dcrTtlMinSeconds);
}
if (dcrTtlMinSeconds > dcrTtlMaxSeconds) {
console.error(
`[serve-http] WARNING: oauth.dcr_ttl_min_seconds (${dcrTtlMinSeconds}) exceeds ` +
`oauth.dcr_ttl_max_seconds (${dcrTtlMaxSeconds}); collapsing the window to ` +
`the min bound (${dcrTtlMinSeconds}).`,
);
dcrTtlMaxSeconds = dcrTtlMinSeconds;
}
return { dcrTtlMinSeconds, dcrTtlMaxSeconds };
}
/**
* Builds the complete Express app for `gbrain serve --http`: startup checks,
* OAuth provider, admin auth, every route and middleware in registration
* order. `runServeHttp` is the production caller; it owns listen, the banner,
* the resolve-IPC binding and shutdown.
*/
export async function buildServeHttpApp(app: express.Express, engine: BrainEngine, options: ServeHttpOptions) {
const { port, tokenTtl, enableDcr, enableDcrInsecure, publicUrl, logFullParams } = options;
// v0.34.1 (#864, D11): default bind flipped from 0.0.0.0 to 127.0.0.1.
// gbrain's primary use case is a personal-knowledge brain on a laptop;
// the pre-v0.34 default exposed brains on every interface. Server
// operators who need remote access pass `--bind 0.0.0.0` (or a specific
// interface). Declaring `--public-url` without `--bind` is almost always
// a misconfiguration; we WARN to stderr at startup in that case rather
// than silently binding loopback only.
const bind = options.bind ?? '127.0.0.1';
const config = (await loadServeConfigs(engine)).operationConfig || { engine: 'pglite' as const }; // #6589: CLI parity, read once
const skillStatus = await logServeHttpStartup(engine, options, config);
// Engine-aware SQL adapter. Routes through engine.executeRaw on both
// Postgres and PGLite — the OAuth/admin/auth surface no longer requires
// a postgres.js singleton, so `gbrain serve --http` works against PGLite
// brains too. The narrow SqlQuery contract is scalar-binds-only; JSONB
// writes use executeRawJsonb (see mcp_request_log INSERT sites below).
const sql = sqlQueryForEngine(engine);
// Initialize OAuth provider. F12 cleanup: DCR-disable now flips a
// constructor option instead of monkey-patching `_clientsStore` after
// construction. Same outcome (no /register endpoint when --enable-dcr
// is not passed); cleaner shape for tests and future maintainers.
// #2179: admin-configured clamp window for DCR-requested token TTLs.
// DB-plane config keys (`gbrain config set oauth.dcr_ttl_min_seconds ...`).
// FAIL-CLOSED defaults: an unset/invalid max is bounded by the operator's
// own --token-ttl (never a fixed permissive ceiling), and an inverted
// window collapses to the min bound — the same direction clampDcrTokenTtl
// itself resolves. A bad config narrows the window; it never widens it.
const { dcrTtlMinSeconds, dcrTtlMaxSeconds } = await resolveDcrTtlWindow(engine, tokenTtl);
// The issuer URL goes into discovery metadata + token iss claims. It MUST
// match the URL clients actually hit, or strict OAuth clients reject tokens
// (RFC 8414 §3.3). Honor --public-url for production deployments behind
// reverse proxies / tunnels; default to localhost for dev.
const issuerUrl = new URL(publicUrl || `http://localhost:${port}`);
// MCP authorization spec (2025-06-18 draft §5.1) and RFC 9728 require the
// protected resource server to return its discovery metadata URL in the
// WWW-Authenticate header on 401 responses:
//
// WWW-Authenticate: Bearer resource_metadata="<URL>"
//
// Clients (claude.ai, Cursor, every other MCP-aware OAuth client) use that
// URL to find the authorization-server discovery doc + token endpoint
// without the user having to paste those URLs manually. Pre-fix the header
// shipped `Bearer error="invalid_token", ...` with no resource_metadata
// parameter, so MCP clients couldn't begin the OAuth flow from a fresh
// 401 — they would silently fail to connect with a generic "couldn't
// reach the MCP server" error.
// RFC 9728 / MCP auth spec: the protected-resource metadata describes the
// resource the client connects to (/mcp), not the authorization-server root.
// Without resourceServerUrl the SDK falls back to issuerUrl, advertising
// `resource: "https://host/"` and 404ing the path-based PRM URL
// (/.well-known/oauth-protected-resource/mcp) that clients derive from the
// connector URL (#4893). The 401 challenge's resource_metadata URL is
// derived from the same value so the two can never drift apart.
const mcpResourceUrl = new URL('/mcp', issuerUrl);
const resourceMetadataUrl = getOAuthProtectedResourceMetadataUrl(mcpResourceUrl);
const oauthProvider = new GBrainOAuthProvider({
sql,
transaction: fn => engine.transaction(tx => fn(sqlQueryForEngine(tx))),
tokenTtl,
dcrDisabled: !enableDcr,
allowClientCredentialsDcr: enableDcrInsecure === true,
dcrTtlMinSeconds,
dcrTtlMaxSeconds,
resourceUrl: mcpResourceUrl,
});
// #1353: loud stderr security WARN when DCR is enabled. DCR is an
// unauthenticated network registration endpoint; surface the posture change
// (and the extra blast radius of --enable-dcr-insecure) so it's visible in
// logs, not buried in the neutral "DCR: enabled" banner line.
if (enableDcr) {
console.error(
'SECURITY WARNING: Dynamic Client Registration (--enable-dcr) is ON. Any network caller ' +
'can self-register an OAuth client, limited to read/write (read-only for client_credentials ' +
'under --enable-dcr-insecure); every authorization_code connection needs owner approval in the admin UI. See SECURITY.md.',
);
if (enableDcrInsecure) {
console.error(
'SECURITY WARNING: --enable-dcr-insecure is ON — self-registered DCR clients may ' +
'request the client_credentials grant, which BYPASSES owner approval (they are capped ' +
'at read-only scope). Only use this on a trusted network.',
);
}
}
// Sweep expired tokens on startup (non-blocking)
try {
const swept = await oauthProvider.sweepExpiredTokens();
if (swept > 0) console.error(`Swept ${swept} expired tokens`);
} catch (e) {
console.error('Token sweep failed (non-blocking):', e instanceof Error ? e.message : e);
}
// v0.36.x #1024: bootstrap token sourcing.
//
// Default: regenerate per process start, print to stderr so the operator
// can paste into /admin login. Stable across restarts only when env var
// is set. The env override must be a strong secret — `[A-Za-z0-9_-]{32+}`
// — otherwise refuse to start. Logging the bootstrap-token value every
// restart is the original gripe; with `GBRAIN_ADMIN_BOOTSTRAP_TOKEN` set
// and `--suppress-bootstrap-token`, no value reaches the log.
const resolved = resolveBootstrapToken(process.env.GBRAIN_ADMIN_BOOTSTRAP_TOKEN);
if (resolved.kind === 'error') {
console.error(resolved.message);
process.exit(1);
}
let bootstrapToken: string = resolved.token;
let bootstrapFromEnv: boolean = resolved.fromEnv;
const bootstrapHash = createHash('sha256').update(bootstrapToken).digest('hex');
const suppressBootstrapPrint = shouldSuppressBootstrapPrint({
suppress: options.suppressBootstrapToken === true,
fromEnv: bootstrapFromEnv,
forcePrint: options.printAdminToken === true,
isTty: process.stderr.isTTY === true,
});
const adminSessions = new Map<string, number>(); // sessionId → expiresAt
// SSE clients for live activity feed
const sseClients = new Set<express.Response>();
// Broadcast MCP request event to all SSE clients
function broadcastEvent(event: Record<string, unknown>) {
const data = `data: ${JSON.stringify(event)}\n\n`;
for (const client of sseClients) {
try { client.write(data); } catch { sseClients.delete(client); }
}
}
// v0.41.3 (T8): configurable trust-proxy via GBRAIN_HTTP_TRUST_PROXY env.
// Default 'loopback' (trust Caddy/Tailscale on the same host) preserves
// pre-v0.41.3 behavior. Operators behind Fly.io / Render / Vercel / nginx
// set GBRAIN_HTTP_TRUST_PROXY=1 (one hop) so X-Forwarded-For lands as the
// real client IP for rate-limiting and req.secure detection. The legacy
// transport already reads this env var (src/mcp/http-transport.ts:111)
// for the same purpose; T8 makes the Express path agree.
app.set('trust proxy', resolveTrustProxy(process.env.GBRAIN_HTTP_TRUST_PROXY));
// ---------------------------------------------------------------------------
// Cookie parsing — required for /admin auth (express 5 has no built-in)
// ---------------------------------------------------------------------------
app.use(cookieParser());
// Installed before every admin login, nonce and API handler.
app.use((req, res, next) => {
if (req.path === '/admin' || req.path.startsWith('/admin/')) {
res.set({ 'Cache-Control': 'no-store', 'Referrer-Policy': 'no-referrer', 'X-Frame-Options': 'DENY' });
}
next();
});
// #3893 (reimplemented from @y2688): request metrics. Mounted here, BEFORE
// every route — Express only applies `app.use` middleware to routes
// registered after it, and the original PR mounted the tracker after most
// routes, so they were never counted. The /metrics route itself lives
// below requireAdmin's definition.
const metricsCounters = createMetricsCounters();
app.use(metricsTrackingMiddleware(metricsCounters));
const oauthTokenRateLimit = resolveOAuthTokenRateLimit();
const ccRateLimiter = rateLimit({
windowMs: oauthTokenRateLimit.windowMs,
max: oauthTokenRateLimit.max,
standardHeaders: true,
legacyHeaders: false,
message: { error: 'too_many_requests', error_description: 'Rate limit exceeded. Try again later.' },
});
const adminLimits = createAdminLimiters();
// The SDK validates expiry/scopes but leaves audience enforcement to us.
// Legacy grants without a resource retain their existing compatibility; an
// origin-bound token minted before #5222 passes the same canonicalizer.
const resourceVerifier = {
async verifyAccessToken(token: string) {
const auth = await oauthProvider.verifyAccessToken(token);
if (auth.resource) {
try {
canonicalOAuthResource(auth.resource, mcpResourceUrl);
} catch {
throw new InvalidTokenError('Token is bound to a different resource');
}
}
return auth;
},
};
// F9: cookie `secure` flag honors both the request's TLS state (req.secure
// is set when express trust-proxy lands an X-Forwarded-Proto: https) AND
// the operator's declared issuer protocol (so a Cloudflare-tunnel deploy
// where the connection inside the tunnel looks like http but the public
// URL is https still tags cookies Secure). Without this, an attacker on
// the network path could MITM the admin cookie over plaintext.
const adminCookie = (req: Request, maxAge: number) => ({
httpOnly: true,
sameSite: 'strict' as const,
secure: req.secure || issuerUrl.protocol === 'https:',
maxAge,
path: '/admin',
});
// The HTTP MCP surface never sees localOnly operations; serve-http-mcp.ts
// narrows this list further per request (surface, grants, scope).
const mcpOperationsBase = operations.filter(op => !op.localOnly);
const requireAdmin = createRequireAdmin(adminSessions);
const { ingestRateLimiter, githubWebhookLimiter } = createWebhookLimiters();
const ctx: ServeHttpContext = {
noticeLedger: new NoticeLedger(), readinessCache: createReadinessCache(), engine, config, sql, bind, enableDcr, logFullParams, surface: options.surface, advertise: options.advertise ?? null, mcpOperationsBase,
issuerUrl, mcpResourceUrl, resourceMetadataUrl, oauthProvider, resourceVerifier,
bootstrapHash, adminSessions, adminCookie,
magicLinkNonces: new Map<string, number>(),
consumedNonces: new Set<string>(),
requireAdmin, adminLimits, ccRateLimiter, ingestRateLimiter, githubWebhookLimiter,
metricsCounters, sseClients, broadcastEvent,
};
mountOAuth(app, ctx);
mountHealth(app, ctx);
mountAdminLogin(app, ctx);
mountOwnerLoginLinks(app, ctx);
mountOAuthConsent(app, oauthProvider, requireAdmin, adminLimits.consent);
mountMetrics(app, ctx);
mountAdminApi(app, ctx);
await mountSpa(app, ctx);
mountMcp(app, ctx);
mountWebhooks(app, ctx);
return { bind, config, sql, issuerUrl, skillStatus, bootstrapToken, bootstrapFromEnv, suppressBootstrapPrint };
}
/** The HTTP server runs in a local scope; each POST /mcp enters its engine's scope (serve-http-mcp.ts). */
export function runServeHttp(engine: BrainEngine, options: ServeHttpOptions) {
return withLocalScope(async () => {
const { port, tokenTtl, enableDcr, enableDcrInsecure } = options;
// Express 5 app
const app = express();
const { bind, config, sql, issuerUrl, skillStatus, bootstrapToken, bootstrapFromEnv, suppressBootstrapPrint } =
await buildServeHttpApp(app, engine, options);
// ---------------------------------------------------------------------------
// Start server
// ---------------------------------------------------------------------------
const clientCount = await sql`SELECT count(*)::int as count FROM oauth_clients`;
const httpServer = await listenOrRefuse(app, port, bind, options.adoptServer);
console.error(`
╔══════════════════════════════════════════════════════╗
║ GBrain MCP Server v${VERSION.padEnd(37)}║
╠══════════════════════════════════════════════════════╣
║ Port: ${String(port).padEnd(40)}║
║ Bind: ${bind.padEnd(40)}║
║ Engine: ${(config.engine || 'pglite').padEnd(40)}║
║ Issuer: ${issuerUrl.origin.padEnd(40)}║
║ Clients: ${String((clientCount[0] as any).count).padEnd(40)}║
║ DCR: ${(enableDcr ? (enableDcrInsecure ? 'enabled (INSECURE: read-only M2M)' : 'enabled (consent; DCR max read write)') : 'disabled').padEnd(40)}║
║ Skills: ${skillStatus.bannerValue.padEnd(40)}║
║ Token TTL: ${(tokenTtl + 's').padEnd(40)}║
╠══════════════════════════════════════════════════════╣
║ Admin: http://localhost:${port}/admin${' '.repeat(Math.max(0, 19 - String(port).length))}║
║ MCP: http://localhost:${port}/mcp${' '.repeat(Math.max(0, 21 - String(port).length))}║
║ Health: http://localhost:${port}/health${' '.repeat(Math.max(0, 18 - String(port).length))}║
╠══════════════════════════════════════════════════════╣
${bootstrapFromEnv
? '║ Admin Token: from $GBRAIN_ADMIN_BOOTSTRAP_TOKEN ║\n╚══════════════════════════════════════════════════════╝'
: suppressBootstrapPrint
? '║ Admin Token: hidden (non-TTY log-leak guard) ║\n║ set $GBRAIN_ADMIN_BOOTSTRAP_TOKEN, or pass ║\n║ --print-admin-token on a trusted terminal. ║\n╚══════════════════════════════════════════════════════╝'
: `║ Admin Token (paste into /admin login): ║\n║ ${bootstrapToken.substring(0, 50)} ║\n║ ${bootstrapToken.substring(50).padEnd(50)} ║\n╚══════════════════════════════════════════════════════╝`}
`);
// #4474: bind the resolve-IPC unix socket under --http too. This is the
// exact posture `gbrain bootstrap harness` targets — without the listener
// every wired lifecycle hook (SessionStart / UserPromptSubmit / PreCompact)
// degrades to `no_serve` forever, and on a PGLite brain there is no local
// recovery (the http serve owns the single-writer lock, so a second stdio
// serve can't provide the socket). Shares the stdio path's wiring via
// bindResolveIpcForServe; best-effort — failure to bind never blocks the
// HTTP server.
const ipcBinding = await bindResolveIpcForServe(
engine,
(await resolveMcpStdioSourceScope(engine)).sourceId,
await createPersistenceIpcProvider(engine, residentPersistenceConfig(config) ?? config),
);
if (ipcBinding.socketPath) {
console.error(` Resolve IPC: ${ipcBinding.socketPath}`);
}
// SIGTERM/SIGHUP route through process-cleanup's pass and then
// `process.exit`, which skips cli.ts's finally-teardown — so on those
// signals the PGLite write handle was never closed. An unclosed PGLite
// can leave the control file pointing at a checkpoint record whose WAL
// page never reached disk; every later start then dies with
// `PANIC: could not locate a valid checkpoint record` (surfaced as the
// misleading WASM-init hint) and the daemon crash-loops until a human
// intervenes. Registering the engine here gives abnormal termination
// the same clean close the SIGINT path already gets via the cli
// teardown. Deregistered on normal return so the cli finally remains
// the single owner of orderly shutdown.
const deregisterIpcCleanup = registerCleanup('resolve-ipc-close', async () => {
ipcBinding.close();
});
// Automatic facts drain (Lane D): the resident HTTP serve owns a PGLite brain the way stdio serve does.
const { startFactsDrainScheduler } = await import('../core/facts/drain-scheduler.ts');
const factsDrain = startFactsDrainScheduler(engine, { owner: 'serve_http', log: (line) => console.error(line) });
// #6317 (B4): one notice when a managed source's sync data stops moving (reader in persistence/sync-movement.ts).
const { startMovementWatch } = await import('../core/persistence/sync-movement.ts');
const movementWatch = startMovementWatch(engine, { log: (line) => console.error(line) });
// #6858 ask 6: on-commit sync of this host's managed checkouts while `sync.on_commit` is on (serve-head-watcher.ts).
const { startServeHeadWatcher } = await import('../core/serve-head-watcher.ts');
const headWatcher = startServeHeadWatcher(engine, { log: (line) => console.error(line), resident: 'serve-http' });
const deregisterEngineCleanup = registerCleanup('pglite-engine-disconnect', async () => {
await headWatcher.stop();
movementWatch.stop();
await factsDrain.stop();
await engine.disconnect();
});
try {
await waitForHttpServerLifecycle(httpServer);
} finally {
await headWatcher.stop();
movementWatch.stop();
await factsDrain.stop();
// Close the IPC listener + reap the socket file on orderly shutdown
// (abnormal termination goes through the registered cleanup above).
ipcBinding.close();
deregisterIpcCleanup();
deregisterEngineCleanup();
}
});
}