node-auth-kit 1.0.2

package/LICENSE

@@ -0,0 +1,5 @@
+MIT License
+
+Copyright (c) 2025 Yogendra Prajapati
+
+Permission is hereby granted, free of charge, to any person obtaining a copy...

package/README.md

@@ -0,0 +1,335 @@
+🔐 # Device Auth
+
+Device Auth is a **Devise-inspired authentication and authorization library for Node.js**.
+
+It gives you:
+
+- **Config-driven auth** (email + password, roles, JWT, password rules)
+- **Plug-and-play Express routes** via `createAuthRouter`
+- **JWT-based security** with `authenticate` middleware
+- **Role-based authorization** with `authorize`
+- **Database-agnostic adapter system** (`mongooseAdapter`, future Prisma, etc.)
+- **Lifecycle hooks** (before/after register/login) for side effects
+
+You bring your framework (Express) and database (Mongo, Prisma, SQL). Device Auth handles the rest.
+
+---
+
+## ✨ Features
+
+- **✅ JWT Authentication (Access Tokens)**
+- **🔑 Role-based Authorization**
+- **🧩 Adapter Pattern (DB-agnostic)**
+- **🚀 Ready-to-use Express routes** via `createAuthRouter`
+- **🔒 Secure password hashing**
+- **📦 Mongoose adapter (Stable)**
+- **🧪 Prisma adapter (In progress – V2)**
+- **🧠 Inspired by Ruby on Rails Devise**
+
+---
+
+## 📦 Installation
+
+```bash
+npm install device_auth
+```
+
+or
+
+```bash
+yarn add device_auth
+```
+
+`device_auth` itself is DB-agnostic. Database drivers / ORMs are **optional** and only required if you use the corresponding adapter:
+
+- For Mongoose adapter: `mongoose`
+- For Prisma adapter (V2): `@prisma/client`
+
+---
+
+## ⚡ Quick Start (Express + MongoDB)
+
+### 1️⃣ Environment Variables
+
+Create a `.env` file:
+
+```env
+MONGO_URL=mongodb://localhost:27017/device-auth
+DEVICE_AUTH_JWT_SECRET=your-super-secret-key
+```
+
+### 2️⃣ User Model (Mongoose)
+
+```ts
+import mongoose from 'mongoose';
+
+const UserSchema = new mongoose.Schema({
+  email: {
+    type: String,
+    unique: true,
+    required: true,
+  },
+  password: {
+    type: String,
+    required: true,
+  },
+  role: {
+    type: String,
+    enum: ['admin', 'staff', 'user'],
+    default: 'user',
+  },
+  createdAt: {
+    type: Date,
+    default: Date.now,
+  },
+});
+
+export const User = mongoose.model('User', UserSchema);
+```
+
+### 3️⃣ Express App Setup
+
+```ts
+import 'dotenv/config';
+import express from 'express';
+import mongoose from 'mongoose';
+
+import {
+  deviceAuth,
+  mongooseAdapter,
+  createAuthRouter,
+  authenticate,
+  authorize,
+} from 'node-auth-kit';
+
+import { User } from './models/User';
+
+const app = express();
+app.use(express.json());
+
+// 1. Connect MongoDB
+mongoose
+  .connect(process.env.MONGO_URL)
+  .then(() => console.log('MongoDB connected'))
+  .catch(console.error);
+
+// 2. Initialize Device Auth
+deviceAuth
+  .init({
+    authType: 'jwt',
+    signupFields: ['email', 'password'],
+    defaultRole: 'user',
+    password: {
+      minLength: 8,
+      requireNumbers: true,
+      requireSpecialChars: true,
+      saltRounds: 10,
+    },
+    token: {
+      accessTokenTtl: '15m',
+    },
+  })
+  .useAdapter(
+    mongooseAdapter({
+      userModel: User,
+    }),
+  );
+
+// 3. Mount Auth Routes
+app.use('/auth', createAuthRouter());
+
+// 4. Example Protected Route
+app.get(
+  '/admin',
+  authenticate,
+  authorize('admin'),
+  (req, res) => {
+    res.json({ message: 'Admin access granted' });
+  },
+);
+
+app.listen(3000, () => {
+  console.log('Server running on http://localhost:3000');
+});
+```
+
+---
+
+## 🔁 Authentication Routes
+
+The default router created by `createAuthRouter()` exposes:
+
+| Method | Endpoint      | Description        |
+| ------ | ------------- | ------------------ |
+| POST   | `/auth/register` | Register new user |
+| POST   | `/auth/login` | Login user         |
+| GET    | `/auth/me`    | Get current user   |
+
+You can mount it under any base path (e.g. `/api/auth`).
+
+```ts
+app.use('/auth', createAuthRouter());
+```
+
+---
+
+## 🔐 Middleware
+
+### `authenticate`
+
+Validates the JWT from the `Authorization: Bearer <token>` header and attaches the user to `req.user`.
+
+```ts
+app.get('/profile', authenticate, (req, res) => {
+  res.json(req.user);
+});
+```
+
+### `authorize(...roles)`
+
+Restricts access based on user role.
+
+```ts
+app.get('/admin', authenticate, authorize('admin', 'staff'), (req, res) => {
+  res.json({ message: 'Admin or staff only' });
+});
+```
+
+---
+
+## 🧩 Adapter System
+
+Device Auth uses a **pluggable adapter architecture**, allowing it to work with different databases without changing core logic.
+
+Supported / planned adapters:
+
+| Adapter  | Status                     |
+| -------- | -------------------------- |
+| Mongoose | ✅ Stable                  |
+| Prisma   | 🚧 In Progress (V2)        |
+| TypeORM  | ❌ Planned                 |
+
+The public exports you can use:
+
+- `mongooseAdapter` – helper for MongoDB via Mongoose
+- `MongooseAdapter` – underlying class (advanced use)
+
+---
+
+## ⚙️ Configuration
+
+The central entry point is `deviceAuth`:
+
+```ts
+import { deviceAuth, defaultConfig } from 'device_auth';
+
+deviceAuth.init({
+  ...defaultConfig,
+  authType: 'jwt',
+  defaultRole: 'user',
+  signupFields: ['email', 'password'],
+  // override anything you need
+});
+```
+
+Key options:
+
+- **`authType`**: currently `jwt`
+- **`signupFields`**: required fields on registration
+- **`defaultRole`**: assigned when no role is provided
+- **`password`**:
+  - `minLength`
+  - `requireNumbers`
+  - `requireSpecialChars`
+  - `saltRounds`
+- **`token`**:
+  - `accessTokenTtl` (e.g. `15m`, `1h`)
+
+The merged configuration is accessible via:
+
+```ts
+const config = deviceAuth.config;
+```
+
+---
+
+## 🧠 Hooks
+
+Hooks let you run side effects around key lifecycle events without forking core logic.
+
+Supported hook names:
+
+- `beforeRegister`
+- `afterRegister`
+- `beforeLogin`
+- `afterLogin`
+
+Register hooks on `deviceAuth`:
+
+```ts
+import { deviceAuth } from 'device_auth';
+
+deviceAuth
+  .registerHook('beforeRegister', async (createData) => {
+    // e.g. validate extra fields, audit, etc.
+  })
+  .registerHook('afterRegister', async (user) => {
+    // e.g. send welcome email
+  })
+  .registerHook('beforeLogin', async (user) => {
+    // e.g. check if user is blocked
+  })
+  .registerHook('afterLogin', async (user) => {
+    // e.g. log login event
+  });
+```
+
+Hook errors are intentionally swallowed so they **never break core auth flow**.
+
+---
+
+## 🛣️ Roadmap (V2)
+
+Planned for upcoming versions:
+
+- 🔁 Refresh tokens
+- 📱 Multi-device sessions
+- 🚪 Logout (single device / all devices)
+- 📧 Forgot & reset password
+- ✅ Email verification
+- 🧪 Stable Prisma adapter
+- 🧠 Additional hooks & lifecycle events
+
+---
+
+## 🧪 Testing
+
+```bash
+npm test
+```
+
+Postman collection – _coming soon_.
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome!
+
+1. **Fork** the repository
+2. **Create** a new branch
+
+   ```bash
+   git checkout -b feature/my-feature
+   ```
+
+3. **Commit** your changes
+4. **Push** to your branch
+5. **Open** a Pull Request
+
+---
+
+## 📄 License
+
+MIT License © 2025
+

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export { deviceAuth } from './src/deviceAuth';
+export type { DeviceAuthConfig } from './src/config';
+export { defaultConfig } from './src/config';
+export { applyControllerOverrides } from './src/overrides';
+export type { User, Role, Adapter, Config } from './src/types';
+export { pick } from './src/utils';
+export type { ResponseLike } from './src/utils';
+export { sendJson, sendError, badRequest, unauthorized, forbidden, internalError, } from './src/utils';
+export { MongooseAdapter, mongooseAdapter } from './src/adapters/mongoose.adapter';
+export type { MongooseAdapterOptions } from './src/adapters/mongoose.adapter';
+export { createAuthRouter } from './src/routes/auth.routes';
+export { authenticate } from './src/middlewares/authenticate.middleware';
+export { authorize } from './src/middlewares/authorize.middleware';

