feat(vault-api): post-quantum transport feature flag (X25519MLKEM768)

CHANGELOG.md

@@ -10,6 +10,16 @@ range may break in any release.
 
 ### Added
 
+- **Post-quantum transport (`pqc` feature, off by default).** A GPL-clean hybrid
+  **X25519MLKEM768** key-exchange group is added to the rustls client config, so
+  a TLS 1.3 handshake negotiates a post-quantum-secure secret when the server
+  offers it (silent classical fallback otherwise). The classical half reuses
+  ring's X25519; the PQ half is RustCrypto `ml-kem` (Apache-2.0/MIT) — *not*
+  aws-lc-rs, whose OpenSSL-licensed AWS-LC is GPL-incompatible. Build with
+  `cargo build -p vault-agent --features pqc`; see `docs/pqc.md`. Satisfies the
+  PRD §12 M7 "PQC transport feature flag" item (`vault-api/src/pqc.rs`, client
+  role only). Tests cover the ML-KEM client kx round-trip + the hybrid layout.
+
 - **`EncString` parser fuzz harness.** A cargo-fuzz / libFuzzer target
   (`fuzz/fuzz_targets/enc_string_parse.rs`) for the security-critical Bitwarden
   "type 2" parser — feeds arbitrary input to `EncString::parse` and asserts the

README.md

@@ -50,6 +50,10 @@ agent logs to `agent.log` beside the socket.
 The security-critical `EncString` parser has a cargo-fuzz harness under `fuzz/`
 (a standalone workspace, run on nightly) — see [`docs/fuzzing.md`](docs/fuzzing.md).
 
+An optional **post-quantum transport** (`--features pqc`) prefers the hybrid
+X25519MLKEM768 key exchange on the HTTPS client, off by default — see
+[`docs/pqc.md`](docs/pqc.md).
+
 ## Getting started
 
 ```sh

crates/vault-agent/Cargo.toml

@@ -27,6 +27,9 @@ workspace = true
 # returns a clean "not compiled in" error.
 default = ["clipboard"]
 clipboard = ["dep:arboard"]
+# Post-quantum transport (off by default): prefer X25519MLKEM768 on the HTTPS
+# client. Passes through to vault-api; see `docs/pqc.md`.
+pqc = ["vault-api/pqc"]
 
 [dependencies]
 anyhow = { workspace = true }

crates/vault-api/Cargo.toml

@@ -16,6 +16,12 @@ readme.workspace = true
 [lints]
 workspace = true
 
+[features]
+# Off-by-default post-quantum transport. Adds a GPL-clean X25519MLKEM768 hybrid
+# key-exchange group (ring X25519 + RustCrypto ML-KEM-768) to the rustls client
+# config. See `docs/pqc.md`.
+pqc = ["dep:rustls", "dep:ml-kem", "dep:kem", "dep:rand_core", "dep:webpki-roots"]
+
 [dependencies]
 thiserror = { workspace = true }
 serde = { workspace = true }
@@ -28,6 +34,16 @@ time = { workspace = true }
 base64 = { workspace = true }
 vault-core = { path = "../vault-core" }
 
+# PQC transport (feature = "pqc"). Pinned to the versions reqwest already pulls
+# so rustls unifies to one crate instance (required for `use_preconfigured_tls`).
+rustls = { version = "0.23", default-features = false, features = ["ring", "std", "tls12"], optional = true }
+ml-kem = { version = "0.2", optional = true }
+# `kem` provides the Encapsulate/Decapsulate traits ml-kem's keys implement;
+# pinned to the exact pre-release ml-kem 0.2 depends on.
+kem = { version = "=0.3.0-pre.0", optional = true }
+rand_core = { version = "0.6", features = ["getrandom"], optional = true }
+webpki-roots = { version = "1", optional = true }
+
 [dev-dependencies]
 tokio = { workspace = true }
 wiremock = { workspace = true }

crates/vault-api/src/client.rs

@@ -61,10 +61,16 @@ impl BitwardenClient {
     /// Returns [`Error::Transport`] if the underlying `reqwest` client fails to build.
     pub fn new(urls: BaseUrls, device_id: Uuid, device_name: impl Into<String>) -> Result<Self> {
         let user_agent = format!("vault/{} (Spacecraft-Software)", env!("CARGO_PKG_VERSION"));
-        let http = Client::builder()
+        let builder = Client::builder()
             .user_agent(&user_agent)
-            .https_only(urls.api.scheme() == "https")
-            .build()?;
+            .https_only(urls.api.scheme() == "https");
+        // With the `pqc` feature, prefer the X25519MLKEM768 hybrid key exchange
+        // on the TLS layer (falls back to classical when the server lacks it).
+        #[cfg(feature = "pqc")]
+        let builder = builder.use_preconfigured_tls(
+            crate::pqc::client_config().map_err(|e| Error::PqcTls(e.to_string()))?,
+        );
+        let http = builder.build()?;
         Ok(Self {
             http,
             urls,

crates/vault-api/src/error.rs

@@ -39,6 +39,12 @@ pub enum Error {
     /// vault-core surfaced an error (KDF, hashing, etc.) during the API flow.
     #[error("crypto: {0}")]
     Crypto(#[from] vault_core::Error),
+
+    /// The post-quantum transport (feature `pqc`) could not build its rustls
+    /// client config. Not expected in practice (safe defaults are always valid).
+    #[cfg(feature = "pqc")]
+    #[error("pqc tls config: {0}")]
+    PqcTls(String),
 }
 
 /// Convenience `Result` alias used throughout `vault-api`.

crates/vault-api/src/lib.rs

@@ -9,6 +9,8 @@
 pub mod client;
 pub mod error;
 pub mod identity;
+#[cfg(feature = "pqc")]
+pub mod pqc;
 pub mod sync;
 pub mod urls;