dark-lord/README.md

CYBERLUX

The clearnet is a showroom. The onion is the door. One engine behind every door.

One Next.js stack projected through 43 independent Tor v3 hidden services. Nginx sits in the middle; Tor does the publishing. Same codebase, same deploy — different .onion front doors with host-aware rewrites (proxy.ts + X-Cyberlux-Node). No fork army. No split deployments.

---

Architecture

  Tor Browser
      │  http://<56-char>.onion
      ▼
  [ Tor Network ]
      │
      ▼
  nginx  127.0.0.1:8080–8122   (one vhost per .onion, host header → X-Cyberlux-Node)
      │
      ▼
  Next.js  127.0.0.1:3000      (single instance, proxy.ts routes by header)

43 onion services → one app → zero public ports.

---

Quick Start

sudo apt install tor nginx
chmod +x start.sh
./start.sh

Open the hub in Tor Browser (addresses print at the end of start.sh).
Local-only (skip Tor/nginx): CYBERLUX_SKIP_TOR=1 ./start.sh

---

Operator Commands

Command	What it does
./start.sh	Full pipeline: generate → build → Tor/nginx → print URLs → start Next
npm run onions:list	Print all live .onion URLs from /var/lib/tor/*/hostname
sudo npm run onions:export	Write live URLs to onion-urls.txt in repo root
npm run onions:status	URLs + HTTP probe each nginx vhost
npm run health:stack	Curl Tor/nginx/Next loopbacks and report status
npm run verify	Full pre-ship check: config gen, TS, shell syntax, build
sudo bash scripts/install-tor-onion.sh	Install/refresh Tor + nginx config
sudo bash scripts/backup-onion-keys.sh	Back up all hidden-service key dirs
sudo bash scripts/restore-onion-keys.sh	Restore missing key dirs from backup
sudo bash scripts/install-systemd.sh	Install cyberlux.service for boot-time start
sudo bash scripts/classroom-ufw.sh	Lock firewall to loopback-only (recommended)

---

Onion URL Reference

See ONION-URLS.md — full table of all 43 services with ports and app paths.

To export live .onion addresses after Tor is running:

sudo bash scripts/export-onion-urls.sh
# writes onion-urls.txt (gitignored — reflects runtime state)

---

What Ships in the Box

• 43 Tor v3 hidden services
• Loopback range 127.0.0.1:8080–8122 (nginx vhosts, never public)
• Next.js bound only to 127.0.0.1:3000
• One .onion per major surface — hub, forum, market, exchange, wiki, and 38 more
• Persistent hidden-service identity keyed by HiddenServiceDir name
• Self-healing backup / restore for onion keys
• BTCPay Server integration (configurable) for on-chain + Lightning deposits
• Systemd unit generator for unattended boot

---

What ./start.sh Does (in order)

1. Regenerates Tor / nginx / app route maps from scripts/onion-nodes.json
2. Runs git pull --ff-only if repo has .git (non-fatal on failure)
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 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

---

Source of Truth

Everything — Tor config, nginx vhosts, app route maps — is generated from one file:

scripts/onion-nodes.json

Generated artifacts (do not edit manually):

File	Description
tor/cyberlux-nodes.conf	Tor HiddenServiceDir / HiddenServicePort blocks
nginx/cyberlux-onion-servers.inc	nginx server blocks (one per onion)
lib/onionRoutes.generated.ts	TypeScript route map used by proxy.ts
scripts/generated/tor-dirs.txt	Newline-separated list of service dir names
scripts/generated/onion-labels.tsv	Human-readable labels per service
scripts/generated/onion-port-range.txt	Port min / max for scripts

---

Persistent Onion Addresses

Addresses are stable as long as:

• 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

Normal app restarts, rebuilds, and standard Tor restarts do not rotate addresses.

Backup location: /var/backups/cyberlux-onion-keys/current

---

BTCPay Server

The checkout flow supports BTCPay Server for on-chain + Lightning payments. Configure with environment variables (see .env.example or DEPLOY.md). The stack runs without BTCPay — the API returns 503 if not configured.

---

Boot at Startup (systemd)

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.

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

---

Verification

npm run verify

Checks: config generation, TypeScript compilation, shell syntax for all boot/install/backup/restore scripts, full Next.js production build.

---

Common Fixes

.next permission error (built with sudo):

sudo bash scripts/fix-next-perms.sh
./start.sh

Onion hostnames not showing up:

sudo systemctl status tor
sudo ls -la /var/lib/tor/
# Wait ~30s after Tor starts for v3 descriptor publication

Port 3000 already in use:

ss -ltnp | grep 3000
# Stop the conflicting process, then ./start.sh

---

Security

• Next.js and nginx bind to loopback only — they are never public
• Tor publishes the .onion endpoints
• Do not expose ports 3000 or 8080–8122 to the internet
• Harden with: sudo bash scripts/classroom-ufw.sh
• Tor obscures reachability — it does not forgive bad code or bad ops

Read DEPLOY.md before pointing real users at this stack.

---

Site Map

Vertical	Path	Onion
Hub storefront	/	cyberlux
Forum (Void Aggregate)	/forum	cyberlux_forum
Exchange (classifieds)	/exchange	cyberlux_exchange
Market (full catalog)	/market	cyberlux_market
Barter (Ash Pit)	/barter	cyberlux_barter
Search (Void Crawler)	/search	cyberlux_search
Hidden Wiki	/hidden-wiki	cyberlux_wiki
Syndicate (shell net)	/syndicate	cyberlux_syndicate
Dashboard	/dashboard	cyberlux_dashboard
Account / mirror map	/account	cyberlux_account
+ 33 more	see ONION-URLS.md

---

Stack

• Next.js 16 · React 19 · Tailwind CSS 4
• nginx reverse proxy (loopback vhosts)
• Tor v3 hidden services
• BTCPay Server (optional, on-chain + Lightning)
• Generated route / host mapping from single JSON source

---

If you are running this, you are past cosplay.
The network does not owe you anonymity — you owe the network discipline.
Read DEPLOY.md. Own your jurisdiction.