authforge/docs/plans/2026-04-26-ubuntu-fido-design.md

# ubuntu-fido — Design Document

**Date:** 2026-04-26
**Status:** Draft (brainstorm complete, validated through Section 2 with stakeholder)
**Owner:** Dangerous Things (ops@dangerousthings.com)

## Problem

Enabling U2F / FIDO2 passkey / TOTP on Ubuntu desktops today is a manual, error-prone process. `libpam-u2f` exists and works, but:
- New-account enrollment requires the admin to either physically have the user's key at provisioning time, or talk the user through `pamu2fcfg` over chat.
- There is no GUI. Admins hand-edit `/etc/pam.d/*` files, with no safety net against locking themselves out.
- There is no first-login enrollment pattern equivalent to Windows OOBE / macOS Setup Assistant.
- TOTP and U2F live in separate, unrelated tools.

This project ships a single deb package that gives end users and admins a turnkey path to MFA — install, click, done — while staying compatible with fleet-management workflows.

## Scope decisions (locked)

| # | Decision | Reasoning |
|---|---|---|
| 1 | **Audience: end-user-first, admin-extensible.** PPA + apt + GUI is the headline path; drop-in `/etc/` config files cover fleet/Ansible. | Maximizes reach and matches Dangerous Things' customer mix (hobbyists + small business IT). |
| 2 | **v1 target: Ubuntu LTS + GNOME.** Ultimate target: Ubuntu + Debian × GNOME + KDE Plasma. | ~25–30% of Linux desktop on day one, ~50–60% at target state. v1 ships in months not years. |
| 3 | **GUI: standalone GTK4/libadwaita app + optional gnome-control-center Users-panel shortcut deb.** | gnome-control-center has no stable plugin API. Standalone app is forward-compatible; shortcut deb adds discoverability without coupling to GNOME release cycle. |
| 4 | **Authenticators: U2F + FIDO2 passkey + TOTP.** TOTP behind a build-time feature flag. | Full scope as written; flag lets us ship a beta without TOTP if the QR/recovery-code UX slips schedule. |
| 5 | **Policy contexts: 3 in main GUI (gdm-password, sudo, sshd) with Disabled / Optional / Required modes.** Full list (polkit, su, login, plus auto-detected stacks) under pkexec admin gate or via `/etc/ubuntu-fido/policy.d/*.conf`. | 95% case stays simple; advanced/fleet path unrestricted. Mandatory pre-commit lockout simulation. |
| 6 | **First-login enrollment: `chage -d 0` + autostart enrollment app + small `pam_ubuntu_fido_pending.so` blocking module.** | Belt-and-suspenders: leverages existing forced-password-change, adds enrollment via autostart, PAM module ensures user can't bypass by killing the modal. |

## Architecture

```
┌─────────────────────────┐  ┌──────────────────────────┐  ┌──────────────┐
│  ubuntu-fido GTK app    │  │  ubuntu-fidoctl (CLI)    │  │  Future KDE  │
│  (libadwaita panel)     │  │  (admin/fleet scripting) │  │  KCM module  │
└─────────────┬───────────┘  └────────────┬─────────────┘  └──────┬───────┘
              │ D-Bus (org.dt.UbuntuFido) │                        │
              └─────────────┬─────────────┴────────────────────────┘
                            ▼
            ┌────────────────────────────────────┐
            │  ubuntu-fidod  (system daemon)     │   ← polkit-mediated
            │  - enrollment orchestration        │
            │  - policy read/write + lockout     │
            │    safety simulation               │
            │  - libfido2 bindings (Rust)        │
            │  - PAM stack edits via             │
            │    pam-auth-update                 │
            └────────────────┬───────────────────┘
                             ▼
   ┌─────────────────┬───────┴────────┬──────────────────────┐
   ▼                 ▼                ▼                      ▼
/etc/pam.d/*    /etc/ubuntu-fido/  ~/.config/Yubico/   /var/lib/ubuntu-fido/
(stack edits    policy.d/*.conf   u2f_keys (per-user)  pending/<user>
via pam-auth-   (admin/fleet      /etc/u2f_mappings    (first-login flag)
update)         drop-ins)         (central override)
```

### Trust boundary

The daemon owns all writes to `/etc/pam.d/`, `/etc/ubuntu-fido/`, and `/var/lib/ubuntu-fido/`. GUIs never write these directly. polkit policies decide who can call which method:

| D-Bus method | Default polkit action |
|---|---|
| `EnrollOwn(user)`, `RemoveOwn(user)` | `auth_self_keep` (user authenticates with password once per 5 min) |
| `EnrollOther(user)`, `SetPolicy(...)`, `SetPendingFlag(user)` | `auth_admin_keep` (admin password) |
| `GetState()`, `GetPolicy()` | `yes` (read is free) |

### Why Rust for the daemon

