@marinoscar/platform-api 0.0.0-stage → 0.1.0-next.4

package/dist/notifications/channels/android-app-notification.channel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"android-app-notification.channel.d.ts","sourceRoot":"","sources":["../../../src/notifications/channels/android-app-notification.channel.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgC,KAAK,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAGjF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AACpE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAClE,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,iCAAiC,EAAE,MAAM,qCAAqC,CAAC;AAGxF,OAAO,EAAE,uBAAuB,EAAE,MAAM,6BAA6B,CAAC;AACtE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAuBtD;;;;;;;GAOG;AACH,qBACa,6BAA8B,SAAQ,uBAAwB,YAAW,YAAY;IAW9F,OAAO,CAAC,QAAQ,CAAC,OAAO;IAV1B,qCAAqC;IACrC,SAAkB,OAAO,EAAE,mBAAmB,CAAuC;gBAG1D,MAAM,EAAE,mBAAmB,EACpD,UAAU,EAAE,iBAAiB,EAIkB,WAAW,EAAE,eAAe,GAAG,IAAI,GAAG,SAAS,EAC7E,OAAO,EAAE,iCAAiC;IAK7D,wFAAwF;IACxF,YAAY,IAAI,IAAI;IAIpB;;;;OAIG;cACgB,iBAAiB,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAI/D;;;;OAIG;cACgB,oBAAoB,IAAI,MAAM;CAGlD"}

package/dist/notifications/channels/android-app-notification.channel.js

@@ -0,0 +1,88 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AndroidAppNotificationChannel = void 0;
+const common_1 = require("@nestjs/common");
+const index_1 = require("../../core/index");
+const push_config_service_1 = require("../push-config.service");
+const channel_sender_registry_1 = require("../registry/channel-sender.registry");
+const platform_channels_1 = require("../registry/platform-channels");
+const ports_1 = require("../ports");
+const push_notification_channel_1 = require("./push-notification.channel");
+// =============================================================================
+// AndroidAppNotificationChannel (#746, PP-9.4; harvested from EvoPath #312)
+// =============================================================================
+//
+// The `push` sender restricted to the subscriptions registered from inside the
+// Android companion (`push_subscriptions.platform = 'android_app'`). Same
+// render, same inbox row, same pruning: only the subscription scope and the
+// "nothing to push to" error differ, through the push channel's two
+// protected hooks.
+//
+// NOT A PLATFORM SENDER. It registers itself with
+// `NotificationChannelSenderRegistry` from `onModuleInit`, like any app
+// channel, because the `android_app` channel id exists only when the app's
+// manifest called `registerAndroidAppNotificationChannel()`. The provider is
+// `AndroidAppModule` (`@marinoscar/platform-api/android-app`); an app without
+// the Android companion never declares the id and never builds this class.
+//
+// `push` covers it (`coveredBy: 'push'`): a dispatch resolving both keeps only
+// `push`, so no subscription is pushed twice (`collapseOverlappingChannels`).
+// =============================================================================
+/**
+ * The `android_app` channel's transport: Web Push to Android app
+ * subscriptions only. Provided and self-registered by `AndroidAppModule`;
+ * exported for that sibling slice and for an app's unit tests, not an
+ * extension point.
+ *
+ * @internal
+ */
+let AndroidAppNotificationChannel = class AndroidAppNotificationChannel extends push_notification_channel_1.PushNotificationChannel {
+    senders;
+    /** The channel id, `android_app`. */
+    channel = platform_channels_1.ANDROID_APP_NOTIFICATION_CHANNEL.id;
+    constructor(prisma, pushConfig, pushPayload, senders) {
+        super(prisma, pushConfig, pushPayload);
+        this.senders = senders;
+    }
+    /** Registers this sender for `android_app`; the channel id must be registered first. */
+    onModuleInit() {
+        this.senders.register(this);
+    }
+    /**
+     * Only the Android app's subscriptions.
+     *
+     * @returns `{ platform: 'android_app' }`.
+     */
+    subscriptionScope() {
+        return { platform: 'android_app' };
+    }
+    /**
+     * The error recorded when the user never enabled notifications in the app.
+     *
+     * @returns the delivery error text.
+     */
+    noSubscriptionsError() {
+        return 'No Android app push subscriptions for this user';
+    }
+};
+exports.AndroidAppNotificationChannel = AndroidAppNotificationChannel;
+exports.AndroidAppNotificationChannel = AndroidAppNotificationChannel = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Inject)(index_1.PLATFORM_PRISMA)),
+    __param(2, (0, common_1.Optional)()),
+    __param(2, (0, common_1.Inject)(ports_1.NOTIFICATION_PUSH_PAYLOAD)),
+    __metadata("design:paramtypes", [Object, push_config_service_1.PushConfigService, Object, channel_sender_registry_1.NotificationChannelSenderRegistry])
+], AndroidAppNotificationChannel);
+//# sourceMappingURL=android-app-notification.channel.js.map

