@ultimat3/notify 29.3.2 → 30.0.0

package/src/native-jwt.ts

@@ -0,0 +1,63 @@
+// Single responsibility: the two signed JWTs native push needs, over WebCrypto and nothing else —
+// APNs' ES256 provider token (a `.p8` key) and Google's RS256 service-account assertion. The key
+// arrives as a `Secret` and is revealed in exactly one place, the import below.
+
+import type { Secret } from '@ultimat3/core';
+import { revealSecret } from '@ultimat3/core';
+
+export type JwtAlgorithm = 'ES256' | 'RS256';
+
+/** A ternary over the closed pair, never a map read: `bun run proto-index` (`X_PROTO_CHAIN_INDEX`). */
+const importParams = (algorithm: JwtAlgorithm): EcKeyImportParams | RsaHashedImportParams =>
+  algorithm === 'ES256'
+    ? { name: 'ECDSA', namedCurve: 'P-256' }
+    : { name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-256' };
+
+/** WebCrypto's ECDSA output is raw `r || s`, which is exactly JWS ES256's encoding — no DER. */
+const signParams = (algorithm: JwtAlgorithm): AlgorithmIdentifier | EcdsaParams =>
+  algorithm === 'ES256' ? { name: 'ECDSA', hash: 'SHA-256' } : { name: 'RSASSA-PKCS1-v1_5' };
+
+const base64Url = (bytes: Uint8Array): string => Buffer.from(bytes).toString('base64url');
+
+const PEM_BODY = /-----BEGIN PRIVATE KEY-----([\s\S]+?)-----END PRIVATE KEY-----/;
+
+/**
+ * The DER inside a PKCS#8 PEM, or `undefined`. A key pasted into an env var often arrives with its
+ * newlines spelled `\n` (a JSON service-account file's `private_key`), so both spellings read.
+ */
+export function pkcs8Der(pem: string): Uint8Array<ArrayBuffer> | undefined {
+  const match = PEM_BODY.exec(pem.replaceAll('\\n', '\n'));
+  if (match?.[1] === undefined) return undefined;
+  const body = match[1].replace(/\s+/g, '');
+  if (!/^[A-Za-z0-9+/]+={0,2}$/.test(body)) return undefined;
+  return Uint8Array.from(Buffer.from(body, 'base64'));
+}
+
+/** Import a PKCS#8 key for signing, or `undefined` when it is no key of that algorithm. */
+export async function importSigningKey(
+  algorithm: JwtAlgorithm,
+  key: Secret,
+): Promise<CryptoKey | undefined> {
+  const der = pkcs8Der(revealSecret(key));
+  if (der === undefined) return undefined;
+  try {
+    return await crypto.subtle.importKey('pkcs8', der, importParams(algorithm), false, ['sign']);
+  } catch {
+    // The engine's message can quote key material; the caller names the variable instead.
+    return undefined;
+  }
+}
+
+/** `header.claims.signature`, each segment base64url JSON. */
+export async function signJwt(
+  algorithm: JwtAlgorithm,
+  key: CryptoKey,
+  header: Readonly<Record<string, string>>,
+  claims: Readonly<Record<string, string | number>>,
+): Promise<string> {
+  const text = new TextEncoder();
+  const segment = (value: object): string => base64Url(text.encode(JSON.stringify(value)));
+  const unsigned = `${segment({ ...header, alg: algorithm })}.${segment(claims)}`;
+  const signature = await crypto.subtle.sign(signParams(algorithm), key, text.encode(unsigned));
+  return `${unsigned}.${base64Url(new Uint8Array(signature))}`;
+}

package/src/native-push.ts

@@ -0,0 +1,173 @@
+// Single responsibility: `nativePush()`, the APNs + FCM transport as one `Pusher` — every device a
+// person registered, each in its own locale, dead tokens deleted, refusals coded. It satisfies
+// `pushChannel({ pusher })` for a visible push and `pushChannel({ pusher, data })` for a data-only
+// one, which `webPush()` cannot (a browser push always shows) — so that mistake is a type error.
+
+import type { Clock } from '@ultimat3/core';
+import { finiteCount, isUltimateError, logger, systemClock } from '@ultimat3/core';
+import type { OutboundFetch } from '@ultimat3/core/outbound';
+import { translatorFor } from '@ultimat3/i18n';
+import type { ApnsOptions } from './apns';
+import { apnsSender } from './apns';
+import type { DataPusher, NotifyPushMessage, Pusher } from './channel-push';
+import type { FcmOptions } from './fcm';
+import { fcmSender } from './fcm';
+import { platformFetch } from './native-transport';
+import type { PushDeviceStore, PushPlatform } from './push-device';
+import { isDeviceToken } from './push-device';
+import type { NativePush, NativeSender, PushData, PushTranslate } from './push-message';
+import { renderNativePush, screenPushData } from './push-message';
+
+export const DEFAULT_NATIVE_PUSH_DEADLINE_MS = 10_000;
+
+/**
+ * Bad-token answers in a row (APNs `BadDeviceToken`, FCM `INVALID_ARGUMENT` on `message.token`)
+ * that delete a device. Never 1: `BadDeviceToken` is also a sandbox build's token sent to
+ * production, and a delivery in between starts the count again.
+ */
+export const PUSH_BAD_TOKEN_LIMIT = 3;
+
+export interface NativePushOptions {
+  /** The registrations `pushRegister()` writes — the same store, handed to both. */
+  readonly devices: PushDeviceStore;
+  /** iOS devices. Absent, an `ios` registration is skipped with a warning. */
+  readonly apns?: ApnsOptions | undefined;
+  /** Android devices. Absent, an `android` registration is skipped with a warning. */
+  readonly fcm?: FcmOptions | undefined;
+  /** Each provider call, retries included. Default `DEFAULT_NATIVE_PUSH_DEADLINE_MS`. */
+  readonly deadlineMs?: number | undefined;
+  /** Test seams: the fake provider, the environment the keys are read from, the clock. */
+  readonly fetch?: OutboundFetch | undefined;
+  readonly env?: Readonly<Record<string, string | undefined>> | undefined;
+  readonly clock?: Clock | undefined;
+  readonly translate?: ((locale: string) => PushTranslate) | undefined;
+}
+
+/** Both seams, each answering a promise: a send settles once every device was tried. */
+export interface NativePusher extends Pusher, DataPusher {
+  send(push: Parameters<Pusher['send']>[0]): Promise<void>;
+  sendData(push: Parameters<DataPusher['sendData']>[0]): Promise<void>;
+}
+
+/** The message for one device, in that device's locale. */
+type PushFor = (locale: string) => NativePush;
+
+type Senders = ReadonlyMap<PushPlatform, NativeSender>;
+
+const metaOf = (error: { readonly meta?: Readonly<Record<string, unknown>> | undefined }) =>
+  error.meta ?? {};
+
+/**
+ * Every device of `to`, in `(platform, token)` order. A dead token is deleted; a token the
+ * provider cannot parse is deleted on its `PUSH_BAD_TOKEN_LIMIT`th answer in a row; a refusal for
+ * good is logged with its code and the next device tried; a blip (a 5xx, a 429, a timeout) is
+ * rethrown AFTER every other device was tried, for the job's retry. A CREDENTIAL refusal ends that
+ * provider's fan-out on the spot and is thrown — every other device would be refused alike, each
+ * after a re-sign Apple throttles. When no device took it and one refused, the first refusal is
+ * thrown: a delivery nothing accepted must fail, not settle as sent.
+ */
+async function eachDevice(
+  devices: PushDeviceStore,
+  senders: Senders,
+  push: { readonly to: string; readonly signal: AbortSignal; readonly message: PushFor },
+): Promise<void> {
+  let delivered = 0;
+  let retry: unknown;
+  let refusal: unknown;
+  let credential: unknown;
+  const stopped = new Set<PushPlatform>();
+  for (const device of await devices.listFor(push.to)) {
+    if (stopped.has(device.platform)) continue;
+    const sender = senders.get(device.platform);
+    if (sender === undefined) {
+      logger.warn('notify.push.unconfigured', {
+        platform: device.platform,
+        fix: `nativePush({ ${device.platform === 'ios' ? 'apns' : 'fcm'}: { … } })   # or drop '${device.platform}' from pushRegister({ platforms })`,
+      });
+      continue;
+    }
+    // A stored token no provider could take is a row no send will ever reach.
+    if (!isDeviceToken(device.platform, device.token)) {
+      await devices.remove(device.platform, device.token);
+      continue;
+    }
+    try {
+      await sender.send(device.token, push.message(device.locale), push.signal);
+      delivered += 1;
+      if ((device.badTokens ?? 0) > 0) await devices.clearBadToken(device.platform, device.token);
+    } catch (error) {
+      if (!isUltimateError(error) || !error.code.startsWith('X_NOTIFY_PUSH_')) {
+        retry ??= error;
+        continue;
+      }
+      if (error.code === 'X_NOTIFY_PUSH_DEVICE_GONE') {
+        await devices.remove(device.platform, device.token);
+        logger.info('notify.push.gone', { code: error.code, cause: error.cause });
+        continue;
+      }
+      logger.error('notify.push.refused', { code: error.code, cause: error.cause, fix: error.fix });
+      const meta = metaOf(error);
+      if (meta['credential'] === true) {
+        stopped.add(device.platform);
+        credential ??= error;
+        continue;
+      }
+      refusal ??= error;
+      if (
+        meta['badToken'] === true &&
+        (await devices.noteBadToken(device.platform, device.token)) >= PUSH_BAD_TOKEN_LIMIT
+      ) {
+        await devices.remove(device.platform, device.token);
+        logger.info('notify.push.bad_token_removed', { code: error.code, cause: error.cause });
+      }
+    }
+  }
+  if (credential !== undefined) throw credential;
+  if (retry !== undefined) throw retry;
+  if (delivered === 0 && refusal !== undefined) throw refusal;
+}
+
+/**
+ * `pushChannel({ pusher: nativePush({ devices, apns: { teamId, keyId, topic }, fcm: { projectId,
+ * clientEmail } }), message })`. The private keys are never options: they are read from
+ * `ULTIMATE_APNS_PRIVATE_KEY` / `ULTIMATE_FCM_PRIVATE_KEY` (`x secrets set …`) when a token is
+ * minted, boxed in a `Secret` at once, and signed with through WebCrypto.
+ */
+export function nativePush(options: NativePushOptions): NativePusher {
+  const deps = {
+    fetch: options.fetch ?? platformFetch,
+    env: options.env ?? Bun.env,
+    clock: options.clock ?? systemClock,
+    deadlineMs: finiteCount(
+      'nativePush()',
+      'deadlineMs',
+      options.deadlineMs ?? DEFAULT_NATIVE_PUSH_DEADLINE_MS,
+      1,
+    ),
+  };
+  const senders = new Map<PushPlatform, NativeSender>();
+  if (options.apns !== undefined) senders.set('ios', apnsSender(options.apns, deps));
+  if (options.fcm !== undefined) senders.set('android', fcmSender(options.fcm, deps));
+  const translate = options.translate ?? ((locale: string) => translatorFor(locale));
+  return {
+    send({ to, message, signal }: { to: string; message: NotifyPushMessage; signal: AbortSignal }) {
+      return eachDevice(options.devices, senders, {
+        to,
+        signal,
+        message: (locale) => ({
+          kind: 'alert',
+          push: renderNativePush(message, translate(locale)),
+        }),
+      });
+    },
+    sendData({ to, data, signal }: { to: string; data: PushData; signal: AbortSignal }) {
+      // Screened once, before any device: a refusal here is the notifier's, not a provider's.
+      const screened = screenPushData(data);
+      return eachDevice(options.devices, senders, {
+        to,
+        signal,
+        message: () => ({ kind: 'data', data: screened }),
+      });
+    },
+  };
+}

package/src/native-transport.ts

@@ -0,0 +1,99 @@
+// Single responsibility: what the APNs and FCM senders share — the injected seams, the private key
+// read out of the environment (where `x secrets` puts it) straight into a `Secret` box, and a coded
+// `outbound()` refusal read back into a status and the provider's reason.
+
+import type { Clock } from '@ultimat3/core';
+import { ConfigInvalidError, EnvMissingError, isUltimateError, secret } from '@ultimat3/core';
+import type { OutboundFetch, OutboundInit } from '@ultimat3/core/outbound';
+import { importSigningKey } from './native-jwt';
+import type { PushProvider } from './push-errors';
+
+export interface NativeTransportDeps {
+  /** "Just the call" — the platform's `fetch` unless a test hands its fake provider. */
+  readonly fetch: OutboundFetch;
+  /** Where the private keys are read, per mint. `Bun.env` unless a test hands its own. */
+  readonly env: Readonly<Record<string, string | undefined>>;
+  readonly clock: Clock;
+  /** The whole call to the provider, retries included. */
+  readonly deadlineMs: number;
+}
+
+/** The platform's `fetch`, read per call so a test's sealed network sees it. */
+export const platformFetch: OutboundFetch = (url, init) => fetch(url, init);
+
+/**
+ * APNs speaks HTTP/2 only; an HTTP/1.1 request is a malformed response. Bun's `fetch` negotiates it
+ * when asked, so the transport asks on every APNs hop.
+ */
+export const http2 =
+  (base: OutboundFetch): OutboundFetch =>
+  (url, init) =>
+    base(url, Object.assign({}, init, { protocol: 'http2' }) satisfies OutboundInit);
+
+/** Where each provider's private key is read from — `x secrets set <name>` puts it there. */
+export const APNS_KEY_ENV = 'ULTIMATE_APNS_PRIVATE_KEY';
+export const FCM_KEY_ENV = 'ULTIMATE_FCM_PRIVATE_KEY';
+
+/** Spelled per provider rather than interpolated: a `fix:` names its command whole. */
+const SET_APNS_KEY =
+  'x secrets set ULTIMATE_APNS_PRIVATE_KEY   # paste the .p8 file whole, BEGIN and END lines included; a real environment variable of that name wins';
+const SET_FCM_KEY =
+  'x secrets set ULTIMATE_FCM_PRIVATE_KEY   # paste the service-account private_key whole, BEGIN and END lines included; a real environment variable of that name wins';
+
+/** The provider's signing key, imported — or the refusal naming its variable, never its value. */
+export async function signingKeyFrom(
+  env: NativeTransportDeps['env'],
+  provider: PushProvider,
+): Promise<CryptoKey> {
+  const apns = provider === 'apns';
+  const variable = apns ? APNS_KEY_ENV : FCM_KEY_ENV;
+  const fix = apns ? SET_APNS_KEY : SET_FCM_KEY;
+  const raw = env[variable];
+  if (raw === undefined || raw.trim() === '') {
+    throw new EnvMissingError({
+      cause: `nativePush() needs ${variable} to sign its ${provider} token, and the environment has none`,
+      fix,
+      meta: { variable },
+    });
+  }
+  const key = await importSigningKey(apns ? 'ES256' : 'RS256', secret(raw, variable));
+  if (key === undefined) {
+    throw new ConfigInvalidError({
+      cause: `${variable} is not a PKCS#8 ${apns ? 'P-256 (.p8)' : 'RSA'} private key`,
+      fix,
+      meta: { variable },
+    });
+  }
+  return key;
+}
+
+/** A provider's refusal as `outbound()` coded it: the status, and the JSON body it kept. */
+export interface ProviderRefusal {
+  readonly status: number;
+  readonly body: Readonly<Record<string, unknown>> | undefined;
+  /** The redacted text itself — read when a long body was cut and no longer parses. */
+  readonly detail: string;
+}
+
+/**
+ * `X_OUTBOUND_REFUSED`'s status and `meta.detail` (a redacted JSON object, 200 characters at most —
+ * so a cut one parses to nothing and the status alone decides). Anything else is `undefined`: a
+ * 5xx, a 429 or a timeout is the provider's blip and is rethrown for the job's retry.
+ */
+export function refusalOf(error: unknown): ProviderRefusal | undefined {
+  if (!isUltimateError(error) || error.code !== 'X_OUTBOUND_REFUSED') return undefined;
+  const status = error.meta?.['status'];
+  if (typeof status !== 'number') return undefined;
+  const raw = error.meta?.['detail'];
+  const detail = typeof raw === 'string' ? raw : '';
+  let body: Record<string, unknown> | undefined;
+  try {
+    const parsed: unknown = detail === '' ? null : JSON.parse(detail);
+    if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) {
+      body = parsed as Record<string, unknown>;
+    }
+  } catch {
+    body = undefined;
+  }
+  return { status, body, detail };
+}

