@ultimat3/pwa 25.2.0 → 26.1.0

package/src/push-actions.ts

@@ -0,0 +1,104 @@
+// Single responsibility: the subscription surface, as two FACTORIES OVER `action` — never a ninth
+// primitive and never a hand-mounted route. What they return is an action an app exports from its
+// own actions module, so each one has its route, OpenAPI operation, typed client, contract tests
+// and policy like any other write:
+//
+//   // apps/web/app/push/actions.ts
+//   export const subscribePush = pushSubscribe({ permission: 'push:subscribe' });
+//   export const unsubscribePush = pushUnsubscribe({ permission: 'push:subscribe' });
+//
+// The subscription is stored against `ctx.actor.id`, the person the request ran as — never an id
+// the body names, so a caller can subscribe only themselves and unsubscribe only their own device.
+
+import type { Action } from '@ultimat3/action';
+import { action } from '@ultimat3/action';
+import type { KnownPermission, PolicyArgs, PolicyDecision } from '@ultimat3/policy';
+import { can, denied } from '@ultimat3/policy';
+import { t } from '@ultimat3/schema';
+import { subscriptionKeyBytes } from './push-encrypt';
+import { webPushRuntime } from './push-runtime';
+import { assertPushEndpoint } from './push-send';
+
+/** `PushSubscription.toJSON()`, plus the two facts a server-rendered notification needs. */
+const subscribeInput = () =>
+  t.object({
+    endpoint: t.string.min(1).max(2048),
+    expirationTime: t.nullable(t.number),
+    keys: t.object({ p256dh: t.string.max(128), auth: t.string.max(64) }),
+    /** BCP-47 — every notification to this device renders in it (`renderPushPayload`). */
+    locale: t.locale,
+    /** IANA — the zone a notification formatting a date would need. */
+    timeZone: t.timezone,
+  });
+
+const subscribeOutput = () => t.object({ endpoint: t.string });
+const unsubscribeInput = () => t.object({ endpoint: t.string.min(1).max(2048) });
+const unsubscribeOutput = () => t.object({ removed: t.boolean });
+
+type SubscribeInput = ReturnType<typeof subscribeInput>;
+type SubscribeOutput = ReturnType<typeof subscribeOutput>;
+type UnsubscribeInput = ReturnType<typeof unsubscribeInput>;
+type UnsubscribeOutput = ReturnType<typeof unsubscribeOutput>;
+
+export interface PushSubscriptionActionOptions {
+  /** What the subscribing actor must hold — read by `can()`, like every action's permission. */
+  readonly permission: KnownPermission;
+  /**
+   * The app's further rule, over the actor. Absent, any actor holding the permission subscribes
+   * themselves. An AGENT never does, whatever this says: a notification is for a person's device.
+   */
+  readonly check?: ((args: PolicyArgs<unknown, null>) => boolean | PolicyDecision) | undefined;
+}
+
+const policyOf = (options: PushSubscriptionActionOptions) =>
+  can<unknown, null>(options.permission, (args) => {
+    if (args.actor?.kind === 'agent') return denied('push.agent-subscriber');
+    return options.check === undefined ? true : options.check(args);
+  });
+
+/** Store this browser's subscription for the person signed in. Idempotent per endpoint. */
+export function pushSubscribe(
+  options: PushSubscriptionActionOptions,
+): Action<SubscribeInput, SubscribeOutput> {
+  return action({
+    input: subscribeInput(),
+    output: subscribeOutput(),
+    policy: policyOf(options),
+    idempotent: true,
+    async handle({ input, ctx }) {
+      const runtime = webPushRuntime('pushSubscribe');
+      // Refused before it is stored: an endpoint is where this server will POST, and only a push
+      // service the app sends to is ever one (`push-hosts.ts`).
+      assertPushEndpoint(input.endpoint, runtime.pushHosts);
+      // Refused HERE rather than at the first send: a key no message can be encrypted for is a
+      // subscription that fails every notification, silently, on a device that thinks it is on.
+      subscriptionKeyBytes(input.keys);
+      await runtime.store.save({
+        endpoint: input.endpoint,
+        keys: { p256dh: input.keys.p256dh, auth: input.keys.auth },
+        locale: input.locale,
+        timeZone: input.timeZone,
+        actorId: ctx.actor.id,
+        createdAt: ctx.now().getTime(),
+        expirationTime: input.expirationTime,
+      });
+      return { endpoint: input.endpoint };
+    },
+  });
+}
+
+/** Forget this browser's subscription — the caller's own only; another person's is absent. */
+export function pushUnsubscribe(
+  options: PushSubscriptionActionOptions,
+): Action<UnsubscribeInput, UnsubscribeOutput> {
+  return action({
+    input: unsubscribeInput(),
+    output: unsubscribeOutput(),
+    policy: policyOf(options),
+    idempotent: true,
+    async handle({ input, ctx }) {
+      const runtime = webPushRuntime('pushUnsubscribe');
+      return { removed: await runtime.store.remove(input.endpoint, ctx.actor.id) };
+    },
+  });
+}

