Robots/git-ots
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Remove Node.js hooks, require ots CLI only

Browse source 
- Delete hooks/post-commit-node (local proofs only, no attestation)
- Delete hooks/pre-commit-node (no upgrade support)
- Update hooks/install.sh to require ots CLI (no fallback)
- Update documentation with clear ots CLI requirement
- Add prominent warnings about Node.js limitations

Rationale: The @opentimestamps/ots Node.js package only creates
local proofs without calendar submission or Bitcoin attestation.
For tamper-evident timestamps, ots CLI is the only complete
implementation. No partial/fallback implementations.
This commit is contained in:
Otto 2026-03-08 00:50:32 +01:00
parent b1e305d831
commit b4e2eb3c12
6 changed files with 203 additions and 357 deletions
Download patch file Download diff file Expand all files Collapse all files

91
AGENTS.md
View file

@ -2,85 +2,88 @@
Quick reference for AI agents installing OpenTimestamp hooks.
## When to Use
## ⚠️ Hard Requirement
Use this skill when the user wants to:
- Add tamper-evident timestamps to git commits
- Create cryptographic proof of commit history
- Anchor commits to Bitcoin blockchain via OpenTimestamp
## Installation (Auto-Detect)
**`ots` CLI must be installed.** No fallback available.
```bash
# 1. Install prerequisites (ots CLI recommended)
pipx install opentimestamps-client
```
# 2. Install hooks (auto-detects available tools)
The Node.js `@opentimestamps/ots` package is **not a valid alternative** - it only creates local proofs without calendar submission or Bitcoin attestation.
## Installation
```bash
# 1. Verify/install prerequisites
if ! command -v ots &> /dev/null; then
pipx install opentimestamps-client
fi
# 2. Install hooks
./hooks/install.sh .
# 3. Commit proofs to repository
# 3. Commit proofs
git add .ots/ .gitignore
git commit -m "Add OpenTimestamp proofs for commit history"
```
## Installation Modes
The installer auto-detects and installs matching hooks:
| Detected | Hooks Installed | Attestation |
|----------|----------------|-------------|
| `ots` CLI | `post-commit-ots`, `pre-commit-ots` | Full Bitcoin |
| `@opentimestamps/ots` (node) | `post-commit-node`, `pre-commit-node` | Local only |
**Recommendation:** Always prefer ots CLI for production use.
## Manual Installation
### ots CLI Mode
```bash
cp hooks/post-commit-ots .git/hooks/
cp hooks/pre-commit-ots .git/hooks/
chmod +x .git/hooks/*
cp hooks/post-commit-ots .git/hooks/post-commit
cp hooks/pre-commit-ots .git/hooks/pre-commit
chmod +x .git/hooks/post-commit .git/hooks/pre-commit
```
### Node.js Mode
```bash
cp hooks/post-commit-node .git/hooks/
cp hooks/pre-commit-node .git/hooks/
chmod +x .git/hooks/*
npm install @opentimestamps/ots # If not already installed
**.gitignore:**
```
.ots/.attestation-cache
```
## Key Files
| File | Purpose | Version? |
|------|---------|----------|
| `hooks/post-commit-ots` | Post-commit hook (ots CLI) | Yes |
| `hooks/pre-commit-ots` | Backfill hook (ots CLI) | Yes |
| `hooks/post-commit-node` | Post-commit hook (Node.js) | Yes |
| `hooks/pre-commit-node` | Backfill hook (Node.js) | Yes |
| `hooks/install.sh` | Auto-detect installer | Yes |
| `hooks/post-commit-ots` | Post-commit hook | Yes |
| `hooks/pre-commit-ots` | Backfill hook | Yes |
| `hooks/install.sh` | Installer (checks ots) | Yes |
| `.ots/*.ots` | Individual proofs | Yes |
| `.ots/proof.ots` | Latest proof reference | Yes |
| `.ots/commit-chain.txt` | Commit chain | Yes |
| `.ots/.attestation-cache` | Local cache | No |
| `node_modules/` | Node dependencies (if used) | No |
## Verification
```bash
# Check if proof is attested
# Check attestation status
ots info .ots/<commit-hash>.ots | grep -c "PendingAttestation"
# 0 = attested, >0 = pending
# Verify proof
ots verify .ots/<commit-hash>.ots
# Upgrade pending proofs
ots upgrade .ots/<commit-hash>.ots
```
## Notes
## Important Notes
- Proofs take ~10 min to become Bitcoin-attested
- Cache avoids redundant calendar calls (1-hour validity)
- Pre-commit backfill adds ~10-15s to commit time
- Node.js version creates local proofs only (no calendar submission)
- Safe to commit `.ots/` directory (binary proofs are ~500-900B each)
- **No Node.js fallback** - ots CLI is mandatory
- **Attestation time:** ~10 min (Bitcoin confirmation)
- **Cache validity:** 1 hour, re-checks pending after 10 min
- **Commit overhead:** ~10-15s after initial backfill
- **Proof size:** ~500-900 bytes each
- **Safe to commit:** Yes, `.ots/` directory should be versioned
## Why ots CLI is Required
| Feature | ots CLI | Node.js Package |
|---------|---------|-----------------|
| Calendar submission | ✓ | ✗ |
| Bitcoin attestation | ✓ | ✗ |
| Proof upgrade | ✓ | ✗ |
| Verification | ✓ | ✗ |
| Local proofs | ✓ | ✓ |
The Node.js package only creates self-attested local proofs with no third-party verification. For tamper-evident timestamps anchored to Bitcoin, ots CLI is the only complete implementation.