package/src/notifier.ts

@@ -13,7 +13,7 @@ import { finiteCount } from '@ultimat3/core';
 import type { JobHandle, JobTenant, RetryPolicy } from '@ultimat3/jobs';
 import { DEFAULT_RETRY, job } from '@ultimat3/jobs';
 import type { Schema } from '@ultimat3/schema';
-import { t } from '@ultimat3/schema';
+import { parse, t } from '@ultimat3/schema';
 import { isBulkChannel } from './channel';
 import {
   NotifyChannelDuplicateError,
@@ -142,6 +142,7 @@ export function notifier<Params>(
     ),
     deliveries,
     keyFor: (params) => definition.key(params),
+    parseParams: (raw) => parse(definition.input, raw) as Params,
     // Bound to the definition rather than torn off it, so an author who writes `recipients` as a
     // method rather than an arrow still gets the right `this`. An enqueue that names no audience
     // and a notifier that resolves none is an empty fan-out, not an error: a broadcast with no

package/src/plan.ts

@@ -107,6 +107,8 @@ export interface NotifyPlan<Params> {
    * channel with no wait fires immediately even when a later one waits an hour. */
   readonly deliveries: readonly ResolvedDelivery<Params>[];
   keyFor(params: Params): string;
+  /** The notifier's `input`, for params read back out of a store or a step in their stored form. */
+  parseParams(raw: unknown): Params;
   recipientsFor(args: RecipientArgs<Params>): Promise<readonly Recipient[]> | readonly Recipient[];
 }
 

package/src/push-device-pg.ts

@@ -0,0 +1,126 @@
+// Single responsibility: native push devices in Postgres — `x_push_devices`, a framework table
+// applied by the boot (`@ultimat3/cli`'s `FRAMEWORK_SCHEMA`) the way `x_notify_inbox` is, 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 { PushDeviceRecord, PushDeviceStore, PushPlatform } from './push-device';
+
+/** The table. One name, read by this DDL and by the statements below. */
+export const PUSH_DEVICES_TABLE = 'x_push_devices';
+
+/**
+ * Applied by the boot, never by an app migration; `if not exists` throughout, so every boot can.
+ * `(platform, token)` is the key (`push-device.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_DEVICES_TABLE = `
+create table if not exists x_push_devices (
+  platform   text        not null check (platform in ('ios', 'android')),
+  token      text        not null,
+  actor_id   text        not null,
+  locale     text        not null,
+  time_zone  text        not null,
+  created_at timestamptz not null default now(),
+  bad_tokens integer     not null default 0,
+  primary key (platform, token)
+);
+
+alter table x_push_devices add column if not exists bad_tokens integer not null default 0;
+
+create index if not exists x_push_devices_actor_idx on x_push_devices (actor_id);
+`;
+
+/** A re-register moves the token to this actor and its locale; `created_at` and `bad_tokens` stay. */
+export const SQL_PUSH_DEVICE_SAVE = `
+insert into x_push_devices (platform, token, actor_id, locale, time_zone, created_at)
+values ($1, $2, $3, $4, $5, $6)
+on conflict (platform, token) do update set
+  actor_id = excluded.actor_id, locale = excluded.locale, time_zone = excluded.time_zone
+`;
+
+/** `collate "C"`: the memory store orders by code point, and one order is the contract. */
+export const SQL_PUSH_DEVICE_LIST = `
+select platform, token, actor_id, locale, time_zone, created_at, bad_tokens
+from x_push_devices where actor_id = $1
+order by platform collate "C", token collate "C"
+`;
+
+/** `$3` null deletes whoever holds it — the sender's dead token; an unregister names its owner. */
+export const SQL_PUSH_DEVICE_REMOVE = `
+delete from x_push_devices
+where platform = $1 and token = $2 and ($3::text is null or actor_id = $3)
+returning token
+`;
+
+/** One more bad-token answer; no row answers no count, which the sender reads as 0. */
+export const SQL_PUSH_DEVICE_BAD_TOKEN = `
+update x_push_devices set bad_tokens = bad_tokens + 1
+where platform = $1 and token = $2
+returning bad_tokens
+`;
+
+/** Only a row that has a count is written: a delivery to a healthy device costs no write. */
+export const SQL_PUSH_DEVICE_BAD_TOKEN_CLEAR = `
+update x_push_devices set bad_tokens = 0
+where platform = $1 and token = $2 and bad_tokens > 0
+`;
+
+interface DeviceDbRow {
+  readonly platform: PushPlatform;
+  readonly token: string;
+  readonly actor_id: string;
+  readonly locale: string;
+  readonly time_zone: string;
+  readonly created_at: Date | string;
+  readonly bad_tokens: number | string;
+}
+
+const fromRow = (row: DeviceDbRow): PushDeviceRecord => ({
+  platform: row.platform,
+  token: row.token,
+  actorId: row.actor_id,
+  locale: row.locale,
+  timeZone: row.time_zone,
+  createdAt: (row.created_at instanceof Date ? row.created_at : new Date(row.created_at)).getTime(),
+  // Absent at 0, as the memory store leaves it: one record shape from both.
+  ...(Number(row.bad_tokens) > 0 ? { badTokens: Number(row.bad_tokens) } : {}),
+});
+
+export interface PostgresPushDeviceStoreOptions {
+  /** `@ultimat3/db`'s `dbExecutor()` — `Bun.sql` does not satisfy it. */
+  readonly executor: PgExecutor;
+}
+
+export function postgresPushDeviceStore(options: PostgresPushDeviceStoreOptions): PushDeviceStore {
+  const { executor } = options;
+  return {
+    async save(record) {
+      await executor.query(SQL_PUSH_DEVICE_SAVE, [
+        record.platform,
+        record.token,
+        record.actorId,
+        record.locale,
+        record.timeZone,
+        new Date(record.createdAt),
+      ]);
+    },
+    async listFor(actorId) {
+      return (await executor.query<DeviceDbRow>(SQL_PUSH_DEVICE_LIST, [actorId])).map(fromRow);
+    },
+    async remove(platform, token, actorId) {
+      const rows = await executor.query(SQL_PUSH_DEVICE_REMOVE, [platform, token, actorId ?? null]);
+      return rows.length > 0;
+    },
+    async noteBadToken(platform, token) {
+      const rows = await executor.query<{ bad_tokens: number | string }>(
+        SQL_PUSH_DEVICE_BAD_TOKEN,
+        [platform, token],
+      );
+      return rows[0] === undefined ? 0 : Number(rows[0].bad_tokens);
+    },
+    async clearBadToken(platform, token) {
+      await executor.query(SQL_PUSH_DEVICE_BAD_TOKEN_CLEAR, [platform, token]);
+    },
+  };
+}

package/src/push-device.ts

@@ -0,0 +1,125 @@
+// Single responsibility: what one native device registration is — its platform, its token's
+// shape, the store seam it lives behind, and the in-memory store a test or a single process uses.
+// The Postgres store is `push-device-pg.ts`.
+//
+// A device is keyed by `(platform, token)`, never by actor: a token names one app install, and when
+// a second person signs in on that phone the registration is theirs now — keyed by the actor too,
+// the first person would go on receiving the second person's notifications.
+
+/** The two native transports `nativePush()` speaks: APNs for `ios`, FCM for `android`. */
+export const PUSH_PLATFORMS = ['ios', 'android'] as const;
+
+export type PushPlatform = (typeof PUSH_PLATFORMS)[number];
+
+/**
+ * An APNs device token is hex — 32 bytes today, and Apple says it may grow, so up to 100. It is
+ * spliced into the APNs URL PATH, so anything else is refused rather than escaped: a token is
+ * never a place a `/` or a `?` reaches the provider from.
+ */
+export const APNS_TOKEN = /^(?:[0-9a-fA-F]{2}){32,100}$/;
+
+/** An FCM registration token: URL-safe base64 with `:` and `-`, 4 KiB at most. */
+export const FCM_TOKEN = /^[A-Za-z0-9_:.-]{32,4096}$/;
+
+/** Whether `token` is one `platform`'s provider could ever accept — read at register AND send. */
+export const isDeviceToken = (platform: PushPlatform, token: string): boolean =>
+  (platform === 'ios' ? APNS_TOKEN : FCM_TOKEN).test(token);
+
+/** One app install's registration. Tokens are stored lowercase for `ios`, as APNs reads them. */
+export interface PushDeviceRecord {
+  readonly platform: PushPlatform;
+  readonly token: string;
+  readonly actorId: string;
+  /** BCP-47 — a visible push to this device renders in it. */
+  readonly locale: string;
+  /** IANA — the zone a push formatting a date would need. */
+  readonly timeZone: string;
+  /** Epoch ms of the first registration; a re-register keeps it. */
+  readonly createdAt: number;
+  /**
+   * Bad-token answers in a row (`noteBadToken`), present only when above 0 — a store writes it,
+   * a caller of `save` never does, and a re-register keeps it: the token is no better for it.
+   */
+  readonly badTokens?: number | undefined;
+}
+
+export interface PushDeviceStore {
+  /** Insert, or hand an existing `(platform, token)` to this record's actor and locale. */
+  save(record: PushDeviceRecord): Promise<void>;
+  /** Every device of one actor, ordered `(platform, token)` by code point in both stores. */
+  listFor(actorId: string): Promise<readonly PushDeviceRecord[]>;
+  /**
+   * Delete one device. With `actorId`, only when it is that actor's — an unregister names its
+   * owner, so a token somebody else holds is simply absent. Without, unconditionally — the
+   * sender's answer to a provider saying the token is dead, whoever held it.
+   */
+  remove(platform: PushPlatform, token: string, actorId?: string): Promise<boolean>;
+  /** One more bad-token answer for this device; the count after it, `0` when there is no row. */
+  noteBadToken(platform: PushPlatform, token: string): Promise<number>;
+  /** It delivered: the bad-token answers before it were not in a row after all. */
+  clearBadToken(platform: PushPlatform, token: string): Promise<void>;
+}
+
+const keyOf = (platform: PushPlatform, token: string): string => `${platform}\u0000${token}`;
+
+const byDevice = (a: PushDeviceRecord, b: PushDeviceRecord): number => {
+  const left = keyOf(a.platform, a.token);
+  const right = keyOf(b.platform, b.token);
+  return left < right ? -1 : left > right ? 1 : 0;
+};
+
+/** One process's devices. Lost on restart, which is the right fate for a test's. */
+export function memoryPushDeviceStore(): PushDeviceStore {
+  const rows = new Map<string, PushDeviceRecord>();
+  return {
+    save(record) {
+      const key = keyOf(record.platform, record.token);
+      const existing = rows.get(key);
+      // The first `createdAt` and the bad-token count survive a re-register, as `on conflict do
+      // update` leaves both.
+      const { badTokens: _ignored, ...fields } = record;
+      rows.set(
+        key,
+        existing === undefined
+          ? fields
+          : {
+              ...fields,
+              createdAt: existing.createdAt,
+              ...(existing.badTokens === undefined ? {} : { badTokens: existing.badTokens }),
+            },
+      );
+      return Promise.resolve();
+    },
+    noteBadToken(platform, token) {
+      const key = keyOf(platform, token);
+      const row = rows.get(key);
+      if (row === undefined) return Promise.resolve(0);
+      const badTokens = (row.badTokens ?? 0) + 1;
+      rows.set(key, { ...row, badTokens });
+      return Promise.resolve(badTokens);
+    },
+    clearBadToken(platform, token) {
+      const key = keyOf(platform, token);
+      const row = rows.get(key);
+      if (row !== undefined) {
+        const { badTokens: _cleared, ...rest } = row;
+        rows.set(key, rest);
+      }
+      return Promise.resolve();
+    },
+    listFor(actorId) {
+      return Promise.resolve(
+        [...rows.values()].filter((row) => row.actorId === actorId).sort(byDevice),
+      );
+    },
+    remove(platform, token, actorId) {
+      const key = keyOf(platform, token);
+      const row = rows.get(key);
+      if (row === undefined || (actorId !== undefined && row.actorId !== actorId)) {
+        return Promise.resolve(false);
+      }
+      rows.delete(key);
+      return Promise.resolve(true);
+    },
+  };
+}