tempest-express-sdk 0.6.0 → 0.7.0

package/dist/index.d.cts

@@ -2771,12 +2771,62 @@ declare const authResponseSchema: z.ZodObject<{
         expiresIn: number;
     };
 }>;
+/** MFA enrollment response (`POST /auth/mfa/enroll`). */
+declare const mfaEnrollResponseSchema: z.ZodObject<{
+    secret: z.ZodString;
+    otpauthUri: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    secret: string;
+    otpauthUri: string;
+}, {
+    secret: string;
+    otpauthUri: string;
+}>;
+/** A 6-digit MFA code body (`POST /auth/mfa/confirm|disable`). */
+declare const mfaCodeSchema: z.ZodObject<{
+    code: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    code: string;
+}, {
+    code: string;
+}>;
+/** Activation body (`POST /auth/activate`). */
+declare const activationSchema: z.ZodObject<{
+    token: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    token: string;
+}, {
+    token: string;
+}>;
+/** Password-reset request body (`POST /auth/password-reset/request`). */
+declare const passwordResetRequestSchema: z.ZodObject<{
+    email: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    email: string;
+}, {
+    email: string;
+}>;
+/** Password-reset confirm body (`POST /auth/password-reset/confirm`). */
+declare const passwordResetConfirmSchema: z.ZodObject<{
+    token: z.ZodString;
+    password: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    password: string;
+    token: string;
+}, {
+    password: string;
+    token: string;
+}>;
 type SignupInput = z.infer<typeof signupSchema>;
 type LoginInput = z.infer<typeof loginSchema>;
 type RefreshInput = z.infer<typeof refreshSchema>;
 type TokenPair = z.infer<typeof tokenPairSchema>;
 type UserPublic = z.infer<typeof userPublicSchema>;
 type AuthResponse = z.infer<typeof authResponseSchema>;
