Refactor: replace enclave framework with Nix runtime toolchain

[chris-ricketts]

Summary

Refocus this repository from a full application framework into a reusable Nix toolchain and Go runtime for AWS Nitro Enclaves. Downstream applications now package their own executable and consume the exported flake API directly.

What changed

• Add public Nix functions for building measured EIFs, production AMIs, QEMU test hosts, and OpenTofu deployment stacks.
• Add a downstream application flake template.
• Move host lifecycle management into shared NixOS services used by both production Nitro hosts and QEMU test hosts.
• Generate a blue/green OpenTofu stack with a stable EIP, PCR0-specific AMIs, Object-Locked migration intents, SSM configuration, and least-privilege IAM.
• Retain the attestation-verifying Go client and replace the framework CLI with a focused enclave curl command.
• Rename Go modules from github.com/ArkLabsHQ/introspector-enclave to github.com/ArkLabsHQ/enclave.
• Fix ACME configuration through SSM, default-SNI handling, and encrypted cache key layout.
• Replace the Docker-based integration harness with NixOS tests that boot real measured EIFs under QEMU.
• Rewrite the documentation around the new architecture, deployment model, migration runbook, and security boundaries.

Why remove the K/V store?

This removes roughly 5,600 lines, including tests, implementing the Redis-compatible K/V store, RESP server, and rollback anchoring.

We do not yet know whether downstream Arkade applications need this functionality. Keeping it in the core runtime would require every change to be maintained, reviewed, and security-audited despite having no confirmed consumer.

If downstream demand emerges, the storage engine can be extracted into a separate library. The runtime would export a DEK to the application, and the library would consume it alongside standard AWS configuration and storage resource names. Preserving rollback protection would additionally require an Object-Locked S3 anchor bucket.

End-to-end coverage

The NixOS test exercises:

• EIF measurement and production AMI construction
• OpenTofu validation and blue/green plan invariants
• Genesis state and static-secret creation
• Attestation-verified application requests
• Blue-to-green migration and state adoption
• Stable EIP cutover and blue retirement
• Pebble ACME issuance and encrypted S3 certificate caching
• Green restart and certificate cache reuse

Breaking changes

• The previous application scaffolding, deployment CLI, host supervisor, runner, and release workflows are removed.
• The built-in Redis-compatible, rollback-resistant K/V store is removed. It can be restored as a separate library if downstream demand materializes.
• The CLI now exposes only attestation-verified enclave curl.
• The Go module path changes to github.com/ArkLabsHQ/enclave.
• Applications must consume the Nix flake directly.
• BusyBox is no longer included in EIFs by default; applications requiring shell utilities must pass them through extraPackages.

Validation

CI now runs:

• nix develop --command make test
• nix develop --command make lint
• nix build .#checks.x86_64-linux.e2e --print-build-logs

The full e2e check requires x86_64 or aarch64 Linux, nested KVM, and the nixos-test system feature.

Note: aarch64 target has not been tested.

Minimal downstream consumer flake.nix

A downstream application only needs to package its executable and pass it to buildEif:

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    enclave.url = "github:ArkLabsHQ/enclave";
  };

  outputs =
    { nixpkgs, enclave, ... }:
    let
      system = "x86_64-linux";
      pkgs = import nixpkgs { inherit system; };

      app = pkgs.buildGoModule {
        pname = "myapp";
        version = "0.1.0";
        src = ./.;
        subPackages = [ "cmd/myapp" ];
        vendorHash = null;
        env.CGO_ENABLED = "0";
      };
    in
    {
      packages.${system}.default = enclave.lib.buildEif {
        inherit pkgs app;
        env = {
          ENCLAVE_DEPLOYMENT = "prod";
          ENCLAVE_APP_NAME = "myapp";
          ENCLAVE_AWS_REGION = "us-east-1";
          ENCLAVE_PREVIOUS_PCR0 = "genesis";
          ENCLAVE_MIGRATION_INTENT_RETENTION = "87600h";
        };
      };
    };
}

