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

package/dist/identity/auth/interfaces/authenticated-user.interface.d.ts

@@ -0,0 +1,121 @@
+import type { OrgMemberStatus } from '@marinoscar/platform-contract/identity';
+import type { CredentialKind } from '../../../core/index';
+import type { IdentityUserRow } from '../../data/identity-db';
+/**
+ * A role row with its permissions, as the principal graph loads it.
+ *
+ * @stability stable
+ */
+export interface AuthenticatedRole {
+    /** The role's id. */
+    id: string;
+    /** The role name (`admin`, `viewer`, ...). */
+    name: string;
+    /** Its description. */
+    description: string | null;
+    /** `system` or `org`. */
+    scope?: 'system' | 'org';
+    /** Its grants. */
+    rolePermissions: Array<{
+        /** The granted permission. */
+        permission: AuthenticatedPermission;
+    }>;
+}
+/**
+ * A permission row, as the principal graph loads it.
+ *
+ * @stability stable
+ */
+export interface AuthenticatedPermission {
+    /** The permission's id. */
+    id: string;
+    /** The permission string (`users:read`). */
+    name: string;
+    /** Its description. */
+    description: string | null;
+    /** `system` or `org`. */
+    scope?: 'system' | 'org';
+}
+/**
+ * One membership of the user, with its org role, as the principal graph loads it.
+ *
+ * @stability stable
+ */
+export interface AuthenticatedMembership {
+    /** The organization. */
+    orgId: string;
+    /** `active` or `suspended`. */
+    status: OrgMemberStatus;
+    /** When the user last acted in the organization. */
+    lastActiveAt: Date | null;
+    /** When the membership was created. */
+    createdAt?: Date;
+    /** The organization's id and whether it is the default one. */
+    org?: {
+        /** The organization's id. */
+        id: string;
+        /** Whether it is the deployment's default organization. */
+        isDefault: boolean;
+    } | null;
+    /** The org role on the membership. */
+    role: AuthenticatedRole;
+}
+/**
+ * User object attached to request after credential validation: the user,
+ * their SYSTEM roles (`userRoles`) and their memberships with each one's ORG
+ * role (issue #723). Loaded with `PRINCIPAL_USER_INCLUDE`
+ * (`auth/principal.factory.ts`). `memberships` is optional so a graph loaded
+ * without it (an older caller, a test fixture) still type-checks; it then
+ * contributes no org role.
+ *
+ * @stability stable
+ */
+export interface AuthenticatedUser extends IdentityUserRow {
+    /** The user's SYSTEM roles (`user_roles`). */
+    userRoles: Array<{
+        /** The role. */
+        role: AuthenticatedRole;
+    }>;
+    /** The user's memberships, each with its ORG role. */
+    memberships?: AuthenticatedMembership[];
+    /**
+     * The org this request's credential is bound to (#724), stamped by the
+     * credential path that admitted it: the access token's `org` claim, the
+     * PAT's `orgId`, or `null` for a system-scoped node credential. Absent on a
+     * graph loaded outside a request; `PrincipalFactory` then applies the
+     * sign-in rule. Never taken from a header, query or body.
+     */
+    activeOrgId?: string | null;
+    /** How the request authenticated (#724): `session`, `device`, `pat` or `node`. */
+    tokenKind?: CredentialKind;
+}
+/**
+ * Simplified user info for request context.
+ *
+ * @stability stable
+ */
+export interface RequestUser {
+    /** The user's id. */
+    id: string;
+    /** The user's email. */
+    email: string;
+    /** System role names plus the current org role name (issue #723). */
+    roles: string[];
+    /** Effective permissions: system grants ∪ current-org membership grants. */
+    permissions: string[];
+    /** Whether the account is active. */
+    isActive: boolean;
+    /** The active org (#724): present when the credential path stamped one; `null` for a node. */
+    activeOrgId?: string | null;
+}
+/**
+ * Extract RequestUser from AuthenticatedUser. The roles and permissions come
+ * from `PrincipalFactory` (system roles ∪ current-org membership role).
+ *
+ * @param user - the loaded user graph.
+ * @returns the simplified view.
+ *
+ * @stability stable
+ */
+export declare function toRequestUser(user: AuthenticatedUser): RequestUser;
+//# sourceMappingURL=authenticated-user.interface.d.ts.map

package/dist/identity/auth/interfaces/authenticated-user.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authenticated-user.interface.d.ts","sourceRoot":"","sources":["../../../../src/identity/auth/interfaces/authenticated-user.interface.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wCAAwC,CAAC;AAC9E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAG9D;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,qBAAqB;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,uBAAuB;IACvB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,yBAAyB;IACzB,KAAK,CAAC,EAAE,QAAQ,GAAG,KAAK,CAAC;IACzB,kBAAkB;IAClB,eAAe,EAAE,KAAK,CAAC;QACrB,8BAA8B;QAC9B,UAAU,EAAE,uBAAuB,CAAC;KACrC,CAAC,CAAC;CACJ;AAED;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC,2BAA2B;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,uBAAuB;IACvB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,yBAAyB;IACzB,KAAK,CAAC,EAAE,QAAQ,GAAG,KAAK,CAAC;CAC1B;AAED;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC,wBAAwB;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,+BAA+B;IAC/B,MAAM,EAAE,eAAe,CAAC;IACxB,oDAAoD;IACpD,YAAY,EAAE,IAAI,GAAG,IAAI,CAAC;IAC1B,uCAAuC;IACvC,SAAS,CAAC,EAAE,IAAI,CAAC;IACjB,+DAA+D;IAC/D,GAAG,CAAC,EAAE;QACJ,6BAA6B;QAC7B,EAAE,EAAE,MAAM,CAAC;QACX,2DAA2D;QAC3D,SAAS,EAAE,OAAO,CAAC;KACpB,GAAG,IAAI,CAAC;IACT,sCAAsC;IACtC,IAAI,EAAE,iBAAiB,CAAC;CACzB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,iBAAkB,SAAQ,eAAe;IACxD,8CAA8C;IAC9C,SAAS,EAAE,KAAK,CAAC;QACf,gBAAgB;QAChB,IAAI,EAAE,iBAAiB,CAAC;KACzB,CAAC,CAAC;IACH,sDAAsD;IACtD,WAAW,CAAC,EAAE,uBAAuB,EAAE,CAAC;IACxC;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,kFAAkF;IAClF,SAAS,CAAC,EAAE,cAAc,CAAC;CAC5B;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,qBAAqB;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,wBAAwB;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,qEAAqE;IACrE,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,4EAA4E;IAC5E,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,qCAAqC;IACrC,QAAQ,EAAE,OAAO,CAAC;IAClB,8FAA8F;IAC9F,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,iBAAiB,GAAG,WAAW,CAWlE"}

package/dist/identity/auth/interfaces/authenticated-user.interface.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toRequestUser = toRequestUser;
+const principal_factory_1 = require("../principal.factory");
+/**
+ * Extract RequestUser from AuthenticatedUser. The roles and permissions come
+ * from `PrincipalFactory` (system roles ∪ current-org membership role).
+ *
+ * @param user - the loaded user graph.
+ * @returns the simplified view.
+ *
+ * @stability stable
+ */
+function toRequestUser(user) {
+    const { roles, permissions } = principal_factory_1.principalFactory.access(user);
+    return {
+        id: user.id,
+        email: user.email,
+        roles,
+        permissions,
+        isActive: user.isActive,
+        ...(user.activeOrgId !== undefined ? { activeOrgId: user.activeOrgId } : {}),
+    };
+}
+//# sourceMappingURL=authenticated-user.interface.js.map

package/dist/identity/auth/interfaces/authenticated-user.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"authenticated-user.interface.js","sourceRoot":"","sources":["../../../../src/identity/auth/interfaces/authenticated-user.interface.ts"],"names":[],"mappings":";;AA8HA,sCAWC;AAtID,4DAAwD;AAkHxD;;;;;;;;GAQG;AACH,SAAgB,aAAa,CAAC,IAAuB;IACnD,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,GAAG,oCAAgB,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAE7D,OAAO;QACL,EAAE,EAAE,IAAI,CAAC,EAAE;QACX,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,KAAK;QACL,WAAW;QACX,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,GAAG,CAAC,IAAI,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC7E,CAAC;AACJ,CAAC"}

package/dist/identity/auth/principal-cache/index.d.ts

