Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Request-outcome gates for the serve-http module split (refactor wave 1,
* TE1 / T-6 / S-1): the production app from `buildServeHttpApp` on an
* in-memory PGLite brain, driven over real HTTP.
*
* Protects: state the split moved into one shared ServeHttpContext and the
* auth decisions the moved routes make: a rate limiter shared across two
* modules, owner cookie vs OAuth admin bearer at /admin/api/*, session
* revocation, the PKCE authorization-code and refresh-token flows through
* owner consent, resource-audience rejection at /mcp, the /mcp dispatch
* context (remote, auth, source scope, surface), the transport whoami and
* gbrain://capabilities report from the verified principal, and the OAuth
* CORS gate ordered ahead of the SDK router's own `*` CORS.
* Fails when: a module builds its own limiter or session map, an OAuth token
* can administer, sign-out leaves a session alive, a flow step breaks, a
* foreign-audience token reaches dispatch, dispatch loses remote/auth/source
* or surface, or a denied preflight reaches the SDK's permissive CORS.
* Why new: the route goldens pin registration order and middleware identity,
* not the outcome of requests through the real stack.
*/
import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
import type { Server } from 'node:http';
import { createHash } from 'node:crypto';
import express from 'express';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { buildServeHttpApp } from '../src/commands/serve-http.ts';
import { VERB_NAMES } from '../src/core/verbs.ts';
import { mintLegacyToken } from '../src/core/token-mint.ts';
import { TEST_PKCE_CHALLENGE, TEST_PKCE_VERIFIER } from './helpers/oauth.ts';
import { withEnv } from './helpers/with-env.ts';
let engine: PGLiteEngine;
beforeAll(async () => {
engine = new PGLiteEngine();
await engine.connect({});
await engine.initSchema();
});
afterAll(async () => {
await engine.disconnect();
});
interface RunningApp {
base: string;
bootstrap: string;
close: () => Promise<void>;
}
const running: RunningApp[] = [];
afterAll(async () => {
for (const app of running) await app.close();
});
async function startApp(opts: { enableDcr?: boolean; surface?: 'verbs' | 'starter' | 'full' } = {}): Promise<RunningApp> {
const app = express();
const server: Server = await new Promise(resolve => {
const s = app.listen(0, '127.0.0.1', () => resolve(s));
});
const address = server.address();
if (!address || typeof address === 'string') throw new Error('expected a TCP address');
const base = `http://127.0.0.1:${address.port}`;
const built = await buildServeHttpApp(app, engine, {
port: address.port, tokenTtl: 3600, enableDcr: opts.enableDcr ?? false, publicUrl: base, surface: opts.surface,
});
const handle: RunningApp = {
base,
bootstrap: built.bootstrapToken,
close: () => new Promise(resolve => { server.closeAllConnections?.(); server.close(() => resolve()); }),
};
running.push(handle);
return handle;
}
async function ownerCookie(app: RunningApp): Promise<string> {
const login = await fetch(`${app.base}/admin/login`, {
method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ token: app.bootstrap }),
});
expect(login.status).toBe(200);
return login.headers.get('set-cookie')!.split(';')[0];
}
let clientSeq = 0;
async function registerClient(app: RunningApp, cookie: string, body: Record<string, unknown>): Promise<{ clientId: string; clientSecret?: string }> {
const res = await fetch(`${app.base}/admin/api/register-client`, {
method: 'POST', headers: { Cookie: cookie, 'Content-Type': 'application/json' },
body: JSON.stringify({ name: `outcome-client-${++clientSeq}`, ...body }),
});
expect(res.status).toBe(200);
return await res.json() as { clientId: string; clientSecret?: string };
}
async function clientCredentialsToken(app: RunningApp, clientId: string, secret: string, scope: string): Promise<string> {
const res = await fetch(`${app.base}/token`, {
method: 'POST', headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
body: new URLSearchParams({ grant_type: 'client_credentials', client_id: clientId, client_secret: secret, scope }),
});
expect(res.status).toBe(200);
return (await res.json() as { access_token: string }).access_token;
}
function mcpPost(app: RunningApp, token: string, method: string, params?: unknown, headers: Record<string, string> = {}): Promise<Response> {
return fetch(`${app.base}/mcp`, {
method: 'POST',
headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json', Accept: 'application/json, text/event-stream', ...headers },
body: JSON.stringify({ jsonrpc: '2.0', id: 1, method, ...(params ? { params } : {}) }),
});
}
async function mcpResult(app: RunningApp, token: string, method: string, params?: unknown): Promise<any> {
const res = await mcpPost(app, token, method, params);
expect(res.status).toBe(200);
const text = await res.text();
const dataLine = text.split('\n').find(l => l.startsWith('data:'));
const rpc = JSON.parse(dataLine ? dataLine.slice('data:'.length) : text);
expect(rpc.error).toBeUndefined();
return rpc.result;
}
function toolPayload(result: any): any {
return JSON.parse(result.content[0].text);
}
describe('shared context: one limiter spans two modules (T-6)', () => {
test('failed owner logins in serve-http-admin-api.ts exhaust the magic-link route in serve-http-oauth.ts', async () => {
const app = await startApp();
const redeem = () => fetch(`${app.base}/admin/auth/not-a-real-nonce`, { redirect: 'manual' });
expect((await redeem()).status).toBe(401);
for (let i = 0; i < 9; i++) {
const res = await fetch(`${app.base}/admin/login`, {
method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ token: 'wrong-owner-credential' }),
});
expect(res.status).toBe(401);
}
// One redemption attempt plus nine failed logins = the 10-failure allowance.
// The magic-link route saw a single request, so its 429 is the login
// module's failures spending the SAME adminLimits.failures store.
expect((await redeem()).status).toBe(429);
const mint = await fetch(`${app.base}/admin/api/issue-magic-link`, { method: 'POST', headers: { Authorization: 'Bearer wrong-owner-credential' } });
expect(mint.status).toBe(429);
});
});
describe('owner administration vs OAuth admin tokens', () => {
test('the owner cookie can use /admin/api/*; an OAuth admin-scoped bearer token cannot', async () => {
const app = await startApp();
const cookie = await ownerCookie(app);
expect((await fetch(`${app.base}/admin/api/stats`, { headers: { Cookie: cookie } })).status).toBe(200);
const { clientId, clientSecret } = await registerClient(app, cookie, { scopes: 'read write admin', grantTypes: ['client_credentials'] });
const token = await clientCredentialsToken(app, clientId, clientSecret!, 'read write admin');
const bearer = await fetch(`${app.base}/admin/api/stats`, { headers: { Authorization: `Bearer ${token}` } });
expect(bearer.status).toBe(401);
expect(await bearer.json()).toEqual({ error: 'Admin authentication required' });
const asOwner = await fetch(`${app.base}/admin/login`, {
method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ token }),
});
expect(asOwner.status).toBe(401);
expect((await asOwner.json() as { error: string }).error).toContain('an OAuth token cannot administer it');
expect((await fetch(`${app.base}/metrics`, { headers: { Authorization: `Bearer ${token}` } })).status).toBe(401);
expect((await fetch(`${app.base}/metrics`, { headers: { Cookie: cookie } })).status).toBe(200);
});
test('sign-out-everywhere revokes every owner session, including the caller', async () => {
const app = await startApp();
const first = await ownerCookie(app);
const second = await ownerCookie(app);
const signOut = await fetch(`${app.base}/admin/api/sign-out-everywhere`, { method: 'POST', headers: { Cookie: first } });
expect(signOut.status).toBe(200);
expect(await signOut.json()).toEqual({ revoked_sessions: 2 });
for (const cookie of [first, second]) {
expect((await fetch(`${app.base}/admin/api/stats`, { headers: { Cookie: cookie } })).status).toBe(401);
}
expect((await fetch(`${app.base}/admin/api/stats`, { headers: { Cookie: await ownerCookie(app) } })).status).toBe(200);
});
});
describe('OAuth flows through the split modules', () => {
test('PKCE authorization code via owner consent, then a rotating refresh token', async () => {
const app = await startApp();
const cookie = await ownerCookie(app);
const redirectUri = `${app.base}/callback`;
const { clientId } = await registerClient(app, cookie, {
scopes: 'read', grantTypes: ['authorization_code', 'refresh_token'], redirectUris: [redirectUri], tokenEndpointAuthMethod: 'none',
});
const authorize = await fetch(`${app.base}/authorize?${new URLSearchParams({
client_id: clientId, response_type: 'code', redirect_uri: redirectUri, code_challenge: TEST_PKCE_CHALLENGE,
code_challenge_method: 'S256', scope: 'read', state: 'outcome-state',
})}`, { redirect: 'manual' });
expect(authorize.status).toBe(302);
const pending = new URL(authorize.headers.get('location')!, app.base);
expect(pending.pathname).toBe('/admin/');
const id = pending.searchParams.get('oauth_request')!;
const consentUrl = `${app.base}/admin/api/oauth-requests/${id}`;
expect((await fetch(consentUrl)).status).toBe(401);
const details = await (await fetch(consentUrl, { headers: { Cookie: cookie } })).json() as { csrf: string };
const approved = await fetch(consentUrl, {
method: 'POST', headers: { Cookie: cookie, 'Content-Type': 'application/json' },
body: JSON.stringify({ decision: 'approve', csrf: details.csrf }),
});
expect(approved.status).toBe(200);
const callback = new URL((await approved.json() as { redirectUrl: string }).redirectUrl);
expect(callback.searchParams.get('state')).toBe('outcome-state');
const code = callback.searchParams.get('code')!;
const token = (body: Record<string, string>) => fetch(`${app.base}/token`, {
method: 'POST', headers: { 'Content-Type': 'application/x-www-form-urlencoded' }, body: new URLSearchParams(body),
});
const wrongVerifier = await token({ grant_type: 'authorization_code', code, code_verifier: `${TEST_PKCE_VERIFIER}-wrong`, client_id: clientId, redirect_uri: redirectUri });
expect(wrongVerifier.status).toBe(400);
const exchanged = await token({ grant_type: 'authorization_code', code, code_verifier: TEST_PKCE_VERIFIER, client_id: clientId, redirect_uri: redirectUri });
expect(exchanged.status).toBe(200);
const first = await exchanged.json() as { access_token: string; refresh_token: string };
expect(first.refresh_token).toBeTruthy();
expect((await mcpResult(app, first.access_token, 'tools/list')).tools.length).toBeGreaterThan(0);
const refreshed = await token({ grant_type: 'refresh_token', refresh_token: first.refresh_token, client_id: clientId });
expect(refreshed.status).toBe(200);
const second = await refreshed.json() as { access_token: string; refresh_token: string };
expect(second.access_token).not.toBe(first.access_token);
expect((await mcpResult(app, second.access_token, 'tools/list')).tools.length).toBeGreaterThan(0);
const reused = await token({ grant_type: 'refresh_token', refresh_token: first.refresh_token, client_id: clientId });
expect(reused.status).toBe(400);
});
test('/mcp rejects a token bound to a different resource before dispatch', async () => {
const app = await startApp();
const cookie = await ownerCookie(app);
const { clientId, clientSecret } = await registerClient(app, cookie, { scopes: 'read', grantTypes: ['client_credentials'] });
const token = await clientCredentialsToken(app, clientId, clientSecret!, 'read');
expect((await mcpPost(app, token, 'tools/list')).status).toBe(200);
await engine.executeRaw(`UPDATE oauth_tokens SET resource = $1 WHERE token_hash = $2`, [
'https://different-resource.example/mcp', createHash('sha256').update(token).digest('hex'),
]);
const res = await mcpPost(app, token, 'tools/list');
expect(res.status).toBe(401);
expect((await res.json() as { error: string }).error).toBe('invalid_token');
});
});
describe('/mcp dispatch context', () => {
test('tools/call runs remote with the caller auth and source scope', async () => {
const app = await startApp();
const cookie = await ownerCookie(app);
const { clientId, clientSecret } = await registerClient(app, cookie, { scopes: 'read write admin', grantTypes: ['client_credentials'] });
const token = await clientCredentialsToken(app, clientId, clientSecret!, 'read write admin');
const who = toolPayload(await mcpResult(app, token, 'tools/call', { name: 'whoami', arguments: {} }));
expect(who.transport).toBe('oauth');
expect(who.client_id).toBe(clientId);
expect(who.source_id).toBe('default');
expect(who.scopes).toEqual(expect.arrayContaining(['read', 'write', 'admin']));
// submit_job routes any caller whose ctx.remote is not strictly false
// through remote-submission authority; an admin-scoped token asking for a
// shell job is refused there, so dispatch ran with remote: true.
const shell = await mcpResult(app, token, 'tools/call', { name: 'submit_job', arguments: { name: 'shell', data: { cmd: 'true' } } });
expect(shell.isError).toBe(true);
expect(shell.content[0].text).toContain('permission_denied');
expect(shell.content[0].text).toContain('through remote submit_job');
});
test('a verbs surface ceiling narrows both the list and dispatch', async () => {
const app = await startApp({ surface: 'verbs' });
const cookie = await ownerCookie(app);
const { clientId, clientSecret } = await registerClient(app, cookie, { scopes: 'read write', grantTypes: ['client_credentials'] });
const token = await clientCredentialsToken(app, clientId, clientSecret!, 'read write');
const listed = (await mcpResult(app, token, 'tools/list')).tools.map((t: { name: string }) => t.name).sort();
expect(listed).toEqual([...VERB_NAMES].sort());
const hidden = await mcpResult(app, token, 'tools/call', { name: 'list_pages', arguments: {} });
expect(hidden.isError).toBe(true);
expect(toolPayload(hidden).error).toBe('unknown_operation');
});
});
// whoami and gbrain://capabilities must report the transport the verifier
// actually authenticated, not one guessed from the id: hand-provisioned OAuth
// client ids need not start with gbrain_cl_, and legacy tokens may be named
// like one. Both callers are checked through the real HTTP stack so principal
// propagation and serialization are covered, not just the helper.
describe('/mcp transport provenance', () => {
async function capabilities(app: RunningApp, token: string): Promise<any> {
const read = await mcpResult(app, token, 'resources/read', { uri: 'gbrain://capabilities' });
return JSON.parse(read.contents[0].text);
}
test('an OAuth client whose id lacks the gbrain_cl_ prefix reports oauth on both surfaces', async () => {
const app = await startApp();
const cookie = await ownerCookie(app);
const { clientId, clientSecret } = await registerClient(app, cookie, { scopes: 'read write', grantTypes: ['client_credentials'] });
const handProvisioned = `research-custom-client-${clientSeq}`;
await engine.executeRaw('UPDATE oauth_clients SET client_id = $1 WHERE client_id = $2', [handProvisioned, clientId]);
const token = await clientCredentialsToken(app, handProvisioned, clientSecret!, 'read write');
const who = toolPayload(await mcpResult(app, token, 'tools/call', { name: 'whoami', arguments: {} }));
expect(who.transport).toBe('oauth');
expect(who.client_id).toBe(handProvisioned);
expect(who.source_id).toBe('default');
expect(who.token_name).toBeUndefined();
const caps = await capabilities(app, token);
expect(caps.transport).toBe('oauth');
expect(caps.client_id).toBe(handProvisioned);
});
test('a legacy token named like an OAuth client id reports legacy on both surfaces', async () => {
const app = await startApp();
const lookalike = `gbrain_cl_lookalike-${++clientSeq}`;
const { token } = await mintLegacyToken(engine, { name: lookalike, takesHolders: ['world'], scopes: ['read'] });
const who = toolPayload(await mcpResult(app, token, 'tools/call', { name: 'whoami', arguments: {} }));
// Agent contract v1 (F2): additive config-plane `readiness`.
expect(who).toMatchObject({ transport: 'legacy', token_name: lookalike, scopes: ['read'], expires_at: null });
expect(Array.isArray(who.readiness)).toBe(true);
const caps = await capabilities(app, token);
expect(caps.transport).toBe('legacy');
expect(caps.client_id).toBe(lookalike);
});
});
describe('OAuth CORS gate runs before the SDK router', () => {
const origin = 'https://browser-app.example';
const preflight = (app: RunningApp, path: string) => fetch(`${app.base}${path}`, {
method: 'OPTIONS', headers: { Origin: origin, 'Access-Control-Request-Method': 'POST', 'Access-Control-Request-Headers': 'authorization,content-type' },
});
test('default deny: preflights on /token, /register, /revoke and /mcp carry no Allow-Origin', async () => {
await withEnv({ GBRAIN_HTTP_CORS_ORIGIN: undefined }, async () => {
const app = await startApp({ enableDcr: true });
for (const path of ['/token', '/register', '/revoke', '/mcp']) {
const res = await preflight(app, path);
expect(res.headers.get('access-control-allow-origin'), `${path} must not fall through to a permissive CORS`).toBeNull();
}
});
});
test('allowlisted origin: the preflight reflects it and an authenticated /mcp call carries it', async () => {
await withEnv({ GBRAIN_HTTP_CORS_ORIGIN: origin }, async () => {
const app = await startApp({ enableDcr: true });
for (const path of ['/token', '/register', '/revoke', '/mcp']) {
expect((await preflight(app, path)).headers.get('access-control-allow-origin')).toBe(origin);
}
const cookie = await ownerCookie(app);
const { clientId, clientSecret } = await registerClient(app, cookie, { scopes: 'read', grantTypes: ['client_credentials'] });
const token = await clientCredentialsToken(app, clientId, clientSecret!, 'read');
const call = await mcpPost(app, token, 'tools/list', undefined, { Origin: origin });
expect(call.status).toBe(200);
expect(call.headers.get('access-control-allow-origin')).toBe(origin);
await call.text();
const denied = await mcpPost(app, token, 'tools/list', undefined, { Origin: 'https://other-app.example' });
expect(denied.headers.get('access-control-allow-origin')).toBeNull();
await denied.text();
});
});
});