src/job-signing.ts

Functions

Imports

It imports src/auth.ts, src/signed-docs.ts. Imported by src/jobs-holder.ts, src/jobs-mirror.ts, src/jobs-seat.ts, src/jobs.ts, src/ops-feed.ts.

Source

1import { hmacHex } from "./auth";
2import { safeEqual } from "@dustinedwards/site-runtime/compare";
3import { deriveTaskKey } from "./signed-docs";
4
5// Signed resume notes and block commands (job_9e602b31888f item 4, OWASP ASI07).
6//
7// A job body is signed at post and verified at claim, but what a job carries after that
8// was plain text: the approval a resume hands the driver, and the command a block asks a
9// person to run. Both now carry an HMAC under the same key as a job body, bound to the
10// job id and to what kind of text it is, so a note cannot be moved to another job and a
11// summary cannot pass as a note.
12//
13// Text written before this was signed carries no signature. It is reported as
14// "legacy-unsigned", never as verified: re-signing it now would put today's key on
15// whatever it holds today, which is exactly what a signature must not vouch for.
16
17export type JobTextKind = "resume-note" | "summary";
18
19export type SignatureCheck =
20  // The signature matches the text and the job.
21  | "verified"
22  // Written before signing existed, or by a writer that does not sign: shown, labelled.
23  | "legacy-unsigned"
24  // A signature is present and does not match: the text or the signature was changed.
25  | "mismatch"
26  // IMPROVE_SCORE_SECRET is unset, so nothing can be checked.
27  | "unconfigured";
28
29function payload(kind: JobTextKind, jobId: string, fields: Record<string, string | null>): string {
30  // Keys in a fixed order, so the same fields always produce the same bytes.
31  const ordered = Object.fromEntries(Object.keys(fields).sort().map((k) => [k, fields[k]]));
32  return `capsid-job-${kind}:v1\n${jobId}\n${JSON.stringify(ordered)}`;
33}
34
35export async function signJobText(
36  rootSecret: string | undefined,
37  kind: JobTextKind,
38  jobId: string,
39  fields: Record<string, string | null>
40): Promise<string | null> {
41  if (!rootSecret) return null;
42  return hmacHex(await deriveTaskKey(rootSecret), payload(kind, jobId, fields));
43}
44
45export async function checkJobText(
46  rootSecret: string | undefined,
47  kind: JobTextKind,
48  jobId: string,
49  fields: Record<string, string | null>,
50  signature: string | null | undefined
51): Promise<SignatureCheck> {
52  if (!signature) return "legacy-unsigned";
53  if (!rootSecret) return "unconfigured";
54  const expected = await hmacHex(await deriveTaskKey(rootSecret), payload(kind, jobId, fields));
55  return await safeEqual(signature.toLowerCase(), expected) ? "verified" : "mismatch";
56}