dark-lord/README.md

CYBERLUX

One Next build. Dozens of v3 onions. Nginx in the middle. Tor does the rest.

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).

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.

Operator cheat sheet:

Command	What
./start.sh	Full pipeline: generate → build → Tor/nginx → print every .onion URL → next start on 127.0.0.1:3000
npm run onions:list	Print all http://….onion URLs from /var/lib/tor/*/hostname (use sudo if needed)
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

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).

This repo ships:

• 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:

sudo apt install tor nginx

Then run:

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:

http://<56-char-v3-address>.onion

Persistent Onion Addresses

Yes: the onion addresses are meant to persist.

Each service uses a fixed Tor directory:

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:

/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:

sudo bash scripts/install-tor-onion.sh

Back up onion keys immediately:

sudo bash scripts/backup-onion-keys.sh

Restore missing onion keys:

sudo bash scripts/restore-onion-keys.sh

Run local-only, skipping Tor/nginx:

CYBERLUX_SKIP_TOR=1 ./start.sh

Start app without the helper:

npm run build
npm run start:onion

Boot at startup (systemd)

Generate the real unit with your Unix user and repo path (don’t hand-edit placeholders):

sudo CYBERLUX_USER=$USER bash scripts/install-systemd.sh
sudo systemctl enable --now tor.service nginx.service cyberlux.service
# use `tor@default.service` instead of `tor.service` if your distro names it that way

The installer writes /etc/systemd/system/cyberlux.service and /etc/default/cyberlux. Legacy template notes live in scripts/cyberlux.service (prefer the generator).

Tor + nginx must already be configured (./start.sh or sudo bash scripts/install-tor-onion.sh at least once).

Verification

Run the full local verification suite:

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:

sudo bash scripts/fix-next-perms.sh

Then rerun:

./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

If you’re running this, you’re past LARP. The stack is designed 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

Read DEPLOY.md before you point real people at it. You own jurisdiction, opsec, and what you ship.