package/dist/index.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.authorize = exports.authenticate = exports.createAuthRouter = exports.mongooseAdapter = exports.MongooseAdapter = exports.internalError = exports.forbidden = exports.unauthorized = exports.badRequest = exports.sendError = exports.sendJson = exports.pick = exports.applyControllerOverrides = exports.defaultConfig = exports.deviceAuth = void 0;
+var deviceAuth_1 = require("./src/deviceAuth");
+Object.defineProperty(exports, "deviceAuth", { enumerable: true, get: function () { return deviceAuth_1.deviceAuth; } });
+var config_1 = require("./src/config");
+Object.defineProperty(exports, "defaultConfig", { enumerable: true, get: function () { return config_1.defaultConfig; } });
+var overrides_1 = require("./src/overrides");
+Object.defineProperty(exports, "applyControllerOverrides", { enumerable: true, get: function () { return overrides_1.applyControllerOverrides; } });
+var utils_1 = require("./src/utils");
+Object.defineProperty(exports, "pick", { enumerable: true, get: function () { return utils_1.pick; } });
+var utils_2 = require("./src/utils");
+Object.defineProperty(exports, "sendJson", { enumerable: true, get: function () { return utils_2.sendJson; } });
+Object.defineProperty(exports, "sendError", { enumerable: true, get: function () { return utils_2.sendError; } });
+Object.defineProperty(exports, "badRequest", { enumerable: true, get: function () { return utils_2.badRequest; } });
+Object.defineProperty(exports, "unauthorized", { enumerable: true, get: function () { return utils_2.unauthorized; } });
+Object.defineProperty(exports, "forbidden", { enumerable: true, get: function () { return utils_2.forbidden; } });
+Object.defineProperty(exports, "internalError", { enumerable: true, get: function () { return utils_2.internalError; } });
+var mongoose_adapter_1 = require("./src/adapters/mongoose.adapter");
+Object.defineProperty(exports, "MongooseAdapter", { enumerable: true, get: function () { return mongoose_adapter_1.MongooseAdapter; } });
+Object.defineProperty(exports, "mongooseAdapter", { enumerable: true, get: function () { return mongoose_adapter_1.mongooseAdapter; } });
+var auth_routes_1 = require("./src/routes/auth.routes");
+Object.defineProperty(exports, "createAuthRouter", { enumerable: true, get: function () { return auth_routes_1.createAuthRouter; } });
+var authenticate_middleware_1 = require("./src/middlewares/authenticate.middleware");
+Object.defineProperty(exports, "authenticate", { enumerable: true, get: function () { return authenticate_middleware_1.authenticate; } });
+var authorize_middleware_1 = require("./src/middlewares/authorize.middleware");
+Object.defineProperty(exports, "authorize", { enumerable: true, get: function () { return authorize_middleware_1.authorize; } });

