@ultimat3/notify 29.3.2 → 30.0.0

package/src/push-errors.ts

@@ -0,0 +1,83 @@
+// Single responsibility: the native push transport's three refusals. Registered with the rest of
+// the package's codes in `errors.ts`; here so that file stays the fan-out's. No cause ever carries
+// a device token, a credential or a message body — only the provider, its status and its reason.
+
+import { UltimateError } from '@ultimat3/core';
+
+export type PushProvider = 'apns' | 'fcm';
+
+/** The provider's reason word (`Unregistered`, `UNREGISTERED`), or `unknown` — never free text. */
+export const providerReason = (value: unknown): string =>
+  typeof value === 'string' && /^[A-Za-z_]{1,64}$/.test(value) ? value : 'unknown';
+
+/**
+ * The provider says this token names no install any more: APNs 410, FCM `UNREGISTERED`. Thrown by
+ * one device's send and caught by `nativePush()`, which deletes the row and logs this — so it
+ * never fails a delivery, and the next notification does not pay for the dead device again.
+ */
+export class NotifyPushDeviceGoneError extends UltimateError {
+  constructor(input: { provider: PushProvider; status: number; reason: string }) {
+    super({
+      code: 'X_NOTIFY_PUSH_DEVICE_GONE',
+      cause: `${input.provider} answered ${String(input.status)} (${input.reason}) for a device token: the app was uninstalled, or the device rotated its token`,
+      fix: 'x jobs list --json   # nothing to repair: the dead device row is already deleted, and the app stores its new token with its next pushRegister() call',
+      meta: { provider: input.provider, status: input.status, reason: input.reason },
+    });
+  }
+}
+
+/** Spelled per provider rather than interpolated: a `fix:` names its command whole. */
+const APNS_CREDENTIAL_FIX =
+  "x secrets set ULTIMATE_APNS_PRIVATE_KEY   # with the team's current .p8 key, and check teamId, keyId and topic on nativePush({ apns })";
+const FCM_CREDENTIAL_FIX =
+  "x secrets set ULTIMATE_FCM_PRIVATE_KEY   # with the service account's current private_key, and check projectId and clientEmail on nativePush({ fcm })";
+
+const REQUEST_FIX =
+  'x jobs list --json   # read meta.reason on the failed step, then fix the topic, project or message nativePush() was given';
+
+/**
+ * A refusal the same request gets again: a credential, a topic or project, a payload limit.
+ * `meta.credential` (a 401/403, or Google refusing the assertion) ends that provider's fan-out in
+ * `nativePush()`: every other device would be refused the same way, each after a re-sign.
+ * `meta.badToken` (APNs `BadDeviceToken`, FCM `INVALID_ARGUMENT` on `message.token`) counts
+ * against that one device row.
+ */
+export class NotifyPushProviderRefusedError extends UltimateError {
+  constructor(input: {
+    provider: PushProvider;
+    status: number;
+    reason: string;
+    credential?: boolean | undefined;
+    badToken?: boolean | undefined;
+  }) {
+    const credential = input.credential ?? (input.status === 401 || input.status === 403);
+    super({
+      code: 'X_NOTIFY_PUSH_PROVIDER_REFUSED',
+      cause: `${input.provider} answered ${String(input.status)} (${input.reason}), and the same request will be refused again`,
+      fix: credential
+        ? input.provider === 'apns'
+          ? APNS_CREDENTIAL_FIX
+          : FCM_CREDENTIAL_FIX
+        : REQUEST_FIX,
+      meta: {
+        provider: input.provider,
+        status: input.status,
+        reason: input.reason,
+        credential,
+        badToken: input.badToken === true,
+      },
+    });
+  }
+}
+
+/** A data-only push carrying more than an id: a reserved key, too many keys, a long value. */
+export class NotifyPushMessageInvalidError extends UltimateError {
+  constructor(input: { problem: string }) {
+    super({
+      code: 'X_NOTIFY_PUSH_MESSAGE_INVALID',
+      cause: `the data of a data-only push ${input.problem}; it travels through the provider, so it carries ids and nothing a person would read`,
+      fix: 'pushChannel({ pusher, data: ({ event }) => ({ id: event.params.id }) })   # in the notifier: one id per push, the app fetches the rest over its API',
+      meta: { problem: input.problem },
+    });
+  }
+}

package/src/push-message.ts

