@astram/guard 0.1.1 → 0.3.0

package/dist/auth/account.controller.js

@@ -0,0 +1,673 @@
+"use strict";
+/**
+ * The framework-owned **`/account/*` self-scoped HTTP controller** — the
+ * authenticated user acting on THEIR OWN credential/profile (spec §2). Unlike the
+ * `/auth/*` routes (which run BEFORE a session exists), these routes authenticate
+ * the CALLER first — they resolve the bearer access token to the principal's claims
+ * and operate ONLY on `claims.id`. There is NO `decide()`/object-type authorization
+ * here: "change my own password" has no `typeKey` to gate on (that is the later
+ * permission-management milestone). So the routes are `@Public()` to the
+ * classification guard (not object-gated), but NOT unauthenticated.
+ *
+ * ── AUTH (fail-closed) ── the caller is authenticated by resolving the bearer token
+ *   DIRECTLY via the {@link SessionTokenBinder} (`binder.resolve(token)`), NOT via
+ *   `resolveRequestPrincipal` — because change-password needs the caller's
+ *   `sessionId` (to keep the current session alive while sweeping the others), and
+ *   `resolveRequestPrincipal` collapses the claims down to a `Principal` (dropping
+ *   `sessionId`). No token / no binder / resolve → null → generic 401.
+ *
+ * ── SEAMS (fail-closed → 501) ── the credential read+write goes through the
+ *   consumer-plugged {@link CredentialWriter} (`getPasswordHash` + `setPassword`, now
+ *   password-only); the current-password verify uses the {@link PasswordHasher};
+ *   sessions are swept by the {@link SessionSweeper}. The {@link RecoveryCodeStore},
+ *   the core {@link FactorVerifier} (single-secret TOTP, for per-device code checks),
+ *   the {@link ProfileResolver} (otpauth label), and the {@link MfaDeviceStore}
+ *   (the N-device persistence) are injected here for the multi-device MFA routes. Each
+ *   is `@Optional()`; when a required seam is absent the route returns an honest 501
+ *   (`not_available`) rather than a partial mutation.
+ *
+ *   NOTE: TOTP secrets no longer live on the {@link CredentialWriter} — the
+ *   multi-device MFA model stores every authenticator secret in the `MfaDeviceStore`.
+ *   The old single-secret `mfa/enroll/{begin,confirm}` + `mfa/disable` routes were
+ *   removed; the multi-device `/account/mfa/devices/*` routes replace them.
+ *
+ * ── ROUTES ── `POST /account/change-password` (change own password);
+ *   `PATCH /account/profile` (edit own display name/email → the refreshed display
+ *   profile); the multi-device MFA routes — `GET /account/mfa/devices` (list),
+ *   `POST /account/mfa/devices/begin` (enroll), `POST /account/mfa/devices/confirm`
+ *   (activate + first-device recovery codes), `PATCH /account/mfa/devices/:id/rename`,
+ *   `DELETE /account/mfa/devices/:id` (code-gated), `POST
+ *   /account/mfa/recovery-codes/regenerate` (code-gated).
+ *
+ * ── NO ORACLE ── a wrong current password is an indistinguishable generic 401
+ *   (same body as no-token). We never reveal whether the principal exists, nor which
+ *   check failed. Passwords/hashes are NEVER logged.
+ */
+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);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AccountController = void 0;
+const common_1 = require("@nestjs/common");
+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 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;
+/** Minimum acceptable new-password length (the only policy this route enforces). */
+const MIN_PASSWORD_LEN = 8;
+/**
+ * The issuer name embedded in the `otpauth://` provisioning URI (shown in the user's
+ * authenticator app as the account's service). A constant for the framework surface;
+ * a deployment that white-labels can lift this to config later without touching the
+ * enrollment flow.
+ */
+const TOTP_ISSUER = 'Astram';
+/**
+ * The otpauth account label used when the caller's display identity can't be resolved
+ * (no profile resolver, or it returns null). Deliberately a NON-UUID generic string —
+ * the raw principal id must NEVER become the label (it ends up in the URI shown to the
+ * user, and the never-show-UUIDs rule forbids surfacing a `*_uuid`).
+ */
+const FALLBACK_OTPAUTH_LABEL = 'account';
+/**
+ * The SINGLE generic 401 for EVERY unauthenticated/bad-credential path here (no
+ * token, no binder, resolve→null, wrong current password). Deliberately
+ * non-distinguishing — never leaks whether the principal exists or which check
+ * failed.
+ */
+function unauthorized() {
+    throw new common_1.HttpException({ error: 'unauthorized' }, common_1.HttpStatus.UNAUTHORIZED);
+}
+/** The honest 501 when a required seam is unplugged (fail-closed, no mutation). */
+function notAvailable() {
+    throw new common_1.HttpException({ error: 'not_available' }, common_1.HttpStatus.NOT_IMPLEMENTED);
+}
+/**
+ * The generic 400 for a bad MFA request (no pending enrollment / wrong or missing
+ * code). Like {@link unauthorized}, deliberately non-distinguishing — it never
+ * reveals WHICH check failed (no pending vs wrong code), so it is no oracle. No
+ * mutation happens on this path.
+ */
+function badRequest() {
+    throw new common_1.HttpException({ error: 'invalid_request' }, common_1.HttpStatus.BAD_REQUEST);
+}
+/**
+ * The 422 for a semantically invalid profile edit — an empty change (`no_changes`)
+ * or a malformed email (`invalid_email`). Distinct from {@link badRequest}: this is
+ * a self-scoped edit of the caller's OWN profile (no credential oracle to protect),
+ * so a precise field-level reason is safe and helpful for the form.
+ */
+function unprocessable(error) {
+    throw new common_1.HttpException({ error }, common_1.HttpStatus.UNPROCESSABLE_ENTITY);
+}
+let AccountController = class AccountController {
+    binder;
+    hasher;
+    writer;
+    sweeper;
+    recoveryCodes;
+    totpVerifier;
+    profileResolver;
+    profileWriter;
+    mfaDevices;
+    constructor(binder, hasher, writer, sweeper, recoveryCodes, totpVerifier, profileResolver, profileWriter, mfaDevices) {
+        this.binder = binder;
+        this.hasher = hasher;
+        this.writer = writer;
+        this.sweeper = sweeper;
+        this.recoveryCodes = recoveryCodes;
+        this.totpVerifier = totpVerifier;
+        this.profileResolver = profileResolver;
+        this.profileWriter = profileWriter;
+        this.mfaDevices = mfaDevices;
+    }
+    /**
+     * 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
+     * store error → the generic {@link FALLBACK_OTPAUTH_LABEL}. NEVER returns the raw
+     * principal id — the label is shown to the user (in the URI), so a `*_uuid` there
+     * would violate the never-show-UUIDs rule.
+     */
+    async resolveOtpauthLabel(claims) {
+        if (this.profileResolver === undefined || this.profileResolver === null) {
+            return FALLBACK_OTPAUTH_LABEL;
+        }
+        try {
+            const profile = await this.profileResolver.resolve({
+                id: claims.id,
+                tenantId: claims.tenantId,
+                roleIds: [...claims.roleIds],
+                kind: 'user',
+                isRoot: false,
+            });
+            const label = profile?.email ?? profile?.name;
+            return typeof label === 'string' && label.length > 0 ? label : FALLBACK_OTPAUTH_LABEL;
+        }
+        catch {
+            // Fail-soft: a profile-store hiccup must not block enrollment — use the generic
+            // label rather than leak the id or error out.
+            return FALLBACK_OTPAUTH_LABEL;
+        }
+    }
+    /**
+     * Resolve the bearer token → the caller's FULL claims (id + sessionId), or throw a
+     * generic 401. Uses the binder DIRECTLY (not `resolveRequestPrincipal`) so the
+     * `sessionId` survives — change-password needs it to keep the current session.
+     */
+    async requireClaims(authorization) {
+        if (this.binder === undefined || this.binder === null)
+            unauthorized();
+        const token = (0, request_principal_js_1.extractBearerToken)(authorization);
+        if (token === null)
+            unauthorized();
+        const claims = await this.binder.resolve(token);
+        if (claims === null)
+            unauthorized();
+        return claims;
+    }
+    /**
+     * ENFORCED-RE-ENROLL GATE for the self-scoped `/account/*` surface (spec §4.2).
+     *
+     * WHY IT LIVES HERE (not only in the GlobalEnforcementGuard): every `/account/*`
+     * route is `@Public()` to the classification guard (it self-authenticates via
+     * {@link requireClaims}), so the guard's `mustReenroll` gate — which fires only on
+     * `@Classified` routes — NEVER runs on this surface. Without this chokepoint, a
+     * recovery-login (`mustReenroll:true`) session could call the account API DIRECTLY —
+     * e.g. `DELETE /account/mfa/devices/:id` to strip every device + wipe recovery codes
+     * WITHOUT confirming a fresh device — defeating the whole safeguard (spec §4.2:
+     * "calling the API directly cannot bypass it").
+     *
+     * WHY A PER-HANDLER BOOLEAN (not path matching): each handler declares its OWN
+     * re-enroll policy via a literal `allowedDuringReenroll`. This is unambiguous and
+     * cannot be fooled by URL/path normalization — there is no string matching to trick.
+     *
+     * POLICY (spec §4.2 + hardening): a `mustReenroll` session may ADD a device
+     * (`begin`/`confirm`), REGENERATE codes, and READ its devices — but must NOT
+     * REMOVE devices, rename them, change the password, or edit the profile. Removing
+     * devices is the exact attack vector (it strips MFA), so `removeDevice` is BLOCKED.
+     *
+     * 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);
+        }
+    }
+    /**
+     * `POST /account/change-password` — change the AUTHENTICATED caller's own password.
+     * Verifies the current password (read by principal id via the writer seam), writes
+     * the new hash, then revokes the caller's OTHER sessions (keeping the current one
+     * live). Self-scoped: acts only on `claims.id`.
+     *
+     * Outcomes:
+     *   • no/invalid token                       → 401 (generic)
+     *   • newPassword shorter than the minimum   → 422 `{ error: 'weak_password' }`
+     *   • writer/hasher seam absent              → 501 `{ error: 'not_available' }`
+     *   • wrong current password                 → 401 (generic, no write)
+     *   • success                                → 204 (no body)
+     */
+    async changePassword(authorization, body) {
+        const claims = await this.requireClaims(authorization);
+        // BLOCKED during re-enroll: a recovery session must re-secure (add a device) before
+        // it can change the password.
+        this.enforceReenroll(claims, false);
+        const currentPassword = typeof body?.currentPassword === 'string' ? body.currentPassword : '';
+        const newPassword = typeof body?.newPassword === 'string' ? body.newPassword : '';
+        if (newPassword.length < MIN_PASSWORD_LEN) {
+            throw new common_1.HttpException({ error: 'weak_password' }, common_1.HttpStatus.UNPROCESSABLE_ENTITY);
+        }
+        // Fail-closed when the write side or the hasher is unplugged — never a partial
+        // mutation, an honest "not available" instead.
+        if (this.writer === undefined || this.writer === null || this.hasher === undefined) {
+            notAvailable();
+        }
+        const writer = this.writer;
+        const hasher = this.hasher;
+        // Verify the current password: read the stored hash BY PRINCIPAL ID via the writer
+        // seam's `getPasswordHash` (change-password holds the principal id from the token,
+        // whereas CredentialResolver keys by identityHint). A missing hash or a mismatch is
+        // the SAME generic 401 (no oracle), and no write happens.
+        const stored = await writer.getPasswordHash(claims.id);
+        if (stored === null || !(await hasher.verify(stored, currentPassword))) {
+            unauthorized();
+        }
+        const newHash = await hasher.hash(newPassword);
+        await writer.setPassword(claims.id, newHash);
+        // 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);
+        }
+    }
+    /**
+     * Verify a presented TOTP `code` against a base32 `secret` using the injected core
+     * verifier (the SAME RFC-6238 verifier the login MFA branch uses). Returns the
+     * verdict's `satisfied` boolean; a malformed code/secret → `false` (the verifier
+     * never throws). NEVER logs the code or the secret.
+     */
+    async verifyTotp(secret, code) {
+        if (this.totpVerifier === undefined || this.totpVerifier === null)
+            return false;
+        const verdict = await this.totpVerifier.verify({ factor: 'totp', payload: { code } }, secret);
+        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.
+     *
+     * 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)
+     */
+    async updateProfile(authorization, body) {
+        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;
+        // Nothing to update → explicit 422 (rather than a silent no-op re-read).
+        if (name === undefined && email === undefined) {
+            unprocessable('no_changes');
+        }
+        // Basic email shape check when an email is supplied (non-empty already ensured).
+        if (email !== undefined && !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);
+    }
+    // ───────────────────────────────────────────────────────────────────────────
+    // Multi-device MFA — self-scoped device management. Every route
+    // authenticates the caller (bearer → claims.id) and acts ONLY on the caller's
+    // own devices; a device not owned by the caller → 404 (never confirms another
+    // principal's device exists). A device `secret` is NEVER returned except the
+    // freshly-minted one at `begin` (the caller's own, for their QR). The store
+    // (`SHIELD_MFA_DEVICE_STORE`) absent → 501.
+    // ───────────────────────────────────────────────────────────────────────────
+    /**
+     * 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
+     * codes to show the user exactly once. Caller guarantees the recovery store + hasher
+     * are present (checked at the route). NEVER logs the codes or hashes.
+     */
+    async replaceRecoveryCodes(principalId, store, hasher) {
+        const rawCodes = (0, totp_enrollment_js_1.generateRecoveryCodes)();
+        const hashes = await Promise.all(rawCodes.map((c) => hasher.hash(c)));
+        await store.replaceAll(principalId, hashes);
+        return rawCodes;
+    }
+    /**
+     * Verify a presented `code` against ANY of the caller's CONFIRMED device secrets
+     * (TOTP), returning true on the first match. Used by remove/regenerate where the
+     * proof may come from any live device (not a specific one). NEVER logs the code.
+     */
+    async verifyAgainstAnyDevice(store, principalId, code) {
+        const secrets = await store.listConfirmedSecrets(principalId);
+        for (const secret of secrets) {
+            if (await this.verifyTotp(secret, code))
+                return true;
+        }
+        return false;
+    }
+    /**
+     * `GET /account/mfa/devices` — list the caller's CONFIRMED authenticator devices.
+     * `mfaEnabled` reflects whether any confirmed device exists. Pending (unconfirmed)
+     * devices are internal and never surfaced. A device `secret` is never included
+     * (the {@link MfaDevice} display shape omits it).
+     *
+     * Outcomes: no/invalid token → 401; store absent → 501; success → 200
+     * `{ devices: MfaDevice[], mfaEnabled: boolean }`.
+     */
+    async listDevices(authorization) {
+        const claims = await this.requireClaims(authorization);
+        // ALLOWED during re-enroll: the re-enroll screen lists devices to show progress.
+        this.enforceReenroll(claims, true);
+        if (this.mfaDevices === undefined || this.mfaDevices === null)
+            notAvailable();
+        const all = await this.mfaDevices.listAll(claims.id);
+        const devices = all.filter((d) => d.confirmed);
+        return { devices, mfaEnabled: devices.length > 0 };
+    }
+    /**
+     * `POST /account/mfa/devices/begin` — start enrolling a NEW authenticator device.
+     * Mints a fresh secret, creates a PENDING device row, and returns the provisioning
+     * 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 }`.
+     */
+    async beginDevice(authorization, body) {
+        const claims = await this.requireClaims(authorization);
+        // ALLOWED during re-enroll: adding a fresh device is the whole point of re-enroll.
+        this.enforceReenroll(claims, true);
+        if (this.mfaDevices === undefined || this.mfaDevices === null)
+            notAvailable();
+        const store = this.mfaDevices;
+        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}`;
+        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);
+        return { deviceId, otpauthUri, secret };
+    }
+    /**
+     * `POST /account/mfa/devices/confirm` — activate a pending device by proving a live
+     * code from it. Loads THAT device's secret (owned + still pending), verifies the
+     * code, and confirms. If this is the caller's FIRST confirmed device, fresh recovery
+     * 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? }`.
+     */
+    async confirmDevice(authorization, body) {
+        const claims = await this.requireClaims(authorization);
+        // ALLOWED during re-enroll: confirming a fresh device is the action that RE-SECURES
+        // the account — and (below) the SOLE action that clears the re-enroll restriction.
+        this.enforceReenroll(claims, true);
+        if (this.mfaDevices === undefined ||
+            this.mfaDevices === null ||
+            this.recoveryCodes === undefined ||
+            this.recoveryCodes === null ||
+            this.hasher === undefined) {
+            notAvailable();
+        }
+        const store = this.mfaDevices;
+        const recoveryStore = this.recoveryCodes;
+        const hasher = this.hasher;
+        const deviceId = typeof body?.deviceId === 'string' ? body.deviceId : '';
+        const code = typeof body?.code === 'string' ? body.code : '';
+        // Load the pending device's OWN secret (owned by the caller) — else 404. The secret
+        // never leaves the server; it is only used to check the presented code here.
+        const secret = await store.getSecret(claims.id, deviceId);
+        if (secret === null) {
+            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) {
+            throw new common_1.HttpException({ error: 'not_found' }, common_1.HttpStatus.NOT_FOUND);
+        }
+        // ENFORCED-RE-ENROLL CLEAR (spec §4.3): confirming a fresh device is the SOLE
+        // action that lifts a recovery-login session's re-enroll restriction. If this
+        // caller's session is marked `mustReenroll`, clear the bound claim so its very next
+        // request is unrestricted (the access token is NOT re-minted — only the claim
+        // flips). Best-effort: a clear failure just means the user re-confirms/retries. The
+        // binder is present under `auth: true` (it authenticated `requireClaims` above);
+        // guarded for wiring resilience. Regenerate-codes deliberately does NOT clear.
+        if (claims.mustReenroll === true && this.binder !== undefined && this.binder !== null) {
+            await this.binder.clearReenroll(claims.sessionId);
+        }
+        if (wasFirst) {
+            const recoveryCodes = await this.replaceRecoveryCodes(claims.id, recoveryStore, hasher);
+            return { recoveryCodes };
+        }
+        // Subsequent devices never mint / wipe recovery codes.
+        return {};
+    }
+    /**
+     * `PATCH /account/mfa/devices/:id/rename` — rename one of the caller's devices.
+     * Cosmetic (renaming a label doesn't weaken 2FA), so it is session-auth only (no
+     * code required), consistent with profile-edit. Trimmed empty name → 422.
+     *
+     * Outcomes: 401; store absent → 501; blank name → 422; not found/owned → 404;
+     * success → 200 `{ device }`.
+     */
+    async renameDevice(authorization, id, body) {
+        const claims = await this.requireClaims(authorization);
+        // BLOCKED during re-enroll: renaming is not part of re-securing the account.
+        this.enforceReenroll(claims, false);
+        if (this.mfaDevices === undefined || this.mfaDevices === null)
+            notAvailable();
+        const store = this.mfaDevices;
+        const name = typeof body?.name === 'string' ? body.name.trim() : '';
+        if (name.length === 0)
+            unprocessable('invalid_name');
+        const device = await store.rename(claims.id, id, name.slice(0, MAX_DEVICE_NAME_LEN));
+        if (device === null) {
+            throw new common_1.HttpException({ error: 'not_found' }, common_1.HttpStatus.NOT_FOUND);
+        }
+        return { device };
+    }
+    /**
+     * `DELETE /account/mfa/devices/:id` — remove one of the caller's devices. Requires
+     * proof: a live TOTP code from ANY of the caller's remaining confirmed devices, OR a
+     * recovery code — so a hijacked live session can't silently strip MFA. Removing the
+     * LAST device is the "disable MFA" path (authorized by that last device's own code)
+     * and additionally wipes the account's recovery codes.
+     *
+     * Outcomes: 401; store absent → 501; wrong code → 400 (no remove); not found/owned →
+     * 404; success → 204.
+     */
+    async removeDevice(authorization, id, body) {
+        const claims = await this.requireClaims(authorization);
+        // BLOCKED during re-enroll (THE exploit the safeguard exists to stop): a recovery
+        // session must NOT be able to strip devices / disable MFA before re-securing. It
+        // must add + confirm a fresh device first (which clears the flag), THEN it may
+        // remove devices.
+        this.enforceReenroll(claims, false);
+        if (this.mfaDevices === undefined || this.mfaDevices === null)
+            notAvailable();
+        const store = this.mfaDevices;
+        const code = typeof body?.code === 'string' ? body.code : '';
+        // 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.
+        const byTotp = await this.verifyAgainstAnyDevice(store, claims.id, code);
+        const byRecovery = !byTotp &&
+            this.recoveryCodes !== undefined &&
+            this.recoveryCodes !== null &&
+            (await this.recoveryCodes.consume(claims.id, code));
+        if (!byTotp && !byRecovery)
+            badRequest();
+        const removed = await store.remove(claims.id, id);
+        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) {
+            if (this.recoveryCodes !== undefined && this.recoveryCodes !== null) {
+                await this.recoveryCodes.replaceAll(claims.id, []);
+            }
+        }
+    }
+    /**
+     * `POST /account/mfa/recovery-codes/regenerate` — mint a fresh recovery-code batch
+     * (replacing the old set). Requires MFA to be enabled (≥1 confirmed device) and proof
+     * — a TOTP from any confirmed device OR an existing recovery code.
+     *
+     * Outcomes: 401; store/recovery/hasher absent → 501; MFA off → 400; wrong code → 400;
+     * success → 200 `{ recoveryCodes }`.
+     */
+    async regenerateRecoveryCodes(authorization, body) {
+        const claims = await this.requireClaims(authorization);
+        // ALLOWED during re-enroll: the user may refresh recovery codes while re-securing.
+        // (Allowed ≠ gate-clearing, spec §4.3: regenerating codes does NOT lift the
+        // restriction — only confirming a fresh device does.)
+        this.enforceReenroll(claims, true);
+        if (this.mfaDevices === undefined ||
+            this.mfaDevices === null ||
+            this.recoveryCodes === undefined ||
+            this.recoveryCodes === null ||
+            this.hasher === undefined) {
+            notAvailable();
+        }
+        const store = this.mfaDevices;
+        const recoveryStore = this.recoveryCodes;
+        const hasher = this.hasher;
+        const code = typeof body?.code === 'string' ? body.code : '';
+        // MFA must be on — else there's nothing to protect / no code source → generic 400.
+        if ((await store.countConfirmed(claims.id)) === 0)
+            badRequest();
+        // Proof: a TOTP from any confirmed device OR an existing recovery code.
+        const byTotp = await this.verifyAgainstAnyDevice(store, claims.id, code);
+        const byRecovery = !byTotp && (await recoveryStore.consume(claims.id, code));
+        if (!byTotp && !byRecovery)
+            badRequest();
+        const recoveryCodes = await this.replaceRecoveryCodes(claims.id, recoveryStore, hasher);
+        return { recoveryCodes };
+    }
+};
+exports.AccountController = AccountController;
+__decorate([
+    (0, classification_decorator_js_1.Public)(),
+    (0, common_1.Post)('change-password'),
+    (0, common_1.HttpCode)(common_1.HttpStatus.NO_CONTENT),
+    __param(0, (0, common_1.Headers)('authorization')),
+    __param(1, (0, common_1.Body)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object]),
+    __metadata("design:returntype", Promise)
+], AccountController.prototype, "changePassword", null);
+__decorate([
+    (0, classification_decorator_js_1.Public)(),
+    (0, common_1.Patch)('profile'),
+    (0, common_1.HttpCode)(common_1.HttpStatus.OK),
+    __param(0, (0, common_1.Headers)('authorization')),
+    __param(1, (0, common_1.Body)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object]),
+    __metadata("design:returntype", Promise)
+], AccountController.prototype, "updateProfile", null);
+__decorate([
+    (0, classification_decorator_js_1.Public)(),
+    (0, common_1.Get)('mfa/devices'),
+    (0, common_1.HttpCode)(common_1.HttpStatus.OK),
+    __param(0, (0, common_1.Headers)('authorization')),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], AccountController.prototype, "listDevices", null);
+__decorate([
+    (0, classification_decorator_js_1.Public)(),
+    (0, common_1.Post)('mfa/devices/begin'),
+    (0, common_1.HttpCode)(common_1.HttpStatus.OK),
+    __param(0, (0, common_1.Headers)('authorization')),
+    __param(1, (0, common_1.Body)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object]),
+    __metadata("design:returntype", Promise)
+], AccountController.prototype, "beginDevice", null);
+__decorate([
+    (0, classification_decorator_js_1.Public)(),
+    (0, common_1.Post)('mfa/devices/confirm'),
+    (0, common_1.HttpCode)(common_1.HttpStatus.OK),
+    __param(0, (0, common_1.Headers)('authorization')),
+    __param(1, (0, common_1.Body)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object]),
+    __metadata("design:returntype", Promise)
+], AccountController.prototype, "confirmDevice", null);
+__decorate([
+    (0, classification_decorator_js_1.Public)(),
+    (0, common_1.Patch)('mfa/devices/:id/rename'),
+    (0, common_1.HttpCode)(common_1.HttpStatus.OK),
+    __param(0, (0, common_1.Headers)('authorization')),
+    __param(1, (0, common_1.Param)('id')),
+    __param(2, (0, common_1.Body)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, String, Object]),
+    __metadata("design:returntype", Promise)
+], AccountController.prototype, "renameDevice", null);
+__decorate([
+    (0, classification_decorator_js_1.Public)(),
+    (0, common_1.Delete)('mfa/devices/:id'),
+    (0, common_1.HttpCode)(common_1.HttpStatus.NO_CONTENT),
+    __param(0, (0, common_1.Headers)('authorization')),
+    __param(1, (0, common_1.Param)('id')),
+    __param(2, (0, common_1.Body)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, String, Object]),
+    __metadata("design:returntype", Promise)
+], AccountController.prototype, "removeDevice", null);
+__decorate([
+    (0, classification_decorator_js_1.Public)(),
+    (0, common_1.Post)('mfa/recovery-codes/regenerate'),
+    (0, common_1.HttpCode)(common_1.HttpStatus.OK),
+    __param(0, (0, common_1.Headers)('authorization')),
+    __param(1, (0, common_1.Body)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object]),
+    __metadata("design:returntype", Promise)
+], AccountController.prototype, "regenerateRecoveryCodes", null);
+exports.AccountController = AccountController = __decorate([
+    (0, common_1.Controller)('account'),
+    __param(0, (0, common_1.Optional)()),
+    __param(0, (0, common_1.Inject)(tokens_js_1.SHIELD_SESSION_TOKEN_BINDER)),
+    __param(1, (0, common_1.Optional)()),
+    __param(1, (0, common_1.Inject)(tokens_js_2.SHIELD_PASSWORD_HASHER)),
+    __param(2, (0, common_1.Optional)()),
+    __param(2, (0, common_1.Inject)(tokens_js_2.SHIELD_CREDENTIAL_WRITER)),
+    __param(3, (0, common_1.Optional)()),
+    __param(3, (0, common_1.Inject)(tokens_js_2.SHIELD_SESSION_SWEEPER)),
+    __param(4, (0, common_1.Optional)()),
+    __param(4, (0, common_1.Inject)(tokens_js_2.SHIELD_RECOVERY_CODE_STORE)),
+    __param(5, (0, common_1.Optional)()),
+    __param(5, (0, common_1.Inject)(tokens_js_2.SHIELD_TOTP_VERIFIER)),
+    __param(6, (0, common_1.Optional)()),
+    __param(6, (0, common_1.Inject)(tokens_js_2.SHIELD_PROFILE_RESOLVER)),
+    __param(7, (0, common_1.Optional)()),
+    __param(7, (0, common_1.Inject)(tokens_js_2.SHIELD_PROFILE_WRITER)),
+    __param(8, (0, common_1.Optional)()),
+    __param(8, (0, common_1.Inject)(tokens_js_2.SHIELD_MFA_DEVICE_STORE)),
+    __metadata("design:paramtypes", [Function, 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('.');
+}