@zudojs/auth 0.1.0 → 1.0.0

package/dist/authPassword/authPassword.core.js

@@ -7,8 +7,22 @@
  * Compatible with Node.js ≥ 24 (no external dependencies).
  */
 import { randomBytes, scrypt, timingSafeEqual } from "node: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;
+/**
+ * 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;
 /** Default key length for scrypt. */
 const KEY_LENGTH = 64;
 /** Scrypt parameters (N, r, p). */
@@ -18,31 +32,73 @@ const SCRYPT_P = 1;
 /**
  * Hash a plain-text password.
  *
- * @param password - Plain-text password
- * @param saltLength - Salt length in bytes (default: 32)
- * @returns Hashed password string in format "scrypt$salt$hash"
+ * @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 async function hashPassword(password, saltLength = SALT_LENGTH) {
+    if (typeof password !== "string") {
+        throw new AuthError("Password must be a string.", {
+            code: ErrorCode.INVALID_INPUT,
+            statusCode: 400,
+        });
+    }
+    if (Buffer.byteLength(password, "utf-8") > MAX_PASSWORD_BYTES) {
+        throw new AuthError(`Password exceeds the maximum of ${MAX_PASSWORD_BYTES} bytes.`, { code: ErrorCode.INVALID_INPUT, statusCode: 400 });
+    }
+    if (!Number.isInteger(saltLength) ||
+        saltLength < MIN_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);
-    return `scrypt${salt}$${derivedKey}`;
+    const derivedKey = await deriveKey(password, salt, {
+        N: SCRYPT_N,
+        r: SCRYPT_R,
+        p: SCRYPT_P,
+    });
+    return `scrypt$${SCRYPT_N}$${SCRYPT_R}$${SCRYPT_P}$${salt}$${derivedKey}`;
 }
 /**
  * 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.
+ *
+ * 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
  */
 export async function verifyPassword(password, hashedPassword) {
-    const parts = hashedPassword.split("$");
-    if (parts.length !== 2 || !parts[0].startsWith("scrypt")) {
+    if (typeof password !== "string" || typeof hashedPassword !== "string") {
+        return false;
+    }
+    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);
     }
-    const salt = parts[0].slice(6);
-    const storedHash = parts[1];
-    const derivedKey = await deriveKey(password, salt);
-    const storedBuffer = Buffer.from(storedHash, "hex");
+    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;
@@ -50,19 +106,21 @@ export async function verifyPassword(password, hashedPassword) {
     return timingSafeEqual(storedBuffer, derivedBuffer);
 }
 /**
- * Check if a password hash needs rehashing (e.g. after salt length change).
+ * 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 parts = hashedPassword.split("$");
-    if (parts.length !== 2 || !parts[0].startsWith("scrypt")) {
+    const parsed = parseHash(hashedPassword);
+    if (!parsed || parsed.legacy)
         return true;
-    }
-    const salt = parts[0].slice(6);
-    const saltBytes = salt.length / 2;
-    return saltBytes !== SALT_LENGTH;
+    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);
 }
 /**
  * Generate a random token string (for password reset, etc.).
@@ -71,11 +129,52 @@ export function needsRehash(hashedPassword) {
  * @returns Hex-encoded random string
  */
 export function generateRandomToken(length = 32) {
+    if (!Number.isInteger(length) || length < 16 || length > 1024) {
+        throw new AuthError("generateRandomToken length must be an integer between 16 and 1024 bytes.", { code: ErrorCode.INVALID_INPUT, statusCode: 400 });
+    }
     return randomBytes(length).toString("hex");
 }
