kroxt 1.0.1 → 1.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kroxt Auth
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,82 +1,169 @@
-# kroxt
-
-A framework-agnostic, modular authentication engine for modern TypeScript applications. Built for security, extensibility, and ease of use.
-
-## Features
-
-- 🔐 **Secure Hashing**: Powered by `argon2` for industry-standard password security.
-- 🎟️ **Stateless Sessions**: Managed via `jose` with high-performance JWT signing and verification.
-- 🌍 **OAuth Ready**: Built-in support for GitHub and Google OAuth via `arctic`.
-- 🧩 **Database Agnostic**: Use Mongoose, Prisma, Drizzle, or even in-memory stores via the `AuthAdapter` pattern.
-- ✅ **Zod Schema Support**: Perfectly preserves and types your extended user metadata.
-- 🚀 **ESM First**: Native support for NodeNext module resolution.
-
-## Installation
-
-```bash
-npm install kroxt
-```
-
-## Quick Start
-
-### 1. Initialize the Auth Engine
-
-```typescript
-import { createAuth } from "kroxt";
-import { myDatabaseAdapter } from "./myAdapter.js";
-
-const auth = createAuth({
-  adapter: myDatabaseAdapter,
-  secret: process.env.AUTH_SECRET,
-  session: {
-    expires: "7d" // jose compatible duration
-  }
-});
-```
-
-### 2. Sign Up a User
-
-```typescript
-const { user, token } = await auth.signup({
-  email: "user@example.com",
-  firstName: "Tobi",
-  role: "tenant",
-  // ...any other extended fields supported by your adapter
-}, "strong-password-123");
-```
-
-### 3. Log In
-
-```typescript
-const { user, token } = await auth.loginWithPassword("user@example.com", "password");
-```
-
-### 4. Verify a Session
-
-```typescript
-const payload = await auth.verifyToken(token);
-// auth.verifyToken returns the signed payload { sub: string, role: string, ... }
-```
-
-## The Adapter Pattern
-
-Gatekeeper doesn't care which DB you use. You just need to implement the `AuthAdapter` interface:
-
-```typescript
-import type { AuthAdapter, User } from "kroxt/adapter";
-
-export const myAdapter: AuthAdapter = {
-  createUser: async (data) => { /* logic */ },
-  findUserByEmail: async (email) => { /* logic */ },
-  findUserById: async (id) => { /* logic */ },
-  linkOAuthAccount: async (user, provider, provId) => { /* logic */ }
-};
-```
-
-## Reference Project
-
-Check out the `test-project` folder for a complete **Express + MongoDB** implementation using this library.
-
-## License
-
-ISC
+# kroxt
+
+A framework-agnostic, modular authentication engine for modern TypeScript applications. Built for security, extensibility, and ease of use.
+
+## Features
+
+- 🔐 **Secure Hashing**: Powered by `argon2` for industry-standard password security.
+- 🎟️ **Dual-Token Sessions**: Native support for Access and Refresh tokens via `jose`.
+- 🌍 **OAuth Ready**: Built-in support for GitHub and Google OAuth via `arctic`.
+- 🧩 **Database Agnostic**: Use Mongoose, Prisma, Drizzle, or any store via the `AuthAdapter` pattern.
+- 🌶️ **Password Peppering**: Server-side pepper support for enhanced hash protection.
+- 🛡️ **Timing Attack Protection**: Built-in safeguards against side-channel analysis during login.
+- ✅ **Zod Schema Support**: Perfectly preserves and types your user metadata.
+- 🚀 **ESM First**: Native support for NodeNext module resolution.
+
+## Installation
+
+```bash
+npm install kroxt
+```
+
+---
+
+## Guide: Full Authentication Flow
+
+This guide walks you through setting up Kroxt from scratch in your application.
+
+### Step 1: The Adapter Pattern
+
+Kroxt doesn't care which database you use. You just need to implement the `AuthAdapter` interface. 
+
+In this example, we use a simple user structure: `name`, `email`, and `password`.
+> [!NOTE]
+> Kroxt's adapter can accept **any** additional fields your application requires (e.g., `role`, `avatar`, `preferences`) with no limits.
+
+```typescript
+import type { AuthAdapter, User } from "kroxt/adapter";
+
+export const myAdapter: AuthAdapter = {
+  createUser: async (data) => {
+    // Save to your DB: { name, email, passwordHash, ...anyOtherFields }
+    // return the created user including its unique id
+  },
+  findUserByEmail: async (email) => {
+    // Find user by email in your DB
+  },
+  findUserById: async (id) => {
+    // Find user by ID in your DB
+  },
+  linkOAuthAccount: async (user, provider, providerId) => {
+    // Link an OAuth provider to an existing user
+  }
+};
+```
+
+### Step 2: Initialize the Auth Engine
+
+Configure Kroxt with your adapter and security settings.
+
+```typescript
+import { createAuth } from "kroxt";
+import { myAdapter } from "./myAdapter.js";
+
+export const auth = createAuth({
+  adapter: myAdapter,
+  secret: process.env.AUTH_SECRET, // High-entropy secret for JWT signing
+  pepper: process.env.AUTH_PEPPER, // Optional: Server-side pepper for password hashing
+  session: {
+    expires: "15m",        // Access token duration
+    refreshExpires: "7d"   // Refresh token duration
+  }
+});
+```
+
+### Step 3: Implement Controllers & Routes
+
+Use the engine in your application logic. Examples below use an Express-like structure.
+
+#### Registration
+```typescript
+app.post("/register", async (req, res) => {
+  const { name, email, password, ...extraFields } = req.body;
+  
+  // Kroxt handles argon2 hashing (with pepper) and token generation
+  const { user, accessToken, refreshToken } = await auth.signup({
+    name,
+    email,
+    ...extraFields
+  }, password);
+
+  res.json({ user, accessToken, refreshToken });
+});
+```
+
+#### Login
+```typescript
+app.post("/login", async (req, res) => {
+  const { email, password } = req.body;
+  
+  // Kroxt verifies password (timing-attack safe) and returns tokens
+  const { user, accessToken, refreshToken } = await auth.loginWithPassword(email, password);
+
+  res.json({ user, accessToken, refreshToken });
+});
+```
+
+#### Token Refresh
+Keep users logged in by rotating access tokens using a valid refresh token.
+```typescript
+app.post("/refresh", async (req, res) => {
+  const { refreshToken } = req.body;
+  
+  // Returns a fresh access token
+  const { accessToken } = await auth.refresh(refreshToken);
+  
+  res.json({ accessToken });
+});
+```
+
+#### Protecting Routes (Middleware)
+```typescript
+app.get("/me", async (req, res) => {
+  const token = req.headers.authorization?.split(" ")[1];
+  
+  // Verify the JWT and get the payload { sub: string, role: string, ... }
+  const payload = await auth.verifyToken(token, "access");
+  
+  if (!payload) return res.status(401).send("Unauthorized");
+  
+  const user = await myAdapter.findUserById(payload.sub);
+  res.json(user);
+});
+```
+
+---
+
+## Security Best Practices
+
+### 1. Password Peppering
+Always use a `pepper` in production. It's a server-side secret added to passwords before hashing. If your database is leaked, the hashes cannot be cracked without this pepper.
+
+### 2. CSRF Protection
+Kroxt provides helpers for the double-submit cookie pattern. Use these if you are storing tokens in cookies.
+
+```typescript
+import { generateCsrfToken, verifyCsrf } from "kroxt/security";
+
+const token = generateCsrfToken();
+const isValid = verifyCsrf(tokenInRequest, tokenInCookie);
+```
+
+### 3. Secure Cookies
+If using cookies, always set these flags:
+- `httpOnly: true` (Prevents XSS)
+- `secure: true` (Requires HTTPS)
+- `sameSite: 'strict'` (Prevents CSRF)
+
+### 4. Rate Limiting
+Implement rate limiting (e.g., `express-rate-limit`) on `/login` and `/register` to block brute-force attempts.
+
+---
+
+## Reference Project
+
+Check out the `kroxt-example` folder or the [GitHub repository](https://github.com/adepoju-oluwatobi/kroxt-example) for a complete **Express + MongoDB** implementation using this library.
+
+## License
+
+MIT

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,7 @@
 {
   "name": "kroxt",
-  "version": "1.0.1",
+  "version": "1.1.2",
+  "license": "MIT",
   "description": "A framework-agnostic modular auth engine",
   "type": "module",
   "main": "./dist-lib/index.js",