package/dist/src/adapters/base.adapter.d.ts

@@ -0,0 +1,21 @@
+export type AdapterUser = Record<string, unknown>;
+export type CreateUserData = Record<string, unknown>;
+export type UpdateUserData = Record<string, unknown>;
+/**
+ * Base database adapter contract for device_auth.
+ *
+ * This interface is intentionally DB-agnostic and contains no ORM types
+ * or database-specific logic. Concrete adapters (Prisma, Mongoose, SQL, etc.)
+ * must implement this contract so that device_auth can talk to any backend
+ * in a uniform way.
+ */
+export interface BaseAdapter {
+    /** Create a new user record. */
+    createUser(data: CreateUserData): Promise<AdapterUser>;
+    /** Look up a user by email, or return null if not found. */
+    findUserByEmail(email: string): Promise<AdapterUser | null>;
+    /** Look up a user by primary identifier, or return null if not found. */
+    findUserById(id: string | number): Promise<AdapterUser | null>;
+    /** Update an existing user and return the updated record. */
+    updateUser(id: string | number, data: UpdateUserData): Promise<AdapterUser>;
+}

package/dist/src/adapters/base.adapter.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/src/adapters/mongoose.adapter.d.ts

@@ -0,0 +1,53 @@
+import type { AdapterUser, BaseAdapter, CreateUserData, UpdateUserData } from './base.adapter';
+interface MinimalMongooseModel<T = unknown> {
+    create(data: Record<string, unknown>): Promise<T>;
+    findOne(filter: Record<string, unknown>): {
+        exec(): Promise<T | null>;
+    };
+    findById(id: unknown): {
+        exec(): Promise<T | null>;
+    };
+    findByIdAndUpdate(id: unknown, data: Record<string, unknown>, options: {
+        new: boolean;
+    }): {
+        exec(): Promise<T | null>;
+    };
+    findOneAndUpdate(filter: Record<string, unknown>, data: Record<string, unknown>, options: {
+        new: boolean;
+    }): {
+        exec(): Promise<T | null>;
+    };
+}
+export interface MongooseAdapterOptions {
+    userModel: MinimalMongooseModel;
+    idField?: string;
+    emailField?: string;
+}
+export declare class MongooseAdapter implements BaseAdapter {
+    private readonly userModel;
+    private readonly idField;
+    private readonly emailField;
+    constructor(options: MongooseAdapterOptions);
+    createUser(data: CreateUserData): Promise<AdapterUser>;
+    findUserByEmail(email: string): Promise<AdapterUser | null>;
+    findUserById(id: string | number): Promise<AdapterUser | null>;
+    updateUser(id: string | number, data: UpdateUserData): Promise<AdapterUser>;
+    private normalize;
+}
+/**
+ * Mongoose adapter factory.
+ *
+ * You can use either the class-based style:
+ *
+ * ```ts
+ * adapter: new MongooseAdapter({ userModel: User });
+ * ```
+ *
+ * or the function-based style (recommended):
+ *
+ * ```ts
+ * adapter: mongooseAdapter({ userModel: User });
+ * ```
+ */
+export declare function mongooseAdapter(options: MongooseAdapterOptions): BaseAdapter;
+export {};

package/dist/src/adapters/mongoose.adapter.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MongooseAdapter = void 0;
+exports.mongooseAdapter = mongooseAdapter;
+class MongooseAdapter {
+    constructor(options) {
+        this.userModel = options.userModel;
+        this.idField = options.idField ?? '_id';
+        this.emailField = options.emailField ?? 'email';
+    }
+    async createUser(data) {
+        const doc = await this.userModel.create(data);
+        return this.normalize(doc);
+    }
+    async findUserByEmail(email) {
+        const doc = await this.userModel.findOne({ [this.emailField]: email }).exec();
+        if (!doc)
+            return null;
+        return this.normalize(doc);
+    }
+    async findUserById(id) {
+        let doc;
+        if (this.idField === '_id') {
+            doc = await this.userModel.findById(id).exec();
+        }
+        else {
+            doc = await this.userModel.findOne({ [this.idField]: id }).exec();
+        }
+        if (!doc)
+            return null;
+        return this.normalize(doc);
+    }
+    async updateUser(id, data) {
+        let doc;
+        if (this.idField === '_id') {
+            doc = await this.userModel.findByIdAndUpdate(id, data, { new: true }).exec();
+        }
+        else {
+            doc = await this.userModel
+                .findOneAndUpdate({ [this.idField]: id }, data, { new: true })
+                .exec();
+        }
+        if (!doc) {
+            throw new Error('User not found');
+        }
+        return this.normalize(doc);
+    }
+    normalize(doc) {
+        const obj = typeof doc.toObject === 'function' ? doc.toObject() : { ...doc };
+        const adapterUser = { ...obj };
+        const rawId = obj[this.idField];
+        if (rawId != null) {
+            // Expose a normalized id field expected by core
+            adapterUser['id'] =
+                typeof rawId === 'string' || typeof rawId === 'number' ? rawId : String(rawId);
+        }
+        return adapterUser;
+    }
+}
+exports.MongooseAdapter = MongooseAdapter;
+/**
+ * Mongoose adapter factory.
+ *
+ * You can use either the class-based style:
+ *
+ * ```ts
+ * adapter: new MongooseAdapter({ userModel: User });
+ * ```
+ *
+ * or the function-based style (recommended):
+ *
+ * ```ts
+ * adapter: mongooseAdapter({ userModel: User });
+ * ```
+ */
+function mongooseAdapter(options) {
+    return new MongooseAdapter(options);
+}

package/dist/src/adapters/prisma.adapter.d.ts

