/** * Web Push: the encryption against the standard's own worked example, the signed token, the routes, and a message all the way to a stand-in push * service and back out through a stand-in browser. * * Run with: npm test --workspace server */ import { test, describe, before, after } from "node:test"; import assert from "node:assert/strict"; import { createDecipheriv, createECDH, createPublicKey, hkdfSync, verify } from "node:crypto"; import { createServer, type IncomingMessage, type Server } from "node:http"; import { mkdtempSync, rmSync } from "node:fs"; import { tmpdir } from "node:os"; import { join } from "node:path"; import type { AddressInfo } from "node:net"; const dir = mkdtempSync(join(tmpdir(), "hm-push-")); process.env.DATABASE_PATH = join(dir, "test.sqlite"); process.env.SESSION_DIR = join(dir, "sessions"); process.env.CREDENTIALS_ENCRYPTION_KEY = "ab".repeat(32); process.env.HEALTH_STARTUP_GRACE_MS = "0"; const express = (await import("express")).default; const { db } = await import("../src/db/client.js"); const { users, pushSubscriptions, auditLog } = await import("../src/db/schema.js"); const { runMigrations } = await import("../src/db/migrate.js"); const { encryptPayload, vapidAuthorization, getVapidKeys, checkEndpoint, allowLocalPushEndpointsForTests, sendPush } = await import("../src/services/webPush.js"); const { updateSettings } = await import("../src/services/settingsStore.js"); const { notifyNow, enabledChannelCount } = await import("../src/services/notify.js"); const { pushRouter } = await import("../src/routes/push.js"); const { eq } = await import("drizzle-orm"); await runMigrations(); const b64u = (s: string) => Buffer.from(s, "base64url"); /** What a browser does with a push it receives (RFC 8291 §3.4), to read what we wrote. */ function decrypt(body: Buffer, uaPrivate: Buffer, uaPublic: Buffer, authSecret: Buffer): Buffer { const salt = body.subarray(0, 16); const idlen = body[20]; const asPublic = body.subarray(21, 21 + idlen); const ciphertext = body.subarray(21 + idlen); const ecdh = createECDH("prime256v1"); ecdh.setPrivateKey(uaPrivate); const secret = ecdh.computeSecret(asPublic); const ikm = Buffer.from(hkdfSync("sha256", secret, authSecret, Buffer.concat([Buffer.from("WebPush: info\0"), uaPublic, asPublic]), 32)); const cek = Buffer.from(hkdfSync("sha256", ikm, salt, Buffer.from("Content-Encoding: aes128gcm\0"), 16)); const nonce = Buffer.from(hkdfSync("sha256", ikm, salt, Buffer.from("Content-Encoding: nonce\0"), 12)); const d = createDecipheriv("aes-128-gcm", cek, nonce); d.setAuthTag(ciphertext.subarray(ciphertext.length - 16)); const plain = Buffer.concat([d.update(ciphertext.subarray(0, ciphertext.length - 16)), d.final()]); assert.equal(plain[plain.length - 1], 2, "ends with the last-record marker"); return plain.subarray(0, plain.length - 1); } /** A stand-in browser: its keys, in the shape a subscription carries them. */ function browser() { const ecdh = createECDH("prime256v1"); ecdh.generateKeys(); const auth = Buffer.from(Array.from({ length: 16 }, (_, i) => i * 7 + 3)); return { ecdh, priv: ecdh.getPrivateKey(), pub: ecdh.getPublicKey(), auth, keys: { p256dh: ecdh.getPublicKey().toString("base64url"), auth: auth.toString("base64url") } }; } describe("the encryption", () => { test("it reproduces the worked example in RFC 8291, byte for byte", () => { const asPrivate = b64u("yfWPiYE-n46HLnH0KqZOF1fJJU3MYrct3AELtAQ-oRw"); const ephemeral = createECDH("prime256v1"); ephemeral.setPrivateKey(asPrivate); assert.equal(ephemeral.getPublicKey().toString("base64url"), "BP4z9KsN6nGRTbVYI_c7VJSPQTBtkgcy27mlmlMoZIIgDll6e3vCYLocInmYWAmS6TlzAC8wEqKK6PBru3jl7A8"); const body = encryptPayload( Buffer.from("When I grow up, I want to be a watermelon"), { p256dh: "BCVxsr7N_eNgVRqvHtD0zTZsEc6-VV-JvLexhqUzORcxaOzi6-AYWXvTBHm4bjyPjs7Vd8pZGH6SRpkNtoIAiw4", auth: "BTBZMqHH6r4Tts7J_aSIgg" }, { ephemeral, salt: b64u("DGv6ra1nlYgDCS1FRnbzlw") }, ); assert.equal( body.toString("base64url"), "DGv6ra1nlYgDCS1FRnbzlwAAEABBBP4z9KsN6nGRTbVYI_c7VJSPQTBtkgcy27mlmlMoZIIgDll6e3vCYLocInmYWAmS6TlzAC8wEqKK6PBru3jl7A_yl95bQpu6cVPTpK4Mqgkf1CXztLVBSt2Ks3oZwbuwXPXLWyouBWLVWGNWQexSgSxsj_Qulcy4a-fN", ); }); test("the browser it is for can read it, and it is different every time", () => { const b = browser(); const one = encryptPayload(Buffer.from("hello"), b.keys); const two = encryptPayload(Buffer.from("hello"), b.keys); assert.notDeepEqual(one, two, "a fresh key and salt each time"); assert.equal(decrypt(one, b.priv, b.pub, b.auth).toString(), "hello"); const other = browser(); assert.throws(() => decrypt(one, other.priv, other.pub, other.auth), "someone else's browser can't"); }); test("keys that aren't a browser's, or a message too long for one push, are refused", () => { const b = browser(); assert.throws(() => encryptPayload(Buffer.from("x"), { p256dh: "AAAA", auth: b.keys.auth }), /P-256/); assert.throws(() => encryptPayload(Buffer.from("x"), { p256dh: b.keys.p256dh, auth: "AAAA" }), /16 bytes/); assert.throws(() => encryptPayload(Buffer.alloc(4100), b.keys), /too long/); }); }); describe("the signed token", () => { test("it names who it is for, who sent it and when it ends, and the signature checks out against the public key", async () => { const keys = await getVapidKeys(); const header = vapidAuthorization("https://push.example", "mailto:me@example.com", keys, 1_700_000_000_000); const m = /^vapid t=([\w-]+)\.([\w-]+)\.([\w-]+), k=([\w-]+)$/.exec(header)!; assert.ok(m, header); assert.equal(m[4], keys.publicKey); assert.deepEqual(JSON.parse(Buffer.from(m[1], "base64url").toString()), { typ: "JWT", alg: "ES256" }); assert.deepEqual(JSON.parse(Buffer.from(m[2], "base64url").toString()), { aud: "https://push.example", exp: 1_700_000_000 + 12 * 3600, sub: "mailto:me@example.com" }); const pub = b64u(keys.publicKey); const key = createPublicKey({ key: { kty: "EC", crv: "P-256", x: pub.subarray(1, 33).toString("base64url"), y: pub.subarray(33, 65).toString("base64url") }, format: "jwk" }); assert.equal(verify("sha256", Buffer.from(`${m[1]}.${m[2]}`), { key, dsaEncoding: "ieee-p1363" }, b64u(m[3])), true); assert.equal(b64u(m[3]).length, 64, "the signature is the plain r and s, as JWT wants"); }); test("the server's key pair is kept: the same one comes back", async () => { const a = await getVapidKeys(); const b = await getVapidKeys(); assert.deepEqual(a, b); assert.equal(b64u(a.publicKey).length, 65); assert.equal(b64u(a.privateKey).length, 32); }); }); describe("which addresses are push services", () => { test("https only, no login, and never an address on a private network", async () => { await assert.rejects(checkEndpoint("http://fcm.googleapis.com/x"), /https/); await assert.rejects(checkEndpoint("https://user:pw@fcm.googleapis.com/x"), /login/); await assert.rejects(checkEndpoint("not a url"), /web address/); await assert.rejects(checkEndpoint("https://127.0.0.1/x")); await assert.rejects(checkEndpoint("https://192.168.1.10/x")); await assert.rejects(checkEndpoint("https://169.254.169.254/latest")); await assert.rejects(checkEndpoint("https://localhost/x")); }); }); describe("through the routes, the channel and a push service", () => { let app: Server; let base = ""; let who = "ada"; let pushService: Server; let pushBase = ""; const received: { path: string; headers: IncomingMessage["headers"]; body: Buffer }[] = []; let respondWith = 201; let ada = 0; before(async () => { allowLocalPushEndpointsForTests(true); const made = await db .insert(users) .values([ { oidcSub: "ada", name: "Ada", role: "admin" }, { oidcSub: "vic", name: "Vic", role: "viewer" }, ]) .returning({ id: users.id }); ada = made[0].id; pushService = createServer((req, res) => { const chunks: Buffer[] = []; req.on("data", (c) => chunks.push(c)); req.on("end", () => { received.push({ path: req.url ?? "", headers: req.headers, body: Buffer.concat(chunks) }); res.statusCode = respondWith; res.end(); }); }); await new Promise((r) => pushService.listen(0, "127.0.0.1", r)); pushBase = `http://127.0.0.1:${(pushService.address() as AddressInfo).port}`; const a = express(); a.use(express.json()); a.use((req, _res, next) => { (req as unknown as { session: unknown }).session = { user: { sub: who } }; next(); }); a.use("/api/push", pushRouter); app = await new Promise((resolve) => { const s = a.listen(0, "127.0.0.1", () => resolve(s)); }); base = `http://127.0.0.1:${(app.address() as AddressInfo).port}/api/push`; }); after(() => { allowLocalPushEndpointsForTests(false); app.close(); pushService.close(); try { rmSync(dir, { recursive: true, force: true }); } catch { // Windows keeps the database file locked until the process exits. } }); const send = (method: string, path: string, body?: unknown) => fetch(`${base}${path}`, { method, headers: { "content-type": "application/json" }, body: body === undefined ? undefined : JSON.stringify(body) }); const mine = browser(); const vics = browser(); let adaSubId = 0; test("while push is off nobody can subscribe, and there is no key to subscribe with", async () => { assert.equal((await send("GET", "/key")).status, 409); assert.equal((await send("POST", "/subscribe", { endpoint: `${pushBase}/a`, keys: mine.keys })).status, 409); assert.equal(await enabledChannelCount(), 0); }); test("with it on, a browser gets the key and subscribes; the same browser again is the same subscription", async () => { await updateSettings({ webPush: { enabled: true, contact: "me@example.com" } }); const key = await (await send("GET", "/key")).json(); assert.equal(key.publicKey, (await getVapidKeys()).publicKey); const res = await send("POST", "/subscribe", { endpoint: `${pushBase}/ada-phone`, keys: mine.keys, label: "Ada's phone" }); assert.equal(res.status, 201); adaSubId = (await res.json()).id; assert.equal((await send("POST", "/subscribe", { endpoint: `${pushBase}/ada-phone`, keys: mine.keys, label: "Ada's phone" })).status, 201); assert.equal((await db.select().from(pushSubscriptions)).length, 1); const list = await (await send("GET", "/mine")).json(); assert.equal(list.subscriptions.length, 1); assert.equal(list.subscriptions[0].label, "Ada's phone"); assert.equal((await db.select().from(auditLog)).filter((e) => e.category === "push" && e.action === "subscribe").length, 1, "only the first time"); }); test("a subscription that isn't one is refused", async () => { assert.equal((await send("POST", "/subscribe", { endpoint: "nonsense", keys: mine.keys })).status, 400); assert.equal((await send("POST", "/subscribe", { endpoint: `${pushBase}/x`, keys: { p256dh: "short", auth: "short" } })).status, 400); allowLocalPushEndpointsForTests(false); const refused = await send("POST", "/subscribe", { endpoint: "https://10.0.0.5/push", keys: mine.keys }); allowLocalPushEndpointsForTests(true); assert.equal(refused.status, 400, "a private address is never a push service"); }); test("a message through the channels is encrypted for the browser, signed, and addressed to the push service", async () => { received.length = 0; assert.equal(await enabledChannelCount(), 1, "push counts as a channel once someone is subscribed"); await notifyNow("Server down", "elsa has not reported for 3 hours"); assert.equal(received.length, 1); const r = received[0]; assert.equal(r.path, "/ada-phone"); assert.equal(r.headers["content-encoding"], "aes128gcm"); assert.equal(r.headers.ttl, "86400"); assert.match(String(r.headers.authorization), /^vapid t=[\w-]+\.[\w-]+\.[\w-]+, k=[\w-]+$/); const claims = JSON.parse(Buffer.from(String(r.headers.authorization).split(".")[1], "base64url").toString()); assert.equal(claims.aud, pushBase); assert.equal(claims.sub, "mailto:me@example.com"); const message = JSON.parse(decrypt(r.body, mine.priv, mine.pub, mine.auth).toString()); assert.deepEqual(message, { title: "Server down", body: "elsa has not reported for 3 hours", url: "/alerts" }); assert.notEqual((await db.select().from(pushSubscriptions))[0].lastSuccessAt, null); }); test("with push switched off nothing is sent", async () => { await updateSettings({ webPush: { enabled: false } }); received.length = 0; await notifyNow("Server down", "x"); assert.equal(received.length, 0); await updateSettings({ webPush: { enabled: true } }); }); test("a push service that says the browser is gone has that subscription removed; one that is merely failing keeps it", async () => { const rows = await db.select().from(pushSubscriptions); respondWith = 500; assert.deepEqual(await sendPush({ title: "t", body: "b" }, rows), { sent: 0, removed: 0, failed: 1 }); assert.equal((await db.select().from(pushSubscriptions)).length, 1); respondWith = 410; assert.deepEqual(await sendPush({ title: "t", body: "b" }, rows), { sent: 0, removed: 1, failed: 0 }); assert.equal((await db.select().from(pushSubscriptions)).length, 0); respondWith = 201; }); test("the test button writes to this person's own browsers only", async () => { assert.equal((await send("POST", "/test")).status, 400, "nothing subscribed now"); await send("POST", "/subscribe", { endpoint: `${pushBase}/ada-phone`, keys: mine.keys }); who = "vic"; await send("POST", "/subscribe", { endpoint: `${pushBase}/vic-laptop`, keys: vics.keys }); received.length = 0; const res = await send("POST", "/test"); assert.deepEqual(await res.json(), { sent: 1, removed: 0, failed: 0 }); assert.deepEqual(received.map((r) => r.path), ["/vic-laptop"]); assert.equal(JSON.parse(decrypt(received[0].body, vics.priv, vics.pub, vics.auth).toString()).title, "Homelab Manager — Test"); }); test("a person removes their own browsers, not someone else's; an administrator can remove anyone's", async () => { const all = await db.select().from(pushSubscriptions); const adas = all.find((s) => s.userId === ada)!; const vicsRow = all.find((s) => s.userId !== ada)!; who = "vic"; assert.equal((await send("DELETE", `/${adas.id}`)).status, 404, "not found, rather than 'not yours'"); assert.equal((await send("DELETE", `/${vicsRow.id}`)).status, 204); who = "ada"; await send("POST", "/subscribe", { endpoint: `${pushBase}/vic-laptop`, keys: vics.keys }); who = "vic"; assert.equal((await send("POST", "/subscribe", { endpoint: `${pushBase}/vic-laptop`, keys: vics.keys })).status, 201, "taking a browser over makes it theirs"); who = "ada"; const taken = (await db.select().from(pushSubscriptions)).find((s) => s.endpoint.endsWith("/vic-laptop"))!; assert.equal((await send("DELETE", `/${taken.id}`)).status, 204, "an administrator may"); assert.ok(adaSubId > 0); assert.equal((await db.select().from(auditLog)).filter((e) => e.category === "push" && e.action === "unsubscribe").length, 2); assert.equal((await db.select().from(pushSubscriptions).where(eq(pushSubscriptions.userId, ada))).length, 1); }); });