+type MfaCodeInput = z.infer<typeof mfaCodeSchema>;
+type ActivationInput = z.infer<typeof activationSchema>;
+type PasswordResetRequestInput = z.infer<typeof passwordResetRequestSchema>;
+type PasswordResetConfirmInput = z.infer<typeof passwordResetConfirmSchema>;
 
 /**
  * User authentication service, mirroring `auth.service.UserAuthService`.
@@ -2871,6 +2921,197 @@ declare class UserAuthService {
     refresh(refreshToken: string): Promise<AuthResponse>;
 }
 
+/**
+ * TOTP MFA enrollment/verification, mirroring the FastAPI SDK MFA flow.
+ *
+ * Orchestrates {@link TOTPHelper} over a pluggable {@link MfaStore}: enroll
+ * (generate + persist a secret, return the provisioning URI), confirm (verify a
+ * code and flip MFA on), verify (login step) and disable.
+ */
+
+/** Persistence port for MFA secrets/state. */
+interface MfaStore {
+    /** Persist a user's TOTP secret (pending until confirmed). */
+    setSecret(userId: string, secret: string): Promise<void>;
+    /** Read a user's TOTP secret, or `null`. */
+    getSecret(userId: string): Promise<string | null>;
+    /** Flip the MFA-enabled flag. */
+    setEnabled(userId: string, enabled: boolean): Promise<void>;
+    /** Whether MFA is enabled for the user. */
+    isEnabled(userId: string): Promise<boolean>;
+}
+/** The result of starting enrollment. */
+interface MfaEnrollment {
+    /** The base32 secret (persist server-side; also shown once for manual entry). */
+    secret: string;
+    /** The `otpauth://` URI to render as a QR code. */
+    otpauthUri: string;
+}
+/** Options for {@link MfaService}. */
+interface MfaServiceOptions {
+    /** The MFA persistence port. */
+    store: MfaStore;
+    /** The TOTP helper (issuer preconfigured). */
+    totp: TOTPHelper;
+}
+declare class MfaService {
+    private readonly store;
+    private readonly totp;
+    /**
+     * @param options - Store and TOTP helper.
+     */
+    constructor(options: MfaServiceOptions);
+    /**
+     * Begin enrollment: generate and persist a secret, return the QR URI.
+     *
+     * @param userId - The enrolling user.
+     * @param accountName - Label shown in the authenticator (usually the email).
+     * @returns The secret and provisioning URI.
+     */
+    enroll(userId: string, accountName: string): Promise<MfaEnrollment>;
+    /**
+     * Confirm enrollment by verifying a code, enabling MFA on success.
+     *
+     * @param userId - The user.
+     * @param code - The 6-digit code from the authenticator.
+     * @throws {ValidationException} When no secret is pending or the code is wrong.
+     */
+    confirm(userId: string, code: string): Promise<void>;
+    /**
+     * Verify a code (login step). Returns `false` without throwing.
+     *
+     * @param userId - The user.
+     * @param code - The submitted code.
+     * @returns `true` when the code is valid.
+     */
+    verify(userId: string, code: string): Promise<boolean>;
+    /**
+     * Disable MFA after verifying a code.
+     *
+     * @param userId - The user.
+     * @param code - The submitted code.
+     * @throws {ValidationException} When the code is invalid.
+     */
+    disable(userId: string, code: string): Promise<void>;
+}
+
+/**
+ * Email-activation flow, mirroring the FastAPI SDK activation flow.
+ *
+ * Issues a single-use opaque token (only its SHA-256 hash is stored), emails
+ * the plaintext to the user, and activates the account when the link is opened.
+ */
+/** Persistence port for activation tokens. */
+interface ActivationStore {
+    /** Persist a token hash + expiry (epoch ms) for a user. */
+    saveActivationToken(userId: string, tokenHash: string, expiresAt: number): Promise<void>;
+    /** Look up a token hash, returning the owner + expiry, or `null`. */
+    findActivationToken(tokenHash: string): Promise<{
+        userId: string;
+        expiresAt: number;
+    } | null>;
+    /** Remove a token hash (single-use). */
+    clearActivationToken(tokenHash: string): Promise<void>;
+    /** Mark a user active. */
+    activate(userId: string): Promise<void>;
+}
+/** Options for {@link ActivationService}. */
+interface ActivationServiceOptions {
+    /** The activation persistence port. */
+    store: ActivationStore;
+    /** Token lifetime in seconds. Default 86400 (24h). */
+    ttlSeconds?: number;
+}
+declare class ActivationService {
+    private readonly store;
+    private readonly ttlSeconds;
+    /**
+     * @param options - Store and token TTL.
+     */
+    constructor(options: ActivationServiceOptions);
+    /**
+     * Start activation: issue a token and persist its hash.
+     *
+     * @param userId - The user to activate.
+     * @returns The one-time plaintext token (embed in the activation link).
+     */
+    start(userId: string): Promise<string>;
+    /**
+     * Activate an account from a token.
+     *
+     * @param token - The plaintext token from the activation link.
+     * @returns The activated user id.
+     * @throws {InvalidTokenException} When the token is unknown or expired.
+     */
+    activate(token: string): Promise<string>;
+}
+
+/**
+ * Password-reset flow, mirroring the FastAPI SDK reset flow.
+ *
+ * `request` issues a single-use opaque token (hash stored) for a known email,
+ * returning it so the caller can email the reset link — without leaking whether
+ * the email exists. `confirm` validates the token + new password and rehashes.
+ */
+
+/** Persistence port for password resets. */
+interface PasswordResetStore {
+    /** Resolve a (lowercased) email to a user id, or `null`. */
+    findUserIdByEmail(email: string): Promise<string | null>;
+    /** Persist a reset token hash + expiry (epoch ms). */
+    saveResetToken(userId: string, tokenHash: string, expiresAt: number): Promise<void>;
+    /** Look up a reset token hash, returning owner + expiry, or `null`. */
+    findResetToken(tokenHash: string): Promise<{
+        userId: string;
+        expiresAt: number;
+    } | null>;
+    /** Remove a reset token hash (single-use). */
+    clearResetToken(tokenHash: string): Promise<void>;
+    /** Overwrite a user's password hash. */
+    updatePassword(userId: string, passwordHash: string): Promise<void>;
+}
+/** Options for {@link PasswordResetService}. */
+interface PasswordResetServiceOptions {
+    /** The reset persistence port. */
+    store: PasswordResetStore;
+    /** Password hasher. */
+    password: PasswordUtils;
+    /** Token lifetime in seconds. Default 3600 (1h). */
+    ttlSeconds?: number;
+    /** Minimum new-password length. Default 12. */
+    passwordMinLength?: number;
+}
+declare class PasswordResetService {
+    private readonly store;
+    private readonly password;
+    private readonly ttlSeconds;
+    private readonly passwordMinLength;
+    /**
+     * @param options - Store, password hasher and policy.
+     */
+    constructor(options: PasswordResetServiceOptions);
+    /**
+     * Request a reset for `email`.
+     *
+     * Returns the plaintext token only when the email maps to a user; otherwise
+     * `null`. Callers should respond with the same success shape either way to
+     * avoid user enumeration — email the token only when present.
+     *
+     * @param email - The account email.
+     * @returns The one-time token, or `null` when no user matches.
+     */
+    request(email: string): Promise<string | null>;
+    /**
+     * Confirm a reset: validate the token + new password and rehash.
+     *
+     * @param token - The plaintext reset token.
+     * @param newPassword - The new plaintext password.
+     * @throws {ValidationException} When the new password is too short.
+     * @throws {InvalidTokenException} When the token is unknown or expired.
+     */
+    confirm(token: string, newPassword: string): Promise<void>;
+}
+
 /**
  * JWT auth middleware + role guards, mirroring `api.dependencies.auth`.
  *
@@ -2978,6 +3219,15 @@ interface AuthRouterOptions {
     prefix?: string;
     /** When provided, OpenAPI paths are registered for Swagger/Redoc. */
     registry?: OpenAPIRegistry;
+    /** Mount `POST /auth/activate` when provided. */
+    activation?: ActivationService;
+    /** Mount `POST /auth/password-reset/{request,confirm}` when provided. */
+    passwordReset?: PasswordResetService;
+    /**
+     * Mount guarded `POST /auth/mfa/{enroll,confirm,disable}` when provided. The
+     * enrolling account label defaults to the `email` claim (falls back to `sub`).
+     */
+    mfa?: MfaService;
 }
 /**
  * Build the auth router.
@@ -3219,6 +3469,6 @@ interface RunServerOptions {
 declare function runServer(app: Express, options?: RunServerOptions): Promise<Server>;
 
 /** The installed SDK version. Single source of truth for the barrel + CLI. */
-declare const VERSION = "0.6.0";
+declare const VERSION = "0.7.0";
 
-export { type AdminField, type AdminListQuery, type AdminListResult, type AdminResource, type AdminRouterOptions, AdminSite, AppException, type AppExceptionHandlerOptions, type AppExceptionOptions, type AttachWebSocketOptions, AttemptThrottle, type AttemptThrottleOptions, type AuthResponse, type AuthRouterOptions, type AuthUser, type BaseAppSettings, BaseController, BaseModel, type BaseResponse, BaseService, type BrokerManager, CEP_PATTERN, CNPJ_PATTERN, CPF_PATTERN, type CPUMetrics, type CacheManager, type CachedOptions, type CatalogData, CircuitOpenError, type ClientIpOptions, CompositeFeatureFlagBackend, ConflictException, type CreateAppOpenApi, type CreateAppOptions, type CursorPaginationFilter, DEFAULT_LOCALE, type EmailMessage, type EmailOptions, EmailUtils, type Enum, type EnumHelpers, type EnumSpec, EnvFeatureFlagBackend, EventStream, type EventStreamOptions, type ExceptionDetails, ExpiredTokenException, type FeatureFlagBackend, FeatureFlags, type FlagContext, ForbiddenException, type GenerateOpenApiOptions, HTTPClient, type HTTPClientOptions, HTTP_500_MARKER, type HandshakeInfo, type HealthCheck, type HealthRouterOptions, type InboundHandler, type InboundMessage, InvalidTokenException, type IssuedSession, JSONLogger, JWTUtils, type JWTUtilsOptions, type JwtAuthOptions, type JwtClaims, LocalUploadStorage, type LocalUploadStorageOptions, type LogExtra, type LogLevel, type LoginInput, type MediaKind, MemoryBroker, MemoryCacheManager, MemoryFeatureFlagBackend, type MemoryMetrics, MemorySessionStore, MemoryThrottleBackend, MessageCatalog, type MessageHandler, type MessagingProvider, MetricsUtils, NotFoundException, type OpenApiDocument, type OpenApiInfo, type OutboundMedia, type OutboundResult, PHONE_BR_PATTERN, type PaginationFilter, PasswordUtils, REQUEST_ID_HEADER, RabbitBroker, type RabbitBrokerOptions, RedisCacheManager, type RedisLike, type RedocOptions, type RefreshInput, Region, type RegionValue, type RegisterExceptionHandlersOptions, type RequestContext, type ResponseMapper, RetryPolicy, type RunServerOptions, SSEBroker, type SaveOptions, type SendOptions, ServerSentEvent, type ServerSentEventInit, type Session, type SessionMiddlewareOptions, SessionService, type SessionServiceOptions, type SessionStore, type SignupInput, type StateBR, type SwaggerOptions, type SystemMetrics, TOTPHelper, type TOTPOptions, type TaskHandler, TaskManager, type TaskManagerOptions, TelegramProvider, type TelegramProviderOptions, type ThrottleBackend, type ThrottleStatus, type ToDictOptions, type TokenPair, TooManyRequestsException, type TooManyRequestsOptions, TwilioSmsProvider, type TwilioSmsProviderOptions, type TwilioWebhookOptions, UF, type UFValue, UnauthorizedException, type UnhandledExceptionHandlerOptions, type UploadResult, type UploadStorage, UserAuthService, type UserAuthServiceOptions, type UserPublic, type UserStore, VERSION, ValidationException, type WSEnvelope, WebPushDispatcher, type WebPushDispatcherOptions, WebPushError, WebPushGoneError, type WebPushKeys, type WebPushPayload, type WebPushSubscription, type WebSocketConnection, WebSocketHub, type WebSocketHubOptions, type WebSocketLike, WhatsAppProvider, type WhatsAppProviderOptions, type WhatsAppWebhookOptions, attachWebSocketHub, authResponseSchema, baseAppSettingsSchema, baseAppSettingsShape, baseResponseSchema, bearerToken, buildContentDisposition, cached, cepField, citiesByUf, cnpjField, coerceFlag, configureLogging, corsSettingsShape, cpfField, cpfOrCnpjField, createApp, createOpenApiRegistry, createdByColumn, cursorPaginationFilterSchema, cursorPaginationSchema, databaseSettingsShape, decodeCursor, defaultMessageCatalog, defineEnum, deletedAtColumn, encodeCursor, generateOpaqueToken, generateOpenApiDocument, getAuth, getClientIp, getConditions, getPaginationConditions, getRequestId, getState, hashOpaqueToken, inboundMessageSchema, isValidCep, isValidCity, isValidCnpj, isValidCpf, isValidCpfCnpj, isValidPhoneBr, isValidUf, listStates, loadSettings, loginSchema, makeAdminRouter, makeAppExceptionHandler, makeAuthRouter, makeFlagGuard, makeHealthRouter, makeJwtAuthMiddleware, makeSessionMiddleware, makeTwilioWebhookRouter, makeUnhandledExceptionHandler, makeWhatsAppWebhookRouter, modifyDict, mountOpenApiJson, mountRedoc, mountSwaggerUi, normalizeCep, normalizeCnpj, normalizeCpf, normalizeCpfCnpj, normalizePhoneBr, normalizeUf, notFoundHandler, onlyDigits, paginationFilterSchema, paginationSchema, parseAcceptLanguage, parseCookies, phoneBrField, refreshSchema, registerExceptionHandlers, requestIdMiddleware, requireRoles, runServer, runWithRequestContext, serverSettingsShape, sessionCookie, setRequestId, signupSchema, sseResponse, statesByRegion, tableNameFor, toDict, toUtc, tokenFromUrl, tokenPairSchema, ufField, updatedByColumn, userPublicSchema, utcnow, validateTwilioSignature, verifyOpaqueToken, webPushKeysSchema, webPushPayloadSchema, webPushSubscriptionSchema, wsEnvelopeSchema };
+export { type ActivationInput, ActivationService, type ActivationServiceOptions, type ActivationStore, type AdminField, type AdminListQuery, type AdminListResult, type AdminResource, type AdminRouterOptions, AdminSite, AppException, type AppExceptionHandlerOptions, type AppExceptionOptions, type AttachWebSocketOptions, AttemptThrottle, type AttemptThrottleOptions, type AuthResponse, type AuthRouterOptions, type AuthUser, type BaseAppSettings, BaseController, BaseModel, type BaseResponse, BaseService, type BrokerManager, CEP_PATTERN, CNPJ_PATTERN, CPF_PATTERN, type CPUMetrics, type CacheManager, type CachedOptions, type CatalogData, CircuitOpenError, type ClientIpOptions, CompositeFeatureFlagBackend, ConflictException, type CreateAppOpenApi, type CreateAppOptions, type CursorPaginationFilter, DEFAULT_LOCALE, type EmailMessage, type EmailOptions, EmailUtils, type Enum, type EnumHelpers, type EnumSpec, EnvFeatureFlagBackend, EventStream, type EventStreamOptions, type ExceptionDetails, ExpiredTokenException, type FeatureFlagBackend, FeatureFlags, type FlagContext, ForbiddenException, type GenerateOpenApiOptions, HTTPClient, type HTTPClientOptions, HTTP_500_MARKER, type HandshakeInfo, type HealthCheck, type HealthRouterOptions, type InboundHandler, type InboundMessage, InvalidTokenException, type IssuedSession, JSONLogger, JWTUtils, type JWTUtilsOptions, type JwtAuthOptions, type JwtClaims, LocalUploadStorage, type LocalUploadStorageOptions, type LogExtra, type LogLevel, type LoginInput, type MediaKind, MemoryBroker, MemoryCacheManager, MemoryFeatureFlagBackend, type MemoryMetrics, MemorySessionStore, MemoryThrottleBackend, MessageCatalog, type MessageHandler, type MessagingProvider, MetricsUtils, type MfaCodeInput, type MfaEnrollment, MfaService, type MfaServiceOptions, type MfaStore, NotFoundException, type OpenApiDocument, type OpenApiInfo, type OutboundMedia, type OutboundResult, PHONE_BR_PATTERN, type PaginationFilter, type PasswordResetConfirmInput, type PasswordResetRequestInput, PasswordResetService, type PasswordResetServiceOptions, type PasswordResetStore, PasswordUtils, REQUEST_ID_HEADER, RabbitBroker, type RabbitBrokerOptions, RedisCacheManager, type RedisLike, type RedocOptions, type RefreshInput, Region, type RegionValue, type RegisterExceptionHandlersOptions, type RequestContext, type ResponseMapper, RetryPolicy, type RunServerOptions, SSEBroker, type SaveOptions, type SendOptions, ServerSentEvent, type ServerSentEventInit, type Session, type SessionMiddlewareOptions, SessionService, type SessionServiceOptions, type SessionStore, type SignupInput, type StateBR, type SwaggerOptions, type SystemMetrics, TOTPHelper, type TOTPOptions, type TaskHandler, TaskManager, type TaskManagerOptions, TelegramProvider, type TelegramProviderOptions, type ThrottleBackend, type ThrottleStatus, type ToDictOptions, type TokenPair, TooManyRequestsException, type TooManyRequestsOptions, TwilioSmsProvider, type TwilioSmsProviderOptions, type TwilioWebhookOptions, UF, type UFValue, UnauthorizedException, type UnhandledExceptionHandlerOptions, type UploadResult, type UploadStorage, UserAuthService, type UserAuthServiceOptions, type UserPublic, type UserStore, VERSION, ValidationException, type WSEnvelope, WebPushDispatcher, type WebPushDispatcherOptions, WebPushError, WebPushGoneError, type WebPushKeys, type WebPushPayload, type WebPushSubscription, type WebSocketConnection, WebSocketHub, type WebSocketHubOptions, type WebSocketLike, WhatsAppProvider, type WhatsAppProviderOptions, type WhatsAppWebhookOptions, activationSchema, attachWebSocketHub, authResponseSchema, baseAppSettingsSchema, baseAppSettingsShape, baseResponseSchema, bearerToken, buildContentDisposition, cached, cepField, citiesByUf, cnpjField, coerceFlag, configureLogging, corsSettingsShape, cpfField, cpfOrCnpjField, createApp, createOpenApiRegistry, createdByColumn, cursorPaginationFilterSchema, cursorPaginationSchema, databaseSettingsShape, decodeCursor, defaultMessageCatalog, defineEnum, deletedAtColumn, encodeCursor, generateOpaqueToken, generateOpenApiDocument, getAuth, getClientIp, getConditions, getPaginationConditions, getRequestId, getState, hashOpaqueToken, inboundMessageSchema, isValidCep, isValidCity, isValidCnpj, isValidCpf, isValidCpfCnpj, isValidPhoneBr, isValidUf, listStates, loadSettings, loginSchema, makeAdminRouter, makeAppExceptionHandler, makeAuthRouter, makeFlagGuard, makeHealthRouter, makeJwtAuthMiddleware, makeSessionMiddleware, makeTwilioWebhookRouter, makeUnhandledExceptionHandler, makeWhatsAppWebhookRouter, mfaCodeSchema, mfaEnrollResponseSchema, modifyDict, mountOpenApiJson, mountRedoc, mountSwaggerUi, normalizeCep, normalizeCnpj, normalizeCpf, normalizeCpfCnpj, normalizePhoneBr, normalizeUf, notFoundHandler, onlyDigits, paginationFilterSchema, paginationSchema, parseAcceptLanguage, parseCookies, passwordResetConfirmSchema, passwordResetRequestSchema, phoneBrField, refreshSchema, registerExceptionHandlers, requestIdMiddleware, requireRoles, runServer, runWithRequestContext, serverSettingsShape, sessionCookie, setRequestId, signupSchema, sseResponse, statesByRegion, tableNameFor, toDict, toUtc, tokenFromUrl, tokenPairSchema, ufField, updatedByColumn, userPublicSchema, utcnow, validateTwilioSignature, verifyOpaqueToken, webPushKeysSchema, webPushPayloadSchema, webPushSubscriptionSchema, wsEnvelopeSchema };

