@astram/guard 0.22.0 → 0.24.0

package/dist/notifications/notification-retention.job.js

@@ -0,0 +1,97 @@
+"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);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NotificationRetentionJob = exports.NOTIFICATION_RETENTION_BATCH = exports.NOTIFICATION_RETENTION_INTERVAL_MS = exports.NOTIFICATION_RETENTION_FIRST_RUN_MS = void 0;
+/**
+ * `NotificationRetentionJob` — deletes expired notices (notification-store SPEC §5E, §10, §11).
+ *
+ * Registered with `ShieldModule.forRoot({ auth: true })` beside the store, over guard's core pool
+ * `SHIELD_DB_POOL` (it does not own the pool: `ConnectionLifecycle` ends it in
+ * `onApplicationShutdown`, after this job stopped).
+ *
+ * - First pass {@link NOTIFICATION_RETENTION_FIRST_RUN_MS} after bootstrap, then one pass every
+ *   {@link NOTIFICATION_RETENTION_INTERVAL_MS} (hourly), scheduled only after the previous pass
+ *   settled, so passes never overlap.
+ * - One pass = one `purge` of at most {@link NOTIFICATION_RETENTION_BATCH} rows: read notices older
+ *   than `NOTIFICATION_READ_RETENTION_DAYS`, any notice older than `NOTIFICATION_MAX_RETENTION_DAYS`.
+ * - A failed pass is logged by error class only (never the driver message) and retried at the next
+ *   interval; nothing here throws into Nest, so it never blocks boot (a missing table, migration
+ *   108 not applied, is just a logged pass).
+ * - Every timer is `unref()`'d. `onModuleDestroy` (Nest `close()` step 1) clears the timer and
+ *   waits for a running pass. Off the request path (Shield #12).
+ */
+const common_1 = require("@nestjs/common");
+const audit_chain_sealer_js_1 = require("../audit/audit-chain-sealer.js");
+exports.NOTIFICATION_RETENTION_FIRST_RUN_MS = 5_000;
+exports.NOTIFICATION_RETENTION_INTERVAL_MS = 60 * 60 * 1000;
+exports.NOTIFICATION_RETENTION_BATCH = 5000;
+let NotificationRetentionJob = class NotificationRetentionJob {
+    store;
+    policy;
+    now;
+    logger;
+    stopped = false;
+    timer;
+    inFlight;
+    constructor(store, policy, options = {}) {
+        this.store = store;
+        this.policy = policy;
+        this.now = options.now ?? Date.now;
+        this.logger = options.logger ?? new common_1.Logger('Shield');
+    }
+    onApplicationBootstrap() {
+        this.schedule(exports.NOTIFICATION_RETENTION_FIRST_RUN_MS);
+    }
+    async onModuleDestroy() {
+        this.stopped = true;
+        if (this.timer !== undefined)
+            clearTimeout(this.timer);
+        this.timer = undefined;
+        await this.inFlight; // never rejects (runOnce catches)
+    }
+    /**
+     * One retention pass; resolves to the deleted count, or `null` when the pass failed (logged).
+     * Exposed for tests and operators; the timer calls it hourly.
+     */
+    async runOnce() {
+        try {
+            const deleted = await this.store.purge(this.now(), this.policy, exports.NOTIFICATION_RETENTION_BATCH);
+            if (deleted > 0)
+                this.logger.log(`[notifications] retention removed ${deleted} notices`);
+            return deleted;
+        }
+        catch (err) {
+            this.logger.error(`[notifications] retention pass failed (${(0, audit_chain_sealer_js_1.auditSealErrorClass)(err)}); retried next hour`);
+            return null;
+        }
+    }
+    schedule(delayMs) {
+        if (this.stopped || this.timer !== undefined)
+            return;
+        this.timer = setTimeout(() => {
+            this.timer = undefined;
+            if (this.stopped)
+                return;
+            this.inFlight = this.runOnce()
+                .then(() => undefined)
+                .finally(() => {
+                this.inFlight = undefined;
+                this.schedule(exports.NOTIFICATION_RETENTION_INTERVAL_MS);
+            });
+        }, delayMs);
+        this.timer.unref();
+    }
+};
+exports.NotificationRetentionJob = NotificationRetentionJob;
+exports.NotificationRetentionJob = NotificationRetentionJob = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [Object, Object, Object])
+], NotificationRetentionJob);