@@ -0,0 +1,5 @@
+export { PRINCIPAL_CACHE_CLOCK, PRINCIPAL_CACHE_MAX_ENTRIES, PRINCIPAL_INVALIDATE_CHANNEL, PrincipalCache, } from './principal-cache.service';
+export type { PrincipalCacheKey, PrincipalCacheStats, PrincipalInvalidation } from './principal-cache.service';
+export { DEFAULT_PRINCIPAL_CACHE_TTL_SECONDS, parsePrincipalCacheTtlSeconds, } from './principal-cache.config';
+export { PrincipalCacheModule } from './principal-cache.module';
+//# sourceMappingURL=index.d.ts.map

package/dist/identity/auth/principal-cache/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/identity/auth/principal-cache/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,qBAAqB,EACrB,2BAA2B,EAC3B,4BAA4B,EAC5B,cAAc,GACf,MAAM,2BAA2B,CAAC;AACnC,YAAY,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAC/G,OAAO,EACL,mCAAmC,EACnC,6BAA6B,GAC9B,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/identity/auth/principal-cache/index.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PrincipalCacheModule = exports.parsePrincipalCacheTtlSeconds = exports.DEFAULT_PRINCIPAL_CACHE_TTL_SECONDS = exports.PrincipalCache = exports.PRINCIPAL_INVALIDATE_CHANNEL = exports.PRINCIPAL_CACHE_MAX_ENTRIES = exports.PRINCIPAL_CACHE_CLOCK = void 0;
+// Public surface of the JWT principal cache (PP-1.12, issue #683).
+var principal_cache_service_1 = require("./principal-cache.service");
+Object.defineProperty(exports, "PRINCIPAL_CACHE_CLOCK", { enumerable: true, get: function () { return principal_cache_service_1.PRINCIPAL_CACHE_CLOCK; } });
+Object.defineProperty(exports, "PRINCIPAL_CACHE_MAX_ENTRIES", { enumerable: true, get: function () { return principal_cache_service_1.PRINCIPAL_CACHE_MAX_ENTRIES; } });
+Object.defineProperty(exports, "PRINCIPAL_INVALIDATE_CHANNEL", { enumerable: true, get: function () { return principal_cache_service_1.PRINCIPAL_INVALIDATE_CHANNEL; } });
+Object.defineProperty(exports, "PrincipalCache", { enumerable: true, get: function () { return principal_cache_service_1.PrincipalCache; } });
+var principal_cache_config_1 = require("./principal-cache.config");
+Object.defineProperty(exports, "DEFAULT_PRINCIPAL_CACHE_TTL_SECONDS", { enumerable: true, get: function () { return principal_cache_config_1.DEFAULT_PRINCIPAL_CACHE_TTL_SECONDS; } });
+Object.defineProperty(exports, "parsePrincipalCacheTtlSeconds", { enumerable: true, get: function () { return principal_cache_config_1.parsePrincipalCacheTtlSeconds; } });
+var principal_cache_module_1 = require("./principal-cache.module");
+Object.defineProperty(exports, "PrincipalCacheModule", { enumerable: true, get: function () { return principal_cache_module_1.PrincipalCacheModule; } });
+//# sourceMappingURL=index.js.map

package/dist/identity/auth/principal-cache/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/identity/auth/principal-cache/index.ts"],"names":[],"mappings":";;;AAAA,mEAAmE;AACnE,qEAKmC;AAJjC,gIAAA,qBAAqB,OAAA;AACrB,sIAAA,2BAA2B,OAAA;AAC3B,uIAAA,4BAA4B,OAAA;AAC5B,yHAAA,cAAc,OAAA;AAGhB,mEAGkC;AAFhC,6IAAA,mCAAmC,OAAA;AACnC,uIAAA,6BAA6B,OAAA;AAE/B,mEAAgE;AAAvD,8HAAA,oBAAoB,OAAA"}

package/dist/identity/auth/principal-cache/local-event-bus.d.ts

@@ -0,0 +1,15 @@
+import type { IdentityEventBus, IdentityEventBusHealth, IdentityEventBusMeta } from '../../ports';
+/** A single-process bus with the `in-process` adapter's semantics. */
+export declare class LocalIdentityEventBus implements IdentityEventBus {
+    readonly adapter = "in-process";
+    private readonly origin;
+    private readonly startedAt;
+    private readonly handlers;
+    private readonly logger;
+    publish<T>(channel: string, payload: T): Promise<void>;
+    subscribe<T>(channel: string, handler: (payload: T, meta: IdentityEventBusMeta) => void | Promise<void>): () => void;
+    /** How many handlers are subscribed to `channel` (for tests). */
+    handlerCount(channel: string): number;
+    health(): IdentityEventBusHealth;
+}
+//# sourceMappingURL=local-event-bus.d.ts.map

