@zudojs/auth 1.0.0 → 1.2.0

package/README.md

@@ -4,6 +4,12 @@ Authentication primitives: JWT access/refresh tokens, server-side sessions,
 scrypt password hashing, brute-force lockout, and RBAC delegation to
 [`@zudojs/permissions`](https://www.npmjs.com/package/@zudojs/permissions).
 
+<!-- zudo-docs:start -->
+
+**Documentation:** [zudojs.oyinlola.site/docs/packages-auth](https://zudojs.oyinlola.site/docs/packages-auth) · **For AI agents:** [Markdown version](https://zudojs.oyinlola.site/docs/packages-auth.md), [llms.txt](https://zudojs.oyinlola.site/llms.txt)
+
+<!-- zudo-docs:end -->
+
 ## Installation
 
 ```bash
@@ -66,10 +72,10 @@ const auth = createAuthService({
   // Required: look up a user by the identifier submitted at login.
   findUser: async (identifier) => findUserByEmail(identifier),
 
-  // Strongly recommended: look up a user by id. `refresh()` uses it to
-  // re-load the user on every rotation, so deactivations and role changes
-  // take effect immediately. Without it, `refresh()` falls back to
-  // `findUser(sub)` and rejects the refresh when that returns null.
+  // Required: look up a user by id (the token's `sub` claim). `refresh()`
+  // uses it to re-load the user on every rotation, so deactivations and
+  // role changes take effect immediately. It is keyed differently from
+  // `findUser` — do not pass an email-keyed lookup here.
   findUserById: async (id) => findUserById(id),
 
   // Required: check a plain-text password for a user id.
@@ -79,12 +85,14 @@ const auth = createAuthService({
   // Optional: enables atomic refresh-token rotation and replay detection.
   revocationStore: createMemoryTokenRevocationStore(),
 
-  // Optional: failed-attempt lockout + login rate limiting.
+  // Optional: failed-attempt lockout + login rate limiting. Counters are
+  // keyed by the submitted identifier, trimmed and case-folded, so
+  // "Alice@Example.com" and "alice@example.com" share one budget.
   loginThrottle: {
     store: createMemoryLoginAttemptStore({ windowSeconds: 60 }),
     maxFailedAttempts: 5, // -> AccountLockedError (423)
     lockoutSeconds: 900,
-    maxAttemptsPerWindow: 20, // -> AuthRateLimitError (429)
+    maxAttemptsPerWindow: 20, // -> AuthRateLimitError (429), per identifier
   },
 
   // Optional: real permission matching. Without it, `checkAccess()` throws
@@ -112,8 +120,28 @@ await auth.logoutAll(user.id); // sign out everywhere
 `verifyToken()` and `refresh()` require that session to still exist, so
 `logout()` / `logoutAll()` invalidate outstanding access **and** refresh
 tokens immediately rather than leaving them live for their natural lifetime.
-Tokens minted with the standalone `createTokenPair()` carry no `sid` and are
-therefore not session-bound.
+Tokens minted with the standalone `createTokenPair()` carry no `sid`, so no
+logout can revoke them. **The service therefore rejects a token without a
+`sid` (`TokenInvalidError`) unless you set `allowSessionlessTokens: true`.**
+Accepting them by default let a session-less refresh chain outlive
+`logoutAll()`.
+
+### Brute-force lockout
+
+A failure is reserved *before* the password is checked and cleared on
+success, so a parallel burst gets exactly `maxFailedAttempts` guesses before
+the lockout, not `maxAttemptsPerWindow`. Custom `LoginAttemptStore`s must make
+`recordFailure` atomic for this to hold.
+
+The budgets are **per identifier**. An attacker rotating identifiers is not
+limited by them, and every unknown identifier still costs one scrypt
+verification, so put a per-IP limiter (`createRateLimiter` from
+`@zudojs/security`) in front of `login()`.
+
+`createMemoryLoginAttemptStore({ failureTtlSeconds, maxEntries })` forgets an
+unlocked failure streak after `failureTtlSeconds` of inactivity (default 900)
+and caps the tracked identifiers at `maxEntries` (default 100 000, oldest
+unlocked evicted first), so spraying identifiers cannot grow it without bound.
 
 ### Refresh-token rotation
 
@@ -158,7 +186,9 @@ The `jwt` namespace bundles `createTokenPair`, `verifyAccessToken`,
 `jwt.refreshAccessToken()` is the **non-rotating** variant: it checks the
 signature, expiry and type and nothing else — no revocation store, no user
 re-load, no session check — so a stolen refresh token stays replayable for its
-full lifetime. Use `auth.refresh()` for anything user-facing.
+full lifetime. Use `auth.refresh()` for anything user-facing. A refresh token
+that carries a `sid` produces a pair with the same `sid`, so the new tokens
+still die with that session when verified through the service.
 
 Tokens are capped at 8 KB and every segment is bounds-checked before it is
 decoded, so an oversized `Authorization` header is rejected without
@@ -169,11 +199,25 @@ allocating.
 ```typescript
 import { hashPassword, verifyPassword, needsRehash } from "@zudojs/auth";
 
-const hash = await hashPassword("plain-text-password"); // scrypt N=16384,r=8,p=1
+const hash = await hashPassword("plain-text-password"); // "v1$scrypt$16384$8$5$…"
 const ok = await verifyPassword("plain-text-password", hash);
 if (needsRehash(hash)) { /* re-hash on next successful login */ }
 ```
 
+Hashing is delegated to `@zudojs/crypto`: new hashes are its
+`v1$scrypt$N$r$p$<salt>.<hash>` strings (Base64URL, 32-byte salt, 64-byte key)
+with OWASP's N=2^14, r=8, p=5 row. Hashes written by earlier versions of this
+package (`scrypt$N$r$p$…`, including the p=1 default and the param-less legacy
+format) still verify, and `needsRehash()` returns `true` for every hash that is
+not a current-parameter `@zudojs/crypto` scrypt hash, so they upgrade on the
+next login. `hashPassword("")` throws `AuthError` (`INVALID_INPUT`).
+
+- `createAuthService()` validates its configuration up front: bad or
+  identical secrets, a non-positive or `NaN` `sessionTtlSeconds` /
+  `absoluteSessionTtlSeconds`, and a non-finite (`NaN`/`Infinity`)
+  `accessTtl` / `refreshTtl` all throw `AuthConfigurationError` at construction rather
+  than at the first login (a `NaN` session TTL used to yield sessions that
+  never expired).
 - Passwords are limited to 1024 bytes (`MAX_PASSWORD_BYTES`).
 - The optional `saltLength` argument must be 16–64 bytes.
 - `verifyPassword` never throws: junk input is a non-match.

package/dist/authErrors/authError.base.d.ts

@@ -8,33 +8,14 @@
  * name a user, a password, or an account state that the caller did not
  * already supply), so they are safe to return to a client verbatim.
  */
-import { BaseError, ErrorCode, ErrorCategory, ErrorSeverity, type ErrorMetadata } from "@zudojs/errors";
+import { AuthError, type AuthErrorOptions } from "@zudojs/errors";
 /**
- * Options accepted by {@link AuthError} and every subclass.
- *
- * Subclasses supply sensible defaults for `code`, `category`, `statusCode`
- * and `expose`; anything passed here overrides them. Accepting the full set
- * also keeps `BaseError.withMetadata()` — which reconstructs the error from
- * its own fields — lossless for these classes.
+ * `AuthError` (the base of every class below) and `AuthErrorOptions` live
+ * in `@zudojs/errors`; they are re-exported here so existing imports keep
+ * working. Defaults: `401 Unauthorized`, category `authentication`,
+ * `expose: true`; every default can be overridden.
  */
-export interface AuthErrorOptions {
-    readonly code?: ErrorCode;
-    readonly category?: ErrorCategory;
-    readonly severity?: ErrorSeverity;
-    readonly statusCode?: number;
-    readonly expose?: boolean;
-    readonly isOperational?: boolean;
-    readonly metadata?: ErrorMetadata;
-    readonly cause?: unknown;
-}
-/**
- * Base error for all auth-related failures.
- *
- * Defaults to `401 Unauthorized`, category `authentication`, `expose: true`.
- */
-export declare class AuthError extends BaseError {
-    constructor(message: string, options?: AuthErrorOptions);
-}
+export { AuthError, type AuthErrorOptions };
 /**
  * The package is misconfigured (missing/weak signing secret, missing
  * permission engine, …). Not caused by the request, so `500` and not exposed.

package/dist/authErrors/authError.base.js

@@ -8,28 +8,14 @@
  * name a user, a password, or an account state that the caller did not
  * already supply), so they are safe to return to a client verbatim.
  */
-import { BaseError, ErrorCode, ErrorCategory, ErrorSeverity, } from "@zudojs/errors";
+import { AuthError, ErrorCode, ErrorCategory, ErrorSeverity, } from "@zudojs/errors";
 /**
- * Base error for all auth-related failures.
- *
- * Defaults to `401 Unauthorized`, category `authentication`, `expose: true`.
+ * `AuthError` (the base of every class below) and `AuthErrorOptions` live
+ * in `@zudojs/errors`; they are re-exported here so existing imports keep
+ * working. Defaults: `401 Unauthorized`, category `authentication`,
+ * `expose: true`; every default can be overridden.
  */
-export class AuthError extends BaseError {
-    constructor(message, options) {
-        super(message, {
-            code: options?.code ?? ErrorCode.AUTHENTICATION,
-            category: options?.category ?? ErrorCategory.AUTHENTICATION,
-            severity: options?.severity ?? ErrorSeverity.ERROR,
-            statusCode: options?.statusCode ?? 401,
-            expose: options?.expose ?? true,
-            ...(options?.isOperational !== undefined
-                ? { isOperational: options.isOperational }
-                : {}),
-            metadata: options?.metadata,
-            cause: options?.cause,
-        });
-    }
-}
+export { AuthError };
 /**
  * The package is misconfigured (missing/weak signing secret, missing
  * permission engine, …). Not caused by the request, so `500` and not exposed.

package/dist/authPassword/authPassword.core.d.ts

@@ -1,41 +1,34 @@
 /**
- * Password hashing and verification using Node.js crypto scrypt.
+ * Password hashing and verification, delegated to `@zudojs/crypto`.
  *
  * @module authPassword/authPassword
  *
- * Uses scrypt with salt for secure password hashing.
- * Compatible with Node.js ≥ 24 (no external dependencies).
+ * New hashes are `@zudojs/crypto` scrypt hashes
+ * (`v1$scrypt$N$r$p$<salt>.<hash>`, Base64URL). Hashes written by earlier
+ * versions of this package (`scrypt$…`) still verify through the legacy
+ * verifier, and `needsRehash()` reports them so they upgrade on next login.
  */
-/** Accepted range for a caller-supplied salt length, in bytes. */
-export declare const MIN_SALT_LENGTH = 16;
-export declare const MAX_SALT_LENGTH = 64;
 /**
- * Maximum accepted password length in bytes.
+ * Hash a plain-text password with `@zudojs/crypto` (scrypt N=2^14, r=8,
+ * p=5, 64-byte key).
  *
- * scrypt's cost is set by N/r, not by the input length, so a long password
- * is not a work-factor amplifier — but it is still an unbounded allocation
- * driven by an unauthenticated request body. 1024 bytes is far past any
- * real passphrase.
- */
-export declare const MAX_PASSWORD_BYTES = 1024;
-/**
- * Hash a plain-text password.
- *
- * @param password - Plain-text password. Must be at most
+ * @param password - Plain-text password. Must be non-empty and at most
  *   {@link MAX_PASSWORD_BYTES} bytes of UTF-8.
  * @param saltLength - Salt length in bytes (default: 32). Must be an integer
  *   between {@link MIN_SALT_LENGTH} and {@link MAX_SALT_LENGTH}; `0` would
  *   otherwise silently produce unsalted, rainbow-table-able hashes.
- * @returns Hashed password string in format "scrypt$N$r$p$salt$hash"
+ * @returns Hashed password string in the `@zudojs/crypto` format
+ *   `v1$scrypt$N$r$p$<salt>.<hash>`
  * @throws {AuthError} with `ErrorCode.INVALID_INPUT` when the password is
- *   not a string, is too long, or the salt length is out of range.
+ *   not a non-empty string, is too long, or the salt length is out of range.
  */
 export declare function hashPassword(password: string, saltLength?: number): Promise<string>;
 /**
  * Verify a plain-text password against a hash.
  *
- * Accepts the current "scrypt$N$r$p$salt$hash" format as well as the
- * legacy "scrypt<salt>$<hash>" format produced by versions ≤ 0.1.1.
+ * `v1$…` hashes are verified by `@zudojs/crypto`. Hashes from earlier
+ * versions of this package ("scrypt$N$r$p$salt$hash" and the ≤ 0.1.1
+ * "scrypt<salt>$<hash>") go through the legacy verifier.
  *
  * Never throws: any input this function cannot make sense of — a
  * non-string, an over-length password (see {@link MAX_PASSWORD_BYTES}), an
@@ -48,17 +41,12 @@ export declare function hashPassword(password: string, saltLength?: number): Pro
  * @returns Whether the password matches
  */
 export declare function verifyPassword(password: string, hashedPassword: string): Promise<boolean>;
-/**
- * Check if a password hash needs rehashing (legacy format, changed
- * scrypt parameters, or changed salt length).
- *
- * @param hashedPassword - The stored hash
- * @returns Whether the hash should be regenerated
- */
-export declare function needsRehash(hashedPassword: string): boolean;
 /**
  * Generate a random token string (for password reset, etc.).
  *
+ * Synchronous by contract, so it draws from `node:crypto` directly: every
+ * `@zudojs/crypto` random helper is asynchronous.
+ *
  * @param length - Token length in bytes (default: 32)
  * @returns Hex-encoded random string
  */

package/dist/authPassword/authPassword.core.js

@@ -1,49 +1,36 @@
 /**
- * Password hashing and verification using Node.js crypto scrypt.
+ * Password hashing and verification, delegated to `@zudojs/crypto`.
  *
  * @module authPassword/authPassword
  *
- * Uses scrypt with salt for secure password hashing.
- * Compatible with Node.js ≥ 24 (no external dependencies).
+ * New hashes are `@zudojs/crypto` scrypt hashes
+ * (`v1$scrypt$N$r$p$<salt>.<hash>`, Base64URL). Hashes written by earlier
+ * versions of this package (`scrypt$…`) still verify through the legacy
+ * verifier, and `needsRehash()` reports them so they upgrade on next login.
  */
-import { randomBytes, scrypt, timingSafeEqual } from "node:crypto";
+import { randomBytes } from "node:crypto";
+import { hashPassword as cryptoHashPassword, verifyPassword as cryptoVerifyPassword, } from "@zudojs/crypto";
 import { ErrorCode } from "@zudojs/errors";
 import { AuthError } from "../authErrors/authError.base.js";
-/** Default salt length in bytes. */
-const SALT_LENGTH = 32;
-/** Accepted range for a caller-supplied salt length, in bytes. */
-export const MIN_SALT_LENGTH = 16;
-export const MAX_SALT_LENGTH = 64;
+import { KEY_LENGTH, MAX_PASSWORD_BYTES, MAX_SALT_LENGTH, MIN_SALT_LENGTH, SALT_LENGTH, SCRYPT_N, SCRYPT_P, SCRYPT_R, } from "./authPassword.policy.js";
+import { isLegacyPasswordHash, verifyLegacyPassword, } from "./authPassword.legacy.js";
 /**
- * Maximum accepted password length in bytes.
+ * Hash a plain-text password with `@zudojs/crypto` (scrypt N=2^14, r=8,
+ * p=5, 64-byte key).
  *
- * scrypt's cost is set by N/r, not by the input length, so a long password
- * is not a work-factor amplifier — but it is still an unbounded allocation
- * driven by an unauthenticated request body. 1024 bytes is far past any
- * real passphrase.
- */
-export const MAX_PASSWORD_BYTES = 1024;
-/** Default key length for scrypt. */
-const KEY_LENGTH = 64;
-/** Scrypt parameters (N, r, p). */
-const SCRYPT_N = 16384;
-const SCRYPT_R = 8;
-const SCRYPT_P = 1;
-/**
- * Hash a plain-text password.
- *
- * @param password - Plain-text password. Must be at most
+ * @param password - Plain-text password. Must be non-empty and at most
  *   {@link MAX_PASSWORD_BYTES} bytes of UTF-8.
  * @param saltLength - Salt length in bytes (default: 32). Must be an integer
  *   between {@link MIN_SALT_LENGTH} and {@link MAX_SALT_LENGTH}; `0` would
  *   otherwise silently produce unsalted, rainbow-table-able hashes.
- * @returns Hashed password string in format "scrypt$N$r$p$salt$hash"
+ * @returns Hashed password string in the `@zudojs/crypto` format
+ *   `v1$scrypt$N$r$p$<salt>.<hash>`
  * @throws {AuthError} with `ErrorCode.INVALID_INPUT` when the password is
- *   not a string, is too long, or the salt length is out of range.
+ *   not a non-empty string, is too long, or the salt length is out of range.
  */
 export async function hashPassword(password, saltLength = SALT_LENGTH) {
-    if (typeof password !== "string") {
-        throw new AuthError("Password must be a string.", {
+    if (typeof password !== "string" || password.length === 0) {
+        throw new AuthError("Password must be a non-empty string.", {
             code: ErrorCode.INVALID_INPUT,
             statusCode: 400,
         });
@@ -56,19 +43,21 @@ export async function hashPassword(password, saltLength = SALT_LENGTH) {
         saltLength > MAX_SALT_LENGTH) {
         throw new AuthError(`saltLength must be an integer between ${MIN_SALT_LENGTH} and ${MAX_SALT_LENGTH} bytes.`, { code: ErrorCode.INVALID_INPUT, statusCode: 400 });
     }
-    const salt = randomBytes(saltLength).toString("hex");
-    const derivedKey = await deriveKey(password, salt, {
-        N: SCRYPT_N,
-        r: SCRYPT_R,
-        p: SCRYPT_P,
+    const result = await cryptoHashPassword(password, {
+        saltBytes: saltLength,
+        keyBytes: KEY_LENGTH,
+        cost: SCRYPT_N,
+        blockSize: SCRYPT_R,
+        parallelization: SCRYPT_P,
     });
-    return `scrypt$${SCRYPT_N}$${SCRYPT_R}$${SCRYPT_P}$${salt}$${derivedKey}`;
+    return result.encoded;
 }
 /**
  * Verify a plain-text password against a hash.
  *
- * Accepts the current "scrypt$N$r$p$salt$hash" format as well as the
- * legacy "scrypt<salt>$<hash>" format produced by versions ≤ 0.1.1.
+ * `v1$…` hashes are verified by `@zudojs/crypto`. Hashes from earlier
+ * versions of this package ("scrypt$N$r$p$salt$hash" and the ≤ 0.1.1
+ * "scrypt<salt>$<hash>") go through the legacy verifier.
  *
  * Never throws: any input this function cannot make sense of — a
  * non-string, an over-length password (see {@link MAX_PASSWORD_BYTES}), an
@@ -87,44 +76,17 @@ export async function verifyPassword(password, hashedPassword) {
     if (Buffer.byteLength(password, "utf-8") > MAX_PASSWORD_BYTES) {
         return false;
     }
-    const parsed = parseHash(hashedPassword);
-    if (!parsed)
-        return false;
-    let derivedKey;
-    try {
-        derivedKey = await deriveKey(password, parsed.salt, parsed.params);
-    }
-    catch {
-        // scrypt rejects params it cannot satisfy (e.g. over maxmem)
-        return false;
-    }
-    const storedBuffer = Buffer.from(parsed.hash, "hex");
-    const derivedBuffer = Buffer.from(derivedKey, "hex");
-    if (storedBuffer.length !== derivedBuffer.length) {
-        return false;
+    if (isLegacyPasswordHash(hashedPassword)) {
+        return verifyLegacyPassword(password, hashedPassword);
     }
-    return timingSafeEqual(storedBuffer, derivedBuffer);
-}
-/**
- * Check if a password hash needs rehashing (legacy format, changed
- * scrypt parameters, or changed salt length).
- *
- * @param hashedPassword - The stored hash
- * @returns Whether the hash should be regenerated
- */
-export function needsRehash(hashedPassword) {
-    const parsed = parseHash(hashedPassword);
-    if (!parsed || parsed.legacy)
-        return true;
-    const saltBytes = parsed.salt.length / 2;
-    return (saltBytes !== SALT_LENGTH ||
-        parsed.params.N !== SCRYPT_N ||
-        parsed.params.r !== SCRYPT_R ||
-        parsed.params.p !== SCRYPT_P);
+    return cryptoVerifyPassword(password, hashedPassword);
 }
 /**
  * Generate a random token string (for password reset, etc.).
  *
+ * Synchronous by contract, so it draws from `node:crypto` directly: every
+ * `@zudojs/crypto` random helper is asynchronous.
+ *
  * @param length - Token length in bytes (default: 32)
  * @returns Hex-encoded random string
  */
@@ -134,52 +96,4 @@ export function generateRandomToken(length = 32) {
     }
     return randomBytes(length).toString("hex");
 }
-function parseHash(hashedPassword) {
-    const parts = hashedPassword.split("$");
-    if (parts.length === 6 && parts[0] === "scrypt") {
-        const N = Number(parts[1]);
-        const r = Number(parts[2]);
-        const p = Number(parts[3]);
-        // Bounds also cap the memory/CPU a corrupted hash string can request.
-        if (!Number.isInteger(N) ||
-            !Number.isInteger(r) ||
-            !Number.isInteger(p) ||
-            N < 2 ||
-            (N & (N - 1)) !== 0 ||
-            N > 1 << 20 ||
-            r < 1 ||
-            r > 64 ||
-            p < 1 ||
-            p > 16) {
-            return null;
-        }
-        return {
-            params: { N, r, p },
-            salt: parts[4],
-            hash: parts[5],
-            legacy: false,
-        };
-    }
-    // Legacy format from ≤ 0.1.1: "scrypt<salt>$<hash>" (no separator
-    // between the prefix and the salt, params not stored).
-    if (parts.length === 2 && parts[0].startsWith("scrypt")) {
-        return {
-            params: { N: SCRYPT_N, r: SCRYPT_R, p: SCRYPT_P },
-            salt: parts[0].slice(6),
-            hash: parts[1],
-            legacy: true,
-        };
-    }
-    return null;
-}
-function deriveKey(password, salt, params) {
-    return new Promise((resolve, reject) => {
-        scrypt(password, salt, KEY_LENGTH, { N: params.N, r: params.r, p: params.p }, (err, derivedKey) => {
-            if (err)
-                reject(err);
-            else
-                resolve(derivedKey.toString("hex"));
-        });
-    });
-}
 //# sourceMappingURL=authPassword.core.js.map

package/dist/authPassword/authPassword.legacy.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Verifier for password hashes written before auth delegated to
+ * `@zudojs/crypto`: `scrypt$N$r$p$<hexSalt>$<hexHash>` and the param-less
+ * `scrypt<hexSalt>$<hexHash>` format from versions ≤ 0.1.1.
+ *
+ * Nothing new is ever written in these formats. They are kept so stored
+ * hashes still verify, and `needsRehash()` reports every one of them.
+ *
+ * @module authPassword/authPassword.legacy
+ */
+/**
+ * Returns whether a stored hash uses one of the legacy auth formats (the
+ * string starts with `scrypt`). Crypto-format hashes start with `v1$`.
+ */
+export declare function isLegacyPasswordHash(hashedPassword: string): boolean;
+/**
+ * Verifies a password against a legacy hash. Returns `false` for an
+ * unparseable hash or parameters scrypt cannot satisfy; never throws.
+ */
+export declare function verifyLegacyPassword(password: string, hashedPassword: string): Promise<boolean>;
+//# sourceMappingURL=authPassword.legacy.d.ts.map

package/dist/authPassword/authPassword.legacy.js

@@ -0,0 +1,85 @@
+/**
+ * Verifier for password hashes written before auth delegated to
+ * `@zudojs/crypto`: `scrypt$N$r$p$<hexSalt>$<hexHash>` and the param-less
+ * `scrypt<hexSalt>$<hexHash>` format from versions ≤ 0.1.1.
+ *
+ * Nothing new is ever written in these formats. They are kept so stored
+ * hashes still verify, and `needsRehash()` reports every one of them.
+ *
+ * @module authPassword/authPassword.legacy
+ */
+import { scrypt } from "node:crypto";
+import { timingSafeEqual } from "@zudojs/crypto";
+/** Derived-key length used by every legacy format. */
+const LEGACY_KEY_LENGTH = 64;
+/** The fixed parameters of the param-less legacy format (≤ 0.1.1). */
+const PARAMLESS_PARAMS = Object.freeze({
+    N: 16384,
+    r: 8,
+    p: 1,
+});
+/**
+ * Returns whether a stored hash uses one of the legacy auth formats (the
+ * string starts with `scrypt`). Crypto-format hashes start with `v1$`.
+ */
+export function isLegacyPasswordHash(hashedPassword) {
+    return hashedPassword.startsWith("scrypt");
+}
+/**
+ * Verifies a password against a legacy hash. Returns `false` for an
+ * unparseable hash or parameters scrypt cannot satisfy; never throws.
+ */
+export async function verifyLegacyPassword(password, hashedPassword) {
+    const parsed = parseLegacyHash(hashedPassword);
+    if (!parsed)
+        return false;
+    let derived;
+    try {
+        derived = await deriveLegacyKey(password, parsed.salt, parsed.params);
+    }
+    catch {
+        return false;
+    }
+    return timingSafeEqual(Buffer.from(parsed.hash, "hex"), derived);
+}
+function parseLegacyHash(hashedPassword) {
+    const parts = hashedPassword.split("$");
+    if (parts.length === 6 && parts[0] === "scrypt") {
+        const N = Number(parts[1]);
+        const r = Number(parts[2]);
+        const p = Number(parts[3]);
+        // Bounds also cap the memory/CPU a corrupted hash string can request.
+        if (!Number.isInteger(N) ||
+            !Number.isInteger(r) ||
+            !Number.isInteger(p) ||
+            N < 2 ||
+            (N & (N - 1)) !== 0 ||
+            N > 1 << 20 ||
+            r < 1 ||
+            r > 64 ||
+            p < 1 ||
+            p > 16) {
+            return null;
+        }
+        return { params: { N, r, p }, salt: parts[4], hash: parts[5] };
+    }
+    if (parts.length === 2 && parts[0].startsWith("scrypt")) {
+        return {
+            params: PARAMLESS_PARAMS,
+            salt: parts[0].slice(6),
+            hash: parts[1],
+        };
+    }
+    return null;
+}
+function deriveLegacyKey(password, salt, params) {
+    return new Promise((resolve, reject) => {
+        scrypt(password, salt, LEGACY_KEY_LENGTH, { N: params.N, r: params.r, p: params.p }, (err, derivedKey) => {
+            if (err)
+                reject(err);
+            else
+                resolve(derivedKey);
+        });
+    });
+}
+//# sourceMappingURL=authPassword.legacy.js.map

package/dist/authPassword/authPassword.policy.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Hashing policy for new auth password hashes. `needsRehash()` flags any
+ * stored hash that does not match it.
+ *
+ * @module authPassword/authPassword.policy
+ */
+/** Default salt length in bytes. */
+export declare const SALT_LENGTH = 32;
+/** Accepted range for a caller-supplied salt length, in bytes. */
+export declare const MIN_SALT_LENGTH = 16;
+export declare const MAX_SALT_LENGTH = 64;
+/**
+ * Maximum accepted password length in bytes.
+ *
+ * scrypt's cost is set by N/r, not by the input length, so a long password
+ * is not a work-factor amplifier — but it is still an unbounded allocation
+ * driven by an unauthenticated request body. 1024 bytes is far past any
+ * real passphrase.
+ */
+export declare const MAX_PASSWORD_BYTES = 1024;
+/** Derived key length in bytes. */
+export declare const KEY_LENGTH = 64;
+/**
+ * Scrypt parameters (N, r, p) for new hashes: the OWASP Password Storage
+ * Cheat Sheet's N=2^14, r=8, p=5 row.
+ */
+export declare const SCRYPT_N = 16384;
+export declare const SCRYPT_R = 8;
+export declare const SCRYPT_P = 5;
+//# sourceMappingURL=authPassword.policy.d.ts.map

package/dist/authPassword/authPassword.policy.js

@@ -0,0 +1,30 @@
+/**
+ * Hashing policy for new auth password hashes. `needsRehash()` flags any
+ * stored hash that does not match it.
+ *
+ * @module authPassword/authPassword.policy
+ */
+/** Default salt length in bytes. */
+export const SALT_LENGTH = 32;
+/** Accepted range for a caller-supplied salt length, in bytes. */
+export const MIN_SALT_LENGTH = 16;
+export const MAX_SALT_LENGTH = 64;
+/**
+ * Maximum accepted password length in bytes.
+ *
+ * scrypt's cost is set by N/r, not by the input length, so a long password
+ * is not a work-factor amplifier — but it is still an unbounded allocation
+ * driven by an unauthenticated request body. 1024 bytes is far past any
+ * real passphrase.
+ */
+export const MAX_PASSWORD_BYTES = 1024;
+/** Derived key length in bytes. */
+export const KEY_LENGTH = 64;
+/**
+ * Scrypt parameters (N, r, p) for new hashes: the OWASP Password Storage
+ * Cheat Sheet's N=2^14, r=8, p=5 row.
+ */
+export const SCRYPT_N = 16384;
+export const SCRYPT_R = 8;
+export const SCRYPT_P = 5;
+//# sourceMappingURL=authPassword.policy.js.map

package/dist/authPassword/authPassword.rehash.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Rehash detection for stored password hashes.
+ *
+ * @module authPassword/authPassword.rehash
+ */
+/**
+ * Check if a password hash needs rehashing: every hash that is not a
+ * `@zudojs/crypto` scrypt hash with the current parameters (N, r, p, salt
+ * and key length). All legacy `scrypt$…` hashes return `true`.
+ *
+ * @param hashedPassword - The stored hash
+ * @returns Whether the hash should be regenerated
+ */
+export declare function needsRehash(hashedPassword: string): boolean;
+//# sourceMappingURL=authPassword.rehash.d.ts.map