Metadata-Version: 2.5
Name: syft-enclave
Version: 0.1.0
Summary: TEE attestation server for syft
Author-email: OpenMined <info@openmined.org>
License: Apache-2.0
Requires-Python: >=3.10
Requires-Dist: google-auth[pyjwt]>=2.22.0
Requires-Dist: pydantic-settings>=2.11.0
Requires-Dist: requests>=2.32.0
Requires-Dist: syft-rds>=0.6.1
Requires-Dist: syft>=0.10.0
Description-Content-Type: text/markdown

# syft-enclave

Enclave support for syft, enabling secure computation in Trusted Execution Environments (TEEs).

## About

- [Collaboration Flow](./docs/flow.md)
- [Security Overview](./docs/security.md)
- [Enclave Architecture](./docs/enclave_architecture.md)
- [API](./docs/api.md)
- [Terraform Deployment](./docs/terraform.md)

## Prerequisites

- Docker with buildx support (Docker Desktop includes this)
- `gcloud` [CLI installed](https://docs.cloud.google.com/sdk/docs/install-sdk)
- A GCP project with billing enabled
- [`just`](https://github.com/casey/just) and `jq`

All commands are defined in the [`Justfile`](./Justfile). Run them from this directory.

Prefer declarative deploys? The same stack can be managed with Terraform — see [Terraform Deployment](./docs/terraform.md) (`just tf-apply` / `just tf-apply-dev`).

## One-time setup

```bash
just init YOUR_GCLOUD_PROJECT_ID TOKEN_PATH DATA_OWNERS
```

- `TOKEN_PATH` — credentials of the enclave email downloaded from the gcloud console.
- `DATA_OWNERS` — comma-separated emails of the data owners whose approval gates every job on this enclave, e.g. `do1@openmined.org,do2@openmined.org`.

This stores settings (including `data_owners`) in `~/.syft-enclaves/settings.json` and sets the active gcloud project. Every other recipe reads `project_id`, `zone`, and `data_owners` from this file — zone is **not** a per-call arg. To deploy in a different zone or change the data owners, re-run `just init YOUR_PROJECT_ID TOKEN_PATH DATA_OWNERS europe-west4-a`.

### Approval model

The data owners configured at `init` are fixed for the enclave: a job runs only after **all** of them approve it, regardless of which datasets the submission references. The emails are passed to the VM as `SYFT_ENCLAVE_DATA_OWNERS` at deploy time and held in memory by the running enclave. To change the approving data owners, re-run `just init` and redeploy.

## Production deployment

Hardened image — no SSH access, TEE enforcement enabled.

```bash
just start EMAIL                          # defaults: syft-enclave-vm, n2d-standard-2
just start EMAIL my-vm n2d-standard-4     # override name / machine type
just stop [name]                          # Teardown: Deletes the VM (default: syft-enclave-vm)
```

The first run also provisions APIs and IAM roles (idempotent). No inbound port is opened on the enclave — attestation is published through the peer flow, and all other traffic is outbound.

## Debug deployment

Debug image — SSH enabled, container logs redirected to serial output.

```bash
just start-debug EMAIL                          # defaults: syft-enclave-vm, n2d-standard-2
just start-debug EMAIL my-vm n2d-standard-4     # override name / machine type
just stop [name]                                # Teardown: Deletes the VM.
```

Debug enclaves run with encryption off — data owner clients must match: `login_do(encryption=False)`.

## GPU deployments

Prefix any deploy with `hardware=gpu` to switch from the CPU default to `a3-highgpu-1g` (1× H100 80GB, Intel TDX):

```bash
just hardware=gpu start EMAIL           # production
just hardware=gpu start-debug EMAIL     # debug
```

GPU enclaves use flex-start provisioning: the create call may wait for H100 capacity (up to 2h), then the VM runs `gpu_run_duration_seconds` (default 2 days). Details: [docs/terraform.md — GPU deployments](docs/terraform.md#gpu-deployments).

## Inspect a running VM

All inspect commands take an optional `name` (default: `syft-enclave-vm`). Zone is always read from `settings.json`.

```bash
# Works on both production and debug
just status [name]   # RUNNING / TERMINATED / etc.
just get-ip [name]   # external IP

# Debug only
just attest [name]   # fetch TEE attestation report via SSH (no inbound port is open;
                     # production publishes attestation through the peer flow instead)
just ssh    [name]   # SSH into the VM (production image disables SSH)
just logs   [name]   # last 50 lines of serial output (production only shows boot logs;
                     # debug redirects container logs to serial output)
```
