Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

ADR-034: Commit-signature posture: detect now, cryptographic verify deferred

Date: 2026-06-15 Status: Accepted (owner-delegated review, 2026-06-15) Author: Rômulo Febasi

Scopes SYN-249C. Companion to ADR-030 (git substrate + signed commits).

Context

ADR-030 designed binding the Synapse ed25519 identity to SSH-format git commit signing, with verify/doctor checking signatures against known non-revoked identities: because the git author field is forgeable, so only a verified signature makes multi-user attribution non-repudiable. SYN-249C is the “C” slice: actually verify.

Two facts shape the scope:

  1. The value is multi-user. On a single-user, single-disk vault there is one identity and no adversary forging your own authorship to yourself. The 2026-06-15 direction study (4 independent reviewers) is unanimous: cryptographic commit-signature verification is a team / shared-repo feature, the lowest single-user-value item in v0.11.
  2. The crypto path is not smoke-testable in this environment. Full SSHSIG verification needs the ssh-key dependency, reconstruction of the exact signed commit payload, an allowed-signers set bound to the identity registry, and (to validate it honestly) a real SSH-signed commit, which this build environment cannot produce. Shipping an unverifiable crypto verifier would violate the project’s “never fake green” principle (a half-correct signature check is worse than none).

Decision

Split SYN-249C:

  • Ship now (dep-free, single-user-useful, testable): syn doctor reports the signature posture of the workspace’s HEAD commit: signed vs unsigned: by scanning the raw commit object for a gpgsig header (covers GPG and SSH; gix-version-independent). Advisory Info: unsigned is fine for a solo vault, flagged so a shared vault knows to opt into signing.
  • Defer (to multi-user / Commercial, where the value lives): the cryptographic verification: ssh-key SSHSIG verify of the signature against the non-revoked identity allowlist (ADR-016 revocation), with audit verify / doctor rejecting unsigned/unknown-signer commits. This carries the new ssh-key dependency and the allowed-signers bootstrap; it belongs in the team wedge (SYN-231), gated by a real shared-repo need and a way to test it against genuine signed commits.

Consequences

  • Improves: a real, tested, dep-free increment that nudges shared-repo users toward signing; the moat claim (“verifiable attribution”) stays honest: we report posture, we don’t pretend to verify what we can’t yet test; no premature dependency.
  • Worsens: the headline “verify signatures” capability is not delivered for single-user; an attacker forging a signed commit by an unknown key is not yet caught (posture only reports presence, not validity).
  • Open: the full SSHSIG verify (the ssh-key dep + ADR was pre-authorised by ADR-030) moves to the multi-user milestone; pull it with a test harness that produces real signed commits.

Alternatives considered

  • Implement full SSHSIG verification now. Adds ssh-key for a feature with ~no single-user value and no way to smoke-test the crypto path here, exactly the unverifiable-green the project forbids. Defer to where it’s testable and valuable.
  • Do nothing for SYN-249C in v0.11. Leaves zero increment; the dep-free posture check is cheap and genuinely useful (it tells a shared-repo user their commits are forgeable today).
  • Sigstore/gitsign. Already rejected by ADR-030 (online OIDC breaks offline-first).

Research grounding

docs/researchs/2026-06-15-v0.11-issue-direction-study.md §3 (SYN-249C: all four reviewers: multi-user value, opt-in, last); ADR-030; ssh-key SSHSIG support (RustCrypto). Verification harness blocked on producing real SSH-signed commits in CI.