# 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

```bash
# Clone or download this skill
git clone <repository-url>
cd git-ots-hook

# Install both hooks (auto-detects ots CLI or Node.js)
./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.

## Manual Installation

### For ots CLI (Recommended)

```bash
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
```

### For Node.js (Local proofs only)

```bash
cp hooks/post-commit-node .git/hooks/post-commit
cp hooks/pre-commit-node .git/hooks/pre-commit
chmod +x .git/hooks/post-commit .git/hooks/pre-commit
```

### Setup .gitignore

```
.ots/.attestation-cache
node_modules/
```

### 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)