SLT.HOTFIX.001 – Enforce trust threshold in pre-receive hook #84
Description
[SLT.HOTFIX.001] Enforce trust threshold in pre-receive hook
Overview
Update the pre-receive hook to validate that pushes to trust refs are co-signed by the configured maintainer threshold, preventing under-signed trust changes from reaching protected repos.
References & Assets
- Figma / Design: N/A
- Product Spec (Notion / Confluence): N/A
- Related Issues / PRs: SLT.ALPHA.019
- Feature Flags / Experiments: N/A
- Other Assets: contrib/hooks/pre-receive.shiplog
User Story
As a repository administrator,
I want trust updates to be blocked unless the required maintainers have signed them,
so that Shiplog's trust graph cannot be altered by a single compromised actor.
Acceptance Criteria
- Hook parses trust policy and retrieves threshold + maintainers
- Only pushes meeting the N-of-M signature requirement are accepted
- Friendly error message emitted when threshold not met
- Dockerized Bats tests cover passing and failing scenarios
- TRUST.md documents the enforcement behavior
Definition of Done
Hook enforcement shipped, documentation updated, and regression tests added across supported signature mechanisms.
Scope
In-Scope
- Pre-receive validation for trust ref
- SSH and PGP signature verification
- Error messaging and documentation updates
Out-of-Scope
- Journal/policy ref enforcement changes
- UI tooling for managing allowed signers
Deliverables
- Est. Lines of Code: ~180
- Est. Blast Radius: contrib/hooks/pre-receive.shiplog, TRUST docs, tests
Implementation Details
High-Level Approach
Parse trust.json from proposed update, verify signatures using existing verifier helpers, count distinct maintainers, and reject pushes below threshold with actionable errors.
Affected Areas
- contrib/hooks/pre-receive.shiplog
- lib/trust_verifier.sh
- docs/TRUST.md
- tests/26_trust_enforcement.bats
Implementation Steps
- Load trust threshold and maintainer keys from new commit
- Reuse verifier to validate SSH/PGP signatures and map to maintainers
- Reject updates with insufficient distinct maintainers
- Add Dockerized tests for satisfied/unsatisfied pushes
- Update docs with enforcement description
Test Plan
Happy Path
- Push with sufficient distinct maintainer signatures succeeds
Edge Cases
- Duplicate signer counted once toward threshold
- Missing allowed_signers or trust metadata surfaces actionable error
Failure Cases
- Under-threshold push rejected with clear message
Monitoring & Success Metrics
- Hook logs include signature validation summaries
QA Sign-off Matrix
| Environment | Surface | Owner | Status | Notes |
|---|---|---|---|---|
| Docker | Git push | TBD | Pending | Covered via make test |
Requirements
Hard Requirements
- Under-threshold trust updates must be rejected server-side
Soft Requirements
- Error guidance should point to trust docs for remediation
Runtime Requirements
- Hook must operate with default shell/ssh-keygen toolchain
Dependencies & Approvals
- Security review
- Ops approval for deploying updated hook
Production Notes
Priority: 5 / 5
Critical integrity fix (P0) for protecting trust updates.
Complexity: 3 / 5
Moderate shell scripting and integration work.
Estimate: 16 - 24 hours
Includes hook implementation, tests, and documentation.
Risk & Rollback
- Primary Risks: Hook false positives blocking legitimate pushes
- Mitigations: Thorough tests and dry-run validation
- Rollback / Kill Switch: Revert hook update or disable via env guard
Additional Notes
Coordinate with ops to roll out hook update across environments.