Registry / auth-security / kroxt
library1.3.11jsnpmunverified

Kroxt is a premium, framework-agnostic, and security-hardened authentication engine designed for modern TypeScript environments, currently at stable version 1.3.11. It provides core authentication logic (hashing, JWTs, session management, security features) while allowing developers to implement their own UI and routes, making it 'headless'. Recent releases, particularly v1.3.11, emphasize first-class support for Next.js (App Router) + MongoDB, offering comprehensive tooling and a production-ready developer experience. It maintains modularity through configurable security layers (sessions, rate limiting, IP blocking, password policies) and universal adapters for various ORMs/ODMs like Mongoose, Prisma, and Drizzle. Kroxt differentiates itself with its 'Zero-Config' CLI for quick setup, 100% schema control, and robust security features like real-time session revocation and advanced brute-force protection, adhering to a consistent, active release cadence.

npm install kroxt
INSTALL
IMPORT
SIG · KROXT
K
kroxt
auth-securityjavascriptv1.3.11
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

createAuth
import { createAuth } from 'kroxt';
const { createAuth } = require('kroxt');
Kroxt is designed primarily for ES Modules. CommonJS `require` syntax is generally not supported for its main exports.
createMongoAdapter
import { createMongoAdapter } from 'kroxt/adapters/mongoose';
import { createMongoAdapter } from 'kroxt';
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.

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 }); } }
kroxt --version
Debug
Known issues
gotchaKroxt 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.
affects: >=1.0.0
breakingWhile 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.
affects: >=1.3.11
gotchaEnabling `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.
affects: >=1.0.0
gotchaKroxt 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.
affects: >=1.0.0
Errors
Common errors & fixes
Error: JWT_SECRET environment variable is not defined.
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'.
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
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.
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.
Upgrade
Version history
1.3.11latest on npm
Audit
Dependencies
mongooseoptionalRequired for the `kroxt/adapters/mongoose` adapter to interact with MongoDB.
@prisma/clientoptionalRequired for the `kroxt/adapters/prisma` adapter to interact with SQL databases via Prisma.
drizzle-ormoptionalRequired for the `kroxt/adapters/drizzle` adapter to interact with SQL databases via Drizzle.
Agent activity
9 hits · last 30 days
node
8
OpenAI (training)
1
Resources
kroxt — npm install kroxt · libregistry