package/dist/notifications/channels/android-app-notification.channel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"android-app-notification.channel.js","sourceRoot":"","sources":["../../../src/notifications/channels/android-app-notification.channel.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;AAAA,2CAAiF;AAEjF,4CAAmD;AAGnD,gEAA2D;AAC3D,iFAAwF;AACxF,qEAAiF;AACjF,oCAAqD;AACrD,2EAAsE;AAGtE,gFAAgF;AAChF,4EAA4E;AAC5E,gFAAgF;AAChF,EAAE;AACF,+EAA+E;AAC/E,0EAA0E;AAC1E,4EAA4E;AAC5E,oEAAoE;AACpE,mBAAmB;AACnB,EAAE;AACF,kDAAkD;AAClD,wEAAwE;AACxE,2EAA2E;AAC3E,6EAA6E;AAC7E,8EAA8E;AAC9E,2EAA2E;AAC3E,EAAE;AACF,+EAA+E;AAC/E,8EAA8E;AAC9E,gFAAgF;AAEhF;;;;;;;GAOG;AAEI,IAAM,6BAA6B,GAAnC,MAAM,6BAA8B,SAAQ,mDAAuB;IAWrD;IAVnB,qCAAqC;IACnB,OAAO,GAAwB,oDAAgC,CAAC,EAAE,CAAC;IAErF,YAC2B,MAA2B,EACpD,UAA6B,EAIkB,WAA+C,EAC7E,OAA0C;QAE3D,KAAK,CAAC,MAAM,EAAE,UAAU,EAAE,WAAW,CAAC,CAAC;QAFtB,YAAO,GAAP,OAAO,CAAmC;IAG7D,CAAC;IAED,wFAAwF;IACxF,YAAY;QACV,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC9B,CAAC;IAED;;;;OAIG;IACgB,iBAAiB;QAClC,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,CAAC;IACrC,CAAC;IAED;;;;OAIG;IACgB,oBAAoB;QACrC,OAAO,iDAAiD,CAAC;IAC3D,CAAC;CACF,CAAA;AAtCY,sEAA6B;wCAA7B,6BAA6B;IADzC,IAAA,mBAAU,GAAE;IAMR,WAAA,IAAA,eAAM,EAAC,uBAAe,CAAC,CAAA;IAKvB,WAAA,IAAA,iBAAQ,GAAE,CAAA;IAAE,WAAA,IAAA,eAAM,EAAC,iCAAyB,CAAC,CAAA;6CAJlC,uCAAiB,UAKH,2DAAiC;GAXlD,6BAA6B,CAsCzC"}

package/dist/notifications/channels/browser-notification.channel.d.ts

@@ -0,0 +1,125 @@
+import type { NotificationsPrisma } from '../data/notifications-db';
+import type { NotificationChannel } from '../notification-events';
+import { NotificationStreamService } from '../notification-stream.service';
+import type { ChannelDeliveryResult, NotificationChannelSender, NotificationDispatchContext, NotificationRecipient } from '../notification.types';
+export type { BrowserNotificationContent, BrowserNotificationTemplate, } from './browser-templates';
+/**
+ * Exported for an app's own unit tests (`@marinoscar/platform-api/notifications/testing`); not an extension point: reach it through `NotificationsModule` and its documented seams.
+ *
+ * @internal
+ */
+export declare class BrowserNotificationChannel implements NotificationChannelSender {
+    private readonly prisma;
+    private readonly stream;
+    readonly channel: NotificationChannel;
+    private readonly logger;
+    constructor(prisma: NotificationsPrisma, stream: NotificationStreamService);
+    /**
+     * The "address" for this channel is the ACCOUNT ITSELF.
+     *
+     * There is no address to resolve: a browser notification is delivered to a
+     * row in `notifications`, which is keyed by user id. So the user id is what
+     * goes in `notification_deliveries.recipient` — the column that answers
+     * "where did this actually go?" — and the answer for this channel is "into
+     * user X's inbox".
+     *
+     * `null` FOR A RECIPIENT WITH NO ACCOUNT (#128's `allowlist.invitation`,
+     * whose recipient is an email address that has not signed up yet). That is
+     * not a limitation to fix later: `notifications.user_id` is NOT NULL because
+     * an inbox with no account has nobody to open it, and the registry already
+     * declares that event as email-only for the same reason. Returning `null`
+     * means the dispatcher writes no delivery row and makes no attempt, rather
+     * than inventing a placeholder recipient.
+     */
+    resolveTo(recipient: NotificationRecipient): string | null;
+    /**
+     * Write the inbox row, then nudge any open tab.
+     *
+     * NEVER THROWS. Every branch returns a `ChannelDeliveryResult`; the one
+     * genuinely failure-prone operation (the INSERT) is wrapped, and the publish
+     * that follows it cannot throw by its own contract.
+     *
+     * @param to - the user id from {@link resolveTo}, passed in rather than
+     *           re-derived so the delivery row's `recipient` and the row this
+     *           writes can never disagree about who was notified.
+     */
+    deliver(context: NotificationDispatchContext, to: string): Promise<ChannelDeliveryResult>;
+    /**
+     * Render an event's untyped payload into what the user sees.
+     *
+     * -----------------------------------------------------------------------------
+     * ON A TEMPLATE MISS THIS FALLS BACK TO THE REGISTRY. THE EMAIL CHANNEL FAILS.
+     * THE ASYMMETRY IS DELIBERATE.
+     * -----------------------------------------------------------------------------
+     *
+     * `EmailNotificationChannel` records a failed delivery when no template is
+     * registered, because a substituted email is an irreversible message sent to
+     * an address outside this system: wrong copy arrives in someone's mailbox and
+     * cannot be recalled, so refusing is strictly safer than improvising.
+     *
+     * Here the destination is a row in the user's own inbox, inside the app,
+     * correctable by an edit and a redeploy. And there is already user-facing
+     * copy for every event: `label` and `description` are written for the
+     * preferences page (#126), reviewed as product copy, and answer "what is this
+     * and why did I get it?" — generically, but truthfully.
+     *
+     * So the choice on a miss is between a bell that shows a slightly generic
+     * line and a bell that shows NOTHING for an event the registry says the user
+     * should be told about — including `security.role_changed`, which is
+     * `mandatory: true` exactly so it can never be silent. Generic wins.
+     *
+     * It is NOT silent about it: the fallback logs a `warn` naming the event, so
+     * "#128 forgot a template" is visible in the same place an operator already
+     * looks, rather than hiding behind plausible-looking output.
+     */
+    private render;
+}
+/**
+ * Accept a link only if it is unambiguously internal; otherwise drop it.
+ *
+ * -----------------------------------------------------------------------------
+ * A SECURITY CONTROL, ENFORCED ON THE WAY IN
+ * -----------------------------------------------------------------------------
+ *
+ * The web client will put this value in an `href` or hand it to the router.
+ * That makes an unchecked link two vulnerabilities at once:
+ *
+ *   * `https://evil.example/login` — an open redirect wearing this
+ *     application's chrome and its user's trust. Phishing that arrives *inside*
+ *     the product is considerably more convincing than phishing that arrives by
+ *     email.
+ *   * `javascript:...` (and `data:text/html,...`) — script execution in this
+ *     application's own origin, with the user's session, from a string that
+ *     travelled through a notification template.
+ *
+ * VALIDATED AT WRITE TIME, NOT AT RENDER TIME. Storing whatever a template
+ * produced and sanitising on the way out means every current and future
+ * consumer — the bell, the toast, an export, a mobile client — has to remember
+ * to sanitise, and the first one that forgets is the vulnerability. Validating
+ * here means the column only ever holds values that are already safe, so a
+ * consumer that forgets is merely unlucky rather than exploitable.
+ *
+ * ALLOWLIST, NOT DENYLIST: a single leading `/`, no second one, no control
+ * characters. Everything else is rejected, so a scheme nobody has thought of
+ * yet is rejected by default rather than by having been enumerated.
+ *
+ *   accepted:  "/settings", "/admin/users?tab=roles", "/x#frag"
+ *   rejected:  "//evil.example/x"  protocol-relative — a full URL as far as a
+ *                                  browser is concerned, and the classic
+ *                                  bypass of a naive "starts with /" check
+ *              "https://evil/x", "javascript:alert(1)", "data:..."
+ *              "settings"          relative to wherever the user happens to
+ *                                  be, so it resolves differently per page
+ *              "/\\evil.example"   a backslash after the slash: several
+ *                                  browsers normalise `\` to `/`, which makes
+ *                                  this protocol-relative in practice
+ *
+ * A REJECTED LINK IS DROPPED, NOT AN ERROR. The notification itself is still
+ * worth delivering without its link — refusing the whole thing would let a
+ * malformed link silence a mandatory security alert, trading a small usability
+ * bug for the exact failure mode `mandatory` exists to prevent.
+  *
+  * @stability experimental
+ */
+export declare function sanitizeLink(link: string | undefined): string | null;
+//# sourceMappingURL=browser-notification.channel.d.ts.map

