src/site-key.ts

Functions

Imports

It imports src/encoding.ts, src/env.ts, src/log.ts, src/ops-cloudflare.ts, src/ops-sites.ts, src/store-guards.ts. Imported by src/tools/admin.ts.

Source

1import type { Env } from "./env";
2import { CF_API, type FetchLike } from "./ops-cloudflare";
3import { readSiteRow } from "./ops-sites";
4import { auditStatement } from "./store-guards";
5import { b64urlFromBytes } from "./encoding";
6import { logEvent } from "./log";
7
8// SET A SITE KEY (create a site key and set it on both sides, never shown), served as
9// capsid_admin_set_site_key. The site key is the site API's key
10// (DrDustinEdwards/site-api): the site's Worker holds it as CARREL_SITE_KEY, and Carrel
11// holds the same value as SITE_<NAMESPACE>_KEY to call that site. This mints a new one
12// and sets it as a secret on both Workers through the Cloudflare API.
13//
14// THE VALUE IS NEVER SHOWN: not returned, not logged, not in the audit row, not in an
15// error. It exists in this invocation's memory and in the two secrets, and nowhere else.
16//
17// The token is CF_SECRETS_TOKEN, apart from the watcher's read token because it can
18// write: Workers Scripts Edit on the account. Unset, nothing is minted. A step-up (a
19// recent sign-in) is required for an OAuth session (src/scope.ts STEP_UP).
20//
21// ORDER. The site first, then Carrel. When the site takes the new key and Carrel does
22// not, Carrel's calls to the site are refused until the two match; the answer says so
23// and that calling again mints a fresh key and sets both. Nothing is retried silently.
24
25export const CARREL_SCRIPT = "carrel";
26export const SITE_SECRET = "CARREL_SITE_KEY";
27const SCRIPT = /^[A-Za-z0-9_-]{1,63}$/;
28const KEY_BYTES = 32;
29const CF_TIMEOUT_MS = 15_000;
30
31/** Carrel's name for a site's key: SITE_<NAMESPACE>_KEY, upper case, dashes as underscores. */
32export function carrelSecretName(namespace: string): string {
33  return `SITE_${namespace.toUpperCase().replace(/-/g, "_")}_KEY`;
34}
35
36/** A new key: 32 random bytes, base64url, 43 characters (site-api refuses under 32). */
37export function mintSiteKey(): string {
38  return b64urlFromBytes(crypto.getRandomValues(new Uint8Array(KEY_BYTES)));
39}
40
41async function putSecret(fetchImpl: FetchLike, token: string, account: string, script: string, name: string, value: string): Promise<{ ok: true } | { ok: false; error: string }> {
42  let res: Response;
43  try {
44    res = await fetchImpl(`${CF_API}/accounts/${account}/workers/scripts/${script}/secrets`, {
45      method: "PUT",
46      headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", "User-Agent": "capsid (set site key)" },
47      body: JSON.stringify({ name, text: value, type: "secret_text" }),
48      signal: AbortSignal.timeout(CF_TIMEOUT_MS),
49    });
50  } catch (err) {
51    return { ok: false, error: `no answer from Cloudflare: ${(err instanceof Error ? err.message : String(err)).slice(0, 120)}` };
52  }
53  // Only Cloudflare's own error messages are read back, never the request.
54  let messages = "";
55  try {
56    const body = (await res.json()) as { success?: boolean; errors?: Array<{ message?: string }> };
57    if (res.ok && body.success === true) return { ok: true };
58    messages = (body.errors ?? []).map((e) => e.message ?? "").filter(Boolean).join("; ");
59  } catch {
60    messages = "the answer was not JSON";
61  }
62  const hint = res.status === 403 ? " CF_SECRETS_TOKEN needs Workers Scripts Edit on the account." : "";
63  return { ok: false, error: `Cloudflare answered ${res.status}: ${messages || "no error message"}.${hint}` };
64}
65
66export async function setSiteKey(env: Env, actor: string, namespace: string, fetchImpl: FetchLike = fetch) {
67  const token = env.CF_SECRETS_TOKEN?.trim();
68  const account = env.CF_ACCOUNT_ID?.trim() || env.R2_ACCOUNT_ID?.trim();
69  if (!token || !account) {
70    throw new Error(`no key was minted: ${!token ? "CF_SECRETS_TOKEN is not set" : "neither CF_ACCOUNT_ID nor R2_ACCOUNT_ID is set"}. The seat sets CF_SECRETS_TOKEN, a token with Workers Scripts Edit (docs/portal.md, "Site keys").`);
71  }
72  const row = await readSiteRow(env.DB, namespace);
73  if (!row || row.platform !== "cloudflare" || !row.script || !SCRIPT.test(row.script)) {
74    throw new Error(`no key was minted: ${namespace}'s site row names no Cloudflare Worker script, so there is no site Worker to set it on.`);
75  }
76  const siteScript = row.script;
77  const carrelSecret = carrelSecretName(namespace);
78
79  const key = mintSiteKey();
80  const site = await putSecret(fetchImpl, token, account, siteScript, SITE_SECRET, key);
81  const carrel = site.ok ? await putSecret(fetchImpl, token, account, CARREL_SCRIPT, carrelSecret, key) : null;
82  const result = {
83    namespace,
84    site: { script: siteScript, secret: SITE_SECRET, set: site.ok, ...(site.ok ? {} : { error: site.error }) },
85    carrel: carrel
86      ? { script: CARREL_SCRIPT, secret: carrelSecret, set: carrel.ok, ...(carrel.ok ? {} : { error: carrel.error }) }
87      : { script: CARREL_SCRIPT, secret: carrelSecret, set: false, error: "not attempted: the site Worker did not take the key, so Carrel keeps the key the site still holds" },
88  };
89  const matched = site.ok && carrel?.ok === true;
90  // The record of the change, never the value.
91  try {
92    await auditStatement(env.DB, actor, "set_site_key", namespace, null, result).run();
93  } catch (err) {
94    logEvent("error", "AUDIT_INSERT_FAILED", { message: `AUDIT_INSERT_FAILED set_site_key ${namespace}: ${err instanceof Error ? err.message : String(err)}` });
95  }
96  return {
97    ...result,
98    matched,
99    note: matched
100      ? "A new key was minted and set on both Workers. Its value is not shown anywhere. Each Worker serves it from its next request."
101      : site.ok
102        ? "THE TWO SIDES DIFFER: the site Worker holds the new key and Carrel does not, so Carrel's calls to the site are refused until they match. Call again: it mints a fresh key and sets both."
103        : "Nothing changed: the site Worker did not take the key, and Carrel was not touched.",
104  };
105}