tpn-proxy

What this skill does

# TPN Decentralized SOCKS5 Proxy

Route web traffic through Tao Private Network's decentralized SOCKS5 proxies — a Bittensor subnet (SN65) with commercial and residential exit nodes across 80+ countries.

Ask this skill things like:

- Open https://ipv4.icanhazip.com through a proxy in Germany
- Show me a curl command that proxies google.com through a US ip address
- I need a socks5 proxy in Japan for 30 minutes
- Which countries are available on TPN for proxies?

---

## Security Posture

| Aspect | Detail |
|--------|--------|
| Environment variables | `TPN_API_KEY` — existence-checked only (`[ -n "$TPN_API_KEY" ]`), never echoed or logged |
| Files read/written | None |
| Other secrets accessed | None — no signing keys, no credentials beyond `TPN_API_KEY` |
| Network destinations | `api.taoprivatenetwork.com` (API calls) + user-specified URLs (validated per Step 5) |
| x402 signing | Handled entirely by external libraries (`@x402/*`); this skill provides endpoint URLs only |

---

## This is an action skill

This skill executes API calls and returns results directly — it does not output documentation or instructions for the user to follow.

**Expected behaviour:**

- Call the TPN API yourself (via `curl` or equivalent) and return the full proxy credentials to the user.
- When the user asks you to fetch a URL through a proxy, make that request yourself too.
- Show the full SOCKS5 credentials (username, password, host, port) — these are short-lived and scoped to the proxy lease.
- The only time you should show the user how to call the API is when they explicitly ask "how do I do this myself?" or similar.
- If no API key exists, guide the user through account setup — that's the one step only they can do.

**A good check:** if your response contains "you can run this command to…" or "use this curl to generate…", reconsider — the user invoked this skill expecting you to run the command and hand them the output.

---

## Step-by-Step Procedure

Follow this procedure every time the user requests a proxy or asks you to fetch something through a proxy.

### Security: Input validation (mandatory)

Before constructing any shell command, **validate every user-provided value**. Never interpolate raw user input into shell commands.

| Input              | Validation rule                                                                                     |
|--------------------|------------------------------------------------------------------------------------------------------|
| `geo`              | Must be exactly 2 uppercase ASCII letters (ISO 3166-1 alpha-2). Reject anything else.                |
| `minutes`          | Must be a positive integer between 1 and 1440. Reject non-numeric or out-of-range values.            |
| `connection_type`  | Must be one of: `any`, `datacenter`, `residential`. Reject anything else.                            |
| `format`           | Must be one of: `text`, `json`. Reject anything else.                                                |
| URLs (for Step 5)  | Must start with `http://` or `https://`, contain no shell metacharacters (`` ` `` `$` `(` `)` `;` `&` `|` `<` `>` `\n`), and be a well-formed URL. |

**Rules:**

- **Never** interpolate raw user input directly into shell commands. Always validate first.
- **Never** construct `-d` JSON payloads via string concatenation with user input. Use a safe static template and only insert validated values.
- When using `curl`, always **quote** the URL and proxy URI arguments.
- Prefer using the agent's built-in HTTP tools (e.g. `WebFetch`) for fetching user-specified URLs rather than constructing `curl` commands.

### Step 1: Resolve the API key

Check whether `$TPN_API_KEY` is set in the environment (OpenClaw injects this automatically from your config):

1. Test the variable: `[ -n "$TPN_API_KEY" ] && echo "API key is set" || echo "API key is not set"` — **never** echo, log, or display the key value itself.
2. If not set → check if the user can pay via [x402](https://www.x402.org) (no API key needed), otherwise guide them through account setup (see the "Set up TPN" example)

### Step 2: Choose response format

| Situation | Use `format` | Why |
|-----------|--------------|-----|
| Just need a working proxy URI | `text` (default) | No parsing needed |
| Need to show structured host/port/user/pass breakdown | `json` | Gives individual fields |
| Not sure | `text` | Simpler, fewer things to break |

If you choose `json`, parse the response with `jq`:

```bash
curl -s ... | jq -r '.vpnConfig.username'
```

If `jq` is not available, use `format=text` instead — it returns a plain `socks5://` URI that needs no parsing.

> **Do not** use `python -c`, `grep`, `cut`, or other shell-based JSON parsing fallbacks. These patterns risk shell injection when combined with dynamic inputs. Stick to `jq` or `format=text`.

### Step 3: Generate the proxy

```bash
curl -s -X POST https://api.taoprivatenetwork.com/api/v1/proxy/generate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $TPN_API_KEY" \
  -d '{"minutes": 60, "format": "text", "connection_type": "any"}'
```

Map the user's request to these parameters:

| Field             | Type    | Required | Default | Description                                    |
|-------------------|---------|----------|---------|------------------------------------------------|
| `minutes`         | integer | yes      | —       | Lease duration (1–1440). Default to 60 if not specified. |
| `geo`             | string  | no       | any     | ISO country code (e.g. `"US"`, `"DE"`, `"JP"`) |
| `format`          | string  | no       | `text`  | `"text"` for URI string, `"json"` for object   |
| `connection_type` | string  | no       | `any`   | `"any"`, `"datacenter"`, or `"residential"`    |

> **Safe JSON body construction:** Always build the `-d` JSON payload as a static single-quoted string with only validated values inserted. Validate `geo` (2 uppercase letters), `minutes` (integer 1–1440), `connection_type` (enum), and `format` (enum) per the validation rules above **before** constructing the curl command. Never concatenate raw user input into the JSON body or any part of the command.

### Step 4: Present the result

Show the **full proxy credentials** so the user can immediately connect. These are temporary (scoped to the lease duration) and safe to display in context. Use the `socks5h://` scheme (with `h`) to ensure DNS resolves through the proxy — this protects user DNS privacy. (When the agent fetches URLs in Step 5, it uses `socks5://` instead — see Step 5.) Include:

- Structured config block (host, port, username, password, scheme, expiry)
- Full `socks5h://` URI
- A ready-to-paste `curl` example when relevant

### Step 5: If the user asked you to fetch a URL

After generating the proxy, make the request yourself. Use `socks5://` (not `socks5h://`) so DNS resolves locally — the validated IP is the connected IP.

**Use the agent's built-in HTTP tools** (e.g. `WebFetch`) to fetch the URL through the proxy. This is the preferred method — it avoids shell command construction entirely.

**URL validation — every check must pass before fetching:**

1. Scheme must be `http://` or `https://`
2. No shell metacharacters: `` ` `` `$` `(` `)` `;` `&` `|` `<` `>` newlines
3. Domain names only — reject raw IP addresses (IPv4 or IPv6)
4. Reject internal hostnames: `*.internal`, `*.local`, `*.localhost`, `*.localdomain`, `*.corp`, `*.lan`, `metadata.*`, single-label hostnames
5. Hostname must resolve via local DNS — reject unresolvable hostnames
6. Resolved IP must be publicly routable — reject `127.0.0.0/8`, `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `169.254.0.0/16`, `::1`, `fd00::/8`, `169.254.169.254`

**Fallback — curl** (only if WebFetch is unavailable). Always double-quote the URL and proxy URI:

```bash
curl --proxy "socks5://username:password@ip:port" \
  --connect-timeout 10 --max-time 30 \
  "https://validated-target-url.com"
```

Return the res