# 🛡️ VeriPath · Legendary End-to-End Encrypted Routing Gateway

> The pinnacle of real-time encrypted routing and session-bound communication through a precision-crafted middleware system.  
> Empower secure, scalable interactions — from device APIs to private internal tools — and redefine how encrypted paths are governed across every layer of your application.  
> VeriPath handles dynamic decryption, encrypted response orchestration, and claim-aware routing — all in one seamless drop-in router.

---

## 🚀 Features

- 🔐 Automatic request decryption & response encryption  
- 🔄 Real-time session validation with secure key pairing  
- 🧠 Attestation-backed identity claims via session metadata  
- 🗃 Session key and ID persistence  
- ⚙️ Local key mutation for secure storage  
- 🔌 `.get()`, `.post()`, `.put()`, etc. with encrypted middleware stack  
- 🧩 Built-in pairing via `VeriAuth`  
- 🌐 Compatible with `VeriLink` browser gateway clients

---

## 📦 Installation

```bash
npm install @trap_stevo/veripath
```

---

## 🔧 Quick Start

```js
const { VeriPath } = require("@trap_stevo/veripath");

const express = require("express");

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

const vp = new VeriPath({
      persistSessionKey : false,
      persistSessionID  : false,
      enablePairing     : true,
      mutator           : "vlk",
      vaultSGN          : "vlx",
      linkSGN           : "vli"
});

vp.post("/create-user", async (req, res) => {
      const { username, email } = req.vData;
      res.vSend({ message : `User ${username} with email ${email} created.` });
});

vp.get("/fetch-profile", async (req, res) => {
      const { userID } = req.vData;
      res.vSend({ message : `Fetched profile for user ID: ${userID}` });
});

app.use("/", vp.router());

app.listen(12569, () => {
      console.log("🔐 VeriPath running at http://localhost:12569");
});
```

---

## 📘 API Specification

### 🛠 Configuration Options

| Property                 | Type                    | Description                                                                 |
|--------------------------|-------------------------|-----------------------------------------------------------------------------|
| `restoreSessionsPaths`   | `boolean`               | Restores previously stored session paths on startup. Default: `true`        |
| `persistSessionKey`      | `boolean`               | Enables session key persistence across restarts.                            |
| `persistSessionID`       | `boolean`               | Enables session ID persistence across restarts.                             |
| `mutator`                | `string` or `Uint8Array`| Mutator used for XOR obfuscation of session keys. Default: `"vlk"`          |
| `vaultSGN`               | `string`                | Storage key name for the encrypted session key. Default: `"vlx"`            |
| `linkSGN`                | `string`                | Storage key name for the session ID. Default: `"vli"`                       |
| `sessionIDExtractor`     | `function(req)`         | Optional custom extractor for session ID from the request.                  |
| `enablePairing`          | `boolean`               | Enables secure key-pairing route.                                           |
| `pairingGuard`           | `function(req,res,next)`| Optional middleware to guard the pairing route.                             |
| `pairingPath`            | `string`                | Path for the pairing route. Default: `"/device/pair"`                       |
| `veriAuthConfigurations` | `object`                | Optional config passed to `VeriAuth` constructor.                           |

---

### 📚 Instance Methods

| Method                                   | Description                                                                 |
|------------------------------------------|-----------------------------------------------------------------------------|
| `.get(path, ...handlers)`                | Registers encrypted GET route.                                              |
| `.post(path, ...handlers)`               | Registers encrypted POST route.                                             |
| `.put(path, ...handlers)`                | Registers encrypted PUT route.                                              |
| `.patch(path, ...handlers)`              | Registers encrypted PATCH route.                                            |
| `.delete(path, ...handlers)`             | Registers encrypted DELETE route.                                           |
| `.router()`                              | Returns the internal `express.Router()` instance.                           |
| `.enablePairingRoute(path, guard, conf)` | Registers a pairing route manually using `VeriAuth`.                        |

---

### 🔐 Request Helpers

These are injected into route handlers:

| Helper         | Type       | Description                                                   |
|----------------|------------|---------------------------------------------------------------|
| `req.vData`    | `object`   | Decrypted payload from the request (JSON body or query).      |
| `res.vSend()`  | `function` | Sends an encrypted response. Accepts a JSON-serializable object. |

---

## 🤝 Pairing Behavior

When `enablePairing = true`, VeriPath automatically adds a POST route (default: `/device/pair`) using [VeriAuth](https://www.npmjs.com/package/@trap_stevo/veriauth).

- Accepts a session key associated with a session ID.
- You may optionally guard this route with `pairingGuard` middleware.
- Pairing keys are stored in the vault and used to decrypt subsequent requests.

Example guard:

```js
(req, res, next) => {
      if (req.headers["x-admin-key"] !== "expected") return res.status(403).end();
      next();
}
```

---

## 🌐 Compatible Clients

| Client       | Purpose                                 |
|--------------|-----------------------------------------|
| `VeriLink`   | Encrypted browser/client-side communication |
| `VeriAuth`   | Handles session key registration and pairing |

---

## 🧱 Use Cases

- 🔐 Encrypted device-to-server communication  
- 🛡️ Internal dashboards secured by session-based identity  
- 🔄 Stateless APIs with stateful encrypted identity handling  
- 🧠 Claim-aware route control with seamless integration

---

## 📜 License

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

_Every path protected. Every byte encrypted. Every client verified._ 🔐