package/src/push-bytes.ts

@@ -0,0 +1,39 @@
+// Single responsibility: the byte vocabulary Web Push is spelled in — base64url without padding
+// (every key, salt and JWT segment on the wire) and concatenation. `btoa`/`atob`, standard
+// globals, never `node:buffer`; `Uint8Array.fromBase64` is in Bun but not in the TypeScript lib.
+
+/** Unpadded base64url, the alphabet RFC 8291 and RFC 8292 print every value in. */
+export function encodeBase64Url(bytes: Uint8Array): string {
+  let binary = '';
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replaceAll('+', '-').replaceAll('/', '_').replaceAll('=', '');
+}
+
+/**
+ * `undefined` for text that is not base64url, rather than a throw: every caller is holding a value
+ * someone else wrote (a browser's subscription, an environment variable) and refuses it under its
+ * own code, naming which value it was.
+ */
+export function tryDecodeBase64Url(text: string): Uint8Array<ArrayBuffer> | undefined {
+  if (!/^[A-Za-z0-9_-]*={0,2}$/.test(text)) return undefined;
+  const standard = text.replace(/=+$/, '').replaceAll('-', '+').replaceAll('_', '/');
+  if (standard.length % 4 === 1) return undefined;
+  try {
+    const binary = atob(standard.padEnd(standard.length + ((4 - (standard.length % 4)) % 4), '='));
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i += 1) bytes[i] = binary.charCodeAt(i);
+    return bytes;
+  } catch {
+    return undefined;
+  }
+}
+
+export function concatBytes(...parts: readonly Uint8Array[]): Uint8Array<ArrayBuffer> {
+  const out = new Uint8Array(parts.reduce((total, part) => total + part.byteLength, 0));
+  let at = 0;
+  for (const part of parts) {
+    out.set(part, at);
+    at += part.byteLength;
+  }
+  return out;
+}

package/src/push-client.ts

