xypriss 9.0.13 → 9.1.1

package/__tests__/utils/cache.ts

@@ -0,0 +1,15 @@
+/**
+ * Simulated cache utility - like in the bug report
+ */
+import { SCC } from "xypriss-security";
+
+export const cache = new SCC({
+    strategy: "memory",
+    memory: {
+        maxSize: 100,
+        maxEntries: 10000,
+    },
+});
+
+// Auto-connect
+cache.connect();

package/__tests__/verify-network-plugins.sh

@@ -0,0 +1,248 @@
+#!/bin/bash
+
+# Manual Verification Test Script for Network Plugins
+# This script runs actual curl commands and shows you the results
+
+set -e
+
+# Colors
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+CYAN='\033[0;36m'
+MAGENTA='\033[0;35m'
+NC='\033[0m'
+BOLD='\033[1m'
+
+PORT=9999
+BASE_URL="http://localhost:$PORT"
+
+echo -e "${BOLD}${CYAN}"
+echo "╔════════════════════════════════════════════════════════════╗"
+echo "║   XyPriss Network Plugins - Manual Verification Tests     ║"
+echo "╚════════════════════════════════════════════════════════════╝"
+echo -e "${NC}"
+
+# Function to print section
+section() {
+    echo -e "\n${BOLD}${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+    echo -e "${BOLD}${CYAN}$1${NC}"
+    echo -e "${BOLD}${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}\n"
+}
+
+# Function to run test
+run_test() {
+    local name="$1"
+    local cmd="$2"
+    local check="$3"
+    
+    echo -e "${YELLOW}📝 Test:${NC} $name"
+    echo -e "${CYAN}Command:${NC} $cmd"
+    echo ""
+    
+    # Run the command
+    result=$(eval "$cmd" 2>&1)
+    
+    echo -e "${GREEN}Response:${NC}"
+    echo "$result" | head -n 50
+    
+    # Check if we should verify something
+    if [ -n "$check" ]; then
+        if echo "$result" | grep -q "$check"; then
+            echo -e "\n${GREEN}✓ Verification passed:${NC} Found '$check'"
+        else
+            echo -e "\n${RED}✗ Verification failed:${NC} Did not find '$check'"
+        fi
+    fi
+    
+    echo ""
+}
+
+# Wait for server to be ready
+echo -e "${YELLOW}⏳ Waiting for server to be ready...${NC}"
+sleep 2
+
+# Check if server is running
+if ! curl -s "$BASE_URL" > /dev/null 2>&1; then
+    echo -e "${RED}✗ Server is not running on port $PORT${NC}"
+    echo -e "${YELLOW}Please start the demo server first:${NC}"
+    echo -e "  bun __tests__/network-plugins-manual-demo.ts"
+    exit 1
+fi
+
+echo -e "${GREEN}✓ Server is ready!${NC}\n"
+
+# ============================================================================
+# TEST 1: Connection Plugin
+# ============================================================================
+section "TEST 1: Connection Plugin"
+
+run_test \
+    "Basic Connection Test" \
+    "curl -s '$BASE_URL/test/connection' | jq '.plugin, .status, .features'" \
+    "Connection Plugin"
+
+run_test \
+    "Check Keep-Alive Headers" \
+    "curl -v '$BASE_URL/test/connection' 2>&1 | grep -i 'connection:'" \
+    ""
+
+# ============================================================================
+# TEST 2: Compression Plugin
+# ============================================================================
+section "TEST 2: Compression Plugin"
+
+run_test \
+    "Small Response (No Compression Expected)" \
+    "curl -s -H 'Accept-Encoding: gzip' '$BASE_URL/test/compression' | jq '.plugin, .status, .note'" \
+    "Compression Plugin"
+
+echo -e "${YELLOW}📝 Test:${NC} Large Response (Compression Expected)"
+echo -e "${CYAN}Command:${NC} curl -v -H 'Accept-Encoding: gzip' '$BASE_URL/test/compression/large' 2>&1 | grep -i 'content-encoding'"
+echo ""
+
+compression_header=$(curl -v -H 'Accept-Encoding: gzip' "$BASE_URL/test/compression/large" 2>&1 | grep -i 'content-encoding:' || echo "No compression header found")
+
+echo -e "${GREEN}Response Headers:${NC}"
+echo "$compression_header"
+
+if echo "$compression_header" | grep -qi 'gzip\|br\|deflate'; then
+    echo -e "\n${GREEN}✓ Compression is working!${NC} Response is compressed"
+else
+    echo -e "\n${YELLOW}⚠ Compression header not found${NC} (might be handled by Bun runtime)"
+fi
+
+echo ""
+
+# Show size comparison
+echo -e "${YELLOW}📝 Test:${NC} Size Comparison (Compressed vs Uncompressed)"
+echo ""
+
+uncompressed_size=$(curl -s "$BASE_URL/test/compression/large" | wc -c)
+compressed_size=$(curl -s -H 'Accept-Encoding: gzip' "$BASE_URL/test/compression/large" | wc -c)
+
+echo -e "${CYAN}Uncompressed size:${NC} $uncompressed_size bytes"
+echo -e "${CYAN}Compressed size:${NC} $compressed_size bytes"
+
+if [ "$compressed_size" -lt "$uncompressed_size" ]; then
+    reduction=$((100 - (compressed_size * 100 / uncompressed_size)))
+    echo -e "${GREEN}✓ Compression working!${NC} Size reduced by ~${reduction}%"
+else
+    echo -e "${YELLOW}⚠ No size reduction detected${NC}"
+fi
+
+echo ""
+
+# ============================================================================
+# TEST 3: Rate Limiting Plugin
+# ============================================================================
+section "TEST 3: Rate Limiting Plugin"
+
+run_test \
+    "First Request (Should Succeed)" \
+    "curl -s '$BASE_URL/test/ratelimit' | jq '.plugin, .status, .requestNumber'" \
+    "Rate Limiting Plugin"
+
+echo -e "${YELLOW}📝 Test:${NC} Rate Limit Headers"
+echo -e "${CYAN}Command:${NC} curl -v '$BASE_URL/test/ratelimit' 2>&1 | grep -i 'ratelimit'"
+echo ""
+
+ratelimit_headers=$(curl -v "$BASE_URL/test/ratelimit" 2>&1 | grep -i 'ratelimit' || echo "No rate limit headers found")
+echo -e "${GREEN}Rate Limit Headers:${NC}"
+echo "$ratelimit_headers"
+echo ""
+
+echo -e "${YELLOW}📝 Test:${NC} Multiple Requests (Testing Rate Limiting)"
+echo -e "${CYAN}Sending 25 requests rapidly...${NC}"
+echo ""
+
+success_count=0
+limited_count=0
+
+for i in {1..25}; do
+    status=$(curl -s -o /dev/null -w "%{http_code}" "$BASE_URL/test/ratelimit")
+    if [ "$status" = "200" ]; then
+        echo -e "${GREEN}Request $i: 200 OK${NC}"
+        success_count=$((success_count + 1))
+    elif [ "$status" = "429" ]; then
+        echo -e "${RED}Request $i: 429 Too Many Requests (RATE LIMITED)${NC}"
+        limited_count=$((limited_count + 1))
+    else
+        echo -e "${YELLOW}Request $i: $status${NC}"
+    fi
+    sleep 0.1
+done
+
+echo ""
+echo -e "${CYAN}Results:${NC}"
+echo -e "  Successful: $success_count"
+echo -e "  Rate Limited: $limited_count"
+
+if [ "$limited_count" -gt 0 ]; then
+    echo -e "${GREEN}✓ Rate limiting is working!${NC}"
+else
+    echo -e "${YELLOW}⚠ No rate limiting detected${NC} (limit might be higher than 25)"
+fi
+
+echo ""
+
+# ============================================================================
+# TEST 4: All Plugins Together
+# ============================================================================
+section "TEST 4: All Plugins Combined"
+
+run_test \
+    "All Plugins Active" \
+    "curl -s -H 'Accept-Encoding: gzip' '$BASE_URL/test/all' | jq '.message, .plugins'" \
+    "Testing all network plugins"
+
+# ============================================================================
+# TEST 5: Headers Inspection
+# ============================================================================
+section "TEST 5: Headers Inspection"
+
+echo -e "${YELLOW}📝 Test:${NC} Full Response Headers"
+echo -e "${CYAN}Command:${NC} curl -v '$BASE_URL/test/headers' 2>&1 | grep '^<'"
+echo ""
+
+headers=$(curl -v "$BASE_URL/test/headers" 2>&1 | grep '^<' | head -n 20)
+echo -e "${GREEN}Response Headers:${NC}"
+echo "$headers"
+
+echo ""
+echo -e "${CYAN}Looking for plugin-specific headers:${NC}"
+echo "$headers" | grep -i 'content-encoding' && echo -e "${GREEN}✓ Compression header found${NC}" || echo -e "${YELLOW}⚠ No compression header${NC}"
+echo "$headers" | grep -i 'connection' && echo -e "${GREEN}✓ Connection header found${NC}" || echo -e "${YELLOW}⚠ No connection header${NC}"
+echo "$headers" | grep -i 'ratelimit' && echo -e "${GREEN}✓ Rate limit headers found${NC}" || echo -e "${YELLOW}⚠ No rate limit headers${NC}"
+
+echo ""
+
+# ============================================================================
+# TEST 6: Server Statistics
+# ============================================================================
+section "TEST 6: Server Statistics"
+
+run_test \
+    "Server Stats" \
+    "curl -s '$BASE_URL/stats' | jq '.plugins, .requests'" \
+    ""
+
+# ============================================================================
+# Summary
+# ============================================================================
+echo -e "\n${BOLD}${CYAN}"
+echo "╔════════════════════════════════════════════════════════════╗"
+echo "║                    Verification Complete                   ║"
+echo "╚════════════════════════════════════════════════════════════╝"
+echo -e "${NC}"
+
+echo -e "${GREEN}✓ All manual tests completed!${NC}\n"
+echo -e "${CYAN}Summary:${NC}"
+echo -e "  • Connection Plugin: Manages HTTP connections with keep-alive"
+echo -e "  • Compression Plugin: Compresses large responses (>100 bytes)"
+echo -e "  • Rate Limiting Plugin: Limits requests per IP (20/min)"
+echo -e "  • All plugins can work together simultaneously"
+echo ""
+echo -e "${YELLOW}💡 Tip:${NC} Review the output above to verify each plugin is working as expected"
+echo ""

package/__tests__/wildcard-cors.test.ts

@@ -0,0 +1,90 @@
+/**
+ * Tests for wildcard CORS functionality
+ */
+
+import { matchesWildcardPattern, isOriginAllowed, createWildcardOriginFunction } from "../src/server/utils/wildcardMatcher";
+
+describe("Wildcard CORS Functionality", () => {
+    describe("matchesWildcardPattern", () => {
+        test("should match localhost with port wildcard", () => {
+            expect(matchesWildcardPattern("http://localhost:3000", "localhost:*")).toBe(true);
+            expect(matchesWildcardPattern("http://localhost:8080", "localhost:*")).toBe(true);
+            expect(matchesWildcardPattern("https://localhost:443", "localhost:*")).toBe(true);
+        });
+
+        test("should match 127.0.0.1 with port wildcard", () => {
+            expect(matchesWildcardPattern("http://127.0.0.1:3000", "127.0.0.1:*")).toBe(true);
+            expect(matchesWildcardPattern("https://127.0.0.1:8080", "127.0.0.1:*")).toBe(true);
+        });
+
+        test("should match IPv6 localhost with port wildcard", () => {
+            expect(matchesWildcardPattern("http://[::1]:3000", "::1:*")).toBe(true);
+            expect(matchesWildcardPattern("https://[::1]:8080", "::1:*")).toBe(true);
+        });
+
+        test("should match subdomain wildcards", () => {
+            expect(matchesWildcardPattern("https://api.test.com", "*.test.com")).toBe(true);
+            expect(matchesWildcardPattern("https://app.test.com", "*.test.com")).toBe(true);
+            expect(matchesWildcardPattern("https://admin.test.com", "*.test.com")).toBe(true);
+        });
+
+        test("should not match different domains", () => {
+            expect(matchesWildcardPattern("http://example.com:3000", "localhost:*")).toBe(false);
+            expect(matchesWildcardPattern("https://malicious.com", "*.test.com")).toBe(false);
+        });
+
+        test("should handle exact matches without wildcards", () => {
+            expect(matchesWildcardPattern("https://example.com", "example.com")).toBe(true);
+            expect(matchesWildcardPattern("https://example.com", "different.com")).toBe(false);
+        });
+    });
+
+    describe("isOriginAllowed", () => {
+        const allowedOrigins = ["localhost:*", "127.0.0.1:*", "::1:*", "*.test.com"];
+
+        test("should allow origins matching wildcard patterns", () => {
+            expect(isOriginAllowed("http://localhost:3000", allowedOrigins)).toBe(true);
+            expect(isOriginAllowed("https://api.test.com", allowedOrigins)).toBe(true);
+            expect(isOriginAllowed("http://127.0.0.1:8080", allowedOrigins)).toBe(true);
+        });
+
+        test("should reject origins not matching patterns", () => {
+            expect(isOriginAllowed("https://malicious.com", allowedOrigins)).toBe(false);
+            expect(isOriginAllowed("http://example.com", allowedOrigins)).toBe(false);
+        });
+
+        test("should handle empty or invalid inputs", () => {
+            expect(isOriginAllowed("", allowedOrigins)).toBe(false);
+            expect(isOriginAllowed("http://localhost:3000", [])).toBe(false);
+        });
+    });
+
+    describe("createWildcardOriginFunction", () => {
+        const allowedOrigins = ["localhost:*", "*.test.com"];
+        const originFunction = createWildcardOriginFunction(allowedOrigins);
+
+        test("should allow matching origins via callback", (done) => {
+            originFunction("http://localhost:3000", (err, allowed) => {
+                expect(err).toBeNull();
+                expect(allowed).toBe(true);
+                done();
+            });
+        });
+
+        test("should reject non-matching origins via callback", (done) => {
+            originFunction("https://malicious.com", (err, allowed) => {
+                expect(err).toBeNull();
+                expect(allowed).toBe(false);
+                done();
+            });
+        });
+
+        test("should allow requests with no origin", (done) => {
+            originFunction(undefined, (err, allowed) => {
+                expect(err).toBeNull();
+                expect(allowed).toBe(true);
+                done();
+            });
+        });
+    });
+});

package/cache/.write_test

@@ -0,0 +1 @@
+test

package/docs/ENVIRONMENT_SHIELD.md

@@ -0,0 +1,68 @@
+# Environment Security Shield
+
+XyPriss features a military-grade **Environment Security Shield** designed to eliminate secret leakage and enforce robust application architecture.
+
+## Why the Shield?
+
+Traditional Node.js applications rely heavily on `process.env`. While convenient, this approach has several flaws:
+
+1. **Global Exposure**: Any third-party library or dependency can read `process.env`, potentially leaking your database credentials or API keys to malicious actors or telemetry services.
+2. **Accidental Logging**: Developers often log `process.env` during debugging, unintentionally printing sensitive secrets to stdout or cloud logs.
+3. **Implicit Dependencies**: Code becomes hard to test and maintain when it depends on global, mutable state.
+
+## How it Works
+
+XyPriss uses a native **System Proxy** to intercept all access to `process.env`.
+
+### 1. Zero-Dependency DotEnv Loading
+
+XyPriss includes a built-in, ultra-fast `.env` loader. It automatically looks for and merges the following files (in order of priority):
+
+- `.private/.env`
+- `.env.local`
+- `.env`
+
+**Note:** You no longer need `require('dotenv').config()` or any external environment loaders.
+
+### 2. Variable Masking
+
+When code attempts to read from `process.env`, the shield performs a security check:
+
+- **Whitelisted core variables** (e.g., `NODE_ENV`, `PATH`, `PORT`, `TERM`) are returned normally.
+- **Project-prefixed variables** (starting with `XYPRISS_`, `XY_`, `ENC_`, or `DOTENV_`) are returned normally.
+- **All other variables** return `undefined` and trigger a security warning in the console.
+
+### 3. The Official API
+
+To access your application variables, use the system-managed environment manager:
+
+```typescript
+// ❌ Discouraged
+const apiKey = process.env.MY_API_KEY;
+
+// ✅ Recommended
+const apiKey = __sys__.__env__.get("MY_API_KEY");
+```
+
+## Configuration Whitelist
+
+The following variables are always accessible directly via `process.env` to ensure system and runtime stability:
+
+| Variable    | Description                           |
+| ----------- | ------------------------------------- |
+| `NODE_ENV`  | Current runtime environment           |
+| `PORT`      | Standard listening port               |
+| `PATH`      | System execution paths                |
+| `USER`      | Current system user                   |
+| `HOME`      | User home directory                   |
+| `LANG`      | System language/locale                |
+| `COLORTERM` | Terminal color support                |
+| `XYPRISS_*` | All official framework configurations |
+| `ENC_*`     | Encryption keys and seeds             |
+
+## Best Practices
+
+1. **Use Prefixes**: For environment variables that MUST be accessed by legacy libraries, prefix them with `XYPRISS_`.
+2. **Standardize Access**: Use `__sys__.__env__.get()` everywhere in your business logic.
+3. **Use .private/.env**: This file is automatically loaded and is the ideal place for hardware-local secrets that should never be committed to version control.
+

package/docs/README.md

@@ -0,0 +1,49 @@
+# XyPriss XHSC Subsystem Documentation
+
+The **XyPriss Hyper-System Core (XHSC)** is the high-performance heart of XyPriss. It enables native networking, process management (clustering), and advanced traffic guardrails.
+
+## Cluster Documentation
+
+- **[Cluster Overview](./cluster-overview.md)**: High-level architecture and hybrid master/worker design.
+- **[Configuration Guide](./cluster-configuration-guide.md)**: Details on scaling, strategies, and resource limits.
+- **[Performance Tuning](./cluster-performance-tuning-updated.md)**: Optimization strategies for CPU and I/O bound workloads.
+
+## Core Features
+
+- **[XHSC Core Details](./XHSC_CORE.md)**: In-depth look at routing (Radix Trie), native telemetry, and native concurrency control.
+- **[Network Quality Guardrails](./cluster-configuration-guide.md#network-quality--guardrails)**: Protecting your server from slow connections and traffic spikes.
+- **[Environment Security Shield](./ENVIRONMENT_SHIELD.md)**: Built-in .env loading and mission-critical process.env protection.
+
+## Configuration Quick-Start (Honest Implementation)
+
+```typescript
+import { createServer } from "xypriss";
+
+const app = createServer({
+    cluster: {
+        enabled: true, // Enable XHSC clustering
+        workers: "auto", // 1 per physical thread
+        strategy: "least-connections",
+    },
+    requestManagement: {
+        networkQuality: {
+            enabled: true,
+            rejectOnPoorConnection: true,
+            maxLatency: 500,
+        },
+    },
+});
+
+await app.start(3000);
+```
+
+## Current Capabilities
+
+- ✅ **Hybrid Clustering**: Go master + JS workers.
+- ✅ **Advanced Load Balancing**: 6 different distribution strategies.
+- ✅ **Native Concurrency**: Per-IP and server-wide limits managed in Rust.
+- ✅ **Resource Guardrails**: Per-worker CPU and Memory limits.
+- ✅ **Native Circuit Breakers**: Fail-fast protection.
+- 🚧 **Auto-Scaling**: Planned for a future release (not currently available).
+- 🚧 **Dynamic Health Endpoints**: Basic health checks are internal; custom endpoints are planned.
+

package/docs/XEMS_TUTORIAL.md

@@ -0,0 +1,205 @@
+# Building Secure Sessions with XEMS
+
+This tutorial walks through how to use the **XyPriss Encrypted Memory Store (XEMS)** to build high-security authentication systems from the ground up. XEMS is designed to outperform traditional database and Redis-backed sessions by offering hardware-bound encryption, automatic token rotation, and zero-network-overhead storage.
+
+---
+
+## 1. Why XEMS?
+
+Traditional session management relies on a static token (Session ID). If that token is intercepted, the session is fully compromised until it expires — which could be hours or days later.
+
+XEMS addresses this with a **Moving Target Defense** architecture:
+
+- **Atomic Rotation** — Every request produces a new token. Stolen tokens expire after a single use.
+- **Hardware Binding** — Sessions are cryptographically tied to the physical server's identity. Data cannot be decrypted on another machine.
+- **Sidecar Isolation** — All data lives in a dedicated, high-speed Go subprocess, completely isolated from your application's memory space.
+- **Automatic Retention** — Records are purged after a maximum of 5 days, ensuring no long-term traces accumulate on the server.
+
+### XEMS vs. Traditional Session Strategies
+
+| Feature              | LocalStorage / Cookies   | Redis / Database             | XEMS (XyPriss)                 |
+| :------------------- | :----------------------- | :--------------------------- | :----------------------------- |
+| **Data Location**    | Client-side (vulnerable) | Server-side (shared/network) | Isolated sidecar (native)      |
+| **Token Security**   | Static, persistent       | Static, persistent           | Rotated per request            |
+| **Hijacking Window** | Days or weeks            | Hours or days                | Single request (< 1s)          |
+| **Retention Policy** | Indefinite               | Manual cleanup required      | Automatic (max 5 days)         |
+| **Performance**      | Fast                     | Network overhead             | Direct IPC (near zero latency) |
+
+---
+
+## 2. API Architectures
+
+XyPriss exposes two interfaces for interacting with XEMS, each suited to different use cases.
+
+### A. The `xLink` API — High-Level Web Authentication
+
+Best suited for: user sessions, multi-step forms, and automated cookie management.
+
+`xLink` handles token generation, rotation, and HTTP transport (cookies and headers) automatically. You create or consume a session in a single call and let the framework manage the rest.
+
+### B. The `xems` Fluent API — Programmatic Storage
+
+Best suited for: secure caching, stable user record lookups, and internal security logic.
+
+Exported directly from `xypriss`, this API uses a fluent, sandbox-scoped approach to keep operations explicit and isolated:
+
+```ts
+xems.from(sandbox).set(key, value, ttl?)
+xems.from(sandbox).get(key)
+```
+
+> **Note for Multi-Server:** In multi-server environments, each server instance has its own isolated XEMS process. Use `res.xLink` or `req.app.xems` (or `xems.forApp(app)`) to ensure you are interacting with the correct server's store.
+
+---
+
+## 3. Working with Multi-Server
+
+When using the `multiServer` configuration, XyPriss creates isolated environments for each server instance. This extends to XEMS, ensuring that session data for one server (e.g., an API) is completely invisible to another (e.g., a static assets server).
+
+### Accessing the correct XEMS instance
+
+If you are writing shared route handlers or middleware, you should avoid using the global `xems` import and instead use the instance attached to the current `app`:
+
+```typescript
+// ❌ Avoid in multi-server
+import { xems } from "xypriss";
+await xems.from("users").get(id);
+
+// ✅ Correct: Use the server-specific instance
+app.get("/api/user", async (req, res) => {
+    const serverXems = req.app.xems;
+    // OR
+    const serverXems = xems.forApp(req.app);
+
+    const data = await serverXems.from("users").get(req.query.id);
+});
+```
+
+### Exporting for non-request contexts
+
+If you need to use XEMS outside of a request handler (e.g., in a background task), you can export the instance after the app is initialized:
+
+```typescript
+const app = createServer({
+    /* ... */
+});
+export const apiXems = xems.forApp(app);
+```
+
+---
+
+## 4. Real-World Implementation
+
+The following examples demonstrate a complete authentication flow using both APIs.
+
+### Server Configuration
+
+```typescript
+import { createServer } from "xypriss";
+
+const SESSION_SANDBOX = "auth-active";
+const USERS_SANDBOX = "users-registry";
+
+const app = createServer({
+    server: {
+        xems: {
+            enable: true,
+            sandbox: SESSION_SANDBOX, // Default sandbox for xLink sessions
+            ttl: "1h", // Session lifetime
+            autoRotation: true,
+            persistence: {
+                enabled: true,
+                secret: "8f2d6c1b9a5e4f0d3c7b2a1e6d9f8c0b", // Must be exactly 32 bytes
+                path: "./.private/vault",
+            },
+        },
+    },
+});
+```
+
+### Registration — Stable Storage and Session Creation
+
+The `xems` programmatic API lets you store user records securely without an external database for ephemeral or temporary users.
+
+```typescript
+import { xems } from "xypriss";
+
+app.post("/auth/register", async (req, res) => {
+    const { email, password, name } = req.body;
+    const userKey = `user:${hash(email)}`; // Deterministic, stable lookup key
+
+    // Store user data in a dedicated, long-lived sandbox
+    await xems
+        .from(USERS_SANDBOX)
+        .set(userKey, JSON.stringify({ name, email, pass: hash(password) }));
+
+    // Create a rotating session and inject the token via xLink
+    await res.xLink({ email, role: "user" }, SESSION_SANDBOX);
+
+    res.json({ success: true });
+});
+```
+
+### Logout — Complete Session Invalidation
+
+When a user logs out, `xUnlink()` must be called explicitly. It performs a three-step teardown: removing the entry from the Go memory store, clearing the `HttpOnly` cookie, and stripping any session-related response headers.
+
+```typescript
+app.post("/auth/logout", async (req, res) => {
+    await res.xUnlink();
+    res.json({ success: true });
+});
+```
+
+Failing to call `xUnlink()` on logout leaves a valid (though short-lived) token in circulation until the next rotation cycle.
+
+---
+
+## 4. Frontend Integration
+
+Because XyPriss uses `HttpOnly` cookies, the frontend never has direct access to the session token — rotation happens transparently between the browser and the server. This eliminates an entire category of client-side token theft.
+
+The only requirement on the frontend is ensuring credentials are included with every request:
+
+```typescript
+// api.ts
+const api = axios.create({
+    baseURL: "/api",
+    withCredentials: true, // Required for HttpOnly cookie transport
+});
+```
+
+Two rules to enforce across your frontend codebase:
+
+- Always set `withCredentials: true` (or `credentials: "include"` for native `fetch`).
+- Never store an XEMS token in `localStorage` or `sessionStorage`. The browser and XyPriss handle all token management — your code should never touch it.
+
+---
+
+## 5. XEMS as a Temporary Data Store
+
+Beyond session management, XEMS is well suited as a secure, ephemeral data layer for short-lived workflows.
+
+Practical applications include multi-step registration flows, one-time passwords (OTP), email verification states, and transient guest profiles. Any data that is inherently temporary and security-sensitive is a strong candidate.
+
+```typescript
+// Store a pending OTP with a 15-minute TTL
+await xems.from("otp-pending").set(`otp:${hash(email)}`, otpCode, "15m");
+```
+
+Data stored this way is automatically purged when the TTL expires, or at the latest after the 5-day global retention ceiling — no manual cleanup required.
+
+---
+
+## 6. Best Practices
+
+**Sandbox isolation.** Keep authentication sessions, user records, and application caches in separate sandboxes. Isolation is enforced cryptographically, not just logically.
+
+**Explicit invalidation on sensitive events.** Token rotation protects against passive hijacking, but for high-impact actions (password reset, privilege escalation, suspicious activity detection), always call `res.xUnlink()` and force re-authentication.
+
+**Secret hygiene.** The persistence secret must be exactly 32 bytes and generated with a cryptographically secure random source. Do not derive it from user input, application names, or any guessable value. Treat it with the same care as a private key.
+
+---
+
+_Copyright © 2026 Nehonix Team. All rights reserved._
+