From b5cfd26f5fc6d1c2a7cddd429d906f067fc65e57 Mon Sep 17 00:00:00 2001 From: sysadmin Date: Tue, 9 Jun 2026 01:41:48 +0100 Subject: [PATCH] docs(windows): SilverOS Welcome app spec (v1) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit First-logon Blazor Hybrid (MAUI) onboarding app: bootstrap auto-login -> wizard (persona->flavour, account + BitLocker PIN, prefs) -> apply via the existing §A-H PowerShell modules per a JSON flavour manifest -> create real account, enrol BitLocker, self-destruct bootstrap. Resolves the repo-throwaway-password and interactive-PIN gaps. v1 = interactive auto-launch only; silent pre-baked mode + fleet enrolment + Linux-shared model deferred. Co-Authored-By: Claude Opus 4.8 --- windows/welcome-app-spec.md | 109 ++++++++++++++++++++++++++++++++++++ 1 file changed, 109 insertions(+) create mode 100644 windows/welcome-app-spec.md diff --git a/windows/welcome-app-spec.md b/windows/welcome-app-spec.md new file mode 100644 index 0000000..89660f5 --- /dev/null +++ b/windows/welcome-app-spec.md @@ -0,0 +1,109 @@ +# SilverOS Welcome — Specification (v1) + +> **Status**: design approved 2026-06-09. Part of **SilverMetal Enhanced — Windows**. +> First-logon onboarding app that turns a hardened image into a personalised device: +> the user picks a **flavour**, creates their **account + BitLocker PIN**, and the app +> applies the chosen configuration by orchestrating the existing §A–H hardening modules. + +Bound by [`hardening-spec.md`](hardening-spec.md), [`iso-builder.md`](iso-builder.md), and the SilverMetal [`../docs/design-principles.md`](../docs/design-principles.md). + +## 1. Purpose & positioning + +Today the image applies **one fixed** hardening config at first boot (`SetupComplete.cmd` → §A–H modules). The Welcome app makes "SilverMetal Enhanced — Windows" a **selectable platform**: a friendly first-logon wizard where the buyer chooses *what the device is for* (a **flavour** = config profile + app set), sets up their own account, and the device configures itself accordingly. + +It also resolves two real gaps found during VM validation: +- **No throwaway credential in the public repo** — the committed account becomes a locked **bootstrap** account that **self-destructs** after onboarding. +- **BitLocker PIN enrollment** — collected interactively in the wizard (BitLocker TPM+PIN can't be fully automated; this is the right place for it). + +**v1 = interactive auto-launch only.** A fully-silent pre-baked SKU mode is a later phase (§8). + +## 2. Architecture & components + +A **Blazor Hybrid (.NET MAUI + WebView2)** desktop app, published **self-contained** (bundled runtime) and baked into the image. Reuses SilverSHELL components + the SilverDESK "Welcome" wizard aesthetic (Mercury). Four well-bounded units: + +| Unit | Responsibility | Depends on | +|---|---|---| +| **Welcome.Shell** | MAUI host + wizard UI (the steps in §3). What the user sees. | Welcome.Flavours, Welcome.Apply | +| **Welcome.Flavours** | Load + validate flavour manifests from `windows/flavours/*.json` (baked into the image). | manifest schema | +| **Welcome.Apply** | Orchestrator: run the §A–H PowerShell modules per the manifest, install the app set, create the real account, enrol BitLocker, tear down the bootstrap. | PowerShell modules, Windows account/BitLocker APIs | +| **Welcome.Bootstrap** | Answer-file / AutoLogon / RunOnce wiring that auto-logs-in and launches the app. | autounattend, build.ps1 | + +Each unit is independently testable: Welcome.Apply can run headless against a flavour manifest (no UI); Welcome.Flavours validates manifests without applying; the Shell can be run with a mock applier. + +## 3. Boot → onboard → handoff flow (bootstrap lifecycle) + +1. **Image** ships a **locked bootstrap admin account** (`sm-bootstrap`) with **AutoLogon (LogonCount=1)** and a RunOnce/custom-shell that launches the Welcome app in a kiosk-ish session (no taskbar/Explorer escape). The §A–H modules **no longer run from `SetupComplete`** — `SetupComplete` only stages the payload; the Welcome app applies it. +2. **First logon** (auto, as `sm-bootstrap`) → Welcome app launches. Wizard steps: + - **Welcome** — brand intro. + - **What's this device for?** — persona → selects a **flavour** (cards: Privacy-Max / Daily-Driver / Journalist / Developer). + - **Create your account** — username + password (+ confirm). + - **Secure this device** — set a **BitLocker PIN** (≥ flavour-min). + - **Preferences** — a few toggles (e.g. telemetry-floor confirmation, browser default, timezone). + - **Apply** — progress UI while Welcome.Apply runs. + - **Done** — "restart to finish." +3. **Apply** (Welcome.Apply, elevated): + - run the flavour's **hardening modules** (per manifest) + **app-set** install; + - **create the real account** (admin) with the entered credentials; + - **enrol BitLocker TPM+PIN** with the entered PIN; + - remove AutoLogon + the RunOnce. +4. **Self-destruct + reboot** — delete the `sm-bootstrap` account, then **reboot** into the real account (also activates VBS/Credential Guard, which need a reboot). + +## 4. Flavour manifest model + +A flavour is a JSON file in `windows/flavours/` baked into the image: + +```jsonc +{ + "id": "privacy-max", + "label": "Privacy-Max", + "description": "Maximum lockdown. Everything Microsoft exposes, turned to its tightest.", + "hardening": { + "modules": ["00","01","02","03","04","05","06","07"], // which §A-H modules + "params": { "wdac": "enforce", "telemetry": "security" } // per-module overrides + }, + "appSet": ["SilverBrowser","SilverVPN","SilverKeys","SilverDuress"], + "settings": { "defaultBrowser": "SilverBrowser", "autoLock": 120 } +} +``` + +**Welcome.Apply orchestrates the existing PowerShell §A–H modules** per `hardening.modules`/`params` — PowerShell stays the single source of truth for *what hardening does* (also reusable headless for the future silent SKU). *(Rejected alternative: re-implement hardening in a .NET library — cleaner for an all-.NET app but duplicates the proven logic.)* The Shell renders one card per manifest; adding a flavour = adding a JSON file. + +**Starter flavours (v1):** Privacy-Max, Daily-Driver, Journalist, Developer — differing in hardening strictness (e.g. WDAC enforce vs audit, relaxed dev tooling) and app set. + +## 5. Account & BitLocker integration + +- The **real account** is created as a local **Administrator** (personal-device owner). *(Standard-user/least-privilege as a flavour option is a later enhancement — persona was chosen as the role axis, not privilege.)* +- **BitLocker TPM+PIN** is enrolled with the user's PIN during Apply (`Enable-BitLocker -TpmAndPinProtector`), satisfying module C's interactive step. Recovery key stored offline / shown to the user (never cloud-escrowed) per `hardening-spec.md` §C. +- The **bootstrap account** is admin only so the app can run hardening + manage accounts; it is deleted in step 4 so no standing extra admin remains. + +## 6. Build & repo integration + +- New **`windows/welcome/`** (MAUI app source) + **`windows/flavours/*.json`**. +- **`build.ps1`** gains a stage that drops the **published Welcome app + flavours** into the image (`/Program Files/SilverMetal/Welcome` + a flavours dir), and wires the bootstrap (AutoLogon + RunOnce) via the answer file / offline registry. +- The **answer file** switches from "create `silvermetal`/`open sesame`" to "create **`sm-bootstrap`** + AutoLogon + launch Welcome." `SetupComplete.cmd` stops running the §A–H modules directly (the Welcome app runs them). +- A repo switch (**`vars.SILVERMETAL_WELCOME_ENABLED`**, default on) controls whether the build wires onboarding or falls back to today's direct-hardening behaviour (so the current validated path remains available). + +## 7. Testing + +- **Welcome.Flavours**: unit tests validate every shipped manifest against the schema. +- **Welcome.Apply**: headless run against each flavour on the VM (reuses the SLAB01 VM-test harness) → assert the firstboot/apply log shows the expected modules + the real account + BitLocker protector + bootstrap removed. +- **Welcome.Shell**: bUnit-style component tests for step navigation/validation; a manual VM pass for the full wizard. +- The existing **offline ISO assertions** extend to check the Welcome app + flavours are baked. + +## 8. v1 scope + +**In:** interactive auto-launch onboarding; persona→flavour; account + BitLocker-PIN creation; prefs; apply-via-PowerShell-modules; bootstrap self-destruct; 3–4 starter flavours; build/answer-file wiring + `WELCOME_ENABLED` switch. + +**Out (later phases):** +- **Silent pre-baked mode** (apply a baked flavour + pre-set account with no wizard — the "we did everything for you" SKU). +- **SilverDESK / fleet enrollment** role. +- **Shared flavour model with the Linux line.** +- **Real Stack app installs** — the app-set installer is wired, but Stack entries remain stubs until native Windows Stack builds exist (M4). +- **Standard-user/least-privilege** real account option. + +## 9. Open questions / risks + +- **WebView2 + .NET runtime in the image** — confirm WebView2 Evergreen is present on IoT Enterprise LTSC (or bundle the fixed-version runtime); self-contained publish covers .NET. +- **Kiosk lock-down of the bootstrap session** — ensure the user can't escape the wizard to a privileged shell before the real account exists. +- **Apply failure handling** — if a module fails mid-apply, the wizard must surface it and leave the device in a recoverable state (don't delete bootstrap until apply + account creation succeed). +- **Naming** — "SilverOS Welcome" vs "SilverMetal Welcome" (the program is SilverMetal; "SilverOS" is the floated umbrella). Cosmetic; decide before first release.