@@ -0,0 +1,182 @@
+// Single responsibility: the BROWSER half of Web Push — ask for permission, subscribe with the
+// server's VAPID public key, hand the subscription to the app's `pushSubscribe()` action, and undo
+// it. Re-exported by `@ultimat3/pwa/client` (`client.ts`); this file imports NOTHING, so an island
+// that offers a "notify me" button pays for these lines and nothing of the server package.
+//
+//   import { subscribeToPush } from '@ultimat3/pwa/client';
+//   import { client } from '../../shared/browser-client';
+//   onClick={() => subscribeToPush({ save: client.subscribePush })}
+//
+// The key is read from `<meta name="x-push-key">`, which the web role writes into every document
+// once push is configured — so no app passes, bundles or fetches it, and a key rotation reaches
+// every page on its next render.
+
+/** The `<meta name>` the web role emits; `@ultimat3/cli` writes it, this reads it. */
+export const PUSH_KEY_META = 'x-push-key';
+
+export type PushPermission = 'granted' | 'denied' | 'prompt' | 'unsupported';
+
+/**
+ * What `subscribeToPush` answers. Every branch is an outcome the app renders, not an exception:
+ * `denied` is a person's decision, `unsupported` a browser's (iOS before it is installed to the
+ * home screen), `unconfigured` a page served with no push key.
+ */
+export type PushSubscribeOutcome =
+  | { readonly status: 'subscribed'; readonly endpoint: string }
+  | { readonly status: 'denied' }
+  | { readonly status: 'unsupported' }
+  | { readonly status: 'unconfigured' };
+
+/** What the `pushSubscribe()` action takes — `PushSubscription.toJSON()` plus locale and zone. */
+export interface PushSubscriptionInput {
+  readonly endpoint: string;
+  readonly expirationTime: number | null;
+  readonly keys: { readonly p256dh: string; readonly auth: string };
+  readonly locale: string;
+  readonly timeZone: string;
+}
+
+/** The browser surface this module touches — injectable, so a test runs it without a browser. */
+export interface PushClientHost {
+  readonly serviceWorker: { readonly ready: Promise<PushRegistrationLike> } | undefined;
+  readonly notification:
+    | {
+        readonly permission: 'default' | 'denied' | 'granted';
+        requestPermission(): Promise<'default' | 'denied' | 'granted'>;
+      }
+    | undefined;
+  /** `<meta name="x-push-key">`'s content, or `null`. */
+  readonly pushKey: string | null;
+  /** `<html lang>` — the locale this page was rendered in, so the one a notification renders in. */
+  readonly locale: string;
+  /** The device's IANA zone. */
+  readonly timeZone: string;
+}
+
+export interface PushRegistrationLike {
+  readonly pushManager: {
+    getSubscription(): Promise<PushSubscriptionLike | null>;
+    subscribe(options: {
+      userVisibleOnly: boolean;
+      applicationServerKey: Uint8Array<ArrayBuffer>;
+    }): Promise<PushSubscriptionLike>;
+  };
+}
+
+export interface PushSubscriptionLike {
+  readonly endpoint: string;
+  /** The key it was made with — a browser always says; absent here means "cannot tell". */
+  readonly options?: { readonly applicationServerKey?: ArrayBuffer | null } | undefined;
+  toJSON(): {
+    endpoint?: string;
+    expirationTime?: number | null;
+    keys?: Record<string, string>;
+  };
+  unsubscribe(): Promise<boolean>;
+}
+
+/** The real browser, read at call time — never at import, which may run during a server render. */
+export function browserPushHost(): PushClientHost {
+  const nav = globalThis.navigator as Navigator | undefined;
+  const supported =
+    nav !== undefined && 'serviceWorker' in nav && typeof globalThis.PushManager === 'function';
+  // Read only where push can happen at all: a runtime with no service worker answers
+  // `unsupported`, never a throw from a document that is not a browser's.
+  const meta = supported
+    ? globalThis.document?.querySelector(`meta[name="${PUSH_KEY_META}"]`)
+    : undefined;
+  return {
+    serviceWorker: supported
+      ? (nav.serviceWorker as unknown as PushClientHost['serviceWorker'])
+      : undefined,
+    notification:
+      typeof globalThis.Notification === 'function'
+        ? (globalThis.Notification as unknown as PushClientHost['notification'])
+        : undefined,
+    pushKey: meta?.getAttribute('content') ?? null,
+    locale: globalThis.document?.documentElement?.lang || 'en',
+    timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+  };
+}
+
+/** Where this browser stands, without asking anything. */
+export function pushPermission(host: PushClientHost = browserPushHost()): PushPermission {
+  if (host.serviceWorker === undefined || host.notification === undefined) return 'unsupported';
+  const state = host.notification.permission;
+  return state === 'default' ? 'prompt' : state;
+}
+
+function keyBytes(text: string): Uint8Array<ArrayBuffer> {
+  const standard = text.replaceAll('-', '+').replaceAll('_', '/');
+  const binary = atob(standard.padEnd(standard.length + ((4 - (standard.length % 4)) % 4), '='));
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i += 1) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
+
+/** Whether `subscription` was made with `key`; one that does not say is taken at its word. */
+function madeWith(subscription: PushSubscriptionLike, key: Uint8Array): boolean {
+  const held = subscription.options?.applicationServerKey;
+  if (held === undefined || held === null) return true;
+  const bytes = new Uint8Array(held);
+  return bytes.length === key.length && bytes.every((byte, i) => byte === key[i]);
+}
+
+/**
+ * Ask, subscribe, save. Call it from a click: browsers refuse a permission prompt that no user
+ * gesture asked for. An existing subscription is saved again rather than replaced — it re-binds
+ * the device to whoever is signed in now, and keeps the locale current — UNLESS it was made with
+ * another server key (a VAPID rotation): no message signed with the new key can reach it, so it is
+ * unsubscribed and replaced, never re-saved as if it worked.
+ */
+export async function subscribeToPush(
+  options: { readonly save: (input: PushSubscriptionInput) => Promise<unknown> },
+  host: PushClientHost = browserPushHost(),
+): Promise<PushSubscribeOutcome> {
+  if (host.serviceWorker === undefined || host.notification === undefined) {
+    return { status: 'unsupported' };
+  }
+  if (host.pushKey === null || host.pushKey === '') return { status: 'unconfigured' };
+  const permission =
+    host.notification.permission === 'default'
+      ? await host.notification.requestPermission()
+      : host.notification.permission;
+  if (permission !== 'granted') return { status: 'denied' };
+  const registration = await host.serviceWorker.ready;
+  const key = keyBytes(host.pushKey);
+  let subscription = await registration.pushManager.getSubscription();
+  if (subscription !== null && !madeWith(subscription, key)) {
+    await subscription.unsubscribe();
+    subscription = null;
+  }
+  subscription ??= await registration.pushManager.subscribe({
+    userVisibleOnly: true,
+    applicationServerKey: key,
+  });
+  const json = subscription.toJSON();
+  await options.save({
+    endpoint: subscription.endpoint,
+    expirationTime: json.expirationTime ?? null,
+    keys: { p256dh: json.keys?.['p256dh'] ?? '', auth: json.keys?.['auth'] ?? '' },
+    locale: host.locale,
+    timeZone: host.timeZone,
+  });
+  return { status: 'subscribed', endpoint: subscription.endpoint };
+}
+
+/**
+ * Tell the server first, then the browser: the other order leaves a row the sender meets as a 410
+ * at best, and as notifications to a device the person turned off at worst, if the call fails.
+ * `false` when this browser held no subscription.
+ */
+export async function unsubscribeFromPush(
+  options: { readonly remove: (input: { readonly endpoint: string }) => Promise<unknown> },
+  host: PushClientHost = browserPushHost(),
+): Promise<boolean> {
+  if (host.serviceWorker === undefined) return false;
+  const registration = await host.serviceWorker.ready;
+  const subscription = await registration.pushManager.getSubscription();
+  if (subscription === null) return false;
+  await options.remove({ endpoint: subscription.endpoint });
+  return subscription.unsubscribe();
+}

