@zudojs/auth 0.1.0 → 1.0.0

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

@@ -0,0 +1,25 @@
+/**
+ * In-memory token revocation store.
+ *
+ * @module authToken/authToken.revocation
+ *
+ * Good for development and single-process deployments. For production,
+ * implement TokenRevocationStore with Redis or a database so revocations
+ * are shared across instances.
+ */
+import type { TokenRevocationStore } from "../authTypes/authToken.type.js";
+/**
+ * Create an in-memory token revocation store.
+ *
+ * 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(options?: {
+    readonly purgeIntervalMs?: number;
+}): TokenRevocationStore;
+//# sourceMappingURL=authToken.revocation.d.ts.map

package/dist/authToken/authToken.revocation.js

@@ -0,0 +1,71 @@
+/**
+ * In-memory token revocation store.
+ *
+ * @module authToken/authToken.revocation
+ *
+ * Good for development and single-process deployments. For production,
+ * 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.
+ *
+ * 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(options) {
+    const revoked = new Map();
+    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) {
+            maybePurgeExpired();
+            revoked.set(tokenId, expiresAt);
+        },
+        async isRevoked(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;
+        },
+    };
+}
+//# sourceMappingURL=authToken.revocation.js.map

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

@@ -6,12 +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, expiration, and 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;
 /**

package/dist/authToken/authToken.signing.js

@@ -5,10 +5,53 @@
  *
  * Not exported from the package barrel — used internally by authToken.core.ts.
  */
-import { createHmac, timingSafeEqual } from "node:crypto";
-import { randomBytes } from "node:crypto";
+import { createHmac, timingSafeEqual, randomBytes } from "node:crypto";
+import { AuthConfigurationError } from "../authErrors/authError.base.js";
+import { base64UrlEncode, decodeJsonSegment, splitToken, } from "./authToken.encoding.js";
 /** HMAC signing algorithm. */
 const ALGORITHM = "HS256";
+/**
+ * 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 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 function assertTokenSecrets(config) {
+    assertSecret(config?.accessSecret, "accessSecret");
+    assertSecret(config?.refreshSecret, "refreshSecret");
+    if (config.accessSecret === config.refreshSecret) {
+        throw new AuthConfigurationError("TokenConfig.accessSecret and TokenConfig.refreshSecret must differ; " +
+            "sharing one secret collapses the separation between access and " +
+            "refresh tokens.");
+    }
+    if (config.clockToleranceSeconds !== undefined &&
+        (!Number.isFinite(config.clockToleranceSeconds) ||
+            config.clockToleranceSeconds < 0 ||
+            config.clockToleranceSeconds > 300)) {
+        throw new AuthConfigurationError("TokenConfig.clockToleranceSeconds must be between 0 and 300 seconds.");
+    }
+}
+function assertSecret(secret, field) {
+    if (typeof secret !== "string" || secret.length === 0) {
+        throw new AuthConfigurationError(`TokenConfig.${field} is required and must be a non-empty string.`);
+    }
+    if (Buffer.byteLength(secret, "utf-8") < MIN_SECRET_BYTES) {
+        throw new AuthConfigurationError(`TokenConfig.${field} must be at least ${MIN_SECRET_BYTES} bytes; ` +
+            "a shorter HMAC key can be recovered offline from a single token.");
+    }
+}
 /**
  * Sign a JWT payload with HMAC SHA-256.
  */
@@ -20,41 +63,95 @@ export function signToken(payload, secret) {
     return `${signatureInput}.${signature}`;
 }
 /**
- * Verify a JWT token's signature, expiration, and 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 function verifyToken(token, secret, expectedType, config) {
-    const parts = token.split(".");
-    if (parts.length !== 3) {
+    const parts = splitToken(token);
+    if (!parts) {
         return { valid: false, error: "Invalid token format" };
     }
     const [headerB64, bodyB64, signature] = parts;
+    const header = decodeJsonSegment(headerB64);
+    if (!header) {
+        return { valid: false, error: "Invalid header" };
+    }
+    if (header["alg"] !== ALGORITHM) {
+        return { valid: false, error: "Unsupported algorithm" };
+    }
     const signatureInput = `${headerB64}.${bodyB64}`;
     const expectedSignature = hmacSha256(signatureInput, secret);
-    const sigBuffer = Buffer.from(signature ?? "", "hex");
-    const expectedBuffer = Buffer.from(expectedSignature, "hex");
+    const sigBuffer = Buffer.from(signature, "base64url");
+    const expectedBuffer = Buffer.from(expectedSignature, "base64url");
     if (sigBuffer.length !== expectedBuffer.length ||
         !timingSafeEqual(sigBuffer, expectedBuffer)) {
         return { valid: false, error: "Invalid signature" };
     }
-    let payload;
-    try {
-        payload = JSON.parse(base64UrlDecode(bodyB64));
+    const decoded = decodeJsonSegment(bodyB64);
+    if (!decoded) {
+        return { valid: false, error: "Invalid payload" };
     }
-    catch {
+    if (!isTokenPayload(decoded)) {
         return { valid: false, error: "Invalid payload" };
     }
+    const payload = decoded;
     const now = Math.floor(Date.now() / 1000);
-    if (payload.exp < now) {
+    const skew = config.clockToleranceSeconds ?? 0;
+    if (payload.exp + skew < now) {
         return { valid: false, error: "Token expired" };
     }
+    if (payload.iat - skew > now) {
+        return { valid: false, error: "Token issued in the future" };
+    }
+    const nbf = payload["nbf"];
+    if (typeof nbf === "number" && nbf - skew > now) {
+        return { valid: false, error: "Token not yet valid" };
+    }
     if (payload.typ !== expectedType) {
         return { valid: false, error: `Expected ${expectedType} token` };
     }
-    if (config.issuer && payload.iss !== config.issuer) {
+    if (config.issuer && payload["iss"] !== config.issuer) {
         return { valid: false, error: "Invalid issuer" };
     }
+    if (config.audience && payload["aud"] !== config.audience) {
+        return { valid: false, error: "Invalid audience" };
+    }
     return { valid: true, payload };
 }
+/**
+ * Narrow a decoded JWT body to a {@link TokenPayload}.
+ *
+ * Replaces the `as TokenPayload` cast that previously let a `null`, an
+ * array, or a payload with a missing/mistyped `sub`, `jti`, `exp`, `iat` or
+ * `typ` flow into the caller.
+ */
+function isTokenPayload(value) {
+    if (typeof value["sub"] !== "string" || value["sub"].length === 0) {
+        return false;
+    }
+    if (typeof value["jti"] !== "string" || value["jti"].length === 0) {
+        return false;
+    }
+    if (value["typ"] !== "access" && value["typ"] !== "refresh")
+        return false;
+    if (!isFiniteNumber(value["exp"]))
+        return false;
+    if (!isFiniteNumber(value["iat"]))
+        return false;
+    const roles = value["roles"];
+    if (roles !== undefined &&
+        (!Array.isArray(roles) || roles.some((r) => typeof r !== "string"))) {
+        return false;
+    }
+    return true;
+}
+function isFiniteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value);
+}
 /**
  * Generate a random token ID.
  */
@@ -63,25 +160,6 @@ export function generateTokenId() {
 }
 // ─── Internal helpers ─────────────────────────────────────────────────────
 function hmacSha256(data, secret) {
-    return createHmac("sha256", secret).update(data).digest("hex");
-}
-function base64UrlEncode(data) {
-    const encoded = Buffer.from(data).toString("base64");
-    let result = "";
-    for (let i = 0; i < encoded.length; i++) {
-        const char = encoded[i];
-        if (char === "+")
-            result += "-";
-        else if (char === "/")
-            result += "_";
-        else if (char !== "=")
-            result += char;
-    }
-    return result;
-}
-function base64UrlDecode(data) {
-    const padded = data.replace(/-/g, "+").replace(/_/g, "/");
-    const padLength = (4 - (padded.length % 4)) % 4;
-    return Buffer.from(padded + "=".repeat(padLength), "base64").toString("utf-8");
+    return createHmac("sha256", secret).update(data).digest("base64url");
 }
 //# sourceMappingURL=authToken.signing.js.map

