@astram/identity 0.4.0 → 0.6.0

package/dist/features/shared/identity-errors.js

@@ -0,0 +1,41 @@
+"use strict";
+/**
+ * Identity domain errors (security hardening Phase 1). Thrown by identity services, mapped to HTTP
+ * by {@link IdentityErrorInterceptor} in ONE place so every identity route answers the same way.
+ *
+ * Messages are user-facing: they name no raw ids (ADR-0012) and carry no store detail.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IdentityBadRequestError = exports.IdentityConflictError = exports.IdentityNotFoundError = exports.IdentityForbiddenError = void 0;
+/** The caller may not perform this action on this target (→ 403). */
+class IdentityForbiddenError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'IdentityForbiddenError';
+    }
+}
+exports.IdentityForbiddenError = IdentityForbiddenError;
+/** The target does not exist or is outside the caller's reach (→ 404, no existence leak). */
+class IdentityNotFoundError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'IdentityNotFoundError';
+    }
+}
+exports.IdentityNotFoundError = IdentityNotFoundError;
+/** The request conflicts with the current state (cycle, children present, … → 409). */
+class IdentityConflictError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'IdentityConflictError';
+    }
+}
+exports.IdentityConflictError = IdentityConflictError;
+/** The request is malformed (→ 400). */
+class IdentityBadRequestError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'IdentityBadRequestError';
+    }
+}
+exports.IdentityBadRequestError = IdentityBadRequestError;

package/dist/features/user/session-revocation-check.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Boot check (security hardening Phase 3 review P2). Disabling a user revokes its sessions through
+ * guard's `SHIELD_SESSION_SWEEPER` (provided by the auth surface). When the auth surface is on —
+ * guard's session token binder is visible — but no sweeper is, a disable still drops the user's
+ * roles (version bump + `[]` roles) but cannot end its sessions: say so at boot instead of failing
+ * silently. Auth off → no sessions exist → nothing to warn about.
+ *
+ * @returns `true` when the warning was emitted.
+ */
+export declare function warnIfSessionsUnrevocable(binder: unknown, sweeper: unknown, warn: (message: string) => void): boolean;
+//# sourceMappingURL=session-revocation-check.d.ts.map

package/dist/features/user/session-revocation-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-revocation-check.d.ts","sourceRoot":"","sources":["../../../src/features/user/session-revocation-check.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,OAAO,EACf,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,GAC9B,OAAO,CAQT"}

package/dist/features/user/session-revocation-check.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.warnIfSessionsUnrevocable = warnIfSessionsUnrevocable;
+/**
+ * Boot check (security hardening Phase 3 review P2). Disabling a user revokes its sessions through
+ * guard's `SHIELD_SESSION_SWEEPER` (provided by the auth surface). When the auth surface is on —
+ * guard's session token binder is visible — but no sweeper is, a disable still drops the user's
+ * roles (version bump + `[]` roles) but cannot end its sessions: say so at boot instead of failing
+ * silently. Auth off → no sessions exist → nothing to warn about.
+ *
+ * @returns `true` when the warning was emitted.
+ */
+function warnIfSessionsUnrevocable(binder, sweeper, warn) {
+    if (binder === undefined || binder === null)
+        return false;
+    if (sweeper !== undefined && sweeper !== null)
+        return false;
+    warn('SHIELD_SESSION_SWEEPER is not available: disabling a user will not revoke its sessions ' +
+        '(its roles still drop on the next request). Provide a sessionSweeper to ShieldModule.forRoot.');
+    return true;
+}

package/dist/features/user/user.controller.d.ts

@@ -1,5 +1,6 @@
 import { UserService } from './user.service.js';
 import { type ListQueryDto } from '../shared/list-query.js';
+import type { AuthedRequest } from '../shared/http.js';
 export declare class UserController {
     private readonly users;
     constructor(users: UserService);
@@ -14,25 +15,29 @@ export declare class UserController {
         page: number;
         limit: number;
     }>;
-    /** Create a user — gated on `identity:user:create`. */
-    createUser(body: {
+    /**
+     * Create a user — gated on `identity:user:create`. Optional `companyUuid` creates the user's
+     * first (active) membership in the same transaction; it must be a company the caller manages.
+     */
+    createUser(req: AuthedRequest, body: {
         username?: string;
+        companyUuid?: string;
     }): Promise<{
         id: import("packages/engine/dist/types.js").RecordId;
     }>;
     /** Read one user — gated on `identity:user:read` (CONTROL-plane; root, the identity
      *  administrator, may read users). */
     getUser(uuid: string): Promise<import("packages/engine/dist/types.js").RecordView | null>;
-    /** Update a user — gated on `identity:user:update`. */
-    updateUser(uuid: string, body: {
+    /** Update a user — gated on `identity:user:update`. Only `username`, `email`, `status` apply. */
+    updateUser(req: AuthedRequest, uuid: string, body: {
         username?: string;
         email?: string;
         status?: string;
     }): Promise<{
         success: boolean;
     }>;
-    /** Delete a user — gated on `identity:user:delete`. */
-    deleteUser(uuid: string): Promise<{
+    /** Delete a user — gated on `identity:user:delete`; the caller must dominate the user. */
+    deleteUser(req: AuthedRequest, uuid: string): Promise<{
         success: boolean;
     }>;
 }

package/dist/features/user/user.controller.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"user.controller.d.ts","sourceRoot":"","sources":["../../../src/features/user/user.controller.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAkB,KAAK,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAK5E,qBACa,cAAc;IACb,OAAO,CAAC,QAAQ,CAAC,KAAK;gBAAL,KAAK,EAAE,WAAW;IAE/C;;;;OAIG;IAGG,SAAS,CAAU,KAAK,EAAE,YAAY;;;;;;IAM5C,uDAAuD;IAGjD,UAAU,CAAS,IAAI,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE;;;IAKpD;0CACsC;IAGtC,OAAO,CAAgB,IAAI,EAAE,MAAM;IAInC,uDAAuD;IAGjD,UAAU,CACC,IAAI,EAAE,MAAM,EACnB,IAAI,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE;;;IAMtE,uDAAuD;IAGjD,UAAU,CAAgB,IAAI,EAAE,MAAM;;;CAI7C"}
+{"version":3,"file":"user.controller.d.ts","sourceRoot":"","sources":["../../../src/features/user/user.controller.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAkB,KAAK,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAOvD,qBAEa,cAAc;IACb,OAAO,CAAC,QAAQ,CAAC,KAAK;gBAAL,KAAK,EAAE,WAAW;IAE/C;;;;OAIG;IAGG,SAAS,CAAU,KAAK,EAAE,YAAY;;;;;;IAM5C;;;OAGG;IAGG,UAAU,CACP,GAAG,EAAE,aAAa,EACjB,IAAI,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE;;;IAW3D;0CACsC;IAGtC,OAAO,CAAgB,IAAI,EAAE,MAAM;IAInC,iGAAiG;IAG3F,UAAU,CACP,GAAG,EAAE,aAAa,EACV,IAAI,EAAE,MAAM,EACnB,IAAI,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE;;;IAUtE,0FAA0F;IAGpF,UAAU,CAAQ,GAAG,EAAE,aAAa,EAAiB,IAAI,EAAE,MAAM;;;CAIxE"}

package/dist/features/user/user.controller.js

@@ -17,9 +17,11 @@ const common_1 = require("@nestjs/common");
 const guard_1 = require("@astram/guard");
 const user_service_js_1 = require("./user.service.js");
 const list_query_js_1 = require("../shared/list-query.js");
+const identity_error_interceptor_js_1 = require("../shared/identity-error.interceptor.js");
 // User management is gated on `identity:user:<action>` grants. `user` is CONTROL-plane
 // for ALL actions — including read: the capped root is the identity administrator (the
-// identity-administrator model), so it may list/read users AND manage them.
+// identity-administrator model), so it may list/read users AND manage them. Changing a user's
+// email or status, or deleting them, also needs the caller to dominate that user (D2).
 let UserController = class UserController {
     users;
     constructor(users) {
@@ -35,9 +37,17 @@ let UserController = class UserController {
         const result = await this.users.listUsers(params);
         return { total: result.total, rows: result.rows, page, limit };
     }
-    /** Create a user — gated on `identity:user:create`. */
-    async createUser(body) {
-        const id = await this.users.createUser(body?.username ?? 'Untitled');
+    /**
+     * Create a user — gated on `identity:user:create`. Optional `companyUuid` creates the user's
+     * first (active) membership in the same transaction; it must be a company the caller manages.
+     */
+    async createUser(req, body) {
+        const id = await this.users.createUser(req.principal, {
+            username: body?.username ?? 'Untitled',
+            ...(typeof body?.companyUuid === 'string' && body.companyUuid.length > 0
+                ? { companyUuid: body.companyUuid }
+                : {}),
+        });
         return { id };
     }
     /** Read one user — gated on `identity:user:read` (CONTROL-plane; root, the identity
@@ -45,14 +55,18 @@ let UserController = class UserController {
     getUser(uuid) {
         return this.users.getUser(uuid);
     }
-    /** Update a user — gated on `identity:user:update`. */
-    async updateUser(uuid, body) {
-        await this.users.updateUser(uuid, body ?? {});
+    /** Update a user — gated on `identity:user:update`. Only `username`, `email`, `status` apply. */
+    async updateUser(req, uuid, body) {
+        await this.users.updateUser(req.principal, uuid, {
+            username: body?.username,
+            email: body?.email,
+            status: body?.status,
+        });
         return { success: true };
     }
-    /** Delete a user — gated on `identity:user:delete`. */
-    async deleteUser(uuid) {
-        await this.users.deleteUser(uuid);
+    /** Delete a user — gated on `identity:user:delete`; the caller must dominate the user. */
+    async deleteUser(req, uuid) {
+        await this.users.deleteUser(req.principal, uuid);
         return { success: true };
     }
 };
@@ -68,9 +82,10 @@ __decorate([
 __decorate([
     (0, common_1.Post)('users'),
     (0, guard_1.Classified)({ typeKey: 'user', action: 'create' }),
-    __param(0, (0, common_1.Body)()),
+    __param(0, (0, common_1.Req)()),
+    __param(1, (0, common_1.Body)()),
     __metadata("design:type", Function),
-    __metadata("design:paramtypes", [Object]),
+    __metadata("design:paramtypes", [Object, Object]),
     __metadata("design:returntype", Promise)
 ], UserController.prototype, "createUser", null);
 __decorate([
@@ -84,21 +99,24 @@ __decorate([
 __decorate([
     (0, common_1.Put)('users/:uuid'),
     (0, guard_1.Classified)({ typeKey: 'user', action: 'update' }),
-    __param(0, (0, common_1.Param)('uuid')),
-    __param(1, (0, common_1.Body)()),
+    __param(0, (0, common_1.Req)()),
+    __param(1, (0, common_1.Param)('uuid')),
+    __param(2, (0, common_1.Body)()),
     __metadata("design:type", Function),
-    __metadata("design:paramtypes", [String, Object]),
+    __metadata("design:paramtypes", [Object, String, Object]),
     __metadata("design:returntype", Promise)
 ], UserController.prototype, "updateUser", null);
 __decorate([
     (0, common_1.Delete)('users/:uuid'),
     (0, guard_1.Classified)({ typeKey: 'user', action: 'delete' }),
-    __param(0, (0, common_1.Param)('uuid')),
+    __param(0, (0, common_1.Req)()),
+    __param(1, (0, common_1.Param)('uuid')),
     __metadata("design:type", Function),
-    __metadata("design:paramtypes", [String]),
+    __metadata("design:paramtypes", [Object, String]),
     __metadata("design:returntype", Promise)
 ], UserController.prototype, "deleteUser", null);
 exports.UserController = UserController = __decorate([
     (0, common_1.Controller)('identity'),
+    (0, common_1.UseInterceptors)(identity_error_interceptor_js_1.IdentityErrorInterceptor),
     __metadata("design:paramtypes", [user_service_js_1.UserService])
 ], UserController);

package/dist/features/user/user.service.d.ts

@@ -1,26 +1,67 @@
 import { RecordsService, type RecordId } from '@astram/engine';
+import type { Principal } from '@astram/core';
+import { type EmailSender, type ResetTokenStore, type SessionSweeper } from '@astram/guard';
+import { type PostingVersionBump } from '../membership/posting-version-bump.js';
 import { type ListParams } from '../shared/list-query.js';
+import { GrantCeiling } from '../authz/grant-ceiling.js';
+/** The patch keys a generic user update accepts (security hardening #3). */
+export interface UserPatch {
+    username?: unknown;
+    email?: unknown;
+    status?: unknown;
+}
 /**
- * UserService — user (principal) CRUD on the paved road, via the framework's
- * RecordsService facade. The facade supplies the acting identity (the request
- * principal) — this service never threads a Principal. No raw SQL, no RECORD_ENGINE.
+ * UserService — user (principal) CRUD on the paved road, via the framework's RecordsService facade
+ * (the request principal acts). No raw SQL, no RECORD_ENGINE.
+ *
+ * Users are GLOBAL (one user can belong to many tenants) and the email is a credential attribute:
+ * forgot-password mails the reset link to it. So (security hardening #3, D2):
+ *   - the patch is whitelisted to `{username, email, status}`;
+ *   - changing `email` or `status`, and deleting a user, require the actor to DOMINATE the target
+ *     (`GrantCeiling.assertDominates`: every membership of the target inside the actor's subtree,
+ *     and every key the target could hold is held by the actor);
+ *   - an email change burns the target's outstanding password-reset tokens BEFORE the change and
+ *     notifies the OLD address after it (best-effort), when guard's reset-token store and email
+ *     sender are wired (`ShieldModule.forRoot({ auth: true })`).
  */
 export declare class UserService {
     private readonly records;
-    constructor(records: RecordsService);
-    /** Create a user. */
-    createUser(username: string): Promise<RecordId>;
+    private readonly ceiling;
+    private readonly resetTokens?;
+    private readonly emailSender?;
+    private readonly sessions?;
+    private readonly versionBump?;
+    private readonly logger;
+    constructor(records: RecordsService, ceiling: GrantCeiling, resetTokens?: (ResetTokenStore | null) | undefined, emailSender?: (EmailSender | null) | undefined, sessions?: (SessionSweeper | null) | undefined, versionBump?: (PostingVersionBump | null) | undefined);
+    /**
+     * Create a user. With `companyUuid`, the user is created AND attached (one active membership) in
+     * ONE transaction — the onboarding path for a non-root admin, whose membership create is checked
+     * by the engine's create wall (a company outside the caller's subtree ⇒ 403, nothing persists).
+     */
+    createUser(actor: Principal, input: {
+        username: string;
+        companyUuid?: string | undefined;
+    }): Promise<RecordId>;
     /** List users (tenant-scoped by the pipe), with paging/search/sort. */
     listUsers(params?: ListParams): Promise<import("@astram/engine").RecordPage>;
     /** Read a single user. */
     getUser(uuid: string): Promise<import("@astram/engine").RecordView | null>;
-    /** Update a user. */
-    updateUser(uuid: string, patch: {
-        username?: string;
-        email?: string;
-        status?: string;
-    }): Promise<void>;
-    /** Delete a user. */
-    deleteUser(uuid: string): Promise<void>;
+    /** Update a user (whitelisted patch; email/status changes need dominance — see the class doc). */
+    updateUser(actor: Principal, uuid: string, patch: UserPatch): Promise<void>;
+    /**
+     * After a status change (security hardening Phase 3): bump every tenant the user is a member of
+     * (the next request reloads its grants: none while disabled, back when re-enabled), and, when the
+     * account is not `active`, durably revoke all its sessions (Redis unbound too).
+     *
+     * Both are ATTEMPTED INDEPENDENTLY (Phase 3 review P1): a failed bump never skips the revoke, or
+     * the reverse. If either failed, the first error is rethrown, so the admin sees it and can
+     * re-send the same status (which re-runs both). The status itself is already committed, so login
+     * and role reads refuse the account regardless.
+     */
+    private applyStatusChange;
+    /** Delete a user — only a user the actor dominates. */
+    deleteUser(actor: Principal, uuid: string): Promise<void>;
+    /** Tell the OLD address its account email changed (best-effort; never names the new one). */
+    private notifyEmailChanged;
 }
 //# sourceMappingURL=user.service.d.ts.map

package/dist/features/user/user.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"user.service.d.ts","sourceRoot":"","sources":["../../../src/features/user/user.service.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,KAAK,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/D,OAAO,EAAkB,KAAK,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAK1E;;;;GAIG;AACH,qBACa,WAAW;IACV,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,cAAc;IAEpD,qBAAqB;IACrB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAI/C,uEAAuE;IACvE,SAAS,CAAC,MAAM,CAAC,EAAE,UAAU;IAI7B,0BAA0B;IAC1B,OAAO,CAAC,IAAI,EAAE,MAAM;IAIpB,qBAAqB;IACrB,UAAU,CACR,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAC5D,OAAO,CAAC,IAAI,CAAC;IAIhB,qBAAqB;IACrB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAGxC"}
+{"version":3,"file":"user.service.d.ts","sourceRoot":"","sources":["../../../src/features/user/user.service.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,KAAK,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAIL,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,cAAc,EACpB,MAAM,eAAe,CAAC;AACvB,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,uCAAuC,CAAC;AAC/C,OAAO,EAAkB,KAAK,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAC1E,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAMzD,4EAA4E;AAC5E,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;;;GAaG;AACH,qBACa,WAAW;IAIpB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAGxB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC;IACY,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC;IAMtE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC;IAK1B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC;IAnB/B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgC;gBAGpC,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,YAAY,EAGrB,WAAW,CAAC,GAAE,eAAe,GAAG,IAAI,aAAA,EACK,WAAW,CAAC,GAAE,WAAW,GAAG,IAAI,aAAA,EAMzE,QAAQ,CAAC,GAAE,cAAc,GAAG,IAAI,aAAA,EAKhC,WAAW,CAAC,GAAE,kBAAkB,GAAG,IAAI,aAAA;IAG1D;;;;OAIG;IACG,UAAU,CACd,KAAK,EAAE,SAAS,EAChB,KAAK,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE,GAC5D,OAAO,CAAC,QAAQ,CAAC;IAcpB,uEAAuE;IACvE,SAAS,CAAC,MAAM,CAAC,EAAE,UAAU;IAI7B,0BAA0B;IAC1B,OAAO,CAAC,IAAI,EAAE,MAAM;IAIpB,kGAAkG;IAC5F,UAAU,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IA8BjF;;;;;;;;;OASG;YACW,iBAAiB;IAY/B,uDAAuD;IACjD,UAAU,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAO/D,6FAA6F;YAC/E,kBAAkB;CAkBjC"}

package/dist/features/user/user.service.js

@@ -8,26 +8,68 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 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); }
+};
+var UserService_1;
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.UserService = void 0;
 const common_1 = require("@nestjs/common");
 const engine_1 = require("@astram/engine");
+const guard_1 = require("@astram/guard");
+const posting_version_bump_js_1 = require("../membership/posting-version-bump.js");
 const list_query_js_1 = require("../shared/list-query.js");
+const grant_ceiling_js_1 = require("../authz/grant-ceiling.js");
+const identity_errors_js_1 = require("../shared/identity-errors.js");
 const USER_SEARCH_FIELDS = ['username', 'email'];
 const USER_SORT_FIELDS = ['username', 'email', 'status', 'createdAt'];
 /**
- * UserService — user (principal) CRUD on the paved road, via the framework's
- * RecordsService facade. The facade supplies the acting identity (the request
- * principal) — this service never threads a Principal. No raw SQL, no RECORD_ENGINE.
+ * UserService — user (principal) CRUD on the paved road, via the framework's RecordsService facade
+ * (the request principal acts). No raw SQL, no RECORD_ENGINE.
+ *
+ * Users are GLOBAL (one user can belong to many tenants) and the email is a credential attribute:
+ * forgot-password mails the reset link to it. So (security hardening #3, D2):
+ *   - the patch is whitelisted to `{username, email, status}`;
+ *   - changing `email` or `status`, and deleting a user, require the actor to DOMINATE the target
+ *     (`GrantCeiling.assertDominates`: every membership of the target inside the actor's subtree,
+ *     and every key the target could hold is held by the actor);
+ *   - an email change burns the target's outstanding password-reset tokens BEFORE the change and
+ *     notifies the OLD address after it (best-effort), when guard's reset-token store and email
+ *     sender are wired (`ShieldModule.forRoot({ auth: true })`).
  */
-let UserService = class UserService {
+let UserService = UserService_1 = class UserService {
     records;
-    constructor(records) {
+    ceiling;
+    resetTokens;
+    emailSender;
+    sessions;
+    versionBump;
+    logger = new common_1.Logger(UserService_1.name);
+    constructor(records, ceiling, resetTokens, emailSender, sessions, versionBump) {
         this.records = records;
+        this.ceiling = ceiling;
+        this.resetTokens = resetTokens;
+        this.emailSender = emailSender;
+        this.sessions = sessions;
+        this.versionBump = versionBump;
     }
-    /** Create a user. */
-    createUser(username) {
-        return this.records.create('user', { fields: { username } });
+    /**
+     * Create a user. With `companyUuid`, the user is created AND attached (one active membership) in
+     * ONE transaction — the onboarding path for a non-root admin, whose membership create is checked
+     * by the engine's create wall (a company outside the caller's subtree ⇒ 403, nothing persists).
+     */
+    async createUser(actor, input) {
+        if (!input.companyUuid) {
+            return this.records.create('user', { fields: { username: input.username } });
+        }
+        const companyUuid = input.companyUuid;
+        return this.records.transaction(async (tx) => {
+            const id = await tx.create('user', { fields: { username: input.username } });
+            await tx.create('company_membership', {
+                fields: { userUuid: id, companyUuid, isActive: true, status: 'active' },
+            });
+            return id;
+        });
     }
     /** List users (tenant-scoped by the pipe), with paging/search/sort. */
     listUsers(params) {
@@ -37,17 +79,102 @@ let UserService = class UserService {
     getUser(uuid) {
         return this.records.get('user', uuid);
     }
-    /** Update a user. */
-    updateUser(uuid, patch) {
-        return this.records.update('user', uuid, { fields: patch });
+    /** Update a user (whitelisted patch; email/status changes need dominance — see the class doc). */
+    async updateUser(actor, uuid, patch) {
+        const current = await this.records.get('user', uuid);
+        if (current === null)
+            throw new identity_errors_js_1.IdentityNotFoundError('User not found.');
+        const fields = {};
+        if (typeof patch?.username === 'string')
+            fields.username = patch.username;
+        const oldEmail = typeof current.fields.email === 'string' ? current.fields.email : '';
+        const emailChanged = typeof patch?.email === 'string' && patch.email !== oldEmail;
+        const statusChanged = typeof patch?.status === 'string' && patch.status !== current.fields.status;
+        // A request for a non-active status ALWAYS runs the follow-up (Phase 3 review P1), even when
+        // the stored status already matches: re-sending "disable" repairs a disable whose bump or
+        // session revoke failed earlier (idempotent).
+        const wantsInactive = typeof patch?.status === 'string' && patch.status !== 'active';
+        if (emailChanged)
+            fields.email = patch.email;
+        if (statusChanged)
+            fields.status = patch.status;
+        if (emailChanged || statusChanged || wantsInactive) {
+            await this.ceiling.assertDominates(actor, uuid);
+        }
+        if (Object.keys(fields).length > 0) {
+            // Burn outstanding reset links BEFORE the address changes (a failure aborts the change).
+            if (emailChanged && this.resetTokens)
+                await this.resetTokens.invalidateAllForPrincipal(uuid);
+            await this.records.update('user', uuid, { fields });
+        }
+        if (statusChanged || wantsInactive)
+            await this.applyStatusChange(uuid, String(patch.status));
+        if (emailChanged && oldEmail)
+            await this.notifyEmailChanged(oldEmail);
+    }
+    /**
+     * After a status change (security hardening Phase 3): bump every tenant the user is a member of
+     * (the next request reloads its grants: none while disabled, back when re-enabled), and, when the
+     * account is not `active`, durably revoke all its sessions (Redis unbound too).
+     *
+     * Both are ATTEMPTED INDEPENDENTLY (Phase 3 review P1): a failed bump never skips the revoke, or
+     * the reverse. If either failed, the first error is rethrown, so the admin sees it and can
+     * re-send the same status (which re-runs both). The status itself is already committed, so login
+     * and role reads refuse the account regardless.
+     */
+    async applyStatusChange(uuid, status) {
+        const steps = [];
+        if (this.versionBump?.bumpForUser)
+            steps.push(this.versionBump.bumpForUser(uuid));
+        if (status !== 'active' && this.sessions)
+            steps.push(this.sessions.revokeAllForPrincipal(uuid));
+        const results = await Promise.allSettled(steps);
+        const failed = results.find((r) => r.status === 'rejected');
+        if (failed !== undefined) {
+            this.logger.warn('user status follow-up failed; re-send the status to retry');
+            throw failed.reason;
+        }
+    }
+    /** Delete a user — only a user the actor dominates. */
+    async deleteUser(actor, uuid) {
+        const current = await this.records.get('user', uuid);
+        if (current === null)
+            throw new identity_errors_js_1.IdentityNotFoundError('User not found.');
+        await this.ceiling.assertDominates(actor, uuid);
+        await this.records.delete('user', uuid);
     }
-    /** Delete a user. */
-    deleteUser(uuid) {
-        return this.records.delete('user', uuid);
+    /** Tell the OLD address its account email changed (best-effort; never names the new one). */
+    async notifyEmailChanged(oldEmail) {
+        if (!this.emailSender)
+            return;
+        const text = 'The email address on your account was changed by an administrator. ' +
+            'Password-reset links sent before this change no longer work. ' +
+            'If you did not expect this, contact your administrator.';
+        try {
+            await this.emailSender.send({
+                to: oldEmail,
+                subject: 'Your account email address was changed',
+                text,
+                html: `<p>${text}</p>`,
+            });
+        }
+        catch {
+            // Best-effort: the change is committed; a delivery failure must not fail it.
+            this.logger.warn('email-change notice could not be delivered');
+        }
     }
 };
 exports.UserService = UserService;
-exports.UserService = UserService = __decorate([
+exports.UserService = UserService = UserService_1 = __decorate([
     (0, common_1.Injectable)(),
-    __metadata("design:paramtypes", [engine_1.RecordsService])
+    __param(2, (0, common_1.Optional)()),
+    __param(2, (0, common_1.Inject)(guard_1.SHIELD_RESET_TOKEN_STORE)),
+    __param(3, (0, common_1.Optional)()),
+    __param(3, (0, common_1.Inject)(guard_1.SHIELD_EMAIL_SENDER)),
+    __param(4, (0, common_1.Optional)()),
+    __param(4, (0, common_1.Inject)(guard_1.SHIELD_SESSION_SWEEPER)),
+    __param(5, (0, common_1.Optional)()),
+    __param(5, (0, common_1.Inject)(posting_version_bump_js_1.POSTING_VERSION_BUMP)),
+    __metadata("design:paramtypes", [engine_1.RecordsService,
+        grant_ceiling_js_1.GrantCeiling, Object, Object, Object, Object])
 ], UserService);

package/dist/index.d.ts

@@ -37,12 +37,14 @@ export { identityAuthActionKeys, identityControlPlaneKeys } from './auth-facts-k
  */
 export { IdentityFeatureModule } from './features/identity-feature.module.js';
 /**
- * The record-tier authorization wiring: the lean grant-read pool factory + the helper that
- * assembles `RecordAuthorizationInputs` for `ShieldModule.forRoot({ recordAuthorization })`.
- * Once wired, `decide()` is real (the framework's record-tier adapters run over the identity
- * app schema) instead of the deny-everything stub.
+ * The record-tier authorization wiring: the helper that assembles `RecordAuthorizationInputs`
+ * for `ShieldModule.forRoot({ recordAuthorization })`. Once wired, `decide()` is real (the
+ * framework's record-tier adapters run over the identity app schema) instead of the
+ * deny-everything stub. Its pool factory, `createIdentityAuthzPool` (it opens a raw pool), is NOT
+ * exported here (Phase 8 #5): import it from `@astram/identity/internal` in the composition root
+ * (`src/app.module.ts`).
  */
-export { createIdentityAuthzPool, buildIdentityRecordAuthorization, } from './features/authz/record-authorization.js';
+export { buildIdentityRecordAuthorization } from './features/authz/record-authorization.js';
 /**
  * The ADR-0011 per-request session-facts reader (ALS hot path), re-exported so a consumer
  * that wants to construct it directly (rather than via `buildIdentityRecordAuthorization`)

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAC9C,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AACxC,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AACxC,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AACnE,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AACnE,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AACnE,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAE5D;;;;GAIG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE/C;;;;;;GAMG;AACH,OAAO,EAAE,sBAAsB,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAExF;;;;;GAKG;AACH,OAAO,EAAE,qBAAqB,EAAE,MAAM,uCAAuC,CAAC;AAE9E;;;;;GAKG;AACH,OAAO,EACL,uBAAuB,EACvB,gCAAgC,GACjC,MAAM,0CAA0C,CAAC;AAElD;;;;GAIG;AACH,OAAO,EAAE,qBAAqB,EAAE,MAAM,0CAA0C,CAAC;AAEjF;;;;;;GAMG;AACH,OAAO,EAAE,sBAAsB,EAAE,MAAM,4CAA4C,CAAC;AAEpF;;;;;;;GAOG;AACH,OAAO,EAAE,mBAAmB,EAAE,MAAM,6CAA6C,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAC9C,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AACxC,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AACxC,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AACnE,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AACnE,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AACnE,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAE5D;;;;GAIG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE/C;;;;;;GAMG;AACH,OAAO,EAAE,sBAAsB,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAExF;;;;;GAKG;AACH,OAAO,EAAE,qBAAqB,EAAE,MAAM,uCAAuC,CAAC;AAE9E;;;;;;;GAOG;AACH,OAAO,EAAE,gCAAgC,EAAE,MAAM,0CAA0C,CAAC;AAE5F;;;;GAIG;AACH,OAAO,EAAE,qBAAqB,EAAE,MAAM,0CAA0C,CAAC;AAEjF;;;;;;GAMG;AACH,OAAO,EAAE,sBAAsB,EAAE,MAAM,4CAA4C,CAAC;AAEpF;;;;;;;GAOG;AACH,OAAO,EAAE,mBAAmB,EAAE,MAAM,6CAA6C,CAAC"}

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DbMembershipChecker = exports.DbScopeSubtreeResolver = exports.AlsSessionFactsReader = exports.buildIdentityRecordAuthorization = exports.createIdentityAuthzPool = exports.IdentityFeatureModule = exports.identityControlPlaneKeys = exports.identityAuthActionKeys = exports.identityObjects = exports.identityMigrationsDir = exports.ServiceAccount = exports.CompanyBranch = exports.CompanyDepartment = exports.MembershipPosting = exports.CompanyMembership = exports.Branch = exports.Department = exports.Role = exports.User = exports.Company = void 0;
+exports.DbMembershipChecker = exports.DbScopeSubtreeResolver = exports.AlsSessionFactsReader = exports.buildIdentityRecordAuthorization = exports.IdentityFeatureModule = exports.identityControlPlaneKeys = exports.identityAuthActionKeys = exports.identityObjects = exports.identityMigrationsDir = exports.ServiceAccount = exports.CompanyBranch = exports.CompanyDepartment = exports.MembershipPosting = exports.CompanyMembership = exports.Branch = exports.Department = exports.Role = exports.User = exports.Company = void 0;
 /**
  * @astram/identity — the framework-owned identity + tenancy model.
  * The 9 identity object classes (relocated from the consumer app in Sub-plan B) +
@@ -55,13 +55,14 @@ Object.defineProperty(exports, "identityControlPlaneKeys", { enumerable: true, g
 var identity_feature_module_js_1 = require("./features/identity-feature.module.js");
 Object.defineProperty(exports, "IdentityFeatureModule", { enumerable: true, get: function () { return identity_feature_module_js_1.IdentityFeatureModule; } });
 /**
- * The record-tier authorization wiring: the lean grant-read pool factory + the helper that
- * assembles `RecordAuthorizationInputs` for `ShieldModule.forRoot({ recordAuthorization })`.
- * Once wired, `decide()` is real (the framework's record-tier adapters run over the identity
- * app schema) instead of the deny-everything stub.
+ * The record-tier authorization wiring: the helper that assembles `RecordAuthorizationInputs`
+ * for `ShieldModule.forRoot({ recordAuthorization })`. Once wired, `decide()` is real (the
+ * framework's record-tier adapters run over the identity app schema) instead of the
+ * deny-everything stub. Its pool factory, `createIdentityAuthzPool` (it opens a raw pool), is NOT
+ * exported here (Phase 8 #5): import it from `@astram/identity/internal` in the composition root
+ * (`src/app.module.ts`).
  */
 var record_authorization_js_1 = require("./features/authz/record-authorization.js");
-Object.defineProperty(exports, "createIdentityAuthzPool", { enumerable: true, get: function () { return record_authorization_js_1.createIdentityAuthzPool; } });
 Object.defineProperty(exports, "buildIdentityRecordAuthorization", { enumerable: true, get: function () { return record_authorization_js_1.buildIdentityRecordAuthorization; } });
 /**
  * The ADR-0011 per-request session-facts reader (ALS hot path), re-exported so a consumer

package/dist/internal.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @astram/identity/internal — composition-root surface (Phase 8 #5).
+ *
+ * `createIdentityAuthzPool` opens a raw `mariadb` pool, so it is NOT on the package entry point
+ * (`@astram/identity`). An app's `src/app.module.ts` imports it from here to wire
+ * `buildIdentityRecordAuthorization(authzPool)`; the scaffolded app's lint wall rejects this
+ * subpath everywhere else. Feature code never holds a pool: it uses the RecordEngine.
+ */
+export { createIdentityAuthzPool } from './features/authz/record-authorization.js';
+//# sourceMappingURL=internal.d.ts.map

package/dist/internal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal.d.ts","sourceRoot":"","sources":["../src/internal.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,uBAAuB,EAAE,MAAM,0CAA0C,CAAC"}

package/dist/internal.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createIdentityAuthzPool = void 0;
+/**
+ * @astram/identity/internal — composition-root surface (Phase 8 #5).
+ *
+ * `createIdentityAuthzPool` opens a raw `mariadb` pool, so it is NOT on the package entry point
+ * (`@astram/identity`). An app's `src/app.module.ts` imports it from here to wire
+ * `buildIdentityRecordAuthorization(authzPool)`; the scaffolded app's lint wall rejects this
+ * subpath everywhere else. Feature code never holds a pool: it uses the RecordEngine.
+ */
+var record_authorization_js_1 = require("./features/authz/record-authorization.js");
+Object.defineProperty(exports, "createIdentityAuthzPool", { enumerable: true, get: function () { return record_authorization_js_1.createIdentityAuthzPool; } });

package/dist/membership-posting.object.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"membership-posting.object.d.ts","sourceRoot":"","sources":["../src/membership-posting.object.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,qBAiBa,iBAAiB;IAE5B,IAAI,EAAG,MAAM,CAAC;IAGd,cAAc,EAAG,MAAM,CAAC;IAGxB,QAAQ,EAAG,MAAM,CAAC;IAGlB,cAAc,EAAG,MAAM,CAAC;IAGxB,UAAU,EAAG,MAAM,CAAC;IAQpB,aAAa,EAAG,MAAM,CAAC;IAGvB,cAAc,EAAG,MAAM,CAAC;IAGxB,SAAS,EAAG,MAAM,CAAC;CACpB"}
+{"version":3,"file":"membership-posting.object.d.ts","sourceRoot":"","sources":["../src/membership-posting.object.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,qBAiBa,iBAAiB;IAE5B,IAAI,EAAG,MAAM,CAAC;IAKd,cAAc,EAAG,MAAM,CAAC;IAGxB,QAAQ,EAAG,MAAM,CAAC;IAGlB,cAAc,EAAG,MAAM,CAAC;IAGxB,UAAU,EAAG,MAAM,CAAC;IAQpB,aAAa,EAAG,MAAM,CAAC;IAGvB,cAAc,EAAG,MAAM,CAAC;IAGxB,SAAS,EAAG,MAAM,CAAC;CACpB"}

package/dist/membership-posting.object.js

@@ -19,6 +19,8 @@ const schema_1 = require("./schema");
  */
 let MembershipPosting = class MembershipPosting {
     uuid;
+    // immutable (ADR-0034): a posting never moves to another membership or role after create
+    // (a role change is a replace: delete + checked create).
     membershipUuid;
     roleUuid;
     departmentUuid;
@@ -38,11 +40,11 @@ __decorate([
     __metadata("design:type", String)
 ], MembershipPosting.prototype, "uuid", void 0);
 __decorate([
-    (0, engine_1.Field)({ column: 'mp_membership_uuid', type: 'uuid', required: true }),
+    (0, engine_1.Field)({ column: 'mp_membership_uuid', type: 'uuid', required: true, immutable: true }),
     __metadata("design:type", String)
 ], MembershipPosting.prototype, "membershipUuid", void 0);
 __decorate([
-    (0, engine_1.Field)({ column: 'mp_role_uuid', type: 'uuid', required: true }),
+    (0, engine_1.Field)({ column: 'mp_role_uuid', type: 'uuid', required: true, immutable: true }),
     __metadata("design:type", String)
 ], MembershipPosting.prototype, "roleUuid", void 0);
 __decorate([