@astram/guard 0.10.2 → 0.11.1

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

@@ -44,6 +44,10 @@
  */
 import type { FactorVerifier, PasswordHasher } from '@astram/core';
 import type { SessionTokenBinder } from '../request-auth/session-token-binder.js';
+import type { AuditSink } from './ports/audit-sink.js';
+import type { EmailSender } from './ports/email-sender.js';
+import type { EmailChangeTokenStore } from './ports/email-change-token-store.js';
+import type { EmailAddressChanger } from './ports/email-address-changer.js';
 import type { SessionRestrictionStore } from '../session/session-restriction-store.js';
 import type { AttemptLimiter } from './rate-limit/attempt-limiter.js';
 import type { CredentialWriter } from './ports/credential-writer.js';
@@ -52,6 +56,15 @@ import type { CurrentUserProfile, ProfileResolver } from './profile-resolver.js'
 import type { ProfileWriter } from './ports/profile-writer.js';
 import type { RecoveryCodeStore } from './ports/recovery-code-store.js';
 import type { SessionSweeper } from './ports/session-sweeper.js';
+/** The minimal response surface the 202 answer needs (Express-compatible). */
+interface StatusSettable {
+    status(code: number): unknown;
+}
+/** The 202 body of an accepted email change (the address changes only after confirmation). */
+export interface PendingEmailChange {
+    readonly pendingEmail: true;
+    readonly profile: CurrentUserProfile;
+}
 export declare class AccountController {
     private readonly binder?;
     private readonly hasher?;
@@ -66,7 +79,13 @@ export declare class AccountController {
     private readonly loginTotpVerifier?;
     private readonly mfaLimiter?;
     private readonly loginLimiter?;
-    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);
+    private readonly emailChangeTokens?;
+    private readonly emailAddresses?;
+    private readonly emailSender?;
+    private readonly emailChangeLinkBaseUrl?;
+    private readonly emailChangeLimiter?;
+    private readonly auditSink?;
+    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);
     /**
      * 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
@@ -138,27 +157,45 @@ export declare class AccountController {
      */
     private verifyTotp;
     /**
-     * `PATCH /account/profile` — edit the AUTHENTICATED caller's OWN display profile
-     * (name and/or email). Self-scoped: acts only on `claims.id`. On success returns the
-     * refreshed {@link CurrentUserProfile} (display names, never UUIDs — the bare `id`
-     * fields are machine-only), so the UI can update the header/user card in place.
-     *
-     * Only the fields actually supplied are written (partial edit). At least one of
-     * `name`/`email` must be present and non-empty; a supplied email must look like an
-     * email. These are semantic validations on the caller's OWN profile (no credential
-     * oracle), so they return precise 422 reasons rather than a generic 4xx.
+     * `PATCH /account/profile` — edit the AUTHENTICATED caller's OWN profile. Self-scoped: acts only
+     * on `claims.id`. A `name` is applied at once. An `email` is NEVER written here (security
+     * hardening Phase 12, KI #14): the request is verified and a confirm link goes to the NEW
+     * address; `POST /auth/confirm-email` applies it.
      *
      * Outcomes:
-     *   • no/invalid token                       → 401 (generic)
-     *   • profileWriter seam absent              → 501 `{ error: 'not_available' }`
-     *   • neither name nor email supplied        → 422 `{ error: 'no_changes' }`
-     *   • email supplied but malformed           → 422 `{ error: 'invalid_email' }`
-     *   • success                                → 200 (the refreshed CurrentUserProfile)
+     *   • no/invalid token                       → 401 (generic); re-enroll session → 403
+     *   • neither name nor email supplied        → 422 `no_changes`
+     *   • email malformed                        → 422 `invalid_email`
+     *   • email collation-equal to the current   → 422 `no_changes`
+     *   • a seam unplugged                       → 501 `not_available`
+     *   • email without / with a wrong `currentPassword` → 400 `invalid_current_password`
+     *     (counted on the account's `login:pid` budget, like change-password); locked → 429
+     *   • a confirmed MFA device and no `code`   → 400 `mfa_required`; wrong code → 400
+     *     `invalid_request` (`mfa:pid` budget, replay-guarded TOTP or a recovery code, A1); locked → 429
+     *   • `email-change:pid` budget exhausted    → 429 `too_many_requests`
+     *   • a limiter / MFA device or recovery-code store / token store / mail outage → 503
+     *     `authentication_unavailable` (the token is issued before the second factor is checked, so
+     *     a STORE outage never spends a recovery code or a TOTP; a failed proof burns that token. A
+     *     mail failure after a successful proof does spend it — the proof precedes the send)
+     *   • name only                              → 200 (the refreshed CurrentUserProfile)
+     *   • email accepted                         → 202 `{ pendingEmail: true, profile }`
+     *
+     * The token (32 random bytes) is stored only as its sha256, bound to the canonical new address,
+     * the current email and this session (A3), and reaches the user only inside the mailed link's
+     * fragment (`#t=`). This handler writes no log line; the dev `LogEmailSender` (development/test
+     * only) is the one place the link is printed, exactly like a reset link.
      */
     updateProfile(authorization: string | undefined, body: {
         name?: string;
         email?: string;
-    }): Promise<CurrentUserProfile>;
+        currentPassword?: string;
+        code?: string;
+    }, res: StatusSettable): Promise<CurrentUserProfile | PendingEmailChange>;
+    /**
+     * The verified half of an email change request (Phase 12): checks, proofs, budget, token, mail,
+     * audit. Throws the contract's HttpException on every refusal; returns once the link is sent.
+     */
+    private requestEmailChange;
     /**
      * Mint a fresh recovery-code batch, hash each (the SAME Argon2 hasher recovery-code
      * consume verifies against), and REPLACE the caller's prior codes. Returns the RAW
@@ -206,10 +243,20 @@ export declare class AccountController {
      * material (`otpauthUri` for a QR + `secret` for manual entry). NOT active until
      * `confirm`. A blank name defaults to `"Authenticator N"` (N = confirmed count + 1).
      *
-     * Outcomes: 401; store absent → 501; success → 200 `{ deviceId, otpauthUri, secret }`.
+     * KI #14 re-review P1-1: when the caller ALREADY has a confirmed device, adding another needs a
+     * second-factor `code` (a TOTP from an existing device via the replay-guarded verifier, or a
+     * recovery code; `mfa:pid` budget — {@link requireMfaProof}). Otherwise a stolen session alone
+     * could enrol the attacker's authenticator and use it for every code-gated step-up (A1). The
+     * recovery-login re-enroll session (`mustReenroll`, durable `s_must_reenroll`) is exempt: it
+     * proved a recovery code at sign-in and has lost its device, so it cannot produce a code.
+     *
+     * Outcomes: 401; store absent → 501; MFA on and no `code` → 400 `mfa_required`; wrong code →
+     * 400 `invalid_request`; MFA budget exhausted → 429; limiter/replay guard unreachable → 503;
+     * success → 200 `{ deviceId, otpauthUri, secret }`.
      */
     beginDevice(authorization: string | undefined, body: {
         name?: string;
+        code?: string;
     }): Promise<{
         deviceId: string;
         otpauthUri: string;
@@ -222,8 +269,17 @@ export declare class AccountController {
      * codes are minted (shown once) and returned; subsequent devices return `{}` and do
      * NOT touch recovery codes.
      *
-     * Outcomes: 401; store/recovery/hasher absent → 501; device not pending/owned → 404;
-     * wrong/expired code → 400 (device stays pending); success → 200 `{ recoveryCodes? }`.
+     * KI #14 re-review P1-1 (defence in depth for the code-gated `begin`): when MFA is already on and
+     * the session is not a re-enroll session, only a pending device that `begin` created behind its
+     * step-up can be confirmed. A pending device carries no proof flag, so the binding is by time:
+     * while MFA is on, `begin` cannot create a pending device without a proof, so the device must be
+     * younger than the pending window ({@link PENDING_DEVICE_MAX_AGE_MS}, the store's self-prune
+     * TTL) and not older than the newest confirmed device. That refuses a device begun while MFA was
+     * still off (e.g. by a stolen session, before the user enrolled) and any stale pending row.
+     *
+     * Outcomes: 401; store/recovery/hasher absent → 501; device not pending/owned, or (MFA on) not
+     * bound to a step-up begin → 404; wrong/expired code → 400 (device stays pending); success →
+     * 200 `{ recoveryCodes? }`.
      */
     confirmDevice(authorization: string | undefined, body: {
         deviceId?: string;
@@ -272,4 +328,5 @@ export declare class AccountController {
         recoveryCodes: string[];
     }>;
 }
+export {};
 //# sourceMappingURL=account.controller.d.ts.map

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

@@ -58,15 +58,23 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AccountController = void 0;
 const common_1 = require("@nestjs/common");
+const node_crypto_1 = require("node:crypto");
 const engine_1 = require("@astram/engine");
 const classification_decorator_js_1 = require("../enforcement/classification.decorator.js");
 const request_principal_js_1 = require("../request-auth/request-principal.js");
 const tokens_js_1 = require("../request-auth/tokens.js");
 const tokens_js_2 = require("./tokens.js");
+const email_address_js_1 = require("./email-address.js");
+const email_change_messages_js_1 = require("./email-change-messages.js");
 const canonical_hint_js_1 = require("./rate-limit/canonical-hint.js");
 const totp_enrollment_js_1 = require("./totp-enrollment.js");
 /** Max length of a device name (matches the `md_name VARCHAR(120)` column). */
 const MAX_DEVICE_NAME_LEN = 120;
+/**
+ * How long a pending (begun, unconfirmed) device may still be confirmed once MFA is on — the same
+ * 15 minutes after which `MariaDbMfaDeviceStore.begin` prunes it (KI #14 re-review P1-1).
+ */
+const PENDING_DEVICE_MAX_AGE_MS = 15 * 60 * 1000;
 /** Minimum acceptable new-password length (the only policy this route enforces). */
 const MIN_PASSWORD_LEN = 8;
 /**
@@ -154,6 +162,18 @@ async function consumeAttempt(limiter, key) {
 function unprocessable(error) {
     throw new common_1.HttpException({ error }, common_1.HttpStatus.UNPROCESSABLE_ENTITY);
 }
+/**
+ * Phase 12 (A1): an email change by a user with a confirmed MFA device must carry a second-factor
+ * `code`. Missing → this 400 (the client then asks for the code); a wrong code is the generic
+ * {@link badRequest}.
+ */
+function mfaRequired() {
+    throw new common_1.HttpException({ error: 'mfa_required' }, common_1.HttpStatus.BAD_REQUEST);
+}
+/** SHA-256 hex of a raw token: stores only ever see this hash. */
+function sha256Hex(value) {
+    return (0, node_crypto_1.createHash)('sha256').update(value).digest('hex');
+}
 let AccountController = class AccountController {
     binder;
     hasher;
@@ -168,7 +188,13 @@ let AccountController = class AccountController {
     loginTotpVerifier;
     mfaLimiter;
     loginLimiter;
-    constructor(binder, hasher, writer, sweeper, recoveryCodes, totpVerifier, profileResolver, profileWriter, mfaDevices, sessionRestrictions, loginTotpVerifier, mfaLimiter, loginLimiter) {
+    emailChangeTokens;
+    emailAddresses;
+    emailSender;
+    emailChangeLinkBaseUrl;
+    emailChangeLimiter;
+    auditSink;
+    constructor(binder, hasher, writer, sweeper, recoveryCodes, totpVerifier, profileResolver, profileWriter, mfaDevices, sessionRestrictions, loginTotpVerifier, mfaLimiter, loginLimiter, emailChangeTokens, emailAddresses, emailSender, emailChangeLinkBaseUrl, emailChangeLimiter, auditSink) {
         this.binder = binder;
         this.hasher = hasher;
         this.writer = writer;
@@ -182,6 +208,12 @@ let AccountController = class AccountController {
         this.loginTotpVerifier = loginTotpVerifier;
         this.mfaLimiter = mfaLimiter;
         this.loginLimiter = loginLimiter;
+        this.emailChangeTokens = emailChangeTokens;
+        this.emailAddresses = emailAddresses;
+        this.emailSender = emailSender;
+        this.emailChangeLinkBaseUrl = emailChangeLinkBaseUrl;
+        this.emailChangeLimiter = emailChangeLimiter;
+        this.auditSink = auditSink;
     }
     /**
      * Resolve a human-readable otpauth account LABEL for the caller (email, else display
@@ -330,11 +362,20 @@ let AccountController = class AccountController {
         await this.loginLimiter?.reset(loginKey);
         const newHash = await hasher.hash(newPassword);
         await writer.setPassword(claims.id, newHash);
+        // Phase 12 (A8): a pending email change requested with the OLD password dies with it. Burned
+        // after the write (a new request then needs the new password); a failure is surfaced after the
+        // session sweep below ran.
+        let burnError;
+        await this.emailChangeTokens?.invalidateAllForPrincipal(claims.id).catch((err) => {
+            burnError = err;
+        });
         // Revoke the caller's OTHER sessions (keep the current one live). Best-effort:
         // absent seam → skip (the password is already changed).
         if (this.sweeper !== undefined && this.sweeper !== null) {
             await this.sweeper.revokeOthersForPrincipal(claims.id, claims.sessionId);
         }
+        if (burnError !== undefined)
+            throw burnError;
     }
     /**
      * Verify a presented TOTP `code` against a base32 `secret` using the injected core
@@ -349,53 +390,195 @@ let AccountController = class AccountController {
         return verdict.satisfied;
     }
     /**
-     * `PATCH /account/profile` — edit the AUTHENTICATED caller's OWN display profile
-     * (name and/or email). Self-scoped: acts only on `claims.id`. On success returns the
-     * refreshed {@link CurrentUserProfile} (display names, never UUIDs — the bare `id`
-     * fields are machine-only), so the UI can update the header/user card in place.
-     *
-     * Only the fields actually supplied are written (partial edit). At least one of
-     * `name`/`email` must be present and non-empty; a supplied email must look like an
-     * email. These are semantic validations on the caller's OWN profile (no credential
-     * oracle), so they return precise 422 reasons rather than a generic 4xx.
+     * `PATCH /account/profile` — edit the AUTHENTICATED caller's OWN profile. Self-scoped: acts only
+     * on `claims.id`. A `name` is applied at once. An `email` is NEVER written here (security
+     * hardening Phase 12, KI #14): the request is verified and a confirm link goes to the NEW
+     * address; `POST /auth/confirm-email` applies it.
      *
      * Outcomes:
-     *   • no/invalid token                       → 401 (generic)
-     *   • profileWriter seam absent              → 501 `{ error: 'not_available' }`
-     *   • neither name nor email supplied        → 422 `{ error: 'no_changes' }`
-     *   • email supplied but malformed           → 422 `{ error: 'invalid_email' }`
-     *   • success                                → 200 (the refreshed CurrentUserProfile)
+     *   • no/invalid token                       → 401 (generic); re-enroll session → 403
+     *   • neither name nor email supplied        → 422 `no_changes`
+     *   • email malformed                        → 422 `invalid_email`
+     *   • email collation-equal to the current   → 422 `no_changes`
+     *   • a seam unplugged                       → 501 `not_available`
+     *   • email without / with a wrong `currentPassword` → 400 `invalid_current_password`
+     *     (counted on the account's `login:pid` budget, like change-password); locked → 429
+     *   • a confirmed MFA device and no `code`   → 400 `mfa_required`; wrong code → 400
+     *     `invalid_request` (`mfa:pid` budget, replay-guarded TOTP or a recovery code, A1); locked → 429
+     *   • `email-change:pid` budget exhausted    → 429 `too_many_requests`
+     *   • a limiter / MFA device or recovery-code store / token store / mail outage → 503
+     *     `authentication_unavailable` (the token is issued before the second factor is checked, so
+     *     a STORE outage never spends a recovery code or a TOTP; a failed proof burns that token. A
+     *     mail failure after a successful proof does spend it — the proof precedes the send)
+     *   • name only                              → 200 (the refreshed CurrentUserProfile)
+     *   • email accepted                         → 202 `{ pendingEmail: true, profile }`
+     *
+     * The token (32 random bytes) is stored only as its sha256, bound to the canonical new address,
+     * the current email and this session (A3), and reaches the user only inside the mailed link's
+     * fragment (`#t=`). This handler writes no log line; the dev `LogEmailSender` (development/test
+     * only) is the one place the link is printed, exactly like a reset link.
      */
-    async updateProfile(authorization, body) {
+    async updateProfile(authorization, body, res) {
         const claims = await this.requireClaims(authorization);
         // BLOCKED during re-enroll: profile edits are not part of re-securing the account.
         this.enforceReenroll(claims, false);
         // Normalize: treat only non-empty string fields as a real change (trim so a
         // whitespace-only value is not a change).
         const name = typeof body?.name === 'string' && body.name.trim().length > 0 ? body.name.trim() : undefined;
-        const email = typeof body?.email === 'string' && body.email.trim().length > 0
-            ? body.email.trim()
-            : undefined;
+        const rawEmail = typeof body?.email === 'string' && body.email.trim().length > 0 ? body.email : undefined;
         // Nothing to update → explicit 422 (rather than a silent no-op re-read).
-        if (name === undefined && email === undefined) {
+        if (name === undefined && rawEmail === undefined) {
             unprocessable('no_changes');
         }
-        // Basic email shape check when an email is supplied (non-empty already ensured).
-        if (email !== undefined && !isEmailShaped(email)) {
+        // A5: canonicalise ONCE; this value is the token row, the collision check and the write.
+        const email = rawEmail === undefined ? undefined : (0, email_address_js_1.canonicalEmail)(rawEmail);
+        if (email !== undefined && !(0, email_address_js_1.isEmailShaped)(email)) {
             unprocessable('invalid_email');
         }
         // Fail-closed when the write seam is unplugged — an honest "not available".
         if (this.profileWriter === undefined || this.profileWriter === null) {
             notAvailable();
         }
-        // Build the change with ONLY the supplied fields (partial edit), then return the
-        // refreshed display profile the writer re-reads (names, never UUIDs).
-        const changes = {};
-        if (name !== undefined)
-            changes.name = name;
-        if (email !== undefined)
-            changes.email = email;
-        return this.profileWriter.update(claims.id, changes);
+        const profileWriter = this.profileWriter;
+        if (email === undefined) {
+            return profileWriter.update(claims.id, { name: name });
+        }
+        await this.requestEmailChange(claims, email, body);
+        // A name in the same body still applies at once; the email waits for confirmation.
+        const profile = await profileWriter.update(claims.id, name === undefined ? {} : { name });
+        res.status(common_1.HttpStatus.ACCEPTED);
+        return { pendingEmail: true, profile };
+    }
+    /**
+     * The verified half of an email change request (Phase 12): checks, proofs, budget, token, mail,
+     * audit. Throws the contract's HttpException on every refusal; returns once the link is sent.
+     */
+    async requestEmailChange(claims, email, body) {
+        const tokens = this.emailChangeTokens;
+        const addresses = this.emailAddresses;
+        const sender = this.emailSender;
+        const writer = this.writer;
+        const hasher = this.hasher;
+        const devices = this.mfaDevices;
+        if (tokens == null ||
+            addresses == null ||
+            sender == null ||
+            writer == null ||
+            hasher === undefined ||
+            devices == null) {
+            notAvailable();
+        }
+        let current;
+        try {
+            current = await addresses.readCurrent(claims.id, email);
+        }
+        catch {
+            retryableUnavailable();
+        }
+        if (current === null || !current.active)
+            unauthorized();
+        if (current.sameAsCandidate)
+            unprocessable('no_changes');
+        // The current password, on the account's shared `login:pid` budget (as change-password): the
+        // attempt is counted first; a missing password is the same counted 400 as a wrong one.
+        const currentPassword = typeof body?.currentPassword === 'string' ? body.currentPassword : '';
+        const loginKey = (0, canonical_hint_js_1.loginHintKey)('', claims.id);
+        await consumeAttempt(this.loginLimiter, loginKey);
+        let matches;
+        try {
+            const stored = await writer.getPasswordHash(claims.id);
+            matches = stored !== null && (await hasher.verify(stored, currentPassword));
+        }
+        catch {
+            await this.loginLimiter?.refund(loginKey);
+            retryableUnavailable();
+        }
+        if (!matches)
+            invalidCurrentPassword();
+        await this.loginLimiter?.reset(loginKey);
+        // The per-account request budget, counted only once the password proved the caller (a typo
+        // never spends it); given back when the second factor is missing or wrong, and when a store
+        // outage stops the request before any link is mailed (Phase 13 #2b). A mail failure keeps it
+        // counted: the sender may have delivered before it failed.
+        const requestKey = `email-change:pid:${claims.id}`;
+        await consumeAttempt(this.emailChangeLimiter, requestKey);
+        const giveBackRequest = async () => {
+            await this.emailChangeLimiter?.refund(requestKey).catch(() => undefined);
+        };
+        // A1: a confirmed MFA device ⇒ a second factor. A store outage here is a 503, not a 500.
+        let code = null;
+        try {
+            if ((await devices.countConfirmed(claims.id)) > 0) {
+                code = typeof body?.code === 'string' ? body.code.trim() : '';
+            }
+        }
+        catch {
+            await giveBackRequest();
+            retryableUnavailable();
+        }
+        if (code === '') {
+            await giveBackRequest();
+            mfaRequired();
+        }
+        // A2/A3/A4: one pending change; 32 random bytes, stored as sha256, bound to the canonical new
+        // address, the current email and this session; 30-minute TTL.
+        // Phase 13 #2b: the token is issued BEFORE the second factor is checked, so a token-store outage
+        // never spends a recovery code (consumed on a match) or a TOTP (claimed by the replay guard).
+        // Until the mail goes out the raw token exists only in this handler, so a row whose proof then
+        // fails is inert; it is burned anyway (best effort).
+        const rawToken = (0, node_crypto_1.randomBytes)(32).toString('hex');
+        try {
+            await tokens.issue({
+                tokenHash: sha256Hex(rawToken),
+                principalId: claims.id,
+                newEmail: email,
+                oldEmail: current.email,
+                sessionId: claims.sessionId,
+                tenantId: claims.tenantId,
+                expiresAtMs: Date.now() + email_change_messages_js_1.EMAIL_CHANGE_TTL_MS,
+            });
+        }
+        catch {
+            await giveBackRequest();
+            retryableUnavailable();
+        }
+        // A1: TOTP via the replay-guarded verifier, or a recovery code, on the shared `mfa:pid` budget,
+        // exactly like the code-gated MFA routes. Any refusal (400/429/503) burns the token just issued
+        // and gives the request budget back; a store error inside the proof is a 503, not a 500.
+        if (code !== null) {
+            try {
+                await this.requireMfaProof(devices, claims.id, code);
+            }
+            catch (err) {
+                await tokens.invalidateAllForPrincipal(claims.id).catch(() => undefined);
+                await giveBackRequest();
+                if (err instanceof common_1.HttpException)
+                    throw err;
+                retryableUnavailable();
+            }
+        }
+        const link = (0, email_change_messages_js_1.emailChangeLink)(this.emailChangeLinkBaseUrl ?? email_change_messages_js_1.DEFAULT_EMAIL_CHANGE_LINK_BASE_URL, rawToken);
+        try {
+            await sender.send((0, email_change_messages_js_1.confirmEmailChangeMessage)(email, link));
+        }
+        catch {
+            // Undeliverable: burn the token so no orphan link can be used later, and say "retry".
+            await tokens.invalidateAllForPrincipal(claims.id).catch(() => undefined);
+            retryableUnavailable();
+        }
+        // A9: audit the request with the new address masked (no addresses in full, no token).
+        void this.auditSink
+            ?.record({
+            type: 'authentication',
+            occurredAtMs: Date.now(),
+            actorId: claims.id,
+            tenantId: claims.tenantId,
+            action: 'account.email_change_requested',
+            attributes: { newEmail: (0, email_address_js_1.maskEmail)(email) },
+        })
+            .catch(() => {
+            /* best-effort: an audit failure never changes the response */
+        });
     }
     // ───────────────────────────────────────────────────────────────────────────
     // Multi-device MFA — self-scoped device management. Every route
@@ -495,7 +678,16 @@ let AccountController = class AccountController {
      * material (`otpauthUri` for a QR + `secret` for manual entry). NOT active until
      * `confirm`. A blank name defaults to `"Authenticator N"` (N = confirmed count + 1).
      *
-     * Outcomes: 401; store absent → 501; success → 200 `{ deviceId, otpauthUri, secret }`.
+     * KI #14 re-review P1-1: when the caller ALREADY has a confirmed device, adding another needs a
+     * second-factor `code` (a TOTP from an existing device via the replay-guarded verifier, or a
+     * recovery code; `mfa:pid` budget — {@link requireMfaProof}). Otherwise a stolen session alone
+     * could enrol the attacker's authenticator and use it for every code-gated step-up (A1). The
+     * recovery-login re-enroll session (`mustReenroll`, durable `s_must_reenroll`) is exempt: it
+     * proved a recovery code at sign-in and has lost its device, so it cannot produce a code.
+     *
+     * Outcomes: 401; store absent → 501; MFA on and no `code` → 400 `mfa_required`; wrong code →
+     * 400 `invalid_request`; MFA budget exhausted → 429; limiter/replay guard unreachable → 503;
+     * success → 200 `{ deviceId, otpauthUri, secret }`.
      */
     async beginDevice(authorization, body) {
         const claims = await this.requireClaims(authorization);
@@ -504,10 +696,17 @@ let AccountController = class AccountController {
         if (this.mfaDevices === undefined || this.mfaDevices === null)
             notAvailable();
         const store = this.mfaDevices;
+        const confirmedCount = await store.countConfirmed(claims.id);
+        if (confirmedCount > 0 && claims.mustReenroll !== true) {
+            const code = typeof body?.code === 'string' ? body.code.trim() : '';
+            if (code === '')
+                mfaRequired();
+            await this.requireMfaProof(store, claims.id, code);
+        }
         const rawName = typeof body?.name === 'string' ? body.name.trim() : '';
         const name = rawName.length > 0
             ? rawName.slice(0, MAX_DEVICE_NAME_LEN)
-            : `Authenticator ${(await store.countConfirmed(claims.id)) + 1}`;
+            : `Authenticator ${confirmedCount + 1}`;
         const secret = (0, totp_enrollment_js_1.generateTotpSecret)();
         const deviceId = await store.begin(claims.id, name, secret);
         const otpauthUri = (0, totp_enrollment_js_1.buildOtpauthUri)(secret, await this.resolveOtpauthLabel(claims), TOTP_ISSUER);
@@ -520,8 +719,17 @@ let AccountController = class AccountController {
      * codes are minted (shown once) and returned; subsequent devices return `{}` and do
      * NOT touch recovery codes.
      *
-     * Outcomes: 401; store/recovery/hasher absent → 501; device not pending/owned → 404;
-     * wrong/expired code → 400 (device stays pending); success → 200 `{ recoveryCodes? }`.
+     * KI #14 re-review P1-1 (defence in depth for the code-gated `begin`): when MFA is already on and
+     * the session is not a re-enroll session, only a pending device that `begin` created behind its
+     * step-up can be confirmed. A pending device carries no proof flag, so the binding is by time:
+     * while MFA is on, `begin` cannot create a pending device without a proof, so the device must be
+     * younger than the pending window ({@link PENDING_DEVICE_MAX_AGE_MS}, the store's self-prune
+     * TTL) and not older than the newest confirmed device. That refuses a device begun while MFA was
+     * still off (e.g. by a stolen session, before the user enrolled) and any stale pending row.
+     *
+     * Outcomes: 401; store/recovery/hasher absent → 501; device not pending/owned, or (MFA on) not
+     * bound to a step-up begin → 404; wrong/expired code → 400 (device stays pending); success →
+     * 200 `{ recoveryCodes? }`.
      */
     async confirmDevice(authorization, body) {
         const claims = await this.requireClaims(authorization);
@@ -547,11 +755,22 @@ let AccountController = class AccountController {
         if (secret === null) {
             throw new common_1.HttpException({ error: 'not_found' }, common_1.HttpStatus.NOT_FOUND);
         }
+        // First-device check BEFORE confirming (so the just-confirmed device isn't counted).
+        const wasFirst = (await store.countConfirmed(claims.id)) === 0;
+        // MFA already on: the pending device must come from a step-up `begin` (see the doc above).
+        if (!wasFirst && claims.mustReenroll !== true) {
+            const all = await store.listAll(claims.id);
+            const pending = all.find((d) => d.id === deviceId && !d.confirmed);
+            const newestConfirmed = Math.max(...all.filter((d) => d.confirmed).map((d) => d.createdAtMs));
+            if (pending === undefined ||
+                Date.now() - pending.createdAtMs > PENDING_DEVICE_MAX_AGE_MS ||
+                pending.createdAtMs < newestConfirmed) {
+                throw new common_1.HttpException({ error: 'not_found' }, common_1.HttpStatus.NOT_FOUND);
+            }
+        }
         // Wrong/expired code → generic 400; the device stays pending (retry or GC later).
         if (!(await this.verifyTotp(secret, code)))
             badRequest();
-        // First-device check BEFORE confirming (so the just-confirmed device isn't counted).
-        const wasFirst = (await store.countConfirmed(claims.id)) === 0;
         const confirmed = await store.confirm(claims.id, deviceId);
         // A race (device removed / already confirmed between load and confirm) → 404.
         if (!confirmed) {
@@ -697,8 +916,9 @@ __decorate([
     (0, common_1.HttpCode)(common_1.HttpStatus.OK),
     __param(0, (0, common_1.Headers)('authorization')),
     __param(1, (0, common_1.Body)()),
+    __param(2, (0, common_1.Res)({ passthrough: true })),
     __metadata("design:type", Function),
-    __metadata("design:paramtypes", [Object, Object]),
+    __metadata("design:paramtypes", [Object, Object, Object]),
     __metadata("design:returntype", Promise)
 ], AccountController.prototype, "updateProfile", null);
 __decorate([
@@ -790,20 +1010,17 @@ exports.AccountController = AccountController = __decorate([
     __param(11, (0, common_1.Inject)(tokens_js_2.SHIELD_MFA_LIMITER)),
     __param(12, (0, common_1.Optional)()),
     __param(12, (0, common_1.Inject)(tokens_js_2.SHIELD_LOGIN_LIMITER)),
-    __metadata("design:paramtypes", [Function, Object, Object, Object, Object, Object, Object, Object, Object, Object, Object, Object, Object])
+    __param(13, (0, common_1.Optional)()),
+    __param(13, (0, common_1.Inject)(tokens_js_2.SHIELD_EMAIL_CHANGE_TOKEN_STORE)),
+    __param(14, (0, common_1.Optional)()),
+    __param(14, (0, common_1.Inject)(tokens_js_2.SHIELD_EMAIL_ADDRESS_CHANGER)),
+    __param(15, (0, common_1.Optional)()),
+    __param(15, (0, common_1.Inject)(tokens_js_2.SHIELD_EMAIL_SENDER)),
+    __param(16, (0, common_1.Optional)()),
+    __param(16, (0, common_1.Inject)(tokens_js_2.SHIELD_EMAIL_CHANGE_LINK_BASE_URL)),
+    __param(17, (0, common_1.Optional)()),
+    __param(17, (0, common_1.Inject)(tokens_js_2.SHIELD_EMAIL_CHANGE_LIMITER)),
+    __param(18, (0, common_1.Optional)()),
+    __param(18, (0, common_1.Inject)(tokens_js_2.SHIELD_AUDIT_SINK)),
+    __metadata("design:paramtypes", [Function, Object, Object, Object, Object, Object, Object, Object, Object, Object, Object, Object, Object, Object, Object, Object, Object, Object, Object])
 ], AccountController);
-/**
- * A deliberately-minimal email shape check (non-empty, a single `@`, a `.` in the
- * domain, no whitespace). This is a self-service edit of the caller's own profile —
- * a full RFC-5322 validator adds no security value here, only false rejections. The
- * authoritative check is delivery; this just catches obvious typos client-adjacent.
- */
-function isEmailShaped(value) {
-    if (/\s/.test(value))
-        return false;
-    const at = value.indexOf('@');
-    if (at <= 0 || at !== value.lastIndexOf('@') || at === value.length - 1)
-        return false;
-    const domain = value.slice(at + 1);
-    return domain.includes('.') && !domain.startsWith('.') && !domain.endsWith('.');
-}

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

@@ -53,6 +53,7 @@
  * composed engines via DI tokens; it never news-up an engine or an adapter.
  */
 import type { Authenticator, PasswordHasher, SessionAuthority } from '@astram/core';
+import type { EmailChangeTokenStore } from './ports/email-change-token-store.js';
 import type { SessionRestrictionStore } from '../session/session-restriction-store.js';
 import type { SessionRecordStore } from '@astram/core';
 import type { Clock, SessionLifetimeConfig } from '@astram/core';
@@ -113,7 +114,8 @@ export declare class AuthController {
     private readonly rootIds?;
     private readonly sessionRecords?;
     private readonly sessionRestrictions?;
-    constructor(authenticator: Authenticator, sessionAuthority: SessionAuthority, pendingMfa: PendingMfaStore, tokenBinder?: SessionTokenBinder | undefined, profileResolver?: ProfileResolver | undefined, credentialResolver?: (CredentialResolver | null) | undefined, resetTokenStore?: (ResetTokenStore | null) | undefined, emailSender?: (EmailSender | null) | undefined, credentialWriter?: (CredentialWriter | null) | undefined, sessionSweeper?: (SessionSweeper | null) | undefined, passwordHasher?: PasswordHasher | undefined, resetLinkBaseUrl?: string | undefined, recoveryCodes?: (RecoveryCodeStore | null) | undefined, loginLimiter?: (AttemptLimiter | null) | undefined, loginIpLimiter?: (AttemptLimiter | null) | undefined, trustProxyCheck?: (TrustProxyBootCheck | null) | undefined, recoveryLimiter?: (AttemptLimiter | null) | undefined, forgotLimiter?: (AttemptLimiter | null) | undefined, forgotHintLimiter?: (AttemptLimiter | null) | undefined, resetLimiter?: (AttemptLimiter | null) | undefined, auditSink?: (AuditSink | null) | undefined, sessionFactsProjector?: (SessionFactsProjector | null) | undefined, scopeSubtreeResolver?: (ScopeSubtreeResolver | null) | undefined, membershipChecker?: (MembershipChecker | null) | undefined, permissionFacts?: (MariaDbPermissionFactsAdapter | null) | undefined, mfaLimiter?: (AttemptLimiter | null) | undefined, mfaStepUp?: (MfaStepUp | null) | undefined, clock?: (Clock | null) | undefined, lifetimes?: (SessionLifetimeConfig | null) | undefined, rootIds?: (readonly string[] | null) | undefined, sessionRecords?: (Pick<SessionRecordStore, "findSessionById"> | null) | undefined, sessionRestrictions?: (SessionRestrictionStore | null) | undefined);
+    private readonly emailChangeTokens?;
+    constructor(authenticator: Authenticator, sessionAuthority: SessionAuthority, pendingMfa: PendingMfaStore, tokenBinder?: SessionTokenBinder | undefined, profileResolver?: ProfileResolver | undefined, credentialResolver?: (CredentialResolver | null) | undefined, resetTokenStore?: (ResetTokenStore | null) | undefined, emailSender?: (EmailSender | null) | undefined, credentialWriter?: (CredentialWriter | null) | undefined, sessionSweeper?: (SessionSweeper | null) | undefined, passwordHasher?: PasswordHasher | undefined, resetLinkBaseUrl?: string | undefined, recoveryCodes?: (RecoveryCodeStore | null) | undefined, loginLimiter?: (AttemptLimiter | null) | undefined, loginIpLimiter?: (AttemptLimiter | null) | undefined, trustProxyCheck?: (TrustProxyBootCheck | null) | undefined, recoveryLimiter?: (AttemptLimiter | null) | undefined, forgotLimiter?: (AttemptLimiter | null) | undefined, forgotHintLimiter?: (AttemptLimiter | null) | undefined, resetLimiter?: (AttemptLimiter | null) | undefined, auditSink?: (AuditSink | null) | undefined, sessionFactsProjector?: (SessionFactsProjector | null) | undefined, scopeSubtreeResolver?: (ScopeSubtreeResolver | null) | undefined, membershipChecker?: (MembershipChecker | null) | undefined, permissionFacts?: (MariaDbPermissionFactsAdapter | null) | undefined, mfaLimiter?: (AttemptLimiter | null) | undefined, mfaStepUp?: (MfaStepUp | null) | undefined, clock?: (Clock | null) | undefined, lifetimes?: (SessionLifetimeConfig | null) | undefined, rootIds?: (readonly string[] | null) | undefined, sessionRecords?: (Pick<SessionRecordStore, "findSessionById"> | null) | undefined, sessionRestrictions?: (SessionRestrictionStore | null) | undefined, emailChangeTokens?: (EmailChangeTokenStore | null) | undefined);
     /**
      * The access-token binding TTL for an establishment (security hardening #8):
      * `clamp(session.expiresAtMs − now, 1, accessTtlMs)` — on login AND refresh. Never derived