@zudojs/auth 1.0.0 → 1.1.0

package/README.md

@@ -66,10 +66,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,7 +79,9 @@ 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)
@@ -174,6 +176,12 @@ const ok = await verifyPassword("plain-text-password", hash);
 if (needsRehash(hash)) { /* re-hash on next successful login */ }
 ```
 
+- `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/authProvider/authProvider.core.d.ts

@@ -9,6 +9,17 @@ import type { SessionStore, SessionId } from "../authTypes/authSession.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";
+/**
+ * The key under which an identifier's login attempts are counted.
+ *
+ * Identifiers are emails or usernames, which consumers almost always
+ * resolve case-insensitively. Counting the raw string gave
+ * `alice@example.com`, `Alice@example.com` and ` alice@example.com` three
+ * independent attempt budgets against one account — a lockout bypass that
+ * cost the attacker nothing. Trimming, NFKC-folding and lower-casing keeps
+ * unknown and known identifiers throttled identically while closing that.
+ */
+export declare function throttleKey(identifier: string): string;
 /** 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. */

package/dist/authProvider/authProvider.core.js

@@ -5,6 +5,8 @@
  */
 import { hashPassword, verifyPassword, } from "../authPassword/authPassword.core.js";
 import { createTokenPair, verifyAccessToken, verifyRefreshToken, } from "../authToken/authToken.core.js";