package/src/push-decrypt.ts

@@ -0,0 +1,92 @@
+// Single responsibility: RFC 8291 from the USER AGENT's side — open one `aes128gcm` push record
+// with the subscriber's private key and auth secret. A browser does this itself; the framework's
+// caller is `@ultimat3/testing`'s `push` fixture, which plays the browser so a test asserts the
+// notification a device would show rather than the bytes a push service received.
+
+import { PwaPushSubscriptionInvalidError } from './errors';
+import { concatBytes } from './push-bytes';
+
+/** A subscriber: its ECDH key pair (the private half never leaves it) and its auth secret. */
+export interface PushReceiverKeys {
+  readonly privateKey: CryptoKey;
+  /** The 65-byte uncompressed point the subscription's `p256dh` carries. */
+  readonly publicKey: Uint8Array<ArrayBuffer>;
+  /** The 16 bytes the subscription's `auth` carries. */
+  readonly authSecret: Uint8Array<ArrayBuffer>;
+}
+
+const text = new TextEncoder();
+
+async function hkdf(
+  salt: Uint8Array<ArrayBuffer>,
+  ikm: Uint8Array<ArrayBuffer>,
+  info: Uint8Array<ArrayBuffer>,
+  bytes: number,
+): Promise<Uint8Array<ArrayBuffer>> {
+  const key = await crypto.subtle.importKey('raw', ikm, 'HKDF', false, ['deriveBits']);
+  return new Uint8Array(
+    await crypto.subtle.deriveBits({ name: 'HKDF', hash: 'SHA-256', salt, info }, key, bytes * 8),
+  );
+}
+
+/**
+ * The plaintext of one record, delimiter stripped. A body that is not one well-formed record for
+ * these keys — truncated, another subscriber's, tampered — is refused by code, as a browser drops it.
+ */
+export async function decryptPushMessage(
+  body: Uint8Array<ArrayBuffer>,
+  receiver: PushReceiverKeys,
+): Promise<Uint8Array<ArrayBuffer>> {
+  const idLength = body[20] ?? 0;
+  if (body.byteLength < 21 + idLength + 17 || idLength !== 65) {
+    throw new PwaPushSubscriptionInvalidError({
+      field: 'body',
+      reason: 'is not one aes128gcm record with a 65-byte sender key',
+    });
+  }
+  const opened = await open(body, receiver, idLength);
+  if (opened === undefined) {
+    throw new PwaPushSubscriptionInvalidError({
+      field: 'body',
+      reason: 'does not open with these keys: another subscriber’s, truncated or tampered',
+    });
+  }
+  return opened;
+}
+
+/** The record's plaintext, or `undefined` for every way it fails to be one for these keys. */
+async function open(
+  body: Uint8Array<ArrayBuffer>,
+  receiver: PushReceiverKeys,
+  idLength: number,
+): Promise<Uint8Array<ArrayBuffer> | undefined> {
+  const salt = body.slice(0, 16);
+  const asPublic = body.slice(21, 21 + idLength);
+  let padded: Uint8Array<ArrayBuffer>;
+  try {
+    const asKey = await crypto.subtle.importKey(
+      'raw',
+      asPublic,
+      { name: 'ECDH', namedCurve: 'P-256' },
+      false,
+      [],
+    );
+    const ecdh = new Uint8Array(
+      await crypto.subtle.deriveBits({ name: 'ECDH', public: asKey }, receiver.privateKey, 256),
+    );
+    const keyInfo = concatBytes(text.encode('WebPush: info\0'), receiver.publicKey, asPublic);
+    const ikm = await hkdf(receiver.authSecret, ecdh, keyInfo, 32);
+    const cek = await hkdf(salt, ikm, text.encode('Content-Encoding: aes128gcm\0'), 16);
+    const nonce = await hkdf(salt, ikm, text.encode('Content-Encoding: nonce\0'), 12);
+    const key = await crypto.subtle.importKey('raw', cek, 'AES-GCM', false, ['decrypt']);
+    padded = new Uint8Array(
+      await crypto.subtle.decrypt({ name: 'AES-GCM', iv: nonce }, key, body.slice(21 + idLength)),
+    );
+  } catch {
+    return undefined;
+  }
+  // RFC 8188: strip zero padding back to the delimiter; 0x02 marks the last (only) record.
+  let end = padded.byteLength - 1;
+  while (end >= 0 && padded[end] === 0) end -= 1;
+  return padded[end] === 2 ? padded.slice(0, end) : undefined;
+}