package/dist/index.d.ts

@@ -2771,12 +2771,62 @@ declare const authResponseSchema: z.ZodObject<{
         expiresIn: number;
     };
 }>;
+/** MFA enrollment response (`POST /auth/mfa/enroll`). */
+declare const mfaEnrollResponseSchema: z.ZodObject<{
+    secret: z.ZodString;
+    otpauthUri: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    secret: string;
+    otpauthUri: string;
+}, {
+    secret: string;
+    otpauthUri: string;
+}>;
+/** A 6-digit MFA code body (`POST /auth/mfa/confirm|disable`). */
+declare const mfaCodeSchema: z.ZodObject<{
+    code: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    code: string;
+}, {
+    code: string;
+}>;
+/** Activation body (`POST /auth/activate`). */
+declare const activationSchema: z.ZodObject<{
+    token: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    token: string;
+}, {
+    token: string;
+}>;
+/** Password-reset request body (`POST /auth/password-reset/request`). */
+declare const passwordResetRequestSchema: z.ZodObject<{
+    email: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    email: string;
+}, {
+    email: string;
+}>;
+/** Password-reset confirm body (`POST /auth/password-reset/confirm`). */
+declare const passwordResetConfirmSchema: z.ZodObject<{
+    token: z.ZodString;
+    password: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    password: string;
+    token: string;
+}, {
+    password: string;
+    token: string;
+}>;
 type SignupInput = z.infer<typeof signupSchema>;
 type LoginInput = z.infer<typeof loginSchema>;
 type RefreshInput = z.infer<typeof refreshSchema>;
 type TokenPair = z.infer<typeof tokenPairSchema>;
 type UserPublic = z.infer<typeof userPublicSchema>;
 type AuthResponse = z.infer<typeof authResponseSchema>;