package/dist/authToken/index.d.ts

@@ -4,4 +4,5 @@
  * @module authToken
  */
 export { createTokenPair, verifyAccessToken, verifyRefreshToken, refreshAccessToken, } from "./authToken.core.js";
+export { createMemoryTokenRevocationStore } from "./authToken.revocation.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/authToken/index.js

@@ -4,4 +4,5 @@
  * @module authToken
  */
 export { createTokenPair, verifyAccessToken, verifyRefreshToken, refreshAccessToken, } from "./authToken.core.js";
+export { createMemoryTokenRevocationStore } from "./authToken.revocation.js";
 //# sourceMappingURL=index.js.map

package/dist/authToken/jwt.namespace.d.ts

@@ -1,18 +1,28 @@
 /**
  * @zudojs/auth — JWT Namespace
  *
- * Convenience namespace for all JWT-related utilities.
+ * Convenience namespace for the JWT primitives: minting, verification, the
+ * non-rotating refresh helper, the in-memory revocation store, and the
+ * unverified header/claim parsers.
+ *
+ * Note what is *not* here: `createAuthService()`. `jwt.refreshAccessToken`
+ * performs no rotation and consults no revocation store — pair it with
+ * `jwt.createMemoryTokenRevocationStore` yourself, or use
+ * `createAuthService().refresh()`, which rotates, revokes, re-loads the user
+ * and validates the session.
  */
 import { createTokenPair, verifyAccessToken, verifyRefreshToken, refreshAccessToken } from "./authToken.core.js";
+import { createMemoryTokenRevocationStore } from "./authToken.revocation.js";
 import { parseBearerToken, isTokenExpired, extractUserId } from "../authUtils/authUtils.helper.js";
 export type { JwtToken, TokenPair, TokenConfig, TokenVerificationResult, } from "../authTypes/authToken.type.js";
 export declare const jwt: {
-    createTokenPair: typeof createTokenPair;
-    verifyAccessToken: typeof verifyAccessToken;
-    verifyRefreshToken: typeof verifyRefreshToken;
-    refreshAccessToken: typeof refreshAccessToken;
-    parseBearerToken: typeof parseBearerToken;
-    isTokenExpired: typeof isTokenExpired;
-    extractUserId: typeof extractUserId;
+    readonly createTokenPair: typeof createTokenPair;
+    readonly verifyAccessToken: typeof verifyAccessToken;
+    readonly verifyRefreshToken: typeof verifyRefreshToken;
+    readonly refreshAccessToken: typeof refreshAccessToken;
+    readonly createMemoryTokenRevocationStore: typeof createMemoryTokenRevocationStore;
+    readonly parseBearerToken: typeof parseBearerToken;
+    readonly isTokenExpired: typeof isTokenExpired;
+    readonly extractUserId: typeof extractUserId;
 };
 //# sourceMappingURL=jwt.namespace.d.ts.map

package/dist/authToken/jwt.namespace.js

@@ -1,15 +1,25 @@
 /**
  * @zudojs/auth — JWT Namespace
  *
- * Convenience namespace for all JWT-related utilities.
+ * Convenience namespace for the JWT primitives: minting, verification, the
+ * non-rotating refresh helper, the in-memory revocation store, and the
+ * unverified header/claim parsers.
+ *
+ * Note what is *not* here: `createAuthService()`. `jwt.refreshAccessToken`
+ * performs no rotation and consults no revocation store — pair it with
+ * `jwt.createMemoryTokenRevocationStore` yourself, or use
+ * `createAuthService().refresh()`, which rotates, revokes, re-loads the user
+ * and validates the session.
  */
 import { createTokenPair, verifyAccessToken, verifyRefreshToken, refreshAccessToken, } from "./authToken.core.js";