package/src/push-encrypt.ts

@@ -0,0 +1,161 @@
+// Single responsibility: RFC 8291 — encrypt one push message for one subscription, as a single
+// `aes128gcm` record (RFC 8188). WebCrypto only: ECDH P-256 for the shared secret, HKDF-SHA-256
+// for the key schedule, AES-128-GCM for the record.
+//
+// RANDOMNESS IS THE POINT HERE, and it is injectable. Each message needs a fresh salt and a fresh
+// ephemeral key pair — reusing either across messages to one subscription reuses a GCM nonce under
+// one key. Production rolls both; a test hands in RFC 8291 Appendix A's, and gets its exact bytes.
+
+import { PwaPushPayloadTooLargeError, PwaPushSubscriptionInvalidError } from './errors';
+import { concatBytes, tryDecodeBase64Url } from './push-bytes';
+
+/** The one record size this encoder writes: the whole message is one record (RFC 8291 §4). */
+export const PUSH_RECORD_SIZE = 4096;
+
+/** salt(16) + rs(4) + idlen(1) + keyid(65): the `aes128gcm` header with the sender's public key. */
+const HEADER_BYTES = 86;
+const TAG_BYTES = 16;
+/** RFC 8188's last-record delimiter, appended to the plaintext before it is sealed. */
+const LAST_RECORD = 0x02;
+
+/** Plaintext bytes one record holds: 4096 − 86 − 16 − 1 = 3993, RFC 8291 §4's number. */
+export const pushMessageCapacity = (): number => PUSH_RECORD_SIZE - HEADER_BYTES - TAG_BYTES - 1;
+
+/** What a browser's `PushSubscription.toJSON().keys` carries. */
+export interface PushEncryptionKeys {
+  /** The user agent's ECDH public key: 65-byte uncompressed P-256 point, base64url. */
+  readonly p256dh: string;
+  /** The 16-byte authentication secret, base64url. */
+  readonly auth: string;
+}
+
+export interface PushEncryptOptions {
+  /** The application server's ONE-MESSAGE key pair (ECDH). Rolled per message when omitted. */
+  readonly ephemeral?: CryptoKeyPair | undefined;
+  /** 16 bytes. Rolled per message when omitted. */
+  readonly salt?: Uint8Array<ArrayBuffer> | undefined;
+}
+
+export interface ContentKeys {
+  readonly ecdhSecret: Uint8Array<ArrayBuffer>;
+  readonly ikm: Uint8Array<ArrayBuffer>;
+  readonly cek: Uint8Array<ArrayBuffer>;
+  readonly nonce: Uint8Array<ArrayBuffer>;
+  /** The sender's public key as the header's `keyid` carries it. */
+  readonly asPublic: Uint8Array<ArrayBuffer>;
+}
+
+const text = new TextEncoder();
+
+/** HKDF-Extract then HKDF-Expand in one WebCrypto call — exactly RFC 5869's two steps. */
+async function hkdf(
+  salt: Uint8Array<ArrayBuffer>,
+  ikm: Uint8Array<ArrayBuffer>,
+  info: Uint8Array<ArrayBuffer>,
+  bytes: number,
+): Promise<Uint8Array<ArrayBuffer>> {
+  const key = await crypto.subtle.importKey('raw', ikm, 'HKDF', false, ['deriveBits']);
+  const bits = await crypto.subtle.deriveBits(
+    { name: 'HKDF', hash: 'SHA-256', salt, info },
+    key,
+    bytes * 8,
+  );
+  return new Uint8Array(bits);
+}
+
+/** RFC 8291 §3.3–3.4 and RFC 8188 §2.2: the shared secret, then CEK and NONCE. */
+export async function deriveContentKeys(input: {
+  readonly ephemeral: CryptoKeyPair;
+  readonly uaPublic: Uint8Array<ArrayBuffer>;
+  readonly authSecret: Uint8Array<ArrayBuffer>;
+  readonly salt: Uint8Array<ArrayBuffer>;
+}): Promise<ContentKeys> {
+  const uaKey = await crypto.subtle.importKey(
+    'raw',
+    input.uaPublic,
+    { name: 'ECDH', namedCurve: 'P-256' },
+    false,
+    [],
+  );
+  const ecdhSecret = new Uint8Array(
+    await crypto.subtle.deriveBits(
+      { name: 'ECDH', public: uaKey },
+      input.ephemeral.privateKey,
+      256,
+    ),
+  );
+  const asPublic = new Uint8Array(await crypto.subtle.exportKey('raw', input.ephemeral.publicKey));
+  const keyInfo = concatBytes(text.encode('WebPush: info\0'), input.uaPublic, asPublic);
+  const ikm = await hkdf(input.authSecret, ecdhSecret, keyInfo, 32);
+  const cek = await hkdf(input.salt, ikm, text.encode('Content-Encoding: aes128gcm\0'), 16);
+  const nonce = await hkdf(input.salt, ikm, text.encode('Content-Encoding: nonce\0'), 12);
+  return { ecdhSecret, ikm, cek, nonce, asPublic };
+}
+
+/** The subscription's two keys, decoded and size-checked, or the refusal naming which one. */
+export function subscriptionKeyBytes(keys: PushEncryptionKeys): {
+  readonly uaPublic: Uint8Array<ArrayBuffer>;
+  readonly authSecret: Uint8Array<ArrayBuffer>;
+} {
+  const uaPublic = tryDecodeBase64Url(keys.p256dh);
+  if (uaPublic === undefined || uaPublic.byteLength !== 65 || uaPublic[0] !== 4) {
+    throw new PwaPushSubscriptionInvalidError({
+      field: 'keys.p256dh',
+      reason: 'is not a 65-byte uncompressed P-256 point in base64url',
+    });
+  }
+  const authSecret = tryDecodeBase64Url(keys.auth);
+  if (authSecret === undefined || authSecret.byteLength !== 16) {
+    throw new PwaPushSubscriptionInvalidError({
+      field: 'keys.auth',
+      reason: 'is not a 16-byte secret in base64url',
+    });
+  }
+  return { uaPublic, authSecret };
+}
+
+/**
+ * The request body: `salt | rs | idlen | keyid | ciphertext`. One record, so the plaintext gets
+ * the LAST-record delimiter and no padding — padding hides a length, and every message here is a
+ * notification the device shows in full.
+ */
+export async function encryptPushMessage(
+  keys: PushEncryptionKeys,
+  plaintext: Uint8Array,
+  options: PushEncryptOptions = {},
+): Promise<Uint8Array<ArrayBuffer>> {
+  const capacity = pushMessageCapacity();
+  if (plaintext.byteLength > capacity) {
+    throw new PwaPushPayloadTooLargeError({ bytes: plaintext.byteLength, limit: capacity });
+  }
+  const { uaPublic, authSecret } = subscriptionKeyBytes(keys);
+  // why: the salt and the one-message key ARE randomness by specification (RFC 8291 §3.3); the
+  // options above are the seam a test pins them through.
+  const salt = options.salt ?? crypto.getRandomValues(new Uint8Array(16));
+  const ephemeral =
+    options.ephemeral ??
+    (await crypto.subtle.generateKey({ name: 'ECDH', namedCurve: 'P-256' }, true, ['deriveBits']));
+  let derived: ContentKeys;
+  try {
+    derived = await deriveContentKeys({ ephemeral, uaPublic, authSecret, salt });
+  } catch {
+    // A 65-byte string starting 0x04 that is not ON the curve: WebCrypto refuses the import.
+    throw new PwaPushSubscriptionInvalidError({
+      field: 'keys.p256dh',
+      reason: 'is not a point on the P-256 curve',
+    });
+  }
+  const key = await crypto.subtle.importKey('raw', derived.cek, 'AES-GCM', false, ['encrypt']);
+  const sealed = new Uint8Array(
+    await crypto.subtle.encrypt(
+      { name: 'AES-GCM', iv: derived.nonce },
+      key,
+      concatBytes(plaintext, Uint8Array.of(LAST_RECORD)),
+    ),
+  );
+  const header = new Uint8Array(HEADER_BYTES - 65);
+  header.set(salt, 0);
+  new DataView(header.buffer).setUint32(16, PUSH_RECORD_SIZE, false);
+  header[20] = derived.asPublic.byteLength;
+  return concatBytes(header, derived.asPublic, sealed);
+}

