First-run wizards polish: homelab IP placeholder, i18n of setup/login + errors, /setup after closure, restart semantics, path/body hardening, copy #843

Closed
opened 2026-10-03 16:37:38 +00:00 by Cordy · 4 comments
Owner

Found in the #533 QA pass (2026-10-03). These are QA findings 7–12 and 14, grouped because they touch the same three pages (storage-setup.html, setup.html, login.html) and cmd/cairnd/setupmode.go / internal/auth/setup.go.

Findings

  1. Homelab address shipped in product UI. The storage wizard's S3 endpoint placeholder is http://192.168.10.32:3900 (web/static/storage-setup.html:100), the dogfood Garage address. Replace it with a neutral example such as https://s3.example.com, and the region placeholder garage with us-east-1.
  2. Languages.
    • /storage-setup has EN/DE/FR/IT, but its error line shows the raw English server message ("invalid setup token") in every language.
    • /setup and /login have no language selector at all and are English-only.
    • For a German, French or Italian speaking public-sector deployer, the very first screens are English.
  3. Bookmarked /setup after closure. It redirects to /login?next=/setup, and after signing in shows a raw "404 page not found". Once setup is closed, /setup should redirect to / (or the login with next=/).
  4. "Restarting" really means "exiting". After the storage wizard saves the pointer, the process os.Exit(0)s and relies on the supervisor. Compose has restart: unless-stopped, but a bare docker run without --restart simply stops, and the wizard page waits forever. Say it in deployment.md and in the success text ("If the page doesn't come back in a minute, start the container again"). Optionally re-exec in-process instead of exiting.
  5. Relative directory path accepted. It's resolved against the working directory and would be stored relative in the bootstrap pointer, which is fragile across restarts. Require an absolute path (400 "use an absolute path inside the container").
  6. POST /setup decodes an unbounded body (no http.MaxBytesReader) while setup is pending, and it's unauthenticated. The storage wizard caps at 64 KiB; do the same here and on POST /auth/password.
  7. Long dashes in copy. These break the house rule:
    • storage wizard: "…is the host's job — Cairn never mounts anything" (EN; other languages to check);
    • setup: "setup closes permanently — further accounts…".

Research

  • Nextcloud's web installer and Grafana's first login are fully localised and follow the browser language. Nextcloud's installer had a long tail of issues where server-side validation messages stayed English; they solved it by returning error codes that the client translates. Same approach here: the API returns {error, code} and the page maps the code to its four languages, falling back to the text.
  • Portainer and Grafana both document that the container must run with a restart policy for their restart-on-config flows. Portainer's "restart required" pages are a recurring support topic when people use plain docker run.
  • Placeholder leaks like internal hostnames and IPs in shipped UI are routinely flagged in security reviews as information disclosure, low severity but trivially avoidable. A CI grep for RFC 1918 addresses in web/static stops recurrence.

