specs/003-key-trust-allowlist/quickstart.md

Ref: main   Size: 2.2 KiB

# Quickstart: Key Trust Allowlist

**Date**: 2026-03-21 | **Feature**: 003-key-trust-allowlist

## Prerequisites

- Rust toolchain (edition 2021)
- Existing git-collab build: `cargo build`
- A signing keypair: `collab init-key`

## Implementation Order

### Step 1: Add `Untrusted` variant to `VerifyStatus`

File: `src/signing.rs`

Add `Untrusted` to the `VerifyStatus` enum. Update any exhaustive match arms in `src/sync.rs` and `src/signing.rs` that pattern-match on `VerifyStatus` (the compiler will find them).

### Step 2: Add error variant

File: `src/error.rs`

Add `UntrustedKey(String)` variant to the `Error` enum.

### Step 3: Create `src/trust.rs`

New file with these public functions:

```rust
pub fn trusted_keys_path(repo: &Repository) -> PathBuf
pub fn load_trust_policy(repo: &Repository) -> Result<TrustPolicy, Error>
pub fn add_key(repo: &Repository, pubkey: &str, label: Option<&str>) -> Result<(), Error>
pub fn remove_key(repo: &Repository, pubkey: &str) -> Result<(String, Option<String>), Error>
pub fn list_keys(repo: &Repository) -> Result<Vec<TrustedKey>, Error>
pub fn validate_pubkey(pubkey_b64: &str) -> Result<(), Error>
pub fn check_trust(policy: &TrustPolicy, results: &[SignatureVerificationResult]) -> Vec<SignatureVerificationResult>
```

### Step 4: Add CLI commands

File: `src/cli.rs`

Add `KeyCmd` enum and `Key(KeyCmd)` variant to `Commands`.

### Step 5: Wire CLI to trust module

File: `src/lib.rs`

Add `pub mod trust;` and handle `Commands::Key(cmd)` in `run()`.

### Step 6: Integrate trust into sync

File: `src/sync.rs`

In `reconcile_refs()`, after `verify_ref()` succeeds, load `TrustPolicy` and run `check_trust()`. Reject refs with untrusted keys.

### Step 7: Tests

- Unit tests in `src/trust.rs` (`#[cfg(test)]` module)
- Integration test in `tests/trust_test.rs`

## Build and Test

```bash
cargo build
cargo test
cargo test --test trust_test
```

## Manual Verification

```bash
# Generate key if needed
collab init-key

# Add your own key
collab key add --self --label "me"

# List keys
collab key list

# Add a teammate's key
collab key add dGhpcyBpcyBhIHRlc3Qga2V5IGJ5dGVzMTIzNDU= --label "Alice"

# Remove a key
collab key remove dGhpcyBpcyBhIHRlc3Qga2V5IGJ5dGVzMTIzNDU=

# Sync (should warn if no trusted keys configured)
collab sync
```