VA-58: architect agent build + minisign signing pipeline (key custody, deployment models, rotation) #64

Merged

nrupard merged 2 commits from docs/VA-58-signing-architecture into main

2026-06-16 19:19:01 +02:00

nrupard commented

2026-06-16 19:01:24 +02:00

Owner

Adds docs/agent-signing-architecture.md, the design of record for VA-58: how vervain-agent binaries are built, signed, published, and verified, and how the publisher signing key is held and rotated. Decisions confirmed by the maintainer 2026-06-14. Doc-only change (plus a ROADMAP delta row); nothing compiles.

What it covers (maps to the VA-58 acceptance criteria)

Two non-conflated trust controls: the minisign signature attests build provenance (anchored on the publisher public key the server holds), the .msh ServerID attests server scoping (a hash-pin checked at the handshake). The signing key answers "did we build this," never "which customer is this for."
All three deployment models: we-build-and-self-host; self-host (consume our releases with only our public key, or rebuild and sign with your own keypair); and managed multi-tenant (one publisher key, tenant isolation by the ServerID pin, no per-tenant keys).
Key custody: one publisher minisign keypair; the secret lives only as a Forgejo Actions secret (or a secrets manager the CI reads), never in the Vervain server or settings; the server is a zero-secret verifier that holds the public key only, supplied via config (VS-37/VS-38).
The vervain-agent signing-keygen subcommand interface: flags, password-less keypair behaviour, secret/public outputs, and stdout in the exact server-config format. Specified here, implementation tracked as a fast-follow.
The build/sign/publish pipeline VA-57 implements, grounded in the AgentId enum and cross-linked to the distribution doc for the id-to-filename mapping and owner/package/version coordinates.
The verifier change from a single publickey to a backward-compatible publickeys set (single scalar still deserializes as a one-element set; empty set stays fatal), which is the rotation mechanism since minisign has no native rotation.
Routine-rotation and key-compromise procedures, with the full operational runbook noted as a documentation fast-follow.
Where the public key value and the owner/package/version coordinates live, so the server default and the VS-38 env seed can reference them.

Cross-links the VA-57 companion docs/agent-package-distribution.md for the concrete published layout, versioning, and public-key value. Verified the companion-doc anchors all resolve.

Links: relates VS-36; depends VA-57 (resolved) and VA-60; references VS-37 (resolved) and VS-38.

#VA-58

Adds `docs/agent-signing-architecture.md`, the design of record for VA-58: how `vervain-agent` binaries are built, signed, published, and verified, and how the publisher signing key is held and rotated. Decisions confirmed by the maintainer 2026-06-14. Doc-only change (plus a ROADMAP delta row); nothing compiles. ## What it covers (maps to the VA-58 acceptance criteria) - Two non-conflated trust controls: the minisign signature attests build provenance (anchored on the publisher public key the server holds), the `.msh` ServerID attests server scoping (a hash-pin checked at the handshake). The signing key answers "did we build this," never "which customer is this for." - All three deployment models: we-build-and-self-host; self-host (consume our releases with only our public key, or rebuild and sign with your own keypair); and managed multi-tenant (one publisher key, tenant isolation by the ServerID pin, no per-tenant keys). - Key custody: one publisher minisign keypair; the secret lives only as a Forgejo Actions secret (or a secrets manager the CI reads), never in the Vervain server or settings; the server is a zero-secret verifier that holds the public key only, supplied via config (VS-37/VS-38). - The `vervain-agent signing-keygen` subcommand interface: flags, password-less keypair behaviour, secret/public outputs, and stdout in the exact server-config format. Specified here, implementation tracked as a fast-follow. - The build/sign/publish pipeline VA-57 implements, grounded in the `AgentId` enum and cross-linked to the distribution doc for the id-to-filename mapping and owner/package/version coordinates. - The verifier change from a single `publickey` to a backward-compatible `publickeys` set (single scalar still deserializes as a one-element set; empty set stays fatal), which is the rotation mechanism since minisign has no native rotation. - Routine-rotation and key-compromise procedures, with the full operational runbook noted as a documentation fast-follow. - Where the public key value and the owner/package/version coordinates live, so the server default and the VS-38 env seed can reference them. Cross-links the VA-57 companion `docs/agent-package-distribution.md` for the concrete published layout, versioning, and public-key value. Verified the companion-doc anchors all resolve. Links: relates VS-36; depends VA-57 (resolved) and VA-60; references VS-37 (resolved) and VS-38. #VA-58

nrupard added 1 commit

2026-06-16 19:01:24 +02:00

docs(signing): architect agent build + minisign signing pipeline (VA-58)

Check / clippy + fmt + tests (pull_request) Successful in 13m31s

Details

5c7c7fb6f8

Add docs/agent-signing-architecture.md, the design of record for how vervain-agent binaries are built, signed, published, and verified, and how the publisher signing key is held and rotated. Decisions confirmed by the maintainer 2026-06-14.

Covers: the two non-conflated trust controls (minisign signature = provenance, .msh ServerID = server scoping); all three deployment models (we-host, self-host consume-or-rebuild, managed multi-tenant with a single publisher key isolated by the ServerID pin); key custody (one publisher keypair, secret in Forgejo Actions only, server is a zero-secret verifier holding the public key via VS-37/VS-38 config); the vervain-agent signing-keygen subcommand interface (inputs, outputs, server-config output format); the build/sign/publish pipeline VA-57 implements; the verifier change from a single publickey to a backward-compatible publickeys set; and the routine-rotation plus key-compromise procedures with the runbook noted as a fast-follow.

Cross-links the VA-57 companion (docs/agent-package-distribution.md) for the published layout, id-to-filename mapping, versioning, and the concrete public-key value the server default and VS-38 env seed reference. Adds a VA-58 ROADMAP delta row.

#VA-58

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

nrupard added 1 commit

2026-06-16 19:17:55 +02:00

feat(signing): vervain-agent signing-keygen + rotation runbook (VA-58)

Create release / Create release from merged PR (pull_request) Has been skipped

Details

Check / clippy + fmt + tests (pull_request) Successful in 7m55s

Details

8a4b59eee8

Implement the two VA-58 fast-follows in place rather than deferring them.

signing-keygen: a new cross-platform `vervain-agent signing-keygen` subcommand (crates/vervain-agent/src/signing_keygen.rs) that wraps `minisign -G -W` to provision the publisher distribution keypair. It refuses to overwrite an existing key file (no --force), writes the secret key 0600 on unix, and prints the public key to stdout in the exact server-config format the agent-fetch `publickeys` expects. A clear error distinguishes "minisign not installed" from other failures. Routed before store/connect setup like `config`, with the path-existence guard factored out and unit-tested (three lib tests; the actual minisign exec is integration-only, since the build image has no minisign).

Rotation runbook: docs/agent-signing-rotation-runbook.md gives the full step-by-step for routine rotation and key-compromise response, with the release-engineer / fleet-operator roles, the ordering constraint (trust the new key fleet-wide before signing with it), and the convergence check that gates retiring the old key. The architecture doc now links it and drops the "fast-follow" framing for both items; the distribution doc points keypair provisioning at the subcommand.

Verified: cargo fmt --check clean, cargo clippy --workspace --all-targets --deny warnings clean, the three signing_keygen lib tests pass. The pre-existing handshake integration test asserts PlatformType::Desktop and fails inside the builder container (detected Virtual); it is environment-sensitive and excluded from the CI gate, which runs `cargo test --workspace --lib`. This change is purely additive and touches no runtime path it exercises.

#VA-58

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>