hi-secure 1.0.12 → 1.0.14

package/readme.md

@@ -2,279 +2,445 @@
 <p align="center"><strong>One-line security for Express.js</strong></p>
 
 <p align="center">
-HiSecure replaces <strong>10+ common Express security libraries</strong> with one unified API.<br/>
-It provides hashing, authentication, validation, sanitization, rate-limiting, CORS,<br/>
-security headers, compression, JSON parsing, query parsing and logging — all in a single layer.
+HiSecure unifies authentication, validation, sanitization, rate-limiting, headers and parsing<br/>
+into a single, consistent security layer for Express applications.
 </p>
 
-<br/>
+<hr/>
 
-<hr style="border:0; border-top:2px solid #e5e7eb; margin:32px 0"/>
-
-<h2>🚀 Overview</h2>
+<h2>Overview</h2>
 
 <p>
-Most Express applications require multiple security packages: hashing, CORS, headers, sanitization,
-validation, rate-limits, compression, JSON parsing, query parsing, and authentication.  
-Managing all of these separately leads to duplication, bugs, and misconfiguration.
+Modern Express applications require multiple security libraries to handle authentication,
+password hashing, validation, sanitization, rate limiting, headers, compression and parsing.
+Managing these separately leads to duplicated logic, configuration drift and subtle bugs.
 </p>
 
-<p><strong>HiSecure handles all of them for you — with one middleware call.</strong></p>
+<p>
+<strong>HiSecure solves this by acting as a single orchestration layer.</strong>
+</p>
 
 <ul>
-  <li><code>argon2</code> / <code>bcrypt</code> — hashing</li>
-  <li><code>sanitize-html</code> / <code>xss</code> — sanitization</li>
-  <li><code>express-validator</code> / <code>zod</code> — validation</li>
-  <li><code>helmet</code> / <code>hpp</code> — headers + HPP</li>
-  <li><code>cors</code> — CORS control</li>
-  <li><code>express-rate-limit</code> + <code>rate-limiter-flexible</code> — rate limiting</li>
-  <li><code>compression</code> — gzip</li>
-  <li><code>json/urlencoded</code> — parsers</li>
-  <li><code>qs</code> — secure deep query parsing</li>
+  <li>Password hashing (Argon2 with bcrypt fallback)</li>
+  <li>JWT authentication and route protection</li>
+  <li>Google login (ID token verification)</li>
+  <li>Request validation and sanitization</li>
+  <li>Rate limiting and abuse prevention</li>
+  <li>CORS, security headers and compression</li>
+  <li>JSON, URL and query parsing</li>
 </ul>
 
-<p><strong>HiSecure bundles all of these features out-of-the-box.</strong></p>
-
-<br/>
-<hr style="border:0; border-top:2px solid #e5e7eb; margin:32px 0"/>
+<hr/>
 
-<h2>✨ Feature Matrix</h2>
-
-<p>
-A complete list of what HiSecure does.  
-Everything is built to work together without configuration.
-</p>
+<h2>Feature Matrix</h2>
 
 <table width="100%">
   <tr>
     <th align="left">Capability</th>
     <th align="left">Status</th>
-    <th align="left">Details</th>
+    <th align="left">Notes</th>
   </tr>
 
   <tr>
-    <td>🔐 JWT Authentication</td>
-    <td>✅ Stable</td>
-    <td>Built-in issuer, audience, expiry and subject support. Google ID-token adapter included.</td>
+    <td>JWT Authentication</td>
+    <td>Stable</td>
+    <td>Issuer, audience, expiry and subject supported</td>
   </tr>
 
   <tr>
-    <td>🔑 Password Hashing (Argon2 + bcrypt fallback)</td>
-    <td>✅ Stable</td>
-    <td>Argon2-first approach with bcrypt fallback. No salt configuration required.</td>
+    <td>Password Hashing</td>
+    <td>Stable</td>
+    <td>Argon2 primary with bcrypt fallback</td>
   </tr>
 
   <tr>
-    <td>🛡 Route Protection</td>
-    <td>✅ Stable</td>
-    <td>Authentication guard with support for roles (RBAC).</td>
+    <td>Google Login</td>
+    <td>Stable</td>
+    <td>ID token verification adapter included</td>
   </tr>
 
   <tr>
