236 lines
7.2 KiB
Markdown
236 lines
7.2 KiB
Markdown
# CYBERLUX
|
|
|
|
> **The clearnet is a showroom. The onion is the door. One engine behind every door.**
|
|
|
|
One Next.js stack projected through a single Tor v3 hidden service. Nginx sits in the middle; Tor does the publishing. Same codebase, same deploy — **one `.onion` front door** with every section available as a normal app path.
|
|
|
|
---
|
|
|
|
## Architecture
|
|
|
|
```
|
|
Tor Browser
|
|
│ http://<56-char>.onion
|
|
▼
|
|
[ Tor Network ]
|
|
│
|
|
▼
|
|
nginx 127.0.0.1:8080 (single onion vhost)
|
|
│
|
|
▼
|
|
Next.js 127.0.0.1:3000 (single instance, proxy.ts routes by header)
|
|
```
|
|
|
|
**One onion service → 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 the live `.onion` URL from `/var/lib/tor/cyberlux/hostname` |
|
|
| `sudo npm run onions:export` | Write the live URL to `onion-urls.txt` in repo root |
|
|
| `npm run onions:status` | URL + HTTP probe for the 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) |
|
|
| `bash scripts/mkp224o-build.sh` | Build the mkp224o v3 vanity key generator into `vendor/mkp224o/` (gitignored) |
|
|
| `bash scripts/vanity-onion-mine.sh <prefix>` | Brute-force a .onion starting with `prefix` (base32) → `var/vanity-mine/` |
|
|
| `sudo bash scripts/install-vanity-onion-key.sh var/vanity-mine` | Install mined keys into `/var/lib/tor/cyberlux`, restart Tor |
|
|
|
|
**Vanity .onion** (a custom prefix, e.g. the site name) is optional and CPU-heavy. Full steps: [`ONION-URLS.md`](ONION-URLS.md#vanity-onion-custom-prefix-eg-site-name-at-the-start).
|
|
|
|
---
|
|
|
|
## Onion URL Reference
|
|
|
|
See [`ONION-URLS.md`](ONION-URLS.md) — live address notes for the single CyberLux onion.
|
|
|
|
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
|
|
|
|
- **1** Tor v3 hidden service
|
|
- Loopback port `127.0.0.1:8080` (nginx vhost, never public)
|
|
- Next.js bound only to `127.0.0.1:3000`
|
|
- One `.onion` for the whole site — hub, forum, market, exchange, wiki, and directory paths
|
|
- 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 the CyberLux onion hostname file
|
|
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 |
|
|
| `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 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 |
|
|
|---------|------|-------|
|
|
| Master directory | `/directory` | `cyberlux` |
|
|
| Hub storefront | `/` | `cyberlux` |
|
|
| Forum (Void Aggregate) | `/forum` | `cyberlux` |
|
|
| Exchange (classifieds) | `/exchange` | `cyberlux` |
|
|
| Market (full catalog) | `/market` | `cyberlux` |
|
|
| Barter (Ash Pit) | `/barter` | `cyberlux` |
|
|
| Search (Void Crawler) | `/search` | `cyberlux` |
|
|
| Hidden Wiki | `/hidden-wiki` | `cyberlux` |
|
|
| Syndicate (shell net) | `/syndicate` | `cyberlux` |
|
|
|
|
---
|
|
|
|
## 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.
|