<div align="center">
# Entrouter-Universal
### Pipeline Integrity Guardian
[](https://crates.io/crates/entrouter-universal)
[](https://crates.io/crates/entrouter-universal)
[](https://github.com/joarkee-debug/Entrouter-Universal/blob/main/LICENSE)
[](https://www.rust-lang.org)
[](https://docs.rs/entrouter-universal)
**What goes in, comes out identical. Or it tells you exactly what broke and where.**
```
cargo install entrouter-universal
```
</div>
---
## The 20-Minute Problem, Fixed In 1 Second
You're SSH'd into your VPS. You need to run a curl command with JSON. You know what happens next.
<table>
<tr>
<td width="50%">
**Before - The escaping nightmare**
```
$ ssh root@your-vps
# Attempt 1
curl -d '{"key":"val"}' ...
> bash: unexpected EOF
# Attempt 2
curl -d "{\"key\":\"val\"}" ...
> bash: unexpected token
# Attempt 3
curl -d '{\"key\":\"val\"}' ...
> invalid JSON
# Attempt 4
curl -d '{"key":"val"}' ...
> curl: (3) bad/illegal format
...20 minutes later...
```
</td>
<td width="50%">
**After - One command**
```
$ echo 'curl -s -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer er_xxx" \
-d {"tier":"enterprise"} \
http://127.0.0.1:3000/admin/keys/generate' \
| entrouter ssh root@your-vps
{"apiKey":"er_ent_9f3a...","tier":"enterprise"}
# Done. First try. Every time.
```
</td>
</tr>
</table>
You type the command **exactly as you would locally**. Entrouter encodes it to safe base64, sends it over SSH, decodes on the server, executes it. Zero escaping. Zero thinking.
---
## How It Works
```
┌──────────────┐ ┌───────────────────────┐ ┌──────────────┐
│ YOUR SHELL │ │ SSH TRANSPORT │ │ REMOTE VPS │
│ │ encode │ │ decode │ │
│ Raw command ├──────────►│ Safe base64 payload ├──────────►│ Exact same │
│ with JSON, │ SHA-256 │ Nothing to escape. │ verify │ command you │
│ quotes, etc │ fingerprint Nothing to break. │ execute │ typed. │
└──────────────┘ └───────────────────────┘ └──────────────┘
```
**Base64 at entry. SHA-256 fingerprint travels with it. Verify at exit.**
Every layer between your keyboard and the destination - HTTP, JSON, Rust, Redis, Postgres, shell - sees a boring alphanumeric string. Nothing to escape. Nothing to mangle. Nothing to break.
---
## Quick Start
```bash
# Install the CLI
cargo install entrouter-universal
# Or add the library to your project
cargo add entrouter-universal
```
---
## CLI Commands
Six commands. All pipe-friendly. All SSH-safe.
| `entrouter ssh <host>` | Pipe a command in, it runs on the remote machine. No escaping. |
| `entrouter encode` | Stdin → base64 + SHA-256 fingerprint (JSON output) |
| `entrouter decode` | JSON with encoded field → original data |
| `entrouter verify` | JSON with encoded + fingerprint → INTACT or TAMPERED |
| `entrouter raw-encode` | Stdin → raw base64 (no JSON wrapper) |
| `entrouter raw-decode` | Base64 → original (no JSON wrapper) |
### SSH - The Killer Feature
```bash
# Run ANY command on a remote server. Type it exactly how you would locally.
No quoting gymnastics. No backslash hell. No "it works locally but breaks over SSH." Just pipe your command and go.
### Encode / Decode / Verify
```bash
# Encode anything - comes out as base64 + SHA-256 fingerprint
# Decode it back
# Verify it survived the trip
# Decoded: {"tier":"enterprise","keyType":"engine"}
```
### Raw Mode - Pipe Anywhere
```bash
# Just base64. No JSON wrapper. Perfect for piping.
# Encode locally, send over SSH, decode on the other side
---
## The Library - Five Tools
Entrouter isn't just a CLI. It's a Rust crate with five integrity tools for your backend.
```rust
use entrouter_universal::*;
```
### 1. Envelope - Four Flavours
Wrap your data. Pass it through anything. Unwrap and verify on the other side.
```rust
// Standard - works everywhere
let env = Envelope::wrap(data);
let original = env.unwrap_verified()?;
// URL-Safe - uses - and _ instead of + and /
let env = Envelope::wrap_url_safe(data);
// Compressed - gzip first, then base64 (large payloads)
let env = Envelope::wrap_compressed(data)?;
// TTL - self-expiring (race tokens, sessions, anything time-sensitive)
let env = Envelope::wrap_with_ttl(data, 300); // dies in 5 minutes
env.unwrap_verified() // Err(Expired) after 5 min - cannot be replayed
```
Store it anywhere:
```rust
redis.set("key", env.to_json()?).await?; // Redis
db.execute("INSERT INTO t (envelope) VALUES ($1)", &[&env.to_json()?]).await?; // Postgres
Response::json(env) // HTTP (serde-compatible)
```
---
### 2. Chain - Cryptographic Audit Trail
Each link references the previous link's fingerprint. Tamper with any link - everything after it breaks. You know exactly where the chain was cut.
```rust
let mut chain = Chain::new("race:listing_abc - OPENED");
chain.append("user_john joined - token: 000001739850000001");
chain.append("user_jane joined - token: 000001739850000002");
chain.append("WINNER: user_john - mathematically proven");
chain.append("race:listing_abc - CLOSED");
assert!(chain.verify().valid);
```
Tamper detection:
```
━━━━ Entrouter Universal Chain Report ━━━━
Link 2: ✅ | fp: 9f8e7d...
Link 3: ❌ VIOLATED ← tampered here
Link 4: ❌ VIOLATED ← cascade
Link 5: ❌ VIOLATED ← cascade
```
### 3. UniversalStruct - Per-Field Integrity
Not "something broke somewhere." You know **exactly which field** was tampered with.
```rust
let wrapped = UniversalStruct::wrap_fields(&[
("token", "000001739850123456-000004521890000-a3f1b2-user_john"),
("user_id", "john"),
("amount", "299.99"),
("listing_id", "listing:abc123"),
]);
assert!(wrapped.verify_all().all_intact);
```
Tamper detection:
```
━━━━ Entrouter Universal Field Report ━━━━
token: ✅ - 000001739850123456...
user_id: ✅ - john
amount: ❌ VIOLATED ← Redis mangled this one
listing_id: ✅ - listing:abc123
```
---
### 4. Guardian - Find The Exact Layer That Broke It
Checkpoint your data at every layer. Guardian tells you exactly which one corrupted it.
```rust
let mut g = Guardian::new(data);
g.checkpoint("http_ingress", &value_at_http);
g.checkpoint("json_parse", &value_at_json);
g.checkpoint("redis_write", &value_at_redis);
g.checkpoint("postgres_write", &value_at_postgres);
```
```
━━━━ Entrouter Universal Pipeline Report ━━━━
Layer 1: http_ingress - ✅
Layer 2: json_parse - ✅
Layer 3: redis_write - ❌ VIOLATED ← broke here
Layer 4: postgres_write - ❌ VIOLATED ← cascade
```
`g.assert_intact()` - panics with the layer name in your tests.
---
### 5. Core Primitives
```rust
use entrouter_universal::{encode_str, decode_str, fingerprint_str, verify};
let encoded = encode_str(data); // → base64
let original = decode_str(&encoded)?; // → original
let fp = fingerprint_str(data); // → SHA-256 hex
let intact = verify(&encoded, &fp)?; // → bool
```
---
## Why Base64?
| HTTP | `"`, `\`, newlines | ✅ |
| JSON | `"`, `\`, control chars | ✅ |
| Shell | `'`, `"`, `$`, `` ` ``, `\`, spaces | ✅ |
| Redis | newlines, spaces | ✅ |
| Postgres | `'`, `\`, null bytes | ✅ |
| URLs | `+`, `/`, `=` (use `wrap_url_safe`) | ✅ |
Every layer sees a boring alphanumeric string. Problem solved at the encoding level - not the escaping level.
---
## Cross-Machine
Base64 and SHA-256 are universal standards. Identical output on Windows, Linux, Mac, ARM, x86, anywhere.
```
Your Machine Your VPS
┌────────────────────┐ ┌────────────────────┐
│ Envelope::wrap() │───── SSH ────►│ Envelope::from_json│
│ or: entrouter ssh │ │ .unwrap_verified() │
│ │ │ ✅ Identical. │
└────────────────────┘ └────────────────────┘
```
---
## Tested Against The Worst
```
SQL injection ✅ '; DROP TABLE users; --
JSON breaking ✅ {"key":"val\"ue","nested":"b\\\\c"}
Null bytes ✅ \x00\x01\x02\x03
Unicode hellscape ✅ �-�本語 中文 한국어 العربية
Emoji overload ✅ 🔥💀🚀🎯⚡🖤
XSS attempts ✅ <script>alert('xss')</script>
Redis protocol ✅ *3\r\n$3\r\nSET\r\n
Path traversal ✅ ../../../../etc/passwd
Format strings ✅ %s%s%s%n%n%n
Zero-width chars ✅
```
**28 tests. Zero failures.**
---
## Changelog
### v0.5 - SSH Command
- `entrouter ssh <host>` - type the command, it runs on the remote machine. No escaping.
- Encodes locally, decodes on server, executes via `sh`. One step.
### v0.4 - CLI
- `entrouter` CLI binary - encode, decode, verify, raw-encode, raw-decode from the shell
- Pipe-friendly, works over SSH, no shell escaping issues
- `cargo install entrouter-universal`
### v0.3 - Hardening
- `#[must_use]` on all constructors and pure functions
- `#[non_exhaustive]` on `UniversalError`
- `Clone` and `PartialEq` on all error and result types - testable in assertions
- `Display` impls on `VerifyResult`, `ChainVerifyResult`, `StructVerifyResult`, `FieldVerifyResult`
- New `SerializationError` variant - JSON failures no longer misreport as `MalformedEnvelope`
- Guardian now reports decode failures instead of silently swallowing them
- 16 MiB decompression size guard against gzip bombs
---
## License
Apache-2.0 - Free for open-source.
Commercial license available for closed-source / proprietary use.
Contact hello@entrouter.com
*Part of the Entrouter suite - [entrouter.com](https://entrouter.com)*