@aooth/auth-moost 0.1.1

package/dist/index.d.mts

@@ -0,0 +1,1279 @@
+import { AuthContext, AuthContext as AuthContext$1, AuthCredential, AuthEmailEvent, AuthEmailKind, AuthEmailKind as AuthEmailKind$1, AuthSmsEvent, AuthSmsKind, AuthSmsKind as AuthSmsKind$1, BuildMagicLinkUrl, BuildMagicLinkUrl as BuildMagicLinkUrl$1, EmailSender, EmailSender as EmailSender$1, IssueResult, IssueResult as IssueResult$1, SmsSender, generateMagicLinkToken } from "@aooth/auth";
+import * as _$_wooksjs_event_core0 from "@wooksjs/event-core";
+import { TCookieAttributesInput } from "@wooksjs/event-http";
+import { Mate, TInterceptorDef, TMateParamMeta, TMoostMetadata } from "moost";
+import { MoostWf, WfOutlet, WfOutletTokenConfig, WfStateStrategy } from "@moostjs/event-wf";
+import { TrustedDeviceRecord, UserCredentials, UserService } from "@aooth/user";
+import { TAtscriptAnnotatedType } from "@atscript/typescript/utils";
+
+//#region src/auth.config.d.ts
+/** Resolved cookie attributes. Same shape is used for both access + refresh. */
+interface ResolvedAuthCookieConfig {
+  name: string;
+  secure: boolean;
+  sameSite: "lax" | "strict" | "none";
+  httpOnly: boolean;
+  path: string;
+  domain?: string;
+}
+interface AuthOptions {
+  cookie?: Partial<ResolvedAuthCookieConfig>;
+  /**
+   * Refresh-cookie attribute overrides. Defaults to `name='aooth_refresh'`,
+   * `path='/auth/refresh'`; inherits `secure/sameSite/httpOnly/domain` from
+   * the access cookie unless overridden here.
+   */
+  refreshCookie?: Partial<ResolvedAuthCookieConfig>;
+  /** Read the session token from a cookie. Default: `true`. */
+  enableCookie?: boolean;
+  /** Read the session token from `Authorization: Bearer ...`. Default: `true`. */
+  enableBearer?: boolean;
+}
+/**
+ * Fully-resolved options carried by `authGuardInterceptor(opts)` through the
+ * HTTP event slot. `useAuth().options` returns this shape so consumers can type
+ * variables without re-resolving defaults.
+ */
+interface ResolvedAuthOptions {
+  cookie: ResolvedAuthCookieConfig;
+  /**
+   * Narrow `path: '/auth/refresh'` ensures the refresh token only travels to
+   * the refresh endpoint. Transport attrs (`secure/sameSite/httpOnly/domain`)
+   * are inherited from {@link cookie} unless overridden.
+   */
+  refreshCookie: ResolvedAuthCookieConfig;
+  enableCookie: boolean;
+  enableBearer: boolean;
+}
+//#endregion
+//#region src/auth.guard.d.ts
+/**
+ * `GUARD`-priority interceptor factory that authenticates incoming requests.
+ *
+ * Returns a configured `TInterceptorDef`. Each invocation captures its own
+ * resolved options and stashes them onto the HTTP event context's
+ * `authOptionsKey` slot so `useAuth()` (and the workflows that depend on it)
+ * can read the same transport config.
+ *
+ * Token extraction precedence: `Authorization: Bearer ...` wins over cookie
+ * when both transports are enabled. On `@Public()` routes a missing or
+ * invalid token leaves AuthContext as `null` and the handler runs anyway;
+ * on protected routes it throws `HttpError(401)`.
+ *
+ * Never auto-refreshes — refresh is a separate REST endpoint.
+ *
+ * No-ops on non-HTTP event contexts (workflow steps, CLI, WS messages). The
+ * guard reads tokens from HTTP headers/cookies; nothing to read elsewhere.
+ * Authorization for workflow steps is the step's own responsibility (e.g.
+ * an admin-only invite endpoint protects its outlet HTTP route, not the
+ * step handler).
+ */
+declare function authGuardInterceptor(opts?: AuthOptions): TInterceptorDef;
+/**
+ * Decorator-factory sugar for attaching `authGuardInterceptor(opts)` to a
+ * specific controller or method instead of globally. Equivalent to
+ * `@Intercept(authGuardInterceptor(opts))`.
+ */
+declare function AuthGuarded(opts?: AuthOptions): ClassDecorator & MethodDecorator;
+//#endregion
+//#region ../../node_modules/.pnpm/@wooksjs+event-wf@0.7.12_@prostojs+logger@0.4.3_@wooksjs+event-core@0.7.12_@wooksjs+eve_83c9b5cff779134c35c379089be157ae/node_modules/@wooksjs/event-wf/dist/index.d.ts
+interface WfFinishedResponse {
+  type: 'redirect' | 'data';
+  /** Redirect URL or response body */
+  value: unknown;
+  /** HTTP status code (default 200 for data, 302 for redirect) */
+  status?: number;
+  /** Cookies to set */
+  cookies?: Record<string, {
+    value: string;
+    options?: Record<string, unknown>;
+  }>;
+}
+/**
+ * Composable to set the completion response for a finished workflow.
+ *
+ * @example
+ * ```ts
+ * // Redirect after login
+ * useWfFinished().set({ type: 'redirect', value: '/dashboard' })
+ *
+ * // Return data
+ * useWfFinished().set({ type: 'data', value: { success: true } })
+ * ```
+ */
+//#endregion
+//#region src/auth.dto.d.ts
+/** POST /auth/refresh request body. Falls back to the refresh cookie when absent. */
+interface AuthRefreshBody {
+  refreshToken?: string;
+}
+/**
+ * Optional POST /auth/logout body. The refresh cookie's narrow `path:
+ * '/auth/refresh'` keeps the browser from sending it to `/auth/logout`, so
+ * token-style clients (or clients that want to revoke a paired refresh in the
+ * same call) submit it explicitly here.
+ */
+interface AuthLogoutBody {
+  refreshToken?: string;
+}
+/**
+ * POST /auth/refresh response body. Also returned by workflow finalize steps
+ * (e.g. `LoginWorkflow`) 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
+ * a silent refresh; the actual tokens travel only in cookies.
+ */
+interface AuthLoginResponse {
+  userId: string;
+  accessExpiresAt: number;
+  refreshExpiresAt?: number;
+  accessToken?: string;
+  refreshToken?: string;
+}
+/** POST /auth/logout response body. */
+interface AuthOkResponse {
+  ok: true;
+}
+//#endregion
+//#region src/auth.composables.d.ts
+interface AuthBindings {
+  getAuthContext<TClaims extends object = Record<string, unknown>>(): AuthContext$1<TClaims> | null;
+  /** @throws `HttpError(401)` if no `AuthContext` is present in the event. */
+  getUserId(): string;
+  isAuthenticated(): boolean;
+  /** @throws `HttpError(500)` when no `authGuardInterceptor(opts)` is on the chain. */
+  readonly options: ResolvedAuthOptions;
+  /** Same precedence as `authGuardInterceptor`: Bearer wins when both enabled. */
+  extractToken(): string | undefined;
+  writeCookies(issue: IssueResult$1): void;
+  clearCookies(): void;
+  buildLoginResponse(userId: string, issue: IssueResult$1): AuthLoginResponse;
+  buildFinishedCookies(issue: IssueResult$1): WfFinishedResponse["cookies"];
+  /** Build cookie attrs from the resolved access-cookie config, with optional overrides. */
+  cookieAttrs(extra?: TCookieAttributesInput): TCookieAttributesInput;
+}
+/**
+ * Composable for accessing the current event's auth state + transport helpers.
+ *
+ * `defineWook` memoizes the bindings object per event so multiple calls share
+ * one closure. Identity bindings (`getAuthContext`/`getUserId`/`isAuthenticated`)
+ * read the `authContextKey` slot populated by `authGuardInterceptor`. The
+ * remaining closures read the `authOptionsKey` slot stashed by that same
+ * interceptor; calling them outside an HTTP-or-HTTP-parented event throws
+ * `HttpError(500)` loudly — that's a configuration error, not a runtime
+ * fallback case.
+ */
+declare const useAuth: _$_wooksjs_event_core0.WookComposable<AuthBindings>;
+//#endregion
+//#region src/auth.decorator.d.ts
+/**
+ * Marks a route or controller as fully public — opts out of BOTH
+ * authentication (auth-moost's bearer guard) AND authorization
+ * (arbac-moost's `arbacAuthorizeInterceptor`).
+ *
+ * `authGuardInterceptor` still runs on `@Public()` handlers — it populates the
+ * AuthContext when a valid credential is presented, but does NOT throw when
+ * the token is missing or invalid (the handler runs with a `null` AuthContext).
+ * The ARBAC interceptor short-circuits entirely via its `isPublic` check.
+ *
+ * Method-level decoration overrides class-level.
+ */
+declare const Public: () => ClassDecorator & MethodDecorator;
+/**
+ * Resolves the authenticated user's id (string) for a handler parameter.
+ *
+ * Delegates to `useAuth().getUserId()`, which throws `HttpError(401)` when no
+ * `AuthContext` is present in the event. There is no `@User()` counterpart —
+ * `AuthContext` is credential context, not user profile data, and this library
+ * does not own a user profile type.
+ */
+declare const UserId: () => ParameterDecorator & PropertyDecorator;
+//#endregion
+//#region src/auth.mate.d.ts
+/**
+ * Auth metadata fields written by `@Public()` and read by `authGuardInterceptor`.
+ * Merged into `TMoostMetadata` so other moost-aware tooling sees them.
+ */
+interface TAuthMeta {
+  authPublic?: boolean;
+}
+declare module "moost" {
+  interface TMoostMetadata extends TAuthMeta {}
+}
+type AuthMate = Mate<TMoostMetadata & {
+  params: TMateParamMeta[];
+}, TMoostMetadata & {
+  params: TMateParamMeta[];
+}>;
+declare function getAuthMate(): AuthMate;
+//#endregion
+//#region src/auth.controller.d.ts
+/** Workflows allowed by the bundled `/auth/trigger` endpoint. Subclasses override `triggerWf()` to extend. */
+declare const DEFAULT_AUTH_WORKFLOWS: readonly ["auth.login", "auth.recovery", "auth.invite"];
+/**
+ * Public REST endpoints for credential management. Four endpoints total:
+ *
+ * - `POST /auth/logout` — best-effort token revocation + cookie clear.
+ * - `POST /auth/refresh` — rotate access/refresh tokens.
+ * - `GET /auth/status` — return the current `AuthContext`.
+ * - `POST /auth/trigger` — single workflow trigger covering `auth.login`,
+ *   `auth.recovery`, and `auth.invite`.
+ *
+ * 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`).
+ *
+ * Exported so consumers can subclass to add app-specific workflow ids to the
+ * allow-list (override `triggerWf()` with a different `@WfTrigger({ allow })`)
+ * or to inject custom outlets / state stores by subclassing `WfTriggerProvider`.
+ */
+declare class AuthController {
+  protected readonly auth: AuthCredential;
+  constructor(auth: AuthCredential);
+  logout(body: AuthLogoutBody | undefined): Promise<AuthOkResponse>;
+  refresh(body: AuthRefreshBody | undefined): Promise<AuthLoginResponse>;
+  status(): AuthContext$1;
+  triggerWf(): void;
+}
+//#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. */
+  allow?: string[];
+  /** Per-endpoint token wire override. Defaults to the provider's wire (`{read:['body','query','cookie'], write:'body', name:'wfs'}`). */
+  token?: WfOutletTokenConfig;
+}
+/**
+ * Method decorator that turns a handler into a workflow trigger.
+ *
+ * The handler may have an empty body — the interceptor's after-phase invokes
+ * `WfTriggerProvider.handle()` when the handler returns `undefined`. Subclasses
+ * that need to short-circuit (e.g. emit a custom error response) just return a
+ * non-undefined value from the overridden handler and the trigger is skipped.
+ *
+ * The single `useControllerContext().instantiate(...)` call is the one
+ * documented escape hatch: interceptors are functions, not classes, so there's
+ * no ctor to inject into. Every class still uses constructor injection.
+ */
+declare const WfTrigger: (opts?: WfTriggerOpts) => ClassDecorator & MethodDecorator;
+//#endregion
+//#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.
+ *
+ * Defaults are intentionally minimal: in-memory state + HTTP outlet only.
+ * Production deployments swap in a persistent `WfStateStore` and any outlets
+ * they need by extending this class and re-binding via `setReplaceRegistry`.
+ *
+ * Uses `handleAsOutletRequest` (not `MoostWf.handleOutlet`) because the atscript
+ * wrapper restores the `finished: true` marker that `<AsWfForm>` keys off — the
+ * bare wooks request handler strips it during `useWfFinished()` unwrap.
+ */
+declare class WfTriggerProvider {
+  protected readonly wf: MoostWf;
+  protected state: WfStateStrategy;
+  protected outlets: WfOutlet[];
+  protected token: WfOutletTokenConfig;
+  constructor(wf: MoostWf);
+  handle(opts?: {
+    allow?: string[];
+    token?: WfOutletTokenConfig;
+  }): Promise<unknown>;
+}
+//#endregion
+//#region src/audit/index.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).
+ *
+ * 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`). */
+  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;
+}
+//#endregion
+//#region src/workflows/login.workflow.options.d.ts
+type LoginRedirect = "referer" | "home" | false | null;
+type MfaTransport = "sms" | "email" | "totp";
+interface SsoProvider {
+  id: string;
+  label: string;
+  url: string;
+}
+interface ConcurrencyLimitOptions {
+  max: number;
+  onLimit: "reject" | "kickPrompt";
+}
+interface LoginWorkflowOpts {
+  alternateCredentials?: {
+    forgotPassword?: boolean;
+    signup?: boolean;
+    magicLink?: boolean;
+    magicLinkSkipsMfa?: boolean;
+    magicLinkTtlMs?: number;
+    ssoProviders?: SsoProvider[];
+    recoveryUrl?: string;
+    signupUrl?: string;
+    embedRecovery?: boolean;
+  };
+  guards?: {
+    emailVerifiedRequired?: boolean;
+    passwordExpiry?: boolean;
+    passwordInitial?: boolean;
+  };
+  enrollment?: {
+    ensureEmail?: boolean;
+    ensurePhone?: boolean;
+  };
+  mfa?: {
+    enabled?: boolean;
+    transports?: MfaTransport[];
+    backupCodes?: boolean;
+    enrollRequired?: boolean;
+    pincodeTtlMs?: number;
+    pincodeResendTimeoutMs?: number; /** Numeric length of the server-generated OTP for SMS/email pincodes. */
+    pincodeLength?: number;
+  };
+  deviceTrust?: {
+    enabled?: boolean;
+    optIn?: boolean;
+    cookieName?: string;
+    ttlMs?: number;
+    skipsMfa?: boolean;
+    bindsTo?: "cookie" | "cookie+ip";
+  };
+  acceptance?: {
+    termsVersion?: string;
+    profileCompleteRequired?: boolean;
+    consentMarketing?: boolean;
+  };
+  multiContext?: {
+    tenantSelect?: boolean;
+    personaSelect?: boolean;
+  };
+  sessionPolicy?: {
+    concurrencyLimit?: ConcurrencyLimitOptions;
+  };
+  finalize?: {
+    auditLogin?: boolean;
+    notifyNewDevice?: boolean;
+    redirect?: LoginRedirect;
+  };
+  /**
+   * Replaceable form schemas. Each field defaults to the corresponding
+   * `.as` form shipped under `@aooth/auth-moost/atscript/models`; supply a
+   * subset to override only the forms you want to swap.
+   */
+  forms?: {
+    askEmail?: TAtscriptAnnotatedType;
+    askPhone?: TAtscriptAnnotatedType;
+    backupCode?: TAtscriptAnnotatedType;
+    concurrencyLimit?: TAtscriptAnnotatedType;
+    consentMarketing?: TAtscriptAnnotatedType;
+    loginCredentials?: TAtscriptAnnotatedType;
+    mfaCode?: TAtscriptAnnotatedType;
+    personaSelect?: TAtscriptAnnotatedType;
+    pincode?: TAtscriptAnnotatedType;
+    profileComplete?: TAtscriptAnnotatedType;
+    select2fa?: TAtscriptAnnotatedType;
+    setPassword?: TAtscriptAnnotatedType;
+    tenantSelect?: TAtscriptAnnotatedType;
+    termsAccept?: TAtscriptAnnotatedType;
+  };
+}
+/**
+ * Fully-resolved view used by the workflow at runtime — every nested group is
+ * always populated by `mergeLoginOpts`, so schema conditions can read
+ * `ctx.opts.<group>.<flag>` directly without optional chaining.
+ *
+ * Fields without sensible defaults (e.g. `termsVersion`, `concurrencyLimit`)
+ * stay optional inside their group.
+ */
+interface ResolvedLoginWorkflowOpts {
+  alternateCredentials: {
+    forgotPassword: boolean;
+    signup: boolean;
+    magicLink: boolean;
+    magicLinkSkipsMfa: boolean;
+    magicLinkTtlMs: number;
+    ssoProviders: SsoProvider[];
+    recoveryUrl: string;
+    signupUrl: string;
+    embedRecovery: boolean;
+  };
+  guards: {
+    emailVerifiedRequired: boolean;
+    passwordExpiry: boolean;
+    passwordInitial: boolean;
+  };
+  enrollment: {
+    ensureEmail: boolean;
+    ensurePhone: boolean;
+  };
+  mfa: {
+    enabled: boolean;
+    transports: MfaTransport[];
+    backupCodes: boolean;
+    enrollRequired: boolean;
+    pincodeTtlMs: number;
+    pincodeResendTimeoutMs: number;
+    pincodeLength: number;
+  };
+  deviceTrust: {
+    enabled: boolean;
+    optIn: boolean;
+    cookieName: string;
+    ttlMs: number;
+    skipsMfa: boolean;
+    bindsTo: "cookie" | "cookie+ip";
+  };
+  acceptance: {
+    termsVersion?: string;
+    profileCompleteRequired: boolean;
+    consentMarketing: boolean;
+  };
+  multiContext: {
+    tenantSelect: boolean;
+    personaSelect: boolean;
+  };
+  sessionPolicy: {
+    concurrencyLimit?: ConcurrencyLimitOptions;
+  };
+  finalize: {
+    auditLogin: boolean;
+    notifyNewDevice: boolean;
+    redirect: LoginRedirect;
+  };
+  forms: {
+    askEmail: TAtscriptAnnotatedType;
+    askPhone: TAtscriptAnnotatedType;
+    backupCode: TAtscriptAnnotatedType;
+    concurrencyLimit: TAtscriptAnnotatedType;
+    consentMarketing: TAtscriptAnnotatedType;
+    loginCredentials: TAtscriptAnnotatedType;
+    mfaCode: TAtscriptAnnotatedType;
+    personaSelect: TAtscriptAnnotatedType;
+    pincode: TAtscriptAnnotatedType;
+    profileComplete: TAtscriptAnnotatedType;
+    select2fa: TAtscriptAnnotatedType;
+    setPassword: TAtscriptAnnotatedType;
+    tenantSelect: TAtscriptAnnotatedType;
+    termsAccept: 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 mergeLoginOpts(opts?: LoginWorkflowOpts): ResolvedLoginWorkflowOpts;
+//#endregion
+//#region src/workflows/login.workflow.d.ts
+interface LoginWfCtx {
+  opts?: ResolvedLoginWorkflowOpts;
+  username?: string;
+  /** Legacy alias for `pwReset`; kept until tests migrate. */
+  mfaRequired?: boolean;
+  isPasswordInitial?: boolean;
+  usedMagicLink?: boolean;
+  email?: string;
+  emailConfirmed?: boolean;
+  phone?: string;
+  phoneConfirmed?: boolean;
+  mfaEnrolledMethods?: MfaSummary[];
+  mfaMethod?: "sms" | "email" | "totp";
+  mfaSaveAsDefault?: boolean;
+  ignoreMfaDefault?: boolean;
+  mfaChecked?: boolean;
+  /** Counter incremented by the `risk-step-up` step so MFA reruns for the extra factor. */
+  mfaRunsRemaining?: number;
+  pin?: string;
+  pinExpire?: number;
+  pinTimeout?: number;
+  pinSentTo?: 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;
+  termsAcceptedVersion?: string;
+  profileMissingFields?: string[];
+  availableTenants?: Array<{
+    id: string;
+    name: string;
+  }>;
+  selectedTenantId?: string;
+  availablePersonas?: Array<{
+    id: string;
+    label: string;
+  }>;
+  selectedPersonaId?: string;
+  riskStepUpReason?: string;
+  activeSessions?: number;
+  passwordChanged?: boolean;
+  termsAcceptedDone?: boolean;
+  profileApplied?: boolean;
+  consentApplied?: boolean;
+  tokensIssued?: boolean;
+  redirectUrl?: 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.
+   */
+  aborted?: boolean;
+  /** Tracks whether `risk-step-up` has already been evaluated this iteration. */
+  riskStepUpEvaluated?: boolean;
+}
+interface MfaSummary {
+  kind: "sms" | "email" | "totp";
+  /** Underlying `MfaMethod.name` so the workflow can call into UserService. */
+  methodName: string;
+  masked: string;
+  isDefault: boolean;
+}
+/**
+ * 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`).
+ */
+interface DeliverEmail {
+  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;
+  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 {
+  protected readonly opts: ResolvedLoginWorkflowOpts;
+  protected readonly users: UserService;
+  protected readonly auth: AuthCredential;
+  constructor(opts: LoginWorkflowOpts, users: UserService, auth: AuthCredential);
+  /**
+   * Dispatch an email or SMS event. Default throws — consumers MUST override
+   * if any feature that emits is enabled (MFA pincode, ensureEmail/Phone 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.
+   */
+  protected deliver(_payload: DeliverPayload): Promise<void>;
+  /**
+   * Emit an audit event. Default: no-op. Consumers override to fan out to
+   * their audit sink (DB table, log file, Kafka topic, …).
+   */
+  protected audit(_event: AuditEvent): Promise<void>;
+  /**
+   * 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.
+   */
+  protected loadTrustedDevice(userId: string, token: string, ip?: string): Promise<boolean>;
+  /**
+   * 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).
+   */
+  protected storeTrustedDevice(userId: string, record: TrustedDeviceRecord): Promise<void>;
+  /**
+   * 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`.
+   */
+  protected revokeTrustedDevice(userId: string, token: string): Promise<void>;
+  /**
+   * 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>;
+  flow(): void;
+  init(ctx: LoginWfCtx): undefined;
+  /**
+   * Returns the JSON-safe projection of `opts` stashed onto `ctx` for schema
+   * conditions to read. Default: drop the `forms` group (atscript form classes
+   * are not plain JSON) so `AsWfStore`'s plain-JSON persistence doesn't choke.
+   * Step bodies still consult the form classes via `this.opts.forms.*`.
+   *
+   * Consumers who put non-JSON values on `opts` (e.g. by extending the type)
+   * can override this to strip them.
+   */
+  protected snapshotOpts(opts: ResolvedLoginWorkflowOpts): ResolvedLoginWorkflowOpts;
+  credentials(input: {
+    username?: string;
+    password?: string;
+    action?: string;
+  } | undefined, ctx: LoginWfCtx): Promise<unknown>;
+  private handleCredentialsAlt;
+  /**
+   * Builds 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 ?? '')}`.
+   */
+  protected buildRecoveryUrl(username?: string): string;
+  magicLinkRequest(): never;
+  magicLinkSend(): never;
+  magicLinkVerified(): never;
+  passkey(): never;
+  ssoCallback(): never;
+  ensureEmail(input: {
+    email?: string;
+    code?: string;
+  } | undefined, ctx: LoginWfCtx): Promise<unknown>;
+  ensurePhone(input: {
+    phone?: string;
+    code?: string;
+  } | undefined, ctx: LoginWfCtx): Promise<unknown>;
+  checkTrustedDevice(ctx: LoginWfCtx): Promise<undefined>;
+  prepareMfaOptions(ctx: LoginWfCtx): Promise<undefined>;
+  select2fa(input: {
+    methodName?: string;
+    saveAsDefault?: boolean;
+    action?: string;
+  } | undefined, ctx: LoginWfCtx): Promise<unknown>;
+  pincodeSendLogin(ctx: LoginWfCtx): Promise<undefined>;
+  pincodeCheckLogin(input: {
+    code?: string;
+    action?: string;
+    rememberDevice?: boolean;
+  } | undefined, ctx: LoginWfCtx): Promise<unknown>;
+  mfaTotp(input: {
+    code?: string;
+    action?: string;
+    rememberDevice?: boolean;
+  } | undefined, ctx: LoginWfCtx): Promise<unknown>;
+  /**
+   * 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;
+  mfaEnrollRequired(): never;
+  deviceTrust(ctx: LoginWfCtx): Promise<undefined>;
+  preparePasswordRules(ctx: LoginWfCtx): undefined;
+  createPasswordForm(input: {
+    newPassword?: string;
+    confirmPassword?: string;
+    action?: string;
+  } | undefined, ctx: LoginWfCtx): Promise<unknown>;
+  termsAccept(input: {
+    acceptedVersion?: string;
+    accepted?: boolean;
+    action?: string;
+  } | undefined, ctx: LoginWfCtx): Promise<unknown>;
+  profileComplete(input: Record<string, unknown> | undefined, ctx: LoginWfCtx): Promise<unknown>;
+  /**
+   * Persists the profile-complete payload onto the user record. Default:
+   * no-op (the workflow records the form was submitted but writes nothing).
+   * Consumers override to write into their user store.
+   */
+  protected applyProfile(_username: string, _payload: Record<string, unknown>): Promise<void>;
+  consentMarketing(input: {
+    optIn?: boolean;
+    action?: string;
+  } | undefined, ctx: LoginWfCtx): Promise<unknown>;
+  /**
+   * Persists the marketing consent decision. Default: no-op.
+   */
+  protected applyConsentMarketing(_username: string, _optIn: boolean): Promise<void>;
+  tenantSelect(input: {
+    tenantId?: string;
+  } | undefined, 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(input: {
+    personaId?: string;
+  } | undefined, 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;
+  }>>;
+  concurrencyLimit(input: {
+    action?: string;
+  } | undefined, ctx: LoginWfCtx): Promise<unknown>;
+  /**
+   * Implements the "log out other sessions" branch of `sessionPolicy.concurrencyLimit`.
+   * Default: no-op. Consumers override to revoke sessions in their auth store.
+   */
+  protected logoutOtherSessions(_username: string): Promise<void>;
+  riskStepUp(ctx: LoginWfCtx): Promise<undefined>;
+  /**
+   * Risk-step-up assessor. Default: never requires an extra factor. Consumers
+   * override to inspect ctx (IP, geo, time since last login, etc.) and return
+   * `{require: true, reason: '…'}` to force an additional MFA round.
+   */
+  protected assessRiskStepUp(_ctx: LoginWfCtx): Promise<{
+    require: boolean;
+    reason?: string;
+  }>;
+  issue(ctx: LoginWfCtx): Promise<void>;
+  auditLogin(ctx: LoginWfCtx): Promise<undefined>;
+  notifyNewDevice(ctx: LoginWfCtx): Promise<undefined>;
+  redirect(ctx: LoginWfCtx): undefined;
+  /**
+   * 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).
+   *
+   * Consumers who want a computed redirect override this method.
+   */
+  protected resolveRedirect(_ctx: LoginWfCtx): string | undefined;
+  private resolveClientIp;
+}
+//#endregion
+//#region src/workflows/recovery.workflow.options.d.ts
+type RecoveryDeliveryMode = "magicLink" | "otp" | "choice";
+type RecoveryOtpTransport = "sms" | "email";
+interface RecoveryWorkflowOpts {
+  delivery?: {
+    mode?: RecoveryDeliveryMode;
+    magicLinkTtlMs?: number;
+    otp?: {
+      transports?: RecoveryOtpTransport[];
+      codeLength?: number;
+      ttlMs?: number;
+      resendCooldownMs?: number;
+    };
+  };
+  preReset?: {
+    requireKnownFactor?: boolean;
+  };
+  postReset?: {
+    revokeAllSessions?: boolean;
+    freshLoginRequired?: boolean;
+    loginUrl?: string;
+  };
+  altActions?: {
+    backToLogin?: boolean;
+  };
+  audit?: {
+    enabled?: boolean;
+  };
+  /**
+   * Replaceable form schemas. Each field defaults to the corresponding
+   * `.as` form shipped under `@aooth/auth-moost/atscript/models`.
+   */
+  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 schema conditions can read
+ * `ctx.opts.<group>.<flag>` directly without optional chaining.
+ */
+interface ResolvedRecoveryWorkflowOpts {
+  delivery: {
+    mode: RecoveryDeliveryMode;
+    magicLinkTtlMs: number;
+    otp: {
+      transports: RecoveryOtpTransport[];
+      codeLength: number;
+      ttlMs: number;
+      resendCooldownMs: number;
+    };
+  };
+  preReset: {
+    requireKnownFactor: boolean;
+  };
+  postReset: {
+    revokeAllSessions: boolean;
+    freshLoginRequired: boolean;
+    loginUrl: string;
+  };
+  altActions: {
+    backToLogin: boolean;
+  };
+  audit: {
+    enabled: boolean;
+  };
+  forms: {
+    emailIdentifier: TAtscriptAnnotatedType;
+    pincode: TAtscriptAnnotatedType;
+    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 {
+  opts?: ResolvedRecoveryWorkflowOpts;
+  email?: string;
+  username?: string;
+  selectedMode?: "magicLink" | "otp";
+  /** Resolved delivery mode the workflow committed to (populated by `selectMode` or `init`). */
+  resolvedMode?: "magicLink" | "otp";
+  otpTransport?: "sms" | "email";
+  otpCodeLength?: number;
+  pin?: string;
+  pinExpire?: number;
+  pinResendAllowedAt?: number;
+  pinVerified?: boolean;
+  linkSent?: boolean;
+  factorVerified?: boolean;
+  passwordChanged?: boolean;
+  sessionsRevoked?: boolean;
+  tokensIssued?: boolean;
+  /** Set by abort alt-actions (`backToLogin`). Gates all terminal steps. */
+  aborted?: boolean;
+}
+declare class RecoveryWorkflow {
+  protected readonly opts: ResolvedRecoveryWorkflowOpts;
+  protected readonly users: UserService;
+  protected readonly auth: AuthCredential;
+  constructor(opts: RecoveryWorkflowOpts, users: UserService, auth: AuthCredential);
+  /**
+   * 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).
+   */
+  protected deliver(_payload: DeliverPayload): Promise<void>;
+  /**
+   * Emit an audit event. Default: no-op. Consumers override to fan out to
+   * their audit sink.
+   */
+  protected audit(_event: AuditEvent): Promise<void>;
+  flow(): void;
+  init(ctx: RecoveryWfCtx): undefined;
+  /**
+   * Returns the JSON-safe projection of `opts` stashed onto `ctx` for schema
+   * conditions to read. Default: drop the `forms` group (atscript form classes
+   * are not plain JSON) so `AsWfStore`'s plain-JSON persistence doesn't choke.
+   * Step bodies still consult the form classes via `this.opts.forms.*`.
+   *
+   * Consumers who extend the opts type with non-JSON values can override this
+   * to strip them so `AsWfStore`'s plain-JSON persistence doesn't choke.
+   */
+  protected snapshotOpts(opts: ResolvedRecoveryWorkflowOpts): ResolvedRecoveryWorkflowOpts;
+  request(input: {
+    email?: string;
+    action?: string;
+  } | undefined, ctx: RecoveryWfCtx): Promise<unknown>;
+  /**
+   * Resolves the recovery-step `email` input to the `username` (user-id) that
+   * `UserService.getUser` expects. Default: returns the email unchanged (treats
+   * email as username). Apps whose user model separates `username` from
+   * `email` MUST override this; return `null` when no user matches.
+   */
+  protected emailToUserId(email: string): Promise<string | null>;
+  selectMode(input: {
+    mode?: string;
+    action?: string;
+  } | undefined, ctx: RecoveryWfCtx): unknown;
+  sendMagicLink(ctx: RecoveryWfCtx): unknown;
+  sendOtp(ctx: RecoveryWfCtx): Promise<undefined>;
+  checkOtp(input: {
+    code?: string;
+    action?: string;
+  } | undefined, ctx: RecoveryWfCtx): Promise<unknown>;
+  verifyFactor(input: {
+    factor?: string;
+    value?: string;
+    action?: string;
+  } | undefined, ctx: RecoveryWfCtx): Promise<unknown>;
+  /**
+   * 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.
+   */
+  protected verifyRecoveryFactor(input: {
+    factor: string;
+    value: string;
+    ctx: RecoveryWfCtx;
+  }): Promise<boolean>;
+  setPassword(input: {
+    newPassword?: string;
+    confirmPassword?: string;
+    action?: string;
+  } | undefined, ctx: RecoveryWfCtx): Promise<unknown>;
+  revokeSessions(ctx: RecoveryWfCtx): Promise<undefined>;
+  auditStep(ctx: RecoveryWfCtx): Promise<undefined>;
+  freshLoginFinish(_ctx: RecoveryWfCtx): undefined;
+  autoLoginFinish(ctx: RecoveryWfCtx): Promise<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).
+   */
+  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 {
+  adminForm?: {
+    collectRoles?: boolean;
+  };
+  send?: {
+    mode?: InviteSendMode;
+    tokenTtlMs?: number;
+  };
+  accept?: {
+    alreadyAcceptedRedirectUrl?: string;
+    freshLoginRequired?: boolean;
+    loginUrl?: string;
+    showConfirmation?: boolean;
+    confirmationMessage?: string;
+  };
+  cancellation?: {
+    allowed?: boolean;
+  };
+  audit?: {
+    enabled?: boolean;
+  };
+  /**
+   * Replaceable form schemas. Each field defaults to the corresponding
+   * `.as` form shipped under `@aooth/auth-moost/atscript/models`.
+   */
+  forms?: {
+    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 schema conditions can read
+ * `ctx.opts.<group>.<flag>` directly without optional chaining.
+ */
+interface ResolvedInviteWorkflowOpts {
+  adminForm: {
+    collectRoles: boolean;
+  };
+  send: {
+    mode: InviteSendMode;
+    tokenTtlMs: number;
+  };
+  accept: {
+    alreadyAcceptedRedirectUrl: string;
+    freshLoginRequired: boolean;
+    loginUrl: string;
+    showConfirmation: boolean;
+    confirmationMessage: string;
+  };
+  cancellation: {
+    allowed: boolean;
+  };
+  audit: {
+    enabled: boolean;
+  };
+  forms: {
+    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 {
+  opts?: ResolvedInviteWorkflowOpts;
+  /** Boolean projection of `this.getProfileForm() !== undefined` — schema gates on it. */
+  acceptProfileFormPresent?: boolean;
+  /**
+   * Populated by `invitePrepareAvailableRoles` when the override returns a list.
+   * Surfaced into the `InviteForm` via `@wf.context.pass 'availableRoles'` so
+   * the role multi-select renders the whitelisted choices; also used by
+   * `inviteAdminInviteForm` to reject admin-submitted roles outside the list.
+   */
+  availableRoles?: string[];
+  email?: string;
+  /** Typically same as `email`; consumers can override the mapping. */
+  username?: string;
+  firstName?: string;
+  lastName?: string;
+  roles?: string[];
+  /** Populated by `inviteSelectSendMode` (when `send.mode === 'choice'`). */
+  selectedSendMode?: "email" | "shareableLink";
+  /** Resolved send mode the workflow committed to (set in `inviteInit` or `inviteSelectSendMode`). */
+  resolvedSendMode?: "email" | "shareableLink";
+  /** Populated by `inviteReturnShareableLink` so the admin's UI can display it. */
+  shareableLinkUrl?: string;
+  /** Marks that `inviteSendInviteEmail` already emitted the outlet — resume → advance. */
+  linkSent?: boolean;
+  /** Detected at `inviteCheckPendingInvitation`; triggers `inviteIdempotentRedirect`. */
+  alreadyAccepted?: boolean;
+  passwordSet?: boolean;
+  /** Raw input from `inviteCollectProfile`. */
+  profile?: Record<string, unknown>;
+  profileApplied?: boolean;
+  pendingInvitationCleared?: boolean;
+  activated?: boolean;
+  confirmationShown?: boolean;
+  tokensIssued?: boolean;
+  /** Set true by abort alt-actions (`cancel`). Gates all terminal steps. */
+  aborted?: boolean;
+}
+/** 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 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.
+ * `inviteSendInviteEmail` / `inviteReturnShareableLink` are the boundary:
+ * also `@Public()` because the @prostojs/wf runtime re-enters the saved step
+ * on resume (the loop restarts at `indexes[level]`, not after it). Their
+ * bodies are idempotent via `if (ctx.linkSent) return`.
+ *
+ * `auth.reInvite` / `auth.cancelInvite` are admin-only end-to-end (admin
+ * confirms in their own UI; no anonymous boundary), so their phase-A steps
+ * stay class-gated under the same `auth.invite` / `start` grant.
+ */
+declare class InviteWorkflow {
+  protected readonly opts: ResolvedInviteWorkflowOpts;
+  protected readonly users: UserService;
+  protected readonly auth: AuthCredential;
+  constructor(opts: InviteWorkflowOpts, users: UserService, auth: AuthCredential);
+  /**
+   * 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.
+   */
+  protected deliver(_payload: DeliverPayload): Promise<void>;
+  /**
+   * Emit an audit event. Default: no-op. Consumers override to fan out to
+   * their audit sink.
+   */
+  protected audit(_event: AuditEvent): Promise<void>;
+  /**
+   * 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.
+   */
+  protected prepareUser(_input: PreparedUserInput): Promise<Record<string, unknown>>;
+  /**
+   * Return the list of selectable role identifiers for the admin invite form.
+   * When defined AND `adminForm.collectRoles` is true → form ships
+   * `ctx.availableRoles` so the UI renders a multi-select AND the
+   * `inviteAdminInviteForm` step rejects admin-submitted roles outside the
+   * list. When `undefined` (default) → no whitelist is enforced and any role
+   * value the admin form supplies is accepted.
+   */
+  protected getAvailableRoles(): Promise<string[] | undefined>;
+  /**
+   * 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).
+   */
+  protected inferRoles(_input: {
+    email: string;
+    firstName?: string;
+    lastName?: string;
+  }): Promise<string[]>;
+  /**
+   * 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.
+   */
+  protected applyProfile(input: {
+    username: string;
+    profile: Record<string, unknown>;
+  }): Promise<void>;
+  /**
+   * Override the structural duplicate rule for `inviteAdminInviteForm`.
+   * 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.
+   */
+  protected duplicateCheck(input: {
+    email: string;
+    existingUser: UserCredentials | null;
+  }): Promise<DuplicateAction>;
+  /**
+   * Return the consumer-supplied `.as` form schema rendered in the
+   * `inviteCollectProfile` step. `undefined` (default) skips the step
+   * entirely (just password collection).
+   */
+  protected getProfileForm(): TAtscriptAnnotatedType | undefined;
+  /**
+   * Returns the JSON-safe projection of `opts` stashed onto `ctx` for schema
+   * conditions to read. Default: drop the `forms` group (atscript form classes
+   * are not plain JSON) so `AsWfStore`'s plain-JSON persistence doesn't choke.
+   * Step bodies still consult the form classes via `this.opts.forms.*`.
+   *
+   * Consumers who extend the opts type with non-JSON values can override this
+   * to strip them so `AsWfStore`'s plain-JSON persistence doesn't choke.
+   */
+  protected snapshotOpts(opts: ResolvedInviteWorkflowOpts): ResolvedInviteWorkflowOpts;
+  inviteFlow(): void;
+  reInviteFlow(): void;
+  cancelInviteFlow(): void;
+  init(ctx: InviteWfCtx): undefined;
+  prepareAvailableRoles(ctx: InviteWfCtx): Promise<undefined>;
+  selectSendMode(input: {
+    mode?: string;
+    action?: string;
+  } | undefined, ctx: InviteWfCtx): unknown;
+  adminInviteForm(input: {
+    email?: string;
+    firstName?: string;
+    lastName?: string;
+    roles?: string[];
+    action?: string;
+  } | undefined, ctx: InviteWfCtx): Promise<unknown>;
+  inferRolesStep(ctx: InviteWfCtx): Promise<undefined>;
+  preCreateUser(ctx: InviteWfCtx): Promise<undefined>;
+  sendInviteEmail(ctx: InviteWfCtx): unknown;
+  returnShareableLink(ctx: InviteWfCtx): unknown;
+  loadPendingUser(input: {
+    email?: string;
+    action?: string;
+  } | undefined, ctx: InviteWfCtx): Promise<unknown>;
+  checkPendingInvitation(ctx: InviteWfCtx): Promise<undefined>;
+  idempotentRedirect(ctx: InviteWfCtx): undefined;
+  preparePasswordRules(ctx: InviteWfCtx): undefined;
+  createPasswordForm(input: {
+    newPassword?: string;
+    confirmPassword?: string;
+    action?: string;
+  } | undefined, ctx: InviteWfCtx): Promise<unknown>;
+  collectProfile(input: Record<string, unknown> | undefined, ctx: InviteWfCtx): Promise<unknown>;
+  applyProfileStep(ctx: InviteWfCtx): Promise<undefined>;
+  unsetPendingInvitation(ctx: InviteWfCtx): Promise<undefined>;
+  activateUser(ctx: InviteWfCtx): Promise<undefined>;
+  confirmation(ctx: InviteWfCtx): undefined;
+  freshLoginFinish(_ctx: InviteWfCtx): undefined;
+  autoLoginFinish(ctx: InviteWfCtx): Promise<undefined>;
+  cancelInvite(input: {
+    email?: string;
+  } | undefined, ctx: InviteWfCtx): Promise<unknown>;
+  private abort;
+  private loadUserOrNull;
+  private emitAudit;
+}
+//#endregion
+//#region src/workflows/auth-email-outlet.d.ts
+interface AuthEmailOutletDeps {
+  emailSender: EmailSender$1;
+  buildMagicLinkUrl: BuildMagicLinkUrl$1;
+  /** Fallback TTL when the workflow context omits `expiresAtMs`. */
+  magicLinkTtlMs: (kind: AuthEmailKind$1) => number;
+}
+/**
+ * Build the email outlet that delivers magic links via the consumer's
+ * `EmailSender`. Single-use: pass the same instance into one
+ * `handleWfOutletRequest({ outlets })`.
+ */
+declare function createAuthEmailOutlet(deps: AuthEmailOutletDeps): WfOutlet;
+//#endregion
+export { type AuditEmitter, type AuditEvent, type AuthBindings, type AuthContext, AuthController, type AuthEmailEvent, type AuthEmailKind, type AuthEmailOutletDeps, AuthGuarded, type AuthLoginResponse, type AuthLogoutBody, type AuthOkResponse, type AuthOptions, type AuthRefreshBody, type AuthSmsEvent, type AuthSmsKind, type BuildMagicLinkUrl, type ConcurrencyLimitOptions, DEFAULT_AUTH_WORKFLOWS, type DeliverEmail, type DeliverPayload, type DeliverSms, type DuplicateAction, type EmailSender, type InvitePrepareUserInput, type InviteSendMode, type InviteWfCtx, InviteWorkflow, type InviteWorkflowOpts, type IssueResult, type LoginRedirect, type LoginWfCtx, LoginWorkflow, type LoginWorkflowOpts, type MfaSummary, type MfaTransport, type PreparedUserInput, Public, type RecoveryDeliveryMode, type RecoveryOtpTransport, type RecoveryWfCtx, RecoveryWorkflow, type RecoveryWorkflowOpts, type ResolvedAuthCookieConfig, type ResolvedAuthOptions, type ResolvedInviteWorkflowOpts, type ResolvedLoginWorkflowOpts, type ResolvedRecoveryWorkflowOpts, type SmsSender, type SsoProvider, type TAuthMeta, UserId, WfTrigger, type WfTriggerOpts, WfTriggerProvider, authGuardInterceptor, createAuthEmailOutlet, generateMagicLinkToken, getAuthMate, mergeInviteOpts, mergeLoginOpts, mergeRecoveryOpts, parseInviteRoles, useAuth };