-    <td>📏 Validation (Zod + express-validator)</td>
-    <td>✅ Stable</td>
-    <td>Automatically detects schema type. Provides a clean error format.</td>
+    <td>Route Protection (RBAC)</td>
+    <td>Stable</td>
+    <td>Role-based access via JWT payload</td>
   </tr>
 
   <tr>
-    <td>🧼 Sanitization</td>
-    <td>✅ Stable</td>
-    <td>Protects against HTML injection & XSS using sanitize-html + xss fallback.</td>
+    <td>Validation</td>
+    <td>Stable</td>
+    <td>Zod and express-validator supported</td>
   </tr>
 
   <tr>
-    <td>⏱ Rate Limiting</td>
-    <td>✅ Stable</td>
-    <td>Presets (strict/relaxed/api) + custom per-route limits. Fallback engine included.</td>
+    <td>Sanitization</td>
+    <td>Stable</td>
+    <td>HTML injection and XSS protection</td>
   </tr>
 
   <tr>
-    <td>🌐 CORS</td>
-    <td>✅ Stable</td>
-    <td>Dynamic origins + full configuration support.</td>
+    <td>Rate Limiting</td>
+    <td>Stable</td>
+    <td>Presets and per-route configuration</td>
   </tr>
 
   <tr>
-    <td>🧱 Security Headers</td>
-    <td>✅ Stable</td>
-    <td>Automatic helmet + HPP integration.</td>
+    <td>CORS & Headers</td>
+    <td>Stable</td>
+    <td>Helmet, HPP and CORS integrated</td>
   </tr>
 
   <tr>
-    <td>📦 JSON & URL Parsing</td>
-    <td>✅ Stable</td>
-    <td>Togglable express.json + urlencoded, simple and safe.</td>
+    <td>Compression</td>
+    <td>Stable</td>
+    <td>gzip via a single flag</td>
   </tr>
 
   <tr>
-    <td>🔍 Query Parsing</td>
-    <td>✅ Stable</td>
-    <td>Secure <code>qs</code>-based deep parsing out of the box.</td>
+    <td>Logging</td>
+    <td>Beta</td>
+    <td>Structured internal logs</td>
   </tr>
+</table>
 
-  <tr>
-    <td>🌀 Compression</td>
-    <td>✅ Stable</td>
-    <td>gzip enabled via a single flag.</td>
-  </tr>
+<hr/>
 
-  <tr>
-    <td>📊 Structured Logging</td>
-    <td>⚠️ Beta</td>
-    <td>Unified log output for debugging & monitoring.</td>
-  </tr>
+<h2>Developer Experience</h2>
 
-  <tr>
-    <td>🔧 Adapter System</td>
-    <td>✅ Stable</td>
-    <td>Swap hashing/validation/sanitization engines easily.</td>
-  </tr>
-</table>
+<ul>
+  <li>Single global middleware for security</li>
+  <li>No manual wiring of multiple packages</li>
+  <li>Consistent error handling</li>
+  <li>Safe defaults with escape hatches</li>
+  <li>Beginner-friendly, production-ready</li>
+</ul>
+
+<hr/>
+
+<h2>Quick Start</h2>
+
+<pre><code>npm install hi-secure</code></pre>
+
+<pre><code>import express from "express";
+import { HiSecure } from "hi-secure";
+
+const app = express();
+
+app.use(HiSecure.middleware("api"));
+
+app.listen(3000);
+</code></pre>
 
-<br/>
-<hr style="border:0; border-top:2px solid #e5e7eb; margin:32px 0"/>
+<hr/>
 
-<h2>⚡ Developer Experience Highlights</h2>
+<h2>Core Helpers</h2>
+
+<h3>Password Hashing</h3>
+
+<pre><code>const hash = await HiSecure.hash(password);
+const isValid = await HiSecure.verify(password, hash);
+</code></pre>
+
+
+
+
+<h3>Input Validation</h3>
+
+<pre><code>router.post(
+  "/register",
+  HiSecure.validate([...]),
+  controller
+);
+</code></pre>
+
+<h3>Rate Limiting</h3>
+
+<pre><code>HiSecure.rateLimit({ max: 5, windowMs: 15 * 60 * 1000 });
+</code></pre>
+
+
+
+<hr/>
+
+<h2>Global CORS Configuration</h2>
 
 <p>
