@zudojs/auth 0.1.0 → 1.0.0

package/dist/authProvider/authProvider.core.js

@@ -4,71 +4,230 @@
  * @module authProvider/authProvider
  */
 import { hashPassword, verifyPassword, } from "../authPassword/authPassword.core.js";
-import { createTokenPair, verifyAccessToken, refreshAccessToken, } from "../authToken/authToken.core.js";
-import { InvalidCredentialsError, TokenExpiredError, AccountDeactivatedError, } from "../authErrors/authError.base.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";
+/**
+ * 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;
 /**
  * Create an auth service.
  */
 export function createAuthService(config) {
-    const { token: tokenConfig, sessionStore, findUser, verifyPassword: verifyPwd, sessionTtlSeconds, permissions, } = 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);
+        }
+    }
+    /**
+     * 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(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) {
-                throw new TokenExpiredError(result.error ?? "Token verification failed");
+            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.
+         *
+         * 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 = refreshAccessToken(refreshToken, tokenConfig);
-            if (!result) {
-                throw new TokenExpiredError("Refresh token is invalid or expired");
+            const result = verifyRefreshToken(refreshToken, tokenConfig);
+            if (!result.valid || !result.payload) {
+                if (result.error === "Token expired") {
+                    throw new TokenExpiredError("Refresh token has expired");
+                }
+                throw new TokenInvalidError("Refresh token is invalid");
+            }
+            const payload = result.payload;
+            const { sub, jti, exp } = payload;
+            const sid = await requireLiveSession(payload);
+            if (revocationStore) {
+                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 result;
+            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
@@ -82,8 +241,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).
@@ -100,20 +263,31 @@ export function createAuthService(config) {
     };
 }
 /**
- * Simple fallback guard when no permissions engine is configured.
- * Performs basic wildcard matching without full ABAC support.
+ * 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],
+        };
     }
-    const [requiredResource, requiredAction] = permission.split(":");
-    for (const role of userRoles) {
-        // Role-based — simplified check
-        if (role === "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

package/dist/authProvider/index.js

@@ -4,4 +4,5 @@
  * @module authProvider
  */
 export { createAuthService, } from "./authProvider.core.js";
+export { createMemoryLoginAttemptStore } from "./authAttempt.memory.js";
 //# sourceMappingURL=index.js.map

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

@@ -9,8 +9,18 @@ import type { SessionStore } from "../authTypes/authSession.type.js";
 /**
  * Create an in-memory session store.
  *
- * Good for development and testing. For production,
- * implement SessionStore with Redis or a database.
+ * Good for development and testing. For production, implement SessionStore
+ * with Redis or a database.
+ *
+ * Expired sessions are reclaimed on any access — `create`, `get` and `touch`
+ * all run a rate-limited sweep — so a store that stops receiving logins
+ * still releases its memory. The sweep is rate-limited rather than run per
+ * call so that a large store does not turn an O(1) lookup into an O(n) walk.
+ *
+ * @param options.purgeIntervalMs - Minimum gap between full sweeps
+ *   (default: 60000). Set to 0 to sweep on every access.
  */
-export declare function createMemorySessionStore(): SessionStore;
+export declare function createMemorySessionStore(storeOptions?: {
+    readonly purgeIntervalMs?: number;
+}): SessionStore;
 //# sourceMappingURL=authSession.core.d.ts.map

package/dist/authSession/authSession.core.js

@@ -7,19 +7,49 @@
  */
 import { randomBytes } from "node:crypto";
 const DEFAULT_TTL_SECONDS = 86400; // 24 hours
+/** Minimum interval between full sweeps of the session map. */
+const DEFAULT_PURGE_INTERVAL_MS = 60_000;
 /**
  * Create an in-memory session store.
  *
- * Good for development and testing. For production,
- * implement SessionStore with Redis or a database.
+ * Good for development and testing. For production, implement SessionStore
+ * with Redis or a database.
+ *
+ * Expired sessions are reclaimed on any access — `create`, `get` and `touch`
+ * all run a rate-limited sweep — so a store that stops receiving logins
+ * still releases its memory. The sweep is rate-limited rather than run per
+ * call so that a large store does not turn an O(1) lookup into an O(n) walk.
+ *
+ * @param options.purgeIntervalMs - Minimum gap between full sweeps
+ *   (default: 60000). Set to 0 to sweep on every access.
  */
-export function createMemorySessionStore() {
+export function createMemorySessionStore(storeOptions) {
     const sessions = new Map();
+    const ttls = new Map();
+    const purgeIntervalMs = storeOptions?.purgeIntervalMs ?? DEFAULT_PURGE_INTERVAL_MS;
+    let lastPurge = 0;
+    function maybePurgeExpired() {
+        const nowMs = Date.now();
+        if (nowMs - lastPurge < purgeIntervalMs)
+            return;
+        lastPurge = nowMs;
+        for (const [id, session] of sessions) {
+            if (nowMs > session.expiresAt.getTime()) {
+                sessions.delete(id);
+                ttls.delete(id);
+            }
+        }
+    }
     return {
         async create(options) {
+            maybePurgeExpired();
             const id = generateSessionId();
             const now = new Date();
             const ttlMs = (options.ttlSeconds ?? DEFAULT_TTL_SECONDS) * 1000;
+            const absoluteExpiresAt = options.absoluteTtlSeconds !== undefined
+                ? new Date(now.getTime() + options.absoluteTtlSeconds * 1000)
+                : undefined;
+            const expiresAt = clampToAbsolute(new Date(now.getTime() + ttlMs), absoluteExpiresAt);
             const session = {
                 id,
                 userId: options.userId,
@@ -27,46 +57,65 @@ export function createMemorySessionStore() {
                 ip: options.ip,
                 createdAt: now,
                 lastActivityAt: now,
-                expiresAt: new Date(now.getTime() + ttlMs),
-                active: true,
+                expiresAt,
+                absoluteExpiresAt,
                 metadata: options.metadata,
             };
             sessions.set(id, session);
+            ttls.set(id, ttlMs);
             return session;
         },
         async get(sessionId) {
+            maybePurgeExpired();
             const session = sessions.get(sessionId);
             if (!session)
                 return null;
-            if (!session.active)
-                return null;
-            if (new Date() > session.expiresAt) {
+            if (Date.now() > session.expiresAt.getTime()) {
                 sessions.delete(sessionId);
+                ttls.delete(sessionId);
                 return null;
             }
             return session;
         },
         async touch(sessionId) {
+            maybePurgeExpired();
             const session = sessions.get(sessionId);
-            if (session && session.active) {
-                sessions.set(sessionId, {
-                    ...session,
-                    lastActivityAt: new Date(),
-                });
+            if (!session)
+                return;
+            const now = new Date();
+            if (now.getTime() > session.expiresAt.getTime()) {
+                sessions.delete(sessionId);
+                ttls.delete(sessionId);
+                return;
             }
+            const ttlMs = ttls.get(sessionId) ?? DEFAULT_TTL_SECONDS * 1000;
+            sessions.set(sessionId, {
+                ...session,
+                lastActivityAt: now,
+                // Sliding expiration: activity extends the session by its TTL, but
+                // never past the absolute deadline.
+                expiresAt: clampToAbsolute(new Date(now.getTime() + ttlMs), session.absoluteExpiresAt),
+            });
         },
         async destroy(sessionId) {
             sessions.delete(sessionId);
+            ttls.delete(sessionId);
         },
         async destroyAllForUser(userId) {
             for (const [id, session] of sessions) {
                 if (session.userId === userId) {
                     sessions.delete(id);
+                    ttls.delete(id);
                 }
             }
         },
     };
 }
+function clampToAbsolute(expiresAt, absolute) {
+    if (!absolute)
+        return expiresAt;
+    return expiresAt.getTime() > absolute.getTime() ? absolute : expiresAt;
+}
 function generateSessionId() {
     return randomBytes(32).toString("hex");
 }

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

@@ -6,24 +6,50 @@
  * Pure Node.js implementation (no jsonwebtoken dependency).
  * Uses HMAC SHA-256 for signing.
  */
-import type { UserId } from "@zudojs/constants";
+import type { SessionId, UserId } from "@zudojs/constants";
 import type { JwtToken, TokenPair, TokenConfig, TokenVerificationResult } from "../authTypes/authToken.type.js";
 /**
  * Create a new token pair (access + refresh).
+ *
+ * @param options.roles - Roles to embed in both tokens.
+ * @param options.sessionId - Session to bind the pair to (`sid` claim).
+ *   `createAuthService()` sets this so that `logout()` invalidates the pair.
+ * @throws {AuthConfigurationError} when the signing secrets are missing,
+ *   shorter than 32 bytes, or identical to each other.
  */
 export declare function createTokenPair(userId: UserId, config: TokenConfig, options?: {
     readonly roles?: readonly string[];
+    readonly sessionId?: SessionId;
 }): TokenPair;
 /**
  * Verify and decode an access token.
+ *
+ * @throws {AuthConfigurationError} when the signing secrets are invalid.
+ *   Malformed or untrusted *tokens* never throw — they come back as
+ *   `{ valid: false, error }`.
  */
 export declare function verifyAccessToken(token: JwtToken, config: TokenConfig): TokenVerificationResult;
 /**
  * Verify and decode a refresh token.
+ *
+ * @throws {AuthConfigurationError} when the signing secrets are invalid.
  */
 export declare function verifyRefreshToken(token: JwtToken, config: TokenConfig): TokenVerificationResult;
 /**
  * Refresh an access token using a valid refresh token.
+ *
+ * **This is the non-rotating, non-revoking variant.** It checks the refresh
+ * token's signature, expiry and type and nothing else: it consults no
+ * {@link TokenRevocationStore}, does not revoke the token it consumes, does
+ * not re-load the user, and does not check the session. A stolen refresh
+ * token therefore stays replayable for its full lifetime (7 days by
+ * default) — and so does the token it was already exchanged for.
+ *
+ * Use `createAuthService().refresh()` instead for anything user-facing: it
+ * rotates the refresh token atomically, revokes the used `jti`, re-loads the
+ * user so deactivation and role changes take effect, and validates the
+ * session. This function exists for callers who manage all of that
+ * themselves.
  */
 export declare function refreshAccessToken(refreshToken: JwtToken, config: TokenConfig, options?: {
     readonly roles?: readonly string[];

package/dist/authToken/authToken.core.js

@@ -6,14 +6,21 @@
  * Pure Node.js implementation (no jsonwebtoken dependency).
  * Uses HMAC SHA-256 for signing.
  */
-import { TimeMs } from "@zudojs/constants";
-import { signToken, verifyToken, generateTokenId, } from "./authToken.signing.js";
-const DEFAULT_ACCESS_TTL = TimeMs.SECOND * 15; // 15 minutes
-const DEFAULT_REFRESH_TTL = TimeMs.SECOND * 60 * 60 * 24 * 7; // 7 days
+import { signToken, verifyToken, generateTokenId, assertTokenSecrets, } from "./authToken.signing.js";
+// TTLs are in seconds — they are added to Unix-second `iat`/`exp` claims.
+const DEFAULT_ACCESS_TTL = 900; // 15 minutes
+const DEFAULT_REFRESH_TTL = 604_800; // 7 days
 /**
  * Create a new token pair (access + refresh).
+ *
+ * @param options.roles - Roles to embed in both tokens.
+ * @param options.sessionId - Session to bind the pair to (`sid` claim).
+ *   `createAuthService()` sets this so that `logout()` invalidates the pair.
+ * @throws {AuthConfigurationError} when the signing secrets are missing,
+ *   shorter than 32 bytes, or identical to each other.
  */
 export function createTokenPair(userId, config, options) {
+    assertTokenSecrets(config);
     const accessTtl = config.accessTtl ?? DEFAULT_ACCESS_TTL;
     const refreshTtl = config.refreshTtl ?? DEFAULT_REFRESH_TTL;
     const now = Math.floor(Date.now() / 1000);
@@ -24,6 +31,7 @@ export function createTokenPair(userId, config, options) {
         typ: "access",
         jti: generateTokenId(),
         roles: options?.roles,
+        ...(options?.sessionId ? { sid: options.sessionId } : {}),
         ...(config.issuer ? { iss: config.issuer } : {}),
         ...(config.audience ? { aud: config.audience } : {}),
     }, config.accessSecret);
@@ -33,6 +41,8 @@ export function createTokenPair(userId, config, options) {
         exp: now + refreshTtl,
         typ: "refresh",
         jti: generateTokenId(),
+        roles: options?.roles,
+        ...(options?.sessionId ? { sid: options.sessionId } : {}),
         ...(config.issuer ? { iss: config.issuer } : {}),
         ...(config.audience ? { aud: config.audience } : {}),
     }, config.refreshSecret);
@@ -45,18 +55,39 @@ export function createTokenPair(userId, config, options) {
 }
 /**
  * Verify and decode an access token.
+ *
+ * @throws {AuthConfigurationError} when the signing secrets are invalid.
+ *   Malformed or untrusted *tokens* never throw — they come back as
+ *   `{ valid: false, error }`.
  */
 export function verifyAccessToken(token, config) {
+    assertTokenSecrets(config);
     return verifyToken(token, config.accessSecret, "access", config);
 }
 /**
  * Verify and decode a refresh token.
+ *
+ * @throws {AuthConfigurationError} when the signing secrets are invalid.
  */
 export function verifyRefreshToken(token, config) {
+    assertTokenSecrets(config);
     return verifyToken(token, config.refreshSecret, "refresh", config);
 }
 /**
  * Refresh an access token using a valid refresh token.
+ *
+ * **This is the non-rotating, non-revoking variant.** It checks the refresh
+ * token's signature, expiry and type and nothing else: it consults no
+ * {@link TokenRevocationStore}, does not revoke the token it consumes, does
+ * not re-load the user, and does not check the session. A stolen refresh
+ * token therefore stays replayable for its full lifetime (7 days by
+ * default) — and so does the token it was already exchanged for.
+ *
+ * Use `createAuthService().refresh()` instead for anything user-facing: it
+ * rotates the refresh token atomically, revokes the used `jti`, re-loads the
+ * user so deactivation and role changes take effect, and validates the
+ * session. This function exists for callers who manage all of that
+ * themselves.
  */
 export function refreshAccessToken(refreshToken, config, options) {
     const result = verifyRefreshToken(refreshToken, config);

package/dist/authToken/authToken.encoding.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Internal base64url + JWT segment helpers.
+ *
+ * @module authToken/authToken.encoding
+ *
+ * Not exported from the package barrel. Every JWT segment in this package —
+ * verified or not — is decoded through here so that the bounds and the
+ * decoding rules stay in exactly one place.
+ */
+/**
+ * Maximum accepted length, in characters, of a complete JWT.
+ *
+ * An HS256 JWT with a generous set of claims is well under 2 KB; 8 KB is the
+ * conventional HTTP header limit. Anything larger is rejected before it is
+ * decoded so that an unauthenticated request cannot make the process
+ * allocate and parse an arbitrarily large buffer.
+ */
+export declare const MAX_TOKEN_LENGTH = 8192;
+/**
+ * Maximum accepted length, in characters, of the JOSE header segment.
+ * A real header (`{"alg":"HS256","typ":"JWT"}`) is 36 characters encoded.
+ */
+export declare const MAX_HEADER_SEGMENT_LENGTH = 1024;
+/** Encode a UTF-8 string as base64url. */
+export declare function base64UrlEncode(data: string): string;
+/** Decode a base64url segment to a UTF-8 string. */
+export declare function base64UrlDecode(data: string): string;
+/**
+ * Split a JWT into its three segments, rejecting anything that is not a
+ * string, is empty, or exceeds {@link MAX_TOKEN_LENGTH}.
+ *
+ * @returns The three segments, or `null` when the input is not a
+ *   plausibly-shaped, in-bounds JWT.
+ */
+export declare function splitToken(token: unknown): readonly [string, string, string] | null;
+/**
+ * Decode a JWT body segment into a plain object.
+ *
+ * @returns The parsed object, or `null` when the segment is not valid JSON
+ *   or does not decode to a non-null, non-array object.
+ */
+export declare function decodeJsonSegment(segment: string): Record<string, unknown> | null;
+//# sourceMappingURL=authToken.encoding.d.ts.map