diff --git a/README.md b/README.md index 02e0a02..3580a2f 100644 --- a/README.md +++ b/README.md @@ -1,146 +1,118 @@ -# Nexus Local Proxy for DAppNode +# Nexus Proxy -This DAppNode package runs one shared Nexus proxy for OpenAI-compatible -applications installed on the same DAppNode. The proxy verifies fresh AWS -Nitro attestation against measurements it takes from signed Gateway releases, -and encrypts chat request and response bodies with EHBP before they cross -Cloudflare. +Encrypts your Nexus prompts so only the **TEE** — the trusted execution +environment Nexus runs inside — can read them. Not us, not Dappnode, nobody in +between. It verifies the TEE automatically on every connection. -## Client configuration - -Configure DAppNode applications with: +## Use it ```text Base URL: http://nexus-proxy.dappnode.private:3301/v1 -API key: the application's normal Nexus API key -API: OpenAI Chat Completions +API key: your normal Nexus API key ``` -The API key remains in the normal `Authorization: Bearer ...` header. The -proxy does not store it and does not automatically retry inference requests. +Same key, same models, same prices. Some Dappnode apps have a **private mode** +switch that does this for you — Hermes Agent is one. -Applications may declare the package dependency once. They then follow Gateway -releases automatically, without either the application or this package being -republished: +For the whole path, pick a model whose id starts with **`private/`**. Those run +inside a TEE too, so your prompt stays encrypted from this proxy to Nexus and +from Nexus to the model. -```json -{ - "dependencies": { - "nexus-proxy.dnp.dappnode.eth": "^0.1.0" - } -} +## Check it yourself + +```text +http://nexus-proxy.dappnode.private:3301/verification ``` -`POST /v1/chat/completions` and `GET /v1/models` are OpenAI-compatible, so an -application that lists models against its configured base URL works without a -second endpoint. `GET /healthz` reports whether the local proxy is ready. +What was checked, right now, plus the raw proof to verify with independent +tooling. It never shows your prompts. -The model catalog is the one route here that is **not** confidential. It is -public, unauthenticated, cacheable data with no prompt, completion or -credential in it, so the proxy passes it through over ordinary TLS rather than -over EHBP, and does not forward the caller's `Authorization` header. These -requests are not counted on the verification page, because nothing about them -crossed the attested channel. Add `--model-catalog=false` to the service -command to remove the route. +## Good to know -## Privacy verification page +- Auto Router (`nexus/auto`) and PII masking do not work through the proxy. + Pick a specific model. +- If the TEE cannot be verified, requests stop. That is deliberate. +- Keep port 3301 on the internal network. -The package serves a page showing whether the Gateway is currently verified and -what was checked: +--- -```text -http://nexus-proxy.dappnode.private:3301/verification -``` +# Reference -It reports the verdict in plain language, lists the checks the proxy performed -before it would encrypt anything, shows the enclave measurements and attested -key, and lists recent requests with the attested key each one was encrypted to. -From there the raw COSE_Sign1 attestation document and its signed manifest can -be downloaded and re-checked with an independent AWS Nitro verifier. - -The page shows no prompt or completion content. The ledger behind it records -only verification evidence and per request identifiers, timing and sizes. That -history is written to the `verification_state` volume at -`/var/lib/nexus-proxy/verification.json`, so it survives a restart and is -included in package backups. The on-disk format cannot express a prompt or a -completion. Because the page is served on the proxy port, anything on the -DAppNode internal network can read this metadata. Add `--verification-ui=false` -to the service command to remove the page and its API, or drop `--state-file` -from the service command to keep history in memory only. - -## Security boundary - -Callers trust the DAppNode host, this package, and the DAppNode internal -network. The caller-to-proxy hop is ordinary HTTP and is outside EHBP. From -this local proxy to the measured Nexus Gateway process inside AWS Nitro -Enclaves, prompt and completion bodies are encrypted and integrity-protected. - -EHBP does not hide the HTTP method, path, headers, body length, frame sizes, -timing, or bearer API key. This package does not extend the claim to a -downstream inference provider. Do not publish container port 3301 to the host -or Internet. +## Scope -## Trust policy +Encrypted: prompt and reply bodies, from this proxy to the verified Gateway +inside the TEE. + +With a **`private/`** model, that continues past Nexus: the Gateway reaches +those models over an attested, encrypted transport that fails closed, so the +prompt is protected end to end. -This package no longer ships enclave measurements. The proxy derives them from -the most recent Gateway releases, each signed during the Gateway release -workflow with a Sigstore certificate issued to that workflow's GitHub identity. -Only a signature from that exact identity is accepted, so the download is not -trusted: GitHub is a CDN here, and a swapped or edited release is rejected -rather than believed. +Outside that: the hop from your app to this proxy (ordinary HTTP on the +Dappnode internal network) and request metadata — method, path, headers, sizes, +timing and your bearer key. -This is why the package no longer has to be republished for every Gateway -release, and why an installed proxy can no longer be left stranded on -measurements that predate the deployed enclave. +## Endpoints -What the proxy checks has not changed. The measurements are still compared -against the enclave's live attestation exactly as before, and the -body-encryption contract is compiled into the SDK: a signed release may say -which build to trust, never what protection that build owes the caller. +| Route | Encrypted | Notes | +|---|---|---| +| `POST /v1/chat/completions` | yes | Streaming supported | +| `GET /v1/models` | no | Public catalog | +| `GET /healthz` | n/a | Readiness | +| `GET /verification` | n/a | The page above | -A newly deployed Gateway is picked up on first contact rather than on a timer. -A release the current policy has never heard of is precisely what a new -deployment looks like, so the proxy re-derives its policy and verifies again -within the same request. Nothing needs to be pushed to the node, which matters -because DAppNodes sit behind NAT. An hourly background refresh is a backstop on -top of that. +The catalog is public, unauthenticated data with no prompt or credential in it, +so it goes over ordinary TLS and the `Authorization` header is not forwarded. +Those requests are not counted on the verification page. `--model-catalog=false` +removes the route. -It stays fail-closed. If neither the network nor the cache produces a verified -policy, the proxy refuses to start rather than falling back to something older. +## Verification history -`--trust-policy-cache` keeps the signed material from the last successful fetch -on the `verification_state` volume, so a node that restarts without a network -rebuilds the same policy. Every signature is re-verified on load. +No prompt or reply content, ever — only verification evidence and per-request +identifiers, timing and sizes. The on-disk format cannot express a prompt. -This package pins: +Stored on the `verification_state` volume at +`/var/lib/nexus-proxy/verification.json`, so it survives restarts and is in +package backups. Anything on the Dappnode internal network can read it. +`--verification-ui=false` removes the page and its API; dropping `--state-file` +keeps history in memory only. -- SDK commit, as `UPSTREAM_VERSION` in `docker-compose.yml` and - `dappnode_package.json`. -- Gateway origin `https://nexus-api-tee.dappnode.com`. -- The Gateway release-workflow signing identity, compiled into the SDK. +## Trust policy -### Network requirement +Measurements are derived from the most recent Gateway releases, each signed +during the Gateway release workflow with a Sigstore certificate issued to that +workflow's GitHub identity. Only that exact identity is accepted, so the +download is not trusted — GitHub is a CDN here, and a swapped release is +rejected. -The proxy needs outbound HTTPS to `api.github.com` and -`objects.githubusercontent.com` at startup, on meeting an unknown Gateway -release, and hourly. A node that cannot reach them starts only if its cache -already holds a verified policy. +A new Gateway is picked up **on first contact**, not on a timer: a release the +policy has never seen is what a new deployment looks like, so the proxy +re-derives and verifies within the same request. Nothing needs pushing to the +node, which matters behind NAT. An hourly refresh is a backstop. -## Build +Fail-closed: if neither the network nor the cache produces a verified policy, +the proxy refuses to start. `--trust-policy-cache` keeps the signed material on +the `verification_state` volume and every signature is re-verified on load. -```sh -NEXUS_SDK_TOKEN="$(gh auth token)" docker compose build +Pinned here: the SDK commit (`UPSTREAM_VERSION`), the Gateway origin +`https://nexus-api-tee.dappnode.com`, and the release-workflow signing identity +(compiled into the SDK). + +Needs outbound HTTPS to `api.github.com` and `objects.githubusercontent.com` at +startup, on meeting an unknown release, and hourly. Without them it starts only +if the cache already holds a verified policy. + +## Dependency + +```json +{ "dependencies": { "nexus-proxy.dnp.dappnode.eth": "^0.1.0" } } ``` -The image builds the SDK from a full Git commit, verifies the checked-out -revision matches, and runs as an unprivileged user in a minimal runtime image. +## Build -`NEXUS_SDK_TOKEN` must hold a token with read access to the private -`dappnode-nexus-sdk` repository. `docker-compose.yml` passes it to the build as -a BuildKit secret, so it never reaches an image layer. In CI it comes from the -`NEXUS_SDK_TOKEN` repository secret; the default `GITHUB_TOKEN` cannot be used -because it is scoped to this repository only. +```sh +docker compose build +``` -Remove the secret, the `secrets:` blocks in `docker-compose.yml`, and this -section once the SDK repository is public: the Dockerfile already falls back to -an unauthenticated fetch when no secret is supplied. +Builds the SDK from a pinned commit, verifies the checked-out revision, and +runs unprivileged in a minimal image. `dappnode-nexus-sdk` is public, so no +credentials are needed. diff --git a/dappnode_package.json b/dappnode_package.json index 69fa320..14bb879 100644 --- a/dappnode_package.json +++ b/dappnode_package.json @@ -4,8 +4,8 @@ "upstreamVersion": "219977388b9f26435c2529fc1cd52ff7229e5397", "upstreamRepo": "dappnode/dappnode-nexus-sdk", "upstreamArg": "UPSTREAM_VERSION", - "shortDescription": "Attested private AI proxy for DAppNode applications", - "description": "A shared OpenAI-compatible Nexus proxy for applications on the same DAppNode. It verifies the measured Nexus Gateway inside AWS Nitro Enclaves and encrypts prompt and completion bodies with EHBP before they cross Cloudflare. A local verification page at /verification shows the attestation evidence behind that protection and lets you export it for independent checking. GET /v1/models passes the Gateway public model catalog through so ordinary OpenAI clients can list models against the proxy.", + "shortDescription": "Keep your Nexus prompts private, and verify it yourself", + "description": "Encrypts your Nexus prompts so only the TEE (trusted execution environment) that Nexus runs inside can read them — not us, not Dappnode, nobody in between. It verifies the TEE automatically on every connection.\n\nYou do not have to take our word for it: the verification page shows what was checked, right now, and lets you download the raw proof to verify independently. It never shows your prompts.\n\nPoint any OpenAI-compatible app on this Dappnode at http://nexus-proxy.dappnode.private:3301/v1 with your normal Nexus API key. Same key, same models, same prices. Some apps, such as Hermes Agent, have a private mode switch that does this for you.\n\nFor the whole path, pick a model whose id starts with private/ — those run inside a TEE too, so your prompt stays encrypted from the proxy to Nexus and from Nexus to the model.\n\nAuto Router (nexus/auto) and PII masking do not work through the proxy.", "type": "dncore", "backup": [ { @@ -45,6 +45,11 @@ }, "license": "MIT", "warnings": { - "onInstall": "This package protects inference bodies from the local Nexus proxy to the attested Nexus Gateway. The DAppNode host and internal package network remain trusted. Do not expose port 3301 publicly." + "onInstall": "Point your apps at http://nexus-proxy.dappnode.private:3301/v1 with your normal Nexus API key. Auto Router and PII masking do not work through the proxy. If the TEE cannot be verified, requests stop. Keep port 3301 on the internal network." + }, + "links": { + "ui": "http://nexus-proxy.dappnode.private:3301/verification", + "homepage": "https://nexus.dappnode.com", + "docs": "https://github.com/dappnode/DNP_NEXUS_PROXY#readme" } } diff --git a/getting-started.md b/getting-started.md new file mode 100644 index 0000000..111128e --- /dev/null +++ b/getting-started.md @@ -0,0 +1,40 @@ +# Nexus Proxy + +Encrypts your Nexus prompts so only the **TEE** — the trusted execution +environment Nexus runs inside — can read them. Not us, not Dappnode, nobody in +between. + +It verifies the TEE automatically on every connection. + +## Check it yourself + +**[Open the verification page](http://nexus-proxy.dappnode.private:3301/verification)** +— what was checked, right now, plus the raw proof to verify independently. It +never shows your prompts. + +## Use it + +Point any OpenAI-compatible app on this Dappnode at: + +```text +Base URL: http://nexus-proxy.dappnode.private:3301/v1 +API key: your normal Nexus API key +``` + +Same key, same models, same prices. Some apps have a **private mode** switch +that does this for you — Hermes Agent is one. + +## Get the most out of it + +Pick a model whose id starts with **`private/`**. Those run inside a TEE too, +so your prompt stays encrypted the whole way — from this proxy to Nexus, and +from Nexus to the model. + +## Good to know + +- Auto Router (`nexus/auto`) and PII masking do not work through the proxy. + Pick a specific model. +- If the TEE cannot be verified, requests stop. That is deliberate. +- Keep port 3301 on the internal network. + +[Full documentation](https://github.com/dappnode/DNP_NEXUS_PROXY#readme)