# Stella TUF Trust Repository Template

This directory contains a template for creating a TUF (The Update Framework) repository
for distributing trust anchors to StellaOps clients.

## WARNING

**The sample keys in this template are for DEMONSTRATION ONLY.**
**DO NOT USE THESE KEYS IN PRODUCTION.**

Generate new keys using the `scripts/init-tuf-repo.sh` script before deploying.

## Directory Structure

```
stella-trust/
├── root.json           # Root metadata (rotates rarely, high ceremony)
├── snapshot.json       # Current target versions
├── timestamp.json      # Freshness indicator (rotates frequently)
├── targets.json        # Target file metadata
└── targets/
    ├── rekor-key-v1.pub              # Rekor log public key
    ├── fulcio-chain.pem              # Fulcio certificate chain
    └── sigstore-services-v1.json     # Service endpoint map
```

## Quick Start

### 1. Initialize a New Repository

```bash
# Generate new signing keys (do this in a secure environment)
./scripts/init-tuf-repo.sh /path/to/new-repo

# This creates:
# - Root key (keep offline, backup securely)
# - Snapshot key
# - Timestamp key
# - Targets key
# - Initial metadata files
```

### 2. Add a Target

```bash
# Add Rekor public key as a target
./scripts/add-target.sh /path/to/rekor-key.pub rekor-key-v1

# Add service map
./scripts/add-target.sh /path/to/sigstore-services.json sigstore-services-v1
```

### 3. Publish Updates

```bash
# Update timestamp (do this regularly, e.g., daily)
./scripts/update-timestamp.sh

# The timestamp.json should be refreshed frequently to maintain client trust
```

### 4. Deploy

Host the repository contents on a web server:
- HTTPS required for production
- Set appropriate cache headers (short TTL for timestamp.json)
- Consider CDN for global distribution

## Key Management

### Key Hierarchy

```
Root Key (offline, high ceremony)
├── Snapshot Key (can be online)
├── Timestamp Key (must be online for automation)
└── Targets Key (can be online)
```

### Security Recommendations

1. **Root Key**: Store offline in HSM or air-gapped system. Only use for:
   - Initial repository creation
   - Root key rotation (rare)
   - Emergency recovery

2. **Snapshot/Targets Keys**: Can be stored in secure KMS for automation.

3. **Timestamp Key**: Must be accessible for automated updates. Use short-lived
   credentials and rotate regularly.

### Key Rotation

See `docs/operations/key-rotation-runbook.md` for detailed procedures.

Quick rotation example:
```bash
# Add new key while keeping old one active
./scripts/rotate-key.sh targets --add-key /path/to/new-key.pub

# After grace period (clients have updated), remove old key
./scripts/rotate-key.sh targets --remove-key old-key-id
```

## Client Configuration

Configure StellaOps clients to use your TUF repository:

```yaml
attestor:
  trust_repo:
    enabled: true
    tuf_url: https://trust.yourcompany.com/tuf/
    service_map_target: sigstore-services-v1
    rekor_key_targets:
      - rekor-key-v1
```

Or via CLI:
```bash
stella trust init \
  --tuf-url https://trust.yourcompany.com/tuf/ \
  --service-map sigstore-services-v1 \
  --pin rekor-key-v1
```

## Metadata Expiration

Default expiration times (configurable in init script):
- `root.json`: 365 days
- `snapshot.json`: 7 days
- `timestamp.json`: 1 day
- `targets.json`: 30 days

Clients will refuse to use metadata past its expiration. Ensure automated
timestamp updates are running.

## Troubleshooting

### Client reports "metadata expired"
The timestamp.json hasn't been updated. Run:
```bash
./scripts/update-timestamp.sh
```

### Client reports "signature verification failed"
Keys may have rotated without client update. Client should run:
```bash
stella trust sync --force
```

### Client reports "unknown target"
Target hasn't been added to repository. Add it:
```bash
./scripts/add-target.sh /path/to/target target-name
```

## References

- [TUF Specification](https://theupdateframework.github.io/specification/latest/)
- [StellaOps Trust Documentation](docs/modules/attestor/tuf-integration.md)
- [Key Rotation Runbook](docs/operations/key-rotation-runbook.md)