src/operator-key.ts

Functions

Imports

It imports src/auth.ts, src/doc-statements.ts, src/encoding.ts, src/env.ts. Imported by src/tools/status.ts.

Source

1import { sha256Hex } from "./auth";
2import { bytesToHex } from "./encoding";
3import type { Env } from "./env";
4import { systemAudit } from "./doc-statements";
5
6export interface MintedOperatorKey {
7  action: "mint_operator_key";
8  key: string;
9  hash: string;
10  // The OPERATOR_KEY_HASH line, `ro:<hash>`. The tier lives on the entry, so it is
11  // the operator's decision.
12  entry: string;
13  grant: "read-only";
14  already_listed: boolean;
15  next_step: string;
16  command: string;
17  warning: string;
18}
19
20// capsid_admin_control_improve action mint_operator_key. Mints a read-only operator key
21// and prints the command that installs its hash. It does not install it: a Worker that
22// can widen its own authorization list does not have one. The key is returned once and
23// stored nowhere, not even the hash in the audit row, because OPERATOR_KEY_HASH is the
24// verifier; the row gets a fingerprint.
25export async function mintOperatorKey(env: Env, actor: string): Promise<MintedOperatorKey> {
26  const bytes = new Uint8Array(32);
27  crypto.getRandomValues(bytes);
28  // Hex through bytesToHex (src/encoding.ts).
29  const key = `capsid_${bytesToHex(bytes)}`;
30  // The `ro:` prefix goes on the list entry, not the key: src/auth.ts compares the
31  // key's hash to each entry with the prefix stripped. Backwards, this mints a write key.
32  const hash = await sha256Hex(key);
33  const entry = `ro:${hash}`;
34  const existing = (env.OPERATOR_KEY_HASH ?? "").split(",").map((h) => h.trim()).filter(Boolean);
35  const alreadyListed = existing.includes(entry);
36  const next = alreadyListed ? existing : [...existing, entry];
37  await env.DB.batch([
38    systemAudit(env.DB, "operator-key-minted", null, {
39      // Tells two mints apart without being usable as a verifier.
40      fingerprint: hash.slice(0, 8),
41      grant: "read-only",
42    }, actor),
43  ]);
44  return {
45    action: "mint_operator_key",
46    key,
47    hash,
48    entry,
49    grant: "read-only",
50    already_listed: alreadyListed,
51    next_step:
52      "This key does NOTHING until its hash is in OPERATOR_KEY_HASH. Run the command below from a machine with wrangler and this account. The Worker deliberately cannot do it: a Worker that can widen its own authorization list does not have one.",
53    command: `npx wrangler secret put OPERATOR_KEY_HASH
54# then paste, on one line:
55${next.join(",")}`,
56    warning:
57      "The key is shown ONCE and is stored nowhere: not in KV, not in a document, and not in the audit row. Copy it now. Lose it and mint another, then remove the stale hash from the list above. Revoke by removing a hash and putting the secret again.",
58  };
59}