package/dist/notifications/notification.service.d.ts

@@ -0,0 +1,68 @@
+import type { Pool } from 'mariadb';
+import { type FrameworkSchemaNames } from '../config/framework-schema-names.js';
+import { type NotificationCategory, type NotificationKindRegistration, type NotificationStore, type NotificationWriteOptions } from './ports.js';
+/** SPEC §10 limits. */
+export declare const NOTIFICATION_TITLE_MAX = 160;
+export declare const NOTIFICATION_BODY_MAX = 1000;
+export declare const NOTIFICATION_LINK_MAX = 512;
+export declare const NOTIFICATION_RECIPIENTS_MAX = 1000;
+/** The prefix reserved for the framework's own kinds. */
+export declare const FRAMEWORK_KIND_PREFIX = "shield.";
+/** The framework's own kinds. Step 2 registers none (step 3 adds `shield.access_changed`). */
+export declare const FRAMEWORK_NOTIFICATION_KINDS: readonly NotificationKindRegistration[];
+export interface NotificationPostInput {
+    /** The company the notice belongs to; recipients must be active members of it. */
+    readonly tenantId: string;
+    /** User uuids, 1–1000. Service accounts are not users and never receive notices. */
+    readonly recipients: readonly string[];
+    readonly kind: string;
+    readonly title: string;
+    readonly body?: string | null;
+    /** App-relative path only (`/…`, not `//`, no `\`, no control characters). */
+    readonly link?: string | null;
+    /** Idempotency key per recipient and tenant, 1–64 of `[A-Za-z0-9._:-]`. */
+    readonly dedupeKey?: string | null;
+}
+export interface NotificationPostResult {
+    readonly created: number;
+    readonly skipped: number;
+}
+/** Validated kind registry: kind ⇒ category. */
+export type NotificationKindRegistry = ReadonlyMap<string, NotificationCategory>;
+/**
+ * Build the kind registry from the app's `notificationKinds` (validated at boot, SPEC §5C) and the
+ * framework's own kinds. Refuses a malformed or over-long kind, an unknown category, a duplicate,
+ * and an app kind under the reserved `shield.` prefix; each error names the kind.
+ */
+export declare function resolveNotificationKinds(appKinds: readonly NotificationKindRegistration[] | undefined, frameworkKinds?: readonly NotificationKindRegistration[]): NotificationKindRegistry;
+/** Logs counts only (Nest `Logger` shape). */
+export interface NotificationServiceLogger {
+    debug(message: string): void;
+}
+export interface NotificationServiceOptions {
+    /** Default `Date.now`. */
+    readonly now?: () => number;
+    /** Default `new Logger('Shield')`. */
+    readonly logger?: NotificationServiceLogger;
+}
+export declare class NotificationService {
+    private readonly store;
+    /** Guard's core pool: the recipient filter runs here when no caller `query` is given. */
+    private readonly pool;
+    private readonly kinds;
+    private readonly usersTable;
+    private readonly membershipTable;
+    private readonly now;
+    private readonly logger;
+    constructor(store: NotificationStore, 
+    /** Guard's core pool: the recipient filter runs here when no caller `query` is given. */
+    pool: Pick<Pool, 'query'>, kinds: NotificationKindRegistry, 
+    /** Framework database names; absent ⇒ resolved from `SHIELD_DB_NAMESPACE` here, once. */
+    schemas?: FrameworkSchemaNames, options?: NotificationServiceOptions);
+    /** Whether `kind` is registered (framework or app). */
+    hasKind(kind: string): boolean;
+    post(input: NotificationPostInput, opts?: NotificationWriteOptions): Promise<NotificationPostResult>;
+    /** ONE parameterized SELECT: active users with an active membership in `tenantId`. */
+    private activeRecipients;
+}
+//# sourceMappingURL=notification.service.d.ts.map

package/dist/notifications/notification.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notification.service.d.ts","sourceRoot":"","sources":["../../src/notifications/notification.service.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,EAGL,KAAK,oBAAoB,EAC1B,MAAM,qCAAqC,CAAC;AAC7C,OAAO,EAOL,KAAK,oBAAoB,EAEzB,KAAK,4BAA4B,EAEjC,KAAK,iBAAiB,EACtB,KAAK,wBAAwB,EAC9B,MAAM,YAAY,CAAC;AAEpB,uBAAuB;AACvB,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAC1C,eAAO,MAAM,qBAAqB,OAAO,CAAC;AAC1C,eAAO,MAAM,qBAAqB,MAAM,CAAC;AACzC,eAAO,MAAM,2BAA2B,OAAO,CAAC;AAOhD,yDAAyD;AACzD,eAAO,MAAM,qBAAqB,YAAY,CAAC;AAE/C,8FAA8F;AAC9F,eAAO,MAAM,4BAA4B,EAAE,SAAS,4BAA4B,EAAO,CAAC;AAExF,MAAM,WAAW,qBAAqB;IACpC,kFAAkF;IAClF,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,oFAAoF;IACpF,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,8EAA8E;IAC9E,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,2EAA2E;IAC3E,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACpC;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,gDAAgD;AAChD,MAAM,MAAM,wBAAwB,GAAG,WAAW,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;AAWjF;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,SAAS,4BAA4B,EAAE,GAAG,SAAS,EAC7D,cAAc,GAAE,SAAS,4BAA4B,EAAiC,GACrF,wBAAwB,CAqC1B;AAED,8CAA8C;AAC9C,MAAM,WAAW,yBAAyB;IACxC,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED,MAAM,WAAW,0BAA0B;IACzC,0BAA0B;IAC1B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IAC5B,sCAAsC;IACtC,QAAQ,CAAC,MAAM,CAAC,EAAE,yBAAyB,CAAC;CAC7C;AAED,qBAAa,mBAAmB;IAO5B,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,yFAAyF;IACzF,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,KAAK;IATxB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA4B;gBAGhC,KAAK,EAAE,iBAAiB;IACzC,yFAAyF;IACxE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,EACzB,KAAK,EAAE,wBAAwB;IAChD,yFAAyF;IACzF,OAAO,CAAC,EAAE,oBAAoB,EAC9B,OAAO,GAAE,0BAA+B;IAS1C,uDAAuD;IACvD,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIxB,IAAI,CACR,KAAK,EAAE,qBAAqB,EAC5B,IAAI,GAAE,wBAA6B,GAClC,OAAO,CAAC,sBAAsB,CAAC;IA6ClC,sFAAsF;YACxE,gBAAgB;CAwB/B"}

package/dist/notifications/notification.service.js

