@aooth/auth-moost 0.1.3 → 0.1.4

package/dist/index.d.mts

@@ -1,9 +1,10 @@
+import { Mate, TInterceptorDef, TMateParamMeta, TMoostMetadata } from "moost";
 import { AuthContext, AuthContext as AuthContext$1, AuthCredential, AuthEmailEvent, AuthEmailKind, AuthEmailKind as AuthEmailKind$1, AuthSmsEvent, AuthSmsKind, AuthSmsKind as AuthSmsKind$1, BuildMagicLinkUrl, BuildMagicLinkUrl as BuildMagicLinkUrl$1, EmailSender, EmailSender as EmailSender$1, IssueResult, IssueResult as IssueResult$1, SmsSender, generateMagicLinkToken } from "@aooth/auth";
 import * as _$_wooksjs_event_core0 from "@wooksjs/event-core";
 import { TCookieAttributesInput } from "@wooksjs/event-http";
-import { Mate, TInterceptorDef, TMateParamMeta, TMoostMetadata } from "moost";
-import { MoostWf, WfOutlet, WfOutletTokenConfig, WfStateStrategy } from "@moostjs/event-wf";
 import { TrustedDeviceRecord, UserCredentials, UserService } from "@aooth/user";
+import { WfFinished } from "@atscript/moost-wf";
+import { MoostWf, WfOutlet, WfOutletTokenConfig, WfStateStrategy } from "@moostjs/event-wf";
 import { TAtscriptAnnotatedType } from "@atscript/typescript/utils";
 
 //#region src/auth.config.d.ts
@@ -46,6 +47,431 @@ interface ResolvedAuthOptions {
   enableBearer: boolean;
 }
 //#endregion
+//#region src/auth.opts.d.ts
+declare class AuthOpts {
+  /** Pincode infrastructure shared by login MFA, invite MFA, and recovery OTP. */
+  mfa: {
+    pincodeLength: number;
+    pincodeTtlMs: number;
+    pincodeResendTimeoutMs: number;
+  };
+  /** Magic-link TTL shared by login (alt-credentials), invite, recovery. */
+  magicLinkTtlMs: number;
+  /** Canonical login URL — used by invite (post-accept redirect) and recovery (abort-to-login + post-reset redirect) as the resolver-default loginUrl. */
+  loginUrl: string;
+  /** TOTP provisioning issuer — used by login MFA and invite MFA enrollment. */
+  totpIssuer: string;
+}
+//#endregion
+//#region src/workflows/auth-workflow.base.d.ts
+/**
+ * Method names for the MFA enrollment helper. Re-exported from
+ * `login.workflow.options` as `MfaTransport` (kept as the public alias) so
+ * existing consumers don't need to switch import paths.
+ */
+type MfaTransport = "sms" | "email" | "totp";
+/**
+ * Context shape consumed by the `enrollPickPhase` / `enrollAddressPhase` /
+ * `enrollConfirmPhase` helpers. Both `LoginWfCtx` and
+ * `InviteWfCtx` extend this implicitly (they declare the same field set).
+ * Kept structural so neither workflow's full ctx union has to be imported
+ * here — base stays workflow-agnostic.
+ */
+interface MfaEnrollCtx {
+  enrollMethod?: MfaTransport;
+  enrollAddress?: string;
+  enrollSecret?: string;
+  enrollUri?: string;
+  enrollAvailableTransports?: MfaTransport[];
+  enrollDone?: boolean;
+  pin?: string;
+  pinExpire?: number;
+  pinSentTo?: string;
+  /**
+   * Next-allowed-resend timestamp for the Phase 3 confirm pincode (sms/email
+   * only). Written by the Phase 2 initial send + the Phase 3 `resend`
+   * alt-action; consulted by `resend` to throttle re-emits. Mirrors the
+   * `pinTimeout` pattern used by the login `pincode-check-login` step.
+   */
+  enrollPincodeCooldown?: number;
+}
+/**
+ * Looser structural mirror of `DeliverPayload` from `login.workflow.ts`.
+ * The base file mustn't import from a sibling workflow file; the concrete
+ * workflow's strict discriminated union is structurally assignable to this.
+ */
+interface DeliverPayloadLike {
+  channel: "email" | "sms";
+  kind: string;
+  recipient: string;
+  code?: string;
+  expiresAt?: number;
+  ttlMs?: number;
+  userId?: string;
+}
+interface MfaEnrollDeps {
+  ctx: MfaEnrollCtx;
+  username: string;
+  users: UserService;
+  /** Concrete workflow's `deliver` hook, narrowed to the payloads this flow emits. */
+  deliver: (payload: DeliverPayloadLike) => Promise<void>;
+  forms: {
+    pickMethod: TAtscriptAnnotatedType;
+    address: TAtscriptAnnotatedType;
+    confirm: TAtscriptAnnotatedType;
+  };
+  transports: MfaTransport[];
+  pincodeLength: number;
+  pincodeTtlMs: number;
+  /**
+   * Per-method resend cooldown for the Phase 3 confirm pincode (sms/email).
+   * Mirrors `LoginWorkflowOpts.mfa.pincodeResendTimeoutMs`.
+   */
+  pincodeResendTimeoutMs: number;
+  /** TOTP provisioning issuer (rendered in the authenticator app). */
+  issuer: string;
+  /**
+   * Enrollment policy. `'required'` runs through all 3 phases. `'optional'`
+   * additionally watches for a `skip` action on the Phase 1 pickMethod form —
+   * a skip click short-circuits by setting `ctx.enrollDone = true`. The
+   * caller is expected to gate this step out entirely when `mode === 'disabled'`.
+   */
+  mode: "required" | "optional";
+  /**
+   * Optional bridge fired at the end of `enrollConfirmPhase` (or on a skip in
+   * `'optional'` mode at any phase) — right after `enrollDone` flips true. Login
+   * uses this to mirror `enrollDone` → `mfaChecked` so its outer MFA while-loop
+   * (gated on `!mfaChecked`) exits. Invite omits it because its enrollment
+   * while-loop is gated on `!enrollDone` directly.
+   */
+  onComplete?: (ctx: MfaEnrollCtx) => void;
+}
+/** Workflow context shape expected by `mintPin` + `verifyPin`. */
+interface PinCtx {
+  pin?: string;
+  pinExpire?: number;
+}
+/**
+ * Structural ctx shape consumed by `processInlineConsent`. Mirrors the
+ * relevant subset of the workflow ctx types so the helper stays
+ * workflow-agnostic. The helper consumes only the dynamic `pendingConsents`
+ * descriptor array (populated by `prepare-consents` from
+ * `ConsentStore.getPendingConsents()`) and the per-run booking fields it
+ * writes itself — the prior static `acceptance` / `termsVersion` branches
+ * were retired in Phase 6 along with the matching `ctx.acceptance` field
+ * on each workflow ctx type.
+ */
+interface InlineConsentCtx {
+  /**
+   * Descriptors the user still needs to be prompted for — set once by
+   * `prepare-consents` after username-bind. Empty / unset ⇒ no consents to
+   * collect (helper short-circuits).
+   */
+  pendingConsents?: ConsentDescriptorLike[];
+  /**
+   * Subset of descriptor ids the user ticked on the carrier form. Set by
+   * `processInlineConsent` after silent-dropping unknown ids — `pendingConsents`
+   * is the server's whitelist, NOT what the client posts.
+   */
+  acceptedConsentIds?: string[];
+  /**
+   * Wall-clock ms at the moment `processInlineConsent` resolved the
+   * `consents` array. Captured here so the persisted `ConsentEvent.at`
+   * reflects user-action time, not write-time — surviving a paused
+   * workflow's resume gap.
+   */
+  consentsDecidedAt?: number;
+  /**
+   * Set true by `persist-consents` after the batched `consentStore.save`
+   * call fires (or after the step short-circuits with no pending consents).
+   * Gates the helper from re-staging on a subsequent carrier-form submission.
+   */
+  consentsPersisted?: boolean;
+}
+/**
+ * Structural alias of `ConsentDescriptor` — kept inline so this module
+ * doesn't import from `../consent.store.ts` (which would create a cycle:
+ * consent.store.ts already imports `ConsentEvent` from here).
+ */
+interface ConsentDescriptorLike {
+  id: string;
+  text: string;
+  required?: string;
+  version?: string;
+}
+/**
+ * Subset of the carrier-form payload that `processInlineConsent` reads.
+ * Phase 5 replaces the pre-existing static `{ acceptedTerms?, marketingOptIn? }`
+ * pair with a single dynamic `consents: string[]` — the SUBSET of descriptor
+ * ids the user ticked in the `AsConsentArray` (`@atscript/vue-aooth`)
+ * component. The server reads `pendingConsents` from its own ctx (NOT from
+ * this input) to decide which ids are valid; unknown ids are silently
+ * dropped (audit-grade defense — see helper rationale).
+ */
+interface InlineConsentInput {
+  consents?: string[];
+}
+/**
+ * Consent event emitted to the `ConsentStore.save(username, events)` DI
+ * provider. Storage shape is intentionally the consumer's call — Mongo users
+ * typically push the events onto an embedded array, SQL users insert into an
+ * audit table, event-bus users publish to a topic. The library batches all
+ * collected events from a single workflow run into one call: ONE event per
+ * pending descriptor (audit-friendly default — declined-optional consents
+ * are persisted too, so customers can prove the user was asked; customers
+ * who want only accepted events filter in their `save()` override). The
+ * `accepted` boolean is explicit per row — `true` when the user ticked the
+ * matching descriptor, `false` when an optional descriptor went un-ticked.
+ */
+interface ConsentEvent {
+  /** Identifier from the matching `ConsentDescriptor.id`. */
+  id: string;
+  /** Whether the user ticked this descriptor (`false` for un-ticked optionals). */
+  accepted: boolean;
+  /** Stamped from the matching `ConsentDescriptor.version` (when set). */
+  version?: string;
+  /**
+   * Wall-clock ms at the moment `processInlineConsent` resolved the user's
+   * carrier-form submission (NOT at write-time — captured BEFORE the batched
+   * `consentStore.save` call so a paused-workflow resume gap doesn't drift
+   * the timestamp).
+   */
+  at: number;
+}
+/**
+ * Structural alias for `ReturnType<typeof useAtscriptWf>` — only the
+ * `requireInput` method is consumed by `processInlineConsent`, kept narrow
+ * so callers can pass any form's wf handle without TS choking on the form-
+ * specific `resolveInput` return type.
+ */
+type WfRequireInputOnly = {
+  requireInput(opts?: {
+    errors?: Record<string, string>;
+    formMessage?: string;
+  }): unknown;
+};
+declare class AuthWorkflowBase {
+  /**
+   * Asserts `ctx.username` is populated. Workflow steps reach for `ctx.username`
+   * after `credentials`/`init` has set it; losing it indicates a workflow-state
+   * bug, not a client error. Throws `HttpError(500)` on miss; otherwise narrows
+   * the field to `string` for the caller via `asserts`.
+   */
+  protected requireUsername<T extends {
+    username?: string;
+  }>(ctx: T): asserts ctx is T & {
+    username: string;
+  };
+  /**
+   * Wrap an `UserStore` mutation that can race (`withCas`-backed paths:
+   * `consumeBackupCode`, `addMfaMethod`, `confirmMfaMethod`, `addTrustedDevice`)
+   * so a CAS retry-budget exhaustion surfaces as 409 Conflict — the canonical
+   * OCC status — rather than bubbling to the moost default 500. Client SHOULD
+   * retry; a 500 falsely implies the server is broken. Other `UserAuthError`
+   * shapes pass through unchanged so step-local catch blocks (e.g. ALREADY_EXISTS
+   * → 409 with a different reason) still see them.
+   */
+  protected withStoreErrorTranslation<T>(op: () => Promise<T>): Promise<T>;
+  /**
+   * Resolve the client IP from the active HTTP request, swallowing the case
+   * where there is no HTTP context (unit tests that hand-roll the wf runtime).
+   */
+  protected resolveClientIp(): string | undefined;
+  /**
+   * Mint a numeric pincode and stash it + its expiry onto `ctx`. Returns the
+   * code so the caller can hand it to the delivery transport.
+   */
+  protected mintPin(ctx: PinCtx, length: number, ttlMs: number): string;
+  /**
+   * Verify a submitted pincode against `ctx.pin`. Returns a `{ code: '…' }`
+   * error map on expired/invalid, or `null` on success. Callers wrap the result
+   * with `useAtscriptWf(PincodeForm).requireInput({ errors })`.
+   */
+  protected verifyPin(ctx: PinCtx, submitted: string | undefined): {
+    code: string;
+  } | null;
+  /**
+   * Validate + stash inline-consent fields submitted on a carrier form.
+   *
+   * SECURITY (silent-drop): the server reads its OWN `ctx.pendingConsents`
+   * (set once by `prepare-consents` from `ConsentStore.getPendingConsents()`)
+   * as the authoritative whitelist of valid descriptor ids. Any id in the
+   * user-submitted `input.consents` array that does NOT match a current
+   * pending descriptor is SILENTLY DROPPED — no error, no log, no signal
+   * back to the client. This preserves the audit-grade
+   * "what user saw is what server records" invariant: an attacker
+   * submitting `consents: ['terms', 'gdpr-forged-id']` against a descriptor
+   * list of only `['terms']` cannot forge an audit record for the
+   * never-displayed `'gdpr-forged-id'` consent. Surfacing the drop would
+   * leak the consent universe (probing surface), so the defense is silent.
+   *
+   * SECURITY (mandatory-by-message): each descriptor's `required` field is
+   * the load-bearing mandatory flag. A non-empty string means the consent
+   * is MANDATORY and that string IS the per-row error message — the
+   * `AsConsentArray` component surfaces it inline per descriptor; the
+   * server throws the SAME copy as a form-level error on the bound
+   * `consents` field when the first required descriptor is missing from
+   * the submitted set. Absent / empty `required` ⇒ optional consent — the
+   * un-ticked descriptor is still persisted as `{accepted: false}` (audit
+   * default — proves the user was asked).
+   *
+   * Idempotency: once `ctx.consentsPersisted` is true, the helper is a
+   * no-op. Same for `ctx.pendingConsents` being empty / unset — no
+   * pending = nothing to validate (the carrier-form's `AsConsentArray`
+   * also self-hides on empty `pendingConsents`).
+   */
+  protected processInlineConsent(ctx: InlineConsentCtx, input: InlineConsentInput, wf: WfRequireInputOnly): void;
+  /**
+   * Batched consent persistence — shared `persist-consents` step body for
+   * `LoginWorkflow` / `InviteWorkflow` / `RecoveryWorkflow`. Fans one
+   * `ConsentEvent` per pending descriptor out to the `ConsentStore.save`
+   * DI provider in a single call. Audit-friendly default: declined-optional
+   * consents are persisted with `accepted: false` (customers who want only
+   * accepted events filter in their `save()` override). `accepted` is
+   * derived per descriptor by `acceptedConsentIds.has(id)`. Idempotent via
+   * `ctx.consentsPersisted`; short-circuits with no events when
+   * `pendingConsents` is empty (defensive — the schema condition gates on
+   * `consentsDecidedAt` which is only set when pending was non-empty).
+   *
+   * Each workflow's `@Step("persist-consents")` method is a one-liner
+   * delegate to this helper — the @Step decorator must stay on the
+   * subclass so the wf engine registers the step id under the correct
+   * controller, but the body lives here once.
+   */
+  protected runPersistConsents(ctx: InlineConsentCtx & {
+    username?: string;
+  }, consentStore: ConsentStore): Promise<undefined>;
+  /**
+   * Phase 1 of MFA enrollment. Picks the method (auto-pick if only one
+   * transport, otherwise pause for the picker form), handles the `skip`
+   * alt-action in `'optional'` mode, and — when TOTP is picked — provisions
+   * the secret idempotently in the same step body so the next iteration can
+   * proceed straight to confirm. Sync-friendly return type because the
+   * auto-pick branch and the picker-form branch both stay synchronous; the
+   * TOTP-provisioning tail is the only async path.
+   *
+   * Atomic boundary: after this helper runs, `ctx.enrollMethod` is set AND
+   * (for totp) `ctx.enrollSecret` is provisioned. Confirm doesn't need to
+   * worry about provisioning.
+   */
+  protected enrollPickPhase(deps: MfaEnrollDeps): undefined | Promise<undefined>;
+  /**
+   * Phase 2 of MFA enrollment. Collects the sms/email address, persists it as
+   * an unconfirmed method, mints + dispatches the pincode. Handles `skip` /
+   * `useDifferentMethod` alt-actions. Not invoked for totp (no address to
+   * collect — the schema condition gates it out).
+   */
+  protected enrollAddressPhase(deps: MfaEnrollDeps): Promise<undefined>;
+  /**
+   * Phase 3 of MFA enrollment. Verifies the user-submitted code (TOTP or
+   * pincode), marks the method confirmed, sets it as the default, and flags
+   * `ctx.enrollDone = true`. Handles `skip` / `useDifferentMethod` / `resend`
+   * alt-actions (cleanup on the first two; resend re-mints + redispatches).
+   *
+   * Idempotently provisions the TOTP secret at the top when missing — covers
+   * the path where a consumer setter override (e.g. `inviteSetupMfa`)
+   * pre-picks totp, leaving pickPhase's schema gate closed; the secret IS
+   * what confirm needs, so confirm guarantees it exists. For sms/email the
+   * unconfirmed method row + pincode are written by addressPhase, so there's
+   * nothing to provision here.
+   */
+  protected enrollConfirmPhase(deps: MfaEnrollDeps): Promise<undefined>;
+  /**
+   * Send a pincode for the active sms/email enrollment method and stamp
+   * `ctx.pinSentTo` with the masked recipient. Shared by Phase 2 initial
+   * dispatch and Phase 3 `resend`. Caller is responsible for `mintPin` +
+   * stamping `enrollPincodeCooldown` BEFORE calling — this just dispatches.
+   * Not called for TOTP (no pincode to send).
+   */
+  protected sendEnrollPincode(ctx: MfaEnrollCtx, deps: MfaEnrollDeps, address: string, code: string): Promise<void>;
+  /**
+   * Cleanup any partially-persisted enrollment state (unconfirmed method row +
+   * ctx scratch). Called when the user picks `skip` or `useDifferentMethod`
+   * mid-flow on Phase 3, where the unconfirmed method has already been written
+   * via `addMfaMethod` (Phase 1 for totp, Phase 2 for sms/email). On
+   * `useDifferentMethod` the caller relies on `enrollMethod` being cleared so
+   * the loop re-enters Phase 1.
+   */
+  protected cleanupEnrollment(ctx: MfaEnrollCtx, users: UserService, username: string): Promise<void>;
+}
+//#endregion
+//#region src/consent.store.d.ts
+/**
+ * Descriptor for a single consent prompt. Customers' ConsentStore.getPendingConsents
+ * returns an array of these — the workflow transports them via `@wf.context.pass`
+ * to the SPA carrier form, which renders one row per descriptor through the
+ * `AsConsentArray` component (`@atscript/vue-aooth`). The user-submitted
+ * `consents: string[]` field on the carrier form posts back the SUBSET of
+ * `id`s the user accepted; the server-side `processInlineConsent` helper
+ * silently drops any ids that don't match a current descriptor (audit-grade
+ * "what user saw is what server records" invariant — preventing an attacker
+ * from forging audit rows for consents the user was never shown).
+ */
+interface ConsentDescriptor {
+  /** Stable identifier — committed to the user-submitted `consents: string[]`
+   *  array and stamped on the persisted `ConsentEvent` (customer-defined:
+   *  `'terms'`, `'marketing'`, `'jurisdiction-gdpr'`, …). */
+  id: string;
+  /** User-facing label / disclosure text. Markdown links are allowed; the
+   *  SPA component will sanitize-render. */
+  text: string;
+  /**
+   * When present and non-empty, the consent is MANDATORY and this string IS
+   * the per-row error message surfaced by `AsConsentArray` (and the
+   * server-side `processInlineConsent` form-level error) when the user
+   * submits without ticking it. Absent or empty string ⇒ optional consent —
+   * a `ConsentEvent` with `accepted: false` is still persisted so the audit
+   * record proves the user was asked.
+   */
+  required?: string;
+  /** Stamped onto persisted ConsentEvent for versioned policies (terms, ...). */
+  version?: string;
+}
+/**
+ * Injectable DI seam for consent persistence + the customer-defined consent
+ * universe. SINGLETON-scoped (one instance per app lifetime). All methods are
+ * no-op defaults — customers extend this class and replace via
+ * `createReplaceRegistry([ConsentStore, MyConsentStore])`.
+ */
+declare class ConsentStore {
+  /**
+   * Returns descriptors for consents this user still needs to accept on the
+   * next prompt boundary. Empty array → no consent step renders. The workflow
+   * passes its identity + (optionally) the channel it's about to use so the
+   * customer's impl can prompt different consent sets per workflow/channel.
+   */
+  getPendingConsents(_username: string | undefined, _ctx: {
+    workflow: string;
+    channel?: "email" | "sms";
+  }): Promise<ConsentDescriptor[]>;
+  /**
+   * Persist a batch of captured consent events. Default: no-op. Override to
+   * write to your audit table / event store / whatever your legal team
+   * requires.
+   */
+  save(_username: string, _events: ConsentEvent[]): Promise<void>;
+  /**
+   * Read consent history for a user, optionally filtered by event id.
+   * Used by getPendingConsents impls that want to compute "has the user
+   * already accepted version vN" without maintaining a separate index.
+   */
+  read(_username: string, _filter?: {
+    id?: string;
+  }): Promise<ConsentEvent[]>;
+  /**
+   * Fired by LoginWorkflow's verify/:channel step AFTER pincode validates,
+   * i.e., AFTER channel ownership is confirmed. The disclosure text is the
+   * literal copy the user saw beneath the input field at ask/:channel time
+   * (resolveOtpDisclosure result) — passed through so the customer's record
+   * pins exactly what was shown to the user.
+   *
+   * Default: no-op. Disclosure-only is sufficient for transactional OTPs
+   * under TCPA/PECR/CASL/GDPR. Override if your jurisdiction or legal team
+   * requires affirmative consent capture for OTP channels.
+   */
+  recordOtpChannelConsent(_username: string, _channel: "email" | "sms", _target: string, _disclosure: string): Promise<void>;
+}
+//#endregion
 //#region src/auth.guard.d.ts
 /**
  * `GUARD`-priority interceptor factory that authenticates incoming requests.
@@ -76,7 +502,7 @@ declare function authGuardInterceptor(opts?: AuthOptions): TInterceptorDef;
  */
 declare function AuthGuarded(opts?: AuthOptions): ClassDecorator & MethodDecorator;
 //#endregion
