@aooth/auth-moost 0.1.8 → 0.1.10

package/dist/index.d.mts

@@ -1,12 +1,12 @@
 import { Mate, TConsoleBase, TInterceptorDef, TMateParamMeta, TMoostMetadata } from "moost";
 import { AuthContext, AuthContext as AuthContext$1, AuthCredential, AuthEmailEvent, AuthEmailKind, AuthEmailKind as AuthEmailKind$1, AuthSmsEvent, AuthSmsKind, BuildMagicLinkUrl, BuildMagicLinkUrl as BuildMagicLinkUrl$1, CredentialMetadata, EmailSender, EmailSender as EmailSender$1, EnrichedSession, EnrichedSession as EnrichedSession$1, IssueResult, IssueResult as IssueResult$1, SessionEnricher, SessionEnricher as SessionEnricher$1, SessionInfo, SessionInfo as SessionInfo$1, SmsSender, generateMagicLinkToken } from "@aooth/auth";
 import { TCookieAttributesInput } from "@wooksjs/event-http";
-import { FederatedIdentityStore, FederatedProfileSnapshot, TransferablePolicy, TrustedDeviceRecord, UserCredentials, UserService } from "@aooth/user";
+import { FederatedIdentityStore, FederatedProfileSnapshot, MfaMethod, TransferablePolicy, TrustedDeviceRecord, UserCredentials, UserService } from "@aooth/user";
 import { FinishWfOpts, WfFinished, useAtscriptWf } from "@atscript/moost-wf";
 import { MoostWf, WfOutlet, WfOutletTokenConfig, WfStateStrategy } from "@moostjs/event-wf";
 import { FederatedLoginService, NormalizedProfile, OAuthProviderRegistry } from "@aooth/idp";
 import { TAtscriptAnnotatedType } from "@atscript/typescript/utils";
-import { AuthCodeStore, ClientRedirectPolicy, PendingAuthorizationStore } from "@aooth/auth/authz";
+import { AuthCodeStore, ClientRedirectPolicy, IdTokenSigner, OidcClaimsResolver, PendingAuthorizationStore } from "@aooth/auth/authz";
 
 //#region src/auth.config.d.ts
 /** Resolved cookie attributes. Same shape is used for both access + refresh. */
@@ -837,25 +837,50 @@ declare const FEDERATED_IDENTITY_STORE_TOKEN = "aooth:FederatedIdentityStore";
 interface TokenError {
   error: string;
 }
