src/signed-requests.ts

Functions

Imports

It imports src/auth.ts, src/env.ts, src/offaccount.ts, src/time.ts. Imported by src/access-sync.ts, src/bench.ts, src/dcr.ts, src/ops-hooks.ts, src/ops-otlp.ts, src/portal-actions.ts, src/routes.ts, src/shadow.ts.

Source

1import { hmacHex } from "./auth";
2import { safeEqual } from "@dustinedwards/site-runtime/compare";
3import type { Env } from "./env";
4import { isOffaccountSite, OFFACCOUNT_DEFAULT_SITE, OFFACCOUNT_SITES, OFFACCOUNT_SOURCES, type OffaccountSite } from "./offaccount";
5import { readCapped } from "@dustinedwards/site-runtime/body";
6import { MINUTE_MS } from "./time";
7
8// The signed endpoints that are not MCP: the backup mirror's credential mint here, and
9// the bench's three (src/bench.ts). Each is HMAC over timestamp and body, refused
10// outside a time window and replay-protected by a jti the database claims.
11
12// Signed with a backup-specific key derived under its own context, so the mirror job's
13// key opens read access to backups/json/ on a pinned site's backup bucket
14// (src/offaccount.ts) and nothing else. Not under /ops/: an /ops/ path would invite
15// adding the operator-key check.
16export const BACKUP_CREDENTIAL_PATH = "/backup/credential";
17
18// A signature older than this is refused. It bounds replay to the window in which a
19// request is still plausibly in flight; a CI job that takes over half an hour to POST
20// its own result has a different problem.
21const SIGNATURE_MAX_AGE_MS = 30 * MINUTE_MS;
22
23// A signed request is a few hundred bytes of JSON. This is three orders of magnitude
24// of headroom and still refuses a body that is trying to be something else.
25export const MAX_REPORT_BYTES = 16_384;
26
27// Reads a body from the stream and aborts once it exceeds `max` bytes, so an
28// oversized body is refused before it is fully in memory or reaches the HMAC.
29// request.text() would buffer it all first.
30export async function readBoundedText(
31  request: { body: ReadableStream<Uint8Array> | null },
32  max: number
33): Promise<{ ok: true; text: string } | { ok: false }> {
34  // The family's one capped reader (site-runtime ./body): counted as it arrives, null over the ceiling.
35  const text = await readCapped(request, max);
36  return text === null ? { ok: false } : { ok: true, text };
37}
38
39// Claims a request's nonce, or refuses it. The database decides, not the code. A KV
40// get-then-put has nothing atomic between its round trips, so two requests carrying one
41// captured signature both read absent and both proceed, and with the signature valid 30
42// minutes either side, a captured POST could be replayed for an hour. An INSERT against
43// the primary key has no such window: a returned row means this call claimed the nonce.
44// RETURNING, not meta.changes. Fails closed on a database error, because these endpoints
45// mint credentials and record evidence. The table keeps its first name, improve_jti
46// (migrations/0004), from the improve loop that first used it.
47export async function claimJti(
48  db: D1Database,
49  scope: string,
50  jti: string
51): Promise<{ ok: true } | { ok: false; status: number; refusal: string }> {
52  try {
53    const { results } = await db
54      .prepare(
55        `INSERT INTO improve_jti (scope, jti) VALUES (?1, ?2)
56         ON CONFLICT(scope, jti) DO NOTHING
57         RETURNING jti`
58      )
59      .bind(scope, jti)
60      .all<{ jti: string }>();
61    if (results.length === 1) return { ok: true };
62    return { ok: false, status: 409, refusal: "replay: this signed request (jti) was already accepted" };
63  } catch (err) {
64    return {
65      ok: false,
66      status: 503,
67      refusal: `could not verify replay status (${err instanceof Error ? err.message : String(err)}); refusing the request`,
68    };
69  }
70}
71
72// The backup mirror's key: IMPROVE_SCORE_SECRET, the Worker's one root secret, under
73// the backup's own context string, so it differs from the job and policy signing key
74// (src/signed-docs.ts) by construction. The version segment is in the string so a
75// rotation is a one-character change. scripts/derive-backup-key.mjs computes the same
76// value to set the repo secret.
77export async function deriveBackupCredentialKey(rootSecret: string): Promise<string> {
78  return hmacHex(rootSecret, "capsid-backup-credential:v1");
79}
80
81// Timestamp and body joined by a dot. The timestamp is inside the signature, or an
82// attacker could rewrite it to defeat the age check.
83function signaturePayload(timestamp: string, body: string): string {
84  return `${timestamp}.${body}`;
85}
86
87type HmacFail = { ok: false; status: number; refusal: string };
88
89async function verifyHmac(
90  env: Pick<Env, "IMPROVE_SCORE_SECRET">,
91  signed: { timestamp: string; signature: string; body: string },
92  now: Date,
93  opts: {
94    deriveKey: (root: string) => Promise<string>;
95    missingSecret: string;
96    badSig: string;
97  }
98): Promise<{ ok: true } | HmacFail> {
99  if (!env.IMPROVE_SCORE_SECRET) {
100    return { ok: false, status: 503, refusal: opts.missingSecret };
101  }
102  const at = Date.parse(signed.timestamp);
103  if (Number.isNaN(at)) return { ok: false, status: 400, refusal: "missing or unparseable timestamp header" };
104  const age = now.getTime() - at;
105  // Both directions: a future timestamp is as much a replay handle as a past one. The
106  // tolerance is sized for a few minutes of clock skew.
107  if (age > SIGNATURE_MAX_AGE_MS || age < -SIGNATURE_MAX_AGE_MS) {
108    return { ok: false, status: 401, refusal: `request timestamp is ${Math.round(age / 1000)}s from now, outside the accepted window` };
109  }
110  const key = await opts.deriveKey(env.IMPROVE_SCORE_SECRET);
111  const expected = await hmacHex(key, signaturePayload(signed.timestamp, signed.body));
112  if (!await safeEqual(signed.signature.trim().toLowerCase(), expected)) {
113    return { ok: false, status: 401, refusal: opts.badSig };
114  }
115  return { ok: true };
116}
117
118function parseJsonBody(body: string): { ok: true; parsed: unknown } | { ok: false; refusal: string } {
119  try {
120    return { ok: true, parsed: JSON.parse(body) };
121  } catch {
122    return { ok: false, refusal: "the credential request body is not JSON" };
123  }
124}
125
126function jtiOf(parsed: unknown): { ok: true; jti: string } | { ok: false; refusal: string } {
127  const jti = (parsed as { jti?: unknown } | null)?.jti;
128  if (typeof jti !== "string" || jti.length < 8 || jti.length > 128) {
129    return { ok: false, refusal: "the credential request body must carry a jti of 8 to 128 characters" };
130  }
131  return { ok: true, jti };
132}
133
134// The mirror reads backups within minutes of asking; an hour is generous headroom and
135// far under the API's 7-day ceiling.
136const CREDENTIAL_TTL_SECONDS = 3600;
137
138// Everything the mirror job needs to run `aws s3 sync` with no long-lived repo secret,
139// including the endpoint so the account id lives in no repo either.
140export interface ScopedCredential {
141  access_key_id: string;
142  secret_access_key: string;
143  session_token: string;
144  endpoint: string;
145  bucket: string;
146  prefix: string;
147  expires_in: number;
148}
149
150// The call to the temp-access-credentials API: object-read-only, one hour, one bucket,
151// one prefix, derived from the named parent token. The parent's secret never leaves the
152// dashboard; the Worker holds only its access key id and the mint token.
153async function mintScopedCredential(
154  env: Env,
155  scope: { bucket: string; prefix: string; parentAccessKeyId: string }
156): Promise<{ ok: true; credential: ScopedCredential } | { ok: false; status: number; refusal: string }> {
157  const resp = await fetch(`https://api.cloudflare.com/client/v4/accounts/${env.R2_ACCOUNT_ID}/r2/temp-access-credentials`, {
158    method: "POST",
159    headers: { Authorization: `Bearer ${env.R2_TEMP_CRED_TOKEN}`, "Content-Type": "application/json" },
160    body: JSON.stringify({
161      bucket: scope.bucket,
162      parentAccessKeyId: scope.parentAccessKeyId,
163      permission: "object-read-only",
164      ttlSeconds: CREDENTIAL_TTL_SECONDS,
165      prefixes: [scope.prefix],
166    }),
167  });
168  if (!resp.ok) {
169    return { ok: false, status: 502, refusal: `the temp-access-credentials API answered ${resp.status}: ${(await resp.text()).slice(0, 300)}` };
170  }
171  const data = (await resp.json()) as { result?: { accessKeyId?: string; secretAccessKey?: string; sessionToken?: string } };
172  const minted = data.result;
173  if (!minted?.accessKeyId || !minted.secretAccessKey || !minted.sessionToken) {
174    return { ok: false, status: 502, refusal: "the temp-access-credentials API answered without the three credential fields" };
175  }
176  return {
177    ok: true,
178    credential: {
179      access_key_id: minted.accessKeyId,
180      secret_access_key: minted.secretAccessKey,
181      session_token: minted.sessionToken,
182      endpoint: `https://${env.R2_ACCOUNT_ID}.r2.cloudflarestorage.com`,
183      bucket: scope.bucket,
184      prefix: scope.prefix,
185      expires_in: CREDENTIAL_TTL_SECONDS,
186    },
187  };
188}
189
190const BACKUP_DUMP_PREFIX = "backups/json/";
191
192// Derived from its own parent token. One parent covers every pinned site's bucket; the
193// bucket each mint is scoped to comes from the pinned table, never the caller.
194export async function mintBackupCredential(
195  env: Env,
196  site: OffaccountSite = OFFACCOUNT_DEFAULT_SITE
197): Promise<{ ok: true; credential: ScopedCredential } | { ok: false; status: number; refusal: string }> {
198  if (!env.R2_TEMP_CRED_TOKEN || !env.R2_BACKUP_PARENT_ACCESS_KEY_ID || !env.R2_ACCOUNT_ID) {
199    return {
200      ok: false,
201      status: 503,
202      refusal:
203        "backup credential minting is not configured. Set R2_TEMP_CRED_TOKEN, R2_BACKUP_PARENT_ACCESS_KEY_ID and R2_ACCOUNT_ID with wrangler secret put.",
204    };
205  }
206  return mintScopedCredential(env, {
207    bucket: OFFACCOUNT_SOURCES[site].bucket,
208    prefix: BACKUP_DUMP_PREFIX,
209    parentAccessKeyId: env.R2_BACKUP_PARENT_ACCESS_KEY_ID,
210  });
211}
212
213// A jti and an optional site. The site only picks a row of the pinned table, so an
214// unknown one is refused here, before the jti is spent or anything is minted.
215export function parseBackupCredentialRequest(
216  body: string
217): { ok: true; jti: string; site: OffaccountSite } | { ok: false; refusal: string } {
218  const json = parseJsonBody(body);
219  if (!json.ok) return json;
220  const jti = jtiOf(json.parsed);
221  if (!jti.ok) return jti;
222  const site = (json.parsed as { site?: unknown } | null)?.site;
223  if (site === undefined) return { ok: true, jti: jti.jti, site: OFFACCOUNT_DEFAULT_SITE };
224  if (typeof site !== "string" || !isOffaccountSite(site)) {
225    return { ok: false, refusal: `the credential request names no known site; the sites are ${OFFACCOUNT_SITES.join(", ")}` };
226  }
227  return { ok: true, jti: jti.jti, site };
228}
229
230// Verified in a window both directions, with a timing-safe compare, refusing on anything
231// missing, against the backup-specific key, so this key opens nothing else.
232export async function verifyBackupCredentialRequest(
233  env: Pick<Env, "IMPROVE_SCORE_SECRET">,
234  signed: { timestamp: string; signature: string; body: string },
235  now: Date
236): Promise<{ ok: true } | { ok: false; status: number; refusal: string }> {
237  return verifyHmac(env, signed, now, {
238    deriveKey: deriveBackupCredentialKey,
239    missingSecret: "backup credentials are not configured: IMPROVE_SCORE_SECRET is unset",
240    badSig: "backup credential signature does not verify",
241  });
242}
243
244// The bench endpoints' check, under the same rules as the backup's, against the bench
245// key. The key is its own Worker secret, BENCH_SECRET, not derived from
246// IMPROVE_SCORE_SECRET: the owner set it up without that root to hand (docs/bench.md),
247// so a captured backup request opens nothing here and rotating it touches nothing else.
248export async function verifyBenchRequest(
249  env: Pick<Env, "BENCH_SECRET">,
250  signed: { timestamp: string; signature: string; body: string },
251  now: Date
252): Promise<{ ok: true } | { ok: false; status: number; refusal: string }> {
253  return verifyHmac({ IMPROVE_SCORE_SECRET: env.BENCH_SECRET }, signed, now, {
254    deriveKey: async (key) => key,
255    missingSecret: "bench reporting is not configured: BENCH_SECRET is unset",
256    badSig: "bench request signature does not verify",
257  });
258}