@trap_stevo/veriauth/README.md

The ultimate authentication handshake engine for pairing devices and sessions with absolute precision. Empowering secure, modular client pairing with encrypted session key registration, trustless validation, and zero bootstrap dependencies. Designed for r

# 🔐 VeriAuth · Precision Session Pairing Engine

> The foundation of real-time encrypted communication begins with trust.  
> **VeriAuth** securely pairs client devices and sessions with cryptographic keys for ultra-reliable, bootstrapping-free communication using VeriPath and VeriLink.  
> Designed for modular security, identity-aware validation, and plug-and-play extensibility across any backend.

---


## 🚀 Features

- 🔑 Secure session-to-key pairing handshake  
- 🔒 No static secrets or bootstrapping required  
- 🧩 Pluggable key registration logic via `onKey()`  
- ⚙️ Optional session collision protection  
- 🔍 Extensible identity validation during pairing  
- 🔧 Framework-agnostic Express middleware

---


## 📦 Installation

```bash
npm install @trap_stevo/veriauth
```

---


## 🔧 Quick Start

```js
const express = require("express");

const { VeriAuth } = require("@trap_stevo/veriauth");

const { storageManager } = require("./src/HUDManagers/StorageManager.js");

const veriAuth = new VeriAuth({
      onKey: async (sessionID, keyBuffer, req) => {
            const user = req.user;
            
            if (!user?.id) throw new Error("Unauthenticated");
            
            await storageManager.setKey(sessionID, keyBuffer);
      },
      containsKey: async (sessionID) => {
            return await storageManager.hasKey(sessionID);
      },
      allowOverwrite: false
});

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

app.post("/pair", veriAuth.middleware());
```

---


## ✨ Client Pairing Example

```js
import axios from "axios";

async function pairDevice(linkInstance, authToken)
{
      const sessionKey = linkInstance.sessionKey.toString("base64");
      
      const sessionID  = linkInstance.sessionID;
      
      const res = await axios.post("http://localhost:8080/pair", {
            sessionKey
      }, {
            headers: {
                  "x-vlink-id" : sessionID,
                  "Authorization" : `Bearer ${authToken}`
            }
      });
      
      return res.data;
}
```

---


## 🧠 API Overview

### `new VeriAuth(options)`

Creates an instance of the pairing engine.

#### Required:
- `onKey(sessionID, keyBuffer, req)`  
   Custom key registration logic (e.g. store in memory, DB, LevelDB, etc.)

#### Optional:
- `containsKey(sessionID)`  
   Function to check for existing keys (for collision protection)

- `allowOverwrite: true | false`  
   Whether to allow overriding an existing session key (default: `false`)

---


### `veriAuth.middleware()`

Returns an Express-compatible middleware that accepts pairing requests containing:

- `x-vlink-id` in headers
- `sessionKey` in body (base64 string)

---


## 🔒 Best Practices

- Use this **after authentication** (e.g. via VeriKey) to ensure the session belongs to a trusted user
- Do **not** expose this to unauthenticated clients unless pairing is anonymous and bounded
- Avoid `allowOverwrite: true` unless you trust the source of `x-vlink-id` completely

---


## 📂 Example Payload

**POST** `/pair`

```json
Headers:
  x-vlink-id: vl-32c83f9...

Body:
{
  "sessionKey": "bXlFbmNyeXB0ZWRLZXk="
}
```

---


## 🧱 Use Cases

- Securely register ephemeral or persistent session keys  
- Enforce device pairing policies per user or group  
- Foundation for encrypted communication  
- Ideal for IoT or distributed app trust initialization

---


## 📜 License

See License in [LICENSE.md](./LICENSE.md)

_Designed for zero-compromise pairing and precise trust initialization._