Plan

  1. Neutral placeholders, plus a web test that fails on any 192.168., 10. or 172.16-31. literal in web/static/*.html.
  2. Wizard and auth APIs return {error, code}.
    • The three pages share one small i18n dictionary block (EN/DE/FR/IT) and a language selector.
    • The default follows the Accept-Language / navigator.language order the main app uses.
    • Error codes are translated, falling back to the text.
  3. /setup with setup closed → 302 to /.
  4. Deployment docs plus the success text cover the restart policy.
  5. Absolute-path check in probeStorage, with a test.
  6. MaxBytesReader of 64 KiB on POST /setup and POST /auth/password, with a test.
  7. Copy without long dashes in all four languages, and extend the existing no-U+2014 web test to these pages.

Tests

Placeholder grep; code → translated text per language; /setup closed → redirect; relative path → 400; oversized body → 413; no-dash check on all three pages.

Found in the #533 QA pass (2026-10-03). These are QA findings 7–12 and 14, grouped because they touch the same three pages (`storage-setup.html`, `setup.html`, `login.html`) and `cmd/cairnd/setupmode.go` / `internal/auth/setup.go`. ## Findings 1. **Homelab address shipped in product UI.** The storage wizard's S3 endpoint placeholder is `http://192.168.10.32:3900` (web/static/storage-setup.html:100), the dogfood Garage address. Replace it with a neutral example such as `https://s3.example.com`, and the region placeholder `garage` with `us-east-1`. 2. **Languages.** - `/storage-setup` has EN/DE/FR/IT, but its error line shows the **raw English server message** ("invalid setup token") in every language. - **`/setup` and `/login` have no language selector at all** and are English-only. - For a German, French or Italian speaking public-sector deployer, the very first screens are English. 3. **Bookmarked `/setup` after closure.** It redirects to `/login?next=/setup`, and after signing in shows a raw "404 page not found". Once setup is closed, `/setup` should redirect to `/` (or the login with `next=/`). 4. **"Restarting" really means "exiting".** After the storage wizard saves the pointer, the process `os.Exit(0)`s and relies on the supervisor. Compose has `restart: unless-stopped`, but a bare `docker run` without `--restart` simply stops, and the wizard page waits forever. Say it in deployment.md and in the success text ("If the page doesn't come back in a minute, start the container again"). Optionally re-exec in-process instead of exiting. 5. **Relative directory path accepted.** It's resolved against the working directory and would be stored relative in the bootstrap pointer, which is fragile across restarts. Require an absolute path (400 "use an absolute path inside the container"). 6. **`POST /setup` decodes an unbounded body** (no `http.MaxBytesReader`) while setup is pending, and it's unauthenticated. The storage wizard caps at 64 KiB; do the same here and on `POST /auth/password`. 7. **Long dashes in copy.** These break the house rule: - storage wizard: "…is the host's job — Cairn never mounts anything" (EN; other languages to check); - setup: "setup closes permanently — further accounts…". ## Research - **Nextcloud's web installer and Grafana's first login are fully localised** and follow the browser language. Nextcloud's installer had a long tail of issues where server-side validation messages stayed English; they solved it by returning error *codes* that the client translates. Same approach here: the API returns `{error, code}` and the page maps the code to its four languages, falling back to the text. - **Portainer and Grafana both document that the container must run with a restart policy** for their restart-on-config flows. Portainer's "restart required" pages are a recurring support topic when people use plain `docker run`. - **Placeholder leaks** like internal hostnames and IPs in shipped UI are routinely flagged in security reviews as information disclosure, low severity but trivially avoidable. A CI grep for RFC 1918 addresses in `web/static` stops recurrence. ## Plan 1. Neutral placeholders, plus a web test that fails on any `192.168.`, `10.` or `172.16-31.` literal in `web/static/*.html`. 2. Wizard and auth APIs return `{error, code}`. - The three pages share one small i18n dictionary block (EN/DE/FR/IT) and a language selector. - The default follows the `Accept-Language` / `navigator.language` order the main app uses. - Error codes are translated, falling back to the text. 3. `/setup` with setup closed → 302 to `/`. 4. Deployment docs plus the success text cover the restart policy. 5. Absolute-path check in `probeStorage`, with a test. 6. `MaxBytesReader` of 64 KiB on `POST /setup` and `POST /auth/password`, with a test. 7. Copy without long dashes in all four languages, and extend the existing no-U+2014 web test to these pages. ### Tests Placeholder grep; code → translated text per language; `/setup` closed → redirect; relative path → 400; oversized body → 413; no-dash check on all three pages.
Author
Owner

Research honesty note: none of the "Research" bullets above are backed by a source I checked. That covers the Nextcloud installer's error codes, Portainer's and Grafana's restart-policy docs, and placeholder leaks being flagged in reviews. They are background knowledge, so verify them before relying on them. The findings and the plan stand on their own: each finding was reproduced locally.

Research honesty note: none of the "Research" bullets above are backed by a source I checked. That covers the Nextcloud installer's error codes, Portainer's and Grafana's restart-policy docs, and placeholder leaks being flagged in reviews. They are background knowledge, so verify them before relying on them. The findings and the plan stand on their own: each finding was reproduced locally.
Author
Owner

Sourced research. This replaces the unsourced "Research" section above.

1. Internal IP in shipped UI (finding 1)

  • Private-IP disclosure in response bodies is a standard scanner finding: CWE-200, rated Low. It is flagged by PortSwigger (Burp), OWASP ZAP, Invicti/Acunetix and StackHawk.
  • The impact cited is network mapping that helps later attacks, and the fix is to sanitize output.
  • Beyond best practice: a CI grep for RFC 1918 literals in web/static, so it can't come back.

2. Languages on setup and login (finding 2)

  • What failed at Nextcloud:
    • The login page ignored the configured default_language / force_language (server #17329) and followed the browser instead.
    • Some setup and personal pages kept showing English after a language change.
    • Locale errors during install showed up in an unexpected language.
  • Lessons:
    • The pre-login pages must follow one clear rule: explicit choice, then instance default, then browser.
    • Server-side messages must be translated by the client, not by the server.
  • Grafana:
    • Authentication UI (login, registration, password reset) is part of its translated surface since 9.3, using i18next with an English fallback.
    • default_language = detect follows the browser.
  • Plan refined:
    • API errors carry a stable code, and the three pages translate codes, falling back to English text.
    • Language order: ?lang / stored choice, then the instance default (the Basic settings language, if set), then navigator.language.
    • The selector is shared by all three pages.

3. Restart after the storage wizard (finding 4)

  • Portainer:
    • Has the same "restart required" dependency.
    • Docker's default restart policy is no, so a plain docker run doesn't come back.
    • Its own FAQ tells users to restart the container by hand. For example, after its 5-minute initial-admin timeout ("Your Portainer instance has timed out for security purposes").
    • That's exactly the support trap to avoid.
  • Plan refined:
    • Prefer an in-process re-exec (syscall.Exec of the same binary and args). The wizard then never depends on a restart policy.
    • Keep the exit as the fallback when re-exec isn't possible, plus the doc line.
  • Cairn's token-gated wizard already avoids Portainer's timeout-and-race design (see #533 research). Nothing to copy there.

4. Unbounded body on unauthenticated endpoints (finding 6)

  • Same pattern, rated as real advisories:
    • Argo Workflows GHSA-jcc8-g2q4-9fxq: unauthenticated memory exhaustion, with the whole body read before auth;
    • Mailpit CVE-2026-45713;
    • several "login buffers unbounded JSON before authentication" reports in Go projects.
  • The fix everywhere is http.MaxBytesReader. A plain io.LimitReader silently truncates instead of answering 413.
  • Plan refined: 64 KiB MaxBytesReader on POST /setup, POST /auth/password and any other pre-auth JSON endpoint.
    • Beyond best practice: a small test lists every pre-auth route and asserts a body cap, so new ones can't slip in.

Refs:

**Sourced research. This replaces the unsourced "Research" section above.** **1. Internal IP in shipped UI (finding 1)** - Private-IP disclosure in response bodies is a standard scanner finding: CWE-200, rated Low. It is flagged by PortSwigger (Burp), OWASP ZAP, Invicti/Acunetix and StackHawk. - The impact cited is network mapping that helps later attacks, and the fix is to sanitize output. - Beyond best practice: a CI grep for RFC 1918 literals in `web/static`, so it can't come back. **2. Languages on setup and login (finding 2)** - **What failed at Nextcloud:** - The login page ignored the configured `default_language` / `force_language` (server #17329) and followed the browser instead. - Some setup and personal pages kept showing English after a language change. - Locale errors during install showed up in an unexpected language. - **Lessons:** - The pre-login pages must follow one clear rule: explicit choice, then instance default, then browser. - Server-side messages must be translated by the client, not by the server. - **Grafana:** - Authentication UI (login, registration, password reset) is part of its translated surface since 9.3, using i18next with an English fallback. - `default_language = detect` follows the browser. - **Plan refined:** - API errors carry a stable `code`, and the three pages translate codes, falling back to English text. - Language order: `?lang` / stored choice, then the instance default (the Basic settings language, if set), then `navigator.language`. - The selector is shared by all three pages. **3. Restart after the storage wizard (finding 4)** - **Portainer:** - Has the same "restart required" dependency. - Docker's default restart policy is **`no`**, so a plain `docker run` doesn't come back. - Its own FAQ tells users to restart the container by hand. For example, after its 5-minute initial-admin timeout ("Your Portainer instance has timed out for security purposes"). - That's exactly the support trap to avoid. - **Plan refined:** - Prefer an **in-process re-exec** (`syscall.Exec` of the same binary and args). The wizard then never depends on a restart policy. - Keep the exit as the fallback when re-exec isn't possible, plus the doc line. - Cairn's token-gated wizard already avoids Portainer's timeout-and-race design (see #533 research). Nothing to copy there. **4. Unbounded body on unauthenticated endpoints (finding 6)** - Same pattern, rated as real advisories: - Argo Workflows GHSA-jcc8-g2q4-9fxq: unauthenticated memory exhaustion, with the whole body read before auth; - Mailpit CVE-2026-45713; - several "login buffers unbounded JSON before authentication" reports in Go projects. - The fix everywhere is `http.MaxBytesReader`. A plain `io.LimitReader` silently truncates instead of answering 413. - **Plan refined:** 64 KiB `MaxBytesReader` on `POST /setup`, `POST /auth/password` and any other pre-auth JSON endpoint. - Beyond best practice: a small test lists every pre-auth route and asserts a body cap, so new ones can't slip in. Refs: - https://portswigger.net/kb/issues/00600300_private-ip-addresses-disclosed - https://www.zaproxy.org/alerttags/cwe-200/ - https://github.com/nextcloud/server/issues/17329 - https://github.com/grafana/grafana/blob/main/contribute/internationalization.md - https://docs.portainer.io/faqs/installing/your-portainer-instance-has-timed-out-for-security-purposes-error-fix - https://oneuptime.com/blog/post/2026-03-20-portainer-restart-policies/view - https://github.com/argoproj/argo-workflows/security/advisories/GHSA-jcc8-g2q4-9fxq - https://www.kodemsecurity.com/cve-archive/cve-2026-45713 - https://github.com/weavster-dev/weavster/issues/256
Author
Owner

Decisions (Nikola, 2026-10-10)

  • Restart after the storage wizard: Cairn restarts itself in place (re-exec of the same binary and arguments), with exiting kept as the fallback when re-exec isn't possible. deployment.md gets the restart-policy line either way.
  • Language selector: a small mockup was requested and is shown in 843-langsel-mockup.html. Three placements are compared on the sign-in page; option A, top right in the card, is the same control the storage wizard already has. The placement is awaiting Nikola's choice.

All other items have no UI impact (placeholder, /setup after closure, absolute path, body cap, long dashes).

## Decisions (Nikola, 2026-10-10) - **Restart after the storage wizard:** Cairn restarts itself in place (re-exec of the same binary and arguments), with exiting kept as the fallback when re-exec isn't possible. deployment.md gets the restart-policy line either way. - **Language selector:** a small mockup was requested and is shown in `843-langsel-mockup.html`. Three placements are compared on the sign-in page; option A, top right in the card, is the same control the storage wizard already has. The placement is awaiting Nikola's choice. All other items have no UI impact (placeholder, `/setup` after closure, absolute path, body cap, long dashes).
Author
Owner

Decision (Nikola, 2026-10-10): language selector placement A, top right in the card, matching the storage wizard. The spec and plan are on branch batch-v07d: docs/superpowers/specs/2026-10-10-batch-v07d-design.md and docs/superpowers/plans/2026-10-10-batch-v07d.md. #843 and #867 are batched together for v0.6.325.

**Decision (Nikola, 2026-10-10): language selector placement A**, top right in the card, matching the storage wizard. The spec and plan are on branch `batch-v07d`: `docs/superpowers/specs/2026-10-10-batch-v07d-design.md` and `docs/superpowers/plans/2026-10-10-batch-v07d.md`. #843 and #867 are batched together for v0.6.325.
Cordy closed this issue 2026-10-10 12:22:30 +00:00
Sign in to join this conversation.
No labels
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference: Cordy/Cairn#843
No description provided.