+type MfaCodeInput = z.infer<typeof mfaCodeSchema>;
+type ActivationInput = z.infer<typeof activationSchema>;
+type PasswordResetRequestInput = z.infer<typeof passwordResetRequestSchema>;
+type PasswordResetConfirmInput = z.infer<typeof passwordResetConfirmSchema>;
 
 /**
  * User authentication service, mirroring `auth.service.UserAuthService`.
@@ -2871,6 +2921,197 @@ declare class UserAuthService {
     refresh(refreshToken: string): Promise<AuthResponse>;
 }
 
+/**
+ * TOTP MFA enrollment/verification, mirroring the FastAPI SDK MFA flow.
+ *
+ * Orchestrates {@link TOTPHelper} over a pluggable {@link MfaStore}: enroll
+ * (generate + persist a secret, return the provisioning URI), confirm (verify a
+ * code and flip MFA on), verify (login step) and disable.
+ */
+
+/** Persistence port for MFA secrets/state. */
+interface MfaStore {
+    /** Persist a user's TOTP secret (pending until confirmed). */
+    setSecret(userId: string, secret: string): Promise<void>;
+    /** Read a user's TOTP secret, or `null`. */
+    getSecret(userId: string): Promise<string | null>;
+    /** Flip the MFA-enabled flag. */
+    setEnabled(userId: string, enabled: boolean): Promise<void>;
+    /** Whether MFA is enabled for the user. */
+    isEnabled(userId: string): Promise<boolean>;
+}
+/** The result of starting enrollment. */
+interface MfaEnrollment {
+    /** The base32 secret (persist server-side; also shown once for manual entry). */
+    secret: string;
+    /** The `otpauth://` URI to render as a QR code. */
+    otpauthUri: string;
+}
+/** Options for {@link MfaService}. */
+interface MfaServiceOptions {
+    /** The MFA persistence port. */
+    store: MfaStore;
+    /** The TOTP helper (issuer preconfigured). */
+    totp: TOTPHelper;
+}
+declare class MfaService {
+    private readonly store;
+    private readonly totp;
+    /**
+     * @param options - Store and TOTP helper.
+     */
+    constructor(options: MfaServiceOptions);
+    /**
+     * Begin enrollment: generate and persist a secret, return the QR URI.
+     *
+     * @param userId - The enrolling user.
+     * @param accountName - Label shown in the authenticator (usually the email).
+     * @returns The secret and provisioning URI.
+     */
+    enroll(userId: string, accountName: string): Promise<MfaEnrollment>;
+    /**
+     * Confirm enrollment by verifying a code, enabling MFA on success.
+     *
+     * @param userId - The user.
+     * @param code - The 6-digit code from the authenticator.
+     * @throws {ValidationException} When no secret is pending or the code is wrong.
+     */
+    confirm(userId: string, code: string): Promise<void>;
+    /**
+     * Verify a code (login step). Returns `false` without throwing.
+     *
+     * @param userId - The user.
+     * @param code - The submitted code.
+     * @returns `true` when the code is valid.
+     */
+    verify(userId: string, code: string): Promise<boolean>;
+    /**
+     * Disable MFA after verifying a code.
+     *
+     * @param userId - The user.
+     * @param code - The submitted code.
+     * @throws {ValidationException} When the code is invalid.
+     */
+    disable(userId: string, code: string): Promise<void>;
+}
+
+/**
+ * Email-activation flow, mirroring the FastAPI SDK activation flow.
+ *
+ * Issues a single-use opaque token (only its SHA-256 hash is stored), emails
+ * the plaintext to the user, and activates the account when the link is opened.
+ */
+/** Persistence port for activation tokens. */
+interface ActivationStore {
+    /** Persist a token hash + expiry (epoch ms) for a user. */
+    saveActivationToken(userId: string, tokenHash: string, expiresAt: number): Promise<void>;
+    /** Look up a token hash, returning the owner + expiry, or `null`. */
+    findActivationToken(tokenHash: string): Promise<{
+        userId: string;
+        expiresAt: number;
+    } | null>;
+    /** Remove a token hash (single-use). */
+    clearActivationToken(tokenHash: string): Promise<void>;
+    /** Mark a user active. */
+    activate(userId: string): Promise<void>;
+}
+/** Options for {@link ActivationService}. */
+interface ActivationServiceOptions {
+    /** The activation persistence port. */
+    store: ActivationStore;
+    /** Token lifetime in seconds. Default 86400 (24h). */
+    ttlSeconds?: number;
+}
+declare class ActivationService {
+    private readonly store;
+    private readonly ttlSeconds;
+    /**
+     * @param options - Store and token TTL.
+     */
+    constructor(options: ActivationServiceOptions);
+    /**
+     * Start activation: issue a token and persist its hash.
+     *
+     * @param userId - The user to activate.
+     * @returns The one-time plaintext token (embed in the activation link).
+     */
+    start(userId: string): Promise<string>;
+    /**
+     * Activate an account from a token.
+     *
+     * @param token - The plaintext token from the activation link.
+     * @returns The activated user id.
+     * @throws {InvalidTokenException} When the token is unknown or expired.
+     */
+    activate(token: string): Promise<string>;
+}
+
+/**
+ * Password-reset flow, mirroring the FastAPI SDK reset flow.
+ *
+ * `request` issues a single-use opaque token (hash stored) for a known email,
+ * returning it so the caller can email the reset link — without leaking whether
+ * the email exists. `confirm` validates the token + new password and rehashes.
+ */
+
+/** Persistence port for password resets. */
+interface PasswordResetStore {
+    /** Resolve a (lowercased) email to a user id, or `null`. */
+    findUserIdByEmail(email: string): Promise<string | null>;
+    /** Persist a reset token hash + expiry (epoch ms). */
+    saveResetToken(userId: string, tokenHash: string, expiresAt: number): Promise<void>;
+    /** Look up a reset token hash, returning owner + expiry, or `null`. */
+    findResetToken(tokenHash: string): Promise<{
+        userId: string;
+        expiresAt: number;
+    } | null>;
+    /** Remove a reset token hash (single-use). */
+    clearResetToken(tokenHash: string): Promise<void>;
+    /** Overwrite a user's password hash. */
+    updatePassword(userId: string, passwordHash: string): Promise<void>;
+}
+/** Options for {@link PasswordResetService}. */
+interface PasswordResetServiceOptions {
+    /** The reset persistence port. */
+    store: PasswordResetStore;
+    /** Password hasher. */
+    password: PasswordUtils;
+    /** Token lifetime in seconds. Default 3600 (1h). */
+    ttlSeconds?: number;
+    /** Minimum new-password length. Default 12. */
+    passwordMinLength?: number;
+}
+declare class PasswordResetService {
+    private readonly store;
+    private readonly password;
+    private readonly ttlSeconds;
+    private readonly passwordMinLength;
+    /**
+     * @param options - Store, password hasher and policy.
+     */
+    constructor(options: PasswordResetServiceOptions);
+    /**
+     * Request a reset for `email`.
+     *
+     * Returns the plaintext token only when the email maps to a user; otherwise
+     * `null`. Callers should respond with the same success shape either way to
+     * avoid user enumeration — email the token only when present.
+     *
+     * @param email - The account email.
+     * @returns The one-time token, or `null` when no user matches.
+     */
+    request(email: string): Promise<string | null>;
+    /**
+     * Confirm a reset: validate the token + new password and rehash.
+     *
+     * @param token - The plaintext reset token.
+     * @param newPassword - The new plaintext password.
+     * @throws {ValidationException} When the new password is too short.
+     * @throws {InvalidTokenException} When the token is unknown or expired.
+     */
+    confirm(token: string, newPassword: string): Promise<void>;
+}
+
 /**
  * JWT auth middleware + role guards, mirroring `api.dependencies.auth`.
  *
@@ -2978,6 +3219,15 @@ interface AuthRouterOptions {
     prefix?: string;
     /** When provided, OpenAPI paths are registered for Swagger/Redoc. */
     registry?: OpenAPIRegistry;
