@astram/guard 0.23.0 → 0.25.0

package/dist/notifications/ports.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Notification store contract (G-027 step 2, notification-store SPEC §5A, §5B, §10).
+ *
+ * One per-user, tenant-walled inbox in `<ns>_identity.user_notification` (identity migration
+ * 108). Every per-user statement is scoped by BOTH the user and the tenant (the session's active
+ * company): a notice of another user or company is indistinguishable from a missing one (core 50
+ * #4, #7; Shield #4). Notices never grant anything and never touch catalog, grants or `decide()`.
+ *
+ * Errors carry the FIELD, kind or variable name only, never a submitted value (core 50 #10).
+ */
+/** The two inbox categories (SPEC §10). The category always comes from the kind registration. */
+export declare const NOTIFICATION_CATEGORIES: readonly ["announcement", "personal"];
+export type NotificationCategory = (typeof NOTIFICATION_CATEGORIES)[number];
+/** One `notificationKinds` registration (`ShieldModule.forRoot({ notificationKinds })`). */
+export interface NotificationKindRegistration {
+    readonly kind: string;
+    readonly category: NotificationCategory;
+}
+/** A stored notice as the store returns it (no tenant id, user id or dedupe key). */
+export interface NotificationRow {
+    readonly uuid: string;
+    readonly category: NotificationCategory;
+    readonly kind: string;
+    readonly title: string;
+    readonly body: string | null;
+    readonly link: string | null;
+    readonly createdAtMs: number;
+    /** `null` ⇒ unread. */
+    readonly readAtMs: number | null;
+}
+/** A row to insert; every field already validated and server-stamped by the service. */
+export interface NotificationInsert {
+    readonly uuid: string;
+    readonly tenantId: string;
+    readonly userId: string;
+    readonly category: NotificationCategory;
+    readonly kind: string;
+    readonly title: string;
+    readonly body: string | null;
+    readonly link: string | null;
+    readonly dedupeKey: string | null;
+    readonly createdAtMs: number;
+}
+export interface NotificationListQuery {
+    /** Absent ⇒ both categories. */
+    readonly category?: NotificationCategory;
+    readonly unreadOnly: boolean;
+    /** ≥ 1. */
+    readonly page: number;
+    /** 1–100. */
+    readonly limit: number;
+}
+export interface NotificationListResult {
+    readonly total: number;
+    readonly rows: readonly NotificationRow[];
+}
+export interface NotificationUnreadCounts {
+    readonly announcement: number;
+    readonly personal: number;
+}
+/** Retention in days (`loadNotificationConfig`): read notices, and every notice. */
+export interface NotificationRetentionPolicy {
+    readonly readDays: number;
+    readonly maxDays: number;
+}
+/** A query on the caller's open transaction connection (as `MfaResetQuery`). */
+export type NotificationQuery = (sql: string, params?: unknown[]) => Promise<unknown>;
+export interface NotificationWriteOptions {
+    /** Run on the caller's open transaction (step 3: notices commit or roll back with the grant). */
+    readonly query?: NotificationQuery;
+}
+/** The persistence port; `MariaDbNotificationStore` is the framework default. */
+export interface NotificationStore {
+    list(userId: string, tenantId: string, query: NotificationListQuery): Promise<NotificationListResult>;
+    countUnread(userId: string, tenantId: string): Promise<NotificationUnreadCounts>;
+    /** `true` when the notice exists for this user in this tenant (read already or now). */
+    markRead(userId: string, tenantId: string, uuid: string, nowMs: number): Promise<boolean>;
+    /** Number of notices changed from unread to read. */
+    markAllRead(userId: string, tenantId: string, category: NotificationCategory | undefined, nowMs: number): Promise<number>;
+    /** Inserted count; a repeated dedupe key is a no-op, not an error. */
+    insertMany(rows: readonly NotificationInsert[], opts?: NotificationWriteOptions): Promise<number>;
+    /** Deleted count (at most `maxRows`). */
+    purge(nowMs: number, policy: NotificationRetentionPolicy, maxRows: number): Promise<number>;
+}
+/** Kind pattern (SPEC §10): dotted lower-case segments, at least two. */
+export declare const NOTIFICATION_KIND_PATTERN: RegExp;
+export declare const NOTIFICATION_KIND_MAX_LENGTH = 64;
+/**
+ * A kind is not registered (`post`), or a `notificationKinds` registration is invalid (boot).
+ * The message names the kind only when it is well-formed, so no arbitrary input is echoed.
+ */
+export declare class NotificationKindError extends Error {
+    readonly name = "NotificationKindError";
+    constructor(kind: unknown, reason?: string, printed?: string);
+    /**
+     * Boot-time refusal of an app's `notificationKinds` entry: names the kind as registered (a
+     * developer constant, quoted and cut to 80 characters) so the bad entry can be found.
+     */
+    static registration(kind: unknown, reason: string): NotificationKindError;
+}
+/** A `post` input field broke the text, link, dedupe or recipient rules (SPEC §10, §11). */
+export declare class NotificationValidationError extends Error {
+    readonly field: string;
+    readonly name = "NotificationValidationError";
+    constructor(field: string, reason: string);
+}
+/** The store could not answer (DB error); the driver message is never carried. */
+export declare class NotificationUnavailableError extends Error {
+    readonly name = "NotificationUnavailableError";
+    constructor();
+}
+//# sourceMappingURL=ports.d.ts.map

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

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

package/dist/notifications/ports.js

@@ -0,0 +1,63 @@
+"use strict";
+/**
+ * Notification store contract (G-027 step 2, notification-store SPEC §5A, §5B, §10).
+ *
+ * One per-user, tenant-walled inbox in `<ns>_identity.user_notification` (identity migration
+ * 108). Every per-user statement is scoped by BOTH the user and the tenant (the session's active
+ * company): a notice of another user or company is indistinguishable from a missing one (core 50
+ * #4, #7; Shield #4). Notices never grant anything and never touch catalog, grants or `decide()`.
+ *
+ * Errors carry the FIELD, kind or variable name only, never a submitted value (core 50 #10).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NotificationUnavailableError = exports.NotificationValidationError = exports.NotificationKindError = exports.NOTIFICATION_KIND_MAX_LENGTH = exports.NOTIFICATION_KIND_PATTERN = exports.NOTIFICATION_CATEGORIES = void 0;
+/** The two inbox categories (SPEC §10). The category always comes from the kind registration. */
+exports.NOTIFICATION_CATEGORIES = ['announcement', 'personal'];
+/** Kind pattern (SPEC §10): dotted lower-case segments, at least two. */
+exports.NOTIFICATION_KIND_PATTERN = /^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$/;
+exports.NOTIFICATION_KIND_MAX_LENGTH = 64;
+/** The kind when it is well-formed (safe to print), else a placeholder. */
+function printableKind(kind) {
+    return typeof kind === 'string' &&
+        kind.length <= exports.NOTIFICATION_KIND_MAX_LENGTH &&
+        exports.NOTIFICATION_KIND_PATTERN.test(kind)
+        ? kind
+        : '(malformed kind)';
+}
+/**
+ * A kind is not registered (`post`), or a `notificationKinds` registration is invalid (boot).
+ * The message names the kind only when it is well-formed, so no arbitrary input is echoed.
+ */
+class NotificationKindError extends Error {
+    name = 'NotificationKindError';
+    constructor(kind, reason = 'is not registered', printed) {
+        super(`notification kind ${printed ?? printableKind(kind)} ${reason}`);
+    }
+    /**
+     * Boot-time refusal of an app's `notificationKinds` entry: names the kind as registered (a
+     * developer constant, quoted and cut to 80 characters) so the bad entry can be found.
+     */
+    static registration(kind, reason) {
+        const quoted = typeof kind === 'string' ? JSON.stringify(kind.slice(0, 80)) : `(${typeof kind})`;
+        return new NotificationKindError(kind, reason, quoted);
+    }
+}
+exports.NotificationKindError = NotificationKindError;
+/** A `post` input field broke the text, link, dedupe or recipient rules (SPEC §10, §11). */
+class NotificationValidationError extends Error {
+    field;
+    name = 'NotificationValidationError';
+    constructor(field, reason) {
+        super(`notification ${field} ${reason}`);
+        this.field = field;
+    }
+}
+exports.NotificationValidationError = NotificationValidationError;
+/** The store could not answer (DB error); the driver message is never carried. */
+class NotificationUnavailableError extends Error {
+    name = 'NotificationUnavailableError';
+    constructor() {
+        super('notifications are unavailable');
+    }
+}
+exports.NotificationUnavailableError = NotificationUnavailableError;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astram/guard",
-  "version": "0.23.0",
+  "version": "0.25.0",
   "license": "MIT",
   "description": "Astram framework — the enforcement guard + real-world adapters (the 'hands'). One global deny-by-default gate every request passes through (ADR-0002), classification decorators, boot-pool assertion (ADR-0018), the forRoot() registration seam, and the DB/Redis/crypto adapters that connect the sealed core to a real backend. Depends on @astram/core (ADR-0003, ADR-0023).",
   "type": "commonjs",
@@ -36,8 +36,8 @@
     "argon2": "^0.41.1",
     "ioredis": "^5.4.1",
     "mariadb": "^3.5.4",
-    "@astram/engine": "0.16.0",
-    "@astram/core": "1.12.0"
+    "@astram/core": "1.13.0",
+    "@astram/engine": "0.16.1"
   },
   "peerDependencies": {
     "@nestjs/common": "^11",
@@ -45,7 +45,7 @@
     "@nestjs/platform-express": "^11",
     "reflect-metadata": "^0.2",
     "rxjs": "^7",
-    "@astram/messaging": "^0.1.8"
+    "@astram/messaging": "^0.1.10"
   },
   "peerDependenciesMeta": {
     "@astram/messaging": {
@@ -68,7 +68,7 @@
     "typescript": "^5.7.0",
     "unplugin-swc": "^1.5.1",
     "vitest": "^2.1.8",
-    "@astram/messaging": "0.1.8"
+    "@astram/messaging": "0.1.10"
   },
   "repository": {
     "type": "git",