src/web-push.ts

Functions

Imports

It imports no other module of this repo. Imported by src/push.ts.

Source

1// WEB PUSH, SENT FROM THE WORKER (docs/design/design-merge-pipeline.md section 5, PR 7;
2// Dustin's DECIDE 5 of 2026-10-09: Web Push, because his phone is Android). Nothing here
3// knows what is being said or why: src/push.ts decides that. This module encrypts one
4// payload for one browser subscription (RFC 8291, aes128gcm) and signs the request to its
5// push service with the VAPID key (RFC 8292), with WebCrypto only, so no third party and
6// no dependency is added.
7//
8// The VAPID key is one secret, VAPID_PRIVATE_KEY: a P-256 private key as a JWK (its x and
9// y are the public half, which the Portal hands the browser when it subscribes).
10// scripts/vapid-keys.mjs makes one and puts it with wrangler without printing it.
11
12export interface PushSubscriptionKeys {
13  endpoint: string;
14  p256dh: string;
15  auth: string;
16}
17
18export interface VapidKey {
19  jwk: JsonWebKey;
20  /** The public key, 65 bytes uncompressed, base64url: what the browser subscribes with. */
21  publicKey: string;
22}
23
24const RECORD_SIZE = 4096;
25const TTL_SECONDS = 24 * 60 * 60;
26const JWT_LIFETIME_SECONDS = 12 * 60 * 60;
27
28// The push services a subscription may name. The Worker POSTs to the endpoint the browser
29// gave, so an endpoint anywhere else is refused before it is stored: a stored endpoint is
30// a URL the Worker will call every time something is urgent.
31const PUSH_HOSTS: readonly RegExp[] = [
32  /^fcm\.googleapis\.com$/,
33  /^updates\.push\.services\.mozilla\.com$/,
34  /^web\.push\.apple\.com$/,
35  /^[a-z0-9-]+\.push\.apple\.com$/,
36  /^[a-z0-9-]+\.notify\.windows\.com$/,
37];
38
39export function b64url(bytes: Uint8Array): string {
40  let s = "";
41  for (const b of bytes) s += String.fromCharCode(b);
42  return btoa(s).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
43}
44
45export function fromB64url(text: string): Uint8Array {
46  const b64 = text.replace(/-/g, "+").replace(/_/g, "/");
47  const bin = atob(b64 + "=".repeat((4 - (b64.length % 4)) % 4));
48  const out = new Uint8Array(bin.length);
49  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
50  return out;
51}
52
53function concat(...parts: Uint8Array[]): Uint8Array {
54  const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
55  let at = 0;
56  for (const p of parts) {
57    out.set(p, at);
58    at += p.length;
59  }
60  return out;
61}
62
63const utf8 = (s: string) => new TextEncoder().encode(s);
64
65/** Why a subscription cannot be stored, or null. Checked at subscribe time, before any
66 *  row is written, and again before each send. */
67export function subscriptionProblem(sub: Partial<PushSubscriptionKeys>): string | null {
68  if (typeof sub.endpoint !== "string" || sub.endpoint.length > 1024) return "the subscription has no endpoint.";
69  let url: URL;
70  try {
71    url = new URL(sub.endpoint);
72  } catch {
73    return "the subscription's endpoint is not a URL.";
74  }
75  if (url.protocol !== "https:") return "the subscription's endpoint is not https.";
76  if (!PUSH_HOSTS.some((h) => h.test(url.hostname))) return `the subscription's endpoint is on ${url.hostname}, which is not a known push service.`;
77  try {
78    if (typeof sub.p256dh !== "string" || fromB64url(sub.p256dh).length !== 65) return "the subscription's p256dh key is not a 65-byte P-256 point.";
79    if (typeof sub.auth !== "string" || fromB64url(sub.auth).length !== 16) return "the subscription's auth secret is not 16 bytes.";
80  } catch {
81    return "the subscription's keys are not base64url.";
82  }
83  return null;
84}
85
86/** The VAPID key from its secret, or why it cannot be used. */
87export function readVapidKey(secret: string | undefined): VapidKey | string {
88  if (!secret) return "VAPID_PRIVATE_KEY is not set, so no push can be signed (docs/portal.md, \"Phone alerts\").";
89  let jwk: JsonWebKey;
90  try {
91    jwk = JSON.parse(secret) as JsonWebKey;
92  } catch {
93    return "VAPID_PRIVATE_KEY is not JSON: it must be a P-256 private key as a JWK.";
94  }
95  if (jwk.kty !== "EC" || jwk.crv !== "P-256" || !jwk.d || !jwk.x || !jwk.y) return "VAPID_PRIVATE_KEY is not a P-256 private key as a JWK (kty EC, crv P-256, d, x and y).";
96  const point = concat(new Uint8Array([4]), fromB64url(jwk.x), fromB64url(jwk.y));
97  if (point.length !== 65) return "VAPID_PRIVATE_KEY's x and y are not 32 bytes each.";
98  return { jwk: { kty: "EC", crv: "P-256", d: jwk.d, x: jwk.x, y: jwk.y }, publicKey: b64url(point) };
99}
100
101async function hkdf(salt: Uint8Array, ikm: Uint8Array, info: Uint8Array, bytes: number): Promise<Uint8Array> {
102  const key = await crypto.subtle.importKey("raw", ikm, "HKDF", false, ["deriveBits"]);
103  return new Uint8Array(await crypto.subtle.deriveBits({ name: "HKDF", hash: "SHA-256", salt, info }, key, bytes * 8));
104}
105
106/** The sender's half of one message: a fresh ECDH key pair and salt, or fixed ones in a
107 *  test that checks RFC 8291's worked example. */
108export interface Ephemeral {
109  privateJwk?: JsonWebKey;
110  salt?: Uint8Array;
111}
112
113/** RFC 8291: the aes128gcm body for one subscription, a single record. */
114export async function encryptPayload(sub: PushSubscriptionKeys, plaintext: Uint8Array, fixed: Ephemeral = {}): Promise<Uint8Array> {
115  const uaPublic = fromB64url(sub.p256dh);
116  const authSecret = fromB64url(sub.auth);
117  const ecdh = { name: "ECDH", namedCurve: "P-256" } as const;
118  let asPrivate: CryptoKey;
119  let asPublic: Uint8Array;
120  if (fixed.privateJwk) {
121    asPrivate = await crypto.subtle.importKey("jwk", fixed.privateJwk, ecdh, false, ["deriveBits"]);
122    asPublic = concat(new Uint8Array([4]), fromB64url(fixed.privateJwk.x!), fromB64url(fixed.privateJwk.y!));
123  } else {
124    const pair = (await crypto.subtle.generateKey(ecdh, true, ["deriveBits"])) as CryptoKeyPair;
125    asPrivate = pair.privateKey;
126    asPublic = new Uint8Array((await crypto.subtle.exportKey("raw", pair.publicKey)) as ArrayBuffer);
127  }
128  const uaKey = await crypto.subtle.importKey("raw", uaPublic, ecdh, false, []);
129  // The standard member is `public`; workers-types spells it `$public` only because the
130  // word is reserved in its generator, and workerd reads `public`.
131  const derive = { name: "ECDH", public: uaKey } as unknown as SubtleCryptoDeriveKeyAlgorithm;
132  const shared = new Uint8Array(await crypto.subtle.deriveBits(derive, asPrivate, 256));
133  const ikm = await hkdf(authSecret, shared, concat(utf8("WebPush: info\0"), uaPublic, asPublic), 32);
134  const salt = fixed.salt ?? crypto.getRandomValues(new Uint8Array(16));
135  const cek = await hkdf(salt, ikm, utf8("Content-Encoding: aes128gcm\0"), 16);
136  const nonce = await hkdf(salt, ikm, utf8("Content-Encoding: nonce\0"), 12);
137  // One record, so the delimiter is 2 (the last record) and no padding follows it.
138  if (plaintext.length + 1 + 16 > RECORD_SIZE) throw new Error(`a push payload of ${plaintext.length} bytes does not fit one ${RECORD_SIZE}-byte record`);
139  const key = await crypto.subtle.importKey("raw", cek, "AES-GCM", false, ["encrypt"]);
140  const sealed = new Uint8Array(await crypto.subtle.encrypt({ name: "AES-GCM", iv: nonce }, key, concat(plaintext, new Uint8Array([2]))));
141  const header = new Uint8Array(16 + 4 + 1);
142  header.set(salt, 0);
143  new DataView(header.buffer).setUint32(16, RECORD_SIZE);
144  header[20] = asPublic.length;
145  return concat(header, asPublic, sealed);
146}
147
148/** RFC 8292: the Authorization header's JWT for one push service origin. */
149export async function vapidJwt(vapid: VapidKey, audience: string, subject: string, now: Date): Promise<string> {
150  const header = b64url(utf8(JSON.stringify({ typ: "JWT", alg: "ES256" })));
151  const claims = b64url(utf8(JSON.stringify({ aud: audience, exp: Math.floor(now.getTime() / 1000) + JWT_LIFETIME_SECONDS, sub: subject })));
152  const key = await crypto.subtle.importKey("jwk", vapid.jwk, { name: "ECDSA", namedCurve: "P-256" }, false, ["sign"]);
153  // WebCrypto's ECDSA signature is r || s, which is JWS's ES256 form already.
154  const sig = new Uint8Array(await crypto.subtle.sign({ name: "ECDSA", hash: "SHA-256" }, key, utf8(`${header}.${claims}`)));
155  return `${header}.${claims}.${b64url(sig)}`;
156}
157
158export interface PushSent {
159  status: number;
160  /** The push service says the subscription is gone (404 or 410): stop sending to it. */
161  gone: boolean;
162}
163
164/** Encrypt and send one payload to one subscription. Never throws on a push service's
165 *  answer; a network error is returned as status 0. */
166export async function sendPush(
167  vapid: VapidKey,
168  subject: string,
169  sub: PushSubscriptionKeys,
170  payload: unknown,
171  now: Date,
172  fetcher: typeof fetch = fetch
173): Promise<PushSent> {
174  const problem = subscriptionProblem(sub);
175  if (problem) return { status: 0, gone: true };
176  const body = await encryptPayload(sub, utf8(JSON.stringify(payload)));
177  const jwt = await vapidJwt(vapid, new URL(sub.endpoint).origin, subject, now);
178  try {
179    const res = await fetcher(sub.endpoint, {
180      method: "POST",
181      headers: {
182        Authorization: `vapid t=${jwt}, k=${vapid.publicKey}`,
183        "Content-Encoding": "aes128gcm",
184        "Content-Type": "application/octet-stream",
185        TTL: String(TTL_SECONDS),
186        Urgency: "high",
187      },
188      body,
189    });
190    await res.body?.cancel();
191    return { status: res.status, gone: res.status === 404 || res.status === 410 };
192  } catch {
193    return { status: 0, gone: false };
194  }
195}