# CyberLux — Onion URL Reference

CyberLux now uses one Tor v3 hidden service for the whole site. The live `.onion` address is generated at runtime by Tor and stored in `/var/lib/tor/cyberlux/hostname`. This file is a **static registry**; use the commands below to resolve the live address.

---

## Get Live URLs

```bash
# Print the live .onion URL (reads /var/lib/tor/cyberlux/hostname)
bash scripts/list-onion-urls.sh
# or with sudo if not readable as your user:
sudo bash scripts/list-onion-urls.sh

# Save live URLs to onion-urls.txt in the repo root
sudo bash scripts/export-onion-urls.sh
```

---

## Service Registry

| # | `torDir` | Port | Role | App Path |
|---|----------|------|------|----------|
| 1 | `cyberlux` | 8080 | Everything site — hub, market, forum, directory, wiki, account, and all app paths | `/directory` |

---

## Live Address File

After Tor is running, save all live addresses to a plain-text file:

```bash
sudo bash scripts/export-onion-urls.sh
# writes: onion-urls.txt
```

`onion-urls.txt` (if present in this directory) contains the resolved `http://…56chars….onion` address and is gitignored — it reflects runtime state, not source.

---

## How Addresses Stay Stable

The service maps to a fixed `HiddenServiceDir` in `/var/lib/tor/`. As long as:

- the `torDir` name in `scripts/onion-nodes.json` stays `cyberlux`, and
- `/var/lib/tor/cyberlux/` is preserved (or restored from backup),

the `.onion` address **never rotates**, surviving reboots, rebuilds, and Tor restarts.

Backup/restore:

```bash
sudo bash scripts/backup-onion-keys.sh    # saves to /var/backups/cyberlux-onion-keys/current
sudo bash scripts/restore-onion-keys.sh   # restores missing dirs from backup
```

---

## Vanity .onion (custom prefix, e.g. site name at the start)

v3 onion names are random unless you **generate** a key pair whose address matches a **prefix** (brute force). This repo ships scripts around **[mkp224o](https://github.com/cathugger/mkp224o)** (same approach as the [Tor community vanity guide](https://community.torproject.org/onion-services/advanced/vanity-addresses/)).

**Charset:** Onion v3 hostnames are base32: **a–z** and **2–7** only (no `0`, `1`, `8`, `9`). Any other character in the filter is invalid.

**Time:** Shorter prefixes finish sooner; each extra character is much harder. Treat long targets (e.g. full word) as a **long** CPU run or use many cores / a batch-capable build per mkp224o’s `OPTIMISATION.txt`.

### 1) Build the miner (once)

```bash
# Debian/Ubuntu deps (as root)
sudo apt install -y git gcc make autoconf pkg-config libc6-dev libsodium-dev

cd /path/to/cyberlux
bash scripts/mkp224o-build.sh
# produces: vendor/mkp224o/mkp224o
```

`vendor/mkp224o` is gitignored; nothing is committed except these scripts.

**Docker alternative (no local compile):**

```bash
export CYBERLUX_MKP224O_DOCKER=1
export CYBERLUX_VANITY_OUT="/path/to/cyberlux/var/vanity-mine"
mkdir -p "$CYBERLUX_VANITY_OUT"
bash scripts/vanity-onion-mine.sh yourprefix
```

(Requires Docker; uses `ghcr.io/cathugger/mkp224o:master`.)

### 2) Mine a prefix (runs until a match appears)

```bash
bash scripts/vanity-onion-mine.sh cyberl
# Output directory: var/vanity-mine/ (default) — gitignored
```

You get a new subdirectory named like `cyberlXXXXXXXX.onion` containing `hs_ed25519_secret_key` and `hostname`. **Stop the miner** when you have a directory you are happy with if it created more than one.

### 3) Install the key for CyberLux and restart Tor

`HiddenServiceDir` in this project is `/var/lib/tor/cyberlux` (from `onion-nodes.json`). The install script copies the **files** from the mkp224o folder into that directory, fixes ownership, and restarts Tor.

```bash
# If var/vanity-mine has several *.onion folders, the script picks one for you
# (default: first in A–Z order). Newest mtime: CYBERLUX_VANITY_PICK=latest
sudo bash scripts/install-vanity-onion-key.sh var/vanity-mine
sudo env CYBERLUX_VANITY_PICK=latest bash scripts/install-vanity-onion-key.sh var/vanity-mine

# Or point at one directory explicitly:
sudo bash scripts/install-vanity-onion-key.sh var/vanity-mine/cyberlxxxxx....onion
```

The previous service directory is moved to `/var/lib/tor/cyberlux.stale.<timestamp>`. A backup is triggered when `backup-onion-keys.sh` is present.

### 4) Confirm the new URL

```bash
bash scripts/list-onion-urls.sh
# or
sudo cat /var/lib/tor/cyberlux/hostname
```

Open `http://<address>.onion` in **Tor Browser**.

---

## Notes

- The service runs from **one** Next.js instance at `127.0.0.1:3000`.
- nginx on `127.0.0.1:8080` proxies every path to Next.
- Open addresses in **Tor Browser** or **Onion Browser** (iOS). Standard browsers cannot resolve `.onion`.
- Use `http://` — TLS inside the onion circuit is handled end-to-end by Tor.
- A vanity prefix is **not** “configured” in `torrc`; only the private key in `HiddenServiceDir` determines the hostname.