package/dist/notifications/channels/browser-notification.channel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-notification.channel.d.ts","sourceRoot":"","sources":["../../../src/notifications/channels/browser-notification.channel.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAEpE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAElE,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAE3E,OAAO,KAAK,EACV,qBAAqB,EACrB,yBAAyB,EACzB,2BAA2B,EAC3B,qBAAqB,EACtB,MAAM,uBAAuB,CAAC;AAyD/B,YAAY,EACV,0BAA0B,EAC1B,2BAA2B,GAC5B,MAAM,qBAAqB,CAAC;AAY7B;;;;GAIG;AACH,qBACa,0BAA2B,YAAW,yBAAyB;IAM/C,OAAO,CAAC,QAAQ,CAAC,MAAM;IAChD,OAAO,CAAC,QAAQ,CAAC,MAAM;IANzB,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAa;IAElD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA+C;gBAG1B,MAAM,EAAE,mBAAmB,EACpD,MAAM,EAAE,yBAAyB;IAGpD;;;;;;;;;;;;;;;;OAgBG;IACH,SAAS,CAAC,SAAS,EAAE,qBAAqB,GAAG,MAAM,GAAG,IAAI;IAI1D;;;;;;;;;;OAUG;IACG,OAAO,CACX,OAAO,EAAE,2BAA2B,EACpC,EAAE,EAAE,MAAM,GACT,OAAO,CAAC,qBAAqB,CAAC;IAgGjC;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,OAAO,CAAC,MAAM;CAqCf;AAYD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAWpE"}

package/dist/notifications/channels/browser-notification.channel.js

