Robots/git-ots
6
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
No description
12 commits 1 branch 0 tags 111 KiB
  • Shell 100%
Find a file
Exact
pi b65177f785 Stamp commit hash as hex string; add pure-bash verify helper 
Switch the stamped preimage from the raw binary of the commit hash
(python3 bytes.fromhex) to its ASCII hex string. The anchored digest is now
SHA256("<hash>") instead of SHA256(bytes.fromhex(hash)), which:
  - removes the undeclared python3 dependency (pure bash: printf '%s')
  - simplifies future verification (hash the hex string; no hex->binary step)

New hooks/verify (pure bash, no python) verifies a commit proof and handles
both preimage conventions for backward compatibility:
  - detects the convention locally by matching candidate digests against the
    digest stored in the .ots (no Bitcoin round-trip), then runs
    `ots verify -d` exactly once
  - legacy binary proofs (stamped before this change) are recognised
    automatically, so a repo may contain a mix of both
  - null-safe pure-bash hex decode (bytes flow through a pipe, never a var)

install.sh now deploys .ots/verify alongside the hooks.

Docs: replace the flawed "grep PendingAttestation, 0=attested" attestation
check with the positive BitcoinBlockHeaderAttestation marker, document the
verify helper and the `ots verify -d` one-liner, and note the hex preimage.
2026-07-23 01:26:59 +02:00
hooks Stamp commit hash as hex string; add pure-bash verify helper 2026-07-23 01:26:59 +02:00
.gitignore Initial commit: Git OpenTimestamp hooks skill 2026-03-08 00:12:45 +01:00
AGENTS.md Stamp commit hash as hex string; add pure-bash verify helper 2026-07-23 01:26:59 +02:00
README.md Stamp commit hash as hex string; add pure-bash verify helper 2026-07-23 01:26:59 +02:00
SKILL.md Stamp commit hash as hex string; add pure-bash verify helper 2026-07-23 01:26:59 +02:00

README.md

Git OpenTimestamp Hook

Automatically generate OpenTimestamp proofs for git commits with full Bitcoin attestation.

⚠️ Requirements

Required: opentimestamps-client (ots CLI)

pipx install opentimestamps-client

Note: The Node.js @opentimestamps/ots package is not supported - it only creates local proofs without calendar submission or Bitcoin attestation. For tamper-evident timestamps, you must use the Python opentimestamps-client.

Quick Install

# Clone this repository
git clone <repository-url>
cd git-ots

# Install hooks (requires ots CLI)
./hooks/install.sh /path/to/your/repo

# Commit the proofs
cd /path/to/your/repo
git add .ots/
git commit -m "Add OpenTimestamp proofs"

That's it! Every commit will now be timestamped and anchored to Bitcoin.

Manual Installation

# Copy hooks
cp hooks/post-commit .git/hooks/post-commit
cp hooks/pre-commit .git/hooks/pre-commit
chmod +x .git/hooks/post-commit .git/hooks/pre-commit

# Copy the verify helper next to the proofs
mkdir -p .ots && cp hooks/verify .ots/verify && chmod +x .ots/verify

# Setup .gitignore
echo ".ots/.attestation-cache" >> .gitignore
echo ".ots/.backfill-cursor" >> .gitignore

What You Get

  • Automatic timestamping - Every commit gets a cryptographic proof
  • Bitcoin attestation - Proofs anchored to Bitcoin blockchain (~10 min)
  • Full history - Backfill hook upgrades all historical commits
  • Smart caching - Minimal network overhead after initial setup
  • Tamper-evident - Anyone can verify your commit history

Generated Files

repo/
├── .ots/
│   ├── <commit-hash>.ots   # Individual proof (commit this)
│   ├── proof.ots           # Latest proof (commit this)
│   ├── prev-commit.txt     # Chain link (commit this)
│   ├── commit-chain.txt    # Full chain (commit this)
│   ├── verify              # Verify helper (commit this)
│   ├── .attestation-cache  # Local cache (ignore this)
│   └── .backfill-cursor    # Backfill cursor (ignore this)
└── ...

Verification

Check a proof:

ots info .ots/<commit-hash>.ots | grep -c "BitcoinBlockHeaderAttestation"
# >=1 = Bitcoin-attested, 0 = still pending

Verify attestation:

# Installed helper (auto-detects preimage convention, pure bash):
.ots/verify <commit-hash> .ots/<commit-hash>.ots

# Or directly with ots:
HASH=<commit-hash>
ots verify -d "$(printf '%s' "$HASH" | sha256sum | cut -d' ' -f1)" .ots/$HASH.ots

Upgrade pending proofs:

ots upgrade .ots/<commit-hash>.ots

How It Works

  1. You make a git commit
  2. Post-commit hook extracts commit hash
  3. Hash submitted to 4+ remote calendar servers
  4. Calendars aggregate and anchor to Bitcoin
  5. After ~10 min: proof becomes Bitcoin-attested
  6. Pre-commit hook upgrades old proofs before new commits

Performance

  • First backfill: 30-60s (full history scan)
  • Normal commits: 10-15s (cached, minimal network)
  • Attestation: ~10 min (Bitcoin block time)

Uninstall

rm .git/hooks/post-commit .git/hooks/pre-commit

Links

License

MIT