specs/001-gpg-event-signing/quickstart.md

Ref: main   Size: 2.0 KiB

# Quickstart: Ed25519 Signing for Event Commits

## Prerequisites

- Rust toolchain (2021 edition)
- git-collab built from source (`cargo build`)

## Setup

### 1. Generate a signing key

```bash
collab init-key
# Output: Ed25519 keypair generated.
#   Private key: ~/.config/git-collab/signing-key
#   Public key:  ~/.config/git-collab/signing-key.pub
#   Share your public key with collaborators: <base64-encoded-pubkey>
```

### 2. Use git-collab as before

All event operations now automatically sign with your key:

```bash
collab issue open -t "Bug: foo is broken"
# Creates a signed event commit — signature embedded in event.json

collab patch create -t "Fix foo" --head abc123
# Also signed automatically
```

### 3. Sync with verification

```bash
collab sync origin
# Fetches remote events, verifies all signatures
# Rejects unsigned or tamper-detected events
# Reports which commits failed and why
```

## What changes in event.json

Before:
```json
{
  "timestamp": "2026-03-21T10:00:00Z",
  "author": { "name": "Alice", "email": "alice@example.com" },
  "action": { "type": "IssueOpen", "title": "Bug", "body": "Details" }
}
```

After:
```json
{
  "timestamp": "2026-03-21T10:00:00Z",
  "author": { "name": "Alice", "email": "alice@example.com" },
  "action": { "type": "IssueOpen", "title": "Bug", "body": "Details" },
  "signature": "base64-encoded-ed25519-signature...",
  "pubkey": "base64-encoded-ed25519-public-key..."
}
```

## Key files

| File | Purpose |
|------|---------|
| `~/.config/git-collab/signing-key` | Ed25519 private key (base64) |
| `~/.config/git-collab/signing-key.pub` | Ed25519 public key (base64) |

## Error scenarios

| Scenario | Behavior |
|----------|----------|
| No signing key, try to create event | Error: "No signing key found. Run `collab init-key` first." |
| Sync receives unsigned commit | Ref rejected: "Commit abc123: missing signature" |
| Sync receives invalid signature | Ref rejected: "Commit abc123: signature verification failed" |
| Sync receives unknown pubkey | Ref rejected: "Commit abc123: unknown signing key" |