78a071ba02
Add persistent onion key backup and restore, improve startup resilience, and flesh out the major site verticals with richer navigation, search coverage, and operator documentation. Made-with: Cursor
273 lines
6.7 KiB
Markdown
273 lines
6.7 KiB
Markdown
# CYBERLUX
|
||
|
||
> Neon storefront. Forty-three onion doors. One build. One app. No dead air.
|
||
|
||
CyberLux is a layered Next.js fiction stack built for dark-web literacy, classroom demos, mirror discipline drills, and absurdly overbuilt cyberpunk presentation. It runs one app behind Tor + nginx, then fans that app out into dedicated v3 hidden services for the hub, forum, exchange, market, crawler, syndicate, wiki layer, and every other top-level surface in `scripts/onion-nodes.json`.
|
||
|
||
This repo is built to feel like a real underground property while still being a controlled demo environment:
|
||
|
||
- `43` Tor v3 services
|
||
- stable loopback range `127.0.0.1:8080–8122`
|
||
- Next bound only to `127.0.0.1:3000`
|
||
- one `.onion` per major surface
|
||
- persistent hidden-service identity keyed by `HiddenServiceDir`
|
||
- self-healing backup / restore of onion key directories
|
||
|
||
## What It Does
|
||
|
||
CyberLux boots a single 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
|
||
|
||
The routing layer uses host-aware rewrites so a dedicated onion feels like its own property without forking the app into 43 separate deployments.
|
||
|
||
## One-Command Launch
|
||
|
||
Install system deps first on Debian/Ubuntu:
|
||
|
||
```bash
|
||
sudo apt install tor nginx
|
||
```
|
||
|
||
Then run:
|
||
|
||
```bash
|
||
chmod +x start.sh
|
||
./start.sh
|
||
```
|
||
|
||
What `./start.sh` does:
|
||
|
||
1. regenerates Tor / nginx / app route maps from `scripts/onion-nodes.json`
|
||
2. runs `git pull --ff-only` if the repo has `.git` (failure is non-fatal)
|
||
3. runs `npm install`
|
||
4. repairs `.next` ownership if a root-owned build left it unwritable
|
||
5. runs a production build
|
||
6. restores backed-up onion keys if any hidden-service directories are missing
|
||
7. installs Tor + nginx config only when it actually changed
|
||
8. waits for all onion hostname files, not just the hub
|
||
9. refreshes the onion key backup set
|
||
10. prints every live `.onion` URL
|
||
11. starts Next on `127.0.0.1:3000`
|
||
|
||
Use Tor Browser and open the printed URLs as:
|
||
|
||
```text
|
||
http://<56-char-v3-address>.onion
|
||
```
|
||
|
||
## Persistent Onion Addresses
|
||
|
||
Yes: the onion addresses are meant to persist.
|
||
|
||
Each service uses a fixed Tor directory:
|
||
|
||
```tor
|
||
HiddenServiceDir /var/lib/tor/<service-dir>
|
||
HiddenServicePort 80 127.0.0.1:<loopback-port>
|
||
```
|
||
|
||
That means the `.onion` address remains stable as long as:
|
||
|
||
- the `torDir` names in `scripts/onion-nodes.json` do not change
|
||
- `/var/lib/tor/<service-dir>` is preserved
|
||
- or the backup set can restore those directories
|
||
|
||
Addresses do **not** rotate on normal app restarts, rebuilds, or standard Tor restarts.
|
||
|
||
## Self-Healing Onion Identity
|
||
|
||
CyberLux now includes automatic onion key persistence tooling:
|
||
|
||
- `scripts/backup-onion-keys.sh`
|
||
- `scripts/restore-onion-keys.sh`
|
||
|
||
Backup location:
|
||
|
||
```text
|
||
/var/backups/cyberlux-onion-keys/current
|
||
```
|
||
|
||
Behavior:
|
||
|
||
- 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
|
||
|
||
This is the difference between “looks cool in a screenshot” and “survives operator error.”
|
||
|
||
## Tor / nginx Topology
|
||
|
||
Source of truth:
|
||
|
||
- `scripts/onion-nodes.json`
|
||
|
||
Generated artifacts:
|
||
|
||
- `tor/cyberlux-nodes.conf`
|
||
- `nginx/cyberlux-onion-servers.inc`
|
||
- `lib/onionRoutes.generated.ts`
|
||
- `scripts/generated/tor-dirs.txt`
|
||
- `scripts/generated/onion-labels.tsv`
|
||
- `scripts/generated/onion-port-range.txt`
|
||
|
||
Install path:
|
||
|
||
- `/etc/tor/cyberlux-nodes.conf`
|
||
- `/etc/nginx/cyberlux-server-common.inc`
|
||
- `/etc/nginx/cyberlux-onion-servers.inc`
|
||
- `/etc/nginx/sites-available/cyberlux-onion`
|
||
|
||
Runtime:
|
||
|
||
- Next.js: `127.0.0.1:3000`
|
||
- nginx onion vhosts: `127.0.0.1:8080–8122`
|
||
- Tor exposes the public `.onion` endpoints
|
||
|
||
## Manual Ops
|
||
|
||
Install or refresh Tor/nginx config:
|
||
|
||
```bash
|
||
sudo bash scripts/install-tor-onion.sh
|
||
```
|
||
|
||
Back up onion keys immediately:
|
||
|
||
```bash
|
||
sudo bash scripts/backup-onion-keys.sh
|
||
```
|
||
|
||
Restore missing onion keys:
|
||
|
||
```bash
|
||
sudo bash scripts/restore-onion-keys.sh
|
||
```
|
||
|
||
Run local-only, skipping Tor/nginx:
|
||
|
||
```bash
|
||
CYBERLUX_SKIP_TOR=1 ./start.sh
|
||
```
|
||
|
||
Start app without the helper:
|
||
|
||
```bash
|
||
npm run build
|
||
npm run start:onion
|
||
```
|
||
|
||
## Boot At Startup
|
||
|
||
`scripts/cyberlux.service` is included as a systemd template for the Next process.
|
||
|
||
Before installing it, set:
|
||
|
||
- `User=`
|
||
- `Group=`
|
||
- `WorkingDirectory=`
|
||
|
||
Then install:
|
||
|
||
```bash
|
||
sudo install -m 0644 scripts/cyberlux.service /etc/systemd/system/cyberlux.service
|
||
sudo systemctl daemon-reload
|
||
sudo systemctl enable --now cyberlux.service
|
||
```
|
||
|
||
Notes:
|
||
|
||
- Tor and nginx should already be installed and enabled
|
||
- the service unit keeps the Next process alive
|
||
- Tor/nginx config is still managed by the repo scripts
|
||
|
||
## Verification
|
||
|
||
Run the full local verification suite:
|
||
|
||
```bash
|
||
npm run verify
|
||
```
|
||
|
||
That checks:
|
||
|
||
- onion config generation
|
||
- TypeScript
|
||
- shell syntax for boot / install / backup / restore scripts
|
||
- full Next production build
|
||
|
||
## 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:
|
||
|
||
```bash
|
||
sudo bash scripts/fix-next-perms.sh
|
||
```
|
||
|
||
Then rerun:
|
||
|
||
```bash
|
||
./start.sh
|
||
```
|
||
|
||
## Security Notes
|
||
|
||
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
|
||
|
||
Tor hides service reachability better than raw-IP hosting. It does not redeem bad application logic, bad operator habits, or bad judgment.
|
||
|
||
## Site Map
|
||
|
||
Core verticals:
|
||
|
||
- `/` hub storefront
|
||
- `/market` full catalog
|
||
- `/forum` Void Aggregate
|
||
- `/exchange` classifieds
|
||
- `/barter` Ash Pit
|
||
- `/search` Void Crawler
|
||
- `/hidden-wiki` wiki layer
|
||
- `/darknet-atlas` taxonomy / atlas
|
||
- `/syndicate` shell network
|
||
- `/dashboard` personal relay
|
||
- `/account/hidden-services` mirror map
|
||
|
||
There are additional dedicated onions for many top-level routes beyond those.
|
||
|
||
## Stack
|
||
|
||
- Next.js `16`
|
||
- React `19`
|
||
- Tailwind CSS `4`
|
||
- nginx
|
||
- Tor hidden services
|
||
- generated route / host mapping
|
||
|
||
## Final Word
|
||
|
||
CyberLux is supposed to boot like a machine that knows what it is:
|
||
|
||
- same onion doors
|
||
- same identities
|
||
- no shallow mirrors
|
||
- no fake “self healing” copy without actual restore logic
|
||
- no dead routes pretending to be part of the network
|
||
|
||
If it starts, it should start hard.
|