+    /** Mount `POST /auth/activate` when provided. */
+    activation?: ActivationService;
+    /** Mount `POST /auth/password-reset/{request,confirm}` when provided. */
+    passwordReset?: PasswordResetService;
+    /**
+     * Mount guarded `POST /auth/mfa/{enroll,confirm,disable}` when provided. The
+     * enrolling account label defaults to the `email` claim (falls back to `sub`).
+     */
+    mfa?: MfaService;
 }
 /**
  * Build the auth router.
@@ -3219,6 +3469,6 @@ interface RunServerOptions {
 declare function runServer(app: Express, options?: RunServerOptions): Promise<Server>;
 
 /** The installed SDK version. Single source of truth for the barrel + CLI. */
-declare const VERSION = "0.6.0";
+declare const VERSION = "0.7.0";
 
-export { type AdminField, type AdminListQuery, type AdminListResult, type AdminResource, type AdminRouterOptions, AdminSite, AppException, type AppExceptionHandlerOptions, type AppExceptionOptions, type AttachWebSocketOptions, AttemptThrottle, type AttemptThrottleOptions, type AuthResponse, type AuthRouterOptions, type AuthUser, type BaseAppSettings, BaseController, BaseModel, type BaseResponse, BaseService, type BrokerManager, CEP_PATTERN, CNPJ_PATTERN, CPF_PATTERN, type CPUMetrics, type CacheManager, type CachedOptions, type CatalogData, CircuitOpenError, type ClientIpOptions, CompositeFeatureFlagBackend, ConflictException, type CreateAppOpenApi, type CreateAppOptions, type CursorPaginationFilter, DEFAULT_LOCALE, type EmailMessage, type EmailOptions, EmailUtils, type Enum, type EnumHelpers, type EnumSpec, EnvFeatureFlagBackend, EventStream, type EventStreamOptions, type ExceptionDetails, ExpiredTokenException, type FeatureFlagBackend, FeatureFlags, type FlagContext, ForbiddenException, type GenerateOpenApiOptions, HTTPClient, type HTTPClientOptions, HTTP_500_MARKER, type HandshakeInfo, type HealthCheck, type HealthRouterOptions, type InboundHandler, type InboundMessage, InvalidTokenException, type IssuedSession, JSONLogger, JWTUtils, type JWTUtilsOptions, type JwtAuthOptions, type JwtClaims, LocalUploadStorage, type LocalUploadStorageOptions, type LogExtra, type LogLevel, type LoginInput, type MediaKind, MemoryBroker, MemoryCacheManager, MemoryFeatureFlagBackend, type MemoryMetrics, MemorySessionStore, MemoryThrottleBackend, MessageCatalog, type MessageHandler, type MessagingProvider, MetricsUtils, NotFoundException, type OpenApiDocument, type OpenApiInfo, type OutboundMedia, type OutboundResult, PHONE_BR_PATTERN, type PaginationFilter, PasswordUtils, REQUEST_ID_HEADER, RabbitBroker, type RabbitBrokerOptions, RedisCacheManager, type RedisLike, type RedocOptions, type RefreshInput, Region, type RegionValue, type RegisterExceptionHandlersOptions, type RequestContext, type ResponseMapper, RetryPolicy, type RunServerOptions, SSEBroker, type SaveOptions, type SendOptions, ServerSentEvent, type ServerSentEventInit, type Session, type SessionMiddlewareOptions, SessionService, type SessionServiceOptions, type SessionStore, type SignupInput, type StateBR, type SwaggerOptions, type SystemMetrics, TOTPHelper, type TOTPOptions, type TaskHandler, TaskManager, type TaskManagerOptions, TelegramProvider, type TelegramProviderOptions, type ThrottleBackend, type ThrottleStatus, type ToDictOptions, type TokenPair, TooManyRequestsException, type TooManyRequestsOptions, TwilioSmsProvider, type TwilioSmsProviderOptions, type TwilioWebhookOptions, UF, type UFValue, UnauthorizedException, type UnhandledExceptionHandlerOptions, type UploadResult, type UploadStorage, UserAuthService, type UserAuthServiceOptions, type UserPublic, type UserStore, VERSION, ValidationException, type WSEnvelope, WebPushDispatcher, type WebPushDispatcherOptions, WebPushError, WebPushGoneError, type WebPushKeys, type WebPushPayload, type WebPushSubscription, type WebSocketConnection, WebSocketHub, type WebSocketHubOptions, type WebSocketLike, WhatsAppProvider, type WhatsAppProviderOptions, type WhatsAppWebhookOptions, attachWebSocketHub, authResponseSchema, baseAppSettingsSchema, baseAppSettingsShape, baseResponseSchema, bearerToken, buildContentDisposition, cached, cepField, citiesByUf, cnpjField, coerceFlag, configureLogging, corsSettingsShape, cpfField, cpfOrCnpjField, createApp, createOpenApiRegistry, createdByColumn, cursorPaginationFilterSchema, cursorPaginationSchema, databaseSettingsShape, decodeCursor, defaultMessageCatalog, defineEnum, deletedAtColumn, encodeCursor, generateOpaqueToken, generateOpenApiDocument, getAuth, getClientIp, getConditions, getPaginationConditions, getRequestId, getState, hashOpaqueToken, inboundMessageSchema, isValidCep, isValidCity, isValidCnpj, isValidCpf, isValidCpfCnpj, isValidPhoneBr, isValidUf, listStates, loadSettings, loginSchema, makeAdminRouter, makeAppExceptionHandler, makeAuthRouter, makeFlagGuard, makeHealthRouter, makeJwtAuthMiddleware, makeSessionMiddleware, makeTwilioWebhookRouter, makeUnhandledExceptionHandler, makeWhatsAppWebhookRouter, modifyDict, mountOpenApiJson, mountRedoc, mountSwaggerUi, normalizeCep, normalizeCnpj, normalizeCpf, normalizeCpfCnpj, normalizePhoneBr, normalizeUf, notFoundHandler, onlyDigits, paginationFilterSchema, paginationSchema, parseAcceptLanguage, parseCookies, phoneBrField, refreshSchema, registerExceptionHandlers, requestIdMiddleware, requireRoles, runServer, runWithRequestContext, serverSettingsShape, sessionCookie, setRequestId, signupSchema, sseResponse, statesByRegion, tableNameFor, toDict, toUtc, tokenFromUrl, tokenPairSchema, ufField, updatedByColumn, userPublicSchema, utcnow, validateTwilioSignature, verifyOpaqueToken, webPushKeysSchema, webPushPayloadSchema, webPushSubscriptionSchema, wsEnvelopeSchema };
+export { type ActivationInput, ActivationService, type ActivationServiceOptions, type ActivationStore, type AdminField, type AdminListQuery, type AdminListResult, type AdminResource, type AdminRouterOptions, AdminSite, AppException, type AppExceptionHandlerOptions, type AppExceptionOptions, type AttachWebSocketOptions, AttemptThrottle, type AttemptThrottleOptions, type AuthResponse, type AuthRouterOptions, type AuthUser, type BaseAppSettings, BaseController, BaseModel, type BaseResponse, BaseService, type BrokerManager, CEP_PATTERN, CNPJ_PATTERN, CPF_PATTERN, type CPUMetrics, type CacheManager, type CachedOptions, type CatalogData, CircuitOpenError, type ClientIpOptions, CompositeFeatureFlagBackend, ConflictException, type CreateAppOpenApi, type CreateAppOptions, type CursorPaginationFilter, DEFAULT_LOCALE, type EmailMessage, type EmailOptions, EmailUtils, type Enum, type EnumHelpers, type EnumSpec, EnvFeatureFlagBackend, EventStream, type EventStreamOptions, type ExceptionDetails, ExpiredTokenException, type FeatureFlagBackend, FeatureFlags, type FlagContext, ForbiddenException, type GenerateOpenApiOptions, HTTPClient, type HTTPClientOptions, HTTP_500_MARKER, type HandshakeInfo, type HealthCheck, type HealthRouterOptions, type InboundHandler, type InboundMessage, InvalidTokenException, type IssuedSession, JSONLogger, JWTUtils, type JWTUtilsOptions, type JwtAuthOptions, type JwtClaims, LocalUploadStorage, type LocalUploadStorageOptions, type LogExtra, type LogLevel, type LoginInput, type MediaKind, MemoryBroker, MemoryCacheManager, MemoryFeatureFlagBackend, type MemoryMetrics, MemorySessionStore, MemoryThrottleBackend, MessageCatalog, type MessageHandler, type MessagingProvider, MetricsUtils, type MfaCodeInput, type MfaEnrollment, MfaService, type MfaServiceOptions, type MfaStore, NotFoundException, type OpenApiDocument, type OpenApiInfo, type OutboundMedia, type OutboundResult, PHONE_BR_PATTERN, type PaginationFilter, type PasswordResetConfirmInput, type PasswordResetRequestInput, PasswordResetService, type PasswordResetServiceOptions, type PasswordResetStore, PasswordUtils, REQUEST_ID_HEADER, RabbitBroker, type RabbitBrokerOptions, RedisCacheManager, type RedisLike, type RedocOptions, type RefreshInput, Region, type RegionValue, type RegisterExceptionHandlersOptions, type RequestContext, type ResponseMapper, RetryPolicy, type RunServerOptions, SSEBroker, type SaveOptions, type SendOptions, ServerSentEvent, type ServerSentEventInit, type Session, type SessionMiddlewareOptions, SessionService, type SessionServiceOptions, type SessionStore, type SignupInput, type StateBR, type SwaggerOptions, type SystemMetrics, TOTPHelper, type TOTPOptions, type TaskHandler, TaskManager, type TaskManagerOptions, TelegramProvider, type TelegramProviderOptions, type ThrottleBackend, type ThrottleStatus, type ToDictOptions, type TokenPair, TooManyRequestsException, type TooManyRequestsOptions, TwilioSmsProvider, type TwilioSmsProviderOptions, type TwilioWebhookOptions, UF, type UFValue, UnauthorizedException, type UnhandledExceptionHandlerOptions, type UploadResult, type UploadStorage, UserAuthService, type UserAuthServiceOptions, type UserPublic, type UserStore, VERSION, ValidationException, type WSEnvelope, WebPushDispatcher, type WebPushDispatcherOptions, WebPushError, WebPushGoneError, type WebPushKeys, type WebPushPayload, type WebPushSubscription, type WebSocketConnection, WebSocketHub, type WebSocketHubOptions, type WebSocketLike, WhatsAppProvider, type WhatsAppProviderOptions, type WhatsAppWebhookOptions, activationSchema, attachWebSocketHub, authResponseSchema, baseAppSettingsSchema, baseAppSettingsShape, baseResponseSchema, bearerToken, buildContentDisposition, cached, cepField, citiesByUf, cnpjField, coerceFlag, configureLogging, corsSettingsShape, cpfField, cpfOrCnpjField, createApp, createOpenApiRegistry, createdByColumn, cursorPaginationFilterSchema, cursorPaginationSchema, databaseSettingsShape, decodeCursor, defaultMessageCatalog, defineEnum, deletedAtColumn, encodeCursor, generateOpaqueToken, generateOpenApiDocument, getAuth, getClientIp, getConditions, getPaginationConditions, getRequestId, getState, hashOpaqueToken, inboundMessageSchema, isValidCep, isValidCity, isValidCnpj, isValidCpf, isValidCpfCnpj, isValidPhoneBr, isValidUf, listStates, loadSettings, loginSchema, makeAdminRouter, makeAppExceptionHandler, makeAuthRouter, makeFlagGuard, makeHealthRouter, makeJwtAuthMiddleware, makeSessionMiddleware, makeTwilioWebhookRouter, makeUnhandledExceptionHandler, makeWhatsAppWebhookRouter, mfaCodeSchema, mfaEnrollResponseSchema, modifyDict, mountOpenApiJson, mountRedoc, mountSwaggerUi, normalizeCep, normalizeCnpj, normalizeCpf, normalizeCpfCnpj, normalizePhoneBr, normalizeUf, notFoundHandler, onlyDigits, paginationFilterSchema, paginationSchema, parseAcceptLanguage, parseCookies, passwordResetConfirmSchema, passwordResetRequestSchema, phoneBrField, refreshSchema, registerExceptionHandlers, requestIdMiddleware, requireRoles, runServer, runWithRequestContext, serverSettingsShape, sessionCookie, setRequestId, signupSchema, sseResponse, statesByRegion, tableNameFor, toDict, toUtc, tokenFromUrl, tokenPairSchema, ufField, updatedByColumn, userPublicSchema, utcnow, validateTwilioSignature, verifyOpaqueToken, webPushKeysSchema, webPushPayloadSchema, webPushSubscriptionSchema, wsEnvelopeSchema };