@starklabs/backend-core 1.1.0 → 1.2.0

package/dist/js/lib/zod.validations.js

@@ -0,0 +1,247 @@
+import { z } from "zod";
+import { getConfig } from "../config/config.js";
+import "dotenv/config";
+
+/**
+ * =========================
+ * STRING HELPERS
+ * =========================
+ */
+
+export const requiredString = z
+  .string()
+  .trim()
+  .min(1, "At least 1 character in string is required");
+
+export const optionalString = z.string().trim().default("");
+
+/**
+ * =========================
+ * EMAIL
+ * =========================
+ */
+
+export const email = z
+  .string()
+  .trim()
+  .toLowerCase()
+  .email("Invalid email address");
+
+/**
+ * =========================
+ * PASSWORD
+ * =========================
+ */
+
+export const password = z
+  .string({
+    required_error: "Password is required",
+    invalid_type_error: "Password is required",
+  })
+  .min(6, "Password must be at least 6 characters");
+
+/**
+ * =========================
+ * NUMBER HELPERS
+ * =========================
+ */
+
+export const requiredNumber = z.coerce
+  .number()
+  .min(1, "Number must be 1 or greater");
+
+export const optionalNumber = z.coerce.number().default(0);
+
+/**
+ * =========================
+ * BOOLEAN HELPERS
+ * =========================
+ */
+
+export const booleanTrue = z.boolean().default(true);
+export const booleanFalse = z.boolean().default(false);
+
+/**
+ * =========================
+ * DATE
+ * =========================
+ */
+
+export const dateNow = z.date().default(() => new Date());
+
+/**
+ * =========================
+ * ARRAYS
+ * =========================
+ */
+
+export const stringArray = z.preprocess((val) => {
+  if (Array.isArray(val)) return val;
+
+  if (typeof val === "string") {
+    try {
+      const parsed = JSON.parse(val);
+      if (Array.isArray(parsed)) return parsed;
+    } catch (e) {
+      return val.split(",").map((v) => v.trim());
+    }
+  }
+
+  return [];
+}, z.array(z.string()).default([]));
+
+export const requiredStringArray = z.preprocess(
+  (val) => {
+    // already correct
+    if (Array.isArray(val)) return val;
+
+    // string case (your problem case)
+    if (typeof val === "string") {
+      try {
+        const parsed = JSON.parse(val);
+        if (Array.isArray(parsed)) return parsed;
+      } catch (e) {
+        // fallback: treat as comma-separated string
+        return val.split(",").map((v) => v.trim());
+      }
+    }
+
+    // weird multer case: array of broken strings
+    if (Array.isArray(val)) {
+      const joined = val.join("");
+      try {
+        const parsed = JSON.parse(joined);
+        if (Array.isArray(parsed)) return parsed;
+      } catch (e) {
+        return val;
+      }
+    }
+
+    return [];
+  },
+  z.array(z.string()).min(1, "Array must have at least 1 element"),
+);
+
+export const objectArray = z.preprocess(
+  (val) => {
+    if (Array.isArray(val)) return val;
+
+    if (typeof val === "string") {
+      try {
+        const parsed = JSON.parse(val);
+        if (Array.isArray(parsed)) return parsed;
+      } catch (e) {
+        return [];
+      }
+    }
+
+    return [];
+  },
+  z.array(z.object({})).default([]),
+);
+
+export const requiredObjectArray = z.preprocess(
+  (val) => {
+    // already correct
+    if (Array.isArray(val)) return val;
+
+    // string case (JSON from form-data)
+    if (typeof val === "string") {
+      try {
+        const parsed = JSON.parse(val);
+        if (Array.isArray(parsed)) return parsed;
+      } catch (e) {
+        return [];
+      }
+    }
+
+    return [];
+  },
+  z.array(z.object({})).min(1, "Array must have at least 1 object"),
+);
+
+/**
+ * =========================
+ * OBJECT ID / REFERENCES
+ * =========================
+ */
+
+export const objectId = z
+  .string({
+    required_error: "ObjectId is required",
+    invalid_type_error: "Invalid ObjectId",
+  })
+  .regex(/^[0-9a-fA-F]{24}$/, "Invalid ObjectId");
+
+export const requiredObjectId = objectId;
+
+export const userRef = objectId;
+export const requiredUserRef = objectId;
+
+export const userRefArray = z.array(objectId).default([]);
+
+/**
+ * =========================
+ * ENUMS
+ * =========================
+ */
+
+export const provider = z.enum(["local", "google"]).default("local");
+
+const internalRoles = JSON.parse(process.env.INTERNAL_ROLES || "[]");
+
+export const role = z.enum(["user", ...internalRoles]).default("user");
+
+/**
+ * =========================
+ * TIMESTAMPS
+ * =========================
+ */
+
+export const timestamps = {
+  createdAt: dateNow,
+  updatedAt: dateNow,
+};
+
+// files
+const requiredImage = z
+  .object({
+    fieldname: z.string(),
+    originalname: z.string(),
+    mimetype: z.string(),
+    size: z.number(),
+  })
+  .passthrough()
+  .refine((file) => file.mimetype.startsWith("image/"), {
+    message: "Only image files are allowed",
+  });
+/**
+ * =========================
+ * EXPORT ALL
+ * =========================
+ */
+
+export default {
+  requiredString,
+  optionalString,
+  email,
+  password,
+  requiredNumber,
+  optionalNumber,
+  booleanTrue,
+  booleanFalse,
+  dateNow,
+  stringArray,
+  requiredStringArray,
+  objectArray,
+  requiredObjectArray,
+  objectId,
+  requiredObjectId,
+  userRef,
+  requiredUserRef,
+  userRefArray,
+  timestamps,
+  provider,
+  role,
+  requiredImage,
+};

