Share links
An owner can share one item by link: https://{home}.lovely-hub.com/s/{token} opens that item only, with no sign-in and no hub navigation (#1183).
A cleaner's link for one clean, /s/clean/{token}, uses the same /s/* Access bypass; see cleans.md.
What can be shared
| Item | Plan | How it opens | Link lasts |
|---|---|---|---|
| Wi‑Fi | Free and up | Network name, password and a join QR code | 7 days |
| Emergency contacts | Lovely Home+ and Multi Home | Primary and secondary contact names and phone numbers (no emails) | 7 days |
| One guide topic | Lovely Home+ and Multi Home | The published topic, read-only, translated into the visitor's language, with its photos | 30 days |
| One appliance manual | Lovely Home+ and Multi Home | The manual's details and a button that opens the PDF in the browser's viewer | 30 days |
| Door code | Lovely Home+ and Multi Home | The code, after the visitor types the link's 4-digit PIN | 24 hours, 3 opens |
| Lockbox code | Lovely Home+ and Multi Home | The code, after the visitor types the link's 4-digit PIN | 24 hours, 3 opens |
A hub has at most one door code (door_code) and one lockbox code (lockbox_code), both in Home details (#1309), so each is its own kind of link with no item to pick.
The rules live in src/lib/shareLinks.js (SHARE_LINK_KINDS), shared by the hub app and the Worker. The Worker enforces them; what each kind opens is in worker/src/lib/shareLinkItems.js.
How it works
- Settings → Shared links (owner only) lists what can be shared. For a topic or a manual the owner picks which one. The owner taps Create link; the new link (and a door or lockbox code link's PIN) shows right under that item, named (for example Wi‑Fi · Rose Cottage); making another link replaces it (#1272). On a phone it stacks under the item, full width. Copy link changes to Copied for two seconds. Turning that link off removes the box (#1276). Each item's live links are listed under it, with their expiry, opens and Turn off button; there is no separate list of links (#1280).
- The Worker checks the plan, checks that the item exists and that the owner hasn't made it owner-only (#1181), then stores a row in the
share_linkstable (migration0013_share_links.sql) and returns a 32-byte random token. Only the token's SHA-256 hash is stored, so the link is shown to the owner once and can't be read back. - The visitor opens
/s/{token}. Cloudflare Access skips/s/*(see below), and the Pages Functionfunctions/s/[token].jsposts the token to the Worker over theHUB_APIservice binding (POST /api/share/open, token in the body so it isn't in request logs). - The Worker finds the live link by hash, reads the item now (so a changed Wi‑Fi password shows the new one), counts the open, and returns the item. The Pages Function renders a static page: no scripts,
noindex,no-store,no-referrer, and a CSP that allows nothing but inline styles, the hub's own anddata:images, and a form that posts back to the hub (the door or lockbox code PIN).
What "owner-only" means for each item:
- Wi‑Fi, emergency contacts, door code, lockbox code: the secret's list in People → Who sees what is empty.
- Guide topic: the topic isn't published, its audience is owners only, or the House Guide app is shown to nobody.
- Appliance manual: the manual isn't shown to guests (unpublished), or the House Guide app is shown to nobody.
A shared topic leaves out protected values (door and lockbox codes, address and the like), the Wi‑Fi QR block and Alexa buttons: those have their own sharing rules. Its copy is rebuilt from an allowlist on the server (functions/lib/shareRichText.js, the same tags as the hub's DOMPurify list in src/widgets/HouseGuide/guideRichTextFormat.js).
A link stops working when:
- the owner turns it off (Turn off in Settings → Shared links),
- it expires,
- the item is removed, or the owner makes it owner-only,
- the hub drops to Free (for anything but Wi‑Fi),
- the hub is suspended (the Worker refuses every
/api/call), or - the hub is factory reset (all links are deleted).
Every failure shows the visitor the same "This link isn't available" page, so a link can't be probed for whether it ever existed.
Door and lockbox codes and their PIN
A door code or lockbox code link has a second secret, a 4-digit PIN. When the owner makes the link, the Worker picks the PIN at random (generateSharePin), stores only a SHA-256 hash of it salted with the link's id (pin_hash, migration 0014_share_link_pins.sql), and returns it with the token. Settings shows the PIN once, under the link, and asks the owner to send it separately (for example the link by email and the PIN by text), so someone who sees one message doesn't get the code.
- The visitor opens
/s/{token}. The Worker sees the link needs a PIN and answers{ needsPin: true }with no code, and doesn't count the open. The page shows a PIN form. - The form
POSTs the PIN back to/s/{token}(the CSP'sform-action 'self'). The Pages Function sends it to/api/share/openwith the token. - With the right PIN the Worker counts the open and returns the code and how many opens are left. The page shows both; on the last open it says the link won't open again.
- A wrong PIN is
403 WRONG_PINwithattemptsLeft, and the page shows the form again with "That PIN isn't right. Tries left: N." Each wrong PIN counts against the link (pin_failures): after 5, from anyone anywhere, the link stops working for good. Each wrong PIN also counts towards the visitor's IP rate limit. A PIN that isn't 4 digits is refused without counting.
So only opens with the right PIN use up the link's 3: a chat app's link preview, or someone who has the link but not the PIN, doesn't. The live list in Settings shows "Opened: N of 3".
Photos and PDFs
A shared topic's photos load from /s/{token}/media/{mediaId} and a shared manual's PDF from /s/{token}/file (functions/s/[token]/media/[mediaId].js, functions/s/[token]/file.js). Each asks the Worker (POST /api/share/file), which checks the link is still live and the item still shareable, then streams the file from R2. A topic's link serves only the photos that topic shows. Files don't count as opens, but failures count towards the rate limit. Responses are no-store, noindex and nosniff.
Translation
Guides are written in English. The page sends the visitor's language (from Accept-Language, if the hub has it) to the Worker, which translates the topic with the same engine and R2 cache as the hub's live guide translation (translateGuideCatalogLive), with an 8-second budget. If translation isn't available or runs out of time the visitor gets the English copy; whatever was translated is cached for the next visit.
Limits: 50 live links per hub. After five failed opens (unknown, expired or turned-off links, wrong PINs) from one IP within ten minutes, that IP sees "Too many tries" until the oldest failure is ten minutes old. This reuses the owner PIN limiter (OWNER_AUTH_LIMITER, scope share-open). A HEAD request (link checkers) gets a 200 without opening the link. A GET from a chat app's link preview does count as an open, except on a lockbox code link (it only shows the PIN form).
Cloudflare Access
Each hub has a third Access application, <Home name> share links, for {hostname}/s/* with one Bypass → Everyone policy (cloudflare_zero_trust_access_application.share_links in terraform/modules/hub_environment/access.tf). Access uses the most specific application, so /s/* skips sign-in and everything else on the hub still needs it. The Pages middleware skips its own Access check for /s/ too (functions/_middleware.js).
The Worker's own hostname stays behind Access: /api/share/open is reachable only from the hub's /s/ page through the service binding.
Rollout: new hubs get the bypass app when they're provisioned. An existing hub gets it on its next hub Terraform apply (for example the Platform Terraform plan → Platform Terraform apply workflows, #1211/#1215). Until then, a share link on that hub shows the Access sign-in page instead of the item.
Footer link
Every share and cleaner page ends with "Made with Lovely Home — get one for your home" (hub.sharePage.footer, the same words as the hub's own footer link), linking to https://lovely-home.co.uk/?utm_source=share_link&utm_medium=referral&utm_campaign=made_with in a new tab (#1534). The people who open these links aren't signed in and often have homes of their own; the tags let the signup funnel count the sign-ups they bring. The link is plain HTML, so the page still runs no scripts.
Language
The page uses the visitor's browser language when the hub has it, then the hub's language, then English. Its strings are the hub.sharePage.* keys in src/i18n/hubAppLocales/*.json, copied into functions/lib/sharePageStrings.generated.js by npm run build:share-page-strings (the Pages Function can't load the full hub locale files). npm run check and CI fail when the copy is out of date.
API
| Method | Path | Who | Body / result |
|---|---|---|---|
GET | /api/house-settings/share-links | Owner | { links, kinds: { wifi: { planAllows, available }, topic: { planAllows, available, items: [{ id, label }] }, … }, plan, upgradeUrl } |
POST | /api/house-settings/share-links | Owner | { kind, itemId? } (itemId for topic and manual) → { link, token, pin } (pin for door and lockbox, else null); errors INVALID_KIND, PLAN_FEATURE (403), ITEM_NOT_SHAREABLE (409), SHARE_LINK_LIMIT (409) |
DELETE | /api/house-settings/share-links/:id | Owner | Turns the link off |
POST | /api/share/open | Anyone (via /s/) | { token, lang?, pin? } → { kind, needsPin, label, item, expiresAt, opensLeft, hubName, languageCode } (needsPin: true and item: null until a lockbox link gets its PIN), or 403 WRONG_PIN { attemptsLeft, … } / 404 / 429 |
POST | /api/share/file | Anyone (via /s/) | { token, mediaId? } → the photo or PDF, or 404 / 429 |
Tests
- Worker:
worker/tests/shareLinks.test.js,shareLinkItems.test.js(topics, manuals),shareLinkLockbox.test.js(PIN, opens, lock after wrong PINs, door codes). - Share page:
tests/sharePage.test.js. Settings:tests/sharedLinksFields.test.js. - Browser, every PR (site checks):
e2e/share-links.spec.jsagainst the real Pages Functions and Worker (e2e/share/server.mjs). - Real hub, nightly lifecycle:
e2e/lib/shareLinksE2e.js(Settings → Shared links, the/s/*Access bypass, lockbox PIN on Plus).
Hub Pages staging
functions/_middleware.js and the share page import from src/. scripts/prune-hub-pages-functions.mjs --out dist-hub-functions/functions links dist-hub-functions/src to the repo's src/, so Wrangler bundles the staged Functions with the same imports. The platform Pages project drops functions/s/ (scripts/prune-platform-pages-functions.mjs).