Cloudflare Access — dashboard security lockdown
Lovely Home Hub uses Cloudflare Access as the outer authentication boundary. The Worker validates the Access JWT on every sensitive API request and assigns Lovely Home roles server-side. The browser UI mode (owner vs house sitter) is not authorization.
Security model
Cloudflare identity (email allow-list)
↓
Cf-Access-Jwt-Assertion validated by Worker
↓
Lovely Home role
├── owner (email in OWNER_EMAILS, an invited owner, or an account team
│ Admin or Maintainer, #1474)
├── house-sitter (email on the hub's sitter list, or on a stay whose access window is open)
│ (family members, #1184, and account team Read only, #1474,
│ are house-sitters with no stay window)
└── refused (403 SITTER_ACCESS_ENDED: any other identity, even with a valid Access login)A valid Access login is not enough on its own (#1164). Access sessions last up to 30 days and outlive a stay, a removed sitter or a removed invited owner. On every request the Worker checks that a non-owner email is a current sitter (Settings sitter list, or a stay inside its access window). Anyone else gets 403 SITTER_ACCESS_ENDED, and the hub app sends them to lovely-home.co.uk/access-unauthorised.
Secrets and controls are per sitter. A sitter's own login gets the Wi-Fi password, lockbox code, contact details and Alexa controls only when the owner has switched sharing on, or when their own stay is inside its secrets window. Another guest's stay doesn't open them. An owner's tablet locked to sitter mode follows the hub-wide state, as before.
Owner PIN (in-app unlock) only switches what the already authenticated tablet shows. It does not replace Access. Owner-only APIs (calendar, owner PIN endpoint) require an owner Access identity regardless of PIN.
Deployment runbook
Step-by-step checklist (Phase 1 before DNS, Phase 2 for dashboard.lovely-home.co.uk), AUD/secret commands, and smoke-test curls:
- cloudflare-access-setup-guide.md — start here (click-by-click Zero Trust, Pages, Wrangler)
- cloudflare-access-runbook.md — checklist, smoke tests, rollback
Manual Cloudflare configuration
Perform these steps in the Cloudflare Zero Trust dashboard. This repository does not change your Cloudflare account automatically.
1. Create Access applications
Create separate self-hosted (or SaaS) Access applications for each public entry point. Do not use Include: Everyone.
| Hostname | Purpose |
|---|---|
dashboard.lovely-home.co.uk | Production Pages (custom domain — Phase 2 when DNS is live) |
home-dashboard-a11.pages.dev | Production Pages default hostname |
| Pages preview deployments | Add each preview hostname or a documented wildcard policy |
| Worker production hostname | Worker API |
| Worker preview URLs | Worker preview deployments |
Policy (owners):
- Action: Allow
- Include: Emails — list each owner address
- Authentication: One-time PIN and/or IdP as you prefer
Policy (house sitters):
- Action: Allow
- Include: Emails — exact address per sitter
- Do not use unrestricted “Login method = One-time PIN” without an email allow-list
Revoking access = remove the email from the policy (Terraform owner_emails or site tester_emails, then terraform apply; sitters, family and invited owners in the hub's Settings). A sitter removed in Settings, or whose stay has ended, is refused by the Worker straight away, even before their Access session expires.
Who owns which policy (#1274). Terraform owns Platform health checks and Owners. The hub Worker owns House sitters, Family, Invited owners and Account team (#1474): it writes them when the owner changes Settings, stays, family or invited owners. On every plan Terraform reads those from the live app and keeps them as they are, after its own, so a hub apply never removes people added in the hub. Registry sitter_emails only seeds the hub's sitter list at provision (scripts/seed-sitter-access-emails.mjs); Terraform no longer has a sitter_emails variable.
Owner vs tester vs sitter (Terraform-managed hubs)
| List | Scope | Access policy | Worker OWNER_EMAILS |
|---|---|---|---|
owner_emails (global) | Platform hubs only (lovely-home.co.uk) | Owners — Allow | Merged on each platform site |
SUPPORT_OWNER_EMAILS secret | Only a lovely-hub.com hub with no billing owner (one the operator runs for themselves) | Owners — Allow | Used as that site's owners |
tester_emails (per site) | That hub only (e.g. sandbox, test) | Owners — Allow | Merged on that site |
| Sitters, family, invited owners | Added in the hub | House sitters / Family / Invited owners — Allow (written by the hub, kept by Terraform) | Sitters are not owners for calendar/backup APIs |
Customer hubs deliberately do not inherit the global owner_emails list — otherwise every address there would gain owner access to every household. A customer's own owner address is read from the platform billing database at provision time, never committed to platform/sites.yaml.
The operator cannot open a customer's hub. A hub with a billing owner gets that owner and nobody else; the SUPPORT_OWNER_EMAILS addresses are never added beside a customer. If a customer wants help inside their hub, they invite the address under Settings → People → Owners and remove it afterwards. Platform Terraform apply also sets the hub Worker's OWNER_EMAILS from Terraform (scripts/sync-worker-owner-emails.mjs), so an owner Terraform removes is gone from the hub too.
Example: household owners on production + sandbox; Airbnb trial guest on sandbox/test only — set tester_emails under sites.sandbox and sites.test, not in global owner_emails.
Do not add testers manually in Zero Trust → Access → Applications; Terraform owns those policies. Edit hub.tfvars, run terraform apply, then node scripts/set-worker-secrets-from-terraform.mjs {site_id}. See platform-terraform.md — Add a tester.
Unauthorised emails (no login code)
Cloudflare One-time PIN will not send a code when the address is not on an Allow policy, and the hosted login screen still says a code was emailed. That is Cloudflare’s design (it avoids revealing who is on the list). We cannot replace that screen with our own form.
What we do instead:
- Footer copy on the Access login page: if no code arrives, the email is not authorised.
- After someone submits a PIN (or Access otherwise denies identity), they are sent to
access-unauthorised.html(https://lovely-home.co.uk/access-unauthorised). That page is self-contained so CSS and images are not blocked by the marketing Access app. - Hub Access application names are the household title (
Wagtail Home), notLovely Home — wagtail Pages. The left-hand login logo is the team Access login design (node scripts/sync-access-login-design.mjs, needs a token that can edit the Zero Trust organisation).
On Terraform-managed hubs, owners can also edit the House sitters allow-list from Settings → House sitter mode → Sitter login emails or Scheduled stays. The hub Worker stores the list in D1 and updates Cloudflare Access via API (requires CF_ACCESS_MANAGEMENT_TOKEN, ACCESS_PAGES_APP_ID, and ACCESS_WORKER_APP_ID on the Worker).
The hub's Access token (CF_ACCESS_MANAGEMENT_TOKEN)
A hub Worker is the code most exposed to the internet, so it holds a token that can only edit Access apps and policies, never the account-wide deploy token (CLOUDFLARE_API_TOKEN). Until #1566 provisioning fell back to the deploy token, which let any hub Worker read or change every other hub's data, Workers and DNS.
Make the token once:
- Cloudflare dashboard → My Profile → API Tokens → Create Token → Create Custom Token.
- Name it
lovely-home-hub-access. Permissions: Account → Access: Apps and Policies → Edit. Nothing else. Account resources: the Lovely Home account. - Add it as the repository secret
CF_ACCESS_MANAGEMENT_TOKENin bothmarklovely/home-dashboardandmarklovely/lovely-hub-provision. - Run the Platform sync Access management token Action (leave the site empty for every hub). It first asks Cloudflare what the token can do and stops unless it can read Access apps and is refused Workers. Then it puts the token on every hub Worker except the public demo.
- Check one hub: add and remove a test House sitter email in Settings.
- Only then rotate
CLOUDFLARE_API_TOKEN(roll it in Cloudflare, update the secret in both repos), because every hub Worker still has a copy of the old one until step 4 has run.
Cloudflare cannot limit a token to one Access app, so this token can still edit any hub's sign-in lists. It can no longer deploy code, read databases or buckets, or change DNS.
Invited owners (Settings → People → Owners, #843)
Any owner can invite up to 4 more owners, so a hub has at most 5 owners including the original.
- Where they're kept: the Worker stores invited owners in D1 (
house_settings.invited_owner_emails). Requests from those emails get the owner role, as if they were inOWNER_EMAILS. - Access policy: the Worker keeps a hub-managed Invited owners Access policy on both the Pages and Worker apps. It uses the same API and token as House sitters. Invitees open the hub address and sign in with the one-time code.
- Terraform: its Owners policy is never edited. If a Terraform apply on the hub replaces the apps' policies, the hourly cron re-creates Invited owners.
- Rules: original owners (
OWNER_EMAILS, set at signup) can't be removed here, and you can't remove yourself. Removing every invited owner deletes the policy. Saving is blocked on the demo hub. - API:
GETandPOST /api/house-settings/ownerswith{ "emails": [...] }, owner only.
Account team (lovely-home.co.uk → Account → Team, #1474)
People the account holder adds on the account page reach every home on the account, including homes added later. Up to 10 people per account, on every plan, no charge.
| Account role | On each hub | Account page |
|---|---|---|
| Admin | owner | everything, except only the account holder can cancel the whole plan |
| Maintainer | owner, except changing hub owners, reset, restore and secrets (isMaintainerBlockedRequest, 403 ACCOUNT_ROLE) | My Homes, Stays and Cleaners (can change), Saved setups; no Billing, Team, add or close homes |
| Read only | like family: sees everything family see (Wi-Fi, door codes), changes nothing | My Homes, Stays and Cleaners to look at |
- Where it's kept: the platform table
account_membersis the source. The account holder issite_billing.owner_emailand is never a row, so accounts made before #1474 needed nothing copied. Each hub keeps a copy inhouse_settings.account_team_membersand mirrors it into a hub-managed Account team Access policy on both apps (owner emails are left out). - How it reaches hubs: the platform
POSTs{ members }to/api/platform/account-teamon each live home after every change (archive secret + health service token, like stays). The hourly cron also asksGET /api/public/hub-account-team?siteId=…with the hub's own archive secret, so a new home and a hub that was down catch up within the hour. - Removing someone deletes their account sign-ins on that account at once; on hubs they drop out at the push, or at the next hourly pull for a hub that missed it.
- Terraform keeps the Account team policy on apply (
hub_managed_policy_names). - Per-hub invited owners and family are unchanged and separate.
Family (Settings → People → Family, #1184)
Family are trusted people who aren't owners (grandparents, a neighbour with a key). They can sign in at any time, with no stay window.
- Plan limit: 2 per home on Free, no limit on Lovely Home+ and Multi Home (platform
limits.maxFamily; the Worker assumes 2 on Free if the platform doesn't send it). A list already over the cap after a downgrade can be kept or shortened, not grown. More than 2 blocks a downgrade to Free. - Where they're kept:
house_settings.family_member_emails. Requests from those emails are let in without a stay and keep the non-owner role, so owner APIs refuse them. Secrets are always shared with them; controls only when the owner turns onfamily_controls_enabled. - Access policy: a hub-managed Family policy on both apps, kept like Invited owners (same token, re-created by the hourly cron). Removing someone updates the policy and the Worker stops letting them in (within 30 seconds on other Worker instances).
- API:
GETandPOST /api/house-settings/familywith{ "emails"?: [...], "controls"?: boolean }, owner only.
Share links (/s/*, #1183)
Each hub has a third Access app, <Home name> share links, for {hostname}/s/* with a Bypass → Everyone policy (Terraform share_links in modules/hub_environment/access.tf). It lets a share link open one item with no sign-in; the random token in the link is checked by the Worker. Everything else on the hub, and the Worker's own hostname, stays behind Access. Existing hubs get the app on their next hub Terraform apply. See Share links.
Production dashboard (dashboard.lovely-home.co.uk)
The default Worker (lovely-home-hub-api) uses top-level wrangler.toml [vars], not [env.production]. Platform provision sets Access sync on new sites automatically; production must be enabled once:
export CLOUDFLARE_API_TOKEN='…' # Zero Trust Access edit + Workers Scripts Edit
export CLOUDFLARE_ACCOUNT_ID='…'
node scripts/sync-wrangler-production-access.mjs
node scripts/set-production-access-sync-secret.mjs
npm run deploy --prefix workerThen re-save a scheduled stay or sitter login emails in Settings — the Worker creates/updates the House sitters policy on both Pages and Worker Access apps.
Both apps are updated in parallel, and a policy that already lists exactly the wanted emails isn't rewritten (#1142).
Open-ended stays (#1233): Stays with no leave date keep the tenant in the Worker access window for 10 years from the arrival date (renewed if you edit the stay). Cloudflare Access still uses email allow-lists only — the Worker refuses logins after the window. Cancel or End stay now to revoke immediately; set a leave date before using Extend on a long-term stay.
The hub also remembers the guest list it last pushed successfully (house_settings.sitter_access_synced_emails). A save that leaves that list unchanged doesn't call Cloudflare at all (#1146). That's most stay saves, because a stay's access opens 14 days before it. The hourly cron, backup restores and hub resets always check Cloudflare itself, so a policy edited by hand is put right within the hour. A failed push isn't remembered, so the next save tries again.
If sync is not configured, Settings shows a warning and stays save locally without pushing emails to Cloudflare (sitters will not receive Access OTP until their email is on the policy).
2. Application audience (AUD)
Set Worker secret CF_ACCESS_AUD to the Access application audience for requests hitting the Worker.
3. Team domain
Set CF_ACCESS_TEAM_DOMAIN to your Zero Trust team subdomain (before .cloudflareaccess.com).
4. Owner emails
Set OWNER_EMAILS to a comma-separated list of owner addresses.
5. Preview deployments
Protect preview hostnames with Access or disable public previews. No alternate unprotected URL may reach the same API.
6. CORS
Tighten ALLOWED_ORIGINS for production. CORS is not authentication.
Worker configuration
See worker/.dev.vars.example for local development. The Worker only accepts Access JWTs signed by your team's Cloudflare Access keys; there is no shared test secret (#1171). For a local API JWT, set VITE_DEV_ACCESS_JWT to a real token (cloudflared access token -app=<hub URL>). Unit tests sign with a generated key that worker/tests/setup/accessJwks.js serves as the team certs. The hub's Pages middleware checks the same token the same way before proxying (functions/lib/accessJwtVerify.js, keys cached for 10 minutes with one reload per unknown key id, #1389; tests/pagesAccessJwtVerify.test.js covers rotation).
API summary
| Endpoint | Access JWT | Role |
|---|---|---|
GET /api/health | No | — |
GET /api/session | Yes | Any |
GET /api/private-config | Yes | Owner device mode, or sitter device mode when Sitter is here is enabled in Settings |
GET /api/weather | Yes | Any |
POST /api/auth/owner | Yes | Owner email + PIN |
GET /api/calendar | Yes | Owner |
POST /api/button/:code | Yes | Owner only — see CONTROL_PERMISSIONS in Worker |
House sitters cannot trigger Virtual Buttons. Owners must unlock the tablet to owner mode before controls work, even if their Cloudflare Access identity is an owner email.