@zudojs/auth 1.0.0 → 1.2.0

package/dist/authPassword/authPassword.rehash.js

@@ -0,0 +1,33 @@
+/**
+ * Rehash detection for stored password hashes.
+ *
+ * @module authPassword/authPassword.rehash
+ */
+import { CryptoAlgorithm, decodePasswordHash } from "@zudojs/crypto";
+import { KEY_LENGTH, SALT_LENGTH, SCRYPT_N, SCRYPT_P, SCRYPT_R, } from "./authPassword.policy.js";
+/**
+ * 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 function needsRehash(hashedPassword) {
+    if (typeof hashedPassword !== "string")
+        return true;
+    try {
+        const decoded = decodePasswordHash(hashedPassword);
+        if (decoded.algorithm !== CryptoAlgorithm.SCRYPT)
+            return true;
+        return (decoded.salt.byteLength !== SALT_LENGTH ||
+            decoded.hash.byteLength !== KEY_LENGTH ||
+            decoded.cost !== SCRYPT_N ||
+            decoded.blockSize !== SCRYPT_R ||
+            decoded.parallelization !== SCRYPT_P);
+    }
+    catch {
+        return true;
+    }
+}
+//# sourceMappingURL=authPassword.rehash.js.map

package/dist/authPassword/index.d.ts

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

package/dist/authPassword/index.js

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

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

@@ -0,0 +1,26 @@
+/**
+ * Eviction rules for the in-memory login attempt store.
+ *
+ * @module authProvider/authAttempt.eviction
+ */
+/** The fields of an attempt entry that eviction looks at. */
+export interface EvictableAttemptEntry {
+    readonly failures: number;
+    readonly windowStart: number;
+    readonly lastFailureAt: number;
+    readonly lockedUntil?: number;
+}
+/** True when the entry carries no live lockout. */
+export declare function isUnlocked(entry: EvictableAttemptEntry, now: number): boolean;
+/**
+ * True when the entry can be dropped without changing any decision: it is
+ * unlocked, its rate-limit window has passed, and its failure streak (if
+ * any) has been idle for at least `failureTtlMs`.
+ */
+export declare function isStale(entry: EvictableAttemptEntry, now: number, windowMs: number, failureTtlMs: number): boolean;
+/**
+ * Make room for one new entry: drop the oldest unlocked entry (Map order is
+ * insertion order), or the oldest entry of all when every entry is locked.
+ */
+export declare function evictOne<E extends EvictableAttemptEntry>(entries: Map<string, E>, now: number): void;
+//# sourceMappingURL=authAttempt.eviction.d.ts.map

package/dist/authProvider/authAttempt.eviction.js

@@ -0,0 +1,37 @@
+/**
+ * Eviction rules for the in-memory login attempt store.
+ *
+ * @module authProvider/authAttempt.eviction
+ */
+/** True when the entry carries no live lockout. */
+export function isUnlocked(entry, now) {
+    return entry.lockedUntil === undefined || entry.lockedUntil <= now;
+}
+/**
+ * True when the entry can be dropped without changing any decision: it is
+ * unlocked, its rate-limit window has passed, and its failure streak (if
+ * any) has been idle for at least `failureTtlMs`.
+ */
+export function isStale(entry, now, windowMs, failureTtlMs) {
+    if (!isUnlocked(entry, now))
+        return false;
+    if (now - entry.windowStart < windowMs)
+        return false;
+    return entry.failures === 0 || now - entry.lastFailureAt >= failureTtlMs;
+}
+/**
+ * Make room for one new entry: drop the oldest unlocked entry (Map order is
+ * insertion order), or the oldest entry of all when every entry is locked.
+ */
+export function evictOne(entries, now) {
+    for (const [key, entry] of entries) {
+        if (isUnlocked(entry, now)) {
+            entries.delete(key);
+            return;
+        }
+    }
+    const oldest = entries.keys().next();
+    if (!oldest.done)
+        entries.delete(oldest.value);
+}
+//# sourceMappingURL=authAttempt.eviction.js.map

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

@@ -13,9 +13,18 @@ import type { LoginAttemptStore } from "../authTypes/authAttempt.type.js";
  * @param options.windowSeconds - Rate-limit window length (default: 60).
  * @param options.purgeIntervalMs - Minimum gap between sweeps of stale
  *   entries (default: 60000).