-HiSecure is designed so even a beginner can set up security in minutes.
-Here’s what makes it simple:
+Global CORS defines the baseline access rules for your entire application.
+These rules apply to all routes unless explicitly overridden at the route level.
 </p>
 
-<ul>
-  <li><strong>One-line global security</strong> using <code>HiSecure.middleware()</code></li>
+<p>
+This is ideal for standard APIs where most endpoints share the same access policy.
+</p>
+
+<hr/>
+
+<h3>Basic Global CORS</h3>
+
+<p>
+Enable CORS globally using default configuration.
+</p>
+
+<pre><code>app.use(
+  HiSecure.middleware({
+    cors: true
+  })
+);
+</code></pre>
 
-  <li><strong>Password utilities</strong>
-    <br/>• <code>HiSecure.hash()</code> — secure Argon2 hashing  
-    <br/>• <code>HiSecure.verify()</code> — easy password comparison  
-  </li>
+<hr/>
 
-  <li><strong>JWT utilities</strong>
-    <br/>• <code>HiSecure.jwt.sign()</code> — create tokens  
-    <br/>• <code>HiSecure.jwt.verify()</code> — verify tokens  
-  </li>
+<h3>Custom Global CORS</h3>
 
-  <li>Automatic sanitization — no extra middleware needed</li>
+<p>
+Define explicit CORS rules for all routes.
+</p>
 
-  <li>Auto-detected validation (Zod or express-validator)</li>
+<pre><code>app.use(
+  HiSecure.middleware({
+    cors: {
+      origin: ["https://app.example.com"],
+      methods: ["GET", "POST", "PUT", "DELETE"],
+      allowedHeaders: ["Content-Type", "Authorization"],
+      credentials: true
+    }
+  })
+);
+</code></pre>
 
-  <li>Clean route protection with <code>HiSecure.auth()</code></li>
+<hr/>
 
-  <li>Flexible rate limits for login routes and APIs</li>
+<h3>Multiple Client Applications</h3>
 
-  <li>Zero configuration for headers, parsing, gzip, CORS, etc.</li>
+<p>
+Allow multiple frontends (web, admin, mobile) to access the same API.
+</p>
 
-  <li>Perfect for beginners and production-grade APIs</li>
-</ul>
+<pre><code>app.use(
+  HiSecure.middleware({
+    cors: {
+      origin: [
+        "https://web.example.com",
+        "https://admin.example.com",
+        "https://mobile.example.com"
+      ],
+      credentials: true
+    }
+  })
+);
+</code></pre>
 
-<br/>
-<hr style="border:0; border-top:2px solid #e5e7eb; margin:32px 0"/>
+<hr/>
 
-<h2>📌 Summary</h2>
+<h3>Public API (Open Read Access)</h3>
 
 <p>
-HiSecure provides a powerful but easy security layer:
+Use open CORS rules for public or read-only APIs.
 </p>
 
-<ul>
-  <li><strong>JWT Authentication</strong></li>
-  <li><strong>Password Hashing</strong></li>
-  <li><strong>Route Protection</strong></li>
-  <li><strong>Validation + Sanitization</strong></li>
-  <li><strong>Rate Limiting</strong> (primary + fallback)</li>
-  <li><strong>CORS + Security Headers + Compression</strong></li>
-  <li><strong>JSON + Query Parsing</strong></li>
-</ul>
+<pre><code>app.use(
+  HiSecure.middleware({
+    cors: {
+      origin: "*",
+      methods: ["GET"]
+    }
+  })
+);
+</code></pre>
 
-<p align="center"><strong>
-Security without complexity.<br/>
-One dependency — complete Express protection.
-</strong></p>
+<hr/>
 
-<br/><br/>
+<h2> Route-Level Security (Advanced & Real-World Usage)</h2>
 
-<!-- ─────────────────────────────────────────────────────────────── -->
-<h2 align="center">📘 Documentation Sections</h2>
-<!-- ─────────────────────────────────────────────────────────────── -->
+<p>
+HiSecure supports fine-grained security control at the route level.
+Each capability can be configured independently without affecting global middleware.
+</p>
 
