# TOR VAULT — the Rust strongbox behind the jackpot

The second hackathon. A prize of TOR sits at one address, a public puzzle stands
in front of it, and the first wallet that proves it wins — once.

**Status: built and tested, not deployed and not funded.** Nothing in this folder
has held, moved or promised a coin. The funding checklist is near the end, and it
says what to check after each step.

## The one design decision everything else follows from

**The vault holds no key.** There is no private key in this crate, no signing
code, no transfer code, no wallet file, no shell, no upload and no file read. A
bug in this program cannot move money, because the code that moves money has
never existed in this process.

| piece | where it lives | what it can do |
|---|---|---|
| the puzzle + the claim record | `tor-vault` (this crate) | verify a proof, lock once, write `vault.json` |
| the money | the operator's TOR address | nothing automatic; it sits there |
| the payout | `claim_to_wallet.py` | verify the claim, then sign **one** transfer with the product's wallet |

That split is why this vault can be made solid by inspection: the attack surface
that could steal a prize is not in the challenge at all.

## The puzzle

```text
work(seed, nonce) = SHA-256(seed ‖ nonce as 8 big-endian bytes)
solved            = work(...) has >= bits leading zero bits
```

* `seed` is 32 random bytes, published once, chosen when the vault is created.
* `bits` is the difficulty. Default **28** (about 2.7e8 hashes - minutes on a GPU,
  hours on one core). Maximum 40.
* There is exactly one winner: the first valid `(nonce, signature)` to arrive.

A claim must also be **signed by the wallet that wants the prize**, over:

```text
tor-vault:claim:v1|<recipient>|<prize_micro>|<seed>
```

Without the signature, whoever saw a winning nonce first could claim it to their
own address. With it, a stolen nonce is worthless - the signature is bound to the
address, the amount and the seed.

## Run it

```bash
cd vault
cargo test                     # 12 tests, no network, no chain
cargo build --release

# the real vault: 28 bits, 100 TOR prize, loopback only
./target/release/tor-vault --state vault.json --bits 28 --prize 100 --port 8787

# the practice vault: never funded, deliberately weak (see AUDIT.md)
./target/release/tor-vault --training --port 8788
```

| route | what it answers |
|---|---|
| `GET /` or `/status` | the puzzle, the lock, the refusals, `holds_keys: false` |
| `GET /puzzle` | just the seed, bits and prize |
| `GET /health` | `{"ok": true}` |
| `POST /claim` | `{"recipient","pubkey","nonce","signature"}` - the claim, or a refusal by name |
| `GET /training/unlock?password=` | training mode only, and it is meant to be brute-forced |

A solver is included:

```bash
cargo run --release --example mine -- <seed> <bits> <TOR1…> <pubkey b58> <signature b58> 100000000
```

The signature is an argument because **only the participant's own wallet can make
it**. `pentestai/wallet.py` signs the same message:

```python
from pentestai import wallet as W
message = f"tor-vault:claim:v1|{address}|{prize_micro}|{seed}"
signature = W.b58encode(W.sign(seed_bytes, message.encode()))
```

## Fund it - the operator's checklist

The vault needs no funding of its own; the *address* does. Do these in order.

1. **Decide the prize address.** Either the operator's existing wallet
   (`python -m pentestai.wallet status` prints it) or a fresh one
   (`python -m pentestai.wallet new`). It must be a `TOR1…` address the operator
   controls, because that wallet signs the payout.
2. **Send 100 TOR to it** from a wallet that holds that much - the same `send`
   that already works against the chain:

   ```bash
   python -m pentestai.wallet send --to TOR1... --amount 100
   ```

   Keep the txid. Nothing is "available" until the node's own record confirms it.
3. **Publish the address** so the Hackathon page reads the real balance:

   ```
   PENTEST_VAULT_ADDRESS=TOR1...
   ```

   The page shows `FUNDED` only when `GET /api/account/<address>/holdings` answers
   with a positive TOR balance. It shows `not published` while the variable is
   empty - it never guesses.
4. **Start the daemon** and publish its URL. It binds `127.0.0.1` by default;
   `--bind 0.0.0.0` plus a reverse proxy is how a challenge becomes reachable.
5. **Publish the puzzle** (`GET /puzzle`) and the rules: `bits`, `prize`, the
   signing message, and that the first valid claim locks the vault forever.
6. **Pay the winner**, once:

   ```bash
   python vault/claim_to_wallet.py --state vault.json            # verifies, pays nothing
   python vault/claim_to_wallet.py --state vault.json --execute --yes
   ```

   It refuses unless: the proof still solves the puzzle, the digest matches, the
   public key really derives the named address, no receipt exists, and the chain
   is online. It writes `vault.paid.json`; a second run refuses.

### Publishing the daemon (a unit file that works)

```ini
[Unit]
Description=TOR Vault
After=network-online.target

[Service]
Type=simple
WorkingDirectory=/opt/tor-vault
ExecStart=/opt/tor-vault/tor-vault --state /var/lib/tor-vault/vault.json \
          --bits 28 --prize 100 --bind 127.0.0.1 --port 8787
Restart=always
RestartSec=3
User=torvault
Group=torvault
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
PrivateTmp=true
ReadWritePaths=/var/lib/tor-vault

[Install]
WantedBy=multi-user.target
```

The service needs write access to exactly one directory - the one holding
`vault.json` - and no capability at all. It is a small HTTP server with no TLS and
no dependencies beyond four audited crates; terminate TLS at the proxy.

## What is NOT true yet

* **Not deployed.** No daemon is running anywhere, no URL is published.
* **Not funded.** `PENTEST_VAULT_ADDRESS` is empty on every product; the page
  says so instead of showing a prize.
* **No payout has been made**, and none will be until step 6 is run by hand.
* The training (weak) vault is **not** a bug bounty: it is a practice build behind
  its own flag, and it refuses to start if anyone tries to fund it.
