feat(security): harden gateway boundaries and usage policies

Consolidate subscription usage policy enforcement, privacy-safe persistence, and gateway security hardening into one reviewable change.

Includes bounded HTTP and execution envelopes, header and protocol guards, DNS and relay validation, authentication and secret projection hardening, secure backup/install paths, and regression coverage.

crates/aether-data/runtime/src/backend/maintenance.rs

@@ -202,6 +202,22 @@ impl DataBackends {
         }
     }
 
+    pub async fn compare_and_set_system_config_string_value(
+        &self,
+        key: &str,
+        expected: &str,
+        replacement: &str,
+    ) -> Result<bool, DataLayerError> {
+        match self.sql_backend() {
+            Some(backend) => {
+                backend
+                    .compare_and_set_system_config_string_value(key, expected, replacement)
+                    .await
+            }
+            None => Ok(false),
+        }
+    }
+
     pub async fn list_system_config_entries(
         &self,
     ) -> Result<Vec<StoredSystemConfigEntry>, DataLayerError> {
@@ -307,6 +323,8 @@ impl<'a> SqlBackendRef<'a> {
             Self::Sqlite(sqlite) => {
                 warm_pool(sqlite.pool(), sqlite.config().pool.min_connections).await
             }
+            #[cfg(not(any(feature = "postgres", feature = "mysql", feature = "sqlite")))]
+            Self::Disabled(_) => unreachable!("a SQL backend cannot exist without a driver"),
         }
     }
 
@@ -321,6 +339,8 @@ impl<'a> SqlBackendRef<'a> {
             Self::Mysql(mysql) => mysql.run_table_maintenance(table_names).await,
             #[cfg(feature = "sqlite")]
             Self::Sqlite(sqlite) => sqlite.run_table_maintenance(table_names).await,
+            #[cfg(not(any(feature = "postgres", feature = "mysql", feature = "sqlite")))]
+            Self::Disabled(_) => unreachable!("a SQL backend cannot exist without a driver"),
         }
     }
 
@@ -341,6 +361,8 @@ impl<'a> SqlBackendRef<'a> {
                 crate::lifecycle::migrate::run_sqlite_migrations(sqlite.pool()).await?;
                 Ok(true)
             }
+            #[cfg(not(any(feature = "postgres", feature = "mysql", feature = "sqlite")))]
+            Self::Disabled(_) => unreachable!("a SQL backend cannot exist without a driver"),
         }
     }
 
@@ -361,6 +383,8 @@ impl<'a> SqlBackendRef<'a> {
                 crate::lifecycle::backfill::run_sqlite_backfills(sqlite.pool()).await?;
                 Ok(true)
             }
+            #[cfg(not(any(feature = "postgres", feature = "mysql", feature = "sqlite")))]
+            Self::Disabled(_) => unreachable!("a SQL backend cannot exist without a driver"),
         }
     }
 
@@ -380,6 +404,8 @@ impl<'a> SqlBackendRef<'a> {
             Self::Sqlite(sqlite) => Ok(Some(
                 crate::lifecycle::migrate::pending_sqlite_migrations(sqlite.pool()).await?,
             )),
+            #[cfg(not(any(feature = "postgres", feature = "mysql", feature = "sqlite")))]
+            Self::Disabled(_) => unreachable!("a SQL backend cannot exist without a driver"),
         }
     }
 
@@ -400,6 +426,8 @@ impl<'a> SqlBackendRef<'a> {
                 crate::lifecycle::migrate::prepare_sqlite_database_for_startup(sqlite.pool())
                     .await?,
             )),
+            #[cfg(not(any(feature = "postgres", feature = "mysql", feature = "sqlite")))]
+            Self::Disabled(_) => unreachable!("a SQL backend cannot exist without a driver"),
         }
     }
 
@@ -419,6 +447,8 @@ impl<'a> SqlBackendRef<'a> {
             Self::Sqlite(sqlite) => Ok(Some(
                 crate::lifecycle::backfill::pending_sqlite_backfills(sqlite.pool()).await?,
             )),
+            #[cfg(not(any(feature = "postgres", feature = "mysql", feature = "sqlite")))]
+            Self::Disabled(_) => unreachable!("a SQL backend cannot exist without a driver"),
         }
     }
 
@@ -445,6 +475,8 @@ impl<'a> SqlBackendRef<'a> {
                 sqlite.pool().num_idle(),
                 sqlite.config().pool.max_connections,
             ),
+            #[cfg(not(any(feature = "postgres", feature = "mysql", feature = "sqlite")))]
+            Self::Disabled(_) => unreachable!("a SQL backend cannot exist without a driver"),
         }
     }
 
@@ -459,6 +491,8 @@ impl<'a> SqlBackendRef<'a> {
             Self::Mysql(mysql) => mysql.aggregate_wallet_daily_usage(input).await,
             #[cfg(feature = "sqlite")]
             Self::Sqlite(sqlite) => sqlite.aggregate_wallet_daily_usage(input).await,
+            #[cfg(not(any(feature = "postgres", feature = "mysql", feature = "sqlite")))]
+            Self::Disabled(_) => unreachable!("a SQL backend cannot exist without a driver"),
         }
     }
 
@@ -473,6 +507,8 @@ impl<'a> SqlBackendRef<'a> {
             Self::Mysql(mysql) => mysql.aggregate_stats_hourly(input).await,
             #[cfg(feature = "sqlite")]
             Self::Sqlite(sqlite) => sqlite.aggregate_stats_hourly(input).await,
+            #[cfg(not(any(feature = "postgres", feature = "mysql", feature = "sqlite")))]
+            Self::Disabled(_) => unreachable!("a SQL backend cannot exist without a driver"),
         }
     }
 
@@ -487,6 +523,8 @@ impl<'a> SqlBackendRef<'a> {
             Self::Mysql(mysql) => mysql.aggregate_stats_daily(input).await,
             #[cfg(feature = "sqlite")]
             Self::Sqlite(sqlite) => sqlite.aggregate_stats_daily(input).await,
+            #[cfg(not(any(feature = "postgres", feature = "mysql", feature = "sqlite")))]
+            Self::Disabled(_) => unreachable!("a SQL backend cannot exist without a driver"),
         }
     }
 
@@ -501,6 +539,38 @@ impl<'a> SqlBackendRef<'a> {
             Self::Mysql(mysql) => mysql.find_system_config_value(key).await,
             #[cfg(feature = "sqlite")]
             Self::Sqlite(sqlite) => sqlite.find_system_config_value(key).await,
+            #[cfg(not(any(feature = "postgres", feature = "mysql", feature = "sqlite")))]
+            Self::Disabled(_) => unreachable!("a SQL backend cannot exist without a driver"),
+        }
+    }
+
+    async fn compare_and_set_system_config_string_value(
+        self,
+        key: &str,
+        expected: &str,
+        replacement: &str,
+    ) -> Result<bool, DataLayerError> {
+        match self {
+            #[cfg(feature = "postgres")]
+            Self::Postgres(postgres) => {
+                postgres
+                    .compare_and_set_system_config_string_value(key, expected, replacement)
+                    .await
+            }
+            #[cfg(feature = "mysql")]
+            Self::Mysql(mysql) => {
+                mysql
+                    .compare_and_set_system_config_string_value(key, expected, replacement)
+                    .await
+            }
+            #[cfg(feature = "sqlite")]
+            Self::Sqlite(sqlite) => {
+                sqlite
+                    .compare_and_set_system_config_string_value(key, expected, replacement)
+                    .await
+            }
+            #[cfg(not(any(feature = "postgres", feature = "mysql", feature = "sqlite")))]
+            Self::Disabled(_) => unreachable!("a SQL backend cannot exist without a driver"),
         }
     }
 
@@ -514,6 +584,8 @@ impl<'a> SqlBackendRef<'a> {
             Self::Mysql(mysql) => mysql.list_system_config_entries().await,
             #[cfg(feature = "sqlite")]
             Self::Sqlite(sqlite) => sqlite.list_system_config_entries().await,
+            #[cfg(not(any(feature = "postgres", feature = "mysql", feature = "sqlite")))]
+            Self::Disabled(_) => unreachable!("a SQL backend cannot exist without a driver"),
         }
     }
 
@@ -542,6 +614,8 @@ impl<'a> SqlBackendRef<'a> {
                     .upsert_system_config_entry(key, value, description)
                     .await
             }
+            #[cfg(not(any(feature = "postgres", feature = "mysql", feature = "sqlite")))]
+            Self::Disabled(_) => unreachable!("a SQL backend cannot exist without a driver"),
         }
     }
 
@@ -553,6 +627,8 @@ impl<'a> SqlBackendRef<'a> {
             Self::Mysql(mysql) => mysql.delete_system_config_value(key).await,
             #[cfg(feature = "sqlite")]
             Self::Sqlite(sqlite) => sqlite.delete_system_config_value(key).await,
+            #[cfg(not(any(feature = "postgres", feature = "mysql", feature = "sqlite")))]
+            Self::Disabled(_) => unreachable!("a SQL backend cannot exist without a driver"),
         }
     }
 
