Kroxt: Modular Authentication Engine

Common errors

• Error: JWT_SECRET environment variable is not defined.

  cause The `secret` option passed to `createAuth` is `undefined`, typically because `process.env.JWT_SECRET` is not set in the application's environment.
  fix Ensure the `JWT_SECRET` environment variable is correctly defined and accessible in your application's runtime environment (e.g., `.env` file, server configuration).

• TypeError: Cannot read properties of undefined (reading 'modelName') / Argument of type 'Model<any, {}, {}, {}, Document<unknown, {}, any>, any>' is not assignable to parameter of type 'never'.

  cause The adapter creator (e.g., `createMongoAdapter`, `createPrismaAdapter`) was initialized with an incorrect, uninstantiated, or incompatible ORM/ODM client or model object.
  fix Verify that the argument passed to the adapter creator is the correct, instantiated model or client object for your chosen ORM/ODM (e.g., `mongoose.model('User', UserSchema)` for Mongoose, `prisma.user` for Prisma).

• SyntaxError: Unexpected token 'export' / Must use import to load ES Module

  cause Attempting to use `require()` to import Kroxt modules in a CommonJS context, or if your project is not configured for ES Modules.
  fix Ensure your project's `package.json` includes `"type": "module"` and consistently use `import` statements for Kroxt modules. If strictly in CommonJS, consider transpilation or using dynamic `import()` where supported.

• Error: User with provided email not found.

  cause The `auth.loginWithPassword` method was called with credentials for an email address that does not exist in the database or cannot be retrieved by the configured adapter.
  fix Verify that the user account exists in your database. If it's a new user, ensure they have successfully signed up using `auth.signup()` first. Check for typos in the email address during login.

Warnings

• gotcha Kroxt relies on critical environment variables like `JWT_SECRET` and optionally `JWT_PEPPER` for cryptographic operations. Failing to define these variables or using insecure defaults will result in runtime errors or severe security vulnerabilities.
  Fix: Always define `JWT_SECRET` (and `JWT_PEPPER` if `usePepper` is enabled) as strong, randomly generated strings in your `.env` files for development and secure environment variables for production deployments.
• breaking While not explicitly termed a 'breaking change,' version 1.3.11 marked a significant architectural shift with first-class support for Next.js (App Router) + MongoDB. Existing integrations in other frameworks or older Next.js setups might require adjustments to align with the new recommended patterns, especially if not using the `kroxt init` CLI.
  Fix: For new projects, leverage `npx kroxt init` to scaffold the recommended setup. For existing projects, carefully review the latest documentation for your specific framework/ORM to ensure compatibility and adopt best practices.
• gotcha Enabling `session.enforceStrictRevocation: true` provides real-time session invalidation but incurs a database lookup on every authenticated request. This can significantly impact performance under high traffic loads.
  Fix: Assess your application's security needs versus performance requirements. For high-security contexts (e.g., admin dashboards), `true` is advisable. For general-purpose APIs with high throughput, consider setting it to `false` and relying on shorter token expiry for eventual revocation.
• gotcha Kroxt is a 'headless' authentication engine; it provides the core logic but no pre-built UI components or routes. Developers are responsible for implementing their own user interfaces (login, signup forms) and API endpoints to interact with Kroxt's functionality.
  Fix: Plan to develop your own frontend and backend API routes. Consult the Kroxt CLI and official boilerplates (e.g., `kroxt-nextjs-mongo`) for examples on how to structure your application and interact with the `auth` instance.

Install

• npm install kroxt npm
• yarn add kroxt yarn
• pnpm add kroxt pnpm

Imports

• createAuth
  wrong:

  const { createAuth } = require('kroxt');

  correct:

  import { createAuth } from 'kroxt';

  Kroxt is designed primarily for ES Modules. CommonJS `require` syntax is generally not supported for its main exports.
• createMongoAdapter
  wrong:

  import { createMongoAdapter } from 'kroxt';

  correct:

  import { createMongoAdapter } from 'kroxt/adapters/mongoose';

  Adapter creators are located in specific subpaths (e.g., `kroxt/adapters/mongoose`). Ensure the corresponding ORM/ODM library (e.g., `mongoose`) is installed as a peer dependency in your project.
• auth

  import { auth } from '@/lib/kroxt/auth';

  This refers to the `auth` instance you create and export within your application (e.g., `export const auth = createAuth(...)`). The path shown is common in Next.js projects using path aliases.

Quickstart

This quickstart demonstrates how to initialize the Kroxt authentication engine with a Mongoose adapter and implement a basic login route handler using the Next.js App Router, including crucial environment variable handling and a mock User model for immediate testing.

import { createAuth } from "kroxt";
import { createMongoAdapter } from "kroxt/adapters/mongoose";
import { NextRequest, NextResponse } from "next/server";

// IMPORTANT: Replace this mock with your actual Mongoose User model.
// Example: import { Schema, model } from 'mongoose';
// const UserSchema = new Schema({ email: { type: String, unique: true }, password: String, /* ... */ });
// export const User = model('User', UserSchema);
const User = {
  modelName: 'MockUser',
  findOne: async (query: any) => {
    // Simulate finding a user by email for login
    if (query.email === 'test@example.com') return { email: 'test@example.com', password: 'hashedpassword' };
    return null;
  },
  create: async (data: any) => ({
    // Simulate user creation
    _id: 'mockid123',
    ...data
  })
}; // This mock makes the example runnable without a full Mongoose setup.

// 1. Initialize Kroxt authentication engine (e.g., in `lib/kroxt/auth.ts`)
export const auth = createAuth({
  adapter: createMongoAdapter(User),
  secret: process.env.JWT_SECRET ?? 'super-secret-change-me-in-production',
  session: { 
    expires: '15m',
    refreshExpires: '7d',
    enforceStrictRevocation: true 
  },
  passwordPolicy: {
    minLength: 8,
    requireUppercase: true,
    requireSpecialCharacter: true,
    usePepper: false // Set to true if you define process.env.JWT_PEPPER
  }
});

// 2. Example Login Route Handler for Next.js App Router (e.g., `app/api/auth/login/route.ts`)
export async function POST(req: NextRequest) {
  try {
    const { email, password } = await req.json();
    // `req.ip` might be `undefined` in development or certain environments; provide a fallback.
    const result = await auth.loginWithPassword(email, password, req.ip ?? 'unknown');
    
    // In a real application, you might set cookies or return specific tokens.
    return NextResponse.json(result, { status: 200 });
  } catch (error: any) {
    // Log the error internally but provide a generic message to the client for security.
    console.error('Login attempt failed:', error.message);
    return NextResponse.json({ error: error.message || 'Authentication failed' }, { status: 401 });
  }
}