🔐 SADIE Enclave Package

Secure Contract Execution Engine
The core runtime for executing TypeScript contracts in AWS Nitro Enclaves

---

🎯 Purpose

The SADIE Enclave Package is the secure heart of the SADIE framework. It runs inside AWS Nitro Enclaves, providing a trusted execution environment where sensitive computations can be performed with cryptographic attestation guarantees.

🔒 What Makes This Secure?

• Hardware Isolation: Runs in AWS Nitro Enclaves with no persistent storage, no interactive access, and no external networking
• Cryptographic Attestation: Generates tamper-evident quotes that prove code execution authenticity
• Memory Protection: Isolated memory space that's inaccessible to the host OS or hypervisor
• Verified Boot: Enclave images are cryptographically verified before execution

---

🏗️ Architecture

sequenceDiagram
    participant Host as Host Application
    participant VSOCK as VSOCK Channel
    participant Enclave as Enclave Runtime
    participant Contract as Contract Code
    participant Nitro as Nitro Hardware

    Host->>VSOCK: Send CBOR message
    VSOCK->>Enclave: Receive contract + inputs
    Enclave->>Contract: Import & execute contract
    Contract->>Enclave: Return computation result
    Enclave->>Nitro: Request attestation quote
    Nitro->>Enclave: Generate signed quote
    Enclave->>VSOCK: Send result + quote
    VSOCK->>Host: Return CBOR response

---

📦 Package Structure

packages/enclave/
├── main.ts              # Main enclave entry point
├── main_test.ts         # Enclave tests
├── deno-nitro/          # Core Nitro integration (submodule)
├── deno.json           # Package configuration
├── Dockerfile          # Enclave container image
└── README.md           # This file

---

🚀 Usage

Message Format

The enclave communicates via CBOR-encoded messages over VSOCK:

/**
 * Incoming message format
 */
export interface Message {
  /**
   * Data URL of the contract code
   */
  contract: string;
  inputs?: unknown;
}

Contract Execution Flow

1. Receive Message: Enclave receives CBOR message with contract and inputs
2. Import Contract: Dynamically imports contract code from data URL
3. Execute Contract: Runs the contract function with provided inputs
4. Generate Attestation: Creates cryptographic quote of the execution
5. Return Result: Sends back output and attestation quote

Example Contract

// This contract runs inside the secure enclave
export default function secureComputation(inputs: {
  secretValue: string;
  multiplier: number;
}) {
  // This computation happens in isolation
  const processed = inputs.secretValue.length * inputs.multiplier;

  return {
    result: processed,
    timestamp: new Date().toISOString(),
    enclave_id: "secure-enclave-v1",
  };
}

---

🔧 Configuration

Package Configuration

{
  "name": "@sadie-project/deno-nitro-enclave",
  "exports": "./main.ts",
  "tasks": {
    "dev": "deno run --watch main.ts"
  },
  "imports": {
    "@qlever-llc/deno-nitro": "./deno-nitro/mod.ts",
    "@std/assert": "jsr:@std/assert@1",
    "cbor-x": "npm:cbor-x@^1.6.0"
  },
  "test": {
    "exclude": ["./deno-nitro/"]
  }
}

Environment Variables

Variable	Description	Default
DENO_DIR	Deno cache directory	/var/deno_dir
NODE_ENV	Runtime environment	production

---

🧪 Development & Testing

Running Tests

# Run enclave tests
deno test --allow-all packages/enclave/

# Run with watch mode
deno task dev

# Test a specific file
deno test --allow-all packages/enclave/main_test.ts

Local Development

For local development and testing, you can run the enclave code directly with Deno:

# Run enclave locally (no real attestation)
echo '{"contract":"data:application/typescript,export default (x) => x","inputs":{"test":true}}' | \
  deno run --allow-ffi --allow-env packages/enclave/main.ts

---

🐳 Docker Usage

Building the Enclave Image

# Build enclave image
docker build -t sadie-enclave packages/enclave/

# Build with specific Deno version
docker build --build-arg DENO_VERSION=2.4.5 -t sadie-enclave packages/enclave/

Running in Container

# Test the enclave in a container
echo '{"contract":"data:application/typescript,export default (x) => ({...x, processed: true})","inputs":{"data":"secret"}}' | \
  docker run -i sadie-enclave

---

🔐 Security Considerations

Contract Isolation

• Contracts run in a completely isolated environment
• No access to file system, network, or host resources
• Limited to pure computation and memory operations
• Input/output via CBOR serialization only

Attestation Process

The enclave generates cryptographic quotes that include:

• Contract Hash: SHA-256 of the executed contract code
• Input Hash: SHA-256 of the provided inputs
• Output Data: The computation results
• Hardware Signature: Nitro hardware signature proving authenticity

Best Practices

1. Keep Contracts Simple: Minimize dependencies and complexity
2. Validate Inputs: Always validate and sanitize contract inputs
3. Handle Errors Gracefully: Ensure contracts handle edge cases
4. Minimize Side Effects: Avoid operations that could leak information

---

📊 Performance

Benchmarks

Operation	Time	Memory
Contract Import	~50ms	~10MB
Simple Computation	~1ms	~1MB
CBOR Serialization	~5ms	~2MB
Attestation Generation	~100ms	~5MB

Benchmarks are approximate and depend on contract complexity and hardware.

---

🛠️ API Reference

Main Handler Function

/**
 * Main handler for incoming messages
 */
export async function handle({ contract, inputs }: Message) {
  const { default: fun } = await import(contract);
  /**
   * Result of the contract code with the provided inputs
   */
  const output = await fun(inputs);
  /**
   * Things to attest about the contract execution
   */
  const attested = {
    // TODO: Hash this in response
    contract,
    // TODO: Hash this in response
    inputs,
    output,
  };
  return {
    ...attested,
    quote: attest(attested),
  };
}

Message Processing Pipeline

The enclave processes messages through a streaming pipeline:

1. CBOR Decode: Incoming bytes → JavaScript objects
2. Contract Execution: Import and run contract code
3. Attestation: Generate cryptographic proof
4. CBOR Encode: Response objects → bytes
5. Output: Send response via VSOCK

---

🔄 Integration

With Instance Package

The enclave works seamlessly with the @sadie-project/deno-nitro-instance package:

import { DenoEnclave } from "@sadie-project/deno-nitro-instance";

// The instance package handles communication with this enclave
await using enclave = new DenoEnclave();
const result = await enclave.execute(myContract, inputs);

With AWS Nitro CLI

For production deployment:

# Build enclave image file
nitro-cli build-enclave --docker-uri sadie-enclave --output-file enclave.eif

# Run in production
nitro-cli run-enclave --eif-path enclave.eif --memory 512 --cpu-count 1

---

🐛 Troubleshooting

Common Issues

Contract Import Failures

`Error: Failed to import contract``

• Ensure contract is valid TypeScript
• Check data URL encoding
• Verify contract has default export

CBOR Serialization Errors

Error: Cannot serialize circular structure

• Remove circular references from contract outputs
• Ensure all output data is serializable

Memory Limits

Error: Insufficient memory

• Reduce contract complexity
• Increase enclave memory allocation
• Optimize data structures

Debug Mode

Enable debug logging:

# Run with debug output
DENO_LOG_LEVEL=debug deno run --allow-all packages/enclave/main.ts

---

🔗 Related Packages

• @sadie-project/deno-nitro-instance - Client library for connecting to enclaves
• @qlever-llc/deno-nitro - Low-level Nitro integration and attestation

---

Part of the SADIE Deno Nitro Framework

🏠 Back to Main README • 📖 Full Documentation