KeeperHub / KeeperHub/keeperhub
Enclave execution node: run a node's code inside an attested enclave
- Dominant language
- TypeScript
- Stars
- 24
- Forks
- 93
- Avg merge
- 1d 4h
- Merged PRs (30d)
- 253
Description
## Reason: what the current isolation does and does not give
User JavaScript from the Code node already runs outside the application process, in a standalone service (`sandbox/`), hardened at the image and pod level rather than at the language level:
- `gcr.io/distroless/nodejs24-debian12`, pinned by digest. No shell, no package manager, no compiler; the only spawnable executable in the image is the node binary.
- Zero runtime npm dependencies.
- `runAsNonRoot: true` (uid/gid 1001), `seccompProfile: RuntimeDefault`, `allowPrivilegeEscalation: false`, `readOnlyRootFilesystem: true`, `capabilities.drop: [ALL]` (`deploy/keeperhub-sandbox/prod/values.yaml:58-70`).
- `automountServiceAccountToken: false` on a dedicated ServiceAccount with no RoleBindings and deliberately no `eks.amazonaws.com/role-arn` annotation, so the pod has no federated AWS identity at all (`deploy/keeperhub-sandbox/prod/sa.yaml`), plus a memory-backed 64Mi `/tmp` (`prod/pod-hardening-patch.yaml`, applied by `kubectl patch` after `helm upgrade`).
- Ingress restricted to port 8787; egress denied except DNS and TCP 443 to `0.0.0.0/0` with private ranges excluded (`deploy/keeperhub-sandbox/prod/networkpolicy.yaml`).
- Scheduled onto a dedicated `node-role.keeperhub.io/sandbox-only` NodePool via nodeSelector and toleration, so sandbox workloads do not share nodes with the rest of the stack.
The design assumes a `node:vm` escape is possible and makes the landing zone empty. That is a sound posture, and it does not provide two things:
1. **Attestation.** Nothing lets a user verify which code processed their data. They are taking our word for the paragraph above.
2. **Excluding the operator from the trust boundary.** Anyone with sufficient cluster access is inside it.
An enclave turns the second into a cryptographic claim rather than an operational promise, and produces an artifact for the first.
## Scope: a node, not the whole workflow
This is a **new execution node** whose code runs inside an AWS Nitro Enclave, with access to the KeeperHub SDK. It is not the whole workflow moved inside an enclave.
That distinction is the point of the scoping, and it is worth being explicit about why. A Nitro Enclave has no network, no persistent storage and no interactive access; its only channel is a vsock link to the parent instance. A whole workflow is almost entirely network I/O - RPC reads, contract writes, plugin HTTP calls, database queries - so enclosing all of it means the parent proxies every one of those, and the parent is then back in the data path for exactly the traffic the enclave was meant to protect.
A single node is a much better fit. The parent can be a dumb vsock-to-TCP forwarder with TLS terminated **inside** the enclave, so the parent moves ciphertext it cannot read. That is a real boundary rather than a relabelled one, and it is achievable at node scope in a way it is not at workflow scope.
The existing sandbox is already a separately deployed service with its own hardened pod spec, which is the natural place for this to attach.
## What a solution needs to cover
- **Where the boundary sits.** Which parts run in the enclave and which in the parent, and what the parent can observe. The TLS-inside-the-enclave property above is the thing that makes the claim worth making; if a design gives it up, say so plainly rather than keeping the wording.
- **Key release.** KMS attestation-gated release keyed to the enclave's PCR measurements. Every image rebuild changes the measurement, so the release policy has to move in lockstep with the deploy pipeline or executions stop. This is the most likely operational failure mode and it should be designed for, not discovered.
- **SDK access inside the enclave.** Which parts of the KeeperHub SDK are available to code in this node, and how a call that needs the network reaches it over vsock.
- **Cost and cold start per execution**, measured against the existing sandbox path. An enclave that adds seconds per run has a narrow set of workflows it makes sense for, and that set should be named.
- **What the user sees.** An attestation document nobody surfaces is worth nothing. Is it a field on the execution record, a page, a verification endpoint someone else can check independently?
- **Failure behaviour.** What a workflow does when the enclave is unavailable or attestation fails. Falling back to the ordinary sandbox silently would void the entire claim.
## Status and how to contribute
This needs infrastructure work by the core team - enclave-enabled instances, the KMS policy, and the deploy-pipeline change for PCR management are not things an outside contributor can land alone. Coordinate on this issue before writing code.
A written design answering the first three points above, with measured numbers for the fourth, is a complete and welcome contribution on its own.
---
Tracking: [KEEP-1319](https://linear.app/keeperhubapp/issue/KEEP-1319) (internal tracker, not publicly accessible)
Contributor guide
Research direction
Start by reading the existing sandbox/ deployment configuration in deploy/keeperhub-sandbox/prod/values.yaml, sa.yaml, pod-hardening-patch.yaml, and networkpolicy.yaml. Produce a written design covering the enclave/parent boundary, KMS PCR-gated key release, and SDK access, with measured cold-start and per-execution costs; document the relevant user-visible attestation and failure behavior.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- aws, javascript, kubernetes, node.js, typescript
- Domain
- backend, infrastructure, security
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100