Security Model¶

The whole design rests on one property: the daemon has no authentication because it is never reachable. routstrd binds loopback-only on port 8009; the auth proxy on 8008 is the single public surface, and it is the only component that makes authorisation decisions.

Request decision flow¶

The proxy is default-deny. A request is only forwarded if some rule explicitly allows it.

flowchart TD
    A["request arrives on 8008"] --> B{"management path?<br/>npubs, clients, usage"}
    B -->|yes| C["own handler<br/>NIP-98 required"]
    B -->|no| D{"GET or HEAD<br/>on a public path?"}
    D -->|yes| E["forward, no auth"]
    D -->|no| F{"Authorization header?"}
    F -->|missing| G["401"]
    F -->|"Bearer sk-..."| H{"key found in clients?"}
    H -->|no| I["401"]
    H -->|yes| J{"restricted path?<br/>wallet, node control"}
    J -->|yes| K["403"]
    J -->|no| L["forward with header intact"]
    F -->|"Nostr event"| M{"valid NIP-98?<br/>url, method, body hash, sig"}
    M -->|no| N["401"]
    M -->|yes| O{"pubkey registered?<br/>and role sufficient?"}
    O -->|no| P["403"]
    O -->|yes| Q["forward, header stripped"]

Two details are easy to miss:

• Public means GET/HEAD only. The proxy applies the public-path rule only to read methods, because the daemon routes a POST to those same paths as a paid request. GET /v1/models needs no credential; POST /v1/models does.
• Management paths are matched before anything else. /npubs, /clients, /clients/add, /clients/delete, /usage, and /usage/summary are handled by the proxy's own handlers and never forwarded to the daemon wholesale.

Public paths¶

Reachable with no credential at all (GET/HEAD only):

This is intentional — an agent needs to discover models before it has a key, and provider discovery is public information in Routstr.

Credential one: API keys (Bearer sk-...)¶

An API key is looked up in the client records. If no client carries it, the request is rejected with 401 Invalid API key.

Keys are deliberately narrow. A valid key is refused with 403 on every restricted path:

The rule of thumb: an API key buys inference, and nothing else.

Key handling on the way through: the Authorization header is preserved so the daemon can validate the key itself, and its own accounting stays authoritative.

Credential two: NIP-98 (Nostr <base64-event>)¶

Management and wallet operations require a signed NIP-98 event. This is not a bearer token — it is a signature over the specific request, so it cannot be replayed against a different endpoint.

The proxy enforces, in order:

The proxy then looks the pubkey up in routstr_auth_npubs:

• Not registered → 403. The error message is context-aware: on a node with no npubs at all it tells you to run routstrd npubs register; otherwise it says registered auth is required.
• Registered but role insufficient → 403 Admin access required.
• Registered and sufficient → forwarded, with the Authorization header stripped so it does not reach the daemon or the upstream provider.

Role requirements by endpoint¶

Bootstrap window¶

While routstr_auth_npubs is empty, POST /npubs is accepted without authentication. This exists solely so a fresh node can be claimed, and it closes permanently after the first registration.

The practical implication: a node that is deployed and healthy but has not had its first admin register is unclaimed. Treat deployment and bootstrap as one operation.

There is deliberately no hardcoded default admin in the image. The absence of one means an image cannot be shipped with a known admin key — but it also means a half-finished deployment is claimable by whoever finds it first.

As an alternative to the interactive step, admins can be seeded with ROUTSTRD_AUTH_ADMIN_NPUBS, ROUTSTRD_AUTH_ADMIN_PUBKEYS, or ROUTSTRD_AUTH_BOOTSTRAP_NPUB. Rows created this way are tagged source = 'env' and reconciled at every startup — remove the value from the environment and the row is deleted, which is a clean way to authorise a node declaratively.

CORS¶

The proxy answers with:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PATCH, DELETE, OPTIONS
Access-Control-Allow-Headers: Authorization, Content-Type, X-Cashu, X-Routstr-Model
Access-Control-Expose-Headers: X-Cashu, X-Routstr-Request-Id, X-Routstr-Cost-Msats,
                               X-Routstr-Cost-Usd, X-Routstr-Input-Cost-Msats,
                               X-Routstr-Output-Cost-Msats

A wildcard origin is safe here specifically because the app uses no cookies and no sessions. There is no ambient browser identity for a cross-origin page to borrow — a malicious page cannot make an authenticated request on a visitor's behalf, because every non-public request still needs its own API key or signature.

Hardening checklist¶

• Daemon is loopback-only. Verify 8009 is not published (docker port routstr-remote, or check the Cloudron app's port config).
• TLS everywhere. No member or agent should ever send an sk-... key over plaintext HTTP.
• First admin registered immediately after install.
• Reverse proxy sets X-Forwarded-Proto / X-Forwarded-Host, or NIP-98 fails.
• Streaming hangs are fixed with timeouts, not by buffering. Disable proxy_buffering and raise proxy_read_timeout; do not "fix" a truncated stream by publishing the daemon directly.
• ROUTSTRD_AUTH_ADMIN_NPUBS reflects reality if you use env bootstrapping — those rows are deleted on restart when the variable changes.
• Departed members have their clients deleted, not just their npub. Deleting an npub does not revoke existing API keys.
• Backups cover /app/data and are tested, including the nsec in routstrd/config.json.
• Model allowlist verified if you rely on it — it fails open when the model list has not been populated.

Next steps¶

• Troubleshooting — diagnosing 401 and 403 responses.
• Team Members — the two-step offboarding that revocation alone does not cover.