Skip to content

Add transparency-log checkpoint mode alongside git-checkpoint - #13

Open
BenBirt wants to merge 1 commit into
project-oak:mainfrom
BenBirt:claude/git-ratchet-issue-11-cwiu6f
Open

Add transparency-log checkpoint mode alongside git-checkpoint#13
BenBirt wants to merge 1 commit into
project-oak:mainfrom
BenBirt:claude/git-ratchet-issue-11-cwiu6f

Conversation

@BenBirt

@BenBirt BenBirt commented Aug 3, 2026

Copy link
Copy Markdown
Collaborator

Implements the variant proposed in #11: a Merkle transparency log of ref updates, stored in the repository as Git refs and checkpointed with a standard C2SP tlog-checkpoint that standard tlog-witness witnesses can cosign.

Both modes ship; select with --mode on checkpoint/verify/audit and the witness server. git-checkpoint remains the default and is unchanged.

The motivation is witness diversity. In git-checkpoint mode the witness checks Git commit ancestry, which makes the ratchet an enforced property but requires every witness operator to run git-ratchet's own implementation. A tlog checkpoint carries no Git-specific fields, so witnesses that have never heard of git-ratchet can cosign it.

The trade is that a witness verifying only tree consistency will cosign a rollback -- appending a rolled-back state to a log is a consistent operation. The ratchet is preserved by verify walking the logged entries: branch entries must each descend from the last, tags must be logged exactly once. The walk is local and cheap because the log ships with the repository, and it is always performed; there is no cheaper verification path, because a cheaper one would not be safe. TestTlogDetectsBranchRollback asserts both halves of this: the checkpoint succeeds, and verify rejects it.

Design decisions:

  • One log per repository, not per ref. Witness state and operator onboarding are per log, so per-ref logs would multiply the registrations that speaking a standard protocol was meant to avoid.
  • Entries record state (" "), not transitions. The log's ordering already establishes the predecessor; a self-asserted one could not be trusted anyway.
  • The log ref points at a commit, so it can only be advanced by a fast-forward push and an ordinary Git server rejects a rewritten log for free.
  • Merkle math is implemented in-tree against RFC 6962 rather than taking a dependency; no new modules are required.
  • Entry bundles use the tlog-tiles path scheme. Hash tiles are not stored: every consumer holds the whole log, and witnesses are sent their consistency proof in the request.

ML-DSA-44 cosignatures over a tlog-checkpoint use the tlog-cosignature binary struct with its fields carrying their intended values -- log_origin, tree size and root hash -- rather than the repurposing a git-checkpoint body forces.

Not implemented for tlog mode: the decomposed checkpoint-request/checkpoint-store workflow, and therefore the GitHub Issue witness transport. See docs/tlog-variant.md.

    Implements the variant proposed in project-oak#11: a Merkle
    transparency log of ref updates, stored in the repository as Git refs and
    checkpointed with a standard C2SP tlog-checkpoint that standard tlog-witness
    witnesses can cosign.

    Both modes ship; select with --mode on checkpoint/verify/audit and the witness
    server. git-checkpoint remains the default and is unchanged.

    The motivation is witness diversity. In git-checkpoint mode the witness checks
    Git commit ancestry, which makes the ratchet an enforced property but requires
    every witness operator to run git-ratchet's own implementation. A tlog
    checkpoint carries no Git-specific fields, so witnesses that have never heard
    of git-ratchet can cosign it.

    The trade is that a witness verifying only tree consistency will cosign a
    rollback -- appending a rolled-back state to a log is a consistent operation.
    The ratchet is preserved by verify walking the logged entries: branch entries
    must each descend from the last, tags must be logged exactly once. The walk is
    local and cheap because the log ships with the repository, and it is always
    performed; there is no cheaper verification path, because a cheaper one would
    not be safe. TestTlogDetectsBranchRollback asserts both halves of this: the
    checkpoint succeeds, and verify rejects it.

    Design decisions:

    - One log per repository, not per ref. Witness state and operator onboarding
      are per log, so per-ref logs would multiply the registrations that speaking a
      standard protocol was meant to avoid.
    - Entries record state ("<ref> <hash>"), not transitions. The log's ordering
      already establishes the predecessor; a self-asserted one could not be
      trusted anyway.
    - The log ref points at a commit, so it can only be advanced by a fast-forward
      push and an ordinary Git server rejects a rewritten log for free.
    - Merkle math is implemented in-tree against RFC 6962 rather than taking a
      dependency; no new modules are required.
    - Entry bundles use the tlog-tiles path scheme. Hash tiles are not stored:
      every consumer holds the whole log, and witnesses are sent their consistency
      proof in the request.

    ML-DSA-44 cosignatures over a tlog-checkpoint use the tlog-cosignature binary
    struct with its fields carrying their intended values -- log_origin, tree size
    and root hash -- rather than the repurposing a git-checkpoint body forces.

    Not implemented for tlog mode: the decomposed checkpoint-request/checkpoint-store
    workflow, and therefore the GitHub Issue witness transport. See
    docs/tlog-variant.md.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant