Skip to content

Platform site archive (pre-deprovision backup) ​

Automated export of hub state before Terraform destroy during platform site deprovision. Supports suspend/cancel billing flows where a customer hub is torn down and later reprovisioned with the same site_id.

Goals ​

  • Capture a full site backup JSON while D1 and the Worker still exist.
  • Store archives in platform R2 (not a new D1 database).
  • Restore on reactivation via existing POST /api/site/restore or wizard step 1.
  • Support reinstate within about 12 months for the same owner (archive_r2_key on site_billing, automatic restore after reprovision) — see platform-billing.md.
  • Keep cost low: JSON is typically hundreds of KB; optional media copy is separate.

What is archived ​

DataIn JSON backupNotes
House Guide catalog (draft content)YesSame as Settings → Download full site backup
Site profile, bins, petsYes
Hub secrets (Wi‑Fi, PIN, lockbox, calendar)YesPlatform encrypts at rest in R2 (see below)
Sitter settings + scheduled staysYes
Guide photo files (R2)In the media zip (#842)GET /api/platform/site-archive-media → {site_id}/site-media-{exportedAt}.zip, restored automatically
Appliance manual PDFsIn the media zip (#842)Same zip, under media/appliance-manuals/
Worker platform secretsNoRegenerated on provision

Why not a D1 database for archived media? ​

  • Cost: D1 charges on stored rows; large binaries belong in R2 (cheaper object storage).
  • Phase 1: JSON only — minimal cost, good enough for seasonal pause.
  • Phase 2 (#842, done): the hub exports photos and PDFs as one zip (the same format as the owner's backup download) to GET /api/platform/site-archive-media. The archive script stores it next to the JSON and records mediaArchiveKey in the JSON and in latest.json. This is best effort: a hub on an older Worker, or a failed download, still archives the JSON, and the job logs a ::warning::. A large media library is built in the Worker's memory, so a hub with hundreds of MB of PDFs may fail the zip export; the JSON is still kept.

Flow ​

mermaid
sequenceDiagram
  participant CI as Deprovision CI
  participant Hub as Hub Worker
  participant R2 as Platform archive R2

  CI->>Hub: GET {worker_api_origin}/api/platform/site-archive
  Note over CI,Hub: Access service token + archive secret
  Hub->>Hub: buildSiteBackupPayload(full)
  Hub-->>CI: JSON backup
  CI->>R2: Put site-backup.json + latest.json
  CI->>CI: terraform destroy ...

Worker endpoint ​

MethodPathAuth
GET/api/platform/site-archive on the Worker (worker_api_origin, e.g. https://lovely-home-hub-api-{site}.….workers.dev)X-Platform-Site-Archive-Secret header matches Worker secret PLATFORM_SITE_ARCHIVE_SECRET

Do not call the custom Pages hostname. Hub GitHub builds also upload functions/api/platform, and that operator route returns { error: "NOT_FOUND" } on customer hubs. Archive CI uses Terraform worker_api_origin; hub deploys prune those Functions so a Pages URL would proxy to the Worker.

  • Does not require owner device mode (CI has no sitter cookie).
  • Must be called before Terraform destroy removes D1.
  • Blocked on demo hub (DEMO_READ_ONLY).

One secret per hub (#1166) ​

PLATFORM_SITE_ARCHIVE_SECRET on platform Pages and in GitHub Actions is the master. A hub Worker never holds it. Each hub's PLATFORM_SITE_ARCHIVE_SECRET is its own value, HMAC-SHA256(master, "hub-archive:{site_id}") (functions/lib/hubArchiveSecret.js). The platform and the archive and restore scripts work out that value for the hub they call. So anyone who reads one hub's secret can only call that hub's platform routes, not every hub's.

The hub Worker code is unchanged: it still compares the header with its own secret.

The provision step (scripts/set-worker-secrets-from-terraform.mjs) sets the hub's own value when the repo secret is set. The legacy default Worker (prod, not a registry site) gets no archive secret, because the platform never calls it.

Uses wrangler secret put on live Workers; if a Worker has never been deployed (e.g. sandbox), falls back to wrangler versions secret put so the secret is stored for the next deploy.

Existing Workers, or after changing the master: run:

bash
# Local (same CLOUDFLARE_API_TOKEN as deploy)
export PLATFORM_SITE_ARCHIVE_SECRET='…'
node scripts/sync-platform-site-archive-secret.mjs

Or use GitHub Actions → Platform sync archive secret (syncs all hub Workers, or one --site via workflow input).

Rotating the master. Before #1166 every hub held the master itself, so treat the old master as known to every hub. Rotate it once: set a new value in the GitHub secret and on platform Pages (node scripts/set-platform-pages-archive-secret.mjs, then a production redeploy), then run the sync above. Until the sync finishes, platform calls to hubs (Account → Stays and Cleaners, suspend, usage, archive) are refused.

CI script ​

bash
node scripts/archive-hub-site-backup.mjs <site_id>
node scripts/archive-hub-site-backup.mjs <site_id> --skip-platform-archive

Skip (regression / sandbox teardown): Disposable e2e-* lifecycle hubs do not need a platform JSON copy. Set SKIP_PLATFORM_HUB_ARCHIVE_FOR_E2E=1 on the job (Hub lifecycle billing deprovision and E2E sandbox cleanup do this), or SKIP_PLATFORM_HUB_ARCHIVE=1 / composite input skip_platform_hub_archive: true to skip for any site. scripts/deprovision-hub-site.mjs and billing-deprovision-hub honour the same flags.

Environment:

VariablePurpose
SKIP_PLATFORM_HUB_ARCHIVEWhen truthy (1 / true / yes), skip upload for any site
SKIP_PLATFORM_HUB_ARCHIVE_FOR_E2EWhen truthy, skip upload only when site_id matches e2e-*
PLATFORM_SITE_ARCHIVE_SECRETThe platform master; the script derives the hub's own secret from it
PLATFORM_HEALTH_CF_ACCESS_CLIENT_IDAccess service token (edge)
PLATFORM_HEALTH_CF_ACCESS_CLIENT_SECRETAccess service token (edge)
PLATFORM_ARCHIVE_R2_BUCKETPlatform R2 bucket (Terraform lovely-home-hub-archives; script default if unset)
CLOUDFLARE_ACCOUNT_IDSet on the Wrangler process (not --account-id; Wrangler 4 r2 object put rejects that flag)

Objects written to the platform bucket lovely-home-hub-archives (not lovely-home-appliance-guides-{site} or lovely-home-guide-media-{site} — those are destroyed with the hub):

  • {site_id}/site-backup-{exportedAt}.json — full payload
  • {site_id}/site-media-{exportedAt}.zip — guide photos (media/photos/) and appliance PDFs (media/appliance-manuals/), #842
  • {site_id}/latest.json — pointer { archivedAt, backupKey, mediaArchiveKey, formatVersion }

In the Cloudflare dashboard: R2 → search lovely-home-hub-archives → open the {site_id}/ prefix. The bucket sits alphabetically after the lovely-home-guide-media-* list.

Disposable e2e-* sandboxes: lifecycle teardown skips archive upload when SKIP_PLATFORM_HUB_ARCHIVE_FOR_E2E=1, but legacy runs may still have {e2e-*}/site-backup-* objects. Bulk-remove only those hub backup prefixes (not e2e-reports/ Playwright uploads) with npm run prune:e2e-hub-site-archives-r2 — see e2e-sandbox-cleanup.md.

Archive is required for customer deprovision: missing PLATFORM_SITE_ARCHIVE_SECRET or a failed hub fetch stops teardown so the live hub is not destroyed without a copy. Sync GitHub secrets from Terraform state with:

bash
node scripts/sync-platform-archive-github-secrets.mjs

Restore on reactivate ​

  1. Provision hub (same site_id).
  2. Provision CI runs node scripts/restore-hub-site-from-archive.mjs {site_id} when site_billing.archive_r2_key is set and archive_restored_at is null. The script reads the JSON from platform R2 and calls POST /api/platform/site-restore on the hub Worker (X-Platform-Site-Archive-Secret, optional Access service token).
  3. Operators can still call POST /api/site/restore from owner device mode or use the setup wizard restore step.
  4. If the JSON has a mediaArchiveKey, the script then downloads the zip and POSTs it to /api/platform/site-restore-media, which puts the photos and PDFs back into the hub's buckets and relinks them. A media failure stops before archive_restored_at is set, so re-running the workflow retries both steps. Archives from before #842 restore text only; owners re-upload photos and PDFs.
MethodPathAuth
POST/api/platform/site-restore on the WorkerSame as site archive — X-Platform-Site-Archive-Secret
GET/api/platform/site-archive-media on the WorkerSame — returns application/zip
POST/api/platform/site-restore-media on the WorkerSame — body is the zip

Billing deprovision clears archive_restored_at when it stores a new archive_r2_key.