@ultimat3/pwa 25.2.0 → 26.1.0

package/src/push-runtime.ts

@@ -0,0 +1,87 @@
+// Single responsibility: the one Web Push runtime a process holds — the subscription store, the
+// imported VAPID signer, and the transport — installed by the boot and read per call by the
+// subscribe actions and the sender.
+//
+// Read PER CALL, never captured at declaration: an app's `pushSubscribe()` is declared when its
+// modules import, and the boot installs this before that (`@ultimat3/cli`'s `runtime-services.ts`)
+// — but a test installs its own after, and a captured value would be the previous test's.
+
+import type { Clock } from '@ultimat3/core';
+import { systemClock } from '@ultimat3/core';
+import { translatorFor } from '@ultimat3/i18n';
+import { PwaPushUnconfiguredError } from './errors';
+import type { Translate, VapidConfig } from './push';
+import type { VapidSigner } from './push-send';
+import type { PushSubscriptionStore } from './push-store';
+import type { VapidKeyPair } from './vapid';
+import { importVapidKeys } from './vapid';
+
+export interface WebPushOptions {
+  readonly store: PushSubscriptionStore;
+  /** The pair `resolveVapidKeys` answered — the boot checked it is one. */
+  readonly keys: VapidKeyPair;
+  /** `pwa.vapid.subject`: `mailto:` or `https:`. */
+  readonly subject: string;
+  readonly fetch?: typeof fetch | undefined;
+  readonly clock?: Clock | undefined;
+  /** `pwa.vapid.pushHosts`: push services beyond the built-in list, at subscribe and at send. */
+  readonly pushHosts?: readonly string[] | undefined;
+  /**
+   * The catalog a subscriber's locale renders from. `@ultimat3/i18n`'s `translatorFor` — the app's
+   * registered catalogs — unless a test hands its own.
+   */
+  readonly translate?: ((locale: string) => Translate) | undefined;
+}
+
+export interface WebPushRuntime {
+  readonly store: PushSubscriptionStore;
+  readonly signer: VapidSigner;
+  readonly fetch: typeof fetch;
+  readonly clock: Clock;
+  readonly translate: (locale: string) => Translate;
+  readonly pushHosts: readonly string[];
+}
+
+let installed: WebPushRuntime | undefined;
+
+/**
+ * Install the runtime and answer its release. Whole-object replacement, never a merge. The key is
+ * imported once here, not per send: a notifier fanning out to a thousand devices signs a thousand
+ * tokens with one `CryptoKey`.
+ */
+export async function installWebPush(options: WebPushOptions): Promise<() => void> {
+  const keys = await importVapidKeys(options.keys);
+  const runtime: WebPushRuntime = {
+    store: options.store,
+    signer: { keys, publicKey: options.keys.publicKey, subject: options.subject },
+    fetch: options.fetch ?? fetch,
+    clock: options.clock ?? systemClock,
+    translate: options.translate ?? ((locale) => translatorFor(locale)),
+    pushHosts: options.pushHosts ?? [],
+  };
+  installed = runtime;
+  return () => {
+    if (installed === runtime) installed = undefined;
+  };
+}
+
+/** The installed runtime, or `X_PWA_PUSH_UNCONFIGURED` naming what tried to use it. */
+export function webPushRuntime(operation: string): WebPushRuntime {
+  if (installed === undefined) throw new PwaPushUnconfiguredError({ operation });
+  return installed;
+}
+
+/**
+ * The public half a browser subscribes with and the subject, or `undefined` when no runtime is
+ * installed — what the web role writes into `<meta name="x-push-key">` and gates `sw.js`'s push
+ * handler on.
+ */
+export const installedVapid = (): VapidConfig | undefined =>
+  installed === undefined
+    ? undefined
+    : { publicKey: installed.signer.publicKey, subject: installed.signer.subject };
+
+/** Test seam. */
+export function resetWebPush(): void {
+  installed = undefined;
+}

package/src/push-schema.ts

