@aooth/auth-moost 0.1.21 → 0.1.23

package/dist/index.d.mts

@@ -1178,6 +1178,16 @@ interface AuthWfMfaEnrollState {
    */
   mode?: "required" | "optional" | "manage";
   done?: boolean;
+  /**
+   * Set by `enroll-send` when `resolveEnrollPreConfirmed` vouches that the
+   * staged sms/email address is verified-by-construction (e.g. the invited
+   * email the user just proved by redeeming the magic link delivered to it).
+   * `enroll-send` then skips the pincode dispatch and `enroll-confirm` runs
+   * its write-on-confirm tail with no code-entry pause. Server-only (decided
+   * by the resolver, never read from the wire); never set for TOTP —
+   * possession of an authenticator cannot be proven by construction.
+   */
+  preConfirmed?: 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
@@ -1580,12 +1590,40 @@ interface AuthWfAddMfaState {
    * replay-resistant). Gates the one-time swap + the management menu.
    */
   stepUpDone?: boolean;
+  /**
+   * The user has explicitly consented to the step-up pincode dispatch —
+   * either by submitting `manage-stepup-confirm`'s "we'll send a code to
+   * ma•••@x" notice, or by picking a factor on `select-2fa` (choosing
+   * "Email (ma•••@x)" and submitting IS the consent). Gates the
+   * `manage-stepup-confirm` pause so opening the manage dialog never
+   * dispatches a code as a side effect. Also set when
+   * `resolveStepUpConfirmBeforeSend` opts the deployment out of the pause.
+   * Server-only; sms/email step-up only (TOTP dispatches nothing).
+   */
+  stepUpConfirmed?: boolean;
   /** The management action the user picked on the menu. */
   action?: "add" | "replace" | "remove";
   /** The transport the chosen `action` applies to. */
   target?: MfaTransport;
   /** Set by `confirm-remove-mfa` so `finish-add-mfa` can report which factor was removed. */
   removed?: MfaTransport;
+  /**
+   * Removing a factor is currently impossible: the user has exactly one
+   * confirmed (policy-allowed) factor and `mfaPolicy.mode === 'required'`.
+   * Computed by `manage-menu` before its pause and mirrored to
+   * `public.manage.removeBlocked` so `ManageMfaForm` omits the Remove option
+   * (and explains why) instead of offering an operation that can never
+   * succeed. Re-checked server-side in `manage-menu` + `confirm-remove-mfa`.
+   */
+  removeBlocked?: boolean;
+  /**
+   * Set by `confirm-remove-mfa` when it arrives in an un-removable state
+   * (stale/crafted route — the menu filters these): the step aborts to the
+   * `finish-add-mfa` terminal with a reason-specific message instead of
+   * pausing on a form whose only submit re-throws the same guard error
+   * (a dead-end loop, since the manage forms hide their built-in cancel).
+   */
+  blocked?: "last-required-factor" | "method-locked";
 }
 /**
  * Self-signup flow state. Populated by `init-signup` (policy from
@@ -1684,12 +1722,15 @@ interface AuthWfPublicState {
   mfaEnroll?: Pick<AuthWfMfaEnrollState, "method" | "mode" | "availableTransports" | "secret" | "uri">;
   /**
    * Mirrors the manage-MFA menu inputs — the un-enrolled transports the user
-   * can Add and the locked transports to omit from Change/Remove. The enrolled
-   * method list the menu cross-references is `public.mfa.enrolledMethods`.
+   * can Add, the locked transports to omit from Change/Remove, and the
+   * `removeBlocked` flag that omits the Remove option for the last confirmed
+   * factor under a `required` policy. The enrolled method list the menu
+   * cross-references is `public.mfa.enrolledMethods`.
    */
   manage?: {
     candidates?: MfaTransport[];
     locked?: MfaTransport[];
+    removeBlocked?: boolean;
   };
   /** Mirrors `ctx.defaults` — prefill source for the recovery email field. */
   defaults?: {
@@ -1878,7 +1919,8 @@ interface AuthWorkflowOpts {
     enrollConfirm?: TAtscriptAnnotatedType; /** Manage-MFA menu (Add / Change / Remove) shown after step-up. */
     manageMfa?: TAtscriptAnnotatedType; /** Confirm-removal pause for the manage-MFA "Remove" action. */
     removeMfaConfirm?: TAtscriptAnnotatedType; /** Password re-auth — step-up fallback when no factor is MFA-challengeable. */
-    passwordReauth?: TAtscriptAnnotatedType;
+    passwordReauth?: TAtscriptAnnotatedType; /** Step-up dispatch consent — "we'll send a code to ma•••@x" notice before the step-up pincode send. */
+    stepUpConfirm?: TAtscriptAnnotatedType;
     select2fa?: TAtscriptAnnotatedType;
     mfaCode?: TAtscriptAnnotatedType;
     pincode?: TAtscriptAnnotatedType;
@@ -1934,6 +1976,7 @@ interface ResolvedAuthWorkflowOpts {
     manageMfa: TAtscriptAnnotatedType;
     removeMfaConfirm: TAtscriptAnnotatedType;
     passwordReauth: TAtscriptAnnotatedType;
+    stepUpConfirm: TAtscriptAnnotatedType;
     select2fa: TAtscriptAnnotatedType;
     mfaCode: TAtscriptAnnotatedType;
     pincode: TAtscriptAnnotatedType;
@@ -2201,6 +2244,64 @@ declare class AuthWorkflow {
    * Reached from login.flow.
    */
   protected resolveEnrollment(_ctx: AuthWfCtx): NonNullable<AuthWfCtx["enrollment"]> | Promise<NonNullable<AuthWfCtx["enrollment"]>>;
+  /**
+   * Vouch that an MFA-enrolment address is verified-by-construction, skipping
+   * the pincode round-trip: `enroll-send` sends nothing and `enroll-confirm`
+   * writes the confirmed factor (+ `verifiedEmail` for email) with no
+   * code-entry pause. Asked once per dispatch with the staged transport +
+   * normalized address (ctx-first, extra positional args — same convention as
+   * `resolveOtpDisclosure`).
+   *
+   * Default `false` — every enrolment proves its address. The canonical
+   * override is the invite-accept case, where the user is inside the flow
+   * only because they redeemed a magic link delivered to that exact address
+   * minutes earlier (the same proof `activate-user` trusts to write
+   * `account.verifiedEmail`):
+   *
+   * ```ts
+   * protected resolveEnrollPreConfirmed(ctx: AuthWfCtx, method: MfaTransport, address: string) {
+   *   return !!ctx.accept && method === "email" && address === ctx.email;
+   * }
+   * ```
+   *
+   * Keep the equality check — the proof transfers ONLY to the address the
+   * magic link was delivered to; vouching for a different address the user
+   * typed would confirm an unproven inbox. Never asked for TOTP.
+   */
+  protected resolveEnrollPreConfirmed(_ctx: AuthWfCtx, _method: MfaTransport, _address: string): boolean | Promise<boolean>;
+  /**
+   * Pin the enrolment address for an sms/email transport — the policy seam
+   * for deployments whose factor must be BOUND to an account record (e.g.
+   * staff MFA locked to the work mailbox so portal access dies with it at
+   * offboarding; a free-text form would let a self-service swap to a personal
+   * inbox defeat that control entirely). Asked by `enroll-address` BEFORE its
+   * form renders, with the staged transport (ctx-first, extra positional arg —
+   * same convention as `resolveEnrollPreConfirmed`).
+   *
+   * Returning a string stages it as the enrolment address (normalized via
+   * `normalizeMfaAddress`; the free-text form is SKIPPED — the same staging
+   * seam consumer pre-seeding uses, so the user is never shown a form whose
+   * only valid input is one known string). `'collect'` (the default) keeps
+   * the free-text form. A pinned address composes with the rest of the trio
+   * machinery untouched: `enroll-send` dispatches the pincode to it, and
+   * `resolveEnrollPreConfirmed` may vouch it (a deployment pinning to a
+   * verified-by-construction address gets the no-code path for free).
+   *
+   * ```ts
+   * protected async resolveEnrollAddress(ctx: AuthWfCtx, method: MfaTransport) {
+   *   if (method !== "email") return "collect";
+   *   const user = await this.users.getUser(ctx.subject!);
+   *   return (user as { email?: string }).email ?? "collect";
+   * }
+   * ```
+   *
+   * The returned address is trusted as-is (no `validateMfaAddress` pass) —
+   * the deployment is authoritative for its own records. An empty/blank
+   * return falls back to `'collect'`. For nuanced RULES on a user-typed
+   * address (domain allowlists, record comparisons) override the ctx-first
+   * {@link validateMfaAddress} instead.
+   */
+  protected resolveEnrollAddress(_ctx: AuthWfCtx, _method: MfaTransport): string | "collect" | Promise<string | "collect">;
   /**
    * Resolve the finalize policy. Reached from login.flow. `auditLogin` is
    * dropped from the shape per §2 — audit moved out of the workflow layer.
@@ -2280,6 +2381,33 @@ declare class AuthWorkflow {
    * ```
    */
   protected resolveLockedMfaTransports(_ctx: AuthWfCtx): MfaTransport[] | Promise<MfaTransport[]>;
+  /**
+   * Whether the manage-MFA step-up must collect explicit consent BEFORE
+   * dispatching its sms/email pincode (the `manage-stepup-confirm` pause:
+   * "To continue, we will send a verification code to ma•••@x"). Default
+   * `true` — nothing should email/text the user as a side effect of opening
+   * a manage dialog: a user who opened it by mistake (or just to look)
+   * closes it with zero codes consumed, no resend cooldown burnt. Override
+   * to `false` to restore the zero-click dispatch (the code is already in
+   * flight when the first form renders). Never asked for TOTP step-up
+   * (nothing is dispatched) and not consulted by the login flow (its
+   * challenge is mid-authentication, where zero-click is the norm).
+   */
+  protected resolveStepUpConfirmBeforeSend(_ctx: AuthWfCtx): boolean | Promise<boolean>;
+  /**
+   * What the user's authenticator app shows as the ACCOUNT half of
+   * "issuer: account" for a TOTP enrolment (the issuer half is
+   * `resolveMfaPolicy().issuer` / `opts.totpIssuer`). Cosmetic only — never
+   * used for lookup — but it is how a user with several entries tells
+   * accounts apart, and it is encoded into the `otpauth://` URI at
+   * secret-provisioning time, so it lives in the authenticator FOREVER
+   * (re-labeling requires re-enrolment). Default prefers a human-readable
+   * identifier the flow already carries (`ctx.email` — invite/recovery/
+   * signup) and otherwise loads the user's `username`; the stable-uuid
+   * `ctx.subject` is the last resort. Override for a richer label (display
+   * name, tenant-qualified email, …).
+   */
+  protected resolveTotpAccountLabel(ctx: AuthWfCtx): string | Promise<string>;
   /**
    * Resolve the channel-OTP disclosure copy rendered beneath the email/phone
    * input on `AskEmailForm` / `AskPhoneForm`. Reached from login.flow Phase 3.
@@ -2536,10 +2664,30 @@ declare class AuthWorkflow {
   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`.
+   * recipient. Reached only through {@link mintAndSendEnrollPincode}; kept
+   * separate as the delivery-only override seam.
    */
   protected sendEnrollPincode(ctx: AuthWfCtx, address: string, code: string): Promise<void>;
+  /**
+   * The single enrol-dispatch implementation: mint a fresh pin, arm the
+   * resend cooldown + the code-length form hint, and deliver the code.
+   * Shared by `enrollSend` (initial dispatch) and the resend arm inside
+   * `enrollConfirm`, so the arming policy cannot drift between first send
+   * and resend.
+   */
+  private mintAndSendEnrollPincode;
+  /**
+   * Idempotent TOTP secret provisioning into wf-state ONLY (the QR renders
+   * from `public.mfaEnroll.secret/uri`; the user record is written on confirm
+   * — write-on-confirm). The single implementation behind BOTH provisioning
+   * sites — `enroll-pick-method`'s auto-pick/picker tail and `enroll-totp-qr`
+   * (covers the manage add/change path where the picker is skipped) — so the
+   * account label baked into the `otpauth://` URI cannot drift between them.
+   * The label comes from {@link resolveTotpAccountLabel} (human-readable
+   * default); blank falls back to the subject uuid so the URI always carries
+   * SOME account discriminator.
+   */
+  private provisionTotpSecret;
   /**
    * Drop the per-enrolment scratch fields (the `mfaEnroll` provisioning fields +
    * the pincode timers/`sentTo`) off ctx — the shared teardown used by the
@@ -2557,8 +2705,24 @@ declare class AuthWorkflow {
    * or `undefined` when valid. Email must look like an email; SMS is permissive
    * E.164-ish (normalized by {@link normalizeMfaAddress}). Override for stricter
    * (e.g. libphonenumber) validation.
+   *
+   * Ctx-first and async-capable, so record-based rules need no ctx-stash
+   * workaround — an override can load the account and compare directly
+   * (e.g. domain-allowlist the typed inbox, or require it to match a
+   * record field). To PIN the address outright — never show the free-text
+   * form at all — use {@link resolveEnrollAddress} instead; this hook is for
+   * nuanced rules on what the user typed.
+   *
+   * ```ts
+   * protected async validateMfaAddress(ctx: AuthWfCtx, method: MfaTransport, value: string) {
+   *   if (method === "email" && !value.trim().toLowerCase().endsWith("@corp.example")) {
+   *     return "Use your corporate email address";
+   *   }
+   *   return super.validateMfaAddress(ctx, method, value);
+   * }
+   * ```
    */
-  protected validateMfaAddress(method: MfaTransport, value: string): string | undefined;
+  protected validateMfaAddress(_ctx: AuthWfCtx, method: MfaTransport, value: string): string | undefined | Promise<string | undefined>;
   /**
    * Light normalization of a validated MFA address before it is stored. Default:
    * trims, and strips spacing/punctuation from SMS numbers while KEEPING the
@@ -2826,10 +2990,17 @@ declare class AuthWorkflow {
   /**
    * Terminal for the manage-MFA flow. The user KEEPS their current session (no
    * re-issue, no cookies) — a plain data finish. Outcomes, in priority order:
-   * removed → changed (`replace` + done) → added (done) → nothing-available
-   * (zero candidates, never had to step-up) → cancelled.
+   * removed → changed (`replace` + done) → added (done) → blocked
+   * (un-removable operation aborted by `confirm-remove-mfa`) →
+   * nothing-available (zero candidates, never had to step-up) → cancelled.
    */
   finishAddMfa(ctx: AuthWfCtx): undefined;
+  /**
+   * `finish-add-mfa`'s envelope construction, extracted pure so the outcome
+   * priority (removed → changed → added → blocked → nothing-available →
+   * cancelled) is unit-testable without a wf event context.
+   */
+  protected buildAddMfaFinishEnvelope(ctx: AuthWfCtx): WfFinished;
   /**
    * Resolve which transports the user may NOT change/remove via the manage flow
    * (calls {@link resolveLockedMfaTransports}) and write them to
@@ -2844,6 +3015,22 @@ declare class AuthWorkflow {
    * encapsulated when no durable store is wired (the registry default).
    */
   manageStepUpDone(ctx: AuthWfCtx): undefined;
+  /**
+   * Manage-MFA step-up consent — pauses on `StepUpConfirmForm` ("To continue,
+   * we will send a verification code to ma•••@x") BEFORE `pincode-send`
+   * dispatches the step-up code, so opening the manage dialog never consumes
+   * a code send as a side effect. Fires only on the auto-picked paths (single
+   * factor, or default factor) — an explicit `select-2fa` pick already
+   * counts as consent (`select2fa` sets `stepUpConfirmed`). `Continue`
+   * consents and the SAME engine pass mints + sends; `useDifferentMethod`
+   * re-opens the picker; `cancel` aborts with nothing dispatched (the
+   * schema's `{ break: aborted }` right after this step keeps the pair from
+   * sending the declined code). Gated by {@link resolveStepUpConfirmBeforeSend}
+   * (default on) — an opt-out marks consent and falls straight through.
+   */
+  manageStepUpConfirm(ctx: AuthWfCtx): undefined | Promise<undefined>;
+  /** `manage-stepup-confirm` tail — opt-out fall-through or the consent pause. */
+  private applyStepUpConfirm;
   /**
    * Manage-MFA password re-auth — the step-up FALLBACK when the user's only
    * confirmed factor(s) are of kinds the policy no longer allows, so nothing is
@@ -2857,6 +3044,15 @@ declare class AuthWorkflow {
    * subject), and `verifyPassword` is the same check `changePassword` enforces.
    */
   managePasswordReauth(ctx: AuthWfCtx): Promise<undefined>;
+  /**
+   * The keep-at-least-one rule: removing the user's LAST confirmed factor under
+   * a `required` policy can never succeed. The single source for the predicate
+   * `manage-menu` mirrors into `addMfa.removeBlocked` (to drop the Remove option)
+   * AND `confirm-remove-mfa` re-checks before its pause (defence in depth) — so
+   * a policy change (e.g. "keep at least two", or a backup-codes exception)
+   * lands in one place, not two copies that can drift.
+   */
+  private isLastRequiredFactor;
   /**
    * Manage-MFA menu — pauses on `ManageMfaForm` and routes the chosen
    * `operation` (`add:<t>` / `replace:<t>` / `remove:<t>`). Only reached when
@@ -2869,8 +3065,13 @@ declare class AuthWorkflow {
   /**
    * Manage-MFA remove confirmation. Pauses on `RemoveMfaConfirmForm`; the
    * 'Remove' submit performs the removal, 'Cancel' aborts. Re-checks the locked
-   * set (defence in depth) and blocks removing the LAST confirmed factor when
-   * the policy mode is `required` (you must keep at least one).
+   * set and the keep-at-least-one rule (LAST confirmed factor under a
+   * `required` policy) BEFORE the pause — and an un-removable state aborts to
+   * the `finish-add-mfa` terminal (reason on `addMfa.blocked`) instead of
+   * pausing: `manage-menu` filters these operations out, so arriving here
+   * blocked means a stale/crafted route, and a retryable form whose only
+   * submit re-throws the same guard would be a dead-end loop (the manage
+   * forms hide their built-in cancel — the host owns it).
    */
   confirmRemoveMfa(ctx: AuthWfCtx): Promise<undefined>;
   askChannel(ctx: AuthWfCtx, channel: "email" | "phone"): Promise<unknown>;
@@ -2952,15 +3153,43 @@ declare class AuthWorkflow {
    */
   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>;
+   * Unified MFA-enrol phase 2 (collect sms/email address). Not invoked for
+   * totp. Asks {@link resolveEnrollAddress} FIRST — a deployment that pins
+   * the address (factor bound to an account record) stages it here and the
+   * free-text form never renders; this single call site covers every trio
+   * path (picker, auto-pick, manage add/replace pre-seed), and `enroll-send`
+   * dispatches to the pinned address in the same engine pass. Otherwise
+   * (`'collect'`) handles `skip` (opt-in) / `cancel` (manage) /
+   * `useDifferentMethod`, validates the typed address server-side via the
+   * ctx-first {@link validateMfaAddress} (the client `@ui.form.validate`
+   * hint is advisory), then STAGES the candidate value in wf-state
+   * (`m.address`) — the user record is written only on confirm
+   * (write-on-confirm), so an ADD leaves no partial row and a REPLACE keeps
+   * the old confirmed value live until the new code verifies in
+   * `enroll-confirm`. Collection ONLY: the pincode dispatch lives in
+   * `enroll-send` (same engine pass, no extra round-trip), so a consumer
+   * pre-seeding `mfaEnroll.address` — which skips this whole step via its
+   * schema condition — still gets exactly one code.
+   */
+  enrollAddress(ctx: AuthWfCtx): undefined | Promise<undefined>;
+  /**
+   * `enroll-address` tail — stage a pinned address, or run the free-text
+   * collect pause (skip/cancel/useDifferentMethod triage + ctx-first
+   * validation + write-on-confirm staging).
+   */
+  private collectEnrollAddress;
+  /**
+   * Unified MFA-enrol dispatch (sms/email only) — the trio's ONLY pincode
+   * send. A separate step (the canonical "send if no pin" gate, mirroring
+   * `pincode-send`) so both address paths share one dispatch site: collected
+   * by `enroll-address`, or pre-seeded by a consumer (which skips
+   * `enroll-address` entirely — previously skipping the dispatch with it and
+   * stranding the user on a code form no code was sent for). Asks
+   * `resolveEnrollPreConfirmed` first: a verified-by-construction address
+   * (e.g. the invite email the magic link just proved) skips the round-trip —
+   * `enroll-confirm` then writes the factor without pausing.
+   */
+  enrollSend(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
@@ -2985,6 +3214,16 @@ declare class AuthWorkflow {
    * a fresh row for an ADD.
    */
   enrollConfirm(ctx: AuthWfCtx): Promise<undefined>;
+  /**
+   * `enroll-confirm`'s write-on-confirm tail (uniform for ADD and REPLACE, all
+   * transports): the staged value (sms/email `address`, totp `secret`) is now
+   * proven — by a verified pincode/TOTP code, or vouched by
+   * `resolveEnrollPreConfirmed` — so upsert it as confirmed. `addMfaMethod`
+   * replaces any row of the same name, so a REPLACE atomically swaps in the
+   * new value with no pre-confirm clobber window, and an ADD creates the row
+   * fresh.
+   */
+  private confirmEnrolledFactor;
   /**
    * Promote a freshly-confirmed channel into its login-handle column so future
    * login + recovery resolve the account by it (`findByHandle`). Runs once,
@@ -3408,12 +3647,19 @@ declare class AuthWorkflow {
    * 3. STEP-UP (only when `stepUpRequired`): re-verify identity before any
    *    change — `mfaStepUpLoop` challenges an EXISTING factor when one is still
    *    challengeable (`stepUpMode==='mfa'`), else `manage-password-reauth` falls
-   *    back to the account password (`stepUpMode==='password'`). On success
+   *    back to the account password (`stepUpMode==='password'`). The sms/email
+   *    challenge collects explicit consent (`manage-stepup-confirm`) BEFORE
+   *    dispatching its pincode — opening the dialog never sends a code as a
+   *    side effect (see `resolveStepUpConfirmBeforeSend`). On success
    *    `manage-stepup-done` swaps off the encapsulated start onto the durable
    *    `store` strategy (server-anchored, replay-resistant; mirrors login's
    *    swap-after-credentials).
    * 4. `manage-menu` (only when `stepUpRequired`) — pick add / change / remove +
-   *    target; pre-seeds `mfaEnroll.method` for add/change.
+   *    target; pre-seeds `mfaEnroll.method` for add/change. Un-offerable
+   *    operations never render: locked transports drop their Change/Remove
+   *    options, and the LAST factor under a `required` policy drops Remove
+   *    (`removeBlocked`) — `confirm-remove-mfa` aborts to the finish terminal
+   *    if a blocked remove arrives anyway (no retryable dead-end form).
    * 5. Route: `confirm-remove-mfa` for remove; otherwise the REUSED enrol trio
    *    (`enroll-pick-method` → `enroll-address` / `enroll-totp-qr` →
    *    `enroll-confirm`). A zero-MFA user skips step-up + menu and lands on the