-//#region ../../node_modules/.pnpm/@wooksjs+event-wf@0.7.12_@prostojs+logger@0.4.3_@wooksjs+event-core@0.7.12_@wooksjs+eve_83c9b5cff779134c35c379089be157ae/node_modules/@wooksjs/event-wf/dist/index.d.ts
+//#region ../../node_modules/.pnpm/@wooksjs+event-wf@0.7.15_@prostojs+logger@0.4.3_@wooksjs+event-core@0.7.15_@wooksjs+eve_11afd4acf41dda7cd1e566c02621a2f8/node_modules/@wooksjs/event-wf/dist/index.d.ts
 interface WfFinishedResponse {
   type: 'redirect' | 'data';
   /** Redirect URL or response body */
@@ -210,15 +636,15 @@ declare function getAuthMate(): AuthMate;
 //#endregion
 //#region src/auth.controller.d.ts
 /** Workflows allowed by the bundled `/auth/trigger` endpoint. Subclasses override `triggerWf()` to extend. */
-declare const DEFAULT_AUTH_WORKFLOWS: readonly ["auth.login", "auth.recovery", "auth.invite"];
+declare const DEFAULT_AUTH_WORKFLOWS: readonly ["auth/login/flow", "auth/recovery/flow", "auth/invite/start"];
 /**
  * Public REST endpoints for credential management. Four endpoints total:
  *
  * - `POST /auth/logout` — best-effort token revocation + cookie clear.
  * - `POST /auth/refresh` — rotate access/refresh tokens.
  * - `GET /auth/status` — return the current `AuthContext`.
- * - `POST /auth/trigger` — single workflow trigger covering `auth.login`,
- *   `auth.recovery`, and `auth.invite`.
+ * - `POST /auth/trigger` — single workflow trigger covering `auth/login/flow`,
+ *   `auth/recovery/flow`, and `auth/invite/start`.
  *
  * The historical `/auth/login` and `/auth/password` endpoints were dropped —
  * both flows go through the workflow trigger now (full MFA / SSO / etc.
@@ -230,11 +656,37 @@ declare const DEFAULT_AUTH_WORKFLOWS: readonly ["auth.login", "auth.recovery", "
  */
 declare class AuthController {
   protected readonly auth: AuthCredential;
-  constructor(auth: AuthCredential);
+  protected readonly users?: UserService | undefined;
+  constructor(auth: AuthCredential, users?: UserService | undefined);
   logout(body: AuthLogoutBody | undefined): Promise<AuthOkResponse>;
   refresh(body: AuthRefreshBody | undefined): Promise<AuthLoginResponse>;
   status(): AuthContext$1;
   triggerWf(): void;
+  /**
+   * Side route mapping a redeemed-invite `uid` to the same idempotent
+   * envelope the `inviteIdempotentRedirect` workflow step renders. The SPA
+   * falls through to this when an invite magic-link is re-clicked after
+   * redemption: the wf state store has already evicted the finished state
+   * (returns 410) so the workflow can't re-enter `inviteCheckPendingInvitation`,
+   * but the user-id baked into the magic-link URL by `buildMagicLinkUrl(…, {
+   * userId })` lets the SPA resolve the "already accepted" condition itself.
+   *
+   * `@Public()` — invitees aren't signed in at this point.
+   *
+   * Defaults for `loginUrl` / `alreadyAcceptedRedirectUrl` mirror the bundled
+   * `InviteWorkflowOpts` defaults (`/login` / `/login`). Subclasses override
+   * `resolveInvitePostRedemption()` to read live workflow opts.
+   */
+  invitePostRedemption(uid: string | undefined): Promise<WfFinished>;
+  /**
+   * URLs used by `invitePostRedemption`. Defaults mirror
+   * `mergeInviteOpts({})` so subclasses that customize either of those
+   * options can override here to keep the side route in sync.
+   */
+  protected resolveInvitePostRedemption(): {
+    loginUrl: string;
+    alreadyAcceptedRedirectUrl: string;
+  };
 }
 //#endregion
 //#region src/wf-trigger/decorator.d.ts
@@ -271,6 +723,11 @@ declare const WfTrigger: (opts?: WfTriggerOpts) => ClassDecorator & MethodDecora
  * Uses `handleAsOutletRequest` (not `MoostWf.handleOutlet`) because the atscript
  * wrapper restores the `finished: true` marker that `<AsWfForm>` keys off — the
  * bare wooks request handler strips it during `useWfFinished()` unwrap.
+ *
+ * The trigger is a thin pass-through to `handleAsOutletRequest`: the new
+ * `@atscript/moost-wf` wire envelope is `{ wfs, input: { action?, formData? } }`,
+ * and the wf engine reads action + form data directly from `body.input`. No
+ * app-level bridging of `body.action` is needed.
  */
 declare class WfTriggerProvider {
   protected readonly wf: MoostWf;
@@ -298,7 +755,7 @@ interface AuditEvent {
   kind: string;
   /** Auth-scoped user identity (the `username` resolved by the workflow). */
   userId?: string;
-  /** Workflow id that emitted the event (e.g. `auth.login`). */
+  /** Workflow id that emitted the event (e.g. `auth/login/flow`). */
   workflow?: string;
   /** Source IP (when the workflow could resolve one). */
   ip?: string;
@@ -313,7 +770,6 @@ interface AuditEmitter {
 //#endregion
 //#region src/workflows/login.workflow.options.d.ts
 type LoginRedirect = "referer" | "home" | false | null;
-type MfaTransport = "sms" | "email" | "totp";
 interface SsoProvider {
   id: string;
   label: string;
@@ -324,60 +780,11 @@ interface ConcurrencyLimitOptions {
   onLimit: "reject" | "kickPrompt";
 }
 interface LoginWorkflowOpts {
-  alternateCredentials?: {
-    forgotPassword?: boolean;
-    signup?: boolean;
-    magicLink?: boolean;
-    magicLinkSkipsMfa?: boolean;
-    magicLinkTtlMs?: number;
-    ssoProviders?: SsoProvider[];
-    recoveryUrl?: string;
-    signupUrl?: string;
-    embedRecovery?: boolean;
-  };
-  guards?: {
-    emailVerifiedRequired?: boolean;
-    passwordExpiry?: boolean;
-    passwordInitial?: boolean;
-  };
-  enrollment?: {
-    ensureEmail?: boolean;
-    ensurePhone?: boolean;
-  };
-  mfa?: {
-    enabled?: boolean;
-    transports?: MfaTransport[];
-    backupCodes?: boolean;
-    enrollRequired?: boolean;
-    pincodeTtlMs?: number;
-    pincodeResendTimeoutMs?: number; /** Numeric length of the server-generated OTP for SMS/email pincodes. */
-    pincodeLength?: number;
-  };
   deviceTrust?: {
-    enabled?: boolean;
-    optIn?: boolean;
     cookieName?: string;
     ttlMs?: number;
-    skipsMfa?: boolean;
     bindsTo?: "cookie" | "cookie+ip";
   };
-  acceptance?: {
-    termsVersion?: string;
-    profileCompleteRequired?: boolean;
-    consentMarketing?: boolean;
-  };
-  multiContext?: {
-    tenantSelect?: boolean;
-    personaSelect?: boolean;
-  };
-  sessionPolicy?: {
-    concurrencyLimit?: ConcurrencyLimitOptions;
-  };
-  finalize?: {
-    auditLogin?: boolean;
-    notifyNewDevice?: boolean;
-    redirect?: LoginRedirect;
-  };
   /**
    * Replaceable form schemas. Each field defaults to the corresponding
    * `.as` form shipped under `@aooth/auth-moost/atscript/models`; supply a
@@ -388,7 +795,9 @@ interface LoginWorkflowOpts {
     askPhone?: TAtscriptAnnotatedType;
     backupCode?: TAtscriptAnnotatedType;
     concurrencyLimit?: TAtscriptAnnotatedType;
-    consentMarketing?: TAtscriptAnnotatedType;
+    enrollAddress?: TAtscriptAnnotatedType;
+    enrollConfirm?: TAtscriptAnnotatedType;
+    enrollPickMethod?: TAtscriptAnnotatedType;
     loginCredentials?: TAtscriptAnnotatedType;
     mfaCode?: TAtscriptAnnotatedType;
     personaSelect?: TAtscriptAnnotatedType;
@@ -397,78 +806,28 @@ interface LoginWorkflowOpts {
     select2fa?: TAtscriptAnnotatedType;
     setPassword?: TAtscriptAnnotatedType;
     tenantSelect?: TAtscriptAnnotatedType;
-    termsAccept?: TAtscriptAnnotatedType;
+    termsBump?: TAtscriptAnnotatedType;
   };
 }
 /**
  * Fully-resolved view used by the workflow at runtime — every nested group is
- * always populated by `mergeLoginOpts`, so schema conditions can read
- * `ctx.opts.<group>.<flag>` directly without optional chaining.
- *
- * Fields without sensible defaults (e.g. `termsVersion`, `concurrencyLimit`)
- * stay optional inside their group.
+ * always populated by `mergeLoginOpts`, so step bodies can read
+ * `this.opts.<group>.<flag>` directly without optional chaining.
  */
 interface ResolvedLoginWorkflowOpts {
-  alternateCredentials: {
-    forgotPassword: boolean;
-    signup: boolean;
-    magicLink: boolean;
-    magicLinkSkipsMfa: boolean;
-    magicLinkTtlMs: number;
-    ssoProviders: SsoProvider[];
-    recoveryUrl: string;
-    signupUrl: string;
-    embedRecovery: boolean;
-  };
-  guards: {
-    emailVerifiedRequired: boolean;
-    passwordExpiry: boolean;
-    passwordInitial: boolean;
-  };
-  enrollment: {
-    ensureEmail: boolean;
-    ensurePhone: boolean;
-  };
-  mfa: {
-    enabled: boolean;
-    transports: MfaTransport[];
-    backupCodes: boolean;
-    enrollRequired: boolean;
-    pincodeTtlMs: number;
-    pincodeResendTimeoutMs: number;
-    pincodeLength: number;
-  };
   deviceTrust: {
-    enabled: boolean;
-    optIn: boolean;
     cookieName: string;
     ttlMs: number;
-    skipsMfa: boolean;
     bindsTo: "cookie" | "cookie+ip";
   };
-  acceptance: {
-    termsVersion?: string;
-    profileCompleteRequired: boolean;
-    consentMarketing: boolean;
-  };
-  multiContext: {
-    tenantSelect: boolean;
-    personaSelect: boolean;
-  };
-  sessionPolicy: {
-    concurrencyLimit?: ConcurrencyLimitOptions;
-  };
-  finalize: {
-    auditLogin: boolean;
-    notifyNewDevice: boolean;
-    redirect: LoginRedirect;
-  };
   forms: {
     askEmail: TAtscriptAnnotatedType;
     askPhone: TAtscriptAnnotatedType;
     backupCode: TAtscriptAnnotatedType;
     concurrencyLimit: TAtscriptAnnotatedType;
-    consentMarketing: TAtscriptAnnotatedType;
+    enrollAddress: TAtscriptAnnotatedType;
+    enrollConfirm: TAtscriptAnnotatedType;
+    enrollPickMethod: TAtscriptAnnotatedType;
     loginCredentials: TAtscriptAnnotatedType;
     mfaCode: TAtscriptAnnotatedType;
     personaSelect: TAtscriptAnnotatedType;
@@ -477,7 +836,7 @@ interface ResolvedLoginWorkflowOpts {
     select2fa: TAtscriptAnnotatedType;
     setPassword: TAtscriptAnnotatedType;
     tenantSelect: TAtscriptAnnotatedType;
-    termsAccept: TAtscriptAnnotatedType;
+    termsBump: TAtscriptAnnotatedType;
   };
 }
 /**
@@ -489,33 +848,168 @@ declare function mergeLoginOpts(opts?: LoginWorkflowOpts): ResolvedLoginWorkflow
 //#endregion
 //#region src/workflows/login.workflow.d.ts
 interface LoginWfCtx {
-  opts?: ResolvedLoginWorkflowOpts;
+  /**
+   * Whether the user must complete profile fields BEFORE token issuance.
+   * Populated by `prepare-profile` from `resolveProfile(ctx).required`.
+   * Default-false matches the prior behavior (most consumers don't gate logins
+   * on profile completion). Read by the `profile-complete` schema condition.
+   */
+  profileCompleteRequired?: boolean;
+  alternateCredentials?: {
+    forgotPassword: boolean;
+    signup: boolean;
+    magicLink: boolean;
+    magicLinkSkipsMfa: boolean;
+    ssoProviders: SsoProvider[];
+    recoveryUrl: string;
+    signupUrl: string;
+    embedRecovery: boolean;
+  };
+  deviceTrust?: {
+    enabled: boolean;
+    optIn: boolean;
+    skipsMfa: boolean;
+  };
+  enrollment?: {
+    ensureEmail: boolean;
+    ensurePhone: boolean;
+  };
+  finalize?: {
+    auditLogin: boolean;
+    notifyNewDevice: boolean;
+    redirect: LoginRedirect;
+  };
+  guards?: {
+    passwordInitial: boolean;
+    passwordExpiry: boolean;
+    emailVerifiedRequired: boolean;
+  };
+  mfaConfig?: {
+    backupCodes: boolean;
+  };
+  multiContext?: {
+    tenantSelect: boolean;
+    personaSelect: boolean;
+  };
+  sessionPolicy?: {
+    concurrencyLimit?: ConcurrencyLimitOptions;
+  };
   username?: string;
   /** Legacy alias for `pwReset`; kept until tests migrate. */
   mfaRequired?: boolean;
   isPasswordInitial?: boolean;
   usedMagicLink?: boolean;
+  /**
+   * 3-state MFA policy:
+   *   - `'required'` — MFA enforced; users with 0 methods MUST enroll (no skip).
+   *   - `'optional'` — MFA prompted; users with 0 methods see an enrollment
+   *     form that offers a `skip` action (in-flight opt-out).
+   *   - `'disabled'` — MFA loops never fire; Phase 4 is skipped entirely.
+   */
+  mfaMode?: "required" | "optional" | "disabled";
+  availableMfaTransports?: MfaTransport[];
+  /** Pre-selected MFA transport (e.g. existing-user default, single-transport auto-pick). */
+  currentMfa?: MfaTransport;
   email?: string;
   emailConfirmed?: boolean;
   phone?: string;
   phoneConfirmed?: boolean;
+  /**
+   * Disclosure text rendered beneath the channel input field on
+   * `AskEmailForm` / `AskPhoneForm` at ask-time (BEFORE the user submits
+   * their email/phone — typing + submitting constitutes implied consent).
+   * Forwarded to `consentStore.recordOtpChannelConsent` at `verify/:channel`
+   * AFTER the channel is confirmed as an MFA method, so the persisted record
+   * pins the literal copy the user actually saw. The disclosure text itself
+   * is GENERIC per-channel (no target templated in) — the verified target
+   * is captured as a separate audit-record field.
+   */
+  otpDisclosure?: string;
   mfaEnrolledMethods?: MfaSummary[];
   mfaMethod?: "sms" | "email" | "totp";
   mfaSaveAsDefault?: boolean;
   ignoreMfaDefault?: boolean;
   mfaChecked?: boolean;
+  /**
+   * Set true the first time the user picks `useBackupCode` on the MFA step,
+   * so the workflow remembers to route the subsequent `BackupCodeForm`
+   * submission (which carries no `action`) through `handleBackupCode` instead
+   * of falling through to `verifyMfa` / pincode-verify.
+   */
+  usingBackupCode?: boolean;
   /** Counter incremented by the `risk-step-up` step so MFA reruns for the extra factor. */
   mfaRunsRemaining?: number;
+  /** Mirror of `mfaEnrolledMethods.length`. Passed to client forms via `@wf.context.pass` so action buttons (`useDifferentMethod`) can hide when only one method exists. */
+  mfaMethodCount?: number;
+  /** Mirror of `opts.mfa.backupCodes`. Passed to client forms so `useBackupCode` can hide when backup codes are disabled. */
+  mfaBackupCodes?: boolean;
+  altForgotPassword?: boolean;
+  altSignup?: boolean;
+  altMagicLink?: boolean;
+  enrollMethod?: MfaTransport;
+  enrollAddress?: string;
+  /** TOTP secret in flight (passed to UI via `@wf.context.pass` for QR rendering). */
+  enrollSecret?: string;
+  /** Provisioning URI for TOTP QR rendering. */
+  enrollUri?: string;
+  /** Mirror of `ctx.availableMfaTransports`, surfaced to `EnrollPickMethodForm` via `@wf.context.pass`. */
+  enrollAvailableTransports?: MfaTransport[];
+  /**
+   * Mirror of `ctx.mfaMode` (only set when not `'disabled'`). Surfaced to
+   * `EnrollPickMethodForm` via `@wf.context.pass` so the `skip` action can
+   * hide unless mode is `'optional'`.
+   */
+  enrollMode?: "required" | "optional";
+  /** Set true by `enrollConfirmPhase` (or `enrollPickPhase`/`enrollAddressPhase` on `skip` in `'optional'` mode); mirrored to `mfaChecked` via `buildLoginEnrollDeps` `onComplete`. */
+  enrollDone?: boolean;
+  /** Phase 3 confirm-pincode resend cooldown (sms/email). See `MfaEnrollCtx.enrollPincodeCooldown`. */
+  enrollPincodeCooldown?: number;
   pin?: string;
   pinExpire?: number;
   pinTimeout?: number;
   pinSentTo?: string;
+  /**
+   * Per-method "next-allowed-send-at" timestamp. Written by
+   * `pincode-send-login` after each send and consulted by `select2fa` to
+   * reject re-picking a method while it's still in cooldown. Closes the
+   * `useDifferentMethod → same method → fresh SMS` abuse loop: without this
+   * an attacker (or an impatient user) can spam SMS/email by alternating
+   * methods. Persists across `delete ctx.pin` (resend/useDifferentMethod)
+   * so the throttle survives a method switch.
+   */
+  pincodeCooldowns?: {
+    sms?: number;
+    email?: number;
+  };
   deviceTrustToken?: string;
   /** Set true at MFA gate when no trust cookie matched → trigger `notify-new-device`. */
   newDevice?: boolean;
   /** Captured from the OTP/pincode form when `opts.deviceTrust.optIn`. */
   rememberDevice?: boolean;
-  termsAcceptedVersion?: string;
+  /** Mirror of `opts.deviceTrust.optIn`. Passed to `PincodeForm` so the `rememberDevice` checkbox can hide when the consumer's device-trust is off-by-default (no user choice to make). */
+  deviceTrustOptIn?: boolean;
+  /**
+   * Descriptors for the customer-defined general consents (terms, marketing,
+   * jurisdiction, ...) the user still needs to accept. Populated once by
+   * `prepare-consents` after username-bind. Phase 5 will migrate carrier
+   * forms to consume this array; Phase 4 populates transport only.
+   */
+  pendingConsents?: ConsentDescriptor[];
+  /**
+   * Subset of `pendingConsents[].id` the user ticked on the carrier form —
+   * set by `processInlineConsent` after silent-dropping unknown ids.
+   * Consumed by `persist-consents` to compute `accepted: boolean` per
+   * pending descriptor.
+   */
+  acceptedConsentIds?: string[];
+  /**
+   * Wall-clock ms at the moment `processInlineConsent` resolved the
+   * `consents` carrier-form submission (NOT at write-time — captured BEFORE
+   * the batched `persist-consents` step so a paused-workflow resume gap
+   * doesn't drift the timestamp). Also the schema-gate for the
+   * `persist-consents` step — set ⇒ a carrier form has collected consents.
+   */
+  consentsDecidedAt?: number;
   profileMissingFields?: string[];
   availableTenants?: Array<{
     id: string;
@@ -530,9 +1024,15 @@ interface LoginWfCtx {
   riskStepUpReason?: string;
   activeSessions?: number;
   passwordChanged?: boolean;
-  termsAcceptedDone?: boolean;
   profileApplied?: boolean;
-  consentApplied?: boolean;
+  /**
+   * Set true by `persist-consents` after the batched `consentStore.save`
+   * call fires (or after the step short-circuits with no pending consents).
+   * Gates `processInlineConsent` from re-staging on subsequent carrier
+   * forms in the same workflow run, and the `persist-consents` schema
+   * condition from re-firing.
+   */
+  consentsPersisted?: boolean;
   tokensIssued?: boolean;
   redirectUrl?: string;
   /**
@@ -544,6 +1044,32 @@ interface LoginWfCtx {
   /** Tracks whether `risk-step-up` has already been evaluated this iteration. */
   riskStepUpEvaluated?: boolean;
 }
+/**
+ * Per-group policy override shape consumed by `resolveXxx(ctx)` subclass
+ * overrides. Mirrors the `ctx.<group>` fields that the `prepare-<group>`
+ * @Step methods populate — one entry per resolver. Library users typically
+ * accept a payload of this shape on their `LoginWorkflow` subclass ctor /
+ * test harness and have each `resolveXxx` return its matching key (falling
+ * back to `super.resolveXxx(ctx)` for unset groups).
+ */
+interface LoginPolicyOverrides {
+  /**
+   * Override the profile-completion policy (`{ required: boolean }`) — the
+   * boolean is mirrored onto `ctx.profileCompleteRequired` by `prepare-profile`
+   * and read by the `profile-complete` schema condition.
+   */
+  profile?: {
+    required: boolean;
+  };
+  alternateCredentials?: NonNullable<LoginWfCtx["alternateCredentials"]>;
+  deviceTrust?: NonNullable<LoginWfCtx["deviceTrust"]>;
+  enrollment?: NonNullable<LoginWfCtx["enrollment"]>;
+  finalize?: NonNullable<LoginWfCtx["finalize"]>;
+  guards?: NonNullable<LoginWfCtx["guards"]>;
+  mfaConfig?: NonNullable<LoginWfCtx["mfaConfig"]>;
+  multiContext?: NonNullable<LoginWfCtx["multiContext"]>;
+  sessionPolicy?: NonNullable<LoginWfCtx["sessionPolicy"]>;
+}
 interface MfaSummary {
   kind: "sms" | "email" | "totp";
   /** Underlying `MfaMethod.name` so the workflow can call into UserService. */
@@ -583,14 +1109,16 @@ interface DeliverSms {
   userId?: string;
 }
 type DeliverPayload = DeliverEmail | DeliverSms;
-declare class LoginWorkflow {
+declare class LoginWorkflow extends AuthWorkflowBase {
   protected readonly opts: ResolvedLoginWorkflowOpts;
   protected readonly users: UserService;
   protected readonly auth: AuthCredential;
-  constructor(opts: LoginWorkflowOpts, users: UserService, auth: AuthCredential);
+  protected readonly authOpts: AuthOpts;
+  protected readonly consentStore: ConsentStore;
+  constructor(opts: LoginWorkflowOpts, users: UserService, auth: AuthCredential, authOpts: AuthOpts, consentStore: ConsentStore);
   /**
    * Dispatch an email or SMS event. Default throws — consumers MUST override
-   * if any feature that emits is enabled (MFA pincode, ensureEmail/Phone OTP,
+   * if any feature that emits is enabled (MFA pincode, ask/verify channel OTP,
    * notifyNewDevice). The throw surfaces at the HTTP layer as 500 on the
    * first event that triggers a send, which is the fail-loud signal.
    */
@@ -630,62 +1158,197 @@ declare class LoginWorkflow {
    * `storeTrustedDevice` against Redis but keep this default.
    */
   protected issueTrustedDevice(userId: string, ip: string | undefined, ttlMs: number): Promise<TrustedDeviceRecord>;
+  /**
+   * Resolve the profile-completion policy. Returns `{ required: boolean }` —
+   * whether the user must complete profile fields (e.g. `firstName` /
+   * `lastName`) BEFORE token issuance. Override per-tenant or per-user to
+   * gate logins on missing profile fields; the boolean is mirrored onto
+   * `ctx.profileCompleteRequired` by `prepare-profile` and read by the
+   * `profile-complete` schema condition (which AND-s the gate with
+   * `ctx.profileMissingFields.length > 0` so the step only fires when the
+   * consumer has surfaced fields to collect — typically populated by a
+   * `credentials` override that hydrates `ctx.profileMissingFields` from
+   * the user row).
+   *
+   * Default-false matches the prior behavior — most consumers don't gate
+   * logins on profile completion. Async-friendly via the union return type —
+   * sync defaults stay sync (engine fast path).
+   */
+  protected resolveProfile(_ctx: LoginWfCtx): {
+    required: boolean;
+  } | Promise<{
+    required: boolean;
+  }>;
+  /**
+   * Resolve the alternate-credentials policy (forgot-password / signup /
+   * magic-link / SSO providers + their URLs). Override to enable/disable per
+   * tenant. Sync default; async overrides supported.
+   */
+  protected resolveAlternateCredentials(_ctx: LoginWfCtx): NonNullable<LoginWfCtx["alternateCredentials"]> | Promise<NonNullable<LoginWfCtx["alternateCredentials"]>>;
+  /**
+   * Resolve the device-trust policy (enabled / opt-in / skipsMfa). Infrastructure
+   * (cookieName / ttlMs / bindsTo) still lives on `this.opts.deviceTrust` since
+   * those are app-wide constants, not per-request policy. Sync/async friendly.
+   */
+  protected resolveDeviceTrust(_ctx: LoginWfCtx): NonNullable<LoginWfCtx["deviceTrust"]> | Promise<NonNullable<LoginWfCtx["deviceTrust"]>>;
+  /**
+   * Resolve the channel-enrollment policy (ensureEmail / ensurePhone gates).
+   * Override to force email/phone capture per user segment. Sync/async friendly.
+   */
+  protected resolveEnrollment(_ctx: LoginWfCtx): NonNullable<LoginWfCtx["enrollment"]> | Promise<NonNullable<LoginWfCtx["enrollment"]>>;
+  /**
+   * Resolve the finalize policy (audit emission / new-device notification /
+   * redirect target). Override to drive per-tenant audit-log routing or
+   * per-app redirect targets. Sync/async friendly.
+   */
+  protected resolveFinalize(_ctx: LoginWfCtx): NonNullable<LoginWfCtx["finalize"]> | Promise<NonNullable<LoginWfCtx["finalize"]>>;
+  /**
+   * Resolve the guards policy (passwordInitial / passwordExpiry /
+   * emailVerifiedRequired). Override per-tenant to tighten or loosen the
+   * post-credentials gates. Sync/async friendly.
+   */
+  protected resolveGuards(_ctx: LoginWfCtx): NonNullable<LoginWfCtx["guards"]> | Promise<NonNullable<LoginWfCtx["guards"]>>;
+  /**
+   * Resolve the MFA config (currently only backup-codes availability — pincode
+   * timings stay on `this.opts.mfa` as infrastructure). Override to enable or
+   * disable backup-code redemption per tenant. Sync/async friendly.
+   */
+  protected resolveMfaConfig(_ctx: LoginWfCtx): NonNullable<LoginWfCtx["mfaConfig"]> | Promise<NonNullable<LoginWfCtx["mfaConfig"]>>;
+  /**
+   * Resolve the multi-context policy (tenantSelect / personaSelect prompts).
+   * Override to require a tenant/persona pick when the user has more than one.
+   * Sync/async friendly.
+   */
+  protected resolveMultiContext(_ctx: LoginWfCtx): NonNullable<LoginWfCtx["multiContext"]> | Promise<NonNullable<LoginWfCtx["multiContext"]>>;
+  /**
+   * Resolve the disclosure text rendered beneath the channel input field on
+   * `AskEmailForm` / `AskPhoneForm` at ask-time — BEFORE the user submits
+   * their email/phone. Default returns a TCPA / PECR / CASL / GDPR-safe
+   * English paragraph that is GENERIC per channel (no target templated in,
+   * since the user hasn't submitted it yet). Override per-tenant or per-
+   * locale to swap copy (e.g. i18n catalog lookup). The resolved string is
+   * mirrored onto `ctx.otpDisclosure`, transported to the SPA via
+   * `@wf.context.pass`, and forwarded to
+   * `consentStore.recordOtpChannelConsent` at `verify/:channel` AFTER the
+   * pincode validates AND the channel is confirmed as an MFA method — the
+   * persisted audit record pins BOTH the literal disclosure copy the user
+   * saw AND the verified target as a separate field.
+   *
+   * Disclosure-only is sufficient for transactional security codes by default;
+   * customers wanting affirmative consent capture override
+   * `ConsentStore.recordOtpChannelConsent` instead. Sync/async friendly.
+   */
+  protected resolveOtpDisclosure(_ctx: LoginWfCtx, channel: "email" | "phone"): string | Promise<string>;
+  /**
+   * Resolve the session policy (concurrency limit). Override to enforce a
+   * per-tenant or per-user max-concurrent-sessions cap with reject / kickPrompt
+   * behaviour. Sync/async friendly.
+   */
+  protected resolveSessionPolicy(_ctx: LoginWfCtx): NonNullable<LoginWfCtx["sessionPolicy"]> | Promise<NonNullable<LoginWfCtx["sessionPolicy"]>>;
+  /**
+   * Call `resolveProfile(ctx)` and mirror `result.required` onto
+   * `ctx.profileCompleteRequired`. Promise-branched body preserves the engine's
+   * sync fast path: a sync `resolveProfile` override skips the microtask
+   * allocation, while an `async` override is awaited via `.then` before the
+   * `profile-complete` schema condition reads the boolean. The resolved POJO
+   * is intentionally NOT stashed on ctx as a group — `profileCompleteRequired`
+   * is the only field, so a top-level boolean keeps the ctx shape flat.
+   */
+  prepareProfile(ctx: LoginWfCtx): undefined | Promise<undefined>;
+  prepareAlternateCredentials(ctx: LoginWfCtx): undefined | Promise<undefined>;
+  prepareDeviceTrust(ctx: LoginWfCtx): undefined | Promise<undefined>;
+  prepareEnrollment(ctx: LoginWfCtx): undefined | Promise<undefined>;
+  prepareFinalize(ctx: LoginWfCtx): undefined | Promise<undefined>;
+  prepareGuards(ctx: LoginWfCtx): undefined | Promise<undefined>;
+  prepareMfaConfig(ctx: LoginWfCtx): undefined | Promise<undefined>;
+  prepareMultiContext(ctx: LoginWfCtx): undefined | Promise<undefined>;
+  prepareSessionPolicy(ctx: LoginWfCtx): undefined | Promise<undefined>;
+  /**
+   * Populate `ctx.pendingConsents` with the customer-defined general-consent
+   * descriptors (terms, marketing, jurisdiction, ...) the user still needs to
+   * accept. Phase 4 transport only — nothing reads `ctx.pendingConsents` yet;
+   * Phase 5 will migrate carrier forms (`SetPasswordForm`, `ProfileCompleteForm`,
+   * ...) from the `WithInlineConsentForm` static-checkbox mixin onto this
+   * dynamic array.
+   *
+   * Username MUST be bound before we fetch consents — customer impls key
+   * history by user, and pre-bind there's no identity to dedup against. The
+   * schema places this step AFTER the `!ctx.username` break gate, so the
+   * `if (!ctx.username)` guard is belt-and-brace for future refactors that
+   * might re-order the schema.
+   */
+  prepareConsents(ctx: LoginWfCtx): undefined | Promise<undefined>;
   flow(): void;
-  init(ctx: LoginWfCtx): undefined;
   /**
-   * Returns the JSON-safe projection of `opts` stashed onto `ctx` for schema
-   * conditions to read. Default: drop the `forms` group (atscript form classes
-   * are not plain JSON) so `AsWfStore`'s plain-JSON persistence doesn't choke.
-   * Step bodies still consult the form classes via `this.opts.forms.*`.
+   * First step of the workflow; remains as a no-op override hook for
+   * consumers (e.g. seeding pre-flight ctx fields, capturing request metadata).
+   * The pre-PR policy-pojo-on-ctx stash was dropped — policy now lives on
+   * `ctx.<group>` populated by the dedicated `prepare-<group>` steps.
    *
-   * Consumers who put non-JSON values on `opts` (e.g. by extending the type)
-   * can override this to strip them.
+   * Return type is `undefined | Promise<undefined>` so consumers can override
+   * with `async init(...)` without the default fast-path paying a Promise
+   * allocation (the wf engine awaits only when the return value is a Promise).
    */
-  protected snapshotOpts(opts: ResolvedLoginWorkflowOpts): ResolvedLoginWorkflowOpts;
-  credentials(input: {
-    username?: string;
-    password?: string;
-    action?: string;
-  } | undefined, ctx: LoginWfCtx): Promise<unknown>;
+  init(_ctx: LoginWfCtx): undefined | Promise<undefined>;
+  /**
+   * Prepare MFA setup: writes `ctx.mfaMode`, `ctx.availableMfaTransports`, and
+   * (when the user is resolvable) pre-selects `ctx.currentMfa` from the
+   * existing-user `defaultMethod` or the single-available-transport auto-pick.
+   * Override to compute any of the three from tenant policy / user attrs /
+   * request context. Return type allows a sync override (skip the promise
+   * round-trip) when no async work is needed — the default body is async only
+   * because of the `users.getUser` lookup for `currentMfa`.
+   */
+  prepareMfaSetup(ctx: LoginWfCtx): undefined | Promise<undefined>;
+  credentials(ctx: LoginWfCtx): Promise<unknown>;
   private handleCredentialsAlt;
   /**
-   * Builds the redirect URL the `forgotPassword` alt-action navigates to.
+   * Resolves the redirect URL the `forgotPassword` alt-action navigates to.
    * Receives whatever the user typed into the username field so the recovery
    * page can pre-fill it. Default:
    * `${alternateCredentials.recoveryUrl}?username=${encodeURIComponent(username ?? '')}`.
+   * Sync return type only — the caller (`credentials` step's alt-action
+   * handler) uses the URL inline; consumers needing async URL construction
+   * should override the `credentials` @Step instead. The resolved
+   * `alternateCredentials` policy is supplied by the caller so the base impl
+   * doesn't have to re-call `resolveAlternateCredentials`.
    */
-  protected buildRecoveryUrl(username?: string): string;
-  magicLinkRequest(): never;
-  magicLinkSend(): never;
-  magicLinkVerified(): never;
-  passkey(): never;
-  ssoCallback(): never;
-  ensureEmail(input: {
-    email?: string;
-    code?: string;
-  } | undefined, ctx: LoginWfCtx): Promise<unknown>;
-  ensurePhone(input: {
-    phone?: string;
-    code?: string;
-  } | undefined, ctx: LoginWfCtx): Promise<unknown>;
+  protected resolveRecoveryUrl(username: string | undefined, alt: NonNullable<LoginWfCtx["alternateCredentials"]>): string;
+  magicLinkRequest(): void | Promise<void>;
+  magicLinkSend(): void | Promise<void>;
+  magicLinkVerified(): void | Promise<void>;
+  passkey(): void | Promise<void>;
+  ssoCallback(): void | Promise<void>;
+  ask(ctx: LoginWfCtx, channel: "email" | "phone"): Promise<unknown>;
+  verify(ctx: LoginWfCtx, channel: "email" | "phone"): Promise<unknown>;
   checkTrustedDevice(ctx: LoginWfCtx): Promise<undefined>;
-  prepareMfaOptions(ctx: LoginWfCtx): Promise<undefined>;
-  select2fa(input: {
-    methodName?: string;
-    saveAsDefault?: boolean;
-    action?: string;
-  } | undefined, ctx: LoginWfCtx): Promise<unknown>;
+  /**
+   * Load + summarise the user's enrolled MFA methods (filtered against
+   * `ctx.availableMfaTransports`) and mirror the form-gating flags
+   * (`mfaMethodCount`, `mfaBackupCodes`, `deviceTrustOptIn`) onto ctx. Pure
+   * data-load — no selection decision. Split out of the old
+   * `prepare-mfa-options` step so consumers can override the load/summary
+   * shape (custom MFA inventory source) without copying the selection
+   * heuristics in `selectMfaMethod`.
+   */
+  loadEnrolledMfaMethods(ctx: LoginWfCtx): Promise<undefined>;
+  /**
+   * Pick which MFA method to use from the already-loaded
+   * `ctx.mfaEnrolledMethods` summary. Decision-only — no IO. Honors
+   * `ctx.currentMfa` (pre-selected by `prepareMfaSetup` from the user's
+   * `defaultMethod` or single-transport auto-pick), auto-picks when only one
+   * method is enrolled, falls back to the `isDefault` method. All paths are
+   * gated on `!ctx.ignoreMfaDefault` so the `useDifferentMethod` re-pick flow
+   * (which sets the flag) skips straight to the `select2fa` picker. Split out
+   * of the old `prepare-mfa-options` step so consumers can override selection
+   * heuristics (e.g. risk-based per-tenant defaults) without re-implementing
+   * the load/summary.
+   */
+  selectMfaMethod(ctx: LoginWfCtx): undefined | Promise<undefined>;
+  select2fa(ctx: LoginWfCtx): Promise<unknown>;
   pincodeSendLogin(ctx: LoginWfCtx): Promise<undefined>;
-  pincodeCheckLogin(input: {
-    code?: string;
-    action?: string;
-    rememberDevice?: boolean;
-  } | undefined, ctx: LoginWfCtx): Promise<unknown>;
-  mfaTotp(input: {
-    code?: string;
-    action?: string;
-    rememberDevice?: boolean;
-  } | undefined, ctx: LoginWfCtx): Promise<unknown>;
+  pincodeCheckLogin(ctx: LoginWfCtx): Promise<unknown>;
+  mfaTotp(ctx: LoginWfCtx): Promise<unknown>;
   /**
    * Backup-code alt-action handler shared by `select2fa`, `pincode-check-login`,
    * and `mfa-totp`. Validates against `BackupCodeForm` (alphanumeric +
@@ -693,37 +1356,60 @@ declare class LoginWorkflow {
    * produced by `UserService.generateBackupCodes`).
    */
   private handleBackupCode;
-  mfaEnrollRequired(): never;
+  /**
+   * Forced MFA enrollment — Phase 1 (pick method). Auto-picks a single
+   * transport, otherwise pauses for the picker form. When TOTP is picked, the
+   * secret is provisioned in the same step body (see `enrollPickPhase`).
+   * Sync-friendly return: the auto-pick branch and the picker-form branch are
+   * both synchronous; only the TOTP-provisioning tail is async.
+   */
+  loginEnrollPickMethod(ctx: LoginWfCtx): undefined | Promise<undefined>;
+  /**
+   * Forced MFA enrollment — Phase 2 (collect sms/email address + send
+   * pincode). Gated out for totp by the schema condition.
+   */
+  loginEnrollAddress(ctx: LoginWfCtx): undefined | Promise<undefined>;
+  /**
+   * Forced MFA enrollment — Phase 3 (verify code + activate method). Fires
+   * `onComplete` to bridge `enrollDone` → `mfaChecked` so login's outer MFA
+   * while-loop (gated on `!mfaChecked`) exits.
+   */
+  loginEnrollConfirm(ctx: LoginWfCtx): undefined | Promise<undefined>;
+  /**
+   * Build the `MfaEnrollDeps` payload shared by all three login enrollment
+   * step bodies. Sets `ctx.enrollMode` (mirrored onto ctx so
+   * `EnrollPickMethodForm` can hide the `skip` action unless mode is
+   * `'optional'`) and supplies `onComplete` to mirror `enrollDone` →
+   * `mfaChecked` for login's loop-exit signal.
+   */
+  private buildLoginEnrollDeps;
   deviceTrust(ctx: LoginWfCtx): Promise<undefined>;
-  preparePasswordRules(ctx: LoginWfCtx): undefined;
-  createPasswordForm(input: {
-    newPassword?: string;
-    confirmPassword?: string;
-    action?: string;
-  } | undefined, ctx: LoginWfCtx): Promise<unknown>;
-  termsAccept(input: {
-    acceptedVersion?: string;
-    accepted?: boolean;
-    action?: string;
-  } | undefined, ctx: LoginWfCtx): Promise<unknown>;
-  profileComplete(input: Record<string, unknown> | undefined, ctx: LoginWfCtx): Promise<unknown>;
+  preparePasswordRules(ctx: LoginWfCtx): undefined | Promise<undefined>;
+  createPasswordForm(ctx: LoginWfCtx): Promise<unknown>;
+  profileComplete(ctx: LoginWfCtx): Promise<unknown>;
   /**
    * Persists the profile-complete payload onto the user record. Default:
    * no-op (the workflow records the form was submitted but writes nothing).
    * Consumers override to write into their user store.
    */
   protected applyProfile(_username: string, _payload: Record<string, unknown>): Promise<void>;
-  consentMarketing(input: {
-    optIn?: boolean;
-    action?: string;
-  } | undefined, ctx: LoginWfCtx): Promise<unknown>;
   /**
-   * Persists the marketing consent decision. Default: no-op.
+   * Standalone terms re-acceptance prompt for returning users whose accepted
+   * terms version is stale — the consumer's `ConsentStore.getPendingConsents`
+   * returned a non-empty descriptor list (typically a bumped terms version)
+   * and no onboarding carrier form (ask-email/ask-phone/set-password/
+   * profile-complete) ran to capture them via the dynamic `consents: string[]`
+   * carrier field. The body delegates to `processInlineConsent`, which
+   * handles validation + ctx writes identically to the inline path.
    */
-  protected applyConsentMarketing(_username: string, _optIn: boolean): Promise<void>;
-  tenantSelect(input: {
-    tenantId?: string;
-  } | undefined, ctx: LoginWfCtx): Promise<unknown>;
+  termsBumpPrompt(ctx: LoginWfCtx): undefined;
+  /**
+   * Batched consent persistence — delegates to
+   * `AuthWorkflowBase.runPersistConsents`. See that helper for the full
+   * audit-friendly-default / idempotency / silent-drop contract.
+   */
+  persistConsentsStep(ctx: LoginWfCtx): Promise<undefined>;
+  tenantSelect(ctx: LoginWfCtx): Promise<unknown>;
   /**
    * Resolves the user's available tenants. Default: empty array. Consumers
    * who enable `multiContext.tenantSelect` must override this to return the
@@ -733,9 +1419,7 @@ declare class LoginWorkflow {
     id: string;
     name: string;
   }>>;
-  personaSelect(input: {
-    personaId?: string;
-  } | undefined, ctx: LoginWfCtx): Promise<unknown>;
+  personaSelect(ctx: LoginWfCtx): Promise<unknown>;
   /**
    * Resolves the user's available personas. Default: empty array. Consumers
    * who enable `multiContext.personaSelect` must override this.
@@ -744,9 +1428,15 @@ declare class LoginWorkflow {
     id: string;
     label: string;
   }>>;
-  concurrencyLimit(input: {
-    action?: string;
-  } | undefined, ctx: LoginWfCtx): Promise<unknown>;
+  loadActiveSessionsStep(ctx: LoginWfCtx): Promise<undefined>;
+  /**
+   * Return the number of active (non-revoked, non-expired) sessions for the
+   * user — consulted by `concurrency-limit` to decide whether the kickPrompt
+   * branch fires. Default returns `0` (no enforcement). Override with a real
+   * count from your credential store or session table.
+   */
+  protected loadActiveSessions(_username: string): Promise<number>;
+  concurrencyLimit(ctx: LoginWfCtx): Promise<unknown>;
   /**
    * Implements the "log out other sessions" branch of `sessionPolicy.concurrencyLimit`.
    * Default: no-op. Consumers override to revoke sessions in their auth store.
@@ -754,18 +1444,19 @@ declare class LoginWorkflow {
   protected logoutOtherSessions(_username: string): Promise<void>;
   riskStepUp(ctx: LoginWfCtx): Promise<undefined>;
   /**
-   * Risk-step-up assessor. Default: never requires an extra factor. Consumers
-   * override to inspect ctx (IP, geo, time since last login, etc.) and return
-   * `{require: true, reason: '…'}` to force an additional MFA round.
+   * Resolves whether to require an additional MFA round (risk step-up).
+   * Default: never requires an extra factor. Consumers override to inspect ctx
+   * (IP, geo, time since last login, etc.) and return `{require: true, reason: '…'}`
+   * to force an additional MFA round.
    */
-  protected assessRiskStepUp(_ctx: LoginWfCtx): Promise<{
+  protected resolveRiskStepUp(_ctx: LoginWfCtx): Promise<{
     require: boolean;
     reason?: string;
   }>;
   issue(ctx: LoginWfCtx): Promise<void>;
   auditLogin(ctx: LoginWfCtx): Promise<undefined>;
   notifyNewDevice(ctx: LoginWfCtx): Promise<undefined>;
-  redirect(ctx: LoginWfCtx): undefined;
+  redirect(ctx: LoginWfCtx): undefined | Promise<undefined>;
   /**
    * Resolves the post-login redirect URL. Default reads
    * `finalize.redirect`: `false` / `null` (the default) → no redirect, the
@@ -773,40 +1464,17 @@ declare class LoginWorkflow {
    * `'home'` → `/`; `'referer'` → request `Referer` header (undefined when
    * absent, falling back to the data response).
    *
-   * Consumers who want a computed redirect override this method.
+   * Sync return type only — the caller (`redirect` @Step's default body)
+   * uses the URL inline; consumers needing async redirect resolution should
+   * override the `redirect` @Step instead.
    */
-  protected resolveRedirect(_ctx: LoginWfCtx): string | undefined;
-  private resolveClientIp;
+  protected resolveRedirect(ctx: LoginWfCtx): string | undefined;
 }
 //#endregion
 //#region src/workflows/recovery.workflow.options.d.ts
 type RecoveryDeliveryMode = "magicLink" | "otp" | "choice";
 type RecoveryOtpTransport = "sms" | "email";
 interface RecoveryWorkflowOpts {
-  delivery?: {
-    mode?: RecoveryDeliveryMode;
-    magicLinkTtlMs?: number;
-    otp?: {
-      transports?: RecoveryOtpTransport[];
-      codeLength?: number;
-      ttlMs?: number;
-      resendCooldownMs?: number;
-    };
-  };
-  preReset?: {
-    requireKnownFactor?: boolean;
-  };
-  postReset?: {
-    revokeAllSessions?: boolean;
-    freshLoginRequired?: boolean;
-    loginUrl?: string;
-  };
-  altActions?: {
-    backToLogin?: boolean;
-  };
-  audit?: {
-    enabled?: boolean;
-  };
   /**
    * Replaceable form schemas. Each field defaults to the corresponding
    * `.as` form shipped under `@aooth/auth-moost/atscript/models`.
@@ -821,34 +1489,10 @@ interface RecoveryWorkflowOpts {
 }
 /**
  * Fully-resolved view used by the workflow at runtime — every nested group is
- * always populated by `mergeRecoveryOpts`, so schema conditions can read
- * `ctx.opts.<group>.<flag>` directly without optional chaining.
+ * always populated by `mergeRecoveryOpts`, so step bodies can read
+ * `this.opts.<group>.<flag>` directly without optional chaining.
  */
 interface ResolvedRecoveryWorkflowOpts {
-  delivery: {
-    mode: RecoveryDeliveryMode;
-    magicLinkTtlMs: number;
-    otp: {
-      transports: RecoveryOtpTransport[];
-      codeLength: number;
-      ttlMs: number;
-      resendCooldownMs: number;
-    };
-  };
-  preReset: {
-    requireKnownFactor: boolean;
-  };
-  postReset: {
-    revokeAllSessions: boolean;
-    freshLoginRequired: boolean;
-    loginUrl: string;
-  };
-  altActions: {
-    backToLogin: boolean;
-  };
-  audit: {
-    enabled: boolean;
-  };
   forms: {
     emailIdentifier: TAtscriptAnnotatedType;
     pincode: TAtscriptAnnotatedType;
@@ -866,11 +1510,29 @@ declare function mergeRecoveryOpts(opts?: RecoveryWorkflowOpts): ResolvedRecover
 //#endregion
 //#region src/workflows/recovery.workflow.d.ts
 interface RecoveryWfCtx {
-  opts?: ResolvedRecoveryWorkflowOpts;
+  delivery?: {
+    mode: RecoveryDeliveryMode;
+    otpTransports: RecoveryOtpTransport[];
+  };
+  preReset?: {
+    requireKnownFactor: boolean;
+    allowedFactors?: Array<"phone" | "totp">;
+  };
+  postReset?: {
+    revokeAllSessions: boolean;
+    freshLoginRequired: boolean;
+    loginUrl: string;
+  };
+  altActions?: {
+    backToLogin: boolean;
+  };
+  audit?: {
+    enabled: boolean;
+  };
   email?: string;
   username?: string;
   selectedMode?: "magicLink" | "otp";
-  /** Resolved delivery mode the workflow committed to (populated by `selectMode` or `init`). */
+  /** Resolved delivery mode the workflow committed to (set by `prepare-delivery` for fixed modes, by `select-mode` for `'choice'`). */
   resolvedMode?: "magicLink" | "otp";
   otpTransport?: "sms" | "email";
   otpCodeLength?: number;
@@ -878,19 +1540,69 @@ interface RecoveryWfCtx {
   pinExpire?: number;
   pinResendAllowedAt?: number;
   pinVerified?: boolean;
+  /** Mirror of `delivery.otpTransports.length`. Passed to `PincodeForm` so the `useDifferentTransport` action hides when only one transport is configured. */
+  recoveryTransportCount?: number;
   linkSent?: boolean;
   factorVerified?: boolean;
+  /**
+   * Recovery factors the user is actually able to verify on this attempt —
+   * intersection of `preReset.allowedFactors` (workflow whitelist) and
+   * what the user has enrolled (e.g. phone only if a confirmed SMS method
+   * exists). Populated by `verify-factor` before its form pauses and
+   * consumed by `RecoveryFactorForm` via `@wf.context.pass` to render only
+   * the available radio options.
+   */
+  availableRecoveryFactors?: Array<{
+    key: string;
+    label: string;
+  }>;
   passwordChanged?: boolean;
   sessionsRevoked?: boolean;
   tokensIssued?: boolean;
+  /**
+   * Subset of `pendingConsents[].id` the user ticked — set by
+   * `processInlineConsent` after silent-dropping unknown ids.
+   */
+  acceptedConsentIds?: string[];
+  /**
+   * Wall-clock ms when `processInlineConsent` resolved the carrier-form
+   * submission. Also the schema-gate for `persist-consents`.
+   */
+  consentsDecidedAt?: number;
+  /** Set true by `persist-consents` after the batched `consentStore.save` call fires. */
+  consentsPersisted?: boolean;
+  /**
+   * Descriptors for the customer-defined consents (terms, marketing,
+   * jurisdiction, ...) the user still needs to accept. Populated once by
+   * `prepare-consents` after username-bind; consumed by `WithInlineConsentForm`'s
+   * dynamic `AsConsentArray` field on the carrier form (Phase 5).
+   */
+  pendingConsents?: ConsentDescriptor[];
   /** Set by abort alt-actions (`backToLogin`). Gates all terminal steps. */
   aborted?: boolean;
 }
-declare class RecoveryWorkflow {
+/**
+ * Per-group policy override shape consumed by `resolveXxx(ctx)` subclass
+ * overrides. Mirrors the `ctx.<group>` fields that the `prepare-<group>`
+ * @Step methods populate — one entry per resolver. Library users typically
+ * accept a payload of this shape on their `RecoveryWorkflow` subclass ctor /
+ * test harness and have each `resolveXxx` return its matching key (falling
+ * back to `super.resolveXxx(ctx)` for unset groups).
+ */
+interface RecoveryPolicyOverrides {
+  delivery?: NonNullable<RecoveryWfCtx["delivery"]>;
+  preReset?: NonNullable<RecoveryWfCtx["preReset"]>;
+  postReset?: NonNullable<RecoveryWfCtx["postReset"]>;
+  altActions?: NonNullable<RecoveryWfCtx["altActions"]>;
+  audit?: NonNullable<RecoveryWfCtx["audit"]>;
+}
+declare class RecoveryWorkflow extends AuthWorkflowBase {
   protected readonly opts: ResolvedRecoveryWorkflowOpts;
   protected readonly users: UserService;
   protected readonly auth: AuthCredential;
-  constructor(opts: RecoveryWorkflowOpts, users: UserService, auth: AuthCredential);
+  protected readonly authOpts: AuthOpts;
+  protected readonly consentStore: ConsentStore;
+  constructor(opts: RecoveryWorkflowOpts, users: UserService, auth: AuthCredential, authOpts: AuthOpts, consentStore: ConsentStore);
   /**
    * Dispatch an email or SMS event. Default throws — consumers MUST override
    * if `delivery.mode` ever drives email/SMS (i.e. for any non-`magicLink`
@@ -904,22 +1616,76 @@ declare class RecoveryWorkflow {
    * their audit sink.
    */
   protected audit(_event: AuditEvent): Promise<void>;
+  /**
+   * Resolve the delivery policy (mode + OTP transports). Override per-tenant
+   * to drive magic-link vs OTP delivery preferences. Sync/async friendly.
+   */
+  protected resolveDelivery(_ctx: RecoveryWfCtx): NonNullable<RecoveryWfCtx["delivery"]> | Promise<NonNullable<RecoveryWfCtx["delivery"]>>;
+  /**
+   * Resolve the pre-reset policy (requireKnownFactor + allowedFactors whitelist).
+   * Override to enforce a factor check between the magic-link / OTP step and
+   * the new-password form. `allowedFactors` omitted means both phone and TOTP
+   * are eligible. Sync/async friendly.
+   */
+  protected resolvePreReset(_ctx: RecoveryWfCtx): NonNullable<RecoveryWfCtx["preReset"]> | Promise<NonNullable<RecoveryWfCtx["preReset"]>>;
+  /**
+   * Resolve the post-reset policy (session revocation / fresh-login redirect /
+   * loginUrl). Override per-tenant. `loginUrl` defaults to
+   * `this.authOpts.loginUrl` (the cross-workflow shared login URL); customers
+   * can still override per-tenant by overriding this resolver — the field
+   * stays on the policy surface. Sync/async friendly.
+   */
+  protected resolvePostReset(_ctx: RecoveryWfCtx): NonNullable<RecoveryWfCtx["postReset"]> | Promise<NonNullable<RecoveryWfCtx["postReset"]>>;
+  /**
+   * Resolve the alt-actions policy (whether `backToLogin` is offered on the
+   * recovery forms). Override to hide the escape hatch per-tenant. Sync/async
+   * friendly.
+   */
+  protected resolveAltActions(_ctx: RecoveryWfCtx): NonNullable<RecoveryWfCtx["altActions"]> | Promise<NonNullable<RecoveryWfCtx["altActions"]>>;
+  /**
+   * Resolve the audit policy (whether recovery.* audit events fire). Override
+   * to route audit-log emission per-tenant. Sync/async friendly.
+   */
+  protected resolveAudit(_ctx: RecoveryWfCtx): NonNullable<RecoveryWfCtx["audit"]> | Promise<NonNullable<RecoveryWfCtx["audit"]>>;
+  prepareDelivery(ctx: RecoveryWfCtx): undefined | Promise<undefined>;
+  /**
+   * Apply resolved delivery to ctx — also auto-resolves derived ctx fields:
+   *   - `resolvedMode` (when mode !== 'choice' — `'choice'` defers to `select-mode`)
+   *   - `recoveryTransportCount` (mirrored to ctx for the `useDifferentTransport` form gate)
+   *
+   * Validates the otpTransports-not-empty invariant at step time (replacing
+   * the old construction-time `validateOpts` check; the value is now
+   * ctx-driven so the check has to fire at step time).
+   */
+  private applyResolvedDelivery;
+  preparePreReset(ctx: RecoveryWfCtx): undefined | Promise<undefined>;
+  preparePostReset(ctx: RecoveryWfCtx): undefined | Promise<undefined>;
+  prepareAltActions(ctx: RecoveryWfCtx): undefined | Promise<undefined>;
+  prepareAudit(ctx: RecoveryWfCtx): undefined | Promise<undefined>;
+  /**
+   * Populate `ctx.pendingConsents` with the customer-defined general-consent
+   * descriptors (terms, marketing, jurisdiction, ...) the user still needs to
+   * accept. Phase 4 transport only — nothing reads `ctx.pendingConsents` yet;
+   * Phase 5 will migrate the carrier `SetPasswordForm` from the
+   * `WithInlineConsentForm` static-checkbox mixin onto this dynamic array.
+   *
+   * Username MUST be bound before we fetch consents — the schema places this
+   * step AFTER the `!ctx.username` break gate, so the `if (!ctx.username)`
+   * guard is belt-and-brace for future refactors that might re-order the
+   * schema.
+   */
+  prepareConsents(ctx: RecoveryWfCtx): undefined | Promise<undefined>;
   flow(): void;
-  init(ctx: RecoveryWfCtx): undefined;
   /**
-   * Returns the JSON-safe projection of `opts` stashed onto `ctx` for schema
-   * conditions to read. Default: drop the `forms` group (atscript form classes
-   * are not plain JSON) so `AsWfStore`'s plain-JSON persistence doesn't choke.
-   * Step bodies still consult the form classes via `this.opts.forms.*`.
+   * First step of the workflow; remains as a no-op override hook for
+   * consumers. Policy populated by the dedicated `prepare-<group>` steps.
    *
-   * Consumers who extend the opts type with non-JSON values can override this
-   * to strip them so `AsWfStore`'s plain-JSON persistence doesn't choke.
+   * Return type is `undefined | Promise<undefined>` so consumers can override
+   * with `async init(...)` without the default fast-path paying a Promise
+   * allocation (the wf engine awaits only when the return value is a Promise).
    */
-  protected snapshotOpts(opts: ResolvedRecoveryWorkflowOpts): ResolvedRecoveryWorkflowOpts;
-  request(input: {
-    email?: string;
-    action?: string;
-  } | undefined, ctx: RecoveryWfCtx): Promise<unknown>;
+  init(_ctx: RecoveryWfCtx): undefined | Promise<undefined>;
+  request(ctx: RecoveryWfCtx): Promise<unknown>;
   /**
    * Resolves the recovery-step `email` input to the `username` (user-id) that
    * `UserService.getUser` expects. Default: returns the email unchanged (treats
@@ -927,21 +1693,24 @@ declare class RecoveryWorkflow {
    * `email` MUST override this; return `null` when no user matches.
    */
   protected emailToUserId(email: string): Promise<string | null>;
-  selectMode(input: {
-    mode?: string;
-    action?: string;
-  } | undefined, ctx: RecoveryWfCtx): unknown;
+  selectMode(ctx: RecoveryWfCtx): unknown;
   sendMagicLink(ctx: RecoveryWfCtx): unknown;
   sendOtp(ctx: RecoveryWfCtx): Promise<undefined>;
-  checkOtp(input: {
-    code?: string;
-    action?: string;
-  } | undefined, ctx: RecoveryWfCtx): Promise<unknown>;
-  verifyFactor(input: {
-    factor?: string;
-    value?: string;
-    action?: string;
-  } | undefined, ctx: RecoveryWfCtx): Promise<unknown>;
+  checkOtp(ctx: RecoveryWfCtx): Promise<unknown>;
+  verifyFactor(ctx: RecoveryWfCtx): Promise<unknown>;
+  /**
+   * Returns the factor options to show on `RecoveryFactorForm`. Default:
+   * intersection of `preReset.allowedFactors` (workflow whitelist —
+   * `undefined` means both `phone` and `totp` are eligible) and the kinds
+   * the user has actually enrolled (`phone` if a confirmed SMS method
+   * exists, `totp` if a confirmed TOTP method exists). Override to add
+   * custom factors (e.g. security questions) — call `super` to keep the
+   * built-in pair.
+   */
+  protected loadAvailableRecoveryFactors(ctx: RecoveryWfCtx): Promise<Array<{
+    key: string;
+    label: string;
+  }>>;
   /**
    * Verifies a recovery factor against the user's enrolled MFA methods.
    * Default: supports `'phone'` (phone last-4 match) and `'totp'` (current
@@ -956,14 +1725,16 @@ declare class RecoveryWorkflow {
     value: string;
     ctx: RecoveryWfCtx;
   }): Promise<boolean>;
-  setPassword(input: {
-    newPassword?: string;
-    confirmPassword?: string;
-    action?: string;
-  } | undefined, ctx: RecoveryWfCtx): Promise<unknown>;
+  setPassword(ctx: RecoveryWfCtx): Promise<unknown>;
   revokeSessions(ctx: RecoveryWfCtx): Promise<undefined>;
   auditStep(ctx: RecoveryWfCtx): Promise<undefined>;
-  freshLoginFinish(_ctx: RecoveryWfCtx): undefined;
+  /**
+   * Batched consent persistence — delegates to
+   * `AuthWorkflowBase.runPersistConsents`. See that helper for the full
+   * audit-friendly-default / idempotency / silent-drop contract.
+   */
+  persistConsentsStep(ctx: RecoveryWfCtx): Promise<undefined>;
+  freshLoginFinish(ctx: RecoveryWfCtx): undefined | Promise<undefined>;
   autoLoginFinish(ctx: RecoveryWfCtx): Promise<undefined>;
   /**
    * Send the generic "if an account exists, you'll receive instructions"
@@ -994,31 +1765,14 @@ interface PreparedUserInput {
 type DuplicateAction = "allow" | "reject" | "reuseAsReInvite";
 type InviteSendMode = "email" | "shareableLink" | "choice";
 interface InviteWorkflowOpts {
-  adminForm?: {
-    collectRoles?: boolean;
-  };
-  send?: {
-    mode?: InviteSendMode;
-    tokenTtlMs?: number;
-  };
-  accept?: {
-    alreadyAcceptedRedirectUrl?: string;
-    freshLoginRequired?: boolean;
-    loginUrl?: string;
-    showConfirmation?: boolean;
-    confirmationMessage?: string;
-  };
-  cancellation?: {
-    allowed?: boolean;
-  };
-  audit?: {
-    enabled?: boolean;
-  };
   /**
    * Replaceable form schemas. Each field defaults to the corresponding
    * `.as` form shipped under `@aooth/auth-moost/atscript/models`.
    */
   forms?: {
+    enrollAddress?: TAtscriptAnnotatedType;
+    enrollConfirm?: TAtscriptAnnotatedType;
+    enrollPickMethod?: TAtscriptAnnotatedType;
     invite?: TAtscriptAnnotatedType;
     inviteEmail?: TAtscriptAnnotatedType;
     inviteSendMode?: TAtscriptAnnotatedType;
@@ -1027,31 +1781,14 @@ interface InviteWorkflowOpts {
 }
 /**
  * Fully-resolved view used by the workflow at runtime — every nested group is
- * always populated by `mergeInviteOpts`, so schema conditions can read
- * `ctx.opts.<group>.<flag>` directly without optional chaining.
+ * always populated by `mergeInviteOpts`, so step bodies can read
+ * `this.opts.<group>.<flag>` directly without optional chaining.
  */
 interface ResolvedInviteWorkflowOpts {
-  adminForm: {
-    collectRoles: boolean;
-  };
-  send: {
-    mode: InviteSendMode;
-    tokenTtlMs: number;
-  };
-  accept: {
-    alreadyAcceptedRedirectUrl: string;
-    freshLoginRequired: boolean;
-    loginUrl: string;
-    showConfirmation: boolean;
-    confirmationMessage: string;
-  };
-  cancellation: {
-    allowed: boolean;
-  };
-  audit: {
-    enabled: boolean;
-  };
   forms: {
+    enrollAddress: TAtscriptAnnotatedType;
+    enrollConfirm: TAtscriptAnnotatedType;
+    enrollPickMethod: TAtscriptAnnotatedType;
     invite: TAtscriptAnnotatedType;
     inviteEmail: TAtscriptAnnotatedType;
     inviteSendMode: TAtscriptAnnotatedType;
@@ -1072,14 +1809,35 @@ type InvitePrepareUserInput = PreparedUserInput;
 //#endregion
 //#region src/workflows/invite.workflow.d.ts
 interface InviteWfCtx {
-  opts?: ResolvedInviteWorkflowOpts;
+  adminForm?: {
+    collectRoles: boolean;
+  };
+  send?: {
+    mode: InviteSendMode;
+  };
+  accept?: {
+    alreadyAcceptedRedirectUrl: string;
+    freshLoginRequired: boolean;
+    loginUrl: string;
+    showConfirmation: boolean;
+    confirmationMessage: string;
+  };
+  cancellation?: {
+    allowed: boolean;
+  };
+  audit?: {
+    enabled: boolean;
+  };
+  mfa?: {
+    issuer: string;
+  };
   /** Boolean projection of `this.getProfileForm() !== undefined` — schema gates on it. */
   acceptProfileFormPresent?: boolean;
   /**
-   * Populated by `invitePrepareAvailableRoles` when the override returns a list.
+   * Populated by `prepare-available-roles` when the override returns a list.
    * Surfaced into the `InviteForm` via `@wf.context.pass 'availableRoles'` so
    * the role multi-select renders the whitelisted choices; also used by
-   * `inviteAdminInviteForm` to reject admin-submitted roles outside the list.
+   * `admin-form` to reject admin-submitted roles outside the list.
    */
   availableRoles?: string[];
   email?: string;
@@ -1088,27 +1846,97 @@ interface InviteWfCtx {
   firstName?: string;
   lastName?: string;
   roles?: string[];
-  /** Populated by `inviteSelectSendMode` (when `send.mode === 'choice'`). */
+  /**
+   * Extras dict prepared by `build-user-extras` (calls `prepareUser`) and
+   * consumed by `create-user` to populate the user-row fields beyond the
+   * base credential shape. Split apart so consumers can inject e.g. a
+   * tenant-validation step between extras-build and create-user without
+   * copying either body.
+   */
+  userExtras?: Record<string, unknown>;
+  /** Populated by `select-send-mode` (when `send.mode === 'choice'`). */
   selectedSendMode?: "email" | "shareableLink";
-  /** Resolved send mode the workflow committed to (set in `inviteInit` or `inviteSelectSendMode`). */
+  /** Resolved send mode the workflow committed to (set in `prepare-send` or `select-send-mode`). */
   resolvedSendMode?: "email" | "shareableLink";
-  /** Populated by `inviteReturnShareableLink` so the admin's UI can display it. */
+  /** Populated by `return-shareable-link` so the admin's UI can display it. */
   shareableLinkUrl?: string;
-  /** Marks that `inviteSendInviteEmail` already emitted the outlet — resume → advance. */
+  /** Marks that `send-email` already emitted the outlet — resume → advance. */
   linkSent?: boolean;
-  /** Detected at `inviteCheckPendingInvitation`; triggers `inviteIdempotentRedirect`. */
+  /** Detected at `check-pending-invitation`; triggers `idempotent-redirect`. */
   alreadyAccepted?: boolean;
   passwordSet?: boolean;
-  /** Raw input from `inviteCollectProfile`. */
+  enrollMethod?: "sms" | "email" | "totp";
+  enrollAddress?: string;
+  enrollSecret?: string;
+  enrollUri?: string;
+  enrollAvailableTransports?: Array<"sms" | "email" | "totp">;
+  /**
+   * MFA policy (set by `inviteSetupMfa` setter — overridable per consumer).
+   *   - `'required'` — invitee MUST enroll a second factor BEFORE activation.
+   *   - `'optional'` — invitee is prompted but may `skip` the enrollment form.
+   *   - `'disabled'` — enrollment loop is skipped entirely.
+   */
+  mfaMode?: "required" | "optional" | "disabled";
+  /** Available MFA transports (set by `inviteSetupMfa` setter — overridable per consumer). */
+  availableMfaTransports?: Array<"sms" | "email" | "totp">;
+  /**
+   * Mirror of `ctx.mfaMode` (only set when not `'disabled'`). Surfaced to
+   * `EnrollPickMethodForm` via `@wf.context.pass` so the `skip` action can
+   * hide unless mode is `'optional'`.
+   */
+  enrollMode?: "required" | "optional";
+  enrollDone?: boolean;
+  /** Phase 3 confirm-pincode resend cooldown (sms/email). See `MfaEnrollCtx.enrollPincodeCooldown`. */
+  enrollPincodeCooldown?: number;
+  /** Pincode scratch shared with the enrollment helper. */
+  pin?: string;
+  pinExpire?: number;
+  pinSentTo?: string;
+  /** Raw input from `collect-profile`. */
   profile?: Record<string, unknown>;
   profileApplied?: boolean;
   pendingInvitationCleared?: boolean;
   activated?: boolean;
   confirmationShown?: boolean;
   tokensIssued?: boolean;
+  /**
+   * Subset of `pendingConsents[].id` the user ticked — set by
+   * `processInlineConsent` after silent-dropping unknown ids.
+   */
+  acceptedConsentIds?: string[];
+  /**
+   * Wall-clock ms when `processInlineConsent` resolved the carrier-form
+   * submission. Also the schema-gate for `persist-consents`.
+   */
+  consentsDecidedAt?: number;
+  /** Set true by `persist-consents` after the batched `consentStore.save` call fires. */
+  consentsPersisted?: boolean;
+  /**
+   * Descriptors for the customer-defined consents (terms, marketing,
+   * jurisdiction, ...) the user still needs to accept. Populated once by
+   * `prepare-consents` after username-bind; consumed by `WithInlineConsentForm`'s
+   * dynamic `AsConsentArray` field on the carrier form (Phase 5).
+   */
+  pendingConsents?: ConsentDescriptor[];
   /** Set true by abort alt-actions (`cancel`). Gates all terminal steps. */
   aborted?: boolean;
 }
+/**
+ * Per-group policy override shape consumed by `resolveXxx(ctx)` subclass
+ * overrides. Mirrors the `ctx.<group>` fields that the `prepare-<group>`
+ * @Step methods populate — one entry per resolver. Library users typically
+ * accept a payload of this shape on their `InviteWorkflow` subclass ctor /
+ * test harness and have each `resolveXxx` return its matching key (falling
+ * back to `super.resolveXxx(ctx)` for unset groups).
+ */
+interface InvitePolicyOverrides {
+  adminForm?: NonNullable<InviteWfCtx["adminForm"]>;
+  send?: NonNullable<InviteWfCtx["send"]>;
+  accept?: NonNullable<InviteWfCtx["accept"]>;
+  cancellation?: NonNullable<InviteWfCtx["cancellation"]>;
+  audit?: NonNullable<InviteWfCtx["audit"]>;
+  mfa?: NonNullable<InviteWfCtx["mfa"]>;
+}
 /** Trim + de-duplicate role identifiers submitted via the admin invite form. */
 declare function parseInviteRoles(input?: string[]): string[];
 /**
@@ -1116,7 +1944,9 @@ declare function parseInviteRoles(input?: string[]): string[];
  * inherit the class-level `@ArbacResource('auth.invite') @ArbacAction('start')`
  * so every admin-side step event is gated. Apps that wire
  * `arbacAuthorizeInterceptor` globally grant admin a single rule:
- * `allow('auth.invite', 'start')`.
+ * `allow('auth.invite', 'start')`. The ARBAC resource name is intentionally
+ * distinct from the wfid path (`auth/invite/start`) — RBAC policy ids and
+ * wfid namespacing are separate naming schemes.
  *
  * The three `@Workflow` body methods (`inviteFlow` / `reInviteFlow` /
  * `cancelInviteFlow`) are `@Public()` because the wf adapter dispatches the
@@ -1127,20 +1957,22 @@ declare function parseInviteRoles(input?: string[]): string[];
  *
  * Phase-B steps (post `ctx.linkSent`, accept tail) are method-level
  * `@Public()` because they fire on the anonymous magic-link resume.
- * `inviteSendInviteEmail` / `inviteReturnShareableLink` are the boundary:
- * also `@Public()` because the @prostojs/wf runtime re-enters the saved step
- * on resume (the loop restarts at `indexes[level]`, not after it). Their
- * bodies are idempotent via `if (ctx.linkSent) return`.
+ * `send-email` / `return-shareable-link` are the boundary: also `@Public()`
+ * because the @prostojs/wf runtime re-enters the saved step on resume (the
+ * loop restarts at `indexes[level]`, not after it). Their bodies are
+ * idempotent via `if (ctx.linkSent) return`.
  *
- * `auth.reInvite` / `auth.cancelInvite` are admin-only end-to-end (admin
- * confirms in their own UI; no anonymous boundary), so their phase-A steps
- * stay class-gated under the same `auth.invite` / `start` grant.
+ * `auth/invite/resend` / `auth/invite/cancel` are admin-only end-to-end
+ * (admin confirms in their own UI; no anonymous boundary), so their phase-A
+ * steps stay class-gated under the same `auth.invite` / `start` grant.
  */
-declare class InviteWorkflow {
+declare class InviteWorkflow extends AuthWorkflowBase {
   protected readonly opts: ResolvedInviteWorkflowOpts;
   protected readonly users: UserService;
   protected readonly auth: AuthCredential;
-  constructor(opts: InviteWorkflowOpts, users: UserService, auth: AuthCredential);
+  protected readonly authOpts: AuthOpts;
+  protected readonly consentStore: ConsentStore;
+  constructor(opts: InviteWorkflowOpts, users: UserService, auth: AuthCredential, authOpts: AuthOpts, consentStore: ConsentStore);
   /**
    * Dispatch an email or SMS event. Default throws — the default invite send
    * uses `outletEmail` (handled by `createAuthEmailOutlet`) so this method is
@@ -1165,7 +1997,7 @@ declare class InviteWorkflow {
    * Return the list of selectable role identifiers for the admin invite form.
    * When defined AND `adminForm.collectRoles` is true → form ships
    * `ctx.availableRoles` so the UI renders a multi-select AND the
-   * `inviteAdminInviteForm` step rejects admin-submitted roles outside the
+   * `admin-form` step rejects admin-submitted roles outside the
    * list. When `undefined` (default) → no whitelist is enforced and any role
    * value the admin form supplies is accepted.
    */
@@ -1190,7 +2022,7 @@ declare class InviteWorkflow {
     profile: Record<string, unknown>;
   }): Promise<void>;
   /**
-   * Override the structural duplicate rule for `inviteAdminInviteForm`.
+   * Override the structural duplicate rule for `admin-form`.
    * Default: any existing row → `'reject'`; nothing → `'allow'`. Multi-tenant
    * apps that allow re-inviting the same email into a different tenant
    * override to return `'allow'` for those cases.
@@ -1201,62 +2033,157 @@ declare class InviteWorkflow {
   }): Promise<DuplicateAction>;
   /**
    * Return the consumer-supplied `.as` form schema rendered in the
-   * `inviteCollectProfile` step. `undefined` (default) skips the step
+   * `collect-profile` step. `undefined` (default) skips the step
    * entirely (just password collection).
    */
   protected getProfileForm(): TAtscriptAnnotatedType | undefined;
   /**
-   * Returns the JSON-safe projection of `opts` stashed onto `ctx` for schema
-   * conditions to read. Default: drop the `forms` group (atscript form classes
-   * are not plain JSON) so `AsWfStore`'s plain-JSON persistence doesn't choke.
-   * Step bodies still consult the form classes via `this.opts.forms.*`.
+   * Resolve the admin-form policy (whether to collect roles on the admin
+   * invite form). Override per-tenant. Sync/async friendly.
+   */
+  protected resolveAdminForm(_ctx: InviteWfCtx): NonNullable<InviteWfCtx["adminForm"]> | Promise<NonNullable<InviteWfCtx["adminForm"]>>;
+  /**
+   * Resolve the send-mode policy (`'email'` / `'shareableLink'` / `'choice'`).
+   * Override to drive per-tenant magic-link delivery preferences. Sync/async
+   * friendly.
+   */
+  protected resolveSend(_ctx: InviteWfCtx): NonNullable<InviteWfCtx["send"]> | Promise<NonNullable<InviteWfCtx["send"]>>;
+  /**
+   * Resolve the accept-tail policy (idempotent-redirect URL, fresh-login gate,
+   * loginUrl, confirmation message). Override per-tenant. Sync/async friendly.
+   * `loginUrl` defaults to `this.authOpts.loginUrl` (the cross-workflow shared
+   * login URL); customers can still override per-tenant by overriding this
+   * resolver — the field stays on the policy surface.
+   */
+  protected resolveAccept(_ctx: InviteWfCtx): NonNullable<InviteWfCtx["accept"]> | Promise<NonNullable<InviteWfCtx["accept"]>>;
+  /**
+   * Resolve the cancellation policy (whether `auth.cancelInvite` is allowed).
+   * Override to disable hard-delete per-tenant. Sync/async friendly.
+   */
+  protected resolveCancellation(_ctx: InviteWfCtx): NonNullable<InviteWfCtx["cancellation"]> | Promise<NonNullable<InviteWfCtx["cancellation"]>>;
+  /**
+   * Resolve the audit policy (whether invite.* audit events fire). Override
+   * to route audit-log emission per-tenant. Sync/async friendly.
+   */
+  protected resolveAudit(_ctx: InviteWfCtx): NonNullable<InviteWfCtx["audit"]> | Promise<NonNullable<InviteWfCtx["audit"]>>;
+  /**
+   * Resolve the MFA-issuer policy (TOTP provisioning issuer string rendered
+   * in the authenticator app). Default tracks `this.authOpts.totpIssuer` —
+   * customers override the resolver for per-tenant issuers. Pincode timers/
+   * length live on `AuthOpts.mfa`. Sync/async friendly.
+   */
+  protected resolveMfa(_ctx: InviteWfCtx): NonNullable<InviteWfCtx["mfa"]> | Promise<NonNullable<InviteWfCtx["mfa"]>>;
+  prepareAdminForm(ctx: InviteWfCtx): undefined | Promise<undefined>;
+  prepareSend(ctx: InviteWfCtx): undefined | Promise<undefined>;
+  prepareAccept(ctx: InviteWfCtx): undefined | Promise<undefined>;
+  prepareCancellation(ctx: InviteWfCtx): undefined | Promise<undefined>;
+  prepareAudit(ctx: InviteWfCtx): undefined | Promise<undefined>;
+  prepareMfa(ctx: InviteWfCtx): undefined | Promise<undefined>;
+  /**
+   * Populate `ctx.pendingConsents` with the customer-defined general-consent
+   * descriptors (terms, marketing, jurisdiction, ...) the invitee still needs
+   * to accept. Phase 4 transport only — nothing reads `ctx.pendingConsents`
+   * yet; Phase 5 will migrate the carrier `SetPasswordForm` from the
+   * `WithInlineConsentForm` static-checkbox mixin onto this dynamic array.
    *
-   * Consumers who extend the opts type with non-JSON values can override this
-   * to strip them so `AsWfStore`'s plain-JSON persistence doesn't choke.
+   * Username MUST be bound before we fetch consents — schema places this step
+   * AFTER `check-pending-invitation` (which sets `ctx.username` from the
+   * pending-invite row) inside the `linkSent` accept-tail subflow, so the
+   * `if (!ctx.username)` guard is belt-and-brace. `@Public()` is required
+   * because this step fires on the anonymous magic-link resume side of the
+   * workflow.
    */
-  protected snapshotOpts(opts: ResolvedInviteWorkflowOpts): ResolvedInviteWorkflowOpts;
+  prepareConsents(ctx: InviteWfCtx): undefined | Promise<undefined>;
   inviteFlow(): void;
   reInviteFlow(): void;
   cancelInviteFlow(): void;
-  init(ctx: InviteWfCtx): undefined;
+  init(ctx: InviteWfCtx): undefined | Promise<undefined>;
   prepareAvailableRoles(ctx: InviteWfCtx): Promise<undefined>;
-  selectSendMode(input: {
-    mode?: string;
-    action?: string;
-  } | undefined, ctx: InviteWfCtx): unknown;
-  adminInviteForm(input: {
-    email?: string;
-    firstName?: string;
-    lastName?: string;
-    roles?: string[];
-    action?: string;
-  } | undefined, ctx: InviteWfCtx): Promise<unknown>;
+  selectSendMode(ctx: InviteWfCtx): unknown;
+  adminInviteForm(ctx: InviteWfCtx): Promise<unknown>;
   inferRolesStep(ctx: InviteWfCtx): Promise<undefined>;
-  preCreateUser(ctx: InviteWfCtx): Promise<undefined>;
+  /**
+   * Build the extras dict that `create-user` merges into the new user
+   * row. Calls `prepareUser({email, firstName, lastName, roles, invitedBy})`
+   * and writes the result onto `ctx.userExtras`. Split out of the old
+   * `invitePreCreateUser` step so consumers can inject e.g. a
+   * tenant-validation step between extras-build and create-user without
+   * copying the createUser body.
+   */
+  buildUserExtras(ctx: InviteWfCtx): Promise<undefined>;
+  /**
+   * Create the user row from `ctx.userExtras` (plus the admin-supplied
+   * `ctx.roles`), translate store-level CONFLICT into HTTP 409, then stamp
+   * `pendingInvitation = true` via a deep-merge update so the
+   * `createUser`-applied account defaults (`active: false`, `locked: false`)
+   * survive. Split out of the old `invitePreCreateUser` step so consumers can
+   * override extras-build (`build-user-extras`) without touching the
+   * store-write transaction.
+   */
+  createUserStep(ctx: InviteWfCtx): Promise<undefined>;
   sendInviteEmail(ctx: InviteWfCtx): unknown;
   returnShareableLink(ctx: InviteWfCtx): unknown;
-  loadPendingUser(input: {
-    email?: string;
-    action?: string;
-  } | undefined, ctx: InviteWfCtx): Promise<unknown>;
+  loadPendingUser(ctx: InviteWfCtx): Promise<unknown>;
   checkPendingInvitation(ctx: InviteWfCtx): Promise<undefined>;
-  idempotentRedirect(ctx: InviteWfCtx): undefined;
-  preparePasswordRules(ctx: InviteWfCtx): undefined;
-  createPasswordForm(input: {
-    newPassword?: string;
-    confirmPassword?: string;
-    action?: string;
-  } | undefined, ctx: InviteWfCtx): Promise<unknown>;
-  collectProfile(input: Record<string, unknown> | undefined, ctx: InviteWfCtx): Promise<unknown>;
+  idempotentRedirect(ctx: InviteWfCtx): undefined | Promise<undefined>;
+  preparePasswordRules(ctx: InviteWfCtx): undefined | Promise<undefined>;
+  createPasswordForm(ctx: InviteWfCtx): Promise<unknown>;
+  /**
+   * Build the `MfaEnrollDeps` payload shared by all three invite enrollment
+   * step bodies. Sets `ctx.enrollMode` (mirrored onto ctx so
+   * `EnrollPickMethodForm` can hide the `skip` action unless mode is
+   * `'optional'`). Omits `onComplete` because invite's enrollment while-loop
+   * is gated on `!enrollDone` directly — no mirror needed.
+   */
+  private buildInviteEnrollDeps;
+  /**
+   * Prepare MFA enrolment setup: writes `ctx.mfaMode`,
+   * `ctx.availableMfaTransports`, and pre-picks `ctx.enrollMethod` when only
+   * one transport is available. Override to compute any of the three from
+   * tenant policy / invitee role / request context in a single hook. Return
+   * type allows a sync override (skip the promise round-trip) when no async
+   * work is needed.
+   */
+  inviteSetupMfa(ctx: InviteWfCtx): undefined | Promise<undefined>;
+  /**
+   * Forced MFA enrollment — Phase 1 (pick method). Auto-picks a single
+   * transport, otherwise pauses for the picker form. When TOTP is picked, the
+   * secret is provisioned in the same step body (see `enrollPickPhase`).
+   */
+  inviteEnrollPickMethod(ctx: InviteWfCtx): undefined | Promise<undefined>;
+  /**
+   * Forced MFA enrollment — Phase 2 (collect sms/email address + send
+   * pincode). Gated out for totp by the schema condition.
+   */
+  inviteEnrollAddress(ctx: InviteWfCtx): undefined | Promise<undefined>;
+  /**
+   * Forced MFA enrollment — Phase 3 (verify code + activate method). Sets
+   * `enrollDone` on success, which the schema's enrollment while-loop reads
+   * as the exit signal directly.
+   */
+  inviteEnrollConfirm(ctx: InviteWfCtx): undefined | Promise<undefined>;
+  collectProfile(ctx: InviteWfCtx): Promise<unknown>;
   applyProfileStep(ctx: InviteWfCtx): Promise<undefined>;
+  /**
+   * Consumer extension point — override in your subclass to inject extra
+   * accept-tail logic (input pauses, alt actions, persistence). Default:
+   * no-op. Runs AFTER profile collection, BEFORE activation. Signature is
+   * intentionally arg-less; read ctx + form input via composables
+   * (`useWfState`, `useAtscriptWf`) in the override body.
+   */
+  inviteExtraStep(): unknown;
+  /**
+   * Batched consent persistence — delegates to
+   * `AuthWorkflowBase.runPersistConsents`. See that helper for the full
+   * audit-friendly-default / idempotency / silent-drop contract.
+   */
+  persistConsentsStep(ctx: InviteWfCtx): Promise<undefined>;
   unsetPendingInvitation(ctx: InviteWfCtx): Promise<undefined>;
   activateUser(ctx: InviteWfCtx): Promise<undefined>;
-  confirmation(ctx: InviteWfCtx): undefined;
-  freshLoginFinish(_ctx: InviteWfCtx): undefined;
+  confirmation(ctx: InviteWfCtx): undefined | Promise<undefined>;
+  freshLoginFinish(ctx: InviteWfCtx): undefined | Promise<undefined>;
   autoLoginFinish(ctx: InviteWfCtx): Promise<undefined>;
-  cancelInvite(input: {
-    email?: string;
-  } | undefined, ctx: InviteWfCtx): Promise<unknown>;
+  cancelInvite(ctx: InviteWfCtx): Promise<unknown>;
   private abort;
   private loadUserOrNull;
   private emitAudit;
@@ -1264,13 +2191,13 @@ declare class InviteWorkflow {
 //#endregion
 //#region src/workflows/default-workflows.d.ts
 declare class DefaultLoginWorkflow extends LoginWorkflow {
-  constructor(users: UserService, auth: AuthCredential);
+  constructor(users: UserService, auth: AuthCredential, authOpts: AuthOpts, consentStore: ConsentStore);
 }
 declare class DefaultInviteWorkflow extends InviteWorkflow {
-  constructor(users: UserService, auth: AuthCredential);
+  constructor(users: UserService, auth: AuthCredential, authOpts: AuthOpts, consentStore: ConsentStore);
 }
 declare class DefaultRecoveryWorkflow extends RecoveryWorkflow {
-  constructor(users: UserService, auth: AuthCredential);
+  constructor(users: UserService, auth: AuthCredential, authOpts: AuthOpts, consentStore: ConsentStore);
 }
 //#endregion
 //#region src/workflows/auth-email-outlet.d.ts
@@ -1287,4 +2214,12 @@ interface AuthEmailOutletDeps {
  */
 declare function createAuthEmailOutlet(deps: AuthEmailOutletDeps): WfOutlet;
 //#endregion
-export { type AuditEmitter, type AuditEvent, type AuthBindings, type AuthContext, AuthController, type AuthEmailEvent, type AuthEmailKind, type AuthEmailOutletDeps, AuthGuarded, type AuthLoginResponse, type AuthLogoutBody, type AuthOkResponse, type AuthOptions, type AuthRefreshBody, type AuthSmsEvent, type AuthSmsKind, type BuildMagicLinkUrl, type ConcurrencyLimitOptions, DEFAULT_AUTH_WORKFLOWS, DefaultInviteWorkflow, DefaultLoginWorkflow, DefaultRecoveryWorkflow, type DeliverEmail, type DeliverPayload, type DeliverSms, type DuplicateAction, type EmailSender, type InvitePrepareUserInput, type InviteSendMode, type InviteWfCtx, InviteWorkflow, type InviteWorkflowOpts, type IssueResult, type LoginRedirect, type LoginWfCtx, LoginWorkflow, type LoginWorkflowOpts, type MfaSummary, type MfaTransport, type PreparedUserInput, Public, type RecoveryDeliveryMode, type RecoveryOtpTransport, type RecoveryWfCtx, RecoveryWorkflow, type RecoveryWorkflowOpts, type ResolvedAuthCookieConfig, type ResolvedAuthOptions, type ResolvedInviteWorkflowOpts, type ResolvedLoginWorkflowOpts, type ResolvedRecoveryWorkflowOpts, type SmsSender, type SsoProvider, type TAuthMeta, UserId, WfTrigger, type WfTriggerOpts, WfTriggerProvider, authGuardInterceptor, createAuthEmailOutlet, generateMagicLinkToken, getAuthMate, mergeInviteOpts, mergeLoginOpts, mergeRecoveryOpts, parseInviteRoles, useAuth };
+//#region src/workflows/auth-shareable-link-outlet.d.ts
+interface AuthShareableLinkOutletDeps {
+  buildMagicLinkUrl: BuildMagicLinkUrl$1;
+  /** Fallback TTL when the workflow context omits `expiresAtMs`. */
+  magicLinkTtlMs: (kind: AuthEmailKind$1) => number;
+}
+declare function createAuthShareableLinkOutlet(deps: AuthShareableLinkOutletDeps): WfOutlet;
+//#endregion
+export { type AuditEmitter, type AuditEvent, type AuthBindings, type AuthContext, AuthController, type AuthEmailEvent, type AuthEmailKind, type AuthEmailOutletDeps, AuthGuarded, type AuthLoginResponse, type AuthLogoutBody, type AuthOkResponse, type AuthOptions, AuthOpts, type AuthRefreshBody, type AuthShareableLinkOutletDeps, type AuthSmsEvent, type AuthSmsKind, type BuildMagicLinkUrl, type ConcurrencyLimitOptions, type ConsentDescriptor, type ConsentEvent, ConsentStore, DEFAULT_AUTH_WORKFLOWS, DefaultInviteWorkflow, DefaultLoginWorkflow, DefaultRecoveryWorkflow, type DeliverEmail, type DeliverPayload, type DeliverSms, type DuplicateAction, type EmailSender, type InvitePolicyOverrides, type InvitePrepareUserInput, type InviteSendMode, type InviteWfCtx, InviteWorkflow, type InviteWorkflowOpts, type IssueResult, type LoginPolicyOverrides, type LoginRedirect, type LoginWfCtx, LoginWorkflow, type LoginWorkflowOpts, type MfaSummary, type MfaTransport, type PreparedUserInput, Public, type RecoveryDeliveryMode, type RecoveryOtpTransport, type RecoveryPolicyOverrides, type RecoveryWfCtx, RecoveryWorkflow, type RecoveryWorkflowOpts, type ResolvedAuthCookieConfig, type ResolvedAuthOptions, type ResolvedInviteWorkflowOpts, type ResolvedLoginWorkflowOpts, type ResolvedRecoveryWorkflowOpts, type SmsSender, type SsoProvider, type TAuthMeta, UserId, WfTrigger, type WfTriggerOpts, WfTriggerProvider, authGuardInterceptor, createAuthEmailOutlet, createAuthShareableLinkOutlet, generateMagicLinkToken, getAuthMate, mergeInviteOpts, mergeLoginOpts, mergeRecoveryOpts, parseInviteRoles, useAuth };