@puzzle-ui/auth
v0.12.0
Published
Framework-independent authentication for accounts, MFA, passkeys, and lifecycle workflows.
Maintainers
Readme
@puzzle-ui/auth
Framework-independent authentication primitives for Puzzle applications. Use this package when you need server-side registration and password sign-in, session validation, email and password lifecycle flows, MFA, passkeys, recovery codes, or step-up authentication without tying your auth core to a framework.
Documentation: puzzle-ui.com/docs/auth
Install
npm install @puzzle-ui/authThe package uses @puzzle-ui/storage and @puzzle-ui/session adapters, and includes a SimpleWebAuthn server adapter. You provide a storage adapter, a session manager, a secure Argon2id PasswordHasher (or the included Pbkdf2PasswordHasher with a secret pepper on runtimes such as Cloudflare Workers), a shared RateLimitProvider, and an email provider for lifecycle workflows.
Minimal usage
import { StorageAuthManager } from "@puzzle-ui/auth";
const auth = new StorageAuthManager(
{ storage, passwordHasher, rateLimitProvider, sessions },
{ rateLimitKeySecret },
);
await auth.initialize();
const result = await auth.register({
email: "[email protected]",
password: "a-long-unique-password",
ipAddress: trustedClientIp,
});
if (!("status" in result)) {
// Store result.token in a secure, HttpOnly cookie on the server.
}Keep session and challenge tokens server-side. The token must not be sent in browser JSON or stored in local or session storage. Add the MFA manager to the dependencies and configure mfaPolicy when MFA is needed.
Features and entry point
The package exports all APIs from the single root entry point, @puzzle-ui/auth:
StorageAuthManagerfor registration, password sign-in, auth state and session revocation.StorageAuthLifecycleManagerfor email verification/change, password reset/change, profile updates, account deactivation and deletion.StorageAuthMfaManagerfor TOTP, WebAuthn passkeys, recovery codes and factor management.StorageAuthStepUpManagerfor session-bound additional MFA verification and session rotation.StorageRateLimitProvider,WebCryptoAuthSecretProtector, andSimpleWebAuthnProvideras built-in infrastructure adapters.- Typed provider contracts, storage records and collection setup, auth errors, and crypto/TOTP utilities.
For storage adapter capabilities and initialization, see @puzzle-ui/storage. For browser clients, secure cookie handlers, and framework adapters, see @puzzle-ui/fullstack. The Authentication Setup guide describes application integration.
Security notes
Auth requires durable storage with the capabilities used by the configured managers. Production deployments should use HTTPS, secure HttpOnly cookies, shared persistent rate limiting, a maintained Argon2id password hasher (or a peppered Pbkdf2PasswordHasher), encrypted TOTP secrets, hashed recovery codes, and exact WebAuthn origin/RP ID configuration. The package does not provide OAuth, application authorization, or ready-made auth pages.