@@ -0,0 +1,109 @@
+// Single responsibility: what a native push SAYS, before any provider's wire shape — a visible one
+// rendered from catalog keys in the device's locale, or a data-only one screened down to ids. The
+// APNs and FCM bodies are built from this and from nothing else, so nothing else can leave.
+
+import { finiteCount } from '@ultimat3/core';
+import type { NotifyPushMessage } from './channel-push';
+import { NotifyPushMessageInvalidError } from './push-errors';
+
+/** A data-only push's payload: string ids, never content. */
+export type PushData = Readonly<Record<string, string>>;
+
+export const DATA_PUSH_MAX_KEYS = 8;
+export const DATA_PUSH_MAX_VALUE = 256;
+/** The default hold for an offline device, as the web channel's: one day. */
+export const DEFAULT_PUSH_TTL_SECONDS = 86_400;
+
+const DATA_KEY = /^[A-Za-z][A-Za-z0-9_]{0,63}$/;
+
+/**
+ * Keys a provider owns. `aps` would overwrite APNs' own dictionary, and FCM refuses the rest with a
+ * 400 — refused here, before a send, with the key named.
+ */
+const RESERVED = new Set(['aps', 'from', 'notification', 'message_type', 'collapse_key', 'ttl']);
+const RESERVED_PREFIX = /^(?:google|gcm)/i;
+
+/** `data` as the wire may carry it, or `X_NOTIFY_PUSH_MESSAGE_INVALID` naming what is wrong. */
+export function screenPushData(data: unknown): PushData {
+  if (typeof data !== 'object' || data === null || Array.isArray(data)) {
+    throw new NotifyPushMessageInvalidError({ problem: 'is not an object of strings' });
+  }
+  const entries = Object.entries(data);
+  if (entries.length === 0) {
+    throw new NotifyPushMessageInvalidError({ problem: 'is empty, so the app wakes to nothing' });
+  }
+  if (entries.length > DATA_PUSH_MAX_KEYS) {
+    throw new NotifyPushMessageInvalidError({
+      problem: `holds ${String(entries.length)} keys and at most ${String(DATA_PUSH_MAX_KEYS)} are allowed`,
+    });
+  }
+  const screened = new Map<string, string>();
+  for (const [key, value] of entries) {
+    if (!DATA_KEY.test(key)) {
+      throw new NotifyPushMessageInvalidError({ problem: 'names a key that is not an identifier' });
+    }
+    if (RESERVED.has(key) || RESERVED_PREFIX.test(key)) {
+      throw new NotifyPushMessageInvalidError({
+        problem: `names the provider-reserved key "${key}"`,
+      });
+    }
+    if (typeof value !== 'string' || value.length > DATA_PUSH_MAX_VALUE) {
+      throw new NotifyPushMessageInvalidError({
+        problem: `holds "${key}" as something other than a string of at most ${String(DATA_PUSH_MAX_VALUE)} characters`,
+      });
+    }
+    screened.set(key, value);
+  }
+  return Object.freeze(Object.fromEntries(screened));
+}
+
+/** Renders one catalog key; `@ultimat3/i18n`'s `translatorFor(locale)` unless a test hands one. */
+export type PushTranslate = (
+  key: string,
+  params?: Readonly<Record<string, string | number>>,
+) => string;
+
+/** A visible push as both providers read it: text in one locale, plus how it travels. */
+export interface RenderedNativePush {
+  readonly title: string;
+  readonly body: string;
+  readonly url: string;
+  /** Replaces an earlier notification carrying it — `topic`, else `tag`. */
+  readonly collapse: string | undefined;
+  readonly ttlSeconds: number;
+  readonly urgent: boolean;
+}
+
+/**
+ * The web-only fields (`icon`, `badge`, `actions`, `requireInteraction`, `renotify`) have no
+ * native meaning here and are not sent: an app's native shell decides how its alerts look.
+ */
+export function renderNativePush(
+  message: NotifyPushMessage,
+  translate: PushTranslate,
+): RenderedNativePush {
+  const collapse = message.topic ?? message.tag;
+  return {
+    title: translate(message.titleKey, message.params),
+    body: translate(message.bodyKey, message.params),
+    url: message.url,
+    collapse: collapse === undefined || collapse === '' ? undefined : collapse,
+    ttlSeconds: finiteCount(
+      'pushChannel()',
+      'ttlSeconds',
+      message.ttlSeconds ?? DEFAULT_PUSH_TTL_SECONDS,
+    ),
+    urgent:
+      message.urgency === undefined || message.urgency === 'normal' || message.urgency === 'high',
+  };
+}
+
+/** What one device's send carries: a rendered alert, or ids that wake the app and show nothing. */
+export type NativePush =
+  | { readonly kind: 'alert'; readonly push: RenderedNativePush }
+  | { readonly kind: 'data'; readonly data: PushData };
+
+/** One provider, one device. `apns.ts` and `fcm.ts` are the two. */
+export interface NativeSender {
+  send(token: string, push: NativePush, signal: AbortSignal): Promise<void>;
+}

