kroxt 1.1.1 → 1.1.3

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,210 @@
-# 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`.
+- 🧩 **JWT Customization**: Fully extensible payload with support for custom user fields and `sub` override.
+- 🌍 **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: Define your User
+
+First, define what a User looks like in your system. Kroxt allows any additional fields (like `role`, `schoolId`, etc.) which you can later sign into your JWTs.
+
+```typescript
+export interface MyUser {
+  id: string;
+  email: string;
+  passwordHash: string;
+  role: 'admin' | 'user';
+  schoolId: string;    // Custom field for enterprise/multi-tenant apps
+  oauthProvider?: string; // Support for OAuth (e.g., 'github')
+  oauthId?: string;       // Unique ID from the provider
+  name: string;
+}
+```
+
+### Step 2: The Adapter Pattern
+
+Kroxt doesn't care which database you use. You just need to implement the `AuthAdapter` interface using your model. Here is a complete example using Mongoose:
+
+```typescript
+import type { AuthAdapter } from "kroxt/adapter";
+import { User } from "./models/user.model.js"; // Your Mongoose model
+import type { MyUser } from "./types.js";
+
+export const myAdapter: AuthAdapter<MyUser> = {
+  createUser: async (data) => {
+    const user = await User.create(data);
+    const obj = user.toObject();
+    return { ...obj, id: obj._id.toString() };
+  },
+  findUserByEmail: async (email) => {
+    const user = await User.findOne({ email });
+    if (!user) return null;
+    const obj = user.toObject();
+    return { ...obj, id: obj._id.toString() };
+  },
+  findUserById: async (id) => {
+    const user = await User.findById(id);
+    if (!user) return null;
+    const obj = user.toObject();
+    return { ...obj, id: obj._id.toString() };
+  },
+  linkOAuthAccount: async (userId, provider, providerId) => {
+    await User.findByIdAndUpdate(userId, {
+      oauthProvider: provider,
+      oauthId: providerId
+    });
+  }
+};
+```
+
+### Step 3: 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
+  },
+  jwt: {
+    /**
+     * Optional: Fully customize the JWT payload or add extra fields.
+     */
+    payload: (user, type) => {
+      // Only add extra details to 'access' tokens to keep 'refresh' tokens light.
+      if (type === "access") {
+        return {
+          schoolId: user.schoolId, // Add custom user detail
+          role: user.role,         // Explicitly include role
+        };
+      }
+      return {}; // Refresh tokens stay minimal
+    }
+  }
+});
+```
+
+### Step 4: 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

@@ -9,6 +9,15 @@ export interface CreateAuthOptions {
         refreshExpires?: string | number;
     };
     providers?: Provider[];
+    jwt?: {
+        /**
+         * A callback to add custom fields to the JWT payload.
+         * It receives the user object and the token type ('access' or 'refresh').
+         * Return an object containing the fields to be merged into the payload.
+         * You can also override default fields like 'sub'.
+         */
+        payload?: (user: User<any>, type: "access" | "refresh") => Record<string, any>;
+    };
 }
 export declare function createAuth(options: CreateAuthOptions): {
     signup: (userData: Omit<User<any>, "id">, password?: string) => Promise<{

package/dist-lib/core.js

@@ -10,7 +10,12 @@ export function createAuth(options) {
      * Generates a stateless JWT for a user session
      */
     async function generateToken(user, type = "access") {
-        return new SignJWT({ sub: user.id, role: user.role, type })
+        let payload = { sub: user.id, role: user.role, type };
+        if (options.jwt?.payload) {
+            const customPayload = options.jwt.payload(user, type);
+            payload = { ...payload, ...customPayload };
+        }
+        return new SignJWT(payload)
             .setProtectedHeader({ alg: "HS256" })
             .setIssuedAt()
             .setExpirationTime(type === "access" ? expiration : refreshExpiration)

package/package.json

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