kroxt 1.0.0

package/README.md

@@ -0,0 +1,82 @@
+# 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

package/dist-lib/adapter.d.ts

@@ -0,0 +1,13 @@
+export interface BaseUser {
+    id: string;
+    email: string;
+    passwordHash?: string;
+    role?: string;
+}
+export type User<TExtended = Record<string, any>> = BaseUser & TExtended;
+export interface AuthAdapter<TUser = User> {
+    createUser: (data: any) => Promise<TUser>;
+    findUserByEmail: (email: string) => Promise<TUser | null>;
+    findUserById: (id: string) => Promise<TUser | null>;
+    linkOAuthAccount: (userId: string, provider: string, providerId: string) => Promise<void>;
+}

package/dist-lib/adapter.js

@@ -0,0 +1 @@
+export {};

package/dist-lib/core.d.ts

@@ -0,0 +1,23 @@
+import type { AuthAdapter, User } from "./adapter.js";
+import type { Provider } from "./providers.js";
+export interface CreateAuthOptions {
+    adapter: AuthAdapter<any>;
+    secret: string;
+    session?: {
+        expires?: string | number;
+    };
+    providers?: Provider[];
+}
+export declare function createAuth(options: CreateAuthOptions): {
+    signup: (userData: Omit<User<any>, "id">, password?: string) => Promise<{
+        user: any;
+        token: string;
+    }>;
+    loginWithPassword: (email: string, password: string) => Promise<{
+        user: any;
+        token: string;
+    }>;
+    verifyToken: (token: string) => Promise<import("jose").JWTPayload>;
+    generateToken: (user: User<any>) => Promise<string>;
+    _providers: Provider[];
+};

package/dist-lib/core.js

@@ -0,0 +1,67 @@
+import * as argon2 from "argon2";
+import { SignJWT, jwtVerify } from "jose";
+export function createAuth(options) {
+    const { adapter, secret, session, providers } = options;
+    const encodedSecret = new TextEncoder().encode(secret);
+    const expiration = session?.expires || "7d";
+    /**
+     * Generates a stateless JWT for a user session
+     */
+    async function generateToken(user) {
+        return new SignJWT({ sub: user.id, role: user.role })
+            .setProtectedHeader({ alg: "HS256" })
+            .setIssuedAt()
+            .setExpirationTime(expiration)
+            .sign(encodedSecret);
+    }
+    /**
+     * Verifies a JWT and returns the payload
+     */
+    async function verifyToken(token) {
+        try {
+            const { payload } = await jwtVerify(token, encodedSecret);
+            return payload;
+        }
+        catch (e) {
+            return null;
+        }
+    }
+    /**
+     * Signup with a new user payload (handles extended schemas out-of-the-box).
+     * Generates a password hash if password is provided.
+     */
+    async function signup(userData, password) {
+        let dataToSave = { ...userData };
+        if (password) {
+            dataToSave.passwordHash = await argon2.hash(password);
+        }
+        const newUser = await adapter.createUser(dataToSave);
+        const token = await generateToken(newUser);
+        return { user: newUser, token };
+    }
+    /**
+     * Standard Email/Password Login
+     */
+    async function loginWithPassword(email, password) {
+        const user = await adapter.findUserByEmail(email);
+        if (!user) {
+            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 };
+    }
+    return {
+        signup,
+        loginWithPassword,
+        verifyToken,
+        generateToken,
+        _providers: providers // Exposing to internal router mechanisms if needed
+    };
+}

package/dist-lib/index.d.ts

@@ -0,0 +1,6 @@
+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 type { CreateAuthOptions } from "./core.js";
+export { createMemoryAdapter } from "./memoryAdapter.js";

package/dist-lib/index.js

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

package/dist-lib/memoryAdapter.d.ts

@@ -0,0 +1,7 @@
+import type { AuthAdapter, User } from "./adapter.js";
+/**
+ * Creates an in-memory database adapter for the auth engine.
+ * This is useful for testing, prototyping, or when you don't need persistent storage.
+ * All data is kept in memory and is lost when the server restarts.
+ */
+export declare function createMemoryAdapter<TUser extends User = User>(): AuthAdapter<TUser>;

package/dist-lib/memoryAdapter.js

@@ -0,0 +1,34 @@
+/**
+ * Creates an in-memory database adapter for the auth engine.
+ * This is useful for testing, prototyping, or when you don't need persistent storage.
+ * All data is kept in memory and is lost when the server restarts.
+ */
+export function createMemoryAdapter() {
+    const users = new Map();
+    const accounts = new Map();
+    return {
+        createUser: async (data) => {
+            // Auto-generate ID if not provided
+            const id = data.id || Date.now().toString();
+            const newUser = { ...data, id };
+            // Store using email as the primary lookup key
+            users.set(newUser.email, newUser);
+            return newUser;
+        },
+        findUserByEmail: async (email) => {
+            return users.get(email) || null;
+        },
+        findUserById: async (id) => {
+            for (const user of users.values()) {
+                if (user.id === id) {
+                    return user;
+                }
+            }
+            return null;
+        },
+        linkOAuthAccount: async (userId, provider, providerId) => {
+            const accountId = `${provider}_${providerId}`;
+            accounts.set(accountId, { userId, provider, providerId });
+        }
+    };
+}

package/dist-lib/providers.d.ts

@@ -0,0 +1,11 @@
+export interface ProviderConfig {
+    clientId: string;
+    clientSecret: string;
+    redirectURI?: string;
+}
+export interface Provider {
+    id: string;
+    handler: any;
+}
+export declare function GitHub(config: ProviderConfig): Provider;
+export declare function Google(config: ProviderConfig): Provider;

package/dist-lib/providers.js

@@ -0,0 +1,16 @@
+import { GitHub as ArcticGitHub, Google as ArcticGoogle } from "arctic";
+export function GitHub(config) {
+    return {
+        id: "github",
+        handler: new ArcticGitHub(config.clientId, config.clientSecret, null),
+    };
+}
+export function Google(config) {
+    if (!config.redirectURI) {
+        throw new Error("redirectURI is required for Google OAuth provider");
+    }
+    return {
+        id: "google",
+        handler: new ArcticGoogle(config.clientId, config.clientSecret, config.redirectURI),
+    };
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "kroxt",
+  "version": "1.0.0",
+  "description": "A framework-agnostic modular auth engine",
+  "type": "module",
+  "main": "./dist-lib/index.js",
+  "module": "./dist-lib/index.js",
+  "types": "./dist-lib/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist-lib/index.js",
+      "types": "./dist-lib/index.d.ts"
+    },
+    "./adapter": {
+      "import": "./dist-lib/adapter.js",
+      "types": "./dist-lib/adapter.d.ts"
+    },
+    "./core": {
+      "import": "./dist-lib/core.js",
+      "types": "./dist-lib/core.d.ts"
+    },
+    "./providers": {
+      "import": "./dist-lib/providers.js",
+      "types": "./dist-lib/providers.d.ts"
+    },
+    "./memoryAdapter": {
+      "import": "./dist-lib/memoryAdapter.js",
+      "types": "./dist-lib/memoryAdapter.d.ts"
+    }
+  },
+  "files": [
+    "dist-lib",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "npx tsc src/auth/index.ts --outDir dist-lib --module nodenext --declaration"
+  },
+  "dependencies": {
+    "arctic": "^3.7.0",
+    "argon2": "^0.44.0",
+    "jose": "^6.2.1",
+    "zod": "^3.23.8"
+  }
+}