@ultimat3/pwa 25.2.0 → 26.1.0

package/src/vapid.ts

@@ -0,0 +1,167 @@
+// Single responsibility: the application server's identity to a push service — RFC 8292 VAPID.
+// A P-256 key pair, and the ES256 JWT that proves this server holds the private half of the key a
+// subscription was made with. WebCrypto only: no `jose`, no `web-push` (docs/idea/18-build-vs-wrap.md
+// — the whole of RFC 8292 is one signature over two JSON objects).
+//
+// Keys travel as the format every push library prints: the public key as the 65-byte uncompressed
+// point and the private key as the 32-byte scalar, both unpadded base64url. A key pair minted by
+// `web-push generate-vapid-keys` therefore works here unchanged.
+
+import type { Clock } from '@ultimat3/core';
+import { systemClock } from '@ultimat3/core';
+import { PwaVapidKeyInvalidError } from './errors';
+import { encodeBase64Url, tryDecodeBase64Url } from './push-bytes';
+
+/** The pair as configuration holds it: two base64url strings. */
+export interface VapidKeyPair {
+  /** 65-byte uncompressed P-256 point, base64url — what a browser's `applicationServerKey` takes. */
+  readonly publicKey: string;
+  /** 32-byte P-256 scalar, base64url. A secret: `ULTIMATE_VAPID_PRIVATE_KEY`. */
+  readonly privateKey: string;
+}
+
+/** The env var each half is read from — the names `x vapid create` seals and the boot reads. */
+export const VAPID_PUBLIC_KEY_ENV = 'ULTIMATE_VAPID_PUBLIC_KEY';
+export const VAPID_PRIVATE_KEY_ENV = 'ULTIMATE_VAPID_PRIVATE_KEY';
+
+/**
+ * RFC 8292 §2: `exp` no more than 24 hours ahead. Twelve, because a push service compares it with
+ * its own clock, and a server whose clock runs ahead by minutes must not produce a token the
+ * service reads as 24 hours and one minute.
+ */
+export const VAPID_TOKEN_TTL_SECONDS = 12 * 60 * 60;
+
+const P256 = { name: 'ECDSA', namedCurve: 'P-256' } as const;
+
+/** The 65-byte point, or the refusal naming which key and why. */
+export function vapidPublicKeyBytes(
+  publicKey: string,
+  key = VAPID_PUBLIC_KEY_ENV,
+): Uint8Array<ArrayBuffer> {
+  const bytes = tryDecodeBase64Url(publicKey);
+  if (bytes === undefined || bytes.byteLength !== 65 || bytes[0] !== 4) {
+    throw new PwaVapidKeyInvalidError({
+      key,
+      reason: 'is not a 65-byte uncompressed P-256 point in base64url (87 characters, starting B)',
+    });
+  }
+  return bytes;
+}
+
+/**
+ * Import the pair for ECDSA (signing a VAPID token) or ECDH (RFC 8291's key agreement — the same
+ * import, so a test can hand the RFC's application-server pair to the encryptor).
+ *
+ * JWK because WebCrypto has no raw-scalar import: `d` is the private key, `x`/`y` the public point.
+ * WebCrypto does NOT check that `d` belongs to `x`/`y`, so a mismatched pair imports fine and signs
+ * tokens no push service will verify — `assertVapidPair` is the check, run once at boot.
+ */
+export async function importVapidKeys(
+  pair: VapidKeyPair,
+  algorithm: 'ECDSA' | 'ECDH' = 'ECDSA',
+): Promise<CryptoKeyPair> {
+  const point = vapidPublicKeyBytes(pair.publicKey);
+  const scalar = tryDecodeBase64Url(pair.privateKey);
+  if (scalar === undefined || scalar.byteLength !== 32) {
+    throw new PwaVapidKeyInvalidError({
+      key: VAPID_PRIVATE_KEY_ENV,
+      reason: 'is not a 32-byte P-256 scalar in base64url (43 characters)',
+    });
+  }
+  const jwk: JsonWebKey = {
+    kty: 'EC',
+    crv: 'P-256',
+    x: encodeBase64Url(point.slice(1, 33)),
+    y: encodeBase64Url(point.slice(33, 65)),
+    ext: true,
+  };
+  const params = { name: algorithm, namedCurve: 'P-256' } as const;
+  const usages: KeyUsage[] = algorithm === 'ECDSA' ? ['sign'] : ['deriveBits'];
+  try {
+    const privateKey = await crypto.subtle.importKey(
+      'jwk',
+      { ...jwk, d: encodeBase64Url(scalar) },
+      params,
+      false,
+      usages,
+    );
+    const publicKey = await crypto.subtle.importKey(
+      'jwk',
+      jwk,
+      params,
+      true,
+      algorithm === 'ECDSA' ? ['verify'] : [],
+    );
+    return { privateKey, publicKey };
+  } catch {
+    throw new PwaVapidKeyInvalidError({
+      key: VAPID_PUBLIC_KEY_ENV,
+      reason: 'is not a point on the P-256 curve',
+    });
+  }
+}
+
+/**
+ * Sign once with the private half and verify with the public half. The only way to learn that two
+ * strings someone pasted into two variables are one key pair, and a wrong pair is otherwise a 403
+ * from every push service on every send, discovered by a user who never got a notification.
+ */
+export async function assertVapidPair(pair: VapidKeyPair): Promise<void> {
+  const keys = await importVapidKeys(pair);
+  const probe = new TextEncoder().encode('ultimate vapid pair check');
+  const signature = await crypto.subtle.sign({ ...P256, hash: 'SHA-256' }, keys.privateKey, probe);
+  const ok = await crypto.subtle.verify(
+    { ...P256, hash: 'SHA-256' },
+    keys.publicKey,
+    signature,
+    probe,
+  );
+  if (!ok) {
+    throw new PwaVapidKeyInvalidError({
+      key: VAPID_PRIVATE_KEY_ENV,
+      reason: `does not sign for ${VAPID_PUBLIC_KEY_ENV}: the two halves are from different pairs`,
+    });
+  }
+}
+
+/** A fresh pair, for `x vapid create`. The one place in this package that rolls key material. */
+export async function generateVapidKeys(): Promise<VapidKeyPair> {
+  const pair = await crypto.subtle.generateKey(P256, true, ['sign', 'verify']);
+  const jwk = await crypto.subtle.exportKey('jwk', pair.privateKey);
+  const raw = new Uint8Array(await crypto.subtle.exportKey('raw', pair.publicKey));
+  return { publicKey: encodeBase64Url(raw), privateKey: jwk.d ?? '' };
+}
+
+export interface VapidTokenInput {
+  /** The subscription's endpoint; the token's audience is its ORIGIN, never the full URL. */
+  readonly endpoint: string;
+  /** `mailto:` or `https:` — who the push service writes to about this server. */
+  readonly subject: string;
+  readonly keys: CryptoKeyPair;
+  readonly publicKey: string;
+  readonly clock?: Clock | undefined;
+}
+
+/**
+ * The `Authorization` header value: `vapid t=<jwt>, k=<public key>` (RFC 8292 §3). The signature is
+ * WebCrypto's raw `r || s`, which is exactly JWS ES256's encoding — no DER to unwrap.
+ */
+export async function vapidAuthorization(input: VapidTokenInput): Promise<string> {
+  const clock = input.clock ?? systemClock;
+  const exp = Math.floor(clock.now().getTime() / 1000) + VAPID_TOKEN_TTL_SECONDS;
+  const text = new TextEncoder();
+  const segment = (value: object): string => encodeBase64Url(text.encode(JSON.stringify(value)));
+  const unsigned = `${segment({ typ: 'JWT', alg: 'ES256' })}.${segment({
+    aud: new URL(input.endpoint).origin,
+    exp,
+    sub: input.subject,
+  })}`;
+  const signature = new Uint8Array(
+    await crypto.subtle.sign(
+      { ...P256, hash: 'SHA-256' },
+      input.keys.privateKey,
+      text.encode(unsigned),
+    ),
+  );
+  return `vapid t=${unsigned}.${encodeBase64Url(signature)}, k=${input.publicKey}`;
+}

