@zudojs/auth 0.1.1 → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zudojs Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,6 +1,8 @@
 # @zudojs/auth
 
-Authentication primitives including JWT, sessions, password hashing, and RBAC delegation.
+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).
 
 ## Installation
 
@@ -8,44 +10,239 @@ Authentication primitives including JWT, sessions, password hashing, and RBAC de
 npm install @zudojs/auth
 ```
 
-## Quick Start
+## Quick start — the auth service
+
+`createAuthService()` is the primary entry point. It ties the tokens, the
+session store, the password verifier and the permission engine together, and
+it is the only path that gives you working logout, refresh-token rotation and
+account-state enforcement.
 
 ```typescript
 import {
-  createTokenPair,
-  verifyAccessToken,
+  createAuthService,
   createMemorySessionStore,
+  createMemoryTokenRevocationStore,
+  createMemoryLoginAttemptStore,
   hashPassword,
   verifyPassword,
+  type AuthUser,
   type TokenConfig,
 } from "@zudojs/auth";
+import { createPermissionEngine } from "@zudojs/permissions";
+
+// Secrets must be at least 32 bytes and must differ from each other; the
+// package throws AuthConfigurationError otherwise. Never rely on `!` — an
+// env var that is set-but-empty is `""`, not `undefined`.
+function requireSecret(name: string): string {
+  const value = process.env[name];
+  if (!value || value.length < 32) {
+    throw new Error(`${name} must be set to at least 32 characters`);
+  }
+  return value;
+}
 
 const tokenConfig: TokenConfig = {
-  accessSecret: process.env.JWT_ACCESS_SECRET!,
-  refreshSecret: process.env.JWT_REFRESH_SECRET!,
+  accessSecret: requireSecret("JWT_ACCESS_SECRET"),
+  refreshSecret: requireSecret("JWT_REFRESH_SECRET"),
   accessTtl: 900, // seconds (15 minutes)
   refreshTtl: 604_800, // seconds (7 days)
+  issuer: "my-api",
+  audience: "my-app",
+  clockToleranceSeconds: 5, // optional skew allowance for exp/iat/nbf
 };
 
-const tokens = createTokenPair(user.id, tokenConfig, { roles: user.roles });
+const auth = createAuthService({
+  token: tokenConfig,
+
+  // Required: where sessions live. Swap for a Redis-backed SessionStore in
+  // production — the in-memory store is per-process.
+  sessionStore: createMemorySessionStore(),
+
+  // Required: idle timeout for a session, in seconds.
+  sessionTtlSeconds: 86_400,
+  // Recommended: hard ceiling on session age, regardless of activity.
+  absoluteSessionTtlSeconds: 7 * 86_400,
+
+  // 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.
+  findUserById: async (id) => findUserById(id),
+
+  // Required: check a plain-text password for a user id.
+  verifyPassword: async (userId, password) =>
+    verifyPassword(password, await loadHash(userId)),
+
+  // Optional: enables atomic refresh-token rotation and replay detection.
+  revocationStore: createMemoryTokenRevocationStore(),
+
+  // Optional: failed-attempt lockout + login rate limiting.
+  loginThrottle: {
+    store: createMemoryLoginAttemptStore({ windowSeconds: 60 }),
+    maxFailedAttempts: 5, // -> AccountLockedError (423)
+    lockoutSeconds: 900,
+    maxAttemptsPerWindow: 20, // -> AuthRateLimitError (429)
+  },
+
+  // Optional: real permission matching. Without it, `checkAccess()` throws
+  // unless you also set `allowInsecureFallbackGuard: true` (see below).
+  permissions: createPermissionEngine({
+    roles: [{ name: "admin", permissions: ["*:*"] }],
+  }),
+});
+
+const { user, tokens, sessionId } = await auth.login(
+  { identifier: "alice@example.com", password: "correct horse battery" },
+  { userAgent: req.headers["user-agent"], ip: req.socket.remoteAddress },
+);
+
+const payload = await auth.verifyToken(tokens.accessToken); // async
+const rotated = await auth.refresh(tokens.refreshToken);
+
+await auth.logout(sessionId, tokens.refreshToken); // kills both tokens
+await auth.logoutAll(user.id); // sign out everywhere
+```
+
+### Sessions are the kill switch
+
+`login()` stamps the session id into both tokens as a `sid` claim.
+`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.
+
+### Refresh-token rotation
+
+With a `revocationStore` configured, `refresh()` claims the presented token's
+`jti` atomically (via `revokeIfNotRevoked`) before minting the next pair.
+Replaying an already-used refresh token throws `TokenRevokedError` **and**
+destroys every session for that user, on the assumption that the chain is
+compromised (RFC 6819 §5.2.2.3). Implement `revokeIfNotRevoked` in any custom
+store — the `isRevoked` + `revoke` fallback is racy.
+
+### Access control
+
+```typescript
+const decision = await auth.checkAccess({
+  userId: user.id,
+  roles: user.roles,
+  permission: "billing:refund",
+  resourceOwnerId: invoice.ownerId, // optional
+});
+```
+
+When a `permissions` engine is configured the decision comes from it. When it
+is not, `checkAccess()` **throws** `AuthConfigurationError` rather than
+guessing. Setting `allowInsecureFallbackGuard: true` opts into a built-in
+fallback that grants a resource owner *every* permission and grants the
+`fallbackAdminRole` (default `"admin"`) everything; its allowed results carry
+a `reason` naming the fallback so the decision is auditable.
+
+## Standalone JWT helpers
+
+```typescript
+import { jwt, createTokenPair, verifyAccessToken } from "@zudojs/auth";
+
+const tokens = createTokenPair(userId, tokenConfig, { roles: ["editor"] });
 const result = verifyAccessToken(tokens.accessToken, tokenConfig);
+```
+
+The `jwt` namespace bundles `createTokenPair`, `verifyAccessToken`,
+`verifyRefreshToken`, `refreshAccessToken`, `createMemoryTokenRevocationStore`,
+`parseBearerToken`, `isTokenExpired` and `extractUserId`.
+
+`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.
 
-const sessionStore = createMemorySessionStore();
-const hash = await hashPassword("plain-text-password");
+Tokens are capped at 8 KB and every segment is bounds-checked before it is
+decoded, so an oversized `Authorization` header is rejected without
+allocating.
+
+## Passwords
+
+```typescript
+import { hashPassword, verifyPassword, needsRehash } from "@zudojs/auth";
+
+const hash = await hashPassword("plain-text-password"); // scrypt N=16384,r=8,p=1
 const ok = await verifyPassword("plain-text-password", hash);
