Multiplayer agent harness for work.
import { externalSlackCapabilityAllowed } from "./external-slack-capability.ts";
import { MemoryDisclosureDenied } from "../memory/disclosure.ts";
import { MemoryFactsMissing } from "../memory/facts.ts";
import { nameRequest, reportBackendError } from "../../plugins/chassis/src/error-reporting.ts";
import {
createServer as createHttpServer,
type IncomingMessage,
type RequestListener,
type ServerResponse,
type Server,
} from "node:http";
import Fastify, { type FastifyInstance, type FastifyReply, type FastifyRequest, type HTTPMethods } from "fastify";
import type { App } from "./app.ts";
import type { ServerDeps } from "./deps.ts";
import { createControlService } from "./control-service.ts";
import {
createSourceAuth,
isStrongSigningSecret,
MIN_SIGNING_SECRET_LENGTH,
SOURCE_AUTH_REPLAY_WINDOW_MS,
type SourceAuth,
} from "../auth/source-auth.ts";
import { verifyCapabilityToken, CONTROL_PLANE_AUD, type CapabilityClaims } from "../auth/capability-token.ts";
import { verifyPortalIdentity, PORTAL_IDENTITY_HEADER, type PortalIdentity } from "../auth/portal-identity.ts";
import { errMessage } from "../util/errors.ts";
import { parseScopeId, scopeId } from "../types.ts";
import { canonicalPayload } from "../../plugins/chassis/src/source-auth-sign.ts";
import { armBodyDeadline, PayloadTooLargeError, readRawBody, sendJson, verifyOrReject } from "./http.ts";
import { findRoute, run, type AdminAccess, type ApiCtx, type BaseCtx, type Route } from "./routes/route.ts";
import { apiRoutes, rawRoutes } from "./routes/index.ts";
import { proxyDeploymentSubdomain } from "./routes/deployments.ts";
import { CAPABILITY_HEADER } from "./contract.ts";
import { livePersonCapability } from "./artifact-share.ts";
import { canonicalPerson, samePerson } from "../directory/person.ts";
async function capabilityAdminDenied(
access: AdminAccess,
params: Record<string, string>,
url: URL,
claims: CapabilityClaims,
config: ServerDeps["config"],
): Promise<string | null> {
if (access.agent === "anyone") return null;
if (claims.aud !== CONTROL_PLANE_AUD) return "admin routes require the per-turn agent token";
if (!livePersonCapability(claims) && !(access.unattended && claims.grants?.includes(access.unattended.grant))) {
return access.unattended
? `admin actions through the agent require a turn the admin started themselves — this autonomous run lacks the unattended grant ${access.unattended.grant}, which only a cron's org-admin owner can add, from a live turn in their own DM. Report this failure where the run delivers instead of finishing silently.`
: "admin actions through the agent require a turn the admin started themselves — autonomous turns (crons, webhooks) cannot use this route. Report this failure where the run delivers instead of finishing silently.";
}
if (typeof access.agent === "object") return access.agent.portalOnly;
if (access.privateRead && parseScopeId(claims.scopeId).kind !== "personal") {
const target =
access.privateRead === "unless-org-scope" ? (params.scope ?? url.searchParams.get("scope") ?? "") : "";
if (
parseScopeId(target).kind !== "org" &&
(!livePersonCapability(claims) ||
(await config?.resolveSharingPostureDurable(scopeId("personal", claims.actorId), claims.scopeId)) !== "open")
) {
return "this admin read returns private content — ask the agent in a DM";
}
}
return null;
}
const WRITE_METHODS = new Set(["POST", "PUT", "PATCH", "DELETE"]);
function needlessEscape(escaped: string): boolean {
const char = String.fromCharCode(Number.parseInt(escaped.slice(0, 2), 16));
return encodeURIComponent(char) === char;
}
function canonicalPath(req: IncomingMessage, pathname: string): boolean {
return (req.url ?? "/").split("?", 1)[0] === pathname && !pathname.split("%").slice(1).some(needlessEscape);
}
function capabilityFromHeaders(req: IncomingMessage): string | null {
const h = req.headers[CAPABILITY_HEADER];
return typeof h === "string" && h ? h : null;
}
interface GateResult {
body: unknown;
capability: CapabilityClaims | null;
actor: PortalIdentity | null;
}
interface Wiring {
app: App;
deps: ServerDeps;
secret: string | undefined;
auth: SourceAuth | null;
requirePortalIdentity: boolean;
allowUnsignedSourceAuth: boolean;
}
declare module "fastify" {
interface FastifyContextConfig {
route?: Route<ApiCtx>;
}
interface FastifyRequest {
gate?: GateResult;
}
}
const rawBodies = new WeakMap<IncomingMessage, string>();
async function verifyCapability(
req: IncomingMessage,
res: ServerResponse,
{ app, deps, secret }: Wiring,
method: string,
pathname: string,
requiredAud: string | null,
): Promise<CapabilityClaims | null> {
const capToken = capabilityFromHeaders(req);
if (!capToken) {
sendJson(res, 401, { error: "unauthorized", message: `${requiredAud} capability token required` });
return null;
}
const capSecret = deps.capabilitySecret ?? secret;
const capability = capSecret ? await verifyCapabilityToken(capToken, capSecret) : null;
if (!capability) {
sendJson(res, 401, { error: "unauthorized", message: "invalid or expired capability token" });
return null;
}
if (
capability.externalSlack &&
!(
capability.aud === "credential-broker" &&
((method === "POST" && pathname === "/v1/credentials/broker") ||
((method === "GET" || method === "POST") && pathname.startsWith("/v1/credentials/git/")))
)
) {
sendJson(res, 403, { error: "forbidden", message: "This operation requires a private conversation." });
return null;
}
if (deps.identity) {
await deps.identity.refresh();
if (deps.identity.classify(capability.actorId).type !== "internal") {
sendJson(res, 401, { error: "unauthorized", message: "principal is no longer active" });
return null;
}
}
if (capability.deployment !== undefined) {
const deployment = await app.getDeployment(capability.deployment);
if (
!deployment ||
deployment.id !== capability.deployment ||
deployment.status !== "running" ||
deployment.createdBy !== capability.actorId
) {
sendJson(res, 401, { error: "unauthorized", message: "the published app behind this token is not running" });
return null;
}
}
if (
!(capability.externalSlack
? await externalSlackCapabilityAllowed(capability, deps)
: await app.authorizesCapabilityScope({
actorId: capability.actorId,
scopeId: capability.scopeId,
...(capability.scopeVersion ? { scopeVersion: capability.scopeVersion } : {}),
...(capability.botActor ? { botActor: true } : {}),
...(capability.liveActor ? { liveActor: true } : {}),
...(capability.members ? { members: capability.members } : {}),
}))
) {
sendJson(res, 403, {
error: "forbidden",
message: "the acting user is not currently authorized for this conversation",
});
return null;
}
if (requiredAud && capability.aud !== requiredAud) {
sendJson(res, 403, {
error: "forbidden",
message: `this route requires a capability token with audience "${requiredAud}"`,
});
return null;
}
return capability;
}
async function gate(
req: IncomingMessage,
res: ServerResponse,
wiring: Wiring,
method: string,
pathname: string,
url: URL,
raw: string,
route: Pick<Route, "auth" | "actor" | "admin" | "allowedInStrict"> | undefined,
params: Record<string, string>,
): Promise<GateResult | null> {
const routeAuth = route?.auth;
const { deps, secret, auth, requirePortalIdentity, allowUnsignedSourceAuth } = wiring;
const isPublicRoute = routeAuth === "public";
const requiredAud = typeof routeAuth === "object" ? routeAuth.aud : null;
let capability: CapabilityClaims | null = null;
const capToken = capabilityFromHeaders(req);
if (isPublicRoute) {
void isPublicRoute;
} else if (requiredAud || capToken) {
capability = await verifyCapability(req, res, wiring, method, pathname, requiredAud);
if (!capability) return null;
if (routeAuth === "either") {
if (capability.aud !== undefined && capability.aud !== CONTROL_PLANE_AUD) {
sendJson(res, 403, { error: "forbidden", message: "capability token audience not valid for this route" });
return null;
}
if (route?.admin) {
const denied = await capabilityAdminDenied(route.admin, params, url, capability, deps.config);
if (denied) {
sendJson(res, 403, { error: "forbidden", message: denied });
return null;
}
}
} else if (!requiredAud) {
sendJson(res, 403, { error: "forbidden", message: "capability token not valid for this route" });
return null;
}
} else if (
!(await verifyOrReject(
req,
res,
secret,
auth,
canonicalPayload(method, pathname + url.search, raw),
method !== "GET",
allowUnsignedSourceAuth,
))
) {
return null;
}
let body: unknown = {};
if (raw) {
try {
body = JSON.parse(raw);
} catch {
sendJson(res, 400, { error: "bad_request", message: "invalid JSON body" });
return null;
}
}
if (
capability &&
!requiredAud &&
method !== "GET" &&
!route?.allowedInStrict &&
deps.config &&
(await deps.config.getSecurityPostureDurable(capability.scopeId)) === "strict"
) {
sendJson(res, 403, { error: "forbidden", message: "Strict posture blocks direct control-plane mutations" });
return null;
}
let actor: PortalIdentity | null = null;
if (!capability) {
const psecret = deps.portalIdentitySecret ?? secret;
const rawToken = req.headers[PORTAL_IDENTITY_HEADER];
const token = Array.isArray(rawToken) ? rawToken[0] : rawToken;
actor = token && psecret ? await verifyPortalIdentity(token, psecret, Date.now()) : null;
if (actor && deps.identity) {
await deps.identity.refresh(Boolean(actor.authenticatedAs));
if (
deps.identity.classify(actor.p).type !== "internal" ||
(actor.authenticatedAs &&
(deps.identity.classify(actor.authenticatedAs).type !== "internal" ||
!samePerson(actor.authenticatedAs, actor.imp ?? actor.p)))
)
actor = null;
}
if (actor)
actor = { ...actor, p: canonicalPerson(actor.p), ...(actor.imp ? { imp: canonicalPerson(actor.imp) } : {}) };
if (!isPublicRoute && requirePortalIdentity) {
const webTurn =
method === "POST" &&
pathname === "/v1/turns" &&
body !== null &&
typeof body === "object" &&
(body as { surface?: unknown }).surface === "web";
const routeActor = route?.actor ?? (WRITE_METHODS.has(method) ? "person" : undefined);
const needsActor = webTurn || (routeActor !== undefined && routeActor !== "system");
if (needsActor) {
if (!psecret || !actor) {
sendJson(res, 401, { error: "unauthorized", message: "portal identity required" });
return null;
}
const field = !webTurn && routeActor?.includes(".") ? routeActor : undefined;
let asserted: unknown = null;
if (webTurn) asserted = (body as { actor?: { externalId?: unknown } }).actor?.externalId ?? null;
else if (field) asserted = assertedActorField(field, url, body);
const actorId = actor.p;
const matchesActor = (value: unknown): boolean => typeof value === "string" && samePerson(value, actorId);
if ((field && !matchesActor(asserted)) || (!field && asserted !== null && !matchesActor(asserted))) {
sendJson(res, 403, { error: "forbidden", message: "portal identity does not match the requested actor" });
return null;
}
}
}
}
return { body, capability, actor };
}
function assertedActorField(field: string, url: URL, body: unknown): unknown {
const [where, name] = field.split(".", 2) as [string, string];
if (where === "query") return url.searchParams.get(name);
const value = body && typeof body === "object" ? (body as Record<string, unknown>)[name] : undefined;
return typeof value === "string" ? value : null;
}
function baseCtx(req: IncomingMessage, res: ServerResponse, wiring: Wiring): BaseCtx {
const url = new URL(req.url ?? "/", "http://localhost");
return { req, res, ...wiring, url, pathname: url.pathname, method: req.method ?? "GET", params: {} };
}
function respondError(req: IncomingMessage, res: ServerResponse, err: unknown): void {
if (err instanceof MemoryDisclosureDenied || err instanceof MemoryFactsMissing) {
const status = err instanceof MemoryFactsMissing ? 404 : 403;
if (!res.headersSent)
sendJson(res, status, { error: status === 404 ? "not_found" : "forbidden", message: err.message });
else res.destroy();
return;
}
if (err instanceof PayloadTooLargeError) {
if (!res.headersSent) sendJson(res, 413, { error: "payload_too_large", message: errMessage(err) });
else res.destroy();
return;
}
reportBackendError(err);
console.error("[server] 500 %s %s: %s", req.method ?? "?", loggablePath(req.url), errMessage(err));
if (!res.headersSent) sendJson(res, 500, { error: "internal_error", message: "internal server error" });
else res.destroy();
}
function paramsSchema(path: string): object {
const names = path
.split("/")
.filter((seg) => seg.startsWith(":"))
.map((seg) => seg.slice(1));
return {
type: "object",
properties: Object.fromEntries(names.map((n) => [n, { type: "string" }])),
required: names,
};
}
function buildFastify(wiring: Wiring, server: Server): { fastify: FastifyInstance; routing: RequestListener } {
const matchRoutes = apiRoutes.filter(
(route): route is Route<ApiCtx> & { match: (m: string, p: string) => boolean } => !("path" in route),
);
const fallback = async (request: FastifyRequest, reply: FastifyReply): Promise<void> => {
reply.hijack();
const req = request.raw;
const res = reply.raw;
try {
const base = baseCtx(req, res, wiring);
const raw = rawBodies.get(req) ?? "";
const found = findRoute(matchRoutes, base.method, base.pathname);
const g = await gate(
req,
res,
wiring,
base.method,
base.pathname,
base.url,
raw,
found?.route,
found?.params ?? {},
);
if (!g) return;
if (found) {
const ctx: ApiCtx = {
...base,
body: g.body,
capability: g.capability,
actor: g.actor,
};
await run(found.route, found.params, ctx);
return;
}
sendJson(res, 404, { error: "not_found", message: `${base.method} ${base.pathname}` });
} catch (err) {
respondError(req, res, err);
}
};
let routing!: RequestListener;
const fastify = Fastify({
serverFactory: (handler) => {
routing = handler as RequestListener;
return server;
},
logger: false,
exposeHeadRoutes: false,
routerOptions: { maxParamLength: 100_000 },
frameworkErrors: (_err, request, reply) => {
void fallback(request, reply);
},
});
fastify.removeAllContentTypeParsers();
fastify.addContentTypeParser("*", (request, _payload, done) => {
done(null, rawBodies.get(request.raw) ?? "");
});
fastify.decorateRequest("gate", undefined);
fastify.setErrorHandler((err, request, reply) => {
reportBackendError(err);
console.error("%s", `[server] 500 ${request.raw.method ?? "?"} ${loggablePath(request.raw.url)}:`, errMessage(err));
return reply.code(500).send({ error: "internal_error", message: "internal server error" });
});
const gateHook = async (request: FastifyRequest, reply: FastifyReply): Promise<void> => {
const url = new URL(request.raw.url ?? "/", "http://localhost");
const raw = rawBodies.get(request.raw) ?? "";
const result = await gate(
request.raw,
reply.raw,
wiring,
request.raw.method ?? "GET",
url.pathname,
url,
raw,
request.routeOptions.config.route,
request.params as Record<string, string>,
);
if (!result) {
reply.hijack();
return;
}
request.gate = result;
};
const handler = async (request: FastifyRequest, reply: FastifyReply): Promise<void> => {
reply.hijack();
const route = request.routeOptions.config.route!;
const g = request.gate!;
const ctx: ApiCtx = {
...baseCtx(request.raw, reply.raw, wiring),
body: g.body,
capability: g.capability,
actor: g.actor,
};
try {
await run(route, request.params as Record<string, string>, ctx);
} catch (err) {
respondError(request.raw, reply.raw, err);
}
};
for (const route of apiRoutes) {
if (!("path" in route)) continue;
fastify.route({
method: route.method as HTTPMethods,
url: route.path,
config: { route },
schema: { params: paramsSchema(route.path) },
preValidation: gateHook,
handler,
});
}
fastify.setNotFoundHandler(fallback);
return { fastify, routing };
}
type ServerOptions = Omit<ServerDeps, "control">;
function buildServer(app: App, deps: ServerOptions, allowUnsignedSourceAuth: boolean): Server {
const requirePortalIdentity = Boolean(deps.requireSignedPortalIdentity || deps.production);
const auth = deps.signingSecret
? createSourceAuth({
signingSecret: deps.signingSecret,
...(deps.replayDedupe ? { dedupe: deps.replayDedupe } : {}),
})
: null;
const wiring: Wiring = {
app,
deps: { ...deps, control: createControlService(app, deps.scheduler, deps.admin) },
secret: deps.signingSecret,
auth,
requirePortalIdentity,
allowUnsignedSourceAuth,
};
const server = createHttpServer((req, res) => {
req.on("error", () => res.destroy());
res.on("error", () => res.destroy());
void front(req, res).catch((err: unknown) => respondError(req, res, err));
});
const { fastify, routing } = buildFastify(wiring, server);
const ready = Promise.resolve(fastify.ready());
ready.catch((err: unknown) => console.error("[server] fastify initialization failed:", errMessage(err)));
server.requestTimeout = 0;
server.headersTimeout = 10_000;
server.keepAliveTimeout = 5_000;
server.maxConnections = 1024;
async function front(req: IncomingMessage, res: ServerResponse): Promise<void> {
armBodyDeadline(req, 30_000);
const base = baseCtx(req, res, wiring);
if (await proxyDeploymentSubdomain(base)) {
nameRequest(base.method, "/deployment-proxy/*");
return;
}
if (!canonicalPath(req, base.pathname)) {
sendJson(res, 404, { error: "not_found", message: `${base.method} ${base.pathname}` });
return void req.resume();
}
const raw = findRoute(rawRoutes, base.method, base.pathname);
if (raw) {
if ("path" in raw.route) nameRequest(base.method, raw.route.path);
const routeAuth = raw.route.auth;
if (typeof routeAuth === "object") {
base.capability = await verifyCapability(req, res, wiring, base.method, base.pathname, routeAuth.aud);
if (!base.capability) return void req.resume();
}
await run(raw.route, raw.params, base);
return;
}
const matched = findRoute(apiRoutes, base.method, base.pathname);
if (matched && "path" in matched.route) nameRequest(base.method, matched.route.path);
const routeAuth = matched?.route.auth;
const acceptsSourceAuth = !matched || routeAuth === "source" || routeAuth === "either";
if (wiring.secret && !capabilityFromHeaders(req) && routeAuth !== "public" && acceptsSourceAuth) {
const timestamp = Number(req.headers["x-timestamp"] ?? 0);
if (
!Number.isFinite(timestamp) ||
Math.abs(Date.now() - timestamp * 1000) > SOURCE_AUTH_REPLAY_WINDOW_MS ||
typeof req.headers["x-signature"] !== "string"
) {
sendJson(res, 401, {
error: "unauthorized",
message: `missing, invalid, or stale source-auth headers; agent calls must send the capability token as ${CAPABILITY_HEADER}: $AGENT_API_TOKEN`,
});
return;
}
}
rawBodies.set(req, await readRawBody(req, matched?.route.maxBodyBytes));
await ready;
routing(req, res);
}
return server;
}
export function loggablePath(url: string | undefined): string {
if (!url) return "?";
const query = url.indexOf("?");
return query < 0 ? url : `${url.slice(0, query)}?<query omitted>`;
}
export function createServer(app: App, deps: ServerOptions = {}): Server {
if (!deps.signingSecret && deps.allowUnauthenticatedCore) {
console.warn(
"[server] ALLOW_UNAUTHENTICATED_CORE=1 — HTTP ingress is UNAUTHENTICATED (intentionally isolated deployments only).",
);
return buildServer(app, deps, true);
}
if (!isStrongSigningSecret(deps.signingSecret)) {
throw new Error(
`CORE_SIGNING_SECRET must be at least ${MIN_SIGNING_SECRET_LENGTH} characters; tests that intentionally need unsigned source auth must use createInsecureTestServer`,
);
}
if (deps.requireSignedPortalIdentity || deps.production) {
const shared = (name: string, value: string | undefined): string | null => {
if (!value) return `${name} is not set (it would fall back to CORE_SIGNING_SECRET)`;
return value === deps.signingSecret ? `${name} must differ from CORE_SIGNING_SECRET` : null;
};
const problem =
shared("CAPABILITY_SECRET", deps.capabilitySecret) ??
shared("PORTAL_IDENTITY_SECRET", deps.portalIdentitySecret) ??
(deps.capabilitySecret === deps.portalIdentitySecret
? "PORTAL_IDENTITY_SECRET must differ from CAPABILITY_SECRET"
: null);
if (problem)
throw new Error(
`signed portal identity is required but ${problem}. Provision distinct secrets or enforcement is bypassable.`,
);
}
return buildServer(app, deps, false);
}
export function createInsecureTestServer(app: App, deps: ServerOptions = {}): Server {
if (deps.signingSecret) throw new Error("createInsecureTestServer must not receive a signing secret");
return buildServer(app, deps, true);
}