@astram/identity 0.3.1 → 0.5.0

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

@@ -13,6 +13,7 @@ export { CompanyMembership } from './company-membership.object.js';
 export { MembershipPosting } from './membership-posting.object.js';
 export { CompanyDepartment } from './company-department.object.js';
 export { CompanyBranch } from './company-branch.object.js';
+export { ServiceAccount } from './service-account.object.js';
 export { identityMigrationsDir } from './migrations-dir.js';
 /**
  * All identity objects, registered with the engine at boot (same set + order as before).

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,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;;;;;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"}

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.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.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;
 /**
  * @astram/identity — the framework-owned identity + tenancy model.
  * The 9 identity object classes (relocated from the consumer app in Sub-plan B) +
@@ -25,6 +25,8 @@ var company_department_object_js_1 = require("./company-department.object.js");
 Object.defineProperty(exports, "CompanyDepartment", { enumerable: true, get: function () { return company_department_object_js_1.CompanyDepartment; } });
 var company_branch_object_js_1 = require("./company-branch.object.js");
 Object.defineProperty(exports, "CompanyBranch", { enumerable: true, get: function () { return company_branch_object_js_1.CompanyBranch; } });
+var service_account_object_js_1 = require("./service-account.object.js");
+Object.defineProperty(exports, "ServiceAccount", { enumerable: true, get: function () { return service_account_object_js_1.ServiceAccount; } });
 var migrations_dir_js_1 = require("./migrations-dir.js");
 Object.defineProperty(exports, "identityMigrationsDir", { enumerable: true, get: function () { return migrations_dir_js_1.identityMigrationsDir; } });
 /**

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([

package/dist/objects.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"objects.d.ts","sourceRoot":"","sources":["../src/objects.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AActD,6FAA6F;AAC7F,eAAO,MAAM,eAAe,EAAE,SAAS,eAAe,EAIrD,CAAC"}
+{"version":3,"file":"objects.d.ts","sourceRoot":"","sources":["../src/objects.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAetD,6FAA6F;AAC7F,eAAO,MAAM,eAAe,EAAE,SAAS,eAAe,EAcrD,CAAC"}

package/dist/objects.js

@@ -13,9 +13,20 @@ const company_branch_object_js_1 = require("./company-branch.object.js");
 const cross_tenant_grant_object_js_1 = require("./cross-tenant-grant.object.js");
 const record_share_object_js_1 = require("./record-share.object.js");
 const shared_resource_object_js_1 = require("./shared-resource.object.js");
+const service_account_object_js_1 = require("./service-account.object.js");
 /** All identity objects, registered with the engine at boot (same set + order as before). */
 exports.identityObjects = [
-    company_object_js_1.Company, user_object_js_1.User, role_object_js_1.Role, department_object_js_1.Department, branch_object_js_1.Branch,
-    company_membership_object_js_1.CompanyMembership, membership_posting_object_js_1.MembershipPosting, company_department_object_js_1.CompanyDepartment, company_branch_object_js_1.CompanyBranch,
-    cross_tenant_grant_object_js_1.CrossTenantGrant, record_share_object_js_1.RecordShare, shared_resource_object_js_1.SharedResource,
+    company_object_js_1.Company,
+    user_object_js_1.User,
+    role_object_js_1.Role,
+    department_object_js_1.Department,
+    branch_object_js_1.Branch,
+    company_membership_object_js_1.CompanyMembership,
+    membership_posting_object_js_1.MembershipPosting,
+    company_department_object_js_1.CompanyDepartment,
+    company_branch_object_js_1.CompanyBranch,
+    cross_tenant_grant_object_js_1.CrossTenantGrant,
+    record_share_object_js_1.RecordShare,
+    shared_resource_object_js_1.SharedResource,
+    service_account_object_js_1.ServiceAccount,
 ];

package/dist/role.object.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"role.object.d.ts","sourceRoot":"","sources":["../src/role.object.ts"],"names":[],"mappings":"AAGA,8BAA8B;AAC9B,qBAiBa,IAAI;IAEf,IAAI,EAAG,MAAM,CAAC;IAGd,IAAI,EAAG,MAAM,CAAC;IAGd,SAAS,EAAG,MAAM,CAAC;CACpB"}
+{"version":3,"file":"role.object.d.ts","sourceRoot":"","sources":["../src/role.object.ts"],"names":[],"mappings":"AAGA,8BAA8B;AAC9B,qBAoBa,IAAI;IAEf,IAAI,EAAG,MAAM,CAAC;IAGd,IAAI,EAAG,MAAM,CAAC;IAGd,SAAS,EAAG,MAAM,CAAC;CACpB"}

package/dist/role.object.js

@@ -42,8 +42,11 @@ exports.Role = Role = __decorate([
         // "a role in my subtree" derivation the Task-4.2 grant-admin predicate uses (one consistent
         // notion). FIXED framework template; the ONLY dynamic values are the `?`-bound subtree node
         // ids. DECOUPLED from writes. Root spans all.
+        // create:'unscoped' (ADR-0034): a NEW role is bound by no posting yet, so the post-insert
+        // create wall would deny every create; the posting that binds it IS walled.
         readScope: {
             kind: 'subtreeSubquery',
+            create: 'unscoped',
             pkColumn: 'r_uuid',
             subquerySql: `SELECT mp.mp_role_uuid FROM \`${schema_1.SCHEMA}\`.\`membership_posting\` mp JOIN \`${schema_1.SCHEMA}\`.\`company_membership\` cm ON cm.cm_uuid = mp.mp_membership_uuid WHERE cm.cm_company_uuid IN (${engine_1.READ_SCOPE_NODES_TOKEN})`,
         },

package/dist/service-account.object.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `service_account` — a machine principal (ADR-0007 / ADR-0033): the identity an AI agent, an
+ * MCP server, or a script authenticates AS (via an `ask_…` API key, whose HASHED versions live in
+ * `shield_authz.service_account_key`). One row = one machine account, created + scoped + revoked by
+ * a tenant admin from the Service Accounts admin page.
+ *
+ * `plane: 'control'` — creating/scoping/revoking a service account IS who-may-act administration
+ * (the same posture as `user`/`role`/`cross_tenant_grant`): the capped root and a scoped tenant
+ * admin may administer them; a non-root admin needs the `identity:service_account:*` grant.
+ *
+ * `system: true` (never `tenantScoped`) — like `user`/`cross_tenant_grant`, the row-level tenant
+ * column (`sa_tenant_id`) plus the store's own tenant-scoped SELECTs + the grant-ceiling enforce
+ * isolation; we do NOT route it through the RecordEngine's `tenantScoped` create-stamp baseline
+ * (its `ServiceAccountStore` writes it directly, stamping `sa_tenant_id` from the admin's session).
+ *
+ * `readScope: nodeColumn(sa_tenant_id)` (ADR-0027 / ADR-0030) — the account's own row carries its
+ * tenant node, so a NON-ROOT admin's list/read/update/delete is walled to rows whose `sa_tenant_id`
+ * is IN their reachable subtree (a cross-tenant id is invisible → 404, no existence leak). Root
+ * spans all. This is the read/write wall that makes "own tenant only" structural, not handler-level.
+ *
+ * Action vocabulary is administration, not CRUD data ops — see `@astram/guard`'s
+ * `identity-actions.ts` (`read`/`manage` for `service_account`).
+ */
+export declare class ServiceAccount {
+    id: string;
+    tenantId: string;
+    label: string;
+    status: string;
+    createdAtMs: number;
+}
+//# sourceMappingURL=service-account.object.d.ts.map

package/dist/service-account.object.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-account.object.d.ts","sourceRoot":"","sources":["../src/service-account.object.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAQa,cAAc;IAEzB,EAAE,EAAG,MAAM,CAAC;IAGZ,QAAQ,EAAG,MAAM,CAAC;IAGlB,KAAK,EAAG,MAAM,CAAC;IAGf,MAAM,EAAG,MAAM,CAAC;IAGhB,WAAW,EAAG,MAAM,CAAC;CACtB"}

package/dist/service-account.object.js

@@ -0,0 +1,75 @@
+"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);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ServiceAccount = void 0;
+const engine_1 = require("@astram/engine");
+const schema_1 = require("./schema");
+/**
+ * `service_account` — a machine principal (ADR-0007 / ADR-0033): the identity an AI agent, an
+ * MCP server, or a script authenticates AS (via an `ask_…` API key, whose HASHED versions live in
+ * `shield_authz.service_account_key`). One row = one machine account, created + scoped + revoked by
+ * a tenant admin from the Service Accounts admin page.
+ *
+ * `plane: 'control'` — creating/scoping/revoking a service account IS who-may-act administration
+ * (the same posture as `user`/`role`/`cross_tenant_grant`): the capped root and a scoped tenant
+ * admin may administer them; a non-root admin needs the `identity:service_account:*` grant.
+ *
+ * `system: true` (never `tenantScoped`) — like `user`/`cross_tenant_grant`, the row-level tenant
+ * column (`sa_tenant_id`) plus the store's own tenant-scoped SELECTs + the grant-ceiling enforce
+ * isolation; we do NOT route it through the RecordEngine's `tenantScoped` create-stamp baseline
+ * (its `ServiceAccountStore` writes it directly, stamping `sa_tenant_id` from the admin's session).
+ *
+ * `readScope: nodeColumn(sa_tenant_id)` (ADR-0027 / ADR-0030) — the account's own row carries its
+ * tenant node, so a NON-ROOT admin's list/read/update/delete is walled to rows whose `sa_tenant_id`
+ * is IN their reachable subtree (a cross-tenant id is invisible → 404, no existence leak). Root
+ * spans all. This is the read/write wall that makes "own tenant only" structural, not handler-level.
+ *
+ * Action vocabulary is administration, not CRUD data ops — see `@astram/guard`'s
+ * `identity-actions.ts` (`read`/`manage` for `service_account`).
+ */
+let ServiceAccount = class ServiceAccount {
+    id;
+    tenantId;
+    label;
+    status;
+    createdAtMs;
+};
+exports.ServiceAccount = ServiceAccount;
+__decorate([
+    (0, engine_1.Field)({ column: 'sa_id', type: 'uuid', role: 'primaryKey' }),
+    __metadata("design:type", String)
+], ServiceAccount.prototype, "id", void 0);
+__decorate([
+    (0, engine_1.Field)({ column: 'sa_tenant_id', type: 'uuid', required: true, trusted: 'tenantId' }),
+    __metadata("design:type", String)
+], ServiceAccount.prototype, "tenantId", void 0);
+__decorate([
+    (0, engine_1.Field)({ column: 'sa_label', type: 'string', required: true }),
+    __metadata("design:type", String)
+], ServiceAccount.prototype, "label", void 0);
+__decorate([
+    (0, engine_1.Field)({ column: 'sa_status', type: 'string', role: 'status' }),
+    __metadata("design:type", String)
+], ServiceAccount.prototype, "status", void 0);
+__decorate([
+    (0, engine_1.Field)({ column: 'sa_created_at_ms', type: 'number' }),
+    __metadata("design:type", Number)
+], ServiceAccount.prototype, "createdAtMs", void 0);
+exports.ServiceAccount = ServiceAccount = __decorate([
+    (0, engine_1.ObjectType)({
+        typeKey: 'service_account',
+        table: 'service_account',
+        schema: schema_1.SCHEMA,
+        access: { plane: 'control', system: true },
+        readScope: { kind: 'nodeColumn', column: 'sa_tenant_id' },
+    }),
+    (0, engine_1.PrimaryKey)({ kind: 'uuid', column: 'sa_id' })
+], ServiceAccount);

package/dist/user.object.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"user.object.d.ts","sourceRoot":"","sources":["../src/user.object.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,qBAoBa,IAAI;IAEf,IAAI,EAAG,MAAM,CAAC;IAGd,QAAQ,EAAG,MAAM,CAAC;IAGlB,KAAK,EAAG,MAAM,CAAC;IAGf,MAAM,EAAG,MAAM,CAAC;IAGhB,SAAS,EAAG,MAAM,CAAC;CACpB"}
+{"version":3,"file":"user.object.d.ts","sourceRoot":"","sources":["../src/user.object.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,qBAuBa,IAAI;IAEf,IAAI,EAAG,MAAM,CAAC;IAGd,QAAQ,EAAG,MAAM,CAAC;IAGlB,KAAK,EAAG,MAAM,CAAC;IAGf,MAAM,EAAG,MAAM,CAAC;IAGhB,SAAS,EAAG,MAAM,CAAC;CACpB"}

package/dist/user.object.js

@@ -59,8 +59,11 @@ exports.User = User = __decorate([
         // the caller's reachable subtree. A multi-tenant user correctly appears for each subtree
         // they're a member of. FIXED framework template; the ONLY dynamic values are the `?`-bound
         // subtree node ids. DECOUPLED from writes. Root spans all.
+        // create:'unscoped' (ADR-0034): a NEW user has no membership yet, so the post-insert create
+        // wall would deny every create; the membership create that follows IS walled.
         readScope: {
             kind: 'subtreeSubquery',
+            create: 'unscoped',
             pkColumn: 'u_uuid',
             subquerySql: `SELECT cm_user_uuid FROM \`${schema_1.SCHEMA}\`.\`company_membership\` WHERE cm_company_uuid IN (${engine_1.READ_SCOPE_NODES_TOKEN})`,
         },

package/migrations/1710000000018-CreateServiceAccount.cjs

@@ -0,0 +1,53 @@
+/**
+ * Framework identity migration — `shield_app.service_account`: a MACHINE principal (ADR-0007 /
+ * ADR-0033). One row = one service account (an AI agent / MCP server / script identity) that a
+ * tenant admin creates, scopes, and revokes. Its HASHED API keys live separately in
+ * `shield_authz.service_account_key` (guard migration 1710000000017) — this table is the ACCOUNT,
+ * not the credential.
+ *
+ * Column names for the engine-reflected fields (`sa_id`, `sa_tenant_id`, `sa_label`, `sa_status`,
+ * `sa_created_at_ms`) are read from the `@astram/identity` `ServiceAccount` object registration so
+ * the DDL and runtime queries share ONE source of truth (rule 30). The additional columns
+ * (`sa_scope_subtree`, `sa_role_ids`, `sa_created_by`, `sa_updated_at_ms`) are read+written by the
+ * `ServiceAccountStore` directly (not through the RecordEngine), exactly as `users` carries
+ * `u_email`/`u_is_platform_superuser` beyond its declared fields.
+ *
+ * `sa_tenant_id` is server-stamped from the creating admin's session (never client input); a
+ * NON-ROOT admin's list/read/update is walled to their subtree by the object's
+ * `readScope: nodeColumn(sa_tenant_id)`. Schema `shield_app` is created by earlier migrations.
+ * Idempotent (CREATE TABLE IF NOT EXISTS). No hard-coded UUIDs, no seed (accounts are admin-made).
+ * `down` drops the table.
+ */
+const { ServiceAccount } = require('@astram/identity');
+const { columnForRole, reflectObjectType } = require('@astram/engine');
+
+const SCHEMA = 'shield_app';
+
+const SaReg = reflectObjectType(ServiceAccount);
+const col = (role) => columnForRole(SaReg, role);
+
+async function up({ query }) {
+  // Only `primaryKey` + `status` are engine ROLES (single-sourced via col()); the other columns
+  // carry no role, so they are named literally — matching their `@Field({ column })` on the object
+  // (sa_tenant_id/sa_label/sa_created_at_ms) or are store-only (sa_scope_subtree/sa_role_ids/…).
+  await query(`CREATE TABLE IF NOT EXISTS \`${SCHEMA}\`.\`${SaReg.table}\` (
+    ${col('primaryKey')} VARCHAR(36)  NOT NULL,          -- the <accountId> inside the ask_ key
+    sa_tenant_id         VARCHAR(36)  NOT NULL,          -- server-stamped; tenant the account is bound to
+    sa_label             VARCHAR(200) NOT NULL,          -- human name shown in the UI (no raw id ever shown)
+    sa_scope_subtree     JSON         NOT NULL,          -- reachable node ids (least privilege; ⊆ the creator's subtree)
+    sa_role_ids          JSON         NOT NULL,          -- roles the account holds
+    ${col('status')}     VARCHAR(20)  NOT NULL DEFAULT 'active',  -- 'active' | 'disabled' (disabled ⇒ keys fail closed)
+    sa_created_by        VARCHAR(36)  NULL,              -- admin principal id (attribution; resolved to a name in UI)
+    sa_created_at_ms     BIGINT       NOT NULL,          -- epoch-ms
+    sa_updated_at_ms     BIGINT       NULL,              -- epoch-ms of last edit
+    PRIMARY KEY (${col('primaryKey')}),
+    INDEX idx_sa_tenant (sa_tenant_id),
+    INDEX idx_sa_status (${col('status')})
+  ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci`);
+}
+
+async function down({ query }) {
+  await query(`DROP TABLE IF EXISTS \`${SCHEMA}\`.\`${SaReg.table}\``);
+}
+
+module.exports = { up, down };

package/migrations/1710000000019-AddSessionMustReenroll.cjs

@@ -0,0 +1,35 @@
+/**
+ * Framework identity migration — durable re-enroll marker on `shield_identity.session`
+ * (security hardening Phase 3 part B review P1, ADR-0035 §3).
+ *
+ * A recovery-code login binds its session `mustReenroll: true` (restricted to the re-secure
+ * allowlist until a fresh MFA device is confirmed) and is never root. That restriction used to
+ * live only in Redis, so the refresh-time silent recovery (rebuilding a lost Redis binding from
+ * durable state) could not know about it and rebuilt such a session unrestricted (and root for a
+ * user on the root allowlist). This column persists it on the durable session row: set at the
+ * recovery login, cleared when a fresh device is confirmed, read by the rebuild.
+ *
+ * Why a column and not the recovery-code table: `mfa_recovery_code.mrc_consumed_at_ms` exists, but
+ * regenerating codes (allowed inside a restricted session) DELETEs the principal's rows, which
+ * would erase the evidence; and a consumer may supply its own recovery store.
+ *
+ * Additive + idempotent: `ADD COLUMN IF NOT EXISTS` with a default of 0 (existing rows = not
+ * restricted); `down` drops it with `DROP COLUMN IF EXISTS`. Literal schema/column names, no
+ * ids, run by the DDL account. `shield_core` already holds DML on `shield_identity` (no grant
+ * change).
+ */
+
+const SCHEMA = 'shield_identity';
+
+async function up({ query }) {
+  await query(
+    `ALTER TABLE \`${SCHEMA}\`.\`session\`
+       ADD COLUMN IF NOT EXISTS \`s_must_reenroll\` TINYINT(1) NOT NULL DEFAULT 0`,
+  );
+}
+
+async function down({ query }) {
+  await query(`ALTER TABLE \`${SCHEMA}\`.\`session\` DROP COLUMN IF EXISTS \`s_must_reenroll\``);
+}
+
+module.exports = { up, down };