package/src/push-hosts.ts

@@ -0,0 +1,34 @@
+// Single responsibility: which hosts the push sender may dial. An endpoint is a URL from a REQUEST
+// BODY, and a hostname resolves wherever its owner points it — a private address, the cloud
+// metadata service — so checking the name's shape (`https:`, not an IP literal) is not a screen.
+// The one that holds is a list of the push services browsers actually hand out, checked when a
+// subscription is stored AND before every send; an app adds its own with `pwa.vapid.pushHosts`.
+
+/**
+ * Every push service a current browser subscribes with, `As of 2026-10`. Each matches itself and
+ * its subdomains, on a dot boundary — `fcm.googleapis.com.evil.com` and `evilpush.apple.com` match
+ * nothing.
+ *
+ * | Host | Browser | Endpoints look like |
+ * |---|---|---|
+ * | `fcm.googleapis.com` | Chrome, Edge on Android, every Chromium | `https://fcm.googleapis.com/fcm/send/…`, `…/wp/…` |
+ * | `push.services.mozilla.com` | Firefox | `https://updates.push.services.mozilla.com/wpush/v2/…` |
+ * | `push.apple.com` | Safari (macOS, iOS 16.4+) | `https://web.push.apple.com/…` |
+ * | `notify.windows.com` | Edge on Windows (WNS) | `https://wns2-<region>.notify.windows.com/w/?token=…` |
+ */
+export const PUSH_SERVICE_HOSTS: readonly string[] = Object.freeze([
+  'fcm.googleapis.com',
+  'push.services.mozilla.com',
+  'push.apple.com',
+  'notify.windows.com',
+]);
+
+/** `host` is `listed` itself or a subdomain of it — compared lower-case, on a dot boundary. */
+const under = (host: string, listed: string): boolean =>
+  host === listed || host.endsWith(`.${listed}`);
+
+/** Whether `host` is a built-in push service or one the app listed (`pwa.vapid.pushHosts`). */
+export function pushHostAllowed(host: string, extra: readonly string[] = []): boolean {
+  const name = host.toLowerCase().replace(/\.$/, '');
+  return [...PUSH_SERVICE_HOSTS, ...extra].some((listed) => under(name, listed.toLowerCase()));
+}