otpkit.js 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 otpkit.js
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,291 @@
+<p align="center">
+  <img src="https://img.shields.io/npm/v/otpkit.js?style=flat-square&color=blue" alt="npm version" />
+  <img src="https://img.shields.io/npm/l/otpkit.js?style=flat-square&color=green" alt="license" />
+  <img src="https://img.shields.io/npm/dt/otpkit.js?style=flat-square&color=orange" alt="downloads" />
+  <img src="https://img.shields.io/badge/node-%3E%3D14.0.0-brightgreen?style=flat-square" alt="node version" />
+</p>
+
+# 🔐 otpkit.js
+
+**Lightweight, secure OTP generation and verification for Node.js applications.**
+
+A simple, framework-agnostic library for generating and verifying one-time passwords (OTPs) with bcrypt hashing and built-in expiry management. Perfect for email/SMS verification, password resets, and two-factor authentication flows.
+
+---
+
+## ✨ Features
+
+- **🔒 Secure by Default** — OTPs are hashed using bcrypt before storage
+- **⏱️ Built-in Expiry** — Automatic TTL (time-to-live) handling
+- **🎯 Zero Configuration** — Works out of the box with sensible defaults
+- **📦 Lightweight** — Minimal dependencies, small footprint
+- **🔧 Framework Agnostic** — Works with Express, Fastify, Koa, Hono, or vanilla Node.js
+- **🎲 Cryptographically Random** — Uses Node.js `crypto.randomInt()` for secure OTP generation
+- **📝 TypeScript Friendly** — Clean API with predictable return types
+
+---
+
+## 📦 Installation
+
+```bash
+npm install otpkit.js
+```
+
+```bash
+yarn add otpkit.js
+```
+
+```bash
+pnpm add otpkit.js
+```
+
+---
+
+## 🚀 Quick Start
+
+```javascript
+import { createOTP, verifyOTP } from "otpkit.js";
+
+// Generate an OTP
+const { otp, hash, expiresAt } = await createOTP();
+
+console.log(otp);       // "482916" → Send this to the user (email/SMS)
+console.log(hash);      // "$2a$10$..." → Store this in your database
+console.log(expiresAt); // 1703001234567 → Unix timestamp when OTP expires
+
+// Later, verify the OTP entered by the user
+const result = await verifyOTP({
+  otp: "482916",    // User's input
+  hash: hash,       // Retrieved from database
+  expiresAt: expiresAt
+});
+
+if (result.valid) {
+  console.log("OTP verified successfully!");
+} else {
+  console.log("Verification failed:", result.reason);
+  // result.reason: "OTP_EXPIRED" | "OTP_INVALID"
+}
+```
+
+---
+
+## 📖 API Reference
+
+### `createOTP(options?)`
+
+Generates a new OTP with a bcrypt hash.
+
+#### Parameters
+
+| Parameter | Type     | Default | Description                          |
+|-----------|----------|---------|--------------------------------------|
+| `length`  | `number` | `6`     | Length of the OTP (minimum: 4)       |
+| `ttl`     | `number` | `300`   | Time-to-live in seconds (5 minutes)  |
+
+#### Returns
+
+```javascript
+{
+  otp: string,        // The plaintext OTP to send to the user
+  hash: string,       // Bcrypt hash to store in your database
+  expiresAt: number,  // Unix timestamp (ms) when the OTP expires
+  ttl: number         // The TTL value used
+}
+```
+
+#### Examples
+
+```javascript
+// Default: 6-digit OTP, 5-minute expiry
+const { otp, hash, expiresAt } = await createOTP();
+
+// Custom: 8-digit OTP, 10-minute expiry
+const { otp, hash, expiresAt } = await createOTP({ length: 8, ttl: 600 });
+
+// Short-lived: 4-digit OTP, 2-minute expiry
+const { otp, hash, expiresAt } = await createOTP({ length: 4, ttl: 120 });
+```
+
+---
+
+### `verifyOTP(options)`
+
+Verifies an OTP against its hash, checking both validity and expiration.
+
+#### Parameters
+
+| Parameter   | Type     | Required | Description                            |
+|-------------|----------|----------|----------------------------------------|
+| `otp`       | `string` | Yes      | The OTP entered by the user            |
+| `hash`      | `string` | Yes      | The bcrypt hash stored in your database|
+| `expiresAt` | `number` | Yes      | The expiration timestamp               |
+
+#### Returns
+
+```javascript
+{
+  valid: boolean,           // Whether the OTP is valid
+  reason: string | null     // null if valid, otherwise "OTP_EXPIRED" or "OTP_INVALID"
+}
+```
+
+#### Examples
+
+```javascript
+// Successful verification
+const result = await verifyOTP({ otp: "482916", hash, expiresAt });
+// { valid: true, reason: null }
+
+// Expired OTP
+const result = await verifyOTP({ otp: "482916", hash, expiresAt: Date.now() - 1000 });
+// { valid: false, reason: "OTP_EXPIRED" }
+
+// Invalid OTP
+const result = await verifyOTP({ otp: "000000", hash, expiresAt });
+// { valid: false, reason: "OTP_INVALID" }
+```
+
+---
+
+## 💡 Usage Examples
+
+### Email Verification Flow
+
+```javascript
+import { createOTP, verifyOTP } from "otpkit.js";
+import { sendEmail } from "./your-email-service.js";
+import { db } from "./your-database.js";
+
+// Step 1: User requests email verification
+async function requestEmailVerification(userId, email) {
+  const { otp, hash, expiresAt } = await createOTP({ ttl: 600 }); // 10 min expiry
+
+  // Store hash and expiry in database
+  await db.users.update(userId, {
+    emailVerificationHash: hash,
+    emailVerificationExpiry: expiresAt
+  });
+
+  // Send OTP to user's email
+  await sendEmail({
+    to: email,
+    subject: "Your Verification Code",
+    body: `Your verification code is: ${otp}`
+  });
+}
+
+// Step 2: User submits the OTP
+async function verifyEmail(userId, userOtp) {
+  const user = await db.users.findById(userId);
+
+  const result = await verifyOTP({
+    otp: userOtp,
+    hash: user.emailVerificationHash,
+    expiresAt: user.emailVerificationExpiry
+  });
+
+  if (result.valid) {
+    await db.users.update(userId, {
+      emailVerified: true,
+      emailVerificationHash: null,
+      emailVerificationExpiry: null
+    });
+    return { success: true };
+  }
+
+  return { success: false, error: result.reason };
+}
+```
+
+### Express.js Integration
+
+```javascript
+import express from "express";
+import { createOTP, verifyOTP } from "otpkit.js";
+
+const app = express();
+app.use(express.json());
+
+// In-memory store (use Redis/DB in production)
+const otpStore = new Map();
+
+app.post("/api/otp/send", async (req, res) => {
+  const { phone } = req.body;
+  const { otp, hash, expiresAt } = await createOTP();
+
+  otpStore.set(phone, { hash, expiresAt });
+
+  // Send OTP via SMS service
+  console.log(`Send OTP ${otp} to ${phone}`);
+
+  res.json({ message: "OTP sent successfully" });
+});
+
+app.post("/api/otp/verify", async (req, res) => {
+  const { phone, otp } = req.body;
+  const stored = otpStore.get(phone);
+
+  if (!stored) {
+    return res.status(400).json({ error: "No OTP found for this number" });
+  }
+
+  const result = await verifyOTP({
+    otp,
+    hash: stored.hash,
+    expiresAt: stored.expiresAt
+  });
+
+  if (result.valid) {
+    otpStore.delete(phone);
+    return res.json({ success: true });
+  }
+
+  res.status(400).json({ error: result.reason });
+});
+
+app.listen(3000);
+```
+
+---
+
+## 🔒 Security Considerations
+
+1. **Never log or expose the plaintext OTP** — Only send it to the user via a secure channel
+2. **Store only the hash** — Never store the plaintext OTP in your database
+3. **Implement rate limiting** — Prevent brute-force attacks on OTP verification
+4. **Use HTTPS** — Always transmit OTPs over encrypted connections
+5. **Consider attempt limits** — Lock out users after multiple failed verification attempts
+6. **Clean up expired OTPs** — Regularly purge expired OTP records from your database
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+---
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+---
+
+## 👤 Author
+
+**Ashutosh Swamy**
+
+- GitHub: [@ashutoshswamy](https://github.com/ashutoshswamy)
+
+---
+
+<p align="center">
+  Made with ❤️ for the Node.js community
+</p>

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "otpkit.js",
+  "version": "1.0.0",
+  "description": "Lightweight, secure OTP generation and verification for Node.js applications. Framework-agnostic, production-ready, and easy to integrate.",
+  "keywords": [
+    "otp",
+    "one-time-password",
+    "authentication",
+    "auth",
+    "security",
+    "node",
+    "nodejs",
+    "backend",
+    "login",
+    "signup",
+    "verification",
+    "password-reset",
+    "mfa",
+    "2fa",
+    "email-otp",
+    "sms-otp",
+    "bcrypt",
+    "hashing",
+    "framework-agnostic",
+    "utility"
+  ],
+  "homepage": "https://github.com/ashutoshswamy/otpkit.js#readme",
+  "bugs": {
+    "url": "https://github.com/ashutoshswamy/otpkit.js/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ashutoshswamy/otpkit.js.git"
+  },
+  "license": "MIT",
+  "author": "Ashutosh Swamy",
+  "type": "module",
+  "main": "src/index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "dependencies": {
+    "bcryptjs": "^3.0.3"
+  }
+}

