house worker

docs/house-tracker.md

@@ -59,6 +59,31 @@ WAF skip rule for `URI Path starts with /projects/house-tracker/api/worker/`,
 otherwise the worker's POSTs get challenged too. The endpoints are protected by
 the bearer token.
 
+### Development behind Cloudflare Access
+
+For `https://dev.stanrunge.dev`, keep Access enabled. In Cloudflare Zero Trust,
+go to **Access controls → Service credentials → Service Tokens** and create a
+token named `house-worker`. Save its Client ID and Client Secret. In the Access
+application protecting the dev hostname, add a **Service Auth** policy with
+**Include → Service Token → house-worker**. Keep the existing browser login
+policy. See [Cloudflare's service token documentation](https://developers.cloudflare.com/cloudflare-one/access-controls/service-credentials/service-tokens/).
+
+Set `HOUSE_WORKER_TOKEN` in the dev website's `.env` and restart its dev server.
+On the home machine, copy `house.env.example` to `house.env`, fill in the same
+worker token plus the Cloudflare Client ID and Client Secret, then run:
+
+```sh
+chmod 600 house.env
+bun --env-file=house.env scripts/house-worker.ts --check-api
+```
+
+This makes one authenticated GET to the website's worker health endpoint. It
+does not contact Pararius, sync listings or send alerts. The expected output is
+`API connection OK`. Access credentials are sent only to the website API; the
+client refuses redirects and stops immediately on an authentication failure.
+An HTTP 503 can mean the website's worker token is missing; an HTTP 404 can mean
+the running website does not yet include the health route.
+
 ## Home worker setup
 
 Needs a machine that stays on (old laptop, Raspberry Pi, NAS) with Bun 1.4 or