# Proksusha — agent guide

Use this file when helping a developer call Proksusha (goproxy).
Prefer facts below over guessing. Hosts like `ru.proksusha.ru` are placeholders; use the real base URL and `pk_live_…` key the user received.

## What it is

HTTP(S) gateway only. Client sends an HTTP request to a Proksusha node with a gateway API key. The gateway fetches/proxies the target URL via `direct`, `chain`, or multi-hop routing and streams the response back.

Not a VPN. Not WireGuard. Not browser-wide tunneling.

## Critical auth rule (do not mix secrets)

| Secret | Header | Goes to |
|--------|--------|---------|
| Gateway key `pk_live_…` | `X-Api-Key` (or `Authorization: Bearer pk_live_…`) | Proksusha only — never send to OpenAI/Telegram/etc. |
| Upstream secret (`sk-…`, bot token, vendor token) | `X-Upstream-Authorization` or `X-Upstream-X-*` | Target service |

Mapping:

- `X-Upstream-Authorization: Bearer sk-…` → target gets `Authorization: Bearer sk-…`
- `X-Upstream-X-Auth-Token: secret` → target gets `X-Auth-Token: secret`
- `X-Upstream-X-Api-Key: …` → target gets `X-Api-Key: …`

If gateway auth is already `X-Api-Key`, a non-`pk_live_` `Authorization` may be treated as upstream.

## Base URL

```
BASE=https://ru.proksusha.ru   # replace with real entry host
KEY=pk_live_...                    # gateway key
```

Error body shape always: `{"error":"message"}`.

## Routing headers

| Header | Meaning |
|--------|---------|
| `X-Chain` | Explicit hops, e.g. `ru->de` or `ru->de->nl`. Overrides mode when set. |
| `X-Proxy-Mode` | `direct` \| `chain` |
| `X-Exit-Node` | Exit region or `auto` (latency-based) |
| `X-Entry-Node` | Entry region for chain |

Common patterns:

- From RU-friendly entry: `X-Chain: ru->de`
- Direct exit only: `X-Proxy-Mode: direct` + `X-Exit-Node: de` against DE host
- Auto exit: `X-Exit-Node: auto`

Response often includes `X-Proxy-Chain`, `X-Exit-Node`.

## Endpoints

### Health

`GET /health` — public. Returns node id/region/role.

### Auth (cabinet JWT)

`POST /v1/auth/register`

```json
{
  "email": "user@example.com",
  "name": "User",
  "password": "password123",
  "password_confirm": "password123"
}
```

Rules: email with `@`, non-empty name, password ≥ 8, passwords match.
`201` → `{ "token": "<JWT>", "user": {...} }`
`409` email taken.

`POST /v1/auth/login` → `{ "email", "password" }` → same token shape.
`GET /v1/me` — JWT required.

JWT is for cabinet management (keys, origins, ingress). Data-plane scripts usually use `pk_live_…`.

### API keys (JWT)

`POST /v1/api-keys` `{ "name": "main", "scopes": ["proxy","fetch","ingress"] }`
Raw `key` (`pk_live_…`) returned **once**.
`GET /v1/api-keys`, `DELETE /v1/api-keys/{id}` (revoke).

### Proxy (API key scope `proxy` or JWT)

Any method to upstream:

- `METHOD /v1/proxy?url=https://example.com/path`
- or `/v1/proxy/https://example.com/path`

Forwards method, body, most headers. Transparent status/body from upstream.

OpenAI example:

```bash
curl -X POST "$BASE/v1/proxy?url=https://api.openai.com/v1/chat/completions" \
  -H "X-Api-Key: $KEY" \
  -H "X-Upstream-Authorization: Bearer $OPENAI_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Chain: ru->de" \
  -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"hi"}]}'
```

Telegram example:

```bash
curl -H "X-Api-Key: $KEY" -H "X-Chain: ru->de" \
  "$BASE/v1/proxy?url=https://api.telegram.org/bot$BOT_TOKEN/getMe"
```

### Fetch (scope `fetch`)

`GET /v1/fetch?url=https://example.com/file.zip` — GET proxy for downloads.

```bash
curl -L -H "X-Api-Key: $KEY" -H "X-Chain: ru->de" \
  "$BASE/v1/fetch?url=https://example.com/app.zip" -o app.zip
```

### Origins / CDN (JWT to manage; public to read)

`POST /v1/origins`:

```json
{
  "slug": "jsdelivr",
  "target_base": "https://cdn.jsdelivr.net",
  "entry_node": "ru",
  "exit_node": "auto",
  "proxy_mode": "chain"
}
```

Public: `GET|POST|… /o/{slug}/{path}` → `{target_base}/{path}` (no browser API key).
Also: `GET /v1/origins`, `PATCH /v1/origins/{id}`, `DELETE /v1/origins/{id}`.

### Ingress / webhooks (JWT to manage; public to receive)

`POST /v1/ingress`:

```json
{
  "name": "payments",
  "forward_url": "https://backend.example.ru/webhook",
  "entry_node": "ru",
  "proxy_mode": "chain"
}
```

`201` includes `token`, `public_url`.
Public: `ANY /in/{token}` → forward to `forward_url`.

### Nodes

`GET /v1/nodes` (JWT or API key), optional `?host=api.telegram.org`.

### Logs (JWT, cabinet)

**Off by default** (`logging_enabled: false` on the user). While disabled, the gateway does not write access logs for the account; list endpoints return `{ items: [], limit: 20, logging_enabled: false }`.

Enable: `PATCH /v1/me/settings` with `{ "logging_enabled": true }` (or the cabinet toggle). Then last **20** access logs only (`limit` default/max `20`). No request body, no raw secrets.

- `GET /v1/me` — includes `logging_enabled`
- `PATCH /v1/me/settings` `{ "logging_enabled": true|false }`
- `GET /v1/logs?limit=20` — recent logs for the account
- `GET /v1/logs?key_id={api_key_id}&limit=20` — logs for one API key
- `GET /v1/logs?node=de&limit=20` — logs from a node
- `GET /v1/nodes/{id}/logs?limit=20` — same as `?node={id}` (one node)

Item shape: `{ id, user_id, api_key_id, kind, method, target_host, path, entry_node, exit_node, chain, node, status_code, bytes_in, bytes_out, duration_ms, created_at }`.
Response also includes `logging_enabled`.

### Internal

`/internal/*` + `X-Internal-Token` — peer-only. Clients must not call.

## Status codes

| Code | Meaning |
|------|---------|
| 400 | missing/invalid url, chain loop |
| 401 | missing/bad gateway key |
| 403 | SSRF blocked or missing scope |
| 502 | upstream or peer failure |

## Security / trust (honest)

- client↔entry: TLS
- entry↔exit: HTTPS peers; sensitive headers sealed AES-256-GCM (`X-Sealed-Headers`)
- exit↔target: normal HTTPS; exit stack must process plaintext to dial target (HTTP gateway, not E2E)
- API keys stored hashed (SHA-256); passwords bcrypt; dial SSRF-filtered
- Do not log raw Authorization/body in access logs (product policy)

## Agent checklist

1. Ask user for real `BASE` host and `pk_live_…` (or JWT for cabinet ops).
2. Never put gateway key in upstream headers.
3. Prefer `X-Upstream-*` for target secrets.
4. Default RU-friendly path: `X-Chain: ru->de` unless user specifies direct/DE-only.
5. URL-encode target URLs in query params.
6. For CDN/frontends prefer `/o/{slug}/…` after creating origin once.
7. For webhooks create ingress once, give `/in/{token}` to the vendor.
8. For logs: first enable with `PATCH /v1/me/settings` `{ "logging_enabled": true }` (off by default), then JWT `GET /v1/logs?key_id=…` or `/v1/nodes/{id}/logs` (last 20 only).
9. Do not invent VPN setup; stay on HTTP endpoints above.
10. If access missing: tell user to email support@proksusha.ru with scenario.

## Minimal Python (httpx)

```python
import httpx
BASE = "https://ru.proksusha.ru"
KEY = "pk_live_..."
r = httpx.post(
    f"{BASE}/v1/proxy",
    params={"url": "https://api.openai.com/v1/chat/completions"},
    headers={
        "X-Api-Key": KEY,
        "X-Upstream-Authorization": "Bearer sk-...",
        "Content-Type": "application/json",
        "X-Chain": "ru->de",
    },
    json={"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "hi"}]},
)
r.raise_for_status()
print(r.json())
```

## Minimal Node (fetch)

```js
const BASE = "https://ru.proksusha.ru";
const KEY = "pk_live_...";
const target = encodeURIComponent("https://httpbin.org/get");
const res = await fetch(`${BASE}/v1/proxy?url=${target}`, {
  headers: { "X-Api-Key": KEY, "X-Chain": "ru->de" },
});
console.log(await res.json());
```