package/src/push-register.ts

@@ -0,0 +1,167 @@
+// Single responsibility: native device registration, 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, MCP tool and
+// policy like any other write:
+//
+//   export const registerDevice = pushRegister({ permission: 'push:subscribe', platforms, devices });
+//
+// The device is stored against `ctx.actor.id`, the person the request ran as — never an id the body
+// names, so a caller can register only themselves and unregister only their own device.
+
+import type { Action } from '@ultimat3/action';
+import { action } from '@ultimat3/action';
+import { timingSafeEqual } from '@ultimat3/core';
+import type { KnownPermission, PolicyArgs, PolicyDecision } from '@ultimat3/policy';
+import { can, denied } from '@ultimat3/policy';
+import { t } from '@ultimat3/schema';
+import type { PushDeviceRecord, PushDeviceStore, PushPlatform } from './push-device';
+import { FCM_TOKEN, isDeviceToken } from './push-device';
+
+/** Either platform's token alphabet; `platformToken` then holds each to its own. */
+const anyToken = () => t.string.min(32).max(4096).pattern(FCM_TOKEN);
+
+type Platforms = readonly [PushPlatform, ...PushPlatform[]];
+
+const tokensMatch = (value: {
+  platform: PushPlatform;
+  token: string;
+  previousToken?: string | undefined;
+}): boolean =>
+  isDeviceToken(value.platform, value.token) &&
+  (value.previousToken === undefined || isDeviceToken(value.platform, value.previousToken));
+
+const registerInput = (platforms: Platforms) =>
+  t.refine(
+    t.object({
+      platform: t.enum(platforms),
+      token: anyToken(),
+      /** The token this install held before the OS rotated it — deleted as this one is stored. */
+      previousToken: anyToken().optional(),
+      /** BCP-47 — every visible push to this device renders in it. */
+      locale: t.locale,
+      /** IANA — the zone a push formatting a date would need. */
+      timeZone: t.timezone,
+    }),
+    {
+      name: 'platform-token',
+      message:
+        'an ios token is 64 to 200 hex characters, and an android token is an FCM registration token',
+      check: tokensMatch,
+      path: ['token'],
+    },
+  );
+
+const deviceOutput = () => t.object({ platform: t.string, token: t.string });
+const unregisterInput = (platforms: Platforms) =>
+  t.object({ platform: t.enum(platforms), token: anyToken() });
+const unregisterOutput = () => t.object({ removed: t.boolean });
+
+type RegisterInput = ReturnType<typeof registerInput>;
+type DeviceOutput = ReturnType<typeof deviceOutput>;
+type UnregisterInput = ReturnType<typeof unregisterInput>;
+type UnregisterOutput = ReturnType<typeof unregisterOutput>;
+
+export interface PushRegisterOptions {
+  /** What the registering actor must hold — read by `can()`, like every action's permission. */
+  readonly permission: KnownPermission;
+  /** The platforms the app ships; another is a 422. */
+  readonly platforms: Platforms;
+  /** The store `nativePush({ devices })` reads — the same one, handed to both. */
+  readonly devices: PushDeviceStore;
+  /**
+   * The app's further rule, over the actor. Absent, any actor holding the permission registers
+   * 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: PushRegisterOptions) =>
+  can<unknown, null>(options.permission, (args) => {
+    if (args.actor?.kind === 'agent') return denied('push.agent-subscriber');
+    return options.check === undefined ? true : options.check(args);
+  });
+
+/**
+ * Devices one person keeps. Past it, the OLDEST registration is evicted rather than the new one
+ * refused: the newest is the install most likely alive, a person whose rotated tokens were never
+ * pruned keeps getting pushes on the phone they just set up, and a caller registering a pile of
+ * made-up tokens costs each notification at most this many provider requests.
+ */
+export const PUSH_DEVICES_PER_ACTOR = 20;
+
+/** Oldest first; `(platform, token)` breaks a tie, so both stores evict the same row. */
+const byAge = (a: PushDeviceRecord, b: PushDeviceRecord): number =>
+  a.createdAt - b.createdAt || (a.platform + a.token < b.platform + b.token ? -1 : 1);
+
+/** Evict past the cap, never the row just written. Racing registers trim on the next one. */
+async function capDevices(
+  devices: PushDeviceStore,
+  actorId: string,
+  kept: { readonly platform: PushPlatform; readonly token: string },
+): Promise<void> {
+  const held = await devices.listFor(actorId);
+  const extra = held.length - PUSH_DEVICES_PER_ACTOR;
+  if (extra <= 0) return;
+  const evictable = held
+    .filter((device) => device.platform !== kept.platform || device.token !== kept.token)
+    .sort(byAge);
+  for (const device of evictable.slice(0, extra)) {
+    await devices.remove(device.platform, device.token, actorId);
+  }
+}
+
+/** APNs reads hex case-insensitively; one spelling keeps one row per install. */
+const canonical = (platform: PushPlatform, token: string): string =>
+  platform === 'ios' ? token.toLowerCase() : token;
+
+/**
+ * Store this install's token for the person signed in, and — with `previousToken` — forget the one
+ * it replaces. Idempotent per token. The new row is written FIRST: a crash between the two leaves
+ * both, and the old one is deleted by the provider's first "gone", never a device left with none.
+ * Past `PUSH_DEVICES_PER_ACTOR` the oldest of the caller's own devices is evicted.
+ */
+export function pushRegister(options: PushRegisterOptions): Action<RegisterInput, DeviceOutput> {
+  return action({
+    input: registerInput(options.platforms),
+    output: deviceOutput(),
+    policy: policyOf(options),
+    idempotent: true,
+    async handle({ input, ctx }) {
+      const token = canonical(input.platform, input.token);
+      await options.devices.save({
+        platform: input.platform,
+        token,
+        actorId: ctx.actor.id,
+        locale: input.locale,
+        timeZone: input.timeZone,
+        createdAt: ctx.now().getTime(),
+      });
+      if (input.previousToken !== undefined) {
+        const previous = canonical(input.platform, input.previousToken);
+        // Equal is the app re-sending its current token as the previous one: deleting it would
+        // drop the row just written. Neither is a secret; the helper is the one comparison.
+        if (!timingSafeEqual(previous, token)) {
+          await options.devices.remove(input.platform, previous, ctx.actor.id);
+        }
+      }
+      await capDevices(options.devices, ctx.actor.id, { platform: input.platform, token });
+      return { platform: input.platform, token };
+    },
+  });
+}
+
+/** Forget this install — the caller's own registration only; another person's is absent. */
+export function pushUnregister(
+  options: PushRegisterOptions,
+): Action<UnregisterInput, UnregisterOutput> {
+  return action({
+    input: unregisterInput(options.platforms),
+    output: unregisterOutput(),
+    policy: policyOf(options),
+    idempotent: true,
+    async handle({ input, ctx }) {
+      const token = canonical(input.platform, input.token);
+      return { removed: await options.devices.remove(input.platform, token, ctx.actor.id) };
+    },
+  });
+}

package/src/token-cache.ts

@@ -0,0 +1,57 @@
+// Single responsibility: one bearer credential, minted once and reused until shortly before it
+// expires. A fan-out to a thousand devices signs ONE APNs token and exchanges ONE Google assertion,
+// and concurrent sends share the mint in flight rather than each starting their own.
+
+export interface MintedToken {
+  readonly value: string;
+  /** Epoch ms after which the provider refuses it. */
+  readonly expiresAt: number;
+}
+
+export interface TokenCache {
+  /** The cached token, or a fresh one once it is within `refreshBeforeMs` of expiring. */
+  get(): Promise<string>;
+  /**
+   * Forget `stale` — the token the provider just refused — so the next send mints again. Only
+   * when it is still the cached one: a straggler's late refusal for a token already replaced
+   * would otherwise drop the fresh one and re-sign, and Apple throttles a re-sign inside 20 min.
+   * A mint in flight is left alone: it started after `stale` was handed out.
+   */
+  invalidate(stale: string): void;
+}
+
+export function tokenCache(
+  mint: () => Promise<MintedToken>,
+  now: () => number,
+  refreshBeforeMs: number,
+): TokenCache {
+  let current: MintedToken | undefined;
+  let pending: Promise<MintedToken> | undefined;
+  return {
+    async get() {
+      if (current !== undefined && now() < current.expiresAt - refreshBeforeMs) {
+        return current.value;
+      }
+      if (pending === undefined) {
+        const minting = mint();
+        pending = minting;
+        // A failed mint is never cached: the next send tries again rather than replaying it.
+        minting.then(
+          (token) => {
+            if (pending === minting) current = token;
+          },
+          () => undefined,
+        );
+        minting
+          .finally(() => {
+            if (pending === minting) pending = undefined;
+          })
+          .catch(() => undefined);
+      }
+      return (await pending).value;
+    },
+    invalidate(stale) {
+      if (current?.value === stale) current = undefined;
+    },
+  };
+}