@aooth/auth-moost 0.1.7 → 0.1.9

package/dist/index.d.mts

@@ -1,11 +1,12 @@
-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 { Mate, TConsoleBase, TInterceptorDef, TMateParamMeta, TMoostMetadata } from "moost";
+import { AuthContext, AuthContext as AuthContext$1, AuthCredential, AuthEmailEvent, AuthEmailKind, AuthEmailKind as AuthEmailKind$1, AuthSmsEvent, AuthSmsKind, BuildMagicLinkUrl, BuildMagicLinkUrl as BuildMagicLinkUrl$1, CredentialMetadata, EmailSender, EmailSender as EmailSender$1, EnrichedSession, EnrichedSession as EnrichedSession$1, IssueResult, IssueResult as IssueResult$1, SessionEnricher, SessionEnricher as SessionEnricher$1, SessionInfo, SessionInfo as SessionInfo$1, SmsSender, generateMagicLinkToken } from "@aooth/auth";
 import { TCookieAttributesInput } from "@wooksjs/event-http";
-import { TrustedDeviceRecord, UserCredentials, UserService } from "@aooth/user";
-import { WfFinished } from "@atscript/moost-wf";
+import { FederatedIdentityStore, FederatedProfileSnapshot, MfaMethod, TransferablePolicy, TrustedDeviceRecord, UserCredentials, UserService } from "@aooth/user";
+import { FinishWfOpts, WfFinished, useAtscriptWf } from "@atscript/moost-wf";
 import { MoostWf, WfOutlet, WfOutletTokenConfig, WfStateStrategy } from "@moostjs/event-wf";
+import { FederatedLoginService, NormalizedProfile, OAuthProviderRegistry } from "@aooth/idp";
 import { TAtscriptAnnotatedType } from "@atscript/typescript/utils";
+import { AuthCodeStore, ClientRedirectPolicy, IdTokenSigner, OidcClaimsResolver, PendingAuthorizationStore } from "@aooth/auth/authz";
 
 //#region src/auth.config.d.ts
 /** Resolved cookie attributes. Same shape is used for both access + refresh. */
@@ -47,170 +48,7 @@ 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[];
-}
+//#region src/consent.store.d.ts
 /**
  * Consent event emitted to the `ConsentStore.save(username, events)` DI
  * provider. Storage shape is intentionally the consumer's call — Mongo users
@@ -238,164 +76,6 @@ interface ConsentEvent {
    */
   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`
@@ -435,15 +115,14 @@ interface ConsentDescriptor {
  */
 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.
+   * Returns descriptors for general-purpose consents this user still needs to
+   * accept on the next prompt boundary — terms / privacy / marketing / age /
+   * jurisdiction-specific notices. Empty array → no consent step renders.
+   * Scope is the user; the returned descriptor set MUST NOT vary by workflow
+   * or transport channel. OTP channel-ownership disclosures are captured
+   * separately via `recordOtpChannelConsent`.
    */
-  getPendingConsents(_username: string | undefined, _ctx: {
-    workflow: string;
-    channel?: "email" | "sms";
-  }): Promise<ConsentDescriptor[]>;
+  getPendingConsents(_username: string | undefined): 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
@@ -502,7 +181,7 @@ declare function authGuardInterceptor(opts?: AuthOptions): TInterceptorDef;
  */
 declare function AuthGuarded(opts?: AuthOptions): ClassDecorator & MethodDecorator;
 //#endregion
-//#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
+//#region ../../node_modules/.pnpm/@wooksjs+event-wf@0.7.17_@prostojs+logger@0.4.3_@wooksjs+event-core@0.7.17_@wooksjs+eve_308375c6ad6313773ebd6e419ace01e4/node_modules/@wooksjs/event-wf/dist/index.d.ts
 interface WfFinishedResponse {
   type: 'redirect' | 'data';
   /** Redirect URL or response body */
@@ -544,7 +223,7 @@ interface AuthLogoutBody {
 }
 /**
  * POST /auth/refresh response body. Also returned by workflow finalize steps
- * (e.g. `LoginWorkflow`) when issuing tokens after a successful flow.
+ * (e.g. `AuthWorkflow`) when issuing tokens after a successful flow.
  *
  * Tokens are populated only when `enableBearer` is true. With `enableBearer=false`
  * the body still echoes `userId` + `accessExpiresAt` so the caller can schedule
@@ -564,10 +243,32 @@ interface AuthOkResponse {
 //#endregion
 //#region src/auth.composables.d.ts
 interface AuthBindings {
-  getAuthContext<TClaims extends object = Record<string, unknown>>(): AuthContext$1<TClaims> | null;
+  getAuthContext<TPayload extends object = Record<string, unknown>>(): AuthContext$1<TPayload> | null;
   /** @throws `HttpError(401)` if no `AuthContext` is present in the event. */
   getUserId(): string;
   isAuthenticated(): boolean;
+  /**
+   * `sessionId` of the token family that authenticated THIS request — for
+   * "this device" matching and as the `keepSessionId` for `revokeOtherSessions`.
+   * `undefined` when unauthenticated.
+   */
+  getSessionId(): string | undefined;
+  /**
+   * List the current user's active sessions (one row per device). Defaults to
+   * the browser-safe set (ordinary interactive sessions); pass `kind` to segment
+   * a non-browser bucket (`kind: "cli-session"`) or `kind: "*"` for every kind.
+   */
+  listSessions(opts?: {
+    enrich?: SessionEnricher$1;
+    kind?: string | string[];
+  }): Promise<SessionInfo$1[] | EnrichedSession$1[]>;
+  /** Revoke one of the current user's sessions by id (whole token family). */
+  revokeSession(sessionId: string): Promise<void>;
+  /**
+   * Log out the current user's OTHER sessions, keeping this one. Returns the
+   * count revoked. @throws `HttpError(401)` if the current session is unknown.
+   */
+  revokeOtherSessions(): Promise<number>;
   /** @throws `HttpError(500)` when no `authGuardInterceptor(opts)` is on the chain. */
   readonly options: ResolvedAuthOptions;
   /** Same precedence as `authGuardInterceptor`: Bearer wins when both enabled. */
@@ -590,7 +291,7 @@ interface AuthBindings {
  * `HttpError(500)` loudly — that's a configuration error, not a runtime
  * fallback case.
  */
-declare const useAuth: _$_wooksjs_event_core0.WookComposable<AuthBindings>;
+declare const useAuth: import("@wooksjs/event-core").WookComposable<AuthBindings>;
 //#endregion
 //#region src/auth.decorator.d.ts
 /**
@@ -636,19 +337,32 @@ 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/flow", "auth/recovery/flow", "auth/invite/start"];
+declare const DEFAULT_AUTH_WORKFLOWS: readonly ["auth/login/flow", "auth/invite/start", "auth/recovery/flow", "auth/signup/flow"];
+/**
+ * Workflow id allowed by the GUARDED `/auth/change-password` trigger.
+ * Deliberately NOT in `DEFAULT_AUTH_WORKFLOWS` — the authenticated
+ * change-password flow must never be reachable from the public `/auth/trigger`.
+ */
+declare const CHANGE_PASSWORD_WORKFLOW = "auth/change-password/flow";
+/**
+ * Workflow id allowed by the GUARDED `/auth/add-mfa` trigger — the authenticated
+ * "add a second factor" flow. Like {@link CHANGE_PASSWORD_WORKFLOW}, deliberately
+ * NOT in `DEFAULT_AUTH_WORKFLOWS`: it must never be reachable from the public
+ * `/auth/trigger`.
+ */
+declare const ADD_MFA_WORKFLOW = "auth/add-mfa/flow";
 /**
  * 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/flow`,
- *   `auth/recovery/flow`, and `auth/invite/start`.
+ * - `POST /auth/trigger` — single workflow trigger covering the unified
+ *   `AuthWorkflow`'s three `@Workflow` schemas (`/login`, `/invite`, `/recover`).
  *
  * The historical `/auth/login` and `/auth/password` endpoints were dropped —
  * both flows go through the workflow trigger now (full MFA / SSO / etc.
- * surface lives in `LoginWorkflow` and `RecoveryWorkflow`).
+ * surface lives in `AuthWorkflow`).
  *
  * Exported so consumers can subclass to add app-specific workflow ids to the
  * allow-list (override `triggerWf()` with a different `@WfTrigger({ allow })`)
