A local-first multi-agent app development platform, built on PenguinHarness
/**
* The `/api/amsp/v1` gate: who a request is for, and whether it may be made — decided before the
* body is read. In order:
*
* 1. the admin switch: off answers every request 403 `agent_api_disabled` (the CORS preflight
* is answered before this gate runs);
* 2. the path names an Agent (`/agents/:projectId/:agentId…`) or an API Session
* (`/sessions/:sessionId…`): an invalid id, an Agent whose API switch is off or that does not
* exist, a Session no API run created, or one whose Agent's switch is off, is a 404 that says
* nothing about which of these it was;
* 3. the caller: an `Authorization` header must carry a key of that Agent — an unknown key is
* 401, another Agent's key the same 404 as an unknown Agent (or Session); no header at all is
* accepted only when the Agent allows keyless access, 401 otherwise.
*
* Any other path under the prefix passes through untouched, to the group's 404 tail.
*
* The first two checks are also the API tab's try route's (try-route.ts), which stands the
* owner's sign-in where the key would be.
*/
import { isValidId } from "@adelie/core";
import type { MiddlewareHandler } from "hono";
import type { AppEnv } from "../auth/middleware.js";
import { bearerToken } from "../auth/middleware.js";
import type { SessionRow } from "../db/repos/sessions.js";
import { HttpError } from "../http/errors.js";
import type { AgentApi, AgentApiRow } from "../mechanisms/agent-api.js";
import type { AgentConfig } from "../mechanisms/agents.js";
import type { SessionIndex } from "../mechanisms/sessions.js";
import type { Settings } from "../mechanisms/settings.js";
import { hashAgentApiKey } from "./keys.js";
/** What the gate resolved a request to: the Agent it is for, the key it presented, the Session it names. */
export interface AmspContext {
projectId: string;
agentId: string;
/** The key that authenticated the request; null for a keyless request to an open Agent. */
keyId: string | null;
/** The API Session a `/sessions/:sessionId…` path names; null on an Agent path. */
session: SessionRow | null;
}
/** The group's Hono env: the app's, plus the gate's resolution. */
export type AmspEnv = { Variables: AppEnv["Variables"] & { amsp: AmspContext } };
export interface AmspGateDeps {
settings: Pick<Settings, "getAgentApiEnabled">;
agentApi: AgentApi;
sessions: Pick<SessionIndex, "findById">;
agentConfig: Pick<AgentConfig, "exists">;
}
/** One answer for an Agent that does not exist, is not exposed, or is not the key's. */
export const agentNotFound = (): HttpError =>
new HttpError(404, "agent_not_found", "No Agent with this id has its API enabled.");
/** One answer for a Session that does not exist, is not an API Session, or is not the key's Agent's. */
export const sessionNotFound = (): HttpError =>
new HttpError(404, "session_not_found", "No API Session with this id.");
const unauthorized = (message: string): HttpError => new HttpError(401, "unauthorized", message);
/** The admin's switch: off refuses every request 403 `agent_api_disabled`. */
export function requireAgentApiOn(settings: Pick<Settings, "getAgentApiEnabled">): void {
if (!settings.getAgentApiEnabled()) {
throw new HttpError(403, "agent_api_disabled", "The Agent API is turned off on this server.");
}
}
/**
* The Agent a path names, once it is exposed: valid ids, its API switch on, and the Agent there.
* Anything else is the one 404 `agent_not_found`, which says nothing about which it was.
*/
export async function requireExposedAgent(
deps: Pick<AmspGateDeps, "agentApi" | "agentConfig">,
projectId: string,
agentId: string,
): Promise<AgentApiRow> {
if (!isValidId(projectId) || !isValidId(agentId)) throw agentNotFound();
const api = deps.agentApi.get(projectId, agentId);
if (api === null || !api.enabled) throw agentNotFound();
if (!(await deps.agentConfig.exists(projectId, agentId))) throw agentNotFound();
return api;
}
/** The path below the group prefix, split into decoded segments; null when a segment does not decode. */
function segmentsOf(path: string, prefix: string): string[] | null {
const rest = path.startsWith(prefix) ? path.slice(prefix.length) : path;
try {
return rest
.split("/")
.filter((s) => s !== "")
.map((s) => decodeURIComponent(s));
} catch {
return null;
}
}
export function amspGate(prefix: string, deps: AmspGateDeps): MiddlewareHandler<AmspEnv> {
/**
* The caller, against the Agent's settings: the key it presents (null when it presents none),
* or the refusal. `notTheKeys` is the 404 a key of another Agent gets.
*/
const authenticate = (
header: string | undefined,
api: AgentApiRow,
notTheKeys: () => HttpError,
): string | null => {
if (header === undefined) {
if (!api.open) throw unauthorized("This Agent requires an API key.");
return null;
}
const token = bearerToken(header);
const key = token === null ? null : deps.agentApi.findKeyByHash(hashAgentApiKey(token));
if (key === null) throw unauthorized("Invalid API key.");
if (key.projectId !== api.projectId || key.agentId !== api.agentId) throw notTheKeys();
return key.keyId;
};
return async (c, next) => {
requireAgentApiOn(deps.settings);
const segments = segmentsOf(c.req.path, prefix);
const header = c.req.header("authorization");
if (segments !== null && segments[0] === "agents" && segments.length >= 3) {
const [, projectId, agentId] = segments as [string, string, string];
const api = await requireExposedAgent(deps, projectId, agentId);
const keyId = authenticate(header, api, agentNotFound);
c.set("amsp", { projectId, agentId, keyId, session: null });
} else if (segments !== null && segments[0] === "sessions" && segments.length >= 2) {
const sessionId = segments[1]!;
if (!isValidId(sessionId)) throw sessionNotFound();
const row = deps.sessions.findById(sessionId);
if (row === null || row.client !== "api") throw sessionNotFound();
const api = deps.agentApi.get(row.projectId, row.agentId);
if (api === null || !api.enabled) throw sessionNotFound();
const keyId = authenticate(header, api, sessionNotFound);
c.set("amsp", { projectId: row.projectId, agentId: row.agentId, keyId, session: row });
}
await next();
};
}