@aooth/auth-moost 0.1.22 → 0.1.24

package/dist/index.d.mts

@@ -1590,12 +1590,40 @@ interface AuthWfAddMfaState {
    * replay-resistant). Gates the one-time swap + the management menu.
    */
   stepUpDone?: boolean;
+  /**
+   * The user has explicitly consented to the step-up pincode dispatch —
+   * either by submitting `manage-stepup-confirm`'s "we'll send a code to
+   * ma•••@x" notice, or by picking a factor on `select-2fa` (choosing
+   * "Email (ma•••@x)" and submitting IS the consent). Gates the
+   * `manage-stepup-confirm` pause so opening the manage dialog never
+   * dispatches a code as a side effect. Also set when
+   * `resolveStepUpConfirmBeforeSend` opts the deployment out of the pause.
+   * Server-only; sms/email step-up only (TOTP dispatches nothing).
+   */
+  stepUpConfirmed?: boolean;
   /** The management action the user picked on the menu. */
   action?: "add" | "replace" | "remove";
   /** The transport the chosen `action` applies to. */
   target?: MfaTransport;
   /** Set by `confirm-remove-mfa` so `finish-add-mfa` can report which factor was removed. */
   removed?: MfaTransport;
+  /**
+   * Removing a factor is currently impossible: the user has exactly one
+   * confirmed (policy-allowed) factor and `mfaPolicy.mode === 'required'`.
+   * Computed by `manage-menu` before its pause and mirrored to
+   * `public.manage.removeBlocked` so `ManageMfaForm` omits the Remove option
+   * (and explains why) instead of offering an operation that can never
+   * succeed. Re-checked server-side in `manage-menu` + `confirm-remove-mfa`.
+   */
+  removeBlocked?: boolean;
+  /**
+   * Set by `confirm-remove-mfa` when it arrives in an un-removable state
+   * (stale/crafted route — the menu filters these): the step aborts to the
+   * `finish-add-mfa` terminal with a reason-specific message instead of
+   * pausing on a form whose only submit re-throws the same guard error
+   * (a dead-end loop, since the manage forms hide their built-in cancel).
+   */
+  blocked?: "last-required-factor" | "method-locked";
 }
 /**
  * Self-signup flow state. Populated by `init-signup` (policy from
@@ -1694,12 +1722,15 @@ interface AuthWfPublicState {
   mfaEnroll?: Pick<AuthWfMfaEnrollState, "method" | "mode" | "availableTransports" | "secret" | "uri">;
   /**
    * Mirrors the manage-MFA menu inputs — the un-enrolled transports the user
-   * can Add and the locked transports to omit from Change/Remove. The enrolled
-   * method list the menu cross-references is `public.mfa.enrolledMethods`.
+   * can Add, the locked transports to omit from Change/Remove, and the
+   * `removeBlocked` flag that omits the Remove option for the last confirmed
+   * factor under a `required` policy. The enrolled method list the menu
+   * cross-references is `public.mfa.enrolledMethods`.
    */
   manage?: {
     candidates?: MfaTransport[];
     locked?: MfaTransport[];
+    removeBlocked?: boolean;
   };
   /** Mirrors `ctx.defaults` — prefill source for the recovery email field. */
   defaults?: {
@@ -1754,6 +1785,14 @@ interface AuthWfCtx {
   aborted?: boolean;
   isFirstLogin?: boolean;
   newPasswordRequired?: boolean;
+  /**
+   * Idempotency latch for the single `record-login` funnel step. Set true once
+   * a login has been stamped this run — by the `credentials` step (the password
+   * path stamps eagerly via `users.login()`) or by `record-login` itself — so
+   * the funnel never double-writes `account.lastLogin`. Server-only flow
+   * control; never `@wf.context.pass`-ed to the client.
+   */
+  loginRecorded?: boolean;
   autoLogin?: boolean;
   consents?: AuthWfConsentsState;
   pincode?: AuthWfPincodeUiState;
@@ -1888,7 +1927,8 @@ interface AuthWorkflowOpts {
     enrollConfirm?: TAtscriptAnnotatedType; /** Manage-MFA menu (Add / Change / Remove) shown after step-up. */
     manageMfa?: TAtscriptAnnotatedType; /** Confirm-removal pause for the manage-MFA "Remove" action. */
     removeMfaConfirm?: TAtscriptAnnotatedType; /** Password re-auth — step-up fallback when no factor is MFA-challengeable. */
-    passwordReauth?: TAtscriptAnnotatedType;
+    passwordReauth?: TAtscriptAnnotatedType; /** Step-up dispatch consent — "we'll send a code to ma•••@x" notice before the step-up pincode send. */
+    stepUpConfirm?: TAtscriptAnnotatedType;
     select2fa?: TAtscriptAnnotatedType;
     mfaCode?: TAtscriptAnnotatedType;
     pincode?: TAtscriptAnnotatedType;
@@ -1944,6 +1984,7 @@ interface ResolvedAuthWorkflowOpts {
     manageMfa: TAtscriptAnnotatedType;
     removeMfaConfirm: TAtscriptAnnotatedType;
     passwordReauth: TAtscriptAnnotatedType;
+    stepUpConfirm: TAtscriptAnnotatedType;
     select2fa: TAtscriptAnnotatedType;
     mfaCode: TAtscriptAnnotatedType;
     pincode: TAtscriptAnnotatedType;
@@ -2091,6 +2132,47 @@ declare class AuthWorkflow {
    * mirrors `notifyNewDevice`'s posture). Never called by the base class.
    */
   protected sendSecurityAlert(ctx: AuthWfCtx, reason: string, context?: Record<string, unknown>): Promise<void>;
+  /**
+   * 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).
+   */
+  protected afterLogin(_ctx: AuthWfCtx): void | Promise<void>;
+  /**
+   * 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}.)
+   */
+  protected afterInvitationAccepted(_ctx: AuthWfCtx): void | Promise<void>;
+  /**
+   * 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.)
+   */
+  protected afterSignup(_ctx: AuthWfCtx): void | Promise<void>;
+  /**
+   * 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}.
+   */
+  protected afterPasswordReset(_ctx: AuthWfCtx): void | Promise<void>;
+  /**
+   * 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.
+   */
+  protected afterPasswordChanged(_ctx: AuthWfCtx): void | Promise<void>;
+  /**
+   * 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.
+   */
+  protected afterMfaChanged(_ctx: AuthWfCtx): void | Promise<void>;
   /**
    * Return the list of selectable role identifiers for the admin invite form.
    * Mirrors the prior `InviteWorkflow.getAvailableRoles()` consumer hook —
@@ -2236,6 +2318,39 @@ declare class AuthWorkflow {
    * typed would confirm an unproven inbox. Never asked for TOTP.
    */
   protected resolveEnrollPreConfirmed(_ctx: AuthWfCtx, _method: MfaTransport, _address: string): boolean | Promise<boolean>;
+  /**
+   * 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.
+   */
+  protected resolveEnrollAddress(_ctx: AuthWfCtx, _method: MfaTransport): string | "collect" | Promise<string | "collect">;
   /**
    * Resolve the finalize policy. Reached from login.flow. `auditLogin` is
    * dropped from the shape per §2 — audit moved out of the workflow layer.
@@ -2315,6 +2430,33 @@ declare class AuthWorkflow {
    * ```
    */
   protected resolveLockedMfaTransports(_ctx: AuthWfCtx): MfaTransport[] | Promise<MfaTransport[]>;
+  /**
+   * 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).
+   */
+  protected resolveStepUpConfirmBeforeSend(_ctx: AuthWfCtx): boolean | Promise<boolean>;
+  /**
+   * 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, …).
+   */
+  protected resolveTotpAccountLabel(ctx: AuthWfCtx): string | Promise<string>;
   /**
    * Resolve the channel-OTP disclosure copy rendered beneath the email/phone
    * input on `AskEmailForm` / `AskPhoneForm`. Reached from login.flow Phase 3.
@@ -2583,6 +2725,18 @@ declare class AuthWorkflow {
    * and resend.
    */
   private mintAndSendEnrollPincode;
+  /**
+   * 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.
+   */
+  private provisionTotpSecret;
   /**
    * Drop the per-enrolment scratch fields (the `mfaEnroll` provisioning fields +
    * the pincode timers/`sentTo`) off ctx — the shared teardown used by the
@@ -2600,8 +2754,24 @@ declare 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);
+   * }
+   * ```
    */
-  protected validateMfaAddress(method: MfaTransport, value: string): string | undefined;
+  protected validateMfaAddress(_ctx: AuthWfCtx, method: MfaTransport, value: string): string | undefined | Promise<string | undefined>;
   /**
    * Light normalization of a validated MFA address before it is stored. Default:
    * trims, and strips spacing/punctuation from SMS numbers while KEEPING the
@@ -2869,10 +3039,17 @@ declare 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: AuthWfCtx): undefined | Promise<undefined>;
+  /**
+   * `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.
    */
-  finishAddMfa(ctx: AuthWfCtx): undefined;
+  protected buildAddMfaFinishEnvelope(ctx: AuthWfCtx): WfFinished;
   /**
    * Resolve which transports the user may NOT change/remove via the manage flow
    * (calls {@link resolveLockedMfaTransports}) and write them to
@@ -2887,6 +3064,22 @@ declare class AuthWorkflow {
    * encapsulated when no durable store is wired (the registry default).
    */
   manageStepUpDone(ctx: AuthWfCtx): undefined;
+  /**
+   * 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: AuthWfCtx): undefined | Promise<undefined>;
+  /** `manage-stepup-confirm` tail — opt-out fall-through or the consent pause. */
+  private applyStepUpConfirm;
   /**
    * 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
@@ -2900,6 +3093,15 @@ declare class AuthWorkflow {
    * subject), and `verifyPassword` is the same check `changePassword` enforces.
    */
   managePasswordReauth(ctx: AuthWfCtx): Promise<undefined>;
+  /**
+   * 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.
+   */
+  private isLastRequiredFactor;
   /**
    * Manage-MFA menu — pauses on `ManageMfaForm` and routes the chosen
    * `operation` (`add:<t>` / `replace:<t>` / `remove:<t>`). Only reached when
@@ -2912,8 +3114,13 @@ declare 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).
    */
   confirmRemoveMfa(ctx: AuthWfCtx): Promise<undefined>;
   askChannel(ctx: AuthWfCtx, channel: "email" | "phone"): Promise<unknown>;
@@ -2996,17 +3203,30 @@ declare class AuthWorkflow {
   enrollPickMethod(ctx: AuthWfCtx): undefined | Promise<undefined>;
   /**
    * 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.
-   */
-  enrollAddress(ctx: AuthWfCtx): undefined;
+   * 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: AuthWfCtx): undefined | Promise<undefined>;
+  /**
+   * `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).
+   */
+  private collectEnrollAddress;
   /**
    * Unified MFA-enrol dispatch (sms/email only) — the trio's ONLY pincode
    * send. A separate step (the canonical "send if no pin" gate, mirroring
@@ -3178,6 +3398,52 @@ declare class AuthWorkflow {
    * also zeroes `failedLoginAttempts`, so the next login starts clean.
    */
   unlockAccount(ctx: AuthWfCtx): Promise<undefined>;
+  /**
+   * 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: AuthWfCtx): undefined | Promise<undefined>;
+  /**
+   * 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).
+   */
+  recoveryLockCheck(ctx: AuthWfCtx): Promise<undefined>;
+  /**
+   * 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: AuthWfCtx): void | Promise<void>;
+  fireSignup(ctx: AuthWfCtx): void | Promise<void>;
+  firePasswordReset(ctx: AuthWfCtx): void | Promise<void>;
   /**
    * Issue access + refresh tokens via `auth.issue`. Stashes the login
    * response envelope on `useWfFinished` so downstream `redirect` can
@@ -3251,7 +3517,7 @@ declare class AuthWorkflow {
    * confirmation first. Discriminated by ctx-slot presence
    * (`ctx.postReset` → recovery; otherwise invite).
    */
-  finalizeFreshLogin(ctx: AuthWfCtx): undefined | Promise<undefined>;
+  finalizeFreshLogin(ctx: AuthWfCtx): undefined;
   /**
    * Post-reset store read: did an `admin-only` lockout survive the password
    * reset (account still frozen)? Callers MUST first confirm
@@ -3272,10 +3538,17 @@ declare class AuthWorkflow {
    */
   private finishRecoveryReset;
   /**
-   * 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.
    */
   finalizeAutoLogin(ctx: AuthWfCtx): Promise<undefined>;
   /**
@@ -3476,12 +3749,19 @@ declare 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