-<hr style="border:0; border-top:2px dashed #d4d4d8; margin:32px 0"/>
+<p>
+This allows you to apply strict security where needed (auth, payments, admin)
+and relaxed rules for public or internal endpoints.
+</p>
 
-<h2>📘 Part 1 — Quick Start</h2>
+<hr/>
 
-<p>This section is designed for beginners to get started within seconds.</p>
+<h3>Custom CORS (Deep Control)</h3>
 
-<strong>Install</strong>
-<pre><code>npm install hi-secure</code></pre>
+<p>
+Route-level CORS is useful when different consumers access different endpoints
+(e.g. web app, admin panel, third-party services).
+</p>
 
-<strong>Basic Usage</strong>
-<pre><code>const express = require('express');
-const { HiSecure } = require('hi-secure');
+<p><strong>Example: Webhook endpoint (single trusted origin)</strong></p>
 
-const app = express();
+<pre><code>router.post(
+  "/webhook",
+  HiSecure.cors({
+    origin: ["https://trusted-client.com"],
+    methods: ["POST"],
+    allowedHeaders: ["Content-Type", "Authorization"],
+    credentials: true
+  }),
+  controller
+);
+</code></pre>
 
-// One-line complete security preset
-app.use(HiSecure.middleware('api'));
+<p><strong>Example: Admin dashboard with restricted origins</strong></p>
 
-app.listen(3000);
+<pre><code>router.get(
+  "/admin/stats",
+  HiSecure.cors({
+    origin: [
+      "https://admin.example.com",
+      "https://internal.example.com"
+    ],
+    credentials: true
+  }),
+  controller
+);
 </code></pre>
 
-<p><small>The "api" preset includes CORS, Relaxed Rate Limit, Sanitization and basic headers.</small></p>
+<p><strong>Example: Public API with open read access</strong></p>
 
-<br/>
-<hr style="border:0; border-top:2px dashed #d4d4d8; margin:32px 0"/>
+<pre><code>router.get(
+  "/public/feed",
+  HiSecure.cors({ origin: "*" }),
+  controller
+);
+</code></pre>
 
-<h2>📘 Part 2 — Using Built-In Helpers</h2>
+<hr/>
 
-<h3>2.1 Hashing + Verifying Passwords</h3>
+<h3>Validation (Schema vs Rules — When to Use What)</h3>
 
-<p>Perfect for controllers like register/login.</p>
+<p>
+HiSecure automatically detects validation strategy based on input type.
+Choose the style based on complexity and ownership.
+</p>
 
-<pre><code>const hashed = await HiSecure.hash(password);
-const valid = await HiSecure.verify(password, user.password);
-</code></pre>
+<ul>
+  <li><strong>express-validator</strong> — quick, form-like validation</li>
+  <li><strong>Zod</strong> — complex schemas, reuse, shared contracts</li>
+</ul>
 
-<h3>2.2 Validating Inputs in Routes</h3>
+<h4>express-validator (Rule-Based, Inline)</h4>
 
-<p>HiSecure automatically detects whether you're providing Zod or express-validator rules.</p>
+<pre><code>import { body } from "express-validator";
 
