Merge branch 'main' of github.com-red:Routstr/routstr-core into ehbp-proxy-refactor

bump version

.env.example

@@ -2,6 +2,9 @@
 UPSTREAM_BASE_URL=https://api.openai.com/v1
 UPSTREAM_API_KEY=your-upstream-api-key
 
+# Tinfoil (confidential inference enclaves, EHBP)
+# TINFOIL_API_KEY=your-tinfoil-api-key
+
 # ADMIN_PASSWORD=secure-admin-password
 
 # Database

.gitignore

@@ -38,3 +38,4 @@ proof_backups
 
 *.todo
 ui_out
+.worktrees

docs/ehbp-proxy-support.md

@@ -0,0 +1,158 @@
+# EHBP Proxy Support for Tinfoil Models
+
+## Problem
+
+The SDK's `SecureClient.fetch` encrypts request bodies with HPKE (EHBP protocol)
+and sends them to the Routstr provider. The Routstr proxy had no EHBP handling:
+
+1. It tried to `json.loads()` the binary HPKE-sealed body → failed with a 400
+2. The upstream PPQ.AI public endpoint (`/v1/chat/completions`) doesn't speak
+   EHBP, so the response had no `Ehbp-Response-Nonce` header
+3. `SecureClient` threw `Missing Ehbp-Response-Nonce header` because it expects
+   every response from an EHBP-configured `baseURL` to carry that header
+
+## Root cause
+
+PPQ.AI exposes EHBP-aware inference at `/private/`, separate from the public
+`/v1/` endpoint. The Routstr proxy was forwarding to `/v1/` (the public
+endpoint) instead of `/private/` (the enclave endpoint). The public endpoint
+can't decrypt the body, returns a normal HTTP response, and the SDK can't
+decrypt it because there's no nonce header.
+
+The PPQ private-mode proxy (`ppq-private-mode-proxy/lib/proxy.ts`) shows the
+correct pattern: `SecureClient` talks to `api.ppq.ai/private/v1/chat/completions`,
+which decrypts inside the attested enclave and returns an EHBP-encrypted
+response with the `Ehbp-Response-Nonce` header.
+
+## What was changed
+
+### `routstr/proxy.py`
+
+Detects EHBP requests by checking for the `Ehbp-Encapsulated-Key` header (set
+by the EHBP transport on every encrypted request). For EHBP requests:
+
+- Skips JSON body parsing (the body is binary ciphertext, not JSON)
+- Reads the model ID from the `X-Routstr-Model` header (set by the SDK) instead
+  of from `body.model`
+- Routes through new `forward_ehbp_request` (bearer auth) and
+  `forward_ehbp_x_cashu_request` (x-cashu auth) methods
+- Skips reactive 400 param correction (can't parse encrypted response body)
+- Still charges the user via `pay_for_request` (uses `max_cost_for_model` from
+  the model registry, not the body)
+
+### `routstr/upstream/base.py`
+
+Keeps EHBP as an explicit opt-in provider capability instead of making every
+upstream provider appear EHBP-capable:
+
+- `supports_ehbp = False` by default
+- `get_ehbp_forwarding_target(path, model_obj)` raises `NotImplementedError`
+  unless a provider opts in and returns a provider-specific EHBP target
+
+The actual EHBP forwarding logic does **not** live in `base.py`.
+
+### `routstr/upstream/ehbp.py`
+
+Contains the shared opaque EHBP transport helpers:
+
+- `EHBPForwardingTarget` — provider-specific target URL plus extra headers
+- `forward_ehbp_request()` — forwards the raw encrypted body to an EHBP-capable
+  provider, streams the encrypted response back untouched, and finalizes bearer
+  billing at max cost because usage is encrypted
+- `forward_ehbp_x_cashu_request()` — redeems the Cashu token, forwards raw,
+  refunds the full token on upstream failure, and refunds any value above
+  `max_cost_for_model` on success
+
+### `routstr/upstream/ppqai.py`
+
+- Sets `supports_ehbp = True`.
+- Implements `get_ehbp_forwarding_target()` to forward to
+  `https://api.ppq.ai/private/v1/...` — the PPQ.AI enclave endpoint that
+  understands EHBP and returns the `Ehbp-Response-Nonce` header.
+- Adds `X-Private-Model` with the model's `forwarded_model_id` (e.g.
+  `private/kimi-k2-6`). PPQ.AI's billing layer needs this since it can't
+  decrypt the body.
+
+## Why it's done this way
+
+The proxy is a **blind relay** for EHBP requests. It cannot decrypt the body
+(only the attested enclave can), so it must:
+
+1. Get the model ID from a header, not the body
+2. Forward the raw bytes without parsing or transformation
+3. Stream the response back without SSE/cost parsing
+4. Pass through EHBP protocol headers (`Ehbp-Encapsulated-Key` on request,
+   `Ehbp-Response-Nonce` on response)
+
+Cost tracking happens at the proxy level using `max_cost_for_model` from the
+model registry. Because EHBP responses are encrypted, Routstr cannot reconcile
+against token usage. Bearer requests reserve and then finalize max-cost billing;
+X-Cashu requests redeem the token and refund any amount above max cost.
+
+## End-to-end flow
+
+```
+SDK                                  Routstr Proxy                    PPQ.AI /private/
+  │                                       │                                │
+  │── X-Routstr-Model: tinfoil-kimi-k2-6 ─│                                │
+  │── Ehbp-Encapsulated-Key: <hex> ───────│                                │
+  │── Authorization: Bearer <cashu> ──────│                                │
+  │── body = HPKE-encrypted(kimi-k2-6) ───│                                │
+  │                                       │                                │
+  │                                  detects Ehbp-Encapsulated-Key         │
+  │                                  reads model from X-Routstr-Model      │
+  │                                  does billing/routing                  │
+  │                                       │                                │
+  │                                  adds X-Private-Model: private/kimi-k2-6
+  │                                  forwards raw body to /private/v1/...  │
+  │                                       │──────────────────────────────▶│
+  │                                       │                          enclave decrypts
+  │                                       │                          runs inference
+  │                                       │◀── Ehbp-Response-Nonce ──────│
+  │                                       │◀── encrypted response ────────│
+  │                                       │                                │
+  │                                  streams response back untouched       │
+  │◀── encrypted response ────────────────│                                │
+  │                                        │                                │
+  SecureClient reads nonce, decrypts       │                                │
+  SDK SSE processing sees plaintext        │                                │
+```
+
+## Model ID mapping
+
+Three parties see three different model IDs:
+
+| Party | Header/Body | Value | Source |
+|---|---|---|---|
+| Routstr proxy | `X-Routstr-Model` header | `tinfoil-kimi-k2-6` | SDK sends full caller-facing id |
+| PPQ.AI billing | `X-Private-Model` header | `private/kimi-k2-6` | Proxy sends `forwarded_model_id` |
+| Tinfoil enclave | `body.model` (encrypted) | `kimi-k2-6` | SDK strips `tinfoil-` prefix before encryption |
+
+## Implementation status
+
+A dedicated `TinfoilUpstreamProvider` (`routstr/upstream/tinfoil.py`) now
+implements the direct blind-upstream pattern described above. The shared EHBP
+helpers in `routstr/upstream/ehbp.py` were extended to:
+
+- Request usage metrics via `X-Tinfoil-Request-Usage-Metrics: true`.
+- Parse `X-Tinfoil-Usage-Metrics` from the response header (non-streaming).
+- Override the forwarding URL with `X-Tinfoil-Enclave-Url` when the SDK sends it.
+- Finalize bearer billing with actual token cost via `adjust_payment_for_tokens`.
+- Compute X-Cashu refunds from actual cost instead of max cost.
+
+See `docs/tinfoil-direct-integration.md` for the full implementation notes.
+
+## Not yet tested
+
+These changes were written without integration testing due to the complexity
+of the full stack (SDK + proxy + PPQ.AI enclave + Cashu mint). Needs end-to-end
+verification with a real `tinfoil-*` model request.
+
+Important assumptions to verify:
+
+- PPQ.AI accepts `/private/v1/...` with `X-Private-Model`.
+- PPQ.AI enforces consistency between `X-Private-Model` and the encrypted
+  `body.model`, otherwise a malicious client could understate
+  `X-Routstr-Model` for billing.
+- SDK behavior on non-2xx proxy-generated errors that do not carry
+  `Ehbp-Response-Nonce`.

docs/tinfoil-direct-integration.md

@@ -0,0 +1,460 @@
+# Tinfoil / PPQ Private-Mode Integration Notes
+
+This document summarizes the current options for integrating Tinfoil/PPQ private models with Routstr, based on the EHBP work in this branch and local testing against `ppq-private-mode-proxy`.
+
+## Background
+
+PPQ private models run behind a Tinfoil/EHBP flow:
+
+- Request bodies are HPKE-encrypted by a Tinfoil client.
+- The PPQ `/private/` endpoint routes ciphertext to the attested enclave.
+- The enclave decrypts, runs inference, and returns an encrypted response.
+- The caller's Tinfoil client decrypts the response locally.
+
+The PPQ private-mode proxy (`~/projects/ppq-private-mode-proxy`) uses this pattern with the JavaScript `tinfoil` SDK:
+
+```ts
+import { SecureClient } from "tinfoil";
+
+const apiBase = "https://api.ppq.ai";
+
+const client = new SecureClient({
+  baseURL: `${apiBase}/private/`,
+  attestationBundleURL: `${apiBase}/private`,
+  transport: "ehbp",
+});
+
+await client.ready();
+
+const response = await client.fetch(`${apiBase}/private/v1/chat/completions`, {
+  method: "POST",
+  headers: {
+    "Content-Type": "application/json",
+    Authorization: `Bearer ${process.env.PPQ_API_KEY}`,
+    "X-Private-Model": "private/gpt-oss-120b",
+    "x-query-source": "api",
+  },
+  body: JSON.stringify({
+    model: "gpt-oss-120b", // enclave-internal model id
+    messages: [{ role: "user", content: "Hello" }],
+  }),
+});
+
+const json = await response.json();
+console.log(json.usage);
+```
+
+`X-Private-Model` carries the PPQ-facing private model id, while the encrypted JSON body uses the enclave-internal model id without the `private/` prefix.
+
+## PPQ private model pricing
+
+PPQ exposes private model pricing through:
+
+```text
+GET https://api.ppq.ai/v1/models?type=all
+```
+
+Filter models whose IDs start with `private/`.
+
+Example private pricing observed:
+
+| Model | Input USD / 1M tokens | Output USD / 1M tokens |
+|---|---:|---:|
+| `private/gpt-oss-120b` | `0.79125` | `1.31875` |
+| `private/llama3-3-70b` | `1.84625` | `2.90125` |
+| `private/qwen3-vl-30b` | `1.31875` | `4.22` |
+| `private/glm-5-2` | `1.5825` | `5.53875` |
+| `private/gemma4-31b` | `0.47475` | `1.055` |
+| `private/kimi-k2-6` | `1.5825` | `5.53875` |
+
+The `ppq-private-mode-proxy` commit `ba984214793d3bca0f7d046b6955d42abc1c6843` changed OpenClaw display metadata to align with a 5% API margin. The live PPQ model endpoint returns the more precise rates above, which already include that margin.
+
+Actual PPQ private billing is:
+
+```text
+price_usd =
+  input_tokens  * input_per_1M_tokens  / 1_000_000
++ output_tokens * output_per_1M_tokens / 1_000_000
+```
+
+A test request to `private/gpt-oss-120b` produced:
+
+```json
+{
+  "input_count": 74,
+  "output_count": 3,
+  "price_in_usd": 0.00006250875
+}
+```
+
+which exactly matches:
+
+```text
+74 * 0.79125 / 1_000_000 + 3 * 1.31875 / 1_000_000
+= 0.00006250875 USD
+```
+
+## Integration architectures
+
+There are three materially different ways Routstr could integrate Tinfoil/PPQ private inference.
+
+## Option A: User integrates Tinfoil directly
+
+```text
+User app / SDK
+  -> Tinfoil SecureClient / TinfoilAI
+    -> EHBP-encrypted request
+      -> Tinfoil/PPQ private enclave
+```
+
+Properties:
+
+- Best privacy for the user.
+- Routstr is not in the request path.
+- User's client encrypts requests and decrypts responses.
+- Usage is visible to the user's app after decryption.
+- Billing is handled directly by Tinfoil/PPQ.
+
+Example with Tinfoil's OpenAI-compatible client:
+
+```ts
+import { TinfoilAI } from "tinfoil";
+
+const client = new TinfoilAI({
+  apiKey: process.env.TINFOIL_API_KEY,
+  transport: "ehbp",
+});
+
+const res = await client.chat.completions.create({
+  model: "llama3-3-70b",
+  messages: [{ role: "user", content: "Hello" }],
+});
+
+console.log(res.choices[0].message.content);
+console.log(res.usage);
+```
+
+This is not a Routstr marketplace flow unless Routstr only acts as discovery/UI around direct Tinfoil/PPQ usage.
+
+## Option B: Routstr integrates Tinfoil as an upstream client
+
+```text
+User -> Routstr plaintext request
+  -> Routstr Tinfoil SecureClient encrypts to PPQ/Tinfoil
+    -> PPQ private enclave
+  -> Routstr receives decrypted response
+  -> Routstr bills from decrypted usage
+  -> Routstr returns plaintext response to user
+```
+
+Properties:
+
+- Easier exact billing.
+- Routstr can read the decrypted OpenAI response and `usage` object.
+- Routstr can charge exact PPQ token pricing.
+- Privacy is different: the user sends plaintext to Routstr, and Routstr sees prompts/responses.
+- End-to-end encryption is only Routstr-to-enclave, not user-to-enclave.
+
+This should be considered a separate product/provider mode, not the same as an end-to-end private relay.
+
+Practical implementation options:
+
+1. Run a Node sidecar that uses the `tinfoil` npm package and expose it as a local HTTP upstream to Routstr.
+2. Port EHBP client behavior to Python.
+3. Reuse or adapt `ppq-private-mode-proxy` as a local upstream.
+
+A Node sidecar is probably the quickest implementation path because `ppq-private-mode-proxy` already demonstrates the full flow.
+
+## Option C: Routstr uses Tinfoil as a direct blind upstream
+
+This is the current branch's design intent and is likely the best fit if Tinfoil/PPQ exposes usage metadata headers:
+
+```text
+User Tinfoil SecureClient
+  -> encrypted request body
+    -> Routstr proxy
+      -> Tinfoil/PPQ private API
+         with X-Tinfoil-Request-Usage-Metrics: true
+        -> PPQ private enclave
+      <- encrypted response
+         plus X-Tinfoil-Usage-Metrics / cost headers
+    <- Routstr proxy
+  -> user decrypts response
+```
+
+In this mode Routstr is still a normal upstream proxy from the user's point of view, but the upstream is Tinfoil/PPQ private inference and the body remains opaque to Routstr.
+
+Properties:
+
+- Strongest privacy with Routstr in the path.
+- Routstr never sees plaintext prompt or plaintext response.
+- Routstr can authenticate and route based on plaintext headers.
+- Routstr should request Tinfoil usage metadata by adding `X-Tinfoil-Request-Usage-Metrics: true` to the upstream request.
+- Tinfoil documents `X-Tinfoil-Usage-Metrics` as an upstream response header for non-streaming requests.
+- For streaming requests, Tinfoil documents `X-Tinfoil-Usage-Metrics` as an HTTP trailer available only after the response body completes.
+- If Tinfoil/PPQ returns `X-Tinfoil-Usage-Metrics` or a cost header on the encrypted response, Routstr can bill exactly without decrypting the body.
+- If usage is only present inside the encrypted response body, Routstr still cannot read it and exact billing is not possible without a separate metadata path.
+
+This is the only architecture that preserves end-to-end encryption from the user to the PPQ/Tinfoil enclave while still letting Routstr mediate payment. The key requirement is that usage/cost metadata must be returned outside the encrypted body, ideally as a response header available before body streaming begins.
+
+## Current Routstr problem
+
+The current EHBP implementation charges successful EHBP requests at `max_cost_for_model` because Routstr cannot decrypt the response body:
+
+```text
+successful EHBP request -> charge full reserved max cost
+```
+
+That is incorrect for PPQ private models. Max cost should be only a reservation/solvency ceiling. Final charge should use actual PPQ private token pricing.
+
+Desired behavior:
+
+```text
+reserve max cost
+forward encrypted request
+obtain actual usage/cost metadata
+finalize actual cost
+refund/release the difference
+```
+
+## Usage/cost metadata requirement
+
+For blind-relay exact billing, PPQ should return one of the following outside the encrypted response body:
+
+```http
+X-PPQ-Cost-USD: 0.00006250875
+```
+
+or:
+
+```http
+X-Private-Usage-Metrics: input=74,output=3
+```
+
+or:
+
+```http
+X-Tinfoil-Usage-Metrics: prompt=74,completion=3,total=77
+```
+
+Tinfoil proxy documentation references a usage-metrics flow where a proxy can request usage via:
+
+```http
+X-Tinfoil-Request-Usage-Metrics: true
+```
+
+and read usage from:
+
+```http
+X-Tinfoil-Usage-Metrics
+```
+
+Docs/example references:
+
+- https://docs.tinfoil.sh/guides/proxy-server
+- https://github.com/tinfoilsh/encrypted-request-proxy-example
+
+During local PPQ testing, PPQ responses included this CORS exposure header:
+
+```http
+Access-Control-Expose-Headers: Ehbp-Response-Nonce, X-Private-Usage-Metrics, X-Encrypted-Usage-Metrics, X-Tinfoil-Usage-Metrics
+```
+
+However, the actual tested non-streaming response did not include any of these usage headers, even when `X-Tinfoil-Request-Usage-Metrics: true` was sent.
+
+The decrypted body did include normal OpenAI usage, but only the decrypting Tinfoil client can see that body.
+
+## Query-history fallback
+
+PPQ's query history endpoint exposes actual usage and cost:
+
+```text
+GET https://api.ppq.ai/queries/history?page=1&page_count=...
+```
+
+A record includes:
+
+```json
+{
+  "timestamp": "...",
+  "model": "private/gpt-oss-120b",
+  "input_count": 74,
+  "output_count": 3,
+  "price_in_usd": 0.00006250875,
+  "query_type": "chat_completion",
+  "query_source": "api"
+}
+```
+
+This could be used as a fallback, but it is less robust than response headers/trailers because matching a request to a history row can be race-prone under concurrency. It would need a reliable request identifier or metadata field that PPQ stores in history.
+
+## Recommended Routstr direction
+
+Use Tinfoil/PPQ as a direct blind upstream and have Routstr explicitly request usage metadata:
+
+```text
+User encrypts body
+Routstr reserves max cost
+Routstr forwards encrypted body to Tinfoil/PPQ /private/
+Routstr includes X-Tinfoil-Request-Usage-Metrics: true
+Tinfoil/PPQ returns X-Tinfoil-Usage-Metrics as a response header for non-streaming,
+or as an HTTP trailer after the body completes for streaming
+Routstr finalizes exact charge
+User decrypts encrypted response
+```
+
+This preserves both:
+
+- privacy: Routstr cannot read prompts/responses;
+- exact billing: Routstr can charge actual PPQ private model cost, assuming Tinfoil/PPQ returns usage/cost metadata outside the encrypted body.
+
+Implementation steps:
+
+1. Update PPQ model fetching to include private models:
+
+   ```text
+   GET https://api.ppq.ai/v1/models?type=all
+   ```
+
+2. Register `private/*` models and any Routstr-facing aliases with correct `forwarded_model_id`.
+
+3. Keep max-cost reservation for bearer keys and X-Cashu solvency checks.
+
+4. Add parsing support for possible usage/cost headers:
+
+   ```http
+   X-PPQ-Cost-USD
+   X-Private-Usage-Metrics
+   X-Tinfoil-Usage-Metrics
+   X-Encrypted-Usage-Metrics
+   ```
+
+5. Finalize by actual cost instead of max cost:
+
+   ```text
+   actual_msats = ceil((actual_usd / sats_usd_price()) * 1000)
+   actual_msats = max(actual_msats, settings.min_request_msat)
+   actual_msats = min(actual_msats, reserved_msats)
+   ```
+
+   or, if only token counts are available:
+
+   ```text
+   actual_usd =
+     input_tokens  * input_per_1M_tokens  / 1_000_000
+   + output_tokens * output_per_1M_tokens / 1_000_000
+   ```
+
+6. If usage/cost metadata is missing, choose an explicit policy:
+
+   - fail closed and refund/revert;
+   - query PPQ history as a fallback;
+   - fallback to max-cost billing only if explicitly configured and clearly disclosed.
+
+Silent max-cost billing should not be the default for PPQ private requests.
+
+## X-Cashu consideration
+
+For bearer-auth requests, finalization can happen after the response stream completes if usage is delivered as a trailer.
+
+For `X-Cashu`, Routstr needs to return the refund token in the response headers. If usage/cost is only available after consuming the encrypted response stream, Routstr may need to buffer EHBP responses before sending them to the client so it can compute the refund amount first.
+
+Possible approaches:
+
+1. Prefer a non-trailer response header with actual cost, available before streaming body starts.
+2. Buffer EHBP X-Cashu responses and then return `X-Cashu` refund.
+3. Introduce a later/refund-claim mechanism, which would be a larger protocol change.
+
+## Summary
+
+- PPQ private models are billed per actual input/output tokens.
+- Private model rates are available from `GET /v1/models?type=all`.
+- Current Routstr EHBP billing at max cost is wrong for PPQ private models.
+- Direct Tinfoil integration inside Routstr would enable exact usage billing but would make Routstr see plaintext.
+- A blind EHBP relay preserves privacy but requires PPQ/Tinfoil to expose usage/cost in plaintext headers/trailers.
+- The preferred solution is to keep Routstr blind and have PPQ return billing metadata outside the encrypted body.
+
+## Implementation status
+
+Direct Tinfoil upstream integration is implemented in `routstr/upstream/tinfoil.py`
+and `routstr/upstream/ehbp.py`.
+
+### What was built
+
+- `TinfoilUpstreamProvider` (`provider_type = "tinfoil"`):
+  - Base URL: `https://inference.tinfoil.sh`
+  - Fetches models from the public `GET /v1/models` endpoint (no auth needed).
+  - Parses Tinfoil's pricing (`inputTokenPricePer1M`, `outputTokenPricePer1M`,
+    `requestPrice`) into the standard `Model`/`Pricing` schema.
+  - `supports_ehbp = True` — acts as a blind EHBP relay.
+  - `get_ehbp_forwarding_target()` returns a target that includes
+    `X-Tinfoil-Request-Usage-Metrics: true`.
+  - `forward_get_request()` proxies `/attestation` to `https://atc.tinfoil.sh/attestation`
+    so the SDK can fetch attestation bundles through Routstr.
+  - Registered in `routstr/upstream/__init__.py` and seeded from
+    `TINFOIL_API_KEY` env var.
+
+- `routstr/upstream/ehbp.py`:
+  - `parse_tinfoil_usage_metrics()` parses `prompt=N,completion=N[,total=N]`
+    into an OpenAI-style usage dict.
+  - `_resolve_ehbp_target_url()` overrides the forwarding URL with
+    `X-Tinfoil-Enclave-Url` when the SDK sends it.
+  - `_strip_proxy_headers()` removes `X-Routstr-Model`,
+    `X-Tinfoil-Enclave-Url`, and `X-Tinfoil-Request-Usage-Metrics` before
+    forwarding to the enclave.
+  - `_compute_ehbp_actual_cost()` converts the usage header into msats via
+    `calculate_cost()`, clamped to `[min_request_msat, max_cost_for_model]`.
+  - `forward_ehbp_request()` (bearer auth): if `X-Tinfoil-Usage-Metrics` is
+    present in the response header, finalizes with `adjust_payment_for_tokens()`
+    for exact billing; otherwise falls back to max-cost.
+  - `forward_ehbp_x_cashu_request()`: if usage is available, computes the
+    refund from actual cost instead of max cost.
+
+- `routstr/proxy.py`: `/attestation` and `/tee/attestation` paths are forwarded
+  to Tinfoil upstreams without model/cost/auth lookups.
+
+### Billing behavior
+
+| Request shape | Usage source | Billing |
+|---|---|---|
+| Bearer, non-streaming | `X-Tinfoil-Usage-Metrics` response header | Exact token cost via `adjust_payment_for_tokens` |
+| Bearer, streaming | `X-Tinfoil-Usage-Metrics` HTTP trailer | Exact token cost (h11 captures trailers) |
+| Bearer, no usage header/trailer | N/A | Max-cost fallback |
+| X-Cashu, non-streaming | `X-Tinfoil-Usage-Metrics` response header | Refund = `redeemed - actual_cost` |
+| X-Cashu, streaming | `X-Tinfoil-Usage-Metrics` HTTP trailer | Refund = `redeemed - actual_cost` (h11 captures trailers) |
+| X-Cashu, no usage header/trailer | N/A | Refund = `redeemed - max_cost` |
+
+### Cost response headers
+
+Since EHBP response bodies are opaque encrypted blobs, per-request cost cannot
+be injected into the JSON body (as done in the normal proxy flow). Instead,
+Routstr returns cost info as response headers:
+
+| Header | Auth | Description |
+|---|---|---|
+| `X-Routstr-Cost-Msats` | Bearer, X-Cashu | Total msats charged for this request |
+| `X-Routstr-Cost-Usd` | Bearer | USD equivalent of the charge |
+| `X-Routstr-Input-Cost-Msats` | Bearer, X-Cashu | msats attributed to input tokens |
+| `X-Routstr-Output-Cost-Msats` | Bearer, X-Cashu | msats attributed to output tokens |
+
+The client/Tinfoil SDK can read these headers from the HTTP response without
+needing to decrypt the body.
+
+### Setup
+
+```bash
+TINFOIL_API_KEY=your-tinfoil-api-key
+```
+
+The provider is auto-seeded on first startup.
+
+### What still needs verification
+
+- End-to-end test with a real Tinfoil SDK client against a Routstr node with
+  `TINFOIL_API_KEY` set.
+- Streaming requests: usage is delivered as an HTTP trailer. Currently the
+  bearer path finalizes max-cost before streaming begins. Supporting streaming
+  usage would require buffering the response (for X-Cashu) or a deferred
+  finalization (for bearer).
+- Whether Tinfoil's `/v1/responses` endpoint also returns usage metrics
+  headers.