@@ -0,0 +1,312 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+var BrowserNotificationChannel_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BrowserNotificationChannel = void 0;
+exports.sanitizeLink = sanitizeLink;
+const common_1 = require("@nestjs/common");
+const index_1 = require("../../core/index");
+const describe_thrown_1 = require("../describe-thrown");
+const notification_policy_1 = require("../notification-policy");
+const notification_stream_service_1 = require("../notification-stream.service");
+const registry_1 = require("../registry");
+// `EVENT_BROWSER_TEMPLATES` (a frozen snapshot of the binding registry) is gone from the
+// package since #738: taken at package load, before the app's manifest ran,
+// it would be empty. The channel reads the registry live; the reference app
+// keeps the snapshot in `apps/api/src/platform/notifications/index.ts`.
+/** Length caps applied before the row is written. See {@link truncate}. */
+const MAX_TITLE_LENGTH = 200;
+const MAX_BODY_LENGTH = 2_000;
+/**
+ * Exported for an app's own unit tests (`@marinoscar/platform-api/notifications/testing`); not an extension point: reach it through `NotificationsModule` and its documented seams.
+ *
+ * @internal
+ */
+let BrowserNotificationChannel = BrowserNotificationChannel_1 = class BrowserNotificationChannel {
+    prisma;
+    stream;
+    channel = 'browser';
+    logger = new common_1.Logger(BrowserNotificationChannel_1.name);
+    constructor(prisma, stream) {
+        this.prisma = prisma;
+        this.stream = stream;
+    }
+    /**
+     * The "address" for this channel is the ACCOUNT ITSELF.
+     *
+     * There is no address to resolve: a browser notification is delivered to a
+     * row in `notifications`, which is keyed by user id. So the user id is what
+     * goes in `notification_deliveries.recipient` — the column that answers
+     * "where did this actually go?" — and the answer for this channel is "into
+     * user X's inbox".
+     *
+     * `null` FOR A RECIPIENT WITH NO ACCOUNT (#128's `allowlist.invitation`,
+     * whose recipient is an email address that has not signed up yet). That is
+     * not a limitation to fix later: `notifications.user_id` is NOT NULL because
+     * an inbox with no account has nobody to open it, and the registry already
+     * declares that event as email-only for the same reason. Returning `null`
+     * means the dispatcher writes no delivery row and makes no attempt, rather
+     * than inventing a placeholder recipient.
+     */
+    resolveTo(recipient) {
+        return recipient.userId;
+    }
+    /**
+     * Write the inbox row, then nudge any open tab.
+     *
+     * NEVER THROWS. Every branch returns a `ChannelDeliveryResult`; the one
+     * genuinely failure-prone operation (the INSERT) is wrapped, and the publish
+     * that follows it cannot throw by its own contract.
+     *
+     * @param to - the user id from {@link resolveTo}, passed in rather than
+     *           re-derived so the delivery row's `recipient` and the row this
+     *           writes can never disagree about who was notified.
+     */
+    async deliver(context, to) {
+        const eventKey = context.event.key;
+        const rendered = this.render(context);
+        if (!rendered.ok) {
+            return { success: false, error: rendered.error };
+        }
+        // Normalised ONCE, here, and the same values are used for the row and for
+        // the stream. Applying the cap and the link check twice would be two
+        // chances for a tab to be shown something the database does not hold — and
+        // the stream copy is the one a native toast renders, so a divergence is a
+        // user seeing text that no audit of the table can explain.
+        const title = truncate(rendered.content.title, MAX_TITLE_LENGTH);
+        const body = truncate(rendered.content.body, MAX_BODY_LENGTH);
+        const link = sanitizeLink(rendered.content.link);
+        let notification;
+        try {
+            notification = await this.prisma.notification.create({
+                data: { userId: to, eventKey, title, body, link },
+                select: { id: true, createdAt: true },
+            });
+        }
+        catch (err) {
+            // The database IS the delivery for this channel. A failed INSERT is a
+            // genuinely failed notification — unlike a publish that reaches no
+            // subscriber — so it is reported as one and lands in
+            // `notification_deliveries.error`.
+            return {
+                success: false,
+                error: `Could not write the notification record: ${(0, describe_thrown_1.describeThrown)(err)}`,
+            };
+        }
+        // Published AFTER the row is committed, never before. A tab that receives
+        // the event immediately renders or refetches from the same store;
+        // publishing first opens a window in which the client is told about a
+        // notification a refetch cannot find, which reads to the user as a bell
+        // that flickers and loses an item.
+        //
+        // `publish` never throws and returns how many connections it reached. ZERO
+        // IS SUCCESS: the user simply has no tab open, which is the normal state
+        // of most accounts most of the time. Treating it as a failure would fill
+        // `notification_deliveries` with failed rows for notifications that were
+        // delivered perfectly well, and would bury the real failures that table
+        // exists to surface.
+        const delivered = this.stream.publish(to, {
+            id: notification.id,
+            eventKey,
+            title,
+            body,
+            link,
+            createdAt: notification.createdAt.toISOString(),
+            // THE ADMIN POLICY, APPLIED TO THE TOAST AND ONLY TO THE TOAST (#226).
+            //
+            // Note where this sits: AFTER the row was written, and on an event that
+            // is published regardless of its value. That is the invariant of #226 in
+            // one line of code — an operator who mutes browser notifications mutes
+            // the OS bubble, never the durable record. `security.role_changed` is
+            // `mandatory: true` precisely so a privilege change is never silent, and
+            // a policy that could suppress its inbox row would defeat the flag from
+            // the admin page.
+            //
+            // Read from the dispatch context rather than re-queried, so this flag and
+            // the channel decision that produced the row come from one snapshot of
+            // the policy. Absent policy resolves to the permissive default; see
+            // notification-policy.ts.
+            toast: (0, notification_policy_1.isBrowserToastAllowed)(eventKey, context.policy),
+            // IS WEB PUSH PART OF THIS SAME DISPATCH? (#625)
+            //
+            // Read from the dispatcher's final channel list — policy, preferences
+            // and any per-dispatch narrowing already applied — so it describes THIS
+            // dispatch, mandatory events included. It says the push channel will be
+            // attempted, not that it succeeded or that this browser holds a
+            // subscription; the client combines it with its own subscription state
+            // to avoid a duplicate OS toast. Independent of `toast`.
+            pushed: context.channels.includes('push'),
+        });
+        // Event key and connection count only — no title, no body, no link. The
+        // rendered text is what the user was told and can name a role, an
+        // administrator or a resource; application logs are shipped, indexed and
+        // retained far more widely than the `notifications` table is. The content
+        // has exactly one home and this is not it.
+        this.logger.log(`Recorded '${eventKey}' for user ${to} (live to ${delivered} connection(s)).`);
+        // The row id is the message id. It is the one durable handle tying a
+        // `notification_deliveries` row to the `notifications` row it produced,
+        // which is how "the delivery record says sent — what did they actually
+        // see?" gets answered.
+        return { success: true, messageId: notification.id };
+    }
+    /**
+     * Render an event's untyped payload into what the user sees.
+     *
+     * -----------------------------------------------------------------------------
+     * ON A TEMPLATE MISS THIS FALLS BACK TO THE REGISTRY. THE EMAIL CHANNEL FAILS.
+     * THE ASYMMETRY IS DELIBERATE.
+     * -----------------------------------------------------------------------------
+     *
+     * `EmailNotificationChannel` records a failed delivery when no template is
+     * registered, because a substituted email is an irreversible message sent to
+     * an address outside this system: wrong copy arrives in someone's mailbox and
+     * cannot be recalled, so refusing is strictly safer than improvising.
+     *
+     * Here the destination is a row in the user's own inbox, inside the app,
+     * correctable by an edit and a redeploy. And there is already user-facing
+     * copy for every event: `label` and `description` are written for the
+     * preferences page (#126), reviewed as product copy, and answer "what is this
+     * and why did I get it?" — generically, but truthfully.
+     *
+     * So the choice on a miss is between a bell that shows a slightly generic
+     * line and a bell that shows NOTHING for an event the registry says the user
+     * should be told about — including `security.role_changed`, which is
+     * `mandatory: true` exactly so it can never be silent. Generic wins.
+     *
+     * It is NOT silent about it: the fallback logs a `warn` naming the event, so
+     * "#128 forgot a template" is visible in the same place an operator already
+     * looks, rather than hiding behind plausible-looking output.
+     */
+    render(context) {
+        const { event, data } = context;
+        const template = registry_1.eventBrowserTemplateRegistry.get(event.key)?.render;
+        if (!template) {
+            this.logger.warn(`No browser template registered for '${event.key}'; ` +
+                `falling back to the registry's label and description.`);
+            return {
+                ok: true,
+                content: { title: event.label, body: event.description },
+            };
+        }
+        try {
+            // The cast is the boundary, for the reason spelled out at length on
+            // `EmailNotificationChannel.render`: `notify` takes `data: unknown` by
+            // design, so this is the one call site in the system where a payload's
+            // shape is checked by nothing. A template reading `data.actor.email` on
+            // a caller's typo throws a `TypeError` at runtime, and letting that
+            // propagate would violate #125's containment rule — a bad payload would
+            // take down the role change that triggered it.
+            return { ok: true, content: template(data) };
+        }
+        catch (err) {
+            return {
+                ok: false,
+                // The message only, never the payload: `data` is the caller's object
+                // and may hold anything, and this string is persisted.
+                error: `Rendering the browser notification for '${event.key}' failed: ${(0, describe_thrown_1.describeThrown)(err)}`,
+            };
+        }
+    }
+};
+exports.BrowserNotificationChannel = BrowserNotificationChannel;
+exports.BrowserNotificationChannel = BrowserNotificationChannel = BrowserNotificationChannel_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Inject)(index_1.PLATFORM_PRISMA)),
+    __metadata("design:paramtypes", [Object, notification_stream_service_1.NotificationStreamService])
+], BrowserNotificationChannel);
+/**
+ * Characters that must never appear in a stored link.
+ *
+ * C0 controls, DEL, and the space. Browsers STRIP tab, newline and carriage
+ * return from a URL before parsing it, so `java<TAB>script:alert(1)` is a live
+ * payload that would otherwise sail past every structural test below by not
+ * literally starting with `javascript:`.
+ */
+const FORBIDDEN_LINK_CHARS = /[\u0000-\u0020\u007F]/;
+/**
+ * Accept a link only if it is unambiguously internal; otherwise drop it.
+ *
+ * -----------------------------------------------------------------------------
+ * A SECURITY CONTROL, ENFORCED ON THE WAY IN
+ * -----------------------------------------------------------------------------
+ *
+ * The web client will put this value in an `href` or hand it to the router.
+ * That makes an unchecked link two vulnerabilities at once:
+ *
+ *   * `https://evil.example/login` — an open redirect wearing this
+ *     application's chrome and its user's trust. Phishing that arrives *inside*
+ *     the product is considerably more convincing than phishing that arrives by
+ *     email.
+ *   * `javascript:...` (and `data:text/html,...`) — script execution in this
+ *     application's own origin, with the user's session, from a string that
+ *     travelled through a notification template.
+ *
+ * VALIDATED AT WRITE TIME, NOT AT RENDER TIME. Storing whatever a template
+ * produced and sanitising on the way out means every current and future
+ * consumer — the bell, the toast, an export, a mobile client — has to remember
+ * to sanitise, and the first one that forgets is the vulnerability. Validating
+ * here means the column only ever holds values that are already safe, so a
+ * consumer that forgets is merely unlucky rather than exploitable.
+ *
+ * ALLOWLIST, NOT DENYLIST: a single leading `/`, no second one, no control
+ * characters. Everything else is rejected, so a scheme nobody has thought of
+ * yet is rejected by default rather than by having been enumerated.
+ *
+ *   accepted:  "/settings", "/admin/users?tab=roles", "/x#frag"
+ *   rejected:  "//evil.example/x"  protocol-relative — a full URL as far as a
+ *                                  browser is concerned, and the classic
+ *                                  bypass of a naive "starts with /" check
+ *              "https://evil/x", "javascript:alert(1)", "data:..."
+ *              "settings"          relative to wherever the user happens to
+ *                                  be, so it resolves differently per page
+ *              "/\\evil.example"   a backslash after the slash: several
+ *                                  browsers normalise `\` to `/`, which makes
+ *                                  this protocol-relative in practice
+ *
+ * A REJECTED LINK IS DROPPED, NOT AN ERROR. The notification itself is still
+ * worth delivering without its link — refusing the whole thing would let a
+ * malformed link silence a mandatory security alert, trading a small usability
+ * bug for the exact failure mode `mandatory` exists to prevent.
+  *
+  * @stability experimental
+ */
+function sanitizeLink(link) {
+    if (!link)
+        return null;
+    const trimmed = link.trim();
+    if (FORBIDDEN_LINK_CHARS.test(trimmed))
+        return null;
+    if (!trimmed.startsWith('/'))
+        return null;
+    if (trimmed.startsWith('//'))
+        return null;
+    if (trimmed.startsWith('/\\'))
+        return null;
+    return trimmed;
+}
+/**
+ * Hard cap on stored text, cutting at a character boundary and marking it.
+ *
+ * The column is `text` so a legitimately long message is never truncated by
+ * the database, which makes an explicit cap the only remaining guard against
+ * an unbounded one — a body that is a megabyte of accidentally-interpolated
+ * JSON is a bell that never renders and a list page that never returns.
+ *
+ * The ellipsis matters: a silently truncated sentence reads as a bug in the
+ * message, while a marked one reads as a message that was too long.
+ */
+function truncate(value, max) {
+    return value.length <= max ? value : `${value.slice(0, max - 1)}…`;
+}
+//# sourceMappingURL=browser-notification.channel.js.map

