Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

hookServer: the store proxy's rules move to storeProxy.ts, and refuse dot segments

dee89860ac3fc5d
diff --git a/cli/src/hookServer.ts b/cli/src/hookServer.ts
index edfc83690..d00590fbd 100644
--- a/cli/src/hookServer.ts
+++ b/cli/src/hookServer.ts
@@ -17,6 +17,7 @@ import { sid } from './lib/log.js'
import { VERSION } from './version.js'
import { env } from './config/env.js'
import { hookCredentialMatches, loadOrCreateHookCredential } from './lib/hookAuth.js'
+import { routeStoreRequest, type StoreHandler } from './lib/storeProxy.js'
import type { HookTerminalHint } from './lib/terminalTypes.js'
import { ENGINES, type AgentEngine } from './engines/types.js'
@@ -119,12 +120,11 @@ export interface HookServerHandlers {
/** GET /api/auth/me — proxy the signed-in user's profile from backend. */
onAuthMe?: () => Promise<PairOutcome>
/** /api/store/* — proxy the Harness Store's ratings and reviews to backend the same way: reads
- * ungated like the machine list, writes (PUT/DELETE) CSRF-guarded like a rename. */
- onStore?: (method: 'GET' | 'PUT' | 'DELETE', path: string, body?: unknown) => Promise<PairOutcome>
+ * ungated like the machine list, writes (PUT/DELETE) CSRF-guarded like a rename. See storeProxy.ts. */
+ onStore?: StoreHandler
}
-/** A store path the daemon will forward: /api/store/… with nothing but id characters, slashes and a query. */
-export const STORE_PATH_RE = /^\/api\/store\/[A-Za-z0-9_\-./]{1,200}(?:\?[A-Za-z0-9_\-.=&%]{0,200})?$/
+export { STORE_PATH_RE } from './lib/storeProxy.js'
const MAX_HOOK_BODY_BYTES = 256 * 1024
const HOOK_BODY_FIELDS = new Set([
@@ -632,24 +632,14 @@ export function startHookServer(
await proxied(() => remove(machineId)); return
}
- // The Harness Store: ratings and reviews live in the backend, and the app reaches them the way
- // it reaches its machine list — through this daemon's own session. The path is forwarded as
- // given (query included) so the backend's own validation is the one that answers.
+ // The Harness Store: ratings and reviews in the backend, through this daemon's own session. The
+ // rules (reads ungated, writes behind the local header, the paths it forwards) are storeProxy.ts's.
if (url.startsWith('/api/store/')) {
- const store = handlers.onStore
- if (!store) { json(503, { error: 'UNAVAILABLE' }); return }
- const full = req.url ?? url
- if (!STORE_PATH_RE.test(full)) { json(400, { error: 'BAD_PATH' }); return }
- if (req.method === 'GET') { await proxied(() => store('GET', full)); return }
- if (req.method === 'PUT' || req.method === 'DELETE') {
- if (!localOk) { json(403, { error: 'FORBIDDEN' }); return }
- let body: unknown
- if (req.method === 'PUT') {
- try { body = JSON.parse(await readBody(req)) } catch { json(400, { error: 'bad json' }); return }
- }
- await proxied(() => store(req.method as 'PUT' | 'DELETE', full, body)); return
- }
- json(405, { error: 'METHOD_NOT_ALLOWED' }); return
+ // A request an http.Server hands over always has its url; `url` above is it without the query.
+ const route = await routeStoreRequest({ method: req.method, url: req.url as string, localOk, readBody: () => readBody(req) }, handlers.onStore)
+ if ('forward' in route) await proxied(route.forward)
+ else json(route.status, route.body)
+ return
}
// `harness pairings` — list paired browsers.
diff --git a/cli/src/lib/storeProxy.spec.ts b/cli/src/lib/storeProxy.spec.ts
new file mode 100644
index 000000000..1881bc4ad
--- /dev/null
+++ b/cli/src/lib/storeProxy.spec.ts
@@ -0,0 +1,142 @@
+// The Harness Store proxy: which paths it forwards, who may write, and what the hook server answers.
+import http, { type Server } from 'node:http'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { STORE_PATH_RE as FROM_HOOK_SERVER, startHookServer, type HookServerHandlers } from '../hookServer.js'
+import { routeStoreRequest, STORE_PATH_RE, type StoreHandler, type StoreRoute } from './storeProxy.js'
+
+describe('STORE_PATH_RE', () => {
+ it('is the one the hook server uses', () => {
+ expect(FROM_HOOK_SERVER).toBe(STORE_PATH_RE)
+ })
+
+ it('takes the store\'s own paths, with a query', () => {
+ for (const path of [
+ '/api/store/ratings',
+ '/api/store/harnesses/autonomous/marp/reviews?limit=5&cursor=abc%3D',
+ '/api/store/harnesses/autonomous/text-to-cad/review',
+ '/api/store/harnesses/a..b/reviews',
+ '/api/store/harnesses/.well-known/x',
+ '/api/store/x?',
+ ]) expect(STORE_PATH_RE.test(path), path).toBe(true)
+ })
+
+ it('refuses anything else: other characters, an empty rest, and a dot segment fetch would resolve out of the store', () => {
+ for (const path of [
+ '/api/store/',
+ '/api/store/harnesses/a%20b/reviews',
+ '/api/store/harnesses/a b/reviews',
+ '/api/store/ratings#frag',
+ '/api/store/ratings?q=a/b',
+ '/api/machines',
+ '/api/store/../machines',
+ '/api/store/..',
+ '/api/store/..?x=1',
+ '/api/store/./ratings',
+ '/api/store/harnesses/../../auth/me',
+ '/api/store/harnesses/autonomous/..',
+ `/api/store/${'a'.repeat(201)}`,
+ ]) expect(STORE_PATH_RE.test(path), path).toBe(false)
+ })
+})
+
+describe('routeStoreRequest', () => {
+ const store: StoreHandler = async (method, path, body) => ({ status: 200, body: { method, path, body } })
+ const request = (method: string | undefined, url: string, localOk = false, body = ''): Parameters<typeof routeStoreRequest>[0] =>
+ ({ method, url, localOk, readBody: async () => body })
+ const answer = async (route: StoreRoute): Promise<unknown> => ('forward' in route ? { forwarded: await route.forward() } : route)
+
+ it('answers 503 with no backend to proxy to, whatever was asked', async () => {
+ expect(await routeStoreRequest(request('PUT', '/api/store/../x', true), undefined)).toEqual({ status: 503, body: { error: 'UNAVAILABLE' } })
+ })
+
+ it('forwards a read with no header at all, query included', async () => {
+ expect(await answer(await routeStoreRequest(request('GET', '/api/store/ratings?ids=a,b'), store))).toEqual({ status: 400, body: { error: 'BAD_PATH' } })
+ expect(await answer(await routeStoreRequest(request('GET', '/api/store/ratings?ids=a'), store)))
+ .toEqual({ forwarded: { status: 200, body: { method: 'GET', path: '/api/store/ratings?ids=a', body: undefined } } })
+ })
+
+ it('a write needs the local header; a PUT needs a JSON body; a DELETE carries none', async () => {
+ const review = '/api/store/harnesses/autonomous/marp/review'
+ expect(await routeStoreRequest(request('PUT', review, false, '{"rating":5}'), store)).toEqual({ status: 403, body: { error: 'FORBIDDEN' } })
+ expect(await routeStoreRequest(request('DELETE', review, false), store)).toEqual({ status: 403, body: { error: 'FORBIDDEN' } })
+ expect(await routeStoreRequest(request('PUT', review, true, '{not json'), store)).toEqual({ status: 400, body: { error: 'bad json' } })
+ expect(await routeStoreRequest(request('PUT', review, true, ''), store)).toEqual({ status: 400, body: { error: 'bad json' } })
+ expect(await answer(await routeStoreRequest(request('PUT', review, true, '{"rating":5}'), store)))
+ .toEqual({ forwarded: { status: 200, body: { method: 'PUT', path: review, body: { rating: 5 } } } })
+ expect(await answer(await routeStoreRequest(request('DELETE', review, true, '{"ignored":true}'), store)))
+ .toEqual({ forwarded: { status: 200, body: { method: 'DELETE', path: review, body: undefined } } })
+ })
+
+ it('anything but GET, PUT and DELETE is 405, header or not', async () => {
+ for (const method of ['POST', 'PATCH', 'HEAD', undefined]) {
+ expect(await routeStoreRequest(request(method, '/api/store/ratings', true), store), String(method)).toEqual({ status: 405, body: { error: 'METHOD_NOT_ALLOWED' } })
+ }
+ })
+})
+
+describe('the store proxy on the hook server', () => {
+ let server: Server | null = null
+ afterEach(async () => {
+ if (server) await new Promise<void>((resolve) => server!.close(() => resolve()))
+ server = null
+ })
+
+ const start = async (onStore?: HookServerHandlers['onStore']): Promise<number> => {
+ const started = await startHookServer(0, { onRegistered: vi.fn(), onSessionEnd: vi.fn(), onStore })
+ server = started.server
+ return started.port
+ }
+ /** A raw request: the path goes out exactly as written, `..` and all, which fetch would not do. */
+ const send = (port: number, method: string, path: string, headers: Record<string, string> = {}, body?: string): Promise<{ status: number; json: unknown }> =>
+ new Promise((resolve, reject) => {
+ const req = http.request({ host: '127.0.0.1', port, method, path, headers }, (res) => {
+ let text = ''
+ res.setEncoding('utf8')
+ res.on('data', (chunk: string) => { text += chunk })
+ res.on('end', () => resolve({ status: res.statusCode ?? 0, json: JSON.parse(text) }))
+ })
+ req.on('error', reject)
+ req.end(body)
+ })
+
+ it('never forwards a path that climbs out of the store, even to a reader with no header', async () => {
+ // Found by this spec: `.` was an id character, so /api/store/../auth/me was forwarded with the
+ // daemon's own session and fetch resolved it to a backend route that is not the store's.
+ const onStore = vi.fn<StoreHandler>(async () => ({ status: 200, body: { ok: true } }))
+ const port = await start(onStore)
+ expect(await send(port, 'GET', '/api/store/../auth/me')).toEqual({ status: 400, json: { error: 'BAD_PATH' } })
+ expect(await send(port, 'DELETE', '/api/store/harnesses/../../machines/m1', { 'x-adapter-local': '1' })).toEqual({ status: 400, json: { error: 'BAD_PATH' } })
+ expect(onStore).not.toHaveBeenCalled()
+ })
+
+ it('reads are ungated; writes without the local header are refused before the backend hears of them', async () => {
+ const onStore = vi.fn<StoreHandler>(async (method) => ({ status: 201, body: { method } }))
+ const port = await start(onStore)
+ expect(await send(port, 'GET', '/api/store/ratings')).toEqual({ status: 201, json: { method: 'GET' } })
+ expect(await send(port, 'PUT', '/api/store/harnesses/autonomous/marp/review', { 'content-type': 'application/json' }, '{"rating":4}')).toEqual({ status: 403, json: { error: 'FORBIDDEN' } })
+ expect(await send(port, 'DELETE', '/api/store/harnesses/autonomous/marp/review')).toEqual({ status: 403, json: { error: 'FORBIDDEN' } })
+ expect(await send(port, 'DELETE', '/api/store/harnesses/autonomous/marp/review', { 'x-adapter-local': 'yes' })).toEqual({ status: 403, json: { error: 'FORBIDDEN' } })
+ expect(await send(port, 'PUT', '/api/store/harnesses/autonomous/marp/review', { 'x-adapter-local': '1' }, '{"rating":4}')).toEqual({ status: 201, json: { method: 'PUT' } })
+ expect(onStore.mock.calls).toEqual([
+ ['GET', '/api/store/ratings'],
+ ['PUT', '/api/store/harnesses/autonomous/marp/review', { rating: 4 }],
+ ])
+ })
+
+ it('a body past the hook server\'s limit is bad JSON, not a truncated review', async () => {
+ const onStore = vi.fn<StoreHandler>(async () => ({ status: 200, body: {} }))
+ const port = await start(onStore)
+ const huge = JSON.stringify({ rating: 5, body: 'x'.repeat(300 * 1024) })
+ expect(await send(port, 'PUT', '/api/store/harnesses/autonomous/marp/review', { 'x-adapter-local': '1' }, huge)).toEqual({ status: 400, json: { error: 'bad json' } })
+ expect(onStore).not.toHaveBeenCalled()
+ })
+
+ it('a backend call that throws is a 502 the app can read, and no backend at all is a 503', async () => {
+ vi.spyOn(console, 'error').mockImplementation(() => undefined)
+ const port = await start(async () => { throw new Error('socket hang up') })
+ expect(await send(port, 'GET', '/api/store/ratings')).toEqual({ status: 502, json: { success: false, error: { code: 'PROXY_FAILED', message: 'socket hang up' } } })
+ await new Promise<void>((resolve) => server!.close(() => resolve()))
+ const bare = await start(undefined)
+ expect(await send(bare, 'GET', '/api/store/ratings')).toEqual({ status: 503, json: { error: 'UNAVAILABLE' } })
+ })
+})
diff --git a/cli/src/lib/storeProxy.ts b/cli/src/lib/storeProxy.ts
new file mode 100644
index 000000000..7d6b8f3c7
--- /dev/null
+++ b/cli/src/lib/storeProxy.ts
@@ -0,0 +1,47 @@
+/**
+ * `/api/store/*` on the local hook server: the Harness Store's ratings and reviews live in the backend,
+ * and the app reaches them the way it reaches its machine list — through this daemon's own session, so
+ * a local GUI never holds a token. The path is forwarded as given (query included) so the backend's own
+ * validation is the one that answers.
+ *
+ * The rules, decided here and nowhere else: reads are ungated, like the machine list; writes (PUT and
+ * DELETE) need the `x-adapter-local` header, the CSRF guard a cross-origin page cannot set without a
+ * preflight this server never allows; anything else is 405.
+ */
+
+export type StoreMethod = 'GET' | 'PUT' | 'DELETE'
+export type StoreOutcome = { status: number; body: unknown }
+export type StoreHandler = (method: StoreMethod, path: string, body?: unknown) => Promise<StoreOutcome>
+
+/**
+ * A store path the daemon will forward: /api/store/… with nothing but id characters, slashes and a
+ * query — and no `.` or `..` segment. The backend URL is built by concatenation and a `..` there is
+ * resolved by fetch, so `/api/store/../machines` would reach a backend route that is not the store's.
+ */
+export const STORE_PATH_RE = /^\/api\/store\/(?!(?:[^?]*\/)?\.{1,2}(?:[/?]|$))[A-Za-z0-9_\-./]{1,200}(?:\?[A-Za-z0-9_\-.=&%]{0,200})?$/
+
+export interface StoreRequest {
+ method: string | undefined
+ /** The request's full path, query included. */
+ url: string
+ /** Whether the request carries the local CSRF header. */
+ localOk: boolean
+ readBody: () => Promise<string>
+}
+
+/** Either the answer to send now, or the backend call to make (the caller turns a throw into a 502). */
+export type StoreRoute = StoreOutcome | { forward: () => Promise<StoreOutcome> }
+
+export async function routeStoreRequest(request: StoreRequest, store: StoreHandler | undefined): Promise<StoreRoute> {
+ if (!store) return { status: 503, body: { error: 'UNAVAILABLE' } }
+ const path = request.url
+ if (!STORE_PATH_RE.test(path)) return { status: 400, body: { error: 'BAD_PATH' } }
+ const method = request.method
+ if (method === 'GET') return { forward: () => store('GET', path) }
+ if (method !== 'PUT' && method !== 'DELETE') return { status: 405, body: { error: 'METHOD_NOT_ALLOWED' } }
+ if (!request.localOk) return { status: 403, body: { error: 'FORBIDDEN' } }
+ if (method === 'DELETE') return { forward: () => store('DELETE', path, undefined) }
+ let body: unknown
+ try { body = JSON.parse(await request.readBody()) } catch { return { status: 400, body: { error: 'bad json' } } }
+ return { forward: () => store('PUT', path, body) }
+}