leak-cli 2026.2.17-beta.0 → 2026.2.17

package/.env.example

@@ -8,6 +8,8 @@ SELLER_PAY_TO=0xYourAddress
 PRICE_USD=0.01
 CHAIN_ID=eip155:84532
 WINDOW_SECONDS=3600
+ACCESS_MODE=payment-only-no-download-code   # no-download-code-no-payment | download-code-only-no-payment | payment-only-no-download-code | download-code-and-payment
+DOWNLOAD_CODE_HASH=                         # required for download-code modes; hash only
 
 # Required when FACILITATOR_MODE=cdp_mainnet (Base mainnet path)
 # FACILITATOR_URL=https://api.cdp.coinbase.com/platform/v2/x402

package/README.md

@@ -18,6 +18,19 @@ Package name: `leak-cli`
 
 Command: `leak`
 
+Check installed CLI version:
+
+```bash
+leak version
+# or: leak --version
+```
+
+Start interactive publish wizard:
+
+```bash
+leak publish
+```
+
 OpenClaw skill docs live in this repo at:
 - [`/skills/leak-buy`](https://github.com/eucalyptus-viminalis/leak/tree/main/skills/leak-buy)
 - [`/skills/leak-publish`](https://github.com/eucalyptus-viminalis/leak/tree/main/skills/leak-publish)
@@ -34,6 +47,12 @@ Once `leak` is configured, commands become very simple to use:
 
 **Selling**:
 
+```bash
+leak publish
+```
+
+or direct flags:
+
 ```bash
 leak --file ./your-file.bin --public
 ```
@@ -41,13 +60,27 @@ leak --file ./your-file.bin --public
 **Buying**:
 
 ```bash
-leak buy <promo_or_download_link> --buyer-private-key-file <path>
+leak buy <promo_or_download_link> [--download-code <code>] [--buyer-private-key-file <path>]
+```
+
+**Hosting multiple files on one machine (path prefixes)**:
+
+```bash
+leak host --config ./examples/multi-host.example.json
 ```
 
 ### Seller Quickstart 1: Local testnet sale (fastest path)
 
 Goal: run a local sale and verify the x402 flow end to end.
 
+Interactive wizard path:
+
+```bash
+leak publish --file ./your-file.bin
+```
+
+Direct flags path:
+
 Prereqs: fund a buyer test wallet on Base Sepolia ([Circle Faucet](https://faucet.circle.com)); no CDP mainnet setup is needed. 
 
 ```bash
@@ -84,6 +117,73 @@ Use the output URLs like this:
 - open the promo URL in a browser and confirm title, description, and image render correctly for social cards
 - while the tunnel is still running, run the Buyer section below to validate payment + download end-to-end
 
+### Seller Quickstart 3: Multi-file hosting with one domain + path prefixes
+
+Goal: run multiple leak endpoints on one machine and expose them as:
+- `https://<host>/leak/lolboy/` + `/download`
+- `https://<host>/leak/peter/` + `/download`
+
+Use the built-in multi-host runner:
+
+```bash
+leak host --config ./examples/multi-host.example.json
+```
+
+What this command does:
+- starts one leak worker per route (one local port per artifact)
+- starts one reverse proxy that maps `/<prefix>/*` to the right worker
+- sets `PUBLIC_BASE_URL` per worker to `<resolvedOrigin><prefix>` so promo/download URLs are prefix-aware
+
+Dry-run before launching:
+
+```bash
+leak host --config ./examples/multi-host.example.json --dry-run
+```
+
+Local validation with the default example:
+
+```bash
+curl -i http://127.0.0.1:4080/leak/lolboy/
+curl -i http://127.0.0.1:4080/leak/lolboy/download
+curl -i http://127.0.0.1:4080/leak/peter/
+curl -i http://127.0.0.1:4080/health
+```
+
+Public origin modes:
+- local-only (default): no tunnel, origin is `http://127.0.0.1:<proxy-port>`
+- quick tunnel: add `--public` and leak host will start one Cloudflare quick tunnel for the shared proxy
+- configured origin: set optional `publicOrigin` in config for named/manual ingress
+
+Quick tunnel run (non-interactive):
+
+```bash
+leak host --config ./examples/multi-host.example.json --public --public-confirm I_UNDERSTAND_PUBLIC_EXPOSURE
+```
+
+Configured-origin run (named/manual tunnel):
+
+```json
+{
+  "publicOrigin": "https://your-hostname.example",
+  "proxy": { "host": "127.0.0.1", "port": 4080 },
+  "routes": [ ... ]
+}
+```
+
+Precedence note:
+- if `--public` is used and `publicOrigin` exists in config, leak host uses configured `publicOrigin` and does not start a quick tunnel
+
+Capacity baseline (M1 Mac mini, 8 GB RAM, up to 10 concurrent downloads):
+
+| Total hosted content | RAM working set | Disk free target | Practical uplink target |
+| --- | --- | --- | --- |
+| `5 MB` | `~4-5 GB` | `>=20 GB` | `10-20 Mbps` |
+| `50 MB` | `~4-5 GB` | `>=20 GB` | `20-50 Mbps` |
+| `500 MB` | `~4.5-5.5 GB` | `>=22-25 GB` | `50-150 Mbps` |
+| `5 GB` | `~5-6 GB` | `>=30-40 GB` | `200+ Mbps` |
+
+These numbers assume streamed downloads (no whole-file memory loading), one route per worker, and one local reverse proxy.
+
 ### Buyer Skeleton (direct CLI)
 
 Use the direct CLI buy flow:
@@ -92,10 +192,19 @@ Use the direct CLI buy flow:
 leak buy "https://xxxx.trycloudflare.com/" --buyer-private-key-file ./buyer.key
 ```
 
-`leak buy` accepts either the promo URL (`/`) or direct x402 URL (`/download`).
+For download-code modes, add:
+
+```bash
+leak buy "https://xxxx.trycloudflare.com/" --download-code "friends-only"
+```
+
+`leak buy` accepts either the promo URL (`/`) or direct `/download` URL.
 By default, the file is saved to your current directory using the server-provided filename; use `--out` or `--basename` to control naming.
 When settlement metadata is returned, `leak buy` also prints a receipt block with network + transaction hash (and Basescan link on Base networks).
 
+If the sale access mode includes payment, pass a buyer key (`--buyer-private-key-file` or `--buyer-private-key-stdin`).
+If the sale access mode includes download-code, pass `--download-code <code>` (or `--download-code-stdin`).
+
 Security note: use a dedicated buyer key with limited funds.
 
 ### Buyer Skeleton (Clawhub skill flow)
@@ -109,8 +218,9 @@ The hardened skills require a preinstalled `leak` binary on PATH.
 
 Recommended first-time agent UX for unknown URLs:
 - ask only for skill-install approval (`clawhub install leak-buy`)
-- ask for an existing buyer key file path
-- run: `bash skills/leak-buy/scripts/buy.sh "<promo_or_download_url>" --buyer-private-key-file <buyer_key_file_path>`
+- ask for an existing buyer key file path when payment is required
+- ask for download code when download-code is required
+- run: `bash skills/leak-buy/scripts/buy.sh "<promo_or_download_url>" --buyer-private-key-file <buyer_key_file_path>` (append `--download-code <code>` when needed)
 - avoid protocol deep-dives unless the user explicitly asks for x402 internals
 
 ### Next: Mainnet checklist (optional)
@@ -153,6 +263,23 @@ Reference: see [Testnet vs Mainnet facilitator setup](#testnet-vs-mainnet-facili
 
 The easiest way to run the server is the `leak` CLI, which prompts for missing info (price + duration) and auto-stops after the sale window (or `window + ended-window`, if configured).
 
+Recommended for humans: use `leak publish` for a guided interactive wizard.
+Recommended for scripts/automation: use `leak --file ...` direct flags.
+
+```bash
+leak publish
+```
+
+Wizard behavior:
+- Basic step always asks core publish inputs (file, access mode, price/window, network, public tunnel).
+- Advanced step is optional and includes facilitator, port, OG metadata, and ended-window fields.
+- Final summary always requires explicit confirmation before launch.
+- Wizard offers (optional) saving values to `~/.leak/config.json`.
+- Publish runs are always supervised: if the worker crashes, leak restarts it automatically with the remaining sale time.
+- Sale deadlines are fixed at first launch; restarts do not extend total availability.
+- Run-state is persisted at `~/.leak/runs/<run_id>.json` (plus `~/.leak/runs/latest.json` pointer).
+- In `--public` mode, tunnel URLs may rotate after a restart; leak reprints new links and persists latest URLs in run-state.
+
 ```bash
 cd ~/leak
 npm run leak -- --file /path/to/vape.jpg
@@ -175,6 +302,13 @@ It will ask:
 - **How long?** (e.g. `15m`, `1h`)
 
 Optional flags:
+- `--access-mode <mode>` where mode is one of:
+  - `no-download-code-no-payment`
+  - `download-code-only-no-payment`
+  - `payment-only-no-download-code` (default)
+  - `download-code-and-payment`
+- `--download-code "friends-only"` (required for download-code modes)
+- `--download-code-stdin` (read download code from stdin)
 - `--price 0.01` (USDC)
 - `--window 1h` (or seconds)
 - `--confirmed` (settle on-chain before issuing token)
@@ -184,7 +318,7 @@ Optional flags:
 - `--og-image-url https://...` (absolute `http(s)` URL) or `--og-image-url ./cover.png` (local image path)
 - `--ended-window-seconds 86400` (keep ended promo page online before auto-stop)
 - `--network eip155:84532`
-- `--pay-to 0x...` (must be a valid Ethereum address)
+- `--pay-to 0x...` (required only for payment modes; must be a valid Ethereum address)
 - `--port 4021`
 
 ### Persistent config (`leak config`)
@@ -257,12 +391,16 @@ npm run leak -- --file ./song.mp3 --pay-to 0x... --price 1 --window 1h --public
 When a local image path is used for `--og-image-url`, leak serves it from `/og-image` and points OG/Twitter metadata at that endpoint.
 Without `--og-image-url`, leak serves a generated raster OG card from `/og.png` (and keeps `/og.svg` for debug/backward compatibility).
 
-This mirrors the behavior of the original Python scaffold implementation:
+Payment-mode behavior (`payment-only-no-download-code` / `download-code-and-payment`):
 
 - `GET /download` without payment → **402** with `PAYMENT-REQUIRED` header
 - `GET /download` with valid payment headers → returns a **time-limited token** JSON
 - `GET /download?token=...` → streams the artifact
 
+Download-code behavior (`download-code-*` modes):
+- send `X-LEAK-DOWNLOAD-CODE: <code>` on `GET /download`
+- missing/invalid code returns **401**
+
 ### Testnet vs Mainnet facilitator setup
 
 `CHAIN_ID=eip155:8453` by itself is **not enough** for production.
@@ -336,7 +474,7 @@ Server will print:
 - `http://localhost:4021/` (promo page)
 - `http://localhost:4021/info` (machine-readable info)
 - `http://localhost:4021/health`
-- `http://localhost:4021/download` (x402-protected)
+- `http://localhost:4021/download` (protection depends on `ACCESS_MODE`)
 
 ---
 
@@ -348,7 +486,10 @@ Server will print:
 curl -i http://localhost:4021/download
 ```
 
-You should get `402` and a `PAYMENT-REQUIRED` header.
+You should get mode-specific behavior:
+- payment mode: `402` + `PAYMENT-REQUIRED`
+- download-code mode without header: `401`
+- no-payment/no-download-code mode: direct file response
 
 ### B) Paid request → token
 
@@ -406,10 +547,10 @@ export LEAK_DEV=1   # allows BASE_URL to default to http://127.0.0.1:4021
 ```
 
 What it does:
-- first `GET /download` expects **402** + `PAYMENT-REQUIRED`
-- creates a payment payload, retries with `PAYMENT-SIGNATURE`
-- receives `{ token, download_url, filename, mime_type }`
-- downloads via `?token=` and saves to disk
+- if payment is required, first `GET /download` gets **402** + `PAYMENT-REQUIRED`
+- if download-code is required, sends `X-LEAK-DOWNLOAD-CODE`
+- handles payment/token flow when required
+- saves the downloaded artifact
 
 ### C) Use token → download
 
@@ -425,16 +566,16 @@ curl -L -o out.bin "http://localhost:4021/download?token=..."
   - `200` while sale is active
   - `200` once sale has ended (ended state is shown in page content/metadata)
 - `GET|HEAD /.well-known/skills/index.json` RFC skill discovery index
-- `GET|HEAD /.well-known/skills/leak/SKILL.md` RFC skill metadata markdown
-- `GET|HEAD /.well-known/skills/leak/resource.json` RFC sale/resource metadata (`200` live, `410` ended)
+- `GET|HEAD /.well-known/skills/leak-buy/SKILL.md` RFC skill metadata markdown
+- `GET|HEAD /.well-known/skills/leak-buy/resource.json` RFC sale/resource metadata (`200` live, `410` ended)
 - `GET /.well-known/leak` legacy discovery endpoint (backward-compatible)
 - `GET /info` machine-readable JSON status (compat endpoint)
 - `GET|HEAD /og-image` configured OG image file (when using local `--og-image-url` path)
 - `GET|HEAD /og.png` generated default OG image (used when `--og-image-url` is not set)
 - `GET|HEAD /og.svg` debug/backward-compatible OG SVG
 - `GET /health` free health check
-- `GET /download` x402-protected download endpoint
-  - active sale: normal x402/token flow
+- `GET /download` access-controlled download endpoint
+  - active sale: behavior depends on `ACCESS_MODE`
   - ended sale: `410`
 
 ---
@@ -455,8 +596,14 @@ curl -L -o out.bin "http://localhost:4021/download?token=..."
 - `FACILITATOR_URL`
   - default with `FACILITATOR_MODE=testnet`: `https://x402.org/facilitator`
   - default with `FACILITATOR_MODE=cdp_mainnet`: `https://api.cdp.coinbase.com/platform/v2/x402`
-- `SELLER_PAY_TO` receiving address (valid Ethereum address, `0x` + 40 hex chars)
+- `SELLER_PAY_TO` receiving address (required only for payment modes; valid Ethereum address, `0x` + 40 hex chars)
 - `PRICE_USD` (string like `1.00`)
+- `ACCESS_MODE`:
+  - `no-download-code-no-payment`
+  - `download-code-only-no-payment`
+  - `payment-only-no-download-code` (default)
+  - `download-code-and-payment`
+- `DOWNLOAD_CODE_HASH` (required for download-code modes; hash only, not raw code)
 - `CHAIN_ID`
   - default: `eip155:84532` (Base Sepolia) for `x402.org/facilitator`
   - Base mainnet: `eip155:8453` (requires `FACILITATOR_MODE=cdp_mainnet` plus CDP keys)

package/examples/multi-host.example.json

@@ -0,0 +1,50 @@
+{
+  "_hints": {
+    "accessMode_source_of_truth": "src/access_mode.js (ACCESS_MODE_VALUES)",
+    "accessMode_allowed_values": [
+      "no-download-code-no-payment",
+      "download-code-only-no-payment",
+      "payment-only-no-download-code",
+      "download-code-and-payment"
+    ]
+  },
+  "proxy": {
+    "host": "127.0.0.1",
+    "port": 4080
+  },
+  "defaults": {
+    "window": "1h",
+    "network": "eip155:84532",
+    "payTo": "0x1111111111111111111111111111111111111111",
+    "price": "0.01",
+    "facilitatorMode": "testnet",
+    "facilitatorUrl": "https://x402.org/facilitator",
+    "confirmationPolicy": "confirmed",
+    "endedWindowSeconds": 86400
+  },
+  "routes": [
+    {
+      "slug": "lolboy",
+      "prefix": "/leak/lolboy",
+      "port": 4101,
+      "artifactPath": "./protected/lol.mp3",
+      "accessMode": "payment-only-no-download-code",
+      "ogTitle": "lolboy",
+      "ogDescription": "limited drop",
+      "payTo": "0x1111111111111111111111111111111111111111",
+      "price": "0.01"
+    },
+    {
+      "slug": "peter",
+      "prefix": "/leak/peter",
+      "port": 4102,
+      "artifactPath": "./protected/peterkek.mp3",
+      "accessMode": "download-code-and-payment",
+      "downloadCode": "friends-only",
+      "ogTitle": "peter",
+      "ogDescription": "friends release",
+      "payTo": "0x1111111111111111111111111111111111111111",
+      "price": "0.02"
+    }
+  ]
+}

package/package.json

@@ -1,16 +1,19 @@
 {
   "name": "leak-cli",
-  "version": "2026.2.17-beta.0",
+  "version": "2026.2.17",
   "description": "Self-hosted pop-up stores for creators -- with agent-friendly automation built in",
   "type": "module",
   "main": "src/index.js",
   "files": [
     "src/",
     "scripts/cli.js",
+    "scripts/host.js",
     "scripts/leak.js",
     "scripts/buy.js",
     "scripts/config.js",
     "scripts/config_store.js",
+    "scripts/ui.js",
+    "examples/",
     "README.md",
     ".env.example",
     "LICENSE"
@@ -22,6 +25,7 @@
     "start": "node src/index.js",
     "dev": "node --watch src/index.js",
     "cli": "node scripts/cli.js",
+    "host": "node scripts/host.js",
     "buyer": "node scripts/buyer_test.js",
     "leak": "node scripts/leak.js",
     "buy": "node scripts/buy.js",
@@ -29,9 +33,10 @@
     "check:changelog-version": "node scripts/check_changelog_version.js",
     "check:no-local-paths": "node scripts/check_no_local_paths.js",
     "check:skill-security": "bash scripts/check_skill_security.sh",
-    "check:syntax": "node --check src/index.js && node --check src/chain_meta.js && node --check scripts/cli.js && node --check scripts/leak.js && node --check scripts/buy.js && node --check scripts/config.js",
-    "check:smoke": "node scripts/cli.js --help && node scripts/leak.js --help && node scripts/buy.js --help && node scripts/config.js --help",
-    "check:release": "npm run check:version-sync && npm run check:skill-security && npm run check:syntax && npm run check:smoke && npm run check:no-local-paths && npm pack --dry-run --cache ./.npm-cache",
+    "check:download-code-terminology": "bash scripts/check_download_code_terminology.sh",
+    "check:syntax": "node --check src/index.js && node --check src/chain_meta.js && node --check src/access_mode.js && node --check src/download_code.js && node --check scripts/ui.js && node --check scripts/cli.js && node --check scripts/host.js && node --check scripts/leak.js && node --check scripts/buy.js && node --check scripts/config.js",
+    "check:smoke": "node scripts/cli.js --help && node scripts/cli.js publish --help && node scripts/cli.js host --help && node scripts/cli.js --version && node scripts/cli.js version && node scripts/leak.js --help && node scripts/buy.js --help && node scripts/config.js --help && node scripts/host.js --help",
+    "check:release": "npm run check:version-sync && npm run check:skill-security && npm run check:download-code-terminology && npm run check:syntax && npm run check:smoke && npm run check:no-local-paths && npm pack --dry-run --cache ./.npm-cache",
     "release:beta": "npm publish --tag beta --provenance",
     "release:latest": "npm publish --tag latest --provenance"
   },