# 🔐 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._