Context
The Sigstore/Rekor integration is working (DSSE entries, PEM keys, inclusion proofs). The curve-agnostic architecture is documented in docs/contributing/adding_curves.md. But several user-facing and security-critical docs are missing or scattered.
Four docs needed
1. Sigstore integration guide (docs/guides/sigstore.md)
User-facing guide for the --log sigstore-rekor feature. Should cover:
- What happens when you run
auths artifact sign --log sigstore-rekor
- What the DSSE envelope contains and why we use DSSE instead of hashedrekord
- How to verify your entry with
rekor-cli get --log-index <N>
- How to search Rekor by public key
- What the
transparency section in .auths.json means
- How the CI path (
--ci --log sigstore-rekor) differs from the device-key path
- What
--allow-unlogged means and when to use it
Currently this information is split between docs/design/transparency-log-port.md (implementation-level) and ADR-007 (decision rationale). Neither is a "how to use it" guide.
2. Sigstore threat model (docs/security/sigstore-threat-model.md)
Security analysis of the Rekor integration boundary. Should cover:
- What happens if Rekor is compromised (split-view attack, how inclusion proofs defend)
- What happens if Rekor is unavailable (signing still works, logging fails,
--allow-unlogged)
- Trust dependency on the Linux Foundation's operational security
- GHSA-whqx-f9j3-ch6m countermeasure (verify response matches submission)
- Why we don't use Fulcio and the security implications of skipping it
- The DSSE signature vs attestation signature distinction — which signs what
- Rate limiting and retry behavior (429 handling, single retry, exit code 4)
The existing STRIDE threat model (THREAT-MODEL-001-stride.md) covers six trust boundaries but doesn't include the Rekor boundary.
3. Identity lifecycle guide (docs/guides/identity-lifecycle.md)
End-to-end walkthrough of managing an auths identity. Should cover:
auths init — what happens under the hood (key generation, KERI inception, keychain storage)
- Key rotation —
auths id rotate, pre-rotation, what happens to old commits
- Device pairing —
auths pair, QR flow, multi-device signing
- Device revocation — removing a compromised device
- Recovery from device loss — what you can and can't recover
- Attestation expiry and renewal (when TTLs land)
This is currently scattered across CLI --help text, the KERI design doc, and the pairing protocol doc. No single narrative.
4. Migration from GPG/Sigstore (docs/guides/migrating.md)
Practical steps for developers switching from an existing signing setup:
- From GPG: how to keep old GPG-signed commits verifiable while switching new commits to auths, what to do with your GPG key
- From Sigstore/Gitsign: how to switch from gitsign to auths-sign as the signing program, what changes in verification, how Rekor entries differ
- From unsigned commits: the simplest path, just
auths init
The blog post "The Three Paths to Signing a Commit" compares the three approaches but doesn't give migration steps.
Scope
All four are Markdown files in docs/. No code changes. Add entries to mkdocs.yml under the appropriate nav sections.
Context
The Sigstore/Rekor integration is working (DSSE entries, PEM keys, inclusion proofs). The curve-agnostic architecture is documented in
docs/contributing/adding_curves.md. But several user-facing and security-critical docs are missing or scattered.Four docs needed
1. Sigstore integration guide (
docs/guides/sigstore.md)User-facing guide for the
--log sigstore-rekorfeature. Should cover:auths artifact sign --log sigstore-rekorrekor-cli get --log-index <N>transparencysection in.auths.jsonmeans--ci --log sigstore-rekor) differs from the device-key path--allow-unloggedmeans and when to use itCurrently this information is split between
docs/design/transparency-log-port.md(implementation-level) and ADR-007 (decision rationale). Neither is a "how to use it" guide.2. Sigstore threat model (
docs/security/sigstore-threat-model.md)Security analysis of the Rekor integration boundary. Should cover:
--allow-unlogged)The existing STRIDE threat model (
THREAT-MODEL-001-stride.md) covers six trust boundaries but doesn't include the Rekor boundary.3. Identity lifecycle guide (
docs/guides/identity-lifecycle.md)End-to-end walkthrough of managing an auths identity. Should cover:
auths init— what happens under the hood (key generation, KERI inception, keychain storage)auths id rotate, pre-rotation, what happens to old commitsauths pair, QR flow, multi-device signingThis is currently scattered across CLI
--helptext, the KERI design doc, and the pairing protocol doc. No single narrative.4. Migration from GPG/Sigstore (
docs/guides/migrating.md)Practical steps for developers switching from an existing signing setup:
auths initThe blog post "The Three Paths to Signing a Commit" compares the three approaches but doesn't give migration steps.
Scope
All four are Markdown files in
docs/. No code changes. Add entries tomkdocs.ymlunder the appropriate nav sections.