@zudojs/auth 0.1.0 → 1.0.0

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,45 @@ 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).
+ *
+ * Backs refresh-token rotation and explicit revocation. The in-memory
+ * implementation is good for development; production should use Redis
+ * or a database with the same interface.
+ */
+export interface TokenRevocationStore {
+    /**
+     * Mark a token ID as revoked.
+     *
+     * @param tokenId - The token's `jti` claim
+     * @param expiresAt - The token's `exp` claim (Unix seconds); entries
+     *   may be discarded after this time since the token is then invalid anyway.
+     */
+    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 JwtToken, type TokenId, type TokenPayload, type TokenPair, type TokenConfig, 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 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, 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.
  *

package/dist/authUtils/authUtils.helper.js

@@ -4,74 +4,113 @@
  * @module authUtils
  */
 import { randomBytes } from "node:crypto";
+import { decodeJsonSegment, splitToken, } from "../authToken/authToken.encoding.js";
+/**
+ * Maximum accepted length of an `Authorization` header value.
+ * Sized to comfortably hold `Bearer ` plus a maximum-length JWT.
+ */
+const MAX_AUTHORIZATION_LENGTH = 8256;
+/** Maximum accepted length of a `Cookie` header value. */
+const MAX_COOKIE_HEADER_LENGTH = 8192;
+/** Maximum number of cookie pairs parsed from one header. */
+const MAX_COOKIE_PAIRS = 100;
+/**
+ * `Bearer <token>` — the scheme is matched case-insensitively per RFC 7235
+ * §2.1, and surrounding/extra whitespace is tolerated.
+ */
+const BEARER_PATTERN = /^\s*bearer[ \t]+(\S+)\s*$/i;
 /**
  * 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 function parseBearerToken(authorization) {
-    if (!authorization)
+    if (typeof authorization !== "string")
         return null;
-    const parts = authorization.split(" ");
-    if (parts.length !== 2 || parts[0] !== "Bearer")
+    if (authorization.length > MAX_AUTHORIZATION_LENGTH)
         return null;
-    return parts[1] ?? null;
+    const match = BEARER_PATTERN.exec(authorization);
+    return match?.[1] ?? 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 function parseCookies(cookie) {
-    const result = {};
-    if (!cookie)
+    const result = Object.create(null);
+    if (typeof cookie !== "string")
         return result;
+    if (cookie.length === 0 || cookie.length > MAX_COOKIE_HEADER_LENGTH) {
+        return result;
+    }
+    let pairs = 0;
     for (const part of cookie.split(";")) {
+        if (pairs >= MAX_COOKIE_PAIRS)
+            break;
         const [key, ...rest] = part.trim().split("=");
         if (key && rest.length > 0) {
             result[key.trim()] = rest.join("=").trim();
+            pairs++;
         }
     }
     return result;
 }
 /**
- * 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 function isTokenExpired(token) {
-    try {
-        const parts = token.split(".");
-        if (parts.length !== 3)
-            return true;
-        const payload = JSON.parse(Buffer.from(parts[1].replace(/-/g, "+").replace(/_/g, "/"), "base64").toString("utf-8"));
-        const now = Math.floor(Date.now() / 1000);
-        return payload.exp < now;
-    }
-    catch {
+    const parts = splitToken(token);
+    if (!parts)
         return true;
-    }
+    const payload = decodeJsonSegment(parts[1]);
+    if (!payload)
+        return true;
+    const exp = payload["exp"];
+    const now = Math.floor(Date.now() / 1000);
+    return typeof exp !== "number" || !Number.isFinite(exp) || exp < now;
 }
 /**
- * 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 function extractUserId(token) {
-    try {
-        const parts = token.split(".");
-        if (parts.length !== 3)
-            return null;
-        const payload = JSON.parse(Buffer.from(parts[1].replace(/-/g, "+").replace(/_/g, "/"), "base64").toString("utf-8"));
-        return payload.sub ?? null;
-    }
-    catch {
+    const parts = splitToken(token);
+    if (!parts)
         return null;
-    }
+    const payload = decodeJsonSegment(parts[1]);
+    if (!payload)
+        return null;
+    const sub = payload["sub"];
+    return typeof sub === "string" && sub.length > 0 ? sub : null;
 }
 /**
  * Generate a CSRF token.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zudojs/auth",
-  "version": "0.1.0",
-  "description": "Authentication and authorization services for the Zudojs framework — JWT, sessions, RBAC, OAuth2, and password management.",
+  "version": "1.0.0",
+  "description": "Authentication and authorization services for the Zudojs framework — JWT, sessions, RBAC, and password management.",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -15,25 +15,21 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "!dist/**/*.map",
+    "!dist/**/*.tsbuildinfo",
+    "!dist/.tsbuildinfo"
   ],
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "clean": "rm -rf dist",
-    "test": "vitest run",
-    "test:watch": "vitest"
-  },
   "dependencies": {
-    "@zudojs/errors": "0.1.0",
-    "@zudojs/constants": "0.1.0",
-    "@zudojs/permissions": "0.1.0"
+    "@zudojs/errors": "1.0.0",
+    "@zudojs/constants": "1.0.0",
+    "@zudojs/permissions": "1.0.0"
   },
   "engines": {
     "node": ">=24.0.0"
   },
   "devDependencies": {
-    "typescript": "^7.0.2",
+    "typescript": "7.0.2",
     "vitest": "^4.1.11"
   },
   "publishConfig": {
@@ -48,8 +44,19 @@
     "rbac"
   ],
   "homepage": "https://github.com/oyinlola-tech/zudo#readme",
+  "bugs": {
+    "url": "https://github.com/oyinlola-tech/zudo/issues"
+  },
   "repository": {
     "type": "git",
-    "url": "https://github.com/oyinlola-tech/zudo"
+    "url": "https://github.com/oyinlola-tech/zudo",
+    "directory": "packages/auth"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json --noEmit",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "test:watch": "vitest"
   }
-}
+}