migrations/versions/c6d7e8f9a0b1_add_slug_to_upstream_providers.py

@@ -0,0 +1,88 @@
+"""add slug to upstream_providers
+
+Revision ID: c6d7e8f9a0b1
+Revises: b5e7c9d1f3a2
+Create Date: 2026-06-29 00:00:00.000000
+"""
+
+from __future__ import annotations
+
+import sqlalchemy as sa
+from alembic import op
+
+from routstr.core.provider_slugs import provider_slug_base, provider_slug_candidate
+
+revision = "c6d7e8f9a0b1"
+down_revision = "b5e7c9d1f3a2"
+branch_labels = None
+depends_on = None
+
+
+def _allocate_backfill_slug(provider_type: str, reserved_slugs: set[str]) -> str:
+    base = provider_slug_base(provider_type)
+    suffix_number = 1
+    while True:
+        candidate = provider_slug_candidate(base, suffix_number)
+        if candidate not in reserved_slugs:
+            reserved_slugs.add(candidate)
+            return candidate
+        suffix_number += 1
+
+
+def _backfill_provider_slugs(conn: sa.Connection) -> None:
+    existing_rows = conn.execute(
+        sa.text(
+            "SELECT slug FROM upstream_providers "
+            "WHERE slug IS NOT NULL AND slug != ''"
+        )
+    )
+    reserved_slugs = {str(row.slug).lower() for row in existing_rows}
+
+    rows_to_backfill = conn.execute(
+        sa.text(
+            "SELECT id, provider_type FROM upstream_providers "
+            "WHERE slug IS NULL OR slug = '' "
+            "ORDER BY id"
+        )
+    )
+    for row in rows_to_backfill:
+        slug = _allocate_backfill_slug(str(row.provider_type), reserved_slugs)
+        conn.execute(
+            sa.text("UPDATE upstream_providers SET slug = :slug WHERE id = :id"),
+            {"slug": slug, "id": row.id},
+        )
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+    inspector = sa.inspect(conn)
+    columns = {c["name"] for c in inspector.get_columns("upstream_providers")}
+
+    if "slug" not in columns:
+        op.add_column(
+            "upstream_providers",
+            sa.Column("slug", sa.String(), nullable=True),
+        )
+
+    _backfill_provider_slugs(conn)
+
+    existing_indexes = {idx["name"] for idx in inspector.get_indexes("upstream_providers")}
+    if "ix_upstream_providers_slug" not in existing_indexes:
+        op.create_index(
+            "ix_upstream_providers_slug",
+            "upstream_providers",
+            ["slug"],
+            unique=True,
+        )
+
+
+def downgrade() -> None:
+    conn = op.get_bind()
+    inspector = sa.inspect(conn)
+    existing_indexes = {idx["name"] for idx in inspector.get_indexes("upstream_providers")}
+    if "ix_upstream_providers_slug" in existing_indexes:
+        op.drop_index("ix_upstream_providers_slug", table_name="upstream_providers")
+
+    columns = {c["name"] for c in inspector.get_columns("upstream_providers")}
+    if "slug" in columns:
+        op.drop_column("upstream_providers", "slug")

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "routstr"
-version = "0.4.3"
+version = "0.4.4"
 description = "Payment proxy for your LLM endpoint using cashu and nostr."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -10,6 +10,7 @@ dependencies = [
     "aiosqlite>=0.20",
     "sqlmodel>=0.0.24",
     "httpx[socks]>=0.25.2",
+    "h11>=0.14",
     "greenlet>=3.2.1",
     "alembic>=1.13",
     "python-json-logger>=2.0.0",

routstr/core/admin.py

@@ -1,5 +1,6 @@
 import asyncio
 import json
+import re
 import secrets
 from datetime import datetime, timezone
 from pathlib import Path
@@ -8,6 +9,7 @@ from fastapi import APIRouter, Depends, HTTPException, Query, Request
 from pydantic import BaseModel, RootModel
 from pydantic.v1 import ValidationError as PydanticValidationError
 from sqlmodel import select
+from sqlmodel.ext.asyncio.session import AsyncSession
 
 from ..payment.models import _row_to_model, list_models
 from ..proxy import refresh_model_maps, reinitialize_upstreams
@@ -29,6 +31,7 @@ from .db import (
 )
 from .log_manager import log_manager
 from .logging import get_logger
+from .provider_slugs import allocate_unique_provider_slug
 from .settings import SettingsService, settings
 
 logger = get_logger(__name__)
@@ -456,19 +459,18 @@ class ModelCreate(BaseModel):
     dependencies=[Depends(require_admin_api)],
 )
 async def upsert_provider_model(
-    provider_id: int, payload: ModelCreate
+    provider_id: str, payload: ModelCreate
 ) -> dict[str, object]:
     print(payload)
     logger.info(
         f"UPSERT_PROVIDER_MODEL called: provider_id={provider_id}, model_id={payload.id}"
     )
     async with create_session() as session:
-        provider = await session.get(UpstreamProviderRow, provider_id)
-        if not provider:
-            raise HTTPException(status_code=404, detail="Provider not found")
+        provider = await _get_upstream_provider_by_ref(session, provider_id)
+        provider_pk = _provider_pk(provider)
 
         # Try to get existing model
-        existing_row = await session.get(ModelRow, (payload.id, provider_id))
+        existing_row = await session.get(ModelRow, (payload.id, provider_pk))
 
         if existing_row:
             # Update existing model
@@ -524,7 +526,7 @@ async def upsert_provider_model(
                 alias_ids=(
                     json.dumps(payload.alias_ids) if payload.alias_ids else None
                 ),
-                upstream_provider_id=provider_id,
+                upstream_provider_id=provider_pk,
                 enabled=payload.enabled,
                 forwarded_model_id=payload.forwarded_model_id or payload.id,
             )
