diff --git a/README.md b/README.md index 55373a0..bc33583 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,23 @@ # CYBERLUX -> One Next build. Dozens of v3 onions. Nginx in the middle. Tor does the rest. +> **The clearnet is a showroom. The onion is the door. One engine behind every door.** -CyberLux is a **single** Next.js app projected through **nginx loopbacks** into **one Tor hidden service per vertical** — hub, forum, exchange, market, wiki, syndicate, shadow `/w` nodes, and the rest of `scripts/onion-nodes.json`. Same codebase, same deploy, **different `.onion` front doors** with host-aware rewrites (`proxy.ts` + `X-Cyberlux-Node`). +We did not build forty-three repos. We built **one** Next.js stack and **refused** to fracture it—then we **projected** it through Tor until every vertical had its own v3 address, its own myth, its own entry point. Nginx sits in the middle like a bouncer; Tor does the rest. Same codebase. Same deploy. **Different `.onion` front doors** with host-aware rewrites (`proxy.ts` + `X-Cyberlux-Node`). -**Not a toy route list:** stable `HiddenServiceDir` names, backup/restore for onion keys, generated Tor + nginx from one JSON source of truth. Built to **boot, survive operator mistakes, and stay readable under stress**. +This is not a route demo. It is **infrastructure with intent**: stable `HiddenServiceDir` names, backup and restore for onion keys, Tor + nginx generated from **one JSON source of truth**. It is built to **boot, survive operator mistakes, and stay legible when everything else is on fire**. -Operator cheat sheet: +--- + +## The thesis + +- **One truth, many masks** — one build, dozens of onions; no fork army. +- **Identity persists** — keys and dirs are first-class; restarts don’t erase your address book. +- **Loopback only** — Next and nginx don’t audition on the public internet; Tor publishes what you mean to publish. +- **Verify or rot** — `npm run verify` is the line between shipping and LARP. + +--- + +## Operator controls | Command | What | |--------|------| @@ -15,11 +26,13 @@ Operator cheat sheet: | `npm run health:stack` | **Terminal A:** keep `npm run start:onion` running · **Terminal B:** curl Tor/nginx/Next loopbacks | | `npm run onions:status` | URLs + HTTP probe each nginx vhost | | `sudo bash scripts/install-systemd.sh` | Install `cyberlux.service` for boot-time Next | -| See **`DEPLOY.md`** | Firewall posture, compliance reminder, full systemd notes | +| **`DEPLOY.md`** | Firewall posture, compliance reminder, full systemd notes | -**Tor Browser on phone:** use **Onion Browser** (iOS) or **Tor Browser for Android** — Safari/Chrome will **never** resolve `.onion`. Paste the full `http://` + 56-char host + `.onion`; cellular networks sometimes block Tor (try Wi‑Fi). +**Tor on a phone:** **Onion Browser** (iOS) or **Tor Browser for Android** — Safari and Chrome will **never** resolve `.onion`. Paste the full `http://` + 56-char host + `.onion`. Some carriers fight Tor; Wi‑Fi often wins. -This repo ships: +--- + +## What ships in the box - `43` Tor v3 services - stable loopback range `127.0.0.1:8080–8122` @@ -28,30 +41,30 @@ This repo ships: - persistent hidden-service identity keyed by `HiddenServiceDir` - self-healing backup / restore of onion key directories -## What It Does +## What it does (the map) -CyberLux boots a single Next.js app and projects it through multiple onion entry points. +CyberLux boots **one** Next.js app and **projects** it through multiple onion entry points. -- `hub` is the main storefront -- `forum` is Void Aggregate -- `exchange` is the classifieds stack -- `market` is the full catalog vertical -- `search` is Void Crawler -- `wiki` is the hidden-wiki layer -- `w` is the syndicate shell network -- dozens of additional dedicated onions map directly to top-level app routes +- `hub` — main storefront +- `forum` — Void Aggregate +- `exchange` — classifieds stack +- `market` — full catalog vertical +- `search` — Void Crawler +- `wiki` — hidden-wiki layer +- `w` — syndicate shell network +- dozens more dedicated onions map to top-level app routes -The routing layer uses host-aware rewrites so a dedicated onion feels like its own property without forking the app into 43 separate deployments. +The routing layer uses host-aware rewrites so a dedicated onion **feels** like its own property without splitting the app into forty-three deployments. -## One-Command Launch +## One-command launch -Install system deps first on Debian/Ubuntu: +Install system deps on Debian/Ubuntu: ```bash sudo apt install tor nginx ``` -Then run: +Then: ```bash chmod +x start.sh @@ -72,15 +85,15 @@ What `./start.sh` does: 10. prints every live `.onion` URL 11. starts Next on `127.0.0.1:3000` -Use Tor Browser and open the printed URLs as: +Open in Tor Browser: ```text http://<56-char-v3-address>.onion ``` -## Persistent Onion Addresses +## Persistent onion addresses -Yes: the onion addresses are meant to persist. +Yes — the onion addresses are **meant** to persist. Each service uses a fixed Tor directory: @@ -89,17 +102,15 @@ HiddenServiceDir /var/lib/tor/ HiddenServicePort 80 127.0.0.1: ``` -That means the `.onion` address remains stable as long as: +The `.onion` stays stable as long as: -- the `torDir` names in `scripts/onion-nodes.json` do not change +- `torDir` names in `scripts/onion-nodes.json` do not change - `/var/lib/tor/` is preserved - or the backup set can restore those directories -Addresses do **not** rotate on normal app restarts, rebuilds, or standard Tor restarts. +Normal app restarts, rebuilds, and standard Tor restarts do **not** rotate addresses by design. -## Self-Healing Onion Identity - -CyberLux now includes automatic onion key persistence tooling: +## Self-healing onion identity - `scripts/backup-onion-keys.sh` - `scripts/restore-onion-keys.sh` @@ -110,19 +121,11 @@ Backup location: /var/backups/cyberlux-onion-keys/current ``` -Behavior: +After boot, ready onion service directories are backed up. If a service dir is missing from `/var/lib/tor` next boot, it is restored from backup. That is the gap between **screenshotware** and **survives a tired operator**. -- after boot, ready onion service directories are backed up -- on next boot, if a service dir is missing from `/var/lib/tor`, it is restored from backup -- Tor identity is preserved across ordinary host mistakes, partial deletions, or service-dir drift recovery +## Tor / nginx topology -This is the difference between “looks cool in a screenshot” and “survives operator error.” - -## Tor / nginx Topology - -Source of truth: - -- `scripts/onion-nodes.json` +Source of truth: `scripts/onion-nodes.json` Generated artifacts: @@ -146,7 +149,7 @@ Runtime: - nginx onion vhosts: `127.0.0.1:8080–8122` - Tor exposes the public `.onion` endpoints -## Manual Ops +## Manual ops Install or refresh Tor/nginx config: @@ -154,7 +157,7 @@ Install or refresh Tor/nginx config: sudo bash scripts/install-tor-onion.sh ``` -Back up onion keys immediately: +Back up onion keys: ```bash sudo bash scripts/backup-onion-keys.sh @@ -166,7 +169,7 @@ Restore missing onion keys: sudo bash scripts/restore-onion-keys.sh ``` -Run local-only, skipping Tor/nginx: +Local-only, skip Tor/nginx: ```bash CYBERLUX_SKIP_TOR=1 ./start.sh @@ -181,7 +184,7 @@ npm run start:onion ## Boot at startup (systemd) -Generate the real unit with your Unix user and repo path (don’t hand-edit placeholders): +Generate the unit with your Unix user and repo path: ```bash sudo CYBERLUX_USER=$USER bash scripts/install-systemd.sh @@ -195,49 +198,35 @@ Tor + nginx must already be configured (`./start.sh` or `sudo bash scripts/insta ## Verification -Run the full local verification suite: - ```bash npm run verify ``` -That checks: +Checks: onion config generation, TypeScript, shell syntax for boot/install/backup/restore scripts, full Next production build. -- onion config generation -- TypeScript -- shell syntax for boot / install / backup / restore scripts -- full Next production build +## Common failure: `.next` permission hell -## Common Failure: `.next` Permission Hell - -If you previously ran a build with `sudo`, `.next` may be root-owned and Next will fail with `EACCES` during unlink / diagnostics writes. - -Fix once: +If you built with `sudo`, `.next` may be root-owned and Next fails with `EACCES`. ```bash sudo bash scripts/fix-next-perms.sh -``` - -Then rerun: - -```bash ./start.sh ``` -## Security Notes +## Security (read twice) -CyberLux is hardened for a demo stack, not sold as magic invisibility. +CyberLux is hardened for a **demo stack**, not sold as magic invisibility. - Next and nginx bind to loopback only - Tor exposes the onion endpoints - do **not** publish `3000` or `8080–8122` to the public internet -- optional host firewall script: `sudo bash scripts/classroom-ufw.sh` -- the app can still be insecure if the app code is insecure -- operational mistakes still matter more than branding +- optional host firewall: `sudo bash scripts/classroom-ufw.sh` +- bad application logic stays bad behind Tor +- operational mistakes beat branding every time -Tor hides service reachability better than raw-IP hosting. It does not redeem bad application logic, bad operator habits, or bad judgment. +Tor obscures **reachability** better than raw-IP hosting. It does not forgive bad code, bad habits, or bad judgment. -## Site Map +## Site map Core verticals: @@ -253,7 +242,7 @@ Core verticals: - `/dashboard` personal relay - `/account/hidden-services` mirror map -There are additional dedicated onions for many top-level routes beyond those. +Additional dedicated onions exist for many top-level routes beyond these. ## Stack @@ -264,12 +253,16 @@ There are additional dedicated onions for many top-level routes beyond those. - Tor hidden services - generated route / host mapping +--- + ## Final word -If you’re running this, you’re past LARP. The stack is designed to: +If you are running this, you are **past cosplay**. The stack exists to: - keep **onion identities** across rebuilds when you respect `torDir` names and backups -- expose **only** what Tor publishes — not your loopback ports to the raw internet -- fail **loud** in verification (`npm run verify`) instead of silently rotting +- expose **only** what Tor publishes — not your loopback to the raw internet +- fail **loud** in verification instead of silently rotting -Read **`DEPLOY.md`** before you point real people at it. **You** own jurisdiction, opsec, and what you ship. +Read **`DEPLOY.md`** before you point real people at it. **You** own jurisdiction, opsec, and what you ship. The network does not owe you anonymity; **you** owe the network discipline. + +**This README is the product’s declaration of intent. The code is the rest.**