package/src/version-skew.ts

@@ -10,7 +10,6 @@
  * The app decides what to do with that message. This package never navigates a client.
  */
 
-import type { APP_UPDATE_MESSAGE } from '@ultimat3/core';
 import { finiteCount } from '@ultimat3/core';
 import { BuildIdMissingError } from './errors';
 
@@ -111,34 +110,5 @@ export function retentionPlan(deploys: readonly Deploy[], keep = 3): RetentionPl
   };
 }
 
-export type SkewState = 'current' | 'stale' | 'unknown';
-
-/** `unknown` means "no id sent" — a first load, a crawler, or a cache-busted client. */
-export function detectSkew(
-  clientBuildId: string | null | undefined,
-  serverBuildId: string,
-): SkewState {
-  if (clientBuildId === null || clientBuildId === undefined || clientBuildId.trim() === '') {
-    return 'unknown';
-  }
-  return clientBuildId === serverBuildId ? 'current' : 'stale';
-}
-
-/**
- * The client-side contract, and the whole of it: what the generated worker posts to every page it
- * controls on activation. The page compares `to` against its own `CLIENT_BUILD_META` meta (core's)
- * — `detectSkew` is that comparison — and renders its own "refresh to update" affordance.
- *
- * It declared `from`, `forced` and `deadlineAt` too, for a forced reload after a grace period that
- * NOTHING performed: `updateSignal`/`updatePolicy` computed the three and had no runtime caller,
- * and `x deploy --critical`, the flag that was to have set the reason, was removed in 4.0.0 for
- * being read by nobody. The two runtimes that hold both build ids cannot call into this package
- * anyway — `http`'s `ctx.clientBuildId` (tier 2) and `sync`'s `update-available` frame (tier 3)
- * are both BELOW `pwa`, and imports only go down. `version-skew.test.ts` holds this interface to
- * the literal the worker emits, so the two can no longer differ.
- */
-export interface AppUpdateAvailable {
-  readonly type: typeof APP_UPDATE_MESSAGE;
-  /** The build the worker that posted this was generated for. */
-  readonly to: string;
-}
+// `SkewState`, `detectSkew` and `AppUpdateAvailable` — the page's half of skew — live in `skew.ts`,
+// which the browser entry (`client.ts`) re-exports without this file's error table.

package/src/web-push.ts

@@ -0,0 +1,124 @@
+// Single responsibility: one notification to EVERY device of one person. Renders the payload's
+// catalog keys in each subscription's own locale, sends each one, deletes the dead, and reports
+// the rest — throwing only when a retry could change the answer.
+//
+// `webPush()` is the shape `@ultimat3/notify`'s `pushChannel({ pusher })` takes, declared there
+// structurally (notify cannot import this package: same tier), so `notify(user, …)` reaches every
+// subscription that user holds with no glue in the app.
+
+import type { UltimateError } from '@ultimat3/core';
+import { isUltimateError, logger } from '@ultimat3/core';
+import type { PushPayload } from './push';
+import { renderPushPayload, serializePushMessage, subscriptionState } from './push';
+import { webPushRuntime } from './push-runtime';
+import type { PushDelivery } from './push-send';
+import { sendPushMessage } from './push-send';
+
+/** What a notification says (catalog keys, never text) and how it travels. */
+export interface PushNotification extends PushPayload, PushDelivery {}
+
+export interface PushReport {
+  readonly delivered: number;
+  /** 404/410 or expired — deleted from the store. */
+  readonly removed: number;
+  /** Refused for good (`X_PWA_PUSH_REJECTED`, a body too large, a malformed key) — logged. */
+  readonly refused: number;
+}
+
+/**
+ * Every subscription of `actorId`, in endpoint order. A refusal that a retry cannot cure is logged
+ * with its code and fix and counted; a failure a retry CAN cure (`X_PWA_PUSH_FAILED`) is rethrown
+ * AFTER every other device was tried, so one flaky push service does not hold back the rest — and
+ * on the retry the devices that did receive it get it again. A notification with a `tag` replaces
+ * itself on those devices; one without shows twice, which is why a notifier should always set one.
+ */
+export async function pushToActor(
+  actorId: string,
+  notification: PushNotification,
+  signal?: AbortSignal,
+): Promise<PushReport> {
+  const runtime = webPushRuntime('pushToActor');
+  const subscriptions = await runtime.store.listFor(actorId);
+  let delivered = 0;
+  let removed = 0;
+  let refused = 0;
+  let retry: unknown;
+  for (const subscription of subscriptions) {
+    if (subscriptionState(subscription, null, runtime.clock) === 'expired') {
+      await runtime.store.remove(subscription.endpoint);
+      removed += 1;
+      continue;
+    }
+    const rendered = renderPushPayload(
+      notification,
+      subscription.locale,
+      runtime.translate(subscription.locale),
+    );
+    for (const warning of rendered.warnings) logger.warn('pwa.push.render', { warning });
+    try {
+      const outcome = await sendPushMessage({
+        target: subscription,
+        plaintext: new TextEncoder().encode(serializePushMessage(rendered)),
+        vapid: runtime.signer,
+        delivery: notification,
+        fetch: runtime.fetch,
+        clock: runtime.clock,
+        signal,
+        pushHosts: runtime.pushHosts,
+      });
+      if (outcome.kind === 'gone') {
+        await runtime.store.remove(subscription.endpoint);
+        removed += 1;
+      } else {
+        delivered += 1;
+      }
+    } catch (error) {
+      if (isUltimateError(error) && error.code === 'X_PWA_PUSH_FAILED') {
+        retry ??= error;
+        continue;
+      }
+      if (!isUltimateError(error)) throw error;
+      refused += 1;
+      // A stored subscription no send will ever reach is deleted, so the next notification does
+      // not pay for it again: a malformed key, or a 401/403 — made with a VAPID key this server no
+      // longer signs with. That browser re-subscribes under the new key the next time it asks.
+      if (
+        error.code === 'X_PWA_PUSH_SUBSCRIPTION_INVALID' ||
+        error.code === 'X_PWA_PUSH_HOST_UNLISTED' ||
+        unreachableUnderThisKey(error)
+      ) {
+        await runtime.store.remove(subscription.endpoint);
+      }
+      logger.error('pwa.push.refused', { code: error.code, cause: error.cause, fix: error.fix });
+    }
+  }
+  if (retry !== undefined) throw retry;
+  return { delivered, removed, refused };
+}
+
+/** A push service's 401/403: the subscription belongs to another VAPID key, for good. */
+const unreachableUnderThisKey = (error: UltimateError): boolean => {
+  const status = (error.meta as { readonly status?: unknown } | undefined)?.status;
+  return error.code === 'X_PWA_PUSH_REJECTED' && (status === 401 || status === 403);
+};
+
+/** The structural shape `@ultimat3/notify`'s `Pusher` declares. */
+export interface WebPusher {
+  send(push: {
+    readonly to: string;
+    readonly message: PushNotification;
+    readonly signal: AbortSignal;
+  }): Promise<void>;
+}
+
+/**
+ * The installed runtime as a notify pusher: `pushChannel({ pusher: webPush(), message })`. It
+ * reads the runtime per send, so it can be declared at module scope before the boot installs one.
+ */
+export function webPush(): WebPusher {
+  return {
+    async send({ to, message, signal }) {
+      await pushToActor(to, message, signal);
+    },
+  };
+}