@astram/guard 0.18.0 → 0.20.0

package/dist/audit/audit-sealer.service.d.ts

@@ -0,0 +1,62 @@
+/**
+ * `AuditSealerService` — runs the deferred audit sealer in the app (audit-chain-store SPEC
+ * §5.H, §11, §12).
+ *
+ * Registered by `PersistenceModule.forRoot()`, so it exists exactly when `SHIELD_DB_POOL`
+ * does (`ShieldModule.forRoot({ auth: true })`); an enforcement-only app has neither. There
+ * is no switch to turn it off: only `AUDIT_SEAL_INTERVAL_MS` / `AUDIT_SEAL_BATCH` tune it.
+ *
+ * - Boot (`onApplicationBootstrap`): one bounded table probe on `information_schema.TABLES`;
+ *   both `audit_log` and `audit_chain` present ⇒ tick every interval. `audit_log` absent
+ *   (auth without identity), or the probe failing (DB down, a test's stub pool) ⇒ one warning,
+ *   idle; `audit_chain` absent (migration 102 not applied) ⇒ one error per probe, idle. The
+ *   probe repeats every sweep period (1 h) and starts or stops the ticks. Never throws.
+ * - Ticks never overlap: the next one is scheduled only after the previous settled. A
+ *   rejected tick is logged by error class only and the loop continues.
+ * - Shutdown (`onModuleDestroy`, which runs before the pool is ended, and
+ *   `onApplicationShutdown`): stops the timers and waits for an in-flight tick. Idempotent.
+ * - Every timer is `unref()`'d: the sealer never keeps a process alive. Nothing here touches
+ *   the request path (Shield #12).
+ */
+import { type OnApplicationBootstrap, type OnApplicationShutdown, type OnModuleDestroy } from '@nestjs/common';
+import type { Pool } from 'mariadb';
+import type { FrameworkSchemas } from '@astram/core';
+import { type AuditSealConfig } from './audit-seal-config.js';
+import { type AuditSealerLogger } from './audit-chain-sealer.js';
+export interface AuditSealerServiceOptions {
+    /** Default `loadAuditSealConfig(process.env)`. */
+    readonly config?: AuditSealConfig;
+    /** Default `new Logger('Shield')`. */
+    readonly logger?: AuditSealerLogger;
+    /** Test seam; default an {@link AuditChainSealer} over the pool with {@link NodeSha256Hash}. */
+    readonly sealer?: {
+        tick(): Promise<unknown>;
+    };
+}
+export declare class AuditSealerService implements OnApplicationBootstrap, OnModuleDestroy, OnApplicationShutdown {
+    private readonly pool;
+    private readonly schemas;
+    private readonly config;
+    private readonly logger;
+    private readonly sealer;
+    private stopped;
+    private active;
+    private lastOutcome;
+    private tickTimer;
+    private probeTimer;
+    private inFlightTick;
+    private inFlightProbe;
+    constructor(pool: Pool, schemas: FrameworkSchemas, options?: AuditSealerServiceOptions);
+    onApplicationBootstrap(): Promise<void>;
+    onModuleDestroy(): Promise<void>;
+    onApplicationShutdown(): Promise<void>;
+    private stop;
+    /** Probe once (never overlapping, never throwing) and start or stop the ticks. */
+    private runProbe;
+    private probe;
+    /** Warnings once per change of state; the missing-chain error on every probe (SPEC §12). */
+    private report;
+    private schedule;
+    private runTick;
+}
+//# sourceMappingURL=audit-sealer.service.d.ts.map

package/dist/audit/audit-sealer.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-sealer.service.d.ts","sourceRoot":"","sources":["../../src/audit/audit-sealer.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAGL,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,eAAe,EACrB,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,EAAuB,KAAK,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACnF,OAAO,EAIL,KAAK,iBAAiB,EACvB,MAAM,yBAAyB,CAAC;AAMjC,MAAM,WAAW,yBAAyB;IACxC,kDAAkD;IAClD,QAAQ,CAAC,MAAM,CAAC,EAAE,eAAe,CAAC;IAClC,sCAAsC;IACtC,QAAQ,CAAC,MAAM,CAAC,EAAE,iBAAiB,CAAC;IACpC,gGAAgG;IAChG,QAAQ,CAAC,MAAM,CAAC,EAAE;QAAE,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC,CAAA;KAAE,CAAC;CAChD;AAID,qBACa,kBACX,YAAW,sBAAsB,EAAE,eAAe,EAAE,qBAAqB;IAevE,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAd1B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IACzC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoB;IAC3C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA+B;IAEtD,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,WAAW,CAA2B;IAC9C,OAAO,CAAC,SAAS,CAA6B;IAC9C,OAAO,CAAC,UAAU,CAA6B;IAC/C,OAAO,CAAC,YAAY,CAA4B;IAChD,OAAO,CAAC,aAAa,CAA4B;gBAG9B,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,gBAAgB,EAC1C,OAAO,GAAE,yBAA8B;IAenC,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC;IAQvC,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC;IAIhC,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC;YAI9B,IAAI;IAWlB,kFAAkF;IAClF,OAAO,CAAC,QAAQ;YAwBF,KAAK;IA4BnB,4FAA4F;IAC5F,OAAO,CAAC,MAAM;IAsBd,OAAO,CAAC,QAAQ;IAShB,OAAO,CAAC,OAAO;CAehB"}

package/dist/audit/audit-sealer.service.js

