@aooth/auth-moost 0.1.21 → 0.1.23

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { C as Select2faForm, E as TermsBumpForm, S as RemoveMfaConfirmForm, T as SignupForm, _ as PincodeForm, a as ConcurrencyLimitForm, c as EnrollConfirmForm, d as InviteForm, f as LoginCredentialsForm, g as PasswordReauthForm, h as MfaCodeForm, i as ChangePasswordForm, l as EnrollPickMethodForm, m as ManageMfaForm, n as AskPhoneForm, o as EmailIdentifierForm, r as AuthorizeConsentForm, s as EnrollAddressForm, t as AskEmailForm, u as EnrollTotpQrForm, v as ProveControlForm, w as SetPasswordForm, y as ProveControlOtpForm } from "./forms-uqegc32h.mjs";
+import { C as Select2faForm, D as TermsBumpForm, E as StepUpConfirmForm, S as RemoveMfaConfirmForm, T as SignupForm, _ as PincodeForm, a as ConcurrencyLimitForm, c as EnrollConfirmForm, d as InviteForm, f as LoginCredentialsForm, g as PasswordReauthForm, h as MfaCodeForm, i as ChangePasswordForm, l as EnrollPickMethodForm, m as ManageMfaForm, n as AskPhoneForm, o as EmailIdentifierForm, r as AuthorizeConsentForm, s as EnrollAddressForm, t as AskEmailForm, u as EnrollTotpQrForm, v as ProveControlForm, w as SetPasswordForm, y as ProveControlOtpForm } from "./forms-xaBNc5Ng.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";
@@ -797,6 +797,10 @@ const enrollTrioSteps = [
 		id: "enroll-totp-qr",
 		condition: (ctx) => ctx.mfaEnroll?.method === "totp" && !ctx.mfaEnroll.qrSeen
 	},
