src/controls-token.ts

Functions

Imports

It imports src/auth.ts, src/controls-base.ts, src/encoding.ts, src/env.ts, src/ops-types/portal.ts. Imported by src/controls.ts.

Source

1import { safeEqual } from "@dustinedwards/site-runtime/compare";
2import { hmacHex } from "./auth";
3import { isPortalAction, UNKNOWN_ACTION } from "./controls-base";
4import { b64urlEncode, b64urlDecode } from "./encoding";
5import type { Env } from "./env";
6import type { PortalAction } from "./ops-types/portal";
7
8// The confirmation token: base64url of the canonical claims, a dot, and the hex
9// HMAC-SHA256 of that base64url text under the derived key.
10interface ConfirmClaims {
11  v: 2;
12  // A one-time id: a perform spends it in KV, so a confirmation is used once, by whichever
13  // surface took it (controls design, D2). Version 1 tokens had none and are retired.
14  jti: string;
15  action: PortalAction;
16  params: Record<string, string>;
17  email: string;
18  exp: number;
19}
20
21// Its own context string, so this key differs from every other key derived from
22// COOKIE_ENCRYPTION_KEY, and a version bump retires every outstanding token.
23const TOKEN_CONTEXT = "capsid-portal-confirm:v2";
24
25const TOKEN_SHAPE = /^[A-Za-z0-9_-]+\.[0-9a-f]{64}$/;
26const JTI_SHAPE = /^[0-9a-f]{32}$/;
27
28function canonical(claims: ConfirmClaims): string {
29  const params: Record<string, string> = {};
30  for (const key of Object.keys(claims.params).sort()) params[key] = claims.params[key];
31  return JSON.stringify({ v: claims.v, jti: claims.jti, action: claims.action, params, email: claims.email, exp: claims.exp });
32}
33
34async function confirmKey(env: Env): Promise<string> {
35  // Fails closed: with no root secret there is nothing to sign with, and an empty key
36  // would sign with a value anybody knows.
37  if (!env.COOKIE_ENCRYPTION_KEY) throw new Error("COOKIE_ENCRYPTION_KEY is unset, so no confirmation can be signed or checked");
38  return hmacHex(env.COOKIE_ENCRYPTION_KEY, TOKEN_CONTEXT);
39}
40
41export async function signConfirm(env: Env, claims: ConfirmClaims): Promise<string> {
42  const payload = b64urlEncode(canonical(claims));
43  return `${payload}.${await hmacHex(await confirmKey(env), payload)}`;
44}
45
46type Verified = { ok: true; claims: ConfirmClaims } | { ok: false; status: number; refusal: string };
47
48export async function verifyConfirm(env: Env, token: string, email: string, now: Date): Promise<Verified> {
49  if (!TOKEN_SHAPE.test(token)) return { ok: false, status: 403, refusal: "the confirmation token is malformed: preview again." };
50  const dot = token.indexOf(".");
51  const payload = token.slice(0, dot);
52  if (!await safeEqual(token.slice(dot + 1), await hmacHex(await confirmKey(env), payload))) {
53    return { ok: false, status: 403, refusal: "the confirmation token does not verify: preview again." };
54  }
55  let claims: ConfirmClaims;
56  try {
57    claims = JSON.parse(b64urlDecode(payload)) as ConfirmClaims;
58  } catch (err) {
59    // Signed by this Worker and unreadable: a defect, said so.
60    return { ok: false, status: 403, refusal: `the confirmation token verifies but does not parse (${err instanceof Error ? err.message : String(err)}): preview again.` };
61  }
62  const paramsOk =
63    claims && typeof claims.params === "object" && claims.params !== null && Object.values(claims.params).every((v) => typeof v === "string");
64  if (claims?.v !== 2 || typeof claims.jti !== "string" || !JTI_SHAPE.test(claims.jti) || typeof claims.email !== "string" || typeof claims.exp !== "number" || !paramsOk) {
65    return { ok: false, status: 403, refusal: "the confirmation token verifies but its claims are not the shape this Worker signs: preview again." };
66  }
67  if (claims.email !== email) return { ok: false, status: 403, refusal: "the confirmation was issued to another session: preview again." };
68  if (claims.exp * 1000 <= now.getTime()) return { ok: false, status: 410, refusal: "the confirmation expired: preview again." };
69  if (!isPortalAction(claims.action)) return { ok: false, status: 400, refusal: UNKNOWN_ACTION(String(claims.action)) };
70  return { ok: true, claims };
71}