Yubico · DennisDyallo · Jan 27, 2026 · Jan 27, 2026 · Jan 27, 2026 · Apr 1, 2026
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -26,10 +26,23 @@ jobs:
         uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
         with:
           path: ~/.nuget/packages
-          key: ${{ runner.os }}-nuget-${{ hashFiles('**/packages.lock.json') }}
+          key: ${{ runner.os }}-nuget-${{ hashFiles('**/Directory.Packages.props') }}
           restore-keys: |
             ${{ runner.os }}-nuget-
 
+      - name: Install PC/SC dependencies
+        run: |
+          sudo apt-get update -qq
+          sudo apt-get install -y --no-install-recommends pcscd libpcsclite-dev libudev-dev
+          # Run pcscd directly (bypasses systemd/socket-activation issues on CI runners)
+          # and open socket permissions so the test runner user can connect
+          sudo mkdir -p /run/pcscd
+          sudo pcscd --foreground &
+          # Wait for socket to appear (more robust than fixed sleep)
+          timeout 10 bash -c 'until [ -S /run/pcscd/pcscd.comm ]; do sleep 0.2; done' || true
+          # Open socket read/write for the runner user (sockets don't need +x)
+          sudo chmod 666 /run/pcscd/pcscd.comm || true
+
       - name: Build
         run: dotnet build.cs build
 

diff --git a/BUILD.md b/BUILD.md
@@ -35,12 +35,12 @@ dotnet build.cs -- build --project Piv --clean
 
 ### Available Targets
 
-- **clean** - Remove artifacts directory (and optionally run `dotnet clean`)
-- **restore** - Restore NuGet dependencies (depends on: clean)
-- **build** - Build the solution (depends on: clean, restore)
-- **test** - Run unit tests with nice summary output (depends on: clean, restore, build)
-- **coverage** - Run tests with code coverage collection (depends on: clean, restore, build)
-- **pack** - Create NuGet packages (depends on: clean, restore, build)
+- **clean** - Remove artifacts directory (and optionally run `dotnet clean`); must be specified explicitly
+- **restore** - Restore NuGet dependencies
+- **build** - Build the solution (depends on: restore)
+- **test** - Run unit tests with nice summary output (depends on: restore, build)
+- **coverage** - Run tests with code coverage collection (depends on: restore, build)
+- **pack** - Create NuGet packages (depends on: restore, build)
 - **setup-feed** - Configure local NuGet feed
 - **publish** - Publish packages to local feed (depends on: pack, setup-feed)
 - **default** - Run tests and publish (depends on: test, publish)
@@ -55,6 +55,8 @@ dotnet build.cs -- build --project Piv --clean
 - `--clean` - Run `dotnet clean` before build
 - `--filter <expression>` - Test filter expression (e.g., `"FullyQualifiedName~MyTest"`)
 - `--project <name>` - Build/test specific project only (partial match, e.g., `Piv`)
+- `--integration` - Include integration tests (requires `--project`)
+- `--smoke` - Smoke test mode: skip `Slow` and `RequiresUserPresence` tests (fast integration runs)
 - `-h, --help` - Show help message (use `dotnet build.cs -- --help`)
 
 ### Examples
@@ -78,17 +80,23 @@ dotnet build.cs test
 # Run tests for specific project with filter
 dotnet build.cs test --project Piv --filter "Method~Sign"
 
-# Run tests with code coverage
+# Run tests with code coverage (xUnit v2 unit test projects only)
 dotnet build.cs coverage
 
+# Run integration tests for a specific module
+dotnet build.cs test --integration --project Piv
+
+# Quick smoke test (skips slow RSA keygen and user-presence tests)
+dotnet build.cs -- test --integration --project Piv --smoke
+
 # Create and publish packages with custom version
 dotnet build.cs publish --package-version 1.0.0-preview.2
 
 # Dry run to see what would be published
 dotnet build.cs publish --dry-run
 
-# Full clean build
-dotnet build.cs build --clean
+# Full clean build (delete artifacts, then build)
+dotnet build.cs clean build
 ```
 
 ## Target Dependencies
@@ -98,11 +106,12 @@ default
 ├── test
 │   └── build
 │       └── restore
-│           └── clean
 └── publish
     ├── pack
     │   └── build (shared)
     └── setup-feed
+
+clean  (standalone — must be specified explicitly)
 ```
 
 ## Output
