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

```bash
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`](ONION-URLS.md) — full table of all 43 services with ports and app paths.

To export live `.onion` addresses after Tor is running:

```bash
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)

```bash
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

```bash
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):**

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

**Onion hostnames not showing up:**

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

**Port 3000 already in use:**

```bash
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.