Initial commit: Git OpenTimestamp hooks skill

2026-03-08 00:12:45 +01:00 · 2026-03-08 00:12:45 +01:00 · eec64d16c6
commit eec64d16c6
13 changed files with 1145 additions and 0 deletions
--- a/SKILL.md
+++ b/SKILL.md
@ -0,0 +1,163 @@
+---
+name: git-ots-hook
+description: Install and manage OpenTimestamp git hooks that generate cryptographic proof for every commit. Use when you need to add tamper-evident timestamps to git commits using the OpenTimestamp protocol. Supports both ots CLI and nodejs fallback.
+---
+
+# Git OpenTimestamp Hook
+
+Automatically generates OpenTimestamp proofs for git commits via git hooks.
+
+## Quick Start (Recommended)
+
+**New: Self-contained hooks** - No external dependencies, simple installation:
+
+```bash
+# Install both hooks (post-commit + pre-commit backfill)
+./hooks/install.sh /path/to/repo
+
+# Or from repo root
+./hooks/install.sh .
+```
+
+## Legacy Installation
+
+The older `scripts/` directory is still available for backward compatibility, but the new `hooks/` directory is recommended for simpler deployment.
+
+## What It Does
+
+- **Post-commit hook** (`hooks/post-commit`): Generates `.ots/<commit-hash>.ots` for each new commit
+- **Pre-commit backfill** (`hooks/pre-commit`): Before each commit, upgrades all historical proofs to attested status
+- Creates `.ots/proof.ots` with latest commit proof
+- Stores commit chain in `.ots/commit-chain.txt`
+- Works with `ots` CLI (preferred) or `@opentimestamps/ots` node package (fallback)
+- **Self-contained**: No external script dependencies, simple drop-in installation
+
+## Prerequisites
+
+Install one of:
+
+```bash
+# Option 1: ots CLI (recommended)
+git clone https://github.com/opentimestamps/opentimestamps-client
+cd opentimestamps-client
+pipx install .
+
+# Option 2: Node.js fallback
+npm install -g @opentimestamps/ots
+```
+
+## Generated Files
+
+The hooks create:
+
+```
+repo/
+├── .ots/
+│   ├── proof.ots           # Timestamp proof for latest commit
+│   ├── <commit-hash>.ots   # Individual proof for each commit
+│   ├── prev-commit.txt     # Previous commit hash (for chaining)
+│   └── commit-chain.txt    # Full commit chain mapping
+└── ...
+```
+
+Proof files include:
+- Commit hash timestamp (OpenTimestamp format)
+- Bitcoin attestation (after ~10 min confirmation)
+- Commit chain references
+
+## Manual Usage
+
+### New Self-Contained Hooks (Recommended)
+
+**Install hooks:**
+```bash
+./hooks/install.sh /path/to/repo
+```
+
+**Manual hook installation:**
+Copy `hooks/post-commit` and `hooks/pre-commit` directly to `.git/hooks/`
+
+### Legacy Scripts (Deprecated)
+
+**Generate proof for a specific commit:**
+```bash
+./scripts/generate-proof.sh <commit-hash> [output-file]
+```
+
+**Backfill proofs for entire history:**
+```bash
+./scripts/backfill-proofs.sh /path/to/repo
+```
+
+**Setup .gitignore (excludes cache only, keeps proofs):**
+```bash
+./scripts/setup-gitignore.sh /path/to/repo
+```
+
+**Check proof attestation status:**
+```bash
+./scripts/check-attestation.sh .ots/<commit-hash>.ots
+# Output: "attested" or "pending"
+```
+
+Example:
+```bash
+./scripts/generate-proof.sh abc123def456 .ots/proof.ots
+./scripts/backfill-proofs.sh .
+./scripts/setup-gitignore.sh .
+```
+
+## Uninstall
+
+```bash
+rm /path/to/repo/.git/hooks/post-commit
+```
+
+## Notes
+
+### Versioning Proofs (Recommended)
+
+To include proofs in your repository (recommended for tamper-evidence):
+
+```bash
+# Commit proofs with your code
+git add .ots/
+git commit -m "Add OpenTimestamp proofs"
+```
+
+The `.ots/` directory contains:
+- `*.ots` - Binary proof files (commit these)
+- `commit-chain.txt` - Commit chain mapping (commit this)
+- `prev-commit.txt` - Latest previous commit (commit this)
+- `.attestation-cache` - Local cache (add to `.gitignore`)
+
+**Recommended `.gitignore`:**
+```
+.ots/.attestation-cache
+```
+
+### Performance
+
+- **Pre-commit backfill** can slow down commits on large histories
+- First backfill: Full scan + calendar calls (~30-60s)
+- Subsequent commits: Cached status skips calendar calls (~10-15s)
+- Cache expires after 1 hour, re-checks pending proofs after 10 min
+
+### Other Notes
+
+- Hook is silent if neither `ots` nor node package is found
+- Proofs become "attested" after ~10 min (Bitcoin confirmation)
+
+## Troubleshooting
+
+**Hook not running?**
+- Check it's executable: `chmod +x .git/hooks/post-commit`
+- Test manually: `.git/hooks/post-commit`
+
+**Proof not generating?**
+- Verify `ots` or `@opentimestamps/ots` is installed
+- Check hook output: `git commit` shows `[ots]` messages
+
+**Want auto-commit proofs?**
+- Modify the hook to run `git add .ots/proof.ots && git commit --amend --no-edit`
+- ⚠️ This changes commit history - use with caution