@zudojs/auth 0.1.1 → 1.1.0

package/dist/authToken/authToken.signing.js

@@ -5,10 +5,68 @@
  *
  * 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.");
+    }
+    // A NaN TTL (`Number(process.env.X)` with X unset) minted tokens whose
+    // `exp` serialised as `null`, which every verifier then rejected as
+    // "Invalid payload" — a misconfiguration that only surfaced as a mystery
+    // at first login. Zero and negative TTLs are deliberately still accepted:
+    // they mint already-expired tokens, which is a documented way to test
+    // expiry handling.
+    assertFiniteTtl(config.accessTtl, "accessTtl");
+    assertFiniteTtl(config.refreshTtl, "refreshTtl");
+}
+function assertFiniteTtl(value, field) {
+    if (value === undefined)
+        return;
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new AuthConfigurationError(`TokenConfig.${field} must be a finite number of seconds; got ${String(value)}.`);
+    }
+}
+function assertSecret(secret, field) {
+    if (typeof secret !== "string" || secret.length === 0) {
+        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,58 +78,95 @@ export function signToken(payload, secret) {
     return `${signatureInput}.${signature}`;
 }
 /**
- * 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 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;
-    let header;
-    try {
-        header = JSON.parse(base64UrlDecode(headerB64));
-    }
-    catch {
+    const header = decodeJsonSegment(headerB64);
+    if (!header) {
         return { valid: false, error: "Invalid header" };
     }
-    if (header.alg !== ALGORITHM) {
+    if (header["alg"] !== ALGORITHM) {
         return { valid: false, error: "Unsupported algorithm" };
     }
     const signatureInput = `${headerB64}.${bodyB64}`;
     const expectedSignature = hmacSha256(signatureInput, secret);
-    const sigBuffer = Buffer.from(signature ?? "", "base64url");
+    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 (typeof payload.exp !== "number") {
-        return { valid: false, error: "Missing expiration" };
-    }
-    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) {
+    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.
  */
@@ -82,10 +177,4 @@ export function generateTokenId() {
 function hmacSha256(data, secret) {
     return createHmac("sha256", secret).update(data).digest("base64url");
 }
-function base64UrlEncode(data) {
-    return Buffer.from(data, "utf-8").toString("base64url");
-}
-function base64UrlDecode(data) {
-    return Buffer.from(data, "base64url").toString("utf-8");
-}
 //# sourceMappingURL=authToken.signing.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,65 @@
+/**
+ * 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 — trimmed, NFKC-normalised and
+ * lower-cased by `createAuthService()` so that case and whitespace variants
+ * of one email share a budget — 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

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

@@ -4,7 +4,7 @@
  * @module authToken/authToken
  */
 import type { UserId } from "../authTypes/authUser.type.js";
-import type { TokenId } from "@zudojs/constants";
+import type { SessionId, TokenId } from "@zudojs/constants";
 /** JWT token string. */
 export type JwtToken = string;
 /** Token identifier. Re-exported from @zudojs/constants for type safety. */
@@ -25,6 +25,14 @@ export interface TokenPayload {
     readonly jti: TokenId;
     /** User roles */
     readonly roles?: readonly string[];
+    /**
+     * Session ID this token was issued against.
+     *
+     * Set by `createAuthService().login()`. `verifyToken()` and `refresh()`
+     * require the referenced session to still exist, which is what makes
+     * `logout()` actually invalidate outstanding tokens.
+     */
+    readonly sid?: SessionId;
     /** Custom claims */
     readonly [key: string]: unknown;
 }
@@ -57,6 +65,11 @@ export interface TokenConfig {
     readonly issuer?: string;
     /** JWT audience */
     readonly audience?: string;
+    /**
+     * Clock-skew tolerance in seconds applied to `exp`, `iat` and `nbf`
+     * (default: 0, maximum: 300).
+     */
+    readonly clockToleranceSeconds?: number;
 }
 /**
  * Store for revoked token IDs (`jti` claims).
@@ -76,6 +89,21 @@ export interface TokenRevocationStore {
     revoke(tokenId: TokenId, expiresAt: number): Promise<void>;
     /** Check whether a token ID has been revoked. */
     isRevoked(tokenId: TokenId): Promise<boolean>;
+    /**
+     * Atomically revoke a token ID **only if it was not already revoked**,
+     * returning whether this caller was the one that revoked it.
+     *
+     * This is the compare-and-set that makes refresh-token rotation safe: a
+     * separate `isRevoked()` then `revoke()` leaves two `await` points during
+     * which a concurrent replay of the same token also observes "not revoked"
+     * and also mints a valid pair. Implement it with a single synchronous
+     * `Map.has`/`set` in-process, or `SET NX` in Redis.
+     *
+     * Optional for backwards compatibility: `createAuthService().refresh()`
+     * falls back to `isRevoked()` + `revoke()` when it is absent, which is
+     * racy. Implement it in any store used in production.
+     */
+    revokeIfNotRevoked?(tokenId: TokenId, expiresAt: number): Promise<boolean>;
 }
 /**
  * Result of token verification.

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

@@ -5,6 +5,18 @@
  */
 import type { UserId } from "@zudojs/constants";
 export type { UserId } from "@zudojs/constants";
+/**
+ * Brands a plain string as a {@link UserId}.
+ *
+ * `UserId` is a branded type with no public constructor, so callers holding an
+ * id from a database row, a decoded token or a request parameter have no way to
+ * produce one without a cast. This is that constructor.
+ *
+ * @param value - Non-empty user identifier.
+ * @returns The same string, typed as a `UserId`.
+ * @throws {TypeError} If `value` is not a non-empty string.
+ */
+export declare function toUserId(value: string): UserId;
 /**
  * Authenticated user representation.
  */

package/dist/authTypes/authUser.type.js

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

package/dist/authTypes/index.d.ts

@@ -1,11 +1,12 @@
 /**
- * Core auth types: users, tokens, sessions, strategies, and RBAC.
+ * Core auth types: users, tokens, sessions, credentials, and RBAC.
  *
  * @module authTypes
  */
-export { type UserId, type AuthUser, type UserCredentials, type UserRegistration, } from "./authUser.type.js";
+export { type UserId, toUserId, type AuthUser, type UserCredentials, type UserRegistration, } from "./authUser.type.js";
 export { type JwtToken, type TokenId, type TokenPayload, type TokenPair, type TokenConfig, type TokenRevocationStore, type TokenVerificationResult, } from "./authToken.type.js";
-export { type SessionId, type AuthSession, type CreateSessionOptions, type SessionStore, } from "./authSession.type.js";
-export { type OAuthProvider, type OAuthConfig, type OAuthUserInfo, type OAuthResult, type AuthStrategy, type PasswordCredentials, type ApiKeyCredentials, } from "./authStrategy.type.js";
+export { type SessionId, toSessionId, type AuthSession, type CreateSessionOptions, type SessionStore, } from "./authSession.type.js";
+export { type PasswordCredentials, type ApiKeyCredentials, } from "./authCredentials.type.js";
+export { type LoginAttemptRecord, type LoginAttemptStore, type LoginThrottleConfig, } from "./authAttempt.type.js";
 export { type Permission, type Role, type GuardResult, type GuardContext, } from "./authRbac.type.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/authTypes/index.js

@@ -1,11 +1,12 @@
 /**
- * Core auth types: users, tokens, sessions, strategies, and RBAC.
+ * Core auth types: users, tokens, sessions, credentials, and RBAC.
  *
  * @module authTypes
  */
-export {} from "./authUser.type.js";
+export { toUserId, } from "./authUser.type.js";
 export {} from "./authToken.type.js";
-export {} from "./authSession.type.js";
-export {} from "./authStrategy.type.js";
+export { toSessionId, } from "./authSession.type.js";
+export {} from "./authCredentials.type.js";
+export {} from "./authAttempt.type.js";
 export {} from "./authRbac.type.js";
 //# sourceMappingURL=index.js.map

package/dist/authUtils/authUtils.helper.d.ts

@@ -6,31 +6,52 @@
 /**
  * Parse a Bearer token from an Authorization header.
  *
+ * Accepts `unknown` on purpose: this sits on the HTTP trust boundary, where
+ * a duplicated header gives `string[]` and adapter layers routinely pass
+ * through values they have not narrowed. Anything that is not a plausible
+ * header value is `null`, never a thrown `TypeError`.
+ *
  * @param authorization - Raw Authorization header value
  * @returns The token string, or null if not a Bearer token
  */
-export declare function parseBearerToken(authorization: string | undefined): string | null;
+export declare function parseBearerToken(authorization: unknown): string | null;
 /**
  * Parse cookie string into a key-value map.
  *
- * @param cookie - Raw Cookie header value
- * @returns Parsed cookies
+ * The returned object has a `null` prototype, so a cookie named
+ * `constructor`, `hasOwnProperty` or `__proto__` cannot shadow or confuse an
+ * inherited member for the caller. Oversized headers and cookie counts are
+ * capped rather than allocated.
+ *
+ * @param cookie - Raw Cookie header value (any type; see
+ *   {@link parseBearerToken} for why)
+ * @returns Parsed cookies — an object with no prototype
  */
-export declare function parseCookies(cookie: string | undefined): Record<string, string>;
+export declare function parseCookies(cookie: unknown): Record<string, string>;
 /**
- * Check if a token is expired without verifying the signature.
+ * Check if a token is expired **without verifying the signature**.
+ *
+ * The payload is attacker-controlled: treat the answer as a hint (e.g. "should
+ * I refresh before calling?"), never as an authorization decision.
  *
  * @param token - JWT token string
- * @returns Whether the token appears expired
+ * @returns Whether the token appears expired. Unparseable, oversized, or
+ *   malformed input is reported as expired.
  */
-export declare function isTokenExpired(token: string): boolean;
+export declare function isTokenExpired(token: unknown): boolean;
 /**
- * Extract the user ID from a JWT payload without verifying.
+ * Extract the user ID from a JWT payload **without verifying the signature**.
+ *
+ * The returned value is attacker-controlled. It is safe to use as a
+ * diagnostic hint; it must never be used to decide who the caller is, or as
+ * a key in anything security-relevant, without verifying the token first.
  *
  * @param token - JWT token string
- * @returns User ID or null
+ * @returns The `sub` claim when it is a non-empty string, otherwise null.
+ *   A `sub` that is a number, object, or array is reported as null rather
+ *   than leaking a non-string through a `string | null` signature.
  */
-export declare function extractUserId(token: string): string | null;
+export declare function extractUserId(token: unknown): string | null;
 /**
  * Generate a CSRF token.
  *