post-armor 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Evelocore
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,143 @@
+<div align="center">
+  <img src="https://cdn.evelocore.com/files/Evelocore/projects/post-armor/icon.png" alt="PostArmor Logo" width="200" height="200">
+
+</div>
+
+# PostArmor 🛡️
+
+[![npm version](https://badge.fury.io/js/post-armor.svg)](https://badge.fury.io/js/post-armor)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**PostArmor** is a zero-dependency, isomorphic security middleware designed to armor your API requests with time-locked encryption and binary obfuscation. It ensures your API requests are valid only within a specific time window and protects the payload from casual inspection.
+
+Works seamlessly in:
+- ✅ **Node.js** (Express, Nest, Hono, etc.)
+- ✅ **Browsers** (React, Vue, Svelte, Angular, Vanilla JS)
+
+## ✨ Features
+
+- **⏳ Time-Locked Validation**: prevent replay attacks by validating requests only within a short time window (default: 5s).
+- **🔒 Binary Obfuscation**: Payload is converted to a binary stream and XOR-encrypted to prevent easy reading in the Network tab.
+- **📦 Zero Dependencies**: Lightweight and fast. No `Buffer` or `Express` runtime dependencies in the client bundle.
+- **🌍 Isomorphic**: Import the same package in your backend and frontend.
+
+---
+
+## 📦 Installation
+
+```bash
+npm install post-armor
+```
+
+---
+
+## 🚀 Usage
+
+### 1. Server-Side (Node.js + Express)
+
+Wrap your protected endpoint with the `postArmor` middleware. This adds a `res.return()` method to send armored responses back.
+
+> **Important**: You must use a raw body parser so PostArmor can handle the binary decoding itself.
+
+```typescript
+import express from "express";
+import { postArmor } from "post-armor";
+
+const app = express();
+
+// 1. Allow PostArmor to handle binary streams
+app.use(express.raw({ type: "application/octet-stream" }));
+
+// 2. Configure the Guard
+const armorGate = postArmor({
+    key: "YOUR_SECRET_KEY", // Must match client key
+    delay: 5,               // Allowed time difference in seconds
+    strict: true            // Enforce strict response typing
+});
+
+// 3. Protect your route
+app.post("/secure-api", armorGate, (req, res) => {
+    // req.body is automatically decoded to a JSON object here
+    console.log("Received:", req.body);
+    
+    // Send an armored response back
+    res.return("object", { success: true, message: "Secure data" });
+});
+
+app.listen(3000, () => console.log("Server running"));
+```
+
+#### TypeScript Support (Express)
+To get IntelliSense for `res.return`, add this to your `types.d.ts` or main server file:
+
+```typescript
+declare global {
+    namespace Express {
+        interface Response {
+            return: (type: "string" | "number" | "boolean" | "object" | "any", body: any) => void;
+        }
+    }
+}
+```
+
+### 2. Client-Side (React / Vue / Browser)
+
+Use `armoredPost` to send secure requests. This is a wrapper around `fetch` that handles the encryption/decryption handshake.
+
+```typescript
+import { armoredPost } from "post-armor";
+
+async function sendData() {
+    try {
+        const response = await armoredPost({
+            url: "http://localhost:3000/secure-api",
+            key: "YOUR_SECRET_KEY", // Must match server key
+            body: { secret: "data" }
+        });
+
+        if (response.ok) {
+            console.log("Server Response:", response.body);
+        } else {
+            console.error("Error:", response.statusText);
+        }
+    } catch (err) {
+        console.error("Request failed:", err);
+    }
+}
+```
+
+---
+
+## ⚙️ Configuration
+
+### Server: `postArmor(config)`
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `key` | `string` | **Required** | Shared secret key for encryption. |
+| `delay` | `number` | `5` | Validity window in seconds. |
+| `strict` | `boolean` | `true` | Enforce strict type checking on `res.return`. |
+| `headerName` | `string` | `"post-armor-token"` | Custom header name for the secure token. |
+| `sourceName` | `string` | `"post-armor"` | Custom source name in payload metadata. |
+
+### Client: `armoredPost(options)`
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `url` | `string` | **Required** | Target API URL. |
+| `key` | `string` | **Required** | Shared secret key. |
+| `body` | `any` | **Required** | JSON payload to send. |
+| `headers` | `object` | `{}` | Additional headers to include. |
+| `headerName` | `string` | `"post-armor-token"` | Custom header name. |
+
+---
+
+## 🛡️ How it works
+1.  **Client** generates a timestamp, encrypts it with the `key`, and sends it in a header.
+2.  **Client** encrypts requests body to a binary stream.
+3.  **Server** validates the header timestamp is within the `delay` window (preventing replays).
+4.  **Server** decrypts binary body to JSON.
+5.  **Response** follows the same encrypted path back to the client.
+
+## License
+MIT

package/dist/post-armor.d.ts

@@ -0,0 +1,42 @@
+export declare function getTimestamp(): string;
+export declare function getSecureToken(key: string): string;
+export declare function validateToken(token: string | undefined, key: string, delay?: number): boolean;
+export interface SecurePostOptions {
+    url: string;
+    headers?: Record<string, string>;
+    body: any;
+    key: string;
+    headerName?: string;
+    sourceName?: string;
+}
+/**
+ * Sends a secure POST request with the given options.
+ * @param options The options for the request.
+ * @returns A Promise that resolves to the response from the server.
+ */
+export declare function armoredPost({ url, headers, body, key, headerName, sourceName, }: SecurePostOptions): Promise<{
+    status: number;
+    statusText: string;
+    body: undefined;
+    type: "string" | "number" | "bigint" | "boolean" | "symbol" | "undefined" | "object" | "function";
+    ok: boolean;
+    url: string;
+    redirected: boolean;
+    headers: Headers;
+}>;
+/**
+ * Configuration for PostArmor middleware.
+ */
+export interface PostArmorConfig {
+    key: string;
+    delay?: number;
+    strict?: boolean;
+    headerName?: string;
+    sourceName?: string;
+}
+/**
+ * Creates a PostArmor middleware instance with the given configuration.
+ * This middleware is built using Web Standards and can be safely included in
+ * browser bundles without causing errors.
+ */
+export declare function postArmor(config: PostArmorConfig): (req: any, res: any, next: any) => void;

package/dist/post-armor.js

@@ -0,0 +1,201 @@
+const LIB_VERSION = "1.0.0";
+export function getTimestamp() {
+    const date = new Date();
+    return date
+        .toLocaleTimeString("en-GB", {
+        timeZone: "Asia/Kolkata",
+        hour12: false,
+        hour: "2-digit",
+        minute: "2-digit",
+        second: "2-digit",
+    })
+        .replace(/:/g, ""); // Returns "HHmmss"
+}
+function encryptTime(time, key) {
+    let encrypted = "";
+    for (let i = 0; i < time.length; i++) {
+        const charCode = time.charCodeAt(i) ^ key.charCodeAt(i % key.length);
+        encrypted += String.fromCharCode(charCode);
+    }
+    const random1 = Math.random().toString(36).substring(2, 7);
+    const random2 = Math.random().toString(36).substring(2, 7);
+    // Reverse the XOR result
+    encrypted = encrypted.split("").reverse().join("");
+    // Combine with random salts and encode to Base64 (stripping padding)
+    return btoa(random1 + encrypted + random2).replace(/=/g, "");
+}
+function decryptTime(raw, key) {
+    if (raw.length < 10)
+        return "";
+    let encrypted = raw.substring(5, raw.length - 5);
+    encrypted = encrypted.split("").reverse().join("");
+    let decrypted = "";
+    for (let i = 0; i < encrypted.length; i++) {
+        decrypted += String.fromCharCode(encrypted.charCodeAt(i) ^ key.charCodeAt(i % key.length));
+    }
+    return decrypted;
+}
+export function getSecureToken(key) {
+    const time = getTimestamp();
+    return encryptTime(time, key);
+}
+export function validateToken(token, key, delay = 5) {
+    try {
+        if (!token)
+            return false;
+        // Restore Base64 padding if missing
+        const paddedToken = token.padEnd(token.length + ((4 - (token.length % 4)) % 4), "=");
+        const raw = atob(paddedToken);
+        const decryptedTime = decryptTime(raw, key);
+        if (decryptedTime.length !== 6)
+            return false;
+        const serverTime = getTimestamp();
+        const toSeconds = (t) => {
+            const h = parseInt(t.substring(0, 2), 10);
+            const m = parseInt(t.substring(2, 4), 10);
+            const s = parseInt(t.substring(4, 6), 10);
+            return h * 3600 + m * 60 + s;
+        };
+        const serverSec = toSeconds(serverTime);
+        const clientSec = toSeconds(decryptedTime);
+        let diff = serverSec - clientSec;
+        // Handle midnight wrap-around
+        if (diff < -80000)
+            diff += 86400;
+        if (diff > 80000)
+            diff -= 86400;
+        return Math.abs(diff) <= delay;
+    }
+    catch (e) {
+        console.error("Token validation error:", e?.message);
+        return false;
+    }
+}
+/**
+ * Sends a secure POST request with the given options.
+ * @param options The options for the request.
+ * @returns A Promise that resolves to the response from the server.
+ */
+export async function armoredPost({ url, headers = {}, body, key, headerName = "post-armor-token", sourceName = "post-armor", }) {
+    const _headers = {
+        ...headers,
+        "Content-Type": "application/octet-stream",
+        [headerName]: getSecureToken(key),
+    };
+    const encoder = new TextEncoder();
+    const _body = encoder.encode(JSON.stringify({
+        body,
+        _: {
+            source: sourceName,
+            version: LIB_VERSION,
+        },
+    }));
+    const response = await fetch(url, {
+        method: "POST",
+        headers: _headers,
+        body: _body,
+    });
+    let received = {
+        body: undefined,
+        type: "undefined",
+        _: {
+            source: "",
+            version: "",
+        },
+    };
+    if (response.status == 200) {
+        const buffer = await response.arrayBuffer();
+        const decoder = new TextDecoder();
+        const text = decoder.decode(buffer);
+        try {
+            received = JSON.parse(text);
+        }
+        catch (e) {
+            throw new Error("Failed to parse armored response");
+        }
+        if (received._?.source !== sourceName || received._?.version !== LIB_VERSION) {
+            throw new Error(`Invalid response source: expected ${sourceName}, got ${received._?.source}`);
+        }
+    }
+    return {
+        status: response.status,
+        statusText: response.statusText,
+        body: received.body || undefined,
+        type: typeof received.body,
+        ok: response.ok,
+        url: response.url,
+        redirected: response.redirected,
+        headers: response.headers,
+    };
+}
+/**
+ * Creates a PostArmor middleware instance with the given configuration.
+ * This middleware is built using Web Standards and can be safely included in
+ * browser bundles without causing errors.
+ */
+export function postArmor(config) {
+    const KEY = config.key;
+    const MAX_DELAY = config.delay ?? 5;
+    const IS_STRICT = config.strict ?? true;
+    const HEADER_NAME = (config.headerName || "post-armor-token").toLowerCase();
+    const SOURCE_NAME = config.sourceName || "post-armor";
+    if (!KEY) {
+        throw new Error("PostArmor: config.key is required");
+    }
+    // Using 'any' for types here to avoid importing 'express' which breaks browser builds.
+    // The behavior remains identical when used in an Express app.
+    return (req, res, next) => {
+        try {
+            const token = req.headers[HEADER_NAME];
+            if (!validateToken(token, KEY, MAX_DELAY)) {
+                console.warn(`[PostArmor] Invalid or expired token for header ${HEADER_NAME}`);
+                res.status(401).json({ error: "Unauthorized: Invalid secure token" });
+                return;
+            }
+            if (!req.body || (req.body instanceof Uint8Array && req.body.length === 0)) {
+                res.status(400).json({ error: "Missing request body" });
+                return;
+            }
+            let received;
+            try {
+                // Buffer is replaced by Uint8Array and TextDecoder for universal compatibility
+                const decodedBody = typeof req.body === "string"
+                    ? req.body
+                    : (req.body instanceof Uint8Array || (typeof Buffer !== "undefined" && Buffer.isBuffer(req.body)))
+                        ? new TextDecoder().decode(req.body)
+                        : JSON.stringify(req.body);
+                received = JSON.parse(decodedBody);
+            }
+            catch (e) {
+                res.status(400).json({ error: "Malformed request payload" });
+                return;
+            }
+            if (!received._ || received._.source !== SOURCE_NAME) {
+                res.status(400).json({ error: "Invalid request source" });
+                return;
+            }
+            // Replace body with actual payload
+            req.body = received.body;
+            // Custom responder
+            res.return = (type, body) => {
+                if (IS_STRICT && type !== "any" && typeof body !== type) {
+                    throw new Error(`Invalid response type: expected ${type}, got ${typeof body}`);
+                }
+                const responsePayload = JSON.stringify({
+                    body,
+                    _: {
+                        source: SOURCE_NAME,
+                        version: LIB_VERSION,
+                    },
+                });
+                // Use TextEncoder to return a Uint8Array (compatible with Express res.send)
+                res.send(new TextEncoder().encode(responsePayload));
+            };
+            next();
+        }
+        catch (error) {
+            console.error(`[PostArmor] Error processing request on ${req.path}:`, error?.message);
+            res.status(400).json({ error: "Internal processing error" });
+        }
+    };
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "post-armor",
+  "version": "1.0.0",
+  "description": "Zero-dependency binary request obfuscation and time-locked security middleware for Node.js and Browsers.",
+  "type": "module",
+  "main": "./dist/post-armor.js",
+  "module": "./dist/post-armor.js",
+  "types": "./dist/post-armor.d.ts",
+  "files": [
+    "dist/post-armor.js",
+    "dist/post-armor.d.ts"
+  ],
+  "exports": {
+    ".": {
+      "import": "./dist/post-armor.js",
+      "types": "./dist/post-armor.d.ts"
+    }
+  },
+  "author": "K.Prabhasha",
+  "license": "MIT",
+  "keywords": ["post-armor", "security", "middleware", "encryption", "obfuscation", "time-locked", "binary", "request", "nodejs", "express", "browser", "react", "vue"],
+  "scripts": {
+    "dev": "tsx watch receive.ts",
+    "build": "tsc",
+    "start": "node dist/receive.js",
+    "test-client": "tsx web/send.ts"
+  },
+  "devDependencies": {
+    "@types/cors": "^2.8.17",
+    "@types/express": "^4.17.21",
+    "@types/node": "^20.11.0",
+    "cors": "^2.8.5",
+    "express": "^5.2.1",
+    "javascript-obfuscator": "^5.1.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.3.3"
+  }
+}