docs(01-09): document security contract changes

- define explicit MCP read scope boundaries and upgrade handling
- document Nightscout private-origin pinning and reset revocation

docs/integrations/nightscout.md

@@ -0,0 +1,85 @@
+# Nightscout integration
+
+HealthLog can pull continuous-glucose readings from a Nightscout instance.
+Public Nightscout origins work without an allowlist. Access to a private or
+local destination is an operator decision and is denied unless its exact
+origin is listed in `NIGHTSCOUT_PRIVATE_ORIGINS`.
+
+## Security change for upgrades
+
+`NIGHTSCOUT_PRIVATE_ORIGINS` is a breaking security boundary. The old
+per-user “allow private host” opt-in is compatibility metadata only: it no
+longer grants private-network access. Existing private connections that are
+not operator-approved stop syncing with the stable
+`private_origin_not_approved` reason until the operator configures the exact
+origin.
+
+Set a comma-separated list of complete origins:
+
+```env
+NIGHTSCOUT_PRIVATE_ORIGINS="https://cgm.internal.example:443,http://10.20.30.40:1337"
+```
+
+Each entry is an exact normalized `scheme://host:port` trust unit:
+
+- only `http` and `https` are accepted;
+- scheme, hostname, and effective port must all match;
+- paths, query strings, fragments, embedded credentials, and wildcards are
+  rejected;
+- approving one hostname does not approve subdomains, sibling hosts, or a
+  different port; and
+- any malformed non-empty entry fails evaluation instead of silently
+  weakening the configured policy.
+
+Do not put a Nightscout API token, capability URL, health data, or a URL
+containing credentials in the allowlist. Restart the application after
+changing the environment.
+
+## Connect safely
+
+Open **Settings → Integrations → Nightscout** and enter the instance base URL
+and, when required, its Nightscout API token. HealthLog stores the connection
+credentials encrypted. A public, read-only Nightscout instance can omit the
+token.
+
+For a private instance, configure the operator allowlist first and enter the
+same origin in Settings. For example, if the allowlist contains
+`https://cgm.internal.example:443`, these are not equivalent and remain
+blocked:
+
+```text
+http://cgm.internal.example:443
+https://cgm.internal.example:8443
+https://other.cgm.internal.example:443
+```
+
+The user-controlled private-host checkbox or request field cannot override
+this decision.
+
+## DNS pinning and redirects
+
+Every outbound request re-evaluates the stored origin against current server
+policy. For public destinations, HealthLog resolves the hostname, rejects
+private and embedded-private IPv4/IPv6 answers, and pins the approved address
+for the connection so DNS cannot change between validation and use. Redirects
+are validated and pinned again; a public URL cannot redirect into the local
+network.
+
+An exact private origin is intentionally allowed to resolve privately only
+because the operator named that complete origin. Removing it from
+`NIGHTSCOUT_PRIVATE_ORIGINS` takes authority away on the next fetch even if an
+older user preference remains stored.
+
+## Upgrade checklist
+
+1. Inventory private Nightscout connections without copying their tokens into
+   tickets or logs.
+2. Add only the exact origins that HealthLog must reach.
+3. Restart HealthLog so the environment is reloaded.
+4. Test the connection from Settings and confirm a sync succeeds.
+5. Remove obsolete origins promptly; do not use a broad DNS suffix or wildcard
+   as a substitute for explicit entries.
+
+If a previously working private connection reports that operator action is
+required, compare its exact scheme, host, and port with the allowlist. Do not
+restore access by changing the user's legacy opt-in.