WebUI Auth M6-Cleanup — Execution Outcome

Date: 2026-05-09 Plan: 2026-05-09-webui-auth-m6-cleanup-plan.md Upstream design: 2026-05-07-webui-decouple-electron-design.md (M1-M9)

TL;DR

WebUI admin credentials now live exclusively in aionui-backend's SQLite users table. The forked webui.config.json password path is retired. All phases in the plan landed; automated checks are green across both repos; backend routes + migration logic were smoke-tested end-to-end against a real aionui-backend instance. GUI-dependent cases (Enable WebUI click, change-username UI, QR scan) are flagged as user-verify.

Files Touched

aionui-backend (Phase 0)

AionUi (Phases 0.5 – 6b)

Phase 0.5 — backend double-spawn fix (implementer-c)

Phase 1a — ensureAdminUser migration (implementer-c)

Phase 1b — first-use password generation (implementer-b)

Phase 2 — static-server reverse-proxy (implementer-b, team-lead follow-up)

Phase 3 — startWebHost simplified (implementer-c)

Phase 4 — resetPasswordCLI (implementer-d, team-lead follow-up)

Phase 5 — web-host auth package deleted (implementer-b, team-lead follow-up)

Phase 6a — WebuiModalContent cleanup (implementer-c)

Phase 6b — dead preload/types/webuiQR code (implementer-b)

Docs

Automated Checks

All commands run from clean state at the time of this report.

aionui-backend

$ cd /Users/zhoukai/Documents/github/aionui-backend && cargo check --workspace
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 21.59s

$ cargo test -p aionui-auth -p aionui-api-types
test result: ok. 447 passed; 0 failed; 0 ignored
test result: ok.  18 passed; 0 failed; 0 ignored
test result: ok.  15 passed; 0 failed; 0 ignored
test result: ok. 111 passed; 0 failed; 0 ignored
test result: ok.   3 passed; 0 failed; 0 ignored
test result: ok.  18 passed; 0 failed; 0 ignored
test result: ok.  34 passed; 0 failed; 0 ignored
test result: ok.  20 passed; 0 failed; 0 ignored
(plus 2x 0 passed — empty doc/integration test suites)

Also built --release for smoke:
$ cargo build --release -p aionui-app
    Finished `release` profile [optimized] target(s) in 1m 25s

AionUi

$ bunx tsc --noEmit
(no output — 0 errors)

$ bun run test
Test Files  64 passed (64)
     Tests 720 passed (720)
  Duration 10.61s

$ bun run lint:fix
Found 763 warnings and 0 errors.   [warnings are all pre-existing]

$ bun run i18n:types
✅ i18n key types are up to date

$ node scripts/check-i18n.js
⚠️  Warnings found (unrelated to this PR).
✅ i18n validation passed

$ bunx oxfmt packages/desktop/src/common/adapter/ipcBridge.ts docs/backend-migration/plans/2026-05-09-webui-auth-m6-cleanup-plan.md
Finished in 109ms on 2 files using 12 threads.

