Skip to content

docs: explain the remote-access error in user terms - #1000

Merged
frahlg merged 4 commits into
srcfl:masterfrom
HuggeK:docs/remote-access-error
Sep 3, 2026
Merged

docs: explain the remote-access error in user terms#1000
frahlg merged 4 commits into
srcfl:masterfrom
HuggeK:docs/remote-access-error

Conversation

@HuggeK

@HuggeK HuggeK commented Aug 29, 2026

Copy link
Copy Markdown
Contributor

Community users hitting remote access to protected API routes is disabled; configure FTW_API_TOKEN or use a local address currently have nothing to read: the string appears in the update dialog and settings with no link, docs/operations.md never quotes it, and the setup guide doesn't mention it. The confusion is predictable — the check is about the URL and source address, not the network, so people standing next to the Pi don't understand why they are "remote".

This adds:

  • a subsection in docs/operations.md under LAN and API access that quotes the message verbatim (so search finds it), states the two locality rules in user terms, and lists the common LAN traps: dot-free hostnames (not local since v2.2.1 / fix(api): stop treating no-dot hosts as local #952 — an address that worked before an update stops working), router names like pi.lan/ftw.fritz.box, Tailscale (100.x, *.ts.net), global-IPv6 resolution, and public reverse-proxy/HA-ingress URLs. It also says explicitly that the built-in UI never sends the token and that ?token=... in the URL does nothing.
  • one troubleshooting bullet in each of the five setup guides (en/sv/de/es/fr), linking to that subsection.
How this was verified against the code
  • Rules taken from isLocalAuthority / isLocalClient in go/internal/api/security.go on current master, including the fix(api): stop treating no-dot hosts as local #952 change that removed dot-free names from the local list (DNS-rebinding guard).
  • "UI never sends the token": no Authorization: Bearer writer and no token query-param reader anywhere under web/ (the tip circulating among users, appending ?token=... to the URL, is a placebo — it "works" only when the address is a private IP).
  • Prompted by a real support thread: a user on their LAN whose myhost:8080 bookmark broke after updating past v2.2.1; the direct private IP worked.

Docs-only change, so no changeset per the auto-exemption.

🤖 Generated with Claude Code

https://claude.ai/code/session_01JXoRP5AK9zCFxzB2N2Th9V

Co-authored-by: HuggeK <48095810+HuggeK@users.noreply.github.com>

@miravoss26 miravoss26 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Docs-only clarification for the "remote access to protected API routes is disabled" error, added to operations.md and all 5 setup-guide locales (de/en/es/fr/sv).

  • Content matches the actual locality rules (browser address bar + connection origin, both must be local) — consistent across all 5 language versions, no contradictions or drift between translations.
  • No code touched, nothing to break.

Safe to merge from my read.

@frahlg frahlg left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Checked against isLocalAuthority / isLocalClient in go/internal/api/security.go on master. The two rules, the no-dot guard (v2.2.1 / #952 / 5adda2f), .lan/.fritz.box exclusion, Tailscale 100.64/10 (not RFC1918, so IsPrivate is false), and "?token= does nothing" all match the code. The UI has no Bearer writer and no token query-param reader.

The quoted error string is exact, so search finds it. Setup-guide bullets in all five locales point at the same subsection.

@frahlg
frahlg merged commit 937f834 into srcfl:master Sep 3, 2026
14 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants