Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
198 changes: 85 additions & 113 deletions README.md
Original file line number Diff line number Diff line change
@@ -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.
11 changes: 8 additions & 3 deletions dappnode_package.json
Original file line number Diff line number Diff line change
Expand Up @@ -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": [
{
Expand Down Expand Up @@ -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"
}
}
40 changes: 40 additions & 0 deletions getting-started.md
Original file line number Diff line number Diff line change
@@ -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)
Loading