+import { createMemoryTokenRevocationStore } from "./authToken.revocation.js";
 import { parseBearerToken, isTokenExpired, extractUserId, } from "../authUtils/authUtils.helper.js";
 export const jwt = {
     createTokenPair,
     verifyAccessToken,
     verifyRefreshToken,
     refreshAccessToken,
+    createMemoryTokenRevocationStore,
     parseBearerToken,
     isTokenExpired,
     extractUserId,

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

@@ -0,0 +1,63 @@
+/**
+ * Login attempt tracking types — brute-force lockout and rate limiting.
+ *
+ * @module authTypes/authAttempt
+ */
+/**
+ * Current attempt state for one login identifier.
+ */
+export interface LoginAttemptRecord {
+    /** Consecutive failed authentications since the last successful login. */
+    readonly failures: number;
+    /** Attempts counted inside the current rate-limit window. */
+    readonly attempts: number;
+    /** Unix milliseconds until which the identifier is locked, if locked. */
+    readonly lockedUntil?: number;
+}
+/**
+ * Store backing failed-attempt lockout and login rate limiting.
+ *
+ * Keys are the *submitted* identifier, not a resolved user id, so unknown
+ * and known accounts are throttled identically and the endpoint stays free
+ * of an existence oracle. The in-memory implementation
+ * (`createMemoryLoginAttemptStore`) is per-process; back this with Redis to
+ * make limits hold across instances.
+ */
+export interface LoginAttemptStore {
+    /** Read the current state without recording anything. */
+    get(identifier: string): Promise<LoginAttemptRecord>;
+    /** Count an attempt (before credentials are checked). */
+    recordAttempt(identifier: string): Promise<LoginAttemptRecord>;
+    /** Count a failed authentication. */
+    recordFailure(identifier: string): Promise<LoginAttemptRecord>;
+    /** Lock an identifier until `until` (Unix milliseconds). */
+    lock(identifier: string, until: number): Promise<void>;
+    /** Clear all state for an identifier (successful login). */
+    reset(identifier: string): Promise<void>;
+}
+/**
+ * Brute-force protection settings for `createAuthService()`.
+ */
+export interface LoginThrottleConfig {
+    /** Where attempt counters live. */
+    readonly store: LoginAttemptStore;
+    /**
+     * Consecutive failures that trigger a lockout (default: 5).
+     * `login()` then throws `AccountLockedError` until the lockout lapses.
+     */
+    readonly maxFailedAttempts?: number;
+    /** Lockout duration in seconds (default: 900). */
+    readonly lockoutSeconds?: number;
+    /**
+     * Attempts allowed per identifier inside the store's rate-limit window
+     * (default: 20). Exceeding it throws `AuthRateLimitError`. This bounds the
+     * scrypt work an attacker can force the server to perform.
+     */
+    readonly maxAttemptsPerWindow?: number;
+    /**
+     * Window length in seconds reported on `AuthRateLimitError.retryAfterSeconds`
+     * (default: 60). The store owns the actual window.
+     */
+    readonly windowSeconds?: number;
+}
+//# sourceMappingURL=authAttempt.type.d.ts.map

package/dist/authTypes/authAttempt.type.js

@@ -0,0 +1,7 @@
+/**
+ * Login attempt tracking types — brute-force lockout and rate limiting.
+ *
+ * @module authTypes/authAttempt
+ */
+export {};
+//# sourceMappingURL=authAttempt.type.js.map

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

@@ -0,0 +1,26 @@
+/**
+ * Credential shapes accepted by the authentication entry points.
+ *
+ * @module authTypes/authCredentials
+ *
+ * These are plain contracts for the credentials a caller collects from a
+ * request. They carry no behaviour; `createAuthService()` takes the
+ * identifier and password directly.
+ */
+/**
+ * Password credentials: an identifier (username or email) and a password.
+ */
+export interface PasswordCredentials {
+    readonly identifier: string;
+    readonly password: string;
+}
+/**
+ * API key credentials.
+ *
+ * The type exists for callers that model machine-to-machine auth; this
+ * package implements no API-key verification.
+ */
+export interface ApiKeyCredentials {
+    readonly apiKey: string;
+}
+//# sourceMappingURL=authCredentials.type.d.ts.map

package/dist/authTypes/authCredentials.type.js

@@ -0,0 +1,11 @@
+/**
+ * Credential shapes accepted by the authentication entry points.
+ *
+ * @module authTypes/authCredentials
+ *
+ * These are plain contracts for the credentials a caller collects from a
+ * request. They carry no behaviour; `createAuthService()` takes the
+ * identifier and password directly.
+ */
+export {};
+//# sourceMappingURL=authCredentials.type.js.map

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

@@ -6,6 +6,18 @@
 import type { UserId } from "../authTypes/authUser.type.js";
 import type { SessionId } from "@zudojs/constants";
 export type { SessionId } from "@zudojs/constants";
+/**
+ * Brands a plain string as a {@link SessionId}.
+ *
+ * `SessionId` is a branded type with no public constructor, so callers holding
+ * an id from a session store, a cookie or a request parameter have no way to
+ * produce one without a cast. This is that constructor.
+ *
+ * @param value - Non-empty session identifier.
+ * @returns The same string, typed as a `SessionId`.
+ * @throws {TypeError} If `value` is not a non-empty string.
+ */
+export declare function toSessionId(value: string): SessionId;
 /**
  * Server-side session representation.
  */
@@ -22,10 +34,19 @@ export interface AuthSession {
     readonly createdAt: Date;
     /** Last activity time */
     readonly lastActivityAt: Date;
-    /** Session expiration time */
+    /**
+     * Session expiration time.
+     *
+     * With sliding expiration this moves forward on every `touch()`, but never
+     * past `createdAt + absoluteTtlSeconds` when an absolute lifetime was
+     * requested.
+     */
     readonly expiresAt: Date;
-    /** Whether the session is active */
-    readonly active: boolean;
+    /**
+     * Hard deadline for the session, when one was requested at creation.
+     * `touch()` never extends `expiresAt` beyond this.
+     */
+    readonly absoluteExpiresAt?: Date;
     /** Session metadata */
     readonly metadata?: Record<string, unknown>;
 }
@@ -36,7 +57,14 @@ export interface CreateSessionOptions {
     readonly userId: UserId;
     readonly userAgent?: string;
     readonly ip?: string;
+    /** Idle timeout in seconds; refreshed by `touch()` (default: 86400). */
     readonly ttlSeconds?: number;
+    /**
+     * Absolute maximum session lifetime in seconds, measured from creation.
+     * Without it a session that is touched once per idle window never expires,
+     * so a stolen session id is valid indefinitely.
+     */
+    readonly absoluteTtlSeconds?: number;
     readonly metadata?: Record<string, unknown>;
 }
 /**

package/dist/authTypes/authSession.type.js

@@ -3,5 +3,21 @@
  *
  * @module authSession/authSession
  */
-export {};
+/**
+ * Brands a plain string as a {@link SessionId}.
+ *
+ * `SessionId` is a branded type with no public constructor, so callers holding
+ * an id from a session store, a cookie or a request parameter have no way to
+ * produce one without a cast. This is that constructor.
+ *
+ * @param value - Non-empty session identifier.
+ * @returns The same string, typed as a `SessionId`.
+ * @throws {TypeError} If `value` is not a non-empty string.
+ */
+export function toSessionId(value) {
+    if (typeof value !== "string" || value.length === 0) {
+        throw new TypeError("toSessionId: value must be a non-empty string.");
+    }
+    return value;
+}
 //# sourceMappingURL=authSession.type.js.map