+	{
+		id: "enroll-send",
+		condition: (ctx) => (ctx.mfaEnroll?.method === "sms" || ctx.mfaEnroll?.method === "email") && !!ctx.mfaEnroll.address && !ctx.mfaEnroll.done && !ctx.mfaEnroll.preConfirmed && !ctx.pin
+	},
 	{
 		id: "enroll-confirm",
 		condition: (ctx) => !!ctx.mfaEnroll?.method && (ctx.mfaEnroll.method === "totp" ? !!ctx.mfaEnroll.qrSeen : !!ctx.mfaEnroll.address) && !ctx.mfaEnroll.done
@@ -811,21 +815,26 @@ const enrollTrioSteps = [
 * 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
+* re-verifying before letting the user change/remove a factor). It ADDS one
+* manage-only step the login loop doesn't have: `manage-stepup-confirm`, the
+* explicit-consent notice before the sms/email pincode dispatch (login is
+* mid-authentication, so its zero-click dispatch stays). 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.)
+* form (the `manage-stepup-confirm` consent cancel, `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. Every
+* `addMfaFlow` step after this sub-schema is gated off `ctx.aborted` (or on
+* `otp.verified`, which an aborted step-up never set), so the run falls
+* through 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,
@@ -842,6 +851,11 @@ const mfaStepUpLoop = [{
 			id: "select-2fa",
 			condition: (ctx) => !ctx.otp?.verified && !ctx.mfa?.method && (ctx.mfa?.enrolledMethods?.length ?? 0) > 1
 		},
+		{
+			id: "manage-stepup-confirm",
+			condition: (ctx) => !ctx.otp?.verified && (ctx.mfa?.method === "sms" || ctx.mfa?.method === "email") && !ctx.addMfa?.stepUpConfirmed && !ctx.pin
+		},
+		{ break: (ctx) => !!ctx.aborted },
 		{
 			condition: (ctx) => !ctx.otp?.verified && (ctx.mfa?.method === "sms" || ctx.mfa?.method === "email"),
 			steps: pincodeSendCheckPair
@@ -950,6 +964,7 @@ const DEFAULT_FORMS = {
 	manageMfa: ManageMfaForm,
 	removeMfaConfirm: RemoveMfaConfirmForm,
 	passwordReauth: PasswordReauthForm,
+	stepUpConfirm: StepUpConfirmForm,
 	select2fa: Select2faForm,
 	mfaCode: MfaCodeForm,
 	pincode: PincodeForm,
@@ -1414,6 +1429,68 @@ let AuthWorkflow = class AuthWorkflow {
 		};
 	}
 	/**
+	* Vouch that an MFA-enrolment address is verified-by-construction, skipping
+	* the pincode round-trip: `enroll-send` sends nothing and `enroll-confirm`
+	* writes the confirmed factor (+ `verifiedEmail` for email) with no
+	* code-entry pause. Asked once per dispatch with the staged transport +
+	* normalized address (ctx-first, extra positional args — same convention as
+	* `resolveOtpDisclosure`).
+	*
+	* Default `false` — every enrolment proves its address. The canonical
+	* override is the invite-accept case, where the user is inside the flow
+	* only because they redeemed a magic link delivered to that exact address
+	* minutes earlier (the same proof `activate-user` trusts to write
+	* `account.verifiedEmail`):
+	*
+	* ```ts
+	* protected resolveEnrollPreConfirmed(ctx: AuthWfCtx, method: MfaTransport, address: string) {
+	*   return !!ctx.accept && method === "email" && address === ctx.email;
+	* }
+	* ```
+	*
+	* Keep the equality check — the proof transfers ONLY to the address the
+	* magic link was delivered to; vouching for a different address the user
+	* typed would confirm an unproven inbox. Never asked for TOTP.
+	*/
+	resolveEnrollPreConfirmed(_ctx, _method, _address) {
+		return false;
+	}
+	/**
+	* Pin the enrolment address for an sms/email transport — the policy seam
+	* for deployments whose factor must be BOUND to an account record (e.g.
+	* staff MFA locked to the work mailbox so portal access dies with it at
+	* offboarding; a free-text form would let a self-service swap to a personal
+	* inbox defeat that control entirely). Asked by `enroll-address` BEFORE its
+	* form renders, with the staged transport (ctx-first, extra positional arg —
+	* same convention as `resolveEnrollPreConfirmed`).
+	*
+	* Returning a string stages it as the enrolment address (normalized via
+	* `normalizeMfaAddress`; the free-text form is SKIPPED — the same staging
+	* seam consumer pre-seeding uses, so the user is never shown a form whose
+	* only valid input is one known string). `'collect'` (the default) keeps
+	* the free-text form. A pinned address composes with the rest of the trio
+	* machinery untouched: `enroll-send` dispatches the pincode to it, and
+	* `resolveEnrollPreConfirmed` may vouch it (a deployment pinning to a
+	* verified-by-construction address gets the no-code path for free).
+	*
+	* ```ts
+	* protected async resolveEnrollAddress(ctx: AuthWfCtx, method: MfaTransport) {
+	*   if (method !== "email") return "collect";
+	*   const user = await this.users.getUser(ctx.subject!);
+	*   return (user as { email?: string }).email ?? "collect";
+	* }
+	* ```
+	*
+	* The returned address is trusted as-is (no `validateMfaAddress` pass) —
+	* the deployment is authoritative for its own records. An empty/blank
+	* return falls back to `'collect'`. For nuanced RULES on a user-typed
+	* address (domain allowlists, record comparisons) override the ctx-first
+	* {@link validateMfaAddress} instead.
+	*/
+	resolveEnrollAddress(_ctx, _method) {
+		return "collect";
+	}
+	/**
 	* Resolve the finalize policy. Reached from login.flow. `auditLogin` is
 	* dropped from the shape per §2 — audit moved out of the workflow layer.
 	*/
@@ -1527,6 +1604,40 @@ let AuthWorkflow = class AuthWorkflow {
 		return [];
 	}
 	/**
+	* Whether the manage-MFA step-up must collect explicit consent BEFORE
+	* dispatching its sms/email pincode (the `manage-stepup-confirm` pause:
+	* "To continue, we will send a verification code to ma•••@x"). Default
+	* `true` — nothing should email/text the user as a side effect of opening
+	* a manage dialog: a user who opened it by mistake (or just to look)
+	* closes it with zero codes consumed, no resend cooldown burnt. Override
+	* to `false` to restore the zero-click dispatch (the code is already in
+	* flight when the first form renders). Never asked for TOTP step-up
+	* (nothing is dispatched) and not consulted by the login flow (its
+	* challenge is mid-authentication, where zero-click is the norm).
+	*/
+	resolveStepUpConfirmBeforeSend(_ctx) {
+		return true;
+	}
+	/**
+	* What the user's authenticator app shows as the ACCOUNT half of
+	* "issuer: account" for a TOTP enrolment (the issuer half is
+	* `resolveMfaPolicy().issuer` / `opts.totpIssuer`). Cosmetic only — never
+	* used for lookup — but it is how a user with several entries tells
+	* accounts apart, and it is encoded into the `otpauth://` URI at
+	* secret-provisioning time, so it lives in the authenticator FOREVER
+	* (re-labeling requires re-enrolment). Default prefers a human-readable
+	* identifier the flow already carries (`ctx.email` — invite/recovery/
+	* signup) and otherwise loads the user's `username`; the stable-uuid
+	* `ctx.subject` is the last resort. Override for a richer label (display
+	* name, tenant-qualified email, …).
+	*/
+	resolveTotpAccountLabel(ctx) {
+		if (ctx.email) return ctx.email;
+		if (!ctx.subject) return "";
+		const subject = ctx.subject;
+		return this.users.getUser(subject).then((u) => u.username || subject);
+	}
+	/**
 	* 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
@@ -1837,7 +1948,11 @@ let AuthWorkflow = class AuthWorkflow {
 			if (sub) pub.mfaEnroll = sub;
 		}
 		if (ctx.addMfa) {
-			const sub = pickDefined(ctx.addMfa, ["candidates", "locked"]);
+			const sub = pickDefined(ctx.addMfa, [
+				"candidates",
+				"locked",
+				"removeBlocked"
+			]);
 			if (sub) pub.manage = sub;
 		}
 		if (ctx.defaults) {
@@ -1968,8 +2083,8 @@ let AuthWorkflow = class AuthWorkflow {
 	}
 	/**
 	* Send an enrolment pincode and stamp `ctx.pincode.sentTo` with the masked
-	* recipient. Shared by `enrollAddress` (initial dispatch) and the resend
-	* path inside `enrollConfirm`.
+	* recipient. Reached only through {@link mintAndSendEnrollPincode}; kept
+	* separate as the delivery-only override seam.
 	*/
 	async sendEnrollPincode(ctx, address, code) {
 		const pincode = ctx.pincode ??= {};
@@ -1984,6 +2099,44 @@ let AuthWorkflow = class AuthWorkflow {
 		});
 	}
 	/**
+	* The single enrol-dispatch implementation: mint a fresh pin, arm the
+	* resend cooldown + the code-length form hint, and deliver the code.
+	* Shared by `enrollSend` (initial dispatch) and the resend arm inside
+	* `enrollConfirm`, so the arming policy cannot drift between first send
+	* and resend.
+	*/
+	async mintAndSendEnrollPincode(ctx, 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, address, code);
+	}
+	/**
+	* Idempotent TOTP secret provisioning into wf-state ONLY (the QR renders
+	* from `public.mfaEnroll.secret/uri`; the user record is written on confirm
+	* — write-on-confirm). The single implementation behind BOTH provisioning
+	* sites — `enroll-pick-method`'s auto-pick/picker tail and `enroll-totp-qr`
+	* (covers the manage add/change path where the picker is skipped) — so the
+	* account label baked into the `otpauth://` URI cannot drift between them.
+	* The label comes from {@link resolveTotpAccountLabel} (human-readable
+	* default); blank falls back to the subject uuid so the URI always carries
+	* SOME account discriminator.
+	*/
+	provisionTotpSecret(ctx) {
+		const m = ctx.mfaEnroll ??= {};
+		if (m.method !== "totp" || m.secret) return void 0;
+		const issuer = ctx.mfaPolicy?.issuer ?? this.opts.totpIssuer;
+		const secret = generateTotpSecret();
+		const apply = (label) => {
+			m.secret = secret;
+			m.uri = generateTotpUri(secret, issuer, label.trim() || (ctx.subject ?? ""));
+		};
+		const label = this.resolveTotpAccountLabel(ctx);
+		if (label instanceof Promise) return label.then(apply);
+		return apply(label);
+	}
+	/**
 	* 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}.
@@ -2000,6 +2153,7 @@ let AuthWorkflow = class AuthWorkflow {
 			delete m.secret;
 			delete m.uri;
 			delete m.qrSeen;
+			delete m.preConfirmed;
 		}
 		delete ctx.pin;
 		delete ctx.pinExpire;
@@ -2012,8 +2166,24 @@ let AuthWorkflow = class AuthWorkflow {
 	* 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.
+	*
+	* Ctx-first and async-capable, so record-based rules need no ctx-stash
+	* workaround — an override can load the account and compare directly
+	* (e.g. domain-allowlist the typed inbox, or require it to match a
+	* record field). To PIN the address outright — never show the free-text
+	* form at all — use {@link resolveEnrollAddress} instead; this hook is for
+	* nuanced rules on what the user typed.
+	*
+	* ```ts
+	* protected async validateMfaAddress(ctx: AuthWfCtx, method: MfaTransport, value: string) {
+	*   if (method === "email" && !value.trim().toLowerCase().endsWith("@corp.example")) {
+	*     return "Use your corporate email address";
+	*   }
+	*   return super.validateMfaAddress(ctx, method, value);
+	* }
+	* ```
 	*/
-	validateMfaAddress(method, value) {
+	validateMfaAddress(_ctx, 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";
@@ -2837,10 +3007,22 @@ let AuthWorkflow = class AuthWorkflow {
 	/**
 	* 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.
+	* removed → changed (`replace` + done) → added (done) → blocked
+	* (un-removable operation aborted by `confirm-remove-mfa`) →
+	* nothing-available (zero candidates, never had to step-up) → cancelled.
 	*/
 	finishAddMfa(ctx) {
+		useWfFinished().set({
+			type: "data",
+			value: this.buildAddMfaFinishEnvelope(ctx)
+		});
+	}
+	/**
+	* `finish-add-mfa`'s envelope construction, extracted pure so the outcome
+	* priority (removed → changed → added → blocked → nothing-available →
+	* cancelled) is unit-testable without a wf event context.
+	*/
+	buildAddMfaFinishEnvelope(ctx) {
 		const labels = {
 			totp: "Authenticator app",
 			email: "Email code",
@@ -2884,6 +3066,17 @@ let AuthWorkflow = class AuthWorkflow {
 				text: `${labels[method]} added.`
 			}
 		};
+		else if (addMfa?.blocked) envelope = {
+			finished: true,
+			data: {
+				added: false,
+				reason: addMfa.blocked
+			},
+			message: {
+				level: "info",
+				text: addMfa.blocked === "last-required-factor" ? "You must keep at least one two-factor method, so this one can't be removed." : "That method can't be changed here."
+			}
+		};
 		else if (candidates.length === 0 && !addMfa?.stepUpRequired) envelope = {
 			finished: true,
 			data: {
@@ -2906,10 +3099,7 @@ let AuthWorkflow = class AuthWorkflow {
 				text: "No changes were made to your two-factor methods."
 			}
 		};
-		useWfFinished().set({
-			type: "data",
-			value: envelope
-		});
+		return envelope;
 	}
 	/**
 	* Resolve which transports the user may NOT change/remove via the manage flow
@@ -2936,6 +3126,46 @@ let AuthWorkflow = class AuthWorkflow {
 		(ctx.addMfa ??= {}).stepUpDone = true;
 	}
 	/**
+	* Manage-MFA step-up consent — pauses on `StepUpConfirmForm` ("To continue,
+	* we will send a verification code to ma•••@x") BEFORE `pincode-send`
+	* dispatches the step-up code, so opening the manage dialog never consumes
+	* a code send as a side effect. Fires only on the auto-picked paths (single
+	* factor, or default factor) — an explicit `select-2fa` pick already
+	* counts as consent (`select2fa` sets `stepUpConfirmed`). `Continue`
+	* consents and the SAME engine pass mints + sends; `useDifferentMethod`
+	* re-opens the picker; `cancel` aborts with nothing dispatched (the
+	* schema's `{ break: aborted }` right after this step keeps the pair from
+	* sending the declined code). Gated by {@link resolveStepUpConfirmBeforeSend}
+	* (default on) — an opt-out marks consent and falls straight through.
+	*/
+	manageStepUpConfirm(ctx) {
+		const result = this.resolveStepUpConfirmBeforeSend(ctx);
+		if (result instanceof Promise) return result.then((r) => this.applyStepUpConfirm(ctx, r));
+		return this.applyStepUpConfirm(ctx, result);
+	}
+	/** `manage-stepup-confirm` tail — opt-out fall-through or the consent pause. */
+	applyStepUpConfirm(ctx, confirmBeforeSend) {
+		const addMfa = ctx.addMfa ??= {};
+		if (!confirmBeforeSend) {
+			addMfa.stepUpConfirmed = true;
+			return;
+		}
+		const wf = this.useAtscriptWfPublic(ctx, this.opts.forms.stepUpConfirm);
+		const action = wf.resolveAction();
+		if (action === "cancel") {
+			ctx.aborted = true;
+			return;
+		}
+		if (action === "useDifferentMethod") {
+			const mfa = ctx.mfa ??= {};
+			mfa.ignoreDefault = true;
+			delete mfa.method;
+			return;
+		}
+		wf.resolveInput();
+		addMfa.stepUpConfirmed = 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`).
@@ -2960,6 +3190,17 @@ let AuthWorkflow = class AuthWorkflow {
 		(ctx.otp ??= {}).verified = true;
 	}
 	/**
+	* The keep-at-least-one rule: removing the user's LAST confirmed factor under
+	* a `required` policy can never succeed. The single source for the predicate
+	* `manage-menu` mirrors into `addMfa.removeBlocked` (to drop the Remove option)
+	* AND `confirm-remove-mfa` re-checks before its pause (defence in depth) — so
+	* a policy change (e.g. "keep at least two", or a backup-codes exception)
+	* lands in one place, not two copies that can drift.
+	*/
+	isLastRequiredFactor(ctx) {
+		return (ctx.mfa?.enrolledMethods?.length ?? 0) <= 1 && ctx.mfaPolicy?.mode === "required";
+	}
+	/**
 	* 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
@@ -2978,6 +3219,8 @@ let AuthWorkflow = class AuthWorkflow {
 			ctx.aborted = true;
 			return;
 		}
+		if (this.isLastRequiredFactor(ctx)) addMfa.removeBlocked = true;
+		else delete addMfa.removeBlocked;
 		const wf = this.useAtscriptWfPublic(ctx, this.opts.forms.manageMfa);
 		if (wf.resolveAction() === "cancel") {
 			ctx.aborted = true;
@@ -2992,6 +3235,7 @@ let AuthWorkflow = class AuthWorkflow {
 		} 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" } });
+			if (action === "remove" && addMfa.removeBlocked) throw this.throwPublic(ctx, wf, { formMessage: "You must keep at least one two-factor method." });
 		} else throw this.throwPublic(ctx, wf, { errors: { operation: "Choose an option" } });
 		addMfa.action = action;
 		addMfa.target = target;
@@ -3008,22 +3252,35 @@ let AuthWorkflow = class AuthWorkflow {
 	/**
 	* 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).
+	* set and the keep-at-least-one rule (LAST confirmed factor under a
+	* `required` policy) BEFORE the pause — and an un-removable state aborts to
+	* the `finish-add-mfa` terminal (reason on `addMfa.blocked`) instead of
+	* pausing: `manage-menu` filters these operations out, so arriving here
+	* blocked means a stale/crafted route, and a retryable form whose only
+	* submit re-throws the same guard would be a dead-end loop (the manage
+	* forms hide their built-in cancel — the host owns it).
 	*/
 	async confirmRemoveMfa(ctx) {
 		this.requireSubject(ctx);
 		const username = ctx.subject;
 		const addMfa = ctx.addMfa ??= {};
 		const target = addMfa.target;
+		const enrolled = ctx.mfa?.enrolledMethods ?? [];
+		if ((addMfa.locked ?? []).includes(target)) {
+			addMfa.blocked = "method-locked";
+			ctx.aborted = true;
+			return;
+		}
+		if (this.isLastRequiredFactor(ctx)) {
+			addMfa.blocked = "last-required-factor";
+			ctx.aborted = true;
+			return;
+		}
 		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));
@@ -3247,6 +3504,7 @@ let AuthWorkflow = class AuthWorkflow {
 			}
 		}
 		mfa.method = picked.kind;
+		if (ctx.addMfa) ctx.addMfa.stepUpConfirmed = true;
 		mfa.saveAsDefault = Boolean(input.saveAsDefault);
 		if (mfa.saveAsDefault && ctx.subject) await this.users.setDefaultMfaMethod(ctx.subject, picked.methodName);
 	}
@@ -3395,7 +3653,6 @@ let AuthWorkflow = class AuthWorkflow {
 	*/
 	enrollPickMethod(ctx) {
 		this.requireSubject(ctx);
-		const username = ctx.subject;
 		const transports = ctx.mfaPolicy?.availableTransports ?? [];
 		const m = ctx.mfaEnroll ??= {};
 		const mode = m.mode === "manage" ? "manage" : ctx.mfaPolicy?.mode === "required" ? "required" : "optional";
@@ -3426,25 +3683,45 @@ let AuthWorkflow = class AuthWorkflow {
 			if (!m.availableTransports.includes(picked)) throw this.throwPublic(ctx, wf, { errors: { method: "Unknown method" } });
 			m.method = picked;
 		}
-		if (m.method === "totp" && !m.secret) {
-			const issuer = ctx.mfaPolicy?.issuer ?? this.opts.totpIssuer;
-			const secret = generateTotpSecret();
-			m.secret = secret;
-			m.uri = generateTotpUri(secret, issuer, username);
-		}
+		return this.provisionTotpSecret(ctx);
+	}
+	/**
+	* Unified MFA-enrol phase 2 (collect sms/email address). Not invoked for
+	* totp. Asks {@link resolveEnrollAddress} FIRST — a deployment that pins
+	* the address (factor bound to an account record) stages it here and the
+	* free-text form never renders; this single call site covers every trio
+	* path (picker, auto-pick, manage add/replace pre-seed), and `enroll-send`
+	* dispatches to the pinned address in the same engine pass. Otherwise
+	* (`'collect'`) handles `skip` (opt-in) / `cancel` (manage) /
+	* `useDifferentMethod`, validates the typed address server-side via the
+	* ctx-first {@link validateMfaAddress} (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`. Collection ONLY: the pincode dispatch lives in
+	* `enroll-send` (same engine pass, no extra round-trip), so a consumer
+	* pre-seeding `mfaEnroll.address` — which skips this whole step via its
+	* schema condition — still gets exactly one code.
+	*/
+	enrollAddress(ctx) {
+		this.requireSubject(ctx);
+		const methodName = (ctx.mfaEnroll ??= {}).method;
+		const pinned = this.resolveEnrollAddress(ctx, methodName);
+		if (pinned instanceof Promise) return pinned.then((p) => this.collectEnrollAddress(ctx, methodName, p));
+		return this.collectEnrollAddress(ctx, methodName, pinned);
 	}
 	/**
-	* Unified MFA-enrol phase 2 (collect sms/email address + send pincode).
-	* 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`.
+	* `enroll-address` tail — stage a pinned address, or run the free-text
+	* collect pause (skip/cancel/useDifferentMethod triage + ctx-first
+	* validation + write-on-confirm staging).
 	*/
-	async enrollAddress(ctx) {
-		this.requireSubject(ctx);
+	collectEnrollAddress(ctx, methodName, pinned) {
 		const m = ctx.mfaEnroll ??= {};
+		if (pinned !== "collect" && pinned.trim()) {
+			m.address = this.normalizeMfaAddress(methodName, pinned.trim());
+			return;
+		}
 		const mode = m.mode ?? "optional";
 		const wf = this.useAtscriptWfPublic(ctx, this.opts.forms.enrollAddress);
 		const action = wf.resolveAction();
@@ -3462,16 +3739,35 @@ let AuthWorkflow = class AuthWorkflow {
 			return;
 		}
 		const input = wf.resolveInput();
-		const methodName = m.method;
-		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, address, code);
+		const stage = (addrErr) => {
+			if (addrErr) throw this.throwPublic(ctx, wf, { errors: { address: addrErr } });
+			m.address = this.normalizeMfaAddress(methodName, input.address);
+		};
+		const addrErr = this.validateMfaAddress(ctx, methodName, input.address);
+		if (addrErr instanceof Promise) return addrErr.then(stage);
+		return stage(addrErr);
+	}
+	/**
+	* Unified MFA-enrol dispatch (sms/email only) — the trio's ONLY pincode
+	* send. A separate step (the canonical "send if no pin" gate, mirroring
+	* `pincode-send`) so both address paths share one dispatch site: collected
+	* by `enroll-address`, or pre-seeded by a consumer (which skips
+	* `enroll-address` entirely — previously skipping the dispatch with it and
+	* stranding the user on a code form no code was sent for). Asks
+	* `resolveEnrollPreConfirmed` first: a verified-by-construction address
+	* (e.g. the invite email the magic link just proved) skips the round-trip —
+	* `enroll-confirm` then writes the factor without pausing.
+	*/
+	async enrollSend(ctx) {
+		this.requireSubject(ctx);
+		const m = ctx.mfaEnroll ??= {};
+		const method = m.method;
+		const address = m.address;
+		if (await this.resolveEnrollPreConfirmed(ctx, method, address)) {
+			m.preConfirmed = true;
+			return;
+		}
+		await this.mintAndSendEnrollPincode(ctx, address);
 	}
 	/**
 	* MFA-enrol TOTP QR step — shown on its OWN pause between method-pick and
@@ -3486,14 +3782,8 @@ let AuthWorkflow = class AuthWorkflow {
 	*/
 	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();
-			m.secret = secret;
-			m.uri = generateTotpUri(secret, issuer, username);
-		}
+		await this.provisionTotpSecret(ctx);
 		const wf = this.useAtscriptWfPublic(ctx, this.opts.forms.enrollTotpQr);
 		if (this.handleEnrollExit(ctx, wf.resolveAction())) return void 0;
 		wf.resolveInput();
@@ -3512,8 +3802,11 @@ let AuthWorkflow = class AuthWorkflow {
 	*/
 	async enrollConfirm(ctx) {
 		this.requireSubject(ctx);
-		const username = ctx.subject;
 		const m = ctx.mfaEnroll ??= {};
+		if (m.preConfirmed && m.method !== "totp" && m.address) {
+			await this.confirmEnrolledFactor(ctx);
+			return;
+		}
 		const wf = this.useAtscriptWfPublic(ctx, this.opts.forms.enrollConfirm);
 		const action = wf.resolveAction();
 		if (this.handleEnrollExit(ctx, action)) return void 0;
@@ -3524,11 +3817,7 @@ let AuthWorkflow = class AuthWorkflow {
 				const waitSec = Math.ceil((cooldown - Date.now()) / 1e3);
 				throw this.throwPublic(ctx, wf, { formMessage: `Please wait ${waitSec}s before requesting another code` });
 			}
-			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, m.address, code);
+			await this.mintAndSendEnrollPincode(ctx, m.address);
 			return;
 		}
 		const input = wf.resolveInput();
@@ -3538,8 +3827,23 @@ let AuthWorkflow = class AuthWorkflow {
 			const pinErr = this.verifyPin(ctx, input.code);
 			if (pinErr) throw this.throwPublic(ctx, wf, { errors: pinErr });
 		}
+		await this.confirmEnrolledFactor(ctx);
+	}
+	/**
+	* `enroll-confirm`'s write-on-confirm tail (uniform for ADD and REPLACE, all
+	* transports): the staged value (sms/email `address`, totp `secret`) is now
+	* proven — by a verified pincode/TOTP code, or vouched by
+	* `resolveEnrollPreConfirmed` — so upsert it as confirmed. `addMfaMethod`
+	* replaces any row of the same name, so a REPLACE atomically swaps in the
+	* new value with no pre-confirm clobber window, and an ADD creates the row
+	* fresh.
+	*/
+	async confirmEnrolledFactor(ctx) {
+		this.requireSubject(ctx);
+		const username = ctx.subject;
+		const m = ctx.mfaEnroll ??= {};
 		const methodName = m.method;
-		const value = m.method === "totp" ? m.secret : m.address;
+		const value = methodName === "totp" ? m.secret : m.address;
 		await this.withStoreErrorTranslation(() => this.users.addMfaMethod(username, {
 			name: methodName,
 			value,
@@ -4578,12 +4882,19 @@ let AuthWorkflow = class AuthWorkflow {
 	* 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
+	*    back to the account password (`stepUpMode==='password'`). The sms/email
+	*    challenge collects explicit consent (`manage-stepup-confirm`) BEFORE
+	*    dispatching its pincode — opening the dialog never sends a code as a
+	*    side effect (see `resolveStepUpConfirmBeforeSend`). 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.
+	*    target; pre-seeds `mfaEnroll.method` for add/change. Un-offerable
+	*    operations never render: locked transports drop their Change/Remove
+	*    options, and the LAST factor under a `required` policy drops Remove
+	*    (`removeBlocked`) — `confirm-remove-mfa` aborts to the finish terminal
+	*    if a blocked remove arrives anyway (no retryable dead-end form).
 	* 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
@@ -4962,6 +5273,15 @@ __decorate([
 	__decorateMetadata("design:paramtypes", [Object]),
 	__decorateMetadata("design:returntype", void 0)
 ], AuthWorkflow.prototype, "manageStepUpDone", null);
+__decorate([
+	Step("manage-stepup-confirm"),
+	ArbacResource("auth.add-mfa"),
+	ArbacAction("self"),
+	__decorateParam(0, WorkflowParam("context")),
+	__decorateMetadata("design:type", Function),
+	__decorateMetadata("design:paramtypes", [Object]),
+	__decorateMetadata("design:returntype", Object)
+], AuthWorkflow.prototype, "manageStepUpConfirm", null);
 __decorate([
 	Step("manage-password-reauth"),
 	ArbacResource("auth.add-mfa"),
@@ -5077,8 +5397,16 @@ __decorate([
 	__decorateParam(0, WorkflowParam("context")),
 	__decorateMetadata("design:type", Function),
 	__decorateMetadata("design:paramtypes", [Object]),
-	__decorateMetadata("design:returntype", Promise)
+	__decorateMetadata("design:returntype", Object)
 ], AuthWorkflow.prototype, "enrollAddress", null);
+__decorate([
+	Step("enroll-send"),
+	Public(),
+	__decorateParam(0, WorkflowParam("context")),
+	__decorateMetadata("design:type", Function),
+	__decorateMetadata("design:paramtypes", [Object]),
+	__decorateMetadata("design:returntype", Promise)
+], AuthWorkflow.prototype, "enrollSend", null);
 __decorate([
 	Step("enroll-totp-qr"),
 	Public(),
@@ -5572,14 +5900,13 @@ __decorate([
 			id: "manage-password-reauth",
 			condition: (ctx) => !!ctx.addMfa?.stepUpRequired && ctx.addMfa?.stepUpMode === "password" && !ctx.otp?.verified
 		},
-		{ break: (ctx) => !!ctx.aborted },
 		{
 			id: "manage-stepup-done",
-			condition: (ctx) => !!ctx.addMfa?.stepUpRequired && !!ctx.otp?.verified && !ctx.addMfa?.stepUpDone
+			condition: (ctx) => !ctx.aborted && !!ctx.addMfa?.stepUpRequired && !!ctx.otp?.verified && !ctx.addMfa?.stepUpDone
 		},
 		{
 			id: "manage-menu",
-			condition: (ctx) => !!ctx.addMfa?.stepUpRequired && !ctx.addMfa?.action
+			condition: (ctx) => !ctx.aborted && !!ctx.addMfa?.stepUpRequired && !ctx.addMfa?.action
 		},
 		{
 			id: "confirm-remove-mfa",