-<pre><code>router.post(
-  '/register',
+router.post(
+  "/register",
   HiSecure.validate([
-    body("name").notEmpty().isLength({ min: 3 }),
-    body("email").notEmpty().isEmail(),
-    body("password").notEmpty().isLength({ min: 6 })
+    body("email")
+      .notEmpty()
+      .isEmail(),
+
+    body("password")
+      .isLength({ min: 6 }),
+
+    body("role")
+      .optional()
+      .isIn(["user", "admin"])
   ]),
-  registerUser
+  controller
+);
+</code></pre>
+
+<h4>Zod (Schema-Based, Reusable)</h4>
+
+<pre><code>import { z } from "zod";
+
+const registerSchema = z.object({
+  email: z.string().email(),
+  password: z.string().min(6),
+  role: z.enum(["user", "admin"]).optional()
+});
+
+router.post(
+  "/register",
+  HiSecure.validate(registerSchema),
+  controller
 );
 </code></pre>
 
-<h3>2.3 Login Route with Rate Limiting</h3>
+<p>
+Both approaches produce a unified error response format.
+</p>
+
+<hr/>
+
+<h3>Sanitization (Trust Boundaries)</h3>
+
+<p>
+Sanitization should reflect trust boundaries.
+Not all routes require the same level of strictness.
+</p>
+
+<p><strong>User-generated content (allow formatting)</strong></p>
 
 <pre><code>router.post(
-  '/login',
-  HiSecure.validate([...]),
-  HiSecure.rateLimit({ max: 5, windowMs: 15 * 60 * 1000 }),
-  loginUser
+  "/comment",
+  HiSecure.sanitize({
+    allowedTags: ["b", "i", "strong", "em", "a"],
+    allowedAttributes: {
+      a: ["href"]
+    }
+  }),
+  controller
 );
 </code></pre>
 
-<h3>2.4 Protecting Routes with Auth Middleware</h3>
+<p><strong>Strict input (no HTML allowed)</strong></p>
 
-<pre><code>router.get(
-  '/profile',
-  HiSecure.auth({ required: true }),
-  getProfile
+<pre><code>router.post(
+  "/feedback",
+  HiSecure.sanitize({
+    allowedTags: [],
+    allowedAttributes: {}
+  }),
+  controller
+);
+</code></pre>
+
+<p><strong>Trusted internal pipeline (disable sanitization)</strong></p>
+
+<pre><code>router.post(
+  "/internal/import",
+  HiSecure.sanitize(false),
+  controller
+);
+</code></pre>
+
+<hr/>
+
+<h3>Full Route-Level Security Composition</h3>
+
+<p>
+A real-world admin route combining multiple security layers.
+Execution order is deterministic and isolated to the route.
+</p>
+
+<pre><code>router.post(
+  "/admin/create-user",
+  HiSecure.auth({ roles: ["admin"] }),
+  HiSecure.rateLimit({ max: 3, windowMs: 10 * 60 * 1000 }),
+  HiSecure.cors({
+    origin: ["https://admin.example.com"]
+  }),
+  HiSecure.sanitize(),
+  HiSecure.validate([
+    body("email").isEmail(),
+    body("password").isLength({ min: 8 })
+  ]),
+  controller
 );
 </code></pre>
 
-<br/>
-<hr style="border:0; border-top:2px dashed #d4d4d8; margin:32px 0"/>
 
-<h2>📘 Part 3 — JWT Mode (Advanced)</h2>
 
-<p>Enable this mode only if you want full control over JWT signing options.</p>
+<h2>JWT Mode</h2>
 
-<h3>3.1 Configure JWT Engine</h3>
+<p>
+JWT support is optional. Enable it only if you want authentication features.
+</p>
 
 <pre><code>HiSecure.resetInstance();
 
@@ -287,280 +453,292 @@ HiSecure.getInstance({
 });
 </code></pre>
 
-<h3>3.2 Global Security Middleware</h3>
+<hr/>
 
-<pre><code>app.use(HiSecure.middleware({
-  cors: true,
-  rateLimit: "strict",
-  sanitize: true,
-  headers: true,
-  compression: true,
-  json: true
-}));
-</code></pre>
+<h2>Final Authentication Setup</h2>
+
+<hr/>
+
+<h2>🔐 Final Authentication Setup</h2>
+
+<p>
+This section demonstrates a complete, production-ready authentication setup using HiSecure.
+It covers signup, JWT login, Google login, role-based access control, and proper initialization.
+</p>
 
-<br/>
-<hr style="border:0; border-top:2px dashed #d4d4d8; margin:32px 0"/>
+<h3>Features Covered</h3>
+<ul>
+  <li>Signup using email and password</li>
+  <li>Login using email and password (JWT-based)</li>
+  <li>Login with Google (ID token verification)</li>
+  <li>Role-based protected routes</li>
+  <li>Optional authentication support</li>
+  <li>Correct HiSecure bootstrap with reset rules</li>
+</ul>
 
-<h2>📘 Part 4 — Full Example Snapshot</h2>
+<hr/>
 
-<p>This gives developers a quick glance at how the entire system fits together.</p>
+<h3>Application Bootstrap (server.js / app.js)</h3>
 
-<pre><code>// server.js
-require("dotenv").config();
-const express = require("express");
-const dbConnect = require("./config/db");
-const { HiSecure } = require("hi-secure");
+<pre><code>import express from "express";
+import dotenv from "dotenv";
+import { HiSecure } from "hi-secure";
+import authRoutes from "./routes/auth.routes.js";
 
-const app = express();
-const PORT = process.env.PORT || 3000;
+dotenv.config();
 
-dbConnect();
+const app = express();
 
-// ⭐ FORCE NEW INSTANCE WITH CORRECT CONFIG - if use HiSecure.jwt()  
 HiSecure.resetInstance();
 
 HiSecure.getInstance({
-    auth: {
-        enabled: true,
-        jwtSecret: process.env.JWT_SECRET || "supersecret123",
-        jwtExpiresIn: "1d",
-    }
+  auth: {
+    enabled: true,
+    jwtSecret: process.env.JWT_SECRET || "supersecret_32_chars_minimum",
+    jwtExpiresIn: "1d",
+    googleClientId: process.env.GOOGLE_CLIENT_ID
+  }
 });
 
-// if u don't use our jwt config 
-app.use(HiSecure.middleware('api')); // one line setup - along with this u use the HiSecure.validat() and HiSecure.hash() | HiSecure.verify() 
-
-//  Global middleware WITHOUT auth override
-app.use(
-    HiSecure.middleware({
-        cors: true,
-        rateLimit: "strict",
-        sanitize: true,
-        headers: true,
-        compression: true,
-        json: true
-    })
-);
+app.use(HiSecure.middleware("api"));
 
-//  ROUTES (call builder)
-const userRoutes = require("./routes/UserRoutes");
-app.use("/api/auth", userRoutes());
+app.use("/auth", authRoutes);
 
-app.listen(PORT, () => {
-    console.log(`🚀 Server running port ${PORT}`);
-});
-  
+app.listen(3000);
+</code></pre>
+
+<p>
+<em>Note:</em> <code>resetInstance()</code> is recommended only for tests or starter templates.
+It should not be used repeatedly in production runtime.
+</p>
+
+<hr/>
+
+<h3>Authentication Routes</h3>
+
+<pre><code>import { Router } from "express";
+import {
+  signup,
+  loginWithJwt,
+  loginWithGoogle
+} from "../controllers/auth.controller.js";
+import { HiSecure } from "hi-secure";
+
+const router = Router();
+
+router.post("/signup", signup);
+router.post("/login", loginWithJwt);
+router.post("/google", loginWithGoogle);
+
+router.get(
+  "/me",
+  HiSecure.auth(),
+  (req, res) => res.json({ user: req.user })
+);
+
+export default router;
 </code></pre>
 
+<hr/>
 
-<pre><code>// controller
-const { HiSecure } = require('hi-secure');
-const User = require("../models/User");
+<h3>Authentication Controllers</h3>
 
-const JWT_OPTIONS = {
-    issuer: 'hi-secure-backend',
-    audience: ['web-app', 'mobile-app'], // Array format
-    expiresIn: '7d',
-    subject: 'user-authentication'
-};
+<h4>Signup (Email and Password)</h4>
+
+<pre><code>import { HiSecure } from "hi-secure";
+import { HttpError } from "../core/errors/HttpError.js";
+import User from "../models/User.js";
+
+export const signup = async (req, res, next) => {
+  try {
+    const { email, password, name } = req.body;
 
-exports.registerUser = async(req, res) => {
-    try {
-        const { name, email, password } = req.body;
-
-        // Check if user exists
-        const existingUser = await User.findOne({ email });
-        if (existingUser) {
-            return res.status(400).json({
-                error: 'User already exists'
-            });
-        }
-
-        // Hash password
-        const hashedPassword = await HiSecure.hash(password);
-
-        // Create user
-        const user = await User.create({
-            name,
-            email,
-            password: hashedPassword
-        });
-
-        //  FIXED: JWT sign with ALL required options
-        const token = HiSecure.jwt.sign({
-                userId: user._id.toString(),
-                email: user.email,
-                name: user.name,
-                role: 'user'
-            },
-            JWT_OPTIONS
-        );
-
-        res.status(201).json({
-            message: 'User registered successfully',
-            token,
-            user: {
-                id: user._id,
-                name: user.name,
-                email: user.email
-            }
-        });
-
-    } catch (error) {
-        console.error('Registration error:', error);
-        res.status(500).json({
-            error: 'Registration failed',
-            details: error.message
-        });
+    if (!email || !password) {
+      throw HttpError.BadRequest("Email and password required");
     }
-};
 
-exports.loginUser = async(req, res) => {
-    try {
-        const { email, password } = req.body;
-
-        // Find user
-        const user = await User.findOne({ email });
-        if (!user) {
-            return res.status(401).json({
-                error: 'Invalid credentials'
-            });
-        }
-
-        // Verify password
-        const isValid = await HiSecure.verify(password, user.password);
-        if (!isValid) {
-            return res.status(401).json({
-                error: 'Invalid credentials'
-            });
-        }
-
-        //  FIXED: Same JWT options
-        const token = HiSecure.jwt.sign({
-                userId: user._id.toString(),
-                email: user.email,
-                name: user.name,
-                role: 'user'
-            },
-            JWT_OPTIONS
-        );
-
-        res.json({
-            message: 'Login successful',
-            token,
-            user: {
-                id: user._id,
-                name: user.name,
-                email: user.email
-            }
-        });
-
-    } catch (error) {
-        console.error('Login error:', error);
-        res.status(500).json({
-            error: 'Login failed',
-            details: error.message
-        });
+    const existing = await User.findOne({ email });
+    if (existing) {
+      throw HttpError.Conflict("User already exists");
     }
+
+    const passwordHash = await HiSecure.hash(password);
+
+    const user = await User.create({
+      email,
+      name,
+      passwordHash,
+      roles: ["user"],
+      provider: "local"
+    });
+
+    const token = HiSecure.jwt.sign({
+      userId: user.id,
+      roles: user.roles
+    });
+
+    res.status(201).json({ token, user });
+  } catch (err) {
+    next(err);
+  }
 };
+</code></pre>
 
-exports.getProfile = async(req, res) => {
-    try {
-        // req.user is set by HiSecure.auth() middleware
-        const user = await User.findById(req.user.userId).select('-password');
-
-        if (!user) {
-            return res.status(404).json({
-                error: 'User not found'
-            });
-        }
-
-        res.json({
-            message: 'Profile data',
-            user
-        });
-    } catch (error) {
-        console.error('Profile error:', error);
-        res.status(500).json({
-            error: 'Failed to fetch profile',
-            details: error.message
-        });
+<hr/>
+
+<h4>Login (Email and Password)</h4>
+
+<pre><code>export const loginWithJwt = async (req, res, next) => {
+  try {
+    const { email, password } = req.body;
+
+    const user = await User.findOne({ email });
+    if (!user || !user.passwordHash) {
+      throw HttpError.Unauthorized("Invalid credentials");
     }
+
+    const isValid = await HiSecure.verify(password, user.passwordHash);
+    if (!isValid) {
+      throw HttpError.Unauthorized("Invalid credentials");
+    }
+
+    const token = HiSecure.jwt.sign({
+      userId: user.id,
+      roles: user.roles
+    });
+
+    res.json({ token, user });
+  } catch (err) {
+    next(err);
+  }
 };
 </code></pre>
 
+<hr/>
 
-<pre><code>// routes
-const express = require('express');
-const { body } = require('express-validator');
-const { HiSecure } = require('hi-secure');
-const { registerUser, loginUser, getProfile } = require('../controllers/UserControllers');
-
+<h4>Login with Google</h4>
 
+<pre><code>export const loginWithGoogle = async (req, res, next) => {
+  try {
+    const { idToken } = req.body;
+    if (!idToken) {
+      throw HttpError.BadRequest("Google idToken required");
+    }
 
+    const googleUser = await HiSecure.jwt.google.verifyIdToken(idToken);
 
-module.exports = function buildRoutes() {
-    const router = express.Router();
+    if (!googleUser.email_verified) {
+      throw HttpError.Unauthorized("Google email not verified");
+    }
 
-    router.post(
-        '/register',
+    let user = await User.findOne({ email: googleUser.email });
 
-        HiSecure.validate([
-            body("name")
-            .notEmpty().withMessage("Name is required")
-            .isLength({ min: 3 }).withMessage("Name must be at least 3 characters"),
+    if (!user) {
+      user = await User.create({
+        email: googleUser.email,
+        name: googleUser.name,
+        provider: "google",
+        providerId: googleUser.sub,
+        roles: ["user"]
+      });
+    }
 
-            body("email")
-            .notEmpty().withMessage("Email is required")
-            .isEmail().withMessage("Invalid email format"),
+    const token = HiSecure.jwt.sign({
+      userId: user.id,
+      roles: user.roles
+    });
 
-            body("password")
-            .notEmpty().withMessage("Password is required")
-            .isLength({ min: 6 }).withMessage("Password must be at least 6 characters"),
-        ]),
+    res.json({ token, user });
+  } catch (err) {
+    next(err);
+  }
+};
+</code></pre>
 
-        registerUser
-    );
+<hr/>
 
-   
-    router.post(
-        '/login',
+<h3>Role-Based Protected Routes</h3>
 
-        HiSecure.validate([
-            body("email")
-            .notEmpty().withMessage("Email is required")
-            .isEmail().withMessage("Invalid email format"),
+<pre><code>app.get(
+  "/admin",
+  HiSecure.auth({ roles: ["admin"] }),
+  (req, res) => {
+    res.json({ message: "Welcome Admin" });
+  }
+);
+</code></pre>
 
-            body("password")
-            .notEmpty().withMessage("Password is required")
-        ]),
+<hr/>
 
-        // Apply rate limiter also
-        HiSecure.rateLimit({ max: 5, windowMs: 15 * 60 * 1000 }),
+<h3>JWT Options (Optional)</h3>
 
-        loginUser
-    );
+<p>
+HiSecure does not require JWT options for most use cases.
+Default configuration provided during initialization is sufficient.
+</p>
 
+<pre><code>HiSecure.getInstance({
+  auth: {
+    enabled: true,
+    jwtSecret: process.env.JWT_SECRET,
+    jwtExpiresIn: "1d"
+  }
+});
+</code></pre>
 
-    router.get(
-        '/profile',
-        HiSecure.auth({ required: true }),
-        getProfile
-    );
+<p>
+Advanced JWT options can be provided only when needed:
+</p>
 
-    return router;
-};
+<pre><code>HiSecure.jwt.sign(
+  {
+    userId: user.id,
+    roles: user.roles
+  },
+  {
+    issuer: "my-app",
+    audience: ["web", "mobile"],
+    subject: "user-auth",
+    expiresIn: "7d"
+  }
+);
 </code></pre>
 
-<br/>
-<hr style="border:0; border-top:2px dashed #d4d4d8; margin:32px 0"/>
+<p>
+JWT options are optional and intended for advanced authentication scenarios.
+</p>
+
+<hr/>
 
-<h2 align="center">📝 Additional Documentation</h2>
+<h3>Rules to Remember</h3>
+
+<ul>
+  <li>Initialize HiSecure once during application startup</li>
+  <li>Use resetInstance only for tests or starter templates</li>
+  <li>Do not initialize HiSecure inside controllers</li>
+  <li>Google login is used for identity verification only</li>
+  <li>Authorization is enforced using JWT payload and roles</li>
+</ul>
+
+<hr/>
+
+
+<h2>Summary</h2>
+
+<p>
+HiSecure provides a complete, opinionated security layer for Express.
+It focuses on correctness, safety and developer productivity.
+</p>
 
 <p align="center">
-We are actively working on extended documentation:<br/>
-<strong>Advanced patterns, RBAC examples, custom adapters, deployment setups & best practices.</strong>
+<strong>One dependency. One middleware. Complete security.</strong>
 </p>
 
-<p align="center"><i>Updates coming soon.</i></p>
+<hr/>
+
+<h2 align="center">Additional Documentation</h2>
+
+<p align="center">
+Advanced patterns, RBAC strategies, adapter extensions and deployment guides
+will be added over time.
+</p>