@@ -543,7 +545,7 @@ async def upsert_provider_model(
     dependencies=[Depends(require_admin_api)],
 )
 async def update_provider_model_legacy(
-    provider_id: int, model_id: str, payload: ModelCreate
+    provider_id: str, model_id: str, payload: ModelCreate
 ) -> dict[str, object]:
     """Legacy PATCH endpoint - redirects to upsert POST endpoint for backward compatibility."""
     logger.info(
@@ -556,13 +558,12 @@ async def update_provider_model_legacy(
     "/api/upstream-providers/{provider_id}/models/{model_id:path}",
     dependencies=[Depends(require_admin_api)],
 )
-async def get_provider_model(provider_id: int, model_id: str) -> dict[str, object]:
+async def get_provider_model(provider_id: str, model_id: str) -> dict[str, object]:
     async with create_session() as session:
-        provider = await session.get(UpstreamProviderRow, provider_id)
-        if not provider:
-            raise HTTPException(status_code=404, detail="Provider not found")
+        provider = await _get_upstream_provider_by_ref(session, provider_id)
+        provider_pk = _provider_pk(provider)
 
-        row = await session.get(ModelRow, (model_id, provider_id))
+        row = await session.get(ModelRow, (model_id, provider_pk))
         if not row:
             raise HTTPException(
                 status_code=404, detail="Model not found for this provider"
@@ -576,9 +577,11 @@ async def get_provider_model(provider_id: int, model_id: str) -> dict[str, objec
     "/api/upstream-providers/{provider_id}/models/{model_id:path}",
     dependencies=[Depends(require_admin_api)],
 )
-async def delete_provider_model(provider_id: int, model_id: str) -> dict[str, object]:
+async def delete_provider_model(provider_id: str, model_id: str) -> dict[str, object]:
     async with create_session() as session:
-        row = await session.get(ModelRow, (model_id, provider_id))
+        provider = await _get_upstream_provider_by_ref(session, provider_id)
+        provider_pk = _provider_pk(provider)
+        row = await session.get(ModelRow, (model_id, provider_pk))
         if not row:
             raise HTTPException(
                 status_code=404, detail="Model not found for this provider"
@@ -593,10 +596,12 @@ async def delete_provider_model(provider_id: int, model_id: str) -> dict[str, ob
     "/api/upstream-providers/{provider_id}/models",
     dependencies=[Depends(require_admin_api)],
 )
-async def delete_all_provider_models(provider_id: int) -> dict[str, object]:
+async def delete_all_provider_models(provider_id: str) -> dict[str, object]:
     async with create_session() as session:
+        provider = await _get_upstream_provider_by_ref(session, provider_id)
+        provider_pk = _provider_pk(provider)
         result = await session.exec(
-            select(ModelRow).where(ModelRow.upstream_provider_id == provider_id)
+            select(ModelRow).where(ModelRow.upstream_provider_id == provider_pk)
         )  # type: ignore
         rows = result.all()
         for row in rows:
@@ -615,7 +620,7 @@ class BatchOverrideRequest(BaseModel):
     dependencies=[Depends(require_admin_api)],
 )
 async def batch_override_provider_models(
-    provider_id: int, payload: BatchOverrideRequest
+    provider_id: str, payload: BatchOverrideRequest
 ) -> dict[str, object]:
     """Batch override models for a specific provider."""
     logger.info(
@@ -623,15 +628,14 @@ async def batch_override_provider_models(
     )
 
     async with create_session() as session:
-        provider = await session.get(UpstreamProviderRow, provider_id)
-        if not provider:
-            raise HTTPException(status_code=404, detail="Provider not found")
+        provider = await _get_upstream_provider_by_ref(session, provider_id)
+        provider_pk = _provider_pk(provider)
 
         overridden_count = 0
 
         for model_data in payload.models:
             # Try to get existing model regardless of whether it's enabled or not
-            existing_row = await session.get(ModelRow, (model_data.id, provider_id))
+            existing_row = await session.get(ModelRow, (model_data.id, provider_pk))
 
             if existing_row:
                 # Update existing
@@ -685,7 +689,7 @@ async def batch_override_provider_models(
                         if model_data.alias_ids
                         else None
                     ),
-                    upstream_provider_id=provider_id,
+                    upstream_provider_id=provider_pk,
                     enabled=model_data.enabled,
                 )
                 session.add(row)
@@ -702,6 +706,85 @@ async def batch_override_provider_models(
     }
 
 
+_SLUG_PATTERN = re.compile(r"^[a-z0-9][a-z0-9-]{1,62}[a-z0-9]$")
+
+
+def _validate_slug(value: str) -> str:
+    candidate = value.strip().lower()
+    if not _SLUG_PATTERN.fullmatch(candidate):
+        raise HTTPException(
+            status_code=400,
+            detail=(
+                "slug must be 3-64 chars, lowercase letters/digits/hyphens, "
+                "and may not start or end with a hyphen"
+            ),
+        )
+    if candidate.isdigit():
+        raise HTTPException(
+            status_code=400,
+            detail="slug must not be all digits",
+        )
+    return candidate
+
+
+async def _ensure_unique_slug(
+    session: AsyncSession, slug: str, exclude_id: int | None = None
+) -> None:
+    stmt = select(UpstreamProviderRow).where(UpstreamProviderRow.slug == slug)
+    result = await session.exec(stmt)
+    existing = result.first()
+    if existing and existing.id != exclude_id:
+        raise HTTPException(
+            status_code=409,
+            detail="Provider with this slug already exists",
+        )
+
+
+async def _get_upstream_provider_by_ref(
+    session: AsyncSession, provider_ref: str
+) -> UpstreamProviderRow:
+    if provider_ref.isdigit():
+        provider = await session.get(UpstreamProviderRow, int(provider_ref))
+    else:
+        slug = _validate_slug(provider_ref)
+        result = await session.exec(
+            select(UpstreamProviderRow).where(UpstreamProviderRow.slug == slug)
+        )
+        provider = result.first()
+
+    if not provider:
+        raise HTTPException(status_code=404, detail="Provider not found")
+    return provider
+
+
+def _provider_pk(provider: UpstreamProviderRow) -> int:
+    if provider.id is None:
+        raise HTTPException(status_code=500, detail="Provider has no database id")
+    return provider.id
+
+
+def _serialize_provider(
+    provider: UpstreamProviderRow, redact_api_key: bool = True
+) -> dict[str, object]:
+    return {
+        "id": provider.id,
+        "slug": provider.slug,
+        "provider_type": provider.provider_type,
+        "base_url": provider.base_url,
+        "api_key": "[REDACTED]"
+        if (redact_api_key and provider.api_key)
+        else provider.api_key
+        if not redact_api_key
+        else "",
+        "api_version": provider.api_version,
+        "enabled": provider.enabled,
+        "provider_fee": provider.provider_fee,
+        "provider_settings": json.loads(provider.provider_settings)
+        if provider.provider_settings
+        else None,
+    }
+
+
 class UpstreamProviderCreate(BaseModel):
     provider_type: str
     base_url: str
@@ -710,6 +793,7 @@ class UpstreamProviderCreate(BaseModel):
     enabled: bool = True
     provider_fee: float = 1.01
     provider_settings: dict | None = None
+    slug: str | None = None
 
 
 class UpstreamProviderUpdate(BaseModel):
@@ -720,6 +804,50 @@ class UpstreamProviderUpdate(BaseModel):
     enabled: bool | None = None
     provider_fee: float | None = None
     provider_settings: dict | None = None
+    slug: str | None = None
+
+
+class UpstreamProviderUpdateBySlug(BaseModel):
+    slug: str
+    new_slug: str | None = None
+    provider_type: str | None = None
+    base_url: str | None = None
+    api_key: str | None = None
+    api_version: str | None = None
+    enabled: bool | None = None
+    provider_fee: float | None = None
+    provider_settings: dict | None = None
+
+
+async def _apply_provider_update(
+    session: AsyncSession,
+    provider: UpstreamProviderRow,
+    payload: UpstreamProviderUpdate,
+    new_slug: str | None = None,
+) -> None:
+    if new_slug is not None:
+        validated = _validate_slug(new_slug)
+        await _ensure_unique_slug(session, validated, exclude_id=provider.id)
+        provider.slug = validated
+
+    if payload.provider_type is not None:
+        provider.provider_type = payload.provider_type
+    if payload.base_url is not None:
+        provider.base_url = payload.base_url
+    if payload.api_key is not None:
+        provider.api_key = payload.api_key
+    if payload.api_version is not None:
+        provider.api_version = payload.api_version
+    if payload.enabled is not None:
+        provider.enabled = payload.enabled
+    if payload.provider_fee is not None:
+        provider.provider_fee = payload.provider_fee
+    if payload.provider_settings is not None:
+        provider.provider_settings = json.dumps(payload.provider_settings)
+
+    session.add(provider)
+    await session.commit()
+    await session.refresh(provider)
 
 
 @admin_router.get("/api/upstream-providers", dependencies=[Depends(require_admin_api)])
@@ -727,21 +855,7 @@ async def get_upstream_providers() -> list[dict[str, object]]:
     async with create_session() as session:
         result = await session.exec(select(UpstreamProviderRow))
         providers = result.all()
-        return [
-            {
-                "id": p.id,
-                "provider_type": p.provider_type,
-                "base_url": p.base_url,
-                "api_key": "[REDACTED]" if p.api_key else "",
-                "api_version": p.api_version,
-                "enabled": p.enabled,
-                "provider_fee": p.provider_fee,
-                "provider_settings": json.loads(p.provider_settings)
-                if p.provider_settings
-                else None,
-            }
-            for p in providers
-        ]
+        return [_serialize_provider(p) for p in providers]
 
 
 @admin_router.post("/api/upstream-providers", dependencies=[Depends(require_admin_api)])
@@ -761,7 +875,14 @@ async def create_upstream_provider(
                 detail="Provider with this base URL and API key already exists",
             )
 
+        if payload.slug:
+            slug = _validate_slug(payload.slug)
+            await _ensure_unique_slug(session, slug)
+        else:
+            slug = await allocate_unique_provider_slug(session, payload.provider_type)
+
         provider = UpstreamProviderRow(
+            slug=slug,
             provider_type=payload.provider_type,
             base_url=payload.base_url,
             api_key=payload.api_key,
@@ -778,99 +899,81 @@ async def create_upstream_provider(
 
     await reinitialize_upstreams()
     await refresh_model_maps()
-    return {
-        "id": provider.id,
-        "provider_type": provider.provider_type,
-        "base_url": provider.base_url,
-        "api_key": "[REDACTED]",
-        "api_version": provider.api_version,
-        "enabled": provider.enabled,
-        "provider_fee": provider.provider_fee,
-        "provider_settings": payload.provider_settings,
-    }
+    return _serialize_provider(provider)
 
 
 @admin_router.get(
     "/api/upstream-providers/{provider_id}", dependencies=[Depends(require_admin_api)]
 )
-async def get_upstream_provider(provider_id: int) -> dict[str, object]:
+async def get_upstream_provider(provider_id: str) -> dict[str, object]:
     async with create_session() as session:
-        provider = await session.get(UpstreamProviderRow, provider_id)
-        if not provider:
-            raise HTTPException(status_code=404, detail="Provider not found")
-        return {
-            "id": provider.id,
-            "provider_type": provider.provider_type,
-            "base_url": provider.base_url,
-            "api_key": "[REDACTED]" if provider.api_key else "",
-            "api_version": provider.api_version,
-            "enabled": provider.enabled,
-            "provider_fee": provider.provider_fee,
-            "provider_settings": json.loads(provider.provider_settings)
-            if provider.provider_settings
-            else None,
-        }
+        provider = await _get_upstream_provider_by_ref(session, provider_id)
+        return _serialize_provider(provider)
 
 
 @admin_router.patch(
     "/api/upstream-providers/{provider_id}", dependencies=[Depends(require_admin_api)]
 )
 async def update_upstream_provider(
-    provider_id: int, payload: UpstreamProviderUpdate
+    provider_id: str, payload: UpstreamProviderUpdate
 ) -> dict[str, object]:
     async with create_session() as session:
-        provider = await session.get(UpstreamProviderRow, provider_id)
-        if not provider:
-            raise HTTPException(status_code=404, detail="Provider not found")
+        provider = await _get_upstream_provider_by_ref(session, provider_id)
 
-        if payload.provider_type is not None:
-            provider.provider_type = payload.provider_type
-        if payload.base_url is not None:
-            provider.base_url = payload.base_url
-        if payload.api_key is not None:
-            provider.api_key = payload.api_key
-        if payload.api_version is not None:
-            provider.api_version = payload.api_version
-        if payload.enabled is not None:
-            provider.enabled = payload.enabled
-        if payload.provider_fee is not None:
-            provider.provider_fee = payload.provider_fee
-        if payload.provider_settings is not None:
-            provider.provider_settings = json.dumps(payload.provider_settings)
-
-        session.add(provider)
-        await session.commit()
-        await session.refresh(provider)
+        await _apply_provider_update(session, provider, payload, new_slug=payload.slug)
 
     await reinitialize_upstreams()
     await refresh_model_maps()
-    return {
-        "id": provider.id,
-        "provider_type": provider.provider_type,
-        "base_url": provider.base_url,
-        "api_key": "[REDACTED]",
-        "api_version": provider.api_version,
-        "enabled": provider.enabled,
-        "provider_fee": provider.provider_fee,
-        "provider_settings": json.loads(provider.provider_settings)
-        if provider.provider_settings
-        else None,
-    }
+    return _serialize_provider(provider)
+
+
+@admin_router.patch(
+    "/api/upstream-providers", dependencies=[Depends(require_admin_api)]
+)
+async def update_upstream_provider_by_slug(
+    payload: UpstreamProviderUpdateBySlug,
+) -> dict[str, object]:
+    lookup = _validate_slug(payload.slug)
+    async with create_session() as session:
+        result = await session.exec(
+            select(UpstreamProviderRow).where(
+                UpstreamProviderRow.slug == lookup
+            )
+        )
+        provider = result.first()
+        if not provider:
+            raise HTTPException(status_code=404, detail="Provider not found")
+
+        update_payload = UpstreamProviderUpdate(
+            provider_type=payload.provider_type,
+            base_url=payload.base_url,
+            api_key=payload.api_key,
+            api_version=payload.api_version,
+            enabled=payload.enabled,
+            provider_fee=payload.provider_fee,
+            provider_settings=payload.provider_settings,
+        )
+        await _apply_provider_update(
+            session, provider, update_payload, new_slug=payload.new_slug
+        )
+
+    await reinitialize_upstreams()
+    await refresh_model_maps()
+    return _serialize_provider(provider)
 
 
 @admin_router.delete(
     "/api/upstream-providers/{provider_id}", dependencies=[Depends(require_admin_api)]
 )
-async def delete_upstream_provider(provider_id: int) -> dict[str, object]:
+async def delete_upstream_provider(provider_id: str) -> dict[str, object]:
     async with create_session() as session:
-        provider = await session.get(UpstreamProviderRow, provider_id)
-        if not provider:
-            raise HTTPException(status_code=404, detail="Provider not found")
+        provider = await _get_upstream_provider_by_ref(session, provider_id)
+        deleted_id = _provider_pk(provider)
         await session.delete(provider)
         await session.commit()
     await reinitialize_upstreams()
     await refresh_model_maps()
-    return {"ok": True, "deleted_id": provider_id}
+    return {"ok": True, "deleted_id": deleted_id}
 
 
 @admin_router.get("/api/provider-types", dependencies=[Depends(require_admin_api)])
@@ -885,17 +988,16 @@ async def get_provider_types() -> list[dict[str, object]]:
     "/api/upstream-providers/{provider_id}/models",
     dependencies=[Depends(require_admin_api)],
 )
-async def get_provider_models(provider_id: int) -> dict[str, object]:
+async def get_provider_models(provider_id: str) -> dict[str, object]:
     from ..upstream.helpers import _instantiate_provider
 
     async with create_session() as session:
-        provider = await session.get(UpstreamProviderRow, provider_id)
-        if not provider:
-            raise HTTPException(status_code=404, detail="Provider not found")
+        provider = await _get_upstream_provider_by_ref(session, provider_id)
+        provider_pk = _provider_pk(provider)
 
         db_models = await list_models(
             session=session,
-            upstream_id=provider_id,
+            upstream_id=provider_pk,
             include_disabled=True,
             apply_fees=False,
         )
@@ -985,13 +1087,11 @@ class TopupTokenRequest(BaseModel):
     dependencies=[Depends(require_admin_api)],
 )
 async def topup_provider_with_token(
-    provider_id: int, payload: TopupTokenRequest
+    provider_id: str, payload: TopupTokenRequest
 ) -> dict:
     """Redeem a Cashu token for an upstream provider."""
     async with create_session() as session:
-        provider = await session.get(UpstreamProviderRow, provider_id)
-        if not provider:
-            raise HTTPException(status_code=404, detail="Provider not found")
+        provider = await _get_upstream_provider_by_ref(session, provider_id)
 
         import httpx
 
@@ -1022,15 +1122,13 @@ async def topup_provider_with_token(
     dependencies=[Depends(require_admin_api)],
 )
 async def initiate_provider_topup(
-    provider_id: int, payload: TopupRequest
+    provider_id: str, payload: TopupRequest
 ) -> dict[str, object]:
     """Initiate a Lightning Network top-up for the upstream provider account."""
     from ..upstream.helpers import _instantiate_provider
 
     async with create_session() as session:
-        provider = await session.get(UpstreamProviderRow, provider_id)
-        if not provider:
-            raise HTTPException(status_code=404, detail="Provider not found")
+        provider = await _get_upstream_provider_by_ref(session, provider_id)
 
         try:
             logger.info(
@@ -1150,15 +1248,13 @@ async def initiate_provider_topup(
     "/api/upstream-providers/{provider_id}/topup/{invoice_id}/status",
     dependencies=[Depends(require_admin_api)],
 )
-async def check_topup_status(provider_id: int, invoice_id: str) -> dict[str, object]:
+async def check_topup_status(provider_id: str, invoice_id: str) -> dict[str, object]:
     """Check the status of a Lightning Network top-up invoice."""
     from ..upstream.helpers import _instantiate_provider
     from ..upstream.ppqai import PPQAIUpstreamProvider
 
     async with create_session() as session:
-        provider = await session.get(UpstreamProviderRow, provider_id)
-        if not provider:
-            raise HTTPException(status_code=404, detail="Provider not found")
+        provider = await _get_upstream_provider_by_ref(session, provider_id)
 
         # For Routstr providers, proxy the status check
         if provider.provider_type == "routstr":
@@ -1205,14 +1301,12 @@ async def check_topup_status(provider_id: int, invoice_id: str) -> dict[str, obj
     "/api/upstream-providers/{provider_id}/balance",
     dependencies=[Depends(require_admin_api)],
 )
-async def get_provider_balance(provider_id: int) -> dict[str, object]:
+async def get_provider_balance(provider_id: str) -> dict[str, object]:
     """Get the current balance for an upstream provider account."""
     from ..upstream.helpers import _instantiate_provider
 
     async with create_session() as session:
-        provider = await session.get(UpstreamProviderRow, provider_id)
-        if not provider:
-            raise HTTPException(status_code=404, detail="Provider not found")
+        provider = await _get_upstream_provider_by_ref(session, provider_id)
 
         # For Routstr providers, proxy the balance check
         if provider.provider_type == "routstr":
@@ -1591,15 +1685,13 @@ async def get_lightning_invoices_api(
     "/api/upstream-providers/{provider_id}/routstr/refund",
     dependencies=[Depends(require_admin_api)],
 )
-async def refund_routstr_provider_balance(provider_id: int) -> dict[str, object]:
+async def refund_routstr_provider_balance(provider_id: str) -> dict[str, object]:
     """Refund balance from an upstream Routstr provider back to the local wallet."""
     from ..upstream.helpers import _instantiate_provider
     from ..upstream.routstr import RoutstrUpstreamProvider
 
     async with create_session() as session:
-        provider_row = await session.get(UpstreamProviderRow, provider_id)
-        if not provider_row:
-            raise HTTPException(status_code=404, detail="Provider not found")
+        provider_row = await _get_upstream_provider_by_ref(session, provider_id)
 
         if provider_row.provider_type != "routstr":
             raise HTTPException(

routstr/core/db.py

@@ -319,6 +319,12 @@ class UpstreamProviderRow(SQLModel, table=True):  # type: ignore
         ),
     )
     id: int | None = Field(default=None, primary_key=True)
+    slug: str | None = Field(
+        default=None,
+        unique=True,
+        index=True,
+        description="Stable external slug used for updates via API key.",
+    )
     provider_type: str = Field(
         description="Provider type: custom, openai, anthropic, azure, openrouter, etc."
     )

routstr/core/main.py

@@ -257,7 +257,20 @@ app.add_middleware(
     allow_credentials=True,
     allow_methods=["*"],
     allow_headers=["*"],
-    expose_headers=["x-routstr-request-id", "x-cashu"],
+    expose_headers=[
+        "x-routstr-request-id",
+        "x-cashu",
+        "x-routstr-cost-msats",
+        "x-routstr-cost-usd",
+        "x-routstr-input-cost-msats",
+        "x-routstr-output-cost-msats",
+        # EHBP (Tinfoil) protocol headers must be exposed so browser clients
+        # can detect and decrypt encrypted responses. Without these, the
+        # browser hides them via CORS and the SDK treats the response as a
+        # plaintext proxy error, returning raw ciphertext.
+        "Ehbp-Response-Nonce",
+        "Ehbp-Encapsulated-Key",
+    ],
 )
 
 # Add logging middleware

routstr/core/provider_slugs.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+import re
+from itertools import count
+from typing import Collection
+
+from sqlmodel import select
+from sqlmodel.ext.asyncio.session import AsyncSession
+
+from .db import UpstreamProviderRow
+
+_SLUG_BASE_PATTERN = re.compile(r"[^a-z0-9]+")
+_MAX_SLUG_LENGTH = 64
+
+
+def provider_slug_base(provider_type: str) -> str:
+    """Return a deterministic slug base for a provider type."""
+    base = _SLUG_BASE_PATTERN.sub("-", provider_type.lower()).strip("-")
+    if not base:
+        base = "provider"
+    elif base.isdigit():
+        base = f"provider-{base}"
+    elif len(base) < 3:
+        base = f"{base}-provider"
+
+    if len(base) > _MAX_SLUG_LENGTH:
+        base = base[:_MAX_SLUG_LENGTH].rstrip("-") or "provider"
+    return base
+
+
+def provider_slug_candidate(base: str, suffix_number: int) -> str:
+    if suffix_number == 1:
+        return base
+
+    suffix = f"-{suffix_number}"
+    max_base_length = _MAX_SLUG_LENGTH - len(suffix)
+    return f"{base[:max_base_length].rstrip('-')}{suffix}"
+
+
+async def allocate_unique_provider_slug(
+    session: AsyncSession,
+    provider_type: str,
+    reserved_slugs: Collection[str] = (),
+) -> str:
+    """Allocate a stable, deterministic provider slug.
+
+    The first provider of a type gets ``openai``; later collisions get
+    ``openai-2``, ``openai-3``, etc. ``reserved_slugs`` covers rows staged in
+    memory but not flushed yet, such as settings/env seeding.
+    """
+    base = provider_slug_base(provider_type)
+    reserved = {slug.lower() for slug in reserved_slugs}
+
+    for suffix_number in count(1):
+        candidate = provider_slug_candidate(base, suffix_number)
+        if candidate in reserved:
+            continue
+
+        result = await session.exec(
+            select(UpstreamProviderRow).where(UpstreamProviderRow.slug == candidate)
+        )
+        if result.first() is None:
+            return candidate
+
+    raise RuntimeError("unreachable")

routstr/core/version.py

@@ -20,7 +20,7 @@ import subprocess
 from functools import lru_cache
 from pathlib import Path
 
-BASE_VERSION = "0.4.3"
+BASE_VERSION = "0.4.4"
 
 _REPO_ROOT = Path(__file__).resolve().parents[2]
 _GIT_TIMEOUT_SECONDS = 2.0

routstr/payment/cost_calculation.py

@@ -41,6 +41,28 @@ class CostDataError(BaseModel):
     code: str
 
 
+def _empty_cost(cls: type[CostData] = CostData) -> CostData:
+    """Build an all-zero cost object — a full refund for an empty response.
+
+    Shared by the two paths that must not bill: an upstream response with no
+    usage data at all, and one that reports a USD cost but carries zero tokens
+    in every bucket.
+    """
+    return cls(
+        base_msats=0,
+        input_msats=0,
+        output_msats=0,
+        total_msats=0,
+        total_usd=0.0,
+        input_tokens=0,
+        output_tokens=0,
+        cache_read_input_tokens=0,
+        cache_creation_input_tokens=0,
+        cache_read_msats=0,
+        cache_creation_msats=0,
+    )
+
+
 async def calculate_cost(
     response_data: dict,
     max_cost: int,
@@ -83,19 +105,7 @@ async def calculate_cost(
                 else None,
             },
         )
-        return MaxCostData(
-            base_msats=0,
-            input_msats=0,
-            output_msats=0,
-            total_msats=0,
-            total_usd=0.0,
-            input_tokens=0,
-            output_tokens=0,
-            cache_read_input_tokens=0,
-            cache_creation_input_tokens=0,
-            cache_read_msats=0,
-            cache_creation_msats=0,
-        )
+        return _empty_cost(MaxCostData)
 
     usage_data = response_data.get("usage") or {}
     if not isinstance(usage_data, dict):
@@ -109,6 +119,27 @@ async def calculate_cost(
     # Try USD cost first
     usd_cost = _resolve_usd_cost(usage_data, response_data)
     if usd_cost > 0:
+        truly_empty = (
+            input_tokens == 0
+            and output_tokens == 0
+            and cache_read_tokens == 0
+            and cache_creation_tokens == 0
+        )
+        if truly_empty:
+            logger.warning(
+                "Upstream reported a USD cost but the response carries no "
+                "tokens at all (input, output, cache-read and cache-creation "
+                "are all zero) — refunding in full rather than billing the "
+                "USD-derived cost for an empty response.",
+                extra={
+                    "model": response_data.get("model", "unknown"),
+                    "usd_cost": usd_cost,
+                    "usage_keys": sorted(usage_data.keys())
+                    if isinstance(usage_data, dict)
+                    else None,
+                },
+            )
+            return _empty_cost()
         if input_tokens == 0 and output_tokens == 0:
             logger.warning(
                 "Upstream reported a USD cost but no token counts — "

routstr/payment/models.py

@@ -94,7 +94,10 @@ def backfill_cache_pricing(model_id: str, pricing: Pricing) -> Pricing:
     cache reads (DeepSeek hits are 10x cheaper) and undercharges Anthropic
     cache writes (1.25x). litellm ships per-model USD rates keyed by the exact
     OpenRouter id (deepseek/deepseek-chat) or by the bare model name
-    (gpt-4o, claude-sonnet-4-5), so both spellings are tried.
+    (gpt-4o, claude-sonnet-4-5), so both spellings are tried. litellm keys are
+    lowercase, but a generic upstream may report a mixed-case id
+    (``deepseek-ai/DeepSeek-V4-Flash``); an exact match is attempted first, then
+    a case-insensitive fallback so such ids still resolve.
 
     Rates already present (e.g. provided by OpenRouter) are authoritative and
     never overwritten. Unknown models are returned unchanged.
@@ -106,12 +109,26 @@ def backfill_cache_pricing(model_id: str, pricing: Pricing) -> Pricing:
 
     import litellm
 
+    candidates = (model_id, model_id.split("/", 1)[-1])
     info: dict | None = None
-    for key in (model_id, model_id.split("/", 1)[-1]):
+    for key in candidates:
         candidate = litellm.model_cost.get(key)
         if isinstance(candidate, dict):
             info = candidate
             break
+    if info is None:
+        # Case-insensitive fallback: a mixed-case upstream id (e.g.
+        # ``deepseek-ai/DeepSeek-V4-Flash``) won't match litellm's lowercase
+        # keys exactly. Build a lowercased index once and retry.
+        lowered = {c.lower() for c in candidates}
+        for key, candidate in litellm.model_cost.items():
+            if (
+                isinstance(key, str)
+                and key.lower() in lowered
+                and isinstance(candidate, dict)
+            ):
+                info = candidate
+                break
     if info is None:
         return pricing
 
@@ -215,13 +232,29 @@ def _row_to_model(
     )
     top_provider_dict = json.loads(row.top_provider) if row.top_provider else None
 
-    if apply_provider_fee and isinstance(pricing, dict):
-        pricing = {k: float(v) * provider_fee for k, v in pricing.items()}
-
     if isinstance(pricing, dict) and float(pricing.get("request", 0.0)) <= 0.0:
         pricing["request"] = max(pricing.get("request", 0.0), 0.0)
 
     parsed_pricing = Pricing.parse_obj(pricing)
+
+    # Fill missing cache-read/write rates from litellm's cost map BEFORE applying
+    # the provider fee, so they carry the same markup as every other component.
+    # DB-stored override pricing (e.g. generic providers) omits cache rates;
+    # without this, ``_row_to_model`` bills cache reads at the full input rate —
+    # the ``_apply_provider_fee_to_model`` path backfills, but the override path
+    # used for admin-configured providers did not.
+    #
+    # Key on ``forwarded_model_id`` (the actual upstream model name litellm
+    # prices) when set: an alias row (id="local-alias",
+    # forwarded_model_id="deepseek-v4-flash") would otherwise look up the alias
+    # and miss the cache rate.
+    pricing_model_id = getattr(row, "forwarded_model_id", None) or row.id
+    parsed_pricing = backfill_cache_pricing(pricing_model_id, parsed_pricing)
+
+    if apply_provider_fee:
+        parsed_pricing = Pricing.parse_obj(
+            {k: float(v) * provider_fee for k, v in parsed_pricing.dict().items()}
+        )
     model = Model(
         id=row.id,
         name=row.name,

routstr/proxy.py

@@ -29,6 +29,7 @@ from .payment.helpers import (
 )
 from .payment.models import Model
 from .upstream import BaseUpstreamProvider
+from .upstream.ehbp import forward_ehbp_request, forward_ehbp_x_cashu_request
 from .upstream.helpers import init_upstreams
 from .upstream.request_correction import correct_request, extract_error_message
 
@@ -104,6 +105,29 @@ def get_unique_models() -> list[Model]:
     return list(_unique_models.values())
 
 
+def _is_tinfoil_attestation_path(path: str) -> bool:
+    """Return True for Tinfoil attestation-bundle proxy paths."""
+    return path in {"attestation", "tee/attestation"}
+
+
+def _select_unauthenticated_get_upstreams(
+    path: str, upstreams: list[BaseUpstreamProvider]
+) -> list[BaseUpstreamProvider]:
+    """Select upstream candidates for unauthenticated GET bypass paths.
+
+    Tinfoil attestation endpoints are provider-specific. Trying every enabled
+    upstream can return an unrelated provider's 404 before Tinfoil is reached,
+    so route those paths only to Tinfoil providers.
+    """
+    if _is_tinfoil_attestation_path(path):
+        return [
+            upstream
+            for upstream in upstreams
+            if getattr(upstream, "provider_type", None) == "tinfoil"
+        ]
+    return upstreams
+
+
 async def refresh_model_maps() -> None:
     """Refresh global model and provider maps using the cost-based algorithm."""
     from sqlalchemy.orm import selectinload
@@ -166,6 +190,7 @@ _API_PATH_PREFIXES = (
     "moderations",
     "providers",
     "tee/",
+    "attestation",
 )
 
 
@@ -184,20 +209,54 @@ async def proxy(
 
     is_responses_api = path.startswith("v1/responses") or path.startswith("responses")
     request_body = await request.body()
-    request_body_dict = parse_request_body_json(request_body, path)
 
-    # /tee/* GET requests (e.g. attestation) don't map to models — just
-    # forward to all enabled upstreams without model/cost/auth lookups.
-    if request.method == "GET" and path.startswith("tee/"):
-        all_upstreams = _upstreams
+    # EHBP (Encrypted HTTP Body Protocol) requests carry an Ehbp-Encapsulated-Key
+    # header and a binary HPKE-sealed body. The proxy cannot parse the body to
+    # extract the model id, so the SDK sends it in X-Routstr-Model. Forward the
+    # raw encrypted body to the upstream's /private/ endpoint and stream the
+    # encrypted response back untouched — the SDK's SecureClient decrypts it.
+    is_ehbp = "ehbp-encapsulated-key" in headers
+    if is_ehbp:
+        request_body_dict = {}
+        model_id = headers.get("x-routstr-model", "")
+        if not model_id:
+            return create_error_response(
+                "invalid_request",
+                "EHBP request missing X-Routstr-Model header",
+                400,
+                request=request,
+            )
+    else:
+        request_body_dict = parse_request_body_json(request_body, path)
+        if is_responses_api:
+            model_id = extract_model_from_responses_request(request_body_dict)
+        else:
+            model_id = request_body_dict.get("model", "unknown")
+
+    # /tee/* and /attestation GET requests don't map to models — forward
+    # without model/cost/auth lookups. Tinfoil attestation paths are routed
+    # only to Tinfoil providers so an unrelated upstream's 404 cannot
+    # short-circuit before the attestation proxy is tried.
+    if request.method == "GET" and (
+        path.startswith("tee/") or path.startswith("attestation")
+    ):
+        selected_upstreams = _select_unauthenticated_get_upstreams(path, _upstreams)
+        if not selected_upstreams:
+            return create_error_response(
+                "upstream_error",
+                "No upstream available for unauthenticated GET path",
+                502,
+                request=request,
+            )
+
         last_error_response = None
-        for i, upstream in enumerate(all_upstreams):
+        for i, upstream in enumerate(selected_upstreams):
             try:
                 headers = upstream.prepare_headers(dict(request.headers))
                 response = await upstream.forward_get_request(request, path, headers)
-                if response.status_code in [502, 429] and i < len(all_upstreams) - 1:
+                if response.status_code in [502, 429] and i < len(selected_upstreams) - 1:
                     logger.warning(
-                        "Upstream %s returned %s for tee GET %s, trying next",
+                        "Upstream %s returned %s for unauthenticated GET %s, trying next",
                         upstream.provider_type,
                         response.status_code,
                         path,
@@ -206,23 +265,18 @@ async def proxy(
                 return response
             except UpstreamError as e:
                 logger.warning(
-                    "Upstream %s failed for tee GET %s: %s",
+                    "Upstream %s failed for unauthenticated GET %s: %s",
                     upstream.provider_type,
                     path,
                     e,
                 )
-                if i == len(all_upstreams) - 1:
+                if i == len(selected_upstreams) - 1:
                     last_error_response = create_upstream_error_response(e, request)
                 continue
         return last_error_response or create_error_response(
             "upstream_error", "All upstreams failed", 502, request=request
         )
 
-    if is_responses_api:
-        model_id = extract_model_from_responses_request(request_body_dict)
-    else:
-        model_id = request_body_dict.get("model", "unknown")
-
     model_obj = get_model_instance(model_id)
 
     if not model_obj:
@@ -239,6 +293,16 @@ async def proxy(
             request=request,
         )
 
+    if is_ehbp:
+        upstreams = [upstream for upstream in upstreams if upstream.supports_ehbp]
+        if not upstreams:
+            return create_error_response(
+                "unsupported_request",
+                f"No EHBP-capable provider found for model '{model_id}'",
+                400,
+                request=request,
+            )
+
     # todo figure out cost calculation since fallback provider is usually not the same price
     # Use first provider for initial checks/cost calculation
     # primary_upstream = upstreams[0]
@@ -258,7 +322,23 @@ async def proxy(
         last_error = None
         for i, upstream in enumerate(upstreams):
             try:
-                if is_responses_api:
+                if is_ehbp:
+                    if not upstream.supports_ehbp:
+                        logger.warning(
+                            "Upstream %s does not support EHBP for model=%s",
+                            upstream.provider_type,
+                            model_id,
+                        )
+                        continue
+                    return await forward_ehbp_x_cashu_request(
+                        request=request,
+                        x_cashu_token=x_cashu,
+                        path=path,
+                        max_cost_for_model=max_cost_for_model,
+                        model_obj=model_obj,
+                        upstream=upstream,
+                    )
+                elif is_responses_api:
                     return await upstream.handle_x_cashu_responses(
                         request, x_cashu, path, max_cost_for_model, model_obj
                     )
@@ -347,7 +427,7 @@ async def proxy(
             "upstream_error", "All upstreams failed", 502, request=request
         )
 
-    if request_body_dict:
+    if is_ehbp or request_body_dict:
         await pay_for_request(key, max_cost_for_model, session)
 
     # Tracks request params already removed in response to upstream rejections,
@@ -361,7 +441,29 @@ async def proxy(
         try:
             while True:
                 try:
-                    if is_responses_api:
+                    if is_ehbp:
+                        if not upstream.supports_ehbp:
+                            logger.warning(
+                                "Upstream %s does not support EHBP for model=%s",
+                                upstream.provider_type,
+                                model_id,
+                            )
+                            raise UpstreamError(
+                                f"Provider {upstream.provider_type} does not support EHBP",
+                                status_code=400,
+                            )
+                        response = await forward_ehbp_request(
+                            request=request,
+                            path=path,
+                            headers=headers,
+                            request_body=request_body,
+                            upstream=upstream,
+                            key=key,
+                            max_cost_for_model=max_cost_for_model,
+                            session=session,
+                            model_obj=model_obj,
+                        )
+                    elif is_responses_api:
                         response = await upstream.forward_responses_request(
                             request,
                             path,
@@ -406,7 +508,7 @@ async def proxy(
                 # When the upstream 400s naming such a param, strip it from the
                 # body and retry the SAME upstream. ``already_stripped`` bounds
                 # this to one retry per distinct param so it always terminates.
-                if response.status_code == 400:
+                if response.status_code == 400 and not is_ehbp:
                     correction = correct_request(
                         request_body,
                         extract_error_message(response),

routstr/upstream/__init__.py

@@ -11,6 +11,7 @@ from .openrouter import OpenRouterUpstreamProvider
 from .perplexity import PerplexityUpstreamProvider
 from .ppqai import PPQAIUpstreamProvider
 from .routstr import RoutstrUpstreamProvider
+from .tinfoil import TinfoilUpstreamProvider
 from .xai import XAIUpstreamProvider
 
 upstream_provider_classes: list[type[BaseUpstreamProvider]] = [
@@ -26,6 +27,7 @@ upstream_provider_classes: list[type[BaseUpstreamProvider]] = [
     PerplexityUpstreamProvider,
     PPQAIUpstreamProvider,
     RoutstrUpstreamProvider,
+    TinfoilUpstreamProvider,
     XAIUpstreamProvider,
 ]
 """List of all upstream classes"""

routstr/upstream/anthropic.py

@@ -24,7 +24,7 @@ class AnthropicUpstreamProvider(BaseUpstreamProvider):
         )
 
     @classmethod
-    def from_db_row(
+    def _build_from_row(
         cls, provider_row: "UpstreamProviderRow"
     ) -> "AnthropicUpstreamProvider":
         return cls(

routstr/upstream/auto_topup.py

@@ -97,6 +97,8 @@ async def _check_and_topup(row: UpstreamProviderRow) -> None:
 
     # Instantiate provider and check balance
     provider = RoutstrUpstreamProvider.from_db_row(row)
+    if provider is None:
+        return
     balance = await provider.get_balance()
 
     if balance is None:

routstr/upstream/azure.py

@@ -38,7 +38,7 @@ class AzureUpstreamProvider(BaseUpstreamProvider):
         self.api_version = api_version
 
     @classmethod
-    def from_db_row(
+    def _build_from_row(
         cls, provider_row: "UpstreamProviderRow"
     ) -> "AzureUpstreamProvider | None":
         if not provider_row.api_version:

routstr/upstream/base.py

@@ -4,15 +4,15 @@ import asyncio
 import json
 import math
 import traceback
+import typing
 import uuid
 from collections.abc import AsyncGenerator, AsyncIterator, Iterator
-from typing import Any, Mapping, cast
+from typing import Any, Mapping, Self, cast
 
 import httpx
 from fastapi import BackgroundTasks, HTTPException, Request
 from fastapi.responses import Response, StreamingResponse
 from pydantic.v1 import BaseModel
-from sqlmodel import select
 
 from ..auth import adjust_payment_for_tokens
 from ..core import get_logger
@@ -51,6 +51,9 @@ from .count_tokens import count_tokens_locally
 from .litellm_routing import detect_litellm_prefix
 from .rate_limit import UPSTREAM_RATE_LIMIT, classify_rate_limit
 
+if typing.TYPE_CHECKING:
+    from .ehbp import ConfidentialInferenceProfile, EHBPForwardingTarget
+
 logger = get_logger(__name__)
 
 
@@ -92,6 +95,11 @@ class BaseUpstreamProvider:
     base_url: str
     api_key: str
     provider_fee: float = 1.05
+    # Primary key of the ``upstream_providers`` row this instance was built
+    # from. Set by ``from_db_row`` so a live provider can re-find its own row by
+    # stable identity instead of its rotatable ``api_key``. ``None`` for
+    # instances not sourced from a row.
+    db_id: int | None = None
     _models_cache: list[Model] = []
     _models_by_id: dict[str, Model] = {}
 
@@ -106,6 +114,7 @@ class BaseUpstreamProvider:
         self.base_url = base_url
         self.api_key = api_key
         self.provider_fee = provider_fee
+        self.db_id = None
         self._models_cache = []
         self._models_by_id = {}
 
@@ -123,10 +132,13 @@ class BaseUpstreamProvider:
         return detect_litellm_prefix(self.base_url)
 
     @classmethod
-    def from_db_row(
-        cls, provider_row: "UpstreamProviderRow"
-    ) -> "BaseUpstreamProvider | None":
-        """Factory method to instantiate provider from database row.
+    def from_db_row(cls, provider_row: "UpstreamProviderRow") -> "Self | None":
+        """Instantiate a provider from a database row, carrying its identity.
+
+        Construction itself is delegated to the ``_build_from_row`` hook (which
+        subclasses override to match their constructor); this wrapper stamps the
+        row's primary key onto the instance as ``db_id`` so the provider can
+        later re-find its own row by identity rather than by its ``api_key``.
 
         Args:
             provider_row: Database row containing provider configuration
@@ -134,6 +146,19 @@ class BaseUpstreamProvider:
         Returns:
             Instantiated provider or None if instantiation fails
         """
+        provider = cls._build_from_row(provider_row)
+        if provider is not None:
+            provider.db_id = provider_row.id
+        return provider
+
+    @classmethod
+    def _build_from_row(cls, provider_row: "UpstreamProviderRow") -> "Self | None":
+        """Construct the provider instance from a row (no identity stamping).
+
+        Overridden by subclasses whose constructors differ from the base
+        ``(base_url, api_key, provider_fee)`` shape. Callers should use
+        ``from_db_row`` instead, which also attaches ``db_id``.
+        """
         return cls(
             base_url=provider_row.base_url,
             api_key=provider_row.api_key,
@@ -2819,6 +2844,26 @@ class BaseUpstreamProvider:
             # Don't revert here — proxy.py owns payment revert to avoid double-revert
             raise UpstreamError("An unexpected server error occurred", status_code=500)
 
+    supports_ehbp: bool = False
+
+    def get_confidential_inference_profile(self) -> "ConfidentialInferenceProfile | None":
+        """Return provider policy for encrypted/confidential inference forwarding."""
+        return None
+
+    def get_ehbp_forwarding_target(
+        self, path: str, model_obj: Model
+    ) -> "EHBPForwardingTarget":
+        """Return the EHBP forwarding target for this provider.
+
+        Providers must explicitly opt in by setting ``supports_ehbp = True``
+        and overriding this method. Most upstreams do not accept EHBP-encrypted
+        request bodies, so the base provider intentionally does not provide a
+        default endpoint.
+        """
+        raise NotImplementedError(
+            f"Provider {self.provider_type} does not support EHBP forwarding"
+        )
+
     async def forward_responses_request(
         self,
         request: Request,
@@ -4878,14 +4923,11 @@ class BaseUpstreamProvider:
         """Refresh the in-memory models cache from upstream API."""
         try:
             async with create_session() as session:
-                stmt = select(UpstreamProviderRow).where(
-                    UpstreamProviderRow.base_url == self.base_url,
-                    UpstreamProviderRow.api_key == self.api_key,
+                provider = (
+                    await session.get(UpstreamProviderRow, self.db_id)
+                    if self.db_id is not None
+                    else None
                 )
-                result = await session.exec(stmt)
-
-                # .first() returns the object or None if not found
-                provider = result.first()
                 if not provider or not provider.id:
                     raise HTTPException(status_code=404, detail="Provider not found")
 

routstr/upstream/deepseek_v4_pricing_shim.py

@@ -3,10 +3,15 @@
 litellm's bundled cost map does not yet ship ``deepseek-v4-flash`` /
 ``deepseek-v4-pro``. Without an entry, ``backfill_cache_pricing`` cannot find a
 ``cache_read_input_token_cost`` and cache reads fall back to the full input
-rate — a ~60% overcharge on cache hits (DeepSeek hits are ~0.2x input).
+rate — a large overcharge on cache hits (DeepSeek V4 hits are ~0.008-0.02x
+input, i.e. cached tokens cost 50-120x less than regular input).
 
 This module injects the missing entries into ``litellm.model_cost`` at startup
-so the existing backfill path resolves them. Rates mirror the open upstream PR
+so the existing backfill path resolves them. Rates mirror the canonical
+``deepseek`` provider entries now in litellm's ``model_prices`` map
+(``input_cost_per_token`` is the cache-*miss* rate;
+``cache_read_input_token_cost`` is the cache-*hit* rate), sourced from
+https://api-docs.deepseek.com/quick_start/pricing via
 https://github.com/BerriAI/litellm/pull/26380 (issue
 https://github.com/BerriAI/litellm/issues/30430).
 
@@ -22,21 +27,23 @@ from ..core import get_logger
 
 logger = get_logger(__name__)
 
-# USD per token. Source: BerriAI/litellm PR #26380.
+# USD per token. Mirrors the canonical ``deepseek`` provider entries in
+# litellm's model_prices map (source: DeepSeek API pricing docs). Keep these in
+# sync with ``litellm.model_cost["deepseek/deepseek-v4-*"]``.
 _DEEPSEEK_V4_RATES: dict[str, dict[str, float]] = {
     "deepseek-v4-flash": {
         "input_cost_per_token": 1.4e-07,
         "output_cost_per_token": 2.8e-07,
-        "cache_read_input_token_cost": 2.8e-08,
+        "cache_read_input_token_cost": 2.8e-09,
         "cache_creation_input_token_cost": 0.0,
-        "input_cost_per_token_cache_hit": 2.8e-08,
+        "input_cost_per_token_cache_hit": 2.8e-09,
     },
     "deepseek-v4-pro": {
-        "input_cost_per_token": 1.74e-06,
-        "output_cost_per_token": 3.48e-06,
-        "cache_read_input_token_cost": 1.4e-07,
+        "input_cost_per_token": 4.35e-07,
+        "output_cost_per_token": 8.7e-07,
+        "cache_read_input_token_cost": 3.625e-09,
         "cache_creation_input_token_cost": 0.0,
-        "input_cost_per_token_cache_hit": 1.4e-07,
+        "input_cost_per_token_cache_hit": 3.625e-09,
     },
 }
 

routstr/upstream/fireworks.py

@@ -20,7 +20,7 @@ class FireworksUpstreamProvider(BaseUpstreamProvider):
         )
 
     @classmethod
-    def from_db_row(
+    def _build_from_row(
         cls, provider_row: "UpstreamProviderRow"
     ) -> "FireworksUpstreamProvider":
         return cls(

routstr/upstream/gemini.py

@@ -51,7 +51,7 @@ class GeminiUpstreamProvider(BaseUpstreamProvider):
         return self._client
 
     @classmethod
-    def from_db_row(
+    def _build_from_row(
         cls, provider_row: "UpstreamProviderRow"
     ) -> "GeminiUpstreamProvider":
         return cls(

routstr/upstream/generic.py

@@ -45,7 +45,7 @@ class GenericUpstreamProvider(BaseUpstreamProvider):
         )
 
     @classmethod
-    def from_db_row(
+    def _build_from_row(
         cls, provider_row: "UpstreamProviderRow"
     ) -> "GenericUpstreamProvider":
         return cls(

routstr/upstream/groq.py

@@ -20,7 +20,7 @@ class GroqUpstreamProvider(BaseUpstreamProvider):
         )
 
     @classmethod
-    def from_db_row(cls, provider_row: "UpstreamProviderRow") -> "GroqUpstreamProvider":
+    def _build_from_row(cls, provider_row: "UpstreamProviderRow") -> "GroqUpstreamProvider":
         return cls(
             api_key=provider_row.api_key,
             provider_fee=provider_row.provider_fee,

routstr/upstream/helpers.py

@@ -12,6 +12,7 @@ from sqlmodel import select
 
 from ..core import get_logger
 from ..core.db import AsyncSession, ModelRow, UpstreamProviderRow, create_session
+from ..core.provider_slugs import allocate_unique_provider_slug
 from ..payment.models import Model
 from .base import BaseUpstreamProvider
 
@@ -215,9 +216,6 @@ async def init_upstreams() -> list[BaseUpstreamProvider]:
 
             provider = _instantiate_provider(provider_row)
             if provider:
-                # Keep provider DB id on runtime instance so model mapping can
-                # bind DB overrides to the correct upstream.
-                setattr(provider, "db_id", provider_row.id)
                 await provider.refresh_models_cache()
                 logger.debug(
                     f"Initialized {provider_row.provider_type} provider",
@@ -250,6 +248,7 @@ async def _seed_providers_from_settings(
 
     providers_to_add: list[UpstreamProviderRow] = []
     seeded_provider_keys: set[tuple[str, str]] = set()
+    reserved_slugs: set[str] = set()
 
     provider_classes_by_type = {
         cls.provider_type: cls
@@ -264,6 +263,7 @@ async def _seed_providers_from_settings(
         ("PERPLEXITY_API_KEY", "perplexity", None, None),
         ("FIREWORKS_API_KEY", "fireworks", None, None),
         ("XAI_API_KEY", "xai", None, None),
+        ("TINFOIL_API_KEY", "tinfoil", None, None),
     ]
 
     for env_key, provider_type, _, _ in env_mappings:
@@ -279,8 +279,13 @@ async def _seed_providers_from_settings(
                     )
                 )
                 if not result.first():
+                    slug = await allocate_unique_provider_slug(
+                        session, provider_type, reserved_slugs
+                    )
+                    reserved_slugs.add(slug)
                     providers_to_add.append(
                         UpstreamProviderRow(
+                            slug=slug,
                             provider_type=provider_type,
                             base_url=base_url,
                             api_key=api_key,
@@ -299,8 +304,13 @@ async def _seed_providers_from_settings(
             )
         )
         if not result.first():
+            slug = await allocate_unique_provider_slug(
+                session, "ollama", reserved_slugs
+            )
+            reserved_slugs.add(slug)
             providers_to_add.append(
                 UpstreamProviderRow(
+                    slug=slug,
                     provider_type="ollama",
                     base_url=ollama_base_url,
                     api_key=ollama_api_key,
@@ -320,8 +330,13 @@ async def _seed_providers_from_settings(
                 )
             )
             if not result.first():
+                slug = await allocate_unique_provider_slug(
+                    session, "azure", reserved_slugs
+                )
+                reserved_slugs.add(slug)
                 providers_to_add.append(
                     UpstreamProviderRow(
+                        slug=slug,
                         provider_type="azure",
                         base_url=base_url,
                         api_key=api_key,
@@ -342,8 +357,13 @@ async def _seed_providers_from_settings(
                 )
             )
             if not result.first():
+                slug = await allocate_unique_provider_slug(
+                    session, "custom", reserved_slugs
+                )
+                reserved_slugs.add(slug)
                 providers_to_add.append(
                     UpstreamProviderRow(
+                        slug=slug,
                         provider_type="custom",
                         base_url=base_url,
                         api_key=api_key,
@@ -356,7 +376,7 @@ async def _seed_providers_from_settings(
         session.add(provider)
         logger.info(
             f"Seeding {provider.provider_type} provider",  # type: ignore[str-format]
-            extra={"base_url": provider.base_url},
+            extra={"base_url": provider.base_url, "slug": provider.slug},
         )
 
 
@@ -391,9 +411,7 @@ def _instantiate_provider(
             return provider
 
         if provider_row.provider_type == "custom":
-            return BaseUpstreamProvider(
-                provider_row.base_url, provider_row.api_key, provider_row.provider_fee
-            )
+            return BaseUpstreamProvider.from_db_row(provider_row)
 
         logger.error(
             f"Unknown provider type: {provider_row.provider_type}",

routstr/upstream/ollama.py

@@ -43,7 +43,7 @@ class OllamaUpstreamProvider(BaseUpstreamProvider):
         )
 
     @classmethod
-    def from_db_row(
+    def _build_from_row(
         cls, provider_row: "UpstreamProviderRow"
     ) -> "OllamaUpstreamProvider":
         return cls(

routstr/upstream/openai.py

@@ -20,7 +20,7 @@ class OpenAIUpstreamProvider(BaseUpstreamProvider):
         )
 
     @classmethod
-    def from_db_row(
+    def _build_from_row(
         cls, provider_row: "UpstreamProviderRow"
     ) -> "OpenAIUpstreamProvider":
         return cls(

routstr/upstream/openrouter.py

@@ -90,7 +90,7 @@ class OpenRouterUpstreamProvider(BaseUpstreamProvider):
         )
 
     @classmethod
-    def from_db_row(
+    def _build_from_row(
         cls, provider_row: "UpstreamProviderRow"
     ) -> "OpenRouterUpstreamProvider":
         return cls(

routstr/upstream/perplexity.py

@@ -23,7 +23,7 @@ class PerplexityUpstreamProvider(BaseUpstreamProvider):
         )
 
     @classmethod
-    def from_db_row(
+    def _build_from_row(
         cls, provider_row: "UpstreamProviderRow"
     ) -> "PerplexityUpstreamProvider":
         return cls(

routstr/upstream/ppqai.py

@@ -8,6 +8,7 @@ from pydantic.v1 import BaseModel, Field
 from ..core.logging import get_logger
 from ..payment.models import Architecture, Model, Pricing, async_fetch_openrouter_models
 from .base import BaseUpstreamProvider, TopupData
+from .ehbp import EHBPForwardingTarget
 
 if TYPE_CHECKING:
     from ..core.db import UpstreamProviderRow
@@ -39,6 +40,10 @@ class PPQAIUpstreamProvider(BaseUpstreamProvider):
     default_base_url = "https://api.ppq.ai"
     platform_url = "https://ppq.ai/api-docs"
     IGNORED_MODEL_IDS: list[str] = ["auto"]
+    # PPQ.AI has a private encrypted endpoint, but this proxy currently has no
+    # provider-attested usage extractor/model binding for it. Keep EHBP disabled
+    # until a ConfidentialInferenceProfile can bill it without max-cost fallback.
+    supports_ehbp = False
 
     def __init__(self, api_key: str, provider_fee: float = 1.0):
         super().__init__(
@@ -46,7 +51,7 @@ class PPQAIUpstreamProvider(BaseUpstreamProvider):
         )
 
     @classmethod
-    def from_db_row(
+    def _build_from_row(
         cls, provider_row: "UpstreamProviderRow"
     ) -> "PPQAIUpstreamProvider":
         return cls(
@@ -70,6 +75,20 @@ class PPQAIUpstreamProvider(BaseUpstreamProvider):
     def transform_model_name(self, model_id: str) -> str:
         return model_id
 
+    def get_ehbp_forwarding_target(
+        self, path: str, model_obj: Model
+    ) -> EHBPForwardingTarget:
+        """Return the PPQ.AI private enclave target for EHBP requests.
+
+        PPQ.AI exposes EHBP-aware inference under /private/v1/... separate
+        from the public /v1/... endpoint. The encrypted body remains opaque to
+        Routstr, so PPQ.AI also needs X-Private-Model for routing/billing.
+        """
+        return EHBPForwardingTarget(
+            url=f"{self.base_url.rstrip('/')}/private/{path.lstrip('/')}",
+            headers={"X-Private-Model": model_obj.forwarded_model_id or model_obj.id},
+        )
+
     @classmethod
     async def create_account_static(cls) -> dict[str, object]:
         """Create a new PPQ.AI account without requiring an instance.
@@ -229,17 +248,14 @@ class PPQAIUpstreamProvider(BaseUpstreamProvider):
                 f"Disabling PPQ.AI provider ({self.base_url}) due to insufficient balance",
                 extra={"error": error_message},
             )
-            from sqlmodel import select
-
             from ..core.db import UpstreamProviderRow, create_session
 
             async with create_session() as session:
-                statement = select(UpstreamProviderRow).where(
-                    UpstreamProviderRow.base_url == self.base_url,
-                    UpstreamProviderRow.api_key == self.api_key,
+                provider = (
+                    await session.get(UpstreamProviderRow, self.db_id)
+                    if self.db_id is not None
+                    else None
                 )
-                result = await session.exec(statement)
-                provider = result.first()
 
                 if provider:
                     provider.enabled = False

routstr/upstream/routstr.py

@@ -55,7 +55,7 @@ class RoutstrUpstreamProvider(BaseUpstreamProvider):
         return path.lstrip("/")
 
     @classmethod
-    def from_db_row(
+    def _build_from_row(
         cls, provider_row: "UpstreamProviderRow"
     ) -> "RoutstrUpstreamProvider":
         import json

routstr/upstream/tinfoil.py

@@ -0,0 +1,236 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import httpx
+from fastapi import Request
+from fastapi.responses import Response, StreamingResponse
+from pydantic.v1 import BaseModel
+
+from ..core.exceptions import UpstreamError
+from ..core.logging import get_logger
+from ..payment.models import Architecture, Model, Pricing
+from .base import BaseUpstreamProvider
+from .ehbp import (
+    _ENCLAVE_URL_HEADER,
+    _PROXY_ONLY_HEADERS,
+    _RESPONSE_USAGE_HEADER,
+    ConfidentialInferenceProfile,
+    EHBPForwardingTarget,
+)
+
+if TYPE_CHECKING:
+    from ..core.db import UpstreamProviderRow
+
+logger = get_logger(__name__)
+
+
+class TinfoilModelPricing(BaseModel):
+    inputTokenPricePer1M: float = 0.0
+    outputTokenPricePer1M: float = 0.0
+    requestPrice: float = 0.0
+
+
+class TinfoilModel(BaseModel):
+    id: str
+    context_window: int = 0
+    created: int = 0
+    multimodal: bool = False
+    reasoning: bool = False
+    tool_calling: bool = False
+    type: str = "chat"
+    pricing: TinfoilModelPricing = TinfoilModelPricing()
+    endpoints: list[str] = []
+
+
+class TinfoilUpstreamProvider(BaseUpstreamProvider):
+    """Direct upstream provider for the Tinfoil inference API.
+
+    Tinfoil hosts open-source models inside attested secure enclaves and exposes
+    an OpenAI-compatible API at ``https://inference.tinfoil.sh``. Request and
+    response bodies are encrypted end-to-end with EHBP (HPKE), so Routstr acts
+    as a blind relay: it forwards the opaque encrypted body, never sees
+    plaintext, and bills from the ``X-Tinfoil-Usage-Metrics`` header that
+    Tinfoil returns outside the encrypted body when
+    ``X-Tinfoil-Request-Usage-Metrics: true`` is set.
+    """
+
+    provider_type = "tinfoil"
+    default_base_url = "https://inference.tinfoil.sh"
+    platform_url = "https://docs.tinfoil.sh"
+    supports_ehbp = True
+    confidential_inference_profile = ConfidentialInferenceProfile(
+        usage_response_header=_RESPONSE_USAGE_HEADER,
+        client_target_url_header=_ENCLAVE_URL_HEADER,
+        allow_client_target_override=True,
+        proxy_only_headers=_PROXY_ONLY_HEADERS,
+    )
+
+    def __init__(self, api_key: str, provider_fee: float = 1.0):
+        super().__init__(
+            base_url=self.default_base_url,
+            api_key=api_key,
+            provider_fee=provider_fee,
+        )
+
+    @classmethod
+    def from_db_row(
+        cls, provider_row: "UpstreamProviderRow"
+    ) -> "TinfoilUpstreamProvider":
+        return cls(
+            api_key=provider_row.api_key,
+            provider_fee=provider_row.provider_fee,
+        )
+
+    @classmethod
+    def get_provider_metadata(cls) -> dict[str, object]:
+        return {
+            "id": cls.provider_type,
+            "name": "Tinfoil",
+            "default_base_url": cls.default_base_url,
+            "fixed_base_url": True,
+            "platform_url": cls.platform_url,
+            "can_create_account": False,
+            "can_topup": False,
+            "can_show_balance": False,
+        }
+
+    def transform_model_name(self, model_id: str) -> str:
+        return model_id.removeprefix("tinfoil/")
+
+    def get_confidential_inference_profile(self) -> ConfidentialInferenceProfile:
+        return self.confidential_inference_profile
+
+    async def forward_get_request(
+        self,
+        request: Request,
+        path: str,
+        headers: dict,
+    ) -> Response | StreamingResponse:
+        """Handle Tinfoil-specific GET endpoints.
+
+        * ``/attestation`` (or ``/tee/attestation``): proxy to the Tinfoil ATC
+          (attestation bundle proxy) at ``https://atc.tinfoil.sh/attestation``.
+        * Other GETs: forward to the provider base URL
+          (``https://inference.tinfoil.sh``). ``X-Tinfoil-Enclave-Url`` is an
+          EHBP-only header used for encrypted POST requests and is not honored
+          for unencrypted GET requests.
+        """
+        clean_path = path.removeprefix("tee/")
+        if clean_path == "attestation":
+            return await self._proxy_attestation(headers)
+        return await super().forward_get_request(request, path, headers)
+
+    async def _proxy_attestation(self, headers: dict) -> Response:
+        url = "https://atc.tinfoil.sh/attestation"
+        async with httpx.AsyncClient(
+            transport=httpx.AsyncHTTPTransport(retries=1),
+            timeout=30.0,
+        ) as client:
+            try:
+                resp = await client.get(
+                    url,
+                    headers={
+                        "Accept": headers.get("accept", "application/json"),
+                    },
+                )
+                response_headers = dict(resp.headers)
+                response_headers.pop("content-encoding", None)
+                response_headers.pop("content-length", None)
+                return Response(
+                    content=resp.content,
+                    status_code=resp.status_code,
+                    headers=response_headers,
+                )
+            except Exception as exc:
+                raise UpstreamError(
+                    f"Error fetching Tinfoil attestation: {type(exc).__name__}",
+                    status_code=502,
+                ) from exc
+
+    def get_ehbp_forwarding_target(
+        self, path: str, model_obj: Model
+    ) -> EHBPForwardingTarget:
+        """Return the Tinfoil enclave target for EHBP requests.
+
+        Requests usage metrics from the enclave so Routstr can bill exactly
+        without decrypting the response body. The actual forwarding URL is
+        overridden at dispatch time by ``X-Tinfoil-Enclave-Url`` when the SDK
+        sends it (see ``routstr/upstream/ehbp.py``).
+        """
+        return EHBPForwardingTarget(
+            url=f"{self.base_url.rstrip('/')}/{path.lstrip('/')}",
+            headers={"X-Tinfoil-Request-Usage-Metrics": "true"},
+            profile=self.confidential_inference_profile,
+        )
+
+    async def fetch_models(self) -> list[Model]:
+        """Fetch models from the public Tinfoil models endpoint.
+
+        ``GET /v1/models`` is unauthenticated and returns all available models
+        with their pricing in USD per 1M tokens.
+        """
+        url = f"{self.base_url}/v1/models"
+        try:
+            async with httpx.AsyncClient(timeout=30.0) as client:
+                response = await client.get(url)
+                response.raise_for_status()
+                data = response.json()
+                models_data = data.get("data", [])
+
+                models: list[Model] = []
+                for model_data in models_data:
+                    try:
+                        tf = TinfoilModel.parse_obj(model_data)
+                        input_price = tf.pricing.inputTokenPricePer1M
+                        output_price = tf.pricing.outputTokenPricePer1M
+                        request_price = tf.pricing.requestPrice
+
+                        modality = "text->text"
+                        input_modalities = ["text"]
+                        output_modalities = ["text"]
+                        if tf.multimodal:
+                            modality = "text->text+image"
+                            input_modalities = ["text", "image"]
+
+                        models.append(
+                            Model(
+                                id=tf.id,
+                                name=tf.id,
+                                created=tf.created,
+                                description=f"Tinfoil {tf.type} model",
+                                context_length=tf.context_window,
+                                architecture=Architecture(
+                                    modality=modality,
+                                    input_modalities=input_modalities,
+                                    output_modalities=output_modalities,
+                                    tokenizer="Unknown",
+                                    instruct_type=None,
+                                ),
+                                pricing=Pricing(
+                                    prompt=input_price / 1_000_000,
+                                    completion=output_price / 1_000_000,
+                                    request=request_price,
+                                    image=0.0,
+                                    web_search=0.0,
+                                    internal_reasoning=0.0,
+                                ),
+                            )
+                        )
+                    except Exception as e:
+                        logger.warning(
+                            "Failed to parse Tinfoil model",
+                            extra={
+                                "model_id": model_data.get("id", "unknown"),
+                                "error": str(e),
+                                "error_type": type(e).__name__,
+                            },
+                        )
+
+                return models
+        except Exception as e:
+            logger.error(
+                "Error fetching models from Tinfoil",
+                extra={"error": str(e), "error_type": type(e).__name__},
+            )
+            return []

routstr/upstream/tinfoil_trailer.py

@@ -0,0 +1,161 @@
+"""h11-based HTTP client for EHBP requests that captures HTTP trailers.
+
+httpx/httpcore silently discard HTTP trailers during chunked transfer
+decoding. Tinfoil returns ``X-Tinfoil-Usage-Metrics`` as a trailer on
+streaming responses, so we need a lower-level HTTP client that preserves
+trailers from the h11 ``EndOfMessage`` event.
+
+Because EHBP response bodies are opaque encrypted blobs, buffering the full
+response is acceptable — the client decrypts the complete body regardless of
+whether it arrived streamed or buffered.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import ssl
+from dataclasses import dataclass, field
+from urllib.parse import urlsplit
+
+import h11
+
+from ..core import get_logger
+
+logger = get_logger(__name__)
+
+_READ_BUFSIZE = 65536
+_DEFAULT_TIMEOUT_SECONDS = 30.0
+_DEFAULT_CLOSE_TIMEOUT_SECONDS = 1.0
+_DEFAULT_MAX_RESPONSE_BYTES = 25 * 1024 * 1024
+
+
+@dataclass
+class TrailerResponse:
+    """Buffered HTTP response with optional trailer headers."""
+
+    status_code: int
+    headers: list[tuple[str, str]]
+    body: bytes
+    trailers: list[tuple[str, str]] = field(default_factory=list)
+
+
+def _get_header(headers: list[tuple[str, str]], name: str) -> str | None:
+    name_lower = name.lower()
+    for k, v in headers:
+        if k.lower() == name_lower:
+            return v
+    return None
+
+
+async def forward_with_trailer(
+    *,
+    method: str,
+    url: str,
+    headers: dict[str, str],
+    body: bytes,
+    timeout_seconds: float = _DEFAULT_TIMEOUT_SECONDS,
+    max_response_bytes: int = _DEFAULT_MAX_RESPONSE_BYTES,
+    close_timeout_seconds: float = _DEFAULT_CLOSE_TIMEOUT_SECONDS,
+) -> TrailerResponse:
+    """Send an HTTP/1.1 request via h11 and capture HTTP trailers.
+
+    Returns a :class:`TrailerResponse` with the full buffered body and any
+    trailer headers from the ``EndOfMessage`` event.
+    """
+    parsed = urlsplit(url)
+    host = parsed.hostname
+    if not host:
+        raise ValueError(f"Invalid URL (no hostname): {url}")
+    port = parsed.port or 443
+    path = parsed.path or "/"
+    if parsed.query:
+        path = f"{path}?{parsed.query}"
+
+    ssl_ctx = ssl.create_default_context()
+    reader, writer = await asyncio.wait_for(
+        asyncio.open_connection(host, port, ssl=ssl_ctx),
+        timeout=timeout_seconds,
+    )
+
+    try:
+        # Build HTTP/1.1 request
+        header_lines = [f"{method} {path} HTTP/1.1"]
+        has_host = any(k.lower() == "host" for k in headers)
+        if not has_host:
+            header_lines.append(f"Host: {host}")
+        header_lines.append("Connection: close")
+
+        for key, value in headers.items():
+            if key.lower() in ("host", "connection"):
+                continue
+            header_lines.append(f"{key}: {value}")
+
+        if body and not any(k.lower() == "content-length" for k in headers):
+            header_lines.append(f"Content-Length: {len(body)}")
+
+        request_data = "\r\n".join(header_lines).encode() + b"\r\n\r\n"
+        if body:
+            request_data += body
+
+        writer.write(request_data)
+        await asyncio.wait_for(writer.drain(), timeout=timeout_seconds)
+
+        # Parse response with h11
+        conn = h11.Connection(h11.CLIENT)
+        status_code = 0
+        resp_headers: list[tuple[str, str]] = []
+        body_chunks: list[bytes] = []
+        body_size = 0
+        trailers: list[tuple[str, str]] = []
+
+        while True:
+            event = conn.next_event()
+
+            if event is h11.NEED_DATA:
+                data = await asyncio.wait_for(
+                    reader.read(_READ_BUFSIZE),
+                    timeout=timeout_seconds,
+                )
+                conn.receive_data(data if data else b"")
+                continue
+
+            if isinstance(event, h11.Response):
+                status_code = event.status_code
+                resp_headers = [(k.decode(), v.decode()) for k, v in event.headers]
+
+            elif isinstance(event, h11.Data):
+                body_size += len(event.data)
+                if body_size > max_response_bytes:
+                    raise ValueError(
+                        f"EHBP response exceeded {max_response_bytes} bytes"
+                    )
+                body_chunks.append(event.data)
+
+            elif isinstance(event, h11.EndOfMessage):
+                for k, v in event.headers:
+                    trailers.append((k.decode(), v.decode()))
+                break
+
+            elif isinstance(event, h11.PAUSED):
+                # Shouldn't happen for simple request/response, but break safely
+                logger.warning("h11 PAUSED event during EHBP response parsing")
+                break
+
+            elif isinstance(event, h11.ConnectionClosed):
+                break
+
+        return TrailerResponse(
+            status_code=status_code,
+            headers=resp_headers,
+            body=b"".join(body_chunks),
+            trailers=trailers,
+        )
+    finally:
+        writer.close()
+        if close_timeout_seconds > 0:
+            try:
+                await asyncio.wait_for(
+                    writer.wait_closed(), timeout=close_timeout_seconds
+                )
+            except Exception:
+                pass

routstr/upstream/xai.py

@@ -21,7 +21,7 @@ class XAIUpstreamProvider(BaseUpstreamProvider):
         )
 
     @classmethod
-    def from_db_row(cls, provider_row: "UpstreamProviderRow") -> "XAIUpstreamProvider":
+    def _build_from_row(cls, provider_row: "UpstreamProviderRow") -> "XAIUpstreamProvider":
         return cls(
             api_key=provider_row.api_key,
             provider_fee=provider_row.provider_fee,

tests/integration/test_admin_model_cache_pricing.py

@@ -0,0 +1,229 @@
+import json
+from datetime import datetime, timedelta, timezone
+from unittest.mock import patch
+
+import pytest
+from httpx import AsyncClient
+from sqlmodel.ext.asyncio.session import AsyncSession
+
+from routstr.core.admin import admin_sessions
+from routstr.core.db import ModelRow, UpstreamProviderRow
+from routstr.payment.cost_calculation import CostData, calculate_cost
+from routstr.proxy import get_model_instance, reinitialize_upstreams
+
+
+def _admin_headers() -> dict[str, str]:
+    token = "test-admin-cache-pricing-token"
+    admin_sessions[token] = int(
+        (datetime.now(timezone.utc) + timedelta(minutes=5)).timestamp()
+    )
+    return {"Authorization": f"Bearer {token}"}
+
+
+def _model_payload(
+    provider_id: int,
+    *,
+    cache_read: float,
+    cache_write: float,
+) -> dict[str, object]:
+    return {
+        "id": "custom-cache-model",
+        "name": "Custom Cache Model",
+        "description": "custom model with explicit cache pricing",
+        "created": 0,
+        "context_length": 128000,
+        "architecture": {
+            "modality": "text",
+            "input_modalities": ["text"],
+            "output_modalities": ["text"],
+            "tokenizer": "unknown",
+            "instruct_type": None,
+        },
+        "pricing": {
+            "prompt": 1.4e-7,
+            "completion": 2.8e-7,
+            "input_cache_read": cache_read,
+            "input_cache_write": cache_write,
+            "request": 0.0,
+            "image": 0.0,
+            "web_search": 0.0,
+            "internal_reasoning": 0.0,
+        },
+        "per_request_limits": None,
+        "top_provider": None,
+        "upstream_provider_id": provider_id,
+        "canonical_slug": None,
+        "alias_ids": [],
+        "enabled": True,
+        "forwarded_model_id": "custom-cache-model",
+    }
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_admin_provider_model_api_persists_cache_pricing_on_create_and_update(
+    integration_client: AsyncClient,
+    integration_session: AsyncSession,
+) -> None:
+    provider = UpstreamProviderRow(
+        provider_type="generic",
+        base_url="https://custom-upstream.example/v1",
+        api_key="test-key",
+        provider_fee=1.0,
+    )
+    integration_session.add(provider)
+    await integration_session.commit()
+    await integration_session.refresh(provider)
+    assert provider.id is not None
+    await reinitialize_upstreams()
+
+    headers = _admin_headers()
+    create_payload = _model_payload(
+        provider.id,
+        cache_read=2.8e-9,
+        cache_write=3.5e-9,
+    )
+
+    with patch("routstr.payment.models.sats_usd_price", return_value=1e-6):
+        create_response = await integration_client.post(
+            f"/admin/api/upstream-providers/{provider.id}/models",
+            headers=headers,
+            json=create_payload,
+        )
+
+    assert create_response.status_code == 200
+    create_body = create_response.json()
+    assert create_body["pricing"]["input_cache_read"] == pytest.approx(2.8e-9)
+    assert create_body["pricing"]["input_cache_write"] == pytest.approx(3.5e-9)
+
+    row = await integration_session.get(ModelRow, ("custom-cache-model", provider.id))
+    assert row is not None
+    stored_pricing = json.loads(row.pricing)
+    assert stored_pricing["input_cache_read"] == pytest.approx(2.8e-9)
+    assert stored_pricing["input_cache_write"] == pytest.approx(3.5e-9)
+
+    update_payload = _model_payload(
+        provider.id,
+        cache_read=1.25e-9,
+        cache_write=4.5e-9,
+    )
+
+    with patch("routstr.payment.models.sats_usd_price", return_value=1e-6):
+        update_response = await integration_client.post(
+            f"/admin/api/upstream-providers/{provider.id}/models",
+            headers=headers,
+            json=update_payload,
+        )
+
+    assert update_response.status_code == 200
+    update_body = update_response.json()
+    assert update_body["pricing"]["input_cache_read"] == pytest.approx(1.25e-9)
+    assert update_body["pricing"]["input_cache_write"] == pytest.approx(4.5e-9)
+
+    await integration_session.refresh(row)
+    updated_pricing = json.loads(row.pricing)
+    assert updated_pricing["input_cache_read"] == pytest.approx(1.25e-9)
+    assert updated_pricing["input_cache_write"] == pytest.approx(4.5e-9)
+
+    model = get_model_instance("custom-cache-model")
+    assert model is not None
+    assert model.sats_pricing is not None
+    assert model.sats_pricing.input_cache_read == pytest.approx(0.00125)
+    assert model.sats_pricing.input_cache_write == pytest.approx(0.0045)
+
+    with patch("routstr.payment.cost_calculation.sats_usd_price", return_value=1e-6):
+        cost = await calculate_cost(
+            {
+                "model": "custom-cache-model",
+                "usage": {
+                    "prompt_tokens": 1000,
+                    "completion_tokens": 100,
+                    "prompt_tokens_details": {"cached_tokens": 800},
+                },
+            },
+            max_cost=1_000_000,
+        )
+
+    assert isinstance(cost, CostData)
+    assert cost.input_tokens == 200
+    assert cost.cache_read_input_tokens == 800
+    assert cost.cache_read_msats == 1000
+    assert cost.output_msats == 28000
+    assert cost.input_msats == 29000
+    assert cost.total_msats == 57000
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_upstream_response_cost_uses_model_cache_pricing(
+    integration_session: AsyncSession,
+    patched_db_engine: None,
+) -> None:
+    """A model's configured cache price must discount upstream cached-token usage."""
+    provider = UpstreamProviderRow(
+        provider_type="generic",
+        base_url="https://cache-priced-upstream.example/v1",
+        api_key="test-key",
+        provider_fee=1.0,
+    )
+    integration_session.add(provider)
+    await integration_session.commit()
+    await integration_session.refresh(provider)
+    assert provider.id is not None
+
+    row = ModelRow(
+        id="cache-priced-model",
+        name="Cache Priced Model",
+        description="model seeded with explicit cache pricing",
+        created=0,
+        context_length=128000,
+        architecture=json.dumps(
+            {
+                "modality": "text",
+                "input_modalities": ["text"],
+                "output_modalities": ["text"],
+                "tokenizer": "unknown",
+                "instruct_type": None,
+            }
+        ),
+        pricing=json.dumps(
+            {
+                "prompt": 1.4e-7,
+                "completion": 2.8e-7,
+                "input_cache_read": 1.25e-9,
+                "input_cache_write": 4.5e-9,
+            }
+        ),
+        upstream_provider_id=provider.id,
+        enabled=True,
+        forwarded_model_id="cache-priced-model",
+    )
+    integration_session.add(row)
+    await integration_session.commit()
+
+    with patch("routstr.payment.models.sats_usd_price", return_value=1e-6):
+        await reinitialize_upstreams()
+
+    with patch("routstr.payment.cost_calculation.sats_usd_price", return_value=1e-6):
+        cost = await calculate_cost(
+            {
+                "model": "cache-priced-model",
+                "usage": {
+                    "prompt_tokens": 1000,
+                    "completion_tokens": 100,
+                    "prompt_tokens_details": {"cached_tokens": 800},
+                },
+            },
+            max_cost=1_000_000,
+        )
+
+    assert isinstance(cost, CostData)
+    # prompt 1.4e-7 USD/token -> 0.14 sats/token -> 140 msats/token
+    # cache 1.25e-9 USD/token -> 0.00125 sats/token -> 1.25 msats/token
+    # completion 2.8e-7 USD/token -> 0.28 sats/token -> 280 msats/token
+    assert cost.input_tokens == 200
+    assert cost.cache_read_input_tokens == 800
+    assert cost.cache_read_msats == 1000
+    assert cost.input_msats == 29000
+    assert cost.output_msats == 28000
+    assert cost.total_msats == 57000

tests/integration/test_provider_self_lookup.py

@@ -0,0 +1,128 @@
+"""A live upstream provider resolves its OWN database row by stable identity
+(its primary key), not by its mutable/secret ``api_key``.
+
+Today ``from_db_row`` drops ``provider_row.id`` and the two self-referential
+paths — PPQ.AI's insufficient-balance self-disable and the base
+``refresh_models_cache`` — re-find their own row with
+``WHERE base_url == self.base_url AND api_key == self.api_key``. That uses a
+rotatable secret as a self-handle: the moment the row's key changes underneath a
+live object (a rotation racing an in-flight request), the object can no longer
+find itself. These tests pin the invariant that a provider looks itself up by
+identity, so the lookup survives a key change (and, later, key encryption).
+"""
+
+from unittest.mock import AsyncMock, patch
+
+import pytest
+
+from routstr.core.db import UpstreamProviderRow
+from routstr.upstream.ppqai import PPQAIUpstreamProvider
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_provider_object_carries_its_persistent_identity(
+    integration_session: object,
+    patched_db_engine: None,
+) -> None:
+    """``from_db_row`` gives the in-memory object its row's identity (``db_id``)."""
+    row = UpstreamProviderRow(
+        provider_type="ppqai",
+        base_url="https://api.ppq.ai",
+        api_key="sk-original",
+        enabled=True,
+        provider_fee=1.0,
+    )
+    integration_session.add(row)  # type: ignore[attr-defined]
+    await integration_session.commit()  # type: ignore[attr-defined]
+    await integration_session.refresh(row)  # type: ignore[attr-defined]
+
+    provider = PPQAIUpstreamProvider.from_db_row(row)
+    assert provider is not None
+
+    assert provider.db_id == row.id
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_self_disable_targets_own_row_after_key_rotation(
+    integration_session: object,
+    patched_db_engine: None,
+) -> None:
+    """PPQ.AI self-disable must disable *its* row even after the key rotated.
+
+    RED (current): the object holds the pre-rotation key, so the
+    ``(base_url, api_key)`` lookup misses the row → the provider is never
+    disabled. GREEN: lookup by ``id`` finds it and disables it.
+    """
+    row = UpstreamProviderRow(
+        provider_type="ppqai",
+        base_url="https://api.ppq.ai",
+        api_key="sk-original",
+        enabled=True,
+        provider_fee=1.0,
+    )
+    integration_session.add(row)  # type: ignore[attr-defined]
+    await integration_session.commit()  # type: ignore[attr-defined]
+    await integration_session.refresh(row)  # type: ignore[attr-defined]
+
+    provider = PPQAIUpstreamProvider.from_db_row(row)  # captures sk-original
+    assert provider is not None
+
+    # Key is rotated in the DB while `provider` is still live.
+    row.api_key = "sk-rotated"
+    integration_session.add(row)  # type: ignore[attr-defined]
+    await integration_session.commit()  # type: ignore[attr-defined]
+
+    with patch("routstr.proxy.reinitialize_upstreams", new=AsyncMock()):
+        await provider.on_upstream_error_redirect(402, "Insufficient balance")
+
+    await integration_session.refresh(row)  # type: ignore[attr-defined]
+    assert row.enabled is False
+
+
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_refresh_models_cache_finds_own_row_after_key_rotation(
+    integration_session: object,
+    patched_db_engine: None,
+) -> None:
+    """``refresh_models_cache`` must resolve its own row after a key rotation.
+
+    ``refresh_models_cache`` swallows every exception (it only logs), so the
+    observable proof it found its row is that it reaches ``list_models`` — which
+    is called with the row's ``id`` only *after* the row is resolved. RED
+    (current): the stale-key ``(base_url, api_key)`` lookup returns nothing, the
+    method raises ``404`` internally and returns before ``list_models`` is ever
+    called. GREEN: lookup by ``id`` finds the row and ``list_models`` runs for
+    that ``id``.
+    """
+    row = UpstreamProviderRow(
+        provider_type="ppqai",
+        base_url="https://api.ppq.ai",
+        api_key="sk-original",
+        enabled=True,
+        provider_fee=1.0,
+    )
+    integration_session.add(row)  # type: ignore[attr-defined]
+    await integration_session.commit()  # type: ignore[attr-defined]
+    await integration_session.refresh(row)  # type: ignore[attr-defined]
+    row_id = row.id
+
+    provider = PPQAIUpstreamProvider.from_db_row(row)  # captures sk-original
+    assert provider is not None
+
+    row.api_key = "sk-rotated"
+    integration_session.add(row)  # type: ignore[attr-defined]
+    await integration_session.commit()  # type: ignore[attr-defined]
+
+    list_models_mock = AsyncMock(return_value=[])
+    with (
+        patch.object(provider, "fetch_models", new=AsyncMock(return_value=[])),
+        patch("routstr.upstream.base.list_models", new=list_models_mock),
+    ):
+        await provider.refresh_models_cache()
+
+    list_models_mock.assert_awaited_once()
+    assert list_models_mock.await_args is not None
+    assert list_models_mock.await_args.kwargs["upstream_id"] == row_id

tests/unit/test_cache_pricing.py

@@ -81,6 +81,21 @@ def test_backfill_strips_vendor_prefix_for_litellm_lookup() -> None:
     assert result.input_cache_read == expected
 
 
+def test_backfill_case_insensitive_lookup() -> None:
+    """A generic upstream may report a mixed-case id
+    (deepseek-ai/DeepSeek-V4-Flash); litellm keys are lowercase. The
+    case-insensitive fallback still resolves the cache rate."""
+    pricing = Pricing(prompt=1.4e-07, completion=2.8e-07)
+
+    result = backfill_cache_pricing("deepseek-ai/DeepSeek-V4-Flash", pricing)
+
+    expected = litellm.model_cost["deepseek-v4-flash"][
+        "cache_read_input_token_cost"
+    ]
+    assert result.input_cache_read == expected
+    assert result.input_cache_read < pricing.prompt  # sanity: it's a discount
+
+
 def test_backfill_fills_cache_write_rate() -> None:
     """Anthropic cache writes cost more than input (1.25x); billing them at
     the input rate undercharges. litellm carries the write rate."""
@@ -136,6 +151,93 @@ def test_provider_fee_applies_to_backfilled_cache_rates() -> None:
     assert adjusted.pricing.prompt == pytest.approx(2.8e-07 * 2.0)
 
 
+def test_row_to_model_backfills_cache_rate() -> None:
+    """The DB-override path (admin-configured providers, e.g. a generic
+    upstream) stores pricing without cache rates. ``_row_to_model`` must
+    backfill them from litellm just like ``_apply_provider_fee_to_model``,
+    otherwise cache reads bill at the full input rate."""
+    import json
+
+    from routstr.core.db import ModelRow
+    from routstr.payment.models import _row_to_model
+
+    row = ModelRow(
+        id="deepseek-v4-flash",
+        name="deepseek-v4-flash",
+        created=0,
+        description="",
+        context_length=1000000,
+        architecture=json.dumps(
+            {
+                "modality": "text",
+                "input_modalities": ["text"],
+                "output_modalities": ["text"],
+                "tokenizer": "unknown",
+                "instruct_type": None,
+            }
+        ),
+        # Stored pricing omits input_cache_read (generic provider never sets it).
+        pricing=json.dumps({"prompt": 1.4e-07, "completion": 2.8e-07}),
+        enabled=True,
+        upstream_provider_id=1,
+    )
+
+    with patch(
+        "routstr.payment.models.sats_usd_price", return_value=5.0e-5
+    ):
+        model = _row_to_model(row, apply_provider_fee=True, provider_fee=1.0)
+
+    litellm_read = litellm.model_cost["deepseek-v4-flash"][
+        "cache_read_input_token_cost"
+    ]
+    assert model.pricing.input_cache_read == pytest.approx(litellm_read)
+    assert model.pricing.input_cache_read < model.pricing.prompt  # a discount
+    assert model.sats_pricing is not None
+    assert model.sats_pricing.input_cache_read > 0
+
+
+def test_row_to_model_backfills_via_forwarded_model_id() -> None:
+    """An alias row (id != forwarded_model_id) must backfill cache rates from
+    the *forwarded* model name — the real upstream model litellm prices —
+    not the alias id, which litellm doesn't know."""
+    import json
+
+    from routstr.core.db import ModelRow
+    from routstr.payment.models import _row_to_model
+
+    row = ModelRow(
+        id="local-alias",  # litellm has no such key
+        name="local-alias",
+        created=0,
+        description="",
+        context_length=1000000,
+        architecture=json.dumps(
+            {
+                "modality": "text",
+                "input_modalities": ["text"],
+                "output_modalities": ["text"],
+                "tokenizer": "unknown",
+                "instruct_type": None,
+            }
+        ),
+        pricing=json.dumps({"prompt": 1.4e-07, "completion": 2.8e-07}),
+        enabled=True,
+        upstream_provider_id=1,
+        forwarded_model_id="deepseek-v4-flash",
+    )
+
+    with patch(
+        "routstr.payment.models.sats_usd_price", return_value=5.0e-5
+    ):
+        model = _row_to_model(row, apply_provider_fee=True, provider_fee=1.0)
+
+    litellm_read = litellm.model_cost["deepseek-v4-flash"][
+        "cache_read_input_token_cost"
+    ]
+    assert model.pricing.input_cache_read == pytest.approx(litellm_read)
+    assert model.pricing.input_cache_read < model.pricing.prompt
+
+
 # ============================================================================
 # calculate_cost — cached tokens billed at cache rates
 # ============================================================================

tests/unit/test_cost_calculation_caching.py

@@ -404,6 +404,67 @@ async def test_deepseek_malformed_hit_tokens_coerce_to_zero() -> None:
     assert result.cache_read_input_tokens == 0
 
 
+# ============================================================================
+# Truly-empty response with a non-zero USD cost → full refund
+#
+# When an upstream reports a USD cost but the response carries NO tokens at all
+# (input, output, cache-read and cache-creation all zero), billing the
+# USD-derived cost charges the user for nothing. Refund in full. The gate is
+# tightened relative to PR #489: a cache-read/-creation-only turn legitimately
+# reports zero prompt/completion tokens with a real cost and must still bill.
+# ============================================================================
+@pytest.mark.asyncio
+async def test_truly_empty_usd_cost_response_is_refunded(
+    mock_fixed_pricing: None,
+) -> None:
+    """0 input + 0 output + 0 cache tokens with a non-zero USD cost → refund."""
+    response = {
+        "model": "gpt-4",
+        "usage": {
+            "prompt_tokens": 0,
+            "completion_tokens": 0,
+            "total_cost": 0.01,  # non-zero USD cost despite no tokens
+        },
+    }
+    result = await calculate_cost(response, max_cost=100000)
+
+    assert isinstance(result, CostData)
+    assert result.total_msats == 0  # full refund
+    assert result.input_msats == 0
+    assert result.output_msats == 0
+    assert result.total_usd == 0.0
+    assert result.input_tokens == 0
+    assert result.output_tokens == 0
+    assert result.cache_read_input_tokens == 0
+    assert result.cache_creation_input_tokens == 0
+
+
+@pytest.mark.asyncio
+async def test_cache_read_only_usd_cost_response_is_billed(
+    mock_fixed_pricing: None,
+) -> None:
+    """Cache-read-only turn (0 prompt/completion, non-zero cost) still bills."""
+    response = {
+        "model": "claude-3-5-sonnet",
+        "usage": {
+            "input_tokens": 0,
+            "output_tokens": 0,
+            "cache_read_input_tokens": 1000,  # real cached usage
+            "cache_creation_input_tokens": 0,
+            "total_cost": 0.01,  # non-zero USD cost
+        },
+    }
+    result = await calculate_cost(response, max_cost=100000)
+
+    assert isinstance(result, CostData)
+    # NOT refunded — the USD cost is billed in full. Pinning the exact value
+    # guards against any future regression that would over-refund a cache-only
+    # turn (the bug in PR #489, which refunded whenever prompt+completion == 0).
+    assert result.total_msats == 200000
+    assert result.total_usd == 0.01
+    assert result.cache_read_input_tokens == 1000
+
+
 # ============================================================================
 # Test 13: Missing Usage Block
 # ============================================================================

tests/unit/test_ehbp_finalize_payment.py

@@ -0,0 +1,185 @@
+from __future__ import annotations
+
+from typing import AsyncGenerator
+
+import pytest
+from sqlalchemy.ext.asyncio import AsyncEngine, create_async_engine
+from sqlalchemy.pool import StaticPool
+from sqlmodel import SQLModel, select
+from sqlmodel.ext.asyncio.session import AsyncSession
+
+from routstr.core.db import ApiKey
+from routstr.upstream.ehbp import (
+    finalize_ehbp_actual_cost_payment,
+    finalize_ehbp_max_cost_payment,
+)
+
+
+def _make_engine() -> AsyncEngine:
+    return create_async_engine(
+        "sqlite+aiosqlite://",
+        poolclass=StaticPool,
+        connect_args={"check_same_thread": False},
+    )
+
+
+@pytest.fixture
+async def session(monkeypatch: pytest.MonkeyPatch) -> AsyncGenerator[AsyncSession, None]:
+    monkeypatch.setattr("routstr.upstream.ehbp.ROUTSTR_FEE_PERCENT", 0)
+    engine = _make_engine()
+    async with engine.begin() as conn:
+        await conn.run_sync(SQLModel.metadata.create_all)
+    db_session = AsyncSession(engine, expire_on_commit=False)
+    try:
+        yield db_session
+    finally:
+        await db_session.close()
+        await engine.dispose()
+
+
+async def _api_key(session: AsyncSession, hashed_key: str) -> ApiKey | None:
+    return (
+        await session.exec(select(ApiKey).where(ApiKey.hashed_key == hashed_key))
+    ).one_or_none()
+
+
+@pytest.mark.asyncio
+async def test_finalize_actual_cost_payment_updates_balance_and_releases_reserve(
+    session: AsyncSession,
+) -> None:
+    key = ApiKey(
+        hashed_key="ehbp-actual",
+        balance=10_000,
+        reserved_balance=3_000,
+        reserved_at=123,
+    )
+    session.add(key)
+    await session.commit()
+
+    await finalize_ehbp_actual_cost_payment(
+        key,
+        session,
+        reserved_cost_for_model=3_000,
+        model_id="tinfoil/model",
+        cost_info={
+            "total_msats": 1_200,
+            "input_tokens": 10,
+            "output_tokens": 20,
+            "input_msats": 500,
+            "output_msats": 700,
+        },
+    )
+
+    updated = await _api_key(session, "ehbp-actual")
+    assert updated is not None
+    assert updated.balance == 8_800
+    assert updated.reserved_balance == 0
+    assert updated.reserved_at is None
+    assert updated.total_spent == 1_200
+
+
+@pytest.mark.asyncio
+async def test_finalize_max_cost_payment_updates_parent_and_child_spend(
+    session: AsyncSession,
+) -> None:
+    parent = ApiKey(
+        hashed_key="ehbp-parent",
+        balance=10_000,
+        reserved_balance=3_000,
+        reserved_at=123,
+    )
+    child = ApiKey(
+        hashed_key="ehbp-child",
+        balance=0,
+        reserved_balance=3_000,
+        reserved_at=123,
+        parent_key_hash="ehbp-parent",
+    )
+    session.add(parent)
+    session.add(child)
+    await session.commit()
+
+    await finalize_ehbp_max_cost_payment(
+        child,
+        session,
+        max_cost_for_model=3_000,
+        model_id="tinfoil/model",
+    )
+
+    updated_parent = await _api_key(session, "ehbp-parent")
+    updated_child = await _api_key(session, "ehbp-child")
+    assert updated_parent is not None
+    assert updated_child is not None
+    assert updated_parent.balance == 7_000
+    assert updated_parent.reserved_balance == 0
+    assert updated_parent.reserved_at is None
+    assert updated_parent.total_spent == 3_000
+    assert updated_child.balance == 0
+    assert updated_child.reserved_balance == 0
+    assert updated_child.reserved_at is None
+    assert updated_child.total_spent == 3_000
+
+
+@pytest.mark.asyncio
+async def test_finalize_actual_cost_payment_rolls_back_when_parent_update_matches_no_rows(
+    session: AsyncSession,
+) -> None:
+    key = ApiKey(
+        hashed_key="ehbp-missing-parent",
+        balance=10_000,
+        reserved_balance=3_000,
+        reserved_at=123,
+    )
+    session.add(key)
+    await session.commit()
+    await session.delete(key)
+    await session.commit()
+
+    await finalize_ehbp_actual_cost_payment(
+        key,
+        session,
+        reserved_cost_for_model=3_000,
+        model_id="tinfoil/model",
+        cost_info={"total_msats": 1_200},
+    )
+
+    assert await _api_key(session, "ehbp-missing-parent") is None
+
+
+@pytest.mark.asyncio
+async def test_finalize_max_cost_payment_rolls_back_parent_when_child_update_matches_no_rows(
+    session: AsyncSession,
+) -> None:
+    parent = ApiKey(
+        hashed_key="ehbp-rollback-parent",
+        balance=10_000,
+        reserved_balance=3_000,
+        reserved_at=123,
+    )
+    child = ApiKey(
+        hashed_key="ehbp-missing-child",
+        balance=0,
+        reserved_balance=3_000,
+        reserved_at=123,
+        parent_key_hash="ehbp-rollback-parent",
+    )
+    session.add(parent)
+    session.add(child)
+    await session.commit()
+    await session.delete(child)
+    await session.commit()
+
+    await finalize_ehbp_max_cost_payment(
+        child,
+        session,
+        max_cost_for_model=3_000,
+        model_id="tinfoil/model",
+    )
+
+    updated_parent = await _api_key(session, "ehbp-rollback-parent")
+    assert updated_parent is not None
+    assert updated_parent.balance == 10_000
+    assert updated_parent.reserved_balance == 3_000
+    assert updated_parent.reserved_at == 123
+    assert updated_parent.total_spent == 0
+    assert await _api_key(session, "ehbp-missing-child") is None

tests/unit/test_provider_slug_migration.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+import importlib.util
+from pathlib import Path
+
+import sqlalchemy as sa
+
+_MIGRATION_PATH = (
+    Path(__file__).resolve().parents[2]
+    / "migrations"
+    / "versions"
+    / "c6d7e8f9a0b1_add_slug_to_upstream_providers.py"
+)
+_spec = importlib.util.spec_from_file_location("provider_slug_migration", _MIGRATION_PATH)
+assert _spec is not None and _spec.loader is not None
+migration = importlib.util.module_from_spec(_spec)
+_spec.loader.exec_module(migration)
+
+
+def test_slug_migration_backfill_uses_api_safe_deterministic_slugs() -> None:
+    engine = sa.create_engine("sqlite:///:memory:")
+    with engine.begin() as conn:
+        conn.execute(
+            sa.text(
+                "CREATE TABLE upstream_providers ("
+                "id INTEGER PRIMARY KEY, "
+                "provider_type VARCHAR NOT NULL, "
+                "slug VARCHAR NULL"
+                ")"
+            )
+        )
+        conn.execute(
+            sa.text(
+                "INSERT INTO upstream_providers (id, provider_type, slug) VALUES "
+                "(1, 'OpenAI Compatible', NULL), "
+                "(2, 'OpenAI Compatible', ''), "
+                "(3, '123', NULL), "
+                "(4, 'x', NULL), "
+                "(5, 'anthropic', 'anthropic')"
+            )
+        )
+
+        migration._backfill_provider_slugs(conn)
+
+        rows = conn.execute(
+            sa.text("SELECT id, slug FROM upstream_providers ORDER BY id")
+        ).all()
+
+    assert rows == [
+        (1, "openai-compatible"),
+        (2, "openai-compatible-2"),
+        (3, "provider-123"),
+        (4, "x-provider"),
+        (5, "anthropic"),
+    ]

tests/unit/test_provider_slugs.py

@@ -0,0 +1,144 @@
+from __future__ import annotations
+
+import pytest
+from sqlalchemy.ext.asyncio import create_async_engine
+from sqlmodel import SQLModel, select
+from sqlmodel.ext.asyncio.session import AsyncSession
+
+from routstr.core.admin import _get_upstream_provider_by_ref
+from routstr.core.db import UpstreamProviderRow
+from routstr.core.provider_slugs import (
+    allocate_unique_provider_slug,
+    provider_slug_base,
+)
+from routstr.upstream.helpers import _seed_providers_from_settings
+
+
+@pytest.mark.asyncio
+async def test_allocate_unique_provider_slug_is_deterministic_with_suffixes() -> None:
+    engine = create_async_engine("sqlite+aiosqlite:///:memory:")
+    async with engine.begin() as conn:
+        await conn.run_sync(SQLModel.metadata.create_all)
+
+    async with AsyncSession(engine) as session:
+        session.add(
+            UpstreamProviderRow(
+                slug="openai",
+                provider_type="openai",
+                base_url="https://api.openai.com/v1",
+                api_key="key-1",
+            )
+        )
+        await session.commit()
+
+        assert await allocate_unique_provider_slug(session, "openai") == "openai-2"
+        assert (
+            await allocate_unique_provider_slug(session, "openai", {"openai-2"})
+            == "openai-3"
+        )
+
+    await engine.dispose()
+
+
+def test_provider_slug_base_sanitizes_provider_type() -> None:
+    assert provider_slug_base("OpenAI Compatible") == "openai-compatible"
+    assert provider_slug_base("!!!") == "provider"
+    assert provider_slug_base("AI") == "ai-provider"
+    assert provider_slug_base("123") == "provider-123"
+
+
+@pytest.mark.asyncio
+async def test_provider_ref_lookup_accepts_existing_numeric_ids_and_slugs() -> None:
+    engine = create_async_engine("sqlite+aiosqlite:///:memory:")
+    async with engine.begin() as conn:
+        await conn.run_sync(SQLModel.metadata.create_all)
+
+    async with AsyncSession(engine) as session:
+        provider = UpstreamProviderRow(
+            slug="openai",
+            provider_type="openai",
+            base_url="https://api.openai.com/v1",
+            api_key="key-1",
+        )
+        session.add(provider)
+        await session.commit()
+        await session.refresh(provider)
+
+        by_id = await _get_upstream_provider_by_ref(session, str(provider.id))
+        by_slug = await _get_upstream_provider_by_ref(session, "openai")
+
+    assert by_id.id == provider.id
+    assert by_slug.id == provider.id
+
+    await engine.dispose()
+
+
+@pytest.mark.asyncio
+async def test_seed_providers_from_settings_sets_deterministic_slug(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    engine = create_async_engine("sqlite+aiosqlite:///:memory:")
+    async with engine.begin() as conn:
+        await conn.run_sync(SQLModel.metadata.create_all)
+
+    monkeypatch.setenv("OPENAI_API_KEY", "seeded-openai-key")
+
+    class SettingsStub:
+        chat_completions_api_version: str | None = None
+        upstream_base_url: str | None = None
+        upstream_api_key: str = ""
+
+    async with AsyncSession(engine) as session:
+        await _seed_providers_from_settings(session, SettingsStub())  # type: ignore[arg-type]
+        await session.commit()
+
+        result = await session.exec(select(UpstreamProviderRow))
+        providers: list[UpstreamProviderRow] = list(result.all())
+
+    assert [(p.provider_type, p.slug) for p in providers] == [("openai", "openai")]
+
+    await engine.dispose()
+
+
+@pytest.mark.asyncio
+async def test_seed_providers_from_settings_keeps_slug_stable_on_reseed(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    engine = create_async_engine("sqlite+aiosqlite:///:memory:")
+    async with engine.begin() as conn:
+        await conn.run_sync(SQLModel.metadata.create_all)
+
+    monkeypatch.setenv("OPENAI_API_KEY", "seeded-openai-key")
+
+    class SettingsStub:
+        chat_completions_api_version: str | None = None
+        upstream_base_url: str | None = None
+        upstream_api_key: str = ""
+
+    async with AsyncSession(engine) as session:
+        session.add(
+            UpstreamProviderRow(
+                slug="openai",
+                provider_type="openai",
+                base_url="https://example.invalid/v1",
+                api_key="other-key",
+            )
+        )
+        await session.commit()
+
+        await _seed_providers_from_settings(session, SettingsStub())  # type: ignore[arg-type]
+        await session.commit()
+        await _seed_providers_from_settings(session, SettingsStub())  # type: ignore[arg-type]
+        await session.commit()
+
+        result = await session.exec(
+            select(UpstreamProviderRow).order_by(UpstreamProviderRow.slug)
+        )
+        providers: list[UpstreamProviderRow] = list(result.all())
+
+    assert [(p.provider_type, p.slug) for p in providers] == [
+        ("openai", "openai"),
+        ("openai", "openai-2"),
+    ]
+
+    await engine.dispose()

tests/unit/test_proxy_tinfoil_attestation_routing.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+from fastapi import FastAPI
+from fastapi.responses import Response
+from httpx import ASGITransport, AsyncClient
+
+from routstr import proxy as proxy_module
+
+
+@pytest.fixture
+def proxy_app() -> FastAPI:
+    app = FastAPI()
+    app.include_router(proxy_module.proxy_router)
+    return app
+
+
+@pytest.mark.asyncio
+async def test_attestation_get_routes_directly_to_tinfoil_provider(
+    monkeypatch: pytest.MonkeyPatch, proxy_app: FastAPI
+) -> None:
+    non_tinfoil = MagicMock()
+    non_tinfoil.provider_type = "openai"
+    non_tinfoil.prepare_headers = MagicMock(return_value={})
+    non_tinfoil.forward_get_request = AsyncMock(
+        return_value=Response(status_code=404, content=b"wrong upstream")
+    )
+
+    tinfoil = MagicMock()
+    tinfoil.provider_type = "tinfoil"
+    tinfoil.prepare_headers = MagicMock(return_value={"accept": "application/json"})
+    tinfoil.forward_get_request = AsyncMock(
+        return_value=Response(status_code=200, content=b'{"attestation":true}')
+    )
+
+    monkeypatch.setattr(proxy_module, "_upstreams", [non_tinfoil, tinfoil])
+
+    async with AsyncClient(
+        transport=ASGITransport(app=proxy_app), base_url="http://test"  # type: ignore[arg-type]
+    ) as client:
+        response = await client.get("/attestation")
+
+    assert response.status_code == 200
+    assert response.content == b'{"attestation":true}'
+    non_tinfoil.forward_get_request.assert_not_called()
+    tinfoil.forward_get_request.assert_awaited_once()
+
+
+@pytest.mark.asyncio
+async def test_tee_attestation_get_routes_directly_to_tinfoil_provider(
+    monkeypatch: pytest.MonkeyPatch, proxy_app: FastAPI
+) -> None:
+    non_tinfoil = MagicMock()
+    non_tinfoil.provider_type = "openrouter"
+    non_tinfoil.prepare_headers = MagicMock(return_value={})
+    non_tinfoil.forward_get_request = AsyncMock(
+        return_value=Response(status_code=404, content=b"wrong upstream")
+    )
+
+    tinfoil = MagicMock()
+    tinfoil.provider_type = "tinfoil"
+    tinfoil.prepare_headers = MagicMock(return_value={"accept": "application/json"})
+    tinfoil.forward_get_request = AsyncMock(
+        return_value=Response(status_code=200, content=b'{"tee":true}')
+    )
+
+    monkeypatch.setattr(proxy_module, "_upstreams", [non_tinfoil, tinfoil])
+
+    async with AsyncClient(
+        transport=ASGITransport(app=proxy_app), base_url="http://test"  # type: ignore[arg-type]
+    ) as client:
+        response = await client.get("/tee/attestation")
+
+    assert response.status_code == 200
+    assert response.content == b'{"tee":true}'
+    non_tinfoil.forward_get_request.assert_not_called()
+    tinfoil.forward_get_request.assert_awaited_once()
+
+
+def test_attestation_upstream_selection_is_tinfoil_only() -> None:
+    non_tinfoil = MagicMock(provider_type="openai")
+    tinfoil = MagicMock(provider_type="tinfoil")
+
+    assert proxy_module._select_unauthenticated_get_upstreams(
+        "attestation", [non_tinfoil, tinfoil]
+    ) == [tinfoil]
+    assert proxy_module._select_unauthenticated_get_upstreams(
+        "tee/attestation", [non_tinfoil, tinfoil]
+    ) == [tinfoil]
+    assert proxy_module._select_unauthenticated_get_upstreams(
+        "tee/other", [non_tinfoil, tinfoil]
+    ) == [non_tinfoil, tinfoil]
+

tests/unit/test_tinfoil_integration.py

@@ -0,0 +1,367 @@
+"""Unit tests for Tinfoil direct integration.
+
+Covers the EHBP usage-metrics header parser, the proxy header stripping, the
+enclave URL override, and the TinfoilUpstreamProvider model fetching/forwarding
+target logic.
+"""
+
+from __future__ import annotations
+
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from routstr.upstream.ehbp import (
+    _PROXY_ONLY_HEADERS,
+    _compute_ehbp_actual_cost,
+    _prepare_ehbp_upstream_headers,
+    _resolve_ehbp_target_url,
+    _strip_proxy_headers,
+    parse_tinfoil_usage_metrics,
+)
+from routstr.upstream.tinfoil import (
+    TinfoilModel,
+    TinfoilUpstreamProvider,
+)
+
+# ---------------------------------------------------------------------------
+# parse_tinfoil_usage_metrics
+# ---------------------------------------------------------------------------
+
+
+class TestParseTinfoilUsageMetrics:
+    def test_full_header(self) -> None:
+        result = parse_tinfoil_usage_metrics("prompt=67,completion=42,total=109")
+        assert result == {
+            "prompt_tokens": 67,
+            "completion_tokens": 42,
+            "total_tokens": 109,
+        }
+
+    def test_without_total(self) -> None:
+        result = parse_tinfoil_usage_metrics("prompt=10,completion=5")
+        assert result == {"prompt_tokens": 10, "completion_tokens": 5}
+
+    def test_none(self) -> None:
+        assert parse_tinfoil_usage_metrics(None) is None
+
+    def test_empty(self) -> None:
+        assert parse_tinfoil_usage_metrics("") is None
+
+    def test_malformed(self) -> None:
+        assert parse_tinfoil_usage_metrics("garbage") is None
+
+    def test_missing_completion(self) -> None:
+        assert parse_tinfoil_usage_metrics("prompt=10") is None
+
+    def test_extra_whitespace(self) -> None:
+        result = parse_tinfoil_usage_metrics(
+            "prompt = 100 , completion = 200 , total = 300"
+        )
+        assert result == {
+            "prompt_tokens": 100,
+            "completion_tokens": 200,
+            "total_tokens": 300,
+        }
+
+
+# ---------------------------------------------------------------------------
+# _strip_proxy_headers
+# ---------------------------------------------------------------------------
+
+
+class TestStripProxyHeaders:
+    def test_strips_all_proxy_only(self) -> None:
+        headers = {
+            "x-routstr-model": "tinfoil-llama3-3-70b",
+            "X-Tinfoil-Enclave-Url": "https://inference.tinfoil.sh",
+            "X-Tinfoil-Request-Usage-Metrics": "true",
+            "Authorization": "Bearer secret",
+            "Ehbp-Encapsulated-Key": "abc123",
+        }
+        clean = _strip_proxy_headers(headers)
+        assert "x-routstr-model" not in clean
+        assert "X-Tinfoil-Enclave-Url" not in clean
+        assert "X-Tinfoil-Request-Usage-Metrics" not in clean
+        assert clean["Authorization"] == "Bearer secret"
+        assert clean["Ehbp-Encapsulated-Key"] == "abc123"
+
+    def test_all_proxy_only_headers_covered(self) -> None:
+        assert _PROXY_ONLY_HEADERS == {
+            "x-routstr-model",
+            "x-tinfoil-enclave-url",
+            "x-tinfoil-request-usage-metrics",
+        }
+
+
+class TestPrepareEHBPUpstreamHeaders:
+    def test_strips_client_proxy_headers_before_merging_target_headers(self) -> None:
+        headers = {
+            "x-routstr-model": "tinfoil-llama3-3-70b",
+            "X-Tinfoil-Enclave-Url": "https://enclave.tinfoil.sh",
+            "X-Tinfoil-Request-Usage-Metrics": "false",
+            "Authorization": "Bearer upstream-key",
+            "Ehbp-Encapsulated-Key": "abc123",
+        }
+        target_headers = {"X-Tinfoil-Request-Usage-Metrics": "true"}
+
+        clean = _prepare_ehbp_upstream_headers(headers, target_headers)
+
+        assert "x-routstr-model" not in clean
+        assert "X-Tinfoil-Enclave-Url" not in clean
+        assert clean["Authorization"] == "Bearer upstream-key"
+        assert clean["Ehbp-Encapsulated-Key"] == "abc123"
+        assert clean["X-Tinfoil-Request-Usage-Metrics"] == "true"
+
+
+# ---------------------------------------------------------------------------
+# _resolve_ehbp_target_url
+# ---------------------------------------------------------------------------
+
+
+class TestResolveEhbpTargetUrl:
+    def test_override_with_enclave_url_for_tinfoil(self) -> None:
+        result = _resolve_ehbp_target_url(
+            "https://default.example.com/v1/chat/completions",
+            "v1/chat/completions",
+            {"X-Tinfoil-Enclave-Url": "https://enclave.tinfoil.sh"},
+            "tinfoil",
+        )
+        assert result == "https://enclave.tinfoil.sh/v1/chat/completions"
+
+    def test_override_lowercase_header_for_tinfoil(self) -> None:
+        result = _resolve_ehbp_target_url(
+            "https://default.example.com/v1/chat/completions",
+            "v1/chat/completions",
+            {"x-tinfoil-enclave-url": "https://enclave.tinfoil.sh"},
+            "tinfoil",
+        )
+        assert result == "https://enclave.tinfoil.sh/v1/chat/completions"
+
+    def test_no_override(self) -> None:
+        default = "https://inference.tinfoil.sh/v1/chat/completions"
+        result = _resolve_ehbp_target_url(
+            default,
+            "v1/chat/completions",
+            {},
+            "tinfoil",
+        )
+        assert result == default
+
+    def test_non_tinfoil_provider_ignores_enclave_url(self) -> None:
+        default = "https://api.ppq.ai/private/v1/chat/completions"
+        result = _resolve_ehbp_target_url(
+            default,
+            "v1/chat/completions",
+            {"X-Tinfoil-Enclave-Url": "https://enclave.tinfoil.sh"},
+            "ppqai",
+        )
+        assert result == default
+
+    @pytest.mark.parametrize(
+        "bad_url",
+        [
+            "http://enclave.tinfoil.sh",
+            "https://attacker.example",
+            "https://tinfoil.sh.attacker.example",
+            "https://127.0.0.1",
+            "https://enclave.tinfoil.sh:8443",
+            "https://user:pass@enclave.tinfoil.sh",
+        ],
+    )
+    def test_tinfoil_rejects_unsafe_enclave_url(self, bad_url: str) -> None:
+        from routstr.core.exceptions import UpstreamError
+
+        with pytest.raises(UpstreamError):
+            _resolve_ehbp_target_url(
+                "https://default.example.com/v1/chat/completions",
+                "v1/chat/completions",
+                {"X-Tinfoil-Enclave-Url": bad_url},
+                "tinfoil",
+            )
+
+
+# ---------------------------------------------------------------------------
+# _compute_ehbp_actual_cost
+# ---------------------------------------------------------------------------
+
+
+class TestComputeEhbpActualCost:
+    @pytest.mark.asyncio
+    async def test_no_usage_falls_back_to_max_cost(self) -> None:
+        model_obj = MagicMock()
+        model_obj.id = "llama3-3-70b"
+        result = await _compute_ehbp_actual_cost(None, model_obj, 100_000)
+        assert result["total_msats"] == 100_000
+        assert result["input_tokens"] == 0
+        assert result["output_tokens"] == 0
+
+    @pytest.mark.asyncio
+    async def test_usage_parsed_and_clamped(self) -> None:
+        model_obj = MagicMock()
+        model_obj.id = "llama3-3-70b"
+        # The actual cost from calculate_cost will be small; we just verify
+        # it's clamped to min_request_msat at minimum.
+        with patch(
+            "routstr.upstream.ehbp.calculate_cost",
+            new_callable=AsyncMock,
+        ) as mock_calc:
+            from routstr.payment.cost_calculation import CostData
+
+            mock_calc.return_value = CostData(
+                base_msats=0,
+                input_msats=10,
+                output_msats=20,
+                total_msats=30,
+                total_usd=0.0001,
+                input_tokens=67,
+                output_tokens=42,
+            )
+            result = await _compute_ehbp_actual_cost(
+                "prompt=67,completion=42,total=109",
+                model_obj,
+                100_000,
+            )
+            assert result["total_msats"] == 30
+            assert result["total_msats"] <= 100_000
+            assert result["input_tokens"] == 67
+            assert result["output_tokens"] == 42
+            assert result["total_tokens"] == 109
+            assert result["input_msats"] == 10
+            assert result["output_msats"] == 20
+
+    @pytest.mark.asyncio
+    async def test_max_cost_data_falls_back(self) -> None:
+        model_obj = MagicMock()
+        model_obj.id = "llama3-3-70b"
+        with patch(
+            "routstr.upstream.ehbp.calculate_cost",
+            new_callable=AsyncMock,
+        ) as mock_calc:
+            from routstr.payment.cost_calculation import MaxCostData
+
+            mock_calc.return_value = MaxCostData(
+                base_msats=0,
+                input_msats=0,
+                output_msats=0,
+                total_msats=0,
+                total_usd=0.0,
+                input_tokens=0,
+                output_tokens=0,
+            )
+            result = await _compute_ehbp_actual_cost(
+                "prompt=0,completion=0",
+                model_obj,
+                50_000,
+            )
+            assert result["total_msats"] == 50_000
+            assert result["input_tokens"] == 0
+            assert result["output_tokens"] == 0
+
+
+# ---------------------------------------------------------------------------
+# TinfoilUpstreamProvider
+# ---------------------------------------------------------------------------
+
+
+class TestTinfoilUpstreamProvider:
+    def test_provider_type_and_defaults(self) -> None:
+        assert TinfoilUpstreamProvider.provider_type == "tinfoil"
+        assert (
+            TinfoilUpstreamProvider.default_base_url
+            == "https://inference.tinfoil.sh"
+        )
+        assert TinfoilUpstreamProvider.supports_ehbp is True
+
+    def test_transform_model_name(self) -> None:
+        provider = TinfoilUpstreamProvider(api_key="test")
+        assert provider.transform_model_name("tinfoil/llama3-3-70b") == "llama3-3-70b"
+        assert provider.transform_model_name("llama3-3-70b") == "llama3-3-70b"
+
+    def test_get_ehbp_forwarding_target_includes_usage_header(self) -> None:
+        provider = TinfoilUpstreamProvider(api_key="test")
+        model_obj = MagicMock()
+        model_obj.id = "llama3-3-70b"
+        model_obj.forwarded_model_id = "llama3-3-70b"
+        target = provider.get_ehbp_forwarding_target("v1/chat/completions", model_obj)
+        assert (
+            target.headers["X-Tinfoil-Request-Usage-Metrics"] == "true"
+        )
+        assert "v1/chat/completions" in target.url
+
+    def test_get_provider_metadata(self) -> None:
+        meta = TinfoilUpstreamProvider.get_provider_metadata()
+        assert meta["id"] == "tinfoil"
+        assert meta["name"] == "Tinfoil"
+        assert meta["fixed_base_url"] is True
+
+    def test_tinfoil_model_pricing_parses(self) -> None:
+        data = {
+            "id": "llama3-3-70b",
+            "context_window": 128000,
+            "created": 1721764788,
+            "pricing": {
+                "inputTokenPricePer1M": 1.75,
+                "outputTokenPricePer1M": 2.75,
+                "requestPrice": 0,
+            },
+            "endpoints": ["/v1/chat/completions"],
+            "type": "chat",
+        }
+        tf = TinfoilModel.parse_obj(data)
+        assert tf.id == "llama3-3-70b"
+        assert tf.pricing.inputTokenPricePer1M == 1.75
+        assert tf.pricing.outputTokenPricePer1M == 2.75
+
+    @pytest.mark.asyncio
+    async def test_fetch_models_parses_response(self) -> None:
+        provider = TinfoilUpstreamProvider(api_key="test")
+        mock_response = MagicMock()
+        mock_response.status_code = 200
+        mock_response.raise_for_status = MagicMock()
+        mock_response.json.return_value = {
+            "data": [
+                {
+                    "id": "llama3-3-70b",
+                    "context_window": 128000,
+                    "created": 1721764788,
+                    "multimodal": False,
+                    "pricing": {
+                        "inputTokenPricePer1M": 1.75,
+                        "outputTokenPricePer1M": 2.75,
+                        "requestPrice": 0,
+                    },
+                    "endpoints": ["/v1/chat/completions"],
+                    "type": "chat",
+                }
+            ]
+        }
+
+        with patch("routstr.upstream.tinfoil.httpx.AsyncClient") as mock_client_cls:
+            mock_client = MagicMock()
+            mock_client.__aenter__ = AsyncMock(return_value=mock_client)
+            mock_client.__aexit__ = AsyncMock(return_value=None)
+            mock_client.get = AsyncMock(return_value=mock_response)
+            mock_client_cls.return_value = mock_client
+
+            models = await provider.fetch_models()
+
+        assert len(models) == 1
+        assert models[0].id == "llama3-3-70b"
+        assert models[0].pricing.prompt == 1.75 / 1_000_000
+        assert models[0].pricing.completion == 2.75 / 1_000_000
+        assert models[0].context_length == 128000
+
+    @pytest.mark.asyncio
+    async def test_fetch_models_handles_error(self) -> None:
+        provider = TinfoilUpstreamProvider(api_key="test")
+        with patch("routstr.upstream.tinfoil.httpx.AsyncClient") as mock_client_cls:
+            mock_client = MagicMock()
+            mock_client.__aenter__ = AsyncMock(return_value=mock_client)
+            mock_client.__aexit__ = AsyncMock(return_value=None)
+            mock_client.get = AsyncMock(side_effect=Exception("network error"))
+            mock_client_cls.return_value = mock_client
+
+            models = await provider.fetch_models()
+
+        assert models == []

tests/unit/test_tinfoil_trailer.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+from routstr.upstream.tinfoil_trailer import forward_with_trailer
+
+
+class FakeReader:
+    def __init__(self, chunks: list[bytes]) -> None:
+        self._chunks = chunks
+
+    async def read(self, _size: int) -> bytes:
+        if self._chunks:
+            return self._chunks.pop(0)
+        return b""
+
+
+class FakeWriter:
+    def __init__(self) -> None:
+        self.written = b""
+        self.drain = AsyncMock()
+        self.wait_closed = AsyncMock()
+        self.close = MagicMock()
+
+    def write(self, data: bytes) -> None:
+        self.written += data
+
+
+@pytest.mark.asyncio
+async def test_forward_with_trailer_captures_usage_trailer(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    response = (
+        b"HTTP/1.1 200 OK\r\n"
+        b"Transfer-Encoding: chunked\r\n"
+        b"Trailer: X-Tinfoil-Usage-Metrics\r\n"
+        b"\r\n"
+        b"5\r\nhello\r\n"
+        b"0\r\n"
+        b"X-Tinfoil-Usage-Metrics: prompt=1,completion=2,total=3\r\n"
+        b"\r\n"
+    )
+    reader = FakeReader([response])
+    writer = FakeWriter()
+    open_connection = AsyncMock(return_value=(reader, writer))
+    monkeypatch.setattr(
+        "routstr.upstream.tinfoil_trailer.asyncio.open_connection", open_connection
+    )
+
+    result = await forward_with_trailer(
+        method="POST",
+        url="https://enclave.tinfoil.sh/v1/chat/completions?stream=true",
+        headers={"Authorization": "Bearer upstream"},
+        body=b"opaque",
+    )
+
+    assert result.status_code == 200
+    assert result.body == b"hello"
+    assert result.trailers == [
+        ("x-tinfoil-usage-metrics", "prompt=1,completion=2,total=3")
+    ]
+    assert b"Connection: close" in writer.written
+    writer.close.assert_called_once()
+    writer.wait_closed.assert_awaited_once()
+
+
+@pytest.mark.asyncio
+async def test_forward_with_trailer_enforces_response_size_limit(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    response = b"HTTP/1.1 200 OK\r\nContent-Length: 5\r\n\r\nhello"
+    reader = FakeReader([response])
+    writer = FakeWriter()
+    monkeypatch.setattr(
+        "routstr.upstream.tinfoil_trailer.asyncio.open_connection",
+        AsyncMock(return_value=(reader, writer)),
+    )
+
+    with pytest.raises(ValueError, match="EHBP response exceeded"):
+        await forward_with_trailer(
+            method="POST",
+            url="https://enclave.tinfoil.sh/v1/chat/completions",
+            headers={},
+            body=b"opaque",
+            max_response_bytes=4,
+        )
+
+    writer.close.assert_called_once()

ui/components/add-provider-model-dialog.tsx

@@ -68,6 +68,8 @@ const FormSchema = z.object({
   upstream_provider_id: z.string().default(''),
   input_cost: z.coerce.number().min(0).default(0),
   output_cost: z.coerce.number().min(0).default(0),
+  cache_read_cost: z.coerce.number().min(0).default(0),
+  cache_write_cost: z.coerce.number().min(0).default(0),
   request_cost: z.coerce.number().min(0).default(0),
   image_cost: z.coerce.number().min(0).default(0),
   web_search_cost: z.coerce.number().min(0).default(0),
@@ -125,6 +127,8 @@ export function AddProviderModelDialog({
       upstream_provider_id: '',
       input_cost: 0,
       output_cost: 0,
+      cache_read_cost: 0,
+      cache_write_cost: 0,
       request_cost: 0,
       image_cost: 0,
       web_search_cost: 0,
@@ -190,6 +194,8 @@ export function AddProviderModelDialog({
             : initialData.upstream_provider_id?.toString() || '',
         input_cost: pricing?.prompt ?? 0,
         output_cost: pricing?.completion ?? 0,
+        cache_read_cost: pricing?.input_cache_read ?? 0,
+        cache_write_cost: pricing?.input_cache_write ?? 0,
         request_cost: pricing?.request ?? 0,
         image_cost: pricing?.image ?? 0,
         web_search_cost: pricing?.web_search ?? 0,
@@ -231,6 +237,8 @@ export function AddProviderModelDialog({
         upstream_provider_id: '',
         input_cost: 0,
         output_cost: 0,
+        cache_read_cost: 0,
+        cache_write_cost: 0,
         request_cost: 0,
         image_cost: 0,
         web_search_cost: 0,
@@ -294,6 +302,8 @@ export function AddProviderModelDialog({
     );
     form.setValue('input_cost', pricing?.prompt ?? 0);
     form.setValue('output_cost', pricing?.completion ?? 0);
+    form.setValue('cache_read_cost', pricing?.input_cache_read ?? 0);
+    form.setValue('cache_write_cost', pricing?.input_cache_write ?? 0);
     form.setValue('request_cost', pricing?.request ?? 0);
     form.setValue('image_cost', pricing?.image ?? 0);
     form.setValue('web_search_cost', pricing?.web_search ?? 0);
@@ -365,6 +375,8 @@ export function AddProviderModelDialog({
         pricing: {
           prompt: data.input_cost,
           completion: data.output_cost,
+          input_cache_read: data.cache_read_cost,
+          input_cache_write: data.cache_write_cost,
           request: data.request_cost,
           image: data.image_cost,
           web_search: data.web_search_cost,
@@ -810,6 +822,38 @@ export function AddProviderModelDialog({
                     </FormItem>
                   )}
                 />
+                <FormField
+                  control={form.control}
+                  name='cache_read_cost'
+                  render={({ field }) => (
+                    <FormItem>
+                      <FormLabel>Cache Read Cost</FormLabel>
+                      <FormControl>
+                        <Input type='number' step='0.000001' {...field} />
+                      </FormControl>
+                      <FormDescription>
+                        Discounted cached-input read price per 1M tokens.
+                      </FormDescription>
+                      <FormMessage />
+                    </FormItem>
+                  )}
+                />
+                <FormField
+                  control={form.control}
+                  name='cache_write_cost'
+                  render={({ field }) => (
+                    <FormItem>
+                      <FormLabel>Cache Write Cost</FormLabel>
+                      <FormControl>
+                        <Input type='number' step='0.000001' {...field} />
+                      </FormControl>
+                      <FormDescription>
+                        Cached-input creation price per 1M tokens.
+                      </FormDescription>
+                      <FormMessage />
+                    </FormItem>
+                  )}
+                />
                 <FormField
                   control={form.control}
                   name='request_cost'

ui/components/provider-form-fields.tsx

@@ -118,6 +118,26 @@ export function ProviderFormFields({
         />
       )}
 
+      <div className='grid gap-2'>
+        <Label htmlFor={`${idPrefix}slug`}>
+          Slug {mode === 'create' ? '(optional, auto-generated)' : ''}
+        </Label>
+        <Input
+          id={`${idPrefix}slug`}
+          value={formData.slug || ''}
+          onChange={(e) =>
+            setFormData((prev) => ({
+              ...prev,
+              slug: e.target.value || undefined,
+            }))
+          }
+          placeholder='e.g. openai-prod'
+        />
+        <p className='text-muted-foreground text-xs'>
+          Stable external key used to update this provider via the admin API.
+        </p>
+      </div>
+
       <div className='grid gap-2'>
         <Label htmlFor={`${idPrefix}base_url`}>Base URL</Label>
         <Input

ui/lib/api/services/admin.ts

@@ -14,6 +14,7 @@ export const ProviderTypeSchema = z.object({
 
 export const UpstreamProviderSchema = z.object({
   id: z.number(),
+  slug: z.string().nullable().optional(),
   provider_type: z.string(),
   base_url: z.string(),
   api_key: z.string().optional(),
@@ -31,6 +32,7 @@ export const CreateUpstreamProviderSchema = z.object({
   enabled: z.boolean().default(true),
   provider_fee: z.number().optional(),
   provider_settings: z.record(z.string(), z.any()).nullable().optional(),
+  slug: z.string().optional(),
 });
 
 export const UpdateUpstreamProviderSchema = z.object({
@@ -41,6 +43,7 @@ export const UpdateUpstreamProviderSchema = z.object({
   enabled: z.boolean().optional(),
   provider_fee: z.number().optional(),
   provider_settings: z.record(z.string(), z.any()).nullable().optional(),
+  slug: z.string().optional(),
 });
 
 export const AdminModelPricingSchema = z.object({
@@ -50,6 +53,8 @@ export const AdminModelPricingSchema = z.object({
   image: z.number().optional(),
   web_search: z.number().optional(),
   internal_reasoning: z.number().optional(),
+  input_cache_read: z.number().optional(),
+  input_cache_write: z.number().optional(),
 });
 
 export const AdminModelArchitectureSchema = z.object({
@@ -146,7 +151,7 @@ export class AdminService {
     if (!pricing) return pricing;
     const result = { ...pricing };
 
-    // Only prompt and completion are per-token and need scaling to per-1M
+    // Token-priced fields are stored per-token by the API and shown per-1M in the UI.
     const convertField = (field: string) => {
       const val = result[field];
       if (val !== undefined && val !== null) {
@@ -161,6 +166,8 @@ export class AdminService {
 
     convertField('prompt');
     convertField('completion');
+    convertField('input_cache_read');
+    convertField('input_cache_write');
 
     // Other fields (request, image, etc.) are already flat fees (per item)
     // so we do NOT scale them.
@@ -174,7 +181,7 @@ export class AdminService {
     if (!pricing) return pricing;
     const result = { ...pricing };
 
-    // Only prompt and completion are per-1M in UI and need scaling down to per-token
+    // Token-priced fields are per-1M in the UI and need scaling down to per-token.
     const convertField = (field: string) => {
       const val = result[field];
       if (val !== undefined && val !== null) {
@@ -187,6 +194,8 @@ export class AdminService {
 
     convertField('prompt');
     convertField('completion');
+    convertField('input_cache_read');
+    convertField('input_cache_write');
 
     // Other fields stay as flat fees
 

uv.lock

@@ -2392,6 +2392,7 @@ dependencies = [
     { name = "cashu" },
     { name = "fastapi", extra = ["standard"] },
     { name = "greenlet" },
+    { name = "h11" },
     { name = "httpx", extra = ["socks"] },
     { name = "litellm" },
     { name = "marshmallow" },
@@ -2426,6 +2427,7 @@ requires-dist = [
     { name = "cashu", specifier = ">=0.20" },
     { name = "fastapi", extras = ["standard"], specifier = ">=0.115" },
     { name = "greenlet", specifier = ">=3.2.1" },
+    { name = "h11", specifier = ">=0.14" },
     { name = "httpx", extras = ["socks"], specifier = ">=0.25.2" },
     { name = "litellm", specifier = ">=1.55.0" },
     { name = "marshmallow", specifier = ">=3.13,<4.0" },