package/dist/js/middleware/auth.middleware.js

@@ -0,0 +1,51 @@
+import { verifyJWT, AppError } from "../utils/index.js";
+import registerModel from "../lib/model.registry.js";
+import { getConfig } from "../config/config.js";
+
+// find user safely
+const findUser = async (email) => {
+  const { userModel } = getConfig();
+  const Model = registerModel[userModel];
+
+  return await Model.findOne({ email });
+};
+
+// protect middleware
+const protect = async (req, res, next) => {
+  try {
+    const token = req.cookies?.authToken;
+
+    if (!token) {
+      return next(new AppError("Authentication required", 401));
+    }
+
+    const { jwtSecret } = getConfig();
+
+    const payload = verifyJWT(token, jwtSecret);
+
+    if (!payload?.email) {
+      return next(new AppError("Invalid token payload", 401));
+    }
+
+    const user = await findUser(payload.email);
+
+    if (!user) {
+      return next(new AppError("This account no longer exists", 401));
+    }
+
+    // optional: ensure provider consistency
+    if (payload.provider && payload.provider !== user.provider) {
+      return next(new AppError("Provider mismatch", 401));
+    }
+
+    // attach clean user (not raw JWT)
+    const { iat, exp, ...cleanPayload } = payload;
+    req.user = { ...cleanPayload, authProvider: user?.provider };
+
+    next();
+  } catch (error) {
+    return next(new AppError("Unauthorized", 401));
+  }
+};
+
+export default protect;

package/dist/js/middleware/error.middleware.js

@@ -0,0 +1,28 @@
+// custom imports
+import AppLog from "../utils/AppLog.js";
+
+const errorMiddleware = (err, req, res, next) => {
+  let statusCode = err.statusCode || 500;
+  let message = err.message || "Internal Server Error";
+
+  // Log everything for debugging
+  AppLog("X", "error.middleware.js", message);
+  console.log(err);
+
+  // Handle known / operational errors
+  if (err.isOperational) {
+    return res.status(statusCode).json({
+      success: false,
+      message,
+    });
+  }
+
+
+  // Unknown / programming errors
+  return res.status(500).json({
+    success: false,
+    message: "Something went wrong",
+  });
+};
+
+export default errorMiddleware;

package/dist/js/middleware/socket.middleware.js

