import {
defaultScopes,
type OwnershipResolver,
PEOPLE_ONLY_OWNERSHIP,
PolicyEngine,
type Principal,
} from "@cloudhal/agent-runtime";
import { ANALYTICS_OFF } from "@cloudhal/analytics/service";
import { type SchedulesDeps, schedulesAvailable } from "@cloudhal/mcp-server/schedules";
import { defineTools, toolPolicies } from "@cloudhal/mcp-server/tools";
import { type Context, Hono } from "hono";
import { type BuildHub, createBuildHub } from "./build.ts";
import type { ApiDeps, Env } from "./context.ts";
import { errorHandler } from "./errors.ts";
import { mountMcp } from "./mcp-mount.ts";
import { fencedOauthPath, mountClientRegistration, mountOauthServer } from "./oauth-server.ts";
import { PLAYGROUND_PRINCIPAL, playgroundGuard } from "./playground.ts";
import { activity, deploymentActivity } from "./routes/activity.ts";
import { mountAdmin } from "./routes/admin-mount.ts";
import { agentKeys } from "./routes/agent-keys.ts";
import { aiRoutes } from "./routes/ai.ts";
import { analytics } from "./routes/analytics.ts";
import { approvals } from "./routes/approvals.ts";
import { assets, siteMedia } from "./routes/assets.ts";
import { blockTypes } from "./routes/block-types.ts";
import { chrome } from "./routes/chrome.ts";
import { collections } from "./routes/collections.ts";
import { comments } from "./routes/comments.ts";
import { design } from "./routes/design.ts";
import { entries } from "./routes/entries.ts";
import {
agentModesInfo,
commentsFeature,
gatesEnforcedEverywhere,
instanceRoutes,
invitesInfo,
rolesInfo,
schedulesFeature,
} from "./routes/instance.ts";
import { inviteRoutes } from "./routes/invites.ts";
import { meHandler } from "./routes/me.ts";
import { memberRoutes } from "./routes/members.ts";
import { menus } from "./routes/menus.ts";
import { migrations } from "./routes/migrations.ts";
import { notificationRoutes } from "./routes/notifications.ts";
import { pages } from "./routes/pages.ts";
import { passwordResetRoutes } from "./routes/password-reset.ts";
import { previewLinks } from "./routes/preview-links.ts";
import { projects } from "./routes/projects.ts";
import { proposals } from "./routes/proposals.ts";
import { redirects } from "./routes/redirects.ts";
import { scheduleRoutes, schedulerRoute } from "./routes/schedules.ts";
import { siteSearch } from "./routes/search.ts";
import { siteBuild } from "./routes/site-build.ts";
import { sites } from "./routes/sites.ts";
import { snapshots } from "./routes/snapshots.ts";
import { taxonomies } from "./routes/taxonomies.ts";
import { terms } from "./routes/terms.ts";
import { themeSettings } from "./routes/theme-settings.ts";
import { glossary, translations } from "./routes/translations.ts";
import { routeGuard } from "./scopes.ts";
import { randomUploadSecret, type UploadSecret } from "./uploads.ts";
/**
* Better Auth endpoints that are only used server-side: membership changes go through Cloudhal's
* audited routes (RFC-0005 I3), and agent keys through `/api/agent-keys` (role caps, I5/I6).
*/
const FENCED_AUTH_PATHS = /^\/api\/auth\/(organization|admin|api-key)(\/|$)/;
/**
* The site's REST areas for people (agents use the MCP tools), each under
* `/api/sites/:siteId/`; their requirements are in `ROUTE_SCOPES`.
*/
const SITE_AREAS: readonly (readonly [string, Hono])[] = [
["pages", pages],
["entries", entries],
// RFC-0040: the collection registry.
["collections", collections],
["proposals", proposals],
// RFC-0015: the block registry (built-ins and the theme's types).
["block-types", blockTypes],
["theme-settings", themeSettings],
["chrome", chrome],
// RFC-0021: the site's design rules (DESIGN.md).
["design", design],
["snapshots", snapshots],
["activity", activity],
["preview-links", previewLinks],
["approvals", approvals],
// RFC-0002 §6.1: taxonomy, terms, redirects and the tags migration.
["taxonomies", taxonomies],
["terms", terms],
["redirects", redirects],
// RFC-0033 §8: language versions, reviews and the glossary.
["translations", translations],
["glossary", glossary],
["migrations", migrations],
// RFC-0029 §7: the command palette's search over the site's own nodes, drafts included.
["search", siteSearch],
// RFC-0003 §5: navigation menus.
["menus", menus],
// RFC-0004 §6.1: the media library.
["assets", assets],
["media", siteMedia],
// #150: the self-hosted static site's rebuild on publish (`enabled: false` elsewhere).
["site-build", siteBuild],
];
/**
* Builds the Cloudhal API as a Hono app (a `fetch` handler). The same app runs on Node
* (`@hono/node-server`) and on Cloudflare Workers.
*/
export function createApi(deps: ApiDeps) {
const requireAuth = deps.requireAuth ?? true;
const app = new Hono();
app.onError(errorHandler);
const clock = deps.now ?? (() => new Date());
const defer =
deps.defer ??
((task: Promise) => {
task.catch(() => {});
});
const ownership: OwnershipResolver = deps.staff?.ownership ?? PEOPLE_ONLY_OWNERSHIP;
// Upload tickets (RFC-0004 §5.5) are signed with a secret every instance shares when there is
// one; a server without one (local tools) signs with a key of its own process.
const uploadSecret: UploadSecret =
[deps.preview?.secret, deps.mcp?.stateKey].find(
(s): s is string | Uint8Array =>
s !== undefined &&
(typeof s === "string" ? new TextEncoder().encode(s) : s).byteLength >= 32,
) ?? randomUploadSecret();
// RFC-0008: the schedule routes and tools use the deployment's ticker (`ApiDeps.scheduler`)
// unless `schedules.scheduler` names another.
const schedules =
deps.schedules && !deps.schedules.scheduler && deps.scheduler
? { ...deps.schedules, scheduler: deps.scheduler }
: deps.schedules;
let engine: PolicyEngine | undefined;
const policy = () => {
engine ??= new PolicyEngine(toolPolicies(defineTools()));
return engine;
};
// RFC-0036 §5: a playground refuses blocked routes before anything else runs.
const playground = deps.playground;
if (playground) app.use("*", playgroundGuard(playground));
// DNS rebinding: a server without auth (local scripts) only answers its own host names.
if (deps.allowedHosts) {
const allowed = new Set(deps.allowedHosts.map((h) => h.toLowerCase()));
app.use("*", async (c, next) => {
const host = new URL(c.req.url).hostname.toLowerCase();
if (!allowed.has(host))
return c.json({ error: "forbidden", message: `host ${host} is not allowed` }, 403);
await next();
});
}
// RFC-0020 §6: page changes for Studio's Build view (MCP tools and Studio saves report here).
const build = deps.build ?? createBuildHub(deps.now);
const trusted = new Set(deps.trustedOrigins ?? []);
app.use("/api/*", csrfGuard(trusted)); // CSRF for cookie-carrying writes
const shared: SharedContext = { build, ownership, policy, defer, clock, uploadSecret, schedules };
app.use("*", async (c, next) => {
setContext(c, deps, shared);
// The fenced Better Auth endpoints never reach credential resolution.
// Raw and decoded: whichever form Better Auth or Hono would dispatch on is fenced.
if (fencedAuthPath(new URL(c.req.url).pathname, deps) || fencedAuthPath(c.req.path, deps))
return c.json({ error: "not_found", message: "not found" }, 404);
const principal = await resolvePrincipal(c, deps);
c.set("principal", principal);
c.set("actor", principal?.actor);
await next();
});
// Default-deny REST (RFC-0005 I15): every route declares its requirement in `ROUTE_SCOPES`.
const membership = Boolean(deps.staff || playground); // a playground is checked like a role
app.use("/api/*", routeGuard({ requireAuth, membership }));
// API answers are per person and change with every write: a GET without its own caching header
// says `no-store`, because Workers Cache was seen caching header-less GET answers (RFC-0008 §13).
app.use("/api/*", async (c, next) => {
await next();
if ((c.req.method === "GET" || c.req.method === "HEAD") && !c.res.headers.has("cache-control"))
c.res.headers.set("cache-control", "no-store");
});
const problems = mountAdmin(app, deps);
app.get("/api/health", (c) => c.json(problems.length ? { ok: true, problems } : { ok: true }));
mountAuthHandler(app, deps);
app.get("/api/me", meHandler(membership));
// RFC-0044 §1: with `mcp.oauth`, the route also serves OAuth discovery.
if (deps.mcp) mountMcp(app, { ...deps, mcp: deps.mcp }, { build, ownership, schedules });
if (deps.agentKeys) app.route("/api/agent-keys", agentKeys(deps.agentKeys));
// RFC-0044 Phase 2: the authorization server's metadata, consent and connections.
if (deps.oauthServer) mountOauthServer(app, deps.oauthServer);
app.route(
"/api",
instanceRoutes(
async () => ({
signUp: deps.signUp ?? "unknown",
features: {
agentKeys: Boolean(deps.agentKeys),
mcp: Boolean(deps.mcp),
...oauthFeatures(deps),
activity: Boolean(deps.audit ?? deps.mcp?.audit),
previewLinks: Boolean(deps.preview),
deployTransfer: Boolean(deps.admin) && problems.length === 0,
approvals: Boolean(deps.mcp?.approvals),
elevationRequests: Boolean(deps.mcp?.approvals && deps.agentKeys),
members: Boolean(deps.staff),
// RFC-0006 §8: where events go, whether Studio can read them, the budget.
analytics: deps.analytics?.feature() ?? ANALYTICS_OFF,
// RFC-0007 §12: whether comments are served, bot protections, purges waiting.
comments: await commentsFeature(deps.comments),
ai: deps.ai?.transport?.kind ?? "none", // RFC-0016: the AI binding, REST, or none
schedules: schedulesFeature(
// RFC-0008 §13: whether schedules are served, the ticker, gates, the limits.
schedules,
schedulesAvailable(schedules) && (await gatesEnforcedEverywhere(deps.store)),
),
...(playground ? { playground: await playground.info() } : {}), // RFC-0036 §5
referenceFields: deps.store.fieldTypes !== undefined, // RFC-0045, MCP's rule (step 5)
},
agentModes: agentModesInfo(),
roles: rolesInfo(),
invites: invitesInfo(Boolean(deps.mail)),
passwordReset: deps.staff && deps.mail ? ["admin", "email"] : ["admin"],
}),
deps.mcp?.skills ?? [],
),
);
if (deps.staff) {
const links = { studioOrigin: deps.studioOrigin, trustedOrigins: trusted };
app.route("/api/members", memberRoutes(links));
app.route("/api/invites", inviteRoutes(links));
app.route("/api/password-reset", passwordResetRoutes(links));
}
app.route("/api/activity", deploymentActivity);
app.route("/api/notifications", notificationRoutes(clock));
app.route("/api/sites", sites).route("/api/projects", projects);
for (const [area, routes] of SITE_AREAS) app.route(`/api/sites/:siteId/${area}`, routes);
// RFC-0016: in-editor AI settings, the model picker and commands.
// RFC-0021 21c: Build chat renders with the same browser as `render_page`.
app.route(
"/api/sites/:siteId/ai",
aiRoutes(deps.ai && deps.mcp?.render ? { ...deps.ai, render: deps.mcp.render } : deps.ai),
);
// RFC-0006 §9.2: site analytics (people; agents use the MCP analytics tools).
if (deps.analytics) app.route("/api/sites/:siteId/analytics", analytics);
// RFC-0007 §12: reader comments (people; agents use the MCP comment tools).
if (deps.comments) app.route("/api/sites/:siteId", comments);
// RFC-0008 §13: schedules (people; agents use the MCP schedule tools).
if (schedules) {
app.route("/api/sites/:siteId", scheduleRoutes);
app.route("/api/scheduler", schedulerRoute);
}
app.notFound((c) =>
c.json({ error: "not_found", message: `no route for ${c.req.method} ${c.req.path}` }, 404),
);
return app;
}
/**
* RFC-0044: whether remote MCP clients connect by URL (OAuth), and how: the `/mcp` resource they
* are given and which registrations work here (Studio's "Connect by URL" notes, §11).
*/
function oauthFeatures(deps: ApiDeps) {
const server = deps.oauthServer;
const on = Boolean(server && deps.mcp?.oauth);
return {
mcpOauth: on,
...(on && server
? { mcpOauthClients: { resource: server.resource, ...server.registration } }
: {}),
};
}
/** Better Auth paths HTTP callers never reach (raw and decoded forms are both checked). */
function fencedAuthPath(path: string, deps: ApiDeps): boolean {
const open = { register: Boolean(deps.oauthServer?.register) };
return FENCED_AUTH_PATHS.test(path) || fencedOauthPath(path, open);
}
/** Better Auth's routes; RFC-0044 §3: DCR is Cloudhal's route, ahead of the catch-all. */
function mountAuthHandler(app: Hono, deps: ApiDeps): void {
if (deps.oauthServer?.register) mountClientRegistration(app, deps.oauthServer.register);
const handler = deps.authHandler;
if (handler) app.on(["GET", "POST"], "/api/auth/*", (c) => handler(c.req.raw));
}
/**
* CSRF: state-changing requests that may carry a session cookie must come from this origin (or a
* trusted one). Better Auth checks its own routes; /api/admin uses a bearer token, not cookies.
*/
function csrfGuard(trusted: ReadonlySet) {
return async (c: Context, next: () => Promise) => {
const method = c.req.method;
const path = new URL(c.req.url).pathname;
if (method === "GET" || method === "HEAD" || method === "OPTIONS") return next();
if (path.startsWith("/api/auth/") || path.startsWith("/api/admin/")) return next();
const origin = c.req.header("origin");
const own = new URL(c.req.url).origin;
const fetchSite = c.req.header("sec-fetch-site");
const ok =
origin !== undefined
? origin === own || trusted.has(origin)
: fetchSite === undefined || fetchSite === "same-origin" || fetchSite === "none";
if (!ok) return c.json({ error: "forbidden", message: "cross-origin request refused" }, 403);
await next();
};
}
/** What `createApi` builds once and every request reads next to its `ApiDeps`. */
interface SharedContext {
readonly build: BuildHub;
readonly ownership: OwnershipResolver;
readonly policy: () => PolicyEngine;
readonly defer: (task: Promise) => void;
readonly clock: () => Date;
readonly uploadSecret: UploadSecret;
readonly schedules: SchedulesDeps | undefined;
}
/** The per-request variables (`Env["Variables"]`) every route reads. */
function setContext(c: Context, deps: ApiDeps, shared: SharedContext): void {
c.set("store", deps.store);
c.set("build", shared.build);
c.set("audit", deps.audit ?? deps.mcp?.audit);
c.set("previewSecret", deps.preview?.secret);
c.set("approvals", deps.mcp?.approvals);
c.set("agentKeys", deps.agentKeys);
c.set("staff", deps.staff);
c.set("ownership", shared.ownership);
c.set("policy", shared.policy);
c.set("mail", deps.mail);
c.set("defer", shared.defer);
c.set("now", shared.clock);
c.set("uploadSecret", shared.uploadSecret);
c.set("analytics", deps.analytics);
c.set("comments", deps.comments);
c.set("schedules", shared.schedules);
c.set("scheduler", deps.scheduler);
c.set("siteBuild", deps.siteBuild);
// #165: where rate limits read the client's address (`ApiDeps.clientAddressHeader`).
c.set("clientAddressHeader", deps.clientAddressHeader);
}
/** Who is calling: the playground's one principal (RFC-0036 §5), else the deployment's resolver. */
async function resolvePrincipal(c: Context, deps: ApiDeps): Promise {
if (deps.playground) return PLAYGROUND_PRINCIPAL;
if (deps.resolvePrincipal) return deps.resolvePrincipal(c);
const actor = deps.resolveActor ? await deps.resolveActor(c) : undefined;
return actor ? { actor, scopes: defaultScopes(actor) } : undefined;
}
export type CloudhalApi = ReturnType;