enigma-rs

A lightweight secret server built with Rust and Axum. 🦀⚡

It is designed for Kubernetes External Secrets (ESO) and homelabs: small, self-hosted setups that want a straightforward way to store encrypted secrets and sync them into workloads.

Why this exists 🎯

• Lightweight alternative to larger secret platforms.
• Built for ESO webhook flows in Kubernetes. ☸️
• Practical for homelabs and small teams. 🏠

Project status and warranty ⚠️

• Built with Codex. 🤖
• No warranty. Use at your own risk.
• Main functionality is working, but this project is still considered alpha and the code may undergo major refactoring.
• Code quality and security will be improved over time.
• Security experts are welcome: reviews, threat-model feedback, and hardening PRs are encouraged. 🔐

What you get ✨

• Rust + Axum HTTP service. 🦀
• Postgres storage. 🐘
• Secrets encrypted at rest (envelope encryption, KEK/DEK model). 🔒
• Session-based web UI for users/admin flows. 🖥️
• Minimal JavaScript footprint.
• Planned Datastar integration for a reactive UI.
• API key support, including eso:read scope for ESO. 🔑
• Health endpoints: /healthz, /readyz. ❤️

Quickstart 🚀

Prerequisites

• Rust (stable)
• Postgres (14+ recommended)
• openssl (for key generation)

1) Start Postgres 🐘

./scripts/postgres.sh up

Stop it with:

./scripts/postgres.sh down

2) Configure environment ⚙️

export DATABASE_URL="postgres://postgres:postgres@localhost:5432/enigma"
export KEK_CURRENT_ID="dev"
export KEK_CURRENT_B64="$(openssl rand -base64 32)"
export ADMIN_EMAIL="admin@example.com"

Optional:

export HTTP_BIND="0.0.0.0:8080"
export LOG_LEVEL="info"
export ENVIRONMENTS="dev,staging,prod"

3) Run the server ▶️

cargo run

On startup it runs migrations and (if needed) bootstraps an admin account.

4) Sign in 🔐

Open:

• http://localhost:8080/ui/login

If admin bootstrap runs, a temporary password is printed in logs.

KEK rotation (important) 🔁

• New writes always use KEK_CURRENT_ID + KEK_CURRENT_B64.
• Existing secrets can only be decrypted if their original KEK is still available.
• Keep old KEKs during rotation, for example with KEK_OLD_KEYS_B64='[{\"id\":\"k1\",\"b64\":\"...\"}]'.
• You can also use per-key vars like KEK_OLD_k1_B64=\"...\".

Kubernetes External Secrets (ESO) ☸️

This project exposes an ESO webhook-compatible fetch endpoint:

• GET /api/v1/eso/fetch?ref=<project>/<env>/<path>/<key>
• POST /api/v1/eso/fetch with body { "ref": "<project>/<env>/<path>/<key>" }

Expected ref format:

<project>/<env>/<path>/<key>

Example:

acme/prod/apps/payment/DATABASE_URL

Use an API key with eso:read scope for webhook authentication.

Read next 📚

• ESO integration guide

Development shortcuts 🛠️

Use just targets:

• just postgres-up
• just postgres-down
• just run-dev

E2E tests (Playwright) 🧪

Playwright end-to-end tests live in e2e/ and cover key UI/auth flows, including:

• Login, logout, onboarding, and access control/error handling.
• Project navigation and project switching.
• Admin workflows (create user/project, assign members).
• Members management (add, role update, remove).
• Secrets and secret versions (list, create, update, delete, detail views).
• API key management (list, create, revoke).

How to run:

cd e2e
npm install
npx playwright install --with-deps
npm test

Optional modes:

• npm run test:headed
• npm run test:debug

Notes:

• The harness starts Postgres via Testcontainers and starts the Rust server automatically.
• Docker must be running for Testcontainers.

Contributing 🤝

Contributions are welcome, especially around:

• Security hardening 🔐
• Code cleanup/refactoring 🧹
• Kubernetes + ESO production guidance ☸️
• Documentation quality ✍️