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/README.md
+++ b/README.md
@ -0,0 +1,129 @@
+# Git OpenTimestamp Hook
+
+Automatically generate and manage [OpenTimestamp](https://opentimestamps.org/) proofs for git commits.
+
+## What It Does
+
+- **Post-commit hook**: Creates cryptographic proof for every commit
+- **Pre-commit backfill**: Upgrades historical proofs to Bitcoin-attested status
+- **Proof chaining**: Links commits together for full history integrity
+- **Smart caching**: Minimizes network calls after initial backfill
+
+Proofs are stored in `.ots/` and can be versioned alongside your code for tamper-evident history.
+
+## Quick Install
+
+### Recommended: Self-Contained Hooks
+
+```bash
+# Clone or download this skill
+git clone <repository-url>
+cd git-ots-hook
+
+# Install both hooks (single command)
+./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! The hooks are now installed and will automatically timestamp every commit.
+
+### Legacy: Script-Based Installation
+
+The older `scripts/` directory is still available but deprecated. See `SKILL.md` for details.
+
+## Manual Installation
+
+If you prefer to install hooks manually without the installer:
+
+### 1. Copy Hook Files
+
+```bash
+cp hooks/post-commit /path/to/your/repo/.git/hooks/
+cp hooks/pre-commit /path/to/your/repo/.git/hooks/
+chmod +x /path/to/your/repo/.git/hooks/post-commit
+chmod +x /path/to/your/repo/.git/hooks/pre-commit
+```
+
+### 2. Setup .gitignore
+
+Add to your `.gitignore`:
+```
+.ots/.attestation-cache
+```
+
+### 3. Commit Initial Proofs
+
+```bash
+git add .ots/
+git commit -m "Add OpenTimestamp proofs"
+```
+
+## Prerequisites
+
+Install the OpenTimestamp client:
+
+```bash
+# Recommended: Python CLI
+pipx install opentimestamps-client
+
+# Alternative: Node.js package
+npm install -g @opentimestamps/ots
+```
+
+Verify installation:
+```bash
+ots --version
+```
+
+## Generated Files
+
+```
+repo/
+├── .ots/
+│   ├── <commit-hash>.ots    # Individual proof per commit
+│   ├── proof.ots            # Latest commit proof
+│   ├── prev-commit.txt      # Previous commit reference
+│   ├── commit-chain.txt     # Full commit chain
+│   └── .attestation-cache   # Local cache (gitignore this)
+└── ...
+```
+
+## Verification
+
+Verify a proof:
+```bash
+ots verify .ots/<commit-hash>.ots
+```
+
+Check attestation status:
+```bash
+./scripts/check-attestation.sh .ots/<commit-hash>.ots
+# Output: "attested" or "pending"
+```
+
+## How It Works
+
+1. **Commit created** → Post-commit hook runs
+2. **Proof generated** → `ots stamp` creates `.ots` file
+3. **Submitted to calendars** → 4+ remote calendars receive hash
+4. **Bitcoin anchoring** → Calendars batch and anchor to Bitcoin (~10 min)
+5. **Attestation** → Proof becomes fully verifiable against Bitcoin blockchain
+
+## Performance
+
+- **First backfill**: 30-60s (scans history, contacts calendars)
+- **Subsequent commits**: 10-15s (cached status skips redundant calls)
+- **Cache**: 1-hour validity, 10-min recheck for pending proofs
+
+## License
+
+MIT
+
+## Links
+
+- [OpenTimestamp](https://opentimestamps.org/)
+- [ots Client](https://github.com/opentimestamps/opentimestamps-client)