@@ -0,0 +1,27 @@
+// The DDL of Web Push's one framework table, and nothing else: a LEAF module, so the boot's
+// `FRAMEWORK_SCHEMA` (`@ultimat3/cli`) applies it in every role through `@ultimat3/pwa/schema`
+// without pulling the service-worker generator, the sender or `@ultimat3/action` into a worker's
+// or a migrate pod's module graph — `@ultimat3/mcp/schema`'s shape. Imports nothing, by design.
+
+/** The table. One name, read by this DDL and by `push-store-pg.ts`'s statements. */
+export const PUSH_SUBSCRIPTIONS_TABLE = 'x_push_subscriptions';
+
+/**
+ * Applied by the boot, never by an app migration; `if not exists` throughout, so every boot can.
+ * `endpoint` is the key (`push-store.ts` says why). `actor_id` is indexed because the one hot read
+ * is "every device of this person", once per notification sent.
+ */
+export const SQL_PUSH_SUBSCRIPTIONS_TABLE = `
+create table if not exists x_push_subscriptions (
+  endpoint        text        primary key,
+  actor_id        text        not null,
+  p256dh          text        not null,
+  auth            text        not null,
+  locale          text        not null,
+  time_zone       text        not null,
+  expiration_time bigint,
+  created_at      timestamptz not null default now()
+);
+
+create index if not exists x_push_subscriptions_actor_idx on x_push_subscriptions (actor_id);
+`;

package/src/push-send.ts

@@ -0,0 +1,191 @@
+// Single responsibility: ONE push message to ONE subscription — encrypt (RFC 8291), sign
+// (RFC 8292), POST (RFC 8030), and read the answer into one of three outcomes: delivered, gone, or
+// a coded refusal saying whether a retry can help.
+
+import type { Clock } from '@ultimat3/core';
+import {
+  classifyAddress,
+  isRetryableStatus,
+  renderThrowable,
+  retryAfterSecondsOf,
+} from '@ultimat3/core';
+import {
+  PwaPushFailedError,
+  PwaPushHostUnlistedError,
+  PwaPushRejectedError,
+  PwaPushSubscriptionInvalidError,
+} from './errors';
+import { encodeBase64Url } from './push-bytes';
+import type { PushEncryptionKeys } from './push-encrypt';
+import { encryptPushMessage } from './push-encrypt';
+import { pushHostAllowed } from './push-hosts';
+import { vapidAuthorization } from './vapid';
+
+/** RFC 8030 §5.3. `high` wakes a sleeping phone; reserve it for what a person is waiting on. */
+export const PUSH_URGENCIES = ['very-low', 'low', 'normal', 'high'] as const;
+export type PushUrgency = (typeof PUSH_URGENCIES)[number];
+
+/** A day. The push service drops an undelivered message after this — a stale alert is noise. */
+export const DEFAULT_PUSH_TTL_SECONDS = 86_400;
+
+/** How one message travels, as opposed to what it says. */
+export interface PushDelivery {
+  /** Seconds the push service holds the message for an offline device. 0 = now or never. */
+  readonly ttlSeconds?: number | undefined;
+  readonly urgency?: PushUrgency | undefined;
+  /**
+   * Collapse key AT THE PUSH SERVICE: a newer message with the same topic replaces one still
+   * queued for an offline device. Any string — it is sent as the first 32 characters of its
+   * SHA-256 in base64url, because the header admits exactly 32 URL-safe characters.
+   */
+  readonly topic?: string | undefined;
+}
+
+/** The signing half, resolved once per process: `push-runtime.ts` holds it. */
+export interface VapidSigner {
+  readonly keys: CryptoKeyPair;
+  readonly publicKey: string;
+  readonly subject: string;
+}
+
+export interface PushTarget {
+  readonly endpoint: string;
+  readonly keys: PushEncryptionKeys;
+}
+
+export interface PushSendInput {
+  readonly target: PushTarget;
+  /** The notification, serialized — `serializePushMessage`'s output, UTF-8 encoded. */
+  readonly plaintext: Uint8Array;
+  readonly vapid: VapidSigner;
+  readonly delivery?: PushDelivery | undefined;
+  readonly fetch?: typeof fetch | undefined;
+  readonly clock?: Clock | undefined;
+  readonly signal?: AbortSignal | undefined;
+  /** `pwa.vapid.pushHosts`: push services beyond the built-in list (`push-hosts.ts`). */
+  readonly pushHosts?: readonly string[] | undefined;
+}
+
+export type PushSendOutcome =
+  | { readonly kind: 'delivered'; readonly status: number }
+  /** 404/410: the subscription is dead. Delete it; never retry it. */
+  | { readonly kind: 'gone'; readonly status: 404 | 410 };
+
+/** How long one push service may take to answer before the fan-out moves on (retryable). */
+export const PUSH_SEND_TIMEOUT_MS = 30_000;
+
+/**
+ * `https:` to a host on the public internet — every push service a browser hands out is one. The
+ * endpoint came from a REQUEST BODY, so it is where a signed-in caller points this server: `http:`
+ * would send in the clear, and `localhost` or an IP literal that is not public (loopback, private,
+ * link-local, the metadata address) would make the server POST to its own side of the network.
+ * No carve-out for tests: a stub push service is an injected `fetch` over an `https:` URL.
+ */
+export function pushEndpointProblem(endpoint: string): string | undefined {
+  let url: URL;
+  try {
+    url = new URL(endpoint);
+  } catch {
+    return 'is not an absolute URL';
+  }
+  if (url.protocol !== 'https:') return 'is not an https URL';
+  const host = url.hostname.toLowerCase();
+  if (host === 'localhost' || host.endsWith('.localhost')) return 'names this machine';
+  const kind = classifyAddress(host);
+  if (kind !== undefined && kind !== 'public') return `is a ${kind} address`;
+  return undefined;
+}
+
+async function topicHeader(topic: string): Promise<string> {
+  const digest = new Uint8Array(
+    await crypto.subtle.digest('SHA-256', new TextEncoder().encode(topic)),
+  );
+  return encodeBase64Url(digest).slice(0, 32);
+}
+
+const ttlOf = (delivery: PushDelivery | undefined): number => {
+  const ttl = delivery?.ttlSeconds ?? DEFAULT_PUSH_TTL_SECONDS;
+  return Number.isFinite(ttl) && ttl >= 0 ? Math.floor(ttl) : DEFAULT_PUSH_TTL_SECONDS;
+};
+
+/**
+ * The screen an endpoint passes before it is stored and before every send: a well-formed public
+ * `https:` URL (`X_PWA_PUSH_SUBSCRIPTION_INVALID`) on a push service this app sends to
+ * (`X_PWA_PUSH_HOST_UNLISTED`). The list, not the name's shape, is what stops a hostname that
+ * resolves to a private address: shape alone is checked before DNS, and DNS answers the attacker.
+ */
+export function assertPushEndpoint(endpoint: string, pushHosts: readonly string[] = []): void {
+  const problem = pushEndpointProblem(endpoint);
+  if (problem !== undefined) {
+    throw new PwaPushSubscriptionInvalidError({ field: 'endpoint', reason: problem });
+  }
+  const host = new URL(endpoint).hostname;
+  if (!pushHostAllowed(host, pushHosts)) throw new PwaPushHostUnlistedError({ host });
+}
+
+/** Delivered, gone, or a coded throw: `X_PWA_PUSH_FAILED` (retry) / `X_PWA_PUSH_REJECTED` (don't). */
+export async function sendPushMessage(input: PushSendInput): Promise<PushSendOutcome> {
+  assertPushEndpoint(input.target.endpoint, input.pushHosts);
+  const origin = new URL(input.target.endpoint).origin;
+  const body = await encryptPushMessage(input.target.keys, input.plaintext);
+  const headers: Record<string, string> = {
+    authorization: await vapidAuthorization({
+      endpoint: input.target.endpoint,
+      subject: input.vapid.subject,
+      keys: input.vapid.keys,
+      publicKey: input.vapid.publicKey,
+      clock: input.clock,
+    }),
+    'content-encoding': 'aes128gcm',
+    'content-type': 'application/octet-stream',
+    ttl: String(ttlOf(input.delivery)),
+    urgency: input.delivery?.urgency ?? 'normal',
+  };
+  if (input.delivery?.topic !== undefined && input.delivery.topic !== '') {
+    headers['topic'] = await topicHeader(input.delivery.topic);
+  }
+  let response: Response;
+  try {
+    response = await (input.fetch ?? fetch)(input.target.endpoint, {
+      method: 'POST',
+      headers,
+      body,
+      // Never followed: a redirect would carry a token signed for one origin to another.
+      redirect: 'manual',
+      // A deadline: one service that accepts and never answers must not hold the rest of the
+      // fan-out — every later device of this person waits behind it.
+      signal:
+        input.signal === undefined
+          ? AbortSignal.timeout(PUSH_SEND_TIMEOUT_MS)
+          : AbortSignal.any([input.signal, AbortSignal.timeout(PUSH_SEND_TIMEOUT_MS)]),
+    });
+  } catch (error) {
+    // The CALLER cancelled: not the push service's fault, so not the retryable class — a retry
+    // would re-deliver to every device already served. Rethrown as is; the fan-out stops.
+    if (input.signal?.aborted === true) throw error;
+    throw new PwaPushFailedError({ origin, status: null, detail: renderThrowable(error) });
+  }
+  if (response.status >= 200 && response.status < 300) {
+    await response.body?.cancel();
+    return { kind: 'delivered', status: response.status };
+  }
+  if (response.status === 404 || response.status === 410) {
+    await response.body?.cancel();
+    return { kind: 'gone', status: response.status };
+  }
+  if (isRetryableStatus(response.status)) {
+    await response.body?.cancel();
+    throw new PwaPushFailedError({
+      origin,
+      status: response.status,
+      detail: `status ${response.status}`,
+      retryAfterSeconds: retryAfterSecondsOf(
+        response.headers.get('retry-after'),
+        response.headers.get('date'),
+      ),
+    });
+  }
+  // The service's own words, bounded: FCM and Mozilla both name the field they refused.
+  const text = (await response.text().catch(() => '')).slice(0, 200);
+  throw new PwaPushRejectedError({ origin, status: response.status, body: text });
+}

package/src/push-store-pg.ts

@@ -0,0 +1,86 @@
+// Single responsibility: push subscriptions in Postgres — `x_push_subscriptions`, a framework table
+// applied by the boot (`@ultimat3/cli`'s `FRAMEWORK_SCHEMA`) the way `x_jobs` and `x_notify_inbox`
+// are, never an `entity()` an app's `x db gen` would own. Statements are spelled out so the one in
+// a log is the one to run.
+
+import type { PgExecutor } from '@ultimat3/core';
+import type { PushSubscriptionRecord } from './push';
+import type { PushSubscriptionStore } from './push-store';
+
+/** A re-subscribe moves the endpoint to this actor and its new keys; `created_at` stays first. */
+const SQL_PUSH_SAVE = `
+insert into x_push_subscriptions
+  (endpoint, actor_id, p256dh, auth, locale, time_zone, expiration_time, created_at)
+values ($1, $2, $3, $4, $5, $6, $7, $8)
+on conflict (endpoint) do update set
+  actor_id = excluded.actor_id, p256dh = excluded.p256dh, auth = excluded.auth,
+  locale = excluded.locale, time_zone = excluded.time_zone,
+  expiration_time = excluded.expiration_time
+`;
+
+/** `collate "C"`: the memory store orders by code point, and one order is the contract. */
+const SQL_PUSH_LIST = `
+select endpoint, actor_id, p256dh, auth, locale, time_zone, expiration_time, created_at
+from x_push_subscriptions where actor_id = $1 order by endpoint collate "C"
+`;
+
+/** `$2` null deletes whoever holds it — the sender's 404/410; an unsubscribe names its owner. */
+const SQL_PUSH_REMOVE = `
+delete from x_push_subscriptions
+where endpoint = $1 and ($2::text is null or actor_id = $2)
+returning endpoint
+`;
+
+interface PushDbRow {
+  readonly endpoint: string;
+  readonly actor_id: string;
+  readonly p256dh: string;
+  readonly auth: string;
+  readonly locale: string;
+  readonly time_zone: string;
+  readonly expiration_time: number | string | null;
+  readonly created_at: Date | string;
+}
+
+const fromRow = (row: PushDbRow): PushSubscriptionRecord => ({
+  endpoint: row.endpoint,
+  keys: { p256dh: row.p256dh, auth: row.auth },
+  locale: row.locale,
+  timeZone: row.time_zone,
+  actorId: row.actor_id,
+  // `bigint` arrives as a string from some drivers; it is epoch milliseconds either way.
+  expirationTime: row.expiration_time === null ? null : Number(row.expiration_time),
+  createdAt: (row.created_at instanceof Date ? row.created_at : new Date(row.created_at)).getTime(),
+});
+
+export interface PostgresPushSubscriptionStoreOptions {
+  /** `@ultimat3/db`'s `dbExecutor()` — `Bun.sql` does not satisfy it. */
+  readonly executor: PgExecutor;
+}
+
+export function postgresPushSubscriptionStore(
+  options: PostgresPushSubscriptionStoreOptions,
+): PushSubscriptionStore {
+  const { executor } = options;
+  return {
+    async save(record) {
+      await executor.query(SQL_PUSH_SAVE, [
+        record.endpoint,
+        record.actorId,
+        record.keys.p256dh,
+        record.keys.auth,
+        record.locale,
+        record.timeZone,
+        record.expirationTime,
+        new Date(record.createdAt),
+      ]);
+    },
+    async listFor(actorId) {
+      return (await executor.query<PushDbRow>(SQL_PUSH_LIST, [actorId])).map(fromRow);
+    },
+    async remove(endpoint, actorId) {
+      const rows = await executor.query(SQL_PUSH_REMOVE, [endpoint, actorId ?? null]);
+      return rows.length > 0;
+    },
+  };
+}

package/src/push-store.ts

@@ -0,0 +1,54 @@
+// Single responsibility: where push subscriptions live — the seam, and the in-memory store a test
+// or a single process uses. The Postgres store is `push-store-pg.ts`.
+//
+// A subscription is keyed by its ENDPOINT, never by (actor, endpoint): one browser profile holds
+// one subscription, and when a second person signs in on that browser and subscribes, the
+// subscription is theirs now. Keyed by the pair, the first person would go on receiving the second
+// person's notifications on a device they no longer use.
+
+import type { PushSubscriptionRecord } from './push';
+
+export interface PushSubscriptionStore {
+  /** Insert, or hand an existing endpoint to this record's actor with its new keys and locale. */
+  save(record: PushSubscriptionRecord): Promise<void>;
+  /** Every subscription of one actor, ordered by endpoint (code point) — one order in both stores. */
+  listFor(actorId: string): Promise<readonly PushSubscriptionRecord[]>;
+  /**
+   * Delete one endpoint. With `actorId`, only when it is that actor's — an unsubscribe names its
+   * owner, so an endpoint somebody else holds is simply absent. Without, unconditionally — the
+   * sender's answer to a 404/410, which says the endpoint is dead whoever held it.
+   */
+  remove(endpoint: string, actorId?: string): Promise<boolean>;
+}
+
+const byEndpoint = (a: PushSubscriptionRecord, b: PushSubscriptionRecord): number =>
+  a.endpoint < b.endpoint ? -1 : a.endpoint > b.endpoint ? 1 : 0;
+
+/** One process's subscriptions. Lost on restart, which is the right fate for a test's. */
+export function memoryPushSubscriptionStore(): PushSubscriptionStore {
+  const rows = new Map<string, PushSubscriptionRecord>();
+  return {
+    save(record) {
+      const existing = rows.get(record.endpoint);
+      // The first `createdAt` survives a re-subscribe, as `on conflict do update` leaves it.
+      rows.set(
+        record.endpoint,
+        existing === undefined ? record : { ...record, createdAt: existing.createdAt },
+      );
+      return Promise.resolve();
+    },
+    listFor(actorId) {
+      return Promise.resolve(
+        [...rows.values()].filter((row) => row.actorId === actorId).sort(byEndpoint),
+      );
+    },
+    remove(endpoint, actorId) {
+      const row = rows.get(endpoint);
+      if (row === undefined || (actorId !== undefined && row.actorId !== actorId)) {
+        return Promise.resolve(false);
+      }
+      rows.delete(endpoint);
+      return Promise.resolve(true);
+    },
+  };
+}

package/src/skew.ts

@@ -0,0 +1,39 @@
+/**
+ * The PAGE's half of version skew: the message the generated worker posts on activation, and the
+ * comparison a page makes against its own build meta. Split from `version-skew.ts` (ids, retention)
+ * so the browser entry (`@ultimat3/pwa/client`) carries it with no error table and no server code.
+ */
+
+import type { APP_UPDATE_MESSAGE } from '@ultimat3/core/page';
+
+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;
+}

package/src/vapid-keys.ts

@@ -0,0 +1,72 @@
+// Single responsibility: which VAPID pair this process signs with — read from the environment, the
+// published development pair in development/test, and a refusal everywhere else.
+//
+// The cursor secret's rule, applied to a key pair (`@ultimat3/core`'s `devSecretsRefused`): a local
+// process works with no setup at all, and a deployed one that would sign with keys printed in this
+// file is refused at boot. Both halves come from the environment, never one from `app.config.ts`:
+// a public key in committed config and a private key per deploy are two places that can disagree,
+// and the disagreement is a 403 on every send.
+
+import { devSecretsRefused, timingSafeEqual } from '@ultimat3/core';
+import { PwaVapidKeyMissingError } from './errors';
+import type { VapidKeyPair } from './vapid';
+import { assertVapidPair, VAPID_PRIVATE_KEY_ENV, VAPID_PUBLIC_KEY_ENV } from './vapid';
+
+/**
+ * PUBLISHED, and so worthless outside one machine: the pair a development or test process signs
+ * with when neither variable is set. A subscription made against it lives in that machine's
+ * database. Refused by the boot anywhere `devSecretsRefused` holds, exactly as the dev cursor key is.
+ */
+export const DEV_VAPID_KEYS: VapidKeyPair = Object.freeze({
+  publicKey:
+    'BBwNsQrlkkkQ3pNRIpJVgq1VQk-Q6hG49IqxMDe-4X9Ks_5mUZcXb49zGt_vmJ1vNxy43CtF0CgANw8TXj6pA-c',
+  privateKey: 'qkWoagc9adrZnnpYJpI3kM9DjA8B_5qJkJj7Yi9izLM',
+});
+
+type EnvTable = Readonly<Record<string, string | undefined>>;
+
+const read = (env: EnvTable, key: string): string | undefined => {
+  const value = env[key]?.trim();
+  return value === undefined || value === '' ? undefined : value;
+};
+
+/**
+ * True while `env` would leave a process signing with `DEV_VAPID_KEYS`: neither variable set, or
+ * the published private key pasted back in. `x env check` and `x doctor` ask it of a deploy's table.
+ */
+export function usesDevVapidKeys(env: EnvTable): boolean {
+  const privateKey = read(env, VAPID_PRIVATE_KEY_ENV);
+  return privateKey === undefined || timingSafeEqual(privateKey, DEV_VAPID_KEYS.privateKey);
+}
+
+export interface ResolvedVapidKeys {
+  readonly keys: VapidKeyPair;
+  /** `'environment'` or `'development'` — logged once at boot, so a reader knows which pair. */
+  readonly source: 'environment' | 'development';
+}
+
+/**
+ * The pair, checked: both halves present (or neither, locally), each well-formed, and the private
+ * half signing for the public one. Half a pair is refused in EVERY environment — a developer who
+ * set one variable meant to set both, and silently signing with the dev pair would subscribe their
+ * browser to a key their production deploy never holds.
+ */
+export async function resolveVapidKeys(env: EnvTable): Promise<ResolvedVapidKeys> {
+  const publicKey = read(env, VAPID_PUBLIC_KEY_ENV);
+  const privateKey = read(env, VAPID_PRIVATE_KEY_ENV);
+  if (publicKey !== undefined && privateKey !== undefined) {
+    const keys = { publicKey, privateKey };
+    if (devSecretsRefused({ env }) && timingSafeEqual(privateKey, DEV_VAPID_KEYS.privateKey)) {
+      throw new PwaVapidKeyMissingError({ missing: [VAPID_PRIVATE_KEY_ENV], deployed: true });
+    }
+    await assertVapidPair(keys);
+    return { keys, source: 'environment' };
+  }
+  const missing = [
+    ...(publicKey === undefined ? [VAPID_PUBLIC_KEY_ENV] : []),
+    ...(privateKey === undefined ? [VAPID_PRIVATE_KEY_ENV] : []),
+  ];
+  const deployed = devSecretsRefused({ env });
+  if (missing.length === 1 || deployed) throw new PwaVapidKeyMissingError({ missing, deployed });
+  return { keys: DEV_VAPID_KEYS, source: 'development' };
+}