-function deriveKey(password, salt) {
+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: SCRYPT_N, r: SCRYPT_R, p: SCRYPT_P }, (err, derivedKey) => {
+        scrypt(password, salt, KEY_LENGTH, { N: params.N, r: params.r, p: params.p }, (err, derivedKey) => {
             if (err)
                 reject(err);
             else

package/dist/authPassword/index.d.ts

@@ -3,5 +3,5 @@
  *
  * @module authPassword
  */
-export { hashPassword, verifyPassword, needsRehash, generateRandomToken, } from "./authPassword.core.js";
+export { hashPassword, verifyPassword, needsRehash, generateRandomToken, MIN_SALT_LENGTH, MAX_SALT_LENGTH, MAX_PASSWORD_BYTES, } from "./authPassword.core.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/authPassword/index.js

@@ -3,5 +3,5 @@
  *
  * @module authPassword
  */
-export { hashPassword, verifyPassword, needsRehash, generateRandomToken, } from "./authPassword.core.js";
+export { hashPassword, verifyPassword, needsRehash, generateRandomToken, MIN_SALT_LENGTH, MAX_SALT_LENGTH, MAX_PASSWORD_BYTES, } from "./authPassword.core.js";
 //# sourceMappingURL=index.js.map

package/dist/authProvider/authAttempt.memory.d.ts

@@ -0,0 +1,21 @@
+/**
+ * In-memory login attempt store.
+ *
+ * @module authProvider/authAttempt.memory
+ *
+ * Single-process only: counters are not shared between instances. Back
+ * `LoginAttemptStore` with Redis for a real deployment.
+ */
+import type { LoginAttemptStore } from "../authTypes/authAttempt.type.js";
+/**
+ * Create an in-memory {@link LoginAttemptStore}.
+ *
+ * @param options.windowSeconds - Rate-limit window length (default: 60).
+ * @param options.purgeIntervalMs - Minimum gap between sweeps of stale
+ *   entries (default: 60000).
+ */
+export declare function createMemoryLoginAttemptStore(options?: {
+    readonly windowSeconds?: number;
+    readonly purgeIntervalMs?: number;
+}): LoginAttemptStore;
+//# sourceMappingURL=authAttempt.memory.d.ts.map

package/dist/authProvider/authAttempt.memory.js

@@ -0,0 +1,91 @@
+/**
+ * In-memory login attempt store.
+ *
+ * @module authProvider/authAttempt.memory
+ *
+ * Single-process only: counters are not shared between instances. Back
+ * `LoginAttemptStore` with Redis for a real deployment.
+ */
+const DEFAULT_WINDOW_SECONDS = 60;
+const DEFAULT_PURGE_INTERVAL_MS = 60_000;
+const EMPTY = { failures: 0, attempts: 0 };
+/**
+ * Create an in-memory {@link LoginAttemptStore}.
+ *
+ * @param options.windowSeconds - Rate-limit window length (default: 60).
+ * @param options.purgeIntervalMs - Minimum gap between sweeps of stale
+ *   entries (default: 60000).
+ */
+export function createMemoryLoginAttemptStore(options) {
+    const windowMs = (options?.windowSeconds ?? DEFAULT_WINDOW_SECONDS) * 1000;
+    const purgeIntervalMs = options?.purgeIntervalMs ?? DEFAULT_PURGE_INTERVAL_MS;
+    const entries = new Map();
+    let lastPurge = 0;
+    function maybePurge(now) {
+        if (now - lastPurge < purgeIntervalMs)
+            return;
+        lastPurge = now;
+        for (const [key, entry] of entries) {
+            const locked = entry.lockedUntil !== undefined && entry.lockedUntil > now;
+            const fresh = now - entry.windowStart < windowMs;
+            if (!locked && !fresh && entry.failures === 0) {
+                entries.delete(key);
+            }
+        }
+    }
+    function load(identifier, now) {
+        maybePurge(now);
+        let entry = entries.get(identifier);
+        if (!entry) {
+            entry = { failures: 0, attempts: 0, windowStart: now };
+            entries.set(identifier, entry);
+        }
+        if (now - entry.windowStart >= windowMs) {
+            entry.windowStart = now;
+            entry.attempts = 0;
+        }
+        if (entry.lockedUntil !== undefined && entry.lockedUntil <= now) {
+            // Lockout lapsed: clear it and the failure streak that caused it.
+            delete entry.lockedUntil;
+            entry.failures = 0;
+        }
+        return entry;
+    }
+    function snapshot(entry) {
+        return entry.lockedUntil !== undefined
+            ? {
+                failures: entry.failures,
+                attempts: entry.attempts,
+                lockedUntil: entry.lockedUntil,
+            }
+            : { failures: entry.failures, attempts: entry.attempts };
+    }
+    return {
+        async get(identifier) {
+            const now = Date.now();
+            if (!entries.has(identifier)) {
+                maybePurge(now);
+                return EMPTY;
+            }
+            return snapshot(load(identifier, now));
+        },
+        async recordAttempt(identifier) {
+            const entry = load(identifier, Date.now());
+            entry.attempts++;
+            return snapshot(entry);
+        },
+        async recordFailure(identifier) {
+            const entry = load(identifier, Date.now());
+            entry.failures++;
+            return snapshot(entry);
+        },
+        async lock(identifier, until) {
+            const entry = load(identifier, Date.now());
+            entry.lockedUntil = until;
+        },
+        async reset(identifier) {
+            entries.delete(identifier);
+        },
+    };
+}
+//# sourceMappingURL=authAttempt.memory.js.map

package/dist/authProvider/authProvider.core.d.ts

@@ -4,12 +4,15 @@
  * @module authProvider/authProvider
  */
 import type { AuthUser, UserCredentials, UserId } from "../authTypes/authUser.type.js";
-import type { TokenPair, TokenConfig } from "../authTypes/authToken.type.js";
+import type { TokenPair, TokenPayload, TokenConfig, TokenRevocationStore } from "../authTypes/authToken.type.js";
 import type { SessionStore, SessionId } from "../authTypes/authSession.type.js";
-import type { GuardResult } from "../authTypes/authRbac.type.js";
+import type { LoginThrottleConfig } from "../authTypes/authAttempt.type.js";
+import type { GuardContext, GuardResult } from "../authTypes/authRbac.type.js";
 import type { PermissionEngine } from "@zudojs/permissions";
-/** User lookup function provided by the consumer. */
+/** User lookup function provided by the consumer, keyed by login identifier. */
 export type UserLookup = (identifier: string) => Promise<AuthUser | null>;
+/** User lookup function provided by the consumer, keyed by user id. */
+export type UserByIdLookup = (userId: UserId) => Promise<AuthUser | null>;
 /** Password verifier function provided by the consumer. */
 export type PasswordVerifier = (userId: UserId, password: string) => Promise<boolean>;
 /**
@@ -20,14 +23,52 @@ export interface AuthServiceConfig {
     readonly token: TokenConfig;
     /** Session store */
     readonly sessionStore: SessionStore;
-    /** User lookup function */
+    /** User lookup function, keyed by the identifier submitted at login */
     readonly findUser: UserLookup;
+    /**
+     * User lookup keyed by user id (the `sub` claim).
+     *
+     * Used by `refresh()` to re-load the user on every rotation so that
+     * deactivation and role changes take effect instead of being frozen into
+     * the refresh token for its whole lifetime.
+     *
+     * Required. `findUser` is keyed by the login identifier, which for most
+     * deployments is an email or username rather than an id — silently reusing
+     * it here would make every refresh fail closed at runtime. Requiring this
+     * surfaces the mismatch at compile time instead. If your `findUser` really
+     * is id-keyed, pass it for both.
+     */
+    readonly findUserById: UserByIdLookup;
     /** Password verifier function */
     readonly verifyPassword: PasswordVerifier;
-    /** Session TTL in seconds */
+    /** Session idle TTL in seconds */
     readonly sessionTtlSeconds: number;
+    /**
+     * Absolute maximum session lifetime in seconds. Without it, a session that
+     * is used at least once per idle window never expires.
+     */
+    readonly absoluteSessionTtlSeconds?: number;
     /** Optional permission engine */
     readonly permissions?: PermissionEngine;
+    /**
+     * Optional revocation store. When provided, `refresh()` rotates refresh
+     * tokens atomically: the used token's `jti` is revoked so it cannot be
+     * replayed, and a replay attempt destroys the user's sessions.
+     */
+    readonly revocationStore?: TokenRevocationStore;
+    /** Optional brute-force lockout and login rate limiting. */
+    readonly loginThrottle?: LoginThrottleConfig;
+    /**
+     * Allow `checkAccess()` to fall back to the built-in `simpleGuard` when no
+     * `permissions` engine is configured.
+     *
+     * The fallback grants a resource owner *every* permission and grants the
+     * `admin` role everything, so it is opt-in: without this flag,
+     * `checkAccess()` throws instead of silently returning `allowed: true`.
+     */
+    readonly allowInsecureFallbackGuard?: boolean;
+    /** Role name the fallback guard treats as superuser (default: "admin"). */
+    readonly fallbackAdminRole?: string;
 }
 /**
  * Auth service interface.
@@ -37,10 +78,17 @@ export interface AuthService {
         readonly userAgent?: string;
         readonly ip?: string;
     }): Promise<LoginResult>;
-    verifyToken(token: string): Record<string, unknown>;
+    /**
+     * Verify an access token and return its payload.
+     *
+     * Async because a token carrying a `sid` claim is only accepted while its
+     * session is still alive.
+     */
+    verifyToken(token: string): Promise<TokenPayload>;
     refresh(refreshToken: string): Promise<TokenPair>;
-    logout(sessionId: SessionId): Promise<void>;
-    checkAccess(userId: UserId, userRoles: readonly string[], permission: string, resourceOwnerId?: UserId): Promise<GuardResult>;
+    logout(sessionId: SessionId, refreshToken?: string): Promise<void>;
+    logoutAll(userId: UserId): Promise<void>;
+    checkAccess(context: GuardContext): Promise<GuardResult>;
     hashPassword(password: string): Promise<string>;
     verifyPasswordHash(password: string, hash: string): Promise<boolean>;
 }