Hosted Backups Design

Status: design. Target: ADR-0030.

Goal

Two independent backup paths so a single operator failure cannot lose founder data.

1. Founder-owned GitHub mirror. Every commit on the tenant volume is pushed to a founder-owned GitHub repo within 60 seconds. This is the canonical recovery path.
2. Encrypted daily snapshot to founder-owned S3. A nightly tarball encrypted with the tenant DEK, uploaded to a bucket the founder controls (BYO bucket + IAM role).

Why founder-owned

If we hold the only copy, we are the single point of failure. Both paths land in storage the founder controls. We hold a write role, not a read role.

Path 1: GitHub mirror

Setup

1. Founder connects GitHub via OAuth (Settings → Backups).
2. We create (or accept) a private repo lycato-<slug> under the founder's account or org.
3. We store the install token in the tenant secret store (encrypted with the tenant DEK).

Per-commit push

• A post-commit hook in the tenant volume's git config pushes to the founder GitHub remote.
• On push failure, we retry with exponential backoff (max 6 attempts over ~10 minutes), then alert (push notification + email).
• The push includes the full commit history, not just deltas — the GitHub repo is always a complete mirror.

Recovery

If the tenant container is gone, the founder clones the GitHub repo locally and runs:

git clone [email protected]:<founder>/lycato-<slug>.git company
cd company
lycato doctor                       # confirms repo health
lycato migrate                      # if schema version is behind
lycato cockpit                      # back to work

The founder is now running self-hosted. They can stay there or provision a fresh hosted tenant and push the repo in.

Path 2: Encrypted S3 snapshot

Why also have S3

The GitHub mirror covers the markdown + git history. It does NOT cover:

• .founder/keys.env — gitignored on purpose.
• .founder/runs/*.jsonl — gitignored telemetry.
• Lycato/cache/index.json — gitignored derived data.
• inbox/attachments/ audio files — gitignored (large blobs).

A full S3 snapshot covers everything, encrypted, so a true "clone the box" recovery is possible.

Format

• Daily at 03:30 UTC.
• tar czf - <tenant-volume>/ piped through age -r <tenant-recipient> -o snapshot-<date>.tar.gz.age.
• Uploaded to s3://<founder-bucket>/lycato/<tenant-slug>/snapshot-<date>.tar.gz.age.

Encryption

• We use age (not GPG) for the tarball encryption.
• The recipient key is the tenant's public key; the private key is derived from the tenant DEK at restore time.
• We do not hold the founder's S3 bucket key. We have a write role via IAM trust — the founder can rotate or revoke at any time.

Retention

• Founder plan: 7 daily snapshots, 4 weekly snapshots.
• Team plan: 30 daily snapshots, 12 weekly snapshots, 12 monthly snapshots.
• Lifecycle policy enforced via S3 lifecycle rules (we set them on the bucket on first backup).

Restore

Founder-initiated only:

1. Cockpit → Settings → Restore from snapshot → pick date.
2. We provision a temporary container.
3. Container fetches the encrypted tarball, decrypts with the tenant DEK, mounts a new volume.
4. Founder reviews; on confirm, the new volume replaces the live one.

No operator-initiated restore. The founder owns the path back.

Disaster scenarios

Audit

Every backup attempt + every restore writes to:

1. Tenant audit log (.founder/audit/YYYY-MM.jsonl).
2. Control-plane audit_ops table (operator-visible).
3. Push notification to founder for restores.

What's intentionally absent

• Point-in-time restore (PITR). Daily granularity is sufficient.
• Cross-region replication of our operator-side last-resort backup. Out of scope at launch.
• Customer-managed encryption keys for the S3 path. Founder owns the bucket; that's already a strong control.