src/portal-actions.ts

Functions

Imports

It imports src/auth.ts, src/controls.ts, src/env.ts, src/http.ts, src/log.ts, src/ops-feed.ts, src/ops-types/portal.ts, src/portal-activity.ts, src/portal-auth.ts, src/portal-host.ts, src/signed-requests.ts, src/status.ts. Imported by src/push.ts, src/routes.ts.

Source

1import { getCookie } from "./auth";
2import { safeEqual } from "@dustinedwards/site-runtime/compare";
3import { performControl, previewControl } from "./controls";
4import { ACTIVITY_LIMIT, activityFilterFrom, loadActivity } from "./portal-activity";
5import { type PortalUser, portalDisplay, portalGate, portalSignOutCookies, sourceAddress } from "./portal-auth";
6import { portalCookiePath } from "./portal-host";
7import type { Env } from "./env";
8import { capsidStatus } from "./status";
9import { readBoundedText } from "./signed-requests";
10import { isoTime, opsFeed, OPS_RETURN_TO, PORTAL_CSRF_COOKIE, type OpsFeedData } from "./ops-feed";
11import type { PortalActivity, PortalNamespaces, PortalPerformed } from "./ops-types/portal";
12import { logEvent } from "./log";
13import { jsonResponse, textResponse } from "./http";
14// The Portal's routes for the controls (src/controls.ts holds the controls): the eight actions, what each will do, the one dispatch to the
15// shared mutators, and the routes the app calls (the contract is the bottom of
16// src/ops-types/). They replaced the old /console page's forms, which called this
17// same dispatch (capsid/research/design-portal-unify.md), so no transition is
18// implemented twice.
19//
20// No merge (it can start a CI deploy, so it stays behind can_merge) and no mint (a
21// mint hands out a key). test/portal-actions.test.ts asserts both absences.
22//
23// Two requests per action, as ruled 2026-09-11. The preview reads the current state,
24// writes nothing, and returns what will change with a signed token that carries the
25// action, its params, the administrator's email and a five-minute expiry. The perform
26// carries only that token. A replay inside the five minutes is allowed: every
27// transition is guarded on the state it moves from, so a second perform is refused by
28// the mutator or changes nothing.
29//
30// Every route answers to portalGate, as the feed does. They are routes, not tools, so
31// no grant is checked here (one enforcement point, test/route-gates.test.ts); src/scope.ts lists
32// them among the routes gated some other way.
33
34export const PORTAL_PREVIEW_PATH = "/portal/api/actions/preview";
35export const PORTAL_PERFORM_PATH = "/portal/api/actions/perform";
36export const PORTAL_NAMESPACES_PATH = "/portal/api/namespaces";
37export const PORTAL_ACTIVITY_PATH = "/portal/api/activity";
38export const PORTAL_SIGN_OUT_PATH = "/portal/api/sign-out";
39// Every Portal data and action route sits under here. A path under it that no route
40// names is a JSON 404 (handlePortalApiNotFound), never the app's page.
41export const PORTAL_API_PREFIX = "/portal/api/";
42// The double-submit CSRF header: the feed's csrf value, compared with the
43// capsid_portal_csrf cookie. A cross-site page can neither read the value nor set the
44// header without a preflight this Worker does not answer.
45export const PORTAL_CSRF_HEADER = "X-Capsid-CSRF";
46
47// Same cap as the consent form, applied at the stream before parsing.
48const BODY_MAX_BYTES = 65_536;
49
50// ---------------------------------------------------------------------------
51// The routes.
52
53
54type Gated = { ok: true; email: string; user: PortalUser; csrf: string; body: Record<string, unknown> } | { ok: false; response: Response };
55
56/** The checks both POSTs run, in order: the session, the fetch metadata, the body cap,
57 *  the CSRF pair, then the JSON. Nothing here reads or writes state. */
58export async function gateActionRequest(request: Request, env: Env, now: Date): Promise<Gated> {
59  const gate = await portalGate(request, env, now, OPS_RETURN_TO);
60  if (!gate.ok) return gate;
61
62  // A browser names where a request came from. Absent (an older browser, or curl with
63  // the cookies) is let through to the CSRF check; any other site is refused here.
64  const site = request.headers.get("Sec-Fetch-Site");
65  if (site !== null && site !== "same-origin") {
66    return {
67      ok: false,
68      response: textResponse(`forbidden: this request came from ${site}, not from Capsid Portal itself (Sec-Fetch-Site: ${site}). Nothing was read or changed.`, 403),
69    };
70  }
71
72  const bounded = await readBoundedText(request, BODY_MAX_BYTES);
73  if (!bounded.ok) return { ok: false, response: new Response(null, { status: 413, headers: { "Cache-Control": "no-store" } }) };
74
75  const header = request.headers.get(PORTAL_CSRF_HEADER);
76  const cookie = getCookie(request, PORTAL_CSRF_COOKIE);
77  if (!header || !cookie || !await safeEqual(cookie, header)) {
78    return { ok: false, response: textResponse("csrf validation failed: reload Capsid Portal and try again.", 403) };
79  }
80
81  let body: unknown;
82  try {
83    body = JSON.parse(bounded.text);
84  } catch (err) {
85    return { ok: false, response: textResponse(`the body is not JSON: ${err instanceof Error ? err.message : String(err)}`, 400) };
86  }
87  if (!body || typeof body !== "object" || Array.isArray(body)) {
88    return { ok: false, response: textResponse("the body must be a JSON object.", 400) };
89  }
90  return { ok: true, email: gate.user.email, user: gate.user, csrf: cookie, body: body as Record<string, unknown> };
91}
92
93
94/** POST /portal/api/actions/preview: what the action will change, and a token to
95 *  perform it. Writes nothing. */
96export async function handlePortalPreview(request: Request, env: Env, now: Date = new Date()): Promise<Response> {
97  const gated = await gateActionRequest(request, env, now);
98  if (!gated.ok) return gated.response;
99  const previewed = await previewControl(env, gated.email, gated.body.action, gated.body.params, now, "portal");
100  if (!previewed.ok) return textResponse(previewed.refusal, previewed.status);
101  return jsonResponse(previewed.preview);
102}
103
104// What the perform can be handed in a test in place of the live feed read.
105export interface PortalDeps {
106  feed?: (env: Env, now: Date) => Promise<OpsFeedData>;
107}
108
109/** POST /portal/api/actions/perform: the action a preview signed, run through the
110 *  shared mutator, then the fresh feed. */
111export async function handlePortalPerform(request: Request, env: Env, now: Date = new Date(), deps: PortalDeps = {}): Promise<Response> {
112  const gated = await gateActionRequest(request, env, now);
113  if (!gated.ok) return gated.response;
114  const extra = Object.keys(gated.body).filter((key) => key !== "token");
115  if (extra.length) {
116    return textResponse(
117      `a perform carries only { token }: the action and its params come from the signed preview, never from this body. Refused: ${extra.join(", ")}.`,
118      400
119    );
120  }
121  const did = await performControl(env, gated.email, gated.body.token, sourceAddress(request), now, "portal");
122  if (!did.ok) return textResponse(did.refusal, did.status);
123  const { action, result } = did;
124
125  let data: OpsFeedData;
126  try {
127    data = await (deps.feed ?? opsFeed)(env, now);
128  } catch (err) {
129    // The action happened; only the read after it failed. Said as a failure of the
130    // read, never as a failure of the action.
131    const message = err instanceof Error ? err.message : String(err);
132    logEvent("error", "PORTAL_PERFORM_FEED_FAILED", { message: `PORTAL_PERFORM_FEED_FAILED ${action}: ${message}` });
133    return textResponse(`${result.summary} It completed, but reading the feed afterwards failed (${message}). Reload Capsid Portal.`, 500);
134  }
135  const performed: PortalPerformed = { action, summary: result.summary, warning: result.warning, feed: { ...data, csrf: gated.csrf, user: portalDisplay(gated.user) } };
136  // A header value must be printable Latin-1; the error text is not guaranteed to be.
137  return jsonResponse(performed, 200, result.warning ? { "X-Capsid-Warning": result.warning.replace(/[^\x20-\x7e]+/g, " ") } : {});
138}
139
140/** GET /portal/api/namespaces: every roster namespace as capsid_run_improve action status reports it,
141 *  from the same function, so the Portal and the tool agree (ruled 2026-09-11). */
142export async function handlePortalNamespaces(request: Request, env: Env, now: Date = new Date()): Promise<Response> {
143  const gate = await portalGate(request, env, now, OPS_RETURN_TO);
144  if (!gate.ok) return gate.response;
145  const status = await capsidStatus(env);
146  const body: PortalNamespaces = {
147    generated: now.toISOString(),
148    namespaces: status.namespaces.map((ns) => ({
149      namespace: ns.namespace,
150      breaker: { open: ns.breaker.open, failed: ns.breaker.failed, threshold: ns.breaker.threshold, since: ns.breaker.since, reset_at: ns.breaker.reset_at },
151      latest_report: ns.latest_report ? { integrity: ns.latest_report.integrity, generated: ns.latest_report.generated } : null,
152      jobs: { queued: ns.jobs.queued, claimed: ns.jobs.claimed, blocked: ns.jobs.blocked, done_today: ns.jobs.done_today },
153    })),
154  };
155  return jsonResponse(body);
156}
157
158/** GET /portal/api/activity?namespace=&actor=: the last audit rows, filtered. ?id=:
159 *  that one row, for the Activity drawer. */
160export async function handlePortalActivity(request: Request, env: Env, now: Date = new Date()): Promise<Response> {
161  const gate = await portalGate(request, env, now, OPS_RETURN_TO);
162  if (!gate.ok) return gate.response;
163  const parsed = activityFilterFrom(new URL(request.url));
164  if (!parsed.ok) return textResponse(parsed.refusal, 400);
165  const filter = parsed.filter;
166  const rows = await loadActivity(env.DB, filter);
167  const body: PortalActivity = {
168    generated: now.toISOString(),
169    filter,
170    rows: rows.map((row) => ({ ...row, at: isoTime(row.at) })),
171    limit: ACTIVITY_LIMIT,
172  };
173  return jsonResponse(body);
174}
175
176/** POST /portal/api/sign-out, body {}: expire the session and CSRF cookies in this
177 *  browser. The same checks as an action (the session, Sec-Fetch-Site, the body cap,
178 *  the CSRF pair), so a cross-site page cannot sign the administrator out. It ends the
179 *  Portal session only: the Access session at the team domain is Cloudflare's, so the
180 *  next visit to /portal may sign in again without a prompt. */
181export async function handlePortalSignOut(request: Request, env: Env, now: Date = new Date()): Promise<Response> {
182  const gated = await gateActionRequest(request, env, now);
183  if (!gated.ok) return gated.response;
184  const headers = new Headers({ "Cache-Control": "no-store" });
185  for (const cookie of portalSignOutCookies(portalCookiePath(new URL(request.url)))) headers.append("Set-Cookie", cookie);
186  return new Response(null, { status: 204, headers });
187}
188
189/** Any other path under /portal/api/, any method: behind the gate like every Portal
190 *  route, then a JSON 404, so a typo in the app never reads the app's own page as data. */
191export async function handlePortalApiNotFound(request: Request, env: Env, now: Date = new Date()): Promise<Response> {
192  const gate = await portalGate(request, env, now, OPS_RETURN_TO);
193  if (!gate.ok) return gate.response;
194  const path = new URL(request.url).pathname;
195  return jsonResponse({ error: `no Portal route at ${request.method} ${path}` }, 404);
196}