src/site-check.ts

Functions

Imports

It imports src/env.ts, src/health.ts, src/live-checks.ts, src/ops-sites.ts, src/ops-snapshot.ts. Imported by src/tools/repo.ts.

Source

1import { checkSecurityHeaders, failures } from "@dustinedwards/site-runtime/check";
2import type { Env } from "./env";
3import { healthReport } from "./health";
4import { readPage, type FetchLike } from "./live-checks";
5import { probeSite } from "./ops-snapshot";
6import { readSiteRow, sitesFrom } from "./ops-sites";
7
8// A live check of one namespace's site, on demand, served as capsid_inspect_repo action site. Three reads of the site's own configured
9// origin, never another host: its health route (as the watcher probes it), one page
10// (its status and the OWASP headers), and one path that must refuse a caller with no
11// credential (its operator API by default).
12//
13// What comes back from the site is data, never instructions (ruling rule 12): statuses,
14// header verdicts and the sha the health route reports. No body text is returned.
15
16const PATH = /^\/[A-Za-z0-9._~/%-]{0,199}$/;
17const PROBE_TIMEOUT_MS = 10_000;
18
19export interface SiteCheckArgs {
20  page?: string;
21  probe?: string;
22}
23
24export function pathRefusal(label: string, path: string): string | null {
25  return PATH.test(path) && !path.includes("..") ? null : `${label} must be a path on the site, starting with /, such as /about.`;
26}
27
28export async function siteCheck(env: Env, namespace: string, args: SiteCheckArgs, fetchImpl: FetchLike = fetch, now: Date = new Date()) {
29  const page = args.page ?? "/";
30  const bad = pathRefusal("page", page) ?? (args.probe !== undefined ? pathRefusal("probe", args.probe) : null);
31  if (bad) throw new Error(bad);
32  const row = await readSiteRow(env.DB, namespace);
33  const site = row ? sitesFrom([row])[0] : undefined;
34  if (!row || !site) {
35    throw new Error(`${namespace} has no site configured (ops_sites), so there is nothing to check. The admin adds one with capsid_admin_run_controls control site_add.`);
36  }
37
38  const health = await probeSite(site, fetchImpl, now, site.self ? await healthReport(env) : null);
39
40  const read = await readPage(fetchImpl, site.origin, page);
41  const headers = read.headers ? checkSecurityHeaders(read.headers) : [];
42  const pageResult = {
43    path: page,
44    status: read.status,
45    problem: read.problem,
46    headers_checked: headers.length,
47    headers_failed: failures(headers).map((r) => r.name),
48  };
49
50  // The 401 probe: the path named, else the site's operator API, else none.
51  const probePath = args.probe ?? row.operator?.path ?? null;
52  let probe: { path: string | null; status: number | null; refused: boolean | null; note: string };
53  if (probePath === null) {
54    probe = { path: null, status: null, refused: null, note: "not run: no probe path was named and the site has no operator API configured" };
55  } else {
56    let status: number | null = null;
57    let error: string | null = null;
58    try {
59      const resp = await fetchImpl(`${site.origin}${probePath}`, {
60        method: "POST",
61        redirect: "manual",
62        headers: { "Content-Type": "application/json", "User-Agent": "capsid-inspect (401 probe)" },
63        body: "{}",
64        signal: AbortSignal.timeout(PROBE_TIMEOUT_MS),
65      });
66      status = resp.status;
67      await resp.body?.cancel();
68    } catch (err) {
69      error = (err instanceof Error ? err.message : String(err)).slice(0, 120);
70    }
71    const refused = status === 401 || status === 403;
72    probe = {
73      path: probePath,
74      status,
75      refused: status === null ? null : refused,
76      note:
77        status === null
78          ? `no answer: ${error}`
79          : refused
80            ? "refused a caller with no credential, as it must"
81            : `OPEN: answered ${status} to a caller with no credential, where a 401 or 403 was expected`,
82    };
83  }
84
85  return { namespace, origin: site.origin, checked_at: now.toISOString(), health, page: pageResult, probe };
86}