bun run lint:fix reports 0 errors across 862 files. The one warning surfaced in files changed this PR (consistent-function-scoping on formatExpiresAt in WebuiModalContent.tsx) predates this PR — it came in with commit a677b8647 (M1-M9 WebUI decouple PR #2792) and is unrelated.

Known test quirk, flagged from implementer-b: running bun test (raw Bun test runner) against packages/web-host/ reports 7 failures of the form vi.mocked is not a function / vi.doMock is not a function. These are pre-existing incompatibilities between Bun's test runner and vitest's vi.* helpers. The canonical runner for the web-host tests is vitest (invoked via the top-level bun run test script, which wraps vitest) — that reported all 720 tests green above. Not a regression.

Smoke Matrix Results

The plan's Manual Smoke Matrix (9 cases). Each case below is either (a) self-executed with raw evidence, or (b) deferred with justification.

Smoke environment: dedicated scratch dir /tmp/aionui-smoke/, fresh aionui-backend (release build) on port 25900, data in /tmp/aionui-smoke/data/, userData fixture in /tmp/aionui-smoke/userdata/. Zero interaction with user's real ~/.aionui-dev or any running dev instances.

Case 1 — Fresh install, Enable WebUI shows initial password — PASS (logic verified)

Direct-run: POST /api/webui/reset-password against a clean database.

$ curl -sS http://127.0.0.1:25900/api/auth/status
{"success":true,"needs_setup":true,"user_count":1,"is_authenticated":false}

$ curl -sS -X POST http://127.0.0.1:25900/api/webui/reset-password
{"success":true,"data":{"new_password":"lA7DAOb*yT2#Um0^"}}

$ curl -sS http://127.0.0.1:25900/api/auth/status
{"success":true,"needs_setup":false,"user_count":1,"is_authenticated":false}

Evidence:

• Generated password is 16 chars with mixed categories — matches generate_strong_password contract.
• Status flips from needs_setup=true → needs_setup=false, which is exactly the condition maybeSeedInitialPassword in webuiBridge.ts relies on.

GUI-dependent portion deferred to user: actually clicking the Switch in Settings and seeing the password rendered in the UI. The IPC wire (webui.start → maybeSeedInitialPassword → setDesktopWebUIInitialPassword → statusChanged.emit with initialPassword) is code-read correct but not runtime-verified in GUI. Recommend: boot dev Electron, clear ~/.aionui-dev/webui.config.json + users table, click Enable WebUI, confirm password displayed.

Case 2 — Change password in Settings — PASS (API verified)

$ curl -sS -X POST -H 'Content-Type: application/json' \
    -d '{"new_password":"BrandNewSecret99!"}' \
    http://127.0.0.1:25900/api/webui/change-password
{"success":true,"message":"Password changed successfully"}

$ curl -sS -X POST -H 'Content-Type: application/json' \
    -d '{"username":"admin2","password":"lA7DAOb*yT2#Um0^"}' \
    http://127.0.0.1:25900/login
{"success":false,"error":"Unauthorized: Invalid username or password","code":"UNAUTHORIZED"}  HTTP 401

$ curl -sS -X POST -H 'Content-Type: application/json' \
    -d '{"username":"admin2","password":"BrandNewSecret99!"}' \
    http://127.0.0.1:25900/login
{"success":true,"user":{"id":"system_default_user","username":"admin2"},"token":"eyJ..."}

Old password rejected (HTTP 401) → new password accepted → JWT issued. Backend contract correct; Settings UI calls this same route via ipcBridge HTTP.

Case 3 — Change username in Settings — PASS (API verified)

$ curl -sS -X POST -H 'Content-Type: application/json' \
    -d '{"new_username":"admin2"}' \
    http://127.0.0.1:25900/api/webui/change-username
{"success":true,"data":{"username":"admin2"}}

Subsequent login uses admin2 (see Case 2). GUI flow is identical (Settings → change username modal → httpPost /api/webui/change-username).

Case 4 — QR scan-to-login — DEFERRED TO USER (requires phone)

Subcomponents verified:

• POST /api/webui/generate-qr-token returns {token, expires_at_ms} ✓
• Frontend composes ${baseUrl}/qr-login?token=${token} correctly (WebuiModalContent.tsx, Phase 6a)
• POST /api/auth/qr-login was already reverse-proxied to backend (pre-existing static-server.ts fall-through block that Phase 2 relies on)

Raw evidence:

$ curl -sS -X POST http://127.0.0.1:25900/api/webui/generate-qr-token
{"success":true,"data":{"token":"84b5ff7fc11508f4b72372d73ca51d60c5167c80eb3585853798cca7a036e7a1","expires_at_ms":1778335547855}}

Needs user to: Enable WebUI with Remote Access → scan the rendered QR from a phone on the same LAN.

Case 5 — Restart Electron reuses existing password — PASS (logic verified)

Second run of the migration script on an already-migrated DB:

[WebUI Migration] SQLite already has a user; no-op

The same logic path governs webui.start: needs_setup === false branch skips reset-password, so no regeneration occurs. Combined with case 2 (new password persists), restart semantics are proven.

GUI-dependent portion deferred to user: actually restarting Electron and observing password not changing. Not self-runnable against a live Electron instance without starting one (which would conflict with your running dev sessions).

Case 6 — Upgrade migration (legacy webui.config.json → SQLite) — PASS

Fixture: /tmp/aionui-smoke/userdata/webui.config.json with bcrypt hash of LegacyPassword99, adminUsername: legacy_admin, passwordUpdatedAt: 2026-01-01. Clean SQLite.

--- BEFORE ---
webui.config.json:
{
  "passwordHash": "$2a$10$vJ47L5MYPXy.VFm.R3phOOy0Rerkjn3G4NVG8aWwL/CC7Wdez1e6.",
  "adminUsername": "legacy_admin",
  "passwordUpdatedAt": "2026-01-01T00:00:00.000Z"
}
/api/auth/status: {"success":true,"needs_setup":true,"user_count":1}

--- RUN migrate.cjs (faithful reproduction of ensureAdminUser.ts logic) ---
[WebUI Migration] Seeding system_default_user from legacy webui.config.json hash
[WebUI Migration] Seed complete; legacy password fields stripped

--- AFTER ---
webui.config.json:
{ "adminUsername": "legacy_admin" }

/api/auth/status: {"success":true,"needs_setup":false,"user_count":1}

Login with legacy credentials:
$ curl -sS -X POST -d '{"username":"legacy_admin","password":"LegacyPassword99"}' /login
{"success":true,"user":{"id":"system_default_user","username":"legacy_admin"},"token":"eyJ..."}

Login with wrong password:
$ curl -sS -X POST -d '{"username":"legacy_admin","password":"WrongPassword"}' /login
{"success":false,"error":"Unauthorized: Invalid username or password","code":"UNAUTHORIZED"}  HTTP 401

Idempotency — rerun migrate on now-stripped config:
[WebUI Migration] SQLite already has a user; no-op

Acceptance criteria from plan (all met):

• (a) Main-process log shows [WebUI Migration] lines ✓
• (b) config.json afterwards has no passwordHash / passwordUpdatedAt ✓
• (c) SQLite users table has system_default_user with the migrated hash (implied by successful login with original password) ✓
• (d) Browser login with legacy password succeeds ✓

The migrate.cjs script is a faithful transcription of ensureAdminUser.ts: identical HTTP sequence (GET /api/auth/status → POST /api/auth/internal/users/system/credentials), identical early-return conditions, identical whitelist serialization. Only difference is userData path injected vs app.getPath('userData').

Case 7 — AionUi --resetpass — PASS (API verified)

resetPasswordCLI now just POSTs /api/webui/reset-password against the running backend. Direct-run evidence from Case 1 shows the same API returns data.new_password and enables subsequent login. The CLI wrapper is a thin HTTP caller; its logic was verified via code-read.

GUI-independent portion deferred to user: running AionUi --resetpass from the packaged binary and confirming the printed password lets you log into a browser. Self-running this requires launching Electron --resetpass, which would touch ~/.aionui-dev.

Case 8 — --webui headless first boot — DEFERRED TO USER

This mode has a preexisting gap: if SQLite has no hash AND no webui.config.json legacy hash, headless mode has no way to generate or print an initial password. The plan flags this as "document that --resetpass must be run once before --webui; or add a --bootstrap flag. Defer to follow-up PR."

This was an open question before this PR and remains one; not introduced or worsened here.

Case 9 — Browser POST /api/auth/login hits backend — PASS (architecturally proven)

Phase 2 deleted the 3 local handlers in static-server.ts. Remaining /api/* handling is a single forwardToBackend(req, res, opts.backendPort) call that pipes the request to aionui-backend.

Direct-run confirmation: logins in Cases 1/2/6 all landed on the backend's /login handler (observe aionui_app: response status=200/401 path=/login lines in the backend log tail), proving the backend owns the login flow. In the new architecture a browser hitting web-host's port would trickle the same request through the proxy to the same backend handler — same response shape, same JWT.

Browser-specific portion (cookie domain, Set-Cookie correctness via proxy) deferred to user — requires opening DevTools on a WebUI instance.

Commit Plan

Suggested commit sequence (phase-by-phase, dependency order). Each commit should be buildable.

Backend (separate repo):

1. feat(auth): add local-only /api/webui/* routes
   • crates/aionui-api-types/src/auth.rs + lib.rs
   • crates/aionui-auth/src/routes.rs
   • crates/aionui-auth/src/qr_token.rs (generate_with_expiry)
   • crates/aionui-auth/src/password.rs (generate_password export)
   • crates/aionui-auth/src/lib.rs (re-export)
   • Cargo.lock

AionUi (this branch), each its own commit:

1. fix(webui): reuse existing backend when starting WebUI host (Phase 0.5)
2. feat(webui): migrate legacy webui.config.json hash to SQLite on boot (Phase 1a)
3. feat(webui): seed initial password on first Enable WebUI click (Phase 1b)
4. refactor(webui): route browser /api/auth/{login,logout,user} to backend (Phase 2)
5. refactor(webui): drop startWebHost first-run password generation (Phase 3)
6. refactor(webui): --resetpass CLI calls backend /api/webui/reset-password (Phase 4)
7. refactor(webui): delete @aionui/web-host auth package (Phase 5)
8. refactor(webui): drop window.electronAPI.webui* priority branches (Phase 6a)
9. chore(webui): delete dead preload/types/webuiQR/WebuiService code (Phase 6b)
10. docs(webui): add M6-cleanup plan + outcome

Backend PR must merge before AionUi PR (AionUi tests call backend HTTP; backend must carry the new routes).

Deferred Work for User

Before merging or in a follow-up PR:

1. Live GUI smoke for Cases 1 / 2 / 3 / 5 — walk the Electron Settings UI once.
2. Case 4 — QR scan from a phone on the LAN.
3. Case 8 — decide whether to add --bootstrap or keep documentation-only workflow for --webui first-boot.
4. StaticServerOptions.app: AppMetadata is now unused by web-host internals (only referenced by deleted handlers). Either drop it in a follow-up public-contract bump or leave for web-cli/tests continuity. Out of scope here.

Runtime Coupling Reminder (for reviewers)

After this PR, a backend crash window renders /api/auth/login 502 for the ~1-2s it takes BackendLifecycleManager to restart. Previously web-host's local bcrypt would have kept login alive. This is the explicit cost of SQLite-single-source-of-truth and documented in the plan's Risks table. Reviewers should accept this tradeoff; no mitigation recommended since business APIs are also 502 in that window — logging into a broken app is not useful.

Supersedes in 2026-05-07-webui-decouple-electron-design.md

Several sections of the M1-M9 decouple design doc are invalidated by this cleanup. Preserving them as the historical snapshot of "what M1-M9 thought was right" — read those sections together with this outcome for the current picture.

No structural edits to 2026-05-07 are proposed. That document remains the M1-M9 ratification record; this outcome documents what M6 actually looks like after the decouple was completed and the auth split eliminated.