@aooth/auth-moost 0.1.22 → 0.1.24

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";
@@ -815,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,
@@ -846,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
@@ -954,6 +964,7 @@ const DEFAULT_FORMS = {
 	manageMfa: ManageMfaForm,
 	removeMfaConfirm: RemoveMfaConfirmForm,
 	passwordReauth: PasswordReauthForm,
+	stepUpConfirm: StepUpConfirmForm,
 	select2fa: Select2faForm,
 	mfaCode: MfaCodeForm,
 	pincode: PincodeForm,
@@ -1229,6 +1240,47 @@ let AuthWorkflow = class AuthWorkflow {
 		});
 	}
 	/**
+	* A user just authenticated and a session is being established — interactive
+	* login, federated (SSO) login, OR invite/signup/recovery auto-login. Fired
+	* from the single `record-login` funnel, AFTER `account.lastLogin` is stamped
+	* and BEFORE the session/code is delivered, so a throw aborts the login
+	* atomically (no half-issued session). `ctx.subject` is set; read
+	* `ctx.isFirstLogin` to distinguish the very first sign-in, `ctx.oauth` for
+	* federated context. Does NOT fire for the no-session "fresh-login" finalize
+	* (where the user is redirected to sign in separately).
+	*/
+	afterLogin(_ctx) {}
+	/**
+	* An invitee finished accepting their invite — account activated — whether or
+	* not the flow auto-logged-them-in. Fires once, before the finalize terminal.
+	* (An auto-login invite ALSO fires {@link afterLogin}.)
+	*/
+	afterInvitationAccepted(_ctx) {}
+	/**
+	* A self-signup account was created + activated (post password-set, post
+	* activate). Fires once, before the auto-login finalize. (Signup always
+	* auto-logins, so {@link afterLogin} fires too.)
+	*/
+	afterSignup(_ctx) {}
+	/**
+	* A recovery password reset completed. Fires once even when an `admin-only`
+	* lock survived the reset (the password DID change) — so it runs ahead of the
+	* still-locked guard. An auto-login recovery ALSO fires {@link afterLogin}.
+	*/
+	afterPasswordReset(_ctx) {}
+	/**
+	* An already-authenticated user changed their own password (change-password
+	* flow). NOT a login — the session is rotated, not established — so
+	* {@link afterLogin} does NOT fire.
+	*/
+	afterPasswordChanged(_ctx) {}
+	/**
+	* A user added, changed, or removed an MFA factor (add-mfa flow). NOT fired
+	* on a cancel / nothing-to-do finish. The user KEEPS their session (no
+	* re-issue), so {@link afterLogin} does NOT fire.
+	*/
+	afterMfaChanged(_ctx) {}
+	/**
 	* Return the list of selectable role identifiers for the admin invite form.
 	* Mirrors the prior `InviteWorkflow.getAvailableRoles()` consumer hook —
 	* `undefined` (default) means no whitelist is enforced. Read by
@@ -1445,6 +1497,41 @@ let AuthWorkflow = class AuthWorkflow {
 		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.
 	*/
@@ -1558,6 +1645,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
@@ -1868,7 +1989,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) {
@@ -2029,6 +2154,30 @@ let AuthWorkflow = class AuthWorkflow {
 		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}.
@@ -2058,8 +2207,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";
@@ -2240,6 +2405,7 @@ let AuthWorkflow = class AuthWorkflow {
 		try {
 			const result = await this.users.login(input.username, input.password, this.lockoutOverride(ctx));
 			ctx.subject = result.user.id;
+			ctx.loginRecorded = true;
 			swapStrategy("store");
 			if (ctx.guards?.passwordInitial && result.user.password.isInitial) ctx.isPasswordInitial = true;
 			if (ctx.guards?.passwordExpiry && this.users.isPasswordExpired(result.user)) ctx.isPasswordExpired = true;
@@ -2879,14 +3045,30 @@ let AuthWorkflow = class AuthWorkflow {
 			value: envelope,
 			cookies: auth.buildFinishedCookies(issue)
 		});
+		await this.afterPasswordChanged(ctx);
 	}
 	/**
 	* 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)
+		});
+		if (!ctx.addMfa?.removed && !(ctx.mfaEnroll?.done && ctx.mfaEnroll?.method)) return void 0;
+		const hook = this.afterMfaChanged(ctx);
+		return hook instanceof Promise ? hook.then(() => void 0) : void 0;
+	}
+	/**
+	* `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",
@@ -2930,6 +3112,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: {
@@ -2952,10 +3145,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
@@ -2982,6 +3172,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`).
@@ -3006,6 +3236,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
@@ -3024,6 +3265,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;
@@ -3038,6 +3281,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;
@@ -3054,22 +3298,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));
@@ -3293,6 +3550,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);
 	}
@@ -3441,7 +3699,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";
@@ -3472,28 +3729,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. 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`. 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.
+	* 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);
+	}
+	/**
+	* `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).
+	*/
+	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();
@@ -3511,10 +3785,13 @@ 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 } });
-		m.address = this.normalizeMfaAddress(methodName, input.address);
+		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
@@ -3551,14 +3828,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();
@@ -3852,6 +4123,71 @@ let AuthWorkflow = class AuthWorkflow {
 		await this.users.unlockAccount(ctx.subject);
 	}
 	/**
+	* The SINGLE login-completion funnel. Every flow that establishes an
+	* authenticated session routes through here — placed in each login schema
+	* right after the guards and BEFORE the delivery terminal (`issue` /
+	* `mint-authz-code` / `finalize-auto-login`) — so a login can never be
+	* delivered without passing this point. Two uniform jobs:
+	*   1. Stamp `account.lastLogin` exactly once (the sole workflow writer of it).
+	*   2. Fire the `afterLogin` customer hook.
+	*
+	* Idempotent per run via `ctx.loginRecorded`: the password `credentials` path
+	* already stamped eagerly through `users.login()` and latched the flag, so the
+	* stamp NO-OPS there (no double write) — but `afterLogin` still fires, so the
+	* hook runs exactly once for password logins too. Federated (`sso-callback`)
+	* and auto-login (invite/signup/recovery) paths never call `login()`, so this
+	* is their sole stamp. Self-gates on `ctx.subject`. Runs AFTER
+	* `prepare-semantic-flags` derived `isFirstLogin`, so a genuine first
+	* federated login still observes `isFirstLogin === true`.
+	*
+	* A throw (from the stamp or the hook) aborts the flow BEFORE delivery, so the
+	* login fails atomically — no half-issued session.
+	*/
+	recordLogin(ctx) {
+		if (!ctx.subject) return void 0;
+		if (!ctx.loginRecorded) {
+			ctx.loginRecorded = true;
+			return this.users.recordLogin(ctx.subject).then(() => this.afterLogin(ctx)).then(() => void 0);
+		}
+		const hook = this.afterLogin(ctx);
+		return hook instanceof Promise ? hook.then(() => void 0) : void 0;
+	}
+	/**
+	* Recovery-only guard, extracted from the finalize terminals so they stay pure
+	* delivery. An `admin-only` lockout never self-unlocks, so a reset that left
+	* the account frozen must NOT be confirmed-as-success OR auto-logged-in
+	* (minting tokens would defeat the very freeze). When still locked it emits the
+	* warn terminal and sets `ctx.aborted`, so the schema's following `{ break }`
+	* skips BOTH the `record-login` funnel and the finalize terminals — a frozen
+	* account is never stamped or logged in. The schema gates this on
+	* `ctx.lockout?.mode === "admin-only"` (the only mode that can reach finalize
+	* still locked: self-service ran `unlock-account`; temporary auto-expires).
+	*/
+	async recoveryLockCheck(ctx) {
+		if (await this.recoveryLeftAccountLocked(ctx)) {
+			this.finishRecoveryReset(ctx, true);
+			ctx.aborted = true;
+		}
+	}
+	/**
+	* Thin dispatcher steps for the flow-specific lifecycle hooks. Each is its own
+	* schema step (rather than an in-terminal call) because its flow's finalize
+	* terminals are SHARED across flows (`finalize-auto-login` serves invite +
+	* recovery + signup; `finalize-fresh-login` serves invite + recovery), so a
+	* dedicated step in the flow-specific schema fires the right hook without
+	* ctx-discrimination inside a shared terminal. Named `fire*` so the overridable
+	* `after*` hooks keep the clean public name.
+	*/
+	fireInvitationAccepted(ctx) {
+		return this.afterInvitationAccepted(ctx);
+	}
+	fireSignup(ctx) {
+		return this.afterSignup(ctx);
+	}
+	firePasswordReset(ctx) {
+		return this.afterPasswordReset(ctx);
+	}
+	/**
 	* Issue access + refresh tokens via `auth.issue`. Stashes the login
 	* response envelope on `useWfFinished` so downstream `redirect` can
 	* override with a redirect envelope while preserving the cookies.
@@ -3871,7 +4207,7 @@ let AuthWorkflow = class AuthWorkflow {
 				...cookies,
 				[name]: {
 					value,
-					options: auth.cookieAttrs({ maxAge: ttlMs / 1e3 })
+					options: auth.cookieAttrs({ maxAge: ttlMs })
 				}
 			};
 		};
@@ -4083,9 +4419,6 @@ let AuthWorkflow = class AuthWorkflow {
 			(ctx.completion ??= {}).redirectUrl = target;
 			return;
 		}
-		if (ctx.lockout?.mode === "admin-only") return this.recoveryLeftAccountLocked(ctx).then((locked) => {
-			this.finishRecoveryReset(ctx, locked);
-		});
 		this.finishRecoveryReset(ctx, false);
 	}
 	/**
@@ -4147,17 +4480,20 @@ let AuthWorkflow = class AuthWorkflow {
 		(ctx.completion ??= {}).redirectUrl = target;
 	}
 	/**
-	* Auto-login finalize — invite + recovery. Issues access + refresh tokens
-	* and stashes the login response envelope on `useWfFinished`. Invite
-	* preserves any `message` set by an earlier terminal (`confirmation`) so
-	* the SPA paints the confirmation text alongside the tokens (WF-INVITE-020).
+	* Auto-login finalize — invite + recovery + signup. PURE delivery: issues
+	* access + refresh tokens and stashes the login response envelope on
+	* `useWfFinished`. Invite preserves any `message` set by an earlier terminal
+	* (`confirmation`) so the SPA paints the confirmation text alongside the
+	* tokens (WF-INVITE-020).
+	*
+	* It records NOTHING and guards NOTHING: `account.lastLogin` + the
+	* `afterLogin` hook are owned by the upstream `record-login` funnel step, and
+	* the admin-only-survived-lock guard by the upstream `recovery-lock-check`
+	* step — both of which `{ break }`/gate this step out when they apply, so a
+	* still-frozen account never reaches here.
 	*/
 	async finalizeAutoLogin(ctx) {
 		this.requireSubject(ctx);
-		if (ctx.lockout?.mode === "admin-only" && await this.recoveryLeftAccountLocked(ctx)) {
-			this.finishRecoveryReset(ctx, true);
-			return;
-		}
 		const issue = await this.issueForContext(ctx);
 		const auth = useAuth();
 		const previousMessage = (useWfFinished().get()?.value)?.message;
@@ -4657,12 +4993,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
@@ -5021,7 +5364,7 @@ __decorate([
 	__decorateParam(0, WorkflowParam("context")),
 	__decorateMetadata("design:type", Function),
 	__decorateMetadata("design:paramtypes", [Object]),
-	__decorateMetadata("design:returntype", void 0)
+	__decorateMetadata("design:returntype", Object)
 ], AuthWorkflow.prototype, "finishAddMfa", null);
 __decorate([
 	Step("prepare-locked-mfa-transports"),
@@ -5041,6 +5384,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"),
@@ -5156,7 +5508,7 @@ __decorate([
 	__decorateParam(0, WorkflowParam("context")),
 	__decorateMetadata("design:type", Function),
 	__decorateMetadata("design:paramtypes", [Object]),
-	__decorateMetadata("design:returntype", void 0)
+	__decorateMetadata("design:returntype", Object)
 ], AuthWorkflow.prototype, "enrollAddress", null);
 __decorate([
 	Step("enroll-send"),
@@ -5270,6 +5622,46 @@ __decorate([
 	__decorateMetadata("design:paramtypes", [Object]),
 	__decorateMetadata("design:returntype", Promise)
 ], AuthWorkflow.prototype, "unlockAccount", null);
+__decorate([
+	Step("record-login"),
+	Public(),
+	__decorateParam(0, WorkflowParam("context")),
+	__decorateMetadata("design:type", Function),
+	__decorateMetadata("design:paramtypes", [Object]),
+	__decorateMetadata("design:returntype", Object)
+], AuthWorkflow.prototype, "recordLogin", null);
+__decorate([
+	Step("recovery-lock-check"),
+	Public(),
+	__decorateParam(0, WorkflowParam("context")),
+	__decorateMetadata("design:type", Function),
+	__decorateMetadata("design:paramtypes", [Object]),
+	__decorateMetadata("design:returntype", Promise)
+], AuthWorkflow.prototype, "recoveryLockCheck", null);
+__decorate([
+	Step("after-invitation-accepted"),
+	Public(),
+	__decorateParam(0, WorkflowParam("context")),
+	__decorateMetadata("design:type", Function),
+	__decorateMetadata("design:paramtypes", [Object]),
+	__decorateMetadata("design:returntype", Object)
+], AuthWorkflow.prototype, "fireInvitationAccepted", null);
+__decorate([
+	Step("after-signup"),
+	Public(),
+	__decorateParam(0, WorkflowParam("context")),
+	__decorateMetadata("design:type", Function),
+	__decorateMetadata("design:paramtypes", [Object]),
+	__decorateMetadata("design:returntype", Object)
+], AuthWorkflow.prototype, "fireSignup", null);
+__decorate([
+	Step("after-password-reset"),
+	Public(),
+	__decorateParam(0, WorkflowParam("context")),
+	__decorateMetadata("design:type", Function),
+	__decorateMetadata("design:paramtypes", [Object]),
+	__decorateMetadata("design:returntype", Object)
+], AuthWorkflow.prototype, "firePasswordReset", null);
 __decorate([
 	Step("issue"),
 	Public(),
@@ -5316,7 +5708,7 @@ __decorate([
 	__decorateParam(0, WorkflowParam("context")),
 	__decorateMetadata("design:type", Function),
 	__decorateMetadata("design:paramtypes", [Object]),
-	__decorateMetadata("design:returntype", Object)
+	__decorateMetadata("design:returntype", void 0)
 ], AuthWorkflow.prototype, "finalizeFreshLogin", null);
 __decorate([
 	Step("finalize-auto-login"),
@@ -5482,6 +5874,10 @@ __decorate([
 			}]
 		},
 		{ break: (ctx) => !!ctx.aborted },
+		{
+			id: "record-login",
+			condition: (ctx) => !!ctx.subject
+		},
 		{
 			condition: (ctx) => !ctx.authz,
 			steps: [
@@ -5555,6 +5951,7 @@ __decorate([
 				...consentsPersistTailSchema,
 				{ id: "unset-pending-invitation" },
 				{ id: "activate-user" },
+				{ id: "after-invitation-accepted" },
 				{
 					id: "confirmation",
 					condition: (ctx) => !!ctx.accept?.showConfirmation
@@ -5563,6 +5960,10 @@ __decorate([
 					id: "finalize-fresh-login",
 					condition: (ctx) => !ctx.autoLogin
 				},
+				{
+					id: "record-login",
+					condition: (ctx) => !!ctx.autoLogin
+				},
 				{
 					id: "finalize-auto-login",
 					condition: (ctx) => !!ctx.autoLogin
@@ -5605,10 +6006,20 @@ __decorate([
 			condition: (ctx) => ctx.lockout?.mode === "self-service"
 		},
 		...consentsPersistTailSchema,
+		{ id: "after-password-reset" },
+		{
+			id: "recovery-lock-check",
+			condition: (ctx) => ctx.lockout?.mode === "admin-only"
+		},
+		{ break: (ctx) => !!ctx.aborted },
 		{
 			id: "finalize-fresh-login",
 			condition: (ctx) => !ctx.autoLogin
 		},
+		{
+			id: "record-login",
+			condition: (ctx) => !!ctx.autoLogin
+		},
 		{
 			id: "finalize-auto-login",
 			condition: (ctx) => !!ctx.autoLogin
@@ -5659,14 +6070,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",
@@ -5706,6 +6116,8 @@ __decorate([
 		{ id: "activate-user" },
 		...consentsPersistTailSchema,
 		{ id: "signup-extra-step" },
+		{ id: "after-signup" },
+		{ id: "record-login" },
 		{ id: "finalize-auto-login" }
 	]),
 	__decorateMetadata("design:type", Function),