+import { assertTokenSecrets } from "../authToken/authToken.signing.js";
+import { assertPositiveSeconds } from "../authSession/authSession.core.js";
 import { AccountDeactivatedError, AccountLockedError, AuthConfigurationError, AuthRateLimitError, InvalidCredentialsError, SessionExpiredError, TokenExpiredError, TokenInvalidError, TokenRevokedError, } from "../authErrors/authError.base.js";
 /**
  * A syntactically valid hash that no password matches.
@@ -18,11 +20,31 @@ const DEFAULT_MAX_FAILED_ATTEMPTS = 5;
 const DEFAULT_LOCKOUT_SECONDS = 900;
 const DEFAULT_MAX_ATTEMPTS_PER_WINDOW = 20;
 const DEFAULT_WINDOW_SECONDS = 60;
+/**
+ * The key under which an identifier's login attempts are counted.
+ *
+ * Identifiers are emails or usernames, which consumers almost always
+ * resolve case-insensitively. Counting the raw string gave
+ * `alice@example.com`, `Alice@example.com` and ` alice@example.com` three
+ * independent attempt budgets against one account — a lockout bypass that
+ * cost the attacker nothing. Trimming, NFKC-folding and lower-casing keeps
+ * unknown and known identifiers throttled identically while closing that.
+ */
+export function throttleKey(identifier) {
+    return String(identifier).normalize("NFKC").trim().toLowerCase();
+}
 /**
  * Create an auth service.
  */
 export function createAuthService(config) {
     const { token: tokenConfig, sessionStore, findUser, findUserById, verifyPassword: verifyPwd, sessionTtlSeconds, absoluteSessionTtlSeconds, permissions, revocationStore, loginThrottle, allowInsecureFallbackGuard, fallbackAdminRole, } = config;
+    // Fail at construction, not at the first login: a bad secret or a NaN
+    // lifetime (`Number(process.env.X)` with X unset) otherwise surfaced as
+    // a runtime error on the request path — or, for the session TTL, not at
+    // all, because a NaN idle timeout produced sessions that never expired.
+    assertTokenSecrets(tokenConfig);
+    assertPositiveSeconds(sessionTtlSeconds, "sessionTtlSeconds");
+    assertPositiveSeconds(absoluteSessionTtlSeconds, "absoluteSessionTtlSeconds");
     const maxFailedAttempts = loginThrottle?.maxFailedAttempts ?? DEFAULT_MAX_FAILED_ATTEMPTS;
     const lockoutSeconds = loginThrottle?.lockoutSeconds ?? DEFAULT_LOCKOUT_SECONDS;
     const maxAttemptsPerWindow = loginThrottle?.maxAttemptsPerWindow ?? DEFAULT_MAX_ATTEMPTS_PER_WINDOW;
@@ -31,14 +53,15 @@ export function createAuthService(config) {
     async function enforceThrottle(identifier) {
         if (!loginThrottle)
             return;
+        const key = throttleKey(identifier);
         const now = Date.now();
-        const current = await loginThrottle.store.get(identifier);
+        const current = await loginThrottle.store.get(key);
         if (current.lockedUntil !== undefined && current.lockedUntil > now) {
             throw new AccountLockedError(undefined, {
                 retryAfterSeconds: Math.ceil((current.lockedUntil - now) / 1000),
             });
         }
-        const updated = await loginThrottle.store.recordAttempt(identifier);
+        const updated = await loginThrottle.store.recordAttempt(key);
         if (updated.attempts > maxAttemptsPerWindow) {
             throw new AuthRateLimitError(undefined, {
                 retryAfterSeconds: windowSeconds,
@@ -49,9 +72,10 @@ export function createAuthService(config) {
     async function recordFailure(identifier) {
         if (!loginThrottle)
             return;
-        const updated = await loginThrottle.store.recordFailure(identifier);
+        const key = throttleKey(identifier);
+        const updated = await loginThrottle.store.recordFailure(key);
         if (updated.failures >= maxFailedAttempts) {
-            await loginThrottle.store.lock(identifier, Date.now() + lockoutSeconds * 1000);
+            await loginThrottle.store.lock(key, Date.now() + lockoutSeconds * 1000);
         }
     }
     /**
@@ -114,7 +138,7 @@ export function createAuthService(config) {
             }
             // The credentials were correct, so the attempt counter is cleared even
             // if the account turns out to be unusable.
-            await loginThrottle?.store.reset(identifier);
+            await loginThrottle?.store.reset(throttleKey(identifier));
             // Account state is only disclosed once the password has been proven,
             // so it cannot be probed without a valid credential.
             if (!user.active) {

package/dist/authSession/authSession.core.d.ts

@@ -23,4 +23,11 @@ import type { SessionStore } from "../authTypes/authSession.type.js";
 export declare function createMemorySessionStore(storeOptions?: {
     readonly purgeIntervalMs?: number;
 }): SessionStore;
+/**
+ * Reject a TTL that cannot produce a real expiry.
+ *
+ * @throws {AuthConfigurationError} when `value` is defined but is not a
+ *   finite number greater than zero.
+ */
+export declare function assertPositiveSeconds(value: number | undefined, field: string): void;
 //# sourceMappingURL=authSession.core.d.ts.map

package/dist/authSession/authSession.core.js

@@ -5,6 +5,7 @@
  *
  * For production, implement SessionStore backed by Redis, database, etc.
  */
+import { AuthConfigurationError } from "../authErrors/authError.base.js";
 import { randomBytes } from "node:crypto";
 const DEFAULT_TTL_SECONDS = 86400; // 24 hours
 /** Minimum interval between full sweeps of the session map. */
@@ -42,6 +43,11 @@ export function createMemorySessionStore(storeOptions) {
     }
     return {
         async create(options) {
+            // A non-finite TTL (`Number(undefinedEnvVar)` is the usual source)
+            // produced an `Invalid Date` expiry, and `now > NaN` is always false —
+            // so the session never expired, not even at its absolute deadline.
+            assertPositiveSeconds(options.ttlSeconds, "ttlSeconds");
+            assertPositiveSeconds(options.absoluteTtlSeconds, "absoluteTtlSeconds");
             maybePurgeExpired();
             const id = generateSessionId();
             const now = new Date();
@@ -111,6 +117,20 @@ export function createMemorySessionStore(storeOptions) {
         },
     };
 }
+/**
+ * Reject a TTL that cannot produce a real expiry.
+ *
+ * @throws {AuthConfigurationError} when `value` is defined but is not a
+ *   finite number greater than zero.
+ */
+export function assertPositiveSeconds(value, field) {
+    if (value === undefined)
+        return;
+    if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+        throw new AuthConfigurationError(`${field} must be a finite number of seconds greater than zero; ` +
+            `got ${String(value)}. A NaN lifetime would create a session that never expires.`);
+    }
+}
 function clampToAbsolute(expiresAt, absolute) {
     if (!absolute)
         return expiresAt;

package/dist/authToken/authToken.signing.js

@@ -42,6 +42,21 @@ export function assertTokenSecrets(config) {
             config.clockToleranceSeconds > 300)) {
         throw new AuthConfigurationError("TokenConfig.clockToleranceSeconds must be between 0 and 300 seconds.");
     }
+    // A NaN TTL (`Number(process.env.X)` with X unset) minted tokens whose
+    // `exp` serialised as `null`, which every verifier then rejected as
+    // "Invalid payload" — a misconfiguration that only surfaced as a mystery
+    // at first login. Zero and negative TTLs are deliberately still accepted:
+    // they mint already-expired tokens, which is a documented way to test
+    // expiry handling.
+    assertFiniteTtl(config.accessTtl, "accessTtl");
+    assertFiniteTtl(config.refreshTtl, "refreshTtl");
+}
+function assertFiniteTtl(value, field) {
+    if (value === undefined)
+        return;
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new AuthConfigurationError(`TokenConfig.${field} must be a finite number of seconds; got ${String(value)}.`);
+    }
 }
 function assertSecret(secret, field) {
     if (typeof secret !== "string" || secret.length === 0) {

package/dist/authTypes/authAttempt.type.d.ts

@@ -17,9 +17,11 @@ export interface LoginAttemptRecord {
 /**
  * Store backing failed-attempt lockout and login rate limiting.
  *
- * Keys are the *submitted* identifier, not a resolved user id, so unknown
- * and known accounts are throttled identically and the endpoint stays free
- * of an existence oracle. The in-memory implementation
+ * Keys are the *submitted* identifier — trimmed, NFKC-normalised and
+ * lower-cased by `createAuthService()` so that case and whitespace variants
+ * of one email share a budget — not a resolved user id, so unknown and
+ * known accounts are throttled identically and the endpoint stays free of
+ * an existence oracle. The in-memory implementation
  * (`createMemoryLoginAttemptStore`) is per-process; back this with Redis to
  * make limits hold across instances.
  */

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "@zudojs/auth",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Authentication and authorization services for the Zudojs framework — JWT, sessions, RBAC, and password management.",
   "license": "MIT",
+  "author": {
+    "name": "Oluwayemi Oyinlola",
+    "url": "https://github.com/oyinlola-tech"
+  },
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -21,9 +25,9 @@
     "!dist/.tsbuildinfo"
   ],
   "dependencies": {
-    "@zudojs/errors": "1.0.0",
-    "@zudojs/constants": "1.0.0",
-    "@zudojs/permissions": "1.0.0"
+    "@zudojs/errors": "1.0.1",
+    "@zudojs/constants": "1.0.1",
+    "@zudojs/permissions": "1.1.0"
   },
   "engines": {
     "node": ">=24.0.0"