[PR #123] [MERGED] feat: add single-tenant API key authentication #194

New issue

Closed

opened 2026-10-29 14:20:53 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-29 14:20:53 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/kvcache-ai/AgentENV/pull/123
Author: @yingdi-shan
Created: 8/4/2026
Status: ✅ Merged
Merged: 8/19/2026
Merged by: @yingdi-shan

Base: main ← Head: feat/single-tenant-auth

📝 Commits (7)

4fee387 feat: add single-tenant API key authentication
b28eba1 docs: document API key setup in README
bc0ad47 fix: derive sandbox access tokens from shared seed
326ebfb refactor: simplify shared authentication secrets
131e0dc fix: harden managed secret loading
52a66c7 fix: enforce authentication boundaries
c9f4d91 fix: preserve sandbox metrics auth

📊 Changes

66 files changed (+2397 additions, -811 deletions)

View changed files

📝 Cargo.lock (+1 -1)
📝 Cargo.toml (+1 -0)
📝 README.md (+18 -5)
📝 config/default.toml (+1 -1)
📝 crates/aenv/src/client/files.rs (+3 -18)
📝 crates/aenv/src/client/mod.rs (+1 -1)
📝 crates/aenv/src/grpc/mod.rs (+5 -17)
📝 deploy/docker-compose.yml (+8 -2)
📝 deploy/k8s/base/agentenv-daemonset.yaml (+6 -1)
📝 deploy/k8s/base/gateway-deployment.yaml (+5 -0)
📝 deploy/k8s/base/kustomization.yaml (+5 -0)
📝 deploy/k8s/run.sh (+163 -10)
📝 docs/src/SUMMARY.md (+1 -0)
📝 docs/src/concepts/proxy.md (+17 -0)
📝 docs/src/concepts/sandboxes.md (+1 -1)
📝 docs/src/configuration/env-vars.md (+7 -8)
📝 docs/src/configuration/reference.md (+3 -3)
📝 docs/src/deployment/docker-compose.md (+37 -9)
📝 docs/src/deployment/docker.md (+12 -0)
📝 docs/src/deployment/kubernetes.md (+18 -3)

...and 46 more files

📄 Description

Summary

Require one shared single-tenant API key on runtime nodes and the gateway.
Resolve the runtime API key during normal Rust server startup: AENV_API_KEY, then /run/secrets/api-key, then an atomically generated $AENV_HOME/secrets/api-key.
Derive E2B-compatible per-sandbox credentials from the existing runtime seed:
- envdAccessToken = hex(HMAC-SHA256(seed, sandboxID))
- trafficAccessToken = hex(HMAC-SHA256(seed, "sandbox-traffic-" + sandboxID))
Keep sandbox-token derivation and validation on runtime nodes. The gateway only checks that one sandbox credential is present before routing; the owning runtime performs the authoritative scoped validation.

Credential boundaries

X-API-Key: deployment control-plane credential shared by the gateway and runtime nodes.
e2b-traffic-access-token: sandbox-scoped application proxy credential.
X-Access-Token: secure envd credential, accepted only for the matching sandbox envd port.

The API key is independent from both sandbox credentials. Rotating an API key does not rotate sandbox tokens; rotating the runtime seed rotates both per-sandbox credentials.

Proxy routing strips AgentENV credentials before forwarding application requests and preserves application Authorization.

Deployment behavior

Native and standalone Docker starts generate and reuse managed API-key and sandbox-seed files during normal server startup.
Docker Compose shares the runtime secrets directory between nodes and mounts it read-only on the gateway, which reads only the API key.
Kubernetes stores the API key in Secret/agentenv-auth. The existing optional agentenv-runtime-secrets/sandbox-access-token-hash-seed contract is unchanged, avoiding seed migration during upgrades.
Static multi-node deployments provide the API key to the gateway and all runtime nodes, and provide the sandbox seed only to runtime nodes.

Out of scope

External TLS termination is intentionally excluded and will be implemented separately.
/metrics authentication is not supported
https is not supported

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/kvcache-ai/AgentENV/pull/123 **Author:** [@yingdi-shan](https://github.com/yingdi-shan) **Created:** 8/4/2026 **Status:** ✅ Merged **Merged:** 8/19/2026 **Merged by:** [@yingdi-shan](https://github.com/yingdi-shan) **Base:** `main` ← **Head:** `feat/single-tenant-auth` --- ### 📝 Commits (7) - [`4fee387`](https://github.com/kvcache-ai/AgentENV/commit/4fee3879d7533cefbf3890145f844a6171b36bfb) feat: add single-tenant API key authentication - [`b28eba1`](https://github.com/kvcache-ai/AgentENV/commit/b28eba163cfdfb6af3b41dbc811ec3ec2ba74ecd) docs: document API key setup in README - [`bc0ad47`](https://github.com/kvcache-ai/AgentENV/commit/bc0ad47a6e6be641e05350c60fba01b30489255a) fix: derive sandbox access tokens from shared seed - [`326ebfb`](https://github.com/kvcache-ai/AgentENV/commit/326ebfb83a817f0abe202c1a205efa06886e2056) refactor: simplify shared authentication secrets - [`131e0dc`](https://github.com/kvcache-ai/AgentENV/commit/131e0dc53247b2d8825e96ef057acb6e00422a12) fix: harden managed secret loading - [`52a66c7`](https://github.com/kvcache-ai/AgentENV/commit/52a66c71d476d59c8ff995dc8add241a00e12469) fix: enforce authentication boundaries - [`c9f4d91`](https://github.com/kvcache-ai/AgentENV/commit/c9f4d9120484ae6ab3e0ebe9894c690232f0380e) fix: preserve sandbox metrics auth ### 📊 Changes **66 files changed** (+2397 additions, -811 deletions) <details> <summary>View changed files</summary> 📝 `Cargo.lock` (+1 -1) 📝 `Cargo.toml` (+1 -0) 📝 `README.md` (+18 -5) 📝 `config/default.toml` (+1 -1) 📝 `crates/aenv/src/client/files.rs` (+3 -18) 📝 `crates/aenv/src/client/mod.rs` (+1 -1) 📝 `crates/aenv/src/grpc/mod.rs` (+5 -17) 📝 `deploy/docker-compose.yml` (+8 -2) 📝 `deploy/k8s/base/agentenv-daemonset.yaml` (+6 -1) 📝 `deploy/k8s/base/gateway-deployment.yaml` (+5 -0) 📝 `deploy/k8s/base/kustomization.yaml` (+5 -0) 📝 `deploy/k8s/run.sh` (+163 -10) 📝 `docs/src/SUMMARY.md` (+1 -0) 📝 `docs/src/concepts/proxy.md` (+17 -0) 📝 `docs/src/concepts/sandboxes.md` (+1 -1) 📝 `docs/src/configuration/env-vars.md` (+7 -8) 📝 `docs/src/configuration/reference.md` (+3 -3) 📝 `docs/src/deployment/docker-compose.md` (+37 -9) 📝 `docs/src/deployment/docker.md` (+12 -0) 📝 `docs/src/deployment/kubernetes.md` (+18 -3) _...and 46 more files_ </details> ### 📄 Description ## Summary - Require one shared single-tenant API key on runtime nodes and the gateway. - Resolve the runtime API key during normal Rust server startup: `AENV_API_KEY`, then `/run/secrets/api-key`, then an atomically generated `$AENV_HOME/secrets/api-key`. - Derive E2B-compatible per-sandbox credentials from the existing runtime seed: - `envdAccessToken = hex(HMAC-SHA256(seed, sandboxID))` - `trafficAccessToken = hex(HMAC-SHA256(seed, "sandbox-traffic-" + sandboxID))` - Keep sandbox-token derivation and validation on runtime nodes. The gateway only checks that one sandbox credential is present before routing; the owning runtime performs the authoritative scoped validation. ## Credential boundaries - `X-API-Key`: deployment control-plane credential shared by the gateway and runtime nodes. - `e2b-traffic-access-token`: sandbox-scoped application proxy credential. - `X-Access-Token`: secure envd credential, accepted only for the matching sandbox envd port. The API key is independent from both sandbox credentials. Rotating an API key does not rotate sandbox tokens; rotating the runtime seed rotates both per-sandbox credentials. Proxy routing strips AgentENV credentials before forwarding application requests and preserves application `Authorization`. ## Deployment behavior - Native and standalone Docker starts generate and reuse managed API-key and sandbox-seed files during normal server startup. - Docker Compose shares the runtime secrets directory between nodes and mounts it read-only on the gateway, which reads only the API key. - Kubernetes stores the API key in `Secret/agentenv-auth`. The existing optional `agentenv-runtime-secrets/sandbox-access-token-hash-seed` contract is unchanged, avoiding seed migration during upgrades. - Static multi-node deployments provide the API key to the gateway and all runtime nodes, and provide the sandbox seed only to runtime nodes. ## Out of scope - External TLS termination is intentionally excluded and will be implemented separately. - /metrics authentication is not supported - https is not supported --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-29 14:20:53 +00:00