@@ -125,6 +134,10 @@ The build script automatically discovers projects using glob patterns:
 
 This means you don't need to manually update the build script when adding new projects that follow the standard structure. Run `dotnet build.cs -- --help` to see the current list of discovered projects.
 
+## Code Coverage
+
+The `coverage` target collects coverage via `dotnet test` with the `coverlet` collector. Both xUnit v2 and v3 (MTP) projects are supported via the VSTest compatibility layer. Use `--project` to run coverage for a specific module.
+
 ## xUnit v2 vs v3 Test Runner Detection
 
 **IMPORTANT: Always use `dotnet build.cs test` instead of invoking `dotnet test` directly.**

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -2,7 +2,7 @@
 
 This file provides guidance to AI agents when working with code in this repository.
 
-**IMPORTANT:** If you are working in a subproject directory (e.g., `Yubico.YubiKit.SecurityDomain/`, `Yubico.YubiKit.Piv/`, etc.), you MUST also read that subproject's `CLAUDE.md` file if it exists. Subproject CLAUDE.md files contain specific patterns, test harness details, and context for that module.
+**IMPORTANT:** If you are working in a subproject directory (e.g., `src/SecurityDomain/`, `src/Piv/`, etc.), you MUST also read that subproject's `CLAUDE.md` file if it exists. Subproject CLAUDE.md files contain specific patterns, test harness details, and context for that module.
 
 ## Project Overview
 
@@ -17,24 +17,29 @@ Yubico.NET.SDK (YubiKit) is a .NET SDK for interacting with YubiKey devices. The
 
 The SDK is organized into the following modules:
 
+All project folders live under `src/` with the `Yubico.YubiKit.` prefix stripped from directory names. Assembly names, namespaces, and DLL output names remain unchanged (e.g., `Yubico.YubiKit.Core`).
+
 **Core Infrastructure:**
-- `Yubico.YubiKit.Core/` - Device management, connection abstractions, APDU protocol handling, platform interop
-- `Yubico.YubiKit.Management/` - Device information queries, capability detection, firmware version
+- `src/Core/` - Device management, connection abstractions, APDU protocol handling, platform interop
+- `src/Management/` - Device information queries, capability detection, firmware version
 
 **YubiKey Applications:**
-- `Yubico.YubiKit.Piv/` - PIV (Personal Identity Verification) smart card functionality
-- `Yubico.YubiKit.Fido2/` - FIDO2/WebAuthn authentication
-- `Yubico.YubiKit.Oath/` - TOTP/HOTP one-time password generation
-- `Yubico.YubiKit.YubiOtp/` - Yubico OTP configuration and generation
-- `Yubico.YubiKit.OpenPgp/` - OpenPGP card implementation
-- `Yubico.YubiKit.SecurityDomain/` - Secure Channel Protocol (SCP03), key management
+- `src/Piv/` - PIV (Personal Identity Verification) smart card functionality
+- `src/Fido2/` - FIDO2/WebAuthn authentication
+- `src/Oath/` - TOTP/HOTP one-time password generation
+- `src/YubiOtp/` - Yubico OTP configuration and generation
+- `src/OpenPgp/` - OpenPGP card implementation
+- `src/SecurityDomain/` - Secure Channel Protocol (SCP03), key management
 
 **Hardware Security Modules:**
-- `Yubico.YubiKit.YubiHsm/` - YubiHSM 2 hardware security module integration
+- `src/YubiHsm/` - YubiHSM 2 hardware security module integration
+
+**Shared Infrastructure:**
+- `src/Cli.Shared/` - Shared CLI infrastructure for example tools
 
 **Testing Infrastructure:**
-- `Yubico.YubiKit.Tests.Shared/` - Shared test utilities, multi-transport test harness
-- `Yubico.YubiKit.Tests.TestProject/` - xUnit v3 test project structure
+- `src/Tests.Shared/` - Shared test utilities, multi-transport test harness
+- `src/Tests.TestProject/` - xUnit v3 test project structure
 
 **Module-Specific Documentation:**
 Each module directory may contain:
@@ -177,7 +182,7 @@ dotnet build Yubico.YubiKit.sln
 dotnet test Yubico.YubiKit.sln
 
 # Run specific test project