@@ -0,0 +1,29 @@
+import type { AdapterUser, BaseAdapter, CreateUserData, UpdateUserData } from './base.adapter';
+export interface PrismaDelegate<TUser> {
+    create(args: {
+        data: Record<string, unknown>;
+    }): Promise<TUser>;
+    findUnique(args: {
+        where: Record<string, unknown>;
+    }): Promise<TUser | null>;
+    update(args: {
+        where: Record<string, unknown>;
+        data: Record<string, unknown>;
+    }): Promise<TUser>;
+}
+export interface PrismaAdapterOptions<TUser extends Record<string, unknown>> {
+    userDelegate: PrismaDelegate<TUser>;
+    idField?: string;
+    emailField?: string;
+}
+export declare class PrismaAdapter<TUser extends Record<string, unknown>> implements BaseAdapter {
+    private readonly userDelegate;
+    private readonly idField;
+    private readonly emailField;
+    constructor(options: PrismaAdapterOptions<TUser>);
+    createUser(data: CreateUserData): Promise<AdapterUser>;
+    findUserByEmail(email: string): Promise<AdapterUser | null>;
+    findUserById(id: string | number): Promise<AdapterUser | null>;
+    updateUser(id: string | number, data: UpdateUserData): Promise<AdapterUser>;
+    private normalize;
+}

package/dist/src/adapters/prisma.adapter.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PrismaAdapter = void 0;
+class PrismaAdapter {
+    constructor(options) {
+        this.userDelegate = options.userDelegate;
+        this.idField = options.idField ?? 'id';
+        this.emailField = options.emailField ?? 'email';
+    }
+    async createUser(data) {
+        const user = await this.userDelegate.create({ data });
+        return this.normalize(user);
+    }
+    async findUserByEmail(email) {
+        const user = await this.userDelegate.findUnique({ where: { [this.emailField]: email } });
+        if (!user)
+            return null;
+        return this.normalize(user);
+    }
+    async findUserById(id) {
+        const user = await this.userDelegate.findUnique({ where: { [this.idField]: id } });
+        if (!user)
+            return null;
+        return this.normalize(user);
+    }
+    async updateUser(id, data) {
+        const user = await this.userDelegate.update({ where: { [this.idField]: id }, data });
+        return this.normalize(user);
+    }
+    normalize(user) {
+        const adapterUser = { ...user };
+        const rawId = user[this.idField];
+        if (rawId != null) {
+            adapterUser['id'] =
+                typeof rawId === 'string' || typeof rawId === 'number' ? rawId : String(rawId);
+        }
+        return adapterUser;
+    }
+}
+exports.PrismaAdapter = PrismaAdapter;

package/dist/src/config/default.config.d.ts

@@ -0,0 +1,19 @@
+export type AuthType = 'jwt' | 'session';
+export interface PasswordRulesConfig {
+    minLength: number;
+    requireNumbers: boolean;
+    requireSpecialChars: boolean;
+    saltRounds: number;
+}
+export interface TokenConfig {
+    /** e.g. '15m', '1h' */
+    accessTokenTtl: string;
+}
+export interface DeviceAuthConfig {
+    signupFields: string[];
+    defaultRole: string;
+    authType: AuthType;
+    password: PasswordRulesConfig;
+    token: TokenConfig;
+}
+export declare const defaultConfig: DeviceAuthConfig;

package/dist/src/config/default.config.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultConfig = void 0;
+exports.defaultConfig = {
+    signupFields: ['email', 'password'],
+    defaultRole: 'user',
+    authType: 'jwt',
+    password: {
+        minLength: 8,
+        requireNumbers: true,
+        requireSpecialChars: false,
+        saltRounds: 10,
+    },
+    token: {
+        accessTokenTtl: '15m',
+    },
+};

package/dist/src/config/index.d.ts

@@ -0,0 +1,4 @@
+import { defaultConfig, type DeviceAuthConfig } from './default.config';
+export declare const mergeConfig: (userConfig?: Partial<DeviceAuthConfig>) => DeviceAuthConfig;
+export type { DeviceAuthConfig };
+export { defaultConfig };

package/dist/src/config/index.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultConfig = exports.mergeConfig = void 0;
+const default_config_1 = require("./default.config");
+Object.defineProperty(exports, "defaultConfig", { enumerable: true, get: function () { return default_config_1.defaultConfig; } });
+// Merge user config with defaults, including nested objects we know about
+const mergeConfig = (userConfig) => {
+    if (!userConfig)
+        return { ...default_config_1.defaultConfig };
+    return {
+        ...default_config_1.defaultConfig,
+        ...userConfig,
+        password: {
+            ...default_config_1.defaultConfig.password,
+            ...(userConfig.password ?? {}),
+        },
+        token: {
+            ...default_config_1.defaultConfig.token,
+            ...(userConfig.token ?? {}),
+        },
+    };
+};
+exports.mergeConfig = mergeConfig;

package/dist/src/controllers/registrations.controller.d.ts

@@ -0,0 +1,3 @@
+import type { SignupResult } from '../core/auth.service';
+export type RegistrationsController = (data: Record<string, unknown>) => Promise<SignupResult>;
+export declare const getRegistrationsController: () => RegistrationsController;