Add durable credential registry and secret lifecycle

crates/remora-credentials/src/authz.rs

@@ -0,0 +1,28 @@
+use remora_domain::OpaqueId;
+
+use crate::error::CredentialError;
+use crate::types::SourceCredential;
+
+/// Caller identity for credential registry authorization.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct CredentialCaller {
+    pub principal_id: OpaqueId,
+    pub administrator: bool,
+}
+
+/// Owner or administrator may manage a credential; peers see NotFound.
+#[must_use]
+pub fn may_manage(caller: &CredentialCaller, owner: &OpaqueId) -> bool {
+    caller.administrator || caller.principal_id == *owner
+}
+
+/// Map missing and unauthorized credentials to the same NotFound outcome.
+pub fn require_manage(
+    caller: &CredentialCaller,
+    credential: Option<&SourceCredential>,
+) -> Result<SourceCredential, CredentialError> {
+    match credential {
+        Some(record) if may_manage(caller, &record.owner) => Ok(record.clone()),
+        Some(_) | None => Err(CredentialError::NotFound),
+    }
+}

crates/remora-credentials/src/error.rs

@@ -0,0 +1,40 @@
+use remora_domain::IdError;
+use remora_durable::DurableError;
+
+#[derive(Debug, thiserror::Error)]
+pub enum CredentialError {
+    #[error("credential not found")]
+    NotFound,
+    #[error("credential is revoked")]
+    Revoked,
+    #[error("credential has no pinable version")]
+    NoActiveVersion,
+    #[error("invalid credential input: {0}")]
+    InvalidInput(String),
+    #[error("credential material does not match stored kind")]
+    KindMismatch,
+    #[error("execution grant is not active")]
+    GrantInactive,
+    #[error("credential version is not resolvable")]
+    Unresolvable,
+    #[error("secret store unavailable")]
+    SecretStoreUnavailable,
+    #[error("configuration error: {0}")]
+    Config(String),
+    #[error(transparent)]
+    Durable(#[from] DurableError),
+}
+
+impl From<IdError> for CredentialError {
+    fn from(_: IdError) -> Self {
+        Self::InvalidInput("invalid opaque identifier".into())
+    }
+}
+
+impl CredentialError {
+    /// Errors never embed secret material; this helper keeps that invariant explicit.
+    #[must_use]
+    pub fn is_safe_for_logs(&self) -> bool {
+        true
+    }
+}

crates/remora-credentials/src/ids.rs

@@ -0,0 +1,30 @@
+use remora_domain::OpaqueId;
+
+use crate::error::CredentialError;
+
+pub fn new_credential_id() -> Result<OpaqueId, CredentialError> {
+    new_id('c')
+}
+
+pub fn new_version_id() -> Result<OpaqueId, CredentialError> {
+    new_id('v')
+}
+
+pub fn new_intent_id() -> Result<OpaqueId, CredentialError> {
+    new_id('i')
+}
+
+fn new_id(prefix: char) -> Result<OpaqueId, CredentialError> {
+    let mut bytes = [0u8; 16];
+    getrandom::fill(&mut bytes).map_err(|error| {
+        CredentialError::Config(format!("failed to draw opaque identifier entropy: {error}"))
+    })?;
+    let mut hex = String::with_capacity(32);
+    for byte in bytes {
+        hex.push(char::from(HEX[(byte >> 4) as usize]));
+        hex.push(char::from(HEX[(byte & 0x0f) as usize]));
+    }
+    OpaqueId::parse(format!("{prefix}{hex}")).map_err(Into::into)
+}
+
+const HEX: &[u8; 16] = b"0123456789abcdef";

crates/remora-credentials/src/lib.rs

@@ -0,0 +1,29 @@
+//! Source credential registry and grant-bound secret resolution.
+//!
+//! Durable metadata and authorization state live in PostgreSQL. Secret material
+//! is stored in Vault KV v2 behind server-allocated paths and immutable versions.
+//! Submission pins the current authorized version into an execution grant; the
+//! trusted resolver accepts only an ActiveCredentialGrant capability formed
+//! after durable grant activity is verified.
+
+mod authz;
+mod error;
+mod ids;
+mod migrate;
+mod registry;
+mod resolve;
+mod types;
+mod vault;
+
+pub use authz::{CredentialCaller, may_manage, require_manage};
+pub use error::CredentialError;
+pub use migrate::{migrate, migrator};
+pub use registry::CredentialRegistry;
+pub use resolve::GrantBoundResolver;
+pub use types::{
+    CreateCredential, CredentialGrantVersion, SecretMaterial, SourceCredential,
+    SourceCredentialKind, SourceCredentialPage, SourceCredentialStatus, SourceCredentialVersion,
+};
+pub use vault::{LiveVaultVersion, VaultClient, VaultConfig, split_vault_path};
+
+pub use remora_domain::ports::ActiveCredentialGrant;

crates/remora-credentials/src/migrate.rs

@@ -0,0 +1,19 @@
+use remora_durable::DurableError;
+use sqlx::PgPool;
+
+/// Separate migration history from the DurableStore substrate so feature-package
+/// versions do not collide with `remora-durable` in `_sqlx_migrations`.
+const MIGRATION_TABLE: &str = "_remora_credentials_migrations";
+
+pub async fn migrate(pool: &PgPool) -> Result<(), DurableError> {
+    let mut migrator = sqlx::migrate!("./migrations");
+    migrator.dangerous_set_table_name(MIGRATION_TABLE);
+    migrator.run(pool).await?;
+    Ok(())
+}
+
+pub fn migrator() -> sqlx::migrate::Migrator {
+    let mut migrator = sqlx::migrate!("./migrations");
+    migrator.dangerous_set_table_name(MIGRATION_TABLE);
+    migrator
+}

crates/remora-credentials/src/resolve.rs

@@ -0,0 +1,62 @@
+use remora_domain::ports::{ActiveCredentialGrant, CredentialResolver};
+
+use crate::error::CredentialError;
+use crate::registry::CredentialRegistry;
+use crate::types::SecretMaterial;
+use crate::vault::VaultClient;
+
+/// Grant-bound credential resolver.
+///
+/// Every resolve reloads durable execution-grant pin state. Unknown, revoked,
+/// or destroyed pins fail closed. Callers cannot resolve by forging bare
+/// credential/version IDs.
+#[derive(Clone, Debug)]
+pub struct GrantBoundResolver {
+    registry: CredentialRegistry,
+    vault: VaultClient,
+}
+
+impl GrantBoundResolver {
+    #[must_use]
+    pub fn new(registry: CredentialRegistry, vault: VaultClient) -> Self {
+        Self { registry, vault }
+    }
+
+    pub async fn resolve_access(
+        &self,
+        access: &ActiveCredentialGrant,
+    ) -> Result<SecretMaterial, CredentialError> {
+        let pin = self
+            .registry
+            .load_active_grant_pin(access.grant_id())
+            .await?
+            .ok_or(CredentialError::GrantInactive)?;
+        let coord = self
+            .registry
+            .load_version_coord(&pin.credential_id, &pin.version_id)
+            .await?
+            .ok_or(CredentialError::Unresolvable)?;
+        if coord.destroyed {
+            return Err(CredentialError::Unresolvable);
+        }
+        self.vault
+            .get_version(
+                &coord.secret_mount,
+                &coord.secret_path,
+                coord.vault_kv_version,
+            )
+            .await
+    }
+}
+
+impl CredentialResolver for GrantBoundResolver {
+    type Error = CredentialError;
+    type Secret = SecretMaterial;
+
+    fn resolve(
+        &self,
+        access: &ActiveCredentialGrant,
+    ) -> impl std::future::Future<Output = Result<Self::Secret, Self::Error>> + Send {
+        self.resolve_access(access)
+    }
+}

crates/remora-credentials/src/types.rs

@@ -0,0 +1,263 @@
+use std::collections::BTreeMap;
+use std::fmt;
+
+use remora_domain::OpaqueId;
+use serde::{Deserialize, Serialize};
+use time::OffsetDateTime;
+
+#[derive(Clone, Copy, Debug, Deserialize, Eq, Hash, PartialEq, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum SourceCredentialKind {
+    BasicAuth,
+    BearerToken,
+    HttpHeaders,
+    ObjectStore,
+    HuggingFace,
+}
+
+impl SourceCredentialKind {
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::BasicAuth => "basic_auth",
+            Self::BearerToken => "bearer_token",
+            Self::HttpHeaders => "http_headers",
+            Self::ObjectStore => "object_store",
+            Self::HuggingFace => "hugging_face",
+        }
+    }
+
+    pub fn parse(value: &str) -> Result<Self, super::error::CredentialError> {
+        match value {
+            "basic_auth" => Ok(Self::BasicAuth),
+            "bearer_token" => Ok(Self::BearerToken),
+            "http_headers" => Ok(Self::HttpHeaders),
+            "object_store" => Ok(Self::ObjectStore),
+            "hugging_face" => Ok(Self::HuggingFace),
+            other => Err(super::error::CredentialError::InvalidInput(format!(
+                "unknown credential kind '{other}'"
+            ))),
+        }
+    }
+}
+
+#[derive(Clone, Copy, Debug, Deserialize, Eq, Hash, PartialEq, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum SourceCredentialStatus {
+    Active,
+    Revoked,
+}
+
+impl SourceCredentialStatus {
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Active => "active",
+            Self::Revoked => "revoked",
+        }
+    }
+
+    pub fn parse(value: &str) -> Result<Self, super::error::CredentialError> {
+        match value {
+            "active" => Ok(Self::Active),
+            "revoked" => Ok(Self::Revoked),
+            other => Err(super::error::CredentialError::InvalidInput(format!(
+                "unknown credential status '{other}'"
+            ))),
+        }
+    }
+}
+
+/// Write-only secret material. Debug and Display never include values.
+#[derive(Clone, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(tag = "kind", rename_all = "snake_case")]
+pub enum SecretMaterial {
+    BasicAuth {
+        username: String,
+        password: String,
+    },
+    BearerToken {
+        token: String,
+    },
+    HttpHeaders {
+        headers: BTreeMap<String, String>,
+    },
+    ObjectStore {
+        access_key_id: String,
+        secret_access_key: String,
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        session_token: Option<String>,
+    },
+    HuggingFace {
+        token: String,
+    },
+}
+
+impl SecretMaterial {
+    #[must_use]
+    pub fn kind(&self) -> SourceCredentialKind {
+        match self {
+            Self::BasicAuth { .. } => SourceCredentialKind::BasicAuth,
+            Self::BearerToken { .. } => SourceCredentialKind::BearerToken,
+            Self::HttpHeaders { .. } => SourceCredentialKind::HttpHeaders,
+            Self::ObjectStore { .. } => SourceCredentialKind::ObjectStore,
+            Self::HuggingFace { .. } => SourceCredentialKind::HuggingFace,
+        }
+    }
+
+    pub fn validate(&self) -> Result<(), super::error::CredentialError> {
+        match self {
+            Self::BasicAuth { username, password } => {
+                require_nonempty("username", username, 1024)?;
+                require_nonempty("password", password, 16_384)?;
+            }
+            Self::BearerToken { token } | Self::HuggingFace { token } => {
+                require_nonempty("token", token, 16_384)?;
+            }
+            Self::HttpHeaders { headers } => {
+                if headers.is_empty() || headers.len() > 64 {
+                    return Err(super::error::CredentialError::InvalidInput(
+                        "headers must contain between 1 and 64 entries".into(),
+                    ));
+                }
+                for (name, value) in headers {
+                    validate_header_name(name)?;
+                    require_nonempty("header value", value, 16_384)?;
+                }
+            }
+            Self::ObjectStore {
+                access_key_id,
+                secret_access_key,
+                session_token,
+            } => {
+                require_nonempty("access_key_id", access_key_id, 1024)?;
+                require_nonempty("secret_access_key", secret_access_key, 16_384)?;
+                if let Some(token) = session_token {
+                    require_nonempty("session_token", token, 16_384)?;
+                }
+            }
+        }
+        Ok(())
+    }
+}
+
+impl fmt::Debug for SecretMaterial {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::BasicAuth { .. } => formatter.write_str("SecretMaterial::BasicAuth(REDACTED)"),
+            Self::BearerToken { .. } => {
+                formatter.write_str("SecretMaterial::BearerToken(REDACTED)")
+            }
+            Self::HttpHeaders { headers } => formatter
+                .debug_struct("SecretMaterial::HttpHeaders")
+                .field("count", &headers.len())
+                .field("values", &"REDACTED")
+                .finish(),
+            Self::ObjectStore { .. } => {
+                formatter.write_str("SecretMaterial::ObjectStore(REDACTED)")
+            }
+            Self::HuggingFace { .. } => {
+                formatter.write_str("SecretMaterial::HuggingFace(REDACTED)")
+            }
+        }
+    }
+}
+
+impl fmt::Display for SecretMaterial {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(formatter, "SecretMaterial({})", self.kind().as_str())
+    }
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct SourceCredentialVersion {
+    pub id: OpaqueId,
+    pub created_at: OffsetDateTime,
+}
+
+/// Opaque application pin carried by an immutable execution grant.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct CredentialGrantVersion {
+    pub credential_id: OpaqueId,
+    pub version_id: OpaqueId,
+}
+
+/// Metadata projection; never includes secret material or Vault coordinates.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct SourceCredential {
+    pub id: OpaqueId,
+    pub owner: OpaqueId,
+    pub label: String,
+    pub kind: SourceCredentialKind,
+    pub status: SourceCredentialStatus,
+    pub active_version: Option<SourceCredentialVersion>,
+    pub created_at: OffsetDateTime,
+    pub updated_at: OffsetDateTime,
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct SourceCredentialPage {
+    pub items: Vec<SourceCredential>,
+    pub next_cursor: Option<String>,
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct CreateCredential {
+    pub label: String,
+    pub material: SecretMaterial,
+}
+
+fn require_nonempty(
+    field: &str,
+    value: &str,
+    max: usize,
+) -> Result<(), super::error::CredentialError> {
+    if value.is_empty() || value.len() > max {
+        return Err(super::error::CredentialError::InvalidInput(format!(
+            "{field} length must be between 1 and {max}"
+        )));
+    }
+    Ok(())
+}
+
+fn validate_header_name(name: &str) -> Result<(), super::error::CredentialError> {
+    if name.is_empty()
+        || !name.bytes().all(|b| {
+            matches!(b, b'a'..=b'z' | b'0'..=b'9' | b'!' | b'#' | b'$' | b'%' | b'&'
+                | b'\'' | b'*' | b'+' | b'-' | b'.' | b'^' | b'_' | b'`' | b'|' | b'~')
+        })
+    {
+        return Err(super::error::CredentialError::InvalidInput(
+            "header names must be lowercase token characters".into(),
+        ));
+    }
+    const FORBIDDEN: &[&str] = &[
+        "authorization",
+        "connection",
+        "content-length",
+        "cookie",
+        "host",
+        "keep-alive",
+        "proxy-authenticate",
+        "proxy-authorization",
+        "te",
+        "trailer",
+        "transfer-encoding",
+        "upgrade",
+    ];
+    if FORBIDDEN.contains(&name) {
+        return Err(super::error::CredentialError::InvalidInput(format!(
+            "header '{name}' is not permitted"
+        )));
+    }
+    Ok(())
+}
+
+pub(crate) fn validate_label(label: &str) -> Result<(), super::error::CredentialError> {
+    if label.is_empty() || label.len() > 200 {
+        return Err(super::error::CredentialError::InvalidInput(
+            "label length must be between 1 and 200".into(),
+        ));
+    }
+    Ok(())
+}

crates/remora-credentials/src/vault.rs

@@ -0,0 +1,460 @@
+use std::fmt;
+use std::time::Duration;
+
+use remora_domain::OpaqueId;
+use reqwest::redirect::Policy;
+use reqwest::{Client, StatusCode};
+use serde::{Deserialize, Serialize};
+
+use crate::error::CredentialError;
+use crate::types::SecretMaterial;
+
+/// One non-destroyed KV v2 version observed via secret metadata.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct LiveVaultVersion {
+    pub version: u64,
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub(crate) enum EmptyPathFence {
+    Created(u64),
+    Occupied,
+}
+
+/// Vault KV v2 access for credential secret material.
+///
+/// Topology and auth method are deployment choices. This client accepts a token
+/// (fixture root token or workload token after Kubernetes auth) and never logs
+/// request or response bodies that contain secret material.
+#[derive(Clone)]
+pub struct VaultConfig {
+    pub address: String,
+    pub token: String,
+    /// KV v2 mount, e.g. `secret`.
+    pub mount: String,
+    /// Path prefix under the mount where this deployment may allocate secrets.
+    pub path_prefix: String,
+    pub timeout: Duration,
+}
+
+impl fmt::Debug for VaultConfig {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("VaultConfig")
+            .field("address", &self.address)
+            .field("mount", &self.mount)
+            .field("path_prefix", &self.path_prefix)
+            .field("timeout", &self.timeout)
+            .field("token", &"REDACTED")
+            .finish()
+    }
+}
+
+impl VaultConfig {
+    pub fn from_env() -> Result<Self, CredentialError> {
+        let address = required_env("REMORA_VAULT_ADDR")?;
+        let token = required_env("REMORA_VAULT_TOKEN")?;
+        let full_path = required_env("REMORA_VAULT_PATH")?;
+        let (mount, path_prefix) = split_vault_path(&full_path)?;
+        Ok(Self {
+            address,
+            token,
+            mount,
+            path_prefix,
+            timeout: Duration::from_secs(10),
+        })
+    }
+
+    #[must_use]
+    pub fn with_timeout(mut self, timeout: Duration) -> Self {
+        self.timeout = timeout;
+        self
+    }
+
+    /// Allocate the opaque secret path for one credential version identity.
+    #[must_use]
+    pub fn secret_path_for(&self, credential_id: &OpaqueId, version_id: &OpaqueId) -> String {
+        format!(
+            "{}/versions/{}",
+            self.credential_path_for(credential_id),
+            version_id.as_str()
+        )
+    }
+
+    #[must_use]
+    pub fn credential_path_for(&self, credential_id: &OpaqueId) -> String {
+        if self.path_prefix.is_empty() {
+            format!("credentials/{}", credential_id.as_str())
+        } else {
+            format!(
+                "{}/credentials/{}",
+                self.path_prefix.trim_matches('/'),
+                credential_id.as_str()
+            )
+        }
+    }
+}
+
+#[derive(Clone)]
+pub struct VaultClient {
+    http: Client,
+    config: VaultConfig,
+}
+
+impl fmt::Debug for VaultClient {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("VaultClient")
+            .field("config", &self.config)
+            .finish()
+    }
+}
+
+impl VaultClient {
+    pub fn new(config: VaultConfig) -> Result<Self, CredentialError> {
+        // Disable redirects and ambient proxy discovery so X-Vault-Token and
+        // secret write bodies cannot leave the configured Vault endpoint via
+        // hop rewriting or HTTP_PROXY/HTTPS_PROXY injection.
+        let http = Client::builder()
+            .timeout(config.timeout)
+            .redirect(Policy::none())
+            .no_proxy()
+            .build()
+            .map_err(|error| {
+                CredentialError::Config(format!("failed to build vault HTTP client: {error}"))
+            })?;
+        Ok(Self { http, config })
+    }
+
+    #[must_use]
+    pub fn config(&self) -> &VaultConfig {
+        &self.config
+    }
+
+    /// Create secret material and return the immutable KV v2 version number.
+    ///
+    /// The write uses CAS 0 so an existing intent-bound path is never overwritten.
+    pub async fn put_version(
+        &self,
+        mount: &str,
+        secret_path: &str,
+        material: &SecretMaterial,
+    ) -> Result<u64, CredentialError> {
+        let url = format!(
+            "{}/v1/{}/data/{}",
+            self.config.address.trim_end_matches('/'),
+            mount.trim_matches('/'),
+            secret_path.trim_start_matches('/')
+        );
+        let body = KvWriteRequest {
+            data: material.clone(),
+            options: KvWriteOptions { cas: 0 },
+        };
+        let response = self
+            .http
+            .post(&url)
+            .header("X-Vault-Token", &self.config.token)
+            .json(&body)
+            .send()
+            .await
+            .map_err(map_transport)?;
+        let status = response.status();
+        if !status.is_success() {
+            let _ = response.bytes().await;
+            return Err(map_http_status(status, "write secret version"));
+        }
+        let parsed: KvWriteResponse = response.json().await.map_err(map_transport)?;
+        let version = parsed.data.and_then(|data| data.version).ok_or_else(|| {
+            CredentialError::Config("vault write response omitted version".into())
+        })?;
+        if version < 1 {
+            return Err(CredentialError::Config(
+                "vault returned non-positive secret version".into(),
+            ));
+        }
+        Ok(version)
+    }
+
+    pub(crate) async fn fence_empty_path(
+        &self,
+        mount: &str,
+        secret_path: &str,
+    ) -> Result<EmptyPathFence, CredentialError> {
+        let url = format!(
+            "{}/v1/{}/data/{}",
+            self.config.address.trim_end_matches('/'),
+            mount.trim_matches('/'),
+            secret_path.trim_start_matches('/')
+        );
+        let response = self
+            .http
+            .post(&url)
+            .header("X-Vault-Token", &self.config.token)
+            .json(&FenceWriteRequest {
+                data: FenceMarker {
+                    remora_write_fence: true,
+                },
+                options: KvWriteOptions { cas: 0 },
+            })
+            .send()
+            .await
+            .map_err(map_transport)?;
+        let status = response.status();
+        if status == StatusCode::BAD_REQUEST {
+            let _ = response.bytes().await;
+            return Ok(EmptyPathFence::Occupied);
+        }
+        if !status.is_success() {
+            let _ = response.bytes().await;
+            return Err(map_http_status(status, "fence empty secret path"));
+        }
+        let parsed: KvWriteResponse = response.json().await.map_err(map_transport)?;
+        let version = parsed.data.and_then(|data| data.version).ok_or_else(|| {
+            CredentialError::Config("vault fence response omitted version".into())
+        })?;
+        if version < 1 {
+            return Err(CredentialError::Config(
+                "vault returned non-positive fence version".into(),
+            ));
+        }
+        Ok(EmptyPathFence::Created(version))
+    }
+
+    /// Read one exact KV v2 version. Missing or destroyed versions fail closed.
+    pub async fn get_version(
+        &self,
+        mount: &str,
+        secret_path: &str,
+        vault_kv_version: u64,
+    ) -> Result<SecretMaterial, CredentialError> {
+        let url = format!(
+            "{}/v1/{}/data/{}?version={vault_kv_version}",
+            self.config.address.trim_end_matches('/'),
+            mount.trim_matches('/'),
+            secret_path.trim_start_matches('/')
+        );
+        let response = self
+            .http
+            .get(&url)
+            .header("X-Vault-Token", &self.config.token)
+            .send()
+            .await
+            .map_err(map_transport)?;
+        let status = response.status();
+        if status == StatusCode::NOT_FOUND {
+            let _ = response.bytes().await;
+            return Err(CredentialError::Unresolvable);
+        }
+        if !status.is_success() {
+            let _ = response.bytes().await;
+            return Err(map_http_status(status, "read secret version"));
+        }
+        let parsed: KvReadResponse = response.json().await.map_err(map_transport)?;
+        let data = parsed.data.ok_or(CredentialError::Unresolvable)?;
+        let material = data.data.ok_or(CredentialError::Unresolvable)?;
+        let reported = data
+            .metadata
+            .and_then(|meta| meta.version)
+            .ok_or(CredentialError::Unresolvable)?;
+        if reported != vault_kv_version {
+            return Err(CredentialError::Unresolvable);
+        }
+        material.validate()?;
+        Ok(material)
+    }
+
+    /// List non-destroyed KV v2 versions present at a path (for intent recovery).
+    ///
+    pub async fn list_live_versions(
+        &self,
+        mount: &str,
+        secret_path: &str,
+    ) -> Result<Vec<LiveVaultVersion>, CredentialError> {
+        let url = format!(
+            "{}/v1/{}/metadata/{}",
+            self.config.address.trim_end_matches('/'),
+            mount.trim_matches('/'),
+            secret_path.trim_start_matches('/')
+        );
+        let response = self
+            .http
+            .get(&url)
+            .header("X-Vault-Token", &self.config.token)
+            .send()
+            .await
+            .map_err(map_transport)?;
+        let status = response.status();
+        if status == StatusCode::NOT_FOUND {
+            let _ = response.bytes().await;
+            return Ok(Vec::new());
+        }
+        if !status.is_success() {
+            let _ = response.bytes().await;
+            return Err(map_http_status(status, "list secret metadata"));
+        }
+        let parsed: KvMetadataResponse = response.json().await.map_err(map_transport)?;
+        let versions = parsed
+            .data
+            .and_then(|data| data.versions)
+            .unwrap_or_default();
+        let mut live = Vec::new();
+        for (key, meta) in versions {
+            if meta.destroyed.unwrap_or(false) {
+                continue;
+            }
+            let Ok(version) = key.parse::<u64>() else {
+                continue;
+            };
+            if version < 1 {
+                continue;
+            }
+            live.push(LiveVaultVersion { version });
+        }
+        live.sort_by_key(|entry| entry.version);
+        Ok(live)
+    }
+
+    /// Irreversibly destroy one KV v2 version.
+    pub async fn destroy_version(
+        &self,
+        mount: &str,
+        secret_path: &str,
+        vault_kv_version: u64,
+    ) -> Result<(), CredentialError> {
+        let url = format!(
+            "{}/v1/{}/destroy/{}",
+            self.config.address.trim_end_matches('/'),
+            mount.trim_matches('/'),
+            secret_path.trim_start_matches('/')
+        );
+        let body = DestroyRequest {
+            versions: vec![vault_kv_version],
+        };
+        let response = self
+            .http
+            .post(&url)
+            .header("X-Vault-Token", &self.config.token)
+            .json(&body)
+            .send()
+            .await
+            .map_err(map_transport)?;
+        let status = response.status();
+        if !status.is_success() {
+            let _ = response.bytes().await;
+            return Err(map_http_status(status, "destroy secret version"));
+        }
+        let _ = response.bytes().await;
+        Ok(())
+    }
+}
+
+#[derive(Serialize)]
+struct KvWriteRequest {
+    data: SecretMaterial,
+    options: KvWriteOptions,
+}
+
+#[derive(Serialize)]
+struct KvWriteOptions {
+    cas: u8,
+}
+
+#[derive(Serialize)]
+struct FenceWriteRequest {
+    data: FenceMarker,
+    options: KvWriteOptions,
+}
+
+#[derive(Serialize)]
+struct FenceMarker {
+    remora_write_fence: bool,
+}
+
+#[derive(Deserialize)]
+struct KvWriteResponse {
+    data: Option<KvWriteData>,
+}
+
+#[derive(Deserialize)]
+struct KvWriteData {
+    version: Option<u64>,
+}
+
+#[derive(Deserialize)]
+struct KvReadResponse {
+    data: Option<KvReadData>,
+}
+
+#[derive(Deserialize)]
+struct KvReadData {
+    data: Option<SecretMaterial>,
+    metadata: Option<KvMetadata>,
+}
+
+#[derive(Deserialize)]
+struct KvMetadata {
+    version: Option<u64>,
+}
+
+#[derive(Deserialize)]
+struct KvMetadataResponse {
+    data: Option<KvMetadataListData>,
+}
+
+#[derive(Deserialize)]
+struct KvMetadataListData {
+    versions: Option<std::collections::BTreeMap<String, KvVersionMeta>>,
+}
+
+#[derive(Deserialize)]
+struct KvVersionMeta {
+    destroyed: Option<bool>,
+}
+
+#[derive(Serialize)]
+struct DestroyRequest {
+    versions: Vec<u64>,
+}
+
+fn required_env(name: &str) -> Result<String, CredentialError> {
+    std::env::var(name)
+        .ok()
+        .filter(|value| !value.is_empty())
+        .ok_or_else(|| CredentialError::Config(format!("{name} is required")))
+}
+
+/// Split a fixture path such as `secret/remora/lane-0` into mount + prefix.
+pub fn split_vault_path(full: &str) -> Result<(String, String), CredentialError> {
+    let trimmed = full.trim().trim_matches('/');
+    if trimmed.is_empty() {
+        return Err(CredentialError::Config(
+            "REMORA_VAULT_PATH must include a mount".into(),
+        ));
+    }
+    match trimmed.split_once('/') {
+        Some((mount, prefix)) if !mount.is_empty() => {
+            Ok((mount.to_owned(), prefix.trim_matches('/').to_owned()))
+        }
+        Some(_) | None => Ok((trimmed.to_owned(), String::new())),
+    }
+}
+
+fn map_transport(_error: reqwest::Error) -> CredentialError {
+    CredentialError::SecretStoreUnavailable
+}
+
+fn map_http_status(status: StatusCode, operation: &str) -> CredentialError {
+    if status.is_server_error() || status == StatusCode::SERVICE_UNAVAILABLE {
+        CredentialError::SecretStoreUnavailable
+    } else if status == StatusCode::FORBIDDEN || status == StatusCode::UNAUTHORIZED {
+        // Treat policy denials as unresolvable rather than leaking store details.
+        CredentialError::Unresolvable
+    } else if status == StatusCode::NOT_FOUND {
+        CredentialError::Unresolvable
+    } else {
+        CredentialError::Config(format!(
+            "vault {operation} failed with HTTP {}",
+            status.as_u16()
+        ))
+    }
+}