+if (needsRehash(hash)) { /* re-hash on next successful login */ }
 ```
 
-## Features
+- 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.
+- The package enforces **no password policy** (length, complexity,
+  breach checks) — that belongs in your registration handler.
+
+## HTTP helpers
+
+```typescript
+import {
+  parseBearerToken, // RFC 7235 case-insensitive scheme, whitespace tolerant
+  parseCookies, // null-prototype result, capped at 100 pairs / 8 KB
+  generateCsrfToken,
+  isTokenExpired, // UNVERIFIED — a hint, never an authorization decision
+  extractUserId, // UNVERIFIED — attacker-controlled, returns null if not a string
+} from "@zudojs/auth";
+```
+
+`parseBearerToken` and `parseCookies` accept `unknown` on purpose: they sit on
+the HTTP trust boundary, where a duplicated header is a `string[]`. They never
+throw.
+
+## Errors
+
+Every error carries an accurate HTTP status and is safe to expose:
+
+| Error | Status | Category |
+| --- | --- | --- |
+| `AuthError` | 401 | authentication |
+| `InvalidCredentialsError` | 401 | authentication |
+| `TokenExpiredError` | 401 | authentication |
+| `TokenInvalidError` | 401 | authentication |
+| `SessionExpiredError` | 401 | authentication |
+| `TokenRevokedError` | 403 | authorization |
+| `AccountDeactivatedError` | 403 | authorization |
+| `AccessDeniedError` | 403 | authorization |
+| `AccountLockedError` | 423 | rate_limit |
+| `AuthRateLimitError` | 429 | rate_limit |
+| `AuthConfigurationError` | 500 | configuration (not exposed) |
+
+`AccountLockedError` and `AuthRateLimitError` carry
+`metadata.retryAfterSeconds` for a `Retry-After` header; `AccessDeniedError`
+carries `metadata.requiredPermission`.
+
+`login()` throws the same `InvalidCredentialsError` for an unknown user and a
+wrong password, and performs equivalent scrypt work on both paths, so the
+endpoint is not an account-existence oracle. Deactivation is only reported
+after the password has been proven correct.
+
+## What this package does *not* do
 
-- JWT creation and verification
-- Session management with stores
-- Password hashing and verification
-- RBAC delegation to `@zudojs/permissions`
-- Token refresh and revocation
+- **No OAuth2 / social login.** OAuth2 lives in
+  [`@zudojs/auth-oauth`](../auth-oauth), which implements the
+  authorization-code flow with PKCE, mandatory `state`, and provider presets
+  for Google, GitHub, Microsoft, Apple and Discord. Nothing OAuth-related is
+  exported from this package any more.
+- **No password-reset flow.** `generateRandomToken()` gives you a random
+  token; storage, expiry, single-use enforcement and constant-time comparison
+  are yours to build.
+- **No distributed state.** The in-memory session, revocation and attempt
+  stores are per-process. Implement `SessionStore`, `TokenRevocationStore` and
+  `LoginAttemptStore` against Redis or a database for multi-instance
+  deployments.
+- **No `AccessDeniedError` throwing.** `checkAccess()` returns a
+  `GuardResult`; throw the error from your own middleware when
+  `allowed === false`.
 
 ## Use Cases
 
-- API authentication
-- Session-based login
-- Password reset flows
-- Role-based access control
+- API authentication with rotating refresh tokens
+- Session-based login with real logout and "sign out everywhere"
+- Role-based access control via `@zudojs/permissions`

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

@@ -2,47 +2,81 @@
  * Authentication and authorization error classes.
  *
  * @module authErrors
+ *
+ * Every error in this module carries an accurate HTTP `statusCode` and is
+ * marked `expose: true`. The messages are deliberately generic (they never
+ * 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";
+/**
+ * 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.
  */
-import { BaseError, ErrorCode, type ErrorMetadata } from "@zudojs/errors";
+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?: {
-        readonly code?: ErrorCode;
-        readonly metadata?: ErrorMetadata;
-        readonly cause?: unknown;
-    });
+    constructor(message: string, options?: AuthErrorOptions);
+}
+/**
+ * The package is misconfigured (missing/weak signing secret, missing
+ * permission engine, …). Not caused by the request, so `500` and not exposed.
+ */
+export declare class AuthConfigurationError extends AuthError {
+    constructor(message: string, options?: AuthErrorOptions);
 }
 /**
  * Invalid credentials (wrong password, unknown user).
+ *
+ * Deliberately identical for "no such user" and "wrong password" so the
+ * login endpoint is not an account-existence oracle.
  */
 export declare class InvalidCredentialsError extends AuthError {
-    constructor(message?: string);
+    constructor(message?: string, options?: AuthErrorOptions);
 }
 /**
  * Token has expired.
  */
 export declare class TokenExpiredError extends AuthError {
-    constructor(message?: string);
+    constructor(message?: string, options?: AuthErrorOptions);
 }
 /**
  * Token is invalid or malformed.
  */
 export declare class TokenInvalidError extends AuthError {
-    constructor(message?: string);
+    constructor(message?: string, options?: AuthErrorOptions);
 }
 /**
  * Token has been revoked.
  */
 export declare class TokenRevokedError extends AuthError {
-    constructor(message?: string);
+    constructor(message?: string, options?: AuthErrorOptions);
 }
 /**
  * User account is locked (too many failed attempts).
+ *
+ * `423 Locked`; `metadata.retryAfterSeconds` is intended for a `Retry-After`
+ * response header.
  */
 export declare class AccountLockedError extends AuthError {
-    constructor(message?: string, options?: {
+    constructor(message?: string, options?: AuthErrorOptions & {
         readonly retryAfterSeconds?: number;
     });
 }
@@ -50,13 +84,13 @@ export declare class AccountLockedError extends AuthError {
  * User account is deactivated.
  */
 export declare class AccountDeactivatedError extends AuthError {
-    constructor(message?: string);
+    constructor(message?: string, options?: AuthErrorOptions);
 }
 /**
  * Access denied (insufficient permissions).
  */
 export declare class AccessDeniedError extends AuthError {
-    constructor(message?: string, options?: {
+    constructor(message?: string, options?: AuthErrorOptions & {
         readonly requiredPermission?: string;
     });
 }
@@ -64,13 +98,13 @@ export declare class AccessDeniedError extends AuthError {
  * Session has expired or is invalid.
  */
 export declare class SessionExpiredError extends AuthError {
-    constructor(message?: string);
+    constructor(message?: string, options?: AuthErrorOptions);
 }
 /**
- * Rate limit exceeded for auth endpoint.
+ * Rate limit exceeded for an auth endpoint.
  */
 export declare class AuthRateLimitError extends AuthError {
-    constructor(message?: string, options?: {
+    constructor(message?: string, options?: AuthErrorOptions & {
         readonly retryAfterSeconds?: number;
     });
 }

package/dist/authErrors/authError.base.js

@@ -2,63 +2,120 @@
  * Authentication and authorization error classes.
  *
  * @module authErrors
+ *
+ * Every error in this module carries an accurate HTTP `statusCode` and is
+ * marked `expose: true`. The messages are deliberately generic (they never
+ * 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";
 /**
  * Base error for all auth-related failures.
+ *
+ * Defaults to `401 Unauthorized`, category `authentication`, `expose: true`.
  */
 export class AuthError extends BaseError {
     constructor(message, options) {
         super(message, {
             code: options?.code ?? ErrorCode.AUTHENTICATION,
-            category: ErrorCategory.AUTHENTICATION,
-            severity: ErrorSeverity.ERROR,
+            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,
         });
     }
 }
+/**
+ * The package is misconfigured (missing/weak signing secret, missing
+ * permission engine, …). Not caused by the request, so `500` and not exposed.
+ */
+export class AuthConfigurationError extends AuthError {
+    constructor(message, options) {
+        super(message, {
+            code: ErrorCode.CONFIGURATION_INVALID,
+            category: ErrorCategory.CONFIGURATION,
+            severity: ErrorSeverity.CRITICAL,
+            statusCode: 500,
+            expose: false,
+            isOperational: false,
+            ...options,
+        });
+    }
+}
 /**
  * Invalid credentials (wrong password, unknown user).
+ *
+ * Deliberately identical for "no such user" and "wrong password" so the
+ * login endpoint is not an account-existence oracle.
  */
 export class InvalidCredentialsError extends AuthError {
-    constructor(message = "Invalid credentials") {
-        super(message, { code: ErrorCode.INVALID_CREDENTIALS });
+    constructor(message = "Invalid credentials", options) {
+        super(message, {
+            code: ErrorCode.INVALID_CREDENTIALS,
+            statusCode: 401,
+            ...options,
+        });
     }
 }
 /**
  * Token has expired.
  */
 export class TokenExpiredError extends AuthError {
-    constructor(message = "Token has expired") {
-        super(message, { code: ErrorCode.TOKEN_EXPIRED });
+    constructor(message = "Token has expired", options) {
+        super(message, {
+            code: ErrorCode.TOKEN_EXPIRED,
+            statusCode: 401,
+            ...options,
+        });
     }
 }
 /**
  * Token is invalid or malformed.
  */
 export class TokenInvalidError extends AuthError {
-    constructor(message = "Token is invalid") {
-        super(message, { code: ErrorCode.TOKEN_INVALID });
+    constructor(message = "Token is invalid", options) {
+        super(message, {
+            code: ErrorCode.TOKEN_INVALID,
+            statusCode: 401,
+            ...options,
+        });
     }
 }
 /**
  * Token has been revoked.
  */
 export class TokenRevokedError extends AuthError {
-    constructor(message = "Token has been revoked") {
-        super(message, { code: ErrorCode.FORBIDDEN });
+    constructor(message = "Token has been revoked", options) {
+        super(message, {
+            code: ErrorCode.FORBIDDEN,
+            category: ErrorCategory.AUTHORIZATION,
+            statusCode: 403,
+            ...options,
+        });
     }
 }
 /**
  * User account is locked (too many failed attempts).
+ *
+ * `423 Locked`; `metadata.retryAfterSeconds` is intended for a `Retry-After`
+ * response header.
  */
 export class AccountLockedError extends AuthError {
     constructor(message = "Account is locked due to too many failed attempts", options) {
+        const { retryAfterSeconds, metadata, ...rest } = options ?? {};
         super(message, {
             code: ErrorCode.FORBIDDEN,
+            category: ErrorCategory.RATE_LIMIT,
+            statusCode: 423,
+            ...rest,
             metadata: {
-                retryAfterSeconds: options?.retryAfterSeconds ?? 900,
+                retryAfterSeconds: retryAfterSeconds ?? 900,
+                ...metadata,
             },
         });
     }
@@ -67,8 +124,13 @@ export class AccountLockedError extends AuthError {
  * User account is deactivated.
  */
 export class AccountDeactivatedError extends AuthError {
-    constructor(message = "User account is deactivated") {
-        super(message, { code: ErrorCode.FORBIDDEN });
+    constructor(message = "User account is deactivated", options) {
+        super(message, {
+            code: ErrorCode.FORBIDDEN,
+            category: ErrorCategory.AUTHORIZATION,
+            statusCode: 403,
+            ...options,
+        });
     }
 }
 /**
@@ -76,10 +138,15 @@ export class AccountDeactivatedError extends AuthError {
  */
 export class AccessDeniedError extends AuthError {
     constructor(message = "Access denied", options) {
+        const { requiredPermission, metadata, ...rest } = options ?? {};
         super(message, {
             code: ErrorCode.ACCESS_DENIED,
+            category: ErrorCategory.AUTHORIZATION,
+            statusCode: 403,
+            ...rest,
             metadata: {
-                requiredPermission: options?.requiredPermission,
+                ...(requiredPermission !== undefined ? { requiredPermission } : {}),
+                ...metadata,
             },
         });
     }
@@ -88,19 +155,28 @@ export class AccessDeniedError extends AuthError {
  * Session has expired or is invalid.
  */
 export class SessionExpiredError extends AuthError {
-    constructor(message = "Session has expired") {
-        super(message, { code: ErrorCode.SESSION_EXPIRED });
+    constructor(message = "Session has expired", options) {
+        super(message, {
+            code: ErrorCode.SESSION_EXPIRED,
+            statusCode: 401,
+            ...options,
+        });
     }
 }
 /**
- * Rate limit exceeded for auth endpoint.
+ * Rate limit exceeded for an auth endpoint.
  */
 export class AuthRateLimitError extends AuthError {
     constructor(message = "Too many authentication attempts", options) {
+        const { retryAfterSeconds, metadata, ...rest } = options ?? {};
         super(message, {
             code: ErrorCode.RATE_LIMITED,
+            category: ErrorCategory.RATE_LIMIT,
+            statusCode: 429,
+            ...rest,
             metadata: {
-                retryAfterSeconds: options?.retryAfterSeconds ?? 60,
+                retryAfterSeconds: retryAfterSeconds ?? 60,
+                ...metadata,
             },
         });
     }

package/dist/authErrors/index.d.ts

@@ -3,5 +3,5 @@
  *
  * @module authErrors
  */
-export { AuthError, InvalidCredentialsError, TokenExpiredError, TokenInvalidError, TokenRevokedError, AccountLockedError, AccountDeactivatedError, AccessDeniedError, SessionExpiredError, AuthRateLimitError, } from "./authError.base.js";
+export { AuthError, type AuthErrorOptions, AuthConfigurationError, InvalidCredentialsError, TokenExpiredError, TokenInvalidError, TokenRevokedError, AccountLockedError, AccountDeactivatedError, AccessDeniedError, SessionExpiredError, AuthRateLimitError, } from "./authError.base.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/authErrors/index.js

@@ -3,5 +3,5 @@
  *
  * @module authErrors
  */
-export { AuthError, InvalidCredentialsError, TokenExpiredError, TokenInvalidError, TokenRevokedError, AccountLockedError, AccountDeactivatedError, AccessDeniedError, SessionExpiredError, AuthRateLimitError, } from "./authError.base.js";
+export { AuthError, AuthConfigurationError, InvalidCredentialsError, TokenExpiredError, TokenInvalidError, TokenRevokedError, AccountLockedError, AccountDeactivatedError, AccessDeniedError, SessionExpiredError, AuthRateLimitError, } from "./authError.base.js";
 //# sourceMappingURL=index.js.map

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

@@ -6,12 +6,29 @@
  * Uses scrypt with salt for secure password hashing.
  * Compatible with Node.js ≥ 24 (no external dependencies).
  */
+/** 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;
 /**
  * Hash a plain-text password.
  *
- * @param password - Plain-text password
- * @param saltLength - Salt length in bytes (default: 32)
+ * @param password - Plain-text password. Must be 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"
+ * @throws {AuthError} with `ErrorCode.INVALID_INPUT` when the password is
+ *   not a string, is too long, or the salt length is out of range.
  */
 export declare function hashPassword(password: string, saltLength?: number): Promise<string>;
 /**
@@ -20,6 +37,12 @@ export declare function hashPassword(password: string, saltLength?: number): Pro
  * 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.
  *
+ * Never throws: any input this function cannot make sense of — a
+ * non-string, an over-length password (see {@link MAX_PASSWORD_BYTES}), an
+ * unparseable hash — is a non-match. Callers are on the request path and
+ * treat a `false` as "wrong password", which is the correct outcome for all
+ * of those.
+ *
  * @param password - Plain-text password to verify
  * @param hashedPassword - Previously hashed password
  * @returns Whether the password matches