🔐 Auth Engine

A flexible, database-agnostic authentication library for Express that removes repetitive auth logic while letting developers fully control their User model and database.

No mongoose ownership. No schema lock-in. Plug in your own User model and go.

✨ Features

• ✅ Signup, Login, Logout
• ✅ Get current user (/me)
• ✅ Update user (fully configurable)
• ✅ Delete user
• ✅ JWT-based authentication
• ✅ HTTP-only cookies
• ✅ Zero database coupling
• ✅ Highly configurable & secure defaults

📦 Installation

npm install auth-engine

🧠 Core Philosophy

This library does not own your database or schema.

You provide:

• Your own User model
• Your own DB connection (MongoDB, Prisma, TypeORM, etc.)

The library provides:

• Authentication logic
• Token & cookie handling
• Secure, reusable controllers

📋 UserModel Contract (IMPORTANT)

Your UserModel must support the following methods:

UserModel.create(data)
UserModel.findOne(query)
UserModel.findById(id)
UserModel.findByIdAndUpdate(id, data, options)
UserModel.findByIdAndDelete(id)

Password Requirement

• User model must contain a password field
• Password should be selectable during login

Example (Mongoose):

password: { type: String, select: false }

⚙️ Initialization

You must initialize the library once before using any controller.

import { authConfig } from "auth-engine";
import User from "./models/User.js";

authConfig({
  UserModel: User,
  jwtSecret: process.env.JWT_SECRET,
  jwtExpiry: "7d",            // optional
  cookieName: "token",        // optional
  cookieOptions: {             // optional
    sameSite: "strict",
  },
});

🧩 Controllers & Middleware

Import

import {
  signup,
  login,
  logout,
  getMe,
  updateUser,
  deleteUser,
  protect,
} from "auth-engine";

🛣️ Example Routes Setup

import express from "express";
import cookieParser from "cookie-parser";

const app = express();
app.use(express.json());
app.use(cookieParser());

const router = express.Router();

router.post(
  "/signup",
  signup({
    required: ["email", "password"],
    unique: ["email"],
    allowed: ["name"],
  })
);

router.post("/login", login());
router.post("/logout", logout());

router.get("/me", protect(), getMe());

router.put(
  "/update",
  protect(),
  updateUser({
    allowed: ["name", "avatar"],
  })
);

router.delete("/delete", protect(), deleteUser());

app.use("/auth", router);

📝 Controller Options

🔹 signup(options)

signup({
  required: string[], // required fields
  unique: string[],   // must be unique
  allowed: string[],  // optional fields
});

🔹 login(options)

login({
  loginWith: "email",       // field used for login
  passwordField: "password" // password field name
});

🔹 getMe(options)

getMe({
  fields: ["name", "email"] // fields to return
});

If omitted, defaults to:

-password -__v

🔹 updateUser(options)

updateUser({
  allowed: ["name", "email"],
  allowPasswordUpdate: false,
  reIssueToken: false,
});

| Option | Description | | --------------------- | ------------------------ | | allowed | Fields user can update | | allowPasswordUpdate | Allow password changes | | reIssueToken | Refresh JWT after update |

🔹 deleteUser()

Deletes the currently authenticated user only.

🔹 protect()

Authentication middleware.

• Reads token from:

  • HTTP-only cookie
  • Authorization: Bearer <token> header

Adds:

req.userId

🔐 Security Defaults

• HTTP-only cookies
• Secure cookies in production
• SameSite protection
• Password hashing using bcrypt
• JWT expiration enforced

❌ What This Library Does NOT Do

• ❌ Create database connections
• ❌ Define schemas
• ❌ Handle roles/permissions
• ❌ Send emails

(You stay in control.)

🧪 Supported Databases

Works with any database layer that satisfies the UserModel contract:

• MongoDB (Mongoose)
• Prisma
• TypeORM
• Sequelize
• Custom adapters

🚀 Why Use Auth Engine?

• Stop rewriting auth logic
• Full schema freedom
• Production-safe defaults
• Hackathon & startup friendly
• Clean, documented API

📄 License

MIT

❤️ Final Note

This library is designed to be invisible — it should feel like part of your app, not a limitation.

If you need refresh tokens, OAuth, roles, or adapters — build on top of this foundation.

Happy shipping 🚀