diff --git a/docs/superpowers/specs/2026-08-12-az-tc-01-ad-wifi-bootstrap-design.md b/docs/superpowers/specs/2026-08-12-az-tc-01-ad-wifi-bootstrap-design.md new file mode 100644 index 0000000..fdc5586 --- /dev/null +++ b/docs/superpowers/specs/2026-08-12-az-tc-01-ad-wifi-bootstrap-design.md @@ -0,0 +1,76 @@ +# AZ-TC-01 AD and WiFi bootstrap design + +## Goal + +Bring `AZ-TC-01` online as a reproducible pilot in two independent stages: + +1. Integrate the host with Active Directory. +2. Connect it temporarily to the WPA-Personal network `Pluto` using a shared password. + +Certificate-based access to the `Saturn` network remains out of scope until AD is proven functional. + +## Host profile + +`AZ-TC-01` remains on the `staging` site so unrelated production integrations stay disabled. Only AD and WiFi are enabled explicitly. + +The host uses these confirmed infrastructure values: + +- AD DNS domain: `az-group.local` +- Kerberos realm: `AZ-GROUP.LOCAL` +- Primary domain controller: `azdc01.az-group.local` (`192.168.152.253`) +- Secondary domain controller: `adpdc01.az-group.local` (`192.168.152.254`) +- Computer location: default `CN=Computers,DC=az-group,DC=local` container +- Temporary WPA-Personal SSID: `Pluto` + +## Active Directory bootstrap + +An administrator creates or joins the `AZ-TC-01` computer account from an admin workstation that can reach the domain controllers. `adcli` writes a binary host keytab for `AZ-TC-01.az-group.local` without altering the admin workstation's own keytab. + +The binary keytab is encrypted directly from the file into `secrets/AZ-TC-01-krb5-keytab.age`; it must never be copied through a text editor. The current encrypted placeholder is replaced. Before deployment, the decrypted result is checked with `klist -k -e` and must contain machine and host principals in `AZ-GROUP.LOCAL`. + +At boot, agenix decrypts it to `/etc/krb5.keytab` with mode `0600`. SSSD starts only after the age identity is available. Runtime verification covers Kerberos keytab readability, SSSD domain status, identity lookup, and an interactive AD login. + +## Temporary WPA-Personal WiFi + +The WiFi module supports two explicit modes: + +- `psk`: WPA-Personal using a per-host agenix secret. +- `eap-tls`: the existing certificate-based configuration for the later `Saturn` rollout. + +For this pilot, `AZ-TC-01` selects `psk` and SSID `Pluto`. The shared password is entered locally into `secrets/AZ-TC-01-wifi-psk.age`; it is never sent in chat or stored in Nix source. + +Agenix decrypts the password to a root-only runtime file. NetworkManager obtains the PSK at activation time without placing its plaintext in the Nix store. Enabling `psk` requires only the PSK secret; enabling `eap-tls` requires only the client certificate secret. This keeps the deferred `Saturn` certificate from blocking the pilot. + +## Secret and deployment flow + +The existing dedicated host age identity remains the recipient for both per-host secrets: + +- `AZ-TC-01-krb5-keytab.age` +- `AZ-TC-01-wifi-psk.age` + +The deployment preflight evaluates the enabled features, confirms each required encrypted file exists, and verifies that the injected host identity can decrypt it. The identity is copied to `/var/lib/agenix/identity.age` during installation. + +## Validation + +Before touching the target disk: + +1. Evaluate the host configuration and inspect its required secrets. +2. Validate the decrypted keytab with `klist -k -e`. +3. Run the deployment wrapper's non-destructive preflight. +4. Run the Nix flake checks and build the host closure. + +After boot: + +1. Confirm NetworkManager is connected to `Pluto` and DNS resolves both domain controllers. +2. Confirm Kerberos ports and time synchronization are available. +3. Check `systemctl status sssd` and `sssctl domain-status az-group.local`. +4. Resolve an AD user with `getent passwd` and `id`. +5. Perform an SDDM login with an AD account and verify offline credential caching only after one successful online login. + +## Failure handling and rollback + +- A missing or undecryptable required secret blocks deployment. +- An invalid keytab prevents SSSD startup and is diagnosed before deployment with `klist`. +- AD and WiFi stay independently switchable, so either can be disabled while diagnosing the other. +- Returning the host to base staging requires setting both feature flags to `false`; no production integrations are enabled implicitly. +- The future migration to `Saturn` changes the WiFi mode to `eap-tls`, replaces the SSID, installs the trusted RADIUS CA, and adds the client certificate secret. It does not alter the AD design.