package/src/generate.js

@@ -0,0 +1,14 @@
+import bcrypt from "bcryptjs";
+import { generateNumericOTP } from "./utils.js";
+
+export async function createOTP({ length = 6, ttl = 300 } = {}) {
+  const otp = generateNumericOTP(length);
+  const hash = await bcrypt.hash(otp, 10);
+
+  return {
+    otp,                // send to user
+    hash,               // store in DB
+    expiresAt: Date.now() + ttl * 1000,
+    ttl,
+  };
+}

package/src/index.js

@@ -0,0 +1,2 @@
+export { createOTP } from "./generate.js";
+export { verifyOTP } from "./verify.js";

package/src/utils.js

@@ -0,0 +1,18 @@
+import crypto from "crypto";
+
+export function generateNumericOTP(length = 6) {
+  if (length < 4) {
+    throw new Error("OTP length must be at least 4");
+  }
+
+  let otp = "";
+  for (let i = 0; i < length; i++) {
+    otp += crypto.randomInt(0, 10);
+  }
+
+  return otp;
+}
+
+export function isExpired(expiresAt) {
+  return Date.now() > expiresAt;
+}

package/src/verify.js

@@ -0,0 +1,14 @@
+import bcrypt from "bcryptjs";
+import { isExpired } from "./utils.js";
+
+export async function verifyOTP({ otp, hash, expiresAt }) {
+  if (isExpired(expiresAt)) {
+    return { valid: false, reason: "OTP_EXPIRED" };
+  }
+
+  const match = await bcrypt.compare(otp, hash);
+
+  return match
+    ? { valid: true, reason: null }
+    : { valid: false, reason: "OTP_INVALID" };
+}