P3-4: Setup wizard and zero-touch enrolment #33

New issue

Open

opened 2026-09-10 17:44:00 +00:00 by Cordy · 0 comments

Cordy commented

2026-09-10 17:44:00 +00:00

Owner

Depends on P3-3.

Goal

Success criterion #1 from the spec: a non-technical user completes setup in under two minutes with only a server URL and credentials. Measure it — time a real person.

Files

Create: internal/app/setup.go, frontend/setup.*

The flow

Server URL. Accept cairn.example.org, https://cairn.example.org, or https://cairn.example.org/dav/ and normalise all three. Users paste whatever they were sent. Probe the URL and report clearly if it is not a Cairn server, unreachable, or has a bad certificate.
Detect auth mode by asking the server (/auth/mode, as login.html already does). Then branch:
- local / LDAP: username and password directly.
- OIDC: the password field is useless here. Instead, direct the user to create an app password in the web UI and paste it — this is exactly what the WebDAV documentation already tells people to do. Link straight to the right page rather than describing where it is.
Choose the local folder. Default to ~/Cairn. Warn if the chosen folder is non-empty, and explain plainly what will happen: existing files will be uploaded, remote files will be downloaded, and nothing will be deleted.
Confirm and start. Show what is about to happen before the first sync begins, then hand over to the tray.

Zero-touch enrolment

Support a cairn:// URL and a QR code carrying the server URL (and optionally username), so an administrator can send one link that pre-fills steps 1 and 2. Register the URL scheme per platform.

If policy (P3-1) already supplies server, skip step 1 entirely and show it as managed.

Error messages carry the weight

This screen is where trust is won or lost. Be specific:

✗ "Connection failed" — useless.
✓ "Couldn't reach cairn.example.org. Check the address, or whether you need to be on the company VPN."
✓ "That server answered, but it isn't a Cairn instance."
✓ "Sign-in failed. On this server you need an app password rather than your normal password — create one under your avatar menu in Cairn."

Steps

Build the wizard screens.
Implement URL normalisation and server probing, with tests for all three input forms.
Implement auth-mode branching, including the OIDC app-password path.
Implement folder selection with the non-empty warning.
Implement cairn:// handling and QR parsing.
Time a real person doing it end to end. If it exceeds two minutes, cut a step.
Commit: git commit -s -m "feat(app): setup wizard with zero-touch enrolment"

Acceptance criteria

All three URL forms work.
OIDC users are guided to an app password rather than shown a dead password field.
A policy-supplied server is shown as managed and cannot be edited.
Verified under two minutes with someone who has not seen it before.

Depends on P3-3. ## Goal Success criterion #1 from the spec: **a non-technical user completes setup in under two minutes with only a server URL and credentials.** Measure it — time a real person. ## Files - Create: `internal/app/setup.go`, `frontend/setup.*` ## The flow 1. **Server URL.** Accept `cairn.example.org`, `https://cairn.example.org`, or `https://cairn.example.org/dav/` and normalise all three. Users paste whatever they were sent. Probe the URL and report clearly if it is not a Cairn server, unreachable, or has a bad certificate. 2. **Detect auth mode** by asking the server (`/auth/mode`, as `login.html` already does). Then branch: - **local / LDAP:** username and password directly. - **OIDC:** the password field is useless here. Instead, direct the user to create an **app password** in the web UI and paste it — this is exactly what the WebDAV documentation already tells people to do. Link straight to the right page rather than describing where it is. 3. **Choose the local folder.** Default to `~/Cairn`. Warn if the chosen folder is non-empty, and explain plainly what will happen: existing files will be uploaded, remote files will be downloaded, and nothing will be deleted. 4. **Confirm and start.** Show what is about to happen before the first sync begins, then hand over to the tray. ## Zero-touch enrolment Support a `cairn://` URL and a QR code carrying the server URL (and optionally username), so an administrator can send one link that pre-fills steps 1 and 2. Register the URL scheme per platform. If policy (P3-1) already supplies `server`, skip step 1 entirely and show it as managed. ## Error messages carry the weight This screen is where trust is won or lost. Be specific: - ✗ "Connection failed" — useless. - ✓ "Couldn't reach cairn.example.org. Check the address, or whether you need to be on the company VPN." - ✓ "That server answered, but it isn't a Cairn instance." - ✓ "Sign-in failed. On this server you need an app password rather than your normal password — create one under your avatar menu in Cairn." ## Steps - [ ] Build the wizard screens. - [ ] Implement URL normalisation and server probing, with tests for all three input forms. - [ ] Implement auth-mode branching, including the OIDC app-password path. - [ ] Implement folder selection with the non-empty warning. - [ ] Implement `cairn://` handling and QR parsing. - [ ] **Time a real person doing it end to end.** If it exceeds two minutes, cut a step. - [ ] Commit: `git commit -s -m "feat(app): setup wizard with zero-touch enrolment"` ## Acceptance criteria - All three URL forms work. - OIDC users are guided to an app password rather than shown a dead password field. - A policy-supplied server is shown as managed and cannot be edited. - Verified under two minutes with someone who has not seen it before.