Skip to Content

Auth Account Lifecycle

Use @puzzle-ui/auth for email verification, password reset and change, profile updates, email changes, and account closure.

StorageAuthLifecycleManager adds account-maintenance workflows to @puzzle-ui/auth. It uses the same storage, session manager, password hasher, and shared rate-limit provider as the core manager, plus an EmailProvider for verification and reset messages.

Configure and initialize

import { StorageAuthLifecycleManager } from "@puzzle-ui/auth";

const lifecycle = new StorageAuthLifecycleManager(
  { storage, passwordHasher, emailProvider, sessions, rateLimitProvider },
  { rateLimitKeySecret },
);

await lifecycle.initialize();

The rateLimitProvider dependency is optional; when omitted, the lifecycle manager creates a StorageRateLimitProvider using its configured rate-limit collection. The storage adapter must support unique constraints, conditional writes, and atomic batches.

Workflows

MethodInputResultBehavior
sendEmailVerification(input)RequestEmailVerificationInputPromise<void>Sends a verification message for the specified userId; input includes verificationUrl and ipAddress.
verifyEmail(token)token stringPromise<AuthUser>Consumes a valid email-verification token and marks the account verified.
requestPasswordReset(input)RequestPasswordResetInputPromise<void>Requests a reset using email, resetUrl, and ipAddress. Use a non-enumerating public response.
resetPassword(input)ResetPasswordInputPromise<void>Consumes the supplied reset token and sets newPassword.
changePassword(input)ChangePasswordInputPromise<void>Requires sessionToken, currentPassword, and newPassword.
updateProfile(input)UpdateAuthProfileInputPromise<AuthUser>Updates the signed-in user's optional name and/or image.
requestEmailChange(input)RequestEmailChangeInputPromise<void>Requires the session and current password; sends confirmation for the requested email using verificationUrl and ipAddress.
verifyEmailChange(token)token stringPromise<AuthUser>Consumes the confirmation token and applies the new email.
deactivateAccount(input)DeactivateAuthAccountInputPromise<void>Deactivates the signed-in account after password confirmation.
deleteAccount(input)DeleteAuthAccountInputPromise<void>Deletes the signed-in account after password confirmation.

Lifecycle methods use the authenticated session for profile, password, email-change, deactivation, and deletion operations. Email verification and password reset use single-use action tokens. Never log the full token or include it in analytics.

AuthLifecycleManagerOptions

OptionTypeDefaultDescription
rateLimitKeySecretstringRequiredAt least 32 characters; used for opaque rate-limit identifiers.
usersCollectionstringauth_usersUser records collection.
credentialsCollectionstringauth_credentialsPassword credential collection.
actionTokensCollectionstringauth_action_tokensSingle-use email and password action tokens.
auditCollectionstringauth_audit_eventsLifecycle audit events.
rateLimitsCollectionstringauth_rate_limitsStorage-backed rate-limit counters when using the default provider.
minimumPasswordLengthnumber8Minimum new-password length.
maximumPasswordLengthnumber1024Maximum password length, also subject to a 4096 UTF-8 byte limit.
emailVerificationTokenLifetimeSecondsnumber3600Email-verification token lifetime.
passwordResetTokenLifetimeSecondsnumber3600Password-reset token lifetime.
emailChangeTokenLifetimeSecondsnumber3600Email-change token lifetime.
emailTemplatesPartial template mapSee defaults belowTemplate identifiers passed to the email provider.
emailSubjectsPartial subject mapSee defaults belowMessage subjects passed to the email provider.
rateLimitsAuthLifecycleRateLimitPoliciesSee defaults belowOverride email and IP rules for verification, reset, and email change.
clock() => Date() => new Date()Clock injection for tests.
requireVerifiedEmailbooleanfalseAlign with the core manager's email-verification policy.
onEmailDeliveryError(error: unknown) => voidUnsetOptional callback for email delivery failures. Do not log secrets from provider errors.
onSessionRevocationError(error: unknown) => voidUnsetOptional callback for session-revocation failures during lifecycle operations.

Default template identifiers are auth/email-verification, auth/password-reset, and auth/email-change-verification. Default subjects are “Verify your email address”, “Reset your password”, and “Confirm your new email address”.

The default rate limits for each of email verification, password reset, and email change are 3 requests per email per hour and 10 requests per IP per hour. Public reset endpoints should return the same response whether or not an account exists.

Email provider contract

Implement the exported EmailProvider.send(message) contract. Each message contains to, subject, template, and a string-valued variables map. Provide your own delivery, templates, retries, and URL generation. Links must use an application-controlled trusted origin; do not build security-sensitive links from an untrusted Host header.

See @puzzle-ui/fullstack for HTTP integration. Pair this page with the storage guide for the persistence guarantees required by single-use account action tokens.