@astram/guard 0.22.0 → 0.24.0

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);

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/migrations/1710000000107-AddPermissionTextAndFirstSeen.cjs

@@ -0,0 +1,43 @@
+/**
+ * Framework authz migration — G-027 step 1 (NAES G-034; docs/features/permission-notification/SPEC.md §4):
+ * a permission key's caution text and when it first appeared in the catalog.
+ *
+ * Adds to `permission`: `perm_caution` (app-declared caution, plain text), `perm_first_seen_at` /
+ * `perm_first_seen_version` (written once by the catalog reconcile when it first inserts the key;
+ * the version is `APP_RELEASE`, NULL when unset) and `perm_last_activated_at` (first insert and
+ * every orphaned → active flip). `perm_label` (007) and `perm_description` (006) are reused.
+ *
+ * No backfill: rows present when this runs keep NULL `perm_first_seen_at`, meaning "existed before
+ * tracking began", so a later admin-task step never raises tasks for them.
+ *
+ * Idempotent: `ADD COLUMN IF NOT EXISTS` / `DROP COLUMN IF EXISTS`. The timestamps are explicitly
+ * `NULL DEFAULT NULL` so MariaDB never auto-initialises them. Literal column names; run by the
+ * DDL account.
+ */
+
+const { frameworkSchemasForMigration } = require('@astram/core');
+
+const COLUMNS = [
+  ['perm_caution', 'VARCHAR(300) NULL DEFAULT NULL'],
+  ['perm_first_seen_at', 'TIMESTAMP NULL DEFAULT NULL'],
+  ['perm_first_seen_version', 'VARCHAR(64) NULL DEFAULT NULL'],
+  ['perm_last_activated_at', 'TIMESTAMP NULL DEFAULT NULL'],
+];
+
+async function up(ctx) {
+  const { query } = ctx;
+  const SCHEMA = frameworkSchemasForMigration(ctx, process.env).authz;
+  for (const [name, type] of COLUMNS) {
+    await query(`ALTER TABLE \`${SCHEMA}\`.\`permission\` ADD COLUMN IF NOT EXISTS ${name} ${type}`);
+  }
+}
+
+async function down(ctx) {
+  const { query } = ctx;
+  const SCHEMA = frameworkSchemasForMigration(ctx, process.env).authz;
+  for (const [name] of [...COLUMNS].reverse()) {
+    await query(`ALTER TABLE \`${SCHEMA}\`.\`permission\` DROP COLUMN IF EXISTS ${name}`);
+  }
+}
+
+module.exports = { up, down };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astram/guard",
-  "version": "0.22.0",
+  "version": "0.24.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.15.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.7"
+    "@astram/messaging": "^0.1.9"
   },
   "peerDependenciesMeta": {
     "@astram/messaging": {
@@ -68,7 +68,7 @@
     "typescript": "^5.7.0",
     "unplugin-swc": "^1.5.1",
     "vitest": "^2.1.8",
-    "@astram/messaging": "0.1.7"
+    "@astram/messaging": "0.1.9"
   },
   "repository": {
     "type": "git",