+ * @param options.failureTtlSeconds - Idle time after which an unlocked
+ *   failure streak is forgotten and its entry evicted (default: 900).
+ *   Without it, every identifier with one failure was kept forever, so
+ *   spraying random identifiers grew the map without bound.
+ * @param options.maxEntries - Hard cap on tracked identifiers (default:
+ *   100000). At the cap the oldest unlocked entry is evicted; locked
+ *   entries are only evicted when every entry is locked.
  */
 export declare function createMemoryLoginAttemptStore(options?: {
     readonly windowSeconds?: number;
     readonly purgeIntervalMs?: number;
+    readonly failureTtlSeconds?: number;
+    readonly maxEntries?: number;
 }): LoginAttemptStore;
 //# sourceMappingURL=authAttempt.memory.d.ts.map

package/dist/authProvider/authAttempt.memory.js

@@ -6,8 +6,11 @@
  * Single-process only: counters are not shared between instances. Back
  * `LoginAttemptStore` with Redis for a real deployment.
  */
+import { evictOne, isStale, isUnlocked } from "./authAttempt.eviction.js";
 const DEFAULT_WINDOW_SECONDS = 60;
 const DEFAULT_PURGE_INTERVAL_MS = 60_000;
+const DEFAULT_FAILURE_TTL_SECONDS = 900;
+const DEFAULT_MAX_ENTRIES = 100_000;
 const EMPTY = { failures: 0, attempts: 0 };
 /**
  * Create an in-memory {@link LoginAttemptStore}.
@@ -15,10 +18,19 @@ const EMPTY = { failures: 0, attempts: 0 };
  * @param options.windowSeconds - Rate-limit window length (default: 60).
  * @param options.purgeIntervalMs - Minimum gap between sweeps of stale
  *   entries (default: 60000).
+ * @param options.failureTtlSeconds - Idle time after which an unlocked
+ *   failure streak is forgotten and its entry evicted (default: 900).
+ *   Without it, every identifier with one failure was kept forever, so
+ *   spraying random identifiers grew the map without bound.
+ * @param options.maxEntries - Hard cap on tracked identifiers (default:
+ *   100000). At the cap the oldest unlocked entry is evicted; locked
+ *   entries are only evicted when every entry is locked.
  */
 export function createMemoryLoginAttemptStore(options) {
     const windowMs = (options?.windowSeconds ?? DEFAULT_WINDOW_SECONDS) * 1000;
     const purgeIntervalMs = options?.purgeIntervalMs ?? DEFAULT_PURGE_INTERVAL_MS;
+    const failureTtlMs = (options?.failureTtlSeconds ?? DEFAULT_FAILURE_TTL_SECONDS) * 1000;
+    const maxEntries = options?.maxEntries ?? DEFAULT_MAX_ENTRIES;
     const entries = new Map();
     let lastPurge = 0;
     function maybePurge(now) {
@@ -26,20 +38,24 @@ export function createMemoryLoginAttemptStore(options) {
             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) {
+            if (isStale(entry, now, windowMs, failureTtlMs))
                 entries.delete(key);
-            }
         }
     }
     function load(identifier, now) {
         maybePurge(now);
         let entry = entries.get(identifier);
         if (!entry) {
-            entry = { failures: 0, attempts: 0, windowStart: now };
+            if (entries.size >= maxEntries)
+                evictOne(entries, now);
+            entry = { failures: 0, attempts: 0, windowStart: now, lastFailureAt: 0 };
             entries.set(identifier, entry);
         }
+        if (entry.failures > 0 &&
+            isUnlocked(entry, now) &&
+            now - entry.lastFailureAt >= failureTtlMs) {
+            entry.failures = 0;
+        }
         if (now - entry.windowStart >= windowMs) {
             entry.windowStart = now;
             entry.attempts = 0;
@@ -77,6 +93,7 @@ export function createMemoryLoginAttemptStore(options) {
         async recordFailure(identifier) {
             const entry = load(identifier, Date.now());
             entry.failures++;
+            entry.lastFailureAt = Date.now();
             return snapshot(entry);
         },
         async lock(identifier, until) {

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

@@ -9,6 +9,7 @@ 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";
+export { throttleKey } from "./authProvider.throttle.js";
 /** 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. */
@@ -69,6 +70,18 @@ export interface AuthServiceConfig {
     readonly allowInsecureFallbackGuard?: boolean;
     /** Role name the fallback guard treats as superuser (default: "admin"). */
     readonly fallbackAdminRole?: string;
+    /**
+     * Accept access and refresh tokens that carry no `sid` claim (default:
+     * `false`).
+     *
+     * Every pair `login()` mints is session-bound, so by default
+     * `verifyToken()` and `refresh()` reject a token without a `sid`: such a
+     * token cannot be revoked by `logout()` or `logoutAll()`, and accepting
+     * it let a session-less refresh chain outlive "sign out everywhere". Set
+     * this only if you also mint tokens with the standalone `createTokenPair()`
+     * and verify them through this service.
+     */
+    readonly allowSessionlessTokens?: boolean;
 }
 /**
  * Auth service interface.

package/dist/authProvider/authProvider.core.js

@@ -3,9 +3,12 @@
  *
  * @module authProvider/authProvider
  */
+import { createLoginThrottleGate } from "./authProvider.throttle.js";
 import { hashPassword, verifyPassword, } from "../authPassword/authPassword.core.js";
 import { createTokenPair, verifyAccessToken, verifyRefreshToken, } from "../authToken/authToken.core.js";
-import { AccountDeactivatedError, AccountLockedError, AuthConfigurationError, AuthRateLimitError, InvalidCredentialsError, SessionExpiredError, TokenExpiredError, TokenInvalidError, TokenRevokedError, } from "../authErrors/authError.base.js";
+import { assertTokenSecrets } from "../authToken/authToken.signing.js";
+import { assertPositiveSeconds } from "../authSession/authSession.core.js";
+import { AccountDeactivatedError, AuthConfigurationError, InvalidCredentialsError, SessionExpiredError, TokenExpiredError, TokenInvalidError, TokenRevokedError, } from "../authErrors/authError.base.js";
 /**
  * A syntactically valid hash that no password matches.
  *
@@ -13,57 +16,32 @@ import { AccountDeactivatedError, AccountLockedError, AuthConfigurationError, Au
  * the unknown-user path takes comparable time to the wrong-password path and
  * the response time does not disclose whether an account exists.
  */
-const DUMMY_PASSWORD_HASH = `scrypt$16384$8$1$${"0".repeat(64)}$${"0".repeat(128)}`;
-const DEFAULT_MAX_FAILED_ATTEMPTS = 5;
-const DEFAULT_LOCKOUT_SECONDS = 900;
-const DEFAULT_MAX_ATTEMPTS_PER_WINDOW = 20;
-const DEFAULT_WINDOW_SECONDS = 60;
+const DUMMY_PASSWORD_HASH = `v1$scrypt$16384$8$5$${"A".repeat(43)}.${"A".repeat(86)}`;
+export { throttleKey } from "./authProvider.throttle.js";
 /**
  * Create an auth service.
  */
 export function createAuthService(config) {
-    const { token: tokenConfig, sessionStore, findUser, findUserById, verifyPassword: verifyPwd, sessionTtlSeconds, absoluteSessionTtlSeconds, permissions, revocationStore, loginThrottle, allowInsecureFallbackGuard, fallbackAdminRole, } = config;
-    const maxFailedAttempts = loginThrottle?.maxFailedAttempts ?? DEFAULT_MAX_FAILED_ATTEMPTS;
-    const lockoutSeconds = loginThrottle?.lockoutSeconds ?? DEFAULT_LOCKOUT_SECONDS;
-    const maxAttemptsPerWindow = loginThrottle?.maxAttemptsPerWindow ?? DEFAULT_MAX_ATTEMPTS_PER_WINDOW;
-    const windowSeconds = loginThrottle?.windowSeconds ?? DEFAULT_WINDOW_SECONDS;
-    /** Throw if the identifier is locked out or over its attempt budget. */
-    async function enforceThrottle(identifier) {
-        if (!loginThrottle)
-            return;
-        const now = Date.now();
-        const current = await loginThrottle.store.get(identifier);
-        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);
-        if (updated.attempts > maxAttemptsPerWindow) {
-            throw new AuthRateLimitError(undefined, {
-                retryAfterSeconds: windowSeconds,
-            });
-        }
-    }
-    /** Record a failed authentication and lock the identifier if warranted. */
-    async function recordFailure(identifier) {
-        if (!loginThrottle)
-            return;
-        const updated = await loginThrottle.store.recordFailure(identifier);
-        if (updated.failures >= maxFailedAttempts) {
-            await loginThrottle.store.lock(identifier, Date.now() + lockoutSeconds * 1000);
-        }
-    }
+    const { token: tokenConfig, sessionStore, findUser, findUserById, verifyPassword: verifyPwd, sessionTtlSeconds, absoluteSessionTtlSeconds, permissions, revocationStore, loginThrottle, allowInsecureFallbackGuard, fallbackAdminRole, allowSessionlessTokens, } = 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 throttle = createLoginThrottleGate(loginThrottle);
     /**
      * Reject the token unless the session it was issued against is still
      * alive; refresh the session's idle timer when it is.
      */
     async function requireLiveSession(payload) {
         const sid = payload.sid;
-        // Tokens minted by `createTokenPair` directly carry no `sid`; they cannot
-        // be forged, and there is no session to check for them.
-        if (!sid)
-            return undefined;
+        if (!sid) {
+            if (allowSessionlessTokens)
+                return undefined;
+            throw new TokenInvalidError("Token is not bound to a session");
+        }
         const session = await sessionStore.get(sid);
         if (!session) {
             throw new SessionExpiredError("Session is no longer active");
@@ -97,7 +75,7 @@ export function createAuthService(config) {
          */
         async login(credentials, context) {
             const identifier = credentials.identifier;
-            await enforceThrottle(identifier);
+            const slot = await throttle.begin(identifier);
             const user = await findUser(identifier);
             let authenticated = false;
             if (user) {
@@ -109,12 +87,12 @@ export function createAuthService(config) {
                 await verifyPassword(credentials.password, DUMMY_PASSWORD_HASH);
             }
             if (!user || !authenticated) {
-                await recordFailure(identifier);
+                await throttle.fail(identifier, slot);
                 throw new InvalidCredentialsError();
             }
             // 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 throttle.succeed(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/authProvider/authProvider.throttle.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Login throttling for `createAuthService()` — failed-attempt lockout and
+ * per-identifier rate limiting.
+ *
+ * @module authProvider/authProvider.throttle
+ */
+import type { LoginThrottleConfig } from "../authTypes/authAttempt.type.js";
+/**
+ * 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;
+/** A failure slot reserved by {@link LoginThrottleGate.begin}. */
+export interface LoginThrottleSlot {
+    /** The failure count including this attempt's reservation. */
+    readonly failures: number;
+}
+/** Lockout and rate-limit gate wrapped around one `login()` call. */
+export interface LoginThrottleGate {
+    /**
+     * Admit an attempt. Throws when the identifier is locked or over its
+     * window budget; otherwise reserves a failure slot *before* the password
+     * is checked and returns it.
+     */
+    begin(identifier: string): Promise<LoginThrottleSlot>;
+    /** The attempt failed: lock the identifier if its slot reached the limit. */
+    fail(identifier: string, slot: LoginThrottleSlot): Promise<void>;
+    /** The credentials were correct: clear the identifier's counters. */
+    succeed(identifier: string): Promise<void>;
+}
+/**
+ * Build the throttle gate for a {@link LoginThrottleConfig}.
+ *
+ * The failure is counted up front and cleared on success. Counting it only
+ * after the (slow) password check was check-then-act: a parallel burst all
+ * passed the lock check before any failure landed, so an attacker got
+ * `maxAttemptsPerWindow` guesses per lockout instead of `maxFailedAttempts`.
+ * With the reservation, the (n+1)th concurrent attempt sees `failures > n`
+ * and is refused without evaluating the password. This relies on the
+ * store's `recordFailure` being atomic, as the in-memory store's is.
+ *
+ * An attempt that throws for another reason (e.g. the user lookup fails)
+ * keeps its reservation, so it counts as a failure.
+ */
+export declare function createLoginThrottleGate(config: LoginThrottleConfig | undefined): LoginThrottleGate;
+//# sourceMappingURL=authProvider.throttle.d.ts.map

package/dist/authProvider/authProvider.throttle.js

@@ -0,0 +1,88 @@
+/**
+ * Login throttling for `createAuthService()` — failed-attempt lockout and
+ * per-identifier rate limiting.
+ *
+ * @module authProvider/authProvider.throttle
+ */
+import { AccountLockedError, AuthRateLimitError, } from "../authErrors/authError.base.js";
+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();
+}
+const NO_SLOT = Object.freeze({ failures: 0 });
+/**
+ * Build the throttle gate for a {@link LoginThrottleConfig}.
+ *
+ * The failure is counted up front and cleared on success. Counting it only
+ * after the (slow) password check was check-then-act: a parallel burst all
+ * passed the lock check before any failure landed, so an attacker got
+ * `maxAttemptsPerWindow` guesses per lockout instead of `maxFailedAttempts`.
+ * With the reservation, the (n+1)th concurrent attempt sees `failures > n`
+ * and is refused without evaluating the password. This relies on the
+ * store's `recordFailure` being atomic, as the in-memory store's is.
+ *
+ * An attempt that throws for another reason (e.g. the user lookup fails)
+ * keeps its reservation, so it counts as a failure.
+ */
+export function createLoginThrottleGate(config) {
+    const maxFailedAttempts = config?.maxFailedAttempts ?? DEFAULT_MAX_FAILED_ATTEMPTS;
+    const lockoutMs = (config?.lockoutSeconds ?? DEFAULT_LOCKOUT_SECONDS) * 1000;
+    const maxAttemptsPerWindow = config?.maxAttemptsPerWindow ?? DEFAULT_MAX_ATTEMPTS_PER_WINDOW;
+    const windowSeconds = config?.windowSeconds ?? DEFAULT_WINDOW_SECONDS;
+    function locked(record, now) {
+        const until = record.lockedUntil ?? now + lockoutMs;
+        return new AccountLockedError(undefined, {
+            retryAfterSeconds: Math.max(1, Math.ceil((until - now) / 1000)),
+        });
+    }
+    return {
+        async begin(identifier) {
+            if (!config)
+                return NO_SLOT;
+            const key = throttleKey(identifier);
+            const now = Date.now();
+            const current = await config.store.get(key);
+            if (current.lockedUntil !== undefined && current.lockedUntil > now) {
+                throw locked(current, now);
+            }
+            const updated = await config.store.recordAttempt(key);
+            if (updated.attempts > maxAttemptsPerWindow) {
+                throw new AuthRateLimitError(undefined, {
+                    retryAfterSeconds: windowSeconds,
+                });
+            }
+            const reserved = await config.store.recordFailure(key);
+            if (reserved.failures > maxFailedAttempts) {
+                const alreadyLocked = reserved.lockedUntil !== undefined && reserved.lockedUntil > now;
+                if (!alreadyLocked)
+                    await config.store.lock(key, now + lockoutMs);
+                throw locked(reserved, now);
+            }
+            return { failures: reserved.failures };
+        },
+        async fail(identifier, slot) {
+            if (!config)
+                return;
+            if (slot.failures >= maxFailedAttempts) {
+                await config.store.lock(throttleKey(identifier), Date.now() + lockoutMs);
+            }
+        },
+        async succeed(identifier) {
+            await config?.store.reset(throttleKey(identifier));
+        },
+    };
+}
+//# sourceMappingURL=authProvider.throttle.js.map

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,7 +5,8 @@
  *
  * For production, implement SessionStore backed by Redis, database, etc.
  */
-import { randomBytes } from "node:crypto";
+import { randomHex } from "@zudojs/crypto";
+import { AuthConfigurationError } from "../authErrors/authError.base.js";
 const DEFAULT_TTL_SECONDS = 86400; // 24 hours
 /** Minimum interval between full sweeps of the session map. */
 const DEFAULT_PURGE_INTERVAL_MS = 60_000;
@@ -42,8 +43,13 @@ 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 id = await generateSessionId();
             const now = new Date();
             const ttlMs = (options.ttlSeconds ?? DEFAULT_TTL_SECONDS) * 1000;
             const absoluteExpiresAt = options.absoluteTtlSeconds !== undefined
@@ -111,12 +117,27 @@ 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;
     return expiresAt.getTime() > absolute.getTime() ? absolute : expiresAt;
 }
-function generateSessionId() {
-    return randomBytes(32).toString("hex");
+/** 32 random bytes from `@zudojs/crypto`, hex-encoded (64 characters). */
+async function generateSessionId() {
+    return (await randomHex(64));
 }
 //# sourceMappingURL=authSession.core.js.map

package/dist/authToken/authToken.core.d.ts

@@ -50,6 +50,12 @@ export declare function verifyRefreshToken(token: JwtToken, config: TokenConfig)
  * user so deactivation and role changes take effect, and validates the
  * session. This function exists for callers who manage all of that
  * themselves.
+ *
+ * A session-bound refresh token (one with a `sid` claim) yields a pair bound
+ * to the same session, so the new tokens still die with `logout()` /
+ * `logoutAll()` when verified through `createAuthService()`. Earlier
+ * versions dropped the `sid`, turning a logged-out session's refresh token
+ * into a permanent, unbound token chain.
  */
 export declare function refreshAccessToken(refreshToken: JwtToken, config: TokenConfig, options?: {
     readonly roles?: readonly string[];

package/dist/authToken/authToken.core.js

@@ -88,13 +88,21 @@ export function verifyRefreshToken(token, config) {
  * user so deactivation and role changes take effect, and validates the
  * session. This function exists for callers who manage all of that
  * themselves.
+ *
+ * A session-bound refresh token (one with a `sid` claim) yields a pair bound
+ * to the same session, so the new tokens still die with `logout()` /
+ * `logoutAll()` when verified through `createAuthService()`. Earlier
+ * versions dropped the `sid`, turning a logged-out session's refresh token
+ * into a permanent, unbound token chain.
  */
 export function refreshAccessToken(refreshToken, config, options) {
     const result = verifyRefreshToken(refreshToken, config);
     if (!result.valid || !result.payload)
         return null;
+    const sid = result.payload.sid;
     return createTokenPair(result.payload.sub, config, {
         roles: options?.roles ?? result.payload.roles,
+        ...(sid ? { sessionId: sid } : {}),
     });
 }
 //# sourceMappingURL=authToken.core.js.map

package/dist/authToken/authToken.signing.d.ts

@@ -36,6 +36,11 @@ export declare function signToken(payload: TokenPayload, secret: string): JwtTok
  * Never throws for untrusted input: every failure is reported as
  * `{ valid: false, error }`. Oversized tokens are rejected before anything
  * is decoded.
+ *
+ * The signature segment is compared as the canonical base64url *string*,
+ * not as decoded bytes: lenient base64 decoding ignores non-alphabet
+ * characters and non-zero trailing bits, which gave one issued token an
+ * unbounded number of accepted spellings.
  */
 export declare function verifyToken(token: JwtToken, secret: string, expectedType: "access" | "refresh", config: TokenConfig): TokenVerificationResult;
 /**

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) {
@@ -69,6 +84,11 @@ export function signToken(payload, secret) {
  * Never throws for untrusted input: every failure is reported as
  * `{ valid: false, error }`. Oversized tokens are rejected before anything
  * is decoded.
+ *
+ * The signature segment is compared as the canonical base64url *string*,
+ * not as decoded bytes: lenient base64 decoding ignores non-alphabet
+ * characters and non-zero trailing bits, which gave one issued token an
+ * unbounded number of accepted spellings.
  */
 export function verifyToken(token, secret, expectedType, config) {
     const parts = splitToken(token);
@@ -85,8 +105,8 @@ export function verifyToken(token, secret, expectedType, config) {
     }
     const signatureInput = `${headerB64}.${bodyB64}`;
     const expectedSignature = hmacSha256(signatureInput, secret);
-    const sigBuffer = Buffer.from(signature, "base64url");
-    const expectedBuffer = Buffer.from(expectedSignature, "base64url");
+    const sigBuffer = Buffer.from(signature, "utf-8");
+    const expectedBuffer = Buffer.from(expectedSignature, "utf-8");
     if (sigBuffer.length !== expectedBuffer.length ||
         !timingSafeEqual(sigBuffer, expectedBuffer)) {
         return { valid: false, error: "Invalid signature" };