package/dist/identity/auth/principal-cache/local-event-bus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-event-bus.d.ts","sourceRoot":"","sources":["../../../../src/identity/auth/principal-cache/local-event-bus.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAIlG,sEAAsE;AACtE,qBAAa,qBAAsB,YAAW,gBAAgB;IAC5D,QAAQ,CAAC,OAAO,gBAAgB;IAChC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;IACvC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA4B;IACtD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmC;IAC5D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0C;IAE3D,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAY5D,SAAS,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,oBAAoB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,MAAM,IAAI;IASpH,iEAAiE;IACjE,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAIrC,MAAM,IAAI,sBAAsB;CAUjC"}

package/dist/identity/auth/principal-cache/local-event-bus.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LocalIdentityEventBus = void 0;
+// The principal cache's bus when the app binds no `IDENTITY_EVENT_BUS` (a test
+// graph built from one module): this process only, delivered synchronously and
+// marked `local`, so the cache (which applies its own invalidations itself)
+// ignores its own messages exactly as on the app's in-process bus.
+const common_1 = require("@nestjs/common");
+const node_crypto_1 = require("node:crypto");
+/** A single-process bus with the `in-process` adapter's semantics. */
+class LocalIdentityEventBus {
+    adapter = 'in-process';
+    origin = (0, node_crypto_1.randomUUID)();
+    startedAt = new Date().toISOString();
+    handlers = new Map();
+    logger = new common_1.Logger(LocalIdentityEventBus.name);
+    async publish(channel, payload) {
+        // A JSON round trip, as a real bus would serialise it.
+        const copy = JSON.parse(JSON.stringify(payload ?? null));
+        for (const handler of [...(this.handlers.get(channel) ?? [])]) {
+            try {
+                await handler(copy, { origin: this.origin, local: true });
+            }
+            catch (error) {
+                this.logger.warn(`A handler on "${channel}" threw: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+    }
+    subscribe(channel, handler) {
+        const set = this.handlers.get(channel) ?? new Set();
+        set.add(handler);
+        this.handlers.set(channel, set);
+        return () => {
+            set.delete(handler);
+        };
+    }
+    /** How many handlers are subscribed to `channel` (for tests). */
+    handlerCount(channel) {
+        return this.handlers.get(channel)?.size ?? 0;
+    }
+    health() {
+        return {
+            adapter: this.adapter,
+            connected: true,
+            lastError: null,
+            lastConnectedAt: this.startedAt,
+            publishFailures: 0,
+            reconnects: 0,
+        };
+    }
+}
+exports.LocalIdentityEventBus = LocalIdentityEventBus;
+//# sourceMappingURL=local-event-bus.js.map

package/dist/identity/auth/principal-cache/local-event-bus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-event-bus.js","sourceRoot":"","sources":["../../../../src/identity/auth/principal-cache/local-event-bus.ts"],"names":[],"mappings":";;;AAAA,+EAA+E;AAC/E,+EAA+E;AAC/E,4EAA4E;AAC5E,mEAAmE;AACnE,2CAAwC;AACxC,6CAAyC;AAMzC,sEAAsE;AACtE,MAAa,qBAAqB;IACvB,OAAO,GAAG,YAAY,CAAC;IACf,MAAM,GAAG,IAAA,wBAAU,GAAE,CAAC;IACtB,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACrC,QAAQ,GAAG,IAAI,GAAG,EAAwB,CAAC;IAC3C,MAAM,GAAG,IAAI,eAAM,CAAC,qBAAqB,CAAC,IAAI,CAAC,CAAC;IAEjE,KAAK,CAAC,OAAO,CAAI,OAAe,EAAE,OAAU;QAC1C,uDAAuD;QACvD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,IAAI,IAAI,CAAC,CAAY,CAAC;QACpE,KAAK,MAAM,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;YAC9D,IAAI,CAAC;gBACH,MAAM,OAAO,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;YAC5D,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,iBAAiB,OAAO,YAAY,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YACjH,CAAC;QACH,CAAC;IACH,CAAC;IAED,SAAS,CAAI,OAAe,EAAE,OAAyE;QACrG,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,IAAI,GAAG,EAAW,CAAC;QAC7D,GAAG,CAAC,GAAG,CAAC,OAAkB,CAAC,CAAC;QAC5B,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;QAChC,OAAO,GAAG,EAAE;YACV,GAAG,CAAC,MAAM,CAAC,OAAkB,CAAC,CAAC;QACjC,CAAC,CAAC;IACJ,CAAC;IAED,iEAAiE;IACjE,YAAY,CAAC,OAAe;QAC1B,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,IAAI,IAAI,CAAC,CAAC;IAC/C,CAAC;IAED,MAAM;QACJ,OAAO;YACL,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,SAAS,EAAE,IAAI;YACf,SAAS,EAAE,IAAI;YACf,eAAe,EAAE,IAAI,CAAC,SAAS;YAC/B,eAAe,EAAE,CAAC;YAClB,UAAU,EAAE,CAAC;SACd,CAAC;IACJ,CAAC;CACF;AA3CD,sDA2CC"}

package/dist/identity/auth/principal-cache/principal-cache.config.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The principal cache's TTL when `AUTH_PRINCIPAL_CACHE_TTL_SECONDS` is unset or invalid.
+ *
+ * @stability stable
+ */
+export declare const DEFAULT_PRINCIPAL_CACHE_TTL_SECONDS = 30;
+/**
+ * Pure apart from the one warning: the TTL, in seconds, for a configured value.
+ *
+ * @param raw - `AUTH_PRINCIPAL_CACHE_TTL_SECONDS`.
+ * @returns a non-negative whole number of seconds (0 disables the cache).
+ *
+ * @stability stable
+ */
+export declare function parsePrincipalCacheTtlSeconds(raw: unknown): number;
+//# sourceMappingURL=principal-cache.config.d.ts.map

package/dist/identity/auth/principal-cache/principal-cache.config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"principal-cache.config.d.ts","sourceRoot":"","sources":["../../../../src/identity/auth/principal-cache/principal-cache.config.ts"],"names":[],"mappings":"AAmBA;;;;GAIG;AACH,eAAO,MAAM,mCAAmC,KAAK,CAAC;AAItD;;;;;;;GAOG;AACH,wBAAgB,6BAA6B,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAsBlE"}

package/dist/identity/auth/principal-cache/principal-cache.config.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_PRINCIPAL_CACHE_TTL_SECONDS = void 0;
+exports.parsePrincipalCacheTtlSeconds = parsePrincipalCacheTtlSeconds;
+const common_1 = require("@nestjs/common");
+// =============================================================================
+// `AUTH_PRINCIPAL_CACHE_TTL_SECONDS` (PP-1.12, issue #683)
+// =============================================================================
+//
+// A DEPLOYMENT-LEVEL PERFORMANCE KNOB, not a runtime-configured feature: it
+// trades a bounded staleness window (only when the event bus is down) for one
+// fewer four-level join per JWT request. It must be known at boot, before the
+// first request, so it is an environment variable like `JWT_ACCESS_TTL_MINUTES`.
+//
+//   - unset            → the default, 30 seconds;
+//   - a whole number   → that many seconds; `0` disables the cache entirely,
+//                        which is exactly the behaviour before this cache;
+//   - anything else    → 30, with ONE warning. A typo must not silently turn
+//                        the cache off (or into a day-long TTL); the default
+//                        is the safe, documented value.
+// =============================================================================
+/**
+ * The principal cache's TTL when `AUTH_PRINCIPAL_CACHE_TTL_SECONDS` is unset or invalid.
+ *
+ * @stability stable
+ */
+exports.DEFAULT_PRINCIPAL_CACHE_TTL_SECONDS = 30;
+const logger = new common_1.Logger('PrincipalCache');
+/**
+ * Pure apart from the one warning: the TTL, in seconds, for a configured value.
+ *
+ * @param raw - `AUTH_PRINCIPAL_CACHE_TTL_SECONDS`.
+ * @returns a non-negative whole number of seconds (0 disables the cache).
+ *
+ * @stability stable
+ */
+function parsePrincipalCacheTtlSeconds(raw) {
+    if (raw === undefined || raw === null) {
+        return exports.DEFAULT_PRINCIPAL_CACHE_TTL_SECONDS;
+    }
+    const configured = String(raw).trim();
+    if (configured === '') {
+        return exports.DEFAULT_PRINCIPAL_CACHE_TTL_SECONDS;
+    }
+    if (/^\d+$/.test(configured)) {
+        const seconds = Number(configured);
+        if (Number.isSafeInteger(seconds)) {
+            return seconds;
+        }
+    }
+    logger.warn(`Invalid AUTH_PRINCIPAL_CACHE_TTL_SECONDS "${configured}"; expected a non-negative whole ` +
+        `number of seconds (0 disables the cache). Using ${exports.DEFAULT_PRINCIPAL_CACHE_TTL_SECONDS}.`);
+    return exports.DEFAULT_PRINCIPAL_CACHE_TTL_SECONDS;
+}
+//# sourceMappingURL=principal-cache.config.js.map

package/dist/identity/auth/principal-cache/principal-cache.config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"principal-cache.config.js","sourceRoot":"","sources":["../../../../src/identity/auth/principal-cache/principal-cache.config.ts"],"names":[],"mappings":";;;AAoCA,sEAsBC;AA1DD,2CAAwC;AAExC,gFAAgF;AAChF,2DAA2D;AAC3D,gFAAgF;AAChF,EAAE;AACF,4EAA4E;AAC5E,8EAA8E;AAC9E,8EAA8E;AAC9E,iFAAiF;AACjF,EAAE;AACF,kDAAkD;AAClD,6EAA6E;AAC7E,2EAA2E;AAC3E,6EAA6E;AAC7E,6EAA6E;AAC7E,wDAAwD;AACxD,gFAAgF;AAEhF;;;;GAIG;AACU,QAAA,mCAAmC,GAAG,EAAE,CAAC;AAEtD,MAAM,MAAM,GAAG,IAAI,eAAM,CAAC,gBAAgB,CAAC,CAAC;AAE5C;;;;;;;GAOG;AACH,SAAgB,6BAA6B,CAAC,GAAY;IACxD,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;QACtC,OAAO,2CAAmC,CAAC;IAC7C,CAAC;IAED,MAAM,UAAU,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IACtC,IAAI,UAAU,KAAK,EAAE,EAAE,CAAC;QACtB,OAAO,2CAAmC,CAAC;IAC7C,CAAC;IAED,IAAI,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;QAC7B,MAAM,OAAO,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC;QACnC,IAAI,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,EAAE,CAAC;YAClC,OAAO,OAAO,CAAC;QACjB,CAAC;IACH,CAAC;IAED,MAAM,CAAC,IAAI,CACT,6CAA6C,UAAU,mCAAmC;QACxF,mDAAmD,2CAAmC,GAAG,CAC5F,CAAC;IACF,OAAO,2CAAmC,CAAC;AAC7C,CAAC"}

package/dist/identity/auth/principal-cache/principal-cache.module.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Provides the one {@link PrincipalCache} of the process. Import it where a
+ * service invalidates principals.
+ *
+ * @stability stable
+ */
+export declare class PrincipalCacheModule {
+}
+//# sourceMappingURL=principal-cache.module.d.ts.map

package/dist/identity/auth/principal-cache/principal-cache.module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"principal-cache.module.d.ts","sourceRoot":"","sources":["../../../../src/identity/auth/principal-cache/principal-cache.module.ts"],"names":[],"mappings":"AAsBA;;;;;GAKG;AACH,qBAIa,oBAAoB;CAAG"}

package/dist/identity/auth/principal-cache/principal-cache.module.js

@@ -0,0 +1,44 @@
+"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;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PrincipalCacheModule = void 0;
+const common_1 = require("@nestjs/common");
+const principal_cache_service_1 = require("./principal-cache.service");
+// =============================================================================
+// PrincipalCacheModule (PP-1.12, issue #683)
+// =============================================================================
+//
+// A LEAF MODULE, imported explicitly by every module whose providers read or
+// invalidate the cache: `AuthModule`, `CommonModule`
+// (`AdminBootstrapService.assignAdminRole`), `UsersModule`, `SettingsModule`
+// and `TestAuthModule`. It is not provided by `AuthModule` because
+// `AuthModule` itself imports `CommonModule`, which would put an import cycle
+// on the authentication path. It imports nothing: it needs only the global
+// `ConfigService` and (optionally) the global `EVENT_BUS`.
+//
+// ONE INSTANCE PER PROCESS: Nest instantiates a module class once per
+// application however many modules import it, so every importer shares the
+// same map. Two instances would each hold entries the other's `invalidate`
+// never reaches.
+// =============================================================================
+/**
+ * Provides the one {@link PrincipalCache} of the process. Import it where a
+ * service invalidates principals.
+ *
+ * @stability stable
+ */
+let PrincipalCacheModule = class PrincipalCacheModule {
+};
+exports.PrincipalCacheModule = PrincipalCacheModule;
+exports.PrincipalCacheModule = PrincipalCacheModule = __decorate([
+    (0, common_1.Module)({
+        providers: [principal_cache_service_1.PrincipalCache],
+        exports: [principal_cache_service_1.PrincipalCache],
+    })
+], PrincipalCacheModule);
+//# sourceMappingURL=principal-cache.module.js.map

package/dist/identity/auth/principal-cache/principal-cache.module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"principal-cache.module.js","sourceRoot":"","sources":["../../../../src/identity/auth/principal-cache/principal-cache.module.ts"],"names":[],"mappings":";;;;;;;;;AAAA,2CAAwC;AAExC,uEAA2D;AAE3D,gFAAgF;AAChF,6CAA6C;AAC7C,gFAAgF;AAChF,EAAE;AACF,6EAA6E;AAC7E,qDAAqD;AACrD,6EAA6E;AAC7E,mEAAmE;AACnE,8EAA8E;AAC9E,2EAA2E;AAC3E,2DAA2D;AAC3D,EAAE;AACF,sEAAsE;AACtE,2EAA2E;AAC3E,2EAA2E;AAC3E,iBAAiB;AACjB,gFAAgF;AAEhF;;;;;GAKG;AAKI,IAAM,oBAAoB,GAA1B,MAAM,oBAAoB;CAAG,CAAA;AAAvB,oDAAoB;+BAApB,oBAAoB;IAJhC,IAAA,eAAM,EAAC;QACN,SAAS,EAAE,CAAC,wCAAc,CAAC;QAC3B,OAAO,EAAE,CAAC,wCAAc,CAAC;KAC1B,CAAC;GACW,oBAAoB,CAAG"}

package/dist/identity/auth/principal-cache/principal-cache.service.d.ts

@@ -0,0 +1,148 @@
+import { OnModuleDestroy, OnModuleInit } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import type { CredentialKind } from '../../../core/index';
+import { type IdentityEventBus as EventBus, type IdentityEventBusHealth as EventBusHealth } from '../../ports';
+import type { AuthenticatedUser } from '../interfaces/authenticated-user.interface';
+/**
+ * The bus channel every replica listens on. Payload: {@link PrincipalInvalidation}.
+ *
+ * @stability stable
+ */
+export declare const PRINCIPAL_INVALIDATE_CHANNEL = "auth.principal.invalidate";
+/**
+ * The most principals one process holds. Insertion-order eviction past it.
+ *
+ * @stability stable
+ */
+export declare const PRINCIPAL_CACHE_MAX_ENTRIES = 10000;
+/**
+ * Optional DI token for the clock (ms since epoch). Tests inject one; production uses `Date.now`.
+ *
+ * @stability experimental
+ */
+export declare const PRINCIPAL_CACHE_CLOCK: unique symbol;
+/**
+ * What to drop: every entry of one user (all orgs, all credential kinds), or
+ * every principal (a role ↔ permission change affects everyone holding that
+ * role, and there is no index from role to user in the cache).
+ *
+ * @stability stable
+ */
+export type PrincipalInvalidation = {
+    /** Drop every entry of this user. */
+    userId: string;
+} | {
+    /** Drop every principal. */
+    all: true;
+};
+/**
+ * One cache entry's identity (#724): the user, the org the credential is
+ * bound to, and the credential kind. `orgId: null` is a credential bound to
+ * NO org: a pre-#724 access token (the compatibility path in
+ * `AuthService.validateJwtPayload`). Node credentials are never cached.
+ *
+ * @stability stable
+ */
+export interface PrincipalCacheKey {
+    /** The user. */
+    userId: string;
+    /** The org the credential is bound to, or `null`. */
+    orgId: string | null;
+    /** The credential kind. */
+    tokenKind: CredentialKind;
+}
+/**
+ * A snapshot of the cache, for the Doctor.
+ *
+ * @stability stable
+ */
+export interface PrincipalCacheStats {
+    /** Entries held. */
+    size: number;
+    /** Lookups answered from the cache. */
+    hits: number;
+    /** Lookups that missed. */
+    misses: number;
+    /** Invalidations applied. */
+    invalidations: number;
+}
+/**
+ * Short-TTL cache of validated JWT principals (#683), invalidated across
+ * replicas on the event bus. Every write that changes what a user's token
+ * resolves to calls {@link PrincipalCache.invalidateUser} after it commits; an
+ * app that writes users, roles or memberships itself does the same.
+ *
+ * @stability stable
+ */
+export declare class PrincipalCache implements OnModuleInit, OnModuleDestroy {
+    private readonly now;
+    private readonly logger;
+    /** 0 = disabled: `get` always misses and `set` never stores. */
+    readonly ttlMs: number;
+    private readonly entries;
+    /** userId → the keys of its entries, so `invalidateUser` drops them all. */
+    private readonly keysByUser;
+    private counter;
+    private epoch;
+    private readonly generations;
+    private hits;
+    private misses;
+    private invalidations;
+    private unsubscribe;
+    /** The process's bus; a private in-process one only in a graph without the host core's `EVENT_BUS`. */
+    private readonly bus;
+    constructor(config: ConfigService, bus?: EventBus, now?: () => number);
+    /** Whether the cache stores anything at all. */
+    get enabled(): boolean;
+    /** Subscribes to {@link PRINCIPAL_INVALIDATE_CHANNEL}. */
+    onModuleInit(): void;
+    /** Unsubscribes and drops every entry. */
+    onModuleDestroy(): void;
+    /** A key of `userId`'s entries: a live one first, else any (so `get` expires it). */
+    private anyKeyOf;
+    /** Removes one entry and its index slot. */
+    private deleteEntry;
+    /**
+     * The cached principal, or `undefined` when absent, expired or disabled.
+     *
+     * With a bare user id (diagnostics and tests): any live entry of that user,
+     * whatever its org or credential kind. Request paths always pass the full
+     * {@link PrincipalCacheKey}.
+     */
+    get(key: PrincipalCacheKey | string): AuthenticatedUser | undefined;
+    /**
+     * The value to capture BEFORE reading the database for `userId`, and to
+     * hand back to {@link set}. Moves whenever an invalidation covering
+     * `userId` happens, locally or from another replica.
+     */
+    generation(userId: string): number;
+    /**
+     * Stores a deep-frozen copy of `value`, BOUND to the key (#724: its
+     * `activeOrgId` is `key.orgId` when that is set, its `tokenKind` is
+     * `key.tokenKind`; see `credential-binding.ts`), and returns it — unless
+     * the cache is disabled, or `expectedGeneration` is no longer current (an
+     * invalidation happened while the caller was reading), in which case
+     * nothing is stored and `undefined` is returned. Never throws.
+     */
+    set(key: PrincipalCacheKey, value: AuthenticatedUser, expectedGeneration: number): AuthenticatedUser | undefined;
+    /**
+     * Drops every entry of `userId` (every org, every credential kind) here and
+     * on every other replica: {@link invalidate} with `{ userId }`. The one call
+     * the principal-changing writes make (#724), after their transaction
+     * commits: membership create, delete, status or role change; system role
+     * change; user deactivation; PAT revoke; device-session revoke. Never throws.
+     */
+    invalidateUser(userId: string): void;
+    /**
+     * Drops the entry (or every entry) in THIS process synchronously, then
+     * publishes the same invalidation to every other replica. Call it after
+     * the write commits, outside any `$transaction`. Never throws.
+     */
+    invalidate(target: PrincipalInvalidation): void;
+    /** The health of the bus invalidations travel on. Synchronous, no I/O. */
+    busHealth(): EventBusHealth;
+    /** A synchronous snapshot for the Doctor. No I/O. */
+    stats(): PrincipalCacheStats;
+    private drop;
+}
+//# sourceMappingURL=principal-cache.service.d.ts.map

package/dist/identity/auth/principal-cache/principal-cache.service.d.ts.map

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