@zudojs/auth 0.1.1 → 1.0.0

package/dist/authSession/authSession.core.js

@@ -7,19 +7,34 @@
  */
 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();
-    function purgeExpired() {
-        const now = new Date();
+    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 (now > session.expiresAt) {
+            if (nowMs > session.expiresAt.getTime()) {
                 sessions.delete(id);
                 ttls.delete(id);
             }
@@ -27,10 +42,14 @@ export function createMemorySessionStore() {
     }
     return {
         async create(options) {
-            purgeExpired();
+            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,
@@ -38,8 +57,8 @@ 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);
@@ -47,12 +66,11 @@ export function createMemorySessionStore() {
             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;
@@ -60,17 +78,24 @@ export function createMemorySessionStore() {
             return session;
         },
         async touch(sessionId) {
+            maybePurgeExpired();
             const session = sessions.get(sessionId);
-            if (session && session.active && new Date() <= session.expiresAt) {
-                const now = new Date();
-                const ttlMs = ttls.get(sessionId) ?? DEFAULT_TTL_SECONDS * 1000;
-                sessions.set(sessionId, {
-                    ...session,
-                    lastActivityAt: now,
-                    // Sliding expiration: activity extends the session by its TTL
-                    expiresAt: new Date(now.getTime() + ttlMs),
-                });
+            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);
@@ -86,6 +111,11 @@ export function createMemorySessionStore() {
         },
     };
 }
+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 { signToken, verifyToken, generateTokenId, } from "./authToken.signing.js";
+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);
@@ -34,6 +42,7 @@ export function createTokenPair(userId, config, options) {
         typ: "refresh",
         jti: generateTokenId(),
         roles: options?.roles,
+        ...(options?.sessionId ? { sid: options.sessionId } : {}),
         ...(config.issuer ? { iss: config.issuer } : {}),
         ...(config.audience ? { aud: config.audience } : {}),
     }, config.refreshSecret);
@@ -46,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

package/dist/authToken/authToken.encoding.js

@@ -0,0 +1,74 @@
+/**
+ * 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 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 const MAX_HEADER_SEGMENT_LENGTH = 1024;
+/** Encode a UTF-8 string as base64url. */
+export function base64UrlEncode(data) {
+    return Buffer.from(data, "utf-8").toString("base64url");
+}
+/** Decode a base64url segment to a UTF-8 string. */
+export function base64UrlDecode(data) {
+    return Buffer.from(data, "base64url").toString("utf-8");
+}
+/**
+ * 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 function splitToken(token) {
+    if (typeof token !== "string")
+        return null;
+    if (token.length === 0 || token.length > MAX_TOKEN_LENGTH)
+        return null;
+    const parts = token.split(".");
+    if (parts.length !== 3)
+        return null;
+    const [header, body, signature] = parts;
+    if (header.length > MAX_HEADER_SEGMENT_LENGTH)
+        return null;
+    if (header.length === 0 || body.length === 0 || signature.length === 0) {
+        return null;
+    }
+    return [header, body, signature];
+}
+/**
+ * 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 function decodeJsonSegment(segment) {
+    let parsed;
+    try {
+        parsed = JSON.parse(base64UrlDecode(segment));
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        return null;
+    }
+    return parsed;
+}
+//# sourceMappingURL=authToken.encoding.js.map

package/dist/authToken/authToken.revocation.d.ts

@@ -11,7 +11,15 @@ import type { TokenRevocationStore } from "../authTypes/authToken.type.js";
 /**
  * Create an in-memory token revocation store.
  *
- * Entries are purged lazily once their token would have expired anyway.
+ * Expired entries are dropped lazily: the key being read is checked on every
+ * access (O(1)), and a full sweep runs at most once per `purgeIntervalMs`.
+ * The sweep is deliberately *not* driven by a timer — an interval would keep
+ * the process alive and leak without a `dispose()`.
+ *
+ * @param options.purgeIntervalMs - Minimum gap between full sweeps
+ *   (default: 60000). Set to 0 to sweep on every access.
  */
-export declare function createMemoryTokenRevocationStore(): TokenRevocationStore;
+export declare function createMemoryTokenRevocationStore(options?: {
+    readonly purgeIntervalMs?: number;
+}): TokenRevocationStore;
 //# sourceMappingURL=authToken.revocation.d.ts.map

package/dist/authToken/authToken.revocation.js

@@ -7,29 +7,64 @@
  * implement TokenRevocationStore with Redis or a database so revocations
  * are shared across instances.
  */
+/** Minimum interval between full sweeps of the revocation map. */
+const DEFAULT_PURGE_INTERVAL_MS = 60_000;
 /**
  * Create an in-memory token revocation store.
  *
- * Entries are purged lazily once their token would have expired anyway.
+ * Expired entries are dropped lazily: the key being read is checked on every
+ * access (O(1)), and a full sweep runs at most once per `purgeIntervalMs`.
+ * The sweep is deliberately *not* driven by a timer — an interval would keep
+ * the process alive and leak without a `dispose()`.
+ *
+ * @param options.purgeIntervalMs - Minimum gap between full sweeps
+ *   (default: 60000). Set to 0 to sweep on every access.
  */
-export function createMemoryTokenRevocationStore() {
+export function createMemoryTokenRevocationStore(options) {
     const revoked = new Map();
-    function purgeExpired() {
-        const now = Math.floor(Date.now() / 1000);
+    const purgeIntervalMs = options?.purgeIntervalMs ?? DEFAULT_PURGE_INTERVAL_MS;
+    let lastPurge = 0;
+    /** Full sweep, rate-limited so a large map cannot be walked per request. */
+    function maybePurgeExpired() {
+        const nowMs = Date.now();
+        if (nowMs - lastPurge < purgeIntervalMs)
+            return;
+        lastPurge = nowMs;
+        const now = Math.floor(nowMs / 1000);
         for (const [id, expiresAt] of revoked) {
             if (expiresAt < now) {
                 revoked.delete(id);
             }
         }
     }
+    /** O(1) expiry check for a single key. */
+    function isLive(tokenId) {
+        const expiresAt = revoked.get(tokenId);
+        if (expiresAt === undefined)
+            return false;
+        if (expiresAt < Math.floor(Date.now() / 1000)) {
+            revoked.delete(tokenId);
+            return false;
+        }
+        return true;
+    }
     return {
         async revoke(tokenId, expiresAt) {
-            purgeExpired();
+            maybePurgeExpired();
             revoked.set(tokenId, expiresAt);
         },
         async isRevoked(tokenId) {
-            purgeExpired();
-            return revoked.has(tokenId);
+            maybePurgeExpired();
+            return isLive(tokenId);
+        },
+        async revokeIfNotRevoked(tokenId, expiresAt) {
+            // The check and the write happen in one synchronous block with no
+            // intervening await, so two concurrent callers cannot both win.
+            maybePurgeExpired();
+            if (isLive(tokenId))
+                return false;
+            revoked.set(tokenId, expiresAt);
+            return true;
         },
     };
 }

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

@@ -6,13 +6,36 @@
  * Not exported from the package barrel — used internally by authToken.core.ts.
  */
 import type { JwtToken, TokenId, TokenPayload, TokenConfig, TokenVerificationResult } from "../authTypes/authToken.type.js";
+/**
+ * Minimum accepted signing-secret length in bytes.
+ *
+ * HS256 keys should be at least as long as the digest (32 bytes); shorter
+ * keys are brute-forceable offline from a single captured token.
+ */
+export declare const MIN_SECRET_BYTES = 32;
+/**
+ * Validate a {@link TokenConfig}'s signing secrets.
+ *
+ * Called on every mint and every verification. An empty or short secret
+ * yields tokens anyone can forge, and Node accepts a zero-length HMAC key
+ * without complaint, so this has to be checked explicitly rather than
+ * assumed.
+ *
+ * @throws {AuthConfigurationError} when either secret is missing, shorter
+ *   than {@link MIN_SECRET_BYTES}, or when both secrets are identical.
+ */
+export declare function assertTokenSecrets(config: TokenConfig): void;
 /**
  * Sign a JWT payload with HMAC SHA-256.
  */
 export declare function signToken(payload: TokenPayload, secret: string): JwtToken;
 /**
- * Verify a JWT token's signature, algorithm, expiration, type,
+ * Verify a JWT token's signature, algorithm, expiration, not-before, type,
  * and (when configured) issuer and audience.
+ *
+ * Never throws for untrusted input: every failure is reported as
+ * `{ valid: false, error }`. Oversized tokens are rejected before anything
+ * is decoded.
  */
 export declare function verifyToken(token: JwtToken, secret: string, expectedType: "access" | "refresh", config: TokenConfig): TokenVerificationResult;
 /**