@@ -658,10 +372,47 @@ declare class AuthController {
   protected readonly auth: AuthCredential;
   protected readonly users?: UserService | undefined;
   constructor(auth: AuthCredential, users?: UserService | undefined);
+  /**
+   * Scope the refresh cookie to this controller's REAL mounted route, resolved
+   * once at application boot from Moost's post-bind route table. `@HandlerPaths`
+   * defaults to the running controller, so a prefixed or subclassed mount (e.g.
+   * `api/auth` → `/api/auth/refresh`) is handled with no config; the result
+   * feeds {@link RefreshCookiePathHolder}, which `authGuardInterceptor` reads.
+   * Leaves the holder unset — so the guard keeps its configured default — on 0
+   * matches (no refresh route registered) or >1 (ambiguous; never guess),
+   * warning at boot in the ambiguous case rather than on the first request.
+   */
+  initRefreshCookiePath(paths: string[], logger: TConsoleBase): Promise<void>;
   logout(body: AuthLogoutBody | undefined): Promise<AuthOkResponse>;
   refresh(body: AuthRefreshBody | undefined): Promise<AuthLoginResponse>;
   status(): AuthContext$1;
   triggerWf(): void;
+  /**
+   * GUARDED trigger for the authenticated "change my password" flow. Unlike
+   * `triggerWf`, this is NOT `@Public()` — the auth guard rejects an
+   * unauthenticated caller with 401 before the flow starts. The method-level
+   * `@ArbacResource("auth.change-password")` overrides the class `"auth"`
+   * resource so the trigger, the `@Workflow` body, and every flow step all
+   * resolve to the same `auth.change-password` resource / `self` action — a
+   * customer enables the whole feature with a single
+   * `allow("auth.change-password", "*")` grant and forbids it (SSO-only orgs)
+   * by omitting that grant. The flow binds `ctx.subject` from the session in
+   * `init-change-password`, so it is structurally "change MY password" — there
+   * is no target-user parameter.
+   */
+  changePassword(): void;
+  /**
+   * GUARDED trigger for the authenticated "add an MFA method" flow — the
+   * profile-maintenance twin of {@link changePassword}. NOT `@Public()`: the
+   * auth guard rejects an unauthenticated caller with 401 before the flow
+   * starts, and `@ArbacResource("auth.add-mfa")` / `@ArbacAction("self")` gate
+   * the trigger, the `@Workflow` body, and the arbac-gated flow steps to one
+   * resource/action — a customer enables it with a single
+   * `allow("auth.add-mfa", "*")` grant and forbids it by omitting it. The flow
+   * binds `ctx.subject` from the session in `init-add-mfa`, so it is
+   * structurally "add a factor to MY account" with no target-user parameter.
+   */
+  addMfa(): void;
   /**
    * Side route mapping a redeemed-invite `uid` to the same idempotent
    * envelope the `inviteIdempotentRedirect` workflow step renders. The SPA
@@ -673,15 +424,15 @@ declare class AuthController {
    *
    * `@Public()` — invitees aren't signed in at this point.
    *
-   * Defaults for `loginUrl` / `alreadyAcceptedRedirectUrl` mirror the bundled
-   * `InviteWorkflowOpts` defaults (`/login` / `/login`). Subclasses override
+   * Defaults for `loginUrl` / `alreadyAcceptedRedirectUrl` mirror the unified
+   * `AuthWorkflow` 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.
+   * URLs used by `invitePostRedemption`. Defaults mirror the unified
+   * `AuthWorkflow` resolved opts so subclasses that customize either of
+   * those options can override here to keep the side route in sync.
    */
   protected resolveInvitePostRedemption(): {
     loginUrl: string;
@@ -689,6 +440,77 @@ declare class AuthController {
   };
 }
 //#endregion
+//#region src/sessions.controller.d.ts
+/**
+ * Injectable read-time session enricher. Default is identity — aooth ships NO
+ * UA-parser or GeoIP dependency. Consumers who want `device` / `browser` / `os`
+ * / `location` columns subclass this, override `enrich`, and register the
+ * replacement via moost's `createReplaceRegistry([SessionEnricherProvider, MyEnricher])`:
+ *
+ * ```ts
+ * @Injectable() // SINGLETON
+ * class MyEnricher extends SessionEnricherProvider {
+ *   override enrich(s: SessionInfo): EnrichedSession {
+ *     const ua = parseUserAgent(s.metadata?.userAgent);
+ *     return { ...s, device: ua.device, browser: ua.browser, os: ua.os,
+ *              location: geoLookup(s.metadata?.ip) };
+ *   }
+ * }
+ * ```
+ *
+ * Singleton scope is required — `@Injectable()` (no scope arg) → SINGLETON.
+ */
+declare class SessionEnricherProvider {
+  enrich(session: SessionInfo$1): EnrichedSession$1 | Promise<EnrichedSession$1>;
+}
+/**
+ * Optional, mountable controller exposing a user's active sessions for the
+ * "Active sessions" UI. Register it (or a subclass) alongside `AuthController`
+ * to enable the endpoints — registration IS the opt-in; aooth never mounts it
+ * implicitly.
+ *
+ * Routes (all under the `auth.sessions` ARBAC resource):
+ *
+ * | Method + path                      | Action     | Effect                              |
+ * | ---------------------------------- | ---------- | ----------------------------------- |
+ * | `GET    /auth/sessions`            | `read`     | the caller's own sessions           |
+ * | `GET    /auth/sessions/of/:userId` | `readAny`  | another user's sessions (admin)     |
+ * | `DELETE /auth/sessions/:sessionId` | `revoke`   | revoke one of the caller's sessions |
+ * | `DELETE /auth/sessions?others=true`| `revoke`   | revoke all but the caller's current |
+ *
+ * Each `SessionInfo` is mapped through the injectable {@link SessionEnricherProvider}
+ * before returning, and the caller's own session is flagged `current: true`.
+ * Both reads default to the browser-safe set (ordinary interactive sessions);
+ * `?kind=<kind>` segments a non-browser bucket (e.g. `?kind=cli-session`) and
+ * `?kind=*` returns every kind.
+ * NOT `@Public()` — the auth guard rejects unauthenticated callers with 401 and
+ * ARBAC gates each action; a customer enables it with `allow("auth.sessions", "*")`.
+ */
+declare class SessionsController {
+  protected readonly auth: AuthCredential;
+  protected readonly enricher: SessionEnricherProvider;
+  constructor(auth: AuthCredential, enricher: SessionEnricherProvider);
+  listSessions(kind?: string): Promise<EnrichedSession$1[]>;
+  /**
+   * Admin read of another user's sessions. Gated by the separate `readAny`
+   * action so a customer can grant ordinary users `read` (own sessions) without
+   * granting cross-user visibility.
+   */
+  listSessionsOf(userId: string, kind?: string): Promise<EnrichedSession$1[]>;
+  revokeSession(sessionId: string): Promise<{
+    ok: true;
+  }>;
+  /**
+   * `DELETE /auth/sessions?others=true` — log out everywhere else, keeping the
+   * caller's current session. Returns the number of sessions revoked. A bare
+   * `DELETE /auth/sessions` (no `others`) is a 400 — revoking ALL of one's own
+   * sessions (including the current one) is what `POST /auth/logout` is for.
+   */
+  revokeOthers(others: string | undefined): Promise<{
+    revoked: number;
+  }>;
+}
+//#endregion
 //#region src/wf-trigger/decorator.d.ts
 interface WfTriggerOpts {
   /** Whitelist of workflow ids the trigger may start/resume. Defaults to the provider's setting. */
@@ -713,11 +535,24 @@ declare const WfTrigger: (opts?: WfTriggerOpts) => ClassDecorator & MethodDecora
 //#region src/wf-trigger/provider.d.ts
 /**
  * DI singleton owning the workflow-trigger wiring: state persistence, outlets,
- * and token wire. Consumers subclass to swap the state store, add outlets
- * (email, SMS, ...), or override `handle()` for per-request dispatch logic.
+ * and token wire. Consumers subclass to swap the durable state strategy, add
+ * outlets (email, SMS, ...), or override `handle()` for per-request dispatch.
+ *
+ * State is a NAMED STRATEGY REGISTRY rather than a single strategy. Every
+ * workflow STARTS on the `encapsulated` strategy (the registry default): state
+ * rides inside the SPA-held token, so opening a login form persists ZERO
+ * server-side rows before the first validated input — a restart/eviction can no
+ * longer 410 GONE an idle form. A later step swaps to the durable `store`
+ * strategy (`swapStrategy('store')`) once there is real state worth persisting.
  *
- * Defaults are intentionally minimal: in-memory state + HTTP outlet only.
- * Production deployments swap in a persistent `WfStateStore` and any outlets
+ * Per product decision BOTH registry entries default to `EncapsulatedStateStrategy`
+ * — customers override only `storeStrategy()` to supply a real Redis/DB-backed
+ * `HandleStateStrategy`, so `swapStrategy('store')` never crashes on the bundled
+ * default. The encapsulated secret reuses the auth secret via
+ * `AuthCredential.deriveStateKey("wf-state")` (HKDF-derived, stable across
+ * restarts) unless `wfStateSecret()` is overridden with a dedicated secret.
+ *
+ * Outlets default to the HTTP outlet only; production deployments add the ones
  * they need by extending this class and re-binding via `setReplaceRegistry`.
  *
  * Uses `handleAsOutletRequest` (not `MoostWf.handleOutlet`) because the atscript
@@ -729,1501 +564,2505 @@ declare const WfTrigger: (opts?: WfTriggerOpts) => ClassDecorator & MethodDecora
  * and the wf engine reads action + form data directly from `body.input`. No
  * app-level bridging of `body.action` is needed.
  */
+/** Named state-strategy registry: the shape `handleAsOutletRequest` reads off `state`. */
+type StateRegistry = {
+  strategies: Record<string, WfStateStrategy>;
+  default: string;
+};
+/**
+ * Derive the exact 32-byte key the encapsulated wf-state strategy requires from
+ * an arbitrary-length app secret.
+ *
+ * The default {@link WfTriggerProvider.wfStateSecret} reuses the auth secret via
+ * `AuthCredential.deriveStateKey()`, which only works for stores backed by a
+ * symmetric secret (JWT / encapsulated). A stateful store (e.g. atscript-db —
+ * the recommended default once you adopt the session-listing APIs) has no key
+ * material to derive from, so its `deriveStateKey()` throws. Such consumers must
+ * override `wfStateSecret()` and supply their own secret — but the strategy
+ * needs *exactly* 32 bytes (a raw string is otherwise parsed as hex), so the
+ * obvious `return env.MY_SECRET` fails. This helper does the SHA-256-to-32-bytes
+ * derivation for you, no `node:crypto` import required:
+ *
+ * ```ts
+ * protected override wfStateSecret(): Buffer {
+ *   return deriveWfStateSecret(env.MY_SECRET);
+ * }
+ * ```
+ *
+ * Deterministic — the same input always yields the same key, so it is stable
+ * across restarts (matching what `deriveStateKey` provided).
+ */
+declare function deriveWfStateSecret(secret: string): Buffer;
 declare class WfTriggerProvider {
   protected readonly wf: MoostWf;
-  protected state: WfStateStrategy;
+  protected readonly auth: AuthCredential;
   protected outlets: WfOutlet[];
   protected token: WfOutletTokenConfig;
-  constructor(wf: MoostWf);
+  constructor(wf: MoostWf, auth: AuthCredential);
+  /**
+   * Secret for the encapsulated wf-state token. Default reuses the auth secret
+   * (HKDF-derived, stable across restarts) — which works only for stores backed
+   * by a symmetric secret (JWT / encapsulated). A stateful store (atscript-db)
+   * has nothing to derive from, so `deriveStateKey()` throws; those consumers
+   * MUST override this and supply a dedicated secret. The strategy needs exactly
+   * 32 bytes, so wrap your app secret in {@link deriveWfStateSecret}:
+   * `return deriveWfStateSecret(env.MY_SECRET)`.
+   */
+  protected wfStateSecret(): string | Buffer;
+  /** TTL (ms) for encapsulated pre-validation tokens. Default: undefined = no TTL (token valid until used), so an idle login form never expires server-side. */
+  protected wfStateEncapsulatedTtlMs(): number | undefined;
+  /** Durable strategy a workflow swaps to after the first validated input. Default = encapsulated (no real store); customers override to return e.g. new HandleStateStrategy({ store: <redis/db> }). */
+  protected storeStrategy(): WfStateStrategy;
+  private makeEncapsulated;
+  private cachedState?;
+  /** Named strategy registry: every wf starts on `encapsulated` (default); a step calls swapStrategy('store') to move durable. Built lazily so subclass overrides (storeStrategy/wfStateSecret) are in effect. */
+  protected stateRegistry(): StateRegistry;
   handle(opts?: {
     allow?: string[];
     token?: WfOutletTokenConfig;
   }): Promise<unknown>;
 }
 //#endregion
-//#region src/audit/index.d.ts
+//#region src/oauth/oauth.controller.d.ts
 /**
- * Audit event emitter — used by `LoginWorkflow.audit-login` (and future
- * recovery / invite audit steps) to fan out login.success and similar events
- * to consumer-supplied sinks (DB table, log file, Kafka topic).
+ * REST surface for federated-login ACCOUNT MANAGEMENT (OAuth2 / OIDC), RFC
+ * IDP.md §3.7. Two routes — anonymous LOGIN is NOT here: it lives in the login
+ * workflow (the login form offers a "Continue with <provider>" button that ends
+ * the wf with a redirect to the provider; see `AuthWorkflow.beginSso`). The
+ * provider's `redirect_uri` lands on the SPA, which bridges `{ provider, code,
+ * state }` into the public `/auth/trigger` STARTING `auth/login/flow` — so MFA /
+ * consent / cookie issuance reuse the existing workflow machinery.
  *
- * Aoothjs ships no concrete sink. Workflow subclasses override the
- * `audit(event)` protected method to wire their preferred sink; when not
- * overridden the workflow's default implementation is a no-op.
+ * The round-trip is STATELESS — no flow store. The PKCE verifier + OIDC nonce
+ * are DERIVED from a non-secret seed carried in the signed `state` (the same
+ * seed double-submitted in the CSRF cookie) and re-derived at the callback (see
+ * {@link OAuthProviderRegistry.deriveSeededPkce}). Nothing secret rides in the URL.
+ *
+ * - `GET  /auth/oauth/identities` — list the current user's CONNECTED ACCOUNTS
+ *   (linked provider identities). Self-scoped read projection over
+ *   `FederatedIdentityStore.listForUser(userId)`; `(provider, subject)` is the
+ *   key the client passes back to `unlink`.
+ * - `GET  /auth/oauth/:provider/link` — begin an account-LINK for the
+ *   authenticated user. 302s to the provider after deriving PKCE/nonce from a
+ *   fresh seed and signing `{ random, provider, redirect, userId }` into `state`
+ *   (the `userId` is HS256-signed → tamper-proof, server-minted). Self-scoped:
+ *   `getUserId()` 401s an anonymous caller. `sso-callback` links the verified
+ *   identity to that `userId`.
+ * - `DELETE /auth/oauth/:provider/:subject` — disconnect a linked identity.
+ *   Self-scoped; guards against removing the user's only sign-in method, then
+ *   revokes the user's sessions.
+ *
+ * `identities` / `link` / `unlink` are `@Public()` self-scoped primitives
+ * (mirroring `AuthController.logout`/`status`): they derive identity from the
+ * session, never from a parameter. Subclass + add `@ArbacAction(...)` to gate
+ * them further (e.g. an admin cross-user view).
  */
-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/flow`). */
-  workflow?: string;
-  /** Source IP (when the workflow could resolve one). */
-  ip?: string;
-  /** User-agent header. */
-  userAgent?: string;
-  /** Free-form payload — `method`, `tenantId`, etc. */
-  [key: string]: unknown;
+declare class OAuthController {
+  protected readonly registry: OAuthProviderRegistry;
+  protected readonly auth: AuthCredential;
+  protected readonly users: UserService;
+  protected readonly federated: FederatedIdentityStore;
+  constructor(registry: OAuthProviderRegistry, auth: AuthCredential, users: UserService, federated: FederatedIdentityStore);
+  /** Default post-login redirect when the caller supplies none / an unsafe one. */
+  protected defaultRedirect(): string;
+  /**
+   * List the CURRENT user's connected accounts — every provider identity linked
+   * to them, the "connected accounts" view. Self-scoped (`getUserId()` 401s an
+   * anonymous caller), mirroring `link`/`unlink`. Returns a display projection
+   * via {@link toConnectedAccount}: the surrogate `id` and the (own) `userId`
+   * are dropped, and `(provider, subject)` is exactly the key the client passes
+   * back to `DELETE :provider/:subject` to disconnect a row. Ordered by
+   * `linkedAt` (oldest first) by the store.
+   */
+  identities(): Promise<ConnectedAccount[]>;
+  link(providerId: string, redirect: string | undefined): Promise<string>;
+  /**
+   * Start machinery for an account-LINK: STATELESS — mint a fresh non-secret
+   * `seed`, DERIVE the PKCE verifier + OIDC nonce from it
+   * (`registry.deriveSeededPkce`), sign `{ random: seed, provider, redirect,
+   * userId }` into `state` (the `userId` makes the callback link to THIS user;
+   * HS256-signed so it's tamper-proof), drop the Lax double-submit cookie
+   * holding the seed, and 302 to the provider. The verifier is NOT persisted —
+   * `sso-callback` re-derives it from `state.random`. Returns an empty body
+   * (the redirect is in the headers).
+   */
+  protected begin(providerId: string, redirect: string | undefined, userId: string | undefined): Promise<string>;
+  /**
+   * `response_mode=form_post` callback bounce (Apple). Apple POSTs the callback
+   * — `application/x-www-form-urlencoded { code, state, id_token, user? }` — to
+   * the FIXED `redirect_uri`, because it requires `form_post` whenever `email`/
+   * `name` scope is requested. A static SPA page can't read a POST body, so this
+   * thin server route 303-redirects (POST → GET) to the SAME SPA callback URL
+   * with `code`/`state`/`error` in the query. From there it is BYTE-IDENTICAL to
+   * the Google/GitHub GET-callback path: the SPA forwards `{ code, state }` to
+   * `/auth/trigger`, and `sso-callback` does ALL verification (signed state,
+   * CSRF double-submit, PKCE re-derivation, ID-token exchange).
+   *
+   * This route is a DUMB transport adapter — it intentionally verifies nothing.
+   * The Lax CSRF cookie is (correctly) NOT sent on Apple's cross-site POST and
+   * is NOT read here; it rides the subsequent SAME-ORIGIN `/auth/trigger` XHR,
+   * where `sso-callback` checks it. The GET method on this same path is served
+   * by the SPA (no server handler), so there is no collision.
+   *
+   * Same-origin only: the 303 target is the registry's relative callback path
+   * with `:provider` path-encoded and only `code`/`state`/`error` echoed — never
+   * an attacker-influenced absolute URL.
+   */
+  formPostCallback(providerId: string, body: {
+    code?: unknown;
+    state?: unknown;
+    error?: unknown;
+  } | undefined): string;
+  /**
+   * Disconnect a linked provider identity from the current user. Self-scoped
+   * (`getUserId()` 401s an anonymous caller). Refuses to remove the user's ONLY
+   * remaining sign-in method (no other federated identity AND no real password)
+   * — that would strand them. On success revokes the user's sessions so a
+   * session established through the now-removed identity can't outlive it.
+   */
+  unlink(providerId: string, subject: string): Promise<{
+    ok: true;
+  }>;
+  /** Resolve a provider id, mapping the idp `UNKNOWN_PROVIDER` error to HTTP 404. */
+  protected requireProvider(providerId: string): ReturnType<OAuthProviderRegistry["require"]>;
 }
-interface AuditEmitter {
-  emit(event: AuditEvent): Promise<void> | void;
+/**
+ * Wire shape of one connected account returned by `GET /auth/oauth/identities`.
+ * A display projection of a {@link FederatedIdentity} row: the surrogate `id`
+ * and the (caller's own) `userId` are intentionally omitted. `(provider,
+ * subject)` is the disconnect key the client passes back to
+ * `DELETE /auth/oauth/:provider/:subject`; the remaining fields are the profile
+ * snapshot the row carries for display.
+ */
+interface ConnectedAccount {
+  provider: string;
+  subject: string;
+  linkedAt: number;
+  lastLoginAt?: number;
+  email?: string;
+  emailVerified?: boolean;
+  displayName?: string;
+  avatarUrl?: string;
+}
+//#endregion
+//#region src/oauth/oauth-csrf.d.ts
+/**
+ * Name of the double-submit anti-CSRF cookie set at `/:provider/start` and
+ * verified in `oauth-exchange`. Holds the signed-state `random`; the callback
+ * proves it speaks for the same browser that started the flow by matching the
+ * cookie value against the verified `state.random` (RFC IDP.md §7).
+ */
+declare const OAUTH_CSRF_COOKIE = "aooth_oauth";
+/**
+ * Cookie attributes for the CSRF cookie. `SameSite=Lax` (NOT `Strict`) so the
+ * top-level GET navigation BACK from the provider still carries it; `httpOnly`
+ * so script can't read it; short `maxAge` matched to the state TTL. `secure` is
+ * caller-controlled (off for the http test harness, on in production).
+ */
+declare function oauthCsrfCookieAttrs(opts: {
+  secure: boolean; /** Cookie lifetime in seconds — match the signed-state TTL (default 600). */
+  maxAgeSec?: number;
+  path?: string;
+}): TCookieAttributesInput;
+//#endregion
+//#region src/oauth/oauth-redirect.d.ts
+/**
+ * Open-redirect defense for the post-login `redirect` carried across the OAuth
+ * bounce (RFC IDP.md §7). The provider round-trips whatever target the SPA
+ * asked for, so it MUST be validated before it is signed into `state` AND again
+ * before it is honored — an attacker who can seed the `redirect` could
+ * otherwise turn a trusted callback into an open redirector (phishing /
+ * token-leak via `//evil.test`, `/\evil.test`, `https://evil.test`,
+ * `javascript:…`).
+ *
+ * Policy: accept ONLY a same-origin, absolute-path relative URL — it must start
+ * with a single `/`, contain no backslashes (some browsers fold `\` → `/`), and
+ * carry no control/whitespace characters (which browsers may strip, changing
+ * the parsed target). Everything else falls back to the caller's default.
+ */
+declare function isSafeRelativeRedirect(target: string | undefined): target is string;
+/**
+ * Return `requested` when it is a safe same-origin relative redirect, else
+ * `fallback`. Used at `/start` (before signing) and re-checked in
+ * `oauth-exchange` (before honoring) — defense in depth around the signed
+ * round-trip.
+ */
+declare function resolveOAuthRedirect(requested: string | undefined, fallback: string): string;
+//#endregion
+//#region src/oauth/oauth-runtime.d.ts
+/**
+ * DI holder bundling the two app-provided federated-login singletons the
+ * `sso-callback` workflow step needs. It exists so the step can resolve them
+ * via `useControllerContext().instantiate(OAuthRuntime)`: instantiating THIS
+ * `@Injectable` class resolves its constructor deps THROUGH the provide-registry
+ * — the same path that injects `AuthCredential` & friends elsewhere.
+ *
+ * The app provides `OAuthProviderRegistry` + `FederatedLoginService` via
+ * `createProvideRegistry`; this class wires them together for the step without
+ * touching `AuthWorkflow`'s constructor (so the documented subclass ctor stays
+ * unchanged). NO flow store: the PKCE verifier + OIDC nonce are derived
+ * statelessly from the signed-state seed (see `OAuthProviderRegistry.deriveSeededPkce`).
+ */
+declare class OAuthRuntime {
+  readonly registry: OAuthProviderRegistry;
+  readonly federated: FederatedLoginService;
+  constructor(registry: OAuthProviderRegistry, federated: FederatedLoginService);
+}
+//#endregion
+//#region src/oauth/oauth-tokens.d.ts
+/**
+ * Explicit string DI token for the ABSTRACT `FederatedIdentityStore`.
+ *
+ * `FederatedIdentityStore` is an abstract class. moost's constructor injection
+ * keys the provide-registry by the design:paramtype class reference, which
+ * resolves a CONCRETE provided class fine (e.g. `AuthCredential`) but not an
+ * abstract one — for an abstract paramtype infact falls back to auto-
+ * instantiating the (body-less) abstract class, yielding an object whose methods
+ * are missing. Binding the store under an explicit string token and injecting it
+ * with `@Inject(<token>)` sidesteps the class-reference path entirely (the same
+ * pattern the demo uses for its `"EmailSender"` provider).
+ *
+ * Consumers provide the concrete instance under this exact string:
+ *
+ * ```ts
+ * createProvideRegistry(
+ *   [FEDERATED_IDENTITY_STORE_TOKEN, () => new FederatedIdentityStoreAtscriptDb({ table })],
+ * )
+ * ```
+ */
+declare const FEDERATED_IDENTITY_STORE_TOKEN = "aooth:FederatedIdentityStore";
+//#endregion
+//#region src/authz/authorize.controller.d.ts
+/** RFC-6749-shaped token-endpoint error response. */
+interface TokenError {
+  error: string;
+}
+/** OIDC token-endpoint success (RFC 6749 + OIDC Core). `id_token` for OIDC clients; `access_token` per registration. */
+interface TokenSuccess {
+  token_type: "Bearer";
+  access_token?: string;
+  id_token?: string;
+  expires_in?: number;
+  /** The authenticated user id (`sub`) — convenience for a CLI; not part of the OIDC token response. */
+  userId: string;
+}
+/** A minimal OIDC discovery document (`/.well-known/openid-configuration`). */
+interface OidcDiscoveryDocument {
+  issuer: string;
+  authorization_endpoint: string;
+  token_endpoint: string;
+  jwks_uri: string;
+  response_types_supported: string[];
+  grant_types_supported: string[];
+  subject_types_supported: string[];
+  id_token_signing_alg_values_supported: string[];
+  scopes_supported: string[];
+  code_challenge_methods_supported: string[];
+  token_endpoint_auth_methods_supported: string[];
 }
+/**
+ * The authorization-server endpoints (AUTH-SERVER.md). Turns the existing login
+ * workflow into an OAuth/OIDC authorization server for the app's OWN clients — a
+ * local CLI on a loopback redirect (Tier 1) and registered first-party services
+ * (Tier 2, `id_token` / "Sign in with <main app>"). One authorization-code + PKCE
+ * flow; the only things that vary are the injected {@link ClientRedirectPolicy}
+ * and whether an {@link IdTokenSigner} is wired.
+ *
+ * - `GET  /auth/authorize` — validate the client + `redirect_uri` (the policy),
+ *   record a {@link PendingAuthorizationStore} entry (authority fixed HERE), and
+ *   302 the browser to the login page carrying the opaque `handle`. The login
+ *   workflow's `mint-authz-code` terminal delivers the code to the client.
+ * - `POST /auth/token` — the back-channel: consume the single-use code, verify
+ *   PKCE, authenticate the client (Tier 2), and mint the access token and/or the
+ *   `id_token`. Minted HERE, off the browser, so nothing long-lived rides a URL.
+ * - `GET /auth/.well-known/openid-configuration` + `GET /auth/jwks` — OIDC
+ *   discovery + the signer's public JWKS (Tier 2 only; 404 without a signer).
+ *
+ * All routes are `@Public()`. The grant's authority (token policy, `id_token`
+ * intent, audience, scope) is fixed at `/authorize` time and recorded on the
+ * pending authorization + the issued code — never inferred at `/token`.
+ */
+declare class AuthorizeController {
+  protected readonly auth: AuthCredential;
+  protected readonly policy: ClientRedirectPolicy;
+  protected readonly pending: PendingAuthorizationStore;
+  protected readonly codes: AuthCodeStore;
+  constructor(auth: AuthCredential, policy: ClientRedirectPolicy, pending: PendingAuthorizationStore, codes: AuthCodeStore);
+  /**
+   * The Tier-2 OIDC `id_token` signer, or `undefined` for a Tier-1-only (CLI)
+   * deployment — then discovery / `/auth/jwks` 404 and no `id_token` is minted.
+   * **Override** in a subclass to enable OIDC (return one `IdTokenSigner` whose
+   * issuer is `{origin}/auth`). A plain getter rather than a DI token because an
+   * OPTIONAL `@Inject`/`@Optional` dependency panics in moost's `resolveMoost`
+   * route-table pass (`useHandlerPaths`); a method has nothing for it to resolve.
+   */
+  protected getIdTokenSigner(): IdTokenSigner | undefined;
+  /**
+   * The Tier-2 OIDC profile-claims resolver. Defaults to a no-op (`sub`-only
+   * tokens); **override** to emit `email` / `name` / … from your user record.
+   */
+  protected getOidcClaimsResolver(): OidcClaimsResolver;
+  /**
+   * The SPA login route the authorize request bounces to. The opaque pending-auth
+   * `handle` is appended as `?authz=`; the SPA forwards it into the login
+   * workflow's START input so `init-login` raises `ctx.authz`. Override for a
+   * custom login path.
+   */
+  protected loginPath(): string;
+  authorize(responseType: string | undefined, redirectUri: string | undefined, clientId: string | undefined, state: string | undefined, codeChallenge: string | undefined, codeChallengeMethod: string | undefined, scope: string | undefined, nonce: string | undefined): Promise<string>;
+  token(body: {
+    grant_type?: string;
+    code?: string;
+    code_verifier?: string;
+    client_id?: string;
+    client_secret?: string;
+  } | undefined): Promise<TokenSuccess | TokenError>;
+  /**
+   * OIDC discovery (Tier 2). Derives every endpoint from the signer's `issuer`
+   * (configured as `{origin}/auth`), so a relying `OidcProvider` configured with
+   * the same `issuer` resolves `/authorize`, `/token`, and `/jwks` automatically.
+   * 404 when no signer is wired (Tier-1-only deployment).
+   */
+  discovery(): OidcDiscoveryDocument | TokenError;
+  /** The signer's public JWKS (Tier 2). 404 when no signer is wired. */
+  jwks(): Promise<Awaited<ReturnType<IdTokenSigner["jwks"]>>> | TokenError;
+  /** Fail soft: 302 the validated client redirect with an `?error=` (+ echoed `state`). */
+  protected redirectError(redirectUri: string, error: string, state: string | undefined): string;
+}
+//#endregion
+//#region src/authz/authorize-runtime.d.ts
+/**
+ * DI holder bundling the two abstract authorization-server stores the login-wf
+ * terminal (`mint-authz-code`) needs. A `@Step` body cannot `@Inject` a string
+ * token, so it resolves THIS `@Injectable` via
+ * `useControllerContext().instantiate(AuthorizeRuntime)` — instantiating it
+ * resolves its constructor deps THROUGH the provide-registry (the same path that
+ * injects `AuthCredential` & friends), keeping `AuthWorkflow`'s documented ctor
+ * untouched. Mirrors `OAuthRuntime`.
+ */
+declare class AuthorizeRuntime {
+  readonly pending: PendingAuthorizationStore;
+  readonly codes: AuthCodeStore;
+  constructor(pending: PendingAuthorizationStore, codes: AuthCodeStore);
+}
+//#endregion
+//#region src/authz/authz-tokens.d.ts
+/**
+ * Explicit string DI tokens for the ABSTRACT authorization-server stores
+ * ({@link import("@aooth/auth/authz").PendingAuthorizationStore},
+ * {@link import("@aooth/auth/authz").AuthCodeStore}) — the framework-agnostic
+ * abstracts live in `@aooth/auth/authz`; these moost-DI binding strings stay in
+ * the integration layer (the same split as `FEDERATED_IDENTITY_STORE_TOKEN`).
+ *
+ * Both are abstract classes. moost's constructor injection keys the
+ * provide-registry by the design:paramtype class reference — fine for a CONCRETE
+ * provided class, but for an abstract paramtype infact falls back to auto-
+ * instantiating the body-less abstract class, yielding an object whose methods
+ * are missing. Binding under an explicit string token + `@Inject(<token>)`
+ * sidesteps the class-reference path (the same pattern as
+ * `FEDERATED_IDENTITY_STORE_TOKEN`).
+ *
+ * Consumers provide the concrete instance under the exact string:
+ *
+ * ```ts
+ * createProvideRegistry(
+ *   [PENDING_AUTHORIZATION_STORE_TOKEN, () => new PendingAuthorizationStoreMemory()],
+ *   [AUTH_CODE_STORE_TOKEN, () => new AuthCodeStoreMemory()],
+ * )
+ * ```
+ */
+declare const PENDING_AUTHORIZATION_STORE_TOKEN = "aooth:PendingAuthorizationStore";
+declare const AUTH_CODE_STORE_TOKEN = "aooth:AuthCodeStore";
+/**
+ * DI token for the {@link import("@aooth/auth/authz").ClientRedirectPolicy} — an
+ * interface, so it has no class reference to inject by. Provide the concrete
+ * policy (e.g. `new LoopbackClientPolicy()`, a `RegisteredClientPolicy`, or a
+ * `CompositeClientPolicy` of both) under this string.
+ */
+declare const CLIENT_REDIRECT_POLICY_TOKEN = "aooth:ClientRedirectPolicy";
 //#endregion
-//#region src/workflows/login.workflow.options.d.ts
+//#region src/workflow/auth-workflow.ctx.d.ts
+type MfaTransport = "sms" | "email" | "totp";
+/** Per-user MFA method summary surfaced to forms via `@wf.context.pass 'mfa'`. */
+interface MfaSummary {
+  kind: "sms" | "email" | "totp";
+  methodName: string;
+  masked: string;
+  isDefault: boolean;
+}
 type LoginRedirect = "referer" | "home" | false | null;
 interface SsoProvider {
+  /** Provider id — matches an `OAuthProviderRegistry` entry; sent as `ssoProvider` data on the `sso` action. */
   id: string;
+  /** Provider display name — the bundled `AsSsoProviders` renders "Continue with {label}". */
   label: string;
-  url: string;
+  /** Optional icon hint for the button (e.g. an icon-class key the renderer maps). */
+  icon?: string;
 }
 interface ConcurrencyLimitOptions {
   max: number;
   onLimit: "reject" | "kickPrompt";
 }
-interface LoginWorkflowOpts {
-  deviceTrust?: {
-    cookieName?: string;
-    ttlMs?: number;
-    bindsTo?: "cookie" | "cookie+ip";
-  };
-  /**
-   * Replaceable form schemas. Each field defaults to the corresponding
-   * `.as` form shipped under `@aooth/auth-moost/atscript/models`; supply a
-   * subset to override only the forms you want to swap.
-   */
-  forms?: {
-    askEmail?: TAtscriptAnnotatedType;
-    askPhone?: TAtscriptAnnotatedType;
-    backupCode?: TAtscriptAnnotatedType;
-    concurrencyLimit?: TAtscriptAnnotatedType;
-    enrollAddress?: TAtscriptAnnotatedType;
-    enrollConfirm?: TAtscriptAnnotatedType;
-    enrollPickMethod?: TAtscriptAnnotatedType;
-    loginCredentials?: TAtscriptAnnotatedType;
-    mfaCode?: TAtscriptAnnotatedType;
-    personaSelect?: TAtscriptAnnotatedType;
-    pincode?: TAtscriptAnnotatedType;
-    profileComplete?: TAtscriptAnnotatedType;
-    select2fa?: TAtscriptAnnotatedType;
-    setPassword?: TAtscriptAnnotatedType;
-    tenantSelect?: TAtscriptAnnotatedType;
-    termsBump?: TAtscriptAnnotatedType;
-  };
-}
 /**
- * Fully-resolved view used by the workflow at runtime — every nested group is
- * always populated by `mergeLoginOpts`, so step bodies can read
- * `this.opts.<group>.<flag>` directly without optional chaining.
+ * Consent descriptor wire shape — mirrors `ConsentDescriptor` from the
+ * consent store without importing the runtime module (avoids cycles).
  */
-interface ResolvedLoginWorkflowOpts {
-  deviceTrust: {
-    cookieName: string;
-    ttlMs: number;
-    bindsTo: "cookie" | "cookie+ip";
-  };
-  forms: {
-    askEmail: TAtscriptAnnotatedType;
-    askPhone: TAtscriptAnnotatedType;
-    backupCode: TAtscriptAnnotatedType;
-    concurrencyLimit: TAtscriptAnnotatedType;
-    enrollAddress: TAtscriptAnnotatedType;
-    enrollConfirm: TAtscriptAnnotatedType;
-    enrollPickMethod: TAtscriptAnnotatedType;
-    loginCredentials: TAtscriptAnnotatedType;
-    mfaCode: TAtscriptAnnotatedType;
-    personaSelect: TAtscriptAnnotatedType;
-    pincode: TAtscriptAnnotatedType;
-    profileComplete: TAtscriptAnnotatedType;
-    select2fa: TAtscriptAnnotatedType;
-    setPassword: TAtscriptAnnotatedType;
-    tenantSelect: TAtscriptAnnotatedType;
-    termsBump: TAtscriptAnnotatedType;
+interface ConsentDescriptorLike {
+  id: string;
+  text: string;
+  required?: string;
+  version?: string;
+}
+/**
+ * Consents — both server state (`accepted` / `decidedAt`) and the
+ * UI-visible descriptor list (`pending`). Shipped via
+ * `@wf.context.pass 'consents'`.
+ */
+interface AuthWfConsentsState {
+  pending?: ConsentDescriptorLike[];
+  accepted?: string[];
+  decidedAt?: number;
+}
+/**
+ * UI hints for pincode entry — FORM-FACING via `@wf.context.pass 'pincode'`.
+ * All three flows (login MFA SMS/email, recovery OTP, invite MFA
+ * enrol-confirm) write here.
+ *
+ * `channelCooldowns` is the anti-ping-pong gate for the MFA-challenge loop:
+ * a single `resendAllowedAt` is cleared on every `useDifferentMethod` so the
+ * user's first attempt at the new channel isn't gated for the WRONG
+ * channel's reason, BUT the per-channel timestamps in `channelCooldowns`
+ * survive method-switching so ping-ponging (SMS → Email → SMS → …) cannot
+ * be used to bypass the per-channel rate limit. `pincode-send` enforces the
+ * per-channel gate before delivering; `select-2fa` enforces it BEFORE the
+ * send to surface a per-channel error string on the form.
+ */
+interface AuthWfPincodeUiState {
+  sentTo?: string;
+  codeLength?: number;
+  resendAllowedAt?: number;
+  channelCooldowns?: Partial<Record<MfaTransport, number>>;
+}
+/**
+ * MFA enrolment running state. `pincodeCooldown` removed — enrol-confirm
+ * uses the same `ctx.pincode.resendAllowedAt` slot as the challenge path.
+ */
+interface AuthWfMfaEnrollState {
+  method?: MfaTransport;
+  address?: string;
+  secret?: string;
+  uri?: string;
+  availableTransports?: MfaTransport[];
+  /**
+   * Drives skip / cancel visibility on the enrolment forms:
+   * - `'optional'` — login/invite first-time opt-in: "Skip for now" shows.
+   * - `'required'` — forced enrolment: neither skip nor cancel.
+   * - `'manage'` — the standalone manage-MFA flow (user opened it on purpose):
+   *   "Skip for now" is hidden, a "Cancel" action shows instead.
+   */
+  mode?: "required" | "optional" | "manage";
+  done?: boolean;
+  /**
+   * Gates the standalone `enroll-totp-qr` step (TOTP only). Set once the user
+   * has been shown the QR/secret and clicked Continue, so the QR pause fires
+   * before — not alongside — the code-entry step. Shared by both surfaces.
+   */
+  qrSeen?: boolean;
+  /**
+   * When set, `enroll-confirm` does NOT make the freshly-confirmed method the
+   * user's default. Set by `init-add-mfa` (the standalone add-MFA flow) when the
+   * user already has a default — adding a secondary factor must not silently
+   * change which method is challenged first. Unset on the login/invite forced-
+   * enrolment path (the user has no default yet), so the first method still
+   * becomes the default there — behaviour-preserving.
+   */
+  keepExistingDefault?: boolean;
+}
+/** FORM-FACING via `@wf.context.pass 'password'`. Read by `SetPasswordForm`. */
+interface AuthWfPasswordUiState {
+  policies?: TransferablePolicy[];
+  changeReason?: "initial" | "expired" | "reset";
+  heading?: string;
+  intro?: string;
+}
+/**
+ * Completion outcome — carries data set by terminal steps. Step-completion
+ * is encoded by the wf engine's cursor, NOT by ctx flags; only fields that
+ * carry actual data (read downstream) live here.
+ */
+interface AuthWfCompletionState {
+  redirectUrl?: string;
+}
+/** Unified MFA policy — replaces login's hardcoded defaults + invite's `{issuer}` resolver. */
+interface AuthWfMfaPolicy {
+  mode: "required" | "optional" | "disabled";
+  availableTransports: MfaTransport[];
+  issuer: string;
+}
+/**
+ * MFA verification state. Verification result migrated to `AuthWfOtpState`;
+ * cooldown migrated to `AuthWfPincodeUiState`.
+ */
+interface AuthWfMfaState {
+  enrolledMethods?: MfaSummary[];
+  current?: MfaTransport;
+  method?: "sms" | "email" | "totp";
+  saveAsDefault?: boolean;
+  ignoreDefault?: boolean;
+  runsRemaining?: number;
+  methodCount?: number;
+}
+/** Channel-onboarding state (login Phase 3). */
+interface AuthWfChannelState {
+  emailConfirmed?: boolean;
+  phone?: string;
+  phoneConfirmed?: boolean;
+  otpDisclosure?: string;
+}
+/** Device-trust state (login). */
+interface AuthWfTrustState {
+  deviceTrustToken?: string;
+  newDevice?: boolean;
+  rememberDevice?: boolean;
+  optIn?: boolean;
+}
+/** Session-policy state (login). */
+interface AuthWfSessionState {
+  riskStepUpReason?: string;
+  activeSessions?: number;
+  riskStepUpEvaluated?: boolean;
+}
+/** Alt-credential mirror flags (login). */
+interface AuthWfAltActionsState {
+  forgotPassword?: boolean;
+  signup?: boolean;
+  magicLink?: boolean;
+  usedMagicLink?: boolean;
+  /** SSO providers offered on the login form — each renders a `sso-<id>` button. */
+  ssoProviders?: SsoProvider[];
+}
+/** Alternate-credential policy (login). */
+interface AuthWfAltCredsPolicy {
+  forgotPassword: boolean;
+  signup: boolean;
+  magicLink: boolean;
+  magicLinkSkipsMfa: boolean;
+  ssoProviders: SsoProvider[];
+  recoveryUrl: string;
+  signupUrl: string;
+  embedRecovery: boolean;
+}
+/** Device-trust policy (login). */
+interface AuthWfDeviceTrustPolicy {
+  enabled: boolean;
+  optIn: boolean;
+  skipsMfa: boolean;
+}
+/** Channel-enrolment policy (login). */
+interface AuthWfEnrollmentPolicy {
+  ensureEmail: boolean;
+  ensurePhone: boolean;
+}
+/** Finalize policy (login). `auditLogin` REMOVED — audit moved to interceptors. */
+interface AuthWfFinalizePolicy {
+  notifyNewDevice: boolean;
+  redirect: LoginRedirect;
+}
+/** Login-time guards policy. */
+interface AuthWfGuardsPolicy {
+  passwordInitial: boolean;
+  passwordExpiry: boolean;
+  emailVerifiedRequired: boolean;
+}
+/** Session-policy (login). */
+interface AuthWfSessionPolicy {
+  concurrencyLimit?: ConcurrencyLimitOptions;
+}
+/**
+ * Authenticated change-password policy (change-password.flow). Resolved by
+ * `resolveChangePasswordPolicy`, written to `ctx.changePassword` by
+ * `prepare-change-password`. The flow's whole purpose is gated on this slot's
+ * presence (it's also the per-flow discriminator — see the package CLAUDE.md
+ * flow-discrimination table).
+ *
+ * Primary protection is current-password re-entry (enforced by
+ * `UserService.changePassword`), NOT rate limiting — so `rateLimit` is
+ * optional and off by default.
+ *
+ * - `revokeOtherSessions` — on success, revoke every session for the user then
+ *   re-issue the acting session a fresh token (OWASP Session Management: kill
+ *   ghost sessions after a credential change). Default `true`.
+ * - `rateLimit.minIntervalMs` — minimum gap between successive password changes
+ *   (Okta "minimum password age"). Enforced against `password.lastChanged` with
+ *   ZERO extra storage. Omit to disable.
+ */
+interface AuthWfChangePasswordPolicy {
+  revokeOtherSessions: boolean;
+  rateLimit?: {
+    minIntervalMs: number;
   };
 }
 /**
- * Deep-merge defaults with the user-supplied nested pojo. Each group has its
- * own `{ ...defaults, ...input }` line — small enough that pulling in lodash
- * would be silly.
+ * Failed-login lockout posture. Picks HOW a tripped account lockout is lifted:
+ * - `admin-only`   — permanent lock; only an admin (UserService.unlockAccount)
+ *                    lifts it. The recovery flow may still reset the password
+ *                    but does NOT unlock.
+ * - `self-service` — permanent lock; completing the recovery (password-reset)
+ *                    flow lifts it (`unlock-account` step).
+ * - `temporary`    — timed lock; auto-expires after the configured duration
+ *                    (UserService `lockout.duration`). Recovery does NOT
+ *                    unlock early. This is the default (preserves prior behavior).
+ *
+ * The mode governs the lock DURATION the workflow asks UserService to apply on
+ * the threshold trip (`temporary` → configured duration; the two permanent
+ * modes → `0`) and whether recovery runs `unlock-account`. The attempt
+ * THRESHOLD and the temporary DURATION themselves remain UserService config.
+ */
+type AuthWfLockoutMode = "admin-only" | "self-service" | "temporary";
+/** Lockout policy (login + recovery). */
+interface AuthWfLockoutPolicy {
+  mode: AuthWfLockoutMode;
+}
+/** Admin-form policy (invite admin phase). */
+interface AuthWfAdminFormPolicy {
+  collectRoles: boolean;
+}
+/**
+ * Invite-accept state (merged policy + state). No `freshLoginRequired` —
+ * the auto-login choice is the static `AuthWorkflowOpts.autoLoginOnInvite`.
  */
-declare function mergeLoginOpts(opts?: LoginWorkflowOpts): ResolvedLoginWorkflowOpts;
-//#endregion
-//#region src/workflows/login.workflow.d.ts
-interface LoginWfCtx {
-  /**
-   * 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;
+interface AuthWfAcceptState {
+  alreadyAcceptedRedirectUrl?: string;
+  loginUrl?: string;
+  showConfirmation?: boolean;
+  confirmationMessage?: string;
+  alreadyAccepted?: boolean;
+}
+/**
+ * Recovery post-reset state. `freshLoginRequired` removed — the choice is
+ * the static `AuthWorkflowOpts.autoLoginOnRecover`.
+ */
+interface AuthWfPostResetState {
+  revokeAllSessions?: boolean;
+  loginUrl?: string;
+}
+/** Recovery alt-actions policy. */
+interface AuthWfRecoveryAltActions {
+  backToLogin: boolean;
+}
+/**
+ * OTP verification flag — SERVER-ONLY (NOT form-facing). Set true by any
+ * of: pincode-check, totp-check, enroll-confirm. Loop-exit signal.
+ */
+interface AuthWfOtpState {
+  verified?: boolean;
+}
+/** Invite admin-side (Phase A) state. */
+interface AuthWfAdminState {
+  availableRoles?: string[];
+  roles?: string[];
+  userExtras?: Record<string, unknown>;
+  /**
+   * Outlet-pause idempotency marker for `send-email`. Flipped to `true`
+   * after the first dispatch so the invitee's magic-link resume — which
+   * re-executes the step body — short-circuits instead of dispatching a
+   * second email and re-pausing. See `sendInviteEmail` for the why.
+   */
+  emailDispatched?: boolean;
+}
+/**
+ * Pre-fill payload surfaced to forms via `@wf.context.pass 'defaults'`.
+ * Used by recovery's `request` step to seed the email input from a
+ * `?username=` query param carried from login's `forgotPassword` alt-action.
+ */
+interface AuthWfDefaults {
+  email?: string;
+}
+/**
+ * Federated-login (OAuth2 / OIDC) flow state. Populated by the `sso-callback`
+ * @Step after a verified provider profile resolves to a user. The login flow
+ * runs `sso-callback` (instead of `credentials`) when the start input carries
+ * an OAuth callback (`ctx.idpInbound`); `ctx.oauth` set ⇒ this login run came
+ * in through the federated leg (a discriminator usable by `resolveXxx` hooks,
+ * alongside `ctx.accept` / `ctx.postReset` / `ctx.signup`).
+ *
+ * Carries NO secret material — the PKCE verifier / nonce / authorization `code`
+ * are consumed inside `sso-callback`. The verifier + nonce are RE-DERIVED there
+ * from the signed-state seed (HMAC, stateless — no server-side flow store),
+ * never stored and never on ctx. Only the post-resolve audit/UX fields land here.
+ */
+interface AuthWfOAuthState {
+  /** The provider id (`google`, `oidc:<issuer>`, …) the subject authenticated with. */
+  provider: string;
+  /**
+   * The `FederatedLoginService.resolveUser` outcome that set `ctx.subject`.
+   * `interactively-linked` is the `prove-control` completion of a `needs-link`
+   * (the user proved control of an existing account, after which the verified
+   * identity was attached) — recorded distinctly from a returning `linked` for
+   * audit fidelity.
+   */
+  outcome?: "linked" | "created" | "auto-linked" | "interactively-linked";
+  /** `true` only for the `created` outcome (a brand-new federated account). */
+  isNew?: boolean;
+  /**
+   * The validated post-login app redirect target carried across the OAuth
+   * bounce (signed into `state`, re-validated against the allow-list in
+   * `oauth-exchange`). Read by `resolveRedirect` so the `redirect` tail step
+   * sends the SPA to the originating page. Same-origin relative path only.
+   */
+  redirect?: string;
+}
+/**
+ * Pending interactive identity-link state — set by `sso-callback` when
+ * `FederatedLoginService.resolveUser` returns `needs-link` (a verified
+ * federated profile whose email matches an EXISTING local account under the
+ * default `require-interactive-link` policy). The `prove-control` @Step reads
+ * this to challenge the user for control of `candidateUserId`; on success it
+ * calls `linkIdentity` and only THEN sets `ctx.subject`. Cleared
+ * (`delete ctx.pendingLink`) once the link completes, the user cancels, or a
+ * terminal failure fires.
+ *
+ * SECURITY: `candidateUserId` is UNTRUSTED until the proof passes — it must
+ * NEVER be copied to `ctx.subject` before then, because `{ break: !ctx.subject }`
+ * (the schema gate right after `sso-callback`) is what keeps an unproven user
+ * out of the token-issuing tail. The `snapshot` has `profile.raw` stripped (raw
+ * claims are never persisted — RFC §7). The OTP-proof code lives HERE, not on the
+ * shared top-level `ctx.pin`, so it cannot collide with the post-link MFA loop's
+ * own pincode in the same run.
+ */
+interface AuthWfPendingLinkState {
+  /** The existing local account the verified identity attaches to once control is proven. UNTRUSTED until then. */
+  candidateUserId: string;
+  /** Provider id (`google`, `oidc:<issuer>`, …) of the verified identity awaiting link. */
+  provider: string;
+  /** The IdP subject (`sub`) of the verified identity awaiting link. */
+  subject: string;
+  /** Display snapshot stamped onto the federated row on link (`profile.raw` stripped). */
+  snapshot?: FederatedProfileSnapshot;
+  /** Validated post-link app redirect, carried from the signed `state`. Same-origin relative path. */
+  redirect?: string;
+  /** Proof channel: `password` (account has a real password) or `otp` (passwordless → code to the account's OWN confirmed channel). */
+  mode: "password" | "otp";
+  /** OTP mode only — the candidate's confirmed channel the proof code is delivered to. */
+  otpChannel?: "email" | "sms";
+  /** OTP mode only — flipped `true` after the first code dispatch so a re-pause doesn't re-send. */
+  sent?: boolean;
+  /** OTP mode only — epoch ms before which a `resend` is refused (same per-pincode cooldown the MFA loop uses). Armed on every dispatch. */
+  resendAllowedAt?: number;
+  /** Masked candidate identifier shown on the prove-control form ("an account for a***@x.com exists"). Safe to expose. */
+  hint?: string;
+  /** OTP mode only — masked delivery target for the "code sent to …" copy. Safe to expose. */
+  sentTo?: string;
+  pin?: string;
+  pinExpire?: number;
+  pinAttempts?: number;
+}
+/**
+ * Standalone add-MFA flow state (`auth/add-mfa/flow`). Populated by
+ * `init-add-mfa`; its presence on ctx is the flow discriminator (§ per-flow
+ * discrimination — mirrors `ctx.changePassword` / `ctx.signup`). The flow
+ * REUSES the login/invite enrolment trio (`enroll-pick-method` /
+ * `enroll-address` / `enroll-confirm`), driving it via `ctx.mfaPolicy`
+ * narrowed to the un-enrolled transports — so a logged-in user adds exactly the
+ * methods they don't already have (single remaining transport auto-picks).
+ */
+interface AuthWfAddMfaState {
+  /**
+   * Transports the user has NOT yet confirmed = resolved
+   * `availableTransports` minus already-enrolled. The manage menu offers these
+   * as "Add" options (a zero-MFA user goes straight to the enrol picker over
+   * the same list). `finish-add-mfa` reads it to distinguish "nothing to add"
+   * from "user cancelled".
+   */
+  candidates?: MfaTransport[];
+  /**
+   * Transports the user may NOT change or remove via this flow — resolved by
+   * `resolveLockedMfaTransports` (default: none). A customer locks a factor
+   * whose value IS a login handle (e.g. the MFA email equals the
+   * `@aooth.user.email` handle) so the user can't silently desync it here.
+   * Locked transports are omitted from the menu's Change/Remove options and
+   * re-checked server-side in `manage-menu` / `confirm-remove-mfa`.
+   */
+  locked?: MfaTransport[];
+  /**
+   * `true` when the user already has ≥1 confirmed method, so the manage flow
+   * must step-up (re-verify identity) BEFORE offering add/change/remove, and
+   * shows the management menu. The METHOD of step-up is `stepUpMode`. `false`
+   * (zero confirmed methods) skips both — the flow degrades to the first-time
+   * enrol picker (the opt-in path).
+   */
+  stepUpRequired?: boolean;
+  /**
+   * How the step-up is performed (set by `init-add-mfa` when `stepUpRequired`):
+   * - `'mfa'` — the user has ≥1 confirmed factor whose kind is still in the
+   *   policy's `availableTransports`, so `mfaStepUpLoop` challenges it.
+   * - `'password'` — every confirmed factor is of a kind the policy no longer
+   *   allows (none is challengeable), so `manage-password-reauth` re-verifies
+   *   via the account password instead. Fail-closed fallback that keeps "prove
+   *   identity before managing factors" intact even after a policy tightening
+   *   orphaned the only enrolled factor.
+   */
+  stepUpMode?: "mfa" | "password";
+  /**
+   * Set once the step-up factor verifies AND the flow has swapped off the
+   * encapsulated start onto the durable `store` strategy (server-anchored,
+   * replay-resistant). Gates the one-time swap + the management menu.
+   */
+  stepUpDone?: boolean;
+  /** The management action the user picked on the menu. */
+  action?: "add" | "replace" | "remove";
+  /** The transport the chosen `action` applies to. */
+  target?: MfaTransport;
+  /** Set by `confirm-remove-mfa` so `finish-add-mfa` can report which factor was removed. */
+  removed?: MfaTransport;
+}
+/**
+ * Self-signup flow state. Populated by `init-signup` (policy from
+ * `resolveSignupPolicy`) and `signup-form` (the `submitted` marker). Its
+ * presence on ctx is the signup-flow discriminator (§ per-flow discrimination):
+ * `ctx.signup` set ⇒ `auth/signup/flow` is running (mirrors `ctx.accept` /
+ * `ctx.postReset` / `ctx.changePassword` for the other flows).
+ */
+interface AuthWfSignupState {
+  /** Resolved gate — `false` (the default) disables self-signup; `init-signup` emits a terminal "signups are disabled" finish. */
+  allowSignup?: boolean;
+  /** When `true`, the signup form collects a `username` distinct from the email; otherwise `username := email`. */
+  collectUsername?: boolean;
+  /** Set by `signup-form` once a valid email (+ optional username) is submitted — gates the OTP loop. */
+  submitted?: boolean;
+}
+/**
+ * Public-facing context surface — the **only** group form schemas may read
+ * from via `@wf.context.pass 'public'`. Every other top-level key
+ * (`ctx.mfa`, `ctx.pincode`, `ctx.trust`, etc.) is server-only and must
+ * never be whitelisted on a form.
+ *
+ * Population is centralized in `AuthWorkflow.populatePublic(ctx)` which is
+ * invoked by the `throwPublic` helper immediately before any
+ * `requireInput`-style pause. Adding a new FE-consumed field has three
+ * touch points: add it to a subgroup here, copy it in `populatePublic`,
+ * and reference it in the form schema as `ctx.public.<group>.<field>`.
+ *
+ * Subgroups mirror the internal `ctx.<group>` shape one-for-one but only
+ * carry the subset of fields that forms actually read. Internal-only
+ * fields (e.g., `pincode.channelCooldowns`, `mfa.saveAsDefault`,
+ * `mfa.current`, `mfa.ignoreDefault`, `trust.deviceTrustToken`,
+ * `channel.phone`, `mfaEnroll.address`, …) are deliberately omitted so
+ * they cannot leak to the wire.
+ */
+interface AuthWfPublicState {
+  /** Mirrors `ctx.consents` — pending descriptor list + decision marker. */
+  consents?: {
+    pending?: ConsentDescriptorLike[];
+    decidedAt?: number;
   };
-  deviceTrust?: {
-    enabled: boolean;
-    optIn: boolean;
-    skipsMfa: boolean;
+  /** Mirrors `ctx.altActions` — which alt-action buttons render on login (incl. SSO providers). */
+  altActions?: {
+    forgotPassword?: boolean;
+    signup?: boolean;
+    magicLink?: boolean;
+    ssoProviders?: SsoProvider[];
   };
-  enrollment?: {
-    ensureEmail: boolean;
-    ensurePhone: boolean;
+  /**
+   * Mirrors `ctx.mfa` — only the fields forms read (method picker /
+   * useDifferentMethod gating / transport-hint copy). Internal fields like
+   * `saveAsDefault`, `ignoreDefault`, `current` stay on `ctx.mfa`.
+   */
+  mfa?: {
+    method?: MfaTransport;
+    methodCount?: number;
+    enrolledMethods?: MfaSummary[];
   };
-  finalize?: {
-    auditLogin: boolean;
-    notifyNewDevice: boolean;
-    redirect: LoginRedirect;
+  /**
+   * Mirrors `ctx.pincode` — masked recipient + code length + resend
+   * timestamp. `channelCooldowns` (the per-channel anti-ping-pong ledger)
+   * is deliberately omitted so the FE cannot see which other channels are
+   * currently rate-limited.
+   */
+  pincode?: {
+    sentTo?: string;
+    codeLength?: number;
+    resendAllowedAt?: number;
   };
-  guards?: {
-    passwordInitial: boolean;
-    passwordExpiry: boolean;
-    emailVerifiedRequired: boolean;
+  /** Mirrors `ctx.trust.optIn` — gates the "Remember this device" checkbox. */
+  trust?: {
+    optIn?: boolean;
   };
-  mfaConfig?: {
-    backupCodes: boolean;
+  /**
+   * Mirrors `ctx.password` — policy ruleset for the live-rules renderer
+   * plus the per-flow title / intro copy. `changeReason` stays internal —
+   * the user-facing copy is already pre-rendered into `heading`/`intro`.
+   */
+  password?: {
+    heading?: string;
+    intro?: string;
+    policies?: TransferablePolicy[];
   };
-  multiContext?: {
-    tenantSelect: boolean;
-    personaSelect: boolean;
+  /** Mirrors `ctx.admin.availableRoles` — the role picker for invites. */
+  admin?: {
+    availableRoles?: string[];
   };
-  sessionPolicy?: {
-    concurrencyLimit?: ConcurrencyLimitOptions;
+  /** Mirrors `ctx.channel.otpDisclosure` — TCPA/PECR disclosure paragraph. */
+  channel?: {
+    otpDisclosure?: string;
   };
-  username?: string;
-  /** Legacy alias for `pwReset`; kept until tests migrate. */
-  mfaRequired?: boolean;
-  isPasswordInitial?: boolean;
   /**
-   * Set in `credentials` when `guards.passwordExpiry` is true AND
-   * `UserService.isPasswordExpired(user)` returns true. Combined with
-   * `isPasswordInitial` in the forced-change schema condition — either
-   * being truthy routes the user through `prepare-password-rules` +
-   * `create-password-form`. Reset after `create-password-form` commits.
+   * Mirrors `ctx.mfaEnroll` — only what the enrolment forms display.
+   * `address` stays internal (user-typed, no need to bounce it back).
    */
-  isPasswordExpired?: boolean;
+  mfaEnroll?: Pick<AuthWfMfaEnrollState, "method" | "mode" | "availableTransports" | "secret" | "uri">;
   /**
-   * Discriminator for `SetPasswordForm` UX. `'initial'` when the
-   * password has never been used (first-set flow); `'expired'` when the
-   * password aged past `config.password.maxAgeMs` (rotation flow). When
-   * both conditions are true, `'initial'` wins — a never-used password
-   * being "expired" is semantically still its initial set. Shipped to
-   * the client via `@wf.context.pass` on `SetPasswordForm` so the SPA
-   * can swap banner copy; default form labels stay reason-agnostic.
+   * Mirrors the manage-MFA menu inputs — the un-enrolled transports the user
+   * can Add and the locked transports to omit from Change/Remove. The enrolled
+   * method list the menu cross-references is `public.mfa.enrolledMethods`.
    */
-  passwordChangeReason?: "initial" | "expired";
-  usedMagicLink?: boolean;
+  manage?: {
+    candidates?: MfaTransport[];
+    locked?: MfaTransport[];
+  };
+  /** Mirrors `ctx.defaults` — prefill source for the recovery email field. */
+  defaults?: {
+    email?: string;
+  };
   /**
-   * 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;
+   * Mirrors `ctx.pendingLink` display fields — the proof `mode`, the masked
+   * account `hint` ("an account for a***@x.com exists"), the masked delivery
+   * `sentTo` (OTP mode), and the `resendAllowedAt` cooldown the resend button
+   * reads to disable/count-down. Only masked/UX fields are projected — the
+   * `candidateUserId` / provider `subject` / proof `pin` stay server-only.
+   */
+  proveControl?: {
+    mode?: "password" | "otp";
+    hint?: string;
+    sentTo?: string;
+    resendAllowedAt?: number;
+  };
   /**
-   * 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.
+   * Mirrors `ctx.newPasswordRequired` — hides "Remember this device" on
+   * verify forms when a forced password change will follow.
    */
-  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;
+  newPasswordRequired?: boolean;
+}
+/** Unified workflow context shape — one type for all three flows. */
+interface AuthWfCtx {
+  subject?: string;
+  email?: string;
+  defaults?: AuthWfDefaults;
   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;
+  /** Wrong-code attempt counter for the currently minted pincode. Reset by `mintPin`; incremented by `verifyPin`; cleared when the cap is hit (which also clears `pin`/`pinExpire` so the user must request a fresh code). */
+  pinAttempts?: number;
+  aborted?: boolean;
+  isFirstLogin?: boolean;
+  newPasswordRequired?: boolean;
+  autoLogin?: boolean;
+  consents?: AuthWfConsentsState;
+  pincode?: AuthWfPincodeUiState;
+  mfaEnroll?: AuthWfMfaEnrollState;
+  password?: AuthWfPasswordUiState;
+  completion?: AuthWfCompletionState;
+  /**
+   * Marks that the `promote-to-handle` @Step has already run for this flow, so
+   * it fires once after a channel is confirmed and is skipped on every later
+   * resume (the store write is idempotent, but re-running it each resume would
+   * be wasteful). Server-only — never `@wf.context.pass`'d.
+   */
+  promoteToHandleDone?: boolean;
+  alternateCredentials?: AuthWfAltCredsPolicy;
+  deviceTrust?: AuthWfDeviceTrustPolicy;
+  enrollment?: AuthWfEnrollmentPolicy;
+  finalize?: AuthWfFinalizePolicy;
+  guards?: AuthWfGuardsPolicy;
+  lockout?: AuthWfLockoutPolicy;
+  sessionPolicy?: AuthWfSessionPolicy;
+  changePassword?: AuthWfChangePasswordPolicy;
+  signup?: AuthWfSignupState;
+  addMfa?: AuthWfAddMfaState;
+  oauth?: AuthWfOAuthState;
+  pendingLink?: AuthWfPendingLinkState;
+  mfaPolicy?: AuthWfMfaPolicy;
+  adminForm?: AuthWfAdminFormPolicy;
+  accept?: AuthWfAcceptState;
+  postReset?: AuthWfPostResetState;
+  recoveryAltActions?: AuthWfRecoveryAltActions;
+  mfa?: AuthWfMfaState;
+  channel?: AuthWfChannelState;
+  trust?: AuthWfTrustState;
+  session?: AuthWfSessionState;
+  altActions?: AuthWfAltActionsState;
+  admin?: AuthWfAdminState;
+  otp?: AuthWfOtpState;
+  isPasswordInitial?: boolean;
+  isPasswordExpired?: boolean;
+  /**
+   * Captured by `init-login` when the START input is an OAuth callback (signed
+   * `state` present). Presence routes the login schema to `sso-callback` and
+   * skips `credentials`; `sso-callback` reads the callback inputs from HERE (not
+   * the step input) because the wf engine clears the step input after
+   * `init-login` runs — before `sso-callback` (the next step) executes.
+   */
+  idpInbound?: {
+    code?: string;
+    state: string;
+    error?: string;
   };
-  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;
-  /** 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;
-    name: string;
-  }>;
-  selectedTenantId?: string;
-  availablePersonas?: Array<{
-    id: string;
-    label: string;
-  }>;
-  selectedPersonaId?: string;
-  riskStepUpReason?: string;
-  activeSessions?: number;
-  passwordChanged?: boolean;
-  profileApplied?: 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.
+   * Authorization-server marker (AUTH-SERVER.md §4.4). Set when this login was
+   * started from `GET /auth/authorize` — `init-login` raises it from the START
+   * input `authz` (the opaque pending-authorization handle), and `sso-callback`
+   * re-raises it from the federated `state.handle` when the user took a
+   * "Continue with <provider>" detour mid-authorize. Presence routes the login
+   * tail to the `mint-authz-code` terminal (deliver an auth code to the client)
+   * INSTEAD of `issue`/`redirect` — no browser session is minted.
    */
-  consentsPersisted?: boolean;
-  tokensIssued?: boolean;
-  redirectUrl?: string;
+  authz?: {
+    handle: string;
+  };
   /**
-   * Set true by abort alt-actions (`logout`, `decline`, `cancel`). All terminal
-   * steps (`issue`, `audit-login`, `notify-new-device`, `redirect`) gate on
-   * `!ctx.aborted` so the abort response set via `useWfFinished()` stays.
+   * FE-facing surface — the ONLY top-level ctx key whitelisted on form
+   * schemas. Populated by `AuthWorkflow.populatePublic(ctx)` at every pause
+   * boundary; see `AuthWfPublicState` for the exact mirror shape. Never
+   * write to other `ctx.<group>` slots from form schemas — they're internal.
    */
-  aborted?: boolean;
-  /** Tracks whether `risk-step-up` has already been evaluated this iteration. */
-  riskStepUpEvaluated?: boolean;
+  public?: AuthWfPublicState;
+}
+//#endregion
+//#region src/workflow/auth-workflow.opts.d.ts
+interface AuthWorkflowOpts {
+  autoLoginOnInvite?: boolean;
+  autoLoginOnRecover?: boolean;
+  /** Pincode infrastructure shared by login MFA, invite MFA, and recovery OTP. */
+  mfa?: {
+    pincodeLength?: number;
+    pincodeTtlMs?: number;
+    pincodeResendTimeoutMs?: number; /** Max wrong-code submissions per minted pincode before the code is invalidated and the user must request a fresh one. Defaults to 5. */
+    pincodeMaxAttempts?: number;
+  };
+  /** Persisted-state TTL for the recovery flow — caps the window between OTP request and password reset. Applied at every recovery-side `requireInput` pause via the wf engine's `output.expires`. */
+  recoveryStateTtlMs?: 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;
+  deviceTrust?: {
+    cookieName?: string;
+    ttlMs?: number;
+    bindsTo?: "cookie" | "cookie+ip";
+  };
+  forms?: {
+    loginCredentials?: TAtscriptAnnotatedType;
+    invite?: TAtscriptAnnotatedType;
+    recoveryEmailIdentifier?: TAtscriptAnnotatedType;
+    askEmail?: TAtscriptAnnotatedType;
+    askPhone?: TAtscriptAnnotatedType;
+    enrollPickMethod?: TAtscriptAnnotatedType;
+    enrollAddress?: TAtscriptAnnotatedType; /** TOTP QR step — shown before the code-entry pause (manage + opt-in). */
+    enrollTotpQr?: TAtscriptAnnotatedType;
+    enrollConfirm?: TAtscriptAnnotatedType; /** Manage-MFA menu (Add / Change / Remove) shown after step-up. */
+    manageMfa?: TAtscriptAnnotatedType; /** Confirm-removal pause for the manage-MFA "Remove" action. */
+    removeMfaConfirm?: TAtscriptAnnotatedType; /** Password re-auth — step-up fallback when no factor is MFA-challengeable. */
+    passwordReauth?: TAtscriptAnnotatedType;
+    select2fa?: TAtscriptAnnotatedType;
+    mfaCode?: TAtscriptAnnotatedType;
+    pincode?: TAtscriptAnnotatedType;
+    setPassword?: TAtscriptAnnotatedType; /** Authenticated self-service "change my password" form (current + new + confirm). */
+    changePassword?: TAtscriptAnnotatedType; /** Password-proof form rendered by `prove-control` when the matched account has a real password. */
+    proveControl?: TAtscriptAnnotatedType; /** OTP-proof form rendered by `prove-control` when the matched account is passwordless. */
+    proveControlOtp?: TAtscriptAnnotatedType;
+    termsBump?: TAtscriptAnnotatedType;
+    concurrencyLimit?: TAtscriptAnnotatedType;
+    recoveryPincode?: TAtscriptAnnotatedType; /** Self-signup identifier form (`auth/signup/flow` entry pause). */
+    signup?: TAtscriptAnnotatedType;
+  };
 }
 /**
- * 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).
+ * Fully-resolved view used by the workflow at runtime — every nested group
+ * is populated by the (future) `mergeAuthOpts` so step bodies can read
+ * `this.opts.<group>.<field>` without optional chaining. The two
+ * auto-login booleans become required after defaults are applied.
  */
-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;
+interface ResolvedAuthWorkflowOpts {
+  autoLoginOnInvite: boolean;
+  autoLoginOnRecover: boolean;
+  mfa: {
+    pincodeLength: number;
+    pincodeTtlMs: number;
+    pincodeResendTimeoutMs: number;
+    pincodeMaxAttempts: number;
+  };
+  recoveryStateTtlMs: number;
+  loginUrl: string;
+  totpIssuer: string;
+  deviceTrust: {
+    cookieName: string;
+    ttlMs: number;
+    bindsTo: "cookie" | "cookie+ip";
+  };
+  forms: {
+    loginCredentials: TAtscriptAnnotatedType;
+    invite: TAtscriptAnnotatedType;
+    recoveryEmailIdentifier: TAtscriptAnnotatedType;
+    askEmail: TAtscriptAnnotatedType;
+    askPhone: TAtscriptAnnotatedType;
+    enrollPickMethod: TAtscriptAnnotatedType;
+    enrollAddress: TAtscriptAnnotatedType;
+    enrollTotpQr: TAtscriptAnnotatedType;
+    enrollConfirm: TAtscriptAnnotatedType;
+    manageMfa: TAtscriptAnnotatedType;
+    removeMfaConfirm: TAtscriptAnnotatedType;
+    passwordReauth: TAtscriptAnnotatedType;
+    select2fa: TAtscriptAnnotatedType;
+    mfaCode: TAtscriptAnnotatedType;
+    pincode: TAtscriptAnnotatedType;
+    setPassword: TAtscriptAnnotatedType;
+    changePassword: TAtscriptAnnotatedType;
+    proveControl: TAtscriptAnnotatedType;
+    proveControlOtp: TAtscriptAnnotatedType;
+    termsBump: TAtscriptAnnotatedType;
+    concurrencyLimit: TAtscriptAnnotatedType;
+    recoveryPincode: TAtscriptAnnotatedType;
+    signup: TAtscriptAnnotatedType;
   };
-  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. */
-  methodName: string;
-  masked: string;
-  isDefault: boolean;
 }
+//#endregion
+//#region src/workflow/auth-workflow.d.ts
 /**
- * Unified payload for `deliver()` — discriminated by `channel`. `kind`
- * narrows further to the template the consumer should render. The two
- * channels do not share a fields set (email carries `url` for magic links
- * and `expiresAt`; SMS always carries a pincode + `ttlMs`).
+ * Unified outbound-dispatch payload. Customers override `deliver(payload)` on
+ * the `AuthWorkflow` subclass to route by `kind` (per-purpose templates) and
+ * `channel` (email vs SMS). Replaces the prior workflow-specific deliver
+ * payloads which carried slightly different field sets per call site.
  */
-interface DeliverEmail {
+type AuthDeliveryPayload = {
+  kind: "mfa-pincode";
+  channel: "sms" | "email";
+  recipient: string;
+  code: string;
+  expiresInMs: number;
+} | {
+  kind: "recovery-pincode";
+  channel: "sms" | "email";
+  recipient: string;
+  code: string;
+  expiresInMs: number;
+} | {
+  kind: "signup-pincode";
   channel: "email";
-  /** Template kind — discriminator the consumer uses to pick which email template to render. */
-  kind: AuthEmailKind$1;
   recipient: string;
-  /** Numeric pincode (set for `*.pincode` kinds). */
-  code?: string;
-  /** Magic-link URL (set for `*.magicLink` kinds). */
-  url?: string;
-  /** Absolute expiry timestamp for the link/code (ms epoch). */
-  expiresAt?: number;
-  /** Associated user id, when known. */
-  userId?: string;
-  /** Extra context (e.g. `roles` for invite emails, IP/UA for notifyNewDevice). */
-  metadata?: Record<string, unknown>;
-}
-interface DeliverSms {
-  channel: "sms";
-  kind: AuthSmsKind$1;
+  code: string;
+  expiresInMs: number;
+} | {
+  kind: "enroll-pincode";
+  channel: "sms" | "email";
   recipient: string;
-  /** SMS always carries a pincode — that's the only thing SMS gets used for in this lib. */
   code: string;
-  ttlMs?: number;
-  userId?: string;
-}
-type DeliverPayload = DeliverEmail | DeliverSms;
-declare class LoginWorkflow extends AuthWorkflowBase {
-  protected readonly opts: ResolvedLoginWorkflowOpts;
+  expiresInMs: number;
+} | {
+  kind: "invite-link";
+  channel: "email";
+  recipient: string;
+  url: string;
+  expiresInMs: number;
+} | {
+  kind: "new-device-notice";
+  channel: "email";
+  recipient: string;
+  deviceLabel?: string;
+  loginAt: number;
+};
+/**
+ * Top-level `UserCredentials` keys that workflow-collected profile payloads
+ * MUST NEVER carry through to persistence. The server sets these out-of-band
+ * (admin-supplied `ctx.admin?.roles`, password-set step, account activation,
+ * MFA enrolment elsewhere). If the consumer's `.as` profile form mistakenly
+ * declares one — or an attacker submits one as an extra field — the strip
+ * applied at the workflow step blocks shadowing.
+ */
+declare const RESERVED_USER_KEYS: ReadonlySet<string>;
+/**
+ * Return a shallow copy of `profile` with `RESERVED_USER_KEYS` removed.
+ * Does not mutate the input.
+ */
+declare function stripReservedUserKeys(profile: Record<string, unknown>): Record<string, unknown>;
+/** Trim + de-duplicate role identifiers submitted via the admin invite form. */
+declare function parseInviteRoles(input?: string[]): string[];
+/**
+ * Single source of truth for the "this invite was already accepted" finish
+ * envelope. Used by both `idempotent-redirect` (in-workflow) and by
+ * `AuthController.invitePostRedemption` (side route reached when the wf
+ * state store has evicted the finished row and re-resume hits 410).
+ *
+ * Secondary "Request a new invite" option is gated on
+ * `alreadyAcceptedRedirectUrl` being non-empty — mirrors how the resolver
+ * defaults it, but lets consumers blank it to suppress the secondary button.
+ */
+declare function buildInviteAlreadyAcceptedEnvelope(opts: {
+  loginUrl: string;
+  alreadyAcceptedRedirectUrl: string;
+}): FinishWfOpts;
+declare class AuthWorkflow {
+  protected readonly opts: ResolvedAuthWorkflowOpts;
   protected readonly users: UserService;
   protected readonly auth: AuthCredential;
-  protected readonly authOpts: AuthOpts;
   protected readonly consentStore: ConsentStore;
-  constructor(opts: LoginWorkflowOpts, users: UserService, auth: AuthCredential, authOpts: AuthOpts, consentStore: ConsentStore);
+  constructor(opts: Partial<AuthWorkflowOpts>, users: UserService, auth: AuthCredential, consentStore: ConsentStore);
   /**
-   * Dispatch an email or SMS event. Default throws — consumers MUST override
-   * 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.
+   * Unified outbound dispatch hook for direct synchronous deliveries
+   * (MFA / recovery / enrollment pincodes, new-device notices). NOT used for
+   * resume-token flows — the invite magic link is emitted via the wf engine's
+   * `outletEmail()` primitive (pause-and-resume), since the resume URL is
+   * minted by the engine AFTER the step yields and is not knowable here.
+   * Default is a no-op — customer overrides wire concrete senders. Stays
+   * sync-friendly: the default `void` preserves the engine's sync fast path.
    */
-  protected deliver(_payload: DeliverPayload): Promise<void>;
+  protected deliver(_payload: AuthDeliveryPayload): void | Promise<void>;
   /**
-   * Emit an audit event. Default: no-op. Consumers override to fan out to
-   * their audit sink (DB table, log file, Kafka topic, …).
+   * Return the list of selectable role identifiers for the admin invite form.
+   * Mirrors the prior `InviteWorkflow.getAvailableRoles()` consumer hook —
+   * `undefined` (default) means no whitelist is enforced. Read by
+   * `prepareAvailableRoles`.
    */
-  protected audit(_event: AuditEvent): Promise<void>;
+  protected getAvailableRoles(): Promise<string[] | undefined> | string[] | undefined;
   /**
-   * Verify whether a presented trust-cookie token belongs to `userId` and is
-   * still valid. Default: delegates to `UserService.verifyTrustedDevice`
-   * (HMAC + persisted record + expiry + IP-binding). Override to use a
-   * different trust backend.
+   * Build the extras dict merged into the freshly-created user row. Runs for
+   * EVERY new-account path: password-signup and invite-accept merge it at
+   * `createUser` time (the `create-user` step), and a first-time federated
+   * login applies it from `sso-callback` (post-create `users.update`). Default:
+   * `{}`. Override to populate e.g. a required `tenantId` from request context.
+   *
+   * `email` is optional: a federated profile can carry no email, so overrides
+   * must tolerate `email === undefined`.
    */
-  protected loadTrustedDevice(userId: string, token: string, ip?: string): Promise<boolean>;
+  protected prepareUser(_input: {
+    email?: string;
+    roles: string[];
+    invitedBy?: string;
+  }): Promise<Record<string, unknown>> | Record<string, unknown>;
   /**
-   * Persist a freshly-issued trust record. Default: delegates to
-   * `UserService.addTrustedDevice` — the record is appended to the user's
-   * `trustedDevices` array on the user store. `userId` is the username the
-   * record belongs to (passed alongside since `TrustedDeviceRecord` itself
-   * carries no user identifier).
+   * Derive roles server-side from the admin-form payload (e.g. AD lookup).
+   * Result is set-unioned with admin-supplied roles by `infer-roles`.
+   * Default: `[]`.
    */
-  protected storeTrustedDevice(userId: string, record: TrustedDeviceRecord): Promise<void>;
+  protected inferAdminRoles(_input: {
+    email: string;
+  }): Promise<string[]> | string[];
   /**
-   * Revoke a trust record. Default: delegates to
-   * `UserService.revokeTrustedDevice`. Currently unused by the workflow's own
-   * happy path but exposed so consumers can call it from their own "sign out
-   * everywhere" flows for symmetry with `storeTrustedDevice`.
+   * 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.
    */
-  protected revokeTrustedDevice(userId: string, token: string): Promise<void>;
+  protected duplicateInviteCheck(input: {
+    email: string;
+    existingUser: UserCredentials | null;
+  }): Promise<"allow" | "reject"> | "allow" | "reject";
   /**
-   * Mint a new device-trust record + cookie value. Default: delegates to
-   * `UserService.issueTrustedDevice` — produces an HMAC-signed token bound to
-   * `userId` (+ `ip` when `bindsTo === 'cookie+ip'`). Consumers running
-   * multiple instances typically override `loadTrustedDevice`/
-   * `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).
+   * Implements the "log out other sessions" branch of `sessionPolicy.concurrencyLimit`.
+   * Default revokes every existing session via `auth.revokeAllForUser` — which is
+   * mandatory on every store (stateless ones use a per-user epoch sentinel), so the
+   * kick works without an override. Runs BEFORE `issue`, so the session about to be
+   * minted survives. Override to scope the revoke (e.g. keep the current device).
+   */
+  protected logoutOtherSessions(username: string): Promise<void>;
+  /**
+   * Return the number of active (non-revoked, non-expired) sessions for the user,
+   * used by the concurrency-limit gate. Default delegates to `auth.listForUser`,
+   * which counts access-kind credentials and returns `[]` for stateless stores
+   * (no round-trip) — so the count is real when the store can enumerate and `0`
+   * (gate disabled) when it can't. Only consulted when `resolveSessionPolicy`
+   * declared a `concurrencyLimit`. Override for a custom session source.
+   */
+  protected loadActiveSessionsCount(username: string): Promise<number>;
+  /**
+   * Resolves the post-login redirect URL. Default reads `finalize.redirect`:
+   * `false` / `null` → no redirect; `'home'` → `/`; `'referer'` → request
+   * `Referer` header (undefined when absent).
+   */
+  protected resolveRedirect(ctx: AuthWfCtx): string | undefined;
+  protected oauthRuntime(): Promise<OAuthRuntime>;
+  /**
+   * Resolve the {@link AuthorizeRuntime} (the pending-authorization + auth-code
+   * stores) for the `mint-authz-code` terminal — same `instantiate` path as
+   * {@link oauthRuntime}, reached ONLY when a login was started from
+   * `/auth/authorize` (`ctx.authz` set). Override in a unit test to inject fakes.
+   */
+  protected authorizeRuntime(): Promise<AuthorizeRuntime>;
+  /**
+   * Redirect target for a federated-login FAILURE terminal — provider denial,
+   * invalid/expired state, CSRF mismatch, missing transaction, exchange
+   * failure, `denied` / `needs-link` resolution, or a locked/inactive account.
+   * Benign + generic: it MUST NOT reveal WHICH check tripped (no
+   * tamper-vs-expiry oracle — see invariant #5). Default: the login URL with a
+   * single generic `?error=oauth`. Override to route to a dedicated SPA error
+   * page (still without leaking the reason).
+   */
+  protected resolveOAuthErrorRedirect(_ctx: AuthWfCtx, _reason: string): string;
+  /**
+   * Leg 1 of federated login: turn an `sso-<id>` click on the login form into a
+   * redirect to the provider, then END the login wf. STATELESS — no flow store:
+   * a fresh non-secret `seed` is minted, the PKCE verifier + OIDC nonce are
+   * DERIVED from it (`registry.deriveSeededPkce`), the `challenge`/`nonce` build
+   * the authorize URL, and the seed rides in BOTH the signed `state` and a Lax
+   * double-submit CSRF cookie. The callback re-derives the identical verifier
+   * from `state.random` to redeem the `code` (see `sso-callback`) — so nothing
+   * secret is ever in the URL and no server-side transaction is persisted.
    *
-   * 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).
+   * The CSRF cookie is attached to the FINISH ENVELOPE's `cookies` (which the
+   * wf-trigger outlet writes onto the real HTTP response), NOT via
+   * `useResponse().setCookie` — the outlet builds its response from the
+   * `WfFinished` envelope and ignores response-context cookies. Same mechanism
+   * `issue` uses for the session cookie. The resume is a same-origin XHR, so the
+   * `Set-Cookie` is stored before `AsWfForm` follows the redirect.
    */
-  protected resolveProfile(_ctx: LoginWfCtx): {
-    required: boolean;
-  } | Promise<{
-    required: boolean;
-  }>;
+  protected beginSso(providerId: string, authzHandle?: string): Promise<void>;
   /**
    * 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.
+   * magic-link / SSO providers). Reached from login.flow.
+   */
+  protected resolveAlternateCredentials(_ctx: AuthWfCtx): NonNullable<AuthWfCtx["alternateCredentials"]> | Promise<NonNullable<AuthWfCtx["alternateCredentials"]>>;
+  /**
+   * Resolve the device-trust policy. Infrastructure (cookieName / ttlMs /
+   * bindsTo) lives on `this.opts.deviceTrust`. Reached from login.flow.
    */
-  protected resolveAlternateCredentials(_ctx: LoginWfCtx): NonNullable<LoginWfCtx["alternateCredentials"]> | Promise<NonNullable<LoginWfCtx["alternateCredentials"]>>;
+  protected resolveDeviceTrust(_ctx: AuthWfCtx): NonNullable<AuthWfCtx["deviceTrust"]> | Promise<NonNullable<AuthWfCtx["deviceTrust"]>>;
   /**
-   * 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.
+   * Resolve the channel-enrolment policy (ensureEmail / ensurePhone).
+   * Reached from login.flow.
    */
-  protected resolveDeviceTrust(_ctx: LoginWfCtx): NonNullable<LoginWfCtx["deviceTrust"]> | Promise<NonNullable<LoginWfCtx["deviceTrust"]>>;
+  protected resolveEnrollment(_ctx: AuthWfCtx): NonNullable<AuthWfCtx["enrollment"]> | Promise<NonNullable<AuthWfCtx["enrollment"]>>;
   /**
-   * Resolve the channel-enrollment policy (ensureEmail / ensurePhone gates).
-   * Override to force email/phone capture per user segment. Sync/async friendly.
+   * Resolve the finalize policy. Reached from login.flow. `auditLogin` is
+   * dropped from the shape per §2 — audit moved out of the workflow layer.
    */
-  protected resolveEnrollment(_ctx: LoginWfCtx): NonNullable<LoginWfCtx["enrollment"]> | Promise<NonNullable<LoginWfCtx["enrollment"]>>;
+  protected resolveFinalize(_ctx: AuthWfCtx): NonNullable<AuthWfCtx["finalize"]> | Promise<NonNullable<AuthWfCtx["finalize"]>>;
   /**
-   * 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.
+   * Resolve the login-time guards policy (passwordInitial / passwordExpiry /
+   * emailVerifiedRequired). Reached from login.flow.
    */
-  protected resolveFinalize(_ctx: LoginWfCtx): NonNullable<LoginWfCtx["finalize"]> | Promise<NonNullable<LoginWfCtx["finalize"]>>;
+  protected resolveGuards(_ctx: AuthWfCtx): NonNullable<AuthWfCtx["guards"]> | Promise<NonNullable<AuthWfCtx["guards"]>>;
   /**
-   * Resolve the guards policy (passwordInitial / passwordExpiry /
-   * emailVerifiedRequired). Override per-tenant to tighten or loosen the
-   * post-credentials gates. Sync/async friendly.
+   * Resolve the session-policy (concurrency limit). Reached from login.flow.
+   */
+  protected resolveSessionPolicy(_ctx: AuthWfCtx): NonNullable<AuthWfCtx["sessionPolicy"]> | Promise<NonNullable<AuthWfCtx["sessionPolicy"]>>;
+  /**
+   * Resolve the authenticated change-password policy. Reached from
+   * change-password.flow only. Default revokes the user's other sessions on a
+   * successful change (OWASP Session Management) and applies NO rate limit —
+   * current-password re-entry (enforced by `UserService.changePassword`) is the
+   * primary protection, not throttling. Customers override to add a min-interval
+   * (`rateLimit.minIntervalMs`) or to keep other sessions alive.
    *
-   * The `passwordExpiry` flag (default `true`) is the per-tenant escape
-   * hatch for rotation policy: flip to `false` for SSO-only tenants
-   * where the IdP owns rotation, or for service accounts where forced
-   * change would break automation. When `true`, the `credentials` step
-   * consults `UserService.isPasswordExpired(user)` — which is itself
-   * gated on `config.password.maxAgeMs`, so an unset `maxAgeMs` already
-   * disables expiry independent of this flag.
-   */
-  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.
+   * Whether the flow may be STARTED at all is governed by arbac on the trigger
+   * route (deny the `change-password` action to forbid it for SSO-only orgs) —
+   * there is deliberately no on/off flag here.
+   */
+  protected resolveChangePasswordPolicy(_ctx: AuthWfCtx): NonNullable<AuthWfCtx["changePassword"]> | Promise<NonNullable<AuthWfCtx["changePassword"]>>;
+  /**
+   * Resolve the self-signup policy. Reached from signup.flow's `init-signup`.
+   * Default `allowSignup: false` — invite-only is the safe default (mirrors
+   * `resolveAlternateCredentials().signup`); a deployment that wants open
+   * self-serve overrides this to `true` (and flips the login form's `signup`
+   * alt-action on via `resolveAlternateCredentials`). `collectUsername: false`
+   * means `username := email`; override + replace `opts.forms.signup` to
+   * collect a distinct username. There is intentionally no rate-limit field
+   * here yet — override the `signup-form` step (or front it with a captcha /
+   * IP gate) for abuse control; the OTP resend cooldown already bounds repeat
+   * sends per run.
+   */
+  protected resolveSignupPolicy(_ctx: AuthWfCtx): NonNullable<AuthWfCtx["signup"]> | Promise<NonNullable<AuthWfCtx["signup"]>>;
+  /**
+   * Resolve the failed-login lockout posture (admin-only / self-service /
+   * temporary — see `AuthWfLockoutMode`). Reached from login.flow (decides the
+   * lock duration passed to `users.login` / `users.verifyMfa` on a threshold
+   * trip) and recovery.flow (decides whether `unlock-account` runs after a
+   * reset). Default `temporary` preserves the prior auto-expiry behavior.
+   * Customers override per-tenant / per-user (e.g. force `admin-only` for
+   * privileged accounts).
+   */
+  protected resolveLockout(_ctx: AuthWfCtx): NonNullable<AuthWfCtx["lockout"]> | Promise<NonNullable<AuthWfCtx["lockout"]>>;
+  /**
+   * Resolve the unified MFA policy. Replaces login's hardcoded defaults +
+   * invite's `{ issuer }` resolver. Issuer is sourced from
+   * `this.opts.totpIssuer` so per-app TOTP labels remain a single knob.
+   * Reached from login.flow + invite.start.
+   */
+  protected resolveMfaPolicy(_ctx: AuthWfCtx): NonNullable<AuthWfCtx["mfaPolicy"]> | Promise<NonNullable<AuthWfCtx["mfaPolicy"]>>;
+  /**
+   * Transports the user may NOT change or remove via the manage-MFA flow.
+   * Default: none — every factor is freely manageable. Reached from
+   * `auth/add-mfa/flow` (`prepare-locked-mfa-transports`).
    *
-   * 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.
+   * Override to forbid changing a factor whose value IS a login handle — e.g.
+   * the MFA `email` equals the `@aooth.user.email` handle, so letting the user
+   * swap it here would desync identity. A typical override loads the user and
+   * compares each enrolled channel value against the boot-resolved handle
+   * fields (`getAoothUserHandleSpec(...).emailField` / `.phoneField`):
    *
-   * 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;
-  /**
-   * 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.
+   * ```ts
+   * protected async resolveLockedMfaTransports(ctx: AuthWfCtx): Promise<MfaTransport[]> {
+   *   const user = await this.users.getUser(ctx.subject!);
+   *   const locked: MfaTransport[] = [];
+   *   const email = user.mfa?.methods?.find((m) => m.name === "email" && m.confirmed);
+   *   if (email && email.value === (user as { email?: string }).email) locked.push("email");
+   *   return locked;
+   * }
+   * ```
+   */
+  protected resolveLockedMfaTransports(_ctx: AuthWfCtx): MfaTransport[] | Promise<MfaTransport[]>;
+  /**
+   * Resolve the channel-OTP disclosure copy rendered beneath the email/phone
+   * input on `AskEmailForm` / `AskPhoneForm`. Reached from login.flow Phase 3.
+   * Default returns a TCPA / PECR / CASL / GDPR-safe English paragraph that is
+   * GENERIC per channel (no target templated in — the user hasn't submitted
+   * yet at ask-time).
+   */
+  protected resolveOtpDisclosure(_ctx: AuthWfCtx, channel: "email" | "phone"): string | Promise<string>;
+  /**
+   * Resolve whether to require an additional MFA round (risk step-up).
+   * Default never requires an extra factor.
+   */
+  protected resolveRiskStepUp(_ctx: AuthWfCtx): Promise<{
+    require: boolean;
+    reason?: string;
+  }>;
+  /**
+   * Resolve the recovery URL targeted by the `forgotPassword` alt-action on
+   * login's credentials form. Receives whatever the user typed into the
+   * username field so the recovery page can pre-fill it.
    *
-   * 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).
-   */
-  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;
+   * Sync return type only — the caller (`credentials` @Step alt-action
+   * handler) uses the URL inline.
+   */
+  protected resolveRecoveryUrl(username: string | undefined, alt: AuthWfAltCredsPolicy): string;
   /**
-   * 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 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>;
+   * Resolve the admin-form policy (whether to collect roles on the invite
+   * admin form). Reached from invite.start admin phase.
+   */
+  protected resolveAdminForm(_ctx: AuthWfCtx): NonNullable<AuthWfCtx["adminForm"]> | Promise<NonNullable<AuthWfCtx["adminForm"]>>;
   /**
-   * 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(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 +
-   * hyphen-grouped — `MfaCodeForm` is digits-only and rejects backup codes
-   * produced by `UserService.generateBackupCodes`).
-   */
-  private handleBackupCode;
-  /**
-   * 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 | 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>;
-  /**
-   * 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.
-   */
-  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
-   * tenants the user belongs to.
-   */
-  protected loadTenants(_username: string): Promise<Array<{
-    id: string;
-    name: string;
-  }>>;
-  personaSelect(ctx: LoginWfCtx): Promise<unknown>;
-  /**
-   * Resolves the user's available personas. Default: empty array. Consumers
-   * who enable `multiContext.personaSelect` must override this.
-   */
-  protected loadPersonas(_username: string): Promise<Array<{
-    id: string;
-    label: string;
-  }>>;
-  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>;
+   * Resolve the invite accept-tail policy. Reached from invite.start accept
+   * phase. `loginUrl` defaults to `this.opts.loginUrl`. Note: today's
+   * `freshLoginRequired` field is GONE — the auto-login choice is the static
+   * `AuthWorkflowOpts.autoLoginOnInvite` boolean (per §2 decision).
+   */
+  protected resolveAccept(_ctx: AuthWfCtx): NonNullable<AuthWfCtx["accept"]> | Promise<NonNullable<AuthWfCtx["accept"]>>;
   /**
-   * Implements the "log out other sessions" branch of `sessionPolicy.concurrencyLimit`.
-   * Default: no-op. Consumers override to revoke sessions in their auth store.
+   * Resolve the recovery post-reset policy. Reached from recovery.flow.
+   * `freshLoginRequired` REMOVED — the auto-login choice is the static
+   * `AuthWorkflowOpts.autoLoginOnRecover` boolean (per §2 decision).
    */
-  protected logoutOtherSessions(_username: string): Promise<void>;
-  riskStepUp(ctx: LoginWfCtx): Promise<undefined>;
+  protected resolvePostReset(_ctx: AuthWfCtx): NonNullable<AuthWfCtx["postReset"]> | Promise<NonNullable<AuthWfCtx["postReset"]>>;
   /**
-   * 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.
+   * Resolve the recovery alt-actions policy (whether `backToLogin` is offered
+   * on the recovery forms). Renamed from the prior `resolveAltActions` to
+   * disambiguate from login's `resolveAlternateCredentials` (different
+   * concept). Reached from recovery.flow.
    */
-  protected resolveRiskStepUp(_ctx: LoginWfCtx): Promise<{
-    require: boolean;
-    reason?: string;
+  protected resolveRecoveryAltActions(_ctx: AuthWfCtx): NonNullable<AuthWfCtx["recoveryAltActions"]> | Promise<NonNullable<AuthWfCtx["recoveryAltActions"]>>;
+  /**
+   * Pick the form to render for the unified pincode pair. Default routes to
+   * `opts.forms.pincode` (MFA alt-actions) when `ctx.mfa?.method` is set;
+   * otherwise `opts.forms.recoveryPincode` (recovery alt-actions).
+   */
+  protected resolvePincodeForm(ctx: AuthWfCtx): TAtscriptAnnotatedType;
+  /**
+   * Pick the raw recipient + channel for pincode delivery. Default sources
+   * the address from the user's enrolled MFA method (when `ctx.mfa.method` is
+   * set) or from `ctx.email` (recovery path). Loads the user to read the raw
+   * method `value` — the `ctx.mfa.enrolledMethods` summary carries only the
+   * MASKED form, which is for display, never for delivery.
+   */
+  protected resolvePincodeTarget(ctx: AuthWfCtx): {
+    address: string;
+    channel: "sms" | "email";
+  } | Promise<{
+    address: string;
+    channel: "sms" | "email";
   }>;
-  issue(ctx: LoginWfCtx): Promise<void>;
-  auditLogin(ctx: LoginWfCtx): Promise<undefined>;
-  notifyNewDevice(ctx: LoginWfCtx): Promise<undefined>;
-  redirect(ctx: LoginWfCtx): undefined | Promise<undefined>;
-  /**
-   * Resolves the post-login redirect URL. Default reads
-   * `finalize.redirect`: `false` / `null` (the default) → no redirect, the
-   * `issue` step's data response stands (typical for SPAs/API clients);
-   * `'home'` → `/`; `'referer'` → request `Referer` header (undefined when
-   * absent, falling back to the data response).
+  /**
+   * Resolve the recovery OTP `{ address, channel }` for the chosen delivery
+   * `source`.
+   *
+   * - `"typed"` (M1): the address is the typed recovery identifier (`ctx.email`)
+   *   — identifier == destination, so no cross-account redirect — and the
+   *   channel comes from `resolveRecoveryChannel` (identifier-shape inference).
+   * - `"registered"` (M2): the address is read off a confirmed MFA method on the
+   *   row (`selectRecoveryRegisteredMethod`) and the channel is that method's own
+   *   kind. The user only typed an account identifier; the destination is a
+   *   pre-verified channel they already control, so this also can't redirect
+   *   cross-account. `request`'s M2 guard normally generic-finishes any row with
+   *   no deliverable method up front; if the method is deleted in the narrow
+   *   window between that guard and this send (e.g. on a resend), this throws
+   *   `RecoveryMethodUnavailableError`, which `pincode-send` degrades to the
+   *   same generic finish — never a distinguishable 500.
+   */
+  private recoveryPincodeTarget;
+  /**
+   * Recovery OTP delivery channel. The address is ALWAYS the typed recovery
+   * identifier (`ctx.email`) — symmetric with how email recovery already works:
+   * the OTP goes to the value the user typed, which is the handle that resolved
+   * the account (`findByHandle`), so identifier == destination and there is no
+   * cross-account redirect. Default `"email"`. A deployment whose recovery form
+   * accepts a phone overrides this to route SMS (e.g. infer from the identifier
+   * shape) — see the demo's `DemoAuthWorkflow`. Recovery picks ONE channel per
+   * run, so the single `resendAllowedAt` cooldown gate still suffices.
+   */
+  protected resolveRecoveryChannel(_ctx: AuthWfCtx): "email" | "sms" | Promise<"email" | "sms">;
+  /**
+   * Recovery OTP delivery model. Two options:
    *
-   * 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.
+   * - `"typed"` (default — M1): the OTP goes to the recovery identifier the user
+   *   types. Identifier == destination, so there is no cross-account redirect;
+   *   `resolveRecoveryChannel` picks email vs SMS from the identifier shape.
+   * - `"registered"` (M2): the user enters only an account identifier (e.g. a
+   *   username) and the OTP is delivered to a channel **already verified on the
+   *   row** — `selectRecoveryRegisteredMethod` picks the confirmed MFA method;
+   *   the destination is never taken from user input, so it cannot be redirected
+   *   to an attacker-controlled address. A row with no deliverable confirmed
+   *   method finishes with the generic anti-enumeration envelope (see `request`).
+   *
+   * Consulted inline by `request` (no-method guard) and `recoveryPincodeTarget`
+   * — no `prepare-*` step, mirroring `resolveRecoveryChannel`. Override to arm
+   * M2 (per-tenant / per-variant); see the demo's `DemoAuthWorkflow`.
+   */
+  protected resolveRecoveryDeliverySource(_ctx: AuthWfCtx): "typed" | "registered" | Promise<"typed" | "registered">;
+  /**
+   * Pick the confirmed MFA method a registered-channel recovery (M2) delivers
+   * its OTP to. Prefers a confirmed SMS method, then a confirmed email method —
+   * phone-recovery-first. TOTP carries no deliverable address and is skipped.
+   * Returns `null` when the row has no deliverable confirmed method; the caller
+   * turns that into the anti-enumeration generic finish. Stays sync (operates on
+   * an already-loaded row); override to change the selection policy (e.g. honour
+   * the user's `mfa.defaultMethod`).
+   */
+  protected selectRecoveryRegisteredMethod(user: UserCredentials): MfaMethod | null;
+  /**
+   * Decide which login-handle column a freshly-confirmed channel should be
+   * promoted into — so a verified email/phone becomes a login + recovery
+   * handle (`findByHandle`) automatically. Returns the target field name, or
+   * `undefined` to NOT promote (the default).
+   *
+   * Default is OFF: the handle columns are declared via `@aooth.user.*`
+   * annotations on the consumer's concrete model and resolved ONCE at boot
+   * (`@aooth/arbac-moost`'s `getAoothUserHandleSpec`) — `AuthWorkflow` holds no
+   * handle to that model and stays off the per-request reflection path. A
+   * deployment turns promotion ON by overriding this to return the
+   * boot-resolved `emailField` / `phoneField` for the channel — see the demo's
+   * `DemoAuthWorkflow`. `channel` is the wire protocol (`'email'` | `'sms'`),
+   * matching `resolveOtpDisclosure` / the MFA transport.
    */
-  protected 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 {
+  protected resolvePromoteHandleField(_ctx: AuthWfCtx, _channel: "email" | "sms"): string | undefined | Promise<string | undefined>;
   /**
-   * Replaceable form schemas. Each field defaults to the corresponding
-   * `.as` form shipped under `@aooth/auth-moost/atscript/models`.
+   * Route a form alt-action click to a canonical outcome. Defaults match the
+   * action ids the bundled `PincodeForm` declares; customers override per
+   * form when adding new actions or remapping the canonical ones.
    */
-  forms?: {
-    emailIdentifier?: TAtscriptAnnotatedType;
-    pincode?: TAtscriptAnnotatedType;
-    recoveryFactor?: TAtscriptAnnotatedType;
-    recoveryModeSelect?: TAtscriptAnnotatedType;
-    setPassword?: TAtscriptAnnotatedType;
-  };
-}
-/**
- * Fully-resolved view used by the workflow at runtime — every nested group is
- * always populated by `mergeRecoveryOpts`, so step bodies can read
- * `this.opts.<group>.<flag>` directly without optional chaining.
- */
-interface ResolvedRecoveryWorkflowOpts {
-  forms: {
-    emailIdentifier: TAtscriptAnnotatedType;
-    pincode: TAtscriptAnnotatedType;
-    recoveryFactor: TAtscriptAnnotatedType;
-    recoveryModeSelect: TAtscriptAnnotatedType;
-    setPassword: TAtscriptAnnotatedType;
-  };
-}
-/**
- * Deep-merge defaults with the user-supplied nested pojo. Each group has its
- * own `{ ...defaults, ...input }` line — small enough that pulling in lodash
- * would be silly.
- */
-declare function mergeRecoveryOpts(opts?: RecoveryWorkflowOpts): ResolvedRecoveryWorkflowOpts;
-//#endregion
-//#region src/workflows/recovery.workflow.d.ts
-interface RecoveryWfCtx {
-  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;
+  protected resolvePincodeAltAction(_ctx: AuthWfCtx, action: string): "resend" | "exit" | "useDifferentMethod" | undefined;
+  /**
+   * Asserts `ctx.subject` is populated. Throws `HttpError(500)` on miss;
+   * narrows `subject` to `string` for the caller. Ported from
+   * `AuthWorkflowBase` since the unified class no longer extends it.
+   */
+  protected requireSubject<T extends {
+    subject?: string;
+  }>(ctx: T): asserts ctx is T & {
+    subject: string;
   };
-  email?: string;
-  username?: string;
-  selectedMode?: "magicLink" | "otp";
-  /** 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;
-  pin?: string;
-  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.
+   * Project the internal ctx state onto `ctx.public` — the ONLY top-level
+   * key whitelisted on form schemas (via `@wf.context.pass 'public'`).
+   * Mirrors `AuthWfPublicState` field-for-field; intentionally drops
+   * internal-only fields (`pincode.channelCooldowns`, `mfa.saveAsDefault` /
+   * `mfa.current` / `mfa.ignoreDefault`, `trust.deviceTrustToken`,
+   * `channel.phone` / `channel.emailConfirmed`, `mfaEnroll.address`, …)
+   * so they cannot leak to the wire.
+   *
+   * Called via `throwPublic` immediately before every `requireInput`-style
+   * pause so the FE always reads a fresh projection of the post-step ctx.
+   */
+  protected populatePublic(ctx: AuthWfCtx): void;
+  /**
+   * Wrap `wf.requireInput(opts)` so `ctx.public` is freshly projected
+   * before the pause throws. Every `throw wf.requireInput(...)` in the
+   * codebase routes through this so no pause can ship a stale public
+   * surface (and no contributor can accidentally skip the projection).
+   */
+  protected throwPublic<T>(ctx: AuthWfCtx, wf: {
+    requireInput(opts?: T): unknown;
+  }, opts?: T): unknown;
+  /**
+   * Drop-in wrapper around `useAtscriptWf(type)` that projects `ctx.public`
+   * BEFORE returning the form handle. Steps that pause implicitly — via
+   * `wf.resolveInput()` throwing on missing input or `wf.resolveAction()`
+   * throwing on an unknown action — bypass `throwPublic`, so without this
+   * wrapper the implicit-pause path would ship a stale (or missing)
+   * `ctx.public`. Every `useAtscriptWf(...)` call in the workflow routes
+   * through this so both pause flavors snapshot the same fresh projection.
+   */
+  protected useAtscriptWfPublic(ctx: AuthWfCtx, type: Parameters<typeof useAtscriptWf>[0]): ReturnType<typeof useAtscriptWf>;
+  /** Translate `CAS_EXHAUSTED` UserAuthError to 409 Conflict (OCC contract). */
+  protected withStoreErrorTranslation<T>(op: () => Promise<T>): Promise<T>;
+  /** Mint a numeric pincode + stash it onto ctx. Returns the plain code. */
+  protected mintPin(ctx: {
+    pin?: string;
+    pinExpire?: number;
+    pinAttempts?: number;
+  }, length: number, ttlMs: number): string;
+  /**
+   * Verify a submitted pincode against `ctx.pin`. Returns an error map (with
+   * the message keyed under `code` so it renders inline on the code input) or
+   * `null` on success. Brute-force protection: wrong-code attempts increment
+   * `ctx.pinAttempts`; on the `pincodeMaxAttempts`-th miss the code is
+   * invalidated (clears `pin` + `pinExpire` + `pinAttempts`) and the returned
+   * error tells the user to request a fresh code. Without this gate the user
+   * could probe the full 10^pincodeLength space inside one `pincodeTtlMs`
+   * window.
+   */
+  protected verifyPin(ctx: {
+    pin?: string;
+    pinExpire?: number;
+    pinAttempts?: number;
+  }, submitted: string | undefined): {
+    code: string;
+  } | null;
+  /**
+   * Validate + stash inline-consent fields submitted on a carrier form.
+   * SECURITY: silently drops unknown ids (audit-grade defense — see base
+   * class docstring).
+   *
+   * Does NOT persist — persistence is deferred to `persist-consents` at the
+   * workflow tail, AFTER channel/identity verification. Staging the decision
+   * here (without persisting) lets downstream carrier forms hide the consent
+   * block via `decidedAt` while the wf engine still owns the rollback
+   * boundary: if the user abandons before the verification step succeeds,
+   * the consent record never lands in the durable store.
+   */
+  protected processInlineConsent(ctx: AuthWfCtx, input: {
+    consents?: string[];
+  }, wf: {
+    requireInput(opts?: {
+      errors?: Record<string, string>;
+      formMessage?: string;
+    }): unknown;
+  }): void;
+  /**
+   * Mask a raw address for UI display. The masked string is for
+   * `ctx.pincode.sentTo`; the raw value is what gets passed to `deliver`.
+   */
+  protected maskAddress(address: string, channel: "sms" | "email"): string;
+  /** Narrow `MfaMethod.name` to the canonical MfaTransport union. */
+  protected mfaKindOf(methodName: string): MfaTransport | null;
+  /**
+   * Send an enrolment pincode and stamp `ctx.pincode.sentTo` with the masked
+   * recipient. Shared by `enrollAddress` (initial dispatch) and the resend
+   * path inside `enrollConfirm`.
+   */
+  protected sendEnrollPincode(ctx: AuthWfCtx, address: string, code: string): Promise<void>;
+  /**
+   * Drop the per-enrolment scratch fields (the `mfaEnroll` provisioning fields +
+   * the pincode timers/`sentTo`) off ctx — the shared teardown used by the
+   * opt-in `skip` / `useDifferentMethod` arms and {@link cancelManageEnrollment}.
+   * Does NOT touch the user record: the enrol trio stages every candidate value
+   * (sms/email address, totp secret) in wf-state and writes it to the store ONLY
+   * on confirm (write-on-confirm), so a bailed enrolment never persisted a
+   * partial row to undo.
+   */
+  protected clearEnrollScratch(ctx: AuthWfCtx): void;
+  /**
+   * Validate a user-typed MFA address for its transport. Server-side counterpart
+   * to `EnrollAddressForm`'s client `@ui.form.validate` hint — the authoritative
+   * check (a client can bypass the hint). Returns an error string for the form,
+   * or `undefined` when valid. Email must look like an email; SMS is permissive
+   * E.164-ish (normalized by {@link normalizeMfaAddress}). Override for stricter
+   * (e.g. libphonenumber) validation.
+   */
+  protected validateMfaAddress(method: MfaTransport, value: string): string | undefined;
+  /**
+   * Light normalization of a validated MFA address before it is stored. Default:
+   * trims, and strips spacing/punctuation from SMS numbers while KEEPING the
+   * leading `+` (E.164 canonical form). Email is just trimmed. Override for full
+   * E.164 canonicalization.
+   */
+  protected normalizeMfaAddress(method: MfaTransport, value: string): string;
+  /**
+   * Abort an in-progress manage-MFA enrolment cleanly: drop the wf-state scratch
+   * and set `ctx.aborted` so the schema breaks to `finish-add-mfa` (cancelled
+   * terminal). Nothing to undo in the user record — the manage flow stages every
+   * candidate value (sms/email address, totp secret) in wf-state and writes it
+   * to the store ONLY on confirm (write-on-confirm), so an in-progress
+   * add/change/replace never touched the existing factors. This is exactly why
+   * a cancel — or a crafted `useDifferentMethod` routed here — can never strand
+   * or clobber a live factor.
+   */
+  protected cancelManageEnrollment(ctx: AuthWfCtx): void;
+  /**
+   * Shared skip / cancel / useDifferentMethod triage for the enrol-trio steps
+   * that pause after the candidate value is staged (`enroll-totp-qr` +
+   * `enroll-confirm`): `cancel` / `useDifferentMethod` (manage) abort the flow,
+   * `skip` (opt-in) and `useDifferentMethod` (opt-in) drop the wf-state scratch.
+   * Returns `true` when the action terminated the step so the caller can
+   * `return undefined`. (`enroll-pick-method` / `enroll-address` keep their own
+   * preludes — their skip/useDifferentMethod arms diverge from this one.)
+   *
+   * SECURITY: in `'manage'` mode BOTH `cancel` and `useDifferentMethod` (the
+   * manage forms HIDE the latter but it stays in their declared action
+   * whitelist, so a crafted resume can still send it) route through the abort,
+   * which only clears scratch. Because the enrol trio writes the user record
+   * ONLY on confirm (write-on-confirm), an in-progress add/change has touched
+   * nothing in the store — so a cancel/useDifferentMethod can never strand or
+   * clobber the user's live factor, by construction.
+   */
+  protected handleEnrollExit(ctx: AuthWfCtx, action: string | undefined): boolean;
+  initLogin(ctx: AuthWfCtx): void;
+  initInviteAdmin(ctx: AuthWfCtx): void;
+  initInviteAccept(ctx: AuthWfCtx): void;
+  initRecovery(ctx: AuthWfCtx): void;
+  /**
+   * Bind the change-password flow to the CURRENT authenticated user. Identity
+   * comes from the session (`useAuth().getUserId()`) — NEVER from form input —
+   * so the flow is structurally "change MY password" with no target-user
+   * parameter. NOT `@Public()`: the trigger, the `@Workflow` body, and every
+   * step in this flow are gated by `@ArbacResource("auth.change-password")` +
+   * `@ArbacAction("self")`, so a customer enables the whole feature with a
+   * single `allow("auth.change-password", "*")` grant and forbids it (SSO-only
+   * orgs) by omitting it. `getUserId()` throws 401 if unauthenticated — defense
+   * in depth on top of the guarded trigger route.
+   */
+  initChangePassword(ctx: AuthWfCtx): void;
+  /**
+   * Bind the standalone "Manage two-factor authentication" flow (add / change /
+   * remove) to the CURRENT authenticated user. Identity comes from the session
+   * (`useAuth().getUserId()`) — never form input — so it is structurally "manage
+   * MY factors". Mirrors `init-change-password`'s arbac gate (`auth.add-mfa` /
+   * `self`): a customer enables the feature with a single
+   * `allow("auth.add-mfa", "*")` grant and forbids it by omitting it.
+   * `getUserId()` throws 401 if unauthenticated — defence in depth on top of the
+   * guarded trigger route.
+   *
+   * Sets `ctx.mfaPolicy.availableTransports` to the FULL policy set (so the
+   * step-up's `load-enrolled-mfa-methods` can see the confirmed factors to
+   * challenge) and tracks the un-enrolled `candidates` separately on
+   * `ctx.addMfa` for the menu's Add options. `stepUpRequired` is set when the
+   * user has ANY confirmed factor — gating both the step-up and the management
+   * menu; a zero-MFA user skips both and falls through to the first-time enrol
+   * picker (the opt-in path). `stepUpMode` picks the step-up method: `'mfa'`
+   * when a confirmed factor is still challengeable, else `'password'` (a
+   * password re-auth fallback for an orphaned factor). Puts the enrol forms in
+   * `'manage'` mode (Cancel, not "Skip for now") and keeps the existing default.
+   */
+  initAddMfa(ctx: AuthWfCtx): Promise<undefined>;
+  credentials(ctx: AuthWfCtx): Promise<unknown>;
+  /**
+   * Route a credentials alt-action click (forgotPassword / signup / magicLink
+   * / sso-<id>) to a `finishWf` redirect envelope. Returns `ALT_HANDLED` when
+   * the caller should short-circuit without running form validation.
    */
-  acceptedConsentIds?: string[];
+  private handleCredentialsAlt;
+  request(ctx: AuthWfCtx): Promise<unknown>;
   /**
-   * Wall-clock ms when `processInlineConsent` resolved the carrier-form
-   * submission. Also the schema-gate for `persist-consents`.
+   * Resolves the recovery-step `email` input to the user's stable `id` (the
+   * token subject). Default: resolves via `findByHandle` (username exact, then
+   * email exact). Override for custom handle→id mapping; return `null` when no
+   * user matches.
    */
-  consentsDecidedAt?: number;
-  /** Set true by `persist-consents` after the batched `consentStore.save` call fires. */
-  consentsPersisted?: boolean;
+  protected emailToUserId(email: string): Promise<string | null>;
+  /** Anti-enumeration generic finish envelope used when recovery's `request` step receives an unknown email. */
+  private finishGenericRecovery;
+  /**
+   * Stamp `recoveryStateTtlMs` on a paused-state error so the wf engine's
+   * persisted-state strategy expires the state at that timestamp. Use at
+   * recovery-side `requireInput` throws (recovery-only steps) or wrap a
+   * shared-step `resolveInput()` throw inside a `ctx.postReset` guard.
+   */
+  protected stampRecoveryExpiry<E extends {
+    expires?: number;
+  }>(err: E): E;
+  /** Emit the recovery "backToLogin" abort envelope and stamp `ctx.aborted`. */
+  private abortRecoveryToLogin;
+  /**
+   * Canonical writer of `ctx.password.changeReason` + `isFirstLogin` /
+   * `newPasswordRequired`. Discriminates by ctx-slot presence (§10):
+   * `ctx.accept` → invite-accept; `ctx.postReset` → recovery; otherwise login.
+   * Idempotent on re-entry.
+   */
+  prepareSemanticFlags(ctx: AuthWfCtx): undefined | Promise<undefined>;
+  prepareConsents(ctx: AuthWfCtx): undefined | Promise<undefined>;
+  prepareAlternateCredentials(ctx: AuthWfCtx): undefined | Promise<undefined>;
+  prepareDeviceTrust(ctx: AuthWfCtx): undefined | Promise<undefined>;
+  prepareEnrollment(ctx: AuthWfCtx): undefined | Promise<undefined>;
+  prepareFinalize(ctx: AuthWfCtx): undefined | Promise<undefined>;
+  prepareGuards(ctx: AuthWfCtx): undefined | Promise<undefined>;
+  prepareLockout(ctx: AuthWfCtx): undefined | Promise<undefined>;
+  /**
+   * Per-call lockout override for `users.login` / `users.verifyMfa`, derived
+   * from the resolved mode. A permanent mode (`admin-only` / `self-service`)
+   * forces `duration: 0` so the threshold trip locks permanently;
+   * `temporary` (or an unresolved policy) returns `undefined` so UserService's
+   * own configured duration applies. Threshold stays UserService config.
+   */
+  protected lockoutOverride(ctx: AuthWfCtx): {
+    duration: number;
+  } | undefined;
+  prepareSessionPolicy(ctx: AuthWfCtx): undefined | Promise<undefined>;
+  prepareChangePassword(ctx: AuthWfCtx): undefined | Promise<undefined>;
+  /**
+   * Merges login's `prepare-mfa-setup` + invite's `prepare-mfa` + `setup-mfa`.
+   * Writes `ctx.mfaPolicy`; with `ctx.subject` bound, pre-picks
+   * `ctx.mfa.current` from the user's `defaultMethod` (challenge branch);
+   * with zero confirmed methods and a single available transport, pre-picks
+   * `ctx.mfaEnroll.method` (enrol branch). `enrolledMethods` is NOT written
+   * here — `load-enrolled-mfa-methods` owns that masking. Idempotent.
+   */
+  prepareMfa(ctx: AuthWfCtx): undefined | Promise<undefined>;
+  prepareAdminForm(ctx: AuthWfCtx): undefined | Promise<undefined>;
+  prepareAvailableRoles(ctx: AuthWfCtx): Promise<undefined>;
+  /**
+   * Merges policy from `resolveAccept` into `ctx.accept` (rather than
+   * overwriting) so any state stamped by later steps (`alreadyAccepted`)
+   * survives.
+   */
+  prepareAccept(ctx: AuthWfCtx): undefined | Promise<undefined>;
+  preparePasswordRules(ctx: AuthWfCtx): undefined | Promise<undefined>;
+  preparePostReset(ctx: AuthWfCtx): undefined | Promise<undefined>;
+  prepareRecoveryAltActions(ctx: AuthWfCtx): undefined | Promise<undefined>;
+  /**
+   * Admin-side invite form. Pauses for `InviteForm`; binds `ctx.email` +
+   * `ctx.admin.roles`. Server-side enforces the `availableRoles` whitelist
+   * (populated by `prepare-available-roles`). Calls `duplicateInviteCheck`
+   * to decide whether to reject duplicates.
+   */
+  adminForm(ctx: AuthWfCtx): Promise<unknown>;
+  /**
+   * Map admin-provided role labels to canonical IDs via `inferAdminRoles`
+   * hook, set-unioning with admin-supplied roles.
+   */
+  inferRoles(ctx: AuthWfCtx): Promise<undefined>;
+  /**
+   * Build the extras dict that `create-user` merges into the new user row.
+   * Calls `prepareUser({email, roles, invitedBy})` and writes the result onto
+   * `ctx.admin.userExtras`.
+   */
+  buildUserExtras(ctx: AuthWfCtx): Promise<undefined>;
+  /**
+   * Create the user row from `ctx.admin.userExtras` (plus the admin-supplied
+   * `ctx.admin.roles`), then stamp `pendingInvitation = true` via a follow-up
+   * deep-merge update so `createUser`-applied account defaults survive.
+   */
+  createUser(ctx: AuthWfCtx): Promise<undefined>;
+  /**
+   * Issue magic-link token and dispatch the invite email via `outletEmail` —
+   * the wf engine pauses, the email-outlet trigger mints the resume URL, and
+   * the click-through re-enters at this step's level. NOT routed through the
+   * `deliver()` hook because that hook is for direct dispatches where the
+   * payload is fully known at call-time; the magic-link URL exists only after
+   * the pause. Public so the engine can re-enter on the anonymous resume.
+   *
+   * Outlet-pause idempotency via `admin.emailDispatched`: on the invitee's
+   * magic-link resume, the engine re-executes this step body (a paused step's
+   * cursor stays AT the step until the body returns a non-`inputRequired`
+   * value). Returning the outletEmail envelope again would dispatch another
+   * email + re-pause; the flag short-circuits the resume so the cursor
+   * advances into the Phase B accept-tail. This is the engine-documented
+   * step-layer idempotency pattern for outlet pauses with side effects
+   * (`@wooksjs/event-wf` resume semantics — the cursor advances on a
+   * successful step but a re-invocation of the same step body must guard
+   * its own non-idempotent work).
+   */
+  sendInviteEmail(ctx: AuthWfCtx): unknown;
+  /**
+   * Check whether the invite was already accepted. Sets
+   * `ctx.accept.alreadyAccepted` when the user's pending-invitation marker is
+   * cleared.
+   */
+  checkPendingInvitation(ctx: AuthWfCtx): Promise<undefined>;
+  /**
+   * Emit the "this invite was already accepted" finish envelope and short-
+   * circuit the rest of the accept tail.
+   */
+  idempotentRedirect(ctx: AuthWfCtx): undefined;
+  /**
+   * Clear the user's `pendingInvitation` marker after successful password set.
+   */
+  unsetPendingInvitation(ctx: AuthWfCtx): Promise<undefined>;
+  /** Activate the invited user account (flips the account status flag). */
+  activateUser(ctx: AuthWfCtx): Promise<undefined>;
   /**
-   * 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).
+   * Emit the success-confirmation envelope. The downstream `finalize-auto-
+   * login` step preserves this `message` so the SPA paints the configured
+   * confirmation text alongside the tokens (WF-INVITE-020).
    */
-  pendingConsents?: ConsentDescriptor[];
-  /** Set by abort alt-actions (`backToLogin`). 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 `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;
-  protected readonly authOpts: AuthOpts;
-  protected readonly consentStore: ConsentStore;
-  constructor(opts: RecoveryWorkflowOpts, users: UserService, auth: AuthCredential, authOpts: AuthOpts, consentStore: ConsentStore);
+  confirmation(ctx: AuthWfCtx): undefined;
   /**
-   * Dispatch an email or SMS event. Default throws — consumers MUST override
-   * if `delivery.mode` ever drives email/SMS (i.e. for any non-`magicLink`
-   * mode AND for `magicLink` mode the `outletEmail` outlet still runs the
-   * email through `createAuthEmailOutlet`'s `EmailSender` — see the trigger
-   * controller wiring; this method covers OTP code dispatch).
+   * Unified password-set step body — merges login Phase 5 + invite accept-tail
+   * + recovery set-password. Stages copy via `ctx.password.changeReason`
+   * (`initial` / `expired` / `reset`), pauses for `SetPasswordForm`, validates
+   * match, calls `users.setPassword`, processes inline consents, and clears
+   * the per-user `isPasswordInitial` / `isPasswordExpired` flags.
    */
-  protected deliver(_payload: DeliverPayload): Promise<void>;
+  createPasswordForm(ctx: AuthWfCtx): Promise<unknown>;
   /**
-   * Emit an audit event. Default: no-op. Consumers override to fan out to
-   * their audit sink.
+   * Optional min-interval rate limit (Okta "minimum password age"). Gated
+   * upstream by `!!ctx.changePassword?.rateLimit`. Reuses `password.lastChanged`
+   * (no extra storage) — if the last change is more recent than
+   * `minIntervalMs`, emit a warn terminal and set `ctx.aborted` so the schema's
+   * `{ break }` short-circuits BEFORE the form pause (the user can't fix this by
+   * retrying the form — they must wait — so this is a terminal, not a
+   * `requireInput`). NOT the primary protection: current-password re-entry is.
    */
-  protected audit(_event: AuditEvent): Promise<void>;
+  enforceChangePasswordRateLimit(ctx: AuthWfCtx): Promise<undefined>;
   /**
-   * Resolve the delivery policy (mode + OTP transports). Override per-tenant
-   * to drive magic-link vs OTP delivery preferences. Sync/async friendly.
+   * Authenticated self-service password change. `ctx.subject` is the SIGNED-IN
+   * user (set by `init-change-password` from the session — never form input).
+   * Pauses for `ChangePasswordForm`, then calls `users.changePassword`, which
+   * re-verifies the CURRENT password (primary protection) before applying the
+   * policy + history checks. `UserAuthError`s map to per-field form errors so
+   * the user can fix and retry in place (per the requireInput-not-HttpError
+   * convention).
    */
-  protected resolveDelivery(_ctx: RecoveryWfCtx): NonNullable<RecoveryWfCtx["delivery"]> | Promise<NonNullable<RecoveryWfCtx["delivery"]>>;
+  changePasswordForm(ctx: AuthWfCtx): Promise<unknown>;
   /**
-   * 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.
+   * Change-password terminal — rotate the acting session's token (so the
+   * current device stays signed in on a FRESH credential) and emit a success
+   * message. Runs AFTER the optional `revoke-sessions` step, so the net effect
+   * is "kill every other session, keep this one on a new token" (OWASP Session
+   * Management: no ghost sessions survive a credential change).
    */
-  protected resolvePreReset(_ctx: RecoveryWfCtx): NonNullable<RecoveryWfCtx["preReset"]> | Promise<NonNullable<RecoveryWfCtx["preReset"]>>;
+  finishChangePassword(ctx: AuthWfCtx): Promise<undefined>;
   /**
-   * 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.
+   * Terminal for the manage-MFA flow. The user KEEPS their current session (no
+   * re-issue, no cookies) — a plain data finish. Outcomes, in priority order:
+   * removed → changed (`replace` + done) → added (done) → nothing-available
+   * (zero candidates, never had to step-up) → cancelled.
    */
-  protected resolvePostReset(_ctx: RecoveryWfCtx): NonNullable<RecoveryWfCtx["postReset"]> | Promise<NonNullable<RecoveryWfCtx["postReset"]>>;
+  finishAddMfa(ctx: AuthWfCtx): undefined;
   /**
-   * Resolve the alt-actions policy (whether `backToLogin` is offered on the
-   * recovery forms). Override to hide the escape hatch per-tenant. Sync/async
-   * friendly.
+   * Resolve which transports the user may NOT change/remove via the manage flow
+   * (calls {@link resolveLockedMfaTransports}) and write them to
+   * `ctx.addMfa.locked`. Mirrors the `prepare-<group>` convention.
    */
-  protected resolveAltActions(_ctx: RecoveryWfCtx): NonNullable<RecoveryWfCtx["altActions"]> | Promise<NonNullable<RecoveryWfCtx["altActions"]>>;
+  prepareLockedMfaTransports(ctx: AuthWfCtx): undefined | Promise<undefined>;
   /**
-   * Resolve the audit policy (whether recovery.* audit events fire). Override
-   * to route audit-log emission per-tenant. Sync/async friendly.
+   * Fires once the step-up factor verifies — anchor the rest of the flow in the
+   * durable `store` strategy (mirrors login's swap-after-credentials): the
+   * pincode becomes single-use server state and the staged new factor lives
+   * server-side instead of in the SPA-held encapsulated token. Degrades to
+   * encapsulated when no durable store is wired (the registry default).
    */
-  protected resolveAudit(_ctx: RecoveryWfCtx): NonNullable<RecoveryWfCtx["audit"]> | Promise<NonNullable<RecoveryWfCtx["audit"]>>;
-  prepareDelivery(ctx: RecoveryWfCtx): undefined | Promise<undefined>;
+  manageStepUpDone(ctx: AuthWfCtx): 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.
+   * Manage-MFA password re-auth — the step-up FALLBACK when the user's only
+   * confirmed factor(s) are of kinds the policy no longer allows, so nothing is
+   * MFA-challengeable (`addMfa.stepUpMode === "password"`; see `init-add-mfa`).
+   * Pauses on `PasswordReauthForm`, verifies the account password via
+   * `UserService.verifyPassword`, and on success flips `ctx.otp.verified` — the
+   * SAME step-up success signal `mfaStepUpLoop` sets — so `manage-stepup-done`
+   * (swap-to-store) and `manage-menu` proceed identically. `cancel` aborts to
+   * the cancelled terminal (fail closed: no management write without a fresh
+   * proof of identity). Only ARBAC-gated callers reach it (session-bound
+   * subject), and `verifyPassword` is the same check `changePassword` enforces.
    */
-  prepareConsents(ctx: RecoveryWfCtx): undefined | Promise<undefined>;
-  flow(): void;
+  managePasswordReauth(ctx: AuthWfCtx): Promise<undefined>;
   /**
-   * First step of the workflow; remains as a no-op override hook for
-   * consumers. Policy populated by the dedicated `prepare-<group>` steps.
-   *
-   * 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).
+   * Manage-MFA menu — pauses on `ManageMfaForm` and routes the chosen
+   * `operation` (`add:<t>` / `replace:<t>` / `remove:<t>`). Only reached when
+   * the user has ≥1 confirmed factor (a zero-MFA user goes straight to the enrol
+   * picker). Re-checks the locked set + candidate membership server-side, then
+   * sets `ctx.addMfa.action`/`target` (and pre-seeds `mfaEnroll.method` for
+   * add/change). `cancel`, or nothing actionable, aborts to the finish terminal.
    */
-  init(_ctx: RecoveryWfCtx): undefined | Promise<undefined>;
-  request(ctx: RecoveryWfCtx): Promise<unknown>;
+  manageMenu(ctx: AuthWfCtx): Promise<undefined>;
   /**
-   * Resolves the recovery-step `email` input to the `username` (user-id) that
-   * `UserService.getUser` expects. Default: returns the email unchanged (treats
-   * email as username). Apps whose user model separates `username` from
-   * `email` MUST override this; return `null` when no user matches.
+   * Manage-MFA remove confirmation. Pauses on `RemoveMfaConfirmForm`; the
+   * 'Remove' submit performs the removal, 'Cancel' aborts. Re-checks the locked
+   * set (defence in depth) and blocks removing the LAST confirmed factor when
+   * the policy mode is `required` (you must keep at least one).
    */
-  protected emailToUserId(email: string): Promise<string | null>;
-  selectMode(ctx: RecoveryWfCtx): unknown;
-  sendMagicLink(ctx: RecoveryWfCtx): unknown;
-  sendOtp(ctx: RecoveryWfCtx): Promise<undefined>;
-  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
-   * TOTP code). Returns `true` when the factor matches.
-   *
-   * Consumers extend by overriding to support additional factors (e.g.
-   * security questions); call `super.verifyRecoveryFactor(...)` to keep
-   * the built-in checks.
+  confirmRemoveMfa(ctx: AuthWfCtx): Promise<undefined>;
+  askChannel(ctx: AuthWfCtx, channel: "email" | "phone"): Promise<unknown>;
+  verifyChannel(ctx: AuthWfCtx, channel: "email" | "phone"): Promise<unknown>;
+  /**
+   * Read the device-trust cookie; if it matches a valid record, set
+   * `ctx.otp.verified = true` to skip the MFA loop. Otherwise stamp
+   * `ctx.trust.newDevice = true` to drive the post-MFA notify gate.
    */
-  protected verifyRecoveryFactor(input: {
-    factor: string;
-    value: string;
-    ctx: RecoveryWfCtx;
-  }): Promise<boolean>;
-  setPassword(ctx: RecoveryWfCtx): Promise<unknown>;
-  revokeSessions(ctx: RecoveryWfCtx): Promise<undefined>;
-  auditStep(ctx: RecoveryWfCtx): Promise<undefined>;
+  checkTrustedDevice(ctx: AuthWfCtx): Promise<undefined>;
   /**
-   * Batched consent persistence — delegates to
-   * `AuthWorkflowBase.runPersistConsents`. See that helper for the full
-   * audit-friendly-default / idempotency / silent-drop contract.
+   * 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).
+   * Ported from `AuthWorkflowBase`.
    */
-  persistConsentsStep(ctx: RecoveryWfCtx): Promise<undefined>;
-  freshLoginFinish(ctx: RecoveryWfCtx): undefined | Promise<undefined>;
-  autoLoginFinish(ctx: RecoveryWfCtx): Promise<undefined>;
+  protected resolveClientIp(): string | undefined;
   /**
-   * Send the generic "if an account exists, you'll receive instructions"
-   * finished response. Used for unknown emails so a known/unknown lookup is
-   * indistinguishable to the client (anti-enumeration).
+   * Resolve the client `User-Agent` from the active HTTP request. Sibling to
+   * {@link resolveClientIp}; swallows the no-HTTP case (unit tests that
+   * hand-roll the wf runtime) by returning `undefined`.
    */
-  private finishGeneric;
-  private abortToLogin;
-  private emitRequested;
-  private resolveUserPhone;
-}
-//#endregion
-//#region src/workflows/invite.workflow.options.d.ts
-/**
- * Input passed to {@link InviteWorkflow.prepareUser}. The workflow resolves the
- * admin form to these fields before calling the hook, so the override sees a
- * fully-typed payload regardless of which optional fields the admin filled in.
- */
-interface PreparedUserInput {
-  email: string;
-  firstName?: string;
-  lastName?: string;
-  roles: string[];
-  /** Admin's `username` (`useAuth().getAuthContext()?.userId` at invite time). */
-  invitedBy?: string;
-}
-/** Return value of {@link InviteWorkflow.duplicateCheck}. */
-type DuplicateAction = "allow" | "reject" | "reuseAsReInvite";
-type InviteSendMode = "email" | "shareableLink" | "choice";
-interface InviteWorkflowOpts {
-  /**
-   * Replaceable form schemas. Each field defaults to the corresponding
-   * `.as` form shipped under `@aooth/auth-moost/atscript/models`.
+  protected resolveUserAgent(): string | undefined;
+  /**
+   * Build the {@link CredentialMetadata} captured onto every credential at
+   * issue time. Default records the request IP + User-Agent (the raw facts the
+   * session UI derives device/location from at read time). Returns `undefined`
+   * outside an HTTP context — so a hand-rolled (no-HTTP) wf run issues with
+   * `metadata: undefined`. Override to add a `label`, trim PII, etc.
    */
-  forms?: {
-    enrollAddress?: TAtscriptAnnotatedType;
-    enrollConfirm?: TAtscriptAnnotatedType;
-    enrollPickMethod?: TAtscriptAnnotatedType;
-    invite?: TAtscriptAnnotatedType;
-    inviteEmail?: TAtscriptAnnotatedType;
-    inviteSendMode?: TAtscriptAnnotatedType;
-    setPassword?: TAtscriptAnnotatedType;
-  };
-}
-/**
- * Fully-resolved view used by the workflow at runtime — every nested group is
- * always populated by `mergeInviteOpts`, so step bodies can read
- * `this.opts.<group>.<flag>` directly without optional chaining.
- */
-interface ResolvedInviteWorkflowOpts {
-  forms: {
-    enrollAddress: TAtscriptAnnotatedType;
-    enrollConfirm: TAtscriptAnnotatedType;
-    enrollPickMethod: TAtscriptAnnotatedType;
-    invite: TAtscriptAnnotatedType;
-    inviteEmail: TAtscriptAnnotatedType;
-    inviteSendMode: TAtscriptAnnotatedType;
-    setPassword: TAtscriptAnnotatedType;
-  };
-}
-/**
- * Deep-merge defaults with the user-supplied nested pojo. Each group has its
- * own `{ ...defaults, ...input }` line — small enough that pulling in lodash
- * would be silly.
- */
-declare function mergeInviteOpts(opts?: InviteWorkflowOpts): ResolvedInviteWorkflowOpts;
-/**
- * Backwards-compat alias for the prior input-shape name. Consumers who type
- * their `prepareUser()` override against this still compile.
- */
-type InvitePrepareUserInput = PreparedUserInput;
-//#endregion
-//#region src/workflows/invite.workflow.d.ts
-interface InviteWfCtx {
-  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;
+  protected resolveIssueMetadata(_ctx: AuthWfCtx): CredentialMetadata | undefined;
   /**
-   * 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
-   * `admin-form` to reject admin-submitted roles outside the list.
+   * Mint a fresh credential for the workflow user, stamping the default
+   * issue-time metadata (IP + User-Agent via {@link resolveIssueMetadata}).
+   * Shared by every finish step that issues a session (login, change-password,
+   * recovery auto-login). Call after {@link requireSubject} has narrowed
+   * `subject` (the typed param enforces it at the call site).
    */
-  availableRoles?: string[];
-  email?: string;
-  /** Typically same as `email`; consumers can override the mapping. */
-  username?: string;
-  firstName?: string;
-  lastName?: string;
-  roles?: string[];
+  private issueForContext;
   /**
-   * 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.
+   * Load + summarise the user's enrolled MFA methods (filtered against
+   * `ctx.mfaPolicy.availableTransports`) and mirror form-gating flags
+   * (`mfa.methodCount`, `trust.optIn`) onto ctx. Pure data-load.
+   */
+  loadEnrolledMfaMethods(ctx: AuthWfCtx): Promise<undefined>;
+  /**
+   * Pick which MFA method to use from `ctx.mfa.enrolledMethods`. Decision-only,
+   * no IO. Honors `ctx.mfa.current` (pre-selected by `prepare-mfa` from the
+   * user's `defaultMethod`), auto-picks when only one method is enrolled,
+   * falls back to the `isDefault` method. Gated on `!ctx.mfa.ignoreDefault`.
+   */
+  selectMfaMethod(ctx: AuthWfCtx): undefined | Promise<undefined>;
+  /** Pauses for `Select2faForm`; binds `ctx.mfa.method` from input. */
+  select2fa(ctx: AuthWfCtx): Promise<unknown>;
+  /**
+   * Unified MFA pincode send. Used by login MFA SMS/email challenge and
+   * recovery OTP. Form/target picked via `resolvePincodeForm` /
+   * `resolvePincodeTarget` (which discriminate on `ctx.mfa?.method` presence).
+   */
+  pincodeSend(ctx: AuthWfCtx): Promise<unknown>;
+  /**
+   * Unified MFA pincode check. Used by login MFA SMS/email challenge and
+   * recovery OTP. Alt-actions routed via `resolvePincodeAltAction` — the
+   * default returns `undefined` (customers override per form).
+   */
+  pincodeCheck(ctx: AuthWfCtx): Promise<unknown>;
+  /**
+   * TOTP MFA challenge step body. Verifies a TOTP code via `users.verifyMfa`
+   * (lockout-aware); sets `ctx.otp.verified = true` on success. Replaces
+   * login's prior `mfa-totp` step.
+   */
+  totpCheck(ctx: AuthWfCtx): Promise<unknown>;
+  /**
+   * Unified MFA-enrol phase 1 (pick method). Auto-picks a single transport,
+   * otherwise pauses for `EnrollPickMethodForm`. When TOTP is picked, the
+   * secret is idempotently provisioned in the same step body. Handles `skip`
+   * (optional opt-in) / `cancel` (manage). In the manage flow this only runs
+   * for a zero-MFA user — once the user has factors, the menu pre-seeds
+   * `mfaEnroll.method` (add/change) so the picker is skipped.
+   */
+  enrollPickMethod(ctx: AuthWfCtx): undefined | Promise<undefined>;
+  /**
+   * Unified MFA-enrol phase 2 (collect sms/email address + send pincode).
+   * Not invoked for totp. Handles `skip` (opt-in) / `cancel` (manage) /
+   * `useDifferentMethod`. Validates the address server-side (the client
+   * `@ui.form.validate` hint is advisory), then STAGES the candidate value in
+   * wf-state (`m.address`) — the user record is written only on confirm
+   * (write-on-confirm), so an ADD leaves no partial row and a REPLACE keeps the
+   * old confirmed value live until the new code verifies in `enroll-confirm`.
+   */
+  enrollAddress(ctx: AuthWfCtx): Promise<undefined>;
+  /**
+   * MFA-enrol TOTP QR step — shown on its OWN pause between method-pick and
+   * code-entry (so the user scans first, types the code next). Idempotently
+   * provisions the TOTP secret in wf-state ONLY (covers the auto-pick /
+   * menu-pre-seeded paths where `enroll-pick-method` was skipped), then pauses
+   * on `EnrollTotpQrForm`. The user record is written only on confirm
+   * (write-on-confirm), so a manage **replace** never clobbers the live totp
+   * secret and a cancel/crash leaves the existing factor intact — no stash or
+   * restore needed. Handles `skip` (opt-in) / `cancel` (manage) /
+   * `useDifferentMethod`.
+   */
+  enrollTotpQr(ctx: AuthWfCtx): Promise<undefined>;
+  /**
+   * Unified MFA-enrol phase 3 (verify pincode/TOTP, then write the factor). On
+   * success sets `ctx.mfaEnroll.done = true` AND `ctx.otp.verified = true`
+   * (the loop-exit signal — enrol-confirm verifies an OTP, so the unified
+   * `otp.verified` flag fires alongside the MFA-specific `mfaEnroll.done`).
+   * This is the ONLY place the enrol trio touches the user record
+   * (write-on-confirm): the proven value (sms/email address or totp secret,
+   * staged in wf-state) is upserted as confirmed via `addMfaMethod`, which
+   * atomically swaps in a REPLACE with no pre-confirm clobber window and creates
+   * a fresh row for an ADD.
+   */
+  enrollConfirm(ctx: AuthWfCtx): Promise<undefined>;
+  /**
+   * Promote a freshly-confirmed channel into its login-handle column so future
+   * login + recovery resolve the account by it (`findByHandle`). Runs once,
+   * right after `enroll-confirm` in the shared enrolment trio (so it covers
+   * add-mfa AND login/invite forced first-time enrolment). Default is a no-op
+   * unless `resolvePromoteHandleField` is overridden to name a handle column.
+   *
+   * Overridable extension point: a deployment can replace this with richer
+   * logic — e.g. pause on a carrier form asking whether to use the new number
+   * as a login handle before writing it.
+   *
+   * Fires only for a freshly-confirmed `email` / `sms` factor carrying an
+   * address. TOTP has no address; a skipped / `useDifferentMethod` enrolment
+   * cleared `method` + `address` via `clearEnrollScratch`, so the guard below
+   * excludes both — only an actually-confirmed channel is promoted.
    */
-  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 `prepare-send` or `select-send-mode`). */
-  resolvedSendMode?: "email" | "shareableLink";
-  /** Populated by `return-shareable-link` so the admin's UI can display it. */
-  shareableLinkUrl?: string;
-  /** Marks that `send-email` already emitted the outlet — resume → advance. */
-  linkSent?: boolean;
-  /** Detected at `check-pending-invitation`; triggers `idempotent-redirect`. */
-  alreadyAccepted?: boolean;
-  passwordSet?: boolean;
-  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[];
-/**
- * **Per-step ARBAC model.** Phase-A steps (admin-side, pre magic-link send)
- * 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')`. 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
- * flow body on EVERY `start()` / `resume()` call — gating it would 401 the
- * anonymous magic-link resume before any step runs. The real gate is the
- * step methods themselves, which the wf runtime invokes through the same
- * interceptor chain.
- *
- * Phase-B steps (post `ctx.linkSent`, accept tail) are method-level
- * `@Public()` because they fire on the anonymous magic-link resume.
- * `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/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 extends AuthWorkflowBase {
-  protected readonly opts: ResolvedInviteWorkflowOpts;
-  protected readonly users: UserService;
-  protected readonly auth: AuthCredential;
-  protected readonly authOpts: AuthOpts;
-  protected readonly consentStore: ConsentStore;
-  constructor(opts: InviteWorkflowOpts, users: UserService, auth: AuthCredential, authOpts: AuthOpts, consentStore: ConsentStore);
+  promoteToHandle(ctx: AuthWfCtx): Promise<undefined>;
   /**
-   * Dispatch an email or SMS event. Default throws — the default invite send
-   * uses `outletEmail` (handled by `createAuthEmailOutlet`) so this method is
-   * only invoked when a consumer's accept-tail steps drive a manual send.
-   * Override to wire your senders.
+   * Best-effort write of a confirmed channel value into its handle column.
+   * Swallows `ALREADY_EXISTS` — the value is already a handle on ANOTHER
+   * account (e.g. two accounts legitimately sharing one phone for MFA): the
+   * second account keeps the factor as MFA-only and is simply not promoted.
+   * Any other store error propagates. (`UserService.update` translates a
+   * unique-index `CONFLICT` to `ALREADY_EXISTS` for both store adapters.)
    */
-  protected deliver(_payload: DeliverPayload): Promise<void>;
+  protected applyHandlePromotion(subject: string, field: string, value: string): Promise<void>;
   /**
-   * Emit an audit event. Default: no-op. Consumers override to fan out to
-   * their audit sink.
+   * Risk step-up: re-evaluate whether to require another MFA round. Default
+   * `resolveRiskStepUp` returns `{require: false}`. When `require: true`,
+   * clear `ctx.otp.verified` to re-arm the loop.
    */
-  protected audit(_event: AuditEvent): Promise<void>;
+  riskStepUp(ctx: AuthWfCtx): Promise<undefined>;
   /**
-   * Build the extras dictionary merged into the freshly-created user row in
-   * `invitePreCreateUser`. Default: `{}`. Override to populate e.g. a
-   * required `tenantId`. This is the ONLY seam through which the admin form's
-   * `firstName` / `lastName` reach persistence — map them into your schema's
-   * own columns (e.g. `displayName`) and return them here.
+   * Mint a device-trust record + cookie value. Default: delegates to
+   * `UserService.issueTrustedDevice` — produces an HMAC-signed token bound to
+   * `username` (+ `ip` when `bindsTo === 'cookie+ip'`).
    */
-  protected prepareUser(_input: PreparedUserInput): Promise<Record<string, unknown>>;
+  protected issueTrustedDevice(username: string, ip: string | undefined, ttlMs: number): Promise<TrustedDeviceRecord>;
   /**
-   * 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
-   * `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.
+   * Persist the trusted-device record onto the user store. Default: appends
+   * onto the `trustedDevices` array.
    */
-  protected getAvailableRoles(): Promise<string[] | undefined>;
+  protected storeTrustedDevice(username: string, record: TrustedDeviceRecord): Promise<void>;
   /**
-   * Derive roles server-side from the admin-form payload (e.g. email domain
-   * → tenant role, AD lookup). Result is set-unioned with admin-supplied
-   * roles when `adminForm.collectRoles` is true. Default: `[]` (no inference).
+   * Post-MFA device-trust issuance. SECURITY: must bail when
+   * `ctx.newPasswordRequired` is true — issuing a trusted-device token before
+   * the user has set their own password would let an admin-set temporary
+   * credential establish persistent device trust (defence-in-depth on top of
+   * the MFA-form `hidden` expression on `rememberDevice`).
    */
-  protected inferRoles(_input: {
-    email: string;
-    firstName?: string;
-    lastName?: string;
-  }): Promise<string[]>;
+  deviceTrust(ctx: AuthWfCtx): Promise<undefined>;
   /**
-   * Persist the accept-time profile payload. Default: deep-merge into the
-   * user record via `UserService.update(username, profile)`. Override to
-   * route into a separate profile table / external CRM.
+   * Standalone terms-bump prompt for returning users whose accepted terms
+   * version is stale and no carrier form ran. Delegates to
+   * `processInlineConsent` for validation + ctx writes.
    */
-  protected applyProfile(input: {
-    username: string;
-    profile: Record<string, unknown>;
-  }): Promise<void>;
+  termsBumpPrompt(ctx: AuthWfCtx): undefined;
   /**
-   * 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.
+   * Load the user's active session count for the concurrency-limit gate.
+   * Pure data-load — calls the overridable `loadActiveSessionsCount` hook.
    */
-  protected duplicateCheck(input: {
-    email: string;
-    existingUser: UserCredentials | null;
-  }): Promise<DuplicateAction>;
+  loadActiveSessions(ctx: AuthWfCtx): Promise<undefined>;
   /**
-   * Return the consumer-supplied `.as` form schema rendered in the
-   * `collect-profile` step. `undefined` (default) skips the step
-   * entirely (just password collection).
+   * Concurrency-limit gate — pauses for `ConcurrencyLimitForm`. `reject` mode
+   * blocks the login outright with a form-level error. `kickPrompt` mode pauses
+   * on the fieldless prompt; submitting it (the 'Login' button) logs out the
+   * user's other sessions and continues. `resolveInput()` throws to pause on
+   * first arrival and returns once the submit resumes the step.
    */
-  protected getProfileForm(): TAtscriptAnnotatedType | undefined;
+  concurrencyLimit(ctx: AuthWfCtx): Promise<unknown>;
   /**
-   * Resolve the admin-form policy (whether to collect roles on the admin
-   * invite form). Override per-tenant. Sync/async friendly.
+   * Consumer extension point — override in your subclass to inject extra
+   * accept-tail logic (input pauses, alt actions, persistence). Default:
+   * no-op.
    */
-  protected resolveAdminForm(_ctx: InviteWfCtx): NonNullable<InviteWfCtx["adminForm"]> | Promise<NonNullable<InviteWfCtx["adminForm"]>>;
+  extraStep(_ctx: AuthWfCtx): unknown | Promise<unknown>;
   /**
-   * Resolve the send-mode policy (`'email'` / `'shareableLink'` / `'choice'`).
-   * Override to drive per-tenant magic-link delivery preferences. Sync/async
-   * friendly.
+   * Batched consent persistence — fans one `ConsentEvent` per pending
+   * descriptor out to the `ConsentStore.save` DI provider.
    */
-  protected resolveSend(_ctx: InviteWfCtx): NonNullable<InviteWfCtx["send"]> | Promise<NonNullable<InviteWfCtx["send"]>>;
+  persistConsents(ctx: AuthWfCtx): Promise<undefined>;
   /**
-   * 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.
+   * Revoke the user's existing sessions. Shared by recovery (gated upstream by
+   * `ctx.postReset.revokeAllSessions`) and authenticated change-password (gated
+   * by `ctx.changePassword.revokeOtherSessions`).
+   *
+   * - Change-password runs in an authenticated context, so we KEEP the caller's
+   *   current device via `revokeOtherSessions(username, currentSessionId)` —
+   *   OWASP "invalidate other sessions" without logging the user out of the tab
+   *   they just changed their password in. If the current session can't be
+   *   resolved (no session id), fall back to revoking everything (fail-secure).
+   * - Recovery is anonymous (no current session to keep) → `revokeAllForUser`.
+   */
+  revokeSessions(ctx: AuthWfCtx): Promise<undefined>;
+  /**
+   * Lift a failed-login lockout after a successful password reset. Recovery
+   * only — gated upstream by `ctx.lockout?.mode === "self-service"` so the
+   * `admin-only` mode keeps the account frozen (reset succeeds, lock stays)
+   * and `temporary` continues to rely on its own timeout. `unlockAccount`
+   * also zeroes `failedLoginAttempts`, so the next login starts clean.
+   */
+  unlockAccount(ctx: AuthWfCtx): Promise<undefined>;
+  /**
+   * Issue access + refresh tokens via `auth.issue`. Stashes the login
+   * response envelope on `useWfFinished` so downstream `redirect` can
+   * override with a redirect envelope while preserving the cookies.
+   */
+  issue(ctx: AuthWfCtx): Promise<void>;
+  /**
+   * Notify the user of a login from a new device via the unified `deliver`
+   * hook. Gated upstream by
+   * `!ctx.isFirstLogin && !!ctx.finalize.notifyNewDevice && !!ctx.trust.newDevice`.
+   */
+  notifyNewDevice(ctx: AuthWfCtx): Promise<undefined>;
+  /**
+   * Set `ctx.completion.redirectUrl` from `resolveRedirect`. When set,
+   * overrides `issue`'s data envelope with an immediate-redirect envelope
+   * (cookies from `issue` are preserved).
+   */
+  redirect(ctx: AuthWfCtx): undefined;
+  /**
+   * Authorization-server terminal (AUTH-SERVER.md §4.4). Reached INSTEAD of
+   * `issue`/`redirect` when this login was started from `GET /auth/authorize`
+   * (`ctx.authz` set by `init-login` or re-raised by `sso-callback`). Mints a
+   * single-use authorization code bound to the authenticated user + the pending
+   * request's PKCE challenge / redirect / token policy, then 302s the browser to
+   * `redirect_uri?code&state`. It does NOT issue a session and attaches NO
+   * cookies — the token is minted later, off the browser, at `POST /auth/token`.
+   */
+  mintAuthzCode(ctx: AuthWfCtx): Promise<undefined>;
+  /**
+   * Fresh-login finalize — invite + recovery. Emits a finish envelope that
+   * redirects the user to `loginUrl`. Invite uses an immediate redirect;
+   * recovery uses an auto countdown so the user reads the "Password updated"
+   * confirmation first. Discriminated by ctx-slot presence
+   * (`ctx.postReset` → recovery; otherwise invite).
+   */
+  finalizeFreshLogin(ctx: AuthWfCtx): undefined | Promise<undefined>;
+  /**
+   * Post-reset store read: did an `admin-only` lockout survive the password
+   * reset (account still frozen)? Callers MUST first confirm
+   * `ctx.lockout?.mode === "admin-only"` so this read stays off the sync fast
+   * path for every other recovery + invite finalize — `self-service` ran
+   * `unlock-account` and `temporary` auto-expires, so only `admin-only` can
+   * reach finalize still locked. Shared by BOTH finalize terminals: fresh-login
+   * warns instead of confirming success, auto-login warns instead of minting
+   * tokens (a still-frozen account must never be logged straight in).
+   */
+  private recoveryLeftAccountLocked;
+  /**
+   * Emit the recovery password-reset terminal. `stillLocked` is only ever true
+   * for an `admin-only` account whose lock survived the reset — that terminal
+   * warns the user the account remains frozen and offers a manual back-to-
+   * sign-in (no misleading auto-redirect to a login they can't pass yet).
+   * Every other reset confirms success and auto-redirects to sign-in.
+   */
+  private finishRecoveryReset;
+  /**
+   * Auto-login finalize — invite + recovery. Issues access + refresh tokens
+   * and stashes the login response envelope on `useWfFinished`. Invite
+   * preserves any `message` set by an earlier terminal (`confirmation`) so
+   * the SPA paints the confirmation text alongside the tokens (WF-INVITE-020).
+   */
+  finalizeAutoLogin(ctx: AuthWfCtx): Promise<undefined>;
+  /**
+   * Entry step of `auth/signup/flow`. Inline-resolves the signup policy (runs
+   * BEFORE the `!allowSignup` gate, mirroring how `credentials` / `request`
+   * inline the front policies they need) and stamps `ctx.signup` — whose
+   * presence is the flow discriminator. Sets `ctx.autoLogin = true`: v1 always
+   * issues a session on success (the shared `finalize-fresh-login` assumes
+   * invite/recovery ctx slots, so signup uses `finalize-auto-login` only).
+   * When self-signup is disabled (the default), emits a terminal finish so the
+   * SPA shows a closed-signups message instead of a form; the schema's
+   * `{ break: !allowSignup }` short-circuits the rest.
+   */
+  initSignup(ctx: AuthWfCtx): undefined | Promise<undefined>;
+  /**
+   * Collect the signup email (verify-first — no account exists yet). First
+   * entry pauses on `SignupForm`; on submit, stashes `ctx.email` and flips
+   * `ctx.signup.submitted` to open the OTP loop. `backToLogin` aborts to the
+   * login page. The bundled form is email-only (`username := email`); a custom
+   * `opts.forms.signup` + an override here can collect more.
+   */
+  signupForm(ctx: AuthWfCtx): Promise<undefined>;
+  /**
+   * Create the account — runs AFTER the OTP loop, so the email is proven. The
+   * existence check lives HERE (not before the OTP) so the wire path is
+   * identical for new and already-registered emails: both received an OTP
+   * pause, so an attacker on the wire cannot enumerate accounts. A taken email
+   * is only revealed to someone who actually controls the inbox, at which point
+   * we route them to sign-in. A new email creates the (still-inactive) user and
+   * arms the shared password-set phase (`newPasswordRequired`); the reused
+   * `activate-user` step flips it active AFTER the password is set.
+   */
+  signupCreateUser(ctx: AuthWfCtx): Promise<undefined>;
+  /** Generic "you already have an account" finish for the signup existence collision (safe — only reached post-OTP). */
+  private finishSignupAlreadyRegistered;
+  /**
+   * Customer extension point for signup — runs after the account is created,
+   * activated, and consents persisted, just before `finalize-auto-login`. The
+   * default is a no-op; a subclass overrides it to seed app-specific rows
+   * (tenant, profile, welcome email, audit record, ConsentStore.save, …) for
+   * the freshly-created `ctx.subject`. Mirrors login's `extra-step` seam.
+   */
+  signupExtraStep(_ctx: AuthWfCtx): unknown | Promise<unknown>;
+  magicLinkRequest(_ctx: AuthWfCtx): unknown | Promise<unknown>;
+  magicLinkSend(_ctx: AuthWfCtx): unknown | Promise<unknown>;
+  magicLinkVerified(_ctx: AuthWfCtx): unknown | Promise<unknown>;
+  passkey(_ctx: AuthWfCtx): unknown | Promise<unknown>;
+  /**
+   * Verify the OAuth callback and resolve a user. Reaches here (instead of
+   * `credentials`) when `init-login` saw an inbound `state` (`ctx.idpInbound`);
+   * reads `{ provider, code, state, error }` from the START input (the SPA
+   * bridges the provider callback into `/auth/trigger` STARTING `auth/login/flow`).
+   * Order is security-critical:
+   *
+   *   verify state (HS256) → CSRF double-submit → re-derive PKCE verifier/nonce
+   *   from the seed → provider.exchange (verified ID token) → link OR resolveUser
+   *   → ACCOUNT-STATE GATE → seed ctx.subject → fall through to the shared tail.
+   *
+   * Replay defense is the provider's ONE-TIME `code` (a replayed callback fails
+   * at `exchange` when the provider rejects the already-redeemed code), plus the
+   * short-TTL signed state + CSRF cookie — the stateless design carries no
+   * single-use server marker, by design.
+   *
+   * Every pre-subject failure collapses to one benign redirect terminal
+   * (`finishOAuth`) so the wire is not an oracle for which check tripped. The
+   * account-state gate MUST live here — `issue` does not re-gate, so without it
+   * a locked/inactive account could log straight in via OAuth.
+   */
+  ssoCallback(ctx: AuthWfCtx): Promise<undefined>;
+  /**
+   * Emit a benign, generic federated-login failure terminal (immediate redirect
+   * to {@link resolveOAuthErrorRedirect}). Collapses EVERY pre-subject failure
+   * mode so the wire response is never an oracle for which check tripped
+   * (invariant #5). Returns `undefined` so the step can `return this.finishOAuth(...)`;
+   * `{ break: !ctx.subject }` then halts the flow (subject is never set on failure).
+   *
+   * The precise `reason` is handed to `resolveOAuthErrorRedirect` (the override
+   * seam — a consumer MAY branch the target on it, server-side) but the
+   * CLIENT-facing `action.reason` is deliberately the constant `"oauth-failed"`:
+   * exposing `oauth-${reason}` to the SPA would re-introduce the very
+   * which-check-tripped oracle invariant #5 forbids.
+   */
+  private finishOAuth;
+  /**
+   * Seed `ctx.email` / `ctx.channel` from a resolved user's confirmed channels —
+   * shared by `ssoCallback` (linked / created / auto-linked) and `proveControl`
+   * (interactively-linked) so the post-success channel shape can't drift between
+   * the two federated entry points. Mirrors `credentials`' post-login seeding.
+   * `fallbackEmail` (the provider / snapshot email) is a DISPLAY fallback only —
+   * never promoted to the unique login handle (a gated, later-phase concern).
+   */
+  private seedChannelState;
+  /**
+   * `needs-link` setup (decision A — password, OTP fallback). Decide how the
+   * user will prove control of the matched account, stash the pending-link
+   * state, and return so the `prove-control` @Step (gated on `ctx.pendingLink`)
+   * pauses for the challenge. Deliberately does NOT set `ctx.subject` — proving
+   * control is exactly what authorizes that.
+   *
+   * Proof channel:
+   *  - account has a real password (`!password.isInitial`) → `password`;
+   *  - else a confirmed email/SMS factor exists → `otp` to THAT channel (NEVER
+   *    the provider-supplied email — the attacker controls the provider account,
+   *    so a code sent there would be circular);
+   *  - else no provable channel → generic terminal (cannot safely link).
+   */
+  protected stashPendingLink(ctx: AuthWfCtx, profile: NormalizedProfile, candidateUserId: string, redirect: string): Promise<undefined>;
+  /**
+   * Mint + deliver an OTP proof code to the pending-link candidate's OWN
+   * confirmed channel (NEVER the provider-supplied email — that would be
+   * circular) and arm the resend cooldown. Shared by the first auto-dispatch
+   * and the `resend` action. Returns the masked delivery target, or `null` if
+   * the confirmed channel vanished between resolve and dispatch (the caller
+   * routes that to the safe generic terminal).
+   */
+  private deliverPendingLinkPin;
+  /**
+   * Interactive `needs-link` completion — prove control of the matched local
+   * account, then attach the verified federated identity to it. Gated by the
+   * login schema on `ctx.pendingLink && !ctx.subject`, so it runs ONLY on the
+   * federated email-collision path and ONLY while the account is unproven.
+   *
+   * PASSWORD mode re-verifies the account's password via `UserService.login`
+   * with the username bound server-side from `candidateUserId` (the user never
+   * types it, so this can't be repurposed to sign into a different account).
+   * OTP mode verifies a code delivered to the account's OWN confirmed channel.
+   * A wrong proof re-pauses with a generic inline error; `cancel` abandons the
+   * link. On success: `linkIdentity` (cross-user `ALREADY_EXISTS` guarded) →
+   * account-state gate → set `ctx.subject` + `ctx.oauth` → seed channel state →
+   * fall through to the shared login tail exactly like any other login.
    */
-  protected resolveAccept(_ctx: InviteWfCtx): NonNullable<InviteWfCtx["accept"]> | Promise<NonNullable<InviteWfCtx["accept"]>>;
+  proveControl(ctx: AuthWfCtx): Promise<undefined>;
   /**
-   * Resolve the cancellation policy (whether `auth.cancelInvite` is allowed).
-   * Override to disable hard-delete per-tenant. Sync/async friendly.
+   * login.flow — `wfid = '<controller-prefix>/auth/login/flow'` once wired.
+   * `@Public()` on the body because the wf adapter dispatches the flow body
+   * on every `start()` / `resume()` call (anonymous login).
    */
-  protected resolveCancellation(_ctx: InviteWfCtx): NonNullable<InviteWfCtx["cancellation"]> | Promise<NonNullable<InviteWfCtx["cancellation"]>>;
+  loginFlow(): void;
   /**
-   * Resolve the audit policy (whether invite.* audit events fire). Override
-   * to route audit-log emission per-tenant. Sync/async friendly.
+   * invite.start — admin-phase + anonymous magic-link accept-tail. Admin
+   * steps are arbac-evaluated (no `@Public()` on them); accept-tail steps are
+   * all `@Public()` (anonymous resume). The body itself is `@Public()` so the
+   * wf adapter can dispatch start/resume on anonymous magic-link clicks.
    */
-  protected resolveAudit(_ctx: InviteWfCtx): NonNullable<InviteWfCtx["audit"]> | Promise<NonNullable<InviteWfCtx["audit"]>>;
+  inviteFlow(): void;
   /**
-   * 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.
+   * recovery.flow — OTP-via-email reset. `@Public()` on the body because
+   * anonymous users start recovery.
    */
-  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>;
+  recoveryFlow(): void;
   /**
-   * 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.
+   * change-password.flow — authenticated self-service "change my password".
    *
-   * 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.
-   */
-  prepareConsents(ctx: InviteWfCtx): undefined | Promise<undefined>;
-  inviteFlow(): void;
-  reInviteFlow(): void;
-  cancelInviteFlow(): void;
-  init(ctx: InviteWfCtx): undefined | Promise<undefined>;
-  prepareAvailableRoles(ctx: InviteWfCtx): Promise<undefined>;
-  selectSendMode(ctx: InviteWfCtx): unknown;
-  adminInviteForm(ctx: InviteWfCtx): Promise<unknown>;
-  inferRolesStep(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(ctx: InviteWfCtx): Promise<unknown>;
-  checkPendingInvitation(ctx: InviteWfCtx): Promise<undefined>;
-  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 | Promise<undefined>;
-  freshLoginFinish(ctx: InviteWfCtx): undefined | Promise<undefined>;
-  autoLoginFinish(ctx: InviteWfCtx): Promise<undefined>;
-  cancelInvite(ctx: InviteWfCtx): Promise<unknown>;
-  private abort;
-  private loadUserOrNull;
-  private emitAudit;
-}
-//#endregion
-//#region src/workflows/default-workflows.d.ts
-declare class DefaultLoginWorkflow extends LoginWorkflow {
-  constructor(users: UserService, auth: AuthCredential, authOpts: AuthOpts, consentStore: ConsentStore);
-}
-declare class DefaultInviteWorkflow extends InviteWorkflow {
-  constructor(users: UserService, auth: AuthCredential, authOpts: AuthOpts, consentStore: ConsentStore);
-}
-declare class DefaultRecoveryWorkflow extends RecoveryWorkflow {
-  constructor(users: UserService, auth: AuthCredential, authOpts: AuthOpts, consentStore: ConsentStore);
+   * `@Public()` on the body lets the wf adapter dispatch start/resume (mirrors
+   * the other flows); the FLOW itself is NOT public — `init-change-password` is
+   * arbac-gated (`auth:change-password`) and binds `ctx.subject` from the
+   * session, so an unauthenticated / unauthorized caller is rejected at the
+   * first step. Customers forbid the feature (e.g. SSO-only orgs) by denying
+   * the `change-password` action — there is no on/off opts flag.
+   *
+   * NOT in `DEFAULT_AUTH_WORKFLOWS` — it must be reached via a GUARDED trigger
+   * route (see `AuthController.changePassword`), never the public
+   * `/auth/trigger`.
+   */
+  changePasswordFlow(): void;
+  /**
+   * add-mfa.flow — authenticated self-service "Manage two-factor
+   * authentication" (add / change / remove). Same gating model as
+   * change-password: NOT `@Public()` — `init-add-mfa` is arbac-gated
+   * (`auth.add-mfa` / `self`) and binds `ctx.subject` from the session, so an
+   * unauthenticated / unauthorized caller is rejected at the first step. NOT in
+   * `DEFAULT_AUTH_WORKFLOWS` — reached only via the GUARDED trigger route
+   * (`AuthController.addMfa`), never the public `/auth/trigger`.
+   *
+   * Shape:
+   * 1. `init-add-mfa` — bind subject, resolve the FULL transport set + the
+   *    un-enrolled `candidates`, mark `stepUpRequired` when the user already has
+   *    ≥1 confirmed factor, and put the enrol forms in `'manage'` mode.
+   * 2. `prepare-locked-mfa-transports` — resolve which factors the consumer
+   *    forbids changing (handle-bound email/phone).
+   * 3. STEP-UP (only when `stepUpRequired`): re-verify identity before any
+   *    change — `mfaStepUpLoop` challenges an EXISTING factor when one is still
+   *    challengeable (`stepUpMode==='mfa'`), else `manage-password-reauth` falls
+   *    back to the account password (`stepUpMode==='password'`). On success
+   *    `manage-stepup-done` swaps off the encapsulated start onto the durable
+   *    `store` strategy (server-anchored, replay-resistant; mirrors login's
+   *    swap-after-credentials).
+   * 4. `manage-menu` (only when `stepUpRequired`) — pick add / change / remove +
+   *    target; pre-seeds `mfaEnroll.method` for add/change.
+   * 5. Route: `confirm-remove-mfa` for remove; otherwise the REUSED enrol trio
+   *    (`enroll-pick-method` → `enroll-address` / `enroll-totp-qr` →
+   *    `enroll-confirm`). A zero-MFA user skips step-up + menu and lands on the
+   *    enrol picker directly (the first-time opt-in path).
+   * 6. `finish-add-mfa` — added / changed / removed / cancelled / nothing terminal.
+   *    The user KEEPS their session (no token re-issue).
+   */
+  addMfaFlow(): void;
+  /**
+   * signup.flow — verify-first self-signup. `@Public()` on the body (anonymous).
+   * NOT arbac-gated at the flow level: the `resolveSignupPolicy().allowSignup`
+   * gate is the on/off switch (default OFF — invite-only is the safe default).
+   * Reachable via the public `/auth/trigger` (add `auth/signup/flow` to the
+   * controller's `DEFAULT_AUTH_WORKFLOWS`).
+   *
+   * Shape = recovery's email→OTP front + invite's create→set-password→activate→
+   * auto-login tail, so it reuses `pincodeSendCheckPair`, `passwordPhaseSchema`,
+   * `prepare-consents` + `consentsPersistTailSchema`, `activate-user`, and
+   * `finalize-auto-login` verbatim. The account-existence check is deferred to
+   * `signup-create-user` (POST-OTP) so account existence never leaks on the
+   * wire — every email gets an identical OTP pause regardless of whether it is
+   * already registered.
+   */
+  signupFlow(): void;
 }
 //#endregion
 //#region src/workflows/auth-email-outlet.d.ts
@@ -2240,12 +3079,31 @@ interface AuthEmailOutletDeps {
  */
 declare function createAuthEmailOutlet(deps: AuthEmailOutletDeps): WfOutlet;
 //#endregion
-//#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;
+//#region src/audit/index.d.ts
+/**
+ * Audit event emitter — used by `AuthWorkflow`'s audit-login step (and
+ * future recovery / invite audit steps) to fan out login.success and similar
+ * events to consumer-supplied sinks (DB table, log file, Kafka topic).
+ *
+ * Aoothjs ships no concrete sink. Workflow subclasses override the
+ * `audit(event)` protected method to wire their preferred sink; when not
+ * overridden the workflow's default implementation is a no-op.
+ */
+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/flow`). */
+  workflow?: string;
+  /** Source IP (when the workflow could resolve one). */
+  ip?: string;
+  /** User-agent header. */
+  userAgent?: string;
+  /** Free-form payload — `method`, `tenantId`, etc. */
+  [key: string]: unknown;
+}
+interface AuditEmitter {
+  emit(event: AuditEvent): Promise<void> | void;
 }
-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 };
+export { ADD_MFA_WORKFLOW, AUTH_CODE_STORE_TOKEN, type AuditEmitter, type AuditEvent, type AuthBindings, type AuthContext, AuthController, type AuthDeliveryPayload, type AuthEmailEvent, type AuthEmailKind, type AuthEmailOutletDeps, AuthGuarded, type AuthLoginResponse, type AuthLogoutBody, type AuthOkResponse, type AuthOptions, type AuthRefreshBody, type AuthSmsEvent, type AuthSmsKind, type AuthWfCompletionState, type AuthWfConsentsState, type AuthWfCtx, type AuthWfMfaEnrollState, type AuthWfOAuthState, type AuthWfPasswordUiState, type AuthWfPincodeUiState, AuthWorkflow, type AuthWorkflowOpts, AuthorizeController, AuthorizeRuntime, type BuildMagicLinkUrl, CHANGE_PASSWORD_WORKFLOW, CLIENT_REDIRECT_POLICY_TOKEN, type ConcurrencyLimitOptions, type ConnectedAccount, type ConsentDescriptor, type ConsentDescriptorLike, type ConsentEvent, ConsentStore, DEFAULT_AUTH_WORKFLOWS, type EmailSender, type EnrichedSession, FEDERATED_IDENTITY_STORE_TOKEN, type IssueResult, type LoginRedirect, type MfaSummary, type MfaTransport, OAUTH_CSRF_COOKIE, OAuthController, OAuthRuntime, PENDING_AUTHORIZATION_STORE_TOKEN, Public, RESERVED_USER_KEYS, type ResolvedAuthCookieConfig, type ResolvedAuthOptions, type ResolvedAuthWorkflowOpts, type SessionEnricher, SessionEnricherProvider, type SessionInfo, SessionsController, type SmsSender, type SsoProvider, type TAuthMeta, UserId, WfTrigger, type WfTriggerOpts, WfTriggerProvider, authGuardInterceptor, buildInviteAlreadyAcceptedEnvelope, createAuthEmailOutlet, deriveWfStateSecret, generateMagicLinkToken, getAuthMate, isSafeRelativeRedirect, oauthCsrfCookieAttrs, parseInviteRoles, resolveOAuthRedirect, stripReservedUserKeys, useAuth };