package/dist/notifications/channels/browser-notification.channel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-notification.channel.js","sourceRoot":"","sources":["../../../src/notifications/channels/browser-notification.channel.ts"],"names":[],"mappings":"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"}

package/dist/notifications/channels/browser-templates.d.ts

@@ -0,0 +1,98 @@
+/**
+ * What a browser notification renders to.
+ *
+ * The browser-channel analogue of #123's `{ subject, html, text }` email
+ * contract — three fields, no HTML, because the destinations are a bell row
+ * and an OS toast, both of which render plain text and neither of which will
+ * ever run markup from this payload.
+  *
+  * @stability experimental
+ */
+export interface BrowserNotificationContent {
+    /** One short line. The toast headline and the bell row's heading. */
+    title: string;
+    /** A sentence or two of detail. */
+    body: string;
+    /**
+     * Where clicking it should go, as a ROOT-RELATIVE PATH (`/settings/roles`).
+     *
+     * Never an absolute URL. See {@link sanitizeLink} — this value ends up in a
+     * link the user clicks, so it is a security boundary and it is validated
+     * before it is stored, not before it is rendered.
+     */
+    link?: string;
+}
+/**
+ * Renders one event's payload into what the user actually sees.
+ *
+ * @stability experimental
+ */
+export type BrowserNotificationTemplate = (data: never) => BrowserNotificationContent;
+/**
+ * The browser/push rendering of an administrator's broadcast (#322, epic #319).
+ *
+ * A PROJECTION AND NOTHING MORE — and every one of the things it does not do
+ * is done for it, one layer down:
+ *
+ *   * It does NOT truncate. The channel applies `MAX_TITLE_LENGTH` /
+ *     `MAX_BODY_LENGTH` once, to the values it both stores and publishes, so a
+ *     second cap here would be a second chance for the row and the toast to
+ *     disagree about what the message said.
+ *   * It does NOT validate the link. `sanitizeLink` runs in the channel, at
+ *     write time, for the reasons set out on that function — a template that
+ *     pre-checked would move a security control away from the boundary that
+ *     enforces it.
+ *   * It does NOT escape. These destinations are a bell row and an OS toast,
+ *     both of which render plain text and neither of which will ever parse
+ *     markup from this payload. The escaping belongs to the email half, which
+ *     is the only channel emitting HTML.
+ *
+ * It does not branch on `critical` either. The email adds a "you cannot turn
+ * this off" footer because a mailbox has no other place to say it; a toast has
+ * two short lines, and spending one of them on preference mechanics rather than
+ * on the administrator's message would be a poor trade.
+ *
+ * PUSH NEEDS NO SEPARATE REGISTRATION: `push-notification.channel.ts` reads
+ * the same browser binding (and imports `sanitizeLink` from the browser
+ * channel), so one binding serves both channels — do not add a third map.
+ *
+ * The parameter is typed `never` by `BrowserNotificationTemplate` and cast at
+ * the top, the same boundary the channel's `render` describes at length: the
+ * map is reached with an unchecked `data: unknown`, and a payload that does not
+ * match is a recorded delivery failure inside the channel's try/catch, never a
+ * thrown broadcast.
+  *
+  * @stability experimental
+ */
+export declare const broadcastBrowserTemplate: BrowserNotificationTemplate;
+/**
+ * The browser/push rendering of `security.role_changed` (#128).
+ *
+ * The parameter is typed `never` by `BrowserNotificationTemplate` (the map is
+ * reached with an unchecked `data: unknown`), so the cast here is the same
+ * boundary the channel's `render` describes at length. It is inside the
+ * channel's try/catch, so a payload that does not match is a recorded
+ * delivery failure, never a thrown role change.
+  *
+  * @stability experimental
+ */
+export declare const roleChangedBrowserTemplate: BrowserNotificationTemplate;
+/**
+ * The browser/push rendering of `nodes.node_offline` (#288).
+ *
+ * @stability experimental
+ */
+export declare const nodeOfflineBrowserTemplate: BrowserNotificationTemplate;
+/**
+ * The browser/push rendering of `db_backup.backup_failed` (#288).
+ *
+ * @stability experimental
+ */
+export declare const backupFailedBrowserTemplate: BrowserNotificationTemplate;
+/**
+ * The browser/push rendering of `db_backup.restore_completed` (#288).
+ *
+ * @stability experimental
+ */
+export declare const restoreCompletedBrowserTemplate: BrowserNotificationTemplate;
+//# sourceMappingURL=browser-templates.d.ts.map

package/dist/notifications/channels/browser-templates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-templates.d.ts","sourceRoot":"","sources":["../../../src/notifications/channels/browser-templates.ts"],"names":[],"mappings":"AA8BA;;;;;;;;;GASG;AACH,MAAM,WAAW,0BAA0B;IACzC,qEAAqE;IACrE,KAAK,EAAE,MAAM,CAAC;IAEd,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAC;IAEb;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,MAAM,MAAM,2BAA2B,GAAG,CACxC,IAAI,EAAE,KAAK,KACR,0BAA0B,CAAC;AAwBhC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,eAAO,MAAM,wBAAwB,EAAE,2BAoBtC,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,0BAA0B,EAAE,2BAmBxC,CAAC;AAeF;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,EAAE,2BAexC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,EAAE,2BAgBzC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,+BAA+B,EAAE,2BAgB7C,CAAC"}