HEDDLE

Guide

Signing with Ed25519

Heddle's signing is optional but cheap. The CLI commands that accept signatures (heddle redact apply, heddle review sign) take a key file on disk and sign the canonical payload before storing the operation. This guide covers the key plumbing: generating a key, passing it to a signing operation, verifying the result.

1. Generate an Ed25519 keypair

Heddle doesn't ship its own KMS. Use whatever your organisation already uses: OpenSSL, a hardware token, Vault, AWS KMS, a yubikey. For a starter setup, OpenSSL works:

Generate an Ed25519 private key in PEM form

bash$ mkdir -p ~/.heddle/keys$ openssl genpkey -algorithm ed25519 -out ~/.heddle/keys/ops.pem$ chmod 600 ~/.heddle/keys/ops.pem

The PEM header tells Heddle which algorithm to use. If you're using an unusual format or want to override detection, pass --sign-algo ed25519 (or rsa, p256).

2. Sign a redaction

The clearest signing example is heddle redact apply. Every redaction can carry a signature binding the operator's identity to the declaration that the bytes are gone.

Apply a signed redaction

bash$ heddle redact apply HEAD --path src/test-fixtures/auth.json --reason "leaked API key" --sign-with ~/.heddle/keys/ops.pemredacted src/test-fixtures/auth.json (b3a8e201) in hd-7f3kq9wm2xz0 (redaction 0a1b2c3d)  reason: leaked API key

Heddle loads the signer before doing anything destructive, so a bad --sign-with path fails up-front rather than after the redaction lands. The signature itself binds the redaction's canonical payload, so anyone with the public key can verify it didn't change after the fact.

3. Verify the signature

heddle redact show reports the signature status as one of three values. The distinction matters: "unsigned" and "tampered" are not the same.

Inspect a redaction's signature status

bash$ heddle redact show 0a1b2c3dredaction 0a1b2c3d  blob:        b3a8e201  state:       hd-7f3kq9wm2xz0  path:        src/test-fixtures/auth.json  reason:      leaked API key  redactor:    Anan <anan@heddle.sh>  redacted-at: 2026-05-09T14:34:11Z  purged-at:   (bytes on disk)  signed:      verified  sig-algo:    ed25519

The three states:

  • verified: signature present and validates against the canonical payload.
  • unsigned: operator chose not to sign. The redactor identity is still recorded; the operation is just not cryptographically attested.
  • tampered: signature present but fails to verify. Something changed after the operation was signed. Treat as a security incident.

4. Sign a review

Review signing is structurally similar but the CLI shape is different. heddle review sign takes the pre-computed signature bytes, not a key file. The expectation is that an editor integration or heddle agent handles the canonical-payload construction and signing; the CLI is the raw substrate.

Submit a pre-signed review (typically via tooling)

bash$ heddle review sign hd-7f3kq9wm2xz0 --kind read --public-key 64af...3c1d --signature 9b21...a8f3 --signed-at-unix 1715472851signed state hd-7f3kq9wm2xz0 as read (signature_id sig-9a2f)

A note on policy

Authored states are signed automatically by the device identity, so provenance is never the thing that is missing. What is opt-in is the operator signature: a repo with no operator key configured still ships work, and review signatures and redactions simply appear as unsigned. The repo's policy can require them for promotion into specific namespaces; see namespaces for the cascade model. Or run heddle verify --provenance in CI, which checks each state's offline authorship and review-signature chain and exits nonzero until every check is clean.

Next