- Memory safety in code that handles credential material.
- `ctap-hid-fido2` and `webauthn-rs` crates are mature and actively maintained.
- Cross-compiles cleanly to other platforms if the project ever expands beyond Linux.
- Slightly larger build footprint than C, immaterial for a deb package.

## Package layout

| Package | Contents | Type |
|---|---|---|
| `ubuntu-fido` | Empty metapackage. | Depends |
| `ubuntu-fido-daemon` | `/usr/sbin/ubuntu-fidod`, systemd unit (`ubuntu-fido.service`), D-Bus service file, polkit rules under `/usr/share/polkit-1/actions/` | Hard dep of metapackage |
| `ubuntu-fido-pam` | `/usr/lib/$DEB_HOST_MULTIARCH/security/pam_ubuntu_fido_pending.so`, pam-auth-update profile at `/usr/share/pam-configs/ubuntu-fido` | Hard dep |
| `ubuntu-fido-cli` | `/usr/bin/ubuntu-fidoctl` (Rust binary, talks D-Bus) | Hard dep |
| `ubuntu-fido-gui` | `/usr/bin/ubuntu-fido` (GTK4/libadwaita), `.desktop` file with `Categories=Settings;Security;`, app icon | **Recommends** (so headless servers can skip) |
| `ubuntu-fido-gnome-integration` | Tiny shim that adds a "Configure security…" launcher button to gnome-control-center's Users panel via overlay `.desktop` extension | **Suggests** (not auto-installed) |

### Headline install

```bash
sudo add-apt-repository ppa:dangerousthings/ubuntu-fido
sudo apt install ubuntu-fido
```

Two commands. After install:
- Daemon is running.
- All PAM policy is **Disabled** by default. Installation never enables MFA enforcement on its own.
- GUI is available from Activities (search "Authentication" or "Security Keys").
- Empty state: "No security keys configured. Plug in or scan a key to enroll."

### Headless / fleet install

```bash
apt install ubuntu-fido-daemon ubuntu-fido-pam ubuntu-fido-cli
```
Skips the GUI metadata. Configure via `/etc/ubuntu-fido/policy.d/90-fleet.conf` or `ubuntu-fidoctl`. We additionally publish:

- An **Ansible role** `dangerousthings.ubuntu_fido` on Galaxy wrapping `apt + debconf + drop-in config`.
- A **debconf preseed schema** so `debian-installer`/cloud-init can answer questions at install time.

### Clean uninstall

`apt purge ubuntu-fido*` runs `pam-auth-update --remove` (cleanly retracts our PAM hooks), stops and disables the systemd unit, removes `/etc/ubuntu-fido/` only on `purge` (not `remove`), and leaves `~/.config/Yubico/u2f_keys` files alone (so reinstall is painless).

## GUI design

### App: `ubuntu-fido`

GTK4 + libadwaita. Single-window adaptive layout, looks like a stock Settings panel. Top-level navigation via libadwaita `AdwViewStack`:

#### 1. **Security Keys** tab (default)
- List of currently enrolled credentials per the active user. Each row: nickname, type icon (USB-A / NFC / implant / passkey), date added, last used, "Test" button, "Remove" button.
- "+ Add Security Key" primary action button.
- Empty state: large illustration + "Plug in your security key, or tap an NFC implant to begin."

#### 2. **TOTP** tab (visible only if TOTP build-flag enabled)
- List of TOTP enrollments (typically 0 or 1 per user — Linux PAM TOTP is one-secret-per-user by convention).
- "Generate TOTP secret" → modal with QR code + secret string + 8 recovery codes (one-time use).

#### 3. **Authentication Policy** tab
- Three master toggles for the 95% case:
  - **System login** (gdm-password): `Disabled / Optional / Required`
  - **Privileged commands** (sudo): same
  - **Remote SSH** (sshd): same
- "Advanced…" disclosure → pkexec prompt → full list including polkit, su, login, and any auto-detected PAM stacks. Each with same three modes plus a free-text condition (e.g., "only outside corporate network" via pam_access — v2 feature, scoped out of v1).
- Big yellow callout above the toggles when local user has no MFA credentials enrolled: **"You have no security keys. Enabling 'Required' will lock you out at next login."** Apply button disabled until user enrolls or explicitly confirms with second password prompt.

