Skip to content

docs: Add Sigstore integration guide, threat model, identity lifecycle, and migration guides #172

@bordumb

Description

@bordumb

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions