# CA Migration Spec — v0.8 Internal CA → v0.9 step-ca (grill C-07)

**Status**: spec (must be implemented in v0.10-P14a, REQ-066)
**Gate**: C-07 — blocks v0.10-P14a until this spec is reviewed and a dry-run passes on a test cluster

## Problem

The v0.8 internal Go CA (`internal/security/ca.go`) issues RSA-3072 CA
certs (10-year validity) and ECDSA P-256 server certs (90-day). The CA
material lives at `~/.orca/ca.crt` and `~/.orca/ca.key` (flat layout, D-011).
The v0.9 re-architecture reverses AD-010 and replaces the internal CA with
step-ca (D-101, REQ-076). Existing v0.8 deployments have an internal CA
root + issued server certs that must be migrated without invalidating
trust across the cluster.

## Migration options (decision required before v0.10-P14a implementation)

### Option A — Preserve trust root (RECOMMENDED)

Import the existing `ca.key` into step-ca as the root CA key. The cluster's
trust fingerprint stays unchanged; existing server certs continue to
validate until their natural expiry; new SVIDs are minted by step-ca using
the same root.

```bash
orca upgrade --to-v1.0 --import-ca
# reads ~/.orca/ca.key → step ca init --deployment-type standalone \
#   --remote-management --key $(cat ~/.orca/ca.key)
# issues new SVIDs from step-ca for all existing workloads
```

**Pros**: zero trust breakage; existing server certs keep working; minimal
operator disruption.
**Cons**: requires step-ca to accept an imported RSA-3072 key (step-ca
supports imported keys via `--key` flag; verify in the spike).
**Post-migration**: old `internal/security/ca.go` and `csr.go` are deleted
(v0.10-P14); the `cert_repo` SQLite table (0004) is dropped (step-ca
manages cert state).

### Option B — Forced re-bootstrap

Document that v0.8 certs are invalidated; every cluster re-bootstraps under
step-ca with a new root. Existing workloads are re-enrolled.

**Pros**: clean slate; no legacy RSA root.
**Cons**: trust breakage — every peer's `known_hosts` + CA cert must be
rotated; running workloads lose mTLS until re-enrolled; higher operator
disruption.
**Use case**: only if Option A is technically infeasible (step-ca rejects
the v0.8 key format).

## Pre-flight checks (must pass before migration)

1. `orca doctor` reports zero FAILs on the v0.8 cluster
2. All peers reachable via SSH
3. No in-flight transactions (the migration is stop-the-world for the CA)
4. Snapshot taken (`orca backup --include-master-key`)
5. step-ca installed on the lead via `apt-get install step-ca`
6. `step ca init` dry-run succeeds with the imported key

## Migration steps (Option A)

1. SSH to the lead; install step-ca via apt
2. Run `step ca init --deployment-type standalone --remote-management \
     --key <v0.8-ca-key-path> --provisioner orca-admin`
3. Move the root cert: `cp ~/.orca/ca.crt $ORCA_HOME/cluster/ca.crt`
4. Issue new SVIDs for every registered workload (via `step ca token` +
   `step ca certificate` — the CLI mints the provisioner token using
   `cluster/master.key`-derived material)
5. Deploy the new SVIDs to peers via SSH-push (the v0.9 SSH-push transport)
6. Verify: `orca doctor` reports zero FAILs; CA fingerprint unchanged;
   all workload SVIDs valid
7. Archive the old `internal/security/ca.go`/`csr.go` and `cert_repo` table

## Rollback

If any post-migration invariant fails:
1. Restore the v0.8 snapshot via `orca upgrade --rollback <tarball>`
2. Restart the v0.8 orca daemon on the lead
3. Verify `orca doctor` passes on the v0.8 cluster

The v0.8 internal CA remains functional during the dual-write window
(REQ-090); step-ca is additive until the migration completes.

## Post-migration invariants (must all pass)

- CA fingerprint unchanged (Option A)
- Node count unchanged
- Workload count unchanged
- All SVIDs valid (mTLS handshake succeeds lead↔every peer)
- `orca doctor` zero FAILs
- No `internal/security/ca.go` or `cert_repo` references remain in code

## Decision required

This spec is gated by C-07. The decision (Option A vs B) must be made
before v0.10-P14a implementation. Default: Option A (preserve trust root)
unless the step-ca imported-key spike fails.

## Spike (must run before v0.10-P14a)

Run on a test cluster:
1. Install step-ca on a clean Linux host
2. Generate a v0.8-style RSA-3072 CA key via the v0.8 `internal/security` package
3. Run `step ca init --key <v8-key>` and verify step-ca accepts it
4. Mint a test SVID via `step ca token` + `step ca certificate`
5. Verify the SVID validates against the imported root

If the spike fails, fall back to Option B (forced re-bootstrap) and document.