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:

```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 (systemd)

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

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

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:

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

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.