@@ -0,0 +1,29 @@
+// module imports
+import cookie from "cookie";
+
+// custom imports
+import envs from "../config/envs.js";
+import { verifyJWT, AppError } from "../utils/index.js";
+
+export const socketProtect = (io) => {
+  io.use(async (socket, next) => {
+    try {
+      const cookies = cookie.parse(socket.handshake.headers.cookie || "");
+      const token = cookies.authToken;
+      if (!token) throw new AppError("Unauthorized");
+
+      const payLoad = verifyJWT(token);
+      delete payLoad.iat;
+      delete payLoad.exp;
+
+      payLoad.user = payLoad.id;
+
+      delete payLoad.id;
+
+      socket.user = payLoad;
+      next();
+    } catch (error) {
+       return next(new Error("Unauthorized"));
+    }
+  });
+};

package/dist/js/utils/AppLog.js

@@ -2,12 +2,13 @@
 const emojis = {
   check: "✅",
   X: "❌",
+  db: "📚"
 };
 
 // console logs
 /**
  *
- * @param {check | X} emoji
+ * @param {check | X | db} emoji
  * @param {string} file
  * @param {string} message
  */

package/dist/js/utils/deleteFile.js

@@ -0,0 +1,22 @@
+import { cloudinary } from "../config/cloudinary.js";
+import AppError from "./AppError.js";
+
+const deleteFile = async (id, fileType) => {
+  try {
+    if (!fileType) throw new Error(`fileType is required`);
+    if (!id) throw new Error(`${fileType} public_id is required`);
+
+    const item = await cloudinary.uploader.destroy(id, {
+      resource_type: fileType,
+    });
+
+    if (item.result === "not found")
+      throw new AppError("File not found to delete");
+
+    return true;
+  } catch (error) {
+    throw new AppError(error.message);
+  }
+};
+
+export default deleteFile;

package/dist/js/utils/index.js

@@ -4,4 +4,13 @@ export { default as successResponse } from "./successResponse.js";
 export { default as asyncHandler } from "./asyncHandler.js";
 export { default as AppError } from "./AppError.js";
 export { signJWT, verifyJWT } from "./jwt.js";
-export { hashPassword, verifyPassword } from "./libsodium.js";
+export {
+  hash,
+  verifyHash,
+  seal,
+  unSeal,
+  generateJWTSecret,
+  generateMasterKey,
+} from "./libsodium.js";
+export { default as uploadFile } from "./uploadFile.js";
+export {default as deleteFile} from "./deleteFile.js"

package/dist/js/utils/jwt.js

@@ -1,27 +1,16 @@
 import jwt from "jsonwebtoken";
 import AppError from "./AppError.js";
+import getDuration from "../config/duration.js";
 
