DEV Community: Clef.sh

AWS CDK + Clef: Shift secrets policy and governance left

Clef.sh — Wed, 29 Apr 2026 16:06:30 +0000

A ~10-minute, copy-paste tutorial that takes you from an empty directory to a fully working Clef setup, then deploys the production secrets to AWS Secrets Manager via the @clef-sh/cdk constructs.

By the end, you'll have:

A clef.yaml with two namespaces (database, payments) across two environments (dev, production)
All four matrix cells populated with demo secrets, encrypted with SOPS
A service identity (app) whose production envelope is protected by AWS KMS
A CloudFormation stack with three ClefSecrets, each holding a Clef-managed value in AWS Secrets Manager — readable by your app via the standard ASM SDK, with no Clef agent at runtime

Steps 1–3 work fully offline. Steps 4–5 deploy real AWS resources and require working AWS credentials.

Prerequisites

Node.js 20+
AWS account + credentials for steps 4–5 only. Standard SDK resolution applies (AWS_PROFILE, env vars, SSO, etc.). The KMS key, an unwrap Lambda, and three Secrets Manager secrets will be created in the account/region your credentials resolve to. All resources are tagged clef-quick-start so you can find and remove them.
Git — Clef is git-native, and the tutorial commits the initial state after clef init so you can see exactly what each subsequent step adds. Cloning this repo (per the setup step below) gives you a git working tree already.
Shell — commands below are written for a POSIX shell (macOS/Linux Terminal, WSL, or Git Bash on Windows). PowerShell works too; the only block that needs a different syntax is the variable derivation in step 4, where a PowerShell variant is shown alongside.

Setup

git clone https://github.com/clef-sh/quick-start.git
cd quick-start
npm install

npm install puts the clef CLI under node_modules/.bin. The tutorial uses npx clef, but you can also install it globally with npm i -g @clef-sh/cli if you'd rather drop the prefix.

Verify the install:

npx clef doctor

You should see green checks for node, sops, and git (if present).

Step 1 — Initialise Clef

Create the manifest and the encrypted matrix in one shot, using the age backend (no AWS account needed yet):

npx clef init \
  --namespaces database,payments \
  --environments dev,production \
  --backend age \
  --non-interactive

What just happened:

clef.yaml now declares your namespaces, environments, and the age recipient that owns this repo.
.clef/config.yaml records the local age private key location (stored in your OS keychain by default).
secrets/database/{dev,production}.enc.yaml and secrets/payments/{dev,production}.enc.yaml were created — each one is a valid SOPS file with no keys yet.
.clefignore and .gitattributes were written so the SOPS merge driver picks up *.enc.yaml.

Take a look:

cat clef.yaml
tree secrets

Commit the initial state. Clef is git-native and the matrix files are SOPS-encrypted, so they're safe to commit even once you start adding values:

git add clef.yaml .clef .clefignore .gitattributes secrets
git commit -m "Initialise Clef"

Step 2 — Populate the matrix

Set your first secret with an inline value:

npx clef set database/dev DB_HOST localhost

Now set one with hidden input — Clef prompts and never echoes the value to the terminal or writes it to disk:

npx clef set database/dev DB_PASSWORD
# Value: ********

Confirm it landed:

npx clef get database/dev DB_PASSWORD

To populate the rest of the matrix in one go, paste this block:

npx clef set database/dev        DB_USER       dev_user
npx clef set database/production DB_HOST       db.prod.internal
npx clef set database/production DB_USER       app
npx clef set database/production DB_PASSWORD   --random
npx clef set payments/dev        STRIPE_KEY    sk_test_demo
npx clef set payments/dev        WEBHOOK_URL   https://dev.example.com/webhooks/stripe
npx clef set payments/production STRIPE_KEY    --random
npx clef set payments/production WEBHOOK_URL   https://example.com/webhooks/stripe

--random generates a cryptographically random placeholder and marks the key as pending — Clef tracks placeholders so you can find them later with clef lint.

Step 3 — Explore the matrix

Compare environments side by side:

npx clef diff database dev production

Validate the whole repo — schema compliance, matrix completeness, SOPS integrity:

npx clef lint

Open the local web UI to browse the matrix visually:

npx clef ui

This binds to 127.0.0.1:7777 only. From the UI you can edit secrets with masked values, diff environments, and run lint with one click. Press Ctrl-C to stop the server when you're done.

Step 4 — Provision KMS and migrate `production`

Steps 4 and 5 use AWS. Make sure your credentials are set:

aws sts get-caller-identity

The @clef-sh/cdk ClefSecret and ClefParameter constructs require KMS-envelope identities — they need a customer KMS key to wrap each pack's data encryption key. The infra/ directory ships two CDK stacks for this:

QuickStartKms — provisions the KMS key plus the alias alias/clef-quick-start.
QuickStartApp — deploys three ClefSecrets into AWS Secrets Manager. We deploy this in step 5.

The KMS stack uses a fixed alias, so we can compute its ARN up front:

ACCOUNT=$(aws sts get-caller-identity --query Account --output text)
REGION=${AWS_REGION:-$(aws configure get region)}
KMS_ARN="arn:aws:kms:${REGION}:${ACCOUNT}:alias/clef-quick-start"

PowerShell equivalent:

$ACCOUNT = aws sts get-caller-identity --query Account --output text
$REGION  = if ($env:AWS_REGION) { $env:AWS_REGION } else { aws configure get region }
$KMS_ARN = "arn:aws:kms:${REGION}:${ACCOUNT}:alias/clef-quick-start"

Create the app service identity:

npx clef service create app \
  --runtime \
  --namespaces database,payments \
  --kms-env production=aws:$KMS_ARN

Scoped to both namespaces, with KMS-envelope encryption on production. dev stays on age — fine, since the CDK stack only deploys production secrets. --runtime keeps clef from re-encrypting your matrix files with a new shared age key; the CDK pack-helper handles encryption itself at synth time.

Bootstrap CDK (if needed) and deploy the KMS stack:

cd infra
npx cdk bootstrap
npx cdk deploy QuickStartKms --outputs-file ./kms-outputs.json
cd ..

Now re-encrypt the production matrix cells with KMS (dev stays on age):

npx clef migrate-backend \
  --aws-kms-arn $KMS_ARN \
  --environment production

clef migrate-backend decrypts each */production.enc.yaml cell with your age key and re-encrypts it under the new KMS key, in place. Verify with clef lint — the production cells should now show the new backend.

Step 5 — Deploy secrets to AWS Secrets Manager

Take a look at infra/lib/app-stack.ts to see the ClefSecret calls. Each construct synthesises one Secrets Manager secret, with the value computed at deploy time from the encrypted Clef matrix.

The shape property is a template with {{name}} placeholders, and refs binds each placeholder to a (namespace, key) pair in the matrix. Namespace and key stay as separate fields rather than collapsing into a single token, which keeps DB_USER from database distinct from any future DB_USER in another namespace this identity spans. shape also accepts an object literal — see PaymentsConfig in app-stack.ts for a JSON-shaped secret. The unwrap happens inside a synth-time pack step plus a CloudFormation Custom Resource at deploy — see How ClefSecret stays secure for the per-deploy KMS grant model.

Deploy:

cd infra
npx cdk deploy QuickStartApp -c app=true
cd ..

The -c app=true flag opts the app stack into synth — see the comment in infra/bin/infra.ts for why we gate it.

Once the stack settles, list the new secrets:

aws secretsmanager list-secrets \
  --filters Key=tag-value,Values=clef-quick-start \
  --query 'SecretList[].Name'

Read one back the way your application would:

aws secretsmanager get-secret-value \
  --secret-id clef-quick-start/database-url \
  --query SecretString --output text

That value was never typed in plaintext at deploy time — it was reconstructed from secrets/database/production.enc.yaml inside the synth pack step, wrapped under your KMS key, and unwrapped exactly once by the per-deploy grant.

Step 6 — Connect Clef Cloud (optional)

So far everything is local: rotation due-dates, schema rules, lint warnings — they live in .clef/policy.yaml and only fire when you run clef lint or clef policy check. To enforce them across a team, you push the repo and let the Clef Cloud bot watch it on every PR.

clef init already scaffolded two files for this:

.clef/policy.yaml — declares rotation cadence per namespace, schema requirements, allowed backends, and any custom policy rules.
.github/workflows/clef-compliance.yml — a GitHub Actions workflow that runs clef policy check on each PR, writes compliance.json, and uploads it as the workflow artifact the bot reads.

Install the GitHub App and link this repo to a Clef Cloud workspace:

npx clef cloud init

This authenticates you via GitHub OAuth (device flow), installs the Clef GitHub App on the repository, and registers the workspace. The CLI is non-destructive — .clef/policy.yaml is left alone if it already exists.

Once installed, the bot will:

post a status check on every PR summarising rotation overdue counts, schema violations, and pending placeholders,
block merges that violate .clef/policy.yaml (configurable per rule), and
populate the Cloud dashboard with the compliance history of the repo.

The dashboard won't show data until you actually push and let CI run. Compliance is computed from the compliance.json artifact produced by .github/workflows/clef-compliance.yml, so:

git add .clef/policy.yaml .github/workflows/clef-compliance.yml
git commit -m "Enable Clef Cloud"
git push

Open a PR (even a no-op one) to trigger the workflow, then check the dashboard. The bot's status check will appear on the PR and the dashboard tile for this repo will fill in once the workflow finishes.

This is how governance and policy enforcement come into play: policy.yaml is the spec, the workflow is the enforcement point, and the bot is the cross-team visibility layer. Local devs get the same checks via clef lint / clef policy check, so violations surface long before review.

What you just built

Step back for a second — in the last ~10 minutes you stood up:

A central, version-controlled source of truth for secrets. Every value lives in secrets/<ns>/<env>.enc.yaml, encrypted with SOPS, diffable in git, reviewable in PRs.
Per-environment encryption with a clean handoff to AWS. dev rides on age for friction-free local work; production is sealed with your own KMS key. The CDK constructs deliver those values into AWS Secrets Manager so applications keep using the standard aws-sdk — no Clef binary, no agent, no sidecar.
Rotation and schema tracking with a path to enforcement. clef lint already flags pending placeholders and policy violations locally; once Clef Cloud is connected, the same checks run on every PR and the dashboard tracks rotation health across repositories.

If you swap the demo --random placeholders for real values, point a real service at the secrets via the AWS SDK, and add a schema for each namespace, the same pattern scales straight from this tutorial to a production setup.

Cleaning up

This repo is meant to be thrown away. To remove the AWS resources you just deployed:

cd infra
npx cdk destroy QuickStartApp QuickStartKms

Then rm -rf the directory or re-clone if you want to run through the tutorial again.

Where to go next

@clef-sh/cdk reference — github.com/clef-sh/clef/tree/main/packages/cdk covers the other constructs (ClefArtifactBucket for S3 delivery, ClefParameter for SSM Parameter Store) and synth-time validation.
Schemas — define required keys and value patterns per namespace; clef lint will then enforce them. See docs.clef.sh/guide/schemas.
CI — for GitHub Actions, OIDC into KMS so CI never holds long-lived credentials. See docs.clef.sh/guide/ci.

If you hit anything that didn't work, please open an issue — the goal is for this tutorial to run cleanly for everyone.

The Windows Bug That Hung Our CI Forever (And What Node's socket.end() Won't Tell You)

Clef.sh — Wed, 15 Apr 2026 18:45:59 +0000

Building Clef has a non-negotiable constraint: decrypted secrets never touch disk. Encryption and decryption go through the sops binary, and we pipe everything through stdin/stdout. On Linux and macOS, that's a one-liner — pass /dev/stdin as SOPS's input file and stream the content in.

Then we enabled Windows CI, and every test hung until GitHub Actions killed the job at the six-hour timeout.

Here's what happened, and why the fix is three characters different from what you'd probably write first.

The constraint and the Windows problem

SOPS is a Go binary. It expects a file path as input. On Unix we exploit the fact that /dev/stdin is a real path that resolves to the current process's standard input — SOPS opens it, reads to EOF, and we're done.

Windows has no /dev/stdin. There's no equivalent path you can hand to a subprocess. So we need another way to give SOPS a "file" that's really a stream.

The Windows answer is named pipes: paths of the form \\.\pipe\name that Go's os.Open / CreateFile can open exactly like a regular file. The first naive version looked like this:

const server = net.createServer((socket) => {
  socket.end(content);  // <-- seems reasonable
});
server.listen(`\\\\.\\pipe\\clef-sops-${randomBytes(8).toString("hex")}`, () => {
  spawn("sops", ["-e", pipeName], ...);
});

socket.end(content) is the standard Node idiom: write the payload, half-close the stream, let the reader see EOF.

On Unix this works perfectly. On Windows, SOPS would open the pipe, read our content, and then wait forever. The Go side never saw EOF, so its io.ReadAll never returned.

Why `socket.end()` lies on Windows pipes

This is the part that cost me half a day.

Node's socket.end() is supposed to flush pending writes and then signal EOF to the peer via a half-close. Under the hood, that half-close is implemented by libuv's uv_shutdown, which on Unix sockets calls shutdown(fd, SHUT_WR). The peer's read() returns 0 bytes. Clean EOF.

On Windows named pipes, uv_shutdown is effectively a no-op. There's no half-close primitive for Windows pipes — the only way to signal "I'm done writing" is to close the handle entirely. But libuv keeps the handle open because, from its perspective, you only asked to shut down the write side.

So from the Go side: the pipe is still open, no bytes are arriving, but there's no EOF either. ReadAll does the only thing it can — it blocks.

The fix

Close the handle instead of half-closing it:

const server = net.createServer((socket) => {
  socket.write(content, () => {
    socket.destroy();
  });
});

Three things matter here:

socket.write() instead of socket.end() — we're doing the flush ourselves.
The callback — don't destroy until the write is flushed to the kernel, or you'll truncate the content.
socket.destroy() instead of socket.end() — destroy closes the handle. Go's CreateFile handle to the pipe now returns ERROR_BROKEN_PIPE on the next read, which Go's stdlib maps to io.EOF. The read loop terminates. SOPS proceeds.

The final code lives in packages/core/src/sops/client.ts:

const server = net.createServer((socket) => {
  // On Windows, socket.end() does not reliably signal EOF to named pipe
  // clients because libuv's uv_shutdown is a no-op for pipes. Write the
  // content and then force-destroy the socket so the pipe handle is closed,
  // which the Go client (sops) sees as ERROR_BROKEN_PIPE → io.EOF.
  socket.write(content, () => {
    socket.destroy();
  });
});

Takeaways

A few things I walked away with:

socket.end() is not a portable EOF signal. It works on TCP sockets and Unix domain sockets because the underlying primitives support half-close. On Windows named pipes, there is no half-close — only handle close.
Cross-runtime pipes are a minefield. Node and Go both abstract over platform-specific pipe semantics, but the abstractions don't line up exactly. The bug only shows up when both runtimes are on the Windows side of the abstraction at the same time.
"Silent hang in CI" is a strong signal. If the failure mode is "no output, no error, just timeout," the problem is almost always an EOF / blocking-read mismatch somewhere. No exception means neither side thinks anything is wrong.

If you're curious about the larger design — why we're piping to SOPS in the first place, and how the in-memory-only constraint shapes the rest of the architecture — the whitepaper has the longer version.

The Tradeoff Every Secrets Manager Forces on You (And Why It's the Server's Fault)

Clef.sh — Wed, 15 Apr 2026 18:36:42 +0000

Pick any secrets manager and you're picking one of two tradeoffs:

Self-hosted (Vault, Infisical): you keep custody of your plaintext, but you also operate a stateful cluster — HA storage, unseal keys, PostgreSQL, Redis, backups, upgrades.
SaaS (Doppler, AWS Secrets Manager, 1Password): someone else operates the cluster, but your data sits in their system under their control. Ciphertext, key material, plaintext in some cases.

Ops or custody. Pick one.

This post is about the thing that forces the choice: the central server itself. I work on Clef, a git-native secrets tool, so I have a horse in this race. I'll try to be upfront about where the tradeoff actually moves and where it just changes shape.

Why the server creates the dilemma

A central secrets server has to authenticate callers. That means something, somewhere, needs to hold a credential to talk to it — the classic "secret zero" problem. That credential ends up in one of three places: baked into container images, pasted into CI, or stored in another secrets manager. Each is a custody problem in miniature.

Cloud secret managers and Vault both have good answers — OIDC federation, IAM auth, AppRole, Kubernetes auth. The answers work. But they exist because the server model demands them. Every answer is configuration you have to get right, and every piece of configuration is a surface the server can be compromised through.

And once a server is holding plaintext (or the keys to plaintext) for many tenants or many services, it becomes the highest-value target in your infrastructure. A breach is not one secret — it's all of them.

What git-native changes

Clef's bet is that you don't need a server at all. The architecture has two pieces:

At rest: SOPS-encrypted files in your git repo. Keys visible, values encrypted. Code review, diffs, and drift detection work on the encrypted files directly because the key names are plaintext.
At runtime: a lightweight agent (or Lambda extension) pulls a signed, pre-encrypted artifact from S3 or your VCS and decrypts it in memory using the workload's IAM role.

No secrets server. No bootstrap token. The workload's existing IAM identity is the authentication. KMS is the key management. Clef is just the envelope and the delivery path.

The whitepaper walks through this in detail, including the hardened topology (three separate KMS keys: one for source encryption, one for artifact wrapping, one for signing) and how just-in-time decryption lets IAM revocation become an instant kill switch.

The tradeoffs I won't hand-wave

Moving off a server doesn't make tradeoffs disappear. It moves them:

Your repo becomes an access control layer. Read access to the repo reveals namespace names, environment topology, and recipient fingerprints — a reconnaissance map, even without decryption keys. VCS providers weren't designed for that role. If that's unacceptable for your threat model, a private secrets repo with restricted access is the right call, and you lose some of the "secrets and code versioned together" benefit.
Git's limits are real. Repo size grows. Branch-heavy workflows multiply encrypted variants. VCS outages affect CI even if they don't affect running agents (hosted-artifact mode keeps runtime on a separate availability plane).
Clef is not the right answer for everyone. If you're a small team on a PaaS with five secrets, use Doppler. If you're deep in AWS and want managed rotation, AWS Secrets Manager is genuinely good. If you need Vault's dynamic credential engines today, use Vault. The whitepaper's Section 1.1 says this in more words.

What we think we do get right

For teams that already live in git, want review workflows on secret changes, and want zero static credentials in production, removing the server is a real architectural win — not a marketing one. No cluster to operate. No vendor holding your plaintext. No bootstrap token hiding in CI. The custody-vs-ops dilemma doesn't get traded; it gets dissolved, because the thing creating it is gone.

We're not claiming magic. We're claiming the server was the problem, and a different architecture — one built on primitives every team already has (git, IAM, KMS) — doesn't need one.

If you want the long version with the full threat model, the artifact signing design, and the KMS-native envelope flow, the whitepaper is the honest read. It calls out the places Clef is weaker as clearly as the places it's stronger. That's the only way this kind of decision should get made.

I Was Tired of Paying $0.40/Secret/Month, So I spent a month building a CLI tool to manage it.

Clef.sh — Thu, 02 Apr 2026 03:08:53 +0000

Last month I looked at my AWS bill for a side project — a static site on S3 and a Lambda function that maybe 3 people use, including me.

The most expensive line item was secrets management.

AWS Secrets Manager charges $0.40 per secret per month, plus $0.05 per 10,000 API calls. I had 12 secrets across two environments. That's $4.80/month just to store a Stripe key and a database URL — for a project that costs $1.20/month in compute.

The Alternatives All Suck

SSM Parameter Store — free tier exists, but no encryption at rest for SecureString without KMS ($1/month/key), no rotation, no structure.
Hardcoded env vars — works until you need to rotate something, or onboard a teammate, or remember what staging is actually pointing at.
.env files in a private repo — congratulations, your secrets are now in plaintext in git history forever.
HashiCorp Vault — I need a server to store 12 key-value pairs?

What I Actually Wanted

Secrets stored alongside my code (one source of truth)
Encrypted at rest (not plaintext in git)
History of every change (who changed what, when)
Works across environments (dev, staging, production)
Free

So I Built Clef

Clef is a CLI that manages encrypted secrets in your git repo using Mozilla SOPS and age encryption.

Setup takes about 2 minutes:

npm i -g @clef-sh/cli
clef init --namespaces api --non-interactive

This generates an age key (modern, simple encryption — no GPG), creates a clef.yaml manifest, and scaffolds encrypted files for each namespace × environment.

Setting a secret:

clef set api/production STRIPE_KEY sk_live_abc123

The value is encrypted immediately. The file in git looks like:

STRIPE_KEY: ENC[AES256_GCM,data:7a3b9c...,type:str]

Key names visible (great for diffs and code review), values encrypted. Getting it back:

clef get api/production STRIPE_KEY
# sk_live_abc123

Injecting into a process:

clef exec api/production -- node server.js
# STRIPE_KEY is now in process.env

What It Replaced

	AWS Secrets Manager	Clef
Cost	$0.40/secret/month + API calls	Free
Storage	AWS managed	Your git repo
History	CloudTrail (extra cost)	`git log`
Access control	IAM policies	Age keys
Infrastructure	AWS account required	None
Offline access	No	Yes
Vendor lock-in	Yes	No (it's just encrypted YAML)

The Tradeoffs (Being Honest)

Clef isn't a Vault replacement. It's for a different use case:

No runtime secret injection — you decrypt at build time or via clef exec. There's no API your app calls at runtime (though there is an agent sidecar if you want that).
No automatic rotation — you rotate by running clef set with a new value and pushing. No Lambda rotation functions.
Trust model is simpler — if someone has the age key, they can decrypt everything they're a recipient on. There's no per-secret ACL. For a solo dev or small team, this is fine. For a 200-person org, use KMS.

Who This Is For

Side projects where secrets management costs more than the project itself
Small teams (2-5 people) tired of sharing .env files over Slack
Anyone who wants secrets versioned in git with real encryption, not base64 encoding
Developers who don't want to run infrastructure just to store 10 key-value pairs

Who This Is Not For

Large orgs that need centralized access control and audit
Teams that need runtime secret rotation without redeployment
Anyone already happy with their current setup (seriously, don't switch for the sake of it)

The repo is at github.com/clef-sh/clef. It's MIT licensed. Stars appreciated but not required.

If you've ever looked at your AWS bill and wondered why storing a database password costs more than running the database, give it a try.

The Gap Between Encrypting Secrets and Proving You Handled Them Right

Clef.sh — Wed, 01 Apr 2026 15:12:20 +0000

There's a moment in every secrets pipeline that nobody talks about.

You encrypt your secrets at rest. You store them in git as ciphertext. You manage KMS keys with IAM policies. You rotate credentials. You might even use SOPS or sealed-secrets or Vault. Your secrets management story sounds solid in an architecture review.

But at some point, something has to decrypt those secrets and do something with them. And that something runs on a CI runner.

The Plaintext Moment

Think about what happens during a typical deployment. Your CI pipeline checks out the repo, decrypts SOPS-encrypted files, merges the right values for the target service and environment, re-encrypts them into a deployment artifact, and pushes it somewhere your runtime can consume it.

For a brief window, plaintext secrets exist in memory on a general-purpose compute environment. The same environment that runs your test suite, your linters, your build tools, and whatever transitive dependencies those tools pulled in this week.

The ciphertext in your git repo is inert. Your KMS keys in isolation are useless. But the moment ciphertext meets decryption capability in the same execution context — that's when plaintext is born. And that moment happens on your CI runner.

Why This Matters Less Than You Think (And More Than You Think)

If you self-host your CI runners, you probably trust them. You control the machine, the network, the software. Telling you "your CI runner might be compromised" is arguing against your own operational confidence, and it's a hard sell.

But here's the thing: trusting your CI runner and being able to prove what your CI runner did are two different things.

When an auditor asks "what code processed these secrets during the last deployment," the honest answer from most pipelines is "we trust that our CI ran the right code." That's an assertion, not evidence. The CI logs say what happened — but the CI wrote those logs. If the runner were compromised, the logs would say whatever the attacker wanted them to say.

This isn't a security gap in the traditional sense. It's a provenance gap. You might be doing everything right, but you can't prove it cryptographically.

What Cryptographic Provenance Looks Like

Imagine if the "pack" operation — the moment where ciphertext meets KMS decryption and plaintext is born — ran inside hardware-isolated memory. The host operating system can't read it. The hypervisor can't read it. Root access on the machine can't read it.

Now imagine the hardware produces a signed attestation document that says "this exact binary, with this exact image hash, ran this operation." And your KMS key policy says "only decrypt when the request comes with a valid attestation document bearing this specific image hash."

You now have a chain:

The binary is source-available — anyone can read the code
The build is reproducible — anyone can verify the binary matches the source
The image hash is deterministic — same source produces same hash
The KMS policy only allows decryption by that exact image
The attestation document is signed by the hardware, not by software you control
The result is a signed artifact with a receipt that includes the attestation, the source commit, and the KMS keys used

This isn't "we trust the CI runner." This is "the hardware proved what code ran, and the KMS proved only that code could decrypt." No one in the chain needs to be trusted — the proof is anchored in hardware attestation and KMS policy evaluation.

The Audit Answer Changes

Without this: "We followed our procedures and our logs show the pipeline ran correctly."

With this: "Here is the attestation receipt. It proves this specific binary, running inside hardware-isolated memory, processed secrets from this git commit, using these KMS keys, and produced this artifact. The binary is source-available and reproducibly built — here's the build spec if you want to verify the image hash yourself."

The first answer requires trusting the organization. The second requires trusting math.

Who Actually Needs This

Not everyone. If you're a startup with five engineers and you trust your CI, you probably don't need hardware-attested pack operations. Your threat model doesn't justify the operational complexity.

But if you're in a regulated industry — finance, healthcare, government, or any organization where auditors ask pointed questions about secret handling — the provenance gap is real. And it gets wider as your secrets pipeline gets more complex: more services, more environments, more KMS keys, more people with access to CI infrastructure.

The interesting thing is that this isn't about replacing your secrets manager. You keep Vault, or SOPS, or whatever you use. The attestation layer sits on top of your existing pipeline, specifically around the moment where secrets are decrypted and repackaged. It's a narrow, focused intervention at the one point in the pipeline where plaintext exists.

The Punchline

Encryption protects secrets at rest. KMS policies protect secrets at the API boundary. Network isolation protects secrets in transit. But none of these protect the moment of use — the instant when ciphertext is decrypted and plaintext lives in memory.

Hardware enclaves protect that moment. Attestation proves what happened during that moment. Reproducible builds let anyone verify that the attested code matches published source.

The result isn't a security product. It's a provenance product. The answer to "how do you know your pipeline didn't leak these credentials" stops being an assertion and becomes a proof.

We scored ourselves against HashiCorp's 12-point secrets management framework. We have some work to do.

Clef.sh — Tue, 31 Mar 2026 14:22:48 +0000

HashiCorp Says Your Secrets Manager Needs 12 Things. Here's How We Stack Up. 🎹 - DEV Community

HashiCorp recently published a whitepaper called "12 Things a Modern Secrets Management Solution Must...

dev.to

HashiCorp Says Your Secrets Manager Needs 12 Things. Here's How We Stack Up. 🎹

Clef.sh — Tue, 31 Mar 2026 13:50:31 +0000

HashiCorp recently published a whitepaper called "12 Things a Modern Secrets Management Solution Must Do." It's a solid framework — genuinely useful for evaluating any secrets tool.

So we ran Clef through it. Honestly.

We're not going to pretend we check every box the same way Vault does. We're a git-native secrets manager built on SOPS — no servers, no tokens, no vendor custody. Different architecture, different tradeoffs. Here's where we're strong, where we're different, and where we'll tell you to use something else.

The Scorecard 📋

1. Secure Secrets Storage 🔒

Vault: Centralized encrypted KV store. Secrets encrypted before hitting persistent storage. Dashboard + CLI.

Clef: Encrypted files in git. SOPS encrypts values using age or cloud KMS. Decrypted values exist only in memory — plaintext never touches disk. The repo is the store.

✅ Verdict: Both nail this. Different storage model, same outcome — secrets encrypted at rest, protected from raw storage access.

2. Centralized Management 🏢

Vault: Enterprise dashboard. SecOps manages everything from one place without bugging developers.

Clef: The git repo is the single source of truth. clef lint validates the matrix. clef report publishes structured JSON for your observability stack.

🟡 Verdict: Clef is developer-first CLI today — no enterprise dashboard. If you need SecOps visibility without git fluency, that's not us yet. Clef Pro is coming for exactly this. Right now, we're focused on teams where the developers are the security team.

3. Secret Scanning 🔍

Vault: HCP Vault Radar scans across your entire IT estate — code, wikis, Slack, ticketing, cloud storage.

Clef: clef scan does pattern matching + entropy analysis on the git repo. Pre-commit hooks and CI integration catch leaks before merge.

🟡 Verdict: Clef covers the most common leak vector (code), not the whole org. For everything else, pair with GitGuardian or Trufflehog. We're not going to pretend a git hook replaces organization-wide scanning.

4. Strong Encryption 🛡️

Vault: Encryption as a Service (EaaS). AES-256-GCM via transit engine. Encrypt arbitrary application data.

Clef: SOPS + age (X25519/ChaCha20-Poly1305) or cloud KMS (AES-256-GCM). All crypto delegated — zero custom cryptography.

✅ Verdict: Both strong. Clef encrypts secrets, not arbitrary payloads — we're not an EaaS. But the encryption itself? Rock solid, industry-standard, no homebrew.

5. Secrets Versioning 📜

Vault: KV v2 version history. UI shows who changed what. API rollback to previous versions.

Clef: Git is the versioning. Full commit history, PR context, code review, blame, branching. Rollback = git revert → PR → merge → CI repacks.

✅ Verdict: This is Clef's home turf. Git versioning is arguably stronger — you get author, reviewer, CI status, and the complete code context around the change. And every developer already knows how to use it.

6. Advanced Access Control 🚪

Vault: Identity-based policy engine. RBAC, MFA, fine-grained per-path permissions. Dozens of auth methods.

Clef: Cryptographic scoping at the namespace level. Service identities are SOPS recipients only on their namespaces — enforcement is at the encryption layer. Per-environment keys. Git branch protection + CODEOWNERS guard the manifest.

🟡 Verdict: Clef's access control is cryptographic — a service literally cannot decrypt secrets outside its scope. That's powerful. But there's no RBAC, no MFA, no per-key permissions. If you model namespaces at the right granularity (one per dependency), it works. If you need per-secret policies or MFA-gated access, Vault is purpose-built for that.

7. Backup and Recovery 💾

Vault: Raft snapshots, cross-cluster replication, encrypted backups, OIDC integration for recovery.

Clef: Every git clone is a full backup. Break-glass age key in a physical safe decrypts everything if KMS goes sideways. AWS KMS enforces 7-30 day deletion waiting period.

✅ Verdict: Git's distributed nature means backup is inherent — no strategy to design, no snapshots to schedule. Your data is replicated across every developer's checkout.

8. Automated Secrets Rotation 🔄

Vault: Dynamic secrets with TTL leasing. Vault changes the actual credential at the source — database passwords, cloud IAM, certificates. Auto-revoke on expiry.

Clef: Two different things here. Encryption key rotation — automatic, every clef pack generates fresh ephemeral keys. Credential rotation (the actual password at the source) — manual via clef set → PR → merge → repack. Broker-backed dynamic credentials can automate this but require deploying a handler.

🟡 Verdict: We're being honest — Clef doesn't auto-rotate your database password out of the box. Encryption keys rotate automatically on every build, which is great. But if you need push-button credential rotation for 30 backends today, Vault's secrets engines are production-proven.

9. Dynamic Secrets ⚡

Vault: First-class. Dozens of production-hardened engines — AWS, databases, PKI, SSH, LDAP. Years of battle-testing.

Clef: Broker SDK + registry. Templates for STS, RDS IAM, OAuth, SQL users. The architecture supports it. The ecosystem is young.

🔴 Verdict: We'll say it plainly — if you need dynamic credentials today with minimal engineering, use Vault. Our broker architecture is extensible, but you're building, not consuming. Vault's breadth here is an order of magnitude larger.

10. Integrations, APIs, and Secrets Sync 🔌

Vault: RESTful API for everything. One-way KV sync to external destinations. Massive plugin ecosystem.

Clef: Agent HTTP API on 127.0.0.1:7779. Any language that can GET can read secrets. No SDK, no vendor client library. No secrets sync — the packed artifact is the distribution.

🟡 Verdict: Clef's interface is dead simple — one HTTP endpoint, universal. But Vault's pre-built integrations (K8s sidecar injector, native Lambda integration, etc.) mean less glue code. Simplicity vs. breadth. Pick your tradeoff.

11. Automated Key Management 🔑

Vault: Unified API to manage key lifecycles across AWS KMS, Azure Key Vault, GCP Cloud KMS. Create, rotate, disable, delete — one interface.

Clef: Delegated model. Clef uses KMS keys but doesn't manage their lifecycle. Key creation, rotation, and deletion happen through your cloud provider's console or IaC (Terraform, Pulumi). Ephemeral key pairs per clef pack eliminate long-lived runtime keys.

🟡 Verdict: Clef doesn't provide a key management abstraction — your cloud provider does, and you manage it with IaC like everything else. For teams already running Terraform, this adds zero operational surface. If you want one API for keys across three clouds, Vault has that.

12. Robust Auditing 📊

Vault: Built-in audit device. One dashboard, one query: "who accessed what, when."

Clef: Distributed across existing infra — CloudTrail for KMS events, git log for authorship, CI logs for packing, OTLP telemetry for agent health. JIT mode maps every secret read to a distinct CloudTrail entry.

🟡 Verdict: All the audit data exists — it's just in four places, not one. Correlating across them is work. Clef Pro will unify this. Today, teams that already have observability tooling (Datadog, Grafana, etc.) can wire it up, but there's no single-pane view out of the box.

The TL;DR 🎯

	Clef ✅	Even 🟡	Vault ✅
Strong	Storage, Encryption, Versioning, Backup
Different tradeoff		Management, Scanning, Access Control, Rotation, Integrations, Key Mgmt, Auditing
Vault wins today			Dynamic Secrets

The Honest Pitch 🤝

Clef is built for teams that want secrets versioned alongside code, reviewed in PRs, and delivered without a central server to babysit.

If your team lives in git, manages infra through IaC, and values operational simplicity over integration breadth — Clef removes an entire category of infrastructure from your stack. No cluster. No unsealing. No token bootstrapping. No vendor custody.

If you need a policy engine, an enterprise dashboard, or turnkey dynamic credentials for dozens of backends today — Vault is purpose-built for that, and we'd rather you know upfront than find out after adoption.

We think honesty builds more trust than a checkbox grid. 🎹

Clef is open source. Star us on GitHub, read the whitepaper, or just npx clef init and see for yourself.

I thought running a HashiCorp Vault cluster just to securely pass API keys to production was a bit much. So I built Clef: a tokenless, zero-server secrets manager using Git, SOPS, and KMS envelope encryption. Better security, smaller footprint.

Clef.sh — Thu, 26 Mar 2026 12:41:38 +0000

I built a tokenless secrets manager that runs entirely on Git and KMS (No Vault required) - DEV Community

If you've ever had to manage secrets for a production application, you know the pain of the "Secret...

dev.to

I built a tokenless secrets manager that runs entirely on Git and KMS (No Vault required)

Clef.sh — Wed, 25 Mar 2026 20:48:53 +0000

If you've ever had to manage secrets for a production application, you know the pain of the "Secret Zero" problem: How do you securely deliver a secret to a workload without giving it a static .env file or password first?

Today, the industry standard way to solve this is to use HashiCorp Vault or Infisical tied to your cloud's machine identity (like AWS IAM Auth or Kubernetes Service Accounts).

That works beautifully, but the infrastructure cost is massive. You have to run an HA cluster, manage unseal keys, configure storage backends, and maintain a dedicated secrets server just to securely pass an API key.

The alternative is raw Mozilla SOPS + Git, which gives an amazing developer experience but leaves you writing messy custom KMS-decryption bash scripts in your CI pipelines to get those secrets into production.

I wanted the developer experience of Git, but the enterprise security of a tokenless, zero-trust architecture—without running a server. So, I built Clef.

What is Clef?

Clef (https://clef.sh) is an open-source secrets manager. It bridges the gap by treating your Git repository as the authoritative state and your cloud's native IAM as the authentication layer.

Here is how the architecture works from development to production:

1. Local Development (Secrets as Code)

Secrets are encrypted locally using SOPS and Age encryption. You define your service identities and namespaces in a simple clef.yaml manifest. No plaintext is ever written to disk.

# Initialize a new project
clef init

# Set a secret in development
clef set database/development DB_URL "postgres://localhost:5432/myapp"

# Inject secrets directly into your local Node process
clef exec database/development -- node server.js

2. CI/CD (The Pack Phase)

When you merge your code, your CI pipeline runs clef pack. It decrypts only the SOPS files scoped to that specific service, merges them, and creates a lightweight JSON artifact.

3. Solving "Secret Zero" (KMS Envelope Encryption)

This is where the magic happens. To deliver that JSON artifact securely without static credentials, the CI pipeline generates an ephemeral, one-time-use Age key pair.

It encrypts the artifact with the ephemeral key, and then wraps the ephemeral private key using your cloud KMS (AWS or GCP).

4. Production Runtime (The Agent)

A lightweight Clef Agent sidecar runs next to your production app. It doesn't need a password or a .env file. Using the machine's native cloud IAM role (like an AWS EC2 or ECS Task Role), the agent simply asks KMS to unwrap the ephemeral key.

It then decrypts the artifact and serves the secrets to your app via a localhost API (127.0.0.1:7779).

// Your app code just fetches from localhost
const secrets = await fetch("http://127.0.0.1:7779/v1/secrets", {
  headers: { Authorization: "Bearer <local-token>" }
}).then(r => r.json());

The Honest Trade-off

Security is always a trade-off. By eliminating the central server, your Git repository effectively becomes your access control list. You are trading infrastructure complexity for strict GitOps process discipline. If an insider can merge a PR that adds their personal public key to your clef.yaml manifest, they gain access to your secrets. To use Clef safely, you must enforce strict branch protection, require CODEOWNERS reviews on your security manifests, and run isolated CI pipelines.

Properly securing Git + CI is easier than securing Git + CI + Vault, but you have to treat your repo with the seriousness of a vault.

Try it out

Clef is fully open-source under the MIT license.

I wrote a detailed whitepaper breaking down the architecture, the KMS envelope math, and the threat model. I’d love for the DEV community to tear it apart, try out the CLI, and let me know what you think!

GitHub Repo: https://github.com/clef-sh/clef
Docs & Whitepaper: https://clef.sh

Let me know in the comments: For those of you running Vault today, is the operational overhead worth having a centralized policy engine, or would you trade it for a Git-native ACL like this?