@zudojs/auth 0.1.1 → 1.1.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,11 +32,30 @@ const SCRYPT_P = 1;
 /**
  * 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 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, {
         N: SCRYPT_N,
@@ -37,11 +70,23 @@ export async function hashPassword(password, saltLength = SALT_LENGTH) {
  * 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) {
+    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;
@@ -84,6 +129,9 @@ 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 parseHash(hashedPassword) {

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,26 @@
  * @module authProvider/authProvider
  */
 import type { AuthUser, UserCredentials, UserId } from "../authTypes/authUser.type.js";
-import type { TokenPair, TokenConfig, TokenRevocationStore } 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. */
+/**
+ * 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. */
+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,19 +34,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: the used token's `jti` is revoked so it cannot be replayed.
+     * 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.
@@ -42,10 +89,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>;
 }

package/dist/authProvider/authProvider.core.js

@@ -5,57 +5,189 @@
  */
 import { hashPassword, verifyPassword, } from "../authPassword/authPassword.core.js";
 import { createTokenPair, verifyAccessToken, verifyRefreshToken, } from "../authToken/authToken.core.js";
-import { InvalidCredentialsError, TokenExpiredError, TokenInvalidError, TokenRevokedError, AccountDeactivatedError, } from "../authErrors/authError.base.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.
+ *
+ * Verifying against it costs the same scrypt work as a real verification, so
+ * 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;
+/**
+ * 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, verifyPassword: verifyPwd, sessionTtlSeconds, permissions, revocationStore, } = 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;
+    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 key = throttleKey(identifier);
+        const now = Date.now();
+        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(key);
+        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 key = throttleKey(identifier);
+        const updated = await loginThrottle.store.recordFailure(key);
+        if (updated.failures >= maxFailedAttempts) {
+            await loginThrottle.store.lock(key, Date.now() + lockoutSeconds * 1000);
+        }
+    }
+    /**
+     * 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;
+        const session = await sessionStore.get(sid);
+        if (!session) {
+            throw new SessionExpiredError("Session is no longer active");
+        }
+        await sessionStore.touch(sid);
+        return sid;
+    }
+    /**
+     * Atomically claim the used refresh token id.
+     *
+     * @returns true when this call was the one that revoked it.
+     */
+    async function claimRefreshToken(store, jti, exp) {
+        if (store.revokeIfNotRevoked) {
+            return store.revokeIfNotRevoked(jti, exp);
+        }
+        // Racy fallback for stores predating `revokeIfNotRevoked`.
+        if (await store.isRevoked(jti))
+            return false;
+        await store.revoke(jti, exp);
+        return true;
+    }
     return {
         /**
          * Authenticate a user with credentials and return tokens + session.
+         *
+         * Unknown user, wrong password and (before the password is proven)
+         * deactivated account are indistinguishable to the caller: the same
+         * `InvalidCredentialsError` is thrown, and the unknown-user path performs
+         * the same scrypt work as the known-user path.
          */
         async login(credentials, context) {
-            const user = await findUser(credentials.identifier);
-            if (!user) {
+            const identifier = credentials.identifier;
+            await enforceThrottle(identifier);
+            const user = await findUser(identifier);
+            let authenticated = false;
+            if (user) {
+                authenticated = await verifyPwd(user.id, credentials.password);
+            }
+            else {
+                // Burn comparable work so response time does not reveal that the
+                // account does not exist.
+                await verifyPassword(credentials.password, DUMMY_PASSWORD_HASH);
+            }
+            if (!user || !authenticated) {
+                await recordFailure(identifier);
                 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(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) {
                 throw new AccountDeactivatedError();
             }
-            const valid = await verifyPwd(user.id, credentials.password);
-            if (!valid) {
-                throw new InvalidCredentialsError();
-            }
-            const tokens = createTokenPair(user.id, tokenConfig, {
-                roles: user.roles,
-            });
             const session = await sessionStore.create({
                 userId: user.id,
                 userAgent: context?.userAgent,
                 ip: context?.ip,
                 ttlSeconds: sessionTtlSeconds,
+                absoluteTtlSeconds: absoluteSessionTtlSeconds,
+            });
+            const tokens = createTokenPair(user.id, tokenConfig, {
+                roles: user.roles,
+                sessionId: session.id,
             });
             return { user, tokens, sessionId: session.id };
         },
         /**
          * Verify an access token and return the payload.
+         *
+         * @throws {TokenExpiredError} expired token
+         * @throws {TokenInvalidError} malformed, mis-signed or wrong-type token
+         * @throws {SessionExpiredError} the session the token was issued against
+         *   has been destroyed (logout) or expired
          */
-        verifyToken(token) {
+        async verifyToken(token) {
             const result = verifyAccessToken(token, tokenConfig);
-            if (!result.valid) {
+            if (!result.valid || !result.payload) {
                 if (result.error === "Token expired") {
                     throw new TokenExpiredError(result.error);
                 }
                 throw new TokenInvalidError(result.error ?? "Token verification failed");
             }
-            return result.payload;
+            const payload = result.payload;
+            await requireLiveSession(payload);
+            return payload;
         },
         /**
          * Refresh an access token using a refresh token.
          *
-         * When a revocation store is configured, the used refresh token is
-         * revoked (rotation) so it cannot be replayed.
+         * Rotation is atomic when the revocation store implements
+         * `revokeIfNotRevoked`: exactly one of two concurrent refreshes of the
+         * same token wins, and the loser is treated as a replay — the user's
+         * sessions are destroyed and `TokenRevokedError` is thrown.
+         *
+         * The user is re-loaded on every refresh, so deactivation and role
+         * changes take effect immediately rather than at the end of the refresh
+         * token's 7-day life.
          */
         async refresh(refreshToken) {
             const result = verifyRefreshToken(refreshToken, tokenConfig);
@@ -65,27 +197,61 @@ export function createAuthService(config) {
                 }
                 throw new TokenInvalidError("Refresh token is invalid");
             }
-            const { sub, jti, exp, roles } = result.payload;
-            if (revocationStore && (await revocationStore.isRevoked(jti))) {
-                throw new TokenRevokedError("Refresh token has been revoked");
-            }
-            const tokens = createTokenPair(sub, tokenConfig, { roles });
+            const payload = result.payload;
+            const { sub, jti, exp } = payload;
+            const sid = await requireLiveSession(payload);
             if (revocationStore) {
-                await revocationStore.revoke(jti, exp);
+                const claimed = await claimRefreshToken(revocationStore, jti, exp);
+                if (!claimed) {
+                    // Reuse of an already-rotated refresh token: assume the chain is
+                    // compromised and terminate every session for the user
+                    // (RFC 6819 §5.2.2.3).
+                    await sessionStore.destroyAllForUser(sub);
+                    throw new TokenRevokedError("Refresh token has already been used");
+                }
             }
-            return tokens;
+            const user = await findUserById(sub);
+            if (!user || !user.active) {
+                throw new AccountDeactivatedError("User account is no longer active");
+            }
+            return createTokenPair(user.id, tokenConfig, {
+                roles: user.roles,
+                ...(sid ? { sessionId: sid } : {}),
+            });
         },
         /**
-         * Logout — destroy the session.
+         * Logout — destroy the session, which invalidates every access and
+         * refresh token carrying that `sid`.
+         *
+         * @param refreshToken - The refresh token being surrendered. When given
+         *   alongside a revocation store, its `jti` is revoked too, so the token
+         *   stays dead even if it is later presented against a new session.
          */
-        async logout(sessionId) {
+        async logout(sessionId, refreshToken) {
             await sessionStore.destroy(sessionId);
+            if (refreshToken && revocationStore) {
+                const result = verifyRefreshToken(refreshToken, tokenConfig);
+                if (result.valid && result.payload) {
+                    await revocationStore.revoke(result.payload.jti, result.payload.exp);
+                }
+            }
+        },
+        /**
+         * Sign out everywhere — destroy every session for a user. Tokens bound
+         * to those sessions stop verifying immediately.
+         */
+        async logoutAll(userId) {
+            await sessionStore.destroyAllForUser(userId);
         },
         /**
          * Check if a user has a specific permission.
-         * Delegates to @zudojs/permissions engine when configured.
+         * Delegates to the @zudojs/permissions engine when configured.
+         *
+         * @throws {AuthConfigurationError} when no engine is configured and
+         *   `allowInsecureFallbackGuard` was not set.
          */
-        async checkAccess(userId, userRoles, permission, resourceOwnerId) {
+        async checkAccess(context) {
+            const { userId, roles: userRoles, permission, resourceOwnerId } = context;
             if (permissions) {
                 const actor = { id: userId, roles: [...userRoles] };
                 const resource = resourceOwnerId
@@ -99,8 +265,12 @@ export function createAuthService(config) {
                     userRoles: [...userRoles],
                 };
             }
-            // Fallback: simple wildcard matching (no engine configured)
-            return simpleGuard(userRoles, permission, userId, resourceOwnerId);
+            if (!allowInsecureFallbackGuard) {
+                throw new AuthConfigurationError("checkAccess() requires a `permissions` engine. Set " +
+                    "`allowInsecureFallbackGuard: true` to opt into the built-in " +
+                    "fallback, which grants resource owners every permission.");
+            }
+            return simpleGuard(userRoles, permission, userId, resourceOwnerId, fallbackAdminRole ?? "admin");
         },
         /**
          * Hash a password (for user registration).
@@ -117,17 +287,31 @@ export function createAuthService(config) {
     };
 }
 /**
- * Simple fallback guard when no permissions engine is configured.
- * Grants access to resource owners and to the "admin" role only —
- * configure @zudojs/permissions for real role/permission matching.
+ * Simple fallback guard used only when no permissions engine is configured
+ * *and* the consumer opted in with `allowInsecureFallbackGuard`.
+ *
+ * It grants a resource owner every permission and grants the configured
+ * admin role everything — it does no permission matching at all. Every
+ * allowed result carries a `reason` naming the fallback so the decision is
+ * distinguishable from an engine-backed one in an audit log.
  */
-function simpleGuard(userRoles, permission, userId, resourceOwnerId) {
-    // Ownership check
+function simpleGuard(userRoles, permission, userId, resourceOwnerId, adminRole) {
+    // Ownership check — note this ignores `permission` entirely.
     if (resourceOwnerId && resourceOwnerId === userId) {
-        return { allowed: true, userRoles: [...userRoles] };
+        return {
+            allowed: true,
+            reason: "granted by fallback guard: resource ownership",
+            requiredPermission: permission,
+            userRoles: [...userRoles],
+        };
     }
-    if (userRoles.includes("admin")) {
-        return { allowed: true, userRoles: [...userRoles] };
+    if (userRoles.includes(adminRole)) {
+        return {
+            allowed: true,
+            reason: `granted by fallback guard: "${adminRole}" role`,
+            requiredPermission: permission,
+            userRoles: [...userRoles],
+        };
     }
     return {
         allowed: false,

package/dist/authProvider/index.d.ts

@@ -3,5 +3,6 @@
  *
  * @module authProvider
  */
-export { createAuthService, type AuthServiceConfig, type LoginResult, type UserLookup, type PasswordVerifier, } from "./authProvider.core.js";
+export { createAuthService, type AuthService, type AuthServiceConfig, type LoginResult, type UserLookup, type UserByIdLookup, type PasswordVerifier, } from "./authProvider.core.js";
+export { createMemoryLoginAttemptStore } from "./authAttempt.memory.js";
 //# sourceMappingURL=index.d.ts.map