A local-first multi-agent app development platform, built on PenguinHarness
/**
* Admin server-settings routes (admin only, 403 for non-admins):
* GET|PUT /api/admin/settings — the server-global settings stored in server_settings:
* the proxy settings (the "application uses the proxy" and "agent environment uses the
* proxy" switches and their shared explicit address) and the upload limits (the
* per-file and per-message attachment caps, in whole MB) and the Agent API switch.
* A PUT applies immediately: everything is validated first (a rejected request writes
* nothing), then the persisted values are written, then the process dispatcher is
* rebuilt so new outbound connections follow the change without a restart (the agent
* switch needs no push — the command-subprocess policy getter re-reads the repo at
* every spawn). The upload limits need no push either, for the same reason: the
* attachment validators and the request body cap both read the repo per request.
* A PUT carrying `agentApiEnabled` takes a person's sign-in: the local API token is refused
* with 403 `human_required`, and nothing in that body is written. The token may change every
* other field.
*
* GET /api/admin/settings/proxy-probe names the model provider hosts the reachability probe
* would request; POST .../proxy-probe/:provider measures one of them — unauthenticated, see
* services/proxy-probe.ts.
*/
import { Hono } from "hono";
import type {
ProxyProbeResponse,
ProxyProbeTargetsResponse,
ServerSettingsResponse,
} from "../../api/types.js";
import { HttpError } from "../errors.js";
import { requireHuman } from "../../auth/middleware.js";
import type { AppEnv } from "../../auth/middleware.js";
import { optionalBoolean, readJson } from "../validate.js";
import type { ProxyControl } from "../../hmr/capabilities.js";
/** What this route group reaches — bound by its module (src/modules). */
export interface AdminSettingsRouteDeps {
proxyControl: ProxyControl;
serverSettingsRepo: Settings;
}
import { applyProxySettings, normalizeProxyUrl } from "../../net/proxy.js";
import { MAX_ATTACHMENT_MB, MIN_ATTACHMENT_MB } from "../../services/attachment-limits.js";
import {
PROXY_PROBE_TARGETS,
probeProxyReachabilityOf,
proxyProbeTarget,
} from "../../services/proxy-probe.js";
import type { Settings } from "../../mechanisms/settings.js";
/**
* proxyUrl update value -> stored value: null and empty/whitespace-only clear the
* address; anything else must normalize (see normalizeProxyUrl) or the whole PUT is
* rejected with `invalid_proxy_url` — un-normalized values are never stored.
*/
function parseProxyUrl(value: unknown): string | null {
if (value === null) return null;
if (typeof value === "string") {
if (value.trim() === "") return null;
const normalized = normalizeProxyUrl(value);
if (normalized !== null) return normalized;
}
throw new HttpError(
400,
"invalid_proxy_url",
"proxyUrl must be a proxy URL undici supports — http(s)://host[:port] or socks5://host[:port] — or bare host[:port] (empty or null clears it).",
);
}
/**
* An attachment limit update value -> stored whole-MB integer. Everything outside the supported
* range is refused with one dedicated code the Web App renders under the field — the range is the
* point of the setting (an admin typing 100GB must be told no, not obeyed), so the failure has to
* be legible rather than a generic `bad_request`.
*/
function parseAttachmentMb(value: unknown, field: string): number {
if (typeof value === "number" && Number.isInteger(value)) {
if (value >= MIN_ATTACHMENT_MB && value <= MAX_ATTACHMENT_MB) return value;
}
throw new HttpError(
400,
"invalid_attachment_limit",
`${field} must be a whole number of MB between ${MIN_ATTACHMENT_MB} and ${MAX_ATTACHMENT_MB}.`,
);
}
export function adminSettingsRoutes(deps: AdminSettingsRouteDeps): Hono<AppEnv> {
const app = new Hono<AppEnv>();
app.use("*", async (c, next) => {
if (!c.var.user.isAdmin) {
throw new HttpError(403, "admin_required", "Only an admin can perform this operation.");
}
await next();
});
const settings = (): ServerSettingsResponse => ({
settings: {
proxyForApp: deps.serverSettingsRepo.getProxyForApp(),
proxyForAgent: deps.serverSettingsRepo.getProxyForAgent(),
proxyUrl: deps.serverSettingsRepo.getProxyUrl(),
...deps.serverSettingsRepo.getAttachmentLimitsMb(),
companyMode: deps.serverSettingsRepo.getCompanyMode(),
agentApiEnabled: deps.serverSettingsRepo.getAgentApiEnabled(),
},
});
app.get("/", (c) => c.json(settings()));
app.put("/", async (c) => {
const body = await readJson(c);
// The Agent API switch decides whether any Agent can be reached from outside, so it takes a
// person's sign-in, never the local API token every tool subprocess holds (see
// requireHuman). Refused before any field is written.
if (body.agentApiEnabled !== undefined) requireHuman(c);
// Validate every provided field before writing any: a partial PUT with one invalid
// field must leave the others untouched too.
const proxyForApp = optionalBoolean(body, "proxyForApp");
const proxyForAgent = optionalBoolean(body, "proxyForAgent");
const companyMode = optionalBoolean(body, "companyMode");
const agentApiEnabled = optionalBoolean(body, "agentApiEnabled");
const proxyUrlProvided = body.proxyUrl !== undefined;
const proxyUrl = proxyUrlProvided ? parseProxyUrl(body.proxyUrl) : null;
const attachmentMaxMb =
body.attachmentMaxMb === undefined
? undefined
: parseAttachmentMb(body.attachmentMaxMb, "attachmentMaxMb");
const attachmentTotalMb =
body.attachmentTotalMb === undefined
? undefined
: parseAttachmentMb(body.attachmentTotalMb, "attachmentTotalMb");
// The pair is only meaningful together, so the relation is checked against the EFFECTIVE
// post-write values: a PUT that raises only the per-file cap must be refused when the stored
// total would leave a legal single attachment unsendable, and one that lowers only the total
// must be refused for the same reason. Checked before any write, like every other field.
const stored = deps.serverSettingsRepo.getAttachmentLimitsMb();
const effectiveMax = attachmentMaxMb ?? stored.attachmentMaxMb;
const effectiveTotal = attachmentTotalMb ?? stored.attachmentTotalMb;
if (effectiveTotal < effectiveMax) {
throw new HttpError(
400,
"invalid_attachment_limit",
`attachmentTotalMb (${effectiveTotal}) must not be below attachmentMaxMb (${effectiveMax}).`,
);
}
// Read per tick by the organization scheduler and per request by the organization routes, so
// flipping it needs no restart: off holds every automatic trigger and 404s the routes.
if (companyMode !== undefined) deps.serverSettingsRepo.setCompanyMode(companyMode);
// Read per request by the /api/amsp/v1 gate: off refuses every Agent API call from the next
// request on (403 agent_api_disabled); each Agent's switch, approval mode and keys stay.
if (agentApiEnabled !== undefined) deps.serverSettingsRepo.setAgentApiEnabled(agentApiEnabled);
if (proxyForApp !== undefined) deps.serverSettingsRepo.setProxyForApp(proxyForApp);
if (proxyForAgent !== undefined) deps.serverSettingsRepo.setProxyForAgent(proxyForAgent);
if (proxyUrlProvided) deps.serverSettingsRepo.setProxyUrl(proxyUrl);
if (attachmentMaxMb !== undefined) deps.serverSettingsRepo.setAttachmentMaxMb(attachmentMaxMb);
if (attachmentTotalMb !== undefined) {
deps.serverSettingsRepo.setAttachmentTotalMb(attachmentTotalMb);
}
// Mirror the app switch + address into the process: rebuilds the global fetch
// dispatcher (live change, no restart; a no-op when nothing effectively changed).
// Through the claimed capability, not a direct import: this route runs inside the
// platform bundle, whose own copy of net/proxy.js drives a dispatcher that
// globalThis.fetch never routes through (see AppDeps.proxyControl).
deps.proxyControl({
proxyForApp: deps.serverSettingsRepo.getProxyForApp(),
proxyUrl: deps.serverSettingsRepo.getProxyUrl(),
});
return c.json(settings());
});
// What the probe would request, without requesting it: the page lists the targets — name
// and exact URL — before anyone presses the button, so the list is served rather than
// copied into the frontend, where a second copy could drift from what is really fetched.
app.get("/proxy-probe", (c) =>
c.json({ targets: [...PROXY_PROBE_TARGETS] } satisfies ProxyProbeTargetsResponse),
);
// Reachability and latency of the server's outbound path to ONE provider host, named by a
// path segment matched against the fixed target list. Admin-only through the router's guard
// above, like every other route here.
//
// Takes no request body and no URL: the only thing a caller supplies is a provider id, and
// an id that is not in the list is a 404 rather than a fetch. Nothing is written, but it
// does reach the network, so it is a POST rather than a GET.
//
// One target per call because the page renders each answer as it arrives; the concurrency
// is the browser's, and a host that black-holes connections holds up only its own row.
// The path measured is whatever the process dispatcher currently is, which follows the
// STORED settings — a PUT is what moves it, which is why the page puts this below Save.
app.post("/proxy-probe/:provider", async (c) => {
const target = proxyProbeTarget(c.req.param("provider"));
if (target === null) {
throw new HttpError(404, "probe_target_not_found", "No probe target with that provider id.");
}
// Plain global fetch on purpose — that is the undici fetch the startup entry installed,
// and it resolves the proxy dispatcher per call. No credential is attached anywhere
// below, including from the process environment (see services/proxy-probe.ts).
const probe = await probeProxyReachabilityOf(target);
return c.json({ probe } satisfies ProxyProbeResponse);
});
return app;
}