# Phase 9 (Policy Tab) + Phase 12 GUI (Recovery Tab) — Implementation Plan

> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
>
> **EXECUTION GATE:** Do **not** start until Phase 8 has merged to `main` (the plan at [2026-04-27-phase-8-gui-keys.md](2026-04-27-phase-8-gui-keys.md) lands `gui/src/{main,bus,error,keys_page,enroll_dialog}.rs` and the `Daemon` D-Bus client wrapper this lane builds on).

**Goal:** Add two new tabs to the AuthForge GUI:
1. **Policy tab** (Phase 9) — three master `AdwComboRow`s for `gdm-password`, `sudo`, `sshd` (Disabled / Optional / Required), with pre-apply lockout simulation surfaced via inline `AdwBanner`. An "Advanced…" expander that opens the full stack list (gated by polkit prompt on first toggle).
2. **Recovery tab** (Phase 12 GUI half) — generate / list / revoke recovery codes. Shows the freshly-generated 8-digit code in a one-shot copy-to-clipboard dialog (it's only stored hashed, so we cannot show it again).

**Architecture:**
- Introduce the `AppContext` struct foreseen by Phase 8's Task 7 risk note ([2026-04-27-phase-8-gui-keys.md:812](2026-04-27-phase-8-gui-keys.md#L812)) — single owner of `Daemon` and `adw::ToastOverlay` shared across pages.
- Each page is a `struct PolicyPage { root: adw::Bin, ... }` / `struct RecoveryPage { root: adw::Bin, ... }`, mirroring `KeysPage`'s shape (`Rc<Self>`, `glib::MainContext::spawn_local` for async, render swap on disconnect).
- Extend `gui/src/bus.rs` `Daemon` with policy + recovery methods. No new file there — additive only.
- Subscribe to `PolicyChanged` D-Bus signal (already emitted by daemon — see [daemon/src/dbus.rs:142](../../daemon/src/dbus.rs#L142)) so external `authforgectl policy set` invocations refresh the GUI.
- The "Advanced…" expander is the polkit prompt trigger — touching any non-master stack toggles the gating, which the daemon enforces via its existing `…apply-policy` action.

**Tech Stack:**
- `gtk4-rs` + `libadwaita` (already pinned by Phase 8).
- `zbus` with the workspace tokio runtime feature (per [2026-04-27-phase-8-gui-keys.md:23-25](2026-04-27-phase-8-gui-keys.md#L23-L25), the GUI uses zbus's tokio integration via the workspace dep — no glib feature exists).
- `authforge_common::{policy::{Policy, StackPolicy, StorageBackend}, types::{Mode, Method, Violation, PolicyApplyResult, RecoveryCodeSummary}}` for all wire types.

**Reference:**
- Master plan: [2026-04-26-authforge-implementation.md](2026-04-26-authforge-implementation.md) § Phase 9 (line 1190) and § Phase 12 (line 1260).
- Phase 8 plan (consumes this lane's contracts): [2026-04-27-phase-8-gui-keys.md](2026-04-27-phase-8-gui-keys.md).
- Phase 12 backend plan (the daemon contract these views consume): [2026-04-27-phase-12-recovery-backend.md](2026-04-27-phase-12-recovery-backend.md).
- Sibling page (mirror this style): `gui/src/keys_page.rs` (after Phase 8 lands).
- D-Bus methods this lane calls: `GetPolicy`, `SetPolicy`, `GenerateRecoveryCode`, `ListRecoveryCodes`, `RevokeRecoveryCode`, signal `PolicyChanged`.

---

## Conventions

- One logical change per commit. Conventional prefixes scoped to `gui`.
- Always commit with `--no-gpg-sign`.
- TDD only for pure logic in `policy_form.rs` (mode-mapping helpers, violation rendering). Widget code ships with manual smoke (`gui/TESTING.md`).
- After each commit: `cargo fmt --all && cargo clippy -p authforge-gui --all-targets -- -D warnings && cargo build -p authforge-gui`.
- Don't pre-emptively refactor `KeysPage` beyond what the AppContext refactor strictly requires — Phase 8 owns its surface.

---

## Task 1: `AppContext` struct + `KeysPage` migration

**Files:**
- Create: `gui/src/app_context.rs`
- Modify: `gui/src/main.rs` (construct AppContext, pass to pages)
- Modify: `gui/src/keys_page.rs` (constructor takes `AppContext` instead of bare overlay+window)

**Background:** Phase 8 punted this refactor to Phase 9. AppContext owns the shared handles every page needs: `parent_window`, the populated `Daemon` (or its disconnected state), and `toast_overlay`. Pages clone the Rc to make their own copies.

**Step 1: Create the AppContext**

```rust
// gui/src/app_context.rs
//! Shared app-wide handles passed to every page constructor.

use crate::bus::Daemon;
use std::cell::RefCell;
use std::rc::Rc;

/// One-per-window struct holding handles every page needs. `daemon` is
/// `RefCell<Option<...>>` because the connect-on-startup attempt may fail
/// and pages render their disconnected banner; a successful Retry repopulates
/// this same cell.
#[derive(Clone)]
pub(crate) struct AppContext {
    pub parent_window: gtk::Window,
    pub toast_overlay: adw::ToastOverlay,
    pub daemon: Rc<RefCell<Option<Daemon>>>,
}

impl AppContext {
    pub fn new(parent_window: gtk::Window, toast_overlay: adw::ToastOverlay) -> Self {
        Self {
            parent_window,
            toast_overlay,
            daemon: Rc::new(RefCell::new(None)),
        }
    }
}
```

**Step 2: Migrate `KeysPage::new` to take `AppContext`**

In `gui/src/keys_page.rs`, change:

```rust
pub fn new(parent_window: gtk::Window, toast_overlay: adw::ToastOverlay) -> Rc<Self>
```

to:

```rust
pub fn new(ctx: AppContext) -> Rc<Self>
```

Replace the three field accesses (`self.parent_window`, `self.toast_overlay`, `self.daemon`) with `self.ctx.parent_window`, `self.ctx.toast_overlay`, `self.ctx.daemon`. Drop the duplicate `daemon` field on `KeysPage` itself — it now lives in AppContext.

**Step 3: Update `main.rs` to thread the context**

```rust
// gui/src/main.rs
mod app_context;
mod bus;
mod error;
mod keys_page;
// (Phase 9/12 modules added below — declared once Tasks 2/5 land.)

// ... inside connect_activate ...
let toast_overlay = adw::ToastOverlay::new();
let ctx = app_context::AppContext::new(win.clone().upcast(), toast_overlay.clone());
let keys = keys_page::KeysPage::new(ctx.clone());
stack.add_titled_with_icon(&keys.root, Some("keys"), "Keys", "dialog-password-symbolic");
toast_overlay.set_child(Some(&stack));
toolbar.set_content(Some(&toast_overlay));
```

**Step 4: Build + clippy**

Run: `cargo build -p authforge-gui && cargo clippy -p authforge-gui --all-targets -- -D warnings`
Expected: clean.

**Step 5: Commit**

```bash
git add gui/src/app_context.rs gui/src/main.rs gui/src/keys_page.rs
git commit --no-gpg-sign -m "refactor(gui): introduce AppContext for shared page handles"
```

---

## Task 2: Extend `bus.rs` with policy + recovery methods

**Files:**
- Modify: `gui/src/bus.rs`

**Background:** All additive. The existing `Daemon` proxy works for any method on `io.dangerousthings.AuthForge1`.

**Step 1: Append to the `impl Daemon` block**

```rust
use authforge_common::policy::Policy;
use authforge_common::types::{PolicyApplyResult, RecoveryCodeSummary};

impl Daemon {
    // ... existing methods ...

    pub async fn get_policy(&self) -> zbus::Result<Policy> {
        self.proxy.call("GetPolicy", &()).await
    }

    /// `force=false` runs the daemon's lockout simulator first; on
    /// violations, returns `PolicyApplyResult { applied: false, violations }`
    /// without writing.
    pub async fn set_policy(&self, p: &Policy, force: bool) -> zbus::Result<PolicyApplyResult> {
        self.proxy.call("SetPolicy", &(p, force)).await
    }

    pub async fn generate_recovery_code(&self, user: &str) -> zbus::Result<String> {
        self.proxy.call("GenerateRecoveryCode", &(user,)).await
    }

    pub async fn list_recovery_codes(&self) -> zbus::Result<Vec<RecoveryCodeSummary>> {
        self.proxy.call("ListRecoveryCodes", &()).await
    }

    pub async fn revoke_recovery_code(&self, user: &str) -> zbus::Result<bool> {
        self.proxy.call("RevokeRecoveryCode", &(user,)).await
    }

    pub async fn subscribe_policy_changed(
        &self,
    ) -> zbus::Result<zbus::proxy::SignalStream<'static>> {
        self.proxy.receive_signal("PolicyChanged").await
    }
}
```

**Step 2: Build + clippy**

Run: `cargo build -p authforge-gui && cargo clippy -p authforge-gui --all-targets -- -D warnings`
Expected: clean.

**Step 3: Commit**

```bash
git add gui/src/bus.rs
git commit --no-gpg-sign -m "feat(gui): bus client policy + recovery method wrappers"
```

---

## Task 3: `policy_form.rs` — pure mode-mapping helpers (TDD)

**Files:**
- Create: `gui/src/policy_form.rs`
- Modify: `gui/src/main.rs` (add `mod policy_form;`)

**Background:** Pulling pure logic out of the widget code keeps the testable bits isolated. `mode_to_combo_index`, `combo_index_to_mode`, and the violation-grouping helper all run without a display server.

**Step 1: Write the tests + impl**

```rust
//! Pure helpers backing the Policy tab. Mode <-> combo index, violation
//! grouping. Widget code calls these; nothing here touches GTK.

use authforge_common::types::{Mode, Violation};
use std::collections::BTreeMap;

pub(crate) const MODE_LABELS: &[(&str, Mode)] = &[
    ("Disabled", Mode::Disabled),
    ("Optional", Mode::Optional),
    ("Required", Mode::Required),
];

pub(crate) fn mode_to_combo_index(m: Mode) -> u32 {
    match m {
        Mode::Disabled => 0,
        Mode::Optional => 1,
        Mode::Required => 2,
    }
}

pub(crate) fn combo_index_to_mode(idx: u32) -> Mode {
    match idx {
        0 => Mode::Disabled,
        1 => Mode::Optional,
        _ => Mode::Required,
    }
}

/// Group violations by stack, joining reasons with "; ". Used to render the
/// inline AdwBanner content when `SetPolicy(force=false)` returns violations.
pub(crate) fn group_violations_by_stack(vs: &[Violation]) -> BTreeMap<String, String> {
    let mut by_stack: BTreeMap<String, Vec<String>> = BTreeMap::new();
    for v in vs {
        by_stack
            .entry(v.stack.clone())
            .or_default()
            .push(format!("{}: {}", v.user, v.reason));
    }
    by_stack
        .into_iter()
        .map(|(k, vs)| (k, vs.join("; ")))
        .collect()
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn mode_combo_roundtrips() {
        for m in [Mode::Disabled, Mode::Optional, Mode::Required] {
            assert_eq!(combo_index_to_mode(mode_to_combo_index(m)), m);
        }
    }

    #[test]
    fn out_of_range_index_clamps_to_required() {
        assert_eq!(combo_index_to_mode(99), Mode::Required);
    }

    #[test]
    fn violations_group_by_stack() {
        let vs = vec![
            Violation { user: "alice".into(), stack: "sudo".into(), reason: "no fido2".into() },
            Violation { user: "bob".into(),   stack: "sudo".into(), reason: "no fido2".into() },
            Violation { user: "alice".into(), stack: "sshd".into(), reason: "no fido2".into() },
        ];
        let g = group_violations_by_stack(&vs);
        assert_eq!(g.len(), 2);
        assert!(g.get("sudo").unwrap().contains("alice"));
        assert!(g.get("sudo").unwrap().contains("bob"));
        assert_eq!(g.get("sshd").unwrap(), "alice: no fido2");
    }
}
```

**Step 2: Run tests**

Run: `cargo test -p authforge-gui policy_form`
Expected: 3 PASS.

**Step 3: Clippy**

Run: `cargo clippy -p authforge-gui --all-targets -- -D warnings`
Expected: clean.

**Step 4: Commit**

```bash
git add gui/src/policy_form.rs gui/src/main.rs
git commit --no-gpg-sign -m "feat(gui): pure-logic helpers for Policy tab (mode mapping, violation grouping)"
```

---

## Task 4: `policy_page.rs` — three master toggles + Apply

**Files:**
- Create: `gui/src/policy_page.rs`
- Modify: `gui/src/main.rs` (add `mod policy_page;` + register the tab)

**Background:** Three `AdwComboRow`s, one per master stack (`gdm-password`, `sudo`, `sshd`). Each row's combo emits to a local working `Policy` clone; the bottom Apply button calls `SetPolicy(force=false)`. On violations, render an `AdwBanner` above the page with the grouped messages and a "Force apply" action that re-calls with `force=true`.

**Step 1: Create the page**

```rust
//! "Policy" preferences page. Three master stacks as AdwComboRow with
//! Disabled/Optional/Required. Pre-apply lockout simulation surfaces via an
//! inline AdwBanner. Advanced expander opens the full stack list (Task 6).

use crate::app_context::AppContext;
use crate::bus::Daemon;
use crate::error::user_message;
use crate::policy_form::{combo_index_to_mode, group_violations_by_stack, mode_to_combo_index, MODE_LABELS};
use adw::prelude::*;
use authforge_common::policy::{Policy, StackPolicy};
use authforge_common::types::{Method, Mode};
use gtk::glib;
use std::cell::RefCell;
use std::rc::Rc;

const MASTER_STACKS: &[&str] = &["gdm-password", "sudo", "sshd"];

pub(crate) struct PolicyPage {
    pub root: adw::Bin,
    ctx: AppContext,
    /// Working copy of policy, mutated by combo callbacks; sent to daemon on Apply.
    working: Rc<RefCell<Policy>>,
}

impl PolicyPage {
    pub fn new(ctx: AppContext) -> Rc<Self> {
        let page = Rc::new(Self {
            root: adw::Bin::new(),
            ctx,
            working: Rc::new(RefCell::new(Policy::default())),
        });
        let p = page.clone();
        glib::MainContext::default().spawn_local(async move {
            p.refresh().await;
        });
        page
    }

    async fn refresh(self: &Rc<Self>) {
        let daemon = match self.ctx.daemon.borrow().clone() {
            Some(d) => d,
            None => {
                self.render_disconnected("Connect via the Keys tab first.");
                return;
            }
        };
        match daemon.get_policy().await {
            Ok(p) => {
                *self.working.borrow_mut() = p.clone();
                self.render_form(&p, None);
            }
            Err(e) => self.render_disconnected(&user_message(&e)),
        }
    }

    fn render_disconnected(self: &Rc<Self>, msg: &str) {
        let status = adw::StatusPage::builder()
            .icon_name("network-offline-symbolic")
            .title("Daemon unavailable")
            .description(msg)
            .build();
        self.root.set_child(Some(&status));
    }

    fn render_form(self: &Rc<Self>, current: &Policy, banner_msg: Option<String>) {
        let outer = gtk::Box::new(gtk::Orientation::Vertical, 0);

        if let Some(msg) = banner_msg {
            let banner = adw::Banner::builder()
                .title(&msg)
                .button_label("Force apply")
                .revealed(true)
                .build();
            let me = self.clone();
            banner.connect_button_clicked(move |_| {
                let me = me.clone();
                glib::MainContext::default().spawn_local(async move {
                    me.apply(true).await;
                });
            });
            outer.append(&banner);
        }

        let pref_page = adw::PreferencesPage::new();
        let group = adw::PreferencesGroup::builder()
            .title("Where MFA is enforced")
            .description("Disabled = no MFA. Optional = key prompted but not required. Required = blocks login without a key.")
            .build();

        for stack_name in MASTER_STACKS {
            let mode = current
                .stacks
                .get(*stack_name)
                .map(|s| s.mode)
                .unwrap_or(Mode::Disabled);

            let labels: Vec<&str> = MODE_LABELS.iter().map(|(l, _)| *l).collect();
            let model = gtk::StringList::new(&labels);
            let combo = adw::ComboRow::builder()
                .title(*stack_name)
                .model(&model)
                .selected(mode_to_combo_index(mode))
                .build();

            let me = self.clone();
            let stack_owned = stack_name.to_string();
            combo.connect_selected_notify(move |c| {
                let new_mode = combo_index_to_mode(c.selected());
                me.working
                    .borrow_mut()
                    .stacks
                    .entry(stack_owned.clone())
                    .or_insert(StackPolicy {
                        mode: Mode::Disabled,
                        methods: vec![Method::Fido2],
                    })
                    .mode = new_mode;
            });

            group.add(&combo);
        }
        pref_page.add(&group);

        // Apply button row at the bottom.
        let apply_group = adw::PreferencesGroup::new();
        let apply = adw::ActionRow::builder()
            .title("Apply policy")
            .activatable(true)
            .build();
        apply.add_suffix(
            &gtk::Image::builder()
                .icon_name("emblem-ok-symbolic")
                .build(),
        );
        let me = self.clone();
        apply.connect_activated(move |_| {
            let me = me.clone();
            glib::MainContext::default().spawn_local(async move {
                me.apply(false).await;
            });
        });
        apply_group.add(&apply);
        pref_page.add(&apply_group);

        outer.append(&pref_page);
        self.root.set_child(Some(&outer));
    }

    async fn apply(self: &Rc<Self>, force: bool) {
        let daemon = match self.ctx.daemon.borrow().clone() {
            Some(d) => d,
            None => {
                self.show_toast("Daemon unavailable.");
                return;
            }
        };
        let pol = self.working.borrow().clone();
        match daemon.set_policy(&pol, force).await {
            Ok(r) if r.applied => {
                self.show_toast("Policy applied.");
                self.refresh().await;
            }
            Ok(r) => {
                let by_stack = group_violations_by_stack(&r.violations);
                let summary = by_stack
                    .into_iter()
                    .map(|(s, msg)| format!("{s}: {msg}"))
                    .collect::<Vec<_>>()
                    .join(" • ");
                let banner_msg = format!("Would lock users out — {summary}");
                self.render_form(&pol, Some(banner_msg));
            }
            Err(e) => self.show_toast(&user_message(&e)),
        }
    }

    fn show_toast(self: &Rc<Self>, msg: &str) {
        self.ctx
            .toast_overlay
            .add_toast(adw::Toast::builder().title(msg).timeout(5).build());
    }
}
```

**Step 2: Wire into `main.rs`**

```rust
let policy = policy_page::PolicyPage::new(ctx.clone());
stack.add_titled_with_icon(&policy.root, Some("policy"), "Policy", "preferences-system-symbolic");
```

**Step 3: Build + clippy**

Run: `cargo build -p authforge-gui && cargo clippy -p authforge-gui --all-targets -- -D warnings`
Expected: clean.

**Step 4: Commit**

```bash
git add gui/src/policy_page.rs gui/src/main.rs
git commit --no-gpg-sign -m "feat(gui): Policy tab with three master stacks and lockout-violation banner"
```

---

## Task 5: PolicyChanged signal subscription → live refresh

**Files:**
- Modify: `gui/src/policy_page.rs`

**Background:** External `authforgectl policy set` invocations bypass the GUI; without subscribing the GUI shows stale state. Subscribe once on construction; on every signal call `refresh()`.

**Step 1: Spawn the subscriber in `PolicyPage::new`**

After the existing `spawn_local(async move { p.refresh().await })`, add:

```rust
let p = page.clone();
glib::MainContext::default().spawn_local(async move {
    let daemon = match p.ctx.daemon.borrow().clone() {
        Some(d) => d,
        None => return,
    };
    let mut stream = match daemon.subscribe_policy_changed().await {
        Ok(s) => s,
        Err(_) => return,
    };
    use futures_util::StreamExt;
    while stream.next().await.is_some() {
        p.refresh().await;
    }
});
```

**Step 2: Build + clippy**

Run: `cargo build -p authforge-gui && cargo clippy -p authforge-gui --all-targets -- -D warnings`
Expected: clean.

**Step 3: Commit**

```bash
git add gui/src/policy_page.rs
git commit --no-gpg-sign -m "feat(gui): PolicyPage subscribes to PolicyChanged for live refresh"
```

---

## Task 6: Advanced expander — full stack list (polkit-gated)

**Files:**
- Modify: `gui/src/policy_page.rs`

**Background:** Master toggles cover the 95% case; the remaining 5% (auto-detected stacks) lives in an `AdwExpanderRow` titled "Advanced…". Toggling any non-master combo triggers the daemon's polkit prompt at `SetPolicy` time — no special GUI plumbing needed. Daemon's polkit module surfaces the prompt via the system polkit agent.

**Step 1: Add an `AdwExpanderRow` after the master group**

In `render_form`, after `pref_page.add(&group)` and before the Apply group:

```rust
let advanced_group = adw::PreferencesGroup::new();
let expander = adw::ExpanderRow::builder()
    .title("Advanced")
    .subtitle("Per-stack overrides for any PAM stack the daemon knows about.")
    .build();

let mut others: Vec<&String> = current
    .stacks
    .keys()
    .filter(|k| !MASTER_STACKS.contains(&k.as_str()))
    .collect();
others.sort();
for stack_name in others {
    let mode = current.stacks.get(stack_name).map(|s| s.mode).unwrap_or(Mode::Disabled);
    let labels: Vec<&str> = MODE_LABELS.iter().map(|(l, _)| *l).collect();
    let model = gtk::StringList::new(&labels);
    let combo = adw::ComboRow::builder()
        .title(stack_name.as_str())
        .model(&model)
        .selected(mode_to_combo_index(mode))
        .build();
    let me = self.clone();
    let s = stack_name.clone();
    combo.connect_selected_notify(move |c| {
        let new_mode = combo_index_to_mode(c.selected());
        me.working
            .borrow_mut()
            .stacks
            .entry(s.clone())
            .or_insert(StackPolicy { mode: Mode::Disabled, methods: vec![Method::Fido2] })
            .mode = new_mode;
    });
    expander.add_row(&combo);
}

advanced_group.add(&expander);
pref_page.add(&advanced_group);
```

**Step 2: Build + clippy**

Run: `cargo build -p authforge-gui && cargo clippy -p authforge-gui --all-targets -- -D warnings`
Expected: clean.

**Step 3: Commit**

```bash
git add gui/src/policy_page.rs
git commit --no-gpg-sign -m "feat(gui): advanced expander surfaces non-master PAM stacks in Policy tab"
```

---

## Task 7: `recovery_page.rs` — list + revoke

**Files:**
- Create: `gui/src/recovery_page.rs`
- Modify: `gui/src/main.rs` (add `mod recovery_page;` + register tab)

**Background:** Mirrors `KeysPage` shape. List rows show user + "expires in N days/hours" + a revoke button. A "Generate code for…" entry at the bottom prompts for a username and shows the generated code in a one-shot copy dialog.

**Step 1: Create the page**

```rust
//! "Recovery" preferences page. Generate / list / revoke recovery codes.

use crate::app_context::AppContext;
use crate::bus::Daemon;
use crate::error::user_message;
use adw::prelude::*;
use authforge_common::types::RecoveryCodeSummary;
use gtk::glib;
use std::rc::Rc;
use std::time::{SystemTime, UNIX_EPOCH};

pub(crate) struct RecoveryPage {
    pub root: adw::Bin,
    ctx: AppContext,
}

impl RecoveryPage {
    pub fn new(ctx: AppContext) -> Rc<Self> {
        let page = Rc::new(Self {
            root: adw::Bin::new(),
            ctx,
        });
        let p = page.clone();
        glib::MainContext::default().spawn_local(async move {
            p.refresh().await;
        });
        page
    }

    async fn refresh(self: &Rc<Self>) {
        let daemon = match self.ctx.daemon.borrow().clone() {
            Some(d) => d,
            None => {
                self.render_disconnected("Connect via the Keys tab first.");
                return;
            }
        };
        match daemon.list_recovery_codes().await {
            Ok(entries) => self.render_list(&entries),
            Err(e) => self.render_disconnected(&user_message(&e)),
        }
    }

    fn render_disconnected(self: &Rc<Self>, msg: &str) {
        let status = adw::StatusPage::builder()
            .icon_name("network-offline-symbolic")
            .title("Daemon unavailable")
            .description(msg)
            .build();
        self.root.set_child(Some(&status));
    }

    fn render_list(self: &Rc<Self>, entries: &[RecoveryCodeSummary]) {
        let pref = adw::PreferencesPage::new();
        let group = adw::PreferencesGroup::builder()
            .title("Active recovery codes")
            .description(if entries.is_empty() {
                "No active recovery codes. Use the form below to issue one."
            } else {
                "Each code is one-shot and Argon2id-hashed at rest. The 8-digit plaintext is shown once at generation."
            })
            .build();

        for e in entries {
            let row = adw::ActionRow::builder()
                .title(&e.user)
                .subtitle(&format!("expires {}", expires_relative(e.expires_unix)))
                .build();
            let revoke = gtk::Button::builder()
                .label("Revoke")
                .css_classes(["destructive-action"])
                .valign(gtk::Align::Center)
                .build();
            let me = self.clone();
            let user = e.user.clone();
            revoke.connect_clicked(move |_| {
                let me = me.clone();
                let user = user.clone();
                glib::MainContext::default().spawn_local(async move {
                    me.do_revoke(&user).await;
                });
            });
            row.add_suffix(&revoke);
            group.add(&row);
        }
        pref.add(&group);

        let issue_group = adw::PreferencesGroup::new();
        let user_entry = adw::EntryRow::builder().title("Username").build();
        let me = self.clone();
        let entry_clone = user_entry.clone();
        let issue_btn = gtk::Button::builder()
            .label("Generate code")
            .css_classes(["pill", "suggested-action"])
            .halign(gtk::Align::End)
            .build();
        issue_btn.connect_clicked(move |_| {
            let me = me.clone();
            let user = entry_clone.text().to_string();
            if user.is_empty() {
                me.show_toast("Enter a username first.");
                return;
            }
            glib::MainContext::default().spawn_local(async move {
                me.do_generate(&user).await;
            });
        });
        issue_group.add(&user_entry);
        let issue_row = adw::ActionRow::new();
        issue_row.add_suffix(&issue_btn);
        issue_group.add(&issue_row);
        pref.add(&issue_group);

        self.root.set_child(Some(&pref));
    }

    async fn do_generate(self: &Rc<Self>, user: &str) {
        let daemon = match self.ctx.daemon.borrow().clone() {
            Some(d) => d,
            None => return,
        };
        match daemon.generate_recovery_code(user).await {
            Ok(code) => {
                self.show_code_dialog(user, &code);
                self.refresh().await;
            }
            Err(e) => self.show_toast(&user_message(&e)),
        }
    }

    async fn do_revoke(self: &Rc<Self>, user: &str) {
        let daemon = match self.ctx.daemon.borrow().clone() {
            Some(d) => d,
            None => return,
        };
        match daemon.revoke_recovery_code(user).await {
            Ok(true) => {
                self.show_toast(&format!("Revoked {user}'s recovery code."));
                self.refresh().await;
            }
            Ok(false) => self.show_toast(&format!("No recovery code for {user}.")),
            Err(e) => self.show_toast(&user_message(&e)),
        }
    }

    fn show_code_dialog(self: &Rc<Self>, user: &str, code: &str) {
        let dialog = adw::AlertDialog::builder()
            .heading(&format!("Recovery code for {user}"))
            .body("This code is shown only once. Copy it now — it cannot be recovered later.")
            .build();
        dialog.add_response("copy", "Copy");
        dialog.add_response("close", "Close");
        dialog.set_default_response(Some("copy"));
        dialog.set_close_response("close");

        let label = gtk::Label::builder()
            .label(code)
            .css_classes(["title-1"])
            .selectable(true)
            .build();
        dialog.set_extra_child(Some(&label));

        let code_owned = code.to_string();
        let parent = self.ctx.parent_window.clone();
        dialog.connect_response(None, move |d, resp| {
            if resp == "copy" {
                if let Some(disp) = gtk::gdk::Display::default() {
                    disp.clipboard().set_text(&code_owned);
                }
            }
            d.close();
        });
        dialog.present(Some(&parent));
    }

    fn show_toast(self: &Rc<Self>, msg: &str) {
        self.ctx
            .toast_overlay
            .add_toast(adw::Toast::builder().title(msg).timeout(5).build());
    }
}

fn expires_relative(unix: u64) -> String {
    let now = SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .map(|d| d.as_secs())
        .unwrap_or(0);
    if unix <= now {
        return "expired".to_string();
    }
    let delta = unix - now;
    if delta >= 24 * 3600 {
        format!("in {} day(s)", delta / (24 * 3600))
    } else if delta >= 3600 {
        format!("in {} hour(s)", delta / 3600)
    } else {
        format!("in {} min", delta / 60)
    }
}
```

**Step 2: Wire into `main.rs`**

```rust
let recovery = recovery_page::RecoveryPage::new(ctx.clone());
stack.add_titled_with_icon(&recovery.root, Some("recovery"), "Recovery", "emblem-important-symbolic");
```

**Step 3: Build + clippy**

Run: `cargo build -p authforge-gui && cargo clippy -p authforge-gui --all-targets -- -D warnings`
Expected: clean.

**Step 4: Commit**

```bash
git add gui/src/recovery_page.rs gui/src/main.rs
git commit --no-gpg-sign -m "feat(gui): Recovery tab with list / generate / revoke + one-shot copy dialog"
```

---

## Task 8: Acceptance gate — extend `gui/TESTING.md`

**Files:**
- Modify: `gui/TESTING.md`

**Step 1: Append the new manual-smoke walkthroughs**

```markdown
## Policy tab smoke

1. Daemon running (same setup as Keys tab smoke).
2. Open the GUI → Policy tab. Three rows: gdm-password, sudo, sshd. All start at "Disabled" on a clean system.
3. Set sudo to "Required" → Apply. With no enrolled keys you'll see an inline banner "Would lock users out — sudo: <user>: no fido2 enrolled" and a "Force apply" button.
4. Click the trash icon on the row → row vanishes immediately.
5. Switch to Keys tab → enroll a Yubikey → switch back. Apply again with sudo=Required → toast "Policy applied".
6. In another terminal: `authforgectl policy show` should reflect the change.
7. Run `authforgectl policy set sshd disabled --methods fido2` externally → Policy tab refreshes within ~1s (PolicyChanged signal).

## Recovery tab smoke

1. Open Recovery tab. Empty list with hint text.
2. Type "alice" in the username row, click "Generate code". Modal opens showing the 8-digit code with a Copy button. Click Copy → paste somewhere to verify clipboard worked.
3. Close the modal. List now shows alice with "expires in 7 day(s)".
4. Click "Revoke" on alice's row → row vanishes, toast confirms.
5. Generate again, then run `authforgectl recovery list` externally — should show alice with the same expiry.
```

**Step 2: Commit**

```bash
git add gui/TESTING.md
git commit --no-gpg-sign -m "docs(gui): smoke-test recipes for Policy and Recovery tabs"
```

---

## Task 9: Master plan closeout note

**Files:**
- Modify: `docs/plans/2026-04-26-authforge-implementation.md`

**Step 1: Flip Phase 9 + Phase 12 GUI to ✅ Code complete**

Update the roadmap rows at lines 39 and 42:

```
| 9  | GUI: Policy tab + lockout-warning UX | 4 days | ✅ **Code complete** (yyyy-mm-dd) |
| 12 | Recovery flow (codes + emergency unlock) | 4 days | ✅ **Code complete** (yyyy-mm-dd) — backend + GUI both landed |
```

**Step 2: Append a closeout-notes section**

```markdown
### Phase 9 + Phase 12 GUI closeout notes (yyyy-mm-dd)

Landed via the plan at [2026-04-27-phase-9-and-12-gui.md](2026-04-27-phase-9-and-12-gui.md). Built atop the Phase 8 GUI shell.

**Done in Phase 9:**
- `gui/src/app_context.rs` — `AppContext` struct shared across pages (foreseen by Phase 8 Task 7).
- `gui/src/policy_form.rs` — pure mode-mapping + violation-grouping helpers. 3 unit tests.
- `gui/src/policy_page.rs` — Policy tab with three master stacks (gdm-password / sudo / sshd) as `AdwComboRow`, inline `AdwBanner` for lockout simulation results, "Force apply" action, `AdwExpanderRow` for non-master stacks, live refresh via `PolicyChanged` subscription.

**Done in Phase 12 GUI:**
- `gui/src/recovery_page.rs` — list/generate/revoke. One-shot copy dialog for freshly issued codes (codes are Argon2id-hashed at rest by the daemon — never showable twice).
- `gui/src/bus.rs` extended with `get_policy`, `set_policy`, `generate_recovery_code`, `list_recovery_codes`, `revoke_recovery_code`, `subscribe_policy_changed`.

**Plan deviations:** _(fill in)_.

**Deferred until Phase 14 VM smoke:**
- Manual Policy + Recovery walkthroughs in `gui/TESTING.md` against a real GNOME session.
```

**Step 3: Commit**

```bash
git add docs/plans/2026-04-26-authforge-implementation.md
git commit --no-gpg-sign -m "docs: phase 9 + phase 12 GUI closeout notes"
```

---

## Phase 9 + Phase 12 GUI Acceptance Gate

Verify before tagging:

- [ ] `cargo build -p authforge-gui` clean.
- [ ] `cargo clippy -p authforge-gui --all-targets -- -D warnings` clean.
- [ ] `cargo test -p authforge-gui` — all error-classifier tests + 3 new `policy_form` tests PASS.
- [ ] `cargo fmt --all -- --check` clean.
- [ ] `cargo build --workspace --release` succeeds.
- [ ] Manual smoke (deferred to live system + Yubikey): Policy and Recovery tab walkthroughs in `gui/TESTING.md` pass.

Tag the milestone:

```bash
git tag -a v0.6.0-gui-policy-recovery -m "Phase 9 + Phase 12 GUI: Policy and Recovery tabs"
```

---

## Risks / known unknowns

| Risk | Mitigation |
|---|---|
| Phase 8's final `Daemon` shape diverges from what's documented in [2026-04-27-phase-8-gui-keys.md:184-235](2026-04-27-phase-8-gui-keys.md#L184-L235). | EXECUTION GATE waits for Phase 8 to land. If Phase 8 chose a different shape, Task 2 absorbs the rename — purely additive method names map 1:1. |
| `adw::Banner` API differs across libadwaita 0.6 minors (`set_revealed` vs `revealed` builder). | Plan uses the builder + `connect_button_clicked` signal which has been stable since libadwaita 0.5. If a particular minor drops it, fall back to a top-of-page `gtk::InfoBar`. |
| `PolicyChanged` signal uses zbus `tokio` runtime here whereas Phase 8 may have inadvertently picked the glib feature. | The Phase 8 plan was patched (commit `a17f70c`) to clarify "no glib feature exists" — this lane uses `workspace = true` for zbus, matching what Phase 8 lands. Verify at execution time by reading `gui/Cargo.toml` after Phase 8 merges. |
| Clipboard set on a non-default display fails silently. | Acceptable — the dialog also shows the code in a selectable label, so the user can copy by hand. Toast doesn't fire because no error is returned by `gdk::Clipboard::set_text`. |
| `AdwEntryRow::text()` returns a `glib::GString`; needs `.to_string()` for `to_owned`. | Plan already does this; flagged so future edits don't accidentally borrow across an await. |
| Daemon's lockout simulator (Phase 5) returns `Vec<Violation>` but doesn't currently include user-friendly fix suggestions — only "no fido2 enrolled". | The banner copy in Task 4 reflects this: it lists the violation reasons verbatim. A richer "fix it" UX is a Phase 17/18 polish item, not Phase 9. |

---

## Execution Handoff

Plan complete. Single lane, single agent. Suggested execution: open a fresh session in a worktree using `superpowers:using-git-worktrees`, then drive task-by-task with `superpowers:executing-plans`. **Do not start until Phase 8 lands on `main`.**