@@ -564,6 +640,8 @@ impl<'a> SqlBackendRef<'a> {
             Self::Mysql(mysql) => mysql.read_admin_system_stats().await,
             #[cfg(feature = "sqlite")]
             Self::Sqlite(sqlite) => sqlite.read_admin_system_stats().await,
+            #[cfg(not(any(feature = "postgres", feature = "mysql", feature = "sqlite")))]
+            Self::Disabled(_) => unreachable!("a SQL backend cannot exist without a driver"),
         }
     }
 
@@ -578,6 +656,8 @@ impl<'a> SqlBackendRef<'a> {
             Self::Mysql(mysql) => mysql.purge_admin_system_data(target).await,
             #[cfg(feature = "sqlite")]
             Self::Sqlite(sqlite) => sqlite.purge_admin_system_data(target).await,
+            #[cfg(not(any(feature = "postgres", feature = "mysql", feature = "sqlite")))]
+            Self::Disabled(_) => unreachable!("a SQL backend cannot exist without a driver"),
         }
     }
 
@@ -591,6 +671,8 @@ impl<'a> SqlBackendRef<'a> {
             Self::Mysql(mysql) => mysql.export_admin_system_usage_aggregates().await,
             #[cfg(feature = "sqlite")]
             Self::Sqlite(sqlite) => sqlite.export_admin_system_usage_aggregates().await,
+            #[cfg(not(any(feature = "postgres", feature = "mysql", feature = "sqlite")))]
+            Self::Disabled(_) => unreachable!("a SQL backend cannot exist without a driver"),
         }
     }
 
@@ -635,6 +717,8 @@ impl<'a> SqlBackendRef<'a> {
                     )
                     .await
             }
+            #[cfg(not(any(feature = "postgres", feature = "mysql", feature = "sqlite")))]
+            Self::Disabled(_) => unreachable!("a SQL backend cannot exist without a driver"),
         }
     }
 
@@ -649,6 +733,8 @@ impl<'a> SqlBackendRef<'a> {
             Self::Mysql(mysql) => mysql.purge_admin_request_bodies_batch(batch_size).await,
             #[cfg(feature = "sqlite")]
             Self::Sqlite(sqlite) => sqlite.purge_admin_request_bodies_batch(batch_size).await,
+            #[cfg(not(any(feature = "postgres", feature = "mysql", feature = "sqlite")))]
+            Self::Disabled(_) => unreachable!("a SQL backend cannot exist without a driver"),
         }
     }
 }

crates/aether-data/runtime/src/backend/mod.rs

@@ -32,9 +32,9 @@ pub use mysql::MysqlBackend;
 pub use postgres::PostgresBackend;
 pub use read::DataReadRepositories;
 pub use referrals::{
-    ReferralAdminStats, ReferralDataState, ReferralMutationStatus, ReferralRelationshipListQuery,
-    ReferralRelationshipRecord, ReferralRewardConfig, ReferralRewardListQuery,
-    ReferralRewardRecord, ReferralUserDashboard,
+    ReferralAdminStats, ReferralDataState, ReferralMutationStatus, ReferralReconciliationSummary,
+    ReferralRelationshipListQuery, ReferralRelationshipRecord, ReferralRewardConfig,
+    ReferralRewardListQuery, ReferralRewardRecord, ReferralUserDashboard,
 };
 #[cfg(feature = "sqlite")]
 pub use sqlite::SqliteBackend;
@@ -52,6 +52,11 @@ enum SqlBackendRef<'a> {
     Mysql(&'a MysqlBackend),
     #[cfg(feature = "sqlite")]
     Sqlite(&'a SqliteBackend),
+    // Keep the reference lifetime represented when this crate is built without
+    // any SQL driver features.  The no-driver build still exposes the
+    // maintenance facade, but has no concrete backend variant to carry `'a`.
+    #[cfg(not(any(feature = "postgres", feature = "mysql", feature = "sqlite")))]
+    Disabled(std::marker::PhantomData<&'a ()>),
 }
 
 #[derive(Debug, Clone, Default)]

crates/aether-data/runtime/src/backend/sqlite.rs

@@ -302,7 +302,7 @@ mod tests {
             .await
             .expect("sqlite migrations should run");
 
-        let value = serde_json::json!({"enabled": true});
+        let value = serde_json::json!("enabled");
         let stored = backend
             .upsert_system_config_entry("feature.local", &value, Some("local flag"))
             .await
@@ -313,7 +313,40 @@ mod tests {
                 .find_system_config_value("feature.local")
                 .await
                 .expect("system config should read"),
-            Some(value)
+            Some(value.clone())
+        );
+        let replacement = serde_json::json!("disabled");
+        assert!(!backend
+            .compare_and_set_system_config_string_value("feature.local", "stale", "disabled")
+            .await
+            .expect("stale system config compare-and-set should complete"));
+        assert!(backend
+            .compare_and_set_system_config_string_value("feature.local", "enabled", "disabled")
+            .await
+            .expect("matching system config compare-and-set should complete"));
+        assert_eq!(
+            backend
+                .find_system_config_value("feature.local")
+                .await
+                .expect("updated system config should read"),
+            Some(replacement.clone())
+        );
+        sqlx::query("UPDATE system_configs SET value = ? WHERE key = ?")
+            .bind(r#""\u5bc6\u94a5""#)
+            .bind("feature.local")
+            .execute(backend.pool())
+            .await
+            .expect("legacy escaped JSON string should persist");
+        assert!(backend
+            .compare_and_set_system_config_string_value("feature.local", "密钥", "encrypted-value",)
+            .await
+            .expect("escaped JSON string compare-and-set should complete"));
+        assert_eq!(
+            backend
+                .find_system_config_value("feature.local")
+                .await
+                .expect("escaped JSON string replacement should read"),
+            Some(serde_json::json!("encrypted-value"))
         );
         assert_eq!(
             backend
@@ -543,6 +576,22 @@ VALUES ('target-key-1', 'target-user-1', 'hash-target-key', 'target key', 1, 1)
         let api_key_id_map =
             BTreeMap::from([("source-key-1".to_string(), "target-key-1".to_string())]);
 
+        let validation_summary = backend
+            .import_admin_system_usage_aggregates(
+                &snapshot,
+                &user_id_map,
+                &api_key_id_map,
+                AdminSystemUsageAggregateImportMode::ValidateError,
+            )
+            .await
+            .expect("usage aggregates should validate");
+        assert_eq!(validation_summary.stats_daily.created, 1);
+        assert_eq!(validation_summary.stats_user_daily.created, 1);
+        assert_eq!(validation_summary.stats_daily_api_key.created, 1);
+        assert_eq!(sqlite_count(backend.pool(), "stats_daily").await, 0);
+        assert_eq!(sqlite_count(backend.pool(), "stats_user_daily").await, 0);
+        assert_eq!(sqlite_count(backend.pool(), "stats_daily_api_key").await, 0);
+
         let summary = backend
             .import_admin_system_usage_aggregates(
                 &snapshot,

crates/aether-data/runtime/src/backend/system.rs

@@ -170,9 +170,10 @@ fn should_skip_imported_aggregate(
     match mode {
         AdminSystemUsageAggregateImportMode::Skip => Ok(true),
         AdminSystemUsageAggregateImportMode::Overwrite => Ok(false),
-        AdminSystemUsageAggregateImportMode::Error => Err(DataLayerError::InvalidInput(format!(
-            "{table} aggregate already exists for date_unix_secs={date_unix_secs}"
-        ))),
+        AdminSystemUsageAggregateImportMode::Error
+        | AdminSystemUsageAggregateImportMode::ValidateError => Err(DataLayerError::InvalidInput(
+            format!("{table} aggregate already exists for date_unix_secs={date_unix_secs}"),
+        )),
     }
 }
 

crates/aether-data/runtime/src/backend/system/mysql.rs

@@ -392,7 +392,11 @@ ON DUPLICATE KEY UPDATE
         add_aggregate_import_count(&mut summary.stats_daily_api_key, existing.is_some());
     }
 
-    tx.commit().await.map_sql_err()?;
+    if mode == AdminSystemUsageAggregateImportMode::ValidateError {
+        tx.rollback().await.map_sql_err()?;
+    } else {
+        tx.commit().await.map_sql_err()?;
+    }
     Ok(summary)
 }
 
@@ -447,6 +451,34 @@ LIMIT 1
         .transpose()
     }
 
+    pub async fn compare_and_set_system_config_string_value(
+        &self,
+        key: &str,
+        expected: &str,
+        replacement: &str,
+    ) -> Result<bool, DataLayerError> {
+        let now = current_unix_secs();
+        let replacement =
+            serialize_json_value(&serde_json::Value::String(replacement.to_string()))?;
+        let result = sqlx::query(
+            r#"
+UPDATE system_configs
+SET value = ?, updated_at = ?
+WHERE `key` = ?
+  AND JSON_TYPE(value) = 'STRING'
+  AND BINARY JSON_UNQUOTE(value) = BINARY ?
+"#,
+        )
+        .bind(replacement)
+        .bind(now as i64)
+        .bind(key)
+        .bind(expected)
+        .execute(self.pool())
+        .await
+        .map_sql_err()?;
+        Ok(result.rows_affected() > 0)
+    }
+
     pub async fn upsert_system_config_value(
         &self,
         key: &str,
@@ -501,6 +533,7 @@ ORDER BY `key` ASC
 INSERT INTO system_configs (id, `key`, value, description, created_at, updated_at)
 VALUES (?, ?, ?, ?, ?, ?)
 ON DUPLICATE KEY UPDATE
+    `key` = VALUES(`key`),
     value = VALUES(value),
     description = COALESCE(VALUES(description), description),
     updated_at = VALUES(updated_at)

crates/aether-data/runtime/src/backend/system/postgres.rs

@@ -18,6 +18,15 @@ WHERE key = $1
 LIMIT 1
 "#;
 
+const COMPARE_AND_SET_SYSTEM_CONFIG_STRING_VALUE_SQL: &str = r#"
+UPDATE system_configs
+SET value = TO_JSON($3::text),
+    updated_at = NOW()
+WHERE key = $1
+  AND JSON_TYPEOF(value) = 'string'
+  AND value #>> '{}' = $2
+"#;
+
 const UPSERT_SYSTEM_CONFIG_VALUE_SQL: &str = r#"
 INSERT INTO system_configs (id, key, value, description, created_at, updated_at)
 VALUES ($1, $2, $3, $4, NOW(), NOW())
@@ -437,7 +446,11 @@ SET api_key_name = EXCLUDED.api_key_name,
         add_aggregate_import_count(&mut summary.stats_daily_api_key, existing.is_some());
     }
 
-    tx.commit().await.map_postgres_err()?;
+    if mode == AdminSystemUsageAggregateImportMode::ValidateError {
+        tx.rollback().await.map_postgres_err()?;
+    } else {
+        tx.commit().await.map_postgres_err()?;
+    }
     Ok(summary)
 }
 
@@ -1157,6 +1170,22 @@ impl PostgresBackend {
             .map_postgres_err()
     }
 
+    pub async fn compare_and_set_system_config_string_value(
+        &self,
+        key: &str,
+        expected: &str,
+        replacement: &str,
+    ) -> Result<bool, DataLayerError> {
+        let result = sqlx::query(COMPARE_AND_SET_SYSTEM_CONFIG_STRING_VALUE_SQL)
+            .bind(key)
+            .bind(expected)
+            .bind(replacement)
+            .execute(self.pool())
+            .await
+            .map_postgres_err()?;
+        Ok(result.rows_affected() > 0)
+    }
+
     pub async fn upsert_system_config_value(
         &self,
         key: &str,

crates/aether-data/runtime/src/backend/system/sqlite.rs

@@ -396,7 +396,11 @@ SET api_key_name = excluded.api_key_name,
         add_aggregate_import_count(&mut summary.stats_daily_api_key, existing.is_some());
     }
 
-    tx.commit().await.map_sql_err()?;
+    if mode == AdminSystemUsageAggregateImportMode::ValidateError {
+        tx.rollback().await.map_sql_err()?;
+    } else {
+        tx.commit().await.map_sql_err()?;
+    }
     Ok(summary)
 }
 
@@ -1074,6 +1078,35 @@ LIMIT 1
         .transpose()
     }
 
+    pub async fn compare_and_set_system_config_string_value(
+        &self,
+        key: &str,
+        expected: &str,
+        replacement: &str,
+    ) -> Result<bool, DataLayerError> {
+        let now = current_unix_secs();
+        let replacement =
+            serialize_json_value(&serde_json::Value::String(replacement.to_string()))?;
+        let result = sqlx::query(
+            r#"
+UPDATE system_configs
+SET value = ?, updated_at = ?
+WHERE key = ?
+  AND json_valid(value)
+  AND json_type(value) = 'text'
+  AND CAST(json_extract(value, '$') AS TEXT) = ? COLLATE BINARY
+"#,
+        )
+        .bind(replacement)
+        .bind(now as i64)
+        .bind(key)
+        .bind(expected)
+        .execute(self.pool())
+        .await
+        .map_sql_err()?;
+        Ok(result.rows_affected() > 0)
+    }
+
     pub async fn upsert_system_config_value(
         &self,
         key: &str,