Harden cache secret residency and CPU side-channel posture (#335)

* fix(core): make key schedule caching optional

* fix(memory): use guarded hardware-enclave slab

* fix(init): harden process before factory setup

* fix(security): warn on CPU side-channel exposure

* Harden FFI and binding security boundaries (#336)

* fix(security): harden FFI and binding boundaries

* fix(security): require explicit KMS configuration

* fix(security): enforce data row record limits

* fix(security): harden native binding boundaries

* fix(security): zeroize Vault Transit plaintext staging

* docs: add configuration drift guard TODO

* docs: clarify drift guard TOFU adoption

* fix(security): add metastore config drift guard

* Fix CI regressions on cache hardening branch

* Fix review and binding CI regressions

* Move drift guard override logs out of sensitive paths

* Fix sanitizer Miri hardening tests

* Clamp key timestamp precision in factories

Author: jgowdy-godaddy

.github/workflows/ci.yml

@@ -1790,7 +1790,7 @@ jobs:
               composer config repositories.asherah path /work/asherah-php
               composer config minimum-stability dev
               composer config prefer-stable true
-              composer require godaddy/asherah:* --no-interaction --no-progress >/dev/null
+              bash /work/scripts/composer-retry.sh require godaddy/asherah:* --no-interaction --no-progress >/dev/null
               php vendor/godaddy/asherah/tests/consumer_smoke.php
             '
       - name: Consumer source install smoke (musl)
@@ -1806,7 +1806,7 @@ jobs:
               composer config repositories.asherah path /work/asherah-php
               composer config minimum-stability dev
               composer config prefer-stable true
-              composer require godaddy/asherah:* --no-interaction --no-progress >/dev/null
+              bash /work/scripts/composer-retry.sh require godaddy/asherah:* --no-interaction --no-progress >/dev/null
               php vendor/godaddy/asherah/tests/consumer_smoke.php
             '
 

.pre-commit-config.yaml

@@ -17,7 +17,7 @@ repos:
 
       - id: cargo-test
         name: cargo test
-        entry: cargo test --workspace --lib
+        entry: cargo test --workspace --lib --exclude asherah-node --exclude asherah-py --exclude asherah-bench
         language: system
         types: [rust]
         pass_filenames: false

Cargo.lock

@@ -82,4 +82,3 @@ unimplemented = "warn"
 unneeded_field_pattern = "warn"
 unseparated_literal_suffix = "warn"
 used_underscore_binding = "warn"
-

Cargo.toml

@@ -161,8 +161,8 @@ TIER 1: mlock'd Slab (hot cache, ~400ns access)
   +----------------------------------------------------+
   Guard Page [PROT_NONE -- segfaults on access]
 
-  Canary bytes between guard pages and data detect
-  buffer overflows at runtime.
+  Guard pages fault on page-boundary overflows and underflows.
+  Standalone secure buffers also use canaries for corruption detection.
 
 TIER 2: Encrypted Enclaves (cold cache, ~1us access)
 ========================================================
@@ -298,6 +298,21 @@ the key
 - **AES-256-GCM Enclaves**: Keys at rest in regular memory are encrypted
 with authenticated encryption; only the mlock'd Coffer can decrypt them
 
+### Microarchitectural side channels
+
+Asherah's memory hardening reduces normal process-memory exposure, but it does
+not by itself mitigate Spectre, Meltdown, L1TF, MDS, or related CPU side-channel
+classes. Guard pages and `mprotect` catch architectural out-of-bounds access;
+they do not make secrets invisible to speculative-execution gadgets or hostile
+co-tenants on an unmitigated host.
+
+Production deployments that handle high-value plaintext or keys should run on
+hosts with current CPU microcode and kernel mitigations, avoid untrusted
+co-tenants on the same physical core, and consider disabling SMT or using core
+scheduling where the platform requires it. On Linux, `asherah-server` reads
+`/sys/devices/system/cpu/vulnerabilities/*` at startup and warns when the host
+reports a vulnerable or residual-vulnerable status.
+
 ## License
 
 [Apache-2.0](LICENSE)

README.md

@@ -66,6 +66,19 @@ pub struct ConfigOptions {
     /// decryptors that lack metastore write permission.
     #[serde(rename = "SelfHealRecoveredKeys")]
     pub self_heal_recovered_keys: Option<bool>,
+    /// Emergency escape hatch: run even if the persisted TOFU configuration
+    /// drift guard conflicts with this resolved config. The guard is not
+    /// rewritten. Env override: `ASHERAH_CONFIG_DRIFT_FORCE_RUN`.
+    #[serde(rename = "ConfigDriftForceRun", alias = "ForceRunWithConfigDrift")]
+    pub config_drift_force_run: Option<bool>,
+    /// Repair escape hatch: replace the persisted TOFU configuration drift
+    /// guard with this resolved config. Env override:
+    /// `ASHERAH_CONFIG_DRIFT_FORCE_UPDATE`.
+    #[serde(
+        rename = "ConfigDriftForceUpdate",
+        alias = "ForceUpdateConfigDriftGuard"
+    )]
+    pub config_drift_force_update: Option<bool>,
     #[serde(rename = "EnableSessionCaching")]
     pub enable_session_caching: Option<bool>,
     #[serde(rename = "Verbose")]
@@ -169,7 +182,7 @@ pub struct AppliedConfig {
 }
 
 use asherah::builders::{
-    KmsConfig, MetastoreConfig, PolicyConfig, PoolConfig, ResolvedConfig,
+    ConfigDriftGuardOptions, KmsConfig, MetastoreConfig, PolicyConfig, PoolConfig, ResolvedConfig,
     TEST_DEBUG_STATIC_MASTER_KEY_HEX,
 };
 
@@ -179,23 +192,23 @@ impl ConfigOptions {
         Ok(cfg)
     }
 
+    pub fn config_drift_guard_options(&self) -> ConfigDriftGuardOptions {
+        ConfigDriftGuardOptions {
+            allow_mismatch: self.config_drift_force_run.unwrap_or(false),
+            force_update: self.config_drift_force_update.unwrap_or(false),
+        }
+    }
+
     /// Resolve into a structured config — no env var reads or writes.
     pub fn resolve(&self) -> Result<(ResolvedConfig, AppliedConfig)> {
-        // KMS aliases: `static` and `test-debug-static` are synonyms.
-        // `test-debug-static` is the preferred identifier because it
-        // makes the non-production nature obvious, but both must behave
-        // identically to preserve interop with the canonical Go
-        // implementation of Asherah (which accepts `static` and falls
-        // back to the well-known test key when no hex is provided).
-        // The fail-fast on empty `StaticMasterKeyHex` previously here
-        // diverged from Go-canonical behavior; the static-KMS path
-        // already logs a loud warning and tagged the test key as
-        // public, which is the right safety net.
+        // `test-debug-static` is an explicit test-only alias that may use the
+        // public test key. Legacy `static` remains supported, but it must
+        // provide an explicit key so a missing KMS config cannot silently fall
+        // back to static master-key material.
         fn normalize_alias(value: &str) -> String {
             match value.to_lowercase().as_str() {
                 "test-debug-memory" => "memory".to_string(),
                 "test-debug-sqlite" => "sqlite".to_string(),
-                "test-debug-static" => "static".to_string(),
                 other => other.to_string(),
             }
         }
@@ -272,18 +285,24 @@ impl ConfigOptions {
 
         let aws_profile_name = self.aws_profile_name.clone();
 
-        let kms_raw = self.kms.as_deref().unwrap_or("static");
+        let kms_raw = self
+            .kms
+            .as_deref()
+            .ok_or_else(|| anyhow!("KMS is required"))?;
         let kms_kind = normalize_alias(kms_raw);
         let kms = match kms_kind.as_str() {
-            // `static` and `test-debug-static` collapse to the same
-            // arm via `normalize_alias` above. Falls back to the
-            // publicly-known test key when no hex is supplied (this
-            // matches Go-canonical asherah behavior); the static-KMS
-            // builder log-warns loudly that the key is non-production.
             "static" => KmsConfig::Static {
                 key_hex: self
                     .static_master_key_hex
                     .clone()
+                    .filter(|key_hex| !key_hex.is_empty())
+                    .ok_or_else(|| anyhow!("StaticMasterKeyHex is required when KMS=static"))?,
+            },
+            "test-debug-static" => KmsConfig::Static {
+                key_hex: self
+                    .static_master_key_hex
+                    .clone()
+                    .filter(|key_hex| !key_hex.is_empty())
                     .unwrap_or_else(|| TEST_DEBUG_STATIC_MASTER_KEY_HEX.to_string()),
             },
             "aws" => KmsConfig::Aws {
@@ -454,16 +473,25 @@ fn resolve_rdbms_connection(
 /// Build a factory from structured config — no env var side effects.
 pub fn factory_from_config(config: &ConfigOptions) -> Result<(Factory, AppliedConfig)> {
     let (mut resolved, applied) = config.resolve()?;
-    merge_recovery_region_suffixes_from_env(&mut resolved);
-    let factory = asherah::builders::factory_from_resolved(&resolved)?;
+    let mut config_drift_guard = config.config_drift_guard_options();
+    merge_runtime_env_overrides(&mut resolved, &mut config_drift_guard);
+    let factory = asherah::builders::factory_from_resolved_with_config_drift_guard(
+        &resolved,
+        config_drift_guard,
+    )?;
     Ok((factory, applied))
 }
 
 /// Async variant — safe for concurrent use since no env vars are written.
 pub async fn factory_from_config_async(config: &ConfigOptions) -> Result<(Factory, AppliedConfig)> {
     let (mut resolved, applied) = config.resolve()?;
-    merge_recovery_region_suffixes_from_env(&mut resolved);
-    let factory = asherah::builders::factory_from_resolved_async(&resolved).await?;
+    let mut config_drift_guard = config.config_drift_guard_options();
+    merge_runtime_env_overrides(&mut resolved, &mut config_drift_guard);
+    let factory = asherah::builders::factory_from_resolved_with_config_drift_guard_async(
+        &resolved,
+        config_drift_guard,
+    )
+    .await?;
     Ok((factory, applied))
 }
 
@@ -472,7 +500,18 @@ pub async fn factory_from_config_async(config: &ConfigOptions) -> Result<(Factor
 /// while preserving order. This gives every language binding the env-based
 /// recovery lever even when it has no first-class config field for it yet.
 /// Only reads env (never writes), so it is safe for concurrent use.
-fn merge_recovery_region_suffixes_from_env(resolved: &mut ResolvedConfig) {
+fn merge_runtime_env_overrides(
+    resolved: &mut ResolvedConfig,
+    config_drift_guard: &mut ConfigDriftGuardOptions,
+) {
+    fn parse_bool(raw: &str) -> Option<bool> {
+        match raw.trim().to_lowercase().as_str() {
+            "1" | "true" | "yes" | "on" => Some(true),
+            "0" | "false" | "no" | "off" => Some(false),
+            _ => None,
+        }
+    }
+
     if let Ok(raw) = std::env::var("RECOVERY_REGION_SUFFIXES") {
         for entry in raw.split(',').map(str::trim).filter(|s| !s.is_empty()) {
             if !resolved.recovery_region_suffixes.iter().any(|s| s == entry) {
@@ -488,6 +527,16 @@ fn merge_recovery_region_suffixes_from_env(resolved: &mut ResolvedConfig) {
             "0" | "false" | "no" | "off"
         );
     }
+    if let Ok(raw) = std::env::var("ASHERAH_CONFIG_DRIFT_FORCE_RUN") {
+        if let Some(force_run) = parse_bool(&raw) {
+            config_drift_guard.allow_mismatch = force_run;
+        }
+    }
+    if let Ok(raw) = std::env::var("ASHERAH_CONFIG_DRIFT_FORCE_UPDATE") {
+        if let Some(force_update) = parse_bool(&raw) {
+            config_drift_guard.force_update = force_update;
+        }
+    }
 }
 
 /// Resolve the DynamoDB endpoint URL given the user-supplied