bible/rules/patterns/release-signing/contract.md

Contract: Release Signing

Version: 1.0

Purpose

Ed25519 asymmetric signing for Go release binaries. Guarantees that a binary accepted by a running application was produced by a trusted developer. Applies to any Go binary that is distributed or supports self-update.

See README.md for reference code and build snippets.

Rules

• Public keys are stored in the centralized keys repository. Public keys may be committed; private keys must stay on each developer machine and must never be committed or shared.
• Adding or removing a trusted developer means changing the committed .pub set and rebuilding affected releases.
• A release is trusted if its signature verifies against any embedded trusted public key.
• The .sig asset is a raw 64-byte Ed25519 signature, not PEM and not base64.
• Trusted public keys must be injected at build time via -ldflags. Do not hardcode them in source.
• A build without injected keys is a valid dev build. It must continue working normally, but verified updates are disabled.
• Signature verification uses Go stdlib crypto/ed25519 only.
• Signature verification failure must log a warning and keep the current binary. It must not crash the app and must not block unrelated operation.
• Every signed release must ship the binary and its matching .sig asset.