+/** OIDC token-endpoint success (RFC 6749 + OIDC Core). `id_token` for OIDC clients; `access_token` per registration. */
+interface TokenSuccess {
+  token_type: "Bearer";
+  access_token?: string;
+  id_token?: string;
+  expires_in?: number;
+  /** The authenticated user id (`sub`) — convenience for a CLI; not part of the OIDC token response. */
+  userId: string;
+}
+/** A minimal OIDC discovery document (`/.well-known/openid-configuration`). */
+interface OidcDiscoveryDocument {
+  issuer: string;
+  authorization_endpoint: string;
+  token_endpoint: string;
+  jwks_uri: string;
+  response_types_supported: string[];
+  grant_types_supported: string[];
+  subject_types_supported: string[];
+  id_token_signing_alg_values_supported: string[];
+  scopes_supported: string[];
+  code_challenge_methods_supported: string[];
+  token_endpoint_auth_methods_supported: string[];
+}
 /**
- * The authorization-server endpoints (AUTH-SERVER.md Tier 1). Turns the existing
- * login workflow into an OAuth authorization server for the app's OWN clients —
- * a local CLI on a loopback redirect today, a registered first-party service
- * (Tier 2) later. One authorization-code + PKCE flow; the only thing that varies
- * is the injected {@link ClientRedirectPolicy}.
+ * The authorization-server endpoints (AUTH-SERVER.md). Turns the existing login
+ * workflow into an OAuth/OIDC authorization server for the app's OWN clients — a
+ * local CLI on a loopback redirect (Tier 1) and registered first-party services
+ * (Tier 2, `id_token` / "Sign in with <main app>"). One authorization-code + PKCE
+ * flow; the only things that vary are the injected {@link ClientRedirectPolicy}
+ * and whether an {@link IdTokenSigner} is wired.
  *
  * - `GET  /auth/authorize` — validate the client + `redirect_uri` (the policy),
- *   record a {@link PendingAuthorizationStore} entry, and 302 the browser to the
- *   login page carrying the opaque `handle`. The login workflow authenticates
- *   the human and its `mint-authz-code` terminal delivers the code to the client
- *   — this controller never runs the login itself.
+ *   record a {@link PendingAuthorizationStore} entry (authority fixed HERE), and
+ *   302 the browser to the login page carrying the opaque `handle`. The login
+ *   workflow's `mint-authz-code` terminal delivers the code to the client.
  * - `POST /auth/token` — the back-channel: consume the single-use code, verify
- *   PKCE, and `AuthCredential.issue(userId, tokenPolicy)`. The token is minted
- *   HERE, off the browser, so nothing long-lived ever rides a redirect URL.
+ *   PKCE, authenticate the client (Tier 2), and mint the access token and/or the
+ *   `id_token`. Minted HERE, off the browser, so nothing long-lived rides a URL.
+ * - `GET /auth/.well-known/openid-configuration` + `GET /auth/jwks` — OIDC
+ *   discovery + the signer's public JWKS (Tier 2 only; 404 without a signer).
  *
- * Both routes are `@Public()` (anonymous). The grant's authority is fixed at
- * `/authorize` time (the policy's {@link TokenPolicy} is recorded on the pending
- * authorization and copied onto the issued code), never inferred at `/token`.
+ * All routes are `@Public()`. The grant's authority (token policy, `id_token`
+ * intent, audience, scope) is fixed at `/authorize` time and recorded on the
+ * pending authorization + the issued code — never inferred at `/token`.
  */
 declare class AuthorizeController {
   protected readonly auth: AuthCredential;
@@ -863,6 +888,20 @@ declare class AuthorizeController {
   protected readonly pending: PendingAuthorizationStore;
   protected readonly codes: AuthCodeStore;
   constructor(auth: AuthCredential, policy: ClientRedirectPolicy, pending: PendingAuthorizationStore, codes: AuthCodeStore);
+  /**
+   * The Tier-2 OIDC `id_token` signer, or `undefined` for a Tier-1-only (CLI)
+   * deployment — then discovery / `/auth/jwks` 404 and no `id_token` is minted.
+   * **Override** in a subclass to enable OIDC (return one `IdTokenSigner` whose
+   * issuer is `{origin}/auth`). A plain getter rather than a DI token because an
+   * OPTIONAL `@Inject`/`@Optional` dependency panics in moost's `resolveMoost`
+   * route-table pass (`useHandlerPaths`); a method has nothing for it to resolve.
+   */
+  protected getIdTokenSigner(): IdTokenSigner | undefined;
+  /**
+   * The Tier-2 OIDC profile-claims resolver. Defaults to a no-op (`sub`-only
+   * tokens); **override** to emit `email` / `name` / … from your user record.
+   */
+  protected getOidcClaimsResolver(): OidcClaimsResolver;
   /**
    * The SPA login route the authorize request bounces to. The opaque pending-auth
    * `handle` is appended as `?authz=`; the SPA forwards it into the login
@@ -870,18 +909,23 @@ declare class AuthorizeController {
    * custom login path.
    */
   protected loginPath(): string;
-  authorize(responseType: string | undefined, redirectUri: string | undefined, clientId: string | undefined, state: string | undefined, codeChallenge: string | undefined, codeChallengeMethod: string | undefined, scope: string | undefined): Promise<string>;
+  authorize(responseType: string | undefined, redirectUri: string | undefined, clientId: string | undefined, state: string | undefined, codeChallenge: string | undefined, codeChallengeMethod: string | undefined, scope: string | undefined, nonce: string | undefined): Promise<string>;
   token(body: {
     grant_type?: string;
     code?: string;
     code_verifier?: string;
     client_id?: string;
-  } | undefined): Promise<{
-    access_token: string;
-    token_type: "Bearer";
-    expires_in: number;
-    userId: string;
-  } | TokenError>;
+    client_secret?: string;
+  } | undefined): Promise<TokenSuccess | TokenError>;
+  /**
+   * OIDC discovery (Tier 2). Derives every endpoint from the signer's `issuer`
+   * (configured as `{origin}/auth`), so a relying `OidcProvider` configured with
+   * the same `issuer` resolves `/authorize`, `/token`, and `/jwks` automatically.
+   * 404 when no signer is wired (Tier-1-only deployment).
+   */
+  discovery(): OidcDiscoveryDocument | TokenError;
+  /** The signer's public JWKS (Tier 2). 404 when no signer is wired. */
+  jwks(): Promise<Awaited<ReturnType<IdTokenSigner["jwks"]>>> | TokenError;
   /** Fail soft: 302 the validated client redirect with an `?error=` (+ echoed `state`). */
   protected redirectError(redirectUri: string, error: string, state: string | undefined): string;
 }
@@ -932,7 +976,8 @@ declare const AUTH_CODE_STORE_TOKEN = "aooth:AuthCodeStore";
 /**
  * DI token for the {@link import("@aooth/auth/authz").ClientRedirectPolicy} — an
  * interface, so it has no class reference to inject by. Provide the concrete
- * policy (e.g. `new LoopbackClientPolicy()`) under this string.
+ * policy (e.g. `new LoopbackClientPolicy()`, a `RegisteredClientPolicy`, or a
+ * `CompositeClientPolicy` of both) under this string.
  */
 declare const CLIENT_REDIRECT_POLICY_TOKEN = "aooth:ClientRedirectPolicy";
 //#endregion