@@ -0,0 +1,247 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NotificationService = exports.FRAMEWORK_NOTIFICATION_KINDS = exports.FRAMEWORK_KIND_PREFIX = exports.NOTIFICATION_RECIPIENTS_MAX = exports.NOTIFICATION_LINK_MAX = exports.NOTIFICATION_BODY_MAX = exports.NOTIFICATION_TITLE_MAX = void 0;
+exports.resolveNotificationKinds = resolveNotificationKinds;
+/**
+ * `NotificationService` — the one way app and framework code posts notices (notification-store
+ * SPEC §5B, §5C, §10, §11). Bound under `SHIELD_NOTIFICATIONS` with `ShieldModule.forRoot({ auth:
+ * true })`; exported from the main entry.
+ *
+ * `post(input, opts?)`:
+ * - the kind must be registered (`notificationKinds`, plus the framework's own kinds) ⇒ else
+ *   {@link NotificationKindError}; the CATEGORY comes from that registration, never the caller;
+ * - title / body / link / dedupe key / recipients follow SPEC §10 and §11 ⇒ else
+ *   {@link NotificationValidationError} naming the field, never the value (core 50 #10);
+ * - recipients are canonicalised and de-duplicated, then ONE parameterized SELECT keeps the users
+ *   with `u_status = 'active'` and an active `company_membership` in `tenantId` (on `opts.query`
+ *   when given, so it reads the caller's transaction); the rest are skipped and counted;
+ * - rows go to the store in one statement (on `opts.query` when given: the caller commits or rolls
+ *   back with its own write, step 3);
+ * - ⇒ `{ created, skipped }`; any store error ⇒ {@link NotificationUnavailableError}, the driver
+ *   message dropped. No audit row per notice (not an admin action); a debug log with counts only.
+ *
+ * The tenant is the caller's server-side decision (e.g. the session's active company or the
+ * granting transaction's company), never request input passed through unchecked (core 50 #7).
+ */
+const node_crypto_1 = require("node:crypto");
+const common_1 = require("@nestjs/common");
+const engine_1 = require("@astram/engine");
+const framework_schema_names_js_1 = require("../config/framework-schema-names.js");
+const ports_js_1 = require("./ports.js");
+/** SPEC §10 limits. */
+exports.NOTIFICATION_TITLE_MAX = 160;
+exports.NOTIFICATION_BODY_MAX = 1000;
+exports.NOTIFICATION_LINK_MAX = 512;
+exports.NOTIFICATION_RECIPIENTS_MAX = 1000;
+const DEDUPE_KEY_PATTERN = /^[A-Za-z0-9._:-]{1,64}$/;
+/** U+0000–U+001F and U+007F. */
+// eslint-disable-next-line no-control-regex
+const CONTROL_CHARS = /[\u0000-\u001f\u007f]/;
+// eslint-disable-next-line no-control-regex
+const CONTROL_CHARS_EXCEPT_NEWLINE = /[\u0000-\u0009\u000b-\u001f\u007f]/;
+/** The prefix reserved for the framework's own kinds. */
+exports.FRAMEWORK_KIND_PREFIX = 'shield.';
+/** The framework's own kinds. Step 2 registers none (step 3 adds `shield.access_changed`). */
+exports.FRAMEWORK_NOTIFICATION_KINDS = [];
+/** Length in characters (code points), as `VARCHAR(n)` in utf8mb4 counts them. */
+function codePoints(s) {
+    return Array.from(s).length;
+}
+function isCategory(v) {
+    return ports_js_1.NOTIFICATION_CATEGORIES.includes(v);
+}
+/**
+ * Build the kind registry from the app's `notificationKinds` (validated at boot, SPEC §5C) and the
+ * framework's own kinds. Refuses a malformed or over-long kind, an unknown category, a duplicate,
+ * and an app kind under the reserved `shield.` prefix; each error names the kind.
+ */
+function resolveNotificationKinds(appKinds, frameworkKinds = exports.FRAMEWORK_NOTIFICATION_KINDS) {
+    if (appKinds !== undefined && !Array.isArray(appKinds)) {
+        throw new TypeError('notificationKinds must be an array of { kind, category }');
+    }
+    const registry = new Map();
+    const add = (entry, framework) => {
+        const kind = entry?.kind;
+        const category = entry?.category;
+        if (typeof kind !== 'string') {
+            throw ports_js_1.NotificationKindError.registration(kind, 'must be a string');
+        }
+        if (kind.length > ports_js_1.NOTIFICATION_KIND_MAX_LENGTH) {
+            throw ports_js_1.NotificationKindError.registration(kind, `is longer than ${ports_js_1.NOTIFICATION_KIND_MAX_LENGTH} characters`);
+        }
+        if (!ports_js_1.NOTIFICATION_KIND_PATTERN.test(kind)) {
+            throw ports_js_1.NotificationKindError.registration(kind, 'must be dotted lower-case segments (e.g. app.event_name)');
+        }
+        if (!framework && kind.startsWith(exports.FRAMEWORK_KIND_PREFIX)) {
+            throw ports_js_1.NotificationKindError.registration(kind, 'uses the reserved shield. prefix');
+        }
+        if (!isCategory(category)) {
+            throw ports_js_1.NotificationKindError.registration(kind, 'needs a category: announcement or personal');
+        }
+        if (registry.has(kind)) {
+            throw ports_js_1.NotificationKindError.registration(kind, 'is registered more than once');
+        }
+        registry.set(kind, category);
+    };
+    for (const entry of frameworkKinds)
+        add(entry, true);
+    for (const entry of appKinds ?? [])
+        add(entry, false);
+    return registry;
+}
+class NotificationService {
+    store;
+    pool;
+    kinds;
+    usersTable;
+    membershipTable;
+    now;
+    logger;
+    constructor(store, 
+    /** Guard's core pool: the recipient filter runs here when no caller `query` is given. */
+    pool, kinds, 
+    /** Framework database names; absent ⇒ resolved from `SHIELD_DB_NAMESPACE` here, once. */
+    schemas, options = {}) {
+        this.store = store;
+        this.pool = pool;
+        this.kinds = kinds;
+        const s = (0, framework_schema_names_js_1.schemaNamesAtConstruction)(schemas);
+        this.usersTable = (0, framework_schema_names_js_1.qualifiedTableName)(s.app, 'users');
+        this.membershipTable = (0, framework_schema_names_js_1.qualifiedTableName)(s.app, 'company_membership');
+        this.now = options.now ?? Date.now;
+        this.logger = options.logger ?? new common_1.Logger('Shield');
+    }
+    /** Whether `kind` is registered (framework or app). */
+    hasKind(kind) {
+        return this.kinds.has(kind);
+    }
+    async post(input, opts = {}) {
+        if (typeof input !== 'object' || input === null) {
+            throw new ports_js_1.NotificationValidationError('input', 'must be an object');
+        }
+        if (opts.query !== undefined && typeof opts.query !== 'function') {
+            throw new ports_js_1.NotificationValidationError('query', 'must be a function');
+        }
+        const tenantId = (0, engine_1.canonicalUuid)(input.tenantId);
+        if (tenantId === null)
+            throw new ports_js_1.NotificationValidationError('tenantId', 'must be a uuid');
+        const category = typeof input.kind === 'string' ? this.kinds.get(input.kind) : undefined;
+        if (category === undefined)
+            throw new ports_js_1.NotificationKindError(input.kind);
+        const title = validTitle(input.title);
+        const body = validBody(input.body);
+        const link = validLink(input.link);
+        const dedupeKey = validDedupeKey(input.dedupeKey);
+        const recipients = validRecipients(input.recipients);
+        const query = opts.query ?? ((sql, params) => this.pool.query(sql, params));
+        let created;
+        try {
+            const active = await this.activeRecipients(query, tenantId, recipients);
+            const createdAtMs = this.now();
+            const rows = active.map((userId) => ({
+                uuid: (0, node_crypto_1.randomUUID)(),
+                tenantId,
+                userId,
+                category,
+                kind: input.kind,
+                title,
+                body,
+                link,
+                dedupeKey,
+                createdAtMs,
+            }));
+            created = await this.store.insertMany(rows, opts.query ? { query: opts.query } : {});
+        }
+        catch {
+            // The driver message may name tables, values or hosts: never carried (core 50 #10).
+            throw new ports_js_1.NotificationUnavailableError();
+        }
+        const skipped = recipients.length - created;
+        this.logger.debug(`[notifications] posted: created=${created} skipped=${skipped}`);
+        return { created, skipped };
+    }
+    /** ONE parameterized SELECT: active users with an active membership in `tenantId`. */
+    async activeRecipients(query, tenantId, recipients) {
+        const marks = recipients.map(() => '?').join(', ');
+        // `cm_status = 'active'` only (SPEC §5B): `cm_is_active` is the user's ONE default-company
+        // pointer (identity `MembershipService.setActive`), so requiring it would drop members whose
+        // default company is another one.
+        const rows = await query(`SELECT u.u_uuid AS id FROM ${this.usersTable} u
+        WHERE u.u_uuid IN (${marks}) AND u.u_status = 'active'
+          AND EXISTS (SELECT 1 FROM ${this.membershipTable} cm
+                       WHERE cm.cm_user_uuid = u.u_uuid AND cm.cm_company_uuid = ?
+                         AND cm.cm_status = 'active')`, [...recipients, tenantId]);
+        if (!Array.isArray(rows))
+            throw new Error('unexpected recipient result');
+        const found = new Set(rows.map((r) => (0, engine_1.canonicalUuid)(r.id)).filter((v) => v !== null));
+        // Keep the caller's order; every id came from the canonical recipient list.
+        return recipients.filter((id) => found.has(id));
+    }
+}
+exports.NotificationService = NotificationService;
+function validTitle(v) {
+    if (typeof v !== 'string')
+        throw new ports_js_1.NotificationValidationError('title', 'must be a string');
+    const title = v.trim();
+    const n = codePoints(title);
+    if (n < 1 || n > exports.NOTIFICATION_TITLE_MAX) {
+        throw new ports_js_1.NotificationValidationError('title', `must be 1 to ${exports.NOTIFICATION_TITLE_MAX} characters`);
+    }
+    if (CONTROL_CHARS.test(title)) {
+        throw new ports_js_1.NotificationValidationError('title', 'must not contain control characters');
+    }
+    return title;
+}
+function validBody(v) {
+    if (v === undefined || v === null || v === '')
+        return null;
+    if (typeof v !== 'string')
+        throw new ports_js_1.NotificationValidationError('body', 'must be a string');
+    if (codePoints(v) > exports.NOTIFICATION_BODY_MAX) {
+        throw new ports_js_1.NotificationValidationError('body', `must be at most ${exports.NOTIFICATION_BODY_MAX} characters`);
+    }
+    if (CONTROL_CHARS_EXCEPT_NEWLINE.test(v)) {
+        throw new ports_js_1.NotificationValidationError('body', 'must not contain control characters other than newline');
+    }
+    return v;
+}
+function validLink(v) {
+    if (v === undefined || v === null || v === '')
+        return null;
+    if (typeof v !== 'string')
+        throw new ports_js_1.NotificationValidationError('link', 'must be a string');
+    if (codePoints(v) > exports.NOTIFICATION_LINK_MAX) {
+        throw new ports_js_1.NotificationValidationError('link', `must be at most ${exports.NOTIFICATION_LINK_MAX} characters`);
+    }
+    // App-relative only: one leading `/` (never `//`, a protocol-relative URL), so no scheme or host
+    // can follow; no backslash (browsers treat `/\` like `//`); no control characters.
+    if (!v.startsWith('/') || v.startsWith('//')) {
+        throw new ports_js_1.NotificationValidationError('link', 'must be an app-relative path starting with /');
+    }
+    if (v.includes('\\') || CONTROL_CHARS.test(v)) {
+        throw new ports_js_1.NotificationValidationError('link', 'must not contain backslashes or control characters');
+    }
+    return v;
+}
+function validDedupeKey(v) {
+    if (v === undefined || v === null)
+        return null;
+    if (typeof v !== 'string' || !DEDUPE_KEY_PATTERN.test(v)) {
+        throw new ports_js_1.NotificationValidationError('dedupeKey', 'must be 1 to 64 of A-Z a-z 0-9 . _ : -');
+    }
+    return v;
+}
+function validRecipients(v) {
+    if (!Array.isArray(v) || v.length < 1 || v.length > exports.NOTIFICATION_RECIPIENTS_MAX) {
+        throw new ports_js_1.NotificationValidationError('recipients', `must be a list of 1 to ${exports.NOTIFICATION_RECIPIENTS_MAX} user uuids`);
+    }
+    const out = new Set();
+    for (const id of v) {
+        const canonical = (0, engine_1.canonicalUuid)(id);
+        if (canonical === null) {
+            throw new ports_js_1.NotificationValidationError('recipients', 'must contain user uuids only');
+        }
+        out.add(canonical);
+    }
+    return [...out];
+}

package/dist/notifications/notifications.controller.d.ts

@@ -0,0 +1,57 @@
+import type { SessionTokenBinder } from '../request-auth/session-token-binder.js';
+import type { MfaRequirementService } from '../session/mfa-requirement-service.js';
+import { type NotificationCategory, type NotificationStore } from './ports.js';
+/** One notice as the API returns it: no tenant id, user id or dedupe key (SPEC §5D). */
+export interface NotificationView {
+    readonly uuid: string;
+    readonly category: NotificationCategory;
+    readonly kind: string;
+    readonly title: string;
+    readonly body: string | null;
+    readonly link: string | null;
+    /** ISO 8601. */
+    readonly createdAt: string;
+    /** ISO 8601; `null` ⇒ unread. */
+    readonly readAt: string | null;
+}
+export interface NotificationListView {
+    readonly total: number;
+    readonly rows: NotificationView[];
+    readonly page: number;
+    readonly limit: number;
+}
+export interface NotificationUnreadCountView {
+    readonly announcement: number;
+    readonly personal: number;
+    readonly total: number;
+}
+type QueryParams = Record<string, unknown> | undefined;
+export declare class NotificationsController {
+    private readonly binder?;
+    private readonly store?;
+    private readonly mfaRequirement?;
+    constructor(binder?: SessionTokenBinder | undefined, store?: (NotificationStore | null) | undefined, mfaRequirement?: (MfaRequirementService | null) | undefined);
+    /**
+     * The caller's claims after the mandatory-2FA refresh and the restriction gate (mirrors
+     * `AccountController.requireClaims` + `enforceReenroll(claims, false)`): no notification route is
+     * allowed during a restriction.
+     */
+    private requireSession;
+    private requireStore;
+    /** `GET /account/notifications` — newest first ⇒ `{ total, rows, page, limit }`. */
+    list(authorization: string | undefined, query: QueryParams): Promise<NotificationListView>;
+    /** `GET /account/notifications/unread-count` ⇒ `{ announcement, personal, total }`. */
+    unreadCount(authorization: string | undefined): Promise<NotificationUnreadCountView>;
+    /** `POST /account/notifications/read-all?category=` ⇒ `{ updated }`. */
+    readAll(authorization: string | undefined, query: QueryParams): Promise<{
+        updated: number;
+    }>;
+    /**
+     * `POST /account/notifications/:uuid/read` ⇒ 204 (idempotent: the first read time is kept).
+     * The uuid is canonicalised here, after the session check (401 before 400), as
+     * `/account/mfa/devices/:id` does.
+     */
+    read(authorization: string | undefined, rawUuid: string): Promise<void>;
+}
+export {};
+//# sourceMappingURL=notifications.controller.d.ts.map

package/dist/notifications/notifications.controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notifications.controller.d.ts","sourceRoot":"","sources":["../../src/notifications/notifications.controller.ts"],"names":[],"mappings":"AAoCA,OAAO,KAAK,EAEV,kBAAkB,EACnB,MAAM,yCAAyC,CAAC;AAEjD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,uCAAuC,CAAC;AAEnF,OAAO,EAEL,KAAK,oBAAoB,EAEzB,KAAK,iBAAiB,EACvB,MAAM,YAAY,CAAC;AASpB,wFAAwF;AACxF,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,CAAC;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,gBAAgB;IAChB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,iCAAiC;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,gBAAgB,EAAE,CAAC;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AA8ED,KAAK,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;AAEvD,qBACa,uBAAuB;IAKhC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;IAIxB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC;IAIvB,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC;gBARf,MAAM,CAAC,EAAE,kBAAkB,YAAA,EAI3B,KAAK,CAAC,GAAE,iBAAiB,GAAG,IAAI,aAAA,EAIhC,cAAc,CAAC,GAAE,qBAAqB,GAAG,IAAI,aAAA;IAGhE;;;;OAIG;YACW,cAAc;IAgB5B,OAAO,CAAC,YAAY;IAKpB,oFAAoF;IAI9E,IAAI,CACkB,aAAa,EAAE,MAAM,GAAG,SAAS,EAClD,KAAK,EAAE,WAAW,GAC1B,OAAO,CAAC,oBAAoB,CAAC;IAoBhC,uFAAuF;IAIjF,WAAW,CACW,aAAa,EAAE,MAAM,GAAG,SAAS,GAC1D,OAAO,CAAC,2BAA2B,CAAC;IAWvC,wEAAwE;IAIlE,OAAO,CACe,aAAa,EAAE,MAAM,GAAG,SAAS,EAClD,KAAK,EAAE,WAAW,GAC1B,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAU/B;;;;OAIG;IAIG,IAAI,CACkB,aAAa,EAAE,MAAM,GAAG,SAAS,EAC5C,OAAO,EAAE,MAAM,GAC7B,OAAO,CAAC,IAAI,CAAC;CAOjB"}