feat: add composite YubikeyDevice (v2)

.editorconfig

@@ -129,7 +129,10 @@ csharp_style_prefer_readonly_struct = true
 csharp_style_prefer_readonly_struct_member = true
 
 # Code-block preferences
-csharp_prefer_braces = false:when_multiline
+csharp_prefer_braces = when_multiline:none
+csharp_style_prefer_conditional_expression_over_return = true:suggestion
+dotnet_diagnostic.IDE0046.severity = suggestion
+dotnet_diagnostic.IDE0072.severity = suggestion
 csharp_prefer_simple_using_statement = true
 csharp_style_namespace_declarations = file_scoped
 csharp_style_prefer_method_group_conversion = true

.github/workflows/build.yml

@@ -2,9 +2,9 @@ name: Build and Test (2.0)
 
 on:
   push:
-    branches: [ yubikit, yubikit-applets ]
+    branches: [ yubikit*, yubikit/** ]
   pull_request:
-    branches: [ yubikit, yubikit-applets ]
+    branches: [ yubikit*, yubikit/** ]
 
 jobs:
   build-and-test:
@@ -55,6 +55,9 @@ jobs:
       - name: Run unit tests
         run: dotnet toolchain.cs test
 
+      - name: Run runtime resilience checks
+        run: dotnet toolchain.cs -- resilience --fast
+
       - name: Pack NuGet packages
         run: dotnet toolchain.cs pack --package-version 2.0.0-preview.${{ github.run_number }}
 

AGENTS.md

@@ -10,6 +10,7 @@
 - Do not run `dotnet build` directly. Use `dotnet toolchain.cs build` or `dotnet toolchain.cs build --project Piv`.
 - Do not run `dotnet test` directly. Unit tests mix xUnit v3/Microsoft Testing Platform and xUnit v2; `dotnet toolchain.cs test` detects and invokes the right runner.
 - Focus tests with both module and filter when possible: `dotnet toolchain.cs test --project Fido2 --filter "Method~Sign"`.
+- When touching Core runtime loops, polling paths, recovery logic, or listener lifecycle cleanup, also run `dotnet toolchain.cs -- resilience --fast`.
 - `--integration` requires `--project`: `dotnet toolchain.cs -- test --integration --project Piv --smoke`.
 - `--smoke` skips `Slow` and `RequiresUserPresence`; agents should not run touch/insert/remove tests unless a human explicitly coordinates hardware.
 - Use `dotnet toolchain.cs -- --help` when arguments act strangely; `--help` and some options need the `--` separator.
@@ -30,6 +31,7 @@
 - Platform interop belongs under `src/Core/src/PlatformInterop/{Windows,MacOS,Linux,Desktop}` with safe handles and `SdkPlatformInfo` platform selection.
 - FIDO2 over USB primarily uses HID FIDO. SmartCard/CCID FIDO2 is supported over NFC and over USB when the FIDO2 AID is exposed; USB SmartCard FIDO2 requires firmware 5.8.0+.
 - `TlvBuilder` and `DisposableTlvList` must be disposed.
+- Listener/native retry loops must block, back off, exit, or throttle on every failure path; add no-hardware fault-injection tests for persistent native errors.
 
 ## Hardware And Integration Tests
 - Integration tests require authorized YubiKey hardware. The shared test infrastructure reads `YubiKeyTests:AllowedSerialNumbers` from `appsettings.json`; an empty/missing allow list can hard-fail with `Environment.Exit(-1)`, and unauthorized devices are filtered out.
@@ -43,6 +45,7 @@
 - Async byte data crossing awaits should use `Memory<byte>`, `ReadOnlyMemory<byte>`, or `IMemoryOwner<byte>`, not `Span<byte>`.
 - Avoid `.ToArray()` and LINQ on byte data unless data must escape the current scope.
 - Always zero PINs, PUKs, keys, SCP material, and secret-derived buffers with `CryptographicOperations.ZeroMemory()`.
+- Classify YubiKey-returned data by semantics: device metadata/status does not need special zeroing; authentication material, token material, decrypted plaintext, and secret-derived output does.
 - Use `CryptographicOperations.FixedTimeEquals` for secret-derived comparisons; do not use `SequenceEqual` on secrets.
 - Never store a privately cloned sensitive `byte[]` in a struct; struct copies keep references you cannot reliably zero. Use a sealed disposable class for owned sensitive buffers.
 - Logging is static via `YubiKitLogging.CreateLogger<T>()`; do not add SDK constructors that require `ILogger`/`ILoggerFactory`.
@@ -52,6 +55,7 @@
 - Do not add validation-only tests that just prove `ArgumentNullException.ThrowIfNull` or framework type checks work.
 - Do not add skipped placeholder tests. If behavior cannot be unit-tested, document the limitation and point to an integration path.
 - Use fake connections, queued APDU responses, and byte/vector assertions for protocol behavior; use integration tests only for real hardware behavior.
+- Runtime resilience tests should use fakes/seams and must not self-skip because PC/SC, HID, or YubiKey hardware is unavailable.
 
 ## Git And Release Notes
 - The workflow file currently triggers on `yubikit` and `yubikit-applets`; verify the active plan/branch before assuming a PR base.

CLAUDE.md

@@ -56,6 +56,7 @@ These are the always-loaded mandates. Each section ends with a JIT pointer to de
 
 **Security:**
 - ✅ ALWAYS zero sensitive data: `CryptographicOperations.ZeroMemory()`
+- ✅ Classify byte data by semantic meaning, not by direction. YubiKey-returned device metadata/status (device info TLVs, firmware version, capabilities, form factor, public status) does not require special zeroing beyond normal ownership/disposal. YubiKey-returned authentication material, token material, decrypted plaintext, or secret-derived output does.
 - ✅ ALWAYS dispose crypto objects: `using var aes = Aes.Create()`
 - ✅ ALWAYS use `CryptographicOperations.FixedTimeEquals` for secret-derived comparisons
 - ❌ NEVER log PINs, keys, or sensitive payloads

Directory.Packages.props

@@ -39,9 +39,10 @@
     <PackageVersion Include="Spectre.Console" Version="0.49.1" />
     <PackageVersion Include="Spectre.Console.Cli" Version="0.49.1" />
     <!-- Build Tools -->
+    <PackageVersion Include="BenchmarkDotNet" Version="0.15.8" />
     <PackageVersion Include="Microsoft.SourceLink.GitHub" Version="8.0.0" />
     <PackageVersion Include="Microsoft.CodeAnalysis.NetAnalyzers" Version="9.0.0" />
     <PackageVersion Include="Bullseye" Version="5.0.0" />
     <PackageVersion Include="SimpleExec" Version="12.0.0" />
   </ItemGroup>
-</Project>
+</Project>

benchmarks/Yubico.YubiKit.PerformanceBenchmarks/Program.cs

@@ -0,0 +1,241 @@
+using BenchmarkDotNet.Attributes;
+using BenchmarkDotNet.Columns;
+using BenchmarkDotNet.Configs;
+using BenchmarkDotNet.Diagnosers;
+using BenchmarkDotNet.Environments;
+using BenchmarkDotNet.Exporters;
+using BenchmarkDotNet.Exporters.Csv;
+using BenchmarkDotNet.Exporters.Json;
+using BenchmarkDotNet.Jobs;
+using BenchmarkDotNet.Reports;
+using BenchmarkDotNet.Running;
+using BenchmarkDotNet.Validators;
+using Yubico.YubiKit.Core.Abstractions;
+using Yubico.YubiKit.Core.Devices;
+using Yubico.YubiKit.Core.Protocols.Fido.Hid;
+using Yubico.YubiKit.Core.Protocols.SmartCard.Apdu;
+using Yubico.YubiKit.Core.Sessions;
+using Yubico.YubiKit.Core.Transports.Hid;
+using Yubico.YubiKit.Core.Transports.SmartCard;
+using Yubico.YubiKit.Management;
+
+var config = YubiKitBenchmarkConfig.Create();
+BenchmarkSwitcher.FromAssembly(typeof(Program).Assembly).Run(args, config);
+
+internal sealed class YubiKitBenchmarkConfig : ManualConfig
+{
+    private YubiKitBenchmarkConfig()
+    {
+        var runId = DateTimeOffset.UtcNow.ToString("yyyyMMdd-HHmmss");
+        ArtifactsPath = Path.Combine(FindRepoRoot(), "artifacts", "benchmarks", runId);
+
+        AddJob(Job.ShortRun
+            .WithRuntime(CoreRuntime.Core10_0)
+            .WithId("net10-short"));
+
+        AddColumnProvider(DefaultColumnProviders.Instance);
+        AddDiagnoser(MemoryDiagnoser.Default);
+        AddDiagnoser(ThreadingDiagnoser.Default);
+        AddDiagnoser(ExceptionDiagnoser.Default);
+        AddDiagnoser(new EventPipeProfiler(EventPipeProfile.CpuSampling));
+        AddExporter(MarkdownExporter.GitHub);
+        AddExporter(HtmlExporter.Default);
+        AddExporter(CsvExporter.Default);
+        AddExporter(CsvMeasurementsExporter.Default);
+        AddExporter(JsonExporter.Full);
+        AddExporter(RPlotExporter.Default);
+        AddValidator(JitOptimizationsValidator.FailOnError);
+        AddLogger(DefaultConfig.Instance.GetLoggers().ToArray());
+    }
+
+    public static IConfig Create() => new YubiKitBenchmarkConfig();
+
+    private static string FindRepoRoot()
+    {
+        var current = AppContext.BaseDirectory;
+        while (!string.IsNullOrEmpty(current))
+        {
+            if (Directory.Exists(Path.Combine(current, ".git")))
+                return current;
+
+            current = Directory.GetParent(current)?.FullName;
+        }
+
+        return Directory.GetCurrentDirectory();
+    }
+}
+
+public abstract class YubiKeyHardwareBenchmarkBase
+{
+    protected IYubiKey Device { get; private set; } = null!;
+
+    protected void SetupDevice(ConnectionType requiredConnection)
+    {
+        Device = FindDevice(requiredConnection).GetAwaiter().GetResult();
+    }
+
+    [GlobalCleanup]
+    public void Cleanup() => YubiKeyManager.Shutdown();
+
+    private static async Task<IYubiKey> FindDevice(ConnectionType requiredConnection)
+    {
+        var devices = await YubiKeyManager.FindAllAsync(ConnectionType.All, forceRescan: true)
+            .ConfigureAwait(false);
+
+        return devices.FirstOrDefault(device => device.SupportsConnection(requiredConnection))
+            ?? throw new InvalidOperationException(
+                $"No connected YubiKey exposes {requiredConnection}. Connect the YubiKey 5.8 device before running benchmarks.");
+    }
+}
+
+[MemoryDiagnoser]
+[ThreadingDiagnoser]
+[ExceptionDiagnoser]
+public class YubiKeyDiscoveryBenchmarks
+{
+    [GlobalSetup]
+    public void Setup()
+    {
+        _ = YubiKeyManager.FindAllAsync(ConnectionType.All, forceRescan: true)
+            .GetAwaiter()
+            .GetResult();
+    }
+
+    [GlobalCleanup]
+    public void Cleanup() => YubiKeyManager.Shutdown();
+
+    [Benchmark(Baseline = true)]
+    public async Task<int> CachedFindAll()
+    {
+        var devices = await YubiKeyManager.FindAllAsync(ConnectionType.All, forceRescan: false)
+            .ConfigureAwait(false);
+        return devices.Count;
+    }
+
+    [Benchmark]
+    public async Task<int> ForcedRescanFindAll()
+    {
+        var devices = await YubiKeyManager.FindAllAsync(ConnectionType.All, forceRescan: true)
+            .ConfigureAwait(false);
+        return devices.Count;
+    }
+
+    [Benchmark]
+    public async Task<int> ColdFindAll()
+    {
+        await YubiKeyManager.ShutdownAsync().ConfigureAwait(false);
+        var devices = await YubiKeyManager.FindAllAsync(ConnectionType.All, forceRescan: false)
+            .ConfigureAwait(false);
+        return devices.Count;
+    }
+}
+
+[MemoryDiagnoser]
+[ThreadingDiagnoser]
+[ExceptionDiagnoser]
+public class SmartCardManagementBenchmarks : YubiKeyHardwareBenchmarkBase
+{
+    [GlobalSetup]
+    public void Setup() => SetupDevice(ConnectionType.SmartCard);
+
+    [Benchmark(Baseline = true)]
+    public async Task<bool> ConnectSmartCard()
+    {
+        await using var connection = await Device.ConnectAsync<ISmartCardConnection>().ConfigureAwait(false);
+        return connection.SupportsExtendedApdu();
+    }
+
+    [Benchmark]
+    public async Task<int> SelectManagementOverSmartCard()
+    {
+        var connection = await Device.ConnectAsync<ISmartCardConnection>().ConfigureAwait(false);
+        using var protocol = PcscProtocolFactory<ISmartCardConnection>.Create().Create(connection);
+        var response = await protocol.SelectAsync(ApplicationIds.Management).ConfigureAwait(false);
+        return response.Length;
+    }
+
+    [Benchmark]
+    public async Task<int> GetDeviceInfoOverSmartCard()
+    {
+        await using var session = await Device.CreateManagementSessionAsync(
+                preferredConnection: ConnectionType.SmartCard)
+            .ConfigureAwait(false);
+
+        var info = await session.GetDeviceInfoAsync().ConfigureAwait(false);
+        return info.SerialNumber ?? 0;
+    }
+}
+
+[MemoryDiagnoser]
+[ThreadingDiagnoser]
+[ExceptionDiagnoser]
+public class FidoHidManagementBenchmarks : YubiKeyHardwareBenchmarkBase
+{
+    [GlobalSetup]
+    public void Setup() => SetupDevice(ConnectionType.HidFido);
+
+    [Benchmark(Baseline = true)]
+    public async Task<int> ConnectFidoHid()
+    {
+        await using var connection = await Device.ConnectAsync<IFidoHidConnection>().ConfigureAwait(false);
+        return connection.PacketSize;
+    }
+
+    [Benchmark]
+    public async Task<int> CreateManagementSessionOverFidoHid()
+    {
+        await using var session = await Device.CreateManagementSessionAsync(
+                preferredConnection: ConnectionType.HidFido)
+            .ConfigureAwait(false);
+
+        return session.FirmwareVersion.Major;
+    }
+
+    [Benchmark]
+    public async Task<int> GetDeviceInfoOverFidoHid()
+    {
+        await using var session = await Device.CreateManagementSessionAsync(
+                preferredConnection: ConnectionType.HidFido)
+            .ConfigureAwait(false);
+
+        var info = await session.GetDeviceInfoAsync().ConfigureAwait(false);
+        return info.SerialNumber ?? 0;
+    }
+}
+
+[MemoryDiagnoser]
+[ThreadingDiagnoser]
+[ExceptionDiagnoser]
+public class OtpHidManagementBenchmarks : YubiKeyHardwareBenchmarkBase
+{
+    [GlobalSetup]
+    public void Setup() => SetupDevice(ConnectionType.HidOtp);
+
+    [Benchmark(Baseline = true)]
+    public async Task<int> ConnectOtpHid()
+    {
+        await using var connection = await Device.ConnectAsync<IOtpHidConnection>().ConfigureAwait(false);
+        return connection.FeatureReportSize;
+    }
+
+    [Benchmark]
+    public async Task<int> CreateManagementSessionOverOtpHid()
+    {
+        await using var session = await Device.CreateManagementSessionAsync(
+                preferredConnection: ConnectionType.HidOtp)
+            .ConfigureAwait(false);
+
+        return session.FirmwareVersion.Major;
+    }
+
+    [Benchmark]
+    public async Task<int> GetDeviceInfoOverOtpHid()
+    {
+        await using var session = await Device.CreateManagementSessionAsync(
+                preferredConnection: ConnectionType.HidOtp)
+            .ConfigureAwait(false);
+
+        var info = await session.GetDeviceInfoAsync().ConfigureAwait(false);
+        return info.SerialNumber ?? 0;
+    }
+}

benchmarks/Yubico.YubiKit.PerformanceBenchmarks/Yubico.YubiKit.PerformanceBenchmarks.csproj

@@ -0,0 +1,23 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net10.0</TargetFramework>
+    <RootNamespace>Yubico.YubiKit.PerformanceBenchmarks</RootNamespace>
+    <AssemblyName>Yubico.YubiKit.PerformanceBenchmarks</AssemblyName>
+    <IsPackable>false</IsPackable>
+    <PlatformTarget>AnyCPU</PlatformTarget>
+    <DebugType>pdbonly</DebugType>
+    <DebugSymbols>true</DebugSymbols>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="BenchmarkDotNet" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="../../src/Core/src/Yubico.YubiKit.Core.csproj" />
+    <ProjectReference Include="../../src/Management/src/Yubico.YubiKit.Management.csproj" />
+  </ItemGroup>
+
+</Project>

docs/FIDO2-INTEGRATION-TEST-PROGRESS.md

@@ -10,7 +10,7 @@ Successfully debugged and fixed the FIDO2 integration tests. All 42 tests now pa
 ## Fixes Applied
 
 ### 1. Linux HID Report ID Bug
-**File:** `Yubico.YubiKit.Core/src/Hid/Linux/LinuxHidIOReportConnection.cs`
+**File:** `Yubico.YubiKit.Core/src/Transports/Hid/Linux/LinuxHidIOReportConnection.cs`
 
 **Problem:** Linux hidraw requires prepending a report ID byte (0x00) on writes, but the code was writing the 64-byte packet directly.
 
@@ -91,7 +91,7 @@ data.CopyTo(writeBuffer[1..]);
 
 ## Files Modified
 
-1. `Yubico.YubiKit.Core/src/Hid/Linux/LinuxHidIOReportConnection.cs` - HID report ID fix
+1. `Yubico.YubiKit.Core/src/Transports/Hid/Linux/LinuxHidIOReportConnection.cs` - HID report ID fix
 2. `Yubico.YubiKit.Fido2/src/Pin/PinUvAuthProtocolV2.cs` - Token length fix
 3. `Yubico.YubiKit.Fido2/src/Pin/PinUvAuthProtocolV1.cs` - Token length fix
 4. `Yubico.YubiKit.Fido2/src/Credentials/PublicKeyCredentialTypes.cs` - Optional user fields

docs/LOGGING.md

@@ -142,10 +142,10 @@ YubiKit uses the following log categories (class names):
 
 | Category | Description |
 |----------|-------------|
-| `Yubico.YubiKit.Core.DeviceMonitorService` | Device arrival/removal events |
-| `Yubico.YubiKit.Core.DeviceListenerService` | Background device cache updates |
-| `Yubico.YubiKit.Core.DeviceRepositoryCached` | Device cache operations |
-| `Yubico.YubiKit.Core.SmartCard.*` | Smart card/PCSC operations |
+| `Yubico.YubiKit.Core.Devices.*` | Device discovery, metadata, and cache operations |
+| `Yubico.YubiKit.Core.Transports.SmartCard.*` | Smart card/PC/SC transport operations |
+| `Yubico.YubiKit.Core.Protocols.SmartCard.*` | APDU and SCP protocol operations |
+| `Yubico.YubiKit.Core.Transports.Hid.*` | HID device and transport operations |
 | `Yubico.YubiKit.Management.ManagementSession` | Management application commands |
 | `Yubico.YubiKit.Piv.PivSession` | PIV application commands |
 | `Yubico.YubiKit.Fido2.Fido2Session` | FIDO2 application commands |