buildEif is the smallest integration point. Downstream flakes can also use lib.mkEnclaveAmi to build a Nitro-capable NixOS AMI and lib.mkEnclaveTofu to generate the blue/green AWS deployment definitions. lib.mkEnclaveQemuAmi provides the equivalent QEMU host for NixOS tests.

[arkana-ai-bot]

This PR has been open for 4 days without a review. @chris-ricketts is anyone looking at this?

[arkana-ai-bot]

Review — Refactor: replace enclave framework with Nix runtime toolchain

⚠️ This is a large, security-critical architectural change. Human review is mandatory before merge.

This PR refactors the entire enclave repository from a full application framework into a reusable Nix toolchain + Go runtime for AWS Nitro Enclaves. The scope is very large (removes ~5,600 lines, rewrites deployment model, renames Go module).

Key concerns to verify on human review

1. Go module rename ( → ) — any downstream consumers importing the old module path will silently stop getting updates. Verify all consumers are updated or have been notified.

2. K/V store removal — The PR removes the Redis-compatible K/V store. The justification ("no confirmed consumer") should be verified: check whether any deployed enclave applications currently rely on it before merge.

3. PCR pinning correctness — The NixOS e2e test exercises PCR0-specific AMI builds and blue/green migration. Verify the PCR0 measurement is deterministic in CI and matches what a production build would produce.

4. ACME/TLS changes — Default-SNI handling and encrypted cache key layout changed. Verify certificate issuance and renewal still work against production Let's Encrypt.

5. Attestation verification — The retained Go client does attestation-verified requests. Verify it still checks PCRs 0/1/2 correctly and that the nonce freshness mechanism is unchanged.

6. Static secret migration — Existing enclaves hold secrets in the old layout. The migration runbook in the PR description needs careful review — secret loss during migration would be catastrophic.

This PR is open since 2026-07-31 with no review. Given the scope, it urgently needs a dedicated security review.

[arkana-ai-bot]

Review — Refactor: replace enclave framework with Nix runtime toolchain

This is a large, security-critical architectural change. Human review is mandatory before merge.

This PR refactors the entire enclave repository from a full application framework into a reusable Nix toolchain + Go runtime for AWS Nitro Enclaves. The scope is very large (~5,600 lines removed, deployment model rewritten, Go module renamed).

Key concerns to verify on human review

1. Go module rename — Any downstream consumers importing the old module path will silently stop getting updates. Verify all consumers are updated or notified.

2. K/V store removal — The PR removes the Redis-compatible K/V store. Verify no deployed enclave application currently relies on it before merge.

3. PCR pinning correctness — The NixOS e2e test exercises PCR0-specific AMI builds and blue/green migration. Verify the PCR0 measurement is deterministic in CI and matches production builds.

4. ACME/TLS changes — Default-SNI handling and encrypted cache key layout changed. Verify certificate issuance and renewal still work against production Let's Encrypt.

5. Attestation verification — Verify the retained Go client still checks PCRs 0/1/2 correctly and that the nonce freshness mechanism is unchanged.

6. Static secret migration — Existing enclaves hold secrets in the old layout. The migration runbook needs careful review — secret loss during migration would be catastrophic.

This PR is open since 2026-07-31 with no review. Given the scope, it urgently needs a dedicated security review.

[arkana-ai-bot]

This PR has been open for 6+ days without review. @chris-ricketts this is a large architectural change to security infrastructure — is anyone looking at this?

[arkana-ai-bot]

This PR has been open for 11 days without a review decision. @chris-ricketts is anyone looking at this?

[arkana-ai-bot]

This PR has been open for 14+ days without review. @chris-ricketts is anyone looking at this?

[arkana-ai-bot]

This PR has been open for 14+ days without review. @chris-ricketts is anyone looking at this?