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 d01a8b4e (redaction r0a1b2c3)  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 — 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 r0a1b2c3redaction r0a1b2c3  blob:        b3a8e201  state:       d01a8b4e  path:        src/test-fixtures/auth.json  reason:      leaked API key  redactor:    Anan <anan@heddle.sh>  redacted-at: 2026-05-09T14:34:11Z  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-d01a8b4e --kind read --public-key 64af...3c1d --signature 9b21...a8f3 --signed-at-unix 1715472851signed state hd-d01a8b4e as read (signature_id sig-9a2f)

A note on policy

Heddle doesn't enforce signing by default. A repo with no key configured still ships work — operations just appear as unsigned. The repo's policy can require signing for promotion into specific namespaces or for bridge-to-Git export; see namespaces for the cascade model. Or run a CI check that fails any state with signed: unsigned on a regulated branch.

Next