-export const EXPIRY = {
-  "2m": 1000 * 60 * 2,
-  "10m": 1000 * 60 * 10,
-  "1h": 1000 * 60 * 60,
-  "6h": 1000 * 60 * 60 * 6,
-  "12h": 1000 * 60 * 60 * 12,
-  "1d": 1000 * 60 * 60 * 24,
-  "3d": 1000 * 60 * 60 * 24 * 3,
-  "7d": 1000 * 60 * 60 * 24 * 7,
-  "14d": 1000 * 60 * 60 * 24 * 14,
-  "30d": 1000 * 60 * 60 * 24 * 30,
-};
-
-const getExpiry = (key) => {
-  if (!EXPIRY[key]) throw new Error("Invalid expiry key");
-  return EXPIRY[key];
-};
-
-const signJWT = (payLoad, JWT_SECRET, JWT_EXPIRY) => {
+const signJWT = (payLoad, JWT_SECRET, tokenExpiry) => {
   try {
-    return jwt.sign(payLoad, JWT_SECRET, { expiresIn: JWT_EXPIRY });
+    if (!payLoad) throw new Error("payLoad is required");
+    if (!JWT_SECRET) throw new Error("jwtSecret is required");
+    if (!tokenExpiry) throw new Error("tokenExpiry is required");
+
+    return jwt.sign(payLoad, JWT_SECRET, {
+      expiresIn: getDuration(tokenExpiry),
+    });
   } catch (error) {
     throw new AppError(error.message);
   }
@@ -29,6 +18,9 @@ const signJWT = (payLoad, JWT_SECRET, JWT_EXPIRY) => {
 
 const verifyJWT = (token, JWT_SECRET) => {
   try {
+    if (!JWT_SECRET) throw new Error("jwtSecret is required");
+    if (!token) throw new Error("JWT token is required");
+
     return jwt.verify(token, JWT_SECRET);
   } catch (error) {
     throw new AppError("Invalid or expired token", 401);

package/dist/js/utils/libsodium.js

@@ -1,9 +1,9 @@
 import sodium from "libsodium-wrappers-sumo";
 import AppError from "./AppError.js";
-// import envs from "../config/envs.js";
 
 // Hash password
 export const hash = async (password) => {
+  if (!password) throw new AppError("String/password is required to hash.");
   await sodium.ready;
 
   const salt = sodium.randombytes_buf(sodium.crypto_pwhash_SALTBYTES);
@@ -23,6 +23,10 @@ export const hash = async (password) => {
 
 // verifyPassword
 export const verifyHash = async (password, storedHash) => {
+  if (!password) throw new AppError("String/password is required to verify");
+  if (!storedHash)
+    throw new AppError("storedHash is required for verification");
+
   await sodium.ready;
 
   const [saltB64, hashB64] = storedHash.split(":");
@@ -63,7 +67,10 @@ export const generateJWTSecret = async () => {
   const secret = sodium.randombytes_buf(64);
 
   // Convert to base64 for .env storage
-  const base64Secret = sodium.to_base64(secret, sodium.base64_variants.ORIGINAL);
+  const base64Secret = sodium.to_base64(
+    secret,
+    sodium.base64_variants.ORIGINAL,
+  );
   console.log(base64Secret);
   return base64Secret;
 };
@@ -71,6 +78,9 @@ export const generateJWTSecret = async () => {
 // seal
 export const seal = async (string, masterKey) => {
   try {
+    if (!string) throw new Error("Data is required to encrypt");
+    if (!masterKey) throw new Error("masterKey is required for encryption");
+
     await sodium.ready;
 
     const keyPair = sodium.crypto_box_keypair();
@@ -106,7 +116,13 @@ export const seal = async (string, masterKey) => {
 };
 
 // unSeal
-export const unSeal = async (str, nonce, publicKey, securedPrivateKey, masterKey) => {
+export const unSeal = async (
+  str,
+  nonce,
+  publicKey,
+  securedPrivateKey,
+  masterKey,
+) => {
   try {
     if (!str || !nonce || !publicKey || !securedPrivateKey)
       throw new AppError(

package/dist/js/utils/rateLimiter.js

@@ -0,0 +1,25 @@
+import rateLimit from "express-rate-limit";
+import getDuration from "../config/duration.js";
+import AppError from "./AppError.js";
+
+export const apiLimiter = ({
+  rateLimitDuration,
+  maxReqLimit,
+  rateLimitMsg,
+}) => {
+  if (!rateLimitDuration || !maxReqLimit || !rateLimitMsg)
+    throw new AppError(
+      "rateLimitDuration, maxReqLimit and rateLimitMsg are required",
+    );
+
+  return rateLimit({
+    windowMs: getDuration(rateLimitDuration) || 15 * 60 * 1000, // 15 minutes
+    max: maxReqLimit || 200, // limit each IP to 200 requests per windowMs
+    standardHeaders: true,
+    legacyHeaders: false,
+    message: {
+      success: false,
+      message: rateLimitMsg || "Too many requests, please try again later.",
+    },
+  });
+};

package/dist/js/utils/uploadFile.js

@@ -0,0 +1,43 @@
+import { getConfig } from "../config/config.js";
+import { cloudinary, upload } from "../config/cloudinary.js";
+import AppError from "./AppError.js";
+import AppLog from "./AppLog.js";
+
+const uploadFile = async (fileData, uploadFolderName) => {
+  try {
+    if (!fileData) throw new Error("fileData not found");
+    if (!uploadFolderName) throw new Error("uploadFolder is required");
+
+    const uploadResult = await new Promise((resolve, reject) => {
+      const stream = cloudinary.uploader.upload_stream(
+        {
+          resource_type: "auto",
+          folder: uploadFolderName,
+        },
+        (error, result) => {
+          if (error) return reject(error);
+          resolve(result);
+        },
+      );
+
+      stream.end(fileData.buffer);
+    });
+
+    if (uploadResult.name === "Error")
+      throw new AppError(uploadResult.message.split(".")[0]);
+
+    const { public_id, secure_url, width, height } = uploadResult;
+
+    return {
+      public_id,
+      secure_url,
+      width,
+      height,
+    };
+  } catch (error) {
+    throw new AppError(error.message);
+    AppLog("X", "uploadFile", error.message);
+  }
+};
+
+export default uploadFile;

package/handlerMap.js

@@ -0,0 +1,33 @@
+const handlerMap = {
+  // Auth
+  login: "Authenticate a user",
+  signup: "Register a new user",
+  logout: "Sign out a user",
+  resendOTP: "Resend one-time password",
+  twoFactorAuth: "Verify two-factor authentication",
+  forgotPassword: "Request password reset",
+  resetPassword: "Reset password",
+  changePassword: "Change password",
+  verifyEmail: "Verify email address",
+  refreshToken: "Refresh access token",
+  deleteAccount: "Delete current account",
+
+  // Generic CRUD
+  getAll: "Get all resources",
+  getById: "Get a resource by ID",
+  create: "Create a resource",
+  update: "Update a resource",
+  patch: "Partially update a resource",
+  delete: "Delete a resource",
+
+  // Query
+  search: "Search resources",
+  filter: "Filter resources",
+  paginate: "Get paginated resources",
+  count: "Get resource count",
+
+  // Files
+  uploadFile: "Upload a file",
+  downloadFile: "Download a file",
+  deleteFile: "Delete a file",
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@starklabs/backend-core",
-  "version": "1.1.0",
-  "description": "A comprehensive backend authentication library featuring MongoDB integration, JWT-based authentication, encryption/decryption using libsodium, and utilities for error handling and logging. Supports both ES modules and CommonJS. Requires MONGO_URI, DB_NAME, MASTER_KEY, and JWT_SECRET environment variables.",
+  "version": "1.2.0",
+  "description": "A comprehensive backend authentication library featuring MongoDB integration, JWT-based authentication, encryption/decryption using libsodium, and utilities for error handling and logging. Supports both ES modules and CommonJS. Requires MONGODB_URI, DB_NAME, MASTER_KEY, and JWT_SECRET environment variables.",
   "keywords": [
     "auth-mongo",
     "backend-core"
@@ -9,20 +9,33 @@
   "license": "ISC",
   "author": "Musa",
   "type": "module",
-  "main": "index.js",
+  "main": "./dist/index.js",
   "scripts": {
-    "test": "node test.js"
+    "test": "node test.js",
+    "env-open": "npx dotenv-vault@latest open",
+    "env-push": "npx dotenv-vault@latest push",
+    "env-pull": "npx dotenv-vault@latest pull",
+    "env-login": "npx dotenv-vault@latest login",
+    "env-new": "npx dotenv-vault@latest new"
   },
   "dependencies": {
+    "cloudinary": "^2.10.0",
     "cookie-parser": "^1.4.7",
     "cors": "^2.8.6",
     "dotenv": "^17.4.2",
     "express": "^5.2.1",
-    "helmet": "^8.1.0",
+    "express-rate-limit": "^8.5.2",
+    "helmet": "^8.2.0",
     "jsonwebtoken": "^9.0.3",
     "libsodium-wrappers-sumo": "^0.8.4",
     "mongoose": "^9.6.1",
+    "multer": "^2.2.0",
     "resend": "^6.12.2",
     "zod": "^4.4.1"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js"
+    }
   }
 }