1 files changed, 99 insertions, 0 deletions

diff --git a/PLAN.md b/PLAN.md
new file mode 100644
index 0000000..c4373fb
--- /dev/null
+++ b/PLAN.md
@@ -0,0 +1,99 @@
+# TollGate ESP32 — Test-Driven Development Plan
+
+## Overview
+
+Build a TollGate firmware for two ESP32 devices, following the [TollGate protocol spec](https://github.com/OpenTollGate/tollgate) (TIP-01, TIP-02, HTTP-01/02/03). The implementation uses ESP-IDF (C/C++) and integrates the nucula Cashu wallet.
+
+## Architecture Decision: C/C++ (ESP-IDF)
+
+- Existing working captive portal is in C (ESP-IDF)
+- Nucula Cashu wallet is in C/C++ (ESP-IDF)
+- ESP-IDF is already installed at `~/esp/esp-idf`
+- No Rust/ESP32 toolchain installed
+
+## Technology Stack
+
+| Layer | Technology |
+|-------|-----------|
+| Framework | ESP-IDF v5.4.1 (C/C++) |
+| Cashu wallet | nucula `Wallet` class (Phase 3) |
+| HTTP server | `esp_http_server` (port 80 captive portal, port 2121 TollGate API) |
+| DNS | Custom UDP task (hijack unauthenticated, forward authenticated) |
+| NAT | lwIP NAPT |
+| Testing | Playwright + curl + pyserial |
+| Build | Makefile |
+
+## Three-Phase Plan
+
+### Phase 1: Captive Portal + Firewall (No Payments)
+
+**Goal:** WiFi repeater with captive portal that gates internet access. Validates DNS hijack, NAT, DHCP, firewall.
+
+**Endpoints:**
+- `GET /whoami` — returns client MAC
+- `GET /usage` — returns `-1/-1`
+- Captive portal HTML on port 80
+
+**14 Test Cases:**
+| # | Test | Method | Pass Criteria |
+|---|------|--------|---------------|
+| 1 | Boot and AP appears | Serial + nmcli | SSID visible in scan |
+| 2 | DHCP lease | nmcli connect | Gets IP in 192.168.4.0/24 |
+| 3 | Captive portal serves HTML | GET / | 200, contains "TollGate" |
+| 4 | Captive detection URIs work | GET /generate_204 etc. | All return portal HTML |
+| 5 | DNS hijack before auth | nslookup google.com | Resolves to 192.168.4.1 |
+| 6 | No internet before auth | ping 8.8.8.8 | Fails |
+| 7 | /whoami returns MAC | GET /whoami | Returns mac=XX:XX:... |
+| 8 | /usage returns no session | GET /usage | Returns -1/-1 |
+| 9 | Grant access via API | GET /grant_access | 200, status granted |
+| 10 | DNS forward after auth | nslookup google.com | Resolves to real IP |
+| 11 | Internet after auth | ping 8.8.8.8 | Succeeds |
+| 12 | HTTP browsing works | Playwright | Page loads |
+| 13 | Reset auth | GET /reset_authentication | 200 |
+| 14 | Internet blocked after reset | ping 8.8.8.8 | Fails |
+
+### Phase 2: E-Cash Payments (Simple Melt-to-LNURL)
+
+**Goal:** Replace free access with Cashu payment. ESP32 parses token, melts via mint API to operator's LNURL.
+
+**New Endpoints:**
+- `GET /` on :2121 — TollGate advertisement (kind=10021)
+- `POST /` on :2121 — Accept Cashu token, melt, return session (kind=1022) or notice (kind=21023)
+
+**13 Additional Test Cases:**
+| # | Test | Method | Pass Criteria |
+|---|------|--------|---------------|
+| 15 | Advertisement valid | GET :2121/ | kind=10021 with price_per_step |
+| 16 | Valid payment | POST :2121/ with token | kind=1022 session |
+| 17 | Usage tracking | GET :2121/usage | 0/allotment |
+| 18 | Internet after payment | ping | Succeeds |
+| 19 | Invalid token | POST :2121/ garbage | kind=21023 error |
+| 20 | Spent token | Reuse token | kind=21023 spent error |
+| 21 | Wrong mint | Token from unaccepted mint | kind=21023 mint error |
+| 22 | Session expiry | Wait for allotment | Internet blocked |
+| 23 | Session renewal | Second payment | Allotment extended |
+| 24 | Portal payment form | Playwright paste token | Checkmark shown |
+| 25 | Two clients pay independently | Two POSTs | Both authenticated |
+| 26 | Client isolation | Only payer gets internet | Non-payer blocked |
+| 27 | Full e2e: portal→pay→browse | Playwright | Complete flow |
+
+### Phase 3: nucula Wallet Integration + Reseller
+
+**Goal:** Integrate nucula's full Cashu wallet. ESP32 holds balance, can be a reseller.
+
+**11 Additional Test Cases:**
+| # | Test | Method | Pass Criteria |
+|---|------|--------|---------------|
+| 28 | Wallet boot | Serial | Keysets loaded |
+| 29 | Receive via wallet | POST :2121/ | Balance incremented |
+| 30 | Balance persists | Reboot | Same balance |
+| 31 | Payout routine | Wait + serial | Tokens melted to LN |
+| 32 | Reseller discover | Serial | Upstream TollGate found |
+| 33 | Reseller pay | Serial + API | Token POSTed upstream |
+| 34 | Multi-hop internet | Ping from laptop | laptop→A→B→internet |
+| 35 | P2PK receive | Post P2PK token | Auto-signed, accepted |
+| 36 | DLEQ verified | Post token with DLEQ | Verified, accepted |
+| 37 | 5 consecutive payments | Loop | All authenticated |
+| 38 | Stress: rapid pay/expire | Loop with short sessions | No crash/leak |
+
+## Total: 38 Tests across 3 phases