@@ -0,0 +1,197 @@
+"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.AuditSealerService = void 0;
+/**
+ * `AuditSealerService` — runs the deferred audit sealer in the app (audit-chain-store SPEC
+ * §5.H, §11, §12).
+ *
+ * Registered by `PersistenceModule.forRoot()`, so it exists exactly when `SHIELD_DB_POOL`
+ * does (`ShieldModule.forRoot({ auth: true })`); an enforcement-only app has neither. There
+ * is no switch to turn it off: only `AUDIT_SEAL_INTERVAL_MS` / `AUDIT_SEAL_BATCH` tune it.
+ *
+ * - Boot (`onApplicationBootstrap`): one bounded table probe on `information_schema.TABLES`;
+ *   both `audit_log` and `audit_chain` present ⇒ tick every interval. `audit_log` absent
+ *   (auth without identity), or the probe failing (DB down, a test's stub pool) ⇒ one warning,
+ *   idle; `audit_chain` absent (migration 102 not applied) ⇒ one error per probe, idle. The
+ *   probe repeats every sweep period (1 h) and starts or stops the ticks. Never throws.
+ * - Ticks never overlap: the next one is scheduled only after the previous settled. A
+ *   rejected tick is logged by error class only and the loop continues.
+ * - Shutdown (`onModuleDestroy`, which runs before the pool is ended, and
+ *   `onApplicationShutdown`): stops the timers and waits for an in-flight tick. Idempotent.
+ * - Every timer is `unref()`'d: the sealer never keeps a process alive. Nothing here touches
+ *   the request path (Shield #12).
+ */
+const common_1 = require("@nestjs/common");
+const audit_seal_config_js_1 = require("./audit-seal-config.js");
+const audit_chain_sealer_js_1 = require("./audit-chain-sealer.js");
+const node_sha256_hash_js_1 = require("./node-sha256-hash.js");
+/** Upper bound on the boot/re-probe query, so a hung pool cannot stall the boot hook. */
+const PROBE_TIMEOUT_MS = 10_000;
+let AuditSealerService = class AuditSealerService {
+    pool;
+    schemas;
+    config;
+    logger;
+    sealer;
+    stopped = false;
+    active = false;
+    lastOutcome;
+    tickTimer;
+    probeTimer;
+    inFlightTick;
+    inFlightProbe;
+    constructor(pool, schemas, options = {}) {
+        this.pool = pool;
+        this.schemas = schemas;
+        this.config = options.config ?? (0, audit_seal_config_js_1.loadAuditSealConfig)(process.env);
+        this.logger = options.logger ?? new common_1.Logger('Shield');
+        this.sealer =
+            options.sealer ??
+                new audit_chain_sealer_js_1.AuditChainSealer({
+                    pool,
+                    schemas,
+                    hash: new node_sha256_hash_js_1.NodeSha256Hash(),
+                    batch: this.config.batch,
+                    logger: this.logger,
+                });
+    }
+    async onApplicationBootstrap() {
+        if (this.stopped)
+            return;
+        await this.runProbe();
+        if (this.stopped || this.probeTimer !== undefined)
+            return;
+        this.probeTimer = setInterval(() => void this.runProbe(), audit_chain_sealer_js_1.AUDIT_SEAL_SWEEP_MS);
+        this.probeTimer.unref();
+    }
+    async onModuleDestroy() {
+        await this.stop();
+    }
+    async onApplicationShutdown() {
+        await this.stop();
+    }
+    async stop() {
+        this.stopped = true;
+        this.active = false;
+        if (this.tickTimer !== undefined)
+            clearTimeout(this.tickTimer);
+        if (this.probeTimer !== undefined)
+            clearInterval(this.probeTimer);
+        this.tickTimer = undefined;
+        this.probeTimer = undefined;
+        await this.inFlightProbe;
+        await this.inFlightTick;
+    }
+    /** Probe once (never overlapping, never throwing) and start or stop the ticks. */
+    runProbe() {
+        if (this.inFlightProbe !== undefined)
+            return this.inFlightProbe;
+        const run = (async () => {
+            const outcome = await this.probe();
+            if (this.stopped)
+                return;
+            this.report(outcome);
+            this.lastOutcome = outcome;
+            if (outcome === 'ready') {
+                if (!this.active) {
+                    this.active = true;
+                    this.schedule();
+                }
+            }
+            else {
+                this.active = false;
+                if (this.tickTimer !== undefined)
+                    clearTimeout(this.tickTimer);
+                this.tickTimer = undefined;
+            }
+        })().finally(() => {
+            this.inFlightProbe = undefined;
+        });
+        this.inFlightProbe = run;
+        return run;
+    }
+    async probe() {
+        let timer;
+        try {
+            const timeout = new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error('probe_timeout')), PROBE_TIMEOUT_MS);
+                timer.unref();
+            });
+            const query = Promise.resolve().then(() => this.pool.query(`SELECT TABLE_NAME FROM information_schema.TABLES
+            WHERE TABLE_SCHEMA = ? AND TABLE_NAME IN ('audit_log', 'audit_chain')`, [this.schemas.audit]));
+            query.catch(() => undefined); // a late rejection after the timeout is not unhandled
+            const rows = await Promise.race([query, timeout]);
+            if (!Array.isArray(rows))
+                return 'probe_failed';
+            const names = new Set(rows.map((r) => r.TABLE_NAME));
+            if (!names.has('audit_log'))
+                return 'no_audit_log';
+            if (!names.has('audit_chain'))
+                return 'no_audit_chain';
+            return 'ready';
+        }
+        catch {
+            return 'probe_failed';
+        }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+        }
+    }
+    /** Warnings once per change of state; the missing-chain error on every probe (SPEC §12). */
+    report(outcome) {
+        const db = this.schemas.audit;
+        if (outcome === 'no_audit_chain') {
+            this.logger.error(`audit sealer idle: ${db}.audit_chain does not exist (apply framework migration ` +
+                '1710000000102); audit_log rows stay unsealed until it does');
+            return;
+        }
+        if (outcome === this.lastOutcome)
+            return;
+        if (outcome === 'no_audit_log') {
+            this.logger.warn(`audit sealer idle: ${db}.audit_log does not exist (no identity audit store); ` +
+                're-checked every hour');
+        }
+        else if (outcome === 'probe_failed') {
+            this.logger.warn('audit sealer idle: the audit table check could not run; re-checked every hour');
+        }
+    }
+    schedule() {
+        if (!this.active || this.stopped || this.tickTimer !== undefined)
+            return;
+        this.tickTimer = setTimeout(() => {
+            this.tickTimer = undefined;
+            this.runTick();
+        }, this.config.intervalMs);
+        this.tickTimer.unref();
+    }
+    runTick() {
+        if (!this.active || this.stopped || this.inFlightTick !== undefined)
+            return;
+        this.inFlightTick = (async () => {
+            try {
+                await this.sealer.tick();
+            }
+            catch (err) {
+                this.logger.error(`audit sealer: tick failed (${(0, audit_chain_sealer_js_1.auditSealErrorClass)(err)}); retried next interval`);
+            }
+        })().finally(() => {
+            this.inFlightTick = undefined;
+            this.schedule();
+        });
+    }
+};
+exports.AuditSealerService = AuditSealerService;
+exports.AuditSealerService = AuditSealerService = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [Object, Object, Object])
+], AuditSealerService);

package/dist/audit/node-sha256-hash.d.ts

@@ -0,0 +1,6 @@
+import type { HashFunction } from '@astram/core';
+export declare class NodeSha256Hash implements HashFunction {
+    /** Lower-case hex SHA-256 of the UTF-8 bytes of `input`. */
+    hash(input: string): string;
+}
+//# sourceMappingURL=node-sha256-hash.d.ts.map

package/dist/audit/node-sha256-hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-sha256-hash.d.ts","sourceRoot":"","sources":["../../src/audit/node-sha256-hash.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD,qBAAa,cAAe,YAAW,YAAY;IACjD,4DAA4D;IAC5D,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;CAG5B"}

package/dist/audit/node-sha256-hash.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NodeSha256Hash = void 0;
+/**
+ * `HashFunction` adapter over `node:crypto` SHA-256 for the durable audit chain
+ * (audit-chain-store SPEC §5.F). Core is zero-dependency, so the hash is injected into
+ * `linkEntry` / `verifyChain`. Lower-case hex of the UTF-8 bytes; never logs its input.
+ */
+const node_crypto_1 = require("node:crypto");
+class NodeSha256Hash {
+    /** Lower-case hex SHA-256 of the UTF-8 bytes of `input`. */
+    hash(input) {
+        return (0, node_crypto_1.createHash)('sha256').update(input, 'utf8').digest('hex');
+    }
+}
+exports.NodeSha256Hash = NodeSha256Hash;

package/dist/auth/account.controller.d.ts

@@ -44,6 +44,7 @@
  */
 import type { FactorVerifier, PasswordHasher } from '@astram/core';
 import type { SessionTokenBinder } from '../request-auth/session-token-binder.js';
+import type { MfaRequirementService } from '../session/mfa-requirement-service.js';
 import type { AuditSink } from './ports/audit-sink.js';
 import type { EmailSender } from './ports/email-sender.js';
 import type { MessageDispatcher } from '../messaging/message-dispatcher.js';
@@ -87,7 +88,8 @@ export declare class AccountController {
     private readonly emailChangeLimiter?;
     private readonly auditSink?;
     private readonly messageDispatcher?;
-    constructor(binder?: SessionTokenBinder | undefined, hasher?: PasswordHasher | undefined, writer?: (CredentialWriter | null) | undefined, sweeper?: (SessionSweeper | null) | undefined, recoveryCodes?: (RecoveryCodeStore | null) | undefined, totpVerifier?: (FactorVerifier | null) | undefined, profileResolver?: (ProfileResolver | null) | undefined, profileWriter?: (ProfileWriter | null) | undefined, mfaDevices?: (MfaDeviceStore | null) | undefined, sessionRestrictions?: (SessionRestrictionStore | null) | undefined, loginTotpVerifier?: (FactorVerifier | null) | undefined, mfaLimiter?: (AttemptLimiter | null) | undefined, loginLimiter?: (AttemptLimiter | null) | undefined, emailChangeTokens?: (EmailChangeTokenStore | null) | undefined, emailAddresses?: (EmailAddressChanger | null) | undefined, emailSender?: (EmailSender | null) | undefined, emailChangeLinkBaseUrl?: string | null | undefined, emailChangeLimiter?: (AttemptLimiter | null) | undefined, auditSink?: (AuditSink | null) | undefined, messageDispatcher?: (MessageDispatcher | null) | undefined);
+    private readonly mfaRequirement?;
+    constructor(binder?: SessionTokenBinder | undefined, hasher?: PasswordHasher | undefined, writer?: (CredentialWriter | null) | undefined, sweeper?: (SessionSweeper | null) | undefined, recoveryCodes?: (RecoveryCodeStore | null) | undefined, totpVerifier?: (FactorVerifier | null) | undefined, profileResolver?: (ProfileResolver | null) | undefined, profileWriter?: (ProfileWriter | null) | undefined, mfaDevices?: (MfaDeviceStore | null) | undefined, sessionRestrictions?: (SessionRestrictionStore | null) | undefined, loginTotpVerifier?: (FactorVerifier | null) | undefined, mfaLimiter?: (AttemptLimiter | null) | undefined, loginLimiter?: (AttemptLimiter | null) | undefined, emailChangeTokens?: (EmailChangeTokenStore | null) | undefined, emailAddresses?: (EmailAddressChanger | null) | undefined, emailSender?: (EmailSender | null) | undefined, emailChangeLinkBaseUrl?: string | null | undefined, emailChangeLimiter?: (AttemptLimiter | null) | undefined, auditSink?: (AuditSink | null) | undefined, messageDispatcher?: (MessageDispatcher | null) | undefined, mfaRequirement?: (MfaRequirementService | null) | undefined);
     /**
      * Resolve a human-readable otpauth account LABEL for the caller (email, else display
      * name) via the profile resolver. Best-effort: no resolver / null profile / a thrown

package/dist/auth/account.controller.d.ts.map

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

package/dist/auth/account.controller.js

@@ -64,6 +64,8 @@ const classification_decorator_js_1 = require("../enforcement/classification.dec
 const request_principal_js_1 = require("../request-auth/request-principal.js");
 const tokens_js_1 = require("../request-auth/tokens.js");
 const tokens_js_2 = require("./tokens.js");
+const session_restriction_js_1 = require("../session/session-restriction.js");
+const auth_audit_js_1 = require("./auth-audit.js");
 const deliver_email_js_1 = require("../messaging/deliver-email.js");
 const email_address_js_1 = require("./email-address.js");
 const email_change_messages_js_1 = require("./email-change-messages.js");
@@ -169,6 +171,10 @@ function unprocessable(error) {
  * `code`. Missing → this 400 (the client then asks for the code); a wrong code is the generic
  * {@link badRequest}.
  */
+/** R2.7: the 409 for removing the last device while a mandatory-2FA policy applies. */
+function mfaRequiredByPolicy() {
+    throw new common_1.HttpException({ error: 'mfa_required_by_policy' }, common_1.HttpStatus.CONFLICT);
+}
 function nameTaken() {
     throw new common_1.HttpException({ error: 'name_taken' }, common_1.HttpStatus.CONFLICT);
 }
@@ -214,7 +220,8 @@ let AccountController = class AccountController {
     emailChangeLimiter;
     auditSink;
     messageDispatcher;
-    constructor(binder, hasher, writer, sweeper, recoveryCodes, totpVerifier, profileResolver, profileWriter, mfaDevices, sessionRestrictions, loginTotpVerifier, mfaLimiter, loginLimiter, emailChangeTokens, emailAddresses, emailSender, emailChangeLinkBaseUrl, emailChangeLimiter, auditSink, messageDispatcher) {
+    mfaRequirement;
+    constructor(binder, hasher, writer, sweeper, recoveryCodes, totpVerifier, profileResolver, profileWriter, mfaDevices, sessionRestrictions, loginTotpVerifier, mfaLimiter, loginLimiter, emailChangeTokens, emailAddresses, emailSender, emailChangeLinkBaseUrl, emailChangeLimiter, auditSink, messageDispatcher, mfaRequirement) {
         this.binder = binder;
         this.hasher = hasher;
         this.writer = writer;
@@ -235,6 +242,7 @@ let AccountController = class AccountController {
         this.emailChangeLimiter = emailChangeLimiter;
         this.auditSink = auditSink;
         this.messageDispatcher = messageDispatcher;
+        this.mfaRequirement = mfaRequirement;
     }
     /**
      * Resolve a human-readable otpauth account LABEL for the caller (email, else display
@@ -281,6 +289,11 @@ let AccountController = class AccountController {
         const claims = await this.binder.resolve(token);
         if (claims === null)
             unauthorized();
+        // Auth capabilities R2.5: re-evaluate the mandatory-2FA requirement when the permission version
+        // moved (no DB query otherwise; a failure is the 503 `authentication_unavailable`).
+        if (this.mfaRequirement !== undefined && this.mfaRequirement !== null) {
+            return this.mfaRequirement.refresh(token, claims);
+        }
         return claims;
     }
     /**
@@ -307,8 +320,11 @@ let AccountController = class AccountController {
      * A normal (`mustReenroll:false`) session is unaffected — this is a no-op for it.
      */
     enforceReenroll(claims, allowedDuringReenroll) {
-        if (claims.mustReenroll === true && !allowedDuringReenroll) {
-            throw new common_1.HttpException({ error: 'reenrollment_required' }, common_1.HttpStatus.FORBIDDEN);
+        // D-2: the same per-handler policy serves the mandatory-2FA restriction (`mfa_enrollment`,
+        // including a passed grace deadline), each reason with its own 403 code.
+        const reason = (0, session_restriction_js_1.restrictionOf)(claims, Date.now());
+        if (reason !== null && !allowedDuringReenroll) {
+            throw new common_1.HttpException({ error: (0, session_restriction_js_1.restrictionErrorCode)(reason) }, common_1.HttpStatus.FORBIDDEN);
         }
     }
     /**
@@ -812,6 +828,24 @@ let AccountController = class AccountController {
         if (claims.mustReenroll === true && this.sessionRestrictions) {
             await this.sessionRestrictions.clearMustReenroll(claims.sessionId).catch(() => undefined);
         }
+        // MANDATORY 2FA (R2.3, AC-7): a confirmed factor lifts the `mfa_enrollment` restriction and any
+        // grace deadline on THIS session at once (Redis claims + durable column; the very next request
+        // succeeds) and deletes the grace clock (R2.4). Best-effort like the re-enrol clear: a failure
+        // leaves the session restricted (the safe direction).
+        if (this.mfaRequirement !== undefined && this.mfaRequirement !== null) {
+            await this.mfaRequirement.onFactorConfirmed(claims);
+        }
+        else if ((claims.restriction === 'mfa_enrollment' || claims.mfaEnrollmentDeadlineMs !== undefined) &&
+            this.binder !== undefined &&
+            this.binder !== null) {
+            // The feature was switched off since the session was restricted: still lift it.
+            await this.binder.clearRestriction(claims.sessionId);
+            if (claims.restriction === 'mfa_enrollment') {
+                await this.sessionRestrictions?.clearMfaRestriction?.(claims.sessionId).catch(() => { });
+            }
+        }
+        // R12.2: the session's own actor and tenant; no device id, name, secret or code.
+        (0, auth_audit_js_1.emitAuthAudit)(this.auditSink, (0, auth_audit_js_1.authEvent)(auth_audit_js_1.AUTH_MFA_ENROLLED, claims.id, claims.tenantId, { firstDevice: wasFirst }));
         if (wasFirst) {
             const recoveryCodes = await this.replaceRecoveryCodes(claims.id, recoveryStore, hasher);
             return { recoveryCodes };
@@ -869,20 +903,57 @@ let AccountController = class AccountController {
         // Phase 11 #1: the canonical device id or 400 (after the session, before any proof is spent).
         const deviceId = (0, engine_1.canonicalUuid)(id) ?? badRequest();
         const code = typeof body?.code === 'string' ? body.code : '';
+        // R2.7 (AC-11): the LAST confirmed device cannot be removed while a mandatory-2FA policy
+        // applies to the caller. The requirement is evaluated first (DB reads are fine here; a failure
+        // is 503), then a cheap pre-check refuses before any proof is spent (no code is burnt), and the
+        // delete itself re-checks under a per-principal row lock (`removeKeepingOne`), so two
+        // concurrent removals can never leave zero devices.
+        const mfa = this.mfaRequirement;
+        let policyApplies = false;
+        if (mfa !== undefined && mfa !== null) {
+            try {
+                policyApplies = await mfa.requiresFactor(claims);
+            }
+            catch {
+                retryableUnavailable();
+            }
+            if (policyApplies) {
+                const confirmed = (await store.listAll(claims.id)).filter((d) => d.confirmed);
+                if (confirmed.length === 1 && confirmed[0].id === deviceId)
+                    mfaRequiredByPolicy();
+            }
+        }
         // Proof BEFORE the delete: a TOTP from any confirmed device (incl. the one being
         // removed — legit for the last-device disable) OR a valid recovery code. Rate-limited
         // and replay-guarded like `/auth/mfa` (Phase 8 #1).
         await this.requireMfaProof(store, claims.id, code);
-        const removed = await store.remove(claims.id, deviceId);
+        let removed;
+        if (policyApplies && typeof store.removeKeepingOne === 'function') {
+            const outcome = await store.removeKeepingOne(claims.id, deviceId);
+            if (outcome === 'last_device')
+                mfaRequiredByPolicy();
+            removed = outcome === 'removed';
+        }
+        else {
+            removed = await store.remove(claims.id, deviceId);
+        }
         if (!removed) {
             throw new common_1.HttpException({ error: 'not_found' }, common_1.HttpStatus.NOT_FOUND);
         }
         // Removing the last confirmed device disables MFA → wipe the account recovery codes.
-        if ((await store.countConfirmed(claims.id)) === 0) {
+        const mfaOff = (await store.countConfirmed(claims.id)) === 0;
+        // R2.7 defence in depth: a store without the atomic removal (or any other path) still left no
+        // factor while a policy applies → restrict THIS session now, not at the next sign-in.
+        if (mfaOff && policyApplies && mfa !== undefined && mfa !== null) {
+            await mfa.restrictNow(claims);
+        }
+        if (mfaOff) {
             if (this.recoveryCodes !== undefined && this.recoveryCodes !== null) {
                 await this.recoveryCodes.replaceAll(claims.id, []);
             }
         }
+        // R12.2: the session's own actor and tenant; no device id, secret or code.
+        (0, auth_audit_js_1.emitAuthAudit)(this.auditSink, (0, auth_audit_js_1.authEvent)(auth_audit_js_1.AUTH_MFA_REMOVED, claims.id, claims.tenantId, { mfaOff }));
     }
     /**
      * `POST /account/mfa/recovery-codes/regenerate` — mint a fresh recovery-code batch
@@ -1045,5 +1116,7 @@ exports.AccountController = AccountController = __decorate([
     __param(18, (0, common_1.Inject)(tokens_js_2.SHIELD_AUDIT_SINK)),
     __param(19, (0, common_1.Optional)()),
     __param(19, (0, common_1.Inject)(tokens_js_2.SHIELD_MESSAGE_DISPATCHER)),
-    __metadata("design:paramtypes", [Function, Object, Object, Object, Object, Object, Object, Object, Object, Object, Object, Object, Object, Object, Object, Object, Object, Object, Object, Object])
+    __param(20, (0, common_1.Optional)()),
+    __param(20, (0, common_1.Inject)(tokens_js_2.SHIELD_MFA_REQUIREMENT)),
+    __metadata("design:paramtypes", [Function, Object, Object, Object, Object, Object, Object, Object, Object, Object, Object, Object, Object, Object, Object, Object, Object, Object, Object, Object, Object])
 ], AccountController);

package/dist/auth/admin-signin-controls.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Auth capabilities R11 (task 18, B-5): the guard pieces behind `@astram/identity`'s admin sign-in
+ * controls (`POST /identity/users/:uuid/{reset-mfa,unlock,end-sessions}`). Guard never imports
+ * identity (ADR-0003): identity injects these through the tokens re-exported from
+ * `@astram/guard/internal` ({@link SHIELD_ADMIN_STEP_UP}, {@link SHIELD_ACCOUNT_UNLOCKER}).
+ *
+ * ── STEP-UP (R11.2) ─────────────────────────────────────────────────────────
+ *   The admin's OWN current TOTP, checked the way the code-gated `/account` routes check it
+ *   (`AccountController.requireMfaProof`): the attempt is counted on the admin's `mfa:pid:<id>`
+ *   budget BEFORE verifying (atomic increment-first), the code is verified against every confirmed
+ *   device through the replay-guarded login verifier (an accepted code is spent on every path), a
+ *   success resets the budget. TOTP only: recovery codes are not accepted here (R11.2). The login
+ *   step-up (`mfa-step-up.ts`) needs a pending password challenge, so it is not reused directly.
+ *   No confirmed device ⇒ `no_factor` before anything is counted.
+ *
+ * ── UNLOCK (R11.1) ──────────────────────────────────────────────────────────
+ *   Clears `login:pid:<id>`, `mfa:pid:<id>`, `recovery:<id>` (each on its own limiter) and the
+ *   account CAPTCHA counter of every CAPTCHA endpoint (`shield:captcha:<ep>:pid:<id>`). The
+ *   typed-text CAPTCHA keys hash the text a user typed and cannot be derived from the account; they
+ *   expire with their window. Any Redis error rejects ({@link AdminControlUnavailableError}).
+ */
+import type { FactorVerifier } from '@astram/core';
+import type { MfaDeviceStore } from './ports/mfa-device-store.js';
+import type { AttemptLimiter } from './rate-limit/attempt-limiter.js';
+/** A store the admin control needs could not answer; nothing is claimed (caller → 503). */
+export declare class AdminControlUnavailableError extends Error {
+    constructor();
+}
+/**
+ * The step-up verdict:
+ *  - `verified`: the code is right (budget reset);
+ *  - `no_factor`: the admin has no confirmed device (caller → 409 `mfa_required`), nothing counted;
+ *  - `missing`: blank code, nothing counted;
+ *  - `rejected`: wrong code (stays counted);
+ *  - `locked`: the admin's `mfa:pid` budget is spent;
+ *  - `unavailable`: a store could not answer (fail closed).
+ */
+export type AdminStepUpOutcome = 'verified' | 'no_factor' | 'missing' | 'rejected' | 'locked' | 'unavailable';
+/** The seam identity injects under {@link SHIELD_ADMIN_STEP_UP}. */
+export interface AdminStepUp {
+    verify(principalId: string, code: string): Promise<AdminStepUpOutcome>;
+}
+export interface TotpAdminStepUpDeps {
+    readonly devices: Pick<MfaDeviceStore, 'listConfirmedSecrets'> | null;
+    /** The replay-guarded login TOTP verifier (`SHIELD_LOGIN_TOTP_VERIFIER`). */
+    readonly verifier: FactorVerifier | null;
+    /** The MFA step limiter (`SHIELD_MFA_LIMITER`, `mfa:pid:<id>`). */
+    readonly limiter: Pick<AttemptLimiter, 'consume' | 'refund' | 'reset'> | null;
+}
+export declare class TotpAdminStepUp implements AdminStepUp {
+    private readonly deps;
+    constructor(deps: TotpAdminStepUpDeps);
+    verify(principalId: string, code: string): Promise<AdminStepUpOutcome>;
+}
+/** The keys one unlock clears (limiter keys without the `shield:attempts:` namespace). */
+export declare function accountUnlockKeys(principalId: string): {
+    login: string;
+    mfa: string;
+    recovery: string;
+    captcha: string[];
+};
+/** The seam identity injects under {@link SHIELD_ACCOUNT_UNLOCKER}. */
+export interface AccountUnlocker {
+    /** Clear every sign-in counter of the principal; rejects {@link AdminControlUnavailableError}. */
+    unlock(principalId: string): Promise<void>;
+}
+export interface RedisAccountUnlockerDeps {
+    readonly login: Pick<AttemptLimiter, 'clear'>;
+    readonly mfa: Pick<AttemptLimiter, 'clear'>;
+    readonly recovery: Pick<AttemptLimiter, 'clear'>;
+    readonly captcha: {
+        clearStrict(keys: readonly string[]): Promise<void>;
+    };
+}
+export declare class RedisAccountUnlocker implements AccountUnlocker {
+    private readonly deps;
+    constructor(deps: RedisAccountUnlockerDeps);
+    unlock(principalId: string): Promise<void>;
+}
+//# sourceMappingURL=admin-signin-controls.d.ts.map

package/dist/auth/admin-signin-controls.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin-signin-controls.d.ts","sourceRoot":"","sources":["../../src/auth/admin-signin-controls.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAEtE,2FAA2F;AAC3F,qBAAa,4BAA6B,SAAQ,KAAK;;CAKtD;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,kBAAkB,GAC5B,UAAU,GAAG,WAAW,GAAG,SAAS,GAAG,UAAU,GAAG,QAAQ,GAAG,aAAa,CAAC;AAE/E,oEAAoE;AACpE,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;CACxE;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,cAAc,EAAE,sBAAsB,CAAC,GAAG,IAAI,CAAC;IACtE,6EAA6E;IAC7E,QAAQ,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI,CAAC;IACzC,mEAAmE;IACnE,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,cAAc,EAAE,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAC,GAAG,IAAI,CAAC;CAC/E;AAED,qBAAa,eAAgB,YAAW,WAAW;IACrC,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,mBAAmB;IAEhD,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC;CAmC7E;AAED,0FAA0F;AAC1F,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG;IACtD,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB,CAOA;AAED,uEAAuE;AACvE,MAAM,WAAW,eAAe;IAC9B,kGAAkG;IAClG,MAAM,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5C;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC;IAC9C,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC;IAC5C,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC;IACjD,QAAQ,CAAC,OAAO,EAAE;QAAE,WAAW,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;KAAE,CAAC;CAC3E;AAED,qBAAa,oBAAqB,YAAW,eAAe;IAC9C,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,wBAAwB;IAErD,MAAM,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAcjD"}