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

# 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

# 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

# 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

Root Key: Store offline in HSM or air-gapped system. Only use for:
- Initial repository creation
- Root key rotation (rare)
- Emergency recovery
Snapshot/Targets Keys: Can be stored in secure KMS for automation.
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:

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

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:

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:

./scripts/update-timestamp.sh

Client reports "signature verification failed"

Keys may have rotated without client update. Client should run:

stella trust sync --force

Client reports "unknown target"

Target hasn't been added to repository. Add it:

./scripts/add-target.sh /path/to/target target-name

README.md

Stella TUF Trust Repository Template

WARNING

Directory Structure