@astram/guard 0.23.0 → 0.25.0

package/dist/notifications/notification.service.js

@@ -0,0 +1,252 @@
+"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. G-027 step 3: `shield.access_changed` (identity's
+ * `AccessChangeNotifier`, a personal notice listing the recipient's gained / lost capabilities).
+ */
+exports.FRAMEWORK_NOTIFICATION_KINDS = [
+    { kind: `${exports.FRAMEWORK_KIND_PREFIX}access_changed`, category: 'personal' },
+];
+/** 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"}

package/dist/notifications/notifications.controller.js

@@ -0,0 +1,257 @@
+"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.NotificationsController = void 0;
+/**
+ * `/account/notifications` — the signed-in user's own notice inbox (G-027 step 2,
+ * notification-store SPEC §3, §5D, §13).
+ *
+ * Self-authenticated exactly like {@link AccountController} (`packages/guard/src/auth/account.controller.ts`):
+ * every handler is `@Public()` to the classification guard, resolves the bearer through the
+ * {@link SessionTokenBinder} (session tokens only, so an `ask_…` API key is the generic 401), runs
+ * the mandatory-2FA refresh on a permission-version move, then the restriction gate. No `decide()`:
+ * a user always may read their own notices.
+ *
+ * Scope is ONLY `claims.id` in `claims.tenantId` (the session's active company); nothing scoping is
+ * read from the request (core 50 #4, #7; Shield #4). A notice of another user or company is the
+ * same 404 as a missing one.
+ *
+ * Order on every route: 401 (no/invalid session) → 403 (restricted session) → 501 (store not
+ * wired) → 400 (bad query parameter or `:uuid`, naming the parameter, never echoing the value) →
+ * store call (any throw ⇒ 503 `notifications_unavailable`, the driver message never surfaces).
+ */
+const common_1 = require("@nestjs/common");
+const classification_decorator_js_1 = require("../enforcement/classification.decorator.js");
+const uuid_pipe_js_1 = require("../enforcement/uuid.pipe.js");
+const request_principal_js_1 = require("../request-auth/request-principal.js");
+const tokens_js_1 = require("../request-auth/tokens.js");
+const tokens_js_2 = require("../auth/tokens.js");
+const session_restriction_js_1 = require("../session/session-restriction.js");
+const ports_js_1 = require("./ports.js");
+/** Default and maximum page size (SPEC §10). */
+const DEFAULT_LIMIT = 20;
+const MAX_LIMIT = 100;
+/** A decimal integer as a query string (no sign, no exponent, no whitespace). */
+const DIGITS = /^[0-9]{1,16}$/;
+/** The generic 401, as `/account/*` (never distinguishes no token / bad token / API key). */
+function unauthorized() {
+    throw new common_1.HttpException({ error: 'unauthorized' }, common_1.HttpStatus.UNAUTHORIZED);
+}
+/** The honest 501 when the store is not wired (as `/account/*` seams). */
+function notAvailable() {
+    throw new common_1.HttpException({ error: 'not_available' }, common_1.HttpStatus.NOT_IMPLEMENTED);
+}
+/** The one 404 body for a foreign or unknown notice. */
+function notFound() {
+    throw new common_1.HttpException({ error: 'not_found' }, common_1.HttpStatus.NOT_FOUND);
+}
+/** The store could not answer: 503 without the driver message (core 50 #10). */
+function unavailable() {
+    throw new common_1.HttpException({ error: 'notifications_unavailable' }, common_1.HttpStatus.SERVICE_UNAVAILABLE);
+}
+/** 400 naming the parameter only. */
+function badParameter(name) {
+    throw new common_1.BadRequestException(`${name} is invalid`);
+}
+/** Optional `category`: absent ⇒ both; otherwise exactly one of the two categories. */
+function parseCategory(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string' ||
+        !ports_js_1.NOTIFICATION_CATEGORIES.includes(value)) {
+        badParameter('category');
+    }
+    return value;
+}
+/** Optional `unread`: absent ⇒ false; otherwise `true` or `false`. */
+function parseUnread(value) {
+    if (value === undefined)
+        return false;
+    if (value === 'true')
+        return true;
+    if (value === 'false')
+        return false;
+    return badParameter('unread');
+}
+/** Optional positive integer in `[1, max]`; absent ⇒ `fallback`. */
+function parseBoundedInt(name, value, fallback, max) {
+    if (value === undefined)
+        return fallback;
+    if (typeof value !== 'string' || !DIGITS.test(value))
+        badParameter(name);
+    const n = Number(value);
+    if (!Number.isSafeInteger(n) || n < 1 || n > max)
+        badParameter(name);
+    return n;
+}
+function toView(row) {
+    return {
+        uuid: row.uuid,
+        category: row.category,
+        kind: row.kind,
+        title: row.title,
+        body: row.body,
+        link: row.link,
+        createdAt: new Date(row.createdAtMs).toISOString(),
+        readAt: row.readAtMs === null ? null : new Date(row.readAtMs).toISOString(),
+    };
+}
+/** Run one store call; any throw is the fixed 503. */
+async function guarded(call) {
+    try {
+        return await call();
+    }
+    catch {
+        return unavailable();
+    }
+}
+let NotificationsController = class NotificationsController {
+    binder;
+    store;
+    mfaRequirement;
+    constructor(binder, store, mfaRequirement) {
+        this.binder = binder;
+        this.store = store;
+        this.mfaRequirement = mfaRequirement;
+    }
+    /**
+     * 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.
+     */
+    async requireSession(authorization) {
+        if (this.binder === undefined || this.binder === null)
+            unauthorized();
+        const token = (0, request_principal_js_1.extractBearerToken)(authorization);
+        if (token === null)
+            unauthorized();
+        let claims = await this.binder.resolve(token);
+        if (claims === null)
+            unauthorized();
+        if (this.mfaRequirement !== undefined && this.mfaRequirement !== null) {
+            claims = await this.mfaRequirement.refresh(token, claims);
+        }
+        const reason = (0, session_restriction_js_1.restrictionOf)(claims, Date.now());
+        if (reason !== null) {
+            throw new common_1.HttpException({ error: (0, session_restriction_js_1.restrictionErrorCode)(reason) }, common_1.HttpStatus.FORBIDDEN);
+        }
+        return claims;
+    }
+    requireStore() {
+        if (this.store === undefined || this.store === null)
+            notAvailable();
+        return this.store;
+    }
+    /** `GET /account/notifications` — newest first ⇒ `{ total, rows, page, limit }`. */
+    async list(authorization, query) {
+        const claims = await this.requireSession(authorization);
+        const store = this.requireStore();
+        const category = parseCategory(query?.category);
+        const unreadOnly = parseUnread(query?.unread);
+        const limit = parseBoundedInt('limit', query?.limit, DEFAULT_LIMIT, MAX_LIMIT);
+        const page = parseBoundedInt('page', query?.page, 1, Number.MAX_SAFE_INTEGER);
+        // The store refuses an offset past the safe-integer range; answer that as the caller's 400.
+        if (!Number.isSafeInteger((page - 1) * limit))
+            badParameter('page');
+        const result = await guarded(() => store.list(claims.id, claims.tenantId, {
+            ...(category !== undefined ? { category } : {}),
+            unreadOnly,
+            page,
+            limit,
+        }));
+        return { total: result.total, rows: result.rows.map(toView), page, limit };
+    }
+    /** `GET /account/notifications/unread-count` ⇒ `{ announcement, personal, total }`. */
+    async unreadCount(authorization) {
+        const claims = await this.requireSession(authorization);
+        const store = this.requireStore();
+        const counts = await guarded(() => store.countUnread(claims.id, claims.tenantId));
+        return {
+            announcement: counts.announcement,
+            personal: counts.personal,
+            total: counts.announcement + counts.personal,
+        };
+    }
+    /** `POST /account/notifications/read-all?category=` ⇒ `{ updated }`. */
+    async readAll(authorization, query) {
+        const claims = await this.requireSession(authorization);
+        const store = this.requireStore();
+        const category = parseCategory(query?.category);
+        const updated = await guarded(() => store.markAllRead(claims.id, claims.tenantId, category, Date.now()));
+        return { updated };
+    }
+    /**
+     * `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.
+     */
+    async read(authorization, rawUuid) {
+        const claims = await this.requireSession(authorization);
+        const store = this.requireStore();
+        const uuid = (0, uuid_pipe_js_1.uuidField)(rawUuid, 'uuid');
+        const found = await guarded(() => store.markRead(claims.id, claims.tenantId, uuid, Date.now()));
+        if (!found)
+            notFound();
+    }
+};
+exports.NotificationsController = NotificationsController;
+__decorate([
+    (0, classification_decorator_js_1.Public)(),
+    (0, common_1.Get)(),
+    (0, common_1.HttpCode)(common_1.HttpStatus.OK),
+    __param(0, (0, common_1.Headers)('authorization')),
+    __param(1, (0, common_1.Query)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object]),
+    __metadata("design:returntype", Promise)
+], NotificationsController.prototype, "list", null);
+__decorate([
+    (0, classification_decorator_js_1.Public)(),
+    (0, common_1.Get)('unread-count'),
+    (0, common_1.HttpCode)(common_1.HttpStatus.OK),
+    __param(0, (0, common_1.Headers)('authorization')),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], NotificationsController.prototype, "unreadCount", null);
+__decorate([
+    (0, classification_decorator_js_1.Public)(),
+    (0, common_1.Post)('read-all'),
+    (0, common_1.HttpCode)(common_1.HttpStatus.OK),
+    __param(0, (0, common_1.Headers)('authorization')),
+    __param(1, (0, common_1.Query)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object]),
+    __metadata("design:returntype", Promise)
+], NotificationsController.prototype, "readAll", null);
+__decorate([
+    (0, classification_decorator_js_1.Public)(),
+    (0, common_1.Post)(':uuid/read'),
+    (0, common_1.HttpCode)(common_1.HttpStatus.NO_CONTENT),
+    __param(0, (0, common_1.Headers)('authorization')),
+    __param(1, (0, common_1.Param)('uuid')),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, String]),
+    __metadata("design:returntype", Promise)
+], NotificationsController.prototype, "read", null);
+exports.NotificationsController = NotificationsController = __decorate([
+    (0, common_1.Controller)('account/notifications'),
+    __param(0, (0, common_1.Optional)()),
+    __param(0, (0, common_1.Inject)(tokens_js_1.SHIELD_SESSION_TOKEN_BINDER)),
+    __param(1, (0, common_1.Optional)()),
+    __param(1, (0, common_1.Inject)(tokens_js_2.SHIELD_NOTIFICATION_STORE)),
+    __param(2, (0, common_1.Optional)()),
+    __param(2, (0, common_1.Inject)(tokens_js_2.SHIELD_MFA_REQUIREMENT)),
+    __metadata("design:paramtypes", [Function, Object, Object])
+], NotificationsController);