@12-apps/notifications 1.0.0

package/src/react/web-push-setup.tsx

@@ -0,0 +1,167 @@
+/**
+ * The per-BROWSER Web Push enable step, which sits above the preference matrix
+ * because a preference alone cannot reach a device that never subscribed.
+ */
+import { useEffect, useState, type JSX } from 'react';
+
+import { Button } from '@12-apps/ui/form/Button';
+import { Box } from '@12-apps/ui/mui/Box';
+import { Text } from '@12-apps/ui/typography/Text';
+
+import type { NotificationMessages } from '../messages';
+
+import type { NotificationsApiClient } from './api';
+import { enableWebPush, getExistingPushSubscription } from './web-push-client';
+
+/** The panel's copy for a host whose platform blocks browser-level push. */
+export interface WebPushPlatformHint {
+  title: string;
+  body: string;
+}
+
+export interface WebPushSetupConfig {
+  /**
+   * The host's service-worker path. Path-routed SPAs each control their own
+   * scope, and the file itself is the host's.
+   */
+  swPath?: string;
+  /**
+   * Whether THIS platform must be installed to the home screen before a
+   * subscription can exist at all.
+   *
+   * iOS is the case: Safari has no browser-level Web Push, so "Ativar" there
+   * asks no permission, creates no subscription, and fails with nothing a user
+   * could act on. The check is a config seam rather than a dependency because
+   * "is this an installable iOS browser" is a question a host's PWA layer
+   * already answers (future-pay passes
+   * `() => isIosInstallable() && !isStandalone()` from `@12-apps/pwa`).
+   */
+  needsInstallFirst?: () => boolean;
+  /** What to say instead of the button when the check above is true. */
+  installHint?: WebPushPlatformHint;
+}
+
+const cardSx = {
+  p: 2,
+  border: '1px solid',
+  borderColor: 'divider',
+  borderRadius: 2,
+} as const;
+
+function InstallFirstHint({ hint }: { hint: WebPushPlatformHint }): JSX.Element {
+  return (
+    <Box sx={cardSx} data-testid="web-push-install-hint">
+      <Text variant="body" size="sm" weight="semibold" as="p">
+        {hint.title}
+      </Text>
+      <Text variant="caption" size="xs" color="secondary" as="p">
+        {hint.body}
+      </Text>
+    </Box>
+  );
+}
+
+type SetupState = 'idle' | 'checking' | 'on' | 'busy' | 'failed' | 'denied';
+
+/**
+ * "Is this browser receiving alerts?" — asked of the browser AND of the server.
+ *
+ * The browser alone is not enough, and answering from it alone is how a real
+ * person is silenced while being told they are fine. Two users share a counter
+ * PC: Ana enables push, then Otávio signs in on the same browser and enables it
+ * too. `PushManager` hands out the SAME endpoint for the same browser profile,
+ * so the POST re-owns the row and Ana's is gone. Ana signs back in, her browser
+ * still holds the subscription object, and a browser-only check renders "Este
+ * navegador está recebendo alertas." with no button to fix it — forever. The
+ * 404/410 prune reaches the same state from the other direction.
+ *
+ * So the server is asked whether it still has THIS endpoint under THIS user. A
+ * `false` (or an unreachable server) shows *Ativar* again, and one click
+ * re-registers the row — which is the same request the happy path makes, so the
+ * recovery costs nothing to maintain.
+ */
+async function resolveState(api: NotificationsApiClient): Promise<SetupState> {
+  const subscription = await getExistingPushSubscription();
+  if (!subscription) return 'idle';
+  const registration = await api
+    .getPushRegistration({ endpoint: subscription.endpoint })
+    .catch(() => null);
+  return registration?.registered ? 'on' : 'idle';
+}
+
+function statusText(state: SetupState, messages: NotificationMessages): string {
+  if (state === 'on') return messages.devicePushOn;
+  if (state === 'denied') return messages.devicePushDenied;
+  if (state === 'failed') return messages.devicePushFailed;
+  return messages.devicePushIdle;
+}
+
+export function WebPushDeviceSetup({
+  available,
+  api,
+  messages,
+  config,
+}: {
+  available: boolean;
+  api: NotificationsApiClient;
+  messages: NotificationMessages;
+  config: WebPushSetupConfig;
+}): JSX.Element | null {
+  const [state, setState] = useState<SetupState>('checking');
+  // Read once, at mount: neither can change without a new document.
+  const [needsInstall] = useState(() => config.needsInstallFirst?.() ?? false);
+
+  useEffect(() => {
+    let cancelled = false;
+    void resolveState(api).then((next) => {
+      if (!cancelled) setState(next);
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [api]);
+
+  if (!available) return null;
+  if (needsInstall && config.installHint) return <InstallFirstHint hint={config.installHint} />;
+
+  const enable = async (): Promise<void> => {
+    setState('busy');
+    const result = await enableWebPush(api, config.swPath);
+    if (result.ok) setState('on');
+    else setState(result.reason === 'permission-denied' ? 'denied' : 'failed');
+  };
+
+  return (
+    <Box
+      sx={{
+        ...cardSx,
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'space-between',
+        gap: 2,
+      }}
+      data-testid="web-push-device-setup"
+    >
+      <Box sx={{ minWidth: 0 }}>
+        <Text variant="body" size="sm" weight="semibold" as="p">
+          {messages.devicePushTitle}
+        </Text>
+        <Text variant="caption" size="xs" color="secondary" as="p">
+          {statusText(state, messages)}
+        </Text>
+      </Box>
+      {state !== 'on' ? (
+        <Button
+          variant="outline"
+          color="primary"
+          size="sm"
+          disabled={state === 'busy' || state === 'checking'}
+          onClick={() => void enable()}
+          dataTestId="web-push-enable"
+        >
+          {state === 'busy' ? messages.devicePushEnabling : messages.devicePushEnable}
+        </Button>
+      ) : null}
+    </Box>
+  );
+}

package/src/server/by-permission.ts

@@ -0,0 +1,255 @@
+import type { NotificationEvent, NotificationLogger } from '../types';
+
+import type { NotificationRouter } from './router';
+
+/**
+ * Permission-addressed notifications: "tell whoever can act on this", resolved
+ * against the host's REAL authorization engine.
+ *
+ * Naming an audience by ROLE reads a coarse mirror column, so a tenant who
+ * moved a capability onto a custom role — or granted it additively — gets a
+ * notification list that disagrees with what the app actually authorizes. The
+ * two answers drift silently, and the direction they drift in is "the person
+ * who can fix it never hears about it".
+ *
+ * So this addresses by CAPABILITY: name the permissions the recipient must
+ * hold, and the audience is derived from the same evaluation the guards use.
+ *
+ * ## What the package owns, and what the host answers
+ *
+ * The FOLD is the package's: the AND, the deduplication, the refusal of an
+ * empty permission list, the per-recipient isolation, and the log line that
+ * distinguishes "nobody holds it" from "everybody's dispatch failed". Those are
+ * the parts that are the same in every host and that are easy to get subtly
+ * wrong.
+ *
+ * The two QUERIES are the host's, through {@link NotificationAudienceDirectory}
+ * — because an authorization engine is host machinery. In future-pay this
+ * module could not live in a package at all: it needed `notify()` AND the RBAC
+ * engine, and neither package could see the other. Inverting the dependency
+ * (the host answers, the package asks) is what makes it portable.
+ */
+
+/**
+ * The host's authorization engine, as this fan-out needs it.
+ *
+ * `listCandidates` must be BOUNDED to people who actually hold a role at the
+ * tenant. future-pay's implementation requires a role grant, which is what
+ * keeps a store's storefront BUYERS — who all carry a default membership — out
+ * of a loop that resolves permissions one user at a time.
+ *
+ * `getPermissions` must be scoped to `tenantId`. Unioning a user's grants
+ * across tenants — the obvious way to "simplify" it — notifies someone about a
+ * store whose money they have no authority over, and no `where` clause upstream
+ * can save it because that user is already a candidate.
+ */
+export interface NotificationAudienceDirectory {
+  listCandidates(tenantId: string): Promise<readonly string[]>;
+  getPermissions(
+    userId: string,
+    tenantId: string,
+  ): Promise<ReadonlySet<string> | readonly string[]>;
+}
+
+/**
+ * One candidate that did not receive it, and why.
+ *
+ * `audience-error` is deliberately its own reason rather than folded into
+ * `missing-permission`: "this user does not hold the pair" is a configuration
+ * fact, while "we could not find out whether they hold it" is an outage, and
+ * they need opposite responses. Collapsing them would report a database timeout
+ * as a tenant that simply has nobody to tell.
+ */
+export interface PermissionNotificationSkip {
+  userId: string;
+  reason: 'missing-permission' | 'dispatch-failed' | 'audience-error';
+}
+
+/**
+ * What one fan-out actually did. Returned rather than logged-and-forgotten so a
+ * caller (and a test) can assert on the OUTCOME — who was reached and who was
+ * not — without reaching into transport mocks to infer it.
+ */
+export interface PermissionNotificationResult {
+  /** User ids whose notification committed, in candidate order. */
+  notified: string[];
+  /** Candidates that did not receive it, with the reason. */
+  skipped: PermissionNotificationSkip[];
+}
+
+/** What {@link reportOutcome} needs to describe one fan-out. */
+interface OutcomeReport {
+  type: string;
+  clientId: string;
+  permissions: readonly string[];
+  candidateCount: number;
+  result: PermissionNotificationResult;
+}
+
+/**
+ * Log what the fan-out amounted to, keyed on WHY nobody was reached rather
+ * than on the fact that nobody was.
+ *
+ * The distinction is the whole point: "this tenant has nobody holding the pair"
+ * is a configuration fact and belongs at info, while "three people hold it and
+ * every dispatch failed" is an outage in which nobody was told about missing
+ * money. Both leave `notified` empty, so keying on that alone would file the
+ * second under the first and make a dead transport look like an unconfigured
+ * store.
+ */
+function reportOutcome(logger: NotificationLogger, report: OutcomeReport): void {
+  const { type, clientId, permissions, candidateCount, result } = report;
+  // Both non-configuration reasons count as "not reached": a candidate whose
+  // authorization query threw is as un-notified as one whose dispatch threw.
+  const failed = result.skipped.filter((skip) => skip.reason !== 'missing-permission').length;
+  if (failed > 0) {
+    logger.error(
+      `[notifications] ${type}: ${failed} of ${failed + result.notified.length} matching ` +
+        `recipient(s) at client ${clientId} could not be reached; ` +
+        `${result.notified.length} delivered`,
+    );
+    return;
+  }
+  if (result.notified.length > 0) return;
+  // Quiet, and deliberately at info: "nobody at this tenant holds
+  // `orders:refund` + `reports:financial:read`" is worth being able to look up
+  // when someone asks why they heard nothing, but it is not a fault.
+  logger.info(
+    `[notifications] ${type}: no recipient at client ${clientId} holds ` +
+      `[${permissions.join(', ')}] (${candidateCount} candidate(s) evaluated)`,
+  );
+}
+
+export type NotifyByPermission = <TPayload>(
+  clientId: string,
+  permissions: readonly string[],
+  event: Omit<NotificationEvent<TPayload>, 'recipient'>,
+) => Promise<PermissionNotificationResult>;
+
+/**
+ * Send one notification to every user of `clientId` holding ALL of
+ * `permissions` (AND, not OR).
+ *
+ * AND is the semantics that makes an addressed notification openable: pair the
+ * permission that HANDLES the thing with the permission that gates the SURFACE
+ * it links to, and every addressee is, by construction, someone the surface's
+ * own guard will serve. OR would happily notify someone into a 403.
+ *
+ * Contract:
+ *   - `permissions` must be non-empty. An empty list is a PROGRAMMING ERROR and
+ *     throws: "holds every permission in []" is vacuously true for everyone, so
+ *     the quiet reading of an empty list is "fan out to the entire tenant" —
+ *     the one outcome a caller can never have meant. It is the only throw here.
+ *   - TENANT-SCOPED, unconditionally. Permissions are evaluated at `clientId`
+ *     and the inbox row is written with that same tenant.
+ *   - Recipients are DEDUPLICATED: candidates are a set, and holding the
+ *     permissions through two roles is one notification.
+ *   - Zero matching users is a NORMAL outcome — logged, never thrown.
+ *   - Recipients are ISOLATED, in BOTH host queries: the authorization lookup
+ *     and the dispatch each get their own try/catch, so neither a candidate the
+ *     engine cannot answer for nor a recipient `notify` throws on can cost the
+ *     others their notification — or cost the caller the outcome log.
+ *
+ * Cost: one `getPermissions` per candidate, run sequentially. That is only
+ * affordable because the candidate set is bounded (see the directory docs).
+ * Callers run this fire-and-forget, off whatever path produced the event.
+ */
+/** What the two isolated per-candidate steps need. */
+interface FanOutDeps {
+  router: NotificationRouter;
+  directory: NotificationAudienceDirectory;
+  logger: NotificationLogger;
+}
+
+/**
+ * One recipient's dispatch, isolated. Resolves `true` when the notification
+ * committed and `false` when it did not — the failure is contained here so the
+ * loop can carry on, which is the whole point of per-recipient isolation.
+ *
+ * The log names the USER ID and never an address: an e-mail in a log is PII.
+ */
+async function dispatchTo<TPayload>(
+  deps: FanOutDeps,
+  clientId: string,
+  userId: string,
+  event: Omit<NotificationEvent<TPayload>, 'recipient'>,
+): Promise<boolean> {
+  try {
+    await deps.router.notify<TPayload>({ ...event, recipient: { userId, clientId } });
+    return true;
+  } catch (error) {
+    deps.logger.error(
+      `[notifications] ${event.type} dispatch failed for user ${userId} at client ${clientId}:`,
+      error,
+    );
+    return false;
+  }
+}
+
+/**
+ * One candidate's permissions, isolated. `null` means the host's engine could
+ * not answer.
+ *
+ * This await used to sit bare in the loop while only `notify` was guarded, which
+ * made the documented per-recipient isolation half true: an ordinary
+ * connection-pool timeout on candidate #3 of 30 propagated out of
+ * `notifyByPermission`, so #4..#30 were never evaluated, `reportOutcome` never
+ * ran, and the only trace was a rejection in whatever `.catch` the
+ * fire-and-forget caller happened to attach. For a short-payment alert that is
+ * nobody being told that money is missing, with nothing in the log saying so.
+ */
+async function heldBy(
+  deps: FanOutDeps,
+  clientId: string,
+  userId: string,
+): Promise<ReadonlySet<string> | null> {
+  try {
+    const granted = await deps.directory.getPermissions(userId, clientId);
+    return granted instanceof Set ? granted : new Set(granted);
+  } catch (error) {
+    deps.logger.error(
+      `[notifications] audience lookup failed for user ${userId} at client ${clientId}:`,
+      error,
+    );
+    return null;
+  }
+}
+
+export function createNotifyByPermission(deps: FanOutDeps): NotifyByPermission {
+  return async function notifyByPermission(clientId, permissions, event) {
+    if (permissions.length === 0) {
+      throw new Error(
+        'notifyByPermission(): `permissions` must be non-empty — ' +
+          'an empty list matches every user of the tenant.',
+      );
+    }
+    const candidates = [...new Set(await deps.directory.listCandidates(clientId))];
+    const result: PermissionNotificationResult = { notified: [], skipped: [] };
+
+    for (const userId of candidates) {
+      const held = await heldBy(deps, clientId, userId);
+      if (!held) {
+        result.skipped.push({ userId, reason: 'audience-error' });
+        continue;
+      }
+      // THE AND. `held` folds every role the user has at this tenant, so this
+      // one line is the whole authorization question — and a single-element
+      // list needs no special case.
+      if (!permissions.every((permission) => held.has(permission))) {
+        result.skipped.push({ userId, reason: 'missing-permission' });
+        continue;
+      }
+      if (await dispatchTo(deps, clientId, userId, event)) result.notified.push(userId);
+      else result.skipped.push({ userId, reason: 'dispatch-failed' });
+    }
+
+    reportOutcome(deps.logger, {
+      type: event.type,
+      clientId,
+      permissions,
+      candidateCount: candidates.length,
+      result,
+    });
+    return result;
+  };
+}

package/src/server/context.ts

@@ -0,0 +1,269 @@
+import type { NotificationMessages } from '../messages';
+import { NOTIFICATION_CHANNELS, type NotificationChannel } from '../types';
+
+/**
+ * What every route in this surface shares (12-15): the actor, the request, the
+ * response envelope and the body parsing. Mirrors the entity-lifecycle /
+ * report-builder shape — framework-neutral descriptors a forty-line adapter
+ * mounts.
+ */
+
+/**
+ * What a host must resolve before a request reaches these handlers: WHO is
+ * calling. That is the whole seam.
+ *
+ * There is no tenant here and no permission list, and both absences are the
+ * design. Every endpoint in this surface is SELF-scoped — a user reads and
+ * writes their own inbox and their own preferences — so the only authorization
+ * question is "who is signed in", and the answer is applied by scoping every
+ * query to `userId` rather than by a guard that could be forgotten. A
+ * permission-gated ADMIN view of someone else's inbox would be a different
+ * surface, and would need a different actor.
+ */
+export interface NotificationsActor {
+  userId: string;
+}
+
+/** One request, already authenticated and routed by the host. */
+export interface NotificationsRequest {
+  actor: NotificationsActor;
+  params: Record<string, string | undefined>;
+  query: Record<string, string | undefined>;
+  body?: unknown;
+  /** Headers the surface reads (`user-agent`, for the device hint). */
+  headers?: Record<string, string | undefined>;
+}
+
+/** What a handler answers with; the adapter maps it onto its response type. */
+export interface NotificationsResponse {
+  status: number;
+  /** `undefined` means NO body at all (204) — not the same as `null`. */
+  body: unknown;
+}
+
+export interface NotificationsRoute {
+  method: 'GET' | 'POST' | 'PUT' | 'DELETE';
+  /**
+   * Path relative to the host's account mount, in `:param` form. The SHAPE is
+   * fixed because the packaged client builds these URLs.
+   */
+  path: string;
+  handle(request: NotificationsRequest): Promise<NotificationsResponse>;
+}
+
+/** A user-safe API error carrying the HTTP status the wire promises. */
+export class NotificationsApiError extends Error {
+  readonly status: number;
+  constructor(status: number, message: string) {
+    super(message);
+    this.name = 'NotificationsApiError';
+    this.status = status;
+    Object.setPrototypeOf(this, NotificationsApiError.prototype);
+  }
+}
+
+/** Success is `{ data }`; a denial is `{ error }`, unwrapped. */
+export const ok = (data: unknown, status = 200): NotificationsResponse => ({
+  status,
+  body: { data },
+});
+
+const fail = (status: number, error: string): NotificationsResponse => ({
+  status,
+  body: { error },
+});
+
+/** Fold a thrown {@link NotificationsApiError} into a response; rethrow the rest. */
+export function foldApiError(error: unknown): NotificationsResponse {
+  if (error instanceof NotificationsApiError) return fail(error.status, error.message);
+  throw error;
+}
+
+/** Wrap a handler so its thrown api errors become the wire's `{ error }`. */
+export function guarded(
+  handle: (request: NotificationsRequest) => Promise<NotificationsResponse>,
+): (request: NotificationsRequest) => Promise<NotificationsResponse> {
+  return async (request) => {
+    try {
+      return await handle(request);
+    } catch (error) {
+      return foldApiError(error);
+    }
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Body / query parsing — the request contract, in the package
+// ---------------------------------------------------------------------------
+
+function asRecord(body: unknown, messages: NotificationMessages): Record<string, unknown> {
+  if (typeof body !== 'object' || body === null || Array.isArray(body)) {
+    throw new NotificationsApiError(400, messages.invalidBody);
+  }
+  return body as Record<string, unknown>;
+}
+
+/** 1..100 non-empty string ids. */
+function parseIds(value: unknown, messages: NotificationMessages): string[] {
+  if (!Array.isArray(value) || value.length === 0 || value.length > 100) {
+    throw new NotificationsApiError(400, messages.invalidBody);
+  }
+  return value.map((id) => {
+    if (typeof id !== 'string' || id.length === 0) {
+      throw new NotificationsApiError(400, messages.invalidBody);
+    }
+    return id;
+  });
+}
+
+/**
+ * Query strings arrive as strings; the store clamps, but a non-number is a
+ * client bug and must not silently read as "the default page".
+ */
+function parseLimit(raw: string | undefined, messages: NotificationMessages): number | undefined {
+  if (raw === undefined || raw === '') return undefined;
+  const limit = Number(raw);
+  if (!Number.isInteger(limit) || limit < 1 || limit > 100) {
+    throw new NotificationsApiError(400, messages.invalidBody);
+  }
+  return limit;
+}
+
+function parseFilter(
+  raw: string | undefined,
+  messages: NotificationMessages,
+): 'all' | 'unread' | undefined {
+  if (raw === undefined) return undefined;
+  if (raw !== 'all' && raw !== 'unread') {
+    throw new NotificationsApiError(400, messages.invalidBody);
+  }
+  return raw;
+}
+
+/** `GET <mount>/notifications` — `filter`, `cursor`, `limit`. */
+export function parseListQuery(
+  query: Record<string, string | undefined>,
+  messages: NotificationMessages,
+): { filter?: 'all' | 'unread'; cursor?: string; limit?: number } {
+  const filter = parseFilter(query.filter, messages);
+  const limit = parseLimit(query.limit, messages);
+  return {
+    ...(filter !== undefined ? { filter } : {}),
+    ...(query.cursor ? { cursor: query.cursor } : {}),
+    ...(limit !== undefined ? { limit } : {}),
+  };
+}
+
+/** `POST <mount>/notifications/mark-read` — explicit ids, or `all: true`. */
+export function parseMarkReadBody(
+  body: unknown,
+  messages: NotificationMessages,
+): { all: true } | { ids: string[] } {
+  const record = asRecord(body, messages);
+  const wantsAll = record.all === true;
+  const hasIds = record.ids !== undefined;
+  // Exactly one of the two. Both, or neither, is ambiguous in the one direction
+  // that matters: "mark everything read" is not a thing to guess at.
+  if (wantsAll === hasIds) {
+    throw new NotificationsApiError(400, messages.markReadTargetRequired);
+  }
+  return wantsAll ? { all: true } : { ids: parseIds(record.ids, messages) };
+}
+
+/** `POST <mount>/notifications/delete` — 1..100 ids. */
+export function parseDeleteBody(body: unknown, messages: NotificationMessages): string[] {
+  return parseIds(asRecord(body, messages).ids, messages);
+}
+
+/**
+ * `PUT <mount>/notification-preferences` — any subset of categories, each with
+ * any subset of channel toggles. Categories left out stay untouched.
+ */
+export function parsePreferencesBody(
+  body: unknown,
+  messages: NotificationMessages,
+): Record<string, Partial<Record<NotificationChannel, boolean>>> {
+  const record = asRecord(body, messages);
+  const parsed: Record<string, Partial<Record<NotificationChannel, boolean>>> = {};
+  for (const [category, value] of Object.entries(record)) {
+    parsed[category] = parseToggles(value, messages);
+  }
+  return parsed;
+}
+
+/** One category's toggles, narrowed onto the closed channel set. */
+function parseToggles(
+  value: unknown,
+  messages: NotificationMessages,
+): Partial<Record<NotificationChannel, boolean>> {
+  const toggles = asRecord(value, messages);
+  const row: Partial<Record<NotificationChannel, boolean>> = {};
+  for (const channel of NOTIFICATION_CHANNELS) {
+    const flag = toggles[channel];
+    if (flag === undefined) continue;
+    if (typeof flag !== 'boolean') throw new NotificationsApiError(400, messages.invalidBody);
+    row[channel] = flag;
+  }
+  return row;
+}
+
+const MAX_ENDPOINT_CHARS = 2000;
+const MAX_KEY_CHARS = 500;
+
+function parseEndpoint(value: unknown, messages: NotificationMessages): string {
+  if (typeof value !== 'string' || value.length === 0 || value.length > MAX_ENDPOINT_CHARS) {
+    throw new NotificationsApiError(400, messages.invalidBody);
+  }
+  // A push endpoint is a URL the server will POST to, so an absolute http(s)
+  // URL is a hard requirement rather than a formality.
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new NotificationsApiError(400, messages.invalidBody);
+  }
+  if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+    throw new NotificationsApiError(400, messages.invalidBody);
+  }
+  return value;
+}
+
+/** `POST <mount>/push-subscriptions` — `PushSubscription.toJSON()`. */
+export function parsePushSubscriptionBody(
+  body: unknown,
+  messages: NotificationMessages,
+): { endpoint: string; keys: { p256dh: string; auth: string } } {
+  const record = asRecord(body, messages);
+  const keys = asRecord(record.keys, messages);
+  const key = (value: unknown): string => {
+    if (typeof value !== 'string' || value.length === 0 || value.length > MAX_KEY_CHARS) {
+      throw new NotificationsApiError(400, messages.invalidBody);
+    }
+    return value;
+  };
+  return {
+    endpoint: parseEndpoint(record.endpoint, messages),
+    keys: { p256dh: key(keys.p256dh), auth: key(keys.auth) },
+  };
+}
+
+/** `DELETE <mount>/push-subscriptions` — by endpoint. */
+export function parsePushEndpointBody(body: unknown, messages: NotificationMessages): string {
+  return parseEndpoint(asRecord(body, messages).endpoint, messages);
+}
+
+/**
+ * `GET <mount>/push-subscriptions?endpoint=…` — the browser asking "is the
+ * subscription I am holding still MINE on the server?".
+ *
+ * Optional: with no `endpoint` the route answers the key and the count as it
+ * always has. Validated by the same rules as the write, so a junk value is a 400
+ * rather than a lookup.
+ */
+export function parsePushEndpointQuery(
+  query: Record<string, string | undefined>,
+  messages: NotificationMessages,
+): string | undefined {
+  if (query.endpoint === undefined || query.endpoint === '') return undefined;
+  return parseEndpoint(query.endpoint, messages);
+}