kroxt 1.0.1 → 1.1.1

package/dist-lib/core.d.ts

@@ -2,22 +2,34 @@ import type { AuthAdapter, User } from "./adapter.js";
 import type { Provider } from "./providers.js";
 export interface CreateAuthOptions {
     adapter: AuthAdapter<any>;
-    secret: string;
+    secret: string | Uint8Array;
+    pepper?: string;
     session?: {
         expires?: string | number;
+        refreshExpires?: string | number;
     };
     providers?: Provider[];
 }
 export declare function createAuth(options: CreateAuthOptions): {
     signup: (userData: Omit<User<any>, "id">, password?: string) => Promise<{
         user: any;
-        token: string;
+        accessToken: string;
+        refreshToken: string;
     }>;
     loginWithPassword: (email: string, password: string) => Promise<{
         user: any;
-        token: string;
+        accessToken: string;
+        refreshToken: string;
     }>;
-    verifyToken: (token: string) => Promise<import("jose").JWTPayload>;
-    generateToken: (user: User<any>) => Promise<string>;
+    refresh: (refreshToken: string) => Promise<{
+        accessToken: string;
+    }>;
+    verifyToken: (token: string, expectedType?: "access" | "refresh") => Promise<import("jose").JWTPayload>;
+    generateToken: (user: User<any>, type?: "access" | "refresh") => Promise<string>;
     _providers: Provider[];
 };
+/**
+ * Utility to generate a high-entropy cryptographically secure secret.
+ * Useful for initializing the 'secret' option in createAuth.
+ */
+export declare function generateSecret(length?: number): Uint8Array;

package/dist-lib/core.js

@@ -1,25 +1,30 @@
 import * as argon2 from "argon2";
 import { SignJWT, jwtVerify } from "jose";
+import crypto from "crypto";
 export function createAuth(options) {
-    const { adapter, secret, session, providers } = options;
-    const encodedSecret = new TextEncoder().encode(secret);
-    const expiration = session?.expires || "7d";
+    const { adapter, secret, pepper, session, providers } = options;
+    const encodedSecret = typeof secret === "string" ? new TextEncoder().encode(secret) : secret;
+    const expiration = session?.expires || "1h"; // Default access token to 1h
+    const refreshExpiration = session?.refreshExpires || "7d";
     /**
      * Generates a stateless JWT for a user session
      */
-    async function generateToken(user) {
-        return new SignJWT({ sub: user.id, role: user.role })
+    async function generateToken(user, type = "access") {
+        return new SignJWT({ sub: user.id, role: user.role, type })
             .setProtectedHeader({ alg: "HS256" })
             .setIssuedAt()
-            .setExpirationTime(expiration)
+            .setExpirationTime(type === "access" ? expiration : refreshExpiration)
             .sign(encodedSecret);
     }
     /**
-     * Verifies a JWT and returns the payload
+     * Verifies a JWT and returns the payload.
+     * Optionally checks for a specific token type (access/refresh).
      */
-    async function verifyToken(token) {
+    async function verifyToken(token, expectedType = "access") {
         try {
             const { payload } = await jwtVerify(token, encodedSecret);
+            if (payload.type !== expectedType)
+                return null;
             return payload;
         }
         catch (e) {
@@ -27,41 +32,67 @@ export function createAuth(options) {
         }
     }
     /**
-     * Signup with a new user payload (handles extended schemas out-of-the-box).
-     * Generates a password hash if password is provided.
+     * Refreshes an access token using a valid refresh token.
+     */
+    async function refresh(refreshToken) {
+        const payload = await verifyToken(refreshToken, "refresh");
+        if (!payload || !payload.sub) {
+            throw new Error("Invalid or expired refresh token");
+        }
+        const user = await adapter.findUserById(payload.sub);
+        if (!user) {
+            throw new Error("User not found");
+        }
+        const accessToken = await generateToken(user, "access");
+        return { accessToken };
+    }
+    /**
+     * Signup with a new user payload.
+     * Incorporates server-side pepper for password hashing if provided.
      */
     async function signup(userData, password) {
         let dataToSave = { ...userData };
         if (password) {
-            dataToSave.passwordHash = await argon2.hash(password);
+            const passwordWithPepper = pepper ? `${password}${pepper}` : password;
+            dataToSave.passwordHash = await argon2.hash(passwordWithPepper);
         }
         const newUser = await adapter.createUser(dataToSave);
-        const token = await generateToken(newUser);
-        return { user: newUser, token };
+        const accessToken = await generateToken(newUser, "access");
+        const refreshToken = await generateToken(newUser, "refresh");
+        return { user: newUser, accessToken, refreshToken };
     }
     /**
-     * Standard Email/Password Login
+     * Standard Email/Password Login.
+     * Includes timing attack protection and password peppering.
      */
     async function loginWithPassword(email, password) {
         const user = await adapter.findUserByEmail(email);
-        if (!user) {
+        // Timing attack protection: Always verify a hash, even if user doesn't exist.
+        // We use a dummy hash to keep execution time consistent.
+        const dummyHash = "$argon2id$v=19$m=65536,t=3,p=4$c29tZXNhbHQ$RytpInY7i6C9M5l0D4n8Q+7j/J+i";
+        const targetHash = user?.passwordHash || dummyHash;
+        const passwordWithPepper = pepper ? `${password}${pepper}` : password;
+        const isValid = await argon2.verify(targetHash, passwordWithPepper);
+        if (!user || !user.passwordHash || !isValid) {
             throw new Error("Invalid credentials");
         }
-        if (!user.passwordHash) {
-            throw new Error("User does not have a password setup. Did they use OAuth?");
-        }
-        const isValid = await argon2.verify(user.passwordHash, password);
-        if (!isValid) {
-            throw new Error("Invalid credentials");
-        }
-        const token = await generateToken(user);
-        return { user, token };
+        const accessToken = await generateToken(user, "access");
+        const refreshToken = await generateToken(user, "refresh");
+        return { user, accessToken, refreshToken };
     }
     return {
         signup,
         loginWithPassword,
+        refresh,
         verifyToken,
         generateToken,
-        _providers: providers // Exposing to internal router mechanisms if needed
+        _providers: providers
     };
 }
+/**
+ * Utility to generate a high-entropy cryptographically secure secret.
+ * Useful for initializing the 'secret' option in createAuth.
+ */
+export function generateSecret(length = 32) {
+    return crypto.getRandomValues(new Uint8Array(length));
+}

package/dist-lib/index.d.ts

@@ -1,6 +1,7 @@
 export type { AuthAdapter, User, BaseUser } from "./adapter.js";
 export { GitHub, Google } from "./providers.js";
 export type { Provider, ProviderConfig } from "./providers.js";
-export { createAuth } from "./core.js";
+export { createAuth, generateSecret } from "./core.js";
 export type { CreateAuthOptions } from "./core.js";
 export { createMemoryAdapter } from "./memoryAdapter.js";
+export * from "./security.js";

package/dist-lib/index.js

@@ -1,3 +1,4 @@
 export { GitHub, Google } from "./providers.js";
-export { createAuth } from "./core.js";
+export { createAuth, generateSecret } from "./core.js";
 export { createMemoryAdapter } from "./memoryAdapter.js";
+export * from "./security.js";

package/dist-lib/security.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Generates a stateless CSRF token using the double-submit cookie pattern.
+ * This is recommended for Express/Kroxt setups using cookies for sessions.
+ */
+export declare function generateCsrfToken(): string;
+/**
+ * Simple middleware-ready check for CSRF tokens.
+ * Matches a token from the request body/headers against a cookie.
+ */
+export declare function verifyCsrf(tokenInRequest: string, tokenInCookie: string): boolean;
+/**
+ * Security Recommendations for Kroxt:
+ * 1. Always set cookies with: httpOnly: true, secure: true, sameSite: 'strict'
+ * 2. Use a 'pepper' in createAuth to protect hashes.
+ * 3. Implement rate limiting on /login and /register endpoints.
+ */

package/dist-lib/security.js

@@ -0,0 +1,29 @@
+import crypto from "crypto";
+/**
+ * Generates a stateless CSRF token using the double-submit cookie pattern.
+ * This is recommended for Express/Kroxt setups using cookies for sessions.
+ */
+export function generateCsrfToken() {
+    return crypto.randomBytes(32).toString("hex");
+}
+/**
+ * Simple middleware-ready check for CSRF tokens.
+ * Matches a token from the request body/headers against a cookie.
+ */
+export function verifyCsrf(tokenInRequest, tokenInCookie) {
+    if (!tokenInRequest || !tokenInCookie)
+        return false;
+    // Constant time comparison
+    try {
+        return crypto.timingSafeEqual(Buffer.from(tokenInRequest), Buffer.from(tokenInCookie));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Security Recommendations for Kroxt:
+ * 1. Always set cookies with: httpOnly: true, secure: true, sameSite: 'strict'
+ * 2. Use a 'pepper' in createAuth to protect hashes.
+ * 3. Implement rate limiting on /login and /register endpoints.
+ */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kroxt",
-  "version": "1.0.1",
+  "version": "1.1.1",
   "description": "A framework-agnostic modular auth engine",
   "type": "module",
   "main": "./dist-lib/index.js",