#### 4. **Recovery** tab
- Manage recovery codes (regenerate, view remaining count).
- Print recovery sheet (PDF, optionally including a QR-encoded backup of the user's TOTP secret for users who consent).
- "Emergency unlock" — generates a single-use recovery code an admin can hand to a user who lost their key, valid for 24 h.

### App: gnome-control-center Users panel shortcut

Optional `ubuntu-fido-gnome-integration` package ships an overlay file under `/usr/share/gnome-control-center/users/` (or whatever the current GNOME version uses) that adds an additional row labeled **"Authentication & Security Keys…"** to each user's detail view. Clicking launches `ubuntu-fido --user <username>` with elevated D-Bus permissions if the launching user is in `sudo`/`admin` group.

The overlay is shipped separately precisely because gnome-control-center has no stable plugin API — this package may need re-tuning every GNOME release. If it ever breaks, the standalone app keeps working; only the discoverability shortcut is lost.

### Add User flow extension

When `ubuntu-fido-gnome-integration` is installed, the **gnome-control-center Users → Add User** dialog gains a new section: **Configure security**, with three radio options:

1. **Enroll security credential now** — opens enrollment modal, admin must have the user's key/implant present. Sets a real password (admin-supplied).
2. **Require user to set up at first login** — admin sets a temp password (or accepts a generated one). We run `chage -d 0 <user>` and create `/var/lib/ubuntu-fido/pending/<user>`.
3. **No MFA** — only available if local policy permits ("Required" stacks would block this option with a tooltip).

## Enrollment flows

### Flow A: User self-enrollment (the common case)

1. User opens `ubuntu-fido` from Activities.
2. Clicks "+ Add Security Key".
3. Modal: "Plug in your key now or tap your NFC implant to a reader." Daemon polls `libfido2` for new device.
4. Device detected → optional PIN/UV prompt for FIDO2 → daemon emits `pamu2fcfg`-equivalent registration line.
5. User names the credential ("Yellow Yubikey", "xSIID implant").
6. Daemon writes line to `~/.config/Yubico/u2f_keys` (or central file if policy says so).
7. Modal closes, list refreshes.

polkit asks for user password if it's been > 5 minutes since last auth (auth_self_keep).

### Flow B: Admin-enrolls-now at account creation

1. Admin opens Users panel, clicks Add User.
2. Fills in account, picks "Enroll security credential now".
3. Same modal as Flow A but for the new account; daemon writes to that user's home (creates dir with correct ownership) or to central file.
4. Account ready for normal login from minute one.

polkit asks admin password.

### Flow C: First-login enrollment (the novel piece)

**At account creation (admin side):**
1. Admin picks "Require user to set up at first login", enters/accepts temp password.
2. Daemon runs `chage -d 0 <user>` (built-in Linux mechanism: forces password change at next login).
3. Daemon writes flag file `/var/lib/ubuntu-fido/pending/<user>` containing JSON: `{"required_methods": ["fido2"], "created": "...", "deadline": null}`.

**First login (user side):**
1. User logs into GDM with temp password.
2. PAM `passwd` module forces password change (existing Ubuntu behavior, no work for us).
3. GNOME session starts.
4. Our autostart entry `/etc/xdg/autostart/ubuntu-fido-firstrun.desktop` runs `ubuntu-fido --first-run`.
5. Detects pending flag, takes over the screen with a fullscreen modal: "Welcome. Before you continue, please enroll a security key."
6. User enrolls (Flow A inside the modal).
7. On success, daemon clears pending flag.
8. Modal closes, user lands on a normal desktop.

**Backstop (the PAM module):**
- If user kills `ubuntu-fido --first-run` and tries to do anything sudo/login-related, `pam_ubuntu_fido_pending.so` is in their auth stack; it sees the pending flag and denies auth with a friendly message: "Account setup incomplete. Please complete enrollment in the Authentication app."
- A watchdog inside `ubuntu-fido --first-run` calls `gnome-session-quit --logout --no-prompt` after 60 seconds of inactivity in the modal.

### Flow D: Lost key recovery

1. User can't authenticate.
2. User contacts admin.
3. Admin runs `ubuntu-fidoctl recovery generate <user>` (or clicks button in GUI). Outputs an 8-digit one-time code valid 24 h.
4. User enters code at GDM password prompt — `pam_ubuntu_fido_pending.so` recognizes recovery code prefix, lets them through with a forced re-enrollment flag set.
5. User logs in, immediately sees first-login-style modal forcing them to enroll a new key before doing anything else.

## PAM and policy details

### pam-auth-update profile

`/usr/share/pam-configs/ubuntu-fido`:

```
Name: Dangerous Things ubuntu-fido MFA
Default: no
Priority: 192
Auth-Type: Additional
Auth:
        [success=ok default=1 ignore=ignore]   pam_u2f.so cue authfile=/etc/u2f_mappings
        [success=ok default=die]               pam_ubuntu_fido_pending.so
```

Default `no` means the package install does not enable enforcement — admins / GUI explicitly turn it on per stack.

### Policy file format (`/etc/ubuntu-fido/policy.d/*.conf`)

TOML, parsed in lexical order, last-key-wins:

```toml
[stacks.gdm-password]
mode = "required"          # disabled | optional | required
methods = ["fido2", "totp"] # any-of

[stacks.sudo]
mode = "optional"
methods = ["fido2"]

[stacks.sshd]
mode = "required"
methods = ["fido2"]

[storage]
backend = "central"        # per-user | central
central_path = "/etc/u2f_mappings"

[firstrun]
default_required_methods = ["fido2"]
deadline_hours = 0          # 0 = no auto-expire
```

Daemon reloads on `SIGHUP` or when a watched file changes (uses `inotify`).

### Lockout safety simulation

Before applying any policy change, daemon simulates the new policy against:
- The currently logged-in interactive user (resolved via `loginctl`).
- Every user listed in `/var/lib/ubuntu-fido/users.db` (cached enrollment registry).

For each user, it runs the new policy through a dry-run PAM check. If the result would deny login *without* a way to recover (no enrolled credentials of any required method), the daemon refuses the change and returns an actionable error: "Applying this policy would lock out user `alice` from `gdm-password` (no fido2 credentials enrolled). Enroll a credential for alice or set this stack to 'optional'."

The GUI surfaces this as a red banner with a one-click "fix it" suggestion. The CLI returns non-zero with the same message. Override flag `--force-i-know-what-im-doing` exists for the determined.

## Testing strategy

### Unit
- Daemon: Rust `cargo test`, mocking `libfido2` via trait abstraction.
- PAM module: small C test harness using `pam_test_authenticate` from libpam-tests-dev.

### Integration
- Disposable Multipass / LXD VM that boots a minimal Ubuntu 24.04 GNOME image, installs the deb from a local apt repo, and runs scripted enrollment via virtual FIDO2 device (`vhci-hcd` + `umockdev` for USB simulation, or the `libfido2` software backend).
- One scripted test per flow A/B/C/D above. Each asserts both successful path and lockout-prevention failure mode.

### Manual smoke (release gate)
- Real Yubikey (USB-A and NFC), Token2, and a Dangerous Things xSIID/Apex implant via NFC reader.
- Test on Ubuntu 22.04 LTS, 24.04 LTS, and the current latest LTS at release time.

### Continuous fleet test
- Vagrant-based fleet rehearsal: 5 VMs preseeded with our debconf answers, joined to a fake LDAP, Ansible role applied, simulated user creations, simulated lost-key recoveries.

## Roadmap to ultimate target (C)

The architecture is designed so each step here is additive — no refactor of v1.

| Phase | Deliverable | Effort |
|---|---|---|
| **v1.0** | Ubuntu LTS + GNOME, U2F + FIDO2 passkey + TOTP. | Reference. |
| **v1.1** | Debian stable packaging (same source, second build target). | ~2 weeks. |
| **v1.2** | KDE Plasma front-end as a KCM module (`kcm_ubuntu_fido`). Reuses the same daemon over D-Bus. Built with KF6/Qt6. | ~6–8 weeks (mostly Qt port of GUI). |
| **v1.3** | Fedora/RHEL spec file. PAM module and daemon already work; needs `.rpm` packaging and SELinux policy. GNOME GUI works as-is. | ~3–4 weeks. |
| **v2.0** | Optional: organization-wide credential sync via FreeIPA / LDAP integration. Pure backend feature. | Out of scope for now. |

## Risks and open questions

| Risk | Mitigation |
|---|---|
| GNOME panel shortcut deb breaks on GNOME version bumps. | Standalone app remains functional; shortcut deb is `Suggests:` only, version-pinned, and can be skipped without losing core feature. |
| `gdm-password` and screen unlock share a PAM stack — making MFA "required" affects both. Some users want different policies for "log in" vs "unlock screensaver". | Document the limitation. v2 could split via custom stacks with `pam_succeed_if user_unlock_session`. |
| User loses last security key with no TOTP and no recovery codes. | Recovery flow (Flow D) requires admin involvement — accepted trade-off. Document prominently in onboarding. Single-user-laptop edge case: instruct user to keep recovery codes printed. |
| Implants need NFC readers; not all desktop systems have them. | Out of scope for the package. Document supported readers. Standard libfido2 NFC stack works once a reader is plugged in. |
| Pre-existing libpam-u2f config is already in use on the system. | postinst checks for existing `pam_u2f.so` lines in `/etc/pam.d/`; if found, prompts admin (or refuses to install non-interactively) until they migrate or accept import. |

## Out of scope for v1

- Fingerprint readers / FIDO2 platform authenticators (laptop biometric sensors). Future phase via `pam_fprintd` integration.
- WebAuthn for browser-based logins to web apps. Different layer entirely.
- Smart-card / PIV authentication. Adjacent space, future phase via `pam_pkcs11`.
- Per-network policy ("require MFA only off corp VPN"). Defer to v2.
- macOS / Windows clients. This is Linux-specific.

---

*This design was developed via guided brainstorming on 2026-04-26. The next artifact is a detailed implementation plan in `2026-04-26-ubuntu-fido-implementation-plan.md`.*