Cloudflare Worker API
Lovely Home Hub uses a Cloudflare Worker as the secure backend for Virtual Buttons and private house configuration. The Vite PWA never sees the Virtual Buttons access code.
Architecture
Cloudflare Pages (Home Hub PWA)
│
▼
Cloudflare Worker (lovely-home-hub-api)
├── POST /api/button/VBxx → Virtual Buttons (access code in Worker secret)
├── POST /api/auth/owner → Owner PIN (OWNER_PIN Worker secret only)
├── GET /api/weather → Home forecast, advice (Open-Meteo via Worker)
└── GET /api/private-config → Wi-Fi, contacts, addressWorker project
Location: worker/
cd worker
npm install
cp .dev.vars.example .dev.vars # local secrets — never commit
npm run dev # http://127.0.0.1:8787Frontend configuration
Copy .env.example to .env.local:
VITE_API_BASE_URL=http://127.0.0.1:8787For production, set in Cloudflare Pages (frontend project only):
VITE_API_BASE_URL— your*.workers.devURL (or custom API hostname)VITE_DEPLOYMENT_MODE=home— for the full hub tablet (orhouse-sitterfor guest-only builds)
Set the same VITE_API_BASE_URL (and deployment mode) for Preview environment variables, not only Production. PR preview builds use the Preview scope; without it, weather and other Worker features show as unavailable.
Do not set VITE_OWNER_PIN on Pages. Owner PIN validation runs only on the Worker via the OWNER_PIN secret (see below).
Deploy Worker
Production (default environment):
cd worker
npx wrangler login
npx wrangler secret put VIRTUAL_BUTTONS_ACCESS_CODE
npx wrangler secret put PRIVATE_WIFI_SSID
npx wrangler secret put PRIVATE_WIFI_PASSWORD
npx wrangler secret put PRIVATE_MARK_PHONE
npx wrangler secret put PRIVATE_MARK_EMAIL
npx wrangler secret put PRIVATE_DONNA_PHONE
npx wrangler secret put PRIVATE_DONNA_EMAIL
npx wrangler secret put PRIVATE_HOME_ADDRESS
npx wrangler secret put PRIVATE_DOOR_CODE # optional, keypad or smart lock code (#1309)
npx wrangler secret put PRIVATE_LOCKBOX_CODE
npx wrangler secret put OWNER_PIN
npm run deployTest (disposable stack, does not touch production data): cloudflare-test-environment.md — npm run provision:test, then npm run secrets:test, npm run d1:migrate:test, npm run deploy:test.
After pulling CMS or house-settings changes, apply D1 migrations once:
# All hub sites (test, sandbox, demo, dev, wagtail, lovely, …)
npm run d1:migrate:all
npm run deploy:all
# Legacy top-level Worker (dashboard.lovely-home.co.uk) — only if still in use:
npm run deploy:all --prefix worker -- --include-prod
# Or one site
npm run d1:migrate:prod --prefix worker
npm run deploy:test --prefix workerd1:migrate:all and deploy:all discover scripts from worker/package.json. By default both skip the legacy top-level Worker (prod / lovely-home-hub-api and its D1); pass --include-prod only if that stack is still live. Use --dry-run, --site test, or --exclude demo as needed. Requires CLOUDFLARE_API_TOKEN in the environment. Run migrations before deploy when schema changed.
For the isolated test stack (separate D1/R2/Worker), see cloudflare-test-environment.md and use npm run d1:migrate:test / npm run deploy:test.
OWNER_PIN is a Worker secret, not a Pages variable. Rate limiting for owner auth uses the OWNER_AUTH_LIMITER Durable Object binding defined in worker/wrangler.toml (applied on deploy via migrations).
For local dev, add OWNER_PIN to worker/.dev.vars (gitignored) — never commit the real PIN.
Home weather location: HOME_LATITUDE and HOME_LONGITUDE in worker/wrangler.toml [vars]. Update these on the Worker if you move house — the dashboard calls GET /api/weather (optional ?lat=&lon= when the tablet has a Settings override). Postcode/place lookup: GET /api/weather/geocode?q=.
Verify:
curl -s "https://<your-worker>.workers.dev/api/health"CORS
ALLOWED_ORIGINS in wrangler.toml lists the browser origins allowed to call the Worker with credentials. Production hub builds call the API same-origin through the Pages proxy (no Origin reaches the Worker), so each hub only needs its own hosts:
- the hub's custom domain, e.g.
https://lovely.lovely-hub.com - its Pages project,
https://home-dashboard-{site}.pages.dev, and that project's branch previews,https://*.home-dashboard-{site}.pages.dev
Never add https://*.pages.dev: anyone can host a site there (#1167). A * matches one DNS label only. Localhost origins (Vite dev) belong only on the top-level (local wrangler dev) block, never on an [env.*] hub. scripts/platform-site-manage.mjs writes new hub blocks this way, and worker/tests/api.test.js fails if a hub block trusts *.pages.dev or localhost.
Button allowlist
The Worker only accepts VB01–VB10 mapped to the same numeric Virtual Button IDs as src/config.js:
| Code | Control |
|---|---|
| VB01 | Downstairs On |
| VB02 | Bedtime |
| VB03 | Garage Light On |
| VB04 | Garage Light Off |
| VB05 | Downstairs Off |
| VB06 | Watch Movie |
| VB07 | Heat to 20°C (owner only) |
| VB08 | Master Bedroom Lights On |
| VB09 | Restore Lights After Movie |
| VB10 | Master Bedroom Lights Off |
The browser sends only the code (for example POST /api/button/VB01).
Rotating the Virtual Buttons access code
- Generate a new code in Virtual Buttons.
wrangler secret put VIRTUAL_BUTTONS_ACCESS_CODE- Redeploy is not required for secret-only updates.
- Confirm the old code is removed from any legacy Pages env vars (
VITE_VIRTUAL_BUTTONS_ACCESS_CODEmust stay unset).
Cloudflare Access
Production API routes require a valid Cloudflare Access JWT and server-side roles. See:
- cloudflare-access-setup-guide.md — step-by-step Cloudflare UI instructions
- cloudflare-access.md — model and API matrix
- cloudflare-access-runbook.md — deployment checklist and smoke tests
After deploy, set CF_ACCESS_TEAM_DOMAIN, CF_ACCESS_AUD, and OWNER_EMAILS on the Worker before the dashboard can use weather, controls, or private config.
Tests
npm run check # frontend + dist secret scan + worker tests
cd worker && npm test # Worker onlyThe build step runs scripts/check-dist-secrets.js to ensure Virtual Buttons credentials and VITE_OWNER_PIN are not present in dist/.