@12-apps/notifications 4.12.0 → 4.13.0

package/prisma/notifications.prisma

@@ -131,11 +131,23 @@ model PushSubscription {
   endpoint  String   @unique
   p256dh    String
   auth      String
+  /// Which ORIGIN this browser registered on.
+  ///
+  /// NULL is the PLATFORM origin — the host itself, or any adopter serving one
+  /// origin. A subscription stamped with a store receives that store's
+  /// notifications plus platform-wide ones (`clientId IS NULL`) and NEVER
+  /// another store's; a platform-origin subscription receives everything, which
+  /// is what keeps a marketplace host's behaviour identical to before.
+  ///
+  /// Nullable so every pre-existing row reads as "platform" with no backfill.
+  clientId  String?  @map("client_id")
   // Free-form browser/device hint ("Chrome · Linux") for a device list.
   userAgent String?  @map("user_agent")
   createdAt DateTime @default(now()) @map("created_at")
   updatedAt DateTime @updatedAt @map("updated_at")
 
   @@index([userId])
+  // The send path's one query: owner, then the origin rule above.
+  @@index([userId, clientId])
   @@map("push_subscriptions")
 }

package/src/server/context.ts

@@ -22,6 +22,21 @@ import { NOTIFICATION_CHANNELS, type NotificationChannel } from '../types';
  */
 export interface NotificationsActor {
   userId: string;
+  /**
+   * The store whose ORIGIN this request arrived on, resolved by the
+   * HOST from the hostname — never read from the body or the query.
+   *
+   * The paragraph above still holds: this is not a tenant the surface
+   * authorizes against, it is a NARROWING of a read that is already the
+   * caller's own, and it can never widen one. A host with a single origin never
+   * sets it and every endpoint answers exactly what it answered before.
+   *
+   * It exists because a multi-tenant host installs one storefront per store as
+   * its own PWA, and a PWA's identity is its ORIGIN — so an inbox answering a
+   * store's own app with a neighbour's notifications is one store reporting on
+   * another.
+   */
+  scopeClientId?: string;
 }
 
 /** One request, already authenticated and routed by the host. */

package/src/server/db.ts

@@ -54,14 +54,40 @@ export interface NotificationPageAfter {
   id: string;
 }
 
-/** The inbox read filter. `deletedAt: null` is on every read, always. */
-export interface NotificationWhere {
+/**
+ * One BRANCH of an inbox filter — a member of `AND`/`OR`, never a whole read.
+ *
+ * Split out when the store scope arrived, and the split is what keeps `deletedAt: null`
+ * REQUIRED on the read itself (see {@link NotificationWhere}). Widening `OR`
+ * from the old fixed keyset tuple to a general array needed its members to be
+ * valid filters, and the tempting move — relaxing `deletedAt` on the one type —
+ * would have removed the only thing that makes a Prisma-backed host exclude
+ * soft-deleted rows. Both in-package doubles hard-code that filter regardless,
+ * so Prisma is precisely the implementation the requirement was protecting.
+ *
+ * `createdAt` and `id: { lt }` are here because the keyset boundary is built
+ * from them (`../inbox.ts`'s `pageWhere`); without them the branch type cannot
+ * express the very thing the widening exists to preserve.
+ */
+export interface NotificationWhereBranch {
   userId?: string;
-  id?: string | { in: string[] };
-  deletedAt: null;
+  id?: string | { in: string[] } | { lt: string };
+  createdAt?: Date | { lt: Date };
+  deletedAt?: null;
   readAt?: null;
-  /** The keyset half of `(createdAt, id) < (anchor.createdAt, anchor.id)`. */
-  OR?: [{ createdAt: { lt: Date } }, { createdAt: Date; id: { lt: string } }];
+  /** `null` matches the platform-wide rows that travel with every store scope. */
+  clientId?: string | null;
+  OR?: NotificationWhereBranch[];
+  AND?: NotificationWhereBranch[];
+}
+
+/**
+ * The inbox read filter. `deletedAt: null` is on every read, always — and it
+ * stays REQUIRED here, which is the whole reason {@link NotificationWhereBranch}
+ * is a separate type.
+ */
+export interface NotificationWhere extends NotificationWhereBranch {
+  deletedAt: null;
 }
 
 export interface NotificationDelegate {
@@ -180,11 +206,25 @@ export interface PushSubscriptionRow {
   endpoint: string;
   p256dh: string;
   auth: string;
+  /** The origin this browser registered on; `null` = the platform origin. */
+  clientId: string | null;
   userAgent: string | null;
 }
 
+/**
+ * Which of a user's subscriptions one send may reach.
+ *
+ * The disjunction is load-bearing and `clientId: { in: [x, null] }` is NOT a
+ * shortcut for it: SQL `IN` never matches NULL, so the platform-wide rows that
+ * must travel with every store scope would silently vanish.
+ */
+export interface PushSubscriptionWhere {
+  userId: string;
+  OR?: [{ clientId: null }, { clientId: string }];
+}
+
 export interface PushSubscriptionDelegate {
-  count(args: { where: { userId: string } }): Promise<number>;
+  count(args: { where: PushSubscriptionWhere }): Promise<number>;
   /**
    * The row holding one endpoint, whoever owns it. Read BEFORE an upsert so a
    * re-own (the same browser profile, a different signed-in user) is a logged
@@ -192,7 +232,7 @@ export interface PushSubscriptionDelegate {
    * whether THIS browser's subscription is still the caller's.
    */
   findUnique(args: { where: { endpoint: string } }): Promise<PushSubscriptionRow | null>;
-  findMany(args: { where: { userId: string } }): Promise<PushSubscriptionRow[]>;
+  findMany(args: { where: PushSubscriptionWhere }): Promise<PushSubscriptionRow[]>;
   upsert(args: {
     where: { endpoint: string };
     create: {
@@ -200,12 +240,14 @@ export interface PushSubscriptionDelegate {
       endpoint: string;
       p256dh: string;
       auth: string;
+      clientId: string | null;
       userAgent: string | null;
     };
     update: {
       userId: string;
       p256dh: string;
       auth: string;
+      clientId: string | null;
       userAgent: string | null;
     };
   }): Promise<PushSubscriptionRow>;

package/src/server/dispatch.ts

@@ -92,6 +92,7 @@ export interface NotificationDispatchDeps {
 export async function loadRecipient(
   deps: NotificationDispatchDeps,
   userId: string,
+  clientId: string | null,
 ): Promise<TransportRecipient | null> {
   const contact = await deps.contacts.getContact(userId);
   if (!contact) return null;
@@ -103,7 +104,11 @@ export async function loadRecipient(
     // absent case has to stay distinguishable from a stated language, because
     // that is what lets a generator apply its own default in one place.
     ...(contact.locale === undefined ? {} : { locale: contact.locale }),
-    pushSubscriptionCount: await deps.pushSubscriptions.count(userId),
+    clientId,
+    // SCOPED, and this is what keeps `supports()` honest: it gates on this
+    // number, so an unscoped count would enqueue a WEB_PUSH delivery for a
+    // notification no reachable subscription exists for.
+    pushSubscriptionCount: await deps.pushSubscriptions.count(userId, clientId),
   };
 }
 
@@ -223,7 +228,9 @@ export async function dispatchOne(
   });
   if (queued.length === 0) return 0;
 
-  const recipient = await loadRecipient(deps, notification.userId);
+  // The STORED column, so the retry sweep scopes identically to the first
+  // attempt — anything less would let a retry leak what the first send withheld.
+  const recipient = await loadRecipient(deps, notification.userId, notification.clientId);
   if (!recipient) {
     await abandonUnreachable(deps, client, queued, notification.userId);
     return 0;

package/src/server/inbox.ts

@@ -5,6 +5,7 @@ import type {
   NotificationPageAfter,
   NotificationsDbProvider,
   NotificationWhere,
+  NotificationWhereBranch,
 } from './db';
 
 /**
@@ -15,6 +16,29 @@ import type {
  * never be resurrected by mark-read.
  */
 
+/**
+ * The store whose ORIGIN the caller is reading from, or absent for the platform
+ * origin.
+ *
+ * A host that installs one storefront per store as its own PWA reads this from
+ * the request's hostname; a host with one origin never sets it and every read
+ * below is exactly what it was. Set, it narrows to that store's rows PLUS the
+ * platform-wide ones (`clientId IS NULL`) — a password reset or a security
+ * notice is about the person and not about a store, so hiding it inside the
+ * only app a customer opens would be a worse failure than the leak this fixes.
+ */
+export type NotificationScope = string | undefined;
+
+/**
+ * `clientId IN (<scope>, NULL)`, as a filter branch — or nothing at all.
+ *
+ * A disjunction rather than an `in`, because SQL `IN` never matches NULL and
+ * the NULL rows are precisely the ones that must survive every scope.
+ */
+function scopeBranch(scope: NotificationScope): NotificationWhereBranch[] {
+  return scope === undefined ? [] : [{ OR: [{ clientId: scope }, { clientId: null }] }];
+}
+
 export interface ListNotificationsInput {
   /** `unread` narrows to unread rows; default lists all non-deleted. */
   filter?: 'all' | 'unread';
@@ -34,10 +58,27 @@ const DEFAULT_PAGE = 20;
 const MAX_PAGE = 100;
 
 export interface NotificationInboxStore {
-  list(userId: string, input?: ListNotificationsInput): Promise<ListNotificationsResult>;
-  unreadCount(userId: string): Promise<number>;
+  list(
+    userId: string,
+    input?: ListNotificationsInput,
+    scope?: NotificationScope,
+  ): Promise<ListNotificationsResult>;
+  /** Scoped with `list`, or the badge and the list it sits over disagree. */
+  unreadCount(userId: string, scope?: NotificationScope): Promise<number>;
   markRead(userId: string, ids: readonly string[]): Promise<number>;
-  markAllRead(userId: string): Promise<number>;
+  /**
+   * Scoped too, and this one is a WRITE.
+   *
+   * Unscoped, "mark all as read" pressed inside store A's app clears store B's
+   * unread rows everywhere — a cross-store write from the app that exists to be
+   * isolated, and strictly worse than the read leak. `markRead(ids)` and
+   * `softDelete(ids)` need nothing: their ids come from the already-scoped list.
+   *
+   * The platform-wide rows ARE cleared from any origin, and that follows from
+   * the scope rule rather than contradicting it — those rows are one person's,
+   * not one store's.
+   */
+  markAllRead(userId: string, scope?: NotificationScope): Promise<number>;
   softDelete(userId: string, ids: readonly string[]): Promise<number>;
 }
 
@@ -66,27 +107,55 @@ function pageWhere(
   userId: string,
   filter: ListNotificationsInput['filter'],
   anchor: NotificationPageAfter | undefined,
+  scope: NotificationScope,
 ): NotificationWhere {
+  // Two DISJUNCTIONS have to hold at once — the page boundary and the store
+  // scope — so they are AND-ed rather than merged. A second `OR` key on this
+  // object literal would overwrite the first, dropping either the scope or the
+  // anchor; the anchor only from page TWO onward, which is the case a cursor
+  // exists for and the case a single-page test never reaches.
+  const clauses: NotificationWhereBranch[] = [
+    // `(createdAt, id) < (anchor.createdAt, anchor.id)`, as a portable `where`.
+    ...(anchor
+      ? [
+          {
+            OR: [
+              { createdAt: { lt: anchor.createdAt } },
+              { createdAt: anchor.createdAt, id: { lt: anchor.id } },
+            ],
+          },
+        ]
+      : []),
+    ...scopeBranch(scope),
+  ];
   return {
     userId,
     deletedAt: null,
     ...(filter === 'unread' ? { readAt: null } : {}),
-    // `(createdAt, id) < (anchor.createdAt, anchor.id)`, as a portable `where`.
-    ...(anchor
-      ? {
-          OR: [
-            { createdAt: { lt: anchor.createdAt } },
-            { createdAt: anchor.createdAt, id: { lt: anchor.id } },
-          ] as NonNullable<NotificationWhere['OR']>,
-        }
-      : {}),
+    ...(clauses.length > 0 ? { AND: clauses } : {}),
+  };
+}
+
+/**
+ * The unread rows this scope can see — READ by the badge and WRITTEN by "mark
+ * all". One filter for both on purpose: the count and the write have to agree
+ * about which rows are in scope, and two copies of the same object literal is
+ * how a badge ends up saying 3 over a list of 2.
+ */
+function unreadWhere(userId: string, scope: NotificationScope): NotificationWhere {
+  const scoped = scopeBranch(scope);
+  return {
+    userId,
+    deletedAt: null,
+    readAt: null,
+    ...(scoped.length > 0 ? { AND: scoped } : {}),
   };
 }
 
 export function createInboxStore(db: NotificationsDbProvider): NotificationInboxStore {
   return {
     /** The owner's inbox, newest first, keyset-paginated, deleted excluded. */
-    async list(userId, input = {}) {
+    async list(userId, input = {}, scope) {
       const client = await db();
       const limit = Math.min(Math.max(input.limit ?? DEFAULT_PAGE, 1), MAX_PAGE);
       const anchor = input.cursor
@@ -94,7 +163,7 @@ export function createInboxStore(db: NotificationsDbProvider): NotificationInbox
         : undefined;
       if (input.cursor && !anchor) return { items: [], nextCursor: null };
       const rows = await client.notification.findMany({
-        where: pageWhere(userId, input.filter, anchor),
+        where: pageWhere(userId, input.filter, anchor, scope),
         // `id` tie-breaks equal timestamps so pages never skip/repeat.
         orderBy: [{ createdAt: 'desc' }, { id: 'desc' }],
         take: limit + 1,
@@ -107,9 +176,9 @@ export function createInboxStore(db: NotificationsDbProvider): NotificationInbox
     },
 
     /** Unread badge count (non-deleted, unread). */
-    async unreadCount(userId) {
+    async unreadCount(userId, scope) {
       const client = await db();
-      return client.notification.count({ where: { userId, deletedAt: null, readAt: null } });
+      return client.notification.count({ where: unreadWhere(userId, scope) });
     },
 
     /**
@@ -128,10 +197,10 @@ export function createInboxStore(db: NotificationsDbProvider): NotificationInbox
     },
 
     /** Mark every unread notification of the owner read ("mark all"). */
-    async markAllRead(userId) {
+    async markAllRead(userId, scope) {
       const client = await db();
       const result = await client.notification.updateMany({
-        where: { userId, deletedAt: null, readAt: null },
+        where: unreadWhere(userId, scope),
         data: { readAt: new Date() },
       });
       return result.count;

package/src/server/index.ts

@@ -34,11 +34,13 @@ export type {
   NotificationPreferenceDelegate,
   NotificationPreferenceRow,
   NotificationWhere,
+  NotificationWhereBranch,
   NotificationsDb,
   NotificationsDbClient,
   NotificationsDbProvider,
   PushSubscriptionDelegate,
   PushSubscriptionRow,
+  PushSubscriptionWhere,
 } from './db';
 
 export type { ListNotificationsInput, NotificationInboxStore } from './inbox';

package/src/server/push-subscriptions.ts

@@ -1,6 +1,6 @@
 import type { NotificationLogger } from '../types';
 
-import type { NotificationsDbProvider } from './db';
+import type { NotificationsDbProvider, PushSubscriptionWhere } from './db';
 import type { WebPushSubscriptionSource } from './transports/web-push';
 
 /**
@@ -16,6 +16,41 @@ export interface PushSubscriptionInput {
   keys: { p256dh: string; auth: string };
   /** Optional browser/device hint for a device list. */
   userAgent?: string;
+  /**
+   * Which ORIGIN this browser subscribed on — the HOST's resolved
+   * value, never anything the caller sent. Absent/null = the platform origin.
+   */
+  clientId?: string | null;
+}
+
+/**
+ * Which of a user's subscriptions one notification may reach.
+ *
+ * Stated as a rule on the SUBSCRIPTION rather than as a fallback, because the
+ * fallback form ("the platform's rows only when the store's are absent")
+ * silently changes the platform origin's behaviour, and a marketplace host must
+ * be unaffected by this change:
+ *
+ * | the subscription was registered on | it receives |
+ * |---|---|
+ * | the PLATFORM origin (`client_id IS NULL`) | every notification — as today |
+ * | store X's origin | store X's, and platform-wide ones (`clientId IS NULL`) |
+ *
+ * Nothing ever reaches a subscription registered on a DIFFERENT store's origin.
+ * It follows without a special case that a store-B notification reaches a
+ * customer who installed only store A through their PLATFORM subscription, and
+ * through neither app.
+ *
+ * `notificationClientId` is the NOTIFICATION's tenant. `undefined` (nobody
+ * asked to narrow) and `null` (a platform-wide notification) both mean every
+ * row, which is why they share a branch.
+ */
+function reachableBy(
+  userId: string,
+  notificationClientId?: string | null,
+): PushSubscriptionWhere {
+  if (notificationClientId === undefined || notificationClientId === null) return { userId };
+  return { userId, OR: [{ clientId: null }, { clientId: notificationClientId }] };
 }
 
 export interface PushSubscriptionStore extends WebPushSubscriptionSource {
@@ -34,8 +69,19 @@ export interface PushSubscriptionStore extends WebPushSubscriptionSource {
   save(userId: string, input: PushSubscriptionInput): Promise<void>;
   /** Remove one browser's subscription (owner-scoped; unknown = no-op). */
   remove(userId: string, endpoint: string): Promise<void>;
-  /** How many devices the user has registered (settings UI hint). */
-  count(userId: string): Promise<number>;
+  /**
+   * How many devices the user has registered.
+   *
+   * TWO callers with different questions. The settings screen asks unscoped —
+   * "you have 2 devices" is a fact about the PERSON — and passes nothing. The
+   * dispatch path passes the notification's tenant, because this is what
+   * `supports()` gates on: left unscoped there, the router would enqueue a
+   * WEB_PUSH delivery for a notification no reachable subscription exists for,
+   * `send` would find an empty list and throw, and the sweep would burn every
+   * attempt before writing DEAD — a FAILED row for something that was never
+   * undeliverable, only out of scope.
+   */
+  count(userId: string, notificationClientId?: string | null): Promise<number>;
   /**
    * Whether THIS endpoint is currently registered to THIS user.
    *
@@ -75,12 +121,18 @@ export function createPushSubscriptionStore(
           endpoint: input.endpoint,
           p256dh: input.keys.p256dh,
           auth: input.keys.auth,
+          clientId: input.clientId ?? null,
           userAgent: input.userAgent ?? null,
         },
+        // Re-stamped on every save, so the same browser moving between a store's
+        // app and the platform corrects its own scope rather than keeping the
+        // first origin it ever subscribed from. A scope change on the SAME user
+        // is not a re-own and must not log one.
         update: {
           userId,
           p256dh: input.keys.p256dh,
           auth: input.keys.auth,
+          clientId: input.clientId ?? null,
           userAgent: input.userAgent ?? null,
         },
       });
@@ -91,9 +143,9 @@ export function createPushSubscriptionStore(
       await client.pushSubscription.deleteMany({ where: { userId, endpoint } });
     },
 
-    async count(userId) {
+    async count(userId, notificationClientId) {
       const client = await db();
-      return client.pushSubscription.count({ where: { userId } });
+      return client.pushSubscription.count({ where: reachableBy(userId, notificationClientId) });
     },
 
     async isRegisteredTo(userId, endpoint) {
@@ -102,9 +154,11 @@ export function createPushSubscriptionStore(
       return row?.userId === userId;
     },
 
-    async list(userId) {
+    async list(userId, notificationClientId) {
       const client = await db();
-      const rows = await client.pushSubscription.findMany({ where: { userId } });
+      const rows = await client.pushSubscription.findMany({
+        where: reachableBy(userId, notificationClientId),
+      });
       return rows.map((row) => ({
         id: row.id,
         endpoint: row.endpoint,

package/src/server/router.ts

@@ -279,7 +279,11 @@ export function createNotificationRouter(deps: NotificationRouterDeps): Notifica
         Loading first also means a notification addressed to nobody now throws
         before any content is built, which is the cheaper order anyway.
       */
-      const recipient = await loadRecipient(deps, event.recipient.userId);
+      const recipient = await loadRecipient(
+        deps,
+        event.recipient.userId,
+        event.recipient.clientId ?? null,
+      );
       if (!recipient) throw new UnknownNotificationRecipientError(event.recipient.userId);
 
       // Forwarded exactly as the directory stated it, `undefined` included: the

package/src/server/routes.ts

@@ -66,12 +66,14 @@ interface NotificationRoutesDeps {
 async function channelAvailability(
   deps: NotificationRoutesDeps,
   userId: string,
+  scopeClientId: string | null,
 ): Promise<Record<NotificationChannel, boolean>> {
   const contact = await deps.contacts.getContact(userId);
   const recipient = {
     userId,
     email: contact?.email ?? null,
     phone: contact?.phone ?? null,
+    clientId: scopeClientId,
     pushSubscriptionCount: 1,
   };
   return Object.fromEntries(
@@ -86,6 +88,7 @@ async function channelAvailability(
 async function preferencesPayload(
   deps: NotificationRoutesDeps,
   userId: string,
+  scopeClientId: string | null,
 ): Promise<{
   preferences: Record<string, Record<string, boolean>>;
   availability: Record<NotificationChannel, boolean>;
@@ -93,7 +96,7 @@ async function preferencesPayload(
 }> {
   const [preferences, availability] = await Promise.all([
     deps.preferences.get(userId),
-    channelAvailability(deps, userId),
+    channelAvailability(deps, userId, scopeClientId),
   ]);
   // `categories` travels with the matrix so the settings screen renders the
   // HOST's taxonomy without being told it twice (once in the api config, once
@@ -111,6 +114,7 @@ function inboxRoutes(deps: NotificationRoutesDeps): NotificationsRoute[] {
           await deps.inbox.list(
             actor.userId,
             parseListQuery(query, messagesOf(deps, locale)),
+            actor.scopeClientId,
           ),
         ),
       ),
@@ -120,7 +124,7 @@ function inboxRoutes(deps: NotificationRoutesDeps): NotificationsRoute[] {
       path: '/notifications/unread-count',
       handle: guarded(async ({ actor }) =>
         // Polled by the SPAs, so it stays a single indexed COUNT.
-        ok({ count: await deps.inbox.unreadCount(actor.userId) }),
+        ok({ count: await deps.inbox.unreadCount(actor.userId, actor.scopeClientId) }),
       ),
     },
     {
@@ -130,7 +134,7 @@ function inboxRoutes(deps: NotificationRoutesDeps): NotificationsRoute[] {
         const target = parseMarkReadBody(body, messagesOf(deps, locale));
         const updated =
           'all' in target
-            ? await deps.inbox.markAllRead(actor.userId)
+            ? await deps.inbox.markAllRead(actor.userId, actor.scopeClientId)
             : await deps.inbox.markRead(actor.userId, target.ids);
         // Only when something actually flipped. This endpoint is idempotent, so
         // a re-send of an already-read id reports `updated: 0` and has changed
@@ -163,7 +167,9 @@ function preferenceRoutes(deps: NotificationRoutesDeps): NotificationsRoute[] {
     {
       method: 'GET',
       path: '/notification-preferences',
-      handle: guarded(async ({ actor }) => ok(await preferencesPayload(deps, actor.userId))),
+      handle: guarded(async ({ actor }) =>
+        ok(await preferencesPayload(deps, actor.userId, actor.scopeClientId ?? null)),
+      ),
     },
     {
       method: 'PUT',
@@ -175,7 +181,7 @@ function preferenceRoutes(deps: NotificationRoutesDeps): NotificationsRoute[] {
           actor.userId,
           parsePreferencesBody(body, messagesOf(deps, locale)),
         );
-        return ok(await preferencesPayload(deps, actor.userId));
+        return ok(await preferencesPayload(deps, actor.userId, actor.scopeClientId ?? null));
       }),
     },
   ];
@@ -208,6 +214,9 @@ function pushRoutes(deps: NotificationRoutesDeps): NotificationsRoute[] {
         const input = parsePushSubscriptionBody(body, messagesOf(deps, locale));
         const userAgent = headers?.['user-agent'];
         await deps.pushSubscriptions.save(actor.userId, {
+          // The HOST's resolved origin, never the body's — a caller cannot
+          // choose which store's app their browser counts as.
+          clientId: actor.scopeClientId ?? null,
           ...input,
           ...(userAgent ? { userAgent } : {}),
         });

package/src/server/transports/web-push.ts

@@ -90,7 +90,20 @@ export interface WebPushDriverDeclaration extends DriverDeclarationBase {
 
 /** The subscriptions the transport reads and prunes (db-backed by the mount). */
 export interface WebPushSubscriptionSource {
-  list(userId: string): Promise<{ id: string; endpoint: string; p256dh: string; auth: string }[]>;
+  /**
+   * The subscriptions one notification may reach.
+   *
+   * `notificationClientId` is the notification's tenant — `null` for a
+   * platform-wide one, which every subscription receives. An ADOPTER with a
+   * hand-written source must honour it: a function declared with fewer
+   * parameters still type-checks, so an un-updated implementation silently
+   * ignores the scope and keeps fanning out to every origin, with nothing
+   * failing to compile to say so.
+   */
+  list(
+    userId: string,
+    notificationClientId?: string | null,
+  ): Promise<{ id: string; endpoint: string; p256dh: string; auth: string }[]>;
   prune(id: string): Promise<void>;
 }
 
@@ -159,7 +172,7 @@ export function webPushTransport(
     supports: (recipient: TransportRecipient) => recipient.pushSubscriptionCount > 0,
     format: formatWebPush,
     async send(message, recipient) {
-      const rows = await subscriptions.list(recipient.userId);
+      const rows = await subscriptions.list(recipient.userId, recipient.clientId);
       if (rows.length === 0) throw new Error('Recipient no longer has push subscriptions.');
       const payload = JSON.stringify(message);
       let delivered = 0;

package/src/types.ts

@@ -190,8 +190,26 @@ export interface TransportRecipient {
   locale?: string | null;
   /** Phone as the host stores it (transports normalize per provider rules). */
   phone: string | null;
-  /** How many active browser push subscriptions the user holds. */
+  /**
+   * How many push subscriptions this NOTIFICATION can actually reach — not how
+   * many the user holds. Scoped by {@link TransportRecipient.clientId}.
+   */
   pushSubscriptionCount: number;
+  /**
+   * The store this notification belongs to, or `null` for a platform-wide one
+   *.
+   *
+   * REQUIRED, and deliberately so where optional is the tempting answer. An
+   * optional field fails OPEN: a construction site that forgets it yields
+   * `undefined`, which the push scope reads as "platform notification -> every
+   * subscription" — precisely the cross-store fan-out this exists to stop.
+   * Three construction sites is the argument FOR requiring it, not against; the
+   * compiler then names them.
+   *
+   * Not a breaking change for adopters: every external use CONSUMES a recipient
+   * through `supports`/`send` below, and the only constructors are in-package.
+   */
+  clientId: string | null;
 }
 
 /**