🛡️ VeriKey · Legendary Hybrid Authentication

The pinnacle of legendary authentication through a hybrid, precision-crafted access system built for real-time protection, dynamic client validation, and seamless token orchestration.
Secure every route with scalable, token-backed control. Adapt effortlessly to evolving security demands across any application layer.

🚀 Features

• 🔐 Hybrid header + token-based authentication
• ⚡ Real-time client validation
• 🧠 Contextual claim injection
• 🗃 Persistent client identity via LevelDB
• ⚙️ Fully extensible configuration per client
• 🔄 Runtime instance configuration control
• 📁 Client grouping via appName and configName
• 🧩 Drop-in middleware for route protection

📦 Installation

npm install @trap_stevo/verikey

🔧 Quick Start

const express = require("express");
const { VeriKey, VeriGuard } = require("@trap_stevo/verikey");

VeriKey.enablePersistence("./verikey-db");

(async () => {
      await VeriKey.addClient("MyApp", "ProdConfig", "frontend-client", {
            baseSecret : "super-secret",
            headers : { "x-access" : "super-secret" },
            useStrictMode : false,
            jwtSecret : "custom-jwt-secret",
            jwtExpiresIn : "1h",
            refreshTokenEnabled : true,
            refreshTokenTTL : "7d",
            refreshRotation : true
      });
})();

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

app.post("/auth", async (req, res) => {
      const result = await VeriKey.verifyClientAccess("frontend-client", req);
      if (!result.success) return res.status(result.code).json({ message : result.message });
      res.json({ token : result.token, refreshToken : result.refreshToken });
});

app.post("/auth/refresh", async (req, res) => {
      const { clientID, refreshToken } = req.body;
      const result = VeriKey.verifyRefreshToken(clientID, refreshToken);
      if (!result.success) return res.status(401).json({ message : result.message });
      res.json({ token : result.token, refreshToken : result.refreshToken });
});

app.get("/secure", VeriGuard(), (req, res) => {
      res.json({ message : "Access granted!", claims : req.clientClaims });
});

🔑 API Overview

VeriKey.addClient(appName, configName, clientID, options)

Registers a new client with optional JWT settings, headers, IP restrictions, and optional namespace.

VeriKey.verifyClientAccess(clientID, req)

Validates a client’s credentials and generates a token (and refresh token if enabled).

VeriKey.verifyRefreshToken(clientID, refreshToken)

Verifies and rotates a refresh token to issue a new token (and new refresh token if rotation is enabled).

VeriKey.verifyClientJWT(clientID, token)

Validates an issued token using the client’s configuration.

VeriKey.enablePersistence(dbPath)

Enables persistent client storage at the provided path.

VeriKey.disablePersistence()

Disables persistence and safely closes the database.

VeriKey.setInstanceConfig(config)

Globally updates VeriKey configuration (e.g. defaultNamespace, refreshCleanupInterval).

VeriKey.getClientsByApp(appName) / VeriKey.getClientsByConfig(configName)

Filters and retrieves clients by grouping metadata.

VeriKey.getClientsByNamespace(namespace)

Returns clients registered under the specified namespace.

VeriKey.listNamespaces()

Lists all active namespaces stored in persistent mode.

VeriKey.deleteNamespace(namespace)

Deletes all clients under a given namespace (from memory and disk).

VeriGuard(options)

Express middleware for protecting routes using JWT tokens. Accepts { clientID } or reads from x-client-id header.

🛠 Configuration Options

{
      baseSecret           : "string",          // Used for HMAC or plain secret validation
      headers              : { key: value },    // Header name and value
      useStrictMode        : true | false,      // Compare against derived HMAC if true
      ipWhitelist          : [ "x.x.x.x" ],
      ipBlacklist          : [ "y.y.y.y" ],
      jwtEnabled           : true | false,
      jwtSecret            : "jwt-secret-key",
      jwtExpiresIn         : "30m",             // 1s, 1m, 1h, 1w, 1mo, 1d, 1y, 1dec, 1gen, 1cen, ...
      jwtAlgorithm         : "HS256",
      jwtInjectClaims      : (req, clientID) => ({ ... }),
      refreshTokenEnabled  : true | false,
      refreshTokenTTL      : "7d",
      refreshRotation      : true | false       // If true, old refresh tokens revoke on use
}

📂 Persistent Storage

VeriKey supports persistent client authentication across restarts, allowing full recovery of registered clients and their configurations.

✅ Enable Persistence

VeriKey.enablePersistence("./verikey-db");

This activates persistent storage using the provided path. Clients added afterward are retained between application restarts automatically.

🧠 Namespace Support

You can group clients into isolated scopes using namespaces:

await VeriKey.addClient("MyApp", "ProdConfig", "admin-panel", {
      namespace : "internal"
});

Set a default namespace globally:

VeriKey.setInstanceConfig({
      defaultNamespace : "internal"
});

🔁 Disable Persistence

To turn off persistence and cleanly unload stored data:

await VeriKey.disablePersistence();

🔍 Namespace Tools

await VeriKey.listNamespaces();            // → [ "internal", "partner", "admin" ]
await VeriKey.getClientsByNamespace("internal");
await VeriKey.deleteNamespace("partner");  // ⚠ Removes all clients under "partner"

Seamless, scoped, and storage-aware — VeriKey adapts to any scale or architecture 🔐

🧪 Example Curl Usage

# Authenticate and receive token
curl -X POST http://localhost:3000/auth \
  -H "x-access: super-secret" \
  -H "Content-Type: application/json" \
  -d '{}'

# Access secure route
curl -X GET http://localhost:3000/secure \
  -H "Authorization: Bearer <your-token>" \
  -H "x-client-id: frontend-client"

🧱 Use Cases

• Secure multi-client apps with isolated auth logic
• Protect internal services and dashboards
• Grant tiered access via injected claims
• Track identity persistently across service boundaries

📜 License

See License in LICENSE.md

Engineered for real-time protection and unmatched flexibility.