Otto b4e2eb3c12 Remove Node.js hooks, require ots CLI only

- 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.

2026-03-08 00:50:32 +01:00

2.3 KiB

Raw Blame History

AI Agent Instructions

Quick reference for AI agents installing OpenTimestamp hooks.

⚠️ Hard Requirement

ots CLI must be installed. No fallback available.

pipx install opentimestamps-client

The Node.js @opentimestamps/ots package is not a valid alternative - it only creates local proofs without calendar submission or Bitcoin attestation.

Installation

# 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
git add .ots/ .gitignore
git commit -m "Add OpenTimestamp proofs for commit history"

Manual Installation

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

.gitignore:

.ots/.attestation-cache

Key Files

File	Purpose	Version?
`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

Verification

# 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

Important Notes

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.

2.3 KiB Raw Blame History