drjones/dark-lord
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

README: manifesto voice, final product copy

Browse Source 
Lead with thesis and declaration; keep operator table and ops intact.
Closing line marks README as product intent.

Made-with: Cursor
This commit is contained in:
drjones
2026-04-15 22:14:05 -07:00
parent e0a4a20862
commit 9da373a190
1 changed files with 67 additions and 74 deletions
Download Patch File Download Diff File Expand all files Collapse all files

141
README.md
View File

@@ -1,12 +1,23 @@
# CYBERLUX # 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 | | 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 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 | | `npm run onions:status` | URLs + HTTP probe each nginx vhost |
| `sudo bash scripts/install-systemd.sh` | Install `cyberlux.service` for boot-time Next | | `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 - `43` Tor v3 services
- stable loopback range `127.0.0.1:8080–8122` - stable loopback range `127.0.0.1:8080–8122`
@@ -28,30 +41,30 @@ This repo ships:
- persistent hidden-service identity keyed by `HiddenServiceDir` - persistent hidden-service identity keyed by `HiddenServiceDir`
- self-healing backup / restore of onion key directories - 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 - `hub` — main storefront
- `forum` is Void Aggregate - `forum` — Void Aggregate
- `exchange` is the classifieds stack - `exchange` — classifieds stack
- `market` is the full catalog vertical - `market` — full catalog vertical
- `search` is Void Crawler - `search` — Void Crawler
- `wiki` is the hidden-wiki layer - `wiki` — hidden-wiki layer
- `w` is the syndicate shell network - `w` — syndicate shell network
- dozens of additional dedicated onions map directly to top-level app routes - 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 ```bash
sudo apt install tor nginx sudo apt install tor nginx
``` ```
Then run: Then:
```bash ```bash
chmod +x start.sh chmod +x start.sh
@@ -72,15 +85,15 @@ What `./start.sh` does:
10. prints every live `.onion` URL 10. prints every live `.onion` URL
11. starts Next on `127.0.0.1:3000` 11. starts Next on `127.0.0.1:3000`
Use Tor Browser and open the printed URLs as: Open in Tor Browser:
```text ```text
http://<56-char-v3-address>.onion 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: Each service uses a fixed Tor directory:
@@ -89,17 +102,15 @@ HiddenServiceDir /var/lib/tor/<service-dir>
HiddenServicePort 80 127.0.0.1:<loopback-port> HiddenServicePort 80 127.0.0.1:<loopback-port>
``` ```
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/<service-dir>` is preserved - `/var/lib/tor/<service-dir>` is preserved
- or the backup set can restore those directories - 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 ## Self-healing onion identity
CyberLux now includes automatic onion key persistence tooling:
- `scripts/backup-onion-keys.sh` - `scripts/backup-onion-keys.sh`
- `scripts/restore-onion-keys.sh` - `scripts/restore-onion-keys.sh`
@@ -110,19 +121,11 @@ Backup location:
/var/backups/cyberlux-onion-keys/current /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 ## Tor / nginx topology
- 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
This is the difference between “looks cool in a screenshot” and “survives operator error.” Source of truth: `scripts/onion-nodes.json`
## Tor / nginx Topology
Source of truth:
- `scripts/onion-nodes.json`
Generated artifacts: Generated artifacts:
@@ -146,7 +149,7 @@ Runtime:
- nginx onion vhosts: `127.0.0.1:8080–8122` - nginx onion vhosts: `127.0.0.1:8080–8122`
- Tor exposes the public `.onion` endpoints - Tor exposes the public `.onion` endpoints
## Manual Ops ## Manual ops
Install or refresh Tor/nginx config: Install or refresh Tor/nginx config:
@@ -154,7 +157,7 @@ Install or refresh Tor/nginx config:
sudo bash scripts/install-tor-onion.sh sudo bash scripts/install-tor-onion.sh
``` ```
Back up onion keys immediately: Back up onion keys:
```bash ```bash
sudo bash scripts/backup-onion-keys.sh sudo bash scripts/backup-onion-keys.sh
@@ -166,7 +169,7 @@ Restore missing onion keys:
sudo bash scripts/restore-onion-keys.sh sudo bash scripts/restore-onion-keys.sh
``` ```
Run local-only, skipping Tor/nginx: Local-only, skip Tor/nginx:
```bash ```bash
CYBERLUX_SKIP_TOR=1 ./start.sh CYBERLUX_SKIP_TOR=1 ./start.sh
@@ -181,7 +184,7 @@ npm run start:onion
## Boot at startup (systemd) ## 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 ```bash
sudo CYBERLUX_USER=$USER bash scripts/install-systemd.sh 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 ## Verification
Run the full local verification suite:
```bash ```bash
npm run verify 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 ## Common failure: `.next` permission hell
- TypeScript
- shell syntax for boot / install / backup / restore scripts
- full Next production build
## Common Failure: `.next` Permission Hell If you built with `sudo`, `.next` may be root-owned and Next fails with `EACCES`.
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:
```bash ```bash
sudo bash scripts/fix-next-perms.sh sudo bash scripts/fix-next-perms.sh
```
Then rerun:
```bash
./start.sh ./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 - Next and nginx bind to loopback only
- Tor exposes the onion endpoints - Tor exposes the onion endpoints
- do **not** publish `3000` or `8080–8122` to the public internet - do **not** publish `3000` or `8080–8122` to the public internet
- optional host firewall script: `sudo bash scripts/classroom-ufw.sh` - optional host firewall: `sudo bash scripts/classroom-ufw.sh`
- the app can still be insecure if the app code is insecure - bad application logic stays bad behind Tor
- operational mistakes still matter more than branding - 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: Core verticals:
@@ -253,7 +242,7 @@ Core verticals:
- `/dashboard` personal relay - `/dashboard` personal relay
- `/account/hidden-services` mirror map - `/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 ## Stack
@@ -264,12 +253,16 @@ There are additional dedicated onions for many top-level routes beyond those.
- Tor hidden services - Tor hidden services
- generated route / host mapping - generated route / host mapping
---
## Final word ## 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 - 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 - expose **only** what Tor publishes — not your loopback to the raw internet
- fail **loud** in verification (`npm run verify`) instead of silently rotting - 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.**