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/restoreor wizard step 1. - Support reinstate within about 12 months for the same owner (
archive_r2_keyonsite_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
| Data | In JSON backup | Notes |
|---|---|---|
| House Guide catalog (draft content) | Yes | Same as Settings → Download full site backup |
| Site profile, bins, pets | Yes | |
| Hub secrets (Wi‑Fi, PIN, lockbox, calendar) | Yes | Platform encrypts at rest in R2 (see below) |
| Sitter settings + scheduled stays | Yes | |
| 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 PDFs | In the media zip (#842) | Same zip, under media/appliance-manuals/ |
| Worker platform secrets | No | Regenerated 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 recordsmediaArchiveKeyin the JSON and inlatest.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
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
| Method | Path | Auth |
|---|---|---|
| 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:
# Local (same CLOUDFLARE_API_TOKEN as deploy)
export PLATFORM_SITE_ARCHIVE_SECRET='…'
node scripts/sync-platform-site-archive-secret.mjsOr 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
node scripts/archive-hub-site-backup.mjs <site_id>
node scripts/archive-hub-site-backup.mjs <site_id> --skip-platform-archiveSkip (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:
| Variable | Purpose |
|---|---|
SKIP_PLATFORM_HUB_ARCHIVE | When truthy (1 / true / yes), skip upload for any site |
SKIP_PLATFORM_HUB_ARCHIVE_FOR_E2E | When truthy, skip upload only when site_id matches e2e-* |
PLATFORM_SITE_ARCHIVE_SECRET | The platform master; the script derives the hub's own secret from it |
PLATFORM_HEALTH_CF_ACCESS_CLIENT_ID | Access service token (edge) |
PLATFORM_HEALTH_CF_ACCESS_CLIENT_SECRET | Access service token (edge) |
PLATFORM_ARCHIVE_R2_BUCKET | Platform R2 bucket (Terraform lovely-home-hub-archives; script default if unset) |
CLOUDFLARE_ACCOUNT_ID | Set 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:
node scripts/sync-platform-archive-github-secrets.mjsRestore on reactivate
- Provision hub (same
site_id). - Provision CI runs
node scripts/restore-hub-site-from-archive.mjs {site_id}whensite_billing.archive_r2_keyis set andarchive_restored_atis null. The script reads the JSON from platform R2 and callsPOST /api/platform/site-restoreon the hub Worker (X-Platform-Site-Archive-Secret, optional Access service token). - Operators can still call
POST /api/site/restorefrom owner device mode or use the setup wizard restore step. - If the JSON has a
mediaArchiveKey, the script then downloads the zip andPOSTs 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 beforearchive_restored_atis set, so re-running the workflow retries both steps. Archives from before #842 restore text only; owners re-upload photos and PDFs.
| Method | Path | Auth |
|---|---|---|
| POST | /api/platform/site-restore on the Worker | Same as site archive — X-Platform-Site-Archive-Secret |
| GET | /api/platform/site-archive-media on the Worker | Same — returns application/zip |
| POST | /api/platform/site-restore-media on the Worker | Same — body is the zip |
Billing deprovision clears archive_restored_at when it stores a new archive_r2_key.
Related
- site-backup.md — backup format and owner UI
- platform-provision.md — deprovision workflow