@aooth/auth-moost 0.1.8 → 0.1.9

package/dist/index.mjs

@@ -1,16 +1,16 @@
-import { a as EmailIdentifierForm, b as SignupForm, c as EnrollPickMethodForm, f as MfaCodeForm, h as ProveControlOtpForm, i as ConcurrencyLimitForm, l as InviteForm, m as ProveControlForm, n as AskPhoneForm, o as EnrollAddressForm, p as PincodeForm, r as ChangePasswordForm, s as EnrollConfirmForm, t as AskEmailForm, u as LoginCredentialsForm, v as Select2faForm, x as TermsBumpForm, y as SetPasswordForm } from "./forms-Bkr7ECKu.mjs";
+import { C as SetPasswordForm, S as Select2faForm, T as TermsBumpForm, _ as ProveControlForm, a as EmailIdentifierForm, c as EnrollPickMethodForm, d as LoginCredentialsForm, g as PincodeForm, h as PasswordReauthForm, i as ConcurrencyLimitForm, l as EnrollTotpQrForm, m as MfaCodeForm, n as AskPhoneForm, o as EnrollAddressForm, p as ManageMfaForm, r as ChangePasswordForm, s as EnrollConfirmForm, t as AskEmailForm, u as InviteForm, v as ProveControlOtpForm, w as SignupForm, x as RemoveMfaConfirmForm } from "./forms-DV4UcC29.mjs";
 import { Controller, HandlerPaths, Inherit, Inject, InjectMoostLogger, Injectable, Intercept, MoostInit, Optional, Param, Resolve, TInterceptorPriority, defineAfterInterceptor, defineBeforeInterceptor, getMoostMate, useControllerContext } from "moost";
 import { AuthCredential, AuthError, generateMagicLinkToken } from "@aooth/auth";
 import { current, defineWook, eventTypeKey, key } from "@wooksjs/event-core";
 import { HttpError, useAuthorization, useCookies, useHeaders, useRequest, useResponse, useUrlParams } from "@wooksjs/event-http";
 import { ArbacAction, ArbacResource, getArbacMate } from "@aooth/arbac-moost";
-import { FederatedIdentityStore, UserAuthError, UserService, generateTotpSecret, generateTotpUri, maskEmail, maskPhone, pickDefinedProfile } from "@aooth/user";
+import { FederatedIdentityStore, UserAuthError, UserService, generateTotpSecret, generateTotpUri, maskEmail, maskPhone, pickDefinedProfile, verifyTotpCode } from "@aooth/user";
 import { Body, Delete, Get, HttpError as HttpError$1, Post, Query } from "@moostjs/event-http";
 import { createHash, timingSafeEqual } from "node:crypto";
 import { createAsHttpOutlet, finishWf, handleAsOutletRequest, useAtscriptWf } from "@atscript/moost-wf";
 import { EncapsulatedStateStrategy, MoostWf, Step, StepRetriableError, StepTTL, Workflow, WorkflowParam, WorkflowSchema, createEmailOutlet, outletEmail, swapStrategy, useWfFinished, useWfState } from "@moostjs/event-wf";
 import { FederatedLoginService, OAuthError, OAuthProviderRegistry, generateRandomState, pkceChallengeFor } from "@aooth/idp";
-import { AuthorizeError } from "@aooth/auth/authz";
+import { AuthorizeError, NoopOidcClaimsResolver } from "@aooth/auth/authz";
 //#region \0@oxc-project+runtime@0.133.0/helpers/esm/decorate.js
 function __decorate(decorators, target, key, desc) {
 	var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
@@ -651,7 +651,8 @@ const AUTH_CODE_STORE_TOKEN = "aooth:AuthCodeStore";
 /**
 * DI token for the {@link import("@aooth/auth/authz").ClientRedirectPolicy} — an
 * interface, so it has no class reference to inject by. Provide the concrete
-* policy (e.g. `new LoopbackClientPolicy()`) under this string.
+* policy (e.g. `new LoopbackClientPolicy()`, a `RegisteredClientPolicy`, or a
+* `CompositeClientPolicy` of both) under this string.
 */
 const CLIENT_REDIRECT_POLICY_TOKEN = "aooth:ClientRedirectPolicy";
 //#endregion
@@ -702,7 +703,10 @@ OAuthRuntime = __decorate([Injectable(), __decorateMetadata("design:paramtypes",
 const pincodeSendCheckPair = [{
 	id: "pincode-send",
 	condition: (ctx) => !ctx.pin
-}, { id: "pincode-check" }];
+}, {
+	id: "pincode-check",
+	condition: (ctx) => !ctx.aborted
+}];
 /**
 * Shared MFA loop — challenge OR enrol. Used by login.flow + invite.start.
 * Loop exits when `ctx.otp.verified` flips true — set by ANY of: pincode-check (SMS/email challenge),
@@ -728,11 +732,65 @@ const enrollTrioSteps = [
 		id: "enroll-address",
 		condition: (ctx) => !!ctx.mfaEnroll?.method && (ctx.mfaEnroll.method === "sms" || ctx.mfaEnroll.method === "email") && !ctx.mfaEnroll.address
 	},
+	{
+		id: "enroll-totp-qr",
+		condition: (ctx) => ctx.mfaEnroll?.method === "totp" && !ctx.mfaEnroll.qrSeen
+	},
 	{
 		id: "enroll-confirm",
-		condition: (ctx) => !!ctx.mfaEnroll?.method && (ctx.mfaEnroll.method === "totp" || !!ctx.mfaEnroll.address) && !ctx.mfaEnroll.done
+		condition: (ctx) => !!ctx.mfaEnroll?.method && (ctx.mfaEnroll.method === "totp" ? !!ctx.mfaEnroll.qrSeen : !!ctx.mfaEnroll.address) && !ctx.mfaEnroll.done
+	},
+	{
+		id: "promote-to-handle",
+		condition: (ctx) => !!ctx.mfaEnroll?.done && !ctx.promoteToHandleDone
 	}
 ];
+/**
+* MFA step-up loop — challenge an EXISTING confirmed factor (no enrolment).
+* Reuses the login challenge steps verbatim, but DELIBERATELY omits
+* `check-trusted-device` and `risk-step-up`: in a management context a trusted
+* device must NOT be allowed to bypass the step-up (that is the whole point of
+* re-verifying before letting the user change/remove a factor). Loop exits when
+* a challenge step flips `ctx.otp.verified`. Used by the standalone add/manage-
+* MFA flow, guarded by `ctx.addMfa.stepUpRequired` (set only when the user has
+* ≥1 confirmed method).
+*
+* The `while` also breaks on `ctx.aborted` so a cancel/exit on the challenge
+* form (e.g. `pincode-check`'s `exit` alt-action, or a customer-added Back on
+* the MFA challenge) terminates the loop instead of spinning the engine's
+* guardless inner loop forever. The paired `{ break: !!aborted }` after this
+* sub-schema in `addMfaFlow` then routes an aborted step-up straight to
+* `finish-add-mfa` (the cancelled terminal) — fail CLOSED: the user reaches no
+* management write without a fresh challenge. (Note: login's `mfaLoopSchema`
+* intentionally does NOT carry this guard — exiting login's challenge loop
+* without a paired failure terminal would risk issuing a session, so that one
+* stays fail-closed via the engine's no-progress stall instead.)
+*/
+const mfaStepUpLoop = [{
+	while: (ctx) => !ctx.otp?.verified && !ctx.aborted,
+	steps: [
+		{
+			id: "load-enrolled-mfa-methods",
+			condition: (ctx) => !ctx.otp?.verified
+		},
+		{
+			id: "select-mfa-method",
+			condition: (ctx) => !ctx.otp?.verified
+		},
+		{
+			id: "select-2fa",
+			condition: (ctx) => !ctx.otp?.verified && !ctx.mfa?.method && (ctx.mfa?.enrolledMethods?.length ?? 0) > 1
+		},
+		{
+			condition: (ctx) => !ctx.otp?.verified && (ctx.mfa?.method === "sms" || ctx.mfa?.method === "email"),
+			steps: pincodeSendCheckPair
+		},
+		{
+			id: "totp-check",
+			condition: (ctx) => !ctx.otp?.verified && ctx.mfa?.method === "totp"
+		}
+	]
+}];
 const mfaLoopSchema = [{ id: "prepare-mfa" }, {
 	while: (ctx) => ctx.mfaPolicy?.mode !== "disabled" && !ctx.otp?.verified,
 	steps: [
@@ -826,7 +884,11 @@ const DEFAULT_FORMS = {
 	askPhone: AskPhoneForm,
 	enrollPickMethod: EnrollPickMethodForm,
 	enrollAddress: EnrollAddressForm,
+	enrollTotpQr: EnrollTotpQrForm,
 	enrollConfirm: EnrollConfirmForm,
+	manageMfa: ManageMfaForm,
+	removeMfaConfirm: RemoveMfaConfirmForm,
+	passwordReauth: PasswordReauthForm,
 	select2fa: Select2faForm,
 	mfaCode: MfaCodeForm,
 	pincode: PincodeForm,
@@ -996,6 +1058,17 @@ function pickDefined(src, keys) {
 	}
 	return any ? out : void 0;
 }
+/**
+* Thrown by `recoveryPincodeTarget`'s registered (M2) branch when the confirmed
+* recovery method that `request`'s guard saw has VANISHED before send time
+* (deleted between the two row loads — the request→send TOCTOU). `pincode-send`
+* catches it and degrades to the generic anti-enumeration finish instead of
+* surfacing a distinguishable 500, so a known account can never become
+* distinguishable from an unknown one on a resend. Recovery-only; the MFA
+* challenge branch keeps its own `HttpError(500)` (that path is post-password,
+* so enumeration is moot there).
+*/
+var RecoveryMethodUnavailableError = class extends Error {};
 let AuthWorkflow = class AuthWorkflow {
 	opts;
 	users;
@@ -1288,6 +1361,30 @@ let AuthWorkflow = class AuthWorkflow {
 		};
 	}
 	/**
+	* Transports the user may NOT change or remove via the manage-MFA flow.
+	* Default: none — every factor is freely manageable. Reached from
+	* `auth/add-mfa/flow` (`prepare-locked-mfa-transports`).
+	*
+	* Override to forbid changing a factor whose value IS a login handle — e.g.
+	* the MFA `email` equals the `@aooth.user.email` handle, so letting the user
+	* swap it here would desync identity. A typical override loads the user and
+	* compares each enrolled channel value against the boot-resolved handle
+	* fields (`getAoothUserHandleSpec(...).emailField` / `.phoneField`):
+	*
+	* ```ts
+	* protected async resolveLockedMfaTransports(ctx: AuthWfCtx): Promise<MfaTransport[]> {
+	*   const user = await this.users.getUser(ctx.subject!);
+	*   const locked: MfaTransport[] = [];
+	*   const email = user.mfa?.methods?.find((m) => m.name === "email" && m.confirmed);
+	*   if (email && email.value === (user as { email?: string }).email) locked.push("email");
+	*   return locked;
+	* }
+	* ```
+	*/
+	resolveLockedMfaTransports(_ctx) {
+		return [];
+	}
+	/**
 	* Resolve the channel-OTP disclosure copy rendered beneath the email/phone
 	* input on `AskEmailForm` / `AskPhoneForm`. Reached from login.flow Phase 3.
 	* Default returns a TCPA / PECR / CASL / GDPR-safe English paragraph that is
@@ -1386,12 +1483,114 @@ let AuthWorkflow = class AuthWorkflow {
 				};
 			});
 		}
-		return {
-			address: ctx.email ?? "",
-			channel: "email"
+		const sourceResult = this.resolveRecoveryDeliverySource(ctx);
+		if (sourceResult instanceof Promise) return sourceResult.then((source) => this.recoveryPincodeTarget(ctx, source));
+		return this.recoveryPincodeTarget(ctx, sourceResult);
+	}
+	/**
+	* Resolve the recovery OTP `{ address, channel }` for the chosen delivery
+	* `source`.
+	*
+	* - `"typed"` (M1): the address is the typed recovery identifier (`ctx.email`)
+	*   — identifier == destination, so no cross-account redirect — and the
+	*   channel comes from `resolveRecoveryChannel` (identifier-shape inference).
+	* - `"registered"` (M2): the address is read off a confirmed MFA method on the
+	*   row (`selectRecoveryRegisteredMethod`) and the channel is that method's own
+	*   kind. The user only typed an account identifier; the destination is a
+	*   pre-verified channel they already control, so this also can't redirect
+	*   cross-account. `request`'s M2 guard normally generic-finishes any row with
+	*   no deliverable method up front; if the method is deleted in the narrow
+	*   window between that guard and this send (e.g. on a resend), this throws
+	*   `RecoveryMethodUnavailableError`, which `pincode-send` degrades to the
+	*   same generic finish — never a distinguishable 500.
+	*/
+	recoveryPincodeTarget(ctx, source) {
+		if (source === "registered") {
+			this.requireSubject(ctx);
+			return this.users.getUser(ctx.subject).then((user) => {
+				const method = this.selectRecoveryRegisteredMethod(user);
+				const channel = method && this.mfaKindOf(method.name);
+				if (!method || channel !== "sms" && channel !== "email") throw new RecoveryMethodUnavailableError();
+				return {
+					address: method.value,
+					channel
+				};
+			});
+		}
+		const address = ctx.email ?? "";
+		const channel = this.resolveRecoveryChannel(ctx);
+		return channel instanceof Promise ? channel.then((c) => ({
+			address,
+			channel: c
+		})) : {
+			address,
+			channel
 		};
 	}
 	/**
+	* Recovery OTP delivery channel. The address is ALWAYS the typed recovery
+	* identifier (`ctx.email`) — symmetric with how email recovery already works:
+	* the OTP goes to the value the user typed, which is the handle that resolved
+	* the account (`findByHandle`), so identifier == destination and there is no
+	* cross-account redirect. Default `"email"`. A deployment whose recovery form
+	* accepts a phone overrides this to route SMS (e.g. infer from the identifier
+	* shape) — see the demo's `DemoAuthWorkflow`. Recovery picks ONE channel per
+	* run, so the single `resendAllowedAt` cooldown gate still suffices.
+	*/
+	resolveRecoveryChannel(_ctx) {
+		return "email";
+	}
+	/**
+	* Recovery OTP delivery model. Two options:
+	*
+	* - `"typed"` (default — M1): the OTP goes to the recovery identifier the user
+	*   types. Identifier == destination, so there is no cross-account redirect;
+	*   `resolveRecoveryChannel` picks email vs SMS from the identifier shape.
+	* - `"registered"` (M2): the user enters only an account identifier (e.g. a
+	*   username) and the OTP is delivered to a channel **already verified on the
+	*   row** — `selectRecoveryRegisteredMethod` picks the confirmed MFA method;
+	*   the destination is never taken from user input, so it cannot be redirected
+	*   to an attacker-controlled address. A row with no deliverable confirmed
+	*   method finishes with the generic anti-enumeration envelope (see `request`).
+	*
+	* Consulted inline by `request` (no-method guard) and `recoveryPincodeTarget`
+	* — no `prepare-*` step, mirroring `resolveRecoveryChannel`. Override to arm
+	* M2 (per-tenant / per-variant); see the demo's `DemoAuthWorkflow`.
+	*/
+	resolveRecoveryDeliverySource(_ctx) {
+		return "typed";
+	}
+	/**
+	* Pick the confirmed MFA method a registered-channel recovery (M2) delivers
+	* its OTP to. Prefers a confirmed SMS method, then a confirmed email method —
+	* phone-recovery-first. TOTP carries no deliverable address and is skipped.
+	* Returns `null` when the row has no deliverable confirmed method; the caller
+	* turns that into the anti-enumeration generic finish. Stays sync (operates on
+	* an already-loaded row); override to change the selection policy (e.g. honour
+	* the user's `mfa.defaultMethod`).
+	*/
+	selectRecoveryRegisteredMethod(user) {
+		const methods = user.mfa?.methods ?? [];
+		const pick = (kind) => methods.find((m) => m.confirmed && !!m.value && this.mfaKindOf(m.name) === kind);
+		return pick("sms") ?? pick("email") ?? null;
+	}
+	/**
+	* Decide which login-handle column a freshly-confirmed channel should be
+	* promoted into — so a verified email/phone becomes a login + recovery
+	* handle (`findByHandle`) automatically. Returns the target field name, or
+	* `undefined` to NOT promote (the default).
+	*
+	* Default is OFF: the handle columns are declared via `@aooth.user.*`
+	* annotations on the consumer's concrete model and resolved ONCE at boot
+	* (`@aooth/arbac-moost`'s `getAoothUserHandleSpec`) — `AuthWorkflow` holds no
+	* handle to that model and stays off the per-request reflection path. A
+	* deployment turns promotion ON by overriding this to return the
+	* boot-resolved `emailField` / `phoneField` for the channel — see the demo's
+	* `DemoAuthWorkflow`. `channel` is the wire protocol (`'email'` | `'sms'`),
+	* matching `resolveOtpDisclosure` / the MFA transport.
+	*/
+	resolvePromoteHandleField(_ctx, _channel) {}
+	/**
 	* Route a form alt-action click to a canonical outcome. Defaults match the
 	* action ids the bundled `PincodeForm` declares; customers override per
 	* form when adding new actions or remapping the canonical ones.
@@ -1482,6 +1681,10 @@ let AuthWorkflow = class AuthWorkflow {
 			]);
 			if (sub) pub.mfaEnroll = sub;
 		}
+		if (ctx.addMfa) {
+			const sub = pickDefined(ctx.addMfa, ["candidates", "locked"]);
+			if (sub) pub.manage = sub;
+		}
 		if (ctx.defaults) {
 			const sub = pickDefined(ctx.defaults, ["email"]);
 			if (sub) pub.defaults = sub;
@@ -1619,25 +1822,104 @@ let AuthWorkflow = class AuthWorkflow {
 		});
 	}
 	/**
-	* Cleanup any partially-persisted enrolment state (unconfirmed method row +
-	* ctx scratch). Called when the user picks `skip` or `useDifferentMethod`
-	* mid-flow on `enrollConfirm`, where the unconfirmed method has already
-	* been written via `addMfaMethod` (in `enrollPickMethod` for totp /
-	* `enrollAddress` for sms+email).
+	* Drop the per-enrolment scratch fields (the `mfaEnroll` provisioning fields +
+	* the pincode timers/`sentTo`) off ctx — the shared teardown used by the
+	* opt-in `skip` / `useDifferentMethod` arms and {@link cancelManageEnrollment}.
+	* Does NOT touch the user record: the enrol trio stages every candidate value
+	* (sms/email address, totp secret) in wf-state and writes it to the store ONLY
+	* on confirm (write-on-confirm), so a bailed enrolment never persisted a
+	* partial row to undo.
 	*/
-	async cleanupEnrollment(ctx, username) {
+	clearEnrollScratch(ctx) {
 		const m = ctx.mfaEnroll;
 		if (m) {
-			if (m.method) await this.withStoreErrorTranslation(() => this.users.removeMfaMethod(username, m.method));
 			delete m.method;
 			delete m.address;
 			delete m.secret;
 			delete m.uri;
+			delete m.qrSeen;
 		}
 		delete ctx.pin;
 		delete ctx.pinExpire;
 		if (ctx.pincode) delete ctx.pincode.sentTo;
 	}
+	/**
+	* Validate a user-typed MFA address for its transport. Server-side counterpart
+	* to `EnrollAddressForm`'s client `@ui.form.validate` hint — the authoritative
+	* check (a client can bypass the hint). Returns an error string for the form,
+	* or `undefined` when valid. Email must look like an email; SMS is permissive
+	* E.164-ish (normalized by {@link normalizeMfaAddress}). Override for stricter
+	* (e.g. libphonenumber) validation.
+	*/
+	validateMfaAddress(method, value) {
+		const v = (value ?? "").trim();
+		if (!v) return "This field is required";
+		if (method === "email") return /^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(v) ? void 0 : "Enter a valid email address";
+		if (method === "sms") {
+			const digits = v.replace(/[\s()+.-]/g, "");
+			return /^[1-9]\d{6,14}$/.test(digits) ? void 0 : "Enter a valid phone number";
+		}
+	}
+	/**
+	* Light normalization of a validated MFA address before it is stored. Default:
+	* trims, and strips spacing/punctuation from SMS numbers while KEEPING the
+	* leading `+` (E.164 canonical form). Email is just trimmed. Override for full
+	* E.164 canonicalization.
+	*/
+	normalizeMfaAddress(method, value) {
+		const v = value.trim();
+		return method === "sms" ? v.replace(/[\s().-]/g, "") : v;
+	}
+	/**
+	* Abort an in-progress manage-MFA enrolment cleanly: drop the wf-state scratch
+	* and set `ctx.aborted` so the schema breaks to `finish-add-mfa` (cancelled
+	* terminal). Nothing to undo in the user record — the manage flow stages every
+	* candidate value (sms/email address, totp secret) in wf-state and writes it
+	* to the store ONLY on confirm (write-on-confirm), so an in-progress
+	* add/change/replace never touched the existing factors. This is exactly why
+	* a cancel — or a crafted `useDifferentMethod` routed here — can never strand
+	* or clobber a live factor.
+	*/
+	cancelManageEnrollment(ctx) {
+		this.clearEnrollScratch(ctx);
+		ctx.aborted = true;
+	}
+	/**
+	* Shared skip / cancel / useDifferentMethod triage for the enrol-trio steps
+	* that pause after the candidate value is staged (`enroll-totp-qr` +
+	* `enroll-confirm`): `cancel` / `useDifferentMethod` (manage) abort the flow,
+	* `skip` (opt-in) and `useDifferentMethod` (opt-in) drop the wf-state scratch.
+	* Returns `true` when the action terminated the step so the caller can
+	* `return undefined`. (`enroll-pick-method` / `enroll-address` keep their own
+	* preludes — their skip/useDifferentMethod arms diverge from this one.)
+	*
+	* SECURITY: in `'manage'` mode BOTH `cancel` and `useDifferentMethod` (the
+	* manage forms HIDE the latter but it stays in their declared action
+	* whitelist, so a crafted resume can still send it) route through the abort,
+	* which only clears scratch. Because the enrol trio writes the user record
+	* ONLY on confirm (write-on-confirm), an in-progress add/change has touched
+	* nothing in the store — so a cancel/useDifferentMethod can never strand or
+	* clobber the user's live factor, by construction.
+	*/
+	handleEnrollExit(ctx, action) {
+		const m = ctx.mfaEnroll ??= {};
+		const mode = m.mode ?? "optional";
+		if (mode === "manage" && (action === "cancel" || action === "useDifferentMethod")) {
+			this.cancelManageEnrollment(ctx);
+			return true;
+		}
+		if (mode === "optional" && action === "skip") {
+			this.clearEnrollScratch(ctx);
+			m.done = true;
+			(ctx.otp ??= {}).verified = true;
+			return true;
+		}
+		if (action === "useDifferentMethod") {
+			this.clearEnrollScratch(ctx);
+			return true;
+		}
+		return false;
+	}
 	initLogin(ctx) {
 		const state = getInputField("state");
 		if (state) {
@@ -1682,23 +1964,25 @@ let AuthWorkflow = class AuthWorkflow {
 		password.intro = "Enter your current password, then choose a new one.";
 	}
 	/**
-	* Bind the standalone "add an MFA method" flow to the CURRENT authenticated
-	* user and narrow enrolment to the transports they have NOT enrolled yet.
-	* Identity comes from the session (`useAuth().getUserId()`) — never form input
-	* — so it is structurally "add a factor to MY account". Mirrors
-	* `init-change-password`'s arbac gate (`auth.add-mfa` / `self`): a customer
-	* enables the feature with a single `allow("auth.add-mfa", "*")` grant and
-	* forbids it by omitting it. `getUserId()` throws 401 if unauthenticated —
-	* defence in depth on top of the guarded trigger route.
+	* Bind the standalone "Manage two-factor authentication" flow (add / change /
+	* remove) to the CURRENT authenticated user. Identity comes from the session
+	* (`useAuth().getUserId()`) — never form input — so it is structurally "manage
+	* MY factors". Mirrors `init-change-password`'s arbac gate (`auth.add-mfa` /
+	* `self`): a customer enables the feature with a single
+	* `allow("auth.add-mfa", "*")` grant and forbids it by omitting it.
+	* `getUserId()` throws 401 if unauthenticated — defence in depth on top of the
+	* guarded trigger route.
 	*
-	* Drives the REUSED enrol trio (`enroll-pick-method` / `enroll-address` /
-	* `enroll-confirm`) by setting `ctx.mfaPolicy.availableTransports` to the
-	* un-enrolled remainder — so the picker offers only those and auto-picks when
-	* exactly one remains. Forces `mode: "optional"` (the user opted in; an empty
-	* remainder must finish gracefully, never 500 as `required` would). The
-	* remainder is stashed on `ctx.addMfa.candidates` (flow discriminator + finish
-	* summary); when the user already has a default, `enroll-confirm` is asked to
-	* keep it (`mfaEnroll.keepExistingDefault`).
+	* Sets `ctx.mfaPolicy.availableTransports` to the FULL policy set (so the
+	* step-up's `load-enrolled-mfa-methods` can see the confirmed factors to
+	* challenge) and tracks the un-enrolled `candidates` separately on
+	* `ctx.addMfa` for the menu's Add options. `stepUpRequired` is set when the
+	* user has ANY confirmed factor — gating both the step-up and the management
+	* menu; a zero-MFA user skips both and falls through to the first-time enrol
+	* picker (the opt-in path). `stepUpMode` picks the step-up method: `'mfa'`
+	* when a confirmed factor is still challengeable, else `'password'` (a
+	* password re-auth fallback for an orphaned factor). Puts the enrol forms in
+	* `'manage'` mode (Cancel, not "Skip for now") and keeps the existing default.
 	*/
 	async initAddMfa(ctx) {
 		const username = useAuth().getUserId();
@@ -1707,15 +1991,23 @@ let AuthWorkflow = class AuthWorkflow {
 		const policy = policyResult instanceof Promise ? await policyResult : policyResult;
 		const all = policy.availableTransports;
 		const user = await this.users.getUser(username);
-		const enrolled = new Set((user.mfa?.methods ?? []).filter((m) => m.confirmed).map((m) => m.name));
-		const remaining = all.filter((t) => !enrolled.has(t));
+		const enrolledKinds = new Set(this.users.getAvailableMfaMethods(user.mfa).map((m) => this.mfaKindOf(m.name)).filter((k) => k !== null));
+		const candidates = all.filter((t) => !enrolledKinds.has(t));
+		const challengeable = [...enrolledKinds].filter((k) => all.includes(k));
+		const hasFactors = enrolledKinds.size > 0;
 		ctx.mfaPolicy = {
-			mode: "optional",
-			availableTransports: remaining,
+			mode: policy.mode,
+			availableTransports: all,
 			issuer: policy.issuer
 		};
-		ctx.addMfa = { candidates: remaining };
-		if (user.mfa?.defaultMethod) (ctx.mfaEnroll ??= {}).keepExistingDefault = true;
+		ctx.addMfa = {
+			candidates,
+			stepUpRequired: hasFactors,
+			stepUpMode: challengeable.length > 0 ? "mfa" : "password"
+		};
+		const m = ctx.mfaEnroll ??= {};
+		m.mode = "manage";
+		if (user.mfa?.defaultMethod) m.keepExistingDefault = true;
 	}
 	async credentials(ctx) {
 		const altResult = this.resolveAlternateCredentials(ctx);
@@ -1829,6 +2121,14 @@ let AuthWorkflow = class AuthWorkflow {
 			this.finishGenericRecovery();
 			return;
 		}
+		const sourceResult = this.resolveRecoveryDeliverySource(ctx);
+		if ((sourceResult instanceof Promise ? await sourceResult : sourceResult) === "registered") {
+			const user = await this.users.getUser(subject);
+			if (!this.selectRecoveryRegisteredMethod(user)) {
+				this.finishGenericRecovery();
+				return;
+			}
+		}
 		ctx.subject = subject;
 		swapStrategy("store");
 	}
@@ -2345,11 +2645,10 @@ let AuthWorkflow = class AuthWorkflow {
 		});
 	}
 	/**
-	* Terminal for the add-MFA flow. The user KEEPS their current session (no
-	* re-issue, no cookies) — this is a plain data finish. `mfaEnroll.done &&
-	* mfaEnroll.method` is the success signal: a real confirm keeps `.method`,
-	* whereas a cancel runs `cleanupEnrollment` (which deletes it). An empty
-	* `addMfa.candidates` distinguishes "nothing left to add" from a user cancel.
+	* Terminal for the manage-MFA flow. The user KEEPS their current session (no
+	* re-issue, no cookies) — a plain data finish. Outcomes, in priority order:
+	* removed → changed (`replace` + done) → added (done) → nothing-available
+	* (zero candidates, never had to step-up) → cancelled.
 	*/
 	finishAddMfa(ctx) {
 		const labels = {
@@ -2357,10 +2656,34 @@ let AuthWorkflow = class AuthWorkflow {
 			email: "Email code",
 			sms: "Text-message code"
 		};
-		const method = ctx.mfaEnroll?.method;
-		const candidates = ctx.addMfa?.candidates ?? [];
+		const m = ctx.mfaEnroll;
+		const addMfa = ctx.addMfa;
+		const method = m?.method;
+		const candidates = addMfa?.candidates ?? [];
 		let envelope;
-		if (ctx.mfaEnroll?.done && method) envelope = {
+		if (addMfa?.removed) envelope = {
+			finished: true,
+			data: {
+				removed: true,
+				method: addMfa.removed
+			},
+			message: {
+				level: "success",
+				text: `${labels[addMfa.removed]} removed.`
+			}
+		};
+		else if (m?.done && method && addMfa?.action === "replace") envelope = {
+			finished: true,
+			data: {
+				changed: true,
+				method
+			},
+			message: {
+				level: "success",
+				text: `${labels[method]} updated.`
+			}
+		};
+		else if (m?.done && method) envelope = {
 			finished: true,
 			data: {
 				added: true,
@@ -2371,7 +2694,7 @@ let AuthWorkflow = class AuthWorkflow {
 				text: `${labels[method]} added.`
 			}
 		};
-		else if (candidates.length === 0) envelope = {
+		else if (candidates.length === 0 && !addMfa?.stepUpRequired) envelope = {
 			finished: true,
 			data: {
 				added: false,
@@ -2390,7 +2713,7 @@ let AuthWorkflow = class AuthWorkflow {
 			},
 			message: {
 				level: "info",
-				text: "No authentication method was added."
+				text: "No changes were made to your two-factor methods."
 			}
 		};
 		useWfFinished().set({
@@ -2398,6 +2721,124 @@ let AuthWorkflow = class AuthWorkflow {
 			value: envelope
 		});
 	}
+	/**
+	* Resolve which transports the user may NOT change/remove via the manage flow
+	* (calls {@link resolveLockedMfaTransports}) and write them to
+	* `ctx.addMfa.locked`. Mirrors the `prepare-<group>` convention.
+	*/
+	prepareLockedMfaTransports(ctx) {
+		const result = this.resolveLockedMfaTransports(ctx);
+		const apply = (locked) => {
+			(ctx.addMfa ??= {}).locked = locked;
+		};
+		if (result instanceof Promise) return result.then(apply);
+		return apply(result);
+	}
+	/**
+	* Fires once the step-up factor verifies — anchor the rest of the flow in the
+	* durable `store` strategy (mirrors login's swap-after-credentials): the
+	* pincode becomes single-use server state and the staged new factor lives
+	* server-side instead of in the SPA-held encapsulated token. Degrades to
+	* encapsulated when no durable store is wired (the registry default).
+	*/
+	manageStepUpDone(ctx) {
+		swapStrategy("store");
+		(ctx.addMfa ??= {}).stepUpDone = true;
+	}
+	/**
+	* Manage-MFA password re-auth — the step-up FALLBACK when the user's only
+	* confirmed factor(s) are of kinds the policy no longer allows, so nothing is
+	* MFA-challengeable (`addMfa.stepUpMode === "password"`; see `init-add-mfa`).
+	* Pauses on `PasswordReauthForm`, verifies the account password via
+	* `UserService.verifyPassword`, and on success flips `ctx.otp.verified` — the
+	* SAME step-up success signal `mfaStepUpLoop` sets — so `manage-stepup-done`
+	* (swap-to-store) and `manage-menu` proceed identically. `cancel` aborts to
+	* the cancelled terminal (fail closed: no management write without a fresh
+	* proof of identity). Only ARBAC-gated callers reach it (session-bound
+	* subject), and `verifyPassword` is the same check `changePassword` enforces.
+	*/
+	async managePasswordReauth(ctx) {
+		this.requireSubject(ctx);
+		const username = ctx.subject;
+		const wf = this.useAtscriptWfPublic(ctx, this.opts.forms.passwordReauth);
+		if (wf.resolveAction() === "cancel") {
+			ctx.aborted = true;
+			return;
+		}
+		const input = wf.resolveInput();
+		if (!await this.users.verifyPassword(username, input.password)) throw this.throwPublic(ctx, wf, { errors: { password: "Incorrect password" } });
+		(ctx.otp ??= {}).verified = true;
+	}
+	/**
+	* Manage-MFA menu — pauses on `ManageMfaForm` and routes the chosen
+	* `operation` (`add:<t>` / `replace:<t>` / `remove:<t>`). Only reached when
+	* the user has ≥1 confirmed factor (a zero-MFA user goes straight to the enrol
+	* picker). Re-checks the locked set + candidate membership server-side, then
+	* sets `ctx.addMfa.action`/`target` (and pre-seeds `mfaEnroll.method` for
+	* add/change). `cancel`, or nothing actionable, aborts to the finish terminal.
+	*/
+	async manageMenu(ctx) {
+		this.requireSubject(ctx);
+		const addMfa = ctx.addMfa ??= {};
+		const enrolled = ctx.mfa?.enrolledMethods ?? [];
+		const locked = new Set(addMfa.locked ?? []);
+		const candidates = addMfa.candidates ?? [];
+		const changeable = enrolled.filter((e) => !locked.has(e.kind));
+		if (candidates.length === 0 && changeable.length === 0) {
+			ctx.aborted = true;
+			return;
+		}
+		const wf = this.useAtscriptWfPublic(ctx, this.opts.forms.manageMfa);
+		if (wf.resolveAction() === "cancel") {
+			ctx.aborted = true;
+			return;
+		}
+		const input = wf.resolveInput();
+		const sep = input.operation.indexOf(":");
+		const action = sep >= 0 ? input.operation.slice(0, sep) : "";
+		const target = sep >= 0 ? input.operation.slice(sep + 1) : "";
+		if (action === "add") {
+			if (!candidates.includes(target)) throw this.throwPublic(ctx, wf, { errors: { operation: "That method isn't available" } });
+		} else if (action === "replace" || action === "remove") {
+			if (locked.has(target)) throw this.throwPublic(ctx, wf, { formMessage: "That method can't be changed here." });
+			if (!enrolled.some((e) => e.kind === target)) throw this.throwPublic(ctx, wf, { errors: { operation: "Unknown method" } });
+		} else throw this.throwPublic(ctx, wf, { errors: { operation: "Choose an option" } });
+		addMfa.action = action;
+		addMfa.target = target;
+		const m = ctx.mfaEnroll ??= {};
+		if (action === "add" || action === "replace") {
+			m.method = target;
+			delete m.address;
+			delete m.qrSeen;
+			delete m.done;
+			delete m.secret;
+			delete m.uri;
+		} else m.method = target;
+	}
+	/**
+	* Manage-MFA remove confirmation. Pauses on `RemoveMfaConfirmForm`; the
+	* 'Remove' submit performs the removal, 'Cancel' aborts. Re-checks the locked
+	* set (defence in depth) and blocks removing the LAST confirmed factor when
+	* the policy mode is `required` (you must keep at least one).
+	*/
+	async confirmRemoveMfa(ctx) {
+		this.requireSubject(ctx);
+		const username = ctx.subject;
+		const addMfa = ctx.addMfa ??= {};
+		const target = addMfa.target;
+		const wf = this.useAtscriptWfPublic(ctx, this.opts.forms.removeMfaConfirm);
+		if (wf.resolveAction() === "cancel") {
+			ctx.aborted = true;
+			return;
+		}
+		if ((addMfa.locked ?? []).includes(target)) throw this.throwPublic(ctx, wf, { formMessage: "That method can't be removed here." });
+		const enrolled = ctx.mfa?.enrolledMethods ?? [];
+		if (enrolled.length <= 1 && ctx.mfaPolicy?.mode === "required") throw this.throwPublic(ctx, wf, { formMessage: "You must keep at least one two-factor method." });
+		wf.resolveInput();
+		const methodName = enrolled.find((e) => e.kind === target)?.methodName ?? target;
+		await this.withStoreErrorTranslation(() => this.users.removeMfaMethod(username, methodName));
+		addMfa.removed = target;
+	}
 	async askChannel(ctx, channel) {
 		this.requireSubject(ctx);
 		const isEmail = channel === "email";
@@ -2620,8 +3061,18 @@ let AuthWorkflow = class AuthWorkflow {
 	* `resolvePincodeTarget` (which discriminate on `ctx.mfa?.method` presence).
 	*/
 	async pincodeSend(ctx) {
-		const targetResult = this.resolvePincodeTarget(ctx);
-		const target = targetResult instanceof Promise ? await targetResult : targetResult;
+		let target;
+		try {
+			const targetResult = this.resolvePincodeTarget(ctx);
+			target = targetResult instanceof Promise ? await targetResult : targetResult;
+		} catch (err) {
+			if (err instanceof RecoveryMethodUnavailableError) {
+				ctx.aborted = true;
+				this.finishGenericRecovery();
+				return;
+			}
+			throw err;
+		}
 		const code = this.mintPin(ctx, this.opts.mfa.pincodeLength, this.opts.mfa.pincodeTtlMs);
 		if (ctx.mfa?.method) await this.deliver({
 			kind: "mfa-pincode",
@@ -2639,7 +3090,7 @@ let AuthWorkflow = class AuthWorkflow {
 		});
 		else await this.deliver({
 			kind: "recovery-pincode",
-			channel: "email",
+			channel: target.channel,
 			recipient: target.address,
 			code,
 			expiresInMs: this.opts.mfa.pincodeTtlMs
@@ -2737,19 +3188,21 @@ let AuthWorkflow = class AuthWorkflow {
 	/**
 	* Unified MFA-enrol phase 1 (pick method). Auto-picks a single transport,
 	* otherwise pauses for `EnrollPickMethodForm`. When TOTP is picked, the
-	* secret is idempotently provisioned in the same step body. Handles
-	* `skip` in `'optional'` mode.
+	* secret is idempotently provisioned in the same step body. Handles `skip`
+	* (optional opt-in) / `cancel` (manage). In the manage flow this only runs
+	* for a zero-MFA user — once the user has factors, the menu pre-seeds
+	* `mfaEnroll.method` (add/change) so the picker is skipped.
 	*/
 	enrollPickMethod(ctx) {
 		this.requireSubject(ctx);
 		const username = ctx.subject;
 		const transports = ctx.mfaPolicy?.availableTransports ?? [];
-		const mode = ctx.mfaPolicy?.mode === "required" ? "required" : "optional";
 		const m = ctx.mfaEnroll ??= {};
+		const mode = m.mode === "manage" ? "manage" : ctx.mfaPolicy?.mode === "required" ? "required" : "optional";
 		m.mode = mode;
 		if (!m.availableTransports) m.availableTransports = [...transports];
 		if (transports.length === 0) {
-			if (mode === "optional") {
+			if (mode !== "required") {
 				m.done = true;
 				(ctx.otp ??= {}).verified = true;
 				return;
@@ -2759,7 +3212,12 @@ let AuthWorkflow = class AuthWorkflow {
 		if (transports.length === 1) m.method = transports[0];
 		else {
 			const wf = this.useAtscriptWfPublic(ctx, this.opts.forms.enrollPickMethod);
-			if (mode === "optional" && wf.resolveAction() === "skip") {
+			const action = wf.resolveAction();
+			if (mode === "manage" && action === "cancel") {
+				ctx.aborted = true;
+				return;
+			}
+			if (mode === "optional" && action === "skip") {
 				m.done = true;
 				(ctx.otp ??= {}).verified = true;
 				return;
@@ -2771,28 +3229,29 @@ let AuthWorkflow = class AuthWorkflow {
 		if (m.method === "totp" && !m.secret) {
 			const issuer = ctx.mfaPolicy?.issuer ?? this.opts.totpIssuer;
 			const secret = generateTotpSecret();
-			const uri = generateTotpUri(secret, issuer, username);
-			return this.withStoreErrorTranslation(() => this.users.addMfaMethod(username, {
-				name: "totp",
-				value: secret,
-				confirmed: false
-			})).then(() => {
-				m.secret = secret;
-				m.uri = uri;
-			});
+			m.secret = secret;
+			m.uri = generateTotpUri(secret, issuer, username);
 		}
 	}
 	/**
 	* Unified MFA-enrol phase 2 (collect sms/email address + send pincode).
-	* Not invoked for totp. Handles `skip` / `useDifferentMethod`.
+	* Not invoked for totp. Handles `skip` (opt-in) / `cancel` (manage) /
+	* `useDifferentMethod`. Validates the address server-side (the client
+	* `@ui.form.validate` hint is advisory), then STAGES the candidate value in
+	* wf-state (`m.address`) — the user record is written only on confirm
+	* (write-on-confirm), so an ADD leaves no partial row and a REPLACE keeps the
+	* old confirmed value live until the new code verifies in `enroll-confirm`.
 	*/
 	async enrollAddress(ctx) {
 		this.requireSubject(ctx);
-		const username = ctx.subject;
 		const m = ctx.mfaEnroll ??= {};
 		const mode = m.mode ?? "optional";
 		const wf = this.useAtscriptWfPublic(ctx, this.opts.forms.enrollAddress);
 		const action = wf.resolveAction();
+		if (mode === "manage" && action === "cancel") {
+			this.cancelManageEnrollment(ctx);
+			return;
+		}
 		if (mode === "optional" && action === "skip") {
 			m.done = true;
 			(ctx.otp ??= {}).verified = true;
@@ -2804,53 +3263,60 @@ let AuthWorkflow = class AuthWorkflow {
 		}
 		const input = wf.resolveInput();
 		const methodName = m.method;
-		await this.withStoreErrorTranslation(() => this.users.addMfaMethod(username, {
-			name: methodName,
-			value: input.address,
-			confirmed: false
-		}));
-		m.address = input.address;
+		const addrErr = this.validateMfaAddress(methodName, input.address);
+		if (addrErr) throw this.throwPublic(ctx, wf, { errors: { address: addrErr } });
+		const address = this.normalizeMfaAddress(methodName, input.address);
+		m.address = address;
 		const code = this.mintPin(ctx, this.opts.mfa.pincodeLength, this.opts.mfa.pincodeTtlMs);
 		const pincode = ctx.pincode ??= {};
 		pincode.resendAllowedAt = Date.now() + this.opts.mfa.pincodeResendTimeoutMs;
 		pincode.codeLength = this.opts.mfa.pincodeLength;
-		await this.sendEnrollPincode(ctx, input.address, code);
+		await this.sendEnrollPincode(ctx, address, code);
 	}
 	/**
-	* Unified MFA-enrol phase 3 (verify pincode/TOTP, mark confirmed). On
-	* success sets `ctx.mfaEnroll.done = true` AND `ctx.otp.verified = true`
-	* (the loop-exit signal — enrol-confirm verifies an OTP, so the unified
-	* `otp.verified` flag fires alongside the MFA-specific `mfaEnroll.done`).
+	* MFA-enrol TOTP QR step — shown on its OWN pause between method-pick and
+	* code-entry (so the user scans first, types the code next). Idempotently
+	* provisions the TOTP secret in wf-state ONLY (covers the auto-pick /
+	* menu-pre-seeded paths where `enroll-pick-method` was skipped), then pauses
+	* on `EnrollTotpQrForm`. The user record is written only on confirm
+	* (write-on-confirm), so a manage **replace** never clobbers the live totp
+	* secret and a cancel/crash leaves the existing factor intact — no stash or
+	* restore needed. Handles `skip` (opt-in) / `cancel` (manage) /
+	* `useDifferentMethod`.
 	*/
-	async enrollConfirm(ctx) {
+	async enrollTotpQr(ctx) {
 		this.requireSubject(ctx);
 		const username = ctx.subject;
 		const m = ctx.mfaEnroll ??= {};
 		if (m.method === "totp" && !m.secret) {
 			const issuer = ctx.mfaPolicy?.issuer ?? this.opts.totpIssuer;
 			const secret = generateTotpSecret();
-			const uri = generateTotpUri(secret, issuer, username);
-			await this.withStoreErrorTranslation(() => this.users.addMfaMethod(username, {
-				name: "totp",
-				value: secret,
-				confirmed: false
-			}));
 			m.secret = secret;
-			m.uri = uri;
+			m.uri = generateTotpUri(secret, issuer, username);
 		}
+		const wf = this.useAtscriptWfPublic(ctx, this.opts.forms.enrollTotpQr);
+		if (this.handleEnrollExit(ctx, wf.resolveAction())) return void 0;
+		wf.resolveInput();
+		m.qrSeen = true;
+	}
+	/**
+	* Unified MFA-enrol phase 3 (verify pincode/TOTP, then write the factor). On
+	* success sets `ctx.mfaEnroll.done = true` AND `ctx.otp.verified = true`
+	* (the loop-exit signal — enrol-confirm verifies an OTP, so the unified
+	* `otp.verified` flag fires alongside the MFA-specific `mfaEnroll.done`).
+	* This is the ONLY place the enrol trio touches the user record
+	* (write-on-confirm): the proven value (sms/email address or totp secret,
+	* staged in wf-state) is upserted as confirmed via `addMfaMethod`, which
+	* atomically swaps in a REPLACE with no pre-confirm clobber window and creates
+	* a fresh row for an ADD.
+	*/
+	async enrollConfirm(ctx) {
+		this.requireSubject(ctx);
+		const username = ctx.subject;
+		const m = ctx.mfaEnroll ??= {};
 		const wf = this.useAtscriptWfPublic(ctx, this.opts.forms.enrollConfirm);
-		const mode = m.mode ?? "optional";
 		const action = wf.resolveAction();
-		if (mode === "optional" && action === "skip") {
-			await this.cleanupEnrollment(ctx, username);
-			m.done = true;
-			(ctx.otp ??= {}).verified = true;
-			return;
-		}
-		if (action === "useDifferentMethod") {
-			await this.cleanupEnrollment(ctx, username);
-			return;
-		}
+		if (this.handleEnrollExit(ctx, action)) return void 0;
 		if (action === "resend") {
 			if (m.method === "totp") throw this.throwPublic(ctx, wf, { formMessage: "Resend is not applicable for TOTP" });
 			const cooldown = ctx.pincode?.resendAllowedAt;
@@ -2866,18 +3332,19 @@ let AuthWorkflow = class AuthWorkflow {
 			return;
 		}
 		const input = wf.resolveInput();
-		if (m.method === "totp") try {
-			await this.users.verifyTotpSetupCode(username, input.code);
-		} catch (err) {
-			if (err instanceof UserAuthError && err.type === "MFA_INVALID") throw this.throwPublic(ctx, wf, { errors: { code: "Invalid code" } });
-			throw err;
-		}
-		else {
+		if (m.method === "totp") {
+			if (verifyTotpCode(m.secret, input.code) === null) throw this.throwPublic(ctx, wf, { errors: { code: "Invalid code" } });
+		} else {
 			const pinErr = this.verifyPin(ctx, input.code);
 			if (pinErr) throw this.throwPublic(ctx, wf, { errors: pinErr });
 		}
 		const methodName = m.method;
-		await this.withStoreErrorTranslation(() => this.users.confirmMfaMethod(username, methodName));
+		const value = m.method === "totp" ? m.secret : m.address;
+		await this.withStoreErrorTranslation(() => this.users.addMfaMethod(username, {
+			name: methodName,
+			value,
+			confirmed: true
+		}));
 		if (!m.keepExistingDefault) await this.users.setDefaultMfaMethod(username, methodName);
 		m.done = true;
 		(ctx.otp ??= {}).verified = true;
@@ -2885,6 +3352,46 @@ let AuthWorkflow = class AuthWorkflow {
 		delete ctx.pinExpire;
 	}
 	/**
+	* Promote a freshly-confirmed channel into its login-handle column so future
+	* login + recovery resolve the account by it (`findByHandle`). Runs once,
+	* right after `enroll-confirm` in the shared enrolment trio (so it covers
+	* add-mfa AND login/invite forced first-time enrolment). Default is a no-op
+	* unless `resolvePromoteHandleField` is overridden to name a handle column.
+	*
+	* Overridable extension point: a deployment can replace this with richer
+	* logic — e.g. pause on a carrier form asking whether to use the new number
+	* as a login handle before writing it.
+	*
+	* Fires only for a freshly-confirmed `email` / `sms` factor carrying an
+	* address. TOTP has no address; a skipped / `useDifferentMethod` enrolment
+	* cleared `method` + `address` via `clearEnrollScratch`, so the guard below
+	* excludes both — only an actually-confirmed channel is promoted.
+	*/
+	async promoteToHandle(ctx) {
+		const m = ctx.mfaEnroll;
+		if (ctx.subject && m?.address && (m.method === "email" || m.method === "sms")) {
+			const field = await this.resolvePromoteHandleField(ctx, m.method);
+			if (field) await this.applyHandlePromotion(ctx.subject, field, m.address);
+		}
+		ctx.promoteToHandleDone = true;
+	}
+	/**
+	* Best-effort write of a confirmed channel value into its handle column.
+	* Swallows `ALREADY_EXISTS` — the value is already a handle on ANOTHER
+	* account (e.g. two accounts legitimately sharing one phone for MFA): the
+	* second account keeps the factor as MFA-only and is simply not promoted.
+	* Any other store error propagates. (`UserService.update` translates a
+	* unique-index `CONFLICT` to `ALREADY_EXISTS` for both store adapters.)
+	*/
+	async applyHandlePromotion(subject, field, value) {
+		try {
+			await this.users.update(subject, { [field]: value });
+		} catch (err) {
+			if (err instanceof UserAuthError && err.type === "ALREADY_EXISTS") return;
+			throw err;
+		}
+	}
+	/**
 	* Risk step-up: re-evaluate whether to require another MFA round. Default
 	* `resolveRiskStepUp` returns `{require: false}`. When `require: true`,
 	* clear `ctx.otp.verified` to re-arm the loop.
@@ -3123,6 +3630,11 @@ let AuthWorkflow = class AuthWorkflow {
 			codeChallenge: req.codeChallenge,
 			redirectUri: req.redirectUri,
 			...req.clientId !== void 0 && { clientId: req.clientId },
+			...req.scope !== void 0 && { scope: req.scope },
+			...req.nonce !== void 0 && { nonce: req.nonce },
+			...req.idToken !== void 0 && { idToken: req.idToken },
+			...req.accessToken !== void 0 && { accessToken: req.accessToken },
+			...req.audience !== void 0 && { audience: req.audience },
 			tokenPolicy: req.tokenPolicy
 		});
 		await pending.delete(handle);
@@ -3691,20 +4203,35 @@ let AuthWorkflow = class AuthWorkflow {
 	*/
 	changePasswordFlow() {}
 	/**
-	* add-mfa.flow — authenticated self-service "add a second factor". Same
-	* gating model as change-password: NOT `@Public()` — `init-add-mfa` is arbac-
-	* gated (`auth.add-mfa` / `self`) and binds `ctx.subject` from the session, so
-	* an unauthenticated / unauthorized caller is rejected at the first step. NOT
-	* in `DEFAULT_AUTH_WORKFLOWS` — reached only via the GUARDED trigger route
+	* add-mfa.flow — authenticated self-service "Manage two-factor
+	* authentication" (add / change / remove). Same gating model as
+	* change-password: NOT `@Public()` — `init-add-mfa` is arbac-gated
+	* (`auth.add-mfa` / `self`) and binds `ctx.subject` from the session, so an
+	* unauthenticated / unauthorized caller is rejected at the first step. NOT in
+	* `DEFAULT_AUTH_WORKFLOWS` — reached only via the GUARDED trigger route
 	* (`AuthController.addMfa`), never the public `/auth/trigger`.
 	*
-	* The body REUSES the login/invite forced-enrolment trio verbatim
-	* (`enroll-pick-method` → `enroll-address` → `enroll-confirm`); the only
-	* difference is the driver: `init-add-mfa` narrows `ctx.mfaPolicy`
-	* `availableTransports` to the transports the user has NOT enrolled, so the
-	* picker offers exactly those and auto-picks when one remains. Available only
-	* when something is un-enrolled — with everything enrolled the trio is skipped
-	* and `finish-add-mfa` returns a benign "nothing to add" terminal.
+	* Shape:
+	* 1. `init-add-mfa` — bind subject, resolve the FULL transport set + the
+	*    un-enrolled `candidates`, mark `stepUpRequired` when the user already has
+	*    ≥1 confirmed factor, and put the enrol forms in `'manage'` mode.
+	* 2. `prepare-locked-mfa-transports` — resolve which factors the consumer
+	*    forbids changing (handle-bound email/phone).
+	* 3. STEP-UP (only when `stepUpRequired`): re-verify identity before any
+	*    change — `mfaStepUpLoop` challenges an EXISTING factor when one is still
+	*    challengeable (`stepUpMode==='mfa'`), else `manage-password-reauth` falls
+	*    back to the account password (`stepUpMode==='password'`). On success
+	*    `manage-stepup-done` swaps off the encapsulated start onto the durable
+	*    `store` strategy (server-anchored, replay-resistant; mirrors login's
+	*    swap-after-credentials).
+	* 4. `manage-menu` (only when `stepUpRequired`) — pick add / change / remove +
+	*    target; pre-seeds `mfaEnroll.method` for add/change.
+	* 5. Route: `confirm-remove-mfa` for remove; otherwise the REUSED enrol trio
+	*    (`enroll-pick-method` → `enroll-address` / `enroll-totp-qr` →
+	*    `enroll-confirm`). A zero-MFA user skips step-up + menu and lands on the
+	*    enrol picker directly (the first-time opt-in path).
+	* 6. `finish-add-mfa` — added / changed / removed / cancelled / nothing terminal.
+	*    The user KEEPS their session (no token re-issue).
 	*/
 	addMfaFlow() {}
 	/**
@@ -4059,6 +4586,51 @@ __decorate([
 	__decorateMetadata("design:paramtypes", [Object]),
 	__decorateMetadata("design:returntype", void 0)
 ], AuthWorkflow.prototype, "finishAddMfa", null);
+__decorate([
+	Step("prepare-locked-mfa-transports"),
+	ArbacResource("auth.add-mfa"),
+	ArbacAction("self"),
+	__decorateParam(0, WorkflowParam("context")),
+	__decorateMetadata("design:type", Function),
+	__decorateMetadata("design:paramtypes", [Object]),
+	__decorateMetadata("design:returntype", Object)
+], AuthWorkflow.prototype, "prepareLockedMfaTransports", null);
+__decorate([
+	Step("manage-stepup-done"),
+	ArbacResource("auth.add-mfa"),
+	ArbacAction("self"),
+	__decorateParam(0, WorkflowParam("context")),
+	__decorateMetadata("design:type", Function),
+	__decorateMetadata("design:paramtypes", [Object]),
+	__decorateMetadata("design:returntype", void 0)
+], AuthWorkflow.prototype, "manageStepUpDone", null);
+__decorate([
+	Step("manage-password-reauth"),
+	ArbacResource("auth.add-mfa"),
+	ArbacAction("self"),
+	__decorateParam(0, WorkflowParam("context")),
+	__decorateMetadata("design:type", Function),
+	__decorateMetadata("design:paramtypes", [Object]),
+	__decorateMetadata("design:returntype", Promise)
+], AuthWorkflow.prototype, "managePasswordReauth", null);
+__decorate([
+	Step("manage-menu"),
+	ArbacResource("auth.add-mfa"),
+	ArbacAction("self"),
+	__decorateParam(0, WorkflowParam("context")),
+	__decorateMetadata("design:type", Function),
+	__decorateMetadata("design:paramtypes", [Object]),
+	__decorateMetadata("design:returntype", Promise)
+], AuthWorkflow.prototype, "manageMenu", null);
+__decorate([
+	Step("confirm-remove-mfa"),
+	ArbacResource("auth.add-mfa"),
+	ArbacAction("self"),
+	__decorateParam(0, WorkflowParam("context")),
+	__decorateMetadata("design:type", Function),
+	__decorateMetadata("design:paramtypes", [Object]),
+	__decorateMetadata("design:returntype", Promise)
+], AuthWorkflow.prototype, "confirmRemoveMfa", null);
 __decorate([
 	Step("ask/:channel(email|phone)"),
 	Public(),
@@ -4149,6 +4721,14 @@ __decorate([
 	__decorateMetadata("design:paramtypes", [Object]),
 	__decorateMetadata("design:returntype", Promise)
 ], AuthWorkflow.prototype, "enrollAddress", null);
+__decorate([
+	Step("enroll-totp-qr"),
+	Public(),
+	__decorateParam(0, WorkflowParam("context")),
+	__decorateMetadata("design:type", Function),
+	__decorateMetadata("design:paramtypes", [Object]),
+	__decorateMetadata("design:returntype", Promise)
+], AuthWorkflow.prototype, "enrollTotpQr", null);
 __decorate([
 	Step("enroll-confirm"),
 	Public(),
@@ -4157,6 +4737,14 @@ __decorate([
 	__decorateMetadata("design:paramtypes", [Object]),
 	__decorateMetadata("design:returntype", Promise)
 ], AuthWorkflow.prototype, "enrollConfirm", null);
+__decorate([
+	Step("promote-to-handle"),
+	Public(),
+	__decorateParam(0, WorkflowParam("context")),
+	__decorateMetadata("design:type", Function),
+	__decorateMetadata("design:paramtypes", [Object]),
+	__decorateMetadata("design:returntype", Promise)
+], AuthWorkflow.prototype, "promoteToHandle", null);
 __decorate([
 	Step("risk-step-up"),
 	Public(),
@@ -4596,8 +5184,30 @@ __decorate([
 	WorkflowSchema([
 		{ id: "init-add-mfa" },
 		{ break: (ctx) => !ctx.subject },
+		{ id: "prepare-locked-mfa-transports" },
+		{
+			condition: (ctx) => !!ctx.addMfa?.stepUpRequired && ctx.addMfa?.stepUpMode === "mfa",
+			steps: mfaStepUpLoop
+		},
+		{
+			id: "manage-password-reauth",
+			condition: (ctx) => !!ctx.addMfa?.stepUpRequired && ctx.addMfa?.stepUpMode === "password" && !ctx.otp?.verified
+		},
+		{ break: (ctx) => !!ctx.aborted },
 		{
-			condition: (ctx) => (ctx.addMfa?.candidates?.length ?? 0) > 0,
+			id: "manage-stepup-done",
+			condition: (ctx) => !!ctx.addMfa?.stepUpRequired && !!ctx.otp?.verified && !ctx.addMfa?.stepUpDone
+		},
+		{
+			id: "manage-menu",
+			condition: (ctx) => !!ctx.addMfa?.stepUpRequired && !ctx.addMfa?.action
+		},
+		{
+			id: "confirm-remove-mfa",
+			condition: (ctx) => !ctx.aborted && ctx.addMfa?.action === "remove"
+		},
+		{
+			condition: (ctx) => !ctx.aborted && ctx.addMfa?.action !== "remove" && (ctx.addMfa?.action === "replace" || (ctx.addMfa?.candidates?.length ?? 0) > 0),
 			steps: enrollTrioSteps
 		},
 		{ id: "finish-add-mfa" }
@@ -5178,6 +5788,8 @@ function toConnectedAccount(i) {
 }
 //#endregion
 //#region src/authz/authorize.controller.ts
+/** Shared default claims resolver — stateless, so one instance is reused across requests. */
+const NOOP_OIDC_CLAIMS_RESOLVER = new NoopOidcClaimsResolver();
 let AuthorizeController = class AuthorizeController {
 	auth;
 	policy;
@@ -5190,6 +5802,22 @@ let AuthorizeController = class AuthorizeController {
 		this.codes = codes;
 	}
 	/**
+	* The Tier-2 OIDC `id_token` signer, or `undefined` for a Tier-1-only (CLI)
+	* deployment — then discovery / `/auth/jwks` 404 and no `id_token` is minted.
+	* **Override** in a subclass to enable OIDC (return one `IdTokenSigner` whose
+	* issuer is `{origin}/auth`). A plain getter rather than a DI token because an
+	* OPTIONAL `@Inject`/`@Optional` dependency panics in moost's `resolveMoost`
+	* route-table pass (`useHandlerPaths`); a method has nothing for it to resolve.
+	*/
+	getIdTokenSigner() {}
+	/**
+	* The Tier-2 OIDC profile-claims resolver. Defaults to a no-op (`sub`-only
+	* tokens); **override** to emit `email` / `name` / … from your user record.
+	*/
+	getOidcClaimsResolver() {
+		return NOOP_OIDC_CLAIMS_RESOLVER;
+	}
+	/**
 	* The SPA login route the authorize request bounces to. The opaque pending-auth
 	* `handle` is appended as `?authz=`; the SPA forwards it into the login
 	* workflow's START input so `init-login` raises `ctx.authz`. Override for a
@@ -5198,7 +5826,7 @@ let AuthorizeController = class AuthorizeController {
 	loginPath() {
 		return "/login";
 	}
-	async authorize(responseType, redirectUri, clientId, state, codeChallenge, codeChallengeMethod, scope) {
+	async authorize(responseType, redirectUri, clientId, state, codeChallenge, codeChallengeMethod, scope, nonce) {
 		const res = useResponse(current());
 		if (!redirectUri) {
 			res.status = 400;
@@ -5208,7 +5836,8 @@ let AuthorizeController = class AuthorizeController {
 		try {
 			resolved = await this.policy.resolveClient({
 				...clientId !== void 0 && { clientId },
-				redirectUri
+				redirectUri,
+				...scope !== void 0 && { scope }
 			});
 		} catch (e) {
 			res.status = 400;
@@ -5220,7 +5849,11 @@ let AuthorizeController = class AuthorizeController {
 			redirectUri: resolved.redirectUri,
 			codeChallenge,
 			...state !== void 0 && { clientState: state },
-			...scope !== void 0 && { scope },
+			...resolved.scope !== void 0 && { scope: resolved.scope },
+			...nonce !== void 0 && { nonce },
+			...resolved.idToken !== void 0 && { idToken: resolved.idToken },
+			...resolved.accessToken !== void 0 && { accessToken: resolved.accessToken },
+			...resolved.audience !== void 0 && { audience: resolved.audience },
 			tokenPolicy: resolved.tokenPolicy
 		});
 		const loginPath = this.loginPath();
@@ -5231,36 +5864,130 @@ let AuthorizeController = class AuthorizeController {
 	}
 	async token(body) {
 		const res = useResponse(current());
-		const grantType = body?.grant_type;
-		const code = body?.code;
-		const codeVerifier = body?.code_verifier;
-		if (grantType !== "authorization_code") {
+		if (body?.grant_type !== "authorization_code") {
 			res.status = 400;
 			return { error: "unsupported_grant_type" };
 		}
-		if (!code || !codeVerifier) {
+		if (!body.code || !body.code_verifier) {
 			res.status = 400;
 			return { error: "invalid_request" };
 		}
-		const row = await this.codes.consume(code);
+		const row = await this.codes.consume(body.code);
 		if (!row) {
 			res.status = 400;
 			return { error: "invalid_grant" };
 		}
-		if (pkceChallengeFor(codeVerifier) !== row.codeChallenge) {
+		if (pkceChallengeFor(body.code_verifier) !== row.codeChallenge) {
 			res.status = 400;
 			return { error: "invalid_grant" };
 		}
-		const issued = await this.auth.issue(row.userId, tokenPolicyToIssueOptions(row.tokenPolicy));
-		const expiresIn = Math.max(0, Math.floor((issued.accessExpiresAt - Date.now()) / 1e3));
+		if (row.clientId !== void 0) {
+			if (body.client_id !== row.clientId) {
+				res.status = 401;
+				return { error: "invalid_client" };
+			}
+			try {
+				await this.policy.authenticateClient?.({
+					clientId: row.clientId,
+					...body.client_secret !== void 0 && { clientSecret: body.client_secret }
+				});
+			} catch {
+				res.status = 401;
+				return { error: "invalid_client" };
+			}
+		} else if (body.client_id !== void 0) {
+			res.status = 401;
+			return { error: "invalid_client" };
+		}
+		const wantIdToken = row.idToken === true;
+		const wantAccessToken = row.accessToken !== false;
+		if (!wantIdToken && !wantAccessToken) {
+			res.status = 400;
+			return { error: "invalid_request" };
+		}
+		let signing;
+		if (wantIdToken) {
+			const signer = this.getIdTokenSigner();
+			const audience = row.audience ?? row.clientId;
+			if (!signer || audience === void 0) {
+				res.status = 500;
+				return { error: "server_error" };
+			}
+			signing = {
+				signer,
+				audience
+			};
+		}
+		let accessToken;
+		let expiresIn;
+		if (wantAccessToken) {
+			const issued = await this.auth.issue(row.userId, tokenPolicyToIssueOptions(row.tokenPolicy));
+			accessToken = issued.accessToken;
+			expiresIn = Math.max(0, Math.floor((issued.accessExpiresAt - Date.now()) / 1e3));
+		}
+		let idToken;
+		if (signing) {
+			const extra = await this.getOidcClaimsResolver().resolveClaims(row.userId, row.scope);
+			idToken = await signing.signer.sign({
+				sub: row.userId,
+				aud: signing.audience,
+				...row.nonce !== void 0 && { nonce: row.nonce },
+				extra
+			});
+		}
 		res.status = 200;
 		return {
-			access_token: issued.accessToken,
 			token_type: "Bearer",
-			expires_in: expiresIn,
+			...accessToken !== void 0 && {
+				access_token: accessToken,
+				expires_in: expiresIn
+			},
+			...idToken !== void 0 && { id_token: idToken },
 			userId: row.userId
 		};
 	}
+	/**
+	* OIDC discovery (Tier 2). Derives every endpoint from the signer's `issuer`
+	* (configured as `{origin}/auth`), so a relying `OidcProvider` configured with
+	* the same `issuer` resolves `/authorize`, `/token`, and `/jwks` automatically.
+	* 404 when no signer is wired (Tier-1-only deployment).
+	*/
+	discovery() {
+		const res = useResponse(current());
+		const signer = this.getIdTokenSigner();
+		if (!signer) {
+			res.status = 404;
+			return { error: "not_found" };
+		}
+		const iss = signer.issuer;
+		return {
+			issuer: iss,
+			authorization_endpoint: `${iss}/authorize`,
+			token_endpoint: `${iss}/token`,
+			jwks_uri: `${iss}/jwks`,
+			response_types_supported: ["code"],
+			grant_types_supported: ["authorization_code"],
+			subject_types_supported: ["public"],
+			id_token_signing_alg_values_supported: [signer.alg],
+			scopes_supported: [
+				"openid",
+				"email",
+				"profile"
+			],
+			code_challenge_methods_supported: ["S256"],
+			token_endpoint_auth_methods_supported: ["none", "client_secret_post"]
+		};
+	}
+	/** The signer's public JWKS (Tier 2). 404 when no signer is wired. */
+	jwks() {
+		const res = useResponse(current());
+		const signer = this.getIdTokenSigner();
+		if (!signer) {
+			res.status = 404;
+			return { error: "not_found" };
+		}
+		return signer.jwks();
+	}
 	/** Fail soft: 302 the validated client redirect with an `?error=` (+ echoed `state`). */
 	redirectError(redirectUri, error, state) {
 		const url = new URL(redirectUri);
@@ -5282,6 +6009,7 @@ __decorate([
 	__decorateParam(4, Query("code_challenge")),
 	__decorateParam(5, Query("code_challenge_method")),
 	__decorateParam(6, Query("scope")),
+	__decorateParam(7, Query("nonce")),
 	__decorateMetadata("design:type", Function),
 	__decorateMetadata("design:paramtypes", [
 		Object,
@@ -5290,6 +6018,7 @@ __decorate([
 		Object,
 		Object,
 		Object,
+		Object,
 		Object
 	]),
 	__decorateMetadata("design:returntype", Promise)
@@ -5302,6 +6031,20 @@ __decorate([
 	__decorateMetadata("design:paramtypes", [Object]),
 	__decorateMetadata("design:returntype", Promise)
 ], AuthorizeController.prototype, "token", null);
+__decorate([
+	Get(".well-known/openid-configuration"),
+	Public(),
+	__decorateMetadata("design:type", Function),
+	__decorateMetadata("design:paramtypes", []),
+	__decorateMetadata("design:returntype", Object)
+], AuthorizeController.prototype, "discovery", null);
+__decorate([
+	Get("jwks"),
+	Public(),
+	__decorateMetadata("design:type", Function),
+	__decorateMetadata("design:paramtypes", []),
+	__decorateMetadata("design:returntype", Object)
+], AuthorizeController.prototype, "jwks", null);
 AuthorizeController = __decorate([
 	Controller("auth"),
 	__decorateParam(1, Inject(CLIENT_REDIRECT_POLICY_TOKEN)),