MikeFaith/authforge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
5d6b7ceeb0dc72d88a486967d196cdddea7455b4
authforge/docs/plans/2026-04-27-phase-3-6-7-multi-lane.md

1417 lines
46 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Phase 3 + 6 + 7: FIDO2 Backend, PAM Module, CLI — Multi-Lane Implementation Plan
> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
**Goal:** Land three parallel-safe phases — Phase 3 (FIDO2 enrollment via `ctap-hid-fido2`), Phase 6 (`pam_authforge_pending.so` C module), Phase 7 (`authforgectl` CLI) — in one bundled work cycle. They touch disjoint file trees (`daemon/src/fido/`, `pam/`, `cli/src/`) and consume only the D-Bus contract from Phase 1 plus the storage façade from Phase 2.
**Architecture:** Phase 3 hides `ctap-hid-fido2` behind an `Authenticator` trait with a fake impl for unit tests and a hardware-backed real impl. Phase 6 replaces the Phase 0 PAM stub with a real pending-flag check that reads `/var/lib/authforge/pending/<user>` and returns `PAM_AUTH_ERR` if present. Phase 7 is a thin `clap` CLI that maps subcommands to the existing 9 D-Bus methods (with `--json` for fleet/Ansible).
**Tech Stack:**
- Phase 3: `ctap-hid-fido2 = "3"` (already in workspace deps), `hex = "0.4"` for the pam_u2f format encoder. Hardware-dependent paths gated behind `#[cfg(target_os = "linux")]` plus a runtime check.
- Phase 6: ANSI C against `<security/pam_modules.h>` and `<security/pam_ext.h>`. Build via `pam/Makefile` (already exists).
- Phase 7: `clap = "4"` with `derive` (workspace dep), `zbus = "4"` (workspace dep), `serde_json` for `--json` output.
**Reference:**
- Master plan & lane diagram: [2026-04-26-authforge-implementation.md](2026-04-26-authforge-implementation.md) § Parallel Execution Lanes.
- Design doc: [2026-04-26-authforge-design.md](2026-04-26-authforge-design.md) — § Trust boundary, § PAM and policy details.
---
## Conventions
- One logical change per commit. Conventional prefixes: `feat:`, `test:`, `chore:`, `refactor:`. Lane prefix on the scope: `feat(daemon-fido):`, `feat(pam):`, `feat(cli):`.
- Always commit with `--no-gpg-sign`.
- TDD for everything mechanical. Real-hardware paths in Phase 3 are exempt — they get a compile-clean gate plus a "manual smoke pending Phase 14 VM" note.
- After each commit: `cargo fmt --all && cargo clippy --workspace --all-targets -- -D warnings && cargo test -p authforge-{common,daemon,cli}`. PAM lane verifies via `make -C pam` (deferred if `libpam0g-dev` not installed; already documented in BUILDING.md).
- Bundle execution order suggestion: **C (CLI) → B (PAM) → A (FIDO2)**. CLI is the lowest-risk lane (pure Rust, talks settled contract); PAM is small and self-contained; FIDO2 is the largest with real-hardware caveats. Order can shift if blocked.
---
## Lane A: Phase 3 — FIDO2 Enrollment Backend
### Task A1: Add `ctap-hid-fido2` + `hex` to daemon deps
**Files:**
- Modify: `Cargo.toml` (workspace root) — add `hex = "0.4"`.
- Modify: `daemon/Cargo.toml` — add `ctap-hid-fido2 = { workspace = true }` and `hex = { workspace = true }`.
`ctap-hid-fido2` is already in workspace deps from Phase 0 but never pulled into a member crate; the resolver hasn't even fetched it. First use is in this lane.
**Step 1:** Append to root `Cargo.toml` `[workspace.dependencies]`:
```toml
hex = "0.4"
```
**Step 2:** Append to `daemon/Cargo.toml` `[dependencies]`:
```toml
ctap-hid-fido2 = { workspace = true }
hex = { workspace = true }
```
**Step 3:** `cargo check -p authforge-daemon`. Expected: clean (deps unused, but the compile fetches them).
**Step 4:** Commit.
```bash
git add Cargo.toml Cargo.lock daemon/Cargo.toml
git commit --no-gpg-sign -m "chore: add ctap-hid-fido2 and hex deps for Phase 3"
```
---
### Task A2: pam_u2f line-format encoder
**Files:**
- Create: `daemon/src/fido/mod.rs`
- Create: `daemon/src/fido/format.rs`
- Modify: `daemon/src/main.rs` (add `mod fido;`)
**Background:** pam_u2f file format per its source:
```
username:keyHandle,publicKey,COSEType,Attributes[:keyHandle,publicKey,COSEType,Attributes...]
```
- `keyHandle` and `publicKey` are lowercase hex.
- `COSEType` is `es256` (COSE alg -7) or `eddsa` (-8).
- `Attributes` is one of `+presence`, `+verification`, `+pin` joined with `,` if multiple. We always emit `+presence` for v1 (touch required); UV / PIN attributes land in Phase 11 alongside TOTP.
**Step 1:** Create `daemon/src/fido/mod.rs`:
```rust
pub(crate) mod format;
```
**Step 2:** Failing test in `daemon/src/fido/format.rs`:
```rust
//! Convert a make_credential result into a pam_u2f keys file line.
#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) struct PamU2fCred {
pub key_handle: Vec<u8>,
pub public_key_der: Vec<u8>,
pub cose_type: CoseType,
pub user_presence: bool,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) enum CoseType {
Es256,
Eddsa,
}
#[allow(dead_code)] // wired through fido/enroll.rs in Task A5.
impl PamU2fCred {
/// Encode as a pam_u2f file *credential* segment (the part after
/// `username:`). Caller joins `username:` + this + (optional `:` + next).
pub fn to_pam_segment(&self) -> String {
let kh = hex::encode(&self.key_handle);
let pk = hex::encode(&self.public_key_der);
let cose = match self.cose_type {
CoseType::Es256 => "es256",
CoseType::Eddsa => "eddsa",
};
let attrs = if self.user_presence { "+presence" } else { "" };
format!("{kh},{pk},{cose},{attrs}")
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn segment_uses_lowercase_hex_es256_presence() {
let c = PamU2fCred {
key_handle: vec![0xDE, 0xAD, 0xBE, 0xEF],
public_key_der: vec![0x30, 0x59],
cose_type: CoseType::Es256,
user_presence: true,
};
assert_eq!(c.to_pam_segment(), "deadbeef,3059,es256,+presence");
}
#[test]
fn segment_handles_eddsa_no_presence() {
let c = PamU2fCred {
key_handle: vec![0x01],
public_key_der: vec![0x02],
cose_type: CoseType::Eddsa,
user_presence: false,
};
assert_eq!(c.to_pam_segment(), "01,02,eddsa,");
}
}
```
**Step 3:** Add `mod fido;` to `daemon/src/main.rs`.
**Step 4:** Run `cargo test -p authforge-daemon fido::format`. Expected: 2 PASS.
**Step 5:** Commit.
```bash
git add daemon/src/fido/mod.rs daemon/src/fido/format.rs daemon/src/main.rs
git commit --no-gpg-sign -m "feat(daemon-fido): pam_u2f line-format encoder"
```
---
### Task A3: `Authenticator` trait + types
**Files:**
- Create: `daemon/src/fido/authenticator.rs`
- Modify: `daemon/src/fido/mod.rs`
**Step 1:** Add `pub(crate) mod authenticator;` to `daemon/src/fido/mod.rs`.
**Step 2:** Create `daemon/src/fido/authenticator.rs`:
```rust
use crate::fido::format::PamU2fCred;
use thiserror::Error;
#[derive(Debug, Error)]
pub(crate) enum AuthnError {
#[error("no FIDO2 device found")]
NoDevice,
#[error("user cancelled or device timed out")]
Cancelled,
#[error("PIN required but not provided")]
PinRequired,
#[error("backend: {0}")]
Backend(String),
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) struct DiscoveredDevice {
pub name: String,
pub transport: authforge_common::types::Transport,
pub path: String,
}
/// Backend-agnostic enrollment surface. The fake impl is used in unit tests;
/// the real impl wraps `ctap-hid-fido2`. Picking the concrete type happens at
/// the call site in `state.rs`.
pub(crate) trait Authenticator: Send + Sync {
/// List devices currently visible to the host.
fn discover(&self) -> Result<Vec<DiscoveredDevice>, AuthnError>;
/// Enroll a new credential on the currently-attached authenticator.
/// `rp_id` follows pam_u2f convention (`pam://localhost`).
fn make_credential(
&self,
rp_id: &str,
user: &str,
pin: Option<&str>,
) -> Result<PamU2fCred, AuthnError>;
}
```
**Step 3:** `cargo build -p authforge-daemon`. Expected: clean (no impls yet, but the trait compiles).
**Step 4:** Commit.
```bash
git add daemon/src/fido/mod.rs daemon/src/fido/authenticator.rs
git commit --no-gpg-sign -m "feat(daemon-fido): Authenticator trait with DiscoveredDevice and AuthnError"
```
---
### Task A4: `MockAuthenticator` for unit tests
**Files:**
- Create: `daemon/src/fido/mock.rs`
- Modify: `daemon/src/fido/mod.rs`
**Step 1:** Add `pub(crate) mod mock;` to `daemon/src/fido/mod.rs`.
**Step 2:** Failing test plus impl in `daemon/src/fido/mock.rs`:
```rust
use crate::fido::authenticator::{Authenticator, AuthnError, DiscoveredDevice};
use crate::fido::format::{CoseType, PamU2fCred};
use authforge_common::types::Transport;
use std::sync::Mutex;
/// In-memory authenticator for tests. Records every call; produces a
/// deterministic PamU2fCred from a counter so two enrollments differ.
pub(crate) struct MockAuthenticator {
next: Mutex<u32>,
pub devices: Vec<DiscoveredDevice>,
}
impl MockAuthenticator {
#[allow(dead_code)] // used by Task A6.
pub fn with_one_yubikey() -> Self {
Self {
next: Mutex::new(1),
devices: vec![DiscoveredDevice {
name: "Mock Yubikey 5".to_string(),
transport: Transport::Usb,
path: "/dev/mock0".to_string(),
}],
}
}
}
impl Authenticator for MockAuthenticator {
fn discover(&self) -> Result<Vec<DiscoveredDevice>, AuthnError> {
Ok(self.devices.clone())
}
fn make_credential(
&self,
_rp_id: &str,
_user: &str,
_pin: Option<&str>,
) -> Result<PamU2fCred, AuthnError> {
if self.devices.is_empty() {
return Err(AuthnError::NoDevice);
}
let mut n = self.next.lock().unwrap();
let kh = vec![*n as u8, 0xCA, 0xFE];
let pk = vec![*n as u8, 0xBE, 0xEF];
*n += 1;
Ok(PamU2fCred {
key_handle: kh,
public_key_der: pk,
cose_type: CoseType::Es256,
user_presence: true,
})
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn mock_discover_lists_one_device() {
let m = MockAuthenticator::with_one_yubikey();
let devs = m.discover().unwrap();
assert_eq!(devs.len(), 1);
assert_eq!(devs[0].transport, Transport::Usb);
}
#[test]
fn mock_make_credential_is_unique_per_call() {
let m = MockAuthenticator::with_one_yubikey();
let a = m.make_credential("pam://localhost", "alice", None).unwrap();
let b = m.make_credential("pam://localhost", "alice", None).unwrap();
assert_ne!(a.key_handle, b.key_handle);
}
#[test]
fn mock_no_device_errors() {
let m = MockAuthenticator {
next: Mutex::new(1),
devices: vec![],
};
let r = m.make_credential("pam://localhost", "alice", None);
matches!(r, Err(AuthnError::NoDevice));
}
}
```
**Step 3:** Run, confirm 3 PASS.
**Step 4:** Commit.
```bash
git add daemon/src/fido/mod.rs daemon/src/fido/mock.rs
git commit --no-gpg-sign -m "feat(daemon-fido): MockAuthenticator for unit tests"
```
---
### Task A5: `CtapAuthenticator` real impl wrapping `ctap-hid-fido2`
**Files:**
- Create: `daemon/src/fido/ctap.rs`
- Modify: `daemon/src/fido/mod.rs`
**ctap-hid-fido2 3.5.x reference (verified against `~/.cargo/registry/src/index.crates.io-*/ctap-hid-fido2-3.5.9/src/`):**
- `ctap_hid_fido2::get_fidokey_devices() -> Vec<HidInfo>`
- `FidoKeyHidFactory::create(cfg: &LibCfg) -> Result<FidoKeyHid>`
- `FidoKeyHid::make_credential(rpid, challenge, pin) -> Result<Attestation>`
- `Attestation.credential_descriptor.id: Vec<u8>` is the keyHandle.
- `Attestation.credential_publickey.der: Vec<u8>` is the SPKI-DER public key (what pam_u2f expects).
- COSE algorithm sits in `Attestation.attstmt_alg: i32` — `-7` = es256, `-8` = eddsa. Anything else → return `AuthnError::Backend("unsupported COSE alg N")`.
**Step 1:** Add `pub(crate) mod ctap;` to `daemon/src/fido/mod.rs`.
**Step 2:** Create `daemon/src/fido/ctap.rs`:
```rust
use crate::fido::authenticator::{Authenticator, AuthnError, DiscoveredDevice};
use crate::fido::format::{CoseType, PamU2fCred};
use authforge_common::types::Transport;
pub(crate) struct CtapAuthenticator;
impl CtapAuthenticator {
#[allow(dead_code)] // selected by main.rs in Task A6.
pub fn new() -> Self {
Self
}
fn random_challenge() -> Vec<u8> {
// pam_u2f doesn't validate the challenge for *enrollment* (the
// attestation signature does, but pam_u2f only stores the credential).
// Still, generate 32 bytes of randomness so we don't trip authenticator
// anti-replay heuristics.
use rand::RngCore;
let mut buf = [0u8; 32];
rand::rng().fill_bytes(&mut buf);
buf.to_vec()
}
}
impl Authenticator for CtapAuthenticator {
fn discover(&self) -> Result<Vec<DiscoveredDevice>, AuthnError> {
// ctap-hid-fido2 is sync; calling on the tokio runtime is fine because
// device probing finishes in milliseconds. If it grows, wrap in
// spawn_blocking at the call site (state.rs).
let devices = ctap_hid_fido2::get_fidokey_devices();
Ok(devices
.into_iter()
.map(|d| DiscoveredDevice {
name: format!("{} {}", d.product_string, d.serial_number),
transport: Transport::Usb,
path: d.path,
})
.collect())
}
fn make_credential(
&self,
rp_id: &str,
_user: &str,
pin: Option<&str>,
) -> Result<PamU2fCred, AuthnError> {
use ctap_hid_fido2::fidokey::FidoKeyHidFactory;
use ctap_hid_fido2::LibCfg;
let cfg = LibCfg::init();
let fk = FidoKeyHidFactory::create(&cfg)
.map_err(|e| AuthnError::Backend(format!("open device: {e}")))?;
let challenge = Self::random_challenge();
let att = fk
.make_credential(rp_id, &challenge, pin)
.map_err(|e| {
let msg = format!("make_credential: {e}");
if msg.to_lowercase().contains("pin") {
AuthnError::PinRequired
} else if msg.to_lowercase().contains("cancel") || msg.to_lowercase().contains("timeout") {
AuthnError::Cancelled
} else {
AuthnError::Backend(msg)
}
})?;
let cose_type = match att.attstmt_alg {
-7 => CoseType::Es256,
-8 => CoseType::Eddsa,
other => return Err(AuthnError::Backend(format!("unsupported COSE alg {other}"))),
};
Ok(PamU2fCred {
key_handle: att.credential_descriptor.id,
public_key_der: att.credential_publickey.der,
cose_type,
user_presence: true,
})
}
}
```
**Step 3:** `cargo build -p authforge-daemon` (no test — real hardware required). Expected: clean compile.
If `LibCfg::init` doesn't exist, check the actual constructor in
`~/.cargo/registry/src/index.crates.io-*/ctap-hid-fido2-3.5.9/src/lib.rs` and adapt — it may be `LibCfg::default()` or a builder.
**Step 4:** Commit.
```bash
git add daemon/src/fido/mod.rs daemon/src/fido/ctap.rs
git commit --no-gpg-sign -m "feat(daemon-fido): CtapAuthenticator wrapping ctap-hid-fido2 (hardware-dep)"
```
---
### Task A6: Wire enrollment into `AppState::add_credential`
**Files:**
- Modify: `daemon/src/state.rs` — accept an `Arc<dyn Authenticator>` at open-time; switch `add_credential` to use real format.
- Modify: `daemon/src/dbus.rs` — `enroll_own` / `enroll_other` call the new path.
- Modify: `daemon/src/main.rs` — pick `CtapAuthenticator` for prod.
**Why:** Phase 2 stub stored cred ID as opaque "stub-{user}-{ts}". Now the format is real `keyHandle,publicKey,cose,attrs`.
**Step 1:** Modify `state.rs`:
```rust
// New field:
pub struct AppState {
policy: PolicyStore,
pending: PendingStore,
userdb: Mutex<UserDb>,
authn: Arc<dyn Authenticator>,
}
impl AppState {
pub fn open(cfg: StorageConfig, authn: Arc<dyn Authenticator>) -> Result<Self, StateError> {
let policy = PolicyStore::new(cfg.policy_dir);
let pending = PendingStore::new(cfg.pending_dir);
let userdb = Mutex::new(UserDb::open(&cfg.userdb_path)?);
Ok(Self { policy, pending, userdb, authn })
}
```
Replace `add_credential` to call the authenticator and write the real pam_u2f line:
```rust
pub async fn enroll(
&self,
user: &str,
nickname: &str,
) -> Result<Credential, StateError> {
let resolver = self.creds_resolver()?;
let path = resolver.path_for(user)?;
let store = CredentialsStore::new(path);
let pam_cred = self
.authn
.make_credential("pam://localhost", user, None)
.map_err(|e| StateError::Authn(e.to_string()))?;
let segment = pam_cred.to_pam_segment();
let cred_id = hex::encode(&pam_cred.key_handle);
store.add(user, &segment)?;
let db = self.userdb.lock().await;
db.record_enrollment(user, Method::Fido2)?;
Ok(Credential {
id: cred_id,
nickname: nickname.to_string(),
method: Method::Fido2,
transport: Transport::Usb,
created_unix: std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.map(|d| d.as_secs())
.unwrap_or(0),
})
}
```
Add to `StateError`:
```rust
#[error("authenticator: {0}")]
Authn(String),
```
Drop the Phase 2 `add_credential(user, c: Credential)` method — `dbus.rs` was its only caller.
**Step 2:** In `dbus.rs`, replace the body of `enroll_own` and `enroll_other` to call `self.state.enroll(&user, &nickname).await`:
```rust
async fn enroll_own(&self, user: String, nickname: String) -> zbus::fdo::Result<Credential> {
self.authz("io.dangerousthings.AuthForge.enroll-own").await?;
self.state
.enroll(&user, &nickname)
.await
.map_err(|e| zbus::fdo::Error::Failed(e.to_string()))
}
```
(Same for `enroll_other` with the different polkit action string.)
**Step 3:** In `main.rs`:
```rust
let authn: Arc<dyn fido::authenticator::Authenticator> =
Arc::new(fido::ctap::CtapAuthenticator::new());
let state = Arc::new(state::AppState::open(cfg, authn)?);
```
**Step 4:** Update `state.rs` and `dbus.rs` tests to inject `Arc::new(MockAuthenticator::with_one_yubikey())`. The dbus `p2p_pair` constructs `AppState::open(cfg, Arc::new(MockAuthenticator::with_one_yubikey()))`.
**Step 5:** Run `cargo test -p authforge-daemon`. Expected: all green. Tests that previously asserted `cred.id == "stub-..."` must now match a hex pattern; update assertions to `assert!(cred.id.chars().all(|c| c.is_ascii_hexdigit()))`.
**Step 6:** `cargo clippy --workspace --all-targets -- -D warnings` clean.
**Step 7:** Commit.
```bash
git add daemon/src/state.rs daemon/src/dbus.rs daemon/src/main.rs
git commit --no-gpg-sign -m "feat(daemon-fido): wire enrollment through Authenticator + write pam_u2f format"
```
---
### Task A7: D-Bus signals for enrollment progress
**Files:**
- Modify: `daemon/src/dbus.rs` — add `DeviceFound`, `TouchRequired`, `EnrollmentSucceeded`, `EnrollmentFailed` signals.
**Why deferred until A6 lands:** signals report on the `enroll` flow — until that flow exists, there's nothing to signal. Phase 8 (GUI) consumes these.
**Step 1:** Add signal declarations to the `#[zbus::interface]` impl in `dbus.rs`:
```rust
#[zbus(signal)]
pub async fn device_found(
ctx: &zbus::object_server::SignalContext<'_>,
name: String,
transport: String,
) -> zbus::Result<()>;
#[zbus(signal)]
pub async fn touch_required(
ctx: &zbus::object_server::SignalContext<'_>,
device: String,
) -> zbus::Result<()>;
#[zbus(signal)]
pub async fn enrollment_succeeded(
ctx: &zbus::object_server::SignalContext<'_>,
cred_id: String,
) -> zbus::Result<()>;
#[zbus(signal)]
pub async fn enrollment_failed(
ctx: &zbus::object_server::SignalContext<'_>,
reason: String,
) -> zbus::Result<()>;
```
**Step 2:** In `enroll_own` / `enroll_other`, emit signals around the call. Use `#[zbus(signal_context)]` to get the context inside an interface method:
```rust
async fn enroll_own(
&self,
#[zbus(signal_context)] ctx: zbus::object_server::SignalContext<'_>,
user: String,
nickname: String,
) -> zbus::fdo::Result<Credential> {
self.authz("io.dangerousthings.AuthForge.enroll-own").await?;
// Phase 3 emits a synthetic "touch required" before calling. Phase 8 will
// surface this in the GUI; until then it shows up in busctl monitor.
let _ = AuthForge::touch_required(&ctx, "primary".to_string()).await;
match self.state.enroll(&user, &nickname).await {
Ok(c) => {
let _ = AuthForge::enrollment_succeeded(&ctx, c.id.clone()).await;
Ok(c)
}
Err(e) => {
let msg = e.to_string();
let _ = AuthForge::enrollment_failed(&ctx, msg.clone()).await;
Err(zbus::fdo::Error::Failed(msg))
}
}
}
```
**Step 3:** Add an integration test mirroring `policy_changed_signal_fires_on_emit` for `EnrollmentSucceeded`:
```rust
#[tokio::test]
async fn enrollment_succeeded_signal_fires() {
use futures_util::stream::StreamExt;
let (_srv, client, _state, _tmp) = p2p_pair().await;
let p = proxy(&client).await;
let mut stream = p.receive_signal("EnrollmentSucceeded").await.unwrap();
let _: Credential = p.call("EnrollOwn", &("alice", "Yellow")).await.unwrap();
let _msg = tokio::time::timeout(std::time::Duration::from_secs(2), stream.next())
.await
.expect("EnrollmentSucceeded signal not received");
}
```
**Step 4:** Run `cargo test -p authforge-daemon`. Expected: green.
**Step 5:** Commit.
```bash
git add daemon/src/dbus.rs
git commit --no-gpg-sign -m "feat(daemon-fido): emit DeviceFound/TouchRequired/EnrollmentSucceeded/Failed signals"
```
---
## Lane B: Phase 6 — `pam_authforge_pending.so`
### Task B1: Replace stub with real pending-flag check
**Files:**
- Modify: `pam/pam_authforge_pending.c` (full rewrite of the stub)
**Behavior per design doc § PAM module backstop:**
1. Read `PAM_USER` from the conv stack.
2. Reject usernames containing `/`, `\0`, `..`, or that are `.`/empty.
3. `stat("/var/lib/authforge/pending/<user>")`:
- File present → `pam_error()` with the user-facing message + return `PAM_AUTH_ERR`.
- `ENOENT` → return `PAM_IGNORE` (let the rest of the stack decide).
- Other errors → `pam_syslog(LOG_ERR, ...)` + return `PAM_AUTH_ERR` (fail closed).
4. `pam_sm_setcred` always returns `PAM_SUCCESS`.
**Recovery code** (Phase 12) — for Phase 6 we add a hook that the recovery flow can wire up later, but the hook is a no-op for now:
```c
static int recovery_code_matches(const char *user, const char *code) {
(void)user; (void)code;
return 0; // placeholder; Phase 12 implements Argon2id constant-time check.
}
```
**Step 1:** Replace `pam/pam_authforge_pending.c`:
```c
#define PAM_SM_AUTH
#include <security/pam_modules.h>
#include <security/pam_ext.h>
#include <errno.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <syslog.h>
#include <sys/stat.h>
#define PENDING_DIR "/var/lib/authforge/pending/"
#define USER_MSG "Account setup incomplete. Please complete enrollment in the Authentication app."
static int username_is_safe(const char *u) {
if (u == NULL || u[0] == '\0') return 0;
if (strcmp(u, ".") == 0 || strcmp(u, "..") == 0) return 0;
for (const char *p = u; *p; ++p) {
if (*p == '/' || *p == '\0') return 0;
}
/* Also reject any '..' substring just to be safe against weird locales. */
if (strstr(u, "..") != NULL) return 0;
return 1;
}
static int pending_flag_present(const char *user) {
char path[1024];
int n = snprintf(path, sizeof(path), "%s%s", PENDING_DIR, user);
if (n < 0 || (size_t)n >= sizeof(path)) return -1;
struct stat st;
if (stat(path, &st) == 0) return 1;
if (errno == ENOENT) return 0;
return -1;
}
PAM_EXTERN int pam_sm_authenticate(pam_handle_t *pamh, int flags,
int argc, const char **argv) {
(void)flags; (void)argc; (void)argv;
const char *user = NULL;
if (pam_get_user(pamh, &user, NULL) != PAM_SUCCESS || user == NULL) {
pam_syslog(pamh, LOG_ERR, "authforge_pending: pam_get_user failed");
return PAM_AUTH_ERR;
}
if (!username_is_safe(user)) {
pam_syslog(pamh, LOG_ERR, "authforge_pending: rejected unsafe user %s", user);
return PAM_AUTH_ERR;
}
int present = pending_flag_present(user);
if (present < 0) {
pam_syslog(pamh, LOG_ERR, "authforge_pending: stat error for %s", user);
return PAM_AUTH_ERR; /* fail closed */
}
if (present == 0) {
return PAM_IGNORE;
}
pam_error(pamh, "%s", USER_MSG);
return PAM_AUTH_ERR;
}
PAM_EXTERN int pam_sm_setcred(pam_handle_t *pamh, int flags,
int argc, const char **argv) {
(void)pamh; (void)flags; (void)argc; (void)argv;
return PAM_SUCCESS;
}
```
**Step 2:** Build verification:
```bash
make -C pam
```
If `libpam0g-dev` is not installed, the build fails with `<security/pam_modules.h>: No such file or directory`. That matches the deferred-build convention in BUILDING.md; record the deferral and move on.
**Step 3:** Commit.
```bash
git add pam/pam_authforge_pending.c
git commit --no-gpg-sign -m "feat(pam): real pending-flag check with path-traversal guard"
```
---
### Task B2: Test plan via `pamtester` (manual, deferred)
**Files:**
- Create: `pam/TESTING.md`
**Step 1:** Create `pam/TESTING.md` documenting the manual smoke test that runs in a VM with `libpam0g-dev` and `pamtester` installed:
```markdown
# Testing pam_authforge_pending.so
Smoke test (run in a VM or container with `libpam0g-dev` + `pamtester` installed):
```bash
sudo make -C pam install # builds + installs to /usr/lib/.../security/
sudo cp pam/test/authforge.pamd /etc/pam.d/authforge
# Pending case: should be denied with the user-facing message.
sudo mkdir -p /var/lib/authforge/pending
sudo touch /var/lib/authforge/pending/$USER
pamtester authforge "$USER" authenticate
# expect: "Account setup incomplete..." + non-zero exit
# Cleared case: should fall through to PAM_IGNORE -> success via the rest of the stack.
sudo rm /var/lib/authforge/pending/$USER
pamtester authforge "$USER" authenticate
# expect: success
```
Path-traversal regression:
```bash
# These usernames must be rejected with a logged error and PAM_AUTH_ERR:
for u in "../etc" "a/b" "" "." ".." "x..y"; do
pamtester -v authforge "$u" authenticate 2>&1 | head -3
done
```
CI cannot run `pamtester` against a real PAM stack without root and a VM, so
this is the last manual gate before Phase 14 (PPA build).
```
**Step 2:** Add a minimal `pam/test/authforge.pamd` for use by the smoke test:
```
# /etc/pam.d/authforge — only used by manual pamtester runs.
auth required pam_authforge_pending.so
auth required pam_unix.so
account required pam_unix.so
```
**Step 3:** Commit.
```bash
git add pam/TESTING.md pam/test/authforge.pamd
git commit --no-gpg-sign -m "docs(pam): smoke-test recipe for pamtester (manual, VM-gated)"
```
---
## Lane C: Phase 7 — `authforgectl` CLI
### Task C1: Subcommand structure
**Files:**
- Create: `cli/src/commands/mod.rs`
- Modify: `cli/src/main.rs` — replace the Phase 0 stub with full clap derives.
**Subcommands per master plan § Phase 7:**
```
authforgectl status
authforgectl enroll [--user USER] [--nickname NAME]
authforgectl list [--user USER]
authforgectl remove [--user USER] CRED_ID
authforgectl policy show
authforgectl policy set <stack> <mode> [--methods METHOD,...]
authforgectl policy apply [--force-i-know-what-im-doing]
authforgectl policy validate
authforgectl pending set USER [--methods METHOD,...]
authforgectl pending clear USER
authforgectl pending list
authforgectl recovery generate USER
authforgectl recovery list USER
```
**Step 1:** Replace `cli/src/main.rs`:
```rust
use anyhow::Result;
use clap::{Parser, Subcommand};
mod commands;
#[derive(Parser)]
#[command(name = "authforgectl", version, about = "Manage authforge configuration")]
struct Cli {
/// Emit machine-parseable JSON.
#[arg(long, global = true)]
json: bool,
#[command(subcommand)]
cmd: Cmd,
}
#[derive(Subcommand)]
enum Cmd {
/// Show daemon + policy status.
Status,
/// Enroll a security key for a user (interactive).
Enroll {
#[arg(long)]
user: Option<String>,
#[arg(long)]
nickname: Option<String>,
},
/// List enrolled credentials for a user.
List {
#[arg(long)]
user: Option<String>,
},
/// Remove a credential by ID.
Remove {
#[arg(long)]
user: Option<String>,
cred_id: String,
},
/// Manage MFA policy.
Policy {
#[command(subcommand)]
cmd: PolicyCmd,
},
/// Manage first-login pending flags.
Pending {
#[command(subcommand)]
cmd: PendingCmd,
},
/// Manage recovery codes.
Recovery {
#[command(subcommand)]
cmd: RecoveryCmd,
},
}
#[derive(Subcommand)]
enum PolicyCmd {
Show,
Set {
stack: String,
/// disabled | optional | required
mode: String,
#[arg(long, value_delimiter = ',')]
methods: Vec<String>,
},
Apply {
#[arg(long = "force-i-know-what-im-doing")]
force: bool,
},
Validate,
}
#[derive(Subcommand)]
enum PendingCmd {
Set {
user: String,
#[arg(long, value_delimiter = ',')]
methods: Vec<String>,
},
Clear {
user: String,
},
List,
}
#[derive(Subcommand)]
enum RecoveryCmd {
Generate { user: String },
List { user: String },
}
#[tokio::main]
async fn main() -> Result<()> {
let cli = Cli::parse();
commands::dispatch(cli.json, cli.cmd).await
}
```
**Step 2:** Create `cli/src/commands/mod.rs` with a stub dispatcher:
```rust
use anyhow::Result;
pub(crate) async fn dispatch(_json: bool, cmd: super::Cmd) -> Result<()> {
eprintln!("authforgectl: subcommand not yet wired in this build");
let _ = cmd;
Ok(())
}
```
**Step 3:** `cargo build -p authforgectl`. Expected: clean.
**Step 4:** Add a basic clap-parser test in `cli/src/main.rs`:
```rust
#[cfg(test)]
mod tests {
use super::*;
use clap::CommandFactory;
#[test]
fn cli_definition_is_valid() {
Cli::command().debug_assert();
}
#[test]
fn parse_status_subcommand() {
let c = Cli::try_parse_from(["authforgectl", "status"]).unwrap();
assert!(matches!(c.cmd, Cmd::Status));
}
#[test]
fn parse_policy_set_with_methods() {
let c = Cli::try_parse_from([
"authforgectl", "policy", "set", "sudo", "required",
"--methods", "fido2,totp",
])
.unwrap();
match c.cmd {
Cmd::Policy { cmd: PolicyCmd::Set { stack, mode, methods } } => {
assert_eq!(stack, "sudo");
assert_eq!(mode, "required");
assert_eq!(methods, vec!["fido2".to_string(), "totp".to_string()]);
}
_ => panic!("wrong subcommand"),
}
}
}
```
**Step 5:** `cargo test -p authforgectl`. Expected: 3 PASS.
**Step 6:** Commit.
```bash
git add cli/src/main.rs cli/src/commands/mod.rs
git commit --no-gpg-sign -m "feat(cli): authforgectl subcommand structure with clap derive"
```
---
### Task C2: D-Bus client wrapper
**Files:**
- Create: `cli/src/bus.rs`
- Modify: `cli/Cargo.toml` — add `authforge-common`, `serde`, `serde_json` deps if not already present.
**Step 1:** Update `cli/Cargo.toml` `[dependencies]`:
```toml
authforge-common = { path = "../common" }
zbus = { workspace = true }
serde = { workspace = true }
serde_json = { workspace = true }
```
(zbus is already there from Phase 0.)
**Step 2:** Create `cli/src/bus.rs`:
```rust
use anyhow::{Context, Result};
use authforge_common::policy::Policy;
use authforge_common::types::{Credential, PendingFlag, PolicyApplyResult};
pub(crate) struct Daemon {
proxy: zbus::Proxy<'static>,
}
impl Daemon {
pub async fn connect() -> Result<Self> {
let conn = zbus::Connection::system()
.await
.context("connecting to system D-Bus")?;
let proxy = zbus::Proxy::new(
&conn,
"io.dangerousthings.AuthForge",
"/io/dangerousthings/AuthForge",
"io.dangerousthings.AuthForge1",
)
.await?;
// The proxy holds a borrowed connection; we need 'static. Re-build
// an owned proxy.
let proxy: zbus::Proxy<'static> =
zbus::Proxy::new_owned(conn, /* dest */ "io.dangerousthings.AuthForge".into(),
/* path */ "/io/dangerousthings/AuthForge".into(),
/* iface */ "io.dangerousthings.AuthForge1".into())
.await?;
let _ = proxy; // see note below
// zbus 4 actually exposes ProxyBuilder for the owned case; check
// ~/.cargo/registry/src/index.crates.io-*/zbus-4.4.0/src/proxy.rs at
// implementation time and adapt.
Ok(Self { proxy: todo!("replace with real owned-proxy ctor") })
}
```
> **Note on the Proxy lifetime:** the snippet above is wrong-shaped; zbus 4 has `Proxy::new` returning a `Proxy<'_>` borrowing the connection. To keep the connection alive alongside the proxy, hold both:
```rust
pub(crate) struct Daemon {
_conn: zbus::Connection,
proxy: zbus::Proxy<'static>, // 'static via Proxy::into_owned()
}
impl Daemon {
pub async fn connect() -> Result<Self> {
let conn = zbus::Connection::system().await?;
let proxy = zbus::Proxy::new(
&conn,
"io.dangerousthings.AuthForge",
"/io/dangerousthings/AuthForge",
"io.dangerousthings.AuthForge1",
)
.await?
.into_owned();
Ok(Self { _conn: conn, proxy })
}
}
```
(`Proxy::into_owned()` exists in zbus 4 — confirm against the registry source.)
**Step 3:** Add the method calls:
```rust
impl Daemon {
pub async fn list_credentials(&self, user: &str) -> Result<Vec<Credential>> {
Ok(self.proxy.call("ListCredentials", &(user,)).await?)
}
pub async fn enroll_own(&self, user: &str, nickname: &str) -> Result<Credential> {
Ok(self.proxy.call("EnrollOwn", &(user, nickname)).await?)
}
pub async fn remove_own(&self, user: &str, cred_id: &str) -> Result<()> {
Ok(self.proxy.call("RemoveOwn", &(user, cred_id)).await?)
}
pub async fn get_policy(&self) -> Result<Policy> {
Ok(self.proxy.call("GetPolicy", &()).await?)
}
pub async fn set_policy(&self, p: &Policy) -> Result<PolicyApplyResult> {
Ok(self.proxy.call("SetPolicy", &(p,)).await?)
}
pub async fn set_pending_flag(&self, user: &str, flag: &PendingFlag) -> Result<()> {
Ok(self.proxy.call("SetPendingFlag", &(user, flag)).await?)
}
pub async fn clear_pending_flag(&self, user: &str) -> Result<()> {
Ok(self.proxy.call("ClearPendingFlag", &(user,)).await?)
}
pub async fn generate_recovery_code(&self, user: &str) -> Result<String> {
Ok(self.proxy.call("GenerateRecoveryCode", &(user,)).await?)
}
}
```
**Step 4:** Add `mod bus;` to `cli/src/main.rs`.
**Step 5:** `cargo build -p authforgectl`. Expected: clean.
**Step 6:** Commit.
```bash
git add cli/src/bus.rs cli/src/main.rs cli/Cargo.toml
git commit --no-gpg-sign -m "feat(cli): D-Bus client wrapper around AuthForge interface"
```
---
### Task C3: Implement read-side subcommands (`status`, `list`, `policy show`)
**Files:**
- Modify: `cli/src/commands/mod.rs`
**Step 1:** Replace the dispatcher to handle three read commands:
```rust
use anyhow::Result;
use crate::bus::Daemon;
pub(crate) async fn dispatch(json: bool, cmd: crate::Cmd) -> Result<()> {
let d = Daemon::connect().await?;
match cmd {
crate::Cmd::Status => {
let pol = d.get_policy().await?;
if json {
println!("{}", serde_json::to_string_pretty(&pol)?);
} else {
println!("authforge daemon: connected");
println!("policy stacks configured: {}", pol.stacks.len());
for (name, sp) in &pol.stacks {
println!(" {}: {:?} ({:?})", name, sp.mode, sp.methods);
}
}
}
crate::Cmd::List { user } => {
let user = user.unwrap_or_else(|| whoami_or_user());
let creds = d.list_credentials(&user).await?;
if json {
println!("{}", serde_json::to_string_pretty(&creds)?);
} else {
if creds.is_empty() {
println!("no credentials for {user}");
} else {
for c in creds {
println!("{}\t{}\t{:?}\t{:?}", c.id, c.nickname, c.method, c.transport);
}
}
}
}
crate::Cmd::Policy { cmd: crate::PolicyCmd::Show } => {
let pol = d.get_policy().await?;
if json {
println!("{}", serde_json::to_string_pretty(&pol)?);
} else {
println!("{}", toml::to_string_pretty(&pol).unwrap_or_default());
}
}
// Other branches added in Tasks C4 and C5.
_ => anyhow::bail!("subcommand not yet implemented"),
}
Ok(())
}
fn whoami_or_user() -> String {
std::env::var("USER").or_else(|_| std::env::var("LOGNAME")).unwrap_or_else(|_| "unknown".into())
}
```
Add `toml` to `cli/Cargo.toml` `[dependencies]`:
```toml
toml = { workspace = true }
```
**Step 2:** `cargo build -p authforgectl && cargo test -p authforgectl`. Expected: clean + 3 prior parser tests still pass.
**Step 3:** Commit.
```bash
git add cli/src/commands/mod.rs cli/Cargo.toml
git commit --no-gpg-sign -m "feat(cli): status/list/policy-show subcommands wired to D-Bus"
```
---
### Task C4: Write-side subcommands (`enroll`, `remove`, `policy set/apply`)
**Files:**
- Modify: `cli/src/commands/mod.rs`
**Step 1:** Add to the match arms:
```rust
crate::Cmd::Enroll { user, nickname } => {
let user = user.unwrap_or_else(whoami_or_user);
let nickname = nickname.unwrap_or_else(|| "Security Key".to_string());
let cred = d.enroll_own(&user, &nickname).await?;
if json {
println!("{}", serde_json::to_string_pretty(&cred)?);
} else {
println!("enrolled credential {} ({}) for {}", cred.id, cred.nickname, user);
}
}
crate::Cmd::Remove { user, cred_id } => {
let user = user.unwrap_or_else(whoami_or_user);
d.remove_own(&user, &cred_id).await?;
if !json {
println!("removed credential {cred_id} for {user}");
}
}
crate::Cmd::Policy { cmd: crate::PolicyCmd::Set { stack, mode, methods } } => {
use authforge_common::policy::{Policy, StackPolicy};
use authforge_common::types::{Method, Mode};
let m = match mode.as_str() {
"disabled" => Mode::Disabled,
"optional" => Mode::Optional,
"required" => Mode::Required,
other => anyhow::bail!("unknown mode: {other}"),
};
let methods: Result<Vec<Method>> = methods
.into_iter()
.map(|s| match s.as_str() {
"fido2" => Ok(Method::Fido2),
"totp" => Ok(Method::Totp),
other => Err(anyhow::anyhow!("unknown method: {other}")),
})
.collect();
let mut pol = d.get_policy().await?;
pol.stacks.insert(stack.clone(), StackPolicy { mode: m, methods: methods? });
let _ = d.set_policy(&pol).await?;
if !json {
println!("policy updated for stack {stack}");
}
}
crate::Cmd::Policy { cmd: crate::PolicyCmd::Apply { force: _ } } => {
// Phase 4 wires the apply call; until then this is a no-op that
// re-saves the current policy so the daemon emits PolicyChanged.
let pol = d.get_policy().await?;
let _ = d.set_policy(&pol).await?;
if !json {
println!("policy re-applied (Phase 4 wires real pam-auth-update)");
}
}
crate::Cmd::Policy { cmd: crate::PolicyCmd::Validate } => {
// Phase 5 wires the lockout simulator; until then validate is a
// syntax-only round-trip via TOML.
let pol = d.get_policy().await?;
let _ = toml::to_string_pretty(&pol)?;
if !json {
println!("policy is syntactically valid");
}
}
```
**Step 2:** `cargo build -p authforgectl`. Clean.
**Step 3:** Commit.
```bash
git add cli/src/commands/mod.rs
git commit --no-gpg-sign -m "feat(cli): enroll/remove/policy-set/apply/validate subcommands"
```
---
### Task C5: Pending and Recovery subcommands
**Files:**
- Modify: `cli/src/commands/mod.rs`
**Step 1:** Add the remaining match arms:
```rust
crate::Cmd::Pending { cmd: crate::PendingCmd::Set { user, methods } } => {
use authforge_common::types::{Method, PendingFlag};
let methods: Result<Vec<Method>> = methods
.into_iter()
.map(|s| match s.as_str() {
"fido2" => Ok(Method::Fido2),
"totp" => Ok(Method::Totp),
other => Err(anyhow::anyhow!("unknown method: {other}")),
})
.collect();
let now = std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.map(|d| d.as_secs())
.unwrap_or(0);
let flag = PendingFlag {
required_methods: methods?,
created_unix: now,
deadline_unix: 0,
re_enroll: false,
};
d.set_pending_flag(&user, &flag).await?;
if !json {
println!("pending flag set for {user}");
}
}
crate::Cmd::Pending { cmd: crate::PendingCmd::Clear { user } } => {
d.clear_pending_flag(&user).await?;
if !json {
println!("pending flag cleared for {user}");
}
}
crate::Cmd::Pending { cmd: crate::PendingCmd::List } => {
// Phase 7 doesn't have a ListPending D-Bus method yet; print a
// hint and exit cleanly. Adding the method is a Phase 5/12
// adjustment when the GUI's "who has a pending flag?" view ships.
if !json {
println!("(ListPending D-Bus method lands when GUI needs it)");
}
}
crate::Cmd::Recovery { cmd: crate::RecoveryCmd::Generate { user } } => {
let code = d.generate_recovery_code(&user).await?;
if json {
println!("{}", serde_json::json!({ "user": user, "code": code }));
} else {
println!("{code}");
}
}
crate::Cmd::Recovery { cmd: crate::RecoveryCmd::List { user: _ } } => {
if !json {
println!("(ListRecovery lands in Phase 12)");
}
}
```
Drop the trailing `_ => anyhow::bail!(...)` arm since all arms are now covered.
**Step 2:** `cargo build -p authforgectl && cargo test -p authforgectl && cargo clippy -p authforgectl --all-targets -- -D warnings`. Clean.
**Step 3:** Commit.
```bash
git add cli/src/commands/mod.rs
git commit --no-gpg-sign -m "feat(cli): pending and recovery subcommands"
```
---
## Phase 3+6+7 Acceptance Gate
Verify before tagging:
- [ ] `cargo build --workspace --release` succeeds (excluding gui).
- [ ] `cargo test -p authforge-common` — 13 PASS.
- [ ] `cargo test -p authforge-daemon` — original 26 + new ones from A2/A4/A6/A7 = ~32 PASS.
- [ ] `cargo test -p authforgectl` — 3 clap parser tests PASS.
- [ ] `cargo clippy --workspace --all-targets -- -D warnings` clean.
- [ ] `make -C pam` — pass on a box with libpam0g-dev; deferred otherwise (record in BUILDING.md).
- [ ] Manual smoke (deferred): on a Yubikey-equipped Ubuntu VM, `authforgectl enroll --user alice` produces a real pam_u2f line in `~alice/.config/Yubico/u2f_keys`.
- [ ] Manual smoke (deferred): `pamtester authforge "$USER" authenticate` denies when pending flag exists.
Tag the milestone:
```bash
git tag -a v0.3.0-multi-lane -m "Phase 3+6+7: FIDO2 backend + PAM module + CLI"
```
---
## Risks / known unknowns
| Risk | Mitigation |
|---|---|
| `ctap-hid-fido2` API surface drift between 3.5.x patch versions. | Plan tested against 3.5.9; if minor fields rename, adapt at Task A5 against `~/.cargo/registry`. |
| `LibCfg::init` may not be the right constructor — could be `LibCfg::default()` or builder-style. | Verify at A5; small adjustment, no architectural change. |
| pam_u2f format minor variants (some distros use `+pin` instead of `+presence`). | We emit `+presence` which is the dominant default. If the CI VM disagrees, parametrize PamU2fCred::to_pam_segment to take the attribute string. |
| `Proxy::into_owned()` is the zbus 4 API; if the installed minor is 4.0–4.3, the method may differ slightly (`Proxy::clone_into_owned()` in some versions). | Adapt at C2; the lifetime-juggle is local. |
| ctap-hid-fido2 returns `Result<_, String>` from some calls; matching error strings for PinRequired/Cancelled is fragile. | We keyword-match the error string. If the GUI needs structured error codes, Phase 8 can pump back via the `EnrollmentFailed` signal payload — not a Phase 3 change. |
| PAM `pam_get_user` requires conv response on some stacks; for password-prompt stacks it's a pass-through. | We ignore the conv side; the prompt is whatever the next stack module emits. |
---
## Execution Handoff
Plan complete and saved to `docs/plans/2026-04-27-phase-3-6-7-multi-lane.md`. Bundle is **C → B → A** (CLI first, PAM next, FIDO2 last). Each lane's tasks can stand alone if execution is interrupted.
Two execution options:
**1. Subagent-Driven (this session)** — fresh subagent per task, two-stage review. Phase 1 worktree-cwd quirk may resurface; if so, fall back to sequential.
**2. Parallel Session (separate)** — open three new sessions in worktrees, one per lane, using `superpowers:executing-plans`.
For this work cycle, the controller is staying in main and executing Lane C → B → A sequentially with file-tree isolation as the safety mechanism (no two lanes touch the same file).
Reference in New Issue View Git Blame Copy Permalink