-dotnet test Yubico.YubiKit.Core/tests/Yubico.YubiKit.Core.UnitTests/Yubico.YubiKit.Core.UnitTests.csproj
+dotnet test src/Core/tests/Yubico.YubiKit.Core.UnitTests/Yubico.YubiKit.Core.UnitTests.csproj
 
 # Run with coverage directly
 dotnet test --settings coverlet.runsettings.xml --collect:"XPlat Code Coverage"
@@ -1141,6 +1146,21 @@ bool isValid = expected.SequenceEqual(actual);
 
 ## Testing
 
+### Integration Test Strategy
+
+**Run only what's affected.** Don't run the full integration suite unless you're finishing a module or touching shared infrastructure.
+
+| Phase | What to run | Command |
+|-------|------------|---------|
+| **During development** | Smoke test on affected module only | `dotnet build.cs -- test --integration --project Piv --smoke` |
+| **Targeted check** | Specific test you touched | `dotnet build.cs -- test --integration --project Oath --filter "FullyQualifiedName~Calculate"` |
+| **Finishing a module** | Full integration for that module | `dotnet build.cs -- test --integration --project Piv` |
+| **Before PR** | Full integration for all affected modules | Run per-module, not all modules |
+
+**`--smoke` skips:** `Slow` tests (RSA 3072/4096 keygen, 30+ sec each) and `RequiresUserPresence` tests (need physical touch).
+
+**Mark slow tests:** Any integration test that generates RSA 3072+ keys or has delays >5s must have `[Trait(TestCategories.Category, TestCategories.Slow)]`.
+
 ### Test Philosophy: Value Over Coverage
 
 **CRITICAL: Only write tests that provide real value. Don't create tests just to increase coverage metrics.**

diff --git a/Directory.Packages.props b/Directory.Packages.props
@@ -21,7 +21,7 @@
     <!-- Third-party Dependencies -->
     <PackageVersion Include="System.Formats.Cbor" Version="10.0.2" />
     <PackageVersion Include="System.Reactive" Version="6.0.1" />
-    <PackageVersion Include="Yubico.NativeShims" Version="1.14.0" />
+    <PackageVersion Include="Yubico.NativeShims" Version="1.16.0" />
     <!-- Test Dependencies -->
     <PackageVersion Include="xunit" Version="2.9.3" />
     <PackageVersion Include="xunit.v3" Version="3.0.0" />
@@ -37,6 +37,7 @@
     <PackageVersion Include="Xunit.SkippableFact" Version="1.5.23" />
     <!-- CLI / Console Tools -->
     <PackageVersion Include="Spectre.Console" Version="0.49.1" />
+    <PackageVersion Include="Spectre.Console.Cli" Version="0.49.1" />
     <!-- Build Tools -->
     <PackageVersion Include="Microsoft.SourceLink.GitHub" Version="8.0.0" />
     <PackageVersion Include="Microsoft.CodeAnalysis.NetAnalyzers" Version="9.0.0" />

diff --git a/Plans/cli-shared-infrastructure.md b/Plans/cli-shared-infrastructure.md
@@ -0,0 +1,119 @@
+# CLI Shared Infrastructure Extraction — Plan (#12)
+
+**Status:** Review complete, ready for implementation  
+**Branch:** `yubikit-applets` (future work)  
+**Created:** 2026-04-02  
+
+---
+
+## Problem
+
+All 5 CLIs (ManagementTool, OathTool, FidoTool, OpenPgpTool, HsmAuthTool) share ~2600 LOC of duplicated patterns. No shared project exists — each CLI copy-pastes device selection, output formatting, argument parsing, and lifecycle management.
+
+## Proposed Solution
+
+New project: `Yubico.YubiKit.Cli.Shared`
+
+```
+Yubico.YubiKit.Cli.Shared/
+├── src/
+│   ├── Device/
+│   │   ├── DeviceSelection.cs          (shared record)
+│   │   ├── DeviceSelectorBase.cs       (abstract base, ~200 LOC)
+│   │   ├── FormFactorFormatter.cs
+│   │   └── ConnectionTypeFormatter.cs
+│   ├── Output/
+│   │   ├── OutputHelpers.cs            (Spectre.Console variant)
+│   │   ├── PlainTextOutputHelpers.cs   (pipe-friendly alternative)
+│   │   ├── ConfirmationPrompts.cs
+│   │   └── PinPrompt.cs
+│   ├── Cli/
+│   │   ├── ArgumentParser.cs
+│   │   ├── CommandHelper.cs            (YubiKeyManager lifecycle + CTS)
+│   │   └── InteractiveMenuBuilder.cs
+│   └── Yubico.YubiKit.Cli.Shared.csproj
+```
+
+---
+
+## Shared Patterns Found (5/5 CLIs)
+
+### 1. Device Selection (~1000 LOC duplicated)
+- `DeviceSelection` record — identical across all 5
+- `FindDevicesWithRetryAsync` — same retry loop
+- `PromptForDeviceSelectionAsync` — identical interactive prompt
+- `FormatFormFactor` / `FormatConnectionType` — identical switch statements
+- **Variation:** Connection type filtering differs per CLI (SmartCard-only vs HidFido+SmartCard)
+
+### 2. Output Helpers (~850 LOC duplicated)
+- `WriteSuccess`, `WriteError`, `WriteWarning`, `WriteInfo` — identical
+- `WriteKeyValue`, `WriteHex`, `WriteBoolValue` — identical
+- `ConfirmDangerous`, `ConfirmDestructive` — identical
+- `CreateTable` — 4/5 CLIs identical
+- **Variation:** OathTool uses plain text (no Spectre.Console)
+
+### 3. Argument Parser (~100 LOC, 3 CLIs)
+- `HasFlag`, `GetArgValue`, `GetPositionalArgs` — identical logic
+
+### 4. YubiKeyManager Lifecycle (~50 LOC, 5 CLIs)
+- `StartMonitoring()` + `ShutdownAsync()` wrapper
+- CancellationTokenSource + Console.CancelKeyPress boilerplate
+
+---
+
+## Extraction Phases
+
+### Phase 1: Foundation (2-3 hours, Risk: Very Low)
+1. `DeviceSelection` record
+2. `ArgumentParser` (HasFlag, GetArgValue, GetPositionalArgs)
+3. `FormFactorFormatter` + `ConnectionTypeFormatter`
+4. `ConfirmationPrompts` (ConfirmDangerous, ConfirmDestructive)
+
+**Impact:** ~250 LOC saved, zero risk
+
+### Phase 2: UI/Output Layer (3-4 hours, Risk: Low)
+5. `OutputHelpers` (core methods — WriteSuccess/Error/Warning/Info/KeyValue/Hex)
+6. `PinPrompt` helpers
+7. `CommandHelper` (YubiKeyManager lifecycle + CTS setup)
+
+**Impact:** ~350 LOC saved, minimal risk
+
+### Phase 3: Device Selection (4-6 hours, Risk: Medium)
+8. `DeviceSelectorBase` abstract class
+9. 5 CLI-specific subclasses (filtering by connection type)
+
+**Impact:** ~1000 LOC saved, requires testing
+
+### Phase 4: Optional
+10. `InteractiveMenuBuilder` (builder pattern for Spectre.Console menus)
+11. Generic `SessionHelper<TSession>` (device+session creation pattern)
+
+---
+
+## Inconsistencies to Normalize First
+
+| Issue | CLIs Affected | Fix |
+|-------|--------------|-----|
+| OpenPgpTool uses `v` instead of `✓` for success | OpenPgpTool | Use U+2713 |
+| OathTool lacks CancellationToken in entry points | OathTool | Add CTS pattern |
+| Non-interactive auto-select varies (some prompt, some auto) | All | Virtual property on base |
+| Exception handling: some continue, some exit | All | Standardize per-mode |
+| Menu item styling: emoji vs plain text | 3 CLIs | Choose consistent style |
+
+---
+
+## Estimates
+
+| Metric | Value |
+|--------|-------|
+| Total duplicated LOC | ~2,600 |
+| Expected savings | ~2,200 (84%) |
+| Total effort | 9-13 hours (phased) |
+| Risk | Low (Phase 1-2), Medium (Phase 3) |
+
+---
+
+## Decision Log
+
+- 2026-04-02: DevTeam review completed. All patterns documented. Deferred to future sprint.
+- 2026-04-02: Phases 1-3 implemented and committed (`32733e32`). Phase 4 (InteractiveMenuBuilder, SessionHelper) deferred — optional per plan. PlainTextOutputHelpers not created; OathTool retains custom plain-text output by design. Reviewer fixes applied: non-interactive guard, Logger.LogDebug, PromptForTouch rename.