@@ -1008,8 +1053,21 @@ interface AuthWfMfaEnrollState {
   secret?: string;
   uri?: string;
   availableTransports?: MfaTransport[];
-  mode?: "required" | "optional";
+  /**
+   * Drives skip / cancel visibility on the enrolment forms:
+   * - `'optional'` — login/invite first-time opt-in: "Skip for now" shows.
+   * - `'required'` — forced enrolment: neither skip nor cancel.
+   * - `'manage'` — the standalone manage-MFA flow (user opened it on purpose):
+   *   "Skip for now" is hidden, a "Cancel" action shows instead.
+   */
+  mode?: "required" | "optional" | "manage";
   done?: boolean;
+  /**
+   * Gates the standalone `enroll-totp-qr` step (TOTP only). Set once the user
+   * has been shown the QR/secret and clicked Continue, so the QR pause fires
+   * before — not alongside — the code-entry step. Shared by both surfaces.
+   */
+  qrSeen?: boolean;
   /**
    * When set, `enroll-confirm` does NOT make the freshly-confirmed method the
    * user's default. Set by `init-add-mfa` (the standalone add-MFA flow) when the
@@ -1311,12 +1369,52 @@ interface AuthWfPendingLinkState {
 interface AuthWfAddMfaState {
   /**
    * Transports the user has NOT yet confirmed = resolved
-   * `availableTransports` minus already-enrolled. The enrol picker offers
-   * exactly these; an empty list means there is nothing to add and the flow
-   * finishes with a benign "no methods available" terminal. `finish-add-mfa`
-   * reads it to distinguish "nothing to add" from "user cancelled".
+   * `availableTransports` minus already-enrolled. The manage menu offers these
+   * as "Add" options (a zero-MFA user goes straight to the enrol picker over
+   * the same list). `finish-add-mfa` reads it to distinguish "nothing to add"
+   * from "user cancelled".
    */
   candidates?: MfaTransport[];
+  /**
+   * Transports the user may NOT change or remove via this flow — resolved by
+   * `resolveLockedMfaTransports` (default: none). A customer locks a factor
+   * whose value IS a login handle (e.g. the MFA email equals the
+   * `@aooth.user.email` handle) so the user can't silently desync it here.
+   * Locked transports are omitted from the menu's Change/Remove options and
+   * re-checked server-side in `manage-menu` / `confirm-remove-mfa`.
+   */
+  locked?: MfaTransport[];
+  /**
+   * `true` when the user already has ≥1 confirmed method, so the manage flow
+   * must step-up (re-verify identity) BEFORE offering add/change/remove, and
+   * shows the management menu. The METHOD of step-up is `stepUpMode`. `false`
+   * (zero confirmed methods) skips both — the flow degrades to the first-time
+   * enrol picker (the opt-in path).
+   */
+  stepUpRequired?: boolean;
+  /**
+   * How the step-up is performed (set by `init-add-mfa` when `stepUpRequired`):
+   * - `'mfa'` — the user has ≥1 confirmed factor whose kind is still in the
+   *   policy's `availableTransports`, so `mfaStepUpLoop` challenges it.
+   * - `'password'` — every confirmed factor is of a kind the policy no longer
+   *   allows (none is challengeable), so `manage-password-reauth` re-verifies
+   *   via the account password instead. Fail-closed fallback that keeps "prove
+   *   identity before managing factors" intact even after a policy tightening
+   *   orphaned the only enrolled factor.
+   */
+  stepUpMode?: "mfa" | "password";
+  /**
+   * Set once the step-up factor verifies AND the flow has swapped off the
+   * encapsulated start onto the durable `store` strategy (server-anchored,
+   * replay-resistant). Gates the one-time swap + the management menu.
+   */
+  stepUpDone?: 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;
 }
 /**
  * Self-signup flow state. Populated by `init-signup` (policy from
@@ -1412,12 +1510,15 @@ interface AuthWfPublicState {
    * Mirrors `ctx.mfaEnroll` — only what the enrolment forms display.
    * `address` stays internal (user-typed, no need to bounce it back).
    */
-  mfaEnroll?: {
-    method?: MfaTransport;
-    mode?: "required" | "optional";
-    availableTransports?: MfaTransport[];
-    secret?: string;
-    uri?: string;
+  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`.
+   */
+  manage?: {
+    candidates?: MfaTransport[];
+    locked?: MfaTransport[];
   };
   /** Mirrors `ctx.defaults` — prefill source for the recovery email field. */
   defaults?: {
@@ -1460,6 +1561,13 @@ interface AuthWfCtx {
   mfaEnroll?: AuthWfMfaEnrollState;
   password?: AuthWfPasswordUiState;
   completion?: AuthWfCompletionState;
+  /**
+   * Marks that the `promote-to-handle` @Step has already run for this flow, so
+   * it fires once after a channel is confirmed and is skipped on every later
+   * resume (the store write is idempotent, but re-running it each resume would
+   * be wasteful). Server-only — never `@wf.context.pass`'d.
+   */
+  promoteToHandleDone?: boolean;
   alternateCredentials?: AuthWfAltCredsPolicy;
   deviceTrust?: AuthWfDeviceTrustPolicy;
   enrollment?: AuthWfEnrollmentPolicy;
@@ -1548,8 +1656,12 @@ interface AuthWorkflowOpts {
     askEmail?: TAtscriptAnnotatedType;
     askPhone?: TAtscriptAnnotatedType;
     enrollPickMethod?: TAtscriptAnnotatedType;
-    enrollAddress?: TAtscriptAnnotatedType;
-    enrollConfirm?: TAtscriptAnnotatedType;
+    enrollAddress?: TAtscriptAnnotatedType; /** TOTP QR step — shown before the code-entry pause (manage + opt-in). */
+    enrollTotpQr?: TAtscriptAnnotatedType;
+    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;
     select2fa?: TAtscriptAnnotatedType;
     mfaCode?: TAtscriptAnnotatedType;
     pincode?: TAtscriptAnnotatedType;
@@ -1594,7 +1706,11 @@ interface ResolvedAuthWorkflowOpts {
     askPhone: TAtscriptAnnotatedType;
     enrollPickMethod: TAtscriptAnnotatedType;
     enrollAddress: TAtscriptAnnotatedType;
+    enrollTotpQr: TAtscriptAnnotatedType;
     enrollConfirm: TAtscriptAnnotatedType;
+    manageMfa: TAtscriptAnnotatedType;
+    removeMfaConfirm: TAtscriptAnnotatedType;
+    passwordReauth: TAtscriptAnnotatedType;
     select2fa: TAtscriptAnnotatedType;
     mfaCode: TAtscriptAnnotatedType;
     pincode: TAtscriptAnnotatedType;
@@ -1624,7 +1740,7 @@ type AuthDeliveryPayload = {
   expiresInMs: number;
 } | {
   kind: "recovery-pincode";
-  channel: "email";
+  channel: "sms" | "email";
   recipient: string;
   code: string;
   expiresInMs: number;
@@ -1869,6 +1985,28 @@ declare class AuthWorkflow {
    * Reached from login.flow + invite.start.
    */
   protected resolveMfaPolicy(_ctx: AuthWfCtx): NonNullable<AuthWfCtx["mfaPolicy"]> | Promise<NonNullable<AuthWfCtx["mfaPolicy"]>>;
+  /**
+   * Transports the user may NOT change or remove via the manage-MFA flow.
+   * Default: none — every factor is freely manageable. Reached from
+   * `auth/add-mfa/flow` (`prepare-locked-mfa-transports`).
+   *
+   * Override to forbid changing a factor whose value IS a login handle — e.g.
+   * the MFA `email` equals the `@aooth.user.email` handle, so letting the user
+   * swap it here would desync identity. A typical override loads the user and
+   * compares each enrolled channel value against the boot-resolved handle
+   * fields (`getAoothUserHandleSpec(...).emailField` / `.phoneField`):
+   *
+   * ```ts
+   * protected async resolveLockedMfaTransports(ctx: AuthWfCtx): Promise<MfaTransport[]> {
+   *   const user = await this.users.getUser(ctx.subject!);
+   *   const locked: MfaTransport[] = [];
+   *   const email = user.mfa?.methods?.find((m) => m.name === "email" && m.confirmed);
+   *   if (email && email.value === (user as { email?: string }).email) locked.push("email");
+   *   return locked;
+   * }
+   * ```
+   */
+  protected resolveLockedMfaTransports(_ctx: AuthWfCtx): MfaTransport[] | Promise<MfaTransport[]>;
   /**
    * Resolve the channel-OTP disclosure copy rendered beneath the email/phone
    * input on `AskEmailForm` / `AskPhoneForm`. Reached from login.flow Phase 3.
@@ -1939,6 +2077,79 @@ declare class AuthWorkflow {
     address: string;
     channel: "sms" | "email";
   }>;
+  /**
+   * Resolve the recovery OTP `{ address, channel }` for the chosen delivery
+   * `source`.
+   *
+   * - `"typed"` (M1): the address is the typed recovery identifier (`ctx.email`)
+   *   — identifier == destination, so no cross-account redirect — and the
+   *   channel comes from `resolveRecoveryChannel` (identifier-shape inference).
+   * - `"registered"` (M2): the address is read off a confirmed MFA method on the
+   *   row (`selectRecoveryRegisteredMethod`) and the channel is that method's own
+   *   kind. The user only typed an account identifier; the destination is a
+   *   pre-verified channel they already control, so this also can't redirect
+   *   cross-account. `request`'s M2 guard normally generic-finishes any row with
+   *   no deliverable method up front; if the method is deleted in the narrow
+   *   window between that guard and this send (e.g. on a resend), this throws
+   *   `RecoveryMethodUnavailableError`, which `pincode-send` degrades to the
+   *   same generic finish — never a distinguishable 500.
+   */
+  private recoveryPincodeTarget;
+  /**
+   * Recovery OTP delivery channel. The address is ALWAYS the typed recovery
+   * identifier (`ctx.email`) — symmetric with how email recovery already works:
+   * the OTP goes to the value the user typed, which is the handle that resolved
+   * the account (`findByHandle`), so identifier == destination and there is no
+   * cross-account redirect. Default `"email"`. A deployment whose recovery form
+   * accepts a phone overrides this to route SMS (e.g. infer from the identifier
+   * shape) — see the demo's `DemoAuthWorkflow`. Recovery picks ONE channel per
+   * run, so the single `resendAllowedAt` cooldown gate still suffices.
+   */
+  protected resolveRecoveryChannel(_ctx: AuthWfCtx): "email" | "sms" | Promise<"email" | "sms">;
+  /**
+   * Recovery OTP delivery model. Two options:
+   *
+   * - `"typed"` (default — M1): the OTP goes to the recovery identifier the user
+   *   types. Identifier == destination, so there is no cross-account redirect;
+   *   `resolveRecoveryChannel` picks email vs SMS from the identifier shape.
+   * - `"registered"` (M2): the user enters only an account identifier (e.g. a
+   *   username) and the OTP is delivered to a channel **already verified on the
+   *   row** — `selectRecoveryRegisteredMethod` picks the confirmed MFA method;
+   *   the destination is never taken from user input, so it cannot be redirected
+   *   to an attacker-controlled address. A row with no deliverable confirmed
+   *   method finishes with the generic anti-enumeration envelope (see `request`).
+   *
+   * Consulted inline by `request` (no-method guard) and `recoveryPincodeTarget`
+   * — no `prepare-*` step, mirroring `resolveRecoveryChannel`. Override to arm
+   * M2 (per-tenant / per-variant); see the demo's `DemoAuthWorkflow`.
+   */
+  protected resolveRecoveryDeliverySource(_ctx: AuthWfCtx): "typed" | "registered" | Promise<"typed" | "registered">;
+  /**
+   * Pick the confirmed MFA method a registered-channel recovery (M2) delivers
+   * its OTP to. Prefers a confirmed SMS method, then a confirmed email method —
+   * phone-recovery-first. TOTP carries no deliverable address and is skipped.
+   * Returns `null` when the row has no deliverable confirmed method; the caller
+   * turns that into the anti-enumeration generic finish. Stays sync (operates on
+   * an already-loaded row); override to change the selection policy (e.g. honour
+   * the user's `mfa.defaultMethod`).
+   */
+  protected selectRecoveryRegisteredMethod(user: UserCredentials): MfaMethod | null;
+  /**
+   * Decide which login-handle column a freshly-confirmed channel should be
+   * promoted into — so a verified email/phone becomes a login + recovery
+   * handle (`findByHandle`) automatically. Returns the target field name, or
+   * `undefined` to NOT promote (the default).
+   *
+   * Default is OFF: the handle columns are declared via `@aooth.user.*`
+   * annotations on the consumer's concrete model and resolved ONCE at boot
+   * (`@aooth/arbac-moost`'s `getAoothUserHandleSpec`) — `AuthWorkflow` holds no
+   * handle to that model and stays off the per-request reflection path. A
+   * deployment turns promotion ON by overriding this to return the
+   * boot-resolved `emailField` / `phoneField` for the channel — see the demo's
+   * `DemoAuthWorkflow`. `channel` is the wire protocol (`'email'` | `'sms'`),
+   * matching `resolveOtpDisclosure` / the MFA transport.
+   */
+  protected resolvePromoteHandleField(_ctx: AuthWfCtx, _channel: "email" | "sms"): string | undefined | Promise<string | undefined>;
   /**
    * Route a form alt-action click to a canonical outcome. Defaults match the
    * action ids the bundled `PincodeForm` declares; customers override per
@@ -2046,13 +2257,60 @@ declare class AuthWorkflow {
    */
   protected sendEnrollPincode(ctx: AuthWfCtx, address: string, code: string): Promise<void>;
   /**
-   * Cleanup any partially-persisted enrolment state (unconfirmed method row +
-   * ctx scratch). Called when the user picks `skip` or `useDifferentMethod`
-   * mid-flow on `enrollConfirm`, where the unconfirmed method has already
-   * been written via `addMfaMethod` (in `enrollPickMethod` for totp /
-   * `enrollAddress` for sms+email).
-   */
-  protected cleanupEnrollment(ctx: AuthWfCtx, username: string): Promise<void>;
+   * Drop the per-enrolment scratch fields (the `mfaEnroll` provisioning fields +
+   * the pincode timers/`sentTo`) off ctx — the shared teardown used by the
+   * opt-in `skip` / `useDifferentMethod` arms and {@link cancelManageEnrollment}.
+   * Does NOT touch the user record: the enrol trio stages every candidate value
+   * (sms/email address, totp secret) in wf-state and writes it to the store ONLY
+   * on confirm (write-on-confirm), so a bailed enrolment never persisted a
+   * partial row to undo.
+   */
+  protected clearEnrollScratch(ctx: AuthWfCtx): void;
+  /**
+   * Validate a user-typed MFA address for its transport. Server-side counterpart
+   * to `EnrollAddressForm`'s client `@ui.form.validate` hint — the authoritative
+   * check (a client can bypass the hint). Returns an error string for the form,
+   * or `undefined` when valid. Email must look like an email; SMS is permissive
+   * E.164-ish (normalized by {@link normalizeMfaAddress}). Override for stricter
+   * (e.g. libphonenumber) validation.
+   */
+  protected validateMfaAddress(method: MfaTransport, value: string): 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
+   * leading `+` (E.164 canonical form). Email is just trimmed. Override for full
+   * E.164 canonicalization.
+   */
+  protected normalizeMfaAddress(method: MfaTransport, value: string): string;
+  /**
+   * Abort an in-progress manage-MFA enrolment cleanly: drop the wf-state scratch
+   * and set `ctx.aborted` so the schema breaks to `finish-add-mfa` (cancelled
+   * terminal). Nothing to undo in the user record — the manage flow stages every
+   * candidate value (sms/email address, totp secret) in wf-state and writes it
+   * to the store ONLY on confirm (write-on-confirm), so an in-progress
+   * add/change/replace never touched the existing factors. This is exactly why
+   * a cancel — or a crafted `useDifferentMethod` routed here — can never strand
+   * or clobber a live factor.
+   */
+  protected cancelManageEnrollment(ctx: AuthWfCtx): void;
+  /**
+   * Shared skip / cancel / useDifferentMethod triage for the enrol-trio steps
+   * that pause after the candidate value is staged (`enroll-totp-qr` +
+   * `enroll-confirm`): `cancel` / `useDifferentMethod` (manage) abort the flow,
+   * `skip` (opt-in) and `useDifferentMethod` (opt-in) drop the wf-state scratch.
+   * Returns `true` when the action terminated the step so the caller can
+   * `return undefined`. (`enroll-pick-method` / `enroll-address` keep their own
+   * preludes — their skip/useDifferentMethod arms diverge from this one.)
+   *
+   * SECURITY: in `'manage'` mode BOTH `cancel` and `useDifferentMethod` (the
+   * manage forms HIDE the latter but it stays in their declared action
+   * whitelist, so a crafted resume can still send it) route through the abort,
+   * which only clears scratch. Because the enrol trio writes the user record
+   * ONLY on confirm (write-on-confirm), an in-progress add/change has touched
+   * nothing in the store — so a cancel/useDifferentMethod can never strand or
+   * clobber the user's live factor, by construction.
+   */
+  protected handleEnrollExit(ctx: AuthWfCtx, action: string | undefined): boolean;
   initLogin(ctx: AuthWfCtx): void;
   initInviteAdmin(ctx: AuthWfCtx): void;
   initInviteAccept(ctx: AuthWfCtx): void;
@@ -2070,23 +2328,25 @@ declare class AuthWorkflow {
    */
   initChangePassword(ctx: AuthWfCtx): void;
   /**
-   * Bind the standalone "add an MFA method" flow to the CURRENT authenticated
-   * user and narrow enrolment to the transports they have NOT enrolled yet.
-   * Identity comes from the session (`useAuth().getUserId()`) — never form input
-   * — so it is structurally "add a factor to MY account". Mirrors
-   * `init-change-password`'s arbac gate (`auth.add-mfa` / `self`): a customer
-   * enables the feature with a single `allow("auth.add-mfa", "*")` grant and
-   * forbids it by omitting it. `getUserId()` throws 401 if unauthenticated —
-   * defence in depth on top of the guarded trigger route.
+   * Bind the standalone "Manage two-factor authentication" flow (add / change /
+   * remove) to the CURRENT authenticated user. Identity comes from the session
+   * (`useAuth().getUserId()`) — never form input — so it is structurally "manage
+   * MY factors". Mirrors `init-change-password`'s arbac gate (`auth.add-mfa` /
+   * `self`): a customer enables the feature with a single
+   * `allow("auth.add-mfa", "*")` grant and forbids it by omitting it.
+   * `getUserId()` throws 401 if unauthenticated — defence in depth on top of the
+   * guarded trigger route.
    *
-   * Drives the REUSED enrol trio (`enroll-pick-method` / `enroll-address` /
-   * `enroll-confirm`) by setting `ctx.mfaPolicy.availableTransports` to the
-   * un-enrolled remainder — so the picker offers only those and auto-picks when
-   * exactly one remains. Forces `mode: "optional"` (the user opted in; an empty
-   * remainder must finish gracefully, never 500 as `required` would). The
-   * remainder is stashed on `ctx.addMfa.candidates` (flow discriminator + finish
-   * summary); when the user already has a default, `enroll-confirm` is asked to
-   * keep it (`mfaEnroll.keepExistingDefault`).
+   * Sets `ctx.mfaPolicy.availableTransports` to the FULL policy set (so the
+   * step-up's `load-enrolled-mfa-methods` can see the confirmed factors to
+   * challenge) and tracks the un-enrolled `candidates` separately on
+   * `ctx.addMfa` for the menu's Add options. `stepUpRequired` is set when the
+   * user has ANY confirmed factor — gating both the step-up and the management
+   * menu; a zero-MFA user skips both and falls through to the first-time enrol
+   * picker (the opt-in path). `stepUpMode` picks the step-up method: `'mfa'`
+   * when a confirmed factor is still challengeable, else `'password'` (a
+   * password re-auth fallback for an orphaned factor). Puts the enrol forms in
+   * `'manage'` mode (Cancel, not "Skip for now") and keeps the existing default.
    */
   initAddMfa(ctx: AuthWfCtx): Promise<undefined>;
   credentials(ctx: AuthWfCtx): Promise<unknown>;
@@ -2267,13 +2527,55 @@ declare class AuthWorkflow {
    */
   finishChangePassword(ctx: AuthWfCtx): Promise<undefined>;
   /**
-   * Terminal for the add-MFA flow. The user KEEPS their current session (no
-   * re-issue, no cookies) — this is a plain data finish. `mfaEnroll.done &&
-   * mfaEnroll.method` is the success signal: a real confirm keeps `.method`,
-   * whereas a cancel runs `cleanupEnrollment` (which deletes it). An empty
-   * `addMfa.candidates` distinguishes "nothing left to add" from a user cancel.
+   * Terminal for the manage-MFA flow. The user KEEPS their current session (no
+   * re-issue, no cookies) — a plain data finish. Outcomes, in priority order:
+   * removed → changed (`replace` + done) → added (done) → nothing-available
+   * (zero candidates, never had to step-up) → cancelled.
    */
   finishAddMfa(ctx: AuthWfCtx): undefined;
+  /**
+   * Resolve which transports the user may NOT change/remove via the manage flow
+   * (calls {@link resolveLockedMfaTransports}) and write them to
+   * `ctx.addMfa.locked`. Mirrors the `prepare-<group>` convention.
+   */
+  prepareLockedMfaTransports(ctx: AuthWfCtx): undefined | Promise<undefined>;
+  /**
+   * Fires once the step-up factor verifies — anchor the rest of the flow in the
+   * durable `store` strategy (mirrors login's swap-after-credentials): the
+   * pincode becomes single-use server state and the staged new factor lives
+   * server-side instead of in the SPA-held encapsulated token. Degrades to
+   * encapsulated when no durable store is wired (the registry default).
+   */
+  manageStepUpDone(ctx: AuthWfCtx): undefined;
+  /**
+   * Manage-MFA password re-auth — the step-up FALLBACK when the user's only
+   * confirmed factor(s) are of kinds the policy no longer allows, so nothing is
+   * MFA-challengeable (`addMfa.stepUpMode === "password"`; see `init-add-mfa`).
+   * Pauses on `PasswordReauthForm`, verifies the account password via
+   * `UserService.verifyPassword`, and on success flips `ctx.otp.verified` — the
+   * SAME step-up success signal `mfaStepUpLoop` sets — so `manage-stepup-done`
+   * (swap-to-store) and `manage-menu` proceed identically. `cancel` aborts to
+   * the cancelled terminal (fail closed: no management write without a fresh
+   * proof of identity). Only ARBAC-gated callers reach it (session-bound
+   * subject), and `verifyPassword` is the same check `changePassword` enforces.
+   */
+  managePasswordReauth(ctx: AuthWfCtx): Promise<undefined>;
+  /**
+   * Manage-MFA menu — pauses on `ManageMfaForm` and routes the chosen
+   * `operation` (`add:<t>` / `replace:<t>` / `remove:<t>`). Only reached when
+   * the user has ≥1 confirmed factor (a zero-MFA user goes straight to the enrol
+   * picker). Re-checks the locked set + candidate membership server-side, then
+   * sets `ctx.addMfa.action`/`target` (and pre-seeds `mfaEnroll.method` for
+   * add/change). `cancel`, or nothing actionable, aborts to the finish terminal.
+   */
+  manageMenu(ctx: AuthWfCtx): Promise<undefined>;
+  /**
+   * 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).
+   */
+  confirmRemoveMfa(ctx: AuthWfCtx): Promise<undefined>;
   askChannel(ctx: AuthWfCtx, channel: "email" | "phone"): Promise<unknown>;
   verifyChannel(ctx: AuthWfCtx, channel: "email" | "phone"): Promise<unknown>;
   /**
@@ -2346,22 +2648,72 @@ declare class AuthWorkflow {
   /**
    * Unified MFA-enrol phase 1 (pick method). Auto-picks a single transport,
    * otherwise pauses for `EnrollPickMethodForm`. When TOTP is picked, the
-   * secret is idempotently provisioned in the same step body. Handles
-   * `skip` in `'optional'` mode.
+   * secret is idempotently provisioned in the same step body. Handles `skip`
+   * (optional opt-in) / `cancel` (manage). In the manage flow this only runs
+   * for a zero-MFA user — once the user has factors, the menu pre-seeds
+   * `mfaEnroll.method` (add/change) so the picker is skipped.
    */
   enrollPickMethod(ctx: AuthWfCtx): undefined | Promise<undefined>;
   /**
    * Unified MFA-enrol phase 2 (collect sms/email address + send pincode).
-   * Not invoked for totp. Handles `skip` / `useDifferentMethod`.
+   * Not invoked for totp. Handles `skip` (opt-in) / `cancel` (manage) /
+   * `useDifferentMethod`. Validates the address server-side (the client
+   * `@ui.form.validate` hint is advisory), then STAGES the candidate value in
+   * wf-state (`m.address`) — the user record is written only on confirm
+   * (write-on-confirm), so an ADD leaves no partial row and a REPLACE keeps the
+   * old confirmed value live until the new code verifies in `enroll-confirm`.
    */
   enrollAddress(ctx: AuthWfCtx): Promise<undefined>;
   /**
-   * Unified MFA-enrol phase 3 (verify pincode/TOTP, mark confirmed). On
+   * MFA-enrol TOTP QR step — shown on its OWN pause between method-pick and
+   * code-entry (so the user scans first, types the code next). Idempotently
+   * provisions the TOTP secret in wf-state ONLY (covers the auto-pick /
+   * menu-pre-seeded paths where `enroll-pick-method` was skipped), then pauses
+   * on `EnrollTotpQrForm`. The user record is written only on confirm
+   * (write-on-confirm), so a manage **replace** never clobbers the live totp
+   * secret and a cancel/crash leaves the existing factor intact — no stash or
+   * restore needed. Handles `skip` (opt-in) / `cancel` (manage) /
+   * `useDifferentMethod`.
+   */
+  enrollTotpQr(ctx: AuthWfCtx): Promise<undefined>;
+  /**
+   * Unified MFA-enrol phase 3 (verify pincode/TOTP, then write the factor). On
    * success sets `ctx.mfaEnroll.done = true` AND `ctx.otp.verified = true`
    * (the loop-exit signal — enrol-confirm verifies an OTP, so the unified
    * `otp.verified` flag fires alongside the MFA-specific `mfaEnroll.done`).
+   * This is the ONLY place the enrol trio touches the user record
+   * (write-on-confirm): the proven value (sms/email address or totp secret,
+   * staged in wf-state) is upserted as confirmed via `addMfaMethod`, which
+   * atomically swaps in a REPLACE with no pre-confirm clobber window and creates
+   * a fresh row for an ADD.
    */
   enrollConfirm(ctx: AuthWfCtx): Promise<undefined>;
+  /**
+   * Promote a freshly-confirmed channel into its login-handle column so future
+   * login + recovery resolve the account by it (`findByHandle`). Runs once,
+   * right after `enroll-confirm` in the shared enrolment trio (so it covers
+   * add-mfa AND login/invite forced first-time enrolment). Default is a no-op
+   * unless `resolvePromoteHandleField` is overridden to name a handle column.
+   *
+   * Overridable extension point: a deployment can replace this with richer
+   * logic — e.g. pause on a carrier form asking whether to use the new number
+   * as a login handle before writing it.
+   *
+   * Fires only for a freshly-confirmed `email` / `sms` factor carrying an
+   * address. TOTP has no address; a skipped / `useDifferentMethod` enrolment
+   * cleared `method` + `address` via `clearEnrollScratch`, so the guard below
+   * excludes both — only an actually-confirmed channel is promoted.
+   */
+  promoteToHandle(ctx: AuthWfCtx): Promise<undefined>;
+  /**
+   * Best-effort write of a confirmed channel value into its handle column.
+   * Swallows `ALREADY_EXISTS` — the value is already a handle on ANOTHER
+   * account (e.g. two accounts legitimately sharing one phone for MFA): the
+   * second account keeps the factor as MFA-only and is simply not promoted.
+   * Any other store error propagates. (`UserService.update` translates a
+   * unique-index `CONFLICT` to `ALREADY_EXISTS` for both store adapters.)
+   */
+  protected applyHandlePromotion(subject: string, field: string, value: string): Promise<void>;
   /**
    * Risk step-up: re-evaluate whether to require another MFA round. Default
    * `resolveRiskStepUp` returns `{require: false}`. When `require: true`,
@@ -2664,20 +3016,35 @@ declare class AuthWorkflow {
    */
   changePasswordFlow(): void;
   /**
-   * add-mfa.flow — authenticated self-service "add a second factor". Same
-   * gating model as change-password: NOT `@Public()` — `init-add-mfa` is arbac-
-   * gated (`auth.add-mfa` / `self`) and binds `ctx.subject` from the session, so
-   * an unauthenticated / unauthorized caller is rejected at the first step. NOT
-   * in `DEFAULT_AUTH_WORKFLOWS` — reached only via the GUARDED trigger route
+   * add-mfa.flow — authenticated self-service "Manage two-factor
+   * authentication" (add / change / remove). Same gating model as
+   * change-password: NOT `@Public()` — `init-add-mfa` is arbac-gated
+   * (`auth.add-mfa` / `self`) and binds `ctx.subject` from the session, so an
+   * unauthenticated / unauthorized caller is rejected at the first step. NOT in
+   * `DEFAULT_AUTH_WORKFLOWS` — reached only via the GUARDED trigger route
    * (`AuthController.addMfa`), never the public `/auth/trigger`.
    *
-   * The body REUSES the login/invite forced-enrolment trio verbatim
-   * (`enroll-pick-method` → `enroll-address` → `enroll-confirm`); the only
-   * difference is the driver: `init-add-mfa` narrows `ctx.mfaPolicy`
-   * `availableTransports` to the transports the user has NOT enrolled, so the
-   * picker offers exactly those and auto-picks when one remains. Available only
-   * when something is un-enrolled — with everything enrolled the trio is skipped
-   * and `finish-add-mfa` returns a benign "nothing to add" terminal.
+   * Shape:
+   * 1. `init-add-mfa` — bind subject, resolve the FULL transport set + the
+   *    un-enrolled `candidates`, mark `stepUpRequired` when the user already has
+   *    ≥1 confirmed factor, and put the enrol forms in `'manage'` mode.
+   * 2. `prepare-locked-mfa-transports` — resolve which factors the consumer
+   *    forbids changing (handle-bound email/phone).
+   * 3. STEP-UP (only when `stepUpRequired`): re-verify identity before any
+   *    change — `mfaStepUpLoop` challenges an EXISTING factor when one is still
+   *    challengeable (`stepUpMode==='mfa'`), else `manage-password-reauth` falls
+   *    back to the account password (`stepUpMode==='password'`). On success
+   *    `manage-stepup-done` swaps off the encapsulated start onto the durable
+   *    `store` strategy (server-anchored, replay-resistant; mirrors login's
+   *    swap-after-credentials).
+   * 4. `manage-menu` (only when `stepUpRequired`) — pick add / change / remove +
+   *    target; pre-seeds `mfaEnroll.method` for add/change.
+   * 5. Route: `confirm-remove-mfa` for remove; otherwise the REUSED enrol trio
+   *    (`enroll-pick-method` → `enroll-address` / `enroll-totp-qr` →
+   *    `enroll-confirm`). A zero-MFA user skips step-up + menu and lands on the
+   *    enrol picker directly (the first-time opt-in path).
+   * 6. `finish-add-mfa` — added / changed / removed / cancelled / nothing terminal.
+   *    The user KEEPS their session (no token re-issue).
    */
   addMfaFlow(): void;
   /**