From 2f46159dd519ac49582cc5ae7f6608c9534434c1 Mon Sep 17 00:00:00 2001 From: Zeljko Date: Mon, 9 Nov 2026 08:49:53 +0100 Subject: [PATCH 001/105] feat(module-sdk): guardian-module-sdk, the Guardian module protocol and harness (#251) Protocol version 1 types (guardian.module.v1), the Module and ModuleFactory traits, the serve harness for remote modules with per-instance credentials, the basic-policy reference module, and the conformance test. Carried from the prototype (#554); RFC 0002 revision 26. --- Cargo.lock | 17 + Cargo.toml | 2 + crates/guardian-module-sdk/Cargo.toml | 25 + crates/guardian-module-sdk/build.rs | 5 + .../examples/basic-policy-serve.rs | 30 + .../examples/note-policy-serve.rs | 35 ++ .../examples/note_policy/mod.rs | 184 ++++++ .../proto/guardian_module_v1.proto | 222 +++++++ .../guardian-module-sdk/src/basic_policy.rs | 591 ++++++++++++++++++ crates/guardian-module-sdk/src/lib.rs | 313 ++++++++++ crates/guardian-module-sdk/src/serve.rs | 141 +++++ .../guardian-module-sdk/tests/conformance.rs | 151 +++++ 12 files changed, 1716 insertions(+) create mode 100644 crates/guardian-module-sdk/Cargo.toml create mode 100644 crates/guardian-module-sdk/build.rs create mode 100644 crates/guardian-module-sdk/examples/basic-policy-serve.rs create mode 100644 crates/guardian-module-sdk/examples/note-policy-serve.rs create mode 100644 crates/guardian-module-sdk/examples/note_policy/mod.rs create mode 100644 crates/guardian-module-sdk/proto/guardian_module_v1.proto create mode 100644 crates/guardian-module-sdk/src/basic_policy.rs create mode 100644 crates/guardian-module-sdk/src/lib.rs create mode 100644 crates/guardian-module-sdk/src/serve.rs create mode 100644 crates/guardian-module-sdk/tests/conformance.rs diff --git a/Cargo.lock b/Cargo.lock index 7ce5936b..5fdc2d42 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -3470,6 +3470,23 @@ dependencies = [ "tokio", ] +[[package]] +name = "guardian-module-sdk" +version = "0.19.0-rc.1" +dependencies = [ + "async-trait", + "prost", + "prost-types", + "secrecy", + "serde", + "serde_json", + "thiserror 2.0.19", + "tokio", + "tonic", + "tonic-prost", + "tonic-prost-build", +] + [[package]] name = "guardian-prod-benchmarks" version = "0.1.0" diff --git a/Cargo.toml b/Cargo.toml index acea0388..2cc66f27 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -8,6 +8,7 @@ members = [ "crates/miden-rpc-client", "crates/miden-keystore", "crates/contracts", + "crates/guardian-module-sdk", "crates/miden-multisig-client", "crates/qualification-driver", "examples/rust", @@ -20,6 +21,7 @@ default-members = [ "crates/miden-rpc-client", "crates/miden-keystore", "crates/contracts", + "crates/guardian-module-sdk", "crates/miden-multisig-client", ] resolver = "2" diff --git a/crates/guardian-module-sdk/Cargo.toml b/crates/guardian-module-sdk/Cargo.toml new file mode 100644 index 00000000..b5fc6660 --- /dev/null +++ b/crates/guardian-module-sdk/Cargo.toml @@ -0,0 +1,25 @@ +[package] +name = "guardian-module-sdk" +version.workspace = true +edition.workspace = true +rust-version.workspace = true +authors.workspace = true +license.workspace = true +repository.workspace = true +homepage.workspace = true +description = "Module interface, protocol types and serving harness for Guardian policy modules" + +[dependencies] +async-trait = "0.1" +prost = { workspace = true } +prost-types = "0.14" +secrecy = "0.10" +serde = { workspace = true, features = ["derive"] } +serde_json = { workspace = true } +thiserror = { workspace = true } +tokio = { workspace = true, features = ["rt-multi-thread", "macros", "net", "fs"] } +tonic = { workspace = true } +tonic-prost = { workspace = true } + +[build-dependencies] +tonic-prost-build = { workspace = true } diff --git a/crates/guardian-module-sdk/build.rs b/crates/guardian-module-sdk/build.rs new file mode 100644 index 00000000..7927b3cc --- /dev/null +++ b/crates/guardian-module-sdk/build.rs @@ -0,0 +1,5 @@ +fn main() -> Result<(), Box> { + tonic_prost_build::configure() + .compile_protos(&["proto/guardian_module_v1.proto"], &["proto"])?; + Ok(()) +} diff --git a/crates/guardian-module-sdk/examples/basic-policy-serve.rs b/crates/guardian-module-sdk/examples/basic-policy-serve.rs new file mode 100644 index 00000000..9a2e6f76 --- /dev/null +++ b/crates/guardian-module-sdk/examples/basic-policy-serve.rs @@ -0,0 +1,30 @@ +use std::net::SocketAddr; + +use guardian_module_sdk::basic_policy::BasicPolicy; +use guardian_module_sdk::serve::serve; + +#[tokio::main] +async fn main() -> Result<(), Box> { + let mut args = std::env::args().skip(1); + let mut listen: SocketAddr = "127.0.0.1:7443".parse()?; + let mut instances = Vec::new(); + while let Some(arg) = args.next() { + match arg.as_str() { + "--listen" => listen = args.next().ok_or("--listen needs an address")?.parse()?, + "--instance" => { + let id = args.next().ok_or("--instance needs an id")?; + let token_file = args.next().ok_or("--instance needs a token file")?; + instances.push((id, std::fs::read_to_string(token_file)?.trim().to_string())); + } + other => return Err(format!("unknown argument {other}").into()), + } + } + + let mut server = serve(BasicPolicy); + for (id, token) in instances { + server = server.instance(id, token); + } + println!("basic-policy listening on {listen}"); + server.run(listen).await?; + Ok(()) +} diff --git a/crates/guardian-module-sdk/examples/note-policy-serve.rs b/crates/guardian-module-sdk/examples/note-policy-serve.rs new file mode 100644 index 00000000..4d39de15 --- /dev/null +++ b/crates/guardian-module-sdk/examples/note-policy-serve.rs @@ -0,0 +1,35 @@ +//! The `note-policy` module served over gRPC, for the Guardian to call as a remote module. +//! Walkthrough in `docs/guides/policy-modules/custom.md`. +//! +//! ```text +//! cargo run -p guardian-module-sdk --example note-policy-serve -- \ +//! --listen 127.0.0.1:7444 --instance note-policy +//! ``` + +mod note_policy; + +use std::net::SocketAddr; + +use guardian_module_sdk::serve::serve; +use note_policy::NotePolicy; + +#[tokio::main] +async fn main() -> Result<(), Box> { + let mut args = std::env::args().skip(1); + let mut listen: SocketAddr = "127.0.0.1:7444".parse()?; + let mut server = serve(NotePolicy); + while let Some(arg) = args.next() { + match arg.as_str() { + "--listen" => listen = args.next().ok_or("--listen needs an address")?.parse()?, + "--instance" => { + let id = args.next().ok_or("--instance needs an id")?; + let token_file = args.next().ok_or("--instance needs a token file")?; + server = server.instance(id, std::fs::read_to_string(token_file)?.trim()); + } + other => return Err(format!("unknown argument {other}").into()), + } + } + println!("note-policy listening on {listen}"); + server.run(listen).await?; + Ok(()) +} diff --git a/crates/guardian-module-sdk/examples/note_policy/mod.rs b/crates/guardian-module-sdk/examples/note_policy/mod.rs new file mode 100644 index 00000000..26e938c0 --- /dev/null +++ b/crates/guardian-module-sdk/examples/note_policy/mod.rs @@ -0,0 +1,184 @@ +//! The `note-policy` module: limits how many payment notes a transaction may create and can +//! refuse private notes, whose recipients the Guardian cannot see. Shared by the gRPC example +//! (`note-policy-serve`) and the in-process one (`guardian-server`'s `custom_module_server`). + +// Each including example uses only part of this file. +#![allow(dead_code)] + +use std::sync::Arc; + +use async_trait::async_trait; +use guardian_module_sdk::proto::hook_request; +use guardian_module_sdk::{ + Decision, DescribeRequest, Hook, HookRequest, Module, ModuleError, ModuleFactory, ModuleInfo, + ModuleInstanceConfig, NoteType, PROTOCOL_VERSION, ParamsVerdict, +}; +use serde::Deserialize; + +pub const KIND: &str = "note-policy"; + +/// The module's own version, reported by `describe`. Not the crate version: this file is +/// compiled into both the SDK example and a server build. +pub const VERSION: &str = "1.0.0"; + +#[derive(Debug, Deserialize)] +#[serde(deny_unknown_fields)] +struct Params { + max_payment_notes: Option, + #[serde(default)] + deny_private_notes: bool, +} + +fn parse(params: &[u8]) -> Result { + serde_json::from_slice(params).map_err(|e| e.to_string()) +} + +pub struct NotePolicy; + +#[async_trait] +impl Module for NotePolicy { + async fn describe(&self, _guardian: &DescribeRequest) -> Result { + Ok(ModuleInfo { + name: KIND.into(), + version: VERSION.into(), + protocol_version: PROTOCOL_VERSION, + hooks: vec![ + Hook::BeforeProposalCreated as i32, + Hook::BeforeTransactionApproved as i32, + ], + ..Default::default() + }) + } + + async fn validate_params(&self, params: &[u8]) -> Result { + Ok(match parse(params) { + Ok(_) => ParamsVerdict::ok(), + Err(message) => ParamsVerdict::invalid(message), + }) + } + + async fn evaluate(&self, request: &HookRequest) -> Result { + let params = parse(&request.params).map_err(ModuleError::InvalidRequest)?; + let Some(hook_request::Subject::Transaction(subject)) = &request.subject else { + return Ok(Decision::allow()); + }; + let Some(projection) = subject.miden() else { + return Err(ModuleError::InvalidRequest( + "not a Miden transaction".into(), + )); + }; + let payments: Vec<_> = projection + .output_notes + .iter() + .filter(|note| !note.tx_fee) + .collect(); + + if params.deny_private_notes + && payments + .iter() + .any(|note| note.note_type == NoteType::Private as i32) + { + return Ok(Decision::deny( + "private_note_not_allowed", + "the transaction creates a private note", + )); + } + if let Some(max) = params.max_payment_notes + && payments.len() > max as usize + { + return Ok(Decision::deny( + "too_many_payment_notes", + format!("{} payment notes, at most {max} allowed", payments.len()), + )); + } + Ok(Decision::allow()) + } +} + +/// Creates the module for a catalog instance of kind `note-policy` running in process. +pub struct NotePolicyFactory; + +impl ModuleFactory for NotePolicyFactory { + fn create(&self, _instance: &ModuleInstanceConfig) -> Result, ModuleError> { + Ok(Arc::new(NotePolicy)) + } +} + +#[cfg(test)] +mod tests { + use guardian_module_sdk::{ + MidenTransaction, OutputNote, TransactionProjection, TransactionSubject, + }; + + use super::*; + + fn request(params: serde_json::Value, notes: Vec) -> HookRequest { + HookRequest { + params: serde_json::to_vec(¶ms).unwrap(), + subject: Some(hook_request::Subject::Transaction(TransactionSubject { + projection: Some(TransactionProjection::miden(MidenTransaction { + output_notes: notes, + ..Default::default() + })), + ..Default::default() + })), + ..Default::default() + } + } + + fn note(note_type: NoteType, tx_fee: bool) -> OutputNote { + OutputNote { + note_type: note_type as i32, + tx_fee, + ..Default::default() + } + } + + #[tokio::test] + async fn counts_payments_but_not_the_fee_note() { + let params = serde_json::json!({ "max_payment_notes": 1 }); + let one_payment = vec![note(NoteType::Public, false), note(NoteType::Public, true)]; + assert!( + NotePolicy + .evaluate(&request(params.clone(), one_payment)) + .await + .unwrap() + .allow + ); + let two_payments = vec![note(NoteType::Public, false), note(NoteType::Public, false)]; + let decision = NotePolicy + .evaluate(&request(params, two_payments)) + .await + .unwrap(); + assert_eq!(decision.reason_code, "too_many_payment_notes"); + } + + #[tokio::test] + async fn refuses_private_notes_when_asked() { + let notes = vec![note(NoteType::Private, false)]; + let decision = NotePolicy + .evaluate(&request( + serde_json::json!({ "deny_private_notes": true }), + notes.clone(), + )) + .await + .unwrap(); + assert_eq!(decision.reason_code, "private_note_not_allowed"); + assert!( + NotePolicy + .evaluate(&request(serde_json::json!({}), notes)) + .await + .unwrap() + .allow + ); + } + + #[tokio::test] + async fn unknown_params_are_invalid() { + let verdict = NotePolicy + .validate_params(br#"{"max_notes": 1}"#) + .await + .unwrap(); + assert!(!verdict.ok); + } +} diff --git a/crates/guardian-module-sdk/proto/guardian_module_v1.proto b/crates/guardian-module-sdk/proto/guardian_module_v1.proto new file mode 100644 index 00000000..b6ccb0fa --- /dev/null +++ b/crates/guardian-module-sdk/proto/guardian_module_v1.proto @@ -0,0 +1,222 @@ +syntax = "proto3"; +package guardian.module.v1; + +import "google/protobuf/timestamp.proto"; + +service GuardianModule { + rpc Describe(DescribeRequest) returns (ModuleInfo); + rpc ValidateParams(ValidateParamsRequest) returns (ParamsVerdict); + rpc Evaluate(HookRequest) returns (Decision); + rpc Notify(CommitEvent) returns (NotifyAck); + rpc NotifyGap(Gap) returns (NotifyAck); +} + +enum Hook { + HOOK_UNSPECIFIED = 0; + HOOK_BEFORE_TRANSACTION_APPROVED = 1; + HOOK_BEFORE_ACCOUNT_REGISTERED = 2; + HOOK_AFTER_TRANSACTION_COMMITTED = 3; + HOOK_BEFORE_PROPOSAL_CREATED = 4; +} + +message DescribeRequest { + uint32 guardian_protocol_version = 1; // the newest protocol version the Guardian speaks + uint32 guardian_min_protocol_version = 2; // the oldest it still accepts (section 3.5) + repeated string guardian_capabilities = 3; // optional features this Guardian provides +} +message ModuleInfo { + string name = 1; + string version = 2; + uint32 protocol_version = 3; // must lie in the Guardian's supported range + repeated Hook hooks = 4; + repeated string required_capabilities = 5; // startup fails if the Guardian lacks one +} +message ValidateParamsRequest { bytes params = 1; string instance_id = 2; } // params: UTF-8 JSON +message ParamsVerdict { + bool ok = 1; + string message = 2; + bytes normalized_params = 3; // UTF-8 JSON; empty: store the params as sent. Lets a module migrate params it still accepts to its current shape +} +message NotifyAck {} + +message Gap { + string account_id = 1; + string network = 2; + google.protobuf.Timestamp dropped_before = 3; // restart position: events for the account committed before this and not acknowledged may be missing + string instance_id = 4; + uint64 resume_from_nonce = 5; // first nonce delivered after the gap; the module's watermark becomes resume_from_nonce - 1 (section 3.3) +} + +message HookRequest { + string request_id = 1; + Hook hook = 2; + string network = 3; // "miden" + string account_id = 4; + bytes params = 5; // UTF-8 JSON, params of the layer being evaluated (global, account layer, or the account's own for default/assigned) + string instance_id = 6; // catalog id of the instance being called + google.protobuf.Timestamp accounting_time = 7; // recorded as signed_at if this transaction is signed (section 3.4); at before_proposal_created, the evaluation time, never recorded + string submitter = 8; // signer commitment that authenticated this request; verified (section 3.2) + oneof subject { // hook-specific detail only + TransactionSubject transaction = 10; + RegistrationSubject registration = 11; + } + optional AccountView before = 12; // the account as the Guardian holds it; absent for a new registration (section 3.2) + AccountView after = 13; // the account as it will be if every module allows (section 3.2) +} + +message AccountView { + string commitment = 1; + string auth_scheme = 2; // the signers' common scheme, "falcon" or "ecdsa", or "mixed" + repeated string signer_commitments = 3; + reserved 4; // was threshold; renamed default_threshold + reserved "threshold"; + optional uint32 default_threshold = 5; // absent for single-key accounts + map procedure_thresholds = 6; // procedure root -> threshold overriding the default; empty when none + map signer_schemes = 7; // signer commitment -> "falcon" or "ecdsa"; one entry per signer +} + +message TransactionSubject { + reserved 1, 2; // were prev_commitment and new_commitment; now before.commitment and after.commitment + reserved "prev_commitment", "new_commitment"; + reserved 3, 4; // were the Miden-only projection and raw_tx_summary; now the network-tagged fields below + reserved "raw_tx_summary"; + TransactionProjection projection = 10; // the contract modules should rely on, per network + RawTransaction raw = 11; // the network's own encoding; UNSTABLE across that network's protocol bumps + reserved 5; // was unverified_hint; replaced by unverified_metadata + reserved "unverified_hint"; + repeated PendingTransaction pending = 6; // signed for this account, not yet acknowledged by this module (section 3.4) + reserved 7; // was submitter; now HookRequest.submitter + reserved "submitter"; + string proposer = 8; // signer commitment that created the matching proposal; verified; empty when there is none (section 3.2) + bytes unverified_metadata = 9; // UTF-8 JSON, proposer-asserted proposal metadata; never authoritative; UNSTABLE across SDK releases (section 3.2) +} + +message PendingTransaction { + string new_commitment = 1; // = event_id once committed + reserved 2; // was the Miden-only projection + TransactionProjection projection = 9; + google.protobuf.Timestamp signed_at = 3; // the accounting clock (section 3.4) + PendingState state = 4; + uint64 nonce = 5; // account nonce after this transaction; compared with the module's watermark + optional google.protobuf.Timestamp committed_at = 6; // set when state = committed + string submitter = 7; // as in HookRequest at the ack that signed this transaction; verified (section 3.2) + string proposer = 8; // as in TransactionSubject at that ack; empty when there was no matching proposal +} +enum PendingState { + PENDING_STATE_UNSPECIFIED = 0; + PENDING_STATE_CANDIDATE = 1; // signed, waiting to become committed + PENDING_STATE_COMMITTED = 2; // committed, notify not yet acknowledged by this module +} + +message RegistrationSubject { + reserved 1 to 4, 6; // auth_scheme, signer_commitments, threshold and initial_state_commitment moved to HookRequest.after; submitter to HookRequest.submitter + reserved "auth_scheme", "signer_commitments", "threshold", "initial_state_commitment", "submitter"; + reserved 5; // was the Miden-only initial_state + AccountStateProjection initial_state = 7; // the account about to be accepted, per network +} + +enum Effect { + EFFECT_UNSPECIFIED = 0; // a module that predates `effect`: `allow` decides + EFFECT_ALLOW = 1; + EFFECT_DENY = 2; +} + +message Decision { + bool allow = 1; // read only when effect is unspecified + string reason_code = 2; // required on a deny; ignored on an allow + string message = 3; // logged, never forwarded to clients + Effect effect = 4; // wins over allow when set; a value the Guardian does not know is a module failure + string client_message = 5; // optional, plain text, at most 256 characters; forwarded only where the instance allows it +} + +// A transaction as its network describes it. One variant per network; a module reads the +// variant for the networks it supports. +message TransactionProjection { + oneof network { + MidenTransaction miden = 1; + } +} + +// An account's state as its network describes it. +message AccountStateProjection { + oneof network { + MidenAccountState miden = 1; + } +} + +// A transaction in its network's own serialization, for modules that decode it themselves. +message RawTransaction { + string encoding = 1; // names the format and its version line, for example "miden.transaction_summary" + bytes data = 2; +} + +message MidenTransaction { + reserved 1; // was version; protocol_version covers the projection + reserved "version"; // the JSON name cannot be reused either (matters for the proto3 JSON mapping) + int64 nonce_delta = 2; + uint32 expiration_block = 3; + repeated VaultChange vault_changes = 4; + repeated OutputNote output_notes = 5; + repeated InputNote input_notes = 6; + repeated StorageChange storage_changes = 7; +} + +message MidenAccountState { + repeated Asset vault = 1; + repeated StorageSlot storage = 2; +} + +message Asset { + string faucet_id = 1; + oneof value { string fungible_amount = 2; string nft_id = 3; } // amounts as decimal strings +} + +message VaultChange { Asset asset = 1; Direction direction = 2; } +enum Direction { DIRECTION_UNSPECIFIED = 0; DIRECTION_IN = 1; DIRECTION_OUT = 2; } + +message OutputNote { + string note_id = 1; + NoteType note_type = 2; + bool partial = 3; // only the recipient digest is known + string recipient_digest = 4; + repeated Asset assets = 5; + string script_root = 6; + optional string p2id_target = 7; // set only for known P2ID / P2IDE scripts + bool tx_fee = 8; // the fee note pay_fee creates; not a payment +} +enum NoteType { NOTE_TYPE_UNSPECIFIED = 0; NOTE_TYPE_PUBLIC = 1; NOTE_TYPE_PRIVATE = 2; } + +message InputNote { string note_id = 1; repeated Asset assets = 2; } + +message StorageChange { + string slot_name = 1; // StorageSlotName, e.g. "miden::standards::auth::multisig::threshold_config" + StorageSlotKind kind = 2; + StorageOp op = 3; + string value = 4; // kind = value, op = create or update: the new value + MapChanges map = 5; // kind = map, op = create: initial entries; op = update: changed entries +} +enum StorageSlotKind { STORAGE_SLOT_KIND_UNSPECIFIED = 0; STORAGE_SLOT_KIND_VALUE = 1; STORAGE_SLOT_KIND_MAP = 2; } +enum StorageOp { STORAGE_OP_UNSPECIFIED = 0; STORAGE_OP_CREATE = 1; STORAGE_OP_UPDATE = 2; STORAGE_OP_REMOVE = 3; } +message MapChanges { repeated MapEntry entries = 1; } +message MapEntry { string key = 1; string value = 2; } // value = empty word: the entry was removed +message StorageSlot { + string slot_name = 1; + StorageSlotKind kind = 2; + oneof content { string value = 3; MapChanges map = 4; } +} + +message CommitEvent { + string event_id = 1; // = new_commitment; stable across redelivery + string account_id = 2; + string prev_commitment = 3; + string new_commitment = 4; + reserved 5; // was the Miden-only projection + TransactionProjection projection = 13; + google.protobuf.Timestamp committed_at = 6; + string network = 7; // "miden", as in HookRequest + uint64 nonce = 8; // account nonce after this transaction; the delivery watermark (section 3.3) + google.protobuf.Timestamp signed_at = 9; // the accounting clock, identical to the value the module saw in pending (section 3.4) + string instance_id = 10; + string submitter = 11; // as in HookRequest at the ack that signed this transaction; verified (section 3.2) + string proposer = 12; // as in TransactionSubject at that ack; empty when there was no matching proposal (section 3.2) +} diff --git a/crates/guardian-module-sdk/src/basic_policy.rs b/crates/guardian-module-sdk/src/basic_policy.rs new file mode 100644 index 00000000..41cf3957 --- /dev/null +++ b/crates/guardian-module-sdk/src/basic_policy.rs @@ -0,0 +1,591 @@ +//! Reference policy: per-asset amount cap, asset and recipient allowlists, signer lists. + +use std::collections::{BTreeMap, BTreeSet}; + +use async_trait::async_trait; +use serde::Deserialize; + +use crate::proto::{asset, hook_request}; +use crate::{ + AccountView, Decision, DescribeRequest, Hook, HookRequest, Module, ModuleError, ModuleInfo, + PROTOCOL_VERSION, ParamsVerdict, TransactionSubject, +}; + +pub const KIND: &str = "basic-policy"; + +#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum SignerCheck { + #[default] + Added, + All, +} + +#[derive(Debug, Clone, Default, Deserialize)] +#[serde(deny_unknown_fields)] +pub struct Params { + #[serde(default)] + pub max_amount_per_tx: BTreeMap, + #[serde(default)] + pub asset_allowlist: Option>, + #[serde(default)] + pub recipient_allowlist: Option>, + #[serde(default)] + pub recipient_denylist: Option>, + #[serde(default)] + pub deny_unknown_recipients: bool, + #[serde(default)] + pub signer_allowlist: Option>, + #[serde(default)] + pub signer_denylist: Option>, + #[serde(default)] + pub signer_check: SignerCheck, +} + +struct Policy { + caps: BTreeMap, + assets: Option>, + recipients: Option>, + blocked_recipients: Option>, + deny_unknown_recipients: bool, + signers: Option, + signer_check: SignerCheck, +} + +enum SignerList { + Allow(BTreeSet), + Deny(BTreeSet), +} + +impl SignerList { + fn permits(&self, signer: &str) -> bool { + match self { + SignerList::Allow(list) => list.contains(signer), + SignerList::Deny(list) => !list.contains(signer), + } + } +} + +fn normalized(values: &[String]) -> BTreeSet { + values.iter().map(|v| v.to_ascii_lowercase()).collect() +} + +impl TryFrom for Policy { + type Error = String; + + fn try_from(params: Params) -> Result { + let caps = params + .max_amount_per_tx + .into_iter() + .map(|(faucet, amount)| { + amount + .parse::() + .map(|amount| (faucet.to_ascii_lowercase(), amount)) + .map_err(|_| format!("max_amount_per_tx for {faucet} is not a decimal amount")) + }) + .collect::>()?; + let signers = match (params.signer_allowlist, params.signer_denylist) { + (Some(_), Some(_)) => { + return Err("signer_allowlist and signer_denylist are mutually exclusive".into()); + } + (Some(list), None) => Some(SignerList::Allow(normalized(&list))), + (None, Some(list)) => Some(SignerList::Deny(normalized(&list))), + (None, None) => None, + }; + Ok(Self { + caps, + assets: params.asset_allowlist.as_deref().map(normalized), + recipients: params.recipient_allowlist.as_deref().map(normalized), + blocked_recipients: params.recipient_denylist.as_deref().map(normalized), + deny_unknown_recipients: params.deny_unknown_recipients, + signers, + signer_check: params.signer_check, + }) + } +} + +fn parse_policy(params: &[u8]) -> Result { + let params: Params = if params.is_empty() { + Params::default() + } else { + serde_json::from_slice(params).map_err(|e| e.to_string())? + }; + Policy::try_from(params) +} + +impl Policy { + fn evaluate(&self, request: &HookRequest) -> Result { + if let Some(signers) = &self.signers { + let after = request + .after + .as_ref() + .ok_or_else(|| ModuleError::InvalidRequest("request has no account view".into()))?; + if let Some(signer) = self + .checked_signers(request.before.as_ref(), after) + .into_iter() + .find(|signer| !signers.permits(signer)) + { + return Ok(Decision::deny( + "signer_not_allowed", + format!("signer {signer} is not permitted"), + )); + } + } + match &request.subject { + Some(hook_request::Subject::Transaction(tx)) => Ok(self.evaluate_transaction(tx)), + Some(hook_request::Subject::Registration(_)) => Ok(Decision::allow()), + None => Err(ModuleError::InvalidRequest("request has no subject".into())), + } + } + + fn checked_signers(&self, before: Option<&AccountView>, after: &AccountView) -> Vec { + let existing: BTreeSet = match (self.signer_check, before) { + (SignerCheck::Added, Some(before)) => normalized(&before.signer_commitments), + _ => BTreeSet::new(), + }; + normalized(&after.signer_commitments) + .into_iter() + .filter(|signer| !existing.contains(signer)) + .collect() + } + + fn evaluate_transaction(&self, tx: &TransactionSubject) -> Decision { + let Some(projection) = tx.miden() else { + return Decision::deny("projection_missing", "transaction has no Miden projection"); + }; + + let payments = || projection.output_notes.iter().filter(|note| !note.tx_fee); + + if let Some(allowed) = &self.assets { + let sent = payments().flat_map(|n| n.assets.iter()); + let received = projection.input_notes.iter().flat_map(|n| n.assets.iter()); + if let Some(faucet) = sent + .chain(received) + .map(|a| a.faucet_id.to_ascii_lowercase()) + .find(|faucet| !allowed.contains(faucet)) + { + return Decision::deny( + "asset_not_allowed", + format!("asset {faucet} is not allowed"), + ); + } + } + + if let Some(allowed) = &self.recipients { + for note in payments() { + let recipient = match (¬e.p2id_target, note.partial) { + (Some(target), false) => target.to_ascii_lowercase(), + _ => { + return Decision::deny( + "recipient_not_allowed", + format!("note {} has no checkable recipient", note.note_id), + ); + } + }; + if !allowed.contains(&recipient) { + return Decision::deny( + "recipient_not_allowed", + format!("recipient {recipient} is not allowed"), + ); + } + } + } + + if let Some(blocked) = &self.blocked_recipients { + for note in payments() { + match (¬e.p2id_target, note.partial) { + (Some(target), false) if blocked.contains(&target.to_ascii_lowercase()) => { + return Decision::deny( + "recipient_blocked", + format!("recipient {target} is blocked"), + ); + } + (Some(_), false) => {} + _ if self.deny_unknown_recipients => { + return Decision::deny( + "recipient_not_allowed", + format!("note {} has no checkable recipient", note.note_id), + ); + } + _ => {} + } + } + } + + if !self.caps.is_empty() { + let mut sent: BTreeMap = BTreeMap::new(); + for asset in payments().flat_map(|n| n.assets.iter()) { + if let Some(asset::Value::FungibleAmount(amount)) = &asset.value { + let amount = amount.parse::().unwrap_or(u128::MAX); + let total = sent + .entry(asset.faucet_id.to_ascii_lowercase()) + .or_default(); + *total = total.saturating_add(amount); + } + } + for (faucet, cap) in &self.caps { + if sent.get(faucet).is_some_and(|total| total > cap) { + return Decision::deny( + "amount_cap_exceeded", + format!("sent {} of {faucet}, cap {cap}", sent[faucet]), + ); + } + } + } + + Decision::allow() + } +} + +#[derive(Debug, Default, Clone, Copy)] +pub struct BasicPolicy; + +#[async_trait] +impl Module for BasicPolicy { + async fn describe(&self, _guardian: &DescribeRequest) -> Result { + Ok(ModuleInfo { + name: KIND.into(), + version: env!("CARGO_PKG_VERSION").into(), + protocol_version: PROTOCOL_VERSION, + hooks: vec![ + Hook::BeforeTransactionApproved as i32, + Hook::BeforeProposalCreated as i32, + Hook::BeforeAccountRegistered as i32, + ], + ..Default::default() + }) + } + + async fn validate_params(&self, params: &[u8]) -> Result { + Ok(match parse_policy(params) { + Ok(_) => ParamsVerdict::ok(), + Err(message) => ParamsVerdict::invalid(message), + }) + } + + async fn evaluate(&self, request: &HookRequest) -> Result { + parse_policy(&request.params) + .map_err(ModuleError::InvalidRequest)? + .evaluate(request) + } +} + +#[cfg(test)] +mod tests { + use serde_json::json; + + use super::*; + use crate::{ + Asset, MidenTransaction, OutputNote, RegistrationSubject, TransactionProjection, + VaultChange, + }; + + const USDC: &str = "0xaa00"; + const ETH: &str = "0xbb00"; + + fn fungible(faucet: &str, amount: u64) -> Asset { + Asset { + faucet_id: faucet.into(), + value: Some(asset::Value::FungibleAmount(amount.to_string())), + } + } + + fn p2id(target: &str, assets: Vec) -> OutputNote { + OutputNote { + note_id: format!("0xnote{target}"), + assets, + p2id_target: Some(target.into()), + ..Default::default() + } + } + + fn view(signers: &[&str]) -> AccountView { + AccountView { + signer_commitments: signers.iter().map(|s| s.to_string()).collect(), + ..Default::default() + } + } + + fn tx_request(params: serde_json::Value, projection: MidenTransaction) -> HookRequest { + HookRequest { + params: serde_json::to_vec(¶ms).unwrap(), + before: Some(view(&["0xs1"])), + after: Some(view(&["0xs1"])), + subject: Some(hook_request::Subject::Transaction(TransactionSubject { + projection: Some(TransactionProjection::miden(projection)), + ..Default::default() + })), + ..Default::default() + } + } + + async fn decide(request: &HookRequest) -> Decision { + BasicPolicy.evaluate(request).await.unwrap() + } + + fn cap() -> serde_json::Value { + json!({ "max_amount_per_tx": { USDC: "1000" } }) + } + + #[tokio::test] + async fn allows_a_payment_under_the_cap() { + let projection = MidenTransaction { + output_notes: vec![p2id("0xr1", vec![fungible(USDC, 500)])], + ..Default::default() + }; + assert!(decide(&tx_request(cap(), projection)).await.allow); + } + + #[tokio::test] + async fn sums_split_payments_against_the_cap() { + let projection = MidenTransaction { + output_notes: vec![ + p2id("0xr1", vec![fungible(USDC, 600)]), + p2id("0xr2", vec![fungible(USDC, 600)]), + ], + ..Default::default() + }; + let decision = decide(&tx_request(cap(), projection)).await; + assert!(!decision.allow); + assert_eq!(decision.reason_code, "amount_cap_exceeded"); + } + + #[tokio::test] + async fn incoming_amounts_do_not_offset_outgoing() { + let projection = MidenTransaction { + vault_changes: vec![VaultChange { + asset: Some(fungible(USDC, 500)), + direction: crate::Direction::Out as i32, + }], + input_notes: vec![crate::InputNote { + note_id: "0xin".into(), + assets: vec![fungible(USDC, 1000)], + }], + output_notes: vec![p2id("0xr1", vec![fungible(USDC, 1500)])], + ..Default::default() + }; + assert!(!decide(&tx_request(cap(), projection)).await.allow); + } + + #[tokio::test] + async fn uncapped_assets_and_nfts_are_not_counted() { + let nft = Asset { + faucet_id: USDC.into(), + value: Some(asset::Value::NftId("0xnft".into())), + }; + let projection = MidenTransaction { + output_notes: vec![p2id("0xr1", vec![fungible(ETH, 5000), nft])], + ..Default::default() + }; + assert!(decide(&tx_request(cap(), projection)).await.allow); + } + + fn fee_note(amount: u64) -> OutputNote { + OutputNote { + note_id: "0xfee".into(), + assets: vec![fungible(USDC, amount)], + tx_fee: true, + ..Default::default() + } + } + + #[tokio::test] + async fn the_fee_note_is_not_a_payment() { + let projection = MidenTransaction { + output_notes: vec![fee_note(5000), p2id("0xr1", vec![fungible(USDC, 500)])], + ..Default::default() + }; + assert!(decide(&tx_request(cap(), projection.clone())).await.allow); + + let params = json!({ "recipient_allowlist": ["0xr1"], "asset_allowlist": [ETH, USDC] }); + assert!(decide(&tx_request(params, projection)).await.allow); + + let only_fee = MidenTransaction { + output_notes: vec![fee_note(5000)], + ..Default::default() + }; + assert!( + decide(&tx_request(json!({ "asset_allowlist": [ETH] }), only_fee)) + .await + .allow + ); + } + + #[tokio::test] + async fn recipient_allowlist_denies_partial_and_unlisted_notes() { + let params = json!({ "recipient_allowlist": ["0xr1"] }); + let listed = MidenTransaction { + output_notes: vec![p2id("0xR1", vec![fungible(USDC, 1)])], + ..Default::default() + }; + assert!(decide(&tx_request(params.clone(), listed)).await.allow); + + let mut partial_note = p2id("0xr1", vec![fungible(USDC, 1)]); + partial_note.partial = true; + let partial = MidenTransaction { + output_notes: vec![partial_note], + ..Default::default() + }; + assert_eq!( + decide(&tx_request(params.clone(), partial)) + .await + .reason_code, + "recipient_not_allowed" + ); + + let unlisted = MidenTransaction { + output_notes: vec![p2id("0xr9", vec![fungible(USDC, 1)])], + ..Default::default() + }; + assert!(!decide(&tx_request(params, unlisted)).await.allow); + } + + #[tokio::test] + async fn asset_allowlist_covers_sent_and_received_assets() { + let params = json!({ "asset_allowlist": [USDC] }); + let projection = MidenTransaction { + output_notes: vec![p2id("0xr1", vec![fungible(ETH, 1)])], + ..Default::default() + }; + assert_eq!( + decide(&tx_request(params, projection)).await.reason_code, + "asset_not_allowed" + ); + } + + #[tokio::test] + async fn recipient_denylist_blocks_listed_recipients_only() { + let params = json!({ "recipient_denylist": ["0xBAD"] }); + let blocked = MidenTransaction { + output_notes: vec![fee_note(1), p2id("0xbad", vec![fungible(USDC, 1)])], + ..Default::default() + }; + assert_eq!( + decide(&tx_request(params.clone(), blocked)) + .await + .reason_code, + "recipient_blocked" + ); + + let mut partial = p2id("0xr1", vec![fungible(USDC, 1)]); + partial.partial = true; + let unknown = MidenTransaction { + output_notes: vec![p2id("0xr1", vec![fungible(USDC, 1)]), partial], + ..Default::default() + }; + assert!(decide(&tx_request(params, unknown.clone())).await.allow); + + let strict = json!({ "recipient_denylist": ["0xbad"], "deny_unknown_recipients": true }); + assert_eq!( + decide(&tx_request(strict, unknown)).await.reason_code, + "recipient_not_allowed" + ); + } + + #[tokio::test] + async fn asset_allowlist_covers_consumed_notes() { + let projection = MidenTransaction { + input_notes: vec![crate::InputNote { + note_id: "0xin".into(), + assets: vec![fungible(ETH, 1)], + }], + ..Default::default() + }; + assert_eq!( + decide(&tx_request( + json!({ "asset_allowlist": [USDC] }), + projection + )) + .await + .reason_code, + "asset_not_allowed" + ); + } + + #[tokio::test] + async fn forged_metadata_does_not_change_the_decision() { + let projection = MidenTransaction { + output_notes: vec![p2id("0xr1", vec![fungible(USDC, 5000)])], + ..Default::default() + }; + let mut request = tx_request(cap(), projection); + if let Some(hook_request::Subject::Transaction(tx)) = &mut request.subject { + tx.unverified_metadata = + serde_json::to_vec(&json!({ "proposal_type": "change_threshold", "amount": "1" })) + .unwrap(); + } + assert!(!decide(&request).await.allow); + } + + fn signer_request( + params: serde_json::Value, + before: Option<&[&str]>, + after: &[&str], + ) -> HookRequest { + HookRequest { + params: serde_json::to_vec(¶ms).unwrap(), + before: before.map(view), + after: Some(view(after)), + subject: Some(hook_request::Subject::Registration( + RegistrationSubject::default(), + )), + ..Default::default() + } + } + + #[tokio::test] + async fn added_mode_checks_only_new_signers() { + let params = json!({ "signer_allowlist": ["0xs2"] }); + let request = signer_request(params.clone(), Some(&["0xs1"]), &["0xs1", "0xs2"]); + assert!(decide(&request).await.allow); + + let request = signer_request(params, Some(&["0xs1"]), &["0xs1", "0xs3"]); + assert_eq!(decide(&request).await.reason_code, "signer_not_allowed"); + } + + #[tokio::test] + async fn all_mode_checks_every_signer() { + let params = json!({ "signer_check": "all", "signer_allowlist": ["0xs2"] }); + let request = signer_request(params, Some(&["0xs1"]), &["0xs1", "0xs2"]); + assert!(!decide(&request).await.allow); + } + + #[tokio::test] + async fn registration_checks_every_initial_signer() { + let params = json!({ "signer_denylist": ["0xbad"] }); + let request = signer_request(params, None, &["0xs1", "0xBAD"]); + assert!(!decide(&request).await.allow); + } + + #[tokio::test] + async fn missing_account_view_is_an_error_not_an_allow() { + let mut request = signer_request(json!({ "signer_allowlist": ["0xs1"] }), None, &[]); + request.after = None; + assert!(BasicPolicy.evaluate(&request).await.is_err()); + } + + #[tokio::test] + async fn validate_params_rejects_bad_input() { + for params in [ + json!({ "unknown": 1 }), + json!({ "max_amount_per_tx": { USDC: "ten" } }), + json!({ "signer_allowlist": [], "signer_denylist": [] }), + ] { + let verdict = BasicPolicy + .validate_params(&serde_json::to_vec(¶ms).unwrap()) + .await + .unwrap(); + assert!(!verdict.ok, "{params}"); + } + } + + #[tokio::test] + async fn evaluating_twice_gives_the_same_decision() { + let projection = MidenTransaction { + output_notes: vec![p2id("0xr1", vec![fungible(USDC, 900)])], + ..Default::default() + }; + let request = tx_request(cap(), projection); + assert_eq!(decide(&request).await, decide(&request).await); + } +} diff --git a/crates/guardian-module-sdk/src/lib.rs b/crates/guardian-module-sdk/src/lib.rs new file mode 100644 index 00000000..5cc1d3c4 --- /dev/null +++ b/crates/guardian-module-sdk/src/lib.rs @@ -0,0 +1,313 @@ +//! Interface, protocol types and serving harness for Guardian policy modules. + +use std::sync::Arc; + +use async_trait::async_trait; + +pub mod basic_policy; +pub mod serve; + +pub use prost_types; +pub use secrecy; + +pub mod proto { + tonic::include_proto!("guardian.module.v1"); +} + +pub use proto::{ + AccountStateProjection, AccountView, Asset, CommitEvent, Decision, DescribeRequest, Direction, + Effect, Gap, Hook, HookRequest, InputNote, MidenAccountState, MidenTransaction, ModuleInfo, + NoteType, OutputNote, ParamsVerdict, PendingTransaction, RawTransaction, RegistrationSubject, + StorageChange, StorageOp, StorageSlotKind, TransactionProjection, TransactionSubject, + ValidateParamsRequest, VaultChange, +}; + +pub const PROTOCOL_VERSION: u32 = 1; + +/// Optional protocol features, named in `DescribeRequest.guardian_capabilities` and +/// `ModuleInfo.required_capabilities`. New features are added as capabilities, not as a new +/// protocol version, so modules and Guardians of one major version keep working together. +pub mod capability { + /// `Decision.effect` is read. + pub const DECISION_EFFECT: &str = "decision.effect"; + /// `ParamsVerdict.normalized_params` is stored. + pub const PARAMS_NORMALIZATION: &str = "params.normalization"; +} + +#[derive(Debug, thiserror::Error)] +#[non_exhaustive] +pub enum ModuleError { + #[error("module unavailable: {0}")] + Unavailable(String), + #[error("invalid request: {0}")] + InvalidRequest(String), + #[error("module error: {0}")] + Internal(String), +} + +#[async_trait] +pub trait Module: Send + Sync { + /// `guardian` carries the Guardian's protocol range and capabilities. + async fn describe(&self, guardian: &DescribeRequest) -> Result; + + async fn validate_params(&self, params: &[u8]) -> Result; + + /// Must be free of side effects: the same transaction is evaluated at proposal creation + /// and again at approval, and clients retry. + async fn evaluate(&self, request: &HookRequest) -> Result; + + async fn notify(&self, _event: &CommitEvent) -> Result<(), ModuleError> { + Ok(()) + } + + async fn notify_gap(&self, _gap: &Gap) -> Result<(), ModuleError> { + Ok(()) + } +} + +#[derive(Debug, Clone)] +#[non_exhaustive] +pub struct ModuleInstanceConfig { + pub id: String, + pub kind: String, + pub endpoint: Option, + pub auth_token: Option, + pub tls: Option, + pub timeout: std::time::Duration, + pub params: serde_json::Value, +} + +/// TLS settings of a remote module: a private CA (the system roots when absent) and an +/// optional client identity for mutual TLS. +impl ModuleInstanceConfig { + pub fn new( + id: impl Into, + kind: impl Into, + timeout: std::time::Duration, + params: serde_json::Value, + ) -> Self { + Self { + id: id.into(), + kind: kind.into(), + endpoint: None, + auth_token: None, + tls: None, + timeout, + params, + } + } + + pub fn with_endpoint(mut self, endpoint: Option) -> Self { + self.endpoint = endpoint; + self + } + + pub fn with_auth_token(mut self, auth_token: Option) -> Self { + self.auth_token = auth_token; + self + } + + pub fn with_tls(mut self, tls: Option) -> Self { + self.tls = tls; + self + } +} + +#[derive(Debug, Clone, Default)] +#[non_exhaustive] +pub struct ModuleTls { + pub ca_pem: Option>, + pub client_identity: Option, +} + +impl ModuleTls { + pub fn new(ca_pem: Option>, client_identity: Option) -> Self { + Self { + ca_pem, + client_identity, + } + } +} + +#[derive(Debug, Clone)] +#[non_exhaustive] +pub struct ClientIdentity { + pub cert_pem: Vec, + pub key_pem: secrecy::SecretString, +} + +impl ClientIdentity { + pub fn new(cert_pem: Vec, key_pem: secrecy::SecretString) -> Self { + Self { cert_pem, key_pem } + } +} + +pub trait ModuleFactory: Send + Sync { + fn create(&self, instance: &ModuleInstanceConfig) -> Result, ModuleError>; +} + +impl TransactionProjection { + pub fn miden(transaction: MidenTransaction) -> Self { + Self { + network: Some(proto::transaction_projection::Network::Miden(transaction)), + } + } +} + +impl AccountStateProjection { + pub fn miden(state: MidenAccountState) -> Self { + Self { + network: Some(proto::account_state_projection::Network::Miden(state)), + } + } +} + +impl RawTransaction { + /// `encoding` of a Miden `TransactionSummary` in Miden's binary serialization. + pub const MIDEN_TRANSACTION_SUMMARY: &str = "miden.transaction_summary"; +} + +fn miden_transaction(projection: &Option) -> Option<&MidenTransaction> { + match projection.as_ref()?.network.as_ref()? { + proto::transaction_projection::Network::Miden(transaction) => Some(transaction), + } +} + +impl TransactionSubject { + /// The Miden projection, when this is a Miden transaction. + pub fn miden(&self) -> Option<&MidenTransaction> { + miden_transaction(&self.projection) + } +} + +impl PendingTransaction { + /// The Miden projection, when this is a Miden transaction. + pub fn miden(&self) -> Option<&MidenTransaction> { + miden_transaction(&self.projection) + } +} + +impl CommitEvent { + /// The Miden projection, when this is a Miden transaction. + pub fn miden(&self) -> Option<&MidenTransaction> { + miden_transaction(&self.projection) + } +} + +impl RegistrationSubject { + /// The Miden account state, when this is a Miden account. + pub fn miden(&self) -> Option<&MidenAccountState> { + match self.initial_state.as_ref()?.network.as_ref()? { + proto::account_state_projection::Network::Miden(state) => Some(state), + } + } +} + +impl Decision { + pub fn allow() -> Self { + Self { + allow: true, + reason_code: String::new(), + message: String::new(), + effect: Effect::Allow as i32, + client_message: String::new(), + } + } + + pub fn deny(reason_code: impl Into, message: impl Into) -> Self { + Self { + allow: false, + reason_code: reason_code.into(), + message: message.into(), + effect: Effect::Deny as i32, + client_message: String::new(), + } + } + + /// Text for the person who sent the request. The Guardian forwards it only for instances + /// whose catalog entry allows it, as plain text of at most 256 characters. + pub fn with_client_message(mut self, client_message: impl Into) -> Self { + self.client_message = client_message.into(); + self + } +} + +impl ParamsVerdict { + pub fn ok() -> Self { + Self { + ok: true, + message: String::new(), + normalized_params: Vec::new(), + } + } + + pub fn invalid(message: impl Into) -> Self { + Self { + ok: false, + message: message.into(), + normalized_params: Vec::new(), + } + } + + /// Valid, and to be stored in the module's current shape: `params` is what the Guardian + /// keeps instead of what the operator or an older catalog sent. + pub fn normalized(params: &serde_json::Value) -> Self { + Self { + ok: true, + message: String::new(), + normalized_params: serde_json::to_vec(params).unwrap_or_default(), + } + } +} + +pub fn is_valid_reason_code(code: &str) -> bool { + (1..=64).contains(&code.len()) + && code + .bytes() + .all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || b == b'_') +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn instance_config_debug_redacts_the_token() { + let config = ModuleInstanceConfig { + id: "remote".into(), + kind: "grpc".into(), + endpoint: None, + auth_token: Some(secrecy::SecretString::from("very-secret-token")), + tls: Some(ModuleTls { + ca_pem: None, + client_identity: Some(ClientIdentity { + cert_pem: Vec::new(), + key_pem: secrecy::SecretString::from("very-secret-key"), + }), + }), + timeout: std::time::Duration::from_millis(10), + params: serde_json::json!({}), + }; + let debug = format!("{config:?}"); + assert!(!debug.contains("very-secret-token")); + assert!(!debug.contains("very-secret-key")); + } + + #[test] + fn the_miden_accessors_read_only_the_miden_variant() { + assert!(TransactionSubject::default().miden().is_none()); + let subject = TransactionSubject { + projection: Some(TransactionProjection::miden(MidenTransaction { + nonce_delta: 1, + ..Default::default() + })), + ..Default::default() + }; + assert_eq!(subject.miden().map(|miden| miden.nonce_delta), Some(1)); + assert!(RegistrationSubject::default().miden().is_none()); + let registration = RegistrationSubject { + initial_state: Some(AccountStateProjection::miden(MidenAccountState::default())), + }; + assert!(registration.miden().is_some()); + } +} diff --git a/crates/guardian-module-sdk/src/serve.rs b/crates/guardian-module-sdk/src/serve.rs new file mode 100644 index 00000000..255d6cf8 --- /dev/null +++ b/crates/guardian-module-sdk/src/serve.rs @@ -0,0 +1,141 @@ +//! gRPC harness exposing any [`Module`] as a `guardian.module.v1.GuardianModule` service. + +use std::collections::HashMap; +use std::net::SocketAddr; +use std::sync::Arc; + +use tonic::{Request, Response, Status}; + +use crate::proto::NotifyAck; +use crate::proto::guardian_module_server::{GuardianModule, GuardianModuleServer}; +use crate::{ + CommitEvent, Decision, DescribeRequest, Gap, HookRequest, Module, ModuleError, ModuleInfo, + ParamsVerdict, ValidateParamsRequest, +}; + +pub fn serve(module: M) -> Serve { + Serve { + module: Arc::new(module), + tokens: HashMap::new(), + } +} + +pub struct Serve { + module: Arc, + tokens: HashMap, +} + +impl Serve { + /// Accept requests for `instance_id` only when they carry `token` as a bearer credential. + /// With no instance registered, every request is accepted. + pub fn instance(mut self, instance_id: impl Into, token: impl Into) -> Self { + self.tokens.insert(instance_id.into(), token.into()); + self + } + + pub fn into_service(self) -> GuardianModuleServer> { + GuardianModuleServer::new(Harness { + module: self.module, + tokens: Arc::new(self.tokens), + }) + } + + pub async fn run(self, addr: SocketAddr) -> Result<(), tonic::transport::Error> { + tonic::transport::Server::builder() + .add_service(self.into_service()) + .serve(addr) + .await + } +} + +pub struct Harness { + module: Arc, + tokens: Arc>, +} + +impl Harness { + fn authorize(&self, request: &Request, instance_id: Option<&str>) -> Result<(), Status> { + if self.tokens.is_empty() { + return Ok(()); + } + let presented = request + .metadata() + .get("authorization") + .and_then(|value| value.to_str().ok()) + .and_then(|value| value.strip_prefix("Bearer ")) + .ok_or_else(|| Status::unauthenticated("missing bearer token"))?; + let accepted = match instance_id { + Some(id) => self.tokens.get(id).is_some_and(|token| token == presented), + None => self.tokens.values().any(|token| token == presented), + }; + if accepted { + Ok(()) + } else { + Err(Status::permission_denied( + "credential does not match the instance", + )) + } + } +} + +fn status(error: ModuleError) -> Status { + match error { + ModuleError::Unavailable(message) => Status::unavailable(message), + ModuleError::InvalidRequest(message) => Status::invalid_argument(message), + ModuleError::Internal(message) => Status::internal(message), + } +} + +#[tonic::async_trait] +impl GuardianModule for Harness { + async fn describe( + &self, + request: Request, + ) -> Result, Status> { + self.authorize(&request, None)?; + self.module + .describe(request.get_ref()) + .await + .map(Response::new) + .map_err(status) + } + + async fn validate_params( + &self, + request: Request, + ) -> Result, Status> { + self.authorize(&request, Some(&request.get_ref().instance_id))?; + self.module + .validate_params(&request.get_ref().params) + .await + .map(Response::new) + .map_err(status) + } + + async fn evaluate(&self, request: Request) -> Result, Status> { + self.authorize(&request, Some(&request.get_ref().instance_id))?; + self.module + .evaluate(request.get_ref()) + .await + .map(Response::new) + .map_err(status) + } + + async fn notify(&self, request: Request) -> Result, Status> { + self.authorize(&request, Some(&request.get_ref().instance_id))?; + self.module + .notify(request.get_ref()) + .await + .map(|()| Response::new(NotifyAck {})) + .map_err(status) + } + + async fn notify_gap(&self, request: Request) -> Result, Status> { + self.authorize(&request, Some(&request.get_ref().instance_id))?; + self.module + .notify_gap(request.get_ref()) + .await + .map(|()| Response::new(NotifyAck {})) + .map_err(status) + } +} diff --git a/crates/guardian-module-sdk/tests/conformance.rs b/crates/guardian-module-sdk/tests/conformance.rs new file mode 100644 index 00000000..773b6abe --- /dev/null +++ b/crates/guardian-module-sdk/tests/conformance.rs @@ -0,0 +1,151 @@ +use guardian_module_sdk::basic_policy::BasicPolicy; +use guardian_module_sdk::proto::guardian_module_client::GuardianModuleClient; +use guardian_module_sdk::proto::{asset, hook_request}; +use guardian_module_sdk::serve::serve; +use guardian_module_sdk::{ + AccountView, Asset, HookRequest, MidenTransaction, Module, OutputNote, TransactionProjection, + TransactionSubject, +}; +use serde_json::json; +use tokio::net::TcpListener; +use tonic::Request; +use tonic::metadata::MetadataValue; +use tonic::transport::server::TcpIncoming; +use tonic::transport::{Channel, Server}; + +const INSTANCE: &str = "caps"; +const TOKEN: &str = "secret-token"; + +async fn start_remote() -> Channel { + let listener = TcpListener::bind("127.0.0.1:0").await.unwrap(); + let addr = listener.local_addr().unwrap(); + let service = serve(BasicPolicy).instance(INSTANCE, TOKEN).into_service(); + tokio::spawn(async move { + Server::builder() + .add_service(service) + .serve_with_incoming(TcpIncoming::from(listener)) + .await + .unwrap(); + }); + Channel::from_shared(format!("http://{addr}")) + .unwrap() + .connect() + .await + .unwrap() +} + +fn authorized(message: T, token: &str) -> Request { + let mut request = Request::new(message); + request.metadata_mut().insert( + "authorization", + MetadataValue::try_from(format!("Bearer {token}")).unwrap(), + ); + request +} + +fn payment(amounts: &[u64], params: serde_json::Value) -> HookRequest { + let notes = amounts + .iter() + .enumerate() + .map(|(i, amount)| OutputNote { + note_id: format!("0x{i}"), + assets: vec![Asset { + faucet_id: "0xaa".into(), + value: Some(asset::Value::FungibleAmount(amount.to_string())), + }], + p2id_target: Some("0xr1".into()), + ..Default::default() + }) + .collect(); + HookRequest { + instance_id: INSTANCE.into(), + params: serde_json::to_vec(¶ms).unwrap(), + after: Some(AccountView::default()), + subject: Some(hook_request::Subject::Transaction(TransactionSubject { + projection: Some(TransactionProjection::miden(MidenTransaction { + output_notes: notes, + ..Default::default() + })), + ..Default::default() + })), + ..Default::default() + } +} + +#[tokio::test] +async fn in_process_and_remote_decisions_match() { + let mut client = GuardianModuleClient::new(start_remote().await); + let cap = json!({ "max_amount_per_tx": { "0xaa": "1000" } }); + let cases = [ + payment(&[500], cap.clone()), + payment(&[600, 600], cap.clone()), + payment(&[1000], cap.clone()), + payment(&[1], json!({ "recipient_allowlist": ["0xother"] })), + ]; + for case in cases { + let local = BasicPolicy.evaluate(&case).await.unwrap(); + let remote = client + .evaluate(authorized(case.clone(), TOKEN)) + .await + .unwrap() + .into_inner(); + assert_eq!(local, remote); + let again = client + .evaluate(authorized(case, TOKEN)) + .await + .unwrap() + .into_inner(); + assert_eq!(remote, again); + } +} + +#[tokio::test] +async fn remote_rejects_a_credential_for_another_instance() { + let mut client = GuardianModuleClient::new(start_remote().await); + let mut request = payment(&[1], json!({})); + request.instance_id = "other-instance".into(); + let status = client + .evaluate(authorized(request, TOKEN)) + .await + .unwrap_err(); + assert_eq!(status.code(), tonic::Code::PermissionDenied); + + let status = client + .evaluate(authorized(payment(&[1], json!({})), "wrong")) + .await + .unwrap_err(); + assert_eq!(status.code(), tonic::Code::PermissionDenied); +} + +#[tokio::test] +#[ignore = "timing report for the prototype gates; run with --ignored --nocapture"] +async fn loopback_evaluate_round_trip() { + let mut client = GuardianModuleClient::new(start_remote().await); + let request = payment(&[500], json!({ "max_amount_per_tx": { "0xaa": "1000" } })); + for _ in 0..50 { + client + .evaluate(authorized(request.clone(), TOKEN)) + .await + .unwrap(); + } + let mut samples = Vec::with_capacity(1000); + for _ in 0..1000 { + let started = std::time::Instant::now(); + client + .evaluate(authorized(request.clone(), TOKEN)) + .await + .unwrap(); + samples.push(started.elapsed()); + } + samples.sort(); + let local_started = std::time::Instant::now(); + for _ in 0..1000 { + BasicPolicy.evaluate(&request).await.unwrap(); + } + println!( + "remote p50 {:?} p99 {:?}; in-process mean {:?}", + samples[500], + samples[990], + local_started.elapsed() / 1000 + ); +} From 3ce111604fc85cfc27a1d3369eda742bf5fbece4 Mon Sep 17 00:00:00 2001 From: Zeljko Date: Mon, 9 Nov 2026 08:55:10 +0100 Subject: [PATCH 002/105] feat(server): policy module subsystem and operator API (#251) crates/server/src/modules: catalog loading and validation, the kind registry (basic-policy in process, grpc remote), the ordered pipeline with global and account layers, request assembly with account views and the Miden projection, module state on the filesystem and Postgres (migration 2026-10-15 guardian_modules), and the /dashboard/modules operator routes under policies:write, policies:write_global and modules:disable, with audit and params history. Loaded from GUARDIAN_MODULES_CONFIG into AppState; no hook calls the pipeline yet. Carried from the prototype (#554). --- Cargo.lock | 3 + crates/server/Cargo.toml | 5 +- crates/server/build.rs | 3 + .../server/examples/custom_module_server.rs | 101 ++ crates/server/examples/modules_admin.rs | 114 ++ .../down.sql | 4 + .../2026-10-15-000001_guardian_modules/up.sql | 53 + crates/server/src/api/dashboard_modules.rs | 384 +++++ crates/server/src/api/mod.rs | 1 + crates/server/src/audit/kinds.rs | 25 + crates/server/src/builder/handle.rs | 64 + crates/server/src/builder/mod.rs | 37 + crates/server/src/builder/state.rs | 2 + crates/server/src/coordination/mod.rs | 6 + crates/server/src/dashboard/authz.rs | 30 +- crates/server/src/dashboard/permissions.rs | 14 + crates/server/src/dashboard/stats.rs | 2 + crates/server/src/delta_object.rs | 2 + crates/server/src/delta_summary/build.rs | 3 + crates/server/src/delta_summary/decode.rs | 11 +- crates/server/src/delta_summary/mod.rs | 24 + crates/server/src/error.rs | 145 ++ crates/server/src/lib.rs | 1 + crates/server/src/modules/admin.rs | 792 +++++++++++ crates/server/src/modules/catalog.rs | 638 +++++++++ crates/server/src/modules/check_limit.rs | 127 ++ crates/server/src/modules/disclosure.rs | 177 +++ crates/server/src/modules/grpc_kind.rs | 133 ++ crates/server/src/modules/mod.rs | 78 + crates/server/src/modules/pipeline.rs | 1264 +++++++++++++++++ crates/server/src/modules/postgres_store.rs | 783 ++++++++++ crates/server/src/modules/registry.rs | 565 ++++++++ crates/server/src/modules/request.rs | 330 +++++ crates/server/src/modules/store.rs | 631 ++++++++ crates/server/src/modules/testing.rs | 341 +++++ crates/server/src/network/miden/mod.rs | 15 + .../server/src/network/miden/module_views.rs | 480 +++++++ crates/server/src/network/mod.rs | 28 + crates/server/src/services/account_status.rs | 1 + .../server/src/services/configure_account.rs | 1 + .../dashboard_account_delta_detail.rs | 3 + .../src/services/dashboard_account_deltas.rs | 5 + .../services/dashboard_account_proposals.rs | 2 + .../services/dashboard_account_snapshot.rs | 1 + .../server/src/services/dashboard_accounts.rs | 1 + .../src/services/dashboard_global_deltas.rs | 3 + .../services/dashboard_global_proposals.rs | 2 + crates/server/src/services/dashboard_info.rs | 2 + crates/server/src/services/dashboard_stats.rs | 1 + .../server/src/services/get_delta_history.rs | 1 + crates/server/src/services/mod.rs | 1 + .../server/src/services/release_on_switch.rs | 1 + crates/server/src/testing/helpers.rs | 2 + crates/server/src/testing/mocks.rs | 40 + docs/guides/policy-modules/built-in.toml | 48 + .../policy-modules/custom-in-process.toml | 14 + docs/guides/policy-modules/custom.toml | 15 + docs/guides/policy-modules/remote.toml | 26 + docs/openapi-client.json | 56 + docs/openapi.json | 56 + packages/guardian-client/src/error-codes.ts | 8 + 61 files changed, 7701 insertions(+), 5 deletions(-) create mode 100644 crates/server/examples/custom_module_server.rs create mode 100644 crates/server/examples/modules_admin.rs create mode 100644 crates/server/migrations/2026-10-15-000001_guardian_modules/down.sql create mode 100644 crates/server/migrations/2026-10-15-000001_guardian_modules/up.sql create mode 100644 crates/server/src/api/dashboard_modules.rs create mode 100644 crates/server/src/modules/admin.rs create mode 100644 crates/server/src/modules/catalog.rs create mode 100644 crates/server/src/modules/check_limit.rs create mode 100644 crates/server/src/modules/disclosure.rs create mode 100644 crates/server/src/modules/grpc_kind.rs create mode 100644 crates/server/src/modules/mod.rs create mode 100644 crates/server/src/modules/pipeline.rs create mode 100644 crates/server/src/modules/postgres_store.rs create mode 100644 crates/server/src/modules/registry.rs create mode 100644 crates/server/src/modules/request.rs create mode 100644 crates/server/src/modules/store.rs create mode 100644 crates/server/src/modules/testing.rs create mode 100644 crates/server/src/network/miden/module_views.rs create mode 100644 docs/guides/policy-modules/built-in.toml create mode 100644 docs/guides/policy-modules/custom-in-process.toml create mode 100644 docs/guides/policy-modules/custom.toml create mode 100644 docs/guides/policy-modules/remote.toml diff --git a/Cargo.lock b/Cargo.lock index 5fdc2d42..c1f47692 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -3577,6 +3577,7 @@ dependencies = [ "dotenvy", "futures", "futures-util", + "guardian-module-sdk", "guardian-shared", "hex", "hmac 0.12.1", @@ -3601,6 +3602,7 @@ dependencies = [ "rand 0.10.2", "rand_chacha 0.10.0", "rcgen", + "reqwest 0.12.28", "rustls 0.23.46", "rustls-pemfile", "secrecy", @@ -3616,6 +3618,7 @@ dependencies = [ "tokio-postgres", "tokio-postgres-rustls", "tokio-util", + "toml 0.8.23", "tonic", "tonic-prost", "tonic-prost-build", diff --git a/crates/server/Cargo.toml b/crates/server/Cargo.toml index 20efbc0e..fdbdbafe 100644 --- a/crates/server/Cargo.toml +++ b/crates/server/Cargo.toml @@ -44,7 +44,7 @@ zeroize = { version = "1.7", features = ["derive"] } serde_json = { workspace = true } tokio = { workspace = true, features = ["full"] } tokio-util = { version = "0.7", features = ["rt"] } -tonic = { workspace = true } +tonic = { workspace = true, features = ["tls-ring", "tls-native-roots"] } tonic-prost = { workspace = true } tonic-reflection = "0.14" prost = { workspace = true } @@ -57,6 +57,8 @@ tracing-subscriber = { version = "0.3", features = ["env-filter", "fmt", "json"] miden-protocol = { workspace = true, features = ["testing"] } miden-standards = { workspace = true } futures = "0.3" +guardian-module-sdk = { path = "../guardian-module-sdk" } +toml = "0.8" futures-util = { version = "0.3", optional = true } rustls = { version = "0.23", optional = true } rustls-pemfile = { version = "2", optional = true } @@ -88,6 +90,7 @@ tonic-prost-build = { workspace = true } [dev-dependencies] bytes = "1" +reqwest = { version = "0.12", default-features = false, features = ["json", "rustls-tls"] } futures = "0.3" miden-protocol = { workspace = true, features = ["testing"] } tokio = { workspace = true, features = ["full", "test-util"] } diff --git a/crates/server/build.rs b/crates/server/build.rs index 3d94a16c..3136a40b 100644 --- a/crates/server/build.rs +++ b/crates/server/build.rs @@ -17,6 +17,9 @@ fn main() -> Result<(), Box> { .map(|o| String::from_utf8_lossy(&o.stdout).trim().to_string()) }) .unwrap_or_else(|| "unknown".to_string()); + // Declaring any rerun-if-changed below replaces Cargo's default, so the proto must be + // listed too or edits to it compile against stale generated code. + println!("cargo:rerun-if-changed=proto/guardian.proto"); println!("cargo:rustc-env=GUARDIAN_GIT_SHA={git_sha}"); println!("cargo:rerun-if-changed=proto/guardian.proto"); println!("cargo:rerun-if-env-changed=GUARDIAN_GIT_SHA"); diff --git a/crates/server/examples/custom_module_server.rs b/crates/server/examples/custom_module_server.rs new file mode 100644 index 00000000..dad84ca4 --- /dev/null +++ b/crates/server/examples/custom_module_server.rs @@ -0,0 +1,101 @@ +//! The Guardian server with a policy module kind compiled in: `note-policy` runs in this +//! process, so a catalog entry can name it with `kind = "note-policy"` and no endpoint. +//! Everything else matches the `server` binary. Walkthrough in +//! `docs/guides/policy-modules/custom.md`. +//! +//! ```text +//! cargo run -p guardian-server --example custom_module_server +//! ``` +//! +//! `GUARDIAN_EXAMPLE_HTTP_PORT` and `GUARDIAN_EXAMPLE_GRPC_PORT` (default 3000 and 50051) let it +//! run next to another server. + +#[path = "../../guardian-module-sdk/examples/note_policy/mod.rs"] +mod note_policy; + +use std::sync::Arc; + +use server::ack::AckRegistry; +use server::builder::{ServerBuilder, storage::StorageMetadataBuilder}; +use server::canonicalization::CanonicalizationConfig; +use server::config::stage::Stage; +use server::logging::LoggingConfig; +use server::middleware::{BodyLimitConfig, CorsConfig, RateLimitConfig}; +use server::network::{NetworkType, RpcSettings}; +use std::env; +use std::path::PathBuf; + +fn port(var: &str, default: u16) -> u16 { + env::var(var) + .ok() + .and_then(|value| value.parse().ok()) + .unwrap_or(default) +} + +#[tokio::main] +async fn main() { + dotenvy::dotenv().ok(); + + let keystore_path: PathBuf = env::var("GUARDIAN_KEYSTORE_PATH") + .unwrap_or_else(|_| "/var/guardian/keystore".to_string()) + .into(); + + let (storage_backend, metadata, auditor, coordination) = StorageMetadataBuilder::from_env() + .build() + .await + .expect("Failed to initialize storage backends"); + + // Initialize acknowledger registry (supports both Falcon and ECDSA) + let ack = AckRegistry::new(keystore_path) + .await + .expect("Failed to initialize ack registry"); + + let cors_layer = CorsConfig::from_env() + .expect("Failed to initialize CORS config") + .layer(); + + let network_type = + NetworkType::from_env("GUARDIAN_NETWORK_TYPE").expect("Failed to resolve network type"); + + let stage = Stage::from_env().expect("Invalid GUARDIAN_ENV"); + + ServerBuilder::new() + .with_logging(LoggingConfig::default()) + .network(network_type) + .with_rpc(RpcSettings::from_env(network_type).expect("Invalid RPC configuration")) + .with_canonicalization(Some( + CanonicalizationConfig::new(10, 48) + .with_stage_defaults(stage) + .with_submission_grace_period_seconds(600) + .with_fast_promotion_enabled_from_env() + .expect("Invalid fast promotion configuration") + .with_max_concurrent_accounts_from_env() + .expect("Invalid canonicalization concurrency configuration") + .with_retained_ttl_seconds_from_env() + .expect("Invalid retained TTL configuration") + .with_reconcile_interval_seconds_from_env() + .expect("Invalid reconcile interval configuration") + .with_max_pending_candidates_per_account_from_env() + .expect("Invalid pending-candidate queue depth configuration"), + )) + .with_release_sweep(Some( + server::release_sweep::ReleaseSweepConfig::from_env() + .expect("Invalid release sweep configuration"), + )) + .with_rate_limit(RateLimitConfig::from_env()) + .with_body_limit(BodyLimitConfig::from_env()) + .storage(storage_backend) + .metadata(metadata) + .auditor(auditor) + .coordination(coordination) + .ack(ack) + .with_module_kind(note_policy::KIND, Arc::new(note_policy::NotePolicyFactory)) + .http(true, port("GUARDIAN_EXAMPLE_HTTP_PORT", 3000)) + .grpc(true, port("GUARDIAN_EXAMPLE_GRPC_PORT", 50051)) + .cors(cors_layer) + .build() + .await + .expect("Failed to build server") + .run() + .await; +} diff --git a/crates/server/examples/modules_admin.rs b/crates/server/examples/modules_admin.rs new file mode 100644 index 00000000..077efb13 --- /dev/null +++ b/crates/server/examples/modules_admin.rs @@ -0,0 +1,114 @@ +//! Operator CLI for the policy module endpoints. +//! +//! ```text +//! modules_admin keygen +//! modules_admin [--url http://localhost:3000] --key GET /modules +//! modules_admin [--url ...] --key PUT /modules/blocklist/params '{"params":{...},"reason":"..."}' +//! ``` + +use guardian_shared::hex::{FromHex, IntoHex}; +use miden_protocol::Word; +use miden_protocol::crypto::dsa::falcon512_poseidon2::SecretKey; +use miden_protocol::utils::serde::{Deserializable, Serializable}; + +type Error = Box; + +fn load_key(path: &str) -> Result { + let bytes = hex::decode(std::fs::read_to_string(path)?.trim())?; + Ok(SecretKey::read_from_bytes(&bytes)?) +} + +fn keygen(path: &str) -> Result<(), Error> { + let key = SecretKey::new(); + std::fs::write(path, hex::encode(key.to_bytes()))?; + let public_key = key.public_key(); + println!("key written to {path}"); + println!("commitment: {}", public_key.to_commitment().into_hex()); + println!("allowlist entry (put it in the GUARDIAN_OPERATOR_PUBLIC_KEYS_FILE array):"); + println!( + "{}", + serde_json::json!({ + "public_key": public_key.into_hex(), + "permissions": ["dashboard:read", "policies:write", "policies:write_global"] + }) + ); + Ok(()) +} + +async fn login(http: &reqwest::Client, url: &str, key: &SecretKey) -> Result { + let commitment = key.public_key().to_commitment().into_hex(); + let challenge: serde_json::Value = http + .get(format!("{url}/auth/challenge")) + .query(&[("commitment", &commitment)]) + .send() + .await? + .error_for_status()? + .json() + .await?; + let digest = challenge["challenge"]["signing_digest"] + .as_str() + .ok_or("challenge has no signing_digest")?; + let signature = key.sign(Word::from_hex(digest)?); + let response = http + .post(format!("{url}/auth/verify")) + .json(&serde_json::json!({ + "commitment": commitment, + "signature": format!("0x{}", hex::encode(signature.to_bytes())), + })) + .send() + .await?; + let cookie = response + .headers() + .get(reqwest::header::SET_COOKIE) + .and_then(|value| value.to_str().ok()) + .and_then(|value| value.split(';').next()) + .map(str::to_string) + .ok_or("login failed: no session cookie (is the key in the operator allowlist?)")?; + response.error_for_status()?; + Ok(cookie) +} + +#[tokio::main] +async fn main() -> Result<(), Error> { + let mut args: Vec = std::env::args().skip(1).collect(); + if args.first().map(String::as_str) == Some("keygen") { + return keygen(args.get(1).ok_or("keygen needs a key file path")?); + } + let mut url = "http://localhost:3000".to_string(); + let mut key_path = None; + while args.first().is_some_and(|arg| arg.starts_with("--")) { + let flag = args.remove(0); + let value = (!args.is_empty()) + .then(|| args.remove(0)) + .ok_or("flag needs a value")?; + match flag.as_str() { + "--url" => url = value, + "--key" => key_path = Some(value), + other => return Err(format!("unknown flag {other}").into()), + } + } + let [method, path, rest @ ..] = args.as_slice() else { + return Err("usage: modules_admin --key [JSON]".into()); + }; + let key = load_key(key_path.as_deref().ok_or("--key is required")?)?; + let http = reqwest::Client::new(); + let cookie = login(&http, &url, &key).await?; + + let request = http + .request(method.parse()?, format!("{url}/dashboard{path}")) + .header(reqwest::header::COOKIE, cookie); + let request = match rest.first() { + Some(body) => request + .header(reqwest::header::CONTENT_TYPE, "application/json") + .body(body.clone()), + None => request, + }; + let response = request.send().await?; + let status = response.status(); + let text = response.text().await?; + let pretty = serde_json::from_str::(&text) + .and_then(|value| serde_json::to_string_pretty(&value)) + .unwrap_or(text); + println!("{status}\n{pretty}"); + Ok(()) +} diff --git a/crates/server/migrations/2026-10-15-000001_guardian_modules/down.sql b/crates/server/migrations/2026-10-15-000001_guardian_modules/down.sql new file mode 100644 index 00000000..6bea6176 --- /dev/null +++ b/crates/server/migrations/2026-10-15-000001_guardian_modules/down.sql @@ -0,0 +1,4 @@ +DROP TABLE module_params_history; +DROP TABLE module_state_version; +DROP TABLE module_account_params; +DROP TABLE module_instances; diff --git a/crates/server/migrations/2026-10-15-000001_guardian_modules/up.sql b/crates/server/migrations/2026-10-15-000001_guardian_modules/up.sql new file mode 100644 index 00000000..f9637452 --- /dev/null +++ b/crates/server/migrations/2026-10-15-000001_guardian_modules/up.sql @@ -0,0 +1,53 @@ +-- Policy module state (RFC 0002, issue #251). Kept apart from account_metadata, +-- which configure_account rewrites in full: operators write these rows, cosigners +-- write the metadata row. Instance definitions stay in the catalog file. + +CREATE TABLE module_instances ( + module_id TEXT PRIMARY KEY, + enabled BOOLEAN NOT NULL, + global_params JSONB NOT NULL, + seeded_params JSONB NOT NULL, + updated_at TIMESTAMPTZ NOT NULL, + updated_by TEXT NOT NULL +); + +-- Account layers on scope = all instances (only add restrictions) and +-- assignments of default / assigned instances (position = evaluation order). +CREATE TABLE module_account_params ( + account_id TEXT NOT NULL, + module_id TEXT NOT NULL, + kind TEXT NOT NULL CHECK (kind IN ('layer', 'assignment')), + position INTEGER NOT NULL, + params JSONB NOT NULL, + updated_at TIMESTAMPTZ NOT NULL, + updated_by TEXT NOT NULL, + PRIMARY KEY (account_id, module_id) +); + +CREATE INDEX module_account_params_module_idx ON module_account_params (module_id); + +-- One row. Every module write takes this row lock first and bumps it, so +-- writes serialize and the version moves in commit order; replicas key their +-- cache on it. A sequence would hand out numbers in start order instead, and a +-- slow commit with a lower number would never be noticed. +CREATE TABLE module_state_version ( + singleton BOOLEAN PRIMARY KEY DEFAULT TRUE CHECK (singleton), + version BIGINT NOT NULL +); + +INSERT INTO module_state_version (singleton, version) VALUES (TRUE, 0); + +-- Append-only; rows of one write share its version. +CREATE TABLE module_params_history ( + id BIGSERIAL PRIMARY KEY, + version BIGINT NOT NULL, + module_id TEXT NOT NULL, + account_id TEXT NULL, + previous_params JSONB NOT NULL, + new_params JSONB NOT NULL, + operator TEXT NOT NULL, + reason TEXT NOT NULL, + changed_at TIMESTAMPTZ NOT NULL +); + +CREATE INDEX module_params_history_module_idx ON module_params_history (module_id, version); diff --git a/crates/server/src/api/dashboard_modules.rs b/crates/server/src/api/dashboard_modules.rs new file mode 100644 index 00000000..91fd8cf6 --- /dev/null +++ b/crates/server/src/api/dashboard_modules.rs @@ -0,0 +1,384 @@ +//! Operator endpoints for policy module parameters. + +use axum::Json; +use axum::extract::{Extension, Path, State}; +use serde::Deserialize; + +use crate::dashboard::AuthenticatedOperator; +use crate::error::{GuardianError, Result}; +use crate::modules::admin::{ + self, AccountModulesView, ModuleCatalogView, ModuleInstanceView, ParamsHistoryView, +}; +use crate::modules::store::Assigned; +use crate::state::AppState; + +const BODY_LIMIT: usize = 256 * 1024; + +#[derive(Debug, Deserialize)] +pub struct ParamsBody { + pub params: serde_json::Value, + pub reason: String, +} + +#[derive(Debug, Deserialize)] +pub struct ReasonBody { + pub reason: String, +} + +#[derive(Debug, Deserialize)] +pub struct AssignmentBody { + pub modules: Vec, + pub reason: String, +} + +async fn body( + request: axum::extract::Request, +) -> Result<(T, Option)> { + let client_ip = crate::middleware::client_ip::extract_client_ip(&request); + let (_parts, body) = request.into_parts(); + let bytes = axum::body::to_bytes(body, BODY_LIMIT) + .await + .map_err(|_| GuardianError::InvalidInput("failed to read request body".into()))?; + let parsed = serde_json::from_slice(&bytes) + .map_err(|e| GuardianError::InvalidInput(format!("malformed request body: {e}")))?; + Ok((parsed, client_ip)) +} + +pub async fn list_modules(State(state): State) -> Result> { + admin::catalog_view(&state).await.map(Json) +} + +pub async fn account_modules( + State(state): State, + Path(account_id): Path, +) -> Result> { + admin::account_view(&state, &account_id).await.map(Json) +} + +pub async fn params_history( + State(state): State, + Path(module_id): Path, +) -> Result> { + admin::history(&state, &module_id).await.map(Json) +} + +pub async fn set_global_params( + State(state): State, + Extension(operator): Extension, + Path(module_id): Path, + request: axum::extract::Request, +) -> Result> { + let (body, client_ip): (ParamsBody, _) = body(request).await?; + admin::set_global( + &state, + &operator, + &module_id, + body.params, + &body.reason, + client_ip, + ) + .await + .map(Json) +} + +pub async fn enable_module( + State(state): State, + Extension(operator): Extension, + Path(module_id): Path, + request: axum::extract::Request, +) -> Result> { + let (body, client_ip): (ReasonBody, _) = body(request).await?; + admin::enable(&state, &operator, &module_id, &body.reason, client_ip) + .await + .map(Json) +} + +pub async fn disable_module( + State(state): State, + Extension(operator): Extension, + Path(module_id): Path, + request: axum::extract::Request, +) -> Result> { + let (body, client_ip): (ReasonBody, _) = body(request).await?; + admin::disable(&state, &operator, &module_id, &body.reason, client_ip) + .await + .map(Json) +} + +pub async fn set_account_layer( + State(state): State, + Extension(operator): Extension, + Path((account_id, module_id)): Path<(String, String)>, + request: axum::extract::Request, +) -> Result> { + let (body, client_ip): (ParamsBody, _) = body(request).await?; + admin::set_layer( + &state, + &operator, + &account_id, + &module_id, + Some(body.params), + &body.reason, + client_ip, + ) + .await + .map(Json) +} + +pub async fn remove_account_layer( + State(state): State, + Extension(operator): Extension, + Path((account_id, module_id)): Path<(String, String)>, + request: axum::extract::Request, +) -> Result> { + let (body, client_ip): (ReasonBody, _) = body(request).await?; + admin::set_layer( + &state, + &operator, + &account_id, + &module_id, + None, + &body.reason, + client_ip, + ) + .await + .map(Json) +} + +pub async fn set_assignment( + State(state): State, + Extension(operator): Extension, + Path(account_id): Path, + request: axum::extract::Request, +) -> Result> { + let (body, client_ip): (AssignmentBody, _) = body(request).await?; + admin::set_assignment( + &state, + &operator, + &account_id, + body.modules, + &body.reason, + client_ip, + ) + .await + .map(Json) +} + +#[cfg(test)] +mod tests { + use std::collections::BTreeSet; + use std::sync::Arc; + + use axum::body::{Body, to_bytes}; + use axum::http::{Request, StatusCode, header}; + use guardian_module_sdk::basic_policy::BasicPolicy; + use guardian_shared::hex::FromHex; + use miden_protocol::Word; + use serde_json::json; + use tower::ServiceExt; + + use crate::dashboard::DashboardState; + use crate::dashboard::permissions::Permission; + use crate::modules::catalog::HookName; + use crate::modules::testing::{instance_with_params, pipeline}; + use crate::testing::helpers::{TestSigner, create_router, create_test_app_state}; + + use super::*; + + fn operator(signer: &TestSigner, permissions: &[Permission]) -> AuthenticatedOperator { + AuthenticatedOperator { + operator_id: signer.commitment_hex.clone(), + commitment: signer.commitment_hex.clone(), + effective_permissions: Arc::new(permissions.iter().copied().collect::>()), + } + } + + async fn send(app: &axum::Router, request: Request) -> (StatusCode, serde_json::Value) { + let response = app.clone().oneshot(request).await.unwrap(); + let status = response.status(); + let bytes = to_bytes(response.into_body(), usize::MAX).await.unwrap(); + ( + status, + serde_json::from_slice(&bytes).unwrap_or(serde_json::Value::Null), + ) + } + + async fn login(app: &axum::Router, signer: &TestSigner) -> String { + let (_, challenge) = send( + app, + Request::get(format!( + "/auth/challenge?commitment={}", + signer.commitment_hex + )) + .body(Body::empty()) + .unwrap(), + ) + .await; + let digest = challenge["challenge"]["signing_digest"].as_str().unwrap(); + let signature = signer.sign_word(Word::from_hex(digest).unwrap()); + let response = app + .clone() + .oneshot( + Request::post("/auth/verify") + .header(header::CONTENT_TYPE, "application/json") + .body(Body::from( + json!({ "commitment": signer.commitment_hex, "signature": signature }) + .to_string(), + )) + .unwrap(), + ) + .await + .unwrap(); + assert_eq!(response.status(), StatusCode::OK); + response.headers()[header::SET_COOKIE] + .to_str() + .unwrap() + .split(';') + .next() + .unwrap() + .to_string() + } + + fn put(path: &str, cookie: &str, body: serde_json::Value) -> Request { + Request::put(path) + .header(header::COOKIE, cookie) + .header(header::CONTENT_TYPE, "application/json") + .body(Body::from(body.to_string())) + .unwrap() + } + + fn get(path: &str, cookie: &str) -> Request { + Request::get(path) + .header(header::COOKIE, cookie) + .body(Body::empty()) + .unwrap() + } + + #[tokio::test] + async fn global_params_need_their_own_permission_and_are_recorded() { + let support = TestSigner::new(); + let admin = TestSigner::new(); + let mut state = create_test_app_state().await; + state.dashboard = Arc::new(DashboardState::for_tests_with_permissions(vec![ + operator( + &support, + &[Permission::DashboardRead, Permission::PoliciesWrite], + ), + operator( + &admin, + &[Permission::DashboardRead, Permission::PoliciesWriteGlobal], + ), + ])); + state.modules = Some(pipeline(vec![instance_with_params( + "blocklist", + &[HookName::BeforeTransactionApproved], + Arc::new(BasicPolicy), + json!({ "recipient_denylist": ["0xaaa"] }), + )])); + let app = create_router(state); + let support_cookie = login(&app, &support).await; + let admin_cookie = login(&app, &admin).await; + let body = + json!({ "params": { "recipient_denylist": ["0xaaa", "0xddd"] }, "reason": "OP-90" }); + + let (status, _) = send( + &app, + put( + "/dashboard/modules/blocklist/params", + &support_cookie, + body.clone(), + ), + ) + .await; + assert_eq!(status, StatusCode::FORBIDDEN); + + let (status, view) = send( + &app, + put("/dashboard/modules/blocklist/params", &admin_cookie, body), + ) + .await; + assert_eq!(status, StatusCode::OK, "{view}"); + assert_eq!(view["params"]["recipient_denylist"][1], "0xddd"); + + let (status, catalog) = send(&app, get("/dashboard/modules", &support_cookie)).await; + assert_eq!(status, StatusCode::OK); + assert_eq!(catalog["modules"][0]["params_drift"], true); + + let (status, history) = send( + &app, + get( + "/dashboard/modules/blocklist/params/history", + &support_cookie, + ), + ) + .await; + assert_eq!(status, StatusCode::OK); + assert_eq!(history["entries"][0]["reason"], "OP-90"); + assert_eq!(history["entries"][0]["operator"], admin.commitment_hex); + + let (status, _) = send( + &app, + put( + "/dashboard/accounts/0xmissing/modules/blocklist/params", + &support_cookie, + json!({ "params": {}, "reason": "r" }), + ), + ) + .await; + assert_eq!(status, StatusCode::NOT_FOUND); + } + + fn post(path: &str, cookie: &str, body: serde_json::Value) -> Request { + Request::post(path) + .header(header::COOKIE, cookie) + .header(header::CONTENT_TYPE, "application/json") + .body(Body::from(body.to_string())) + .unwrap() + } + + #[tokio::test] + async fn the_disable_permission_can_disable_but_not_enable() { + let on_call = TestSigner::new(); + let mut state = create_test_app_state().await; + state.dashboard = Arc::new(DashboardState::for_tests_with_permissions(vec![operator( + &on_call, + &[Permission::ModulesDisable], + )])); + state.modules = Some(pipeline(vec![instance_with_params( + "risk-scorer", + &[HookName::BeforeTransactionApproved], + Arc::new(BasicPolicy), + json!({}), + )])); + state + .modules + .as_deref() + .unwrap() + .store() + .seed_instance("risk-scorer", true, &json!({}), "2026-10-15T00:00:00Z") + .await + .unwrap(); + let app = create_router(state); + let cookie = login(&app, &on_call).await; + let reason = json!({ "reason": "scorer returning errors" }); + + let (status, view) = send( + &app, + post( + "/dashboard/modules/risk-scorer/disable", + &cookie, + reason.clone(), + ), + ) + .await; + assert_eq!(status, StatusCode::OK, "{view}"); + assert_eq!(view["enabled"], false); + + let (status, _) = send( + &app, + post("/dashboard/modules/risk-scorer/enable", &cookie, reason), + ) + .await; + assert_eq!(status, StatusCode::FORBIDDEN); + } +} diff --git a/crates/server/src/api/mod.rs b/crates/server/src/api/mod.rs index 5f94fadd..ca622a08 100644 --- a/crates/server/src/api/mod.rs +++ b/crates/server/src/api/mod.rs @@ -1,5 +1,6 @@ pub mod dashboard; pub mod dashboard_feeds; +pub mod dashboard_modules; #[cfg(feature = "evm")] pub mod evm; #[cfg(test)] diff --git a/crates/server/src/audit/kinds.rs b/crates/server/src/audit/kinds.rs index 17d9ac48..0b31a303 100644 --- a/crates/server/src/audit/kinds.rs +++ b/crates/server/src/audit/kinds.rs @@ -52,6 +52,21 @@ pub const ACCOUNTS_RELEASE: &str = "accounts.release"; /// request outcome (`queued` / `in_progress` / `cooldown`). pub const STATS_REFRESH: &str = "stats.refresh"; +/// An operator changed a policy module's global params. +pub const MODULES_PARAMS_GLOBAL: &str = "modules.params.global"; + +/// An operator set or removed an account's layer on a mandatory policy module. +pub const MODULES_PARAMS_ACCOUNT: &str = "modules.params.account"; + +/// An operator replaced an account's assigned policy modules. +pub const MODULES_ASSIGNMENT: &str = "modules.assignment"; + +/// An operator enabled a policy module instance. +pub const MODULES_ENABLE: &str = "modules.enable"; + +/// An operator disabled a policy module instance. +pub const MODULES_DISABLE: &str = "modules.disable"; + /// All registered kinds in v1, for tests and introspection. Append /// new consts above and add them to this slice in the same commit. pub const ALL_KINDS: &[&str] = &[ @@ -61,6 +76,11 @@ pub const ALL_KINDS: &[&str] = &[ ACCOUNTS_UNPAUSE, ACCOUNTS_RELEASE, STATS_REFRESH, + MODULES_PARAMS_GLOBAL, + MODULES_PARAMS_ACCOUNT, + MODULES_ASSIGNMENT, + MODULES_ENABLE, + MODULES_DISABLE, ]; #[cfg(test)] @@ -78,6 +98,11 @@ mod tests { ACCOUNTS_UNPAUSE, ACCOUNTS_RELEASE, STATS_REFRESH, + MODULES_PARAMS_GLOBAL, + MODULES_PARAMS_ACCOUNT, + MODULES_ASSIGNMENT, + MODULES_ENABLE, + MODULES_DISABLE, ] ); } diff --git a/crates/server/src/builder/handle.rs b/crates/server/src/builder/handle.rs index ed94a885..521303d7 100644 --- a/crates/server/src/builder/handle.rs +++ b/crates/server/src/builder/handle.rs @@ -454,6 +454,70 @@ pub(crate) fn build_http_router(state: AppState, config: HttpRouterConfig) -> Ro dashboard_routes.merge(pause_router) }; + // Policy modules: reads under `dashboard:read`, per-account writes under `policies:write`, + // global params under their own `policies:write_global`. + let dashboard_routes = { + use crate::api::dashboard_modules as modules; + use axum::routing::{delete, put}; + let read_authz = AuthzState::new(state.clone(), &[Permission::DashboardRead]); + let write_authz = AuthzState::new(state.clone(), &[Permission::PoliciesWrite]); + let global_authz = AuthzState::new(state.clone(), &[Permission::PoliciesWriteGlobal]); + let read = Router::new() + .route("/modules", get(modules::list_modules)) + .route( + "/modules/{module_id}/params/history", + get(modules::params_history), + ) + .route( + "/accounts/{account_id}/modules", + get(modules::account_modules), + ) + .route_layer(from_fn_with_state(read_authz, enforce_authz)) + .route_layer(from_fn_with_state(state.clone(), require_dashboard_session)); + let write = Router::new() + .route( + "/accounts/{account_id}/modules", + put(modules::set_assignment), + ) + .route( + "/accounts/{account_id}/modules/{module_id}/params", + put(modules::set_account_layer).merge(delete(modules::remove_account_layer)), + ) + .route_layer(from_fn_with_state(write_authz, enforce_authz)) + .route_layer(from_fn_with_state(state.clone(), require_dashboard_session)); + let disable_authz = AuthzState::any_of( + state.clone(), + &[Permission::PoliciesWrite, Permission::ModulesDisable], + ); + let enable = Router::new() + .route("/modules/{module_id}/enable", post(modules::enable_module)) + .route_layer(from_fn_with_state( + AuthzState::new(state.clone(), &[Permission::PoliciesWrite]), + enforce_authz, + )) + .route_layer(from_fn_with_state(state.clone(), require_dashboard_session)); + let disable = Router::new() + .route( + "/modules/{module_id}/disable", + post(modules::disable_module), + ) + .route_layer(from_fn_with_state(disable_authz, enforce_authz)) + .route_layer(from_fn_with_state(state.clone(), require_dashboard_session)); + let global = Router::new() + .route( + "/modules/{module_id}/params", + put(modules::set_global_params), + ) + .route_layer(from_fn_with_state(global_authz, enforce_authz)) + .route_layer(from_fn_with_state(state.clone(), require_dashboard_session)); + dashboard_routes + .merge(read) + .merge(write) + .merge(global) + .merge(enable) + .merge(disable) + }; + // Issue #371: operator-triggered refresh of the /dashboard/stats // aggregate, gated by its own `stats:refresh` permission. let dashboard_routes = { diff --git a/crates/server/src/builder/mod.rs b/crates/server/src/builder/mod.rs index 55183574..b840d98f 100644 --- a/crates/server/src/builder/mod.rs +++ b/crates/server/src/builder/mod.rs @@ -54,6 +54,7 @@ pub struct ServerBuilder { rate_limit_config: Option, body_limit_config: Option, metrics_config: Option, + module_kinds: Vec<(String, Arc)>, http_enabled: bool, http_port: u16, grpc_enabled: bool, @@ -81,6 +82,7 @@ impl ServerBuilder { rate_limit_config: None, body_limit_config: None, metrics_config: None, + module_kinds: Vec::new(), http_enabled: true, http_port: 3000, grpc_enabled: true, @@ -440,6 +442,25 @@ impl ServerBuilder { self } + /// Registers a policy module kind that runs in this process, so catalog entries + /// (`GUARDIAN_MODULES_CONFIG`) can name it in `kind`. The module shares the process that + /// holds the acknowledgement keys, so register only code you have reviewed. `build` fails + /// if the name is already taken, including by the first-party `basic-policy` and `grpc`. + /// + /// # Example + /// ```ignore + /// let builder = ServerBuilder::new() + /// .with_module_kind("note-policy", Arc::new(NotePolicyFactory)); + /// ``` + pub fn with_module_kind( + mut self, + kind: impl Into, + factory: Arc, + ) -> Self { + self.module_kinds.push((kind.into(), factory)); + self + } + /// Build the server handle /// /// Validates that all required components are configured and returns @@ -506,6 +527,9 @@ impl ServerBuilder { let ack = self.ack.ok_or("AckRegistry not set. Use .ack(...)")?; let coordination = self.coordination; + let module_store = coordination + .as_ref() + .and_then(|handles| handles.module_store.clone()); // Fail closed before anything else: the Postgres backend must never fall // back to per-process coordination (AlwaysLeader + in-memory sessions), // which would let every replica run canonicalization and split auth @@ -752,6 +776,18 @@ impl ServerBuilder { ); } + crate::modules::check_limit::init_from_env()?; + let mut module_registry = crate::modules::Registry::first_party(); + for (kind, factory) in self.module_kinds { + module_registry.register(kind, factory)?; + } + let modules = crate::modules::from_env( + chrono::Utc::now().to_rfc3339(), + module_store, + &module_registry, + ) + .await?; + let app_state = AppState { storage, metadata, @@ -765,6 +801,7 @@ impl ServerBuilder { auditor, execution, miden_sessions, + modules, #[cfg(feature = "evm")] evm, }; diff --git a/crates/server/src/builder/state.rs b/crates/server/src/builder/state.rs index 15f14fdb..2b1c3e0f 100644 --- a/crates/server/src/builder/state.rs +++ b/crates/server/src/builder/state.rs @@ -39,6 +39,8 @@ pub struct AppState { pub execution: crate::services::execute_proposal::ExecutionState, /// Miden account sessions. pub miden_sessions: Arc, + /// Policy modules consulted before approval; `None` when no catalog is configured. + pub modules: Option>, #[cfg(feature = "evm")] pub evm: Arc, } diff --git a/crates/server/src/coordination/mod.rs b/crates/server/src/coordination/mod.rs index 5b885021..36cf07ca 100644 --- a/crates/server/src/coordination/mod.rs +++ b/crates/server/src/coordination/mod.rs @@ -79,6 +79,8 @@ pub struct CoordinationHandles { pub block_watch_store: Arc, /// Miden account sessions. pub miden_sessions: Arc, + /// Policy module tables on the shared database; `None` keeps them as files. + pub module_store: Option>, #[cfg(feature = "evm")] pub evm_sessions: Arc, #[cfg(feature = "evm")] @@ -112,6 +114,7 @@ impl CoordinationHandles { stats_store: Arc::new(InMemoryStatsStore::new()), block_watch_store: Arc::new(InMemoryBlockWatchStore::new()), miden_sessions: Arc::new(InMemorySessionStore::new()), + module_store: None, #[cfg(feature = "evm")] evm_sessions: Arc::new(InMemorySessionStore::new()), #[cfg(feature = "evm")] @@ -155,6 +158,9 @@ impl CoordinationHandles { stats_store: Arc::new(PgStatsStore::new(pool.clone(), cipher)), block_watch_store: Arc::new(PgBlockWatchStore::new(pool.clone())), miden_sessions: Arc::new(PgSessionStore::new(pool.clone(), Realm::Miden)), + module_store: Some(Arc::new( + crate::modules::postgres_store::PgModuleStore::new(pool.clone()), + )), #[cfg(feature = "evm")] evm_sessions: Arc::new(PgSessionStore::new(pool.clone(), Realm::Evm)), #[cfg(feature = "evm")] diff --git a/crates/server/src/dashboard/authz.rs b/crates/server/src/dashboard/authz.rs index 15878492..596075b1 100644 --- a/crates/server/src/dashboard/authz.rs +++ b/crates/server/src/dashboard/authz.rs @@ -36,6 +36,8 @@ pub type RequiredPermissions = &'static [Permission]; pub struct AuthzState { pub app_state: AppState, pub required: RequiredPermissions, + /// When true, holding any one of `required` is enough. + pub any_of: bool, } impl AuthzState { @@ -43,6 +45,16 @@ impl AuthzState { Self { app_state, required, + any_of: false, + } + } + + /// The route accepts an operator holding at least one of `required`. + pub fn any_of(app_state: AppState, required: RequiredPermissions) -> Self { + Self { + app_state, + required, + any_of: true, } } } @@ -64,6 +76,7 @@ pub async fn enforce( let AuthzState { app_state: state, required, + any_of, } = state; // The session middleware (`require_dashboard_session`) runs first, // so `AuthenticatedOperator` MUST be present. If it's missing we @@ -81,7 +94,12 @@ pub async fn enforce( })?; let missing = missing_permissions(&operator.effective_permissions, required); - if missing.is_empty() { + let satisfied = if any_of { + missing.len() < required.len() + } else { + missing.is_empty() + }; + if satisfied { return Ok(next.run(request).await); } @@ -143,6 +161,16 @@ mod tests { Arc::new(perms.iter().copied().collect()) } + #[test] + fn any_of_is_satisfied_by_one_held_permission() { + let required: RequiredPermissions = + &[Permission::PoliciesWrite, Permission::ModulesDisable]; + let missing = missing_permissions(&held(&[Permission::ModulesDisable]), required); + assert!(missing.len() < required.len()); + let missing = missing_permissions(&held(&[Permission::DashboardRead]), required); + assert_eq!(missing.len(), required.len()); + } + #[test] fn missing_permissions_returns_empty_when_all_held() { let result = missing_permissions( diff --git a/crates/server/src/dashboard/permissions.rs b/crates/server/src/dashboard/permissions.rs index 1b6c884c..a7b60973 100644 --- a/crates/server/src/dashboard/permissions.rs +++ b/crates/server/src/dashboard/permissions.rs @@ -25,6 +25,8 @@ pub enum Permission { DashboardRead, AccountsPause, PoliciesWrite, + PoliciesWriteGlobal, + ModulesDisable, StatsRefresh, } @@ -39,6 +41,14 @@ pub const ACCOUNTS_PAUSE: &str = "accounts:pause"; /// Wire string for [`Permission::PoliciesWrite`]. pub const POLICIES_WRITE: &str = "policies:write"; +/// Wire string for [`Permission::PoliciesWriteGlobal`]: may change the global params of a policy +/// module, which apply to every account. +pub const POLICIES_WRITE_GLOBAL: &str = "policies:write_global"; + +/// Wire string for [`Permission::ModulesDisable`]: may disable a policy module instance the +/// catalog marks `operator_can_disable`, and nothing else. +pub const MODULES_DISABLE: &str = "modules:disable"; + /// Wire string for [`Permission::StatsRefresh`]: may request an /// out-of-cycle refresh of the `/dashboard/stats` aggregate /// (`POST /dashboard/stats/refresh`). @@ -66,6 +76,8 @@ impl Permission { Self::DashboardRead => DASHBOARD_READ, Self::AccountsPause => ACCOUNTS_PAUSE, Self::PoliciesWrite => POLICIES_WRITE, + Self::PoliciesWriteGlobal => POLICIES_WRITE_GLOBAL, + Self::ModulesDisable => MODULES_DISABLE, Self::StatsRefresh => STATS_REFRESH, } } @@ -88,6 +100,8 @@ impl std::str::FromStr for Permission { DASHBOARD_READ => Ok(Self::DashboardRead), ACCOUNTS_PAUSE => Ok(Self::AccountsPause), POLICIES_WRITE => Ok(Self::PoliciesWrite), + POLICIES_WRITE_GLOBAL => Ok(Self::PoliciesWriteGlobal), + MODULES_DISABLE => Ok(Self::ModulesDisable), STATS_REFRESH => Ok(Self::StatsRefresh), other => Err(UnknownPermission(other.to_owned())), } diff --git a/crates/server/src/dashboard/stats.rs b/crates/server/src/dashboard/stats.rs index ed04d1ac..5ac6bf6c 100644 --- a/crates/server/src/dashboard/stats.rs +++ b/crates/server/src/dashboard/stats.rs @@ -1326,6 +1326,7 @@ mod tests { AppState { execution: Default::default(), miden_sessions: std::sync::Arc::new(crate::session::MidenSessions::default()), + modules: None, storage: Arc::new(storage), metadata: Arc::new(metadata), network_client: Arc::new(MockNetworkClient::new()), @@ -2661,6 +2662,7 @@ mod postgres_tests { std::fs::create_dir_all(&keystore_dir).expect("keystore dir"); let ack = AckRegistry::new(keystore_dir).await.expect("ack"); AppState { + modules: None, execution: Default::default(), miden_sessions: std::sync::Arc::new(crate::session::MidenSessions::default()), storage: Arc::new(MockStorageBackend::new()), diff --git a/crates/server/src/delta_object.rs b/crates/server/src/delta_object.rs index faac90a3..b7d095c9 100644 --- a/crates/server/src/delta_object.rs +++ b/crates/server/src/delta_object.rs @@ -666,6 +666,7 @@ mod tests { proposal_type: "p2id".to_string(), ..ProposalMetadata::default() }), + modules: None, }), ..Default::default() }; @@ -710,6 +711,7 @@ mod tests { proposal_type: "p2id".to_string(), ..ProposalMetadata::default() }), + modules: None, }), delta_payload: serde_json::json!({ "metadata": { "proposal_type": "add_signer" } diff --git a/crates/server/src/delta_summary/build.rs b/crates/server/src/delta_summary/build.rs index 4741f8be..362ae25b 100644 --- a/crates/server/src/delta_summary/build.rs +++ b/crates/server/src/delta_summary/build.rs @@ -47,6 +47,7 @@ pub fn build_metadata( counterparty: counterparty_from_proposal(&proposal), note_counts: Default::default(), proposal: Some(proposal), + modules: None, }) } } @@ -96,6 +97,7 @@ fn assemble(summary: &TransactionSummary, proposal: Option) -> counterparty, note_counts, proposal, + modules: None, } } @@ -409,6 +411,7 @@ mod tests { amount: Some("100".to_string()), ..ProposalMetadata::default() }), + modules: None, }; let value = metadata_to_value(&original); let round_tripped = metadata_from_value(value).expect("metadata parses"); diff --git a/crates/server/src/delta_summary/decode.rs b/crates/server/src/delta_summary/decode.rs index fdd39511..37517d7e 100644 --- a/crates/server/src/delta_summary/decode.rs +++ b/crates/server/src/delta_summary/decode.rs @@ -10,10 +10,15 @@ use super::ProposalMetadata; /// Decode a [`TransactionSummary`] from a persisted `delta_payload`. /// /// Handles both shapes: the multisig wrapper `{ tx_summary: {data}, -/// metadata, signatures? }` and the raw `{ data: base64 }`. Returns a -/// short stable token string on failure. +/// metadata, signatures? }` and the raw `{ data: base64 }`. A top-level +/// `data` wins, as it does where the delta is verified and acked, so an +/// extra `tx_summary` key cannot change what is shown. Returns a short +/// stable token string on failure. pub fn decode_transaction_summary(payload: &Value) -> Result { - let candidate = payload.get("tx_summary").unwrap_or(payload); + let candidate = match payload.get("data") { + Some(_) => payload, + None => payload.get("tx_summary").unwrap_or(payload), + }; TransactionSummary::from_json(candidate).map_err(classify_decode_error) } diff --git a/crates/server/src/delta_summary/mod.rs b/crates/server/src/delta_summary/mod.rs index eca9784e..9f27c72e 100644 --- a/crates/server/src/delta_summary/mod.rs +++ b/crates/server/src/delta_summary/mod.rs @@ -55,6 +55,30 @@ pub struct DeltaMetadata { /// `push_delta`, EVM deltas, and pushes where no proposal matched. #[serde(default, skip_serializing_if = "Option::is_none")] pub proposal: Option, + + /// The policy module configuration that approved this delta. Absent when no module ran. + #[serde(default, skip_serializing_if = "Option::is_none")] + pub modules: Option, +} + +/// What the policy modules ran with. Allowed evaluations are not listed: the catalog, params +/// version and account determine which modules ran, so only failures let through by +/// `on_error = allow` are kept. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, utoipa::ToSchema)] +pub struct ModuleApproval { + /// SHA-256 of the catalog file the approving replica loaded. + pub catalog_hash: String, + pub params_version: u64, + #[serde(default, skip_serializing_if = "Vec::is_empty")] + pub failed_open: Vec, +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, utoipa::ToSchema)] +pub struct FailedOpen { + pub module_id: String, + pub layer: String, + /// `timeout`, `error`, `invalid_decision` or `request_unavailable`; the detail is logged. + pub failure: String, } /// Closed, stable enumeration of action categories. Adding a value is diff --git a/crates/server/src/error.rs b/crates/server/src/error.rs index 260c6ac2..5cc55130 100644 --- a/crates/server/src/error.rs +++ b/crates/server/src/error.rs @@ -5,6 +5,9 @@ use chrono::{DateTime, Utc}; use serde::Serialize; use std::fmt; +/// The reason code a generic denial reports, whichever module refused. +pub const GENERIC_REASON_CODE: &str = "policy_denied"; + use guardian_shared::execution::refusal_codes; /// Why Guardian refuses to execute a proposal and leaves it to local execution. @@ -144,6 +147,33 @@ pub enum GuardianError { paused_at: DateTime, paused_reason: Option, }, + /// A policy module refused the request. Stable code `GUARDIAN_MODULE_DENIED`, HTTP 403, + /// gRPC `PERMISSION_DENIED`; `module` is the operator-chosen instance id. + ModuleDenied { + module: String, + reason_code: String, + layer: String, + /// The module's text for the requester, already checked; only for instances with + /// `client_reason = "full"`. + client_message: Option, + }, + /// A denial from an instance with `client_reason = "generic"`: same code and status as + /// [`GuardianError::ModuleDenied`], but nothing about which module refused or why. + ModuleDeniedGeneric, + /// A fail-closed policy module could not decide. Stable code + /// `GUARDIAN_MODULE_UNAVAILABLE`, HTTP 503, gRPC `UNAVAILABLE`, retryable. + ModuleUnavailable { + module: String, + }, + /// No policy module instance with this id. Stable code `GUARDIAN_MODULE_NOT_FOUND`, HTTP 404. + ModuleNotFound { + module: String, + }, + /// The instance's catalog entry does not allow operators to disable it. Stable code + /// `GUARDIAN_MODULE_NOT_DISABLEABLE`, HTTP 409. + ModuleNotDisableable { + module: String, + }, /// A new account asked to register with a signature scheme this Guardian /// does not accept (`GUARDIAN_ALLOWED_ACCOUNT_SCHEMES`). Stable code /// `signature_scheme_not_allowed`, HTTP 403 Forbidden, gRPC @@ -288,6 +318,12 @@ impl GuardianError { GuardianError::DataUnavailable(_) => StatusCode::SERVICE_UNAVAILABLE, GuardianError::AccountPaused { .. } => StatusCode::CONFLICT, GuardianError::SignatureSchemeNotAllowed { .. } => StatusCode::FORBIDDEN, + GuardianError::ModuleDenied { .. } | GuardianError::ModuleDeniedGeneric => { + StatusCode::FORBIDDEN + } + GuardianError::ModuleUnavailable { .. } => StatusCode::SERVICE_UNAVAILABLE, + GuardianError::ModuleNotFound { .. } => StatusCode::NOT_FOUND, + GuardianError::ModuleNotDisableable { .. } => StatusCode::CONFLICT, GuardianError::AccountReleased { .. } => StatusCode::CONFLICT, GuardianError::CandidateLanded { .. } => StatusCode::CONFLICT, GuardianError::ProvingUnavailable => StatusCode::CONFLICT, @@ -351,6 +387,12 @@ impl GuardianError { GuardianError::DataUnavailable(_) => tonic::Code::Unavailable, GuardianError::AccountPaused { .. } => tonic::Code::FailedPrecondition, GuardianError::SignatureSchemeNotAllowed { .. } => tonic::Code::PermissionDenied, + GuardianError::ModuleDenied { .. } | GuardianError::ModuleDeniedGeneric => { + tonic::Code::PermissionDenied + } + GuardianError::ModuleUnavailable { .. } => tonic::Code::Unavailable, + GuardianError::ModuleNotFound { .. } => tonic::Code::NotFound, + GuardianError::ModuleNotDisableable { .. } => tonic::Code::FailedPrecondition, GuardianError::AccountReleased { .. } => tonic::Code::FailedPrecondition, GuardianError::CandidateLanded { .. } => tonic::Code::FailedPrecondition, GuardianError::ProvingUnavailable => tonic::Code::FailedPrecondition, @@ -413,6 +455,12 @@ impl GuardianError { GuardianError::DataUnavailable(_) => "data_unavailable", GuardianError::AccountPaused { .. } => "GUARDIAN_ACCOUNT_PAUSED", GuardianError::SignatureSchemeNotAllowed { .. } => "signature_scheme_not_allowed", + GuardianError::ModuleDenied { .. } | GuardianError::ModuleDeniedGeneric => { + "GUARDIAN_MODULE_DENIED" + } + GuardianError::ModuleUnavailable { .. } => "GUARDIAN_MODULE_UNAVAILABLE", + GuardianError::ModuleNotFound { .. } => "GUARDIAN_MODULE_NOT_FOUND", + GuardianError::ModuleNotDisableable { .. } => "GUARDIAN_MODULE_NOT_DISABLEABLE", GuardianError::AccountReleased { .. } => "GUARDIAN_ACCOUNT_RELEASED", GuardianError::CandidateLanded { .. } => "GUARDIAN_CANDIDATE_LANDED", GuardianError::ProvingUnavailable => refusal_codes::PROVING_UNAVAILABLE, @@ -519,6 +567,16 @@ impl GuardianError { GuardianError::AccountPaused { .. } => { "This account is paused and can't approve transactions right now." } + GuardianError::ModuleDenied { .. } | GuardianError::ModuleDeniedGeneric => { + "This Guardian's policy doesn't allow this request." + } + GuardianError::ModuleUnavailable { .. } => { + "A policy check is unavailable right now. Please try again shortly." + } + GuardianError::ModuleNotFound { .. } => "That policy module doesn't exist.", + GuardianError::ModuleNotDisableable { .. } => { + "That policy module can't be switched off from the dashboard." + } GuardianError::SignatureSchemeNotAllowed { .. } => { "This Guardian doesn't accept new accounts with that signature scheme." } @@ -596,6 +654,7 @@ impl GuardianError { | GuardianError::StateNotOnChain { .. } | GuardianError::RateLimitExceeded { .. } | GuardianError::DataUnavailable(_) + | GuardianError::ModuleUnavailable { .. } | GuardianError::ExecutionBusy ) } @@ -716,6 +775,30 @@ impl fmt::Display for GuardianError { Some(reason) => write!(f, "Account is paused: {reason}"), None => write!(f, "Account is paused"), }, + GuardianError::ModuleDenied { + module, + reason_code, + layer, + .. + } => write!( + f, + "Policy module '{module}' denied the request ({layer} layer): {reason_code}" + ), + GuardianError::ModuleDeniedGeneric => { + write!(f, "A policy module denied the request (generic denial)") + } + GuardianError::ModuleUnavailable { module } => { + write!(f, "Policy module '{module}' is unavailable") + } + GuardianError::ModuleNotFound { module } => { + write!(f, "Policy module '{module}' not found") + } + GuardianError::ModuleNotDisableable { module } => { + write!( + f, + "Policy module '{module}' cannot be disabled by an operator" + ) + } GuardianError::SignatureSchemeNotAllowed { scheme, allowed_schemes, @@ -841,6 +924,19 @@ struct ErrorMeta { /// `signature_scheme_not_allowed`. #[serde(skip_serializing_if = "Option::is_none")] allowed_schemes: Option>, + /// Policy module instance id. Populated only for `GUARDIAN_MODULE_DENIED` and + /// `GUARDIAN_MODULE_UNAVAILABLE`. + #[serde(skip_serializing_if = "Option::is_none")] + module: Option, + /// Machine-readable denial reason. Populated only for `GUARDIAN_MODULE_DENIED`. + #[serde(skip_serializing_if = "Option::is_none")] + reason_code: Option, + /// `global` or `account`: which parameter layer denied. Only for `GUARDIAN_MODULE_DENIED`. + #[serde(skip_serializing_if = "Option::is_none")] + layer: Option, + /// The denying module's text for the requester. Only for a full `GUARDIAN_MODULE_DENIED`. + #[serde(skip_serializing_if = "Option::is_none")] + client_message: Option, /// RFC 3339 UTC timestamp of the guardian-switch release. Populated /// only for `GUARDIAN_ACCOUNT_RELEASED`. #[serde(skip_serializing_if = "Option::is_none")] @@ -916,6 +1012,27 @@ impl GuardianError { } => (Some(scheme.clone()), Some(allowed_schemes.clone())), _ => (None, None), }; + let client_message = match self { + GuardianError::ModuleDenied { client_message, .. } => client_message.clone(), + _ => None, + }; + let (module, reason_code, layer) = match self { + GuardianError::ModuleDenied { + module, + reason_code, + layer, + .. + } => ( + Some(module.clone()), + Some(reason_code.clone()), + Some(layer.clone()), + ), + GuardianError::ModuleDeniedGeneric => (None, Some(GENERIC_REASON_CODE.into()), None), + GuardianError::ModuleUnavailable { module } => (Some(module.clone()), None, None), + GuardianError::ModuleNotFound { module } => (Some(module.clone()), None, None), + GuardianError::ModuleNotDisableable { module } => (Some(module.clone()), None, None), + _ => (None, None, None), + }; let blocking_proposal_id = match self { GuardianError::ExecutionConflict { blocking_proposal_id, @@ -938,6 +1055,10 @@ impl GuardianError { scheme, allowed_schemes, released_at, + module, + reason_code, + layer, + client_message, blocking_proposal_id, proposal_type, reason, @@ -1266,6 +1387,30 @@ mod tests { assert!(!err.user_message().contains("falcon")); } + #[test] + fn a_generic_module_denial_names_nothing_but_the_generic_reason() { + let body = serde_json::to_value(GuardianError::ModuleDeniedGeneric.error_body()).unwrap(); + assert_eq!(body["code"], "GUARDIAN_MODULE_DENIED"); + assert_eq!( + body["meta"], + serde_json::json!({ "retryable": false, "reason_code": "policy_denied" }) + ); + assert_eq!( + GuardianError::ModuleDeniedGeneric.http_status(), + StatusCode::FORBIDDEN + ); + + let full = GuardianError::ModuleDenied { + module: "caps".into(), + reason_code: "amount_cap_exceeded".into(), + layer: "account".into(), + client_message: Some("Ask your treasury admin.".into()), + }; + let body = serde_json::to_value(full.error_body()).unwrap(); + assert_eq!(body["meta"]["module"], "caps"); + assert_eq!(body["meta"]["client_message"], "Ask your treasury admin."); + } + #[test] fn signature_scheme_not_allowed_meta_names_the_scheme_and_allowed_set() { let body = serde_json::to_value(scheme_not_allowed().error_body()).unwrap(); diff --git a/crates/server/src/lib.rs b/crates/server/src/lib.rs index eea83b8e..0e1a00ef 100644 --- a/crates/server/src/lib.rs +++ b/crates/server/src/lib.rs @@ -26,6 +26,7 @@ pub mod evm; pub mod jobs; pub mod metadata; pub mod metrics; +pub mod modules; pub mod network; pub mod openapi; pub(crate) mod secret; diff --git a/crates/server/src/modules/admin.rs b/crates/server/src/modules/admin.rs new file mode 100644 index 00000000..2ab5a371 --- /dev/null +++ b/crates/server/src/modules/admin.rs @@ -0,0 +1,792 @@ +//! Operator management of module parameters: global params, account layers, assignments. + +use serde::Serialize; + +use super::catalog::{ClientReason, Disclosure, Scope, contains_secret_reference}; +use super::pipeline::ModulePipeline; +use super::registry::{Instance, validate_params}; +use super::store::{Assigned, Change, HistoryEntry, ParamsKind}; +use crate::audit::{AuditEvent, AuditOutcome, kinds}; +use crate::dashboard::AuthenticatedOperator; +use crate::error::{GuardianError, Result}; +use crate::state::AppState; + +#[derive(Debug, Clone, Serialize)] +pub struct ModuleInstanceView { + pub module_id: String, + pub kind: String, + pub scope: &'static str, + pub hooks: Vec, + pub enabled: bool, + pub catalog_enabled: bool, + pub enabled_drift: bool, + pub operator_can_disable: bool, + pub params: serde_json::Value, + pub params_drift: bool, + pub file_managed_params: bool, + /// `name version` from `describe` at startup; absent when the startup checks failed. + pub build: Option, + pub disclosure: Disclosure, + #[serde(skip_serializing_if = "Option::is_none")] + pub description: Option, + pub client_reason: ClientReason, + pub dry_run: bool, +} + +#[derive(Debug, Clone, Serialize)] +pub struct ModuleCatalogView { + pub catalog_hash: String, + pub params_version: u64, + pub modules: Vec, +} + +#[derive(Debug, Clone, Serialize)] +pub struct AccountModuleEntry { + pub module_id: String, + pub scope: &'static str, + pub enabled: bool, + #[serde(skip_serializing_if = "Option::is_none")] + pub global_params: Option, + #[serde(skip_serializing_if = "Option::is_none")] + pub account_layer: Option, + #[serde(skip_serializing_if = "Option::is_none")] + pub params: Option, +} + +#[derive(Debug, Clone, Serialize)] +pub struct AccountModulesView { + pub account_id: String, + pub modules: Vec, +} + +#[derive(Debug, Clone, Serialize)] +pub struct ParamsHistoryView { + pub module_id: String, + pub entries: Vec, +} + +fn scope_name(scope: Scope) -> &'static str { + match scope { + Scope::All => "all", + Scope::Assigned => "assigned", + } +} + +fn pipeline(state: &AppState) -> Result<&ModulePipeline> { + state + .modules + .as_deref() + .ok_or_else(|| GuardianError::InvalidInput("no policy modules are configured".into())) +} + +fn instance<'a>(pipeline: &'a ModulePipeline, module_id: &str) -> Result<&'a Instance> { + pipeline + .instance(module_id) + .ok_or_else(|| GuardianError::ModuleNotFound { + module: module_id.to_string(), + }) +} + +fn require_reason(reason: &str) -> Result<()> { + if reason.trim().is_empty() { + return Err(GuardianError::InvalidInput("reason is required".into())); + } + Ok(()) +} + +/// Validates operator-supplied params and returns what to store: the module's normalized form +/// when it sent one. +async fn validated(instance: &Instance, params: &serde_json::Value) -> Result { + if !params.is_object() { + return Err(GuardianError::InvalidInput( + "params must be a JSON object".into(), + )); + } + if contains_secret_reference(params) { + return Err(GuardianError::InvalidInput( + "secret references cannot be set through the operator API".into(), + )); + } + let stored = validate_params(&instance.module, params, instance.config.timeout) + .await + .map_err(|e| GuardianError::InvalidInput(format!("module {}: {e}", instance.config.id)))?; + if contains_secret_reference(&stored) { + return Err(GuardianError::InvalidInput(format!( + "module {}: normalized params contain a secret reference", + instance.config.id + ))); + } + Ok(stored) +} + +async fn existing_account(state: &AppState, account_id: &str) -> Result { + let account_id = account_id.to_ascii_lowercase(); + match state.metadata.get(&account_id).await { + Ok(Some(_)) => Ok(account_id), + Ok(None) => Err(GuardianError::AccountNotFound(account_id)), + Err(e) => Err(GuardianError::StorageError(format!( + "account lookup failed: {e}" + ))), + } +} + +async fn version(pipeline: &ModulePipeline) -> Result { + pipeline + .store() + .version() + .await + .map_err(GuardianError::StorageError) +} + +fn audit( + state: &AppState, + operator: &AuthenticatedOperator, + kind: &'static str, + account_id: Option<&str>, + payload: serde_json::Value, + client_ip: Option, +) { + state.auditor.record(AuditEvent { + operator_identity: operator.operator_id.clone(), + action_kind: kind, + target_account_id: account_id.map(str::to_string), + payload, + outcome: AuditOutcome::Success, + error_code: None, + client_ip, + }); +} + +fn change<'a>( + state: &AppState, + operator: &'a AuthenticatedOperator, + reason: &'a str, +) -> Change<'a> { + Change { + operator: &operator.operator_id, + reason, + at: state.clock.now_rfc3339(), + } +} + +async fn instance_view( + pipeline: &ModulePipeline, + instance: &Instance, +) -> Result { + let params = pipeline.global_params(instance).await?; + let enabled = pipeline.enabled(instance).await?; + Ok(ModuleInstanceView { + module_id: instance.config.id.clone(), + kind: instance.config.kind.clone(), + scope: scope_name(instance.config.scope), + hooks: instance + .config + .hooks + .iter() + .map(|hook| hook.as_str().to_string()) + .collect(), + enabled, + catalog_enabled: instance.config.catalog_enabled, + enabled_drift: enabled != instance.config.catalog_enabled, + operator_can_disable: instance.config.operator_can_disable, + params_drift: params != instance.config.params, + params, + file_managed_params: instance.config.file_managed_params, + build: instance.build.clone(), + disclosure: instance.config.disclosure, + description: instance.config.description.clone(), + client_reason: instance.config.client_reason, + dry_run: instance.config.dry_run, + }) +} + +pub async fn catalog_view(state: &AppState) -> Result { + let pipeline = pipeline(state)?; + let mut modules = Vec::with_capacity(pipeline.instances().len()); + for instance in pipeline.instances() { + modules.push(instance_view(pipeline, instance).await?); + } + Ok(ModuleCatalogView { + catalog_hash: pipeline.catalog_hash.clone(), + params_version: version(pipeline).await?, + modules, + }) +} + +pub async fn account_view(state: &AppState, account_id: &str) -> Result { + let pipeline = pipeline(state)?; + let account_id = existing_account(state, account_id).await?; + let rows = pipeline + .store() + .account_params(&account_id) + .await + .map_err(GuardianError::StorageError)?; + let mut modules = Vec::new(); + for instance in pipeline + .instances() + .iter() + .filter(|instance| instance.config.scope == Scope::All) + { + modules.push(AccountModuleEntry { + module_id: instance.config.id.clone(), + scope: "all", + enabled: pipeline.enabled(instance).await?, + global_params: Some(pipeline.global_params(instance).await?), + account_layer: rows + .iter() + .find(|row| row.kind == ParamsKind::Layer && row.module_id == instance.config.id) + .map(|row| row.params.clone()), + params: None, + }); + } + modules.extend( + rows.into_iter() + .filter(|row| row.kind == ParamsKind::Assignment) + .map(|row| AccountModuleEntry { + scope: "assigned", + module_id: row.module_id, + global_params: None, + account_layer: None, + params: Some(row.params), + enabled: false, + }), + ); + for entry in modules.iter_mut().filter(|entry| entry.scope == "assigned") { + entry.enabled = match pipeline.instance(&entry.module_id) { + Some(instance) => pipeline.enabled(instance).await?, + None => false, + }; + } + Ok(AccountModulesView { + account_id, + modules, + }) +} + +pub async fn history(state: &AppState, module_id: &str) -> Result { + let pipeline = pipeline(state)?; + instance(pipeline, module_id)?; + Ok(ParamsHistoryView { + module_id: module_id.to_string(), + entries: pipeline + .store() + .history(module_id) + .await + .map_err(GuardianError::StorageError)?, + }) +} + +/// Switches an instance on for every account, after re-running its startup checks. +/// Idempotent: enabling an enabled instance changes nothing but is still audited. +pub async fn enable( + state: &AppState, + operator: &AuthenticatedOperator, + module_id: &str, + reason: &str, + client_ip: Option, +) -> Result { + require_reason(reason)?; + let pipeline = pipeline(state)?; + let instance = instance(pipeline, module_id)?; + if !pipeline.enabled(instance).await? { + let params = pipeline.global_params(instance).await?; + let checked = super::registry::check(&instance.config, &instance.module, ¶ms) + .await + .map_err(|error| { + tracing::warn!(module = %module_id, %error, "Module failed its checks; not enabled"); + GuardianError::ModuleUnavailable { + module: module_id.to_string(), + } + })?; + if checked.params != params && !instance.config.file_managed_params { + let migrator = format!( + "module:{}", + instance.build.as_deref().unwrap_or(&instance.config.kind) + ); + let migrated = pipeline + .store() + .set_global_if( + module_id, + ¶ms, + checked.params, + &Change { + operator: &migrator, + reason: "params migrated by the module", + at: state.clock.now_rfc3339(), + }, + ) + .await + .map_err(GuardianError::StorageError)?; + if !migrated { + tracing::warn!(module = %module_id, "Global params changed while the module migrated them; kept the newer value"); + } + } + pipeline + .store() + .set_enabled(module_id, true, &change(state, operator, reason)) + .await + .map_err(GuardianError::StorageError)?; + } + let payload = serde_json::json!({ "module_id": module_id, "reason": reason, "params_version": version(pipeline).await? }); + audit( + state, + operator, + kinds::MODULES_ENABLE, + None, + payload, + client_ip, + ); + instance_view(pipeline, instance).await +} + +/// Switches an instance off for every account, only if its catalog entry allows it. +pub async fn disable( + state: &AppState, + operator: &AuthenticatedOperator, + module_id: &str, + reason: &str, + client_ip: Option, +) -> Result { + require_reason(reason)?; + let pipeline = pipeline(state)?; + let instance = instance(pipeline, module_id)?; + if !instance.config.operator_can_disable { + return Err(GuardianError::ModuleNotDisableable { + module: module_id.to_string(), + }); + } + if pipeline.enabled(instance).await? { + pipeline + .store() + .set_enabled(module_id, false, &change(state, operator, reason)) + .await + .map_err(GuardianError::StorageError)?; + } + let payload = serde_json::json!({ "module_id": module_id, "reason": reason, "params_version": version(pipeline).await? }); + audit( + state, + operator, + kinds::MODULES_DISABLE, + None, + payload, + client_ip, + ); + instance_view(pipeline, instance).await +} + +pub async fn set_global( + state: &AppState, + operator: &AuthenticatedOperator, + module_id: &str, + params: serde_json::Value, + reason: &str, + client_ip: Option, +) -> Result { + require_reason(reason)?; + let pipeline = pipeline(state)?; + let instance = instance(pipeline, module_id)?; + if instance.config.file_managed_params { + return Err(GuardianError::InvalidInput(format!( + "module {module_id}: params with secret references are managed in the catalog file" + ))); + } + let params = validated(instance, ¶ms).await?; + pipeline + .store() + .set_global(module_id, params, &change(state, operator, reason)) + .await + .map_err(GuardianError::StorageError)?; + let payload = serde_json::json!({ "module_id": module_id, "reason": reason, "params_version": version(pipeline).await? }); + audit( + state, + operator, + kinds::MODULES_PARAMS_GLOBAL, + None, + payload, + client_ip, + ); + instance_view(pipeline, instance).await +} + +pub async fn set_layer( + state: &AppState, + operator: &AuthenticatedOperator, + account_id: &str, + module_id: &str, + params: Option, + reason: &str, + client_ip: Option, +) -> Result { + require_reason(reason)?; + let pipeline = pipeline(state)?; + let account_id = existing_account(state, account_id).await?; + let instance = instance(pipeline, module_id)?; + if instance.config.scope != Scope::All { + return Err(GuardianError::InvalidInput(format!( + "module {module_id}: account layers apply only to scope = \"all\" instances; assign it instead" + ))); + } + let params = match params { + Some(params) => Some(validated(instance, ¶ms).await?), + None => None, + }; + pipeline + .store() + .set_layer( + &account_id, + module_id, + params, + &change(state, operator, reason), + ) + .await + .map_err(GuardianError::StorageError)?; + let payload = serde_json::json!({ "module_id": module_id, "reason": reason, "params_version": version(pipeline).await? }); + audit( + state, + operator, + kinds::MODULES_PARAMS_ACCOUNT, + Some(&account_id), + payload, + client_ip, + ); + account_view(state, &account_id).await +} + +pub async fn set_assignment( + state: &AppState, + operator: &AuthenticatedOperator, + account_id: &str, + modules: Vec, + reason: &str, + client_ip: Option, +) -> Result { + require_reason(reason)?; + let pipeline = pipeline(state)?; + let account_id = existing_account(state, account_id).await?; + let mut to_store = Vec::with_capacity(modules.len()); + for (index, assigned) in modules.iter().enumerate() { + let instance = instance(pipeline, &assigned.module_id)?; + if instance.config.scope == Scope::All { + return Err(GuardianError::InvalidInput(format!( + "module {}: scope = \"all\" applies to every account; set an account layer instead", + assigned.module_id + ))); + } + if modules[..index] + .iter() + .any(|earlier| earlier.module_id == assigned.module_id) + { + return Err(GuardianError::InvalidInput(format!( + "module {} listed twice", + assigned.module_id + ))); + } + to_store.push(Assigned { + module_id: assigned.module_id.clone(), + params: validated(instance, &assigned.params).await?, + }); + } + pipeline + .store() + .set_assignment(&account_id, to_store, &change(state, operator, reason)) + .await + .map_err(GuardianError::StorageError)?; + let payload = + serde_json::json!({ "reason": reason, "params_version": version(pipeline).await? }); + audit( + state, + operator, + kinds::MODULES_ASSIGNMENT, + Some(&account_id), + payload, + client_ip, + ); + account_view(state, &account_id).await +} + +#[cfg(test)] +mod tests { + use std::collections::BTreeSet; + use std::sync::Arc; + + use guardian_module_sdk::basic_policy::BasicPolicy; + use serde_json::json; + + use super::*; + use crate::metadata::AccountMetadata; + use crate::metadata::auth::Auth; + use crate::modules::catalog::{HookName, OnError}; + use crate::modules::testing::{instance, instance_with_params, pipeline}; + use crate::testing::helpers::create_test_app_state_with_mocks; + use crate::testing::mocks::{MockMetadataStore, MockNetworkClient, MockStorageBackend}; + + const ACCOUNT: &str = "0xacc"; + + fn operator() -> AuthenticatedOperator { + AuthenticatedOperator { + operator_id: "0xop".into(), + commitment: "0xop".into(), + effective_permissions: Arc::new(BTreeSet::new()), + } + } + + fn state() -> AppState { + let metadata = MockMetadataStore::new().with_row(AccountMetadata { + account_id: ACCOUNT.into(), + auth: Auth::MidenFalconRpo { + cosigner_commitments: vec!["0xs1".into()], + }, + network_config: crate::metadata::NetworkConfig::miden_default(), + created_at: "2026-10-15T00:00:00Z".into(), + updated_at: "2026-10-15T00:00:00Z".into(), + has_pending_candidate: false, + paused_at: None, + paused_reason: None, + released_at: None, + }); + let mut state = create_test_app_state_with_mocks( + Arc::new(MockStorageBackend::new()), + Arc::new(MockNetworkClient::new()), + Arc::new(metadata), + ); + let hooks = [HookName::BeforeTransactionApproved]; + let mut optional = instance("optional", &hooks, OnError::Deny, Arc::new(BasicPolicy)); + optional.config.scope = Scope::Assigned; + let mut secret = instance("vendor", &hooks, OnError::Deny, Arc::new(BasicPolicy)); + secret.config.file_managed_params = true; + secret.config.operator_can_disable = false; + state.modules = Some(pipeline(vec![ + instance_with_params( + "blocklist", + &hooks, + Arc::new(BasicPolicy), + json!({ "recipient_denylist": ["0xaaa"] }), + ), + optional, + secret, + ])); + state + } + + #[tokio::test] + async fn operator_writes_store_the_shape_the_module_normalized() { + let mut stub = crate::modules::testing::ProtocolStub::new(); + stub.normalized = Some(json!({ "new_name": 5 })); + let mut state = state(); + state.modules = Some(pipeline(vec![instance( + "migrating", + &[HookName::BeforeTransactionApproved], + OnError::Deny, + Arc::new(stub), + )])); + let view = set_global( + &state, + &operator(), + "migrating", + json!({ "old_name": 5 }), + "OP-93", + None, + ) + .await + .unwrap(); + assert_eq!(view.params, json!({ "new_name": 5 })); + let view = set_layer( + &state, + &operator(), + ACCOUNT, + "migrating", + Some(json!({ "old_name": 1 })), + "OP-94", + None, + ) + .await + .unwrap(); + assert_eq!( + view.modules[0].account_layer, + Some(json!({ "new_name": 5 })) + ); + } + + #[tokio::test] + async fn global_and_account_writes_are_validated_recorded_and_visible() { + let state = state(); + let operator = operator(); + set_global( + &state, + &operator, + "blocklist", + json!({ "recipient_denylist": ["0xaaa", "0xddd"] }), + "OP-90", + None, + ) + .await + .unwrap(); + let view = set_layer( + &state, + &operator, + ACCOUNT, + "blocklist", + Some(json!({ "recipient_denylist": ["0xccc"] })), + "OP-91", + None, + ) + .await + .unwrap(); + let entry = &view.modules[0]; + assert_eq!( + entry.global_params, + Some(json!({ "recipient_denylist": ["0xaaa", "0xddd"] })) + ); + assert_eq!( + entry.account_layer, + Some(json!({ "recipient_denylist": ["0xccc"] })) + ); + + let history = history(&state, "blocklist").await.unwrap().entries; + assert_eq!(history.len(), 2); + assert_eq!(history[0].reason, "OP-90"); + assert_eq!(history[1].account_id.as_deref(), Some(ACCOUNT)); + } + + #[tokio::test] + async fn invalid_writes_are_refused() { + let state = state(); + let operator = operator(); + let cases = [ + set_global( + &state, + &operator, + "blocklist", + json!({ "unknown": 1 }), + "r", + None, + ) + .await + .err(), + set_global( + &state, + &operator, + "blocklist", + json!({ "k": { "$secret": "x" } }), + "r", + None, + ) + .await + .err(), + set_global(&state, &operator, "blocklist", json!({}), " ", None) + .await + .err(), + set_global(&state, &operator, "vendor", json!({}), "r", None) + .await + .err(), + set_layer( + &state, + &operator, + ACCOUNT, + "optional", + Some(json!({})), + "r", + None, + ) + .await + .err(), + set_layer( + &state, + &operator, + "0xmissing", + "blocklist", + Some(json!({})), + "r", + None, + ) + .await + .err(), + set_assignment( + &state, + &operator, + ACCOUNT, + vec![Assigned { + module_id: "blocklist".into(), + params: json!({}), + }], + "r", + None, + ) + .await + .err(), + ]; + for (index, case) in cases.into_iter().enumerate() { + assert!(case.is_some(), "case {index} should be refused"); + } + assert!(matches!( + set_global(&state, &operator, "nope", json!({}), "r", None).await, + Err(GuardianError::ModuleNotFound { .. }) + )); + } + + #[tokio::test] + async fn disable_and_enable_follow_the_catalog_rules() { + let state = state(); + let operator = operator(); + let pipeline = state.modules.as_deref().unwrap(); + pipeline + .store() + .seed_instance( + "blocklist", + true, + &json!({ "recipient_denylist": ["0xaaa"] }), + "t0", + ) + .await + .unwrap(); + + let view = disable(&state, &operator, "blocklist", "faulty vendor", None) + .await + .unwrap(); + assert!(!view.enabled); + assert!(view.enabled_drift); + let view = enable(&state, &operator, "blocklist", "vendor fixed", None) + .await + .unwrap(); + assert!(view.enabled); + let history = history(&state, "blocklist").await.unwrap().entries; + assert_eq!(history.last().unwrap().new, json!({ "enabled": true })); + } + + #[tokio::test] + async fn an_instance_the_catalog_protects_cannot_be_disabled() { + let state = state(); + let pipeline = state.modules.as_deref().unwrap(); + assert!(pipeline.instance("vendor").is_some()); + let result = disable(&state, &operator(), "protected", "r", None).await; + assert!(matches!(result, Err(GuardianError::ModuleNotFound { .. }))); + let result = disable(&state, &operator(), "vendor", "r", None).await; + assert!(matches!( + result, + Err(GuardianError::ModuleNotDisableable { .. }) + )); + } + + #[tokio::test] + async fn optional_modules_are_assigned_per_account() { + let state = state(); + let view = set_assignment( + &state, + &operator(), + ACCOUNT, + vec![Assigned { + module_id: "optional".into(), + params: json!({ "recipient_denylist": ["0xeee"] }), + }], + "customer request", + None, + ) + .await + .unwrap(); + assert!( + view.modules + .iter() + .any(|m| m.module_id == "optional" && m.params.is_some()) + ); + } +} diff --git a/crates/server/src/modules/catalog.rs b/crates/server/src/modules/catalog.rs new file mode 100644 index 00000000..2690bd8b --- /dev/null +++ b/crates/server/src/modules/catalog.rs @@ -0,0 +1,638 @@ +//! The module catalog: instances declared in the file at `GUARDIAN_MODULES_CONFIG`. + +use std::collections::HashSet; +use std::path::{Path, PathBuf}; +use std::time::Duration; + +use guardian_module_sdk::Hook; +use serde::Deserialize; +use sha2::{Digest, Sha256}; + +pub const CONFIG_ENV: &str = "GUARDIAN_MODULES_CONFIG"; +const TIMEOUT_MAX_MS: u64 = 1000; + +#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum Scope { + All, + Assigned, +} + +#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum OnError { + #[default] + Deny, + Allow, +} + +#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum HookName { + BeforeTransactionApproved, + BeforeProposalCreated, + BeforeAccountRegistered, +} + +impl HookName { + /// The catalog spelling, for example `before_transaction_approved`. + pub fn as_str(self) -> &'static str { + match self { + HookName::BeforeTransactionApproved => "before_transaction_approved", + HookName::BeforeProposalCreated => "before_proposal_created", + HookName::BeforeAccountRegistered => "before_account_registered", + } + } + + pub fn proto(self) -> Hook { + match self { + HookName::BeforeTransactionApproved => Hook::BeforeTransactionApproved, + HookName::BeforeProposalCreated => Hook::BeforeProposalCreated, + HookName::BeforeAccountRegistered => Hook::BeforeAccountRegistered, + } + } +} + +#[derive(Debug, Deserialize)] +#[serde(deny_unknown_fields)] +struct AuthEntry { + token_file: PathBuf, +} + +#[derive(Debug, Deserialize)] +#[serde(deny_unknown_fields)] +struct TlsEntry { + ca_file: Option, + client_cert_file: Option, + client_key_file: Option, +} + +#[derive(Debug, Deserialize)] +#[serde(deny_unknown_fields)] +struct InstanceEntry { + id: String, + kind: String, + endpoint: Option, + scope: Scope, + hooks: Vec, + timeout_ms: u64, + #[serde(default)] + on_error: OnError, + #[serde(default = "enabled_default")] + enabled: bool, + #[serde(default)] + operator_can_disable: bool, + #[serde(default)] + disclosure: Disclosure, + description: Option, + #[serde(default)] + client_reason: ClientReason, + #[serde(default = "enabled_default")] + dry_run: bool, + auth: Option, + tls: Option, + #[serde(default)] + params: Option, +} + +fn enabled_default() -> bool { + true +} + +/// What an account's cosigners may learn about an instance (RFC 0002 section 2.7). +#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Deserialize, serde::Serialize)] +#[serde(rename_all = "snake_case")] +pub enum Disclosure { + #[default] + None, + Summary, + Params, +} + +/// How a denial from an instance reaches the client (RFC 0002 section 4.1). +#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Deserialize, serde::Serialize)] +#[serde(rename_all = "snake_case")] +pub enum ClientReason { + #[default] + Full, + Generic, +} + +const DESCRIPTION_MAX_CHARS: usize = 500; + +#[derive(Debug, Deserialize)] +#[serde(deny_unknown_fields)] +struct CatalogFile { + #[serde(default, rename = "module")] + modules: Vec, +} + +#[derive(Debug, Clone)] +pub struct InstanceConfig { + pub id: String, + pub kind: String, + pub endpoint: Option, + pub scope: Scope, + pub hooks: Vec, + pub timeout: Duration, + pub on_error: OnError, + /// The flag in force: the stored runtime flag once the instance has been seeded. + pub enabled: bool, + /// The catalog's `enabled`, a seed only; kept to report drift. + pub catalog_enabled: bool, + pub operator_can_disable: bool, + pub disclosure: Disclosure, + pub description: Option, + pub client_reason: ClientReason, + /// Whether the dry-run check may call the instance. + pub dry_run: bool, + pub auth_token: Option, + pub tls: Option, + /// Seed for the instance's global params; operator-managed after the first start. + pub params: serde_json::Value, + /// Params holding secret references stay file-managed: the operator API cannot change them. + pub file_managed_params: bool, +} + +#[derive(Debug, Clone)] +pub struct Catalog { + pub instances: Vec, + pub hash: String, +} + +fn json_object(value: Option, what: &str) -> Result { + let value = match value { + Some(value) => serde_json::to_value(value).map_err(|e| format!("{what}: {e}"))?, + None => serde_json::Value::Object(Default::default()), + }; + if value.is_object() { + Ok(value) + } else { + Err(format!("{what} must be a table")) + } +} + +pub(crate) fn contains_secret_reference(value: &serde_json::Value) -> bool { + match value { + serde_json::Value::Object(map) => { + map.contains_key("$secret") || map.values().any(contains_secret_reference) + } + serde_json::Value::Array(items) => items.iter().any(contains_secret_reference), + _ => false, + } +} + +/// How the Guardian reaches a remote module. `grpc://` is TLS; plain text is the explicit +/// `grpc+insecure://` scheme and only for a loopback host. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum Transport { + Tls, + PlaintextLoopback, +} + +impl Transport { + pub const TLS_SCHEME: &str = "grpc://"; + pub const PLAINTEXT_SCHEME: &str = "grpc+insecure://"; + + pub fn of(endpoint: &str, has_tls_settings: bool) -> Result { + if let Some(rest) = endpoint.strip_prefix(Self::PLAINTEXT_SCHEME) { + if has_tls_settings { + return Err("tls settings need a grpc:// endpoint".into()); + } + let uri: tonic::transport::Uri = format!("http://{rest}") + .parse() + .map_err(|e| format!("invalid endpoint: {e}"))?; + let host = uri.host().unwrap_or_default(); + let loopback = host.eq_ignore_ascii_case("localhost") + || host + .trim_start_matches('[') + .trim_end_matches(']') + .parse::() + .is_ok_and(|ip| ip.is_loopback()); + if !loopback { + return Err(format!( + "plain text is only allowed to a loopback host, not {host}; use grpc://" + )); + } + Ok(Self::PlaintextLoopback) + } else if endpoint.starts_with(Self::TLS_SCHEME) { + Ok(Self::Tls) + } else { + Err("endpoint must start with grpc:// (TLS) or grpc+insecure:// (loopback)".into()) + } + } +} + +impl Catalog { + /// Prod-stage rules: remote modules use TLS and authenticate with a bearer token. + pub fn check_production(&self) -> Result<(), String> { + for config in &self.instances { + let Some(endpoint) = &config.endpoint else { + continue; + }; + if Transport::of(endpoint, config.tls.is_some())? != Transport::Tls { + return Err(format!( + "module {}: plain text is not allowed in the prod stage", + config.id + )); + } + if config.auth_token.is_none() { + return Err(format!( + "module {}: auth is mandatory for remote modules in the prod stage", + config.id + )); + } + } + Ok(()) + } + + pub fn load(path: &Path) -> Result { + let text = std::fs::read_to_string(path) + .map_err(|e| format!("cannot read module catalog {}: {e}", path.display()))?; + Self::parse(&text, path.parent()) + } + + pub fn parse(text: &str, base_dir: Option<&Path>) -> Result { + let file: CatalogFile = + toml::from_str(text).map_err(|e| format!("invalid module catalog: {e}"))?; + + let mut seen = HashSet::new(); + let mut instances = Vec::with_capacity(file.modules.len()); + for entry in file.modules { + let id = entry.id; + if !seen.insert(id.clone()) { + return Err(format!("module {id}: duplicate id")); + } + if entry.hooks.is_empty() { + return Err(format!("module {id}: hooks must not be empty")); + } + if !(1..=TIMEOUT_MAX_MS).contains(&entry.timeout_ms) { + return Err(format!( + "module {id}: timeout_ms must be between 1 and {TIMEOUT_MAX_MS}" + )); + } + let remote = entry.kind == "grpc"; + if remote != entry.endpoint.is_some() { + return Err(format!( + "module {id}: endpoint is required for kind grpc and only allowed for it" + )); + } + let description = entry + .description + .map(|text| text.trim().to_string()) + .filter(|text| !text.is_empty()); + if entry.disclosure != Disclosure::None && description.is_none() { + return Err(format!( + "module {id}: a description is required unless disclosure = \"none\"" + )); + } + if description + .as_ref() + .is_some_and(|text| text.chars().count() > DESCRIPTION_MAX_CHARS) + { + return Err(format!( + "module {id}: description is longer than {DESCRIPTION_MAX_CHARS} characters" + )); + } + if !remote && (entry.auth.is_some() || entry.tls.is_some()) { + return Err(format!( + "module {id}: auth and tls are only allowed for remote kinds" + )); + } + if let Some(endpoint) = &entry.endpoint { + Transport::of(endpoint, entry.tls.is_some()) + .map_err(|e| format!("module {id}: {e}"))?; + } + let params = json_object(entry.params, &format!("module {id} params"))?; + if remote && contains_secret_reference(¶ms) { + return Err(format!( + "module {id}: secret references are not allowed in remote module params" + )); + } + if entry.disclosure == Disclosure::Params && contains_secret_reference(¶ms) { + return Err(format!( + "module {id}: disclosure = \"params\" would show cosigners the secret references in its params; use \"summary\" or \"none\"" + )); + } + let auth_token = entry + .auth + .map(|auth| { + let path = match base_dir { + Some(dir) if auth.token_file.is_relative() => dir.join(&auth.token_file), + _ => auth.token_file.clone(), + }; + std::fs::read_to_string(&path) + .map(zeroize::Zeroizing::new) + .map(|token| guardian_module_sdk::secrecy::SecretString::from(token.trim())) + .map_err(|e| format!("module {id}: cannot read token file: {e}")) + }) + .transpose()?; + let resolve = |path: &PathBuf| match base_dir { + Some(dir) if path.is_relative() => dir.join(path), + _ => path.clone(), + }; + let read = |path: &PathBuf, what: &str| { + std::fs::read(resolve(path)) + .map_err(|e| format!("module {id}: cannot read {what}: {e}")) + }; + let tls = entry + .tls + .map(|tls| { + let client_identity = match (&tls.client_cert_file, &tls.client_key_file) { + (Some(cert), Some(key)) => { + let key = zeroize::Zeroizing::new(read(key, "client key")?); + let key = String::from_utf8(key.to_vec()) + .map_err(|_| format!("module {id}: client key is not PEM"))?; + Some(guardian_module_sdk::ClientIdentity::new( + read(cert, "client certificate")?, + guardian_module_sdk::secrecy::SecretString::from(key), + )) + } + (None, None) => None, + _ => { + return Err(format!( + "module {id}: client_cert_file and client_key_file go together" + )); + } + }; + Ok(guardian_module_sdk::ModuleTls::new( + tls.ca_file + .as_ref() + .map(|ca| read(ca, "CA file")) + .transpose()?, + client_identity, + )) + }) + .transpose()?; + instances.push(InstanceConfig { + id, + kind: entry.kind, + endpoint: entry.endpoint, + scope: entry.scope, + hooks: entry.hooks, + timeout: Duration::from_millis(entry.timeout_ms), + on_error: entry.on_error, + enabled: entry.enabled, + catalog_enabled: entry.enabled, + operator_can_disable: entry.operator_can_disable, + disclosure: entry.disclosure, + description, + client_reason: entry.client_reason, + dry_run: entry.dry_run, + auth_token, + tls, + file_managed_params: contains_secret_reference(¶ms), + params, + }); + } + + Ok(Self { + instances, + hash: format!("0x{}", hex::encode(Sha256::digest(text.as_bytes()))), + }) + } +} + +#[cfg(test)] +mod tests { + use super::*; + + fn parse(text: &str) -> Result { + Catalog::parse(text, None) + } + + const VALID: &str = r#" +[[module]] +id = "caps" +kind = "basic-policy" +scope = "all" +hooks = ["before_transaction_approved", "before_proposal_created"] +timeout_ms = 20 +params = { max_amount_per_tx = { "0xaa" = "1000" } } + +[[module]] +id = "signers" +kind = "basic-policy" +scope = "assigned" +hooks = ["before_account_registered"] +timeout_ms = 20 +on_error = "allow" +"#; + + #[test] + fn parses_instances() { + let catalog = parse(VALID).unwrap(); + assert_eq!(catalog.instances.len(), 2); + assert_eq!(catalog.instances[1].on_error, OnError::Allow); + assert!(!catalog.instances[0].file_managed_params); + assert!(catalog.hash.starts_with("0x")); + } + + #[test] + fn rejects_invalid_catalogs() { + let cases = [ + ( + "empty hooks", + VALID.replacen(r#"hooks = ["before_account_registered"]"#, "hooks = []", 1), + ), + ( + "unknown hook", + VALID.replacen( + "before_account_registered", + "after_transaction_committed", + 1, + ), + ), + ( + "default scope", + VALID.replacen(r#"scope = "assigned""#, r#"scope = "default""#, 1), + ), + ( + "timeout", + VALID.replacen("timeout_ms = 20", "timeout_ms = 5000", 1), + ), + ( + "per-account params in the file", + VALID.replacen( + r#"on_error = "allow""#, + "on_error = \"allow\"\naccount_params = { \"0x1\" = {} }", + 1, + ), + ), + ( + "duplicate id", + VALID.replacen(r#"id = "signers""#, r#"id = "caps""#, 1), + ), + ( + "grpc without endpoint", + VALID.replacen(r#"kind = "basic-policy""#, r#"kind = "grpc""#, 1), + ), + ]; + for (name, text) in cases { + assert!(parse(&text).is_err(), "{name} should be rejected"); + } + } + + #[test] + fn params_with_secret_references_are_file_managed() { + let text = VALID.replacen( + r#"params = { max_amount_per_tx = { "0xaa" = "1000" } }"#, + r#"params = { api_key = { "$secret" = "x" } }"#, + 1, + ); + assert!(parse(&text).unwrap().instances[0].file_managed_params); + } + + #[test] + fn tokens_never_appear_in_debug_output() { + let dir = std::env::temp_dir().join(format!("modules_{:016x}", rand::random::())); + std::fs::create_dir_all(&dir).unwrap(); + std::fs::write(dir.join("token"), "very-secret-token\n").unwrap(); + let text = r#" +[[module]] +id = "remote" +kind = "grpc" +endpoint = "grpc://127.0.0.1:7443" +scope = "all" +hooks = ["before_transaction_approved"] +timeout_ms = 20 +auth = { token_file = "token" } +"#; + let catalog = Catalog::parse(text, Some(&dir)).unwrap(); + assert!(!format!("{catalog:?}").contains("very-secret-token")); + assert!(catalog.instances[0].auth_token.is_some()); + std::fs::remove_dir_all(dir).ok(); + } + + fn remote(endpoint: &str, extra: &str) -> String { + format!( + r#" +[[module]] +id = "remote" +kind = "grpc" +endpoint = "{endpoint}" +scope = "all" +hooks = ["before_transaction_approved"] +timeout_ms = 20 +{extra} +"# + ) + } + + #[test] + fn plain_text_is_only_for_loopback_hosts() { + for endpoint in [ + "grpc+insecure://127.0.0.1:7443", + "grpc+insecure://localhost:7443", + "grpc+insecure://[::1]:7443", + ] { + assert!(parse(&remote(endpoint, "")).is_ok(), "{endpoint}"); + } + for endpoint in [ + "grpc+insecure://risk.internal:7443", + "grpc+insecure://10.0.0.5:7443", + "http://127.0.0.1:7443", + ] { + assert!(parse(&remote(endpoint, "")).is_err(), "{endpoint}"); + } + assert!( + parse(&remote( + "grpc+insecure://127.0.0.1:7443", + r#"tls = { ca_file = "ca.pem" }"# + )) + .is_err() + ); + } + + #[test] + fn prod_requires_tls_and_a_token_for_remote_modules() { + let dir = std::env::temp_dir().join(format!("modules_{:016x}", rand::random::())); + std::fs::create_dir_all(&dir).unwrap(); + std::fs::write(dir.join("token"), "t").unwrap(); + let auth = r#"auth = { token_file = "token" }"#; + let check = |endpoint: &str, extra: &str| { + Catalog::parse(&remote(endpoint, extra), Some(&dir)) + .unwrap() + .check_production() + }; + assert!(check("grpc://risk.internal:7443", auth).is_ok()); + assert!(check("grpc://risk.internal:7443", "").is_err()); + assert!(check("grpc+insecure://127.0.0.1:7443", auth).is_err()); + std::fs::remove_dir_all(dir).ok(); + } + + #[test] + fn a_client_certificate_needs_its_key() { + let text = remote( + "grpc://risk.internal:7443", + r#"tls = { client_cert_file = "cert.pem" }"#, + ); + assert!(parse(&text).unwrap_err().contains("go together")); + } + + #[test] + fn disclosure_defaults_to_nothing_and_needs_a_description_to_open_up() { + let base = remote("grpc+insecure://127.0.0.1:7443", ""); + let module = &parse(&base).unwrap().instances[0]; + assert_eq!(module.disclosure, Disclosure::None); + assert_eq!(module.client_reason, ClientReason::Full); + assert!(module.dry_run); + + let without = remote( + "grpc+insecure://127.0.0.1:7443", + r#"disclosure = "summary""#, + ); + assert!( + parse(&without) + .unwrap_err() + .contains("description is required") + ); + + let with = remote( + "grpc+insecure://127.0.0.1:7443", + "disclosure = \"params\"\ndescription = \"At most 5 per transaction\"\nclient_reason = \"generic\"\ndry_run = false", + ); + let module = &parse(&with).unwrap().instances[0]; + assert_eq!(module.disclosure, Disclosure::Params); + assert_eq!( + module.description.as_deref(), + Some("At most 5 per transaction") + ); + assert_eq!(module.client_reason, ClientReason::Generic); + assert!(!module.dry_run); + + let long = remote( + "grpc+insecure://127.0.0.1:7443", + &format!( + "disclosure = \"summary\"\ndescription = \"{}\"", + "x".repeat(501) + ), + ); + assert!(parse(&long).unwrap_err().contains("longer than")); + } + + #[test] + fn params_holding_secret_references_cannot_be_disclosed() { + let catalog = |disclosure: &str| { + format!( + r#" +[[module]] +id = "vendor" +kind = "basic-policy" +scope = "all" +hooks = ["before_transaction_approved"] +timeout_ms = 20 +disclosure = "{disclosure}" +description = "Vendor screening" +params = {{ api_key = {{ "$secret" = "vendor-key" }} }} +"# + ) + }; + assert!( + parse(&catalog("params")) + .unwrap_err() + .contains("secret references") + ); + assert!(parse(&catalog("summary")).is_ok()); + } +} diff --git a/crates/server/src/modules/check_limit.rs b/crates/server/src/modules/check_limit.rs new file mode 100644 index 00000000..92ee7370 --- /dev/null +++ b/crates/server/src/modules/check_limit.rs @@ -0,0 +1,127 @@ +//! The rate limit on dry-run proposal checks, per account and signer. Process-wide and +//! independent of the module catalog: a check rebuilds and verifies the account's state even +//! when no module is configured. + +use std::collections::HashMap; +use std::sync::OnceLock; + +use crate::error::GuardianError; + +/// Env var for how many dry-run checks one signer may make for one account per minute. +pub const CHECK_RATE_ENV: &str = "GUARDIAN_MODULE_CHECK_RATE_PER_MIN"; +const CHECK_RATE_DEFAULT: usize = 30; +const CHECK_WINDOW: std::time::Duration = std::time::Duration::from_secs(60); + +/// Per account and signer sliding window for dry-run checks, so the check cannot be used to +/// enumerate a denylist or a model's thresholds. Per replica. +pub struct CheckLimiter { + per_minute: usize, + calls: + std::sync::Mutex>>, +} + +fn check_rate(raw: Result) -> Result { + match raw { + Err(std::env::VarError::NotPresent) => Ok(CHECK_RATE_DEFAULT), + Ok(value) => value + .trim() + .parse::() + .ok() + .filter(|limit| *limit > 0) + .ok_or_else(|| format!("{CHECK_RATE_ENV} must be a positive integer, got {value:?}")), + Err(std::env::VarError::NotUnicode(_)) => { + Err(format!("{CHECK_RATE_ENV} must contain valid UTF-8")) + } + } +} + +impl CheckLimiter { + pub fn with_limit(per_minute: usize) -> Self { + Self { + per_minute, + calls: Default::default(), + } + } + + /// The limit from `GUARDIAN_MODULE_CHECK_RATE_PER_MIN`, the default when unset; a value + /// that is not a positive integer refuses startup. + fn from_env() -> Result { + check_rate(std::env::var(CHECK_RATE_ENV)).map(Self::with_limit) + } + + pub fn admit(&self, account_id: &str, signer: &str) -> Result<(), GuardianError> { + let now = std::time::Instant::now(); + let mut calls = self + .calls + .lock() + .map_err(|_| GuardianError::StorageError("check limiter poisoned".into()))?; + calls.retain(|_, window| { + window.retain(|at| now.duration_since(*at) < CHECK_WINDOW); + !window.is_empty() + }); + let window = calls + .entry((account_id.to_ascii_lowercase(), signer.to_ascii_lowercase())) + .or_default(); + if window.len() >= self.per_minute { + let retry_after = window + .front() + .map(|oldest| CHECK_WINDOW.saturating_sub(now.duration_since(*oldest))) + .unwrap_or(CHECK_WINDOW); + return Err(GuardianError::RateLimitExceeded { + retry_after_secs: u32::try_from(retry_after.as_secs().max(1)).unwrap_or(60), + scope: "proposal_check".into(), + }); + } + window.push_back(now); + Ok(()) + } +} + +static LIMITER: OnceLock = OnceLock::new(); + +/// Installs the limiter from `GUARDIAN_MODULE_CHECK_RATE_PER_MIN`; a malformed value fails +/// startup. Called once by the server builder. +pub fn init_from_env() -> Result<(), String> { + let limiter = CheckLimiter::from_env()?; + let _ = LIMITER.set(limiter); + Ok(()) +} + +/// Counts one check by `signer` for `account_id`, or refuses it with `rate_limit_exceeded`. +pub fn admit(account_id: &str, signer: &str) -> Result<(), GuardianError> { + LIMITER + .get_or_init(|| CheckLimiter::with_limit(CHECK_RATE_DEFAULT)) + .admit(account_id, signer) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn the_check_rate_is_a_positive_integer_or_startup_fails() { + use std::env::VarError; + assert_eq!( + check_rate(Err(VarError::NotPresent)), + Ok(CHECK_RATE_DEFAULT) + ); + assert_eq!(check_rate(Ok(" 12 ".into())), Ok(12)); + for bad in ["0", "-3", "thirty", "1.5", ""] { + assert!(check_rate(Ok(bad.into())).is_err(), "{bad:?}"); + } + } + + #[test] + fn dry_runs_are_limited_per_account_and_signer() { + let limiter = CheckLimiter::with_limit(3); + for _ in 0..3 { + limiter.admit("0xacc", "0xsigner").unwrap(); + } + assert!(matches!( + limiter.admit("0xacc", "0xsigner"), + Err(GuardianError::RateLimitExceeded { .. }) + )); + assert!(limiter.admit("0xacc", "0xother").is_ok()); + assert!(limiter.admit("0xother", "0xsigner").is_ok()); + } +} diff --git a/crates/server/src/modules/disclosure.rs b/crates/server/src/modules/disclosure.rs new file mode 100644 index 00000000..a5c6b354 --- /dev/null +++ b/crates/server/src/modules/disclosure.rs @@ -0,0 +1,177 @@ +//! What an account's cosigners may learn about the policies that apply to them (RFC 0002 +//! section 2.7). + +use serde::{Deserialize, Serialize}; + +use super::catalog::{Disclosure, Scope}; +use super::pipeline::ModulePipeline; +use super::store::ParamsKind; +use crate::error::GuardianError; + +/// One policy as the account's cosigners see it. +#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, utoipa::ToSchema)] +pub struct PolicyEntry { + pub module_id: String, + pub hooks: Vec, + pub description: String, + /// `disclosure = "params"`: the instance's global params, or the account's own params for + /// an assigned instance. + #[serde(skip_serializing_if = "Option::is_none")] + #[schema(value_type = Option)] + pub params: Option, + /// `disclosure = "params"` on a `scope = all` instance: this account's layer, when set. + #[serde(skip_serializing_if = "Option::is_none")] + #[schema(value_type = Option)] + pub account_layer: Option, +} + +impl ModulePipeline { + /// The enabled instances that apply to the account, in evaluation order, without those + /// whose catalog entry discloses nothing. + pub async fn disclosed(&self, account_id: &str) -> Result, GuardianError> { + let account_id = account_id.to_ascii_lowercase(); + let (_, rows, account_rows) = self.snapshot(&account_id).await?; + let entry = |instance: &super::registry::Instance, + params: Option, + account_layer: Option| { + let config = &instance.config; + let show_params = config.disclosure == Disclosure::Params; + PolicyEntry { + module_id: config.id.clone(), + hooks: config + .hooks + .iter() + .map(|hook| hook.as_str().to_string()) + .collect(), + description: config.description.clone().unwrap_or_default(), + params: params.filter(|_| show_params), + account_layer: account_layer.filter(|_| show_params), + } + }; + let visible = |instance: &super::registry::Instance| { + instance.config.disclosure != Disclosure::None && Self::enabled_in(&rows, instance) + }; + let mut policies = Vec::new(); + for instance in self + .instances() + .iter() + .filter(|instance| instance.config.scope == Scope::All && visible(instance)) + { + let layer = account_rows + .iter() + .find(|row| row.kind == ParamsKind::Layer && row.module_id == instance.config.id) + .map(|row| row.params.clone()); + policies.push(entry( + instance, + Some(Self::global_params_in(&rows, instance)), + layer, + )); + } + for row in account_rows + .iter() + .filter(|row| row.kind == ParamsKind::Assignment) + { + if let Some(instance) = self + .instance(&row.module_id) + .filter(|instance| instance.config.scope != Scope::All && visible(instance)) + { + policies.push(entry(instance, Some(row.params.clone()), None)); + } + } + Ok(policies) + } +} + +#[cfg(test)] +mod tests { + use serde_json::json; + + use super::*; + use crate::modules::catalog::HookName; + use crate::modules::store::{Assigned, Change}; + use crate::modules::testing::{StubModule, instance_with_params, pipeline}; + + const ACCOUNT: &str = "0xacc"; + + fn change() -> Change<'static> { + Change { + operator: "0xop", + reason: "test", + at: "2026-10-16T00:00:00Z".into(), + } + } + + #[tokio::test] + async fn only_disclosed_enabled_policies_are_listed_with_what_they_allow() { + let hooks = [HookName::BeforeTransactionApproved]; + let module = || StubModule::allowing() as std::sync::Arc; + let with = |id: &str, disclosure: Disclosure, scope: Scope| { + let mut instance = instance_with_params(id, &hooks, module(), json!({ "cap": id })); + instance.config.disclosure = disclosure; + instance.config.scope = scope; + if disclosure != Disclosure::None { + instance.config.description = Some(format!("{id} rule")); + } + instance + }; + let pipeline = pipeline(vec![ + with("caps", Disclosure::Params, Scope::All), + with("screening", Disclosure::None, Scope::All), + with("summary", Disclosure::Summary, Scope::All), + with("paused", Disclosure::Summary, Scope::All), + with("treasury", Disclosure::Params, Scope::Assigned), + ]); + let store = pipeline.store(); + for id in ["caps", "screening", "summary", "paused", "treasury"] { + store + .seed_instance(id, true, &json!({ "cap": id }), "2026-10-16T00:00:00Z") + .await + .unwrap(); + } + store.set_enabled("paused", false, &change()).await.unwrap(); + store + .set_layer( + ACCOUNT, + "caps", + Some(json!({ "cap": "tighter" })), + &change(), + ) + .await + .unwrap(); + store + .set_layer( + ACCOUNT, + "summary", + Some(json!({ "cap": "secret" })), + &change(), + ) + .await + .unwrap(); + store + .set_assignment( + ACCOUNT, + vec![Assigned { + module_id: "treasury".into(), + params: json!({ "cap": "own" }), + }], + &change(), + ) + .await + .unwrap(); + + let policies = pipeline.disclosed(ACCOUNT).await.unwrap(); + let ids: Vec<_> = policies.iter().map(|p| p.module_id.as_str()).collect(); + assert_eq!( + ids, + ["caps", "summary", "treasury"], + "none and disabled are absent" + ); + assert_eq!(policies[0].params, Some(json!({ "cap": "caps" }))); + assert_eq!(policies[0].account_layer, Some(json!({ "cap": "tighter" }))); + assert_eq!(policies[1].description, "summary rule"); + assert_eq!(policies[1].params, None, "summary shows no params"); + assert_eq!(policies[1].account_layer, None, "nor the account layer"); + assert_eq!(policies[2].params, Some(json!({ "cap": "own" }))); + assert_eq!(policies[2].hooks, ["before_transaction_approved"]); + } +} diff --git a/crates/server/src/modules/grpc_kind.rs b/crates/server/src/modules/grpc_kind.rs new file mode 100644 index 00000000..d9782ed4 --- /dev/null +++ b/crates/server/src/modules/grpc_kind.rs @@ -0,0 +1,133 @@ +//! The `grpc` kind: a module running as its own service. + +use std::sync::Arc; + +use async_trait::async_trait; +use guardian_module_sdk::proto::guardian_module_client::GuardianModuleClient; +use guardian_module_sdk::secrecy::ExposeSecret; +use guardian_module_sdk::{ + Decision, DescribeRequest, HookRequest, Module, ModuleError, ModuleFactory, ModuleInfo, + ModuleInstanceConfig, ParamsVerdict, ValidateParamsRequest, +}; +use tonic::metadata::MetadataValue; +use tonic::transport::{Certificate, Channel, ClientTlsConfig, Endpoint, Identity}; + +use super::catalog::Transport; + +/// Server authentication against the instance's CA, or the system roots without one; the +/// client identity, when set, adds mutual TLS. +fn tls_config(tls: Option<&guardian_module_sdk::ModuleTls>) -> ClientTlsConfig { + let config = ClientTlsConfig::new(); + let Some(tls) = tls else { + return config.with_native_roots(); + }; + let config = match &tls.ca_pem { + Some(ca) => config.ca_certificate(Certificate::from_pem(ca)), + None => config.with_native_roots(), + }; + match &tls.client_identity { + Some(identity) => config.identity(Identity::from_pem( + &identity.cert_pem, + identity.key_pem.expose_secret(), + )), + None => config, + } +} + +pub struct GrpcFactory; + +impl ModuleFactory for GrpcFactory { + fn create(&self, instance: &ModuleInstanceConfig) -> Result, ModuleError> { + let endpoint = instance + .endpoint + .as_deref() + .ok_or_else(|| ModuleError::InvalidRequest("grpc module needs an endpoint".into()))?; + let invalid = |e: String| ModuleError::InvalidRequest(e); + let transport = Transport::of(endpoint, instance.tls.is_some()).map_err(invalid)?; + let endpoint = match transport { + Transport::Tls => { + let uri = endpoint.replacen(Transport::TLS_SCHEME, "https://", 1); + Endpoint::from_shared(uri) + .map_err(|e| invalid(format!("invalid endpoint: {e}")))? + .tls_config(tls_config(instance.tls.as_ref())) + .map_err(|e| invalid(format!("invalid tls settings: {e}")))? + } + Transport::PlaintextLoopback => { + let uri = endpoint.replacen(Transport::PLAINTEXT_SCHEME, "http://", 1); + Endpoint::from_shared(uri).map_err(|e| invalid(format!("invalid endpoint: {e}")))? + } + }; + let channel = endpoint.connect_timeout(instance.timeout).connect_lazy(); + let authorization = instance + .auth_token + .as_ref() + .map(|token| MetadataValue::try_from(format!("Bearer {}", token.expose_secret()))) + .transpose() + .map_err(|_| ModuleError::InvalidRequest("token is not a valid header value".into()))?; + Ok(Arc::new(GrpcModule { + client: GuardianModuleClient::new(channel), + instance_id: instance.id.clone(), + authorization, + })) + } +} + +struct GrpcModule { + client: GuardianModuleClient, + instance_id: String, + authorization: Option>, +} + +impl GrpcModule { + fn request(&self, message: T) -> tonic::Request { + let mut request = tonic::Request::new(message); + if let Some(value) = &self.authorization { + request + .metadata_mut() + .insert("authorization", value.clone()); + } + request + } +} + +fn module_error(status: tonic::Status) -> ModuleError { + match status.code() { + tonic::Code::Unavailable | tonic::Code::DeadlineExceeded | tonic::Code::Unknown => { + ModuleError::Unavailable(status.message().to_string()) + } + _ => ModuleError::Internal(format!("{}: {}", status.code(), status.message())), + } +} + +#[async_trait] +impl Module for GrpcModule { + async fn describe(&self, guardian: &DescribeRequest) -> Result { + self.client + .clone() + .describe(self.request(guardian.clone())) + .await + .map(tonic::Response::into_inner) + .map_err(module_error) + } + + async fn validate_params(&self, params: &[u8]) -> Result { + self.client + .clone() + .validate_params(self.request(ValidateParamsRequest { + params: params.to_vec(), + instance_id: self.instance_id.clone(), + })) + .await + .map(tonic::Response::into_inner) + .map_err(module_error) + } + + async fn evaluate(&self, request: &HookRequest) -> Result { + self.client + .clone() + .evaluate(self.request(request.clone())) + .await + .map(tonic::Response::into_inner) + .map_err(module_error) + } +} diff --git a/crates/server/src/modules/mod.rs b/crates/server/src/modules/mod.rs new file mode 100644 index 00000000..939c869e --- /dev/null +++ b/crates/server/src/modules/mod.rs @@ -0,0 +1,78 @@ +//! Policy modules: a hook pipeline the Guardian consults before approving. + +pub mod admin; +pub mod catalog; +pub mod check_limit; +pub mod disclosure; +pub mod grpc_kind; +pub mod pipeline; +#[cfg(feature = "postgres")] +pub mod postgres_store; +pub mod registry; +pub mod request; +pub mod store; +#[cfg(test)] +pub mod testing; + +use std::path::PathBuf; +use std::sync::Arc; + +pub use catalog::{CONFIG_ENV, Catalog, HookName}; +pub use pipeline::ModulePipeline; +pub use registry::Registry; + +/// Directory of the filesystem module tables; defaults to `/modules`. +pub const STATE_ENV: &str = "GUARDIAN_MODULES_STATE"; + +fn filesystem_store(catalog_path: &std::path::Path) -> Result { + let dir = std::env::var_os(STATE_ENV) + .filter(|value| !value.is_empty()) + .map(PathBuf::from) + .or_else(|| { + std::env::var_os("GUARDIAN_METADATA_PATH") + .filter(|value| !value.is_empty()) + .map(|path| PathBuf::from(path).join("modules")) + }) + .unwrap_or_else(|| catalog_path.with_extension("tables")); + store::FsModuleStore::open(dir) +} + +/// The pipeline configured by `GUARDIAN_MODULES_CONFIG`, or `None` when it is unset. `store` is +/// the backend's module tables; without one (filesystem backend) they are files. +pub async fn from_env( + now: String, + store: Option>, + registry: &Registry, +) -> Result>, String> { + let Some(path) = std::env::var_os(CONFIG_ENV).filter(|value| !value.is_empty()) else { + return Ok(None); + }; + let catalog_path = PathBuf::from(path); + let catalog = Catalog::load(&catalog_path)?; + if crate::config::stage::Stage::from_env() + .map_err(|e| e.to_string())? + .is_prod() + { + catalog.check_production()?; + } + let store = match store { + Some(store) => store, + None => Arc::new(filesystem_store(&catalog_path)?), + }; + let pipeline = ModulePipeline::new(catalog, registry, store, now).await?; + let version = pipeline.store().version().await?; + let builds = pipeline + .instances() + .iter() + .map(|instance| { + format!( + "{}={}", + instance.config.id, + instance.build.as_deref().unwrap_or("unavailable") + ) + }) + .collect::>() + .join(", "); + tracing::info!(catalog_hash = %pipeline.catalog_hash, params_version = version, %builds, "Policy modules loaded"); + Ok(Some(Arc::new(pipeline))) +} diff --git a/crates/server/src/modules/pipeline.rs b/crates/server/src/modules/pipeline.rs new file mode 100644 index 00000000..6d1179a7 --- /dev/null +++ b/crates/server/src/modules/pipeline.rs @@ -0,0 +1,1264 @@ +//! Ordered evaluation of an account's modules at one hook. + +use guardian_module_sdk::{Decision, Effect, HookRequest, is_valid_reason_code}; + +use super::catalog::{Catalog, ClientReason, HookName, OnError, Scope}; +use std::collections::HashMap; +use std::sync::{Arc, RwLock}; + +use super::registry::{CallError, Instance, Registry, isolated}; +use super::request::ViewCache; +use super::store::{AccountParamsRow, ModuleStore, ParamsKind}; +use crate::delta_summary::{FailedOpen, ModuleApproval}; +use crate::error::GuardianError; + +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum Layer { + Global, + Account, +} + +impl Layer { + pub fn as_str(self) -> &'static str { + match self { + Layer::Global => "global", + Layer::Account => "account", + } + } +} + +pub struct ModulePipeline { + instances: Vec, + store: Arc, + cache: RwLock, + views: Arc, + pub catalog_hash: String, +} + +/// The `module_instances` rows as of one params version. +const SNAPSHOT_ATTEMPTS: usize = 3; + +pub(super) type Rows = Arc>; + +#[derive(Default)] +struct Cache { + version: Option, + rows: Rows, +} + +/// The modules one request runs through, resolved once with a single store read. +pub struct Plan<'a> { + hook: HookName, + account_id: String, + modules: Vec<(&'a Instance, serde_json::Value, Layer)>, + catalog_hash: String, + params_version: u64, + views: Arc, +} + +enum Failure { + Error(String), + Timeout, + InvalidDecision(String), + /// An `effect` value this Guardian does not know: never read as an allow. + UnknownEffect(i32), + RequestUnavailable(String), +} + +impl Failure { + fn kind(&self) -> &'static str { + match self { + Failure::Error(_) => "error", + Failure::Timeout => "timeout", + Failure::InvalidDecision(_) | Failure::UnknownEffect(_) => "invalid_decision", + Failure::RequestUnavailable(_) => "request_unavailable", + } + } +} + +impl std::fmt::Display for Failure { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + match self { + Failure::Error(message) => write!(f, "{message}"), + Failure::Timeout => write!(f, "timed out"), + Failure::InvalidDecision(code) => write!(f, "invalid reason code {code:?}"), + Failure::UnknownEffect(value) => write!(f, "unknown decision effect {value}"), + Failure::RequestUnavailable(message) => write!(f, "request unavailable: {message}"), + } + } +} + +impl ModulePipeline { + pub async fn new( + mut catalog: Catalog, + registry: &Registry, + store: Arc, + now: String, + ) -> Result { + let stored: HashMap = store + .instances() + .await? + .into_iter() + .map(|row| (row.module_id, (row.global_params, row.enabled))) + .collect(); + let mut effective = HashMap::new(); + for config in &mut catalog.instances { + let Some((params, enabled)) = stored.get(&config.id) else { + continue; + }; + if *enabled != config.catalog_enabled { + tracing::warn!(module = %config.id, enabled, "Catalog `enabled` differs from the stored runtime flag; the stored flag applies"); + } + config.enabled = *enabled; + if !config.file_managed_params && *params != config.params { + tracing::warn!(module = %config.id, "Catalog params differ from the operator-managed global params; the stored params apply"); + effective.insert(config.id.clone(), params.clone()); + } + } + let super::registry::Instantiated { + instances, + normalized, + } = registry.instantiate(&catalog, &effective).await?; + for config in catalog + .instances + .iter() + .filter(|config| !stored.contains_key(&config.id)) + { + let seed = if config.file_managed_params { + serde_json::json!({}) + } else { + normalized.get(&config.id).unwrap_or(&config.params).clone() + }; + store + .seed_instance(&config.id, config.enabled, &seed, &now) + .await?; + } + for instance in instances + .iter() + .filter(|instance| !instance.config.file_managed_params) + { + let (Some(params), Some((read, _))) = ( + normalized.get(&instance.config.id), + stored.get(&instance.config.id), + ) else { + continue; + }; + let operator = format!( + "module:{}", + instance.build.as_deref().unwrap_or(&instance.config.kind) + ); + let migrated = store + .set_global_if( + &instance.config.id, + read, + params.clone(), + &super::store::Change { + operator: &operator, + reason: "params migrated by the module", + at: now.clone(), + }, + ) + .await?; + if migrated { + tracing::info!(module = %instance.config.id, %operator, "Module normalized its stored global params; stored the migrated form"); + } else { + tracing::warn!(module = %instance.config.id, "Global params changed while the module migrated them; kept the newer value, migration retries next start"); + } + } + Ok(Self { + instances, + store, + cache: RwLock::new(Cache::default()), + views: Arc::default(), + catalog_hash: catalog.hash, + }) + } + + #[cfg(test)] + pub fn from_instances(instances: Vec) -> Self { + Self::from_instances_with_store( + instances, + Arc::new(super::store::FsModuleStore::in_memory()), + ) + } + + #[cfg(test)] + pub fn from_instances_with_store( + instances: Vec, + store: Arc, + ) -> Self { + Self { + instances, + store, + cache: RwLock::new(Cache::default()), + views: Arc::default(), + catalog_hash: String::new(), + } + } + + pub fn instances(&self) -> &[Instance] { + &self.instances + } + + pub fn instance(&self, module_id: &str) -> Option<&Instance> { + self.instances + .iter() + .find(|instance| instance.config.id == module_id) + } + + pub fn store(&self) -> &dyn ModuleStore { + self.store.as_ref() + } + + fn store_error(error: String) -> GuardianError { + GuardianError::StorageError(format!("module state unavailable: {error}")) + } + + /// The stored `(global params, enabled)` rows, cached per replica and refreshed when the + /// params version moves. One version read per call. + pub(super) async fn rows(&self) -> Result { + Ok(self.versioned_rows().await?.1) + } + + async fn versioned_rows(&self) -> Result<(u64, Rows), GuardianError> { + let version = self.store.version().await.map_err(Self::store_error)?; + if let Ok(cache) = self.cache.read() + && cache.version == Some(version) + { + return Ok((version, cache.rows.clone())); + } + let rows: Rows = Arc::new( + self.store + .instances() + .await + .map_err(Self::store_error)? + .into_iter() + .map(|row| (row.module_id, (row.global_params, row.enabled))) + .collect(), + ); + if let Ok(mut cache) = self.cache.write() { + *cache = Cache { + version: Some(version), + rows: rows.clone(), + }; + } + Ok((version, rows)) + } + + /// The global rows and one account's rows as of a single params version. Every module write + /// moves the version in the same transaction, so an unchanged version across the reads + /// means no write committed between them; otherwise the reads are retried. Without this a + /// request could combine a new global rule with an old account layer, a combination no + /// operator ever configured. + pub(super) async fn snapshot( + &self, + account_id: &str, + ) -> Result<(u64, Rows, Vec), GuardianError> { + for _ in 0..SNAPSHOT_ATTEMPTS { + let (version, rows) = self.versioned_rows().await?; + let account_rows = self + .store + .account_params(account_id) + .await + .map_err(Self::store_error)?; + if self.store.version().await.map_err(Self::store_error)? == version { + return Ok((version, rows, account_rows)); + } + } + Err(Self::store_error( + "module state kept changing while it was read".into(), + )) + } + + pub(super) fn global_params_in(rows: &Rows, instance: &Instance) -> serde_json::Value { + if instance.config.file_managed_params { + return instance.config.params.clone(); + } + rows.get(&instance.config.id).map_or_else( + || instance.config.params.clone(), + |(params, _)| params.clone(), + ) + } + + pub(super) fn enabled_in(rows: &Rows, instance: &Instance) -> bool { + rows.get(&instance.config.id) + .map_or(instance.config.enabled, |(_, enabled)| *enabled) + } + + /// The instance's global params: the stored ones, or the catalog's when they are + /// file-managed or not seeded yet. + pub async fn global_params( + &self, + instance: &Instance, + ) -> Result { + Ok(Self::global_params_in(&self.rows().await?, instance)) + } + + /// Whether the instance is switched on: the stored runtime flag, or the startup flag for an + /// instance without a row yet. + pub async fn enabled(&self, instance: &Instance) -> Result { + Ok(Self::enabled_in(&self.rows().await?, instance)) + } + + /// The modules that run for this account at this hook, or `None` when there are none, so a + /// caller skips building the request. + pub async fn plan( + &self, + hook: HookName, + account_id: &str, + ) -> Result>, GuardianError> { + let account_id = account_id.to_ascii_lowercase(); + let subscribed = |rows: &Rows, instance: &&Instance| { + instance.config.hooks.contains(&hook) && Self::enabled_in(rows, instance) + }; + let (_, rows) = self.versioned_rows().await?; + if !self + .instances + .iter() + .any(|instance| subscribed(&rows, &instance)) + { + return Ok(None); + } + let (params_version, rows, account_rows) = self.snapshot(&account_id).await?; + let active: Vec<&Instance> = self + .instances + .iter() + .filter(|instance| subscribed(&rows, instance)) + .collect(); + if active.is_empty() { + return Ok(None); + } + let mut modules = Vec::new(); + for instance in active + .iter() + .filter(|instance| instance.config.scope == Scope::All) + { + modules.push(( + *instance, + Self::global_params_in(&rows, instance), + Layer::Global, + )); + if let Some(layer) = account_rows + .iter() + .find(|row| row.kind == ParamsKind::Layer && row.module_id == instance.config.id) + { + modules.push((*instance, layer.params.clone(), Layer::Account)); + } + } + for row in account_rows + .iter() + .filter(|row| row.kind == ParamsKind::Assignment) + { + if let Some(instance) = active.iter().find(|instance| { + instance.config.id == row.module_id && instance.config.scope != Scope::All + }) { + modules.push((*instance, row.params.clone(), Layer::Account)); + } + } + Ok((!modules.is_empty()).then_some(Plan { + hook, + account_id, + modules, + catalog_hash: self.catalog_hash.clone(), + params_version, + views: self.views.clone(), + })) + } + + /// The plan for a dry-run check: instances with `dry_run = false` are skipped, and + /// `complete` is false when any was. + pub async fn plan_dry_run( + &self, + hook: HookName, + account_id: &str, + ) -> Result<(Option>, bool), GuardianError> { + let Some(mut plan) = self.plan(hook, account_id).await? else { + return Ok((None, true)); + }; + let planned = plan.modules.len(); + plan.modules + .retain(|(instance, _, _)| instance.config.dry_run); + let complete = plan.modules.len() == planned; + Ok(((!plan.modules.is_empty()).then_some(plan), complete)) + } + + pub async fn applies(&self, hook: HookName, account_id: &str) -> Result { + Ok(self.plan(hook, account_id).await?.is_some()) + } + + /// Plans and runs the hook in one step. + pub async fn run( + &self, + hook: HookName, + account_id: &str, + build: impl FnOnce() -> Result, + ) -> Result<(), GuardianError> { + match self.plan(hook, account_id).await? { + Some(plan) => plan.run(build).await.map(|_| ()), + None => Ok(()), + } + } +} + +impl Plan<'_> { + /// The replica's account view cache, for building this plan's request. + pub fn views(&self) -> Arc { + self.views.clone() + } + + /// Runs the planned modules in order and returns the configuration they ran with. If + /// `build` fails, every module counts as failed and its `on_error` applies. + pub async fn run( + self, + build: impl FnOnce() -> Result, + ) -> Result { + let Plan { + hook, + account_id, + modules, + catalog_hash, + params_version, + views: _, + } = self; + let account_id = account_id.as_str(); + let mut approval = ModuleApproval { + catalog_hash, + params_version, + failed_open: Vec::new(), + }; + let base = match build() { + Ok(base) => base, + Err(error) => { + for (instance, _, layer) in &modules { + let failure = Failure::RequestUnavailable(error.clone()); + approval + .failed_open + .extend(fail(instance, *layer, account_id, &failure)?); + } + return Ok(approval); + } + }; + + for (instance, params, layer) in modules { + let mut request = base.clone(); + request.hook = hook.proto() as i32; + request.instance_id = instance.config.id.clone(); + request.params = serde_json::to_vec(¶ms).unwrap_or_default(); + + let module = instance.module.clone(); + let outcome = isolated(instance.config.timeout, async move { + module.evaluate(&request).await + }) + .await; + let failure = match outcome.map(|decision| (effect(&decision), decision)) { + Ok((Some(Effect::Allow), _)) => continue, + Ok((Some(Effect::Deny), decision)) + if is_valid_reason_code(&decision.reason_code) => + { + tracing::info!( + module = %instance.config.id, + account_id, + ?hook, + reason_code = %decision.reason_code, + layer = layer.as_str(), + message = %decision.message, + client_reason = ?instance.config.client_reason, + "Policy module denied the request" + ); + return Err(match instance.config.client_reason { + ClientReason::Generic => GuardianError::ModuleDeniedGeneric, + ClientReason::Full => GuardianError::ModuleDenied { + module: instance.config.id.clone(), + reason_code: decision.reason_code, + layer: layer.as_str().to_string(), + client_message: client_message(&decision.client_message), + }, + }); + } + Ok((Some(_), decision)) => Failure::InvalidDecision(decision.reason_code), + Ok((None, decision)) => Failure::UnknownEffect(decision.effect), + Err(CallError::Module(error)) => Failure::Error(error.to_string()), + Err(CallError::Panicked(message)) => { + Failure::Error(format!("module panicked: {message}")) + } + Err(CallError::Timeout) => Failure::Timeout, + }; + approval + .failed_open + .extend(fail(instance, layer, account_id, &failure)?); + } + Ok(approval) + } +} + +const CLIENT_MESSAGE_MAX_CHARS: usize = 256; + +/// A module's text for the requester as plain text: control characters dropped, whitespace +/// collapsed, at most 256 characters, and none when empty. +fn client_message(text: &str) -> Option { + let plain: String = text + .chars() + .map(|c| if c.is_control() { ' ' } else { c }) + .collect::() + .split_whitespace() + .collect::>() + .join(" "); + let capped: String = plain.chars().take(CLIENT_MESSAGE_MAX_CHARS).collect(); + (!capped.is_empty()).then_some(capped) +} + +/// What a decision asks for. A module that predates `effect` leaves it unspecified and the +/// legacy `allow` decides; a value this Guardian does not know is `None`. +fn effect(decision: &Decision) -> Option { + match Effect::try_from(decision.effect) { + Ok(Effect::Unspecified) if decision.allow => Some(Effect::Allow), + Ok(Effect::Unspecified) => Some(Effect::Deny), + Ok(effect) => Some(effect), + Err(_) => None, + } +} + +/// Applies the instance's `on_error`: a refusal for `deny`, the failed-open record for `allow`. +fn fail( + instance: &Instance, + layer: Layer, + account_id: &str, + failure: &Failure, +) -> Result, GuardianError> { + match instance.config.on_error { + OnError::Deny => { + tracing::warn!(module = %instance.config.id, account_id, %failure, "Policy module failed; refusing"); + Err(GuardianError::ModuleUnavailable { + module: instance.config.id.clone(), + }) + } + OnError::Allow => { + tracing::warn!(module = %instance.config.id, account_id, %failure, "Policy module failed; continuing (fail-open)"); + Ok(Some(FailedOpen { + module_id: instance.config.id.clone(), + layer: layer.as_str().to_string(), + failure: failure.kind().to_string(), + })) + } + } +} + +#[cfg(test)] +mod tests { + use std::time::Duration; + + use super::*; + use crate::modules::testing::{Behaviour, StubModule, instance, pipeline}; + use guardian_module_sdk::Decision; + + const HOOK: HookName = HookName::BeforeTransactionApproved; + + async fn run(pipeline: &ModulePipeline) -> Result<(), GuardianError> { + pipeline + .run(HOOK, "0xacc", || Ok(HookRequest::default())) + .await + } + + fn caps_catalog(params: &str) -> Catalog { + Catalog::parse( + &format!( + r#" +[[module]] +id = "caps" +kind = "basic-policy" +scope = "all" +hooks = ["before_transaction_approved"] +timeout_ms = 50 +params = {params} +"# + ), + None, + ) + .unwrap() + } + + #[tokio::test] + async fn invalid_catalog_params_stop_startup_without_seeding_them() { + let store: Arc = Arc::new(super::super::store::FsModuleStore::in_memory()); + let registry = Registry::first_party(); + let now = "2026-10-15T00:00:00Z".to_string(); + let started = ModulePipeline::new( + caps_catalog(r#"{ max_amount_per_txx = {} }"#), + ®istry, + store.clone(), + now.clone(), + ) + .await; + assert!(started.is_err()); + assert!(store.instances().await.unwrap().is_empty()); + + let fixed = caps_catalog(r#"{ max_amount_per_tx = { "0xaa" = "5" } }"#); + let started = ModulePipeline::new(fixed, ®istry, store.clone(), now) + .await + .expect("the corrected catalog starts"); + assert!( + started.instances()[0] + .build + .as_deref() + .is_some_and(|build| build.starts_with("basic-policy")) + ); + assert_eq!(store.instances().await.unwrap().len(), 1); + } + + #[tokio::test] + async fn stored_params_not_the_stale_catalog_seed_are_checked_at_startup() { + let store: Arc = Arc::new(super::super::store::FsModuleStore::in_memory()); + let registry = Registry::first_party(); + let now = "2026-10-15T00:00:00Z".to_string(); + store + .seed_instance( + "caps", + true, + &serde_json::json!({ "max_amount_per_tx": {} }), + &now, + ) + .await + .unwrap(); + ModulePipeline::new( + caps_catalog(r#"{ max_amount_per_txx = {} }"#), + ®istry, + store.clone(), + now.clone(), + ) + .await + .expect("the stored params apply, so the stale seed is not checked"); + + store + .set_global( + "caps", + serde_json::json!({ "unknown": true }), + &super::super::store::Change { + operator: "0xop", + reason: "test", + at: now.clone(), + }, + ) + .await + .unwrap(); + let valid_seed = caps_catalog(r#"{ max_amount_per_tx = {} }"#); + assert!( + ModulePipeline::new(valid_seed, ®istry, store, now) + .await + .is_err() + ); + } + + #[tokio::test] + async fn fail_closed_timeout_refuses_as_unavailable() { + let pipeline = pipeline(vec![instance( + "slow", + &[HOOK], + OnError::Deny, + StubModule::new(Behaviour::Hang), + )]); + assert!(matches!( + run(&pipeline).await, + Err(GuardianError::ModuleUnavailable { module }) if module == "slow" + )); + } + + #[tokio::test] + async fn fail_open_failure_continues_to_the_next_module() { + let denier = StubModule::denying("limit_exceeded"); + let pipeline = pipeline(vec![ + instance( + "down", + &[HOOK], + OnError::Allow, + StubModule::new(Behaviour::Fail), + ), + instance("caps", &[HOOK], OnError::Deny, denier.clone()), + ]); + assert!(matches!( + run(&pipeline).await, + Err(GuardianError::ModuleDenied { module, reason_code, .. }) + if module == "caps" && reason_code == "limit_exceeded" + )); + assert_eq!(denier.calls(), 1); + } + + #[tokio::test] + async fn fail_open_timeout_alone_allows() { + let pipeline = pipeline(vec![instance( + "slow", + &[HOOK], + OnError::Allow, + StubModule::new(Behaviour::Hang), + )]); + assert!(run(&pipeline).await.is_ok()); + } + + #[tokio::test] + async fn the_trace_keeps_only_what_failed_open() { + let pipeline = pipeline(vec![ + instance("caps", &[HOOK], OnError::Deny, StubModule::allowing()), + instance( + "risk", + &[HOOK], + OnError::Allow, + StubModule::new(Behaviour::Hang), + ), + ]); + let plan = || async { pipeline.plan(HOOK, "0xacc").await.unwrap().unwrap() }; + let approval = plan() + .await + .run(|| Ok(HookRequest::default())) + .await + .unwrap(); + assert_eq!( + approval.failed_open, + vec![FailedOpen { + module_id: "risk".into(), + layer: "global".into(), + failure: "timeout".into(), + }] + ); + + let unbuilt = plan().await.run(|| Err("no state".to_string())).await; + assert!(unbuilt.is_err(), "caps fails closed without a request"); + } + + #[tokio::test] + async fn a_panicking_module_is_a_module_failure() { + let pipeline = pipeline(vec![instance( + "buggy", + &[HOOK], + OnError::Deny, + StubModule::new(Behaviour::Panic), + )]); + assert!(matches!( + run(&pipeline).await, + Err(GuardianError::ModuleUnavailable { module }) if module == "buggy" + )); + + let pipeline = pipeline_with(OnError::Allow, Behaviour::Panic); + let approval = pipeline + .plan(HOOK, "0xacc") + .await + .unwrap() + .unwrap() + .run(|| Ok(HookRequest::default())) + .await + .unwrap(); + assert_eq!(approval.failed_open[0].failure, "error"); + } + + #[tokio::test(flavor = "multi_thread", worker_threads = 2)] + async fn the_timeout_holds_when_a_module_blocks() { + let pipeline = pipeline_with(OnError::Deny, Behaviour::Block(Duration::from_secs(2))); + let started = std::time::Instant::now(); + assert!(matches!( + run(&pipeline).await, + Err(GuardianError::ModuleUnavailable { .. }) + )); + assert!( + started.elapsed() < Duration::from_secs(1), + "answered at the timeout, not when the module returned" + ); + } + + fn pipeline_with(on_error: OnError, behaviour: Behaviour) -> Arc { + pipeline(vec![instance( + "stub", + &[HOOK], + on_error, + StubModule::new(behaviour), + )]) + } + + fn decision(allow: bool, reason_code: &str, effect: i32) -> Behaviour { + Behaviour::Decide(Decision { + allow, + reason_code: reason_code.into(), + effect, + ..Default::default() + }) + } + + #[tokio::test] + async fn the_effect_decides_and_an_unknown_one_is_a_failure() { + let denied = |behaviour| async { + matches!( + run(&pipeline_with(OnError::Deny, behaviour)).await, + Err(GuardianError::ModuleDenied { .. }) + ) + }; + assert!( + denied(decision(false, "legacy_deny", Effect::Unspecified as i32)).await, + "a module without effect: allow = false still denies" + ); + assert!( + denied(decision(true, "explicit_deny", Effect::Deny as i32)).await, + "effect wins over allow" + ); + assert!( + run(&pipeline_with( + OnError::Deny, + decision(false, "", Effect::Allow as i32) + )) + .await + .is_ok() + ); + assert!( + matches!( + run(&pipeline_with(OnError::Deny, decision(true, "", 99))).await, + Err(GuardianError::ModuleUnavailable { .. }) + ), + "an effect this Guardian does not know is never read as an allow" + ); + } + + #[tokio::test] + async fn startup_stores_params_the_module_migrated() { + use crate::modules::testing::{FixedFactory, ProtocolStub}; + let catalog = || { + Catalog::parse( + r#" +[[module]] +id = "migrating" +kind = "protocol-stub" +scope = "all" +hooks = ["before_transaction_approved"] +timeout_ms = 50 +params = { old_name = 5 } +"#, + None, + ) + .unwrap() + }; + let mut stub = ProtocolStub::new(); + stub.normalized = Some(serde_json::json!({ "new_name": 5 })); + let mut registry = Registry::first_party(); + registry + .register("protocol-stub", Arc::new(FixedFactory(Arc::new(stub)))) + .unwrap(); + let store: Arc = Arc::new(super::super::store::FsModuleStore::in_memory()); + let now = "2026-10-16T00:00:00Z".to_string(); + + ModulePipeline::new(catalog(), ®istry, store.clone(), now.clone()) + .await + .unwrap(); + let seeded = store.instances().await.unwrap(); + assert_eq!( + seeded[0].global_params, + serde_json::json!({ "new_name": 5 }), + "a new instance is seeded in the migrated shape" + ); + + store + .set_global( + "migrating", + serde_json::json!({ "old_name": 7 }), + &super::super::store::Change { + operator: "0xop", + reason: "old shape", + at: now.clone(), + }, + ) + .await + .unwrap(); + ModulePipeline::new(catalog(), ®istry, store.clone(), now) + .await + .unwrap(); + assert_eq!( + store.instances().await.unwrap()[0].global_params, + serde_json::json!({ "new_name": 5 }) + ); + let last = store.history("migrating").await.unwrap().pop().unwrap(); + assert_eq!(last.operator, "module:protocol-stub 1"); + assert_eq!(last.reason, "params migrated by the module"); + assert_eq!(last.previous, serde_json::json!({ "old_name": 7 })); + } + + #[tokio::test] + async fn a_generic_instance_denies_without_details() { + let deny = Behaviour::Decide( + Decision::deny("recipient_sanctioned", "on list X") + .with_client_message("contact support"), + ); + let mut instance = instance("screening", &[HOOK], OnError::Deny, StubModule::new(deny)); + instance.config.client_reason = ClientReason::Generic; + assert!(matches!( + run(&pipeline(vec![instance])).await, + Err(GuardianError::ModuleDeniedGeneric) + )); + } + + #[tokio::test] + async fn a_full_denial_forwards_a_cleaned_client_message() { + let text = format!( + "Limit reached.\n\tAsk your\u{7} treasury admin. {}", + "x".repeat(400) + ); + let deny = Behaviour::Decide( + Decision::deny("amount_cap_exceeded", "internal").with_client_message(text), + ); + match run(&pipeline_with(OnError::Deny, deny)).await { + Err(GuardianError::ModuleDenied { + client_message: Some(message), + .. + }) => { + assert!(message.starts_with("Limit reached. Ask your treasury admin.")); + assert_eq!(message.chars().count(), 256); + assert!(!message.chars().any(char::is_control)); + } + other => panic!("unexpected {other:?}"), + } + assert_eq!(client_message(" \n "), None); + } + + #[tokio::test] + async fn a_request_never_mixes_a_global_rule_and_an_account_layer_from_different_versions() { + use super::super::store::Change; + use crate::modules::testing::{RacingStore, RacingWrite}; + let store = Arc::new(RacingStore::new()); + let change = Change { + operator: "0xop", + reason: "setup", + at: "2026-10-16T00:00:00Z".into(), + }; + store + .inner + .seed_instance( + "caps", + true, + &serde_json::json!({ "cap": 1000 }), + "2026-10-16T00:00:00Z", + ) + .await + .unwrap(); + store + .inner + .set_layer( + "0xacc", + "caps", + Some(serde_json::json!({ "cap": 100 })), + &change, + ) + .await + .unwrap(); + *store.before_account_params.lock().unwrap() = vec![ + RacingWrite::Global("caps", serde_json::json!({ "cap": 100 })), + RacingWrite::Layer("0xacc", "caps", None), + ]; + let pipeline = ModulePipeline::from_instances_with_store( + vec![instance( + "caps", + &[HOOK], + OnError::Deny, + StubModule::allowing(), + )], + store, + ); + + let plan = pipeline.plan(HOOK, "0xacc").await.unwrap().unwrap(); + let params: Vec<_> = plan + .modules + .iter() + .map(|(_, params, _)| params.clone()) + .collect(); + assert_eq!( + params, + vec![serde_json::json!({ "cap": 100 })], + "the version moved during the read, so the plan was rebuilt from one version" + ); + } + + /// An operator lowers the stored params while the module is migrating them at startup; + /// the migration must not replace the operator's newer value with its stale result. + #[tokio::test] + async fn a_startup_migration_never_overwrites_a_newer_operator_write() { + use crate::modules::testing::{FixedFactory, ProtocolStub, RacingStore, RacingWrite}; + let catalog = Catalog::parse( + r#" +[[module]] +id = "migrating" +kind = "protocol-stub" +scope = "all" +hooks = ["before_transaction_approved"] +timeout_ms = 50 +params = { old_name = 1000 } +"#, + None, + ) + .unwrap(); + let mut stub = ProtocolStub::new(); + stub.normalized = Some(serde_json::json!({ "new_name": 1000 })); + let mut registry = Registry::first_party(); + registry + .register("protocol-stub", Arc::new(FixedFactory(Arc::new(stub)))) + .unwrap(); + let store = Arc::new(RacingStore::new()); + store + .inner + .seed_instance( + "migrating", + true, + &serde_json::json!({ "old_name": 1000 }), + "2026-10-16T00:00:00Z", + ) + .await + .unwrap(); + *store.before_set_global_if.lock().unwrap() = vec![RacingWrite::Global( + "migrating", + serde_json::json!({ "new_name": 100 }), + )]; + + ModulePipeline::new( + catalog, + ®istry, + store.clone(), + "2026-10-16T00:00:02Z".into(), + ) + .await + .unwrap(); + assert_eq!( + store.instances().await.unwrap()[0].global_params, + serde_json::json!({ "new_name": 100 }), + "the operator's cap of 100 stays" + ); + let last = store.history("migrating").await.unwrap().pop().unwrap(); + assert_eq!( + last.operator, "0xracing-operator", + "no migration entry after it" + ); + } + + #[tokio::test] + async fn a_deny_stops_evaluation() { + let later = StubModule::allowing(); + let pipeline = pipeline(vec![ + instance("first", &[HOOK], OnError::Deny, StubModule::denying("no")), + instance("second", &[HOOK], OnError::Deny, later.clone()), + ]); + assert!(run(&pipeline).await.is_err()); + assert_eq!(later.calls(), 0); + } + + #[tokio::test] + async fn malformed_reason_code_is_a_failure() { + let pipeline = pipeline(vec![instance( + "bad", + &[HOOK], + OnError::Deny, + StubModule::new(Behaviour::Decide(Decision::deny("Not Valid!", ""))), + )]); + assert!(matches!( + run(&pipeline).await, + Err(GuardianError::ModuleUnavailable { .. }) + )); + } + + #[tokio::test] + async fn request_build_failure_applies_each_failure_mode() { + let closed = pipeline(vec![instance( + "caps", + &[HOOK], + OnError::Deny, + StubModule::allowing(), + )]); + let result = closed + .run(HOOK, "0xacc", || Err("view failed".into())) + .await; + assert!(matches!( + result, + Err(GuardianError::ModuleUnavailable { .. }) + )); + + let open = pipeline(vec![instance( + "caps", + &[HOOK], + OnError::Allow, + StubModule::allowing(), + )]); + assert!( + open.run(HOOK, "0xacc", || Err("view failed".into())) + .await + .is_ok() + ); + } + + #[tokio::test] + async fn modules_not_subscribed_to_the_hook_are_not_called() { + let other = StubModule::denying("no"); + let pipeline = pipeline(vec![instance( + "registration-only", + &[HookName::BeforeAccountRegistered], + OnError::Deny, + other.clone(), + )]); + assert!(!pipeline.applies(HOOK, "0xacc").await.unwrap()); + assert!(run(&pipeline).await.is_ok()); + assert_eq!(other.calls(), 0); + } + + mod layers { + use super::*; + use crate::modules::store::Change; + use crate::modules::testing::instance_with_params; + use guardian_module_sdk::basic_policy::BasicPolicy; + use guardian_module_sdk::proto::hook_request; + use guardian_module_sdk::{ + MidenTransaction, OutputNote, TransactionProjection, TransactionSubject, + }; + use serde_json::json; + + fn pay(recipient: &str) -> HookRequest { + HookRequest { + subject: Some(hook_request::Subject::Transaction(TransactionSubject { + projection: Some(TransactionProjection::miden(MidenTransaction { + output_notes: vec![OutputNote { + note_id: "0xn".into(), + p2id_target: Some(recipient.into()), + ..Default::default() + }], + ..Default::default() + })), + ..Default::default() + })), + ..Default::default() + } + } + + fn blocklist() -> ModulePipeline { + ModulePipeline::from_instances(vec![instance_with_params( + "blocklist", + &[HOOK], + std::sync::Arc::new(BasicPolicy), + json!({ "recipient_denylist": ["0xaaa"] }), + )]) + } + + fn change() -> Change<'static> { + Change { + operator: "0xop", + reason: "test", + at: "t".into(), + } + } + + async fn layer_of( + pipeline: &ModulePipeline, + account: &str, + recipient: &str, + ) -> Option { + match pipeline.run(HOOK, account, || Ok(pay(recipient))).await { + Ok(()) => None, + Err(GuardianError::ModuleDenied { layer, .. }) => Some(layer), + Err(other) => panic!("unexpected {other:?}"), + } + } + + #[tokio::test] + async fn account_layer_extends_the_global_rule() { + let pipeline = blocklist(); + pipeline + .store() + .set_layer( + "0xacc", + "blocklist", + Some(json!({ "recipient_denylist": ["0xccc"] })), + &change(), + ) + .await + .unwrap(); + + assert_eq!( + layer_of(&pipeline, "0xacc", "0xaaa").await.as_deref(), + Some("global") + ); + assert_eq!( + layer_of(&pipeline, "0xacc", "0xccc").await.as_deref(), + Some("account") + ); + assert_eq!(layer_of(&pipeline, "0xacc", "0xbbb").await, None); + assert_eq!(layer_of(&pipeline, "0xother", "0xccc").await, None); + assert_eq!( + layer_of(&pipeline, "0xother", "0xaaa").await.as_deref(), + Some("global") + ); + } + + #[tokio::test] + async fn an_account_layer_cannot_loosen_the_global_rule() { + let pipeline = blocklist(); + pipeline + .store() + .set_layer("0xacc", "blocklist", Some(json!({})), &change()) + .await + .unwrap(); + assert_eq!( + layer_of(&pipeline, "0xacc", "0xaaa").await.as_deref(), + Some("global") + ); + } + + #[tokio::test] + async fn global_params_changed_at_runtime_apply_to_the_next_evaluation() { + let pipeline = blocklist(); + pipeline + .store() + .seed_instance( + "blocklist", + true, + &json!({ "recipient_denylist": ["0xaaa"] }), + "t0", + ) + .await + .unwrap(); + pipeline + .store() + .set_global( + "blocklist", + json!({ "recipient_denylist": ["0xaaa", "0xddd"] }), + &change(), + ) + .await + .unwrap(); + assert_eq!( + layer_of(&pipeline, "0xany", "0xddd").await.as_deref(), + Some("global") + ); + } + + #[tokio::test] + async fn a_module_disabled_at_runtime_is_skipped_until_enabled_again() { + let pipeline = blocklist(); + pipeline + .store() + .seed_instance( + "blocklist", + true, + &json!({ "recipient_denylist": ["0xaaa"] }), + "t0", + ) + .await + .unwrap(); + assert_eq!( + layer_of(&pipeline, "0xacc", "0xaaa").await.as_deref(), + Some("global") + ); + pipeline + .store() + .set_enabled("blocklist", false, &change()) + .await + .unwrap(); + assert_eq!(layer_of(&pipeline, "0xacc", "0xaaa").await, None); + assert!(!pipeline.applies(HOOK, "0xacc").await.unwrap()); + pipeline + .store() + .set_enabled("blocklist", true, &change()) + .await + .unwrap(); + assert_eq!( + layer_of(&pipeline, "0xacc", "0xaaa").await.as_deref(), + Some("global") + ); + } + } +} diff --git a/crates/server/src/modules/postgres_store.rs b/crates/server/src/modules/postgres_store.rs new file mode 100644 index 00000000..3c02531c --- /dev/null +++ b/crates/server/src/modules/postgres_store.rs @@ -0,0 +1,783 @@ +//! The module tables on Postgres. + +use async_trait::async_trait; +use chrono::{DateTime, Utc}; +use diesel::QueryableByName; +use diesel::sql_types::{BigInt, Bool, Integer, Jsonb, Nullable, Text, Timestamptz}; +use diesel_async::pooled_connection::deadpool::Pool; +use diesel_async::scoped_futures::ScopedFutureExt; +use diesel_async::{AsyncConnection, AsyncPgConnection, RunQueryDsl}; + +use super::store::{ + AccountParamsRow, Assigned, Change, HistoryEntry, InstanceRow, ModuleStore, ParamsKind, + assignment_changes, +}; + +pub struct PgModuleStore { + pool: Pool, +} + +impl PgModuleStore { + pub fn new(pool: Pool) -> Self { + Self { pool } + } + + async fn conn( + &self, + ) -> Result, String> { + self.pool + .get() + .await + .map_err(|e| format!("module store pool: {e}")) + } +} + +fn at(change: &Change<'_>) -> Result, String> { + DateTime::parse_from_rfc3339(&change.at) + .map(|at| at.with_timezone(&Utc)) + .map_err(|e| format!("invalid change time: {e}")) +} + +#[derive(QueryableByName)] +struct InstanceSql { + #[diesel(sql_type = Text)] + module_id: String, + #[diesel(sql_type = Bool)] + enabled: bool, + #[diesel(sql_type = Jsonb)] + global_params: serde_json::Value, + #[diesel(sql_type = Jsonb)] + seeded_params: serde_json::Value, + #[diesel(sql_type = Timestamptz)] + updated_at: DateTime, + #[diesel(sql_type = Text)] + updated_by: String, +} + +#[derive(QueryableByName)] +struct AccountParamsSql { + #[diesel(sql_type = Text)] + account_id: String, + #[diesel(sql_type = Text)] + module_id: String, + #[diesel(sql_type = Text)] + kind: String, + #[diesel(sql_type = Integer)] + position: i32, + #[diesel(sql_type = Jsonb)] + params: serde_json::Value, + #[diesel(sql_type = Timestamptz)] + updated_at: DateTime, + #[diesel(sql_type = Text)] + updated_by: String, +} + +#[derive(QueryableByName)] +struct HistorySql { + #[diesel(sql_type = BigInt)] + version: i64, + #[diesel(sql_type = Text)] + module_id: String, + #[diesel(sql_type = Nullable)] + account_id: Option, + #[diesel(sql_type = Jsonb)] + previous_params: serde_json::Value, + #[diesel(sql_type = Jsonb)] + new_params: serde_json::Value, + #[diesel(sql_type = Text)] + operator: String, + #[diesel(sql_type = Text)] + reason: String, + #[diesel(sql_type = Timestamptz)] + changed_at: DateTime, +} + +#[derive(QueryableByName)] +struct VersionSql { + #[diesel(sql_type = BigInt)] + version: i64, +} + +#[derive(QueryableByName)] +struct ParamsSql { + #[diesel(sql_type = Jsonb)] + params: serde_json::Value, +} + +/// Takes the module write lock and returns the version this write commits as. +async fn bump(conn: &mut AsyncPgConnection) -> Result { + let rows: Vec = diesel::sql_query( + "UPDATE module_state_version SET version = version + 1 RETURNING version", + ) + .load(conn) + .await?; + rows.into_iter() + .next() + .map(|row| row.version) + .ok_or(diesel::result::Error::NotFound) +} + +#[allow(clippy::too_many_arguments)] +async fn append( + conn: &mut AsyncPgConnection, + version: i64, + module_id: &str, + account_id: Option<&str>, + previous: &serde_json::Value, + new: &serde_json::Value, + change: &Change<'_>, + changed_at: DateTime, +) -> Result { + diesel::sql_query( + "INSERT INTO module_params_history \ + (version, module_id, account_id, previous_params, new_params, operator, reason, \ + changed_at) VALUES ($1, $2, $3, $4, $5, $6, $7, $8)", + ) + .bind::(version) + .bind::(module_id) + .bind::, _>(account_id) + .bind::(previous) + .bind::(new) + .bind::(change.operator) + .bind::(change.reason) + .bind::(changed_at) + .execute(conn) + .await +} + +#[async_trait] +impl ModuleStore for PgModuleStore { + async fn seed_instance( + &self, + module_id: &str, + enabled: bool, + params: &serde_json::Value, + at_text: &str, + ) -> Result<(), String> { + let changed_at = DateTime::parse_from_rfc3339(at_text) + .map(|at| at.with_timezone(&Utc)) + .map_err(|e| format!("invalid seed time: {e}"))?; + let mut conn = self.conn().await?; + let (module_id, params) = (module_id.to_string(), params.clone()); + let seeded = conn + .transaction::<(), diesel::result::Error, _>(|conn| { + async move { + let version = bump(conn).await?; + let inserted = diesel::sql_query( + "INSERT INTO module_instances \ + (module_id, enabled, global_params, seeded_params, updated_at, updated_by) \ + VALUES ($1, $2, $3, $3, $4, 'catalog') ON CONFLICT (module_id) DO NOTHING", + ) + .bind::(&module_id) + .bind::(enabled) + .bind::(¶ms) + .bind::(changed_at) + .execute(conn) + .await?; + if inserted == 0 { + return Err(diesel::result::Error::RollbackTransaction); + } + let change = Change { + operator: "catalog", + reason: "seeded from the catalog file", + at: String::new(), + }; + append( + conn, + version, + &module_id, + None, + &serde_json::Value::Null, + ¶ms, + &change, + changed_at, + ) + .await?; + Ok(()) + } + .scope_boxed() + }) + .await; + match seeded { + Ok(()) | Err(diesel::result::Error::RollbackTransaction) => Ok(()), + Err(e) => Err(format!("seed module {e}")), + } + } + + async fn instances(&self) -> Result, String> { + let mut conn = self.conn().await?; + let rows: Vec = diesel::sql_query( + "SELECT module_id, enabled, global_params, seeded_params, updated_at, updated_by \ + FROM module_instances ORDER BY module_id", + ) + .load(&mut conn) + .await + .map_err(|e| format!("module instances: {e}"))?; + Ok(rows + .into_iter() + .map(|row| InstanceRow { + module_id: row.module_id, + enabled: row.enabled, + global_params: row.global_params, + seeded_params: row.seeded_params, + updated_at: row.updated_at.to_rfc3339(), + updated_by: row.updated_by, + }) + .collect()) + } + + async fn set_enabled( + &self, + module_id: &str, + enabled: bool, + change: &Change<'_>, + ) -> Result<(), String> { + #[derive(QueryableByName)] + struct EnabledSql { + #[diesel(sql_type = Bool)] + enabled: bool, + } + let changed_at = at(change)?; + let mut conn = self.conn().await?; + let module_id = module_id.to_string(); + conn.transaction::<(), diesel::result::Error, _>(|conn| { + async move { + let version = bump(conn).await?; + let previous: Vec = diesel::sql_query( + "SELECT enabled FROM module_instances WHERE module_id = $1 FOR UPDATE", + ) + .bind::(&module_id) + .load(conn) + .await?; + let previous = previous + .into_iter() + .next() + .ok_or(diesel::result::Error::NotFound)? + .enabled; + diesel::sql_query( + "UPDATE module_instances SET enabled = $2, updated_at = $3, updated_by = $4 \ + WHERE module_id = $1", + ) + .bind::(&module_id) + .bind::(enabled) + .bind::(changed_at) + .bind::(change.operator) + .execute(conn) + .await?; + append( + conn, + version, + &module_id, + None, + &serde_json::json!({ "enabled": previous }), + &serde_json::json!({ "enabled": enabled }), + change, + changed_at, + ) + .await?; + Ok(()) + } + .scope_boxed() + }) + .await + .map_err(|e| format!("set enabled: {e}")) + } + + async fn set_global( + &self, + module_id: &str, + params: serde_json::Value, + change: &Change<'_>, + ) -> Result<(), String> { + let changed_at = at(change)?; + let mut conn = self.conn().await?; + let module_id = module_id.to_string(); + conn.transaction::<(), diesel::result::Error, _>(|conn| { + async move { + let version = bump(conn).await?; + let previous: Vec = diesel::sql_query( + "SELECT global_params AS params FROM module_instances \ + WHERE module_id = $1 FOR UPDATE", + ) + .bind::(&module_id) + .load(conn) + .await?; + let previous = previous + .into_iter() + .next() + .map(|row| row.params) + .unwrap_or_default(); + diesel::sql_query( + "INSERT INTO module_instances \ + (module_id, enabled, global_params, seeded_params, updated_at, updated_by) \ + VALUES ($1, TRUE, $2, $2, $3, $4) ON CONFLICT (module_id) DO UPDATE SET \ + global_params = EXCLUDED.global_params, updated_at = EXCLUDED.updated_at, \ + updated_by = EXCLUDED.updated_by", + ) + .bind::(&module_id) + .bind::(¶ms) + .bind::(changed_at) + .bind::(change.operator) + .execute(conn) + .await?; + append( + conn, version, &module_id, None, &previous, ¶ms, change, changed_at, + ) + .await?; + Ok(()) + } + .scope_boxed() + }) + .await + .map_err(|e| format!("set global params: {e}")) + } + + async fn set_global_if( + &self, + module_id: &str, + expected: &serde_json::Value, + params: serde_json::Value, + change: &Change<'_>, + ) -> Result { + let changed_at = at(change)?; + let mut conn = self.conn().await?; + let (module_id, expected) = (module_id.to_string(), expected.clone()); + let written = conn + .transaction::<(), diesel::result::Error, _>(|conn| { + async move { + let version = bump(conn).await?; + let current: Vec = diesel::sql_query( + "SELECT global_params AS params FROM module_instances \ + WHERE module_id = $1 FOR UPDATE", + ) + .bind::(&module_id) + .load(conn) + .await?; + let Some(previous) = current.into_iter().next().map(|row| row.params) else { + return Err(diesel::result::Error::RollbackTransaction); + }; + if previous != expected { + return Err(diesel::result::Error::RollbackTransaction); + } + diesel::sql_query( + "UPDATE module_instances SET global_params = $2, updated_at = $3, \ + updated_by = $4 WHERE module_id = $1", + ) + .bind::(&module_id) + .bind::(¶ms) + .bind::(changed_at) + .bind::(change.operator) + .execute(conn) + .await?; + append( + conn, version, &module_id, None, &previous, ¶ms, change, changed_at, + ) + .await?; + Ok(()) + } + .scope_boxed() + }) + .await; + match written { + Ok(()) => Ok(true), + Err(diesel::result::Error::RollbackTransaction) => Ok(false), + Err(e) => Err(format!("set global params: {e}")), + } + } + + async fn account_params(&self, account_id: &str) -> Result, String> { + let mut conn = self.conn().await?; + let rows: Vec = diesel::sql_query( + "SELECT account_id, module_id, kind, position, params, updated_at, updated_by \ + FROM module_account_params WHERE account_id = $1 ORDER BY position, module_id", + ) + .bind::(account_id) + .load(&mut conn) + .await + .map_err(|e| format!("account module params: {e}"))?; + rows.into_iter() + .map(|row| { + Ok(AccountParamsRow { + account_id: row.account_id, + module_id: row.module_id, + kind: ParamsKind::parse(&row.kind)?, + position: row.position, + params: row.params, + updated_at: row.updated_at.to_rfc3339(), + updated_by: row.updated_by, + }) + }) + .collect() + } + + async fn set_layer( + &self, + account_id: &str, + module_id: &str, + params: Option, + change: &Change<'_>, + ) -> Result<(), String> { + let changed_at = at(change)?; + let mut conn = self.conn().await?; + let (account_id, module_id) = (account_id.to_string(), module_id.to_string()); + conn.transaction::<(), diesel::result::Error, _>(|conn| { + async move { + let version = bump(conn).await?; + let previous: Vec = diesel::sql_query( + "DELETE FROM module_account_params WHERE account_id = $1 AND module_id = $2 \ + AND kind = 'layer' RETURNING params", + ) + .bind::(&account_id) + .bind::(&module_id) + .load(conn) + .await?; + let previous = previous + .into_iter() + .next() + .map(|row| row.params) + .unwrap_or_default(); + if let Some(params) = ¶ms { + diesel::sql_query( + "INSERT INTO module_account_params \ + (account_id, module_id, kind, position, params, updated_at, updated_by) \ + VALUES ($1, $2, 'layer', 0, $3, $4, $5)", + ) + .bind::(&account_id) + .bind::(&module_id) + .bind::(params) + .bind::(changed_at) + .bind::(change.operator) + .execute(conn) + .await?; + } + let new = params.unwrap_or_default(); + append( + conn, + version, + &module_id, + Some(&account_id), + &previous, + &new, + change, + changed_at, + ) + .await?; + Ok(()) + } + .scope_boxed() + }) + .await + .map_err(|e| format!("set account layer: {e}")) + } + + async fn set_assignment( + &self, + account_id: &str, + modules: Vec, + change: &Change<'_>, + ) -> Result<(), String> { + let changed_at = at(change)?; + let mut conn = self.conn().await?; + let account_id = account_id.to_string(); + conn.transaction::<(), diesel::result::Error, _>(|conn| { + async move { + let version = bump(conn).await?; + let removed: Vec = diesel::sql_query( + "DELETE FROM module_account_params WHERE account_id = $1 \ + AND kind = 'assignment' RETURNING account_id, module_id, kind, position, \ + params, updated_at, updated_by", + ) + .bind::(&account_id) + .load(conn) + .await?; + let previous = removed + .into_iter() + .map(|row| AccountParamsRow { + account_id: row.account_id, + module_id: row.module_id, + kind: ParamsKind::Assignment, + position: row.position, + params: row.params, + updated_at: row.updated_at.to_rfc3339(), + updated_by: row.updated_by, + }) + .collect::>(); + for (position, assigned) in modules.iter().enumerate() { + diesel::sql_query( + "INSERT INTO module_account_params \ + (account_id, module_id, kind, position, params, updated_at, updated_by) \ + VALUES ($1, $2, 'assignment', $3, $4, $5, $6)", + ) + .bind::(&account_id) + .bind::(&assigned.module_id) + .bind::(position as i32) + .bind::(&assigned.params) + .bind::(changed_at) + .bind::(change.operator) + .execute(conn) + .await?; + } + for (module_id, before, after) in assignment_changes(&previous, &modules) { + append( + conn, + version, + &module_id, + Some(&account_id), + &before, + &after, + change, + changed_at, + ) + .await?; + } + Ok(()) + } + .scope_boxed() + }) + .await + .map_err(|e| format!("set assignment: {e}")) + } + + async fn history(&self, module_id: &str) -> Result, String> { + let mut conn = self.conn().await?; + let rows: Vec = diesel::sql_query( + "SELECT version, module_id, account_id, previous_params, new_params, operator, reason, \ + changed_at FROM module_params_history WHERE module_id = $1 ORDER BY id", + ) + .bind::(module_id) + .load(&mut conn) + .await + .map_err(|e| format!("module params history: {e}"))?; + Ok(rows + .into_iter() + .map(|row| HistoryEntry { + version: row.version as u64, + module_id: row.module_id, + account_id: row.account_id, + previous: row.previous_params, + new: row.new_params, + operator: row.operator, + reason: row.reason, + at: row.changed_at.to_rfc3339(), + }) + .collect()) + } + + async fn version(&self) -> Result { + let mut conn = self.conn().await?; + let rows: Vec = diesel::sql_query("SELECT version FROM module_state_version") + .load(&mut conn) + .await + .map_err(|e| format!("module params version: {e}"))?; + Ok(rows.into_iter().next().map_or(0, |row| row.version as u64)) + } +} + +#[cfg(test)] +mod tests { + use serde_json::json; + + use super::*; + use crate::storage::postgres::build_postgres_pool_lazy; + use crate::testing::pg::test_database_url; + + fn change(at: &str) -> Change<'static> { + Change { + operator: "0xop", + reason: "ticket", + at: at.to_string(), + } + } + + #[tokio::test] + #[ignore = "requires Postgres; run ./scripts/test-postgres.sh"] + async fn module_tables_round_trip_and_version_moves_with_history() { + let url = test_database_url().await; + let store = PgModuleStore::new(build_postgres_pool_lazy(&url, 2).expect("pool")); + let other_replica = PgModuleStore::new(build_postgres_pool_lazy(&url, 2).expect("pool")); + let t0 = "2026-10-15T00:00:00Z"; + let module = format!("blocklist-{}", rand::random::()); + let account = format!("0xacc{}", rand::random::()); + let start = store.version().await.unwrap(); + + store + .seed_instance( + &module, + true, + &json!({ "recipient_denylist": ["0xaaa"] }), + t0, + ) + .await + .unwrap(); + store + .seed_instance(&module, true, &json!({ "ignored": true }), t0) + .await + .unwrap(); + store + .set_global( + &module, + json!({ "recipient_denylist": ["0xaaa", "0xddd"] }), + &change(t0), + ) + .await + .unwrap(); + store + .set_layer( + &account, + &module, + Some(json!({ "recipient_denylist": ["0xccc"] })), + &change(t0), + ) + .await + .unwrap(); + store + .set_assignment( + &account, + vec![Assigned { + module_id: format!("{module}-opt"), + params: json!({ "a": 1 }), + }], + &change(t0), + ) + .await + .unwrap(); + + let instance = other_replica + .instances() + .await + .unwrap() + .into_iter() + .find(|row| row.module_id == module) + .unwrap(); + assert_eq!( + instance.global_params, + json!({ "recipient_denylist": ["0xaaa", "0xddd"] }) + ); + assert_eq!( + instance.seeded_params, + json!({ "recipient_denylist": ["0xaaa"] }) + ); + + let rows = other_replica.account_params(&account).await.unwrap(); + assert_eq!(rows.len(), 2); + assert!(rows.iter().any(|row| row.kind == ParamsKind::Layer)); + + let history = other_replica.history(&module).await.unwrap(); + assert_eq!(history.len(), 3); + assert_eq!(history[2].account_id.as_deref(), Some(account.as_str())); + assert_eq!(other_replica.version().await.unwrap(), start + 4); + + store + .set_layer(&account, &module, None, &change(t0)) + .await + .unwrap(); + assert_eq!(store.account_params(&account).await.unwrap().len(), 1); + + store + .set_enabled(&module, false, &change(t0)) + .await + .unwrap(); + let instance = other_replica + .instances() + .await + .unwrap() + .into_iter() + .find(|row| row.module_id == module) + .unwrap(); + assert!(!instance.enabled); + assert!( + store + .set_enabled("no-such-module", false, &change(t0)) + .await + .is_err() + ); + } + + #[tokio::test] + #[ignore = "requires Postgres; run ./scripts/test-postgres.sh"] + async fn concurrent_writes_serialize_and_the_version_follows_commit_order() { + let url = test_database_url().await; + let store = std::sync::Arc::new(PgModuleStore::new( + build_postgres_pool_lazy(&url, 8).expect("pool"), + )); + let account = format!("0xacc{}", rand::random::()); + let t0 = "2026-10-15T00:00:00Z"; + let before = store.version().await.unwrap(); + let writes = (0..8).map(|n| { + let store = store.clone(); + let account = account.clone(); + tokio::spawn(async move { + store + .set_assignment( + &account, + vec![Assigned { + module_id: format!("opt-{n}"), + params: json!({}), + }], + &change(t0), + ) + .await + }) + }); + for write in writes { + write.await.unwrap().unwrap(); + } + let rows = store.account_params(&account).await.unwrap(); + assert_eq!(rows.len(), 1, "one replacement wins, never a union"); + assert!(store.version().await.unwrap() >= before + 8); + } + + #[tokio::test] + #[ignore = "requires Postgres; run ./scripts/test-postgres.sh"] + async fn a_conditional_write_only_replaces_the_value_it_expects() { + let url = test_database_url().await; + let store = PgModuleStore::new(build_postgres_pool_lazy(&url, 2).expect("pool")); + let module = format!("cas-{}", rand::random::()); + let t0 = "2026-10-16T00:00:00Z"; + store + .seed_instance(&module, true, &json!({ "old_name": 1000 }), t0) + .await + .unwrap(); + store + .set_global(&module, json!({ "new_name": 100 }), &change(t0)) + .await + .unwrap(); + let before = store.version().await.unwrap(); + assert!( + !store + .set_global_if( + &module, + &json!({ "old_name": 1000 }), + json!({ "new_name": 1000 }), + &change(t0) + ) + .await + .unwrap(), + "the stale expectation does not write" + ); + assert_eq!( + store.version().await.unwrap(), + before, + "and does not move the version" + ); + assert!( + store + .set_global_if( + &module, + &json!({ "new_name": 100 }), + json!({ "new_name": 50 }), + &change(t0) + ) + .await + .unwrap() + ); + let row = store + .instances() + .await + .unwrap() + .into_iter() + .find(|row| row.module_id == module) + .unwrap(); + assert_eq!(row.global_params, json!({ "new_name": 50 })); + } +} diff --git a/crates/server/src/modules/registry.rs b/crates/server/src/modules/registry.rs new file mode 100644 index 00000000..e47f8788 --- /dev/null +++ b/crates/server/src/modules/registry.rs @@ -0,0 +1,565 @@ +//! Module kinds and instance creation. + +use std::collections::HashMap; +use std::sync::Arc; + +use guardian_module_sdk::basic_policy::{self, BasicPolicy}; +use guardian_module_sdk::{ + DescribeRequest, Module, ModuleError, ModuleFactory, ModuleInfo, ModuleInstanceConfig, + PROTOCOL_VERSION, capability, +}; + +use super::catalog::{Catalog, InstanceConfig}; +use super::grpc_kind::GrpcFactory; + +pub struct Instance { + pub config: InstanceConfig, + pub module: Arc, + /// `name version` from `describe` at startup; `None` when the checks failed. + pub build: Option, +} + +struct BasicPolicyFactory; + +impl ModuleFactory for BasicPolicyFactory { + fn create(&self, _instance: &ModuleInstanceConfig) -> Result, ModuleError> { + Ok(Arc::new(BasicPolicy)) + } +} + +/// The created instances, and the params each module normalized at its startup check (only +/// the instances whose normalized params differ from the ones checked). +pub struct Instantiated { + pub instances: Vec, + pub normalized: HashMap, +} + +pub struct Registry { + factories: HashMap>, +} + +impl Registry { + pub fn first_party() -> Self { + let mut registry = Self { + factories: HashMap::new(), + }; + registry + .factories + .insert(basic_policy::KIND.into(), Arc::new(BasicPolicyFactory)); + registry + .factories + .insert("grpc".into(), Arc::new(GrpcFactory)); + registry + } + + /// Adds a kind the catalog can name. A kind is registered once; the first-party names + /// (`basic-policy`, `grpc`) cannot be replaced. + pub fn register( + &mut self, + kind: impl Into, + factory: Arc, + ) -> Result<(), String> { + let kind = kind.into(); + if self.factories.contains_key(&kind) { + return Err(format!("module kind {kind} is already registered")); + } + self.factories.insert(kind, factory); + Ok(()) + } + + /// Creates every instance and checks it against the params that will apply (`effective`, + /// keyed by instance id; the catalog's when absent). An enabled instance that cannot be + /// created, is unsupported, unreachable or misconfigured stops startup; a disabled one is + /// logged and kept disabled. + pub async fn instantiate( + &self, + catalog: &Catalog, + effective: &HashMap, + ) -> Result { + let mut instances = Vec::with_capacity(catalog.instances.len()); + let mut normalized = HashMap::new(); + for config in &catalog.instances { + let mut config = config.clone(); + let params = effective.get(&config.id).unwrap_or(&config.params); + let ready = match self.create(&config) { + Ok(module) => check(&config, &module, params) + .await + .map(|checked| (module.clone(), checked)) + .map_err(|error| (error, Some(module))), + Err(error) => Err((error, None)), + }; + let (module, build) = match ready { + Ok((module, checked)) => { + if checked.params != *params { + normalized.insert(config.id.clone(), checked.params); + } + ( + module, + Some(format!("{} {}", checked.info.name, checked.info.version)), + ) + } + Err((error, _)) if config.enabled => { + return Err(format!("module {}: {error}", config.id)); + } + Err((error, module)) => { + tracing::warn!(module = %config.id, %error, "Disabled module failed its startup checks"); + config.enabled = false; + (module.unwrap_or_else(|| Arc::new(Unavailable(error))), None) + } + }; + instances.push(Instance { + config, + module, + build, + }); + } + Ok(Instantiated { + instances, + normalized, + }) + } + + fn create(&self, config: &InstanceConfig) -> Result, String> { + let factory = self + .factories + .get(&config.kind) + .ok_or_else(|| format!("unknown kind {}", config.kind))?; + let instance = ModuleInstanceConfig::new( + config.id.clone(), + config.kind.clone(), + config.timeout, + config.params.clone(), + ) + .with_endpoint(config.endpoint.clone()) + .with_auth_token(config.auth_token.clone()) + .with_tls(config.tls.clone()); + std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| factory.create(&instance))) + .map_err(|_| "module factory panicked".to_string())? + .map_err(|e| e.to_string()) + } +} + +/// Stands in for a disabled instance that could not be created; never evaluated while disabled. +struct Unavailable(String); + +#[async_trait::async_trait] +impl Module for Unavailable { + async fn describe( + &self, + _guardian: &guardian_module_sdk::DescribeRequest, + ) -> Result { + Err(ModuleError::Unavailable(self.0.clone())) + } + + async fn validate_params( + &self, + _params: &[u8], + ) -> Result { + Err(ModuleError::Unavailable(self.0.clone())) + } + + async fn evaluate( + &self, + _request: &guardian_module_sdk::HookRequest, + ) -> Result { + Err(ModuleError::Unavailable(self.0.clone())) + } +} + +/// Why a module call produced no result. +#[derive(Debug)] +pub enum CallError { + Timeout, + /// The panic message, when the payload was a string. + Panicked(String), + Module(ModuleError), +} + +impl std::fmt::Display for CallError { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + match self { + CallError::Timeout => write!(f, "timed out"), + CallError::Panicked(message) => write!(f, "panicked: {message}"), + CallError::Module(error) => write!(f, "{error}"), + } + } +} + +/// Runs one module call on its own task, so a panic in the module becomes an error instead of +/// unwinding through the request, and the timeout holds even when an in-process module blocks +/// instead of awaiting. A call that times out is aborted at its next await point. +pub async fn isolated( + timeout: std::time::Duration, + call: impl std::future::Future> + Send + 'static, +) -> Result { + let mut task = tokio::spawn(call); + match tokio::time::timeout(timeout, &mut task).await { + Ok(Ok(result)) => result.map_err(CallError::Module), + Ok(Err(error)) => Err(CallError::Panicked(match error.try_into_panic() { + Ok(payload) => payload + .downcast_ref::<&str>() + .map(|message| message.to_string()) + .or_else(|| payload.downcast_ref::().cloned()) + .unwrap_or_else(|| "non-string panic payload".into()), + Err(error) => error.to_string(), + })), + Err(_) => { + task.abort(); + Err(CallError::Timeout) + } + } +} + +/// The oldest module protocol version this Guardian accepts. It equals `PROTOCOL_VERSION` +/// until a second major version exists; from then on the previous major stays accepted for a +/// deprecation window (RFC 0002 section 3.5). +pub const MIN_PROTOCOL_VERSION: u32 = PROTOCOL_VERSION; + +/// Optional protocol features this Guardian provides. +pub const CAPABILITIES: &[&str] = &[ + capability::DECISION_EFFECT, + capability::PARAMS_NORMALIZATION, +]; + +/// What the Guardian tells a module in `Describe`. +pub fn describe_request() -> DescribeRequest { + DescribeRequest { + guardian_protocol_version: PROTOCOL_VERSION, + guardian_min_protocol_version: MIN_PROTOCOL_VERSION, + guardian_capabilities: CAPABILITIES.iter().map(|c| c.to_string()).collect(), + } +} + +/// A module that passed its startup checks, and the params to store for it (the module's +/// normalized form when it returned one). +pub struct Checked { + pub info: ModuleInfo, + pub params: serde_json::Value, +} + +/// Startup checks: protocol version, required capabilities, hook support and the params that +/// will apply. Also run before enabling. +pub async fn check( + config: &InstanceConfig, + module: &Arc, + params: &serde_json::Value, +) -> Result { + let describing = module.clone(); + let info = isolated(config.timeout, async move { + describing.describe(&describe_request()).await + }) + .await + .map_err(|e| format!("describe {e}"))?; + if !(MIN_PROTOCOL_VERSION..=PROTOCOL_VERSION).contains(&info.protocol_version) { + return Err(format!( + "unsupported protocol version {}; this Guardian accepts {MIN_PROTOCOL_VERSION} to {PROTOCOL_VERSION}", + info.protocol_version + )); + } + if info.protocol_version < PROTOCOL_VERSION { + tracing::warn!(module = %config.id, protocol_version = info.protocol_version, current = PROTOCOL_VERSION, "Module speaks a deprecated protocol version"); + } + if let Some(missing) = info + .required_capabilities + .iter() + .find(|required| !CAPABILITIES.contains(&required.as_str())) + { + return Err(format!( + "module requires capability {missing}, which this Guardian does not provide" + )); + } + for hook in &config.hooks { + if !info.hooks.contains(&(hook.proto() as i32)) { + return Err(format!("module does not support hook {hook:?}")); + } + } + + let params = validate_params(module, params, config.timeout).await?; + Ok(Checked { info, params }) +} + +/// Asks the module whether `params` are valid; used at startup and for every params write. +/// Returns the params to store: the module's normalized form when it sent one, otherwise +/// `params` unchanged. +pub async fn validate_params( + module: &Arc, + params: &serde_json::Value, + timeout: std::time::Duration, +) -> Result { + let bytes = serde_json::to_vec(params).map_err(|e| e.to_string())?; + let validating = module.clone(); + let verdict = isolated( + timeout, + async move { validating.validate_params(&bytes).await }, + ) + .await + .map_err(|e| format!("validate_params {e}"))?; + if !verdict.ok { + return Err(format!("invalid params: {}", verdict.message)); + } + if verdict.normalized_params.is_empty() { + return Ok(params.clone()); + } + match serde_json::from_slice::(&verdict.normalized_params) { + Ok(normalized) if normalized.is_object() => Ok(normalized), + _ => Err("normalized params are not a JSON object".into()), + } +} + +#[cfg(test)] +mod tests { + use super::*; + + fn catalog(entry: &str) -> Catalog { + Catalog::parse(entry, None).unwrap() + } + + const UNKNOWN_KIND: &str = r#" +[[module]] +id = "staged" +kind = "vendor-not-built-in" +scope = "all" +hooks = ["before_transaction_approved"] +timeout_ms = 20 +enabled = ENABLED +"#; + + const BAD_ENDPOINT: &str = r#" +[[module]] +id = "staged" +kind = "grpc" +endpoint = "grpc://not a valid uri" +scope = "all" +hooks = ["before_transaction_approved"] +timeout_ms = 20 +enabled = ENABLED +"#; + + #[tokio::test] + async fn disabled_instances_that_cannot_be_created_stay_disabled() { + for entry in [UNKNOWN_KIND, BAD_ENDPOINT] { + let instances = Registry::first_party() + .instantiate( + &catalog(&entry.replace("ENABLED", "false")), + &HashMap::new(), + ) + .await + .expect("a disabled instance does not block startup") + .instances; + assert_eq!(instances.len(), 1); + assert!(!instances[0].config.enabled); + } + } + + #[tokio::test] + async fn enabled_instances_that_cannot_be_created_stop_startup() { + for entry in [UNKNOWN_KIND, BAD_ENDPOINT] { + let result = Registry::first_party() + .instantiate(&catalog(&entry.replace("ENABLED", "true")), &HashMap::new()) + .await; + assert!(result.is_err()); + } + } + + #[tokio::test] + async fn the_guide_catalogs_load() { + let dir = std::env::temp_dir().join(format!("guide_{:016x}", rand::random::())); + std::fs::create_dir_all(&dir).unwrap(); + for token in ["caps.token", "note-policy.token"] { + std::fs::write(dir.join(token), "t").unwrap(); + } + for text in [ + include_str!("../../../../docs/guides/policy-modules/remote.toml"), + include_str!("../../../../docs/guides/policy-modules/custom.toml"), + include_str!("../../../../docs/guides/policy-modules/custom-in-process.toml"), + ] { + Catalog::parse(text, Some(&dir)).expect("guide catalog parses"); + } + std::fs::remove_dir_all(dir).ok(); + let built_in = include_str!("../../../../docs/guides/policy-modules/built-in.toml"); + let instances = Registry::first_party() + .instantiate(&catalog(built_in), &HashMap::new()) + .await + .expect("the built-in guide catalog passes the startup checks") + .instances; + assert!(instances.iter().all(|instance| instance.config.enabled)); + } + + struct StubFactory; + + impl ModuleFactory for StubFactory { + fn create(&self, _: &ModuleInstanceConfig) -> Result, ModuleError> { + Ok(Arc::new(BasicPolicy)) + } + } + + struct PanickingFactory; + + impl ModuleFactory for PanickingFactory { + fn create(&self, _: &ModuleInstanceConfig) -> Result, ModuleError> { + panic!("factory bug") + } + } + + const CUSTOM: &str = r#" +[[module]] +id = "house-rules" +kind = "house-policy" +scope = "all" +hooks = ["before_transaction_approved"] +timeout_ms = 50 +"#; + + #[tokio::test] + async fn a_registered_kind_loads_from_the_catalog() { + let mut registry = Registry::first_party(); + registry + .register("house-policy", Arc::new(StubFactory)) + .unwrap(); + let instances = registry + .instantiate(&catalog(CUSTOM), &HashMap::new()) + .await + .unwrap() + .instances; + assert_eq!(instances[0].config.kind, "house-policy"); + assert!(instances[0].config.enabled); + assert!( + Registry::first_party() + .instantiate(&catalog(CUSTOM), &HashMap::new()) + .await + .is_err(), + "unregistered, the same catalog stops startup" + ); + } + + #[test] + fn a_kind_name_is_taken_once() { + let mut registry = Registry::first_party(); + for taken in [basic_policy::KIND, "grpc"] { + assert!(registry.register(taken, Arc::new(StubFactory)).is_err()); + } + registry + .register("house-policy", Arc::new(StubFactory)) + .unwrap(); + assert!( + registry + .register("house-policy", Arc::new(StubFactory)) + .is_err() + ); + } + + #[tokio::test] + async fn a_panicking_factory_fails_startup_cleanly() { + let mut registry = Registry::first_party(); + registry + .register("house-policy", Arc::new(PanickingFactory)) + .unwrap(); + let error = registry + .instantiate(&catalog(CUSTOM), &HashMap::new()) + .await + .err() + .unwrap(); + assert!(error.contains("factory panicked"), "{error}"); + } + + #[tokio::test] + async fn a_panic_keeps_its_message() { + let timeout = std::time::Duration::from_secs(1); + let literal = isolated::<()>(timeout, async { panic!("literal message") }).await; + assert!( + matches!(literal, Err(CallError::Panicked(message)) if message == "literal message") + ); + let id = 7; + let formatted = isolated::<()>(timeout, async move { panic!("instance {id} broke") }).await; + assert!( + matches!(formatted, Err(CallError::Panicked(message)) if message == "instance 7 broke") + ); + } + + const PROTOCOL_CATALOG: &str = r#" +[[module]] +id = "negotiated" +kind = "protocol-stub" +scope = "all" +hooks = ["before_transaction_approved"] +timeout_ms = 50 +params = { old_name = 5 } +"#; + + async fn load(stub: crate::modules::testing::ProtocolStub) -> Result { + let mut registry = Registry::first_party(); + registry + .register( + "protocol-stub", + Arc::new(crate::modules::testing::FixedFactory(Arc::new(stub))), + ) + .unwrap(); + registry + .instantiate(&catalog(PROTOCOL_CATALOG), &HashMap::new()) + .await + } + + #[tokio::test] + async fn describe_tells_the_module_what_this_guardian_speaks() { + let stub = Arc::new(crate::modules::testing::ProtocolStub::new()); + let mut registry = Registry::first_party(); + registry + .register( + "protocol-stub", + Arc::new(crate::modules::testing::FixedFactory(stub.clone())), + ) + .unwrap(); + registry + .instantiate(&catalog(PROTOCOL_CATALOG), &HashMap::new()) + .await + .unwrap(); + let sent = stub.described_with.lock().unwrap().clone().unwrap(); + assert_eq!(sent.guardian_protocol_version, PROTOCOL_VERSION); + assert_eq!(sent.guardian_min_protocol_version, MIN_PROTOCOL_VERSION); + assert!( + sent.guardian_capabilities + .contains(&capability::PARAMS_NORMALIZATION.to_string()) + ); + } + + #[tokio::test] + async fn a_protocol_version_outside_the_supported_range_is_refused() { + for version in [MIN_PROTOCOL_VERSION - 1, PROTOCOL_VERSION + 1] { + let mut stub = crate::modules::testing::ProtocolStub::new(); + stub.protocol_version = version; + let error = load(stub).await.err().unwrap(); + assert!(error.contains("unsupported protocol version"), "{error}"); + } + } + + #[tokio::test] + async fn a_capability_this_guardian_lacks_is_refused() { + let mut stub = crate::modules::testing::ProtocolStub::new(); + stub.required_capabilities = vec!["pending.v2".into()]; + let error = load(stub).await.err().unwrap(); + assert!(error.contains("requires capability pending.v2"), "{error}"); + + let mut stub = crate::modules::testing::ProtocolStub::new(); + stub.required_capabilities = vec![capability::DECISION_EFFECT.into()]; + assert!(load(stub).await.is_ok()); + } + + #[tokio::test] + async fn normalized_params_come_back_from_the_startup_check() { + let mut stub = crate::modules::testing::ProtocolStub::new(); + stub.normalized = Some(serde_json::json!({ "new_name": 5 })); + let loaded = load(stub).await.unwrap(); + assert_eq!( + loaded.normalized.get("negotiated"), + Some(&serde_json::json!({ "new_name": 5 })) + ); + assert!( + load(crate::modules::testing::ProtocolStub::new()) + .await + .unwrap() + .normalized + .is_empty(), + "a module that returns nothing changes nothing" + ); + } +} diff --git a/crates/server/src/modules/request.rs b/crates/server/src/modules/request.rs new file mode 100644 index 00000000..725e0589 --- /dev/null +++ b/crates/server/src/modules/request.rs @@ -0,0 +1,330 @@ +//! Assembling what a module receives: account views, projection and proposal context. + +use chrono::{DateTime, Utc}; +use guardian_module_sdk::prost_types::Timestamp; +use guardian_module_sdk::proto::hook_request; +use guardian_module_sdk::{AccountView, HookRequest, RegistrationSubject, TransactionSubject}; + +use crate::delta_object::{DeltaObject, DeltaStatus}; +use crate::metadata::auth::Auth; +use crate::network::NetworkClient; + +#[derive(Debug, Clone, PartialEq)] +pub struct ProposalContext { + pub proposer: String, + pub metadata: serde_json::Value, +} + +/// The proposer and metadata of a stored proposal that is still pending. +pub fn proposal_context(proposal: &DeltaObject) -> Option { + match &proposal.status { + DeltaStatus::Pending { proposer_id, .. } => Some(ProposalContext { + proposer: proposer_id.clone(), + metadata: proposal + .delta_payload + .get("metadata") + .cloned() + .unwrap_or(serde_json::Value::Null), + }), + _ => None, + } +} + +fn timestamp(at: DateTime) -> Timestamp { + Timestamp { + seconds: at.timestamp(), + nanos: at.timestamp_subsec_nanos() as i32, + } +} + +/// An account state and the commitment the Guardian computed for it (never one a client sent). +#[derive(Clone, Copy)] +pub struct StateRef<'a> { + pub commitment: &'a str, + pub json: &'a serde_json::Value, +} + +const VIEW_CACHE_CAPACITY: usize = 4096; + +/// Account views by state commitment. Decoding an account is the main cost of a module request, +/// and states repeat: a chained push starts from the previous push's result, and a proposal's +/// approval sees the same before and after states as its creation. A view depends only on the +/// state, so the commitment is a sufficient key; the parts taken from the registered auth +/// configuration are filled in after the lookup. +#[derive(Default)] +pub struct ViewCache { + entries: std::sync::Mutex<( + std::collections::HashMap, + std::collections::VecDeque, + )>, +} + +impl ViewCache { + fn get_or_build( + &self, + network: &dyn NetworkClient, + state: StateRef<'_>, + ) -> Result { + if let Ok(entries) = self.entries.lock() + && let Some(view) = entries.0.get(state.commitment) + { + return Ok(view.clone()); + } + let view = network.module_account_view(state.json)?; + if let Ok(mut entries) = self.entries.lock() { + let (views, order) = &mut *entries; + if views + .insert(state.commitment.to_string(), view.clone()) + .is_none() + { + order.push_back(state.commitment.to_string()); + if order.len() > VIEW_CACHE_CAPACITY + && let Some(oldest) = order.pop_front() + { + views.remove(&oldest); + } + } + } + Ok(view) + } + + #[cfg(test)] + fn len(&self) -> usize { + self.entries.lock().map_or(0, |entries| entries.0.len()) + } +} + +/// The scheme every signer shares, or `mixed` when the signers use more than one. +fn signers_scheme(schemes: &std::collections::HashMap) -> Result { + let mut distinct: Vec<&String> = schemes.values().collect(); + distinct.sort(); + distinct.dedup(); + match distinct.as_slice() { + [] => Err("account view has no signer schemes".into()), + [scheme] => Ok((*scheme).clone()), + _ => Ok("mixed".into()), + } +} + +/// The account's view, its `auth_scheme` summarizing the signers' schemes. A multisig account's +/// signers and schemes are decoded from its state; a single-key account (no `default_threshold`) +/// takes its one signer and that signer's scheme from its verified auth configuration. +fn view( + network: &dyn NetworkClient, + views: &ViewCache, + state: StateRef<'_>, + auth: &Auth, +) -> Result { + let mut view = views.get_or_build(network, state)?; + if view.default_threshold.is_none() { + match auth.cosigner_commitments().as_slice() { + [signer] => { + let scheme = auth.signer_scheme(signer).ok_or_else(|| { + format!("single-key signer {signer} has no registered scheme") + })?; + view.signer_commitments = vec![signer.clone()]; + view.signer_schemes = [(signer.clone(), scheme.as_str().to_string())].into(); + } + signers => { + return Err(format!( + "single-key account registered with {} signers", + signers.len() + )); + } + } + } + view.auth_scheme = signers_scheme(&view.signer_schemes)?; + Ok(view) +} + +pub struct TransactionInput<'a> { + pub account_id: &'a str, + pub submitter: &'a str, + pub auth: &'a Auth, + pub before: StateRef<'a>, + pub after: StateRef<'a>, + pub tx_summary: &'a serde_json::Value, + pub proposal: Option, + pub accounting_time: DateTime, +} + +pub fn transaction_request( + network: &dyn NetworkClient, + views: &ViewCache, + input: TransactionInput<'_>, +) -> Result { + let transaction = network.module_transaction(input.tx_summary)?; + let (proposer, unverified_metadata) = match input.proposal { + Some(context) => ( + context.proposer, + serde_json::to_vec(&context.metadata).map_err(|e| e.to_string())?, + ), + None => (String::new(), Vec::new()), + }; + Ok(HookRequest { + network: "miden".into(), + account_id: input.account_id.to_string(), + accounting_time: Some(timestamp(input.accounting_time)), + submitter: input.submitter.to_string(), + before: Some(view(network, views, input.before, input.auth)?), + after: Some(view(network, views, input.after, input.auth)?), + subject: Some(hook_request::Subject::Transaction(TransactionSubject { + projection: Some(guardian_module_sdk::TransactionProjection::miden( + transaction.projection, + )), + raw: Some(guardian_module_sdk::RawTransaction { + encoding: guardian_module_sdk::RawTransaction::MIDEN_TRANSACTION_SUMMARY.into(), + data: transaction.raw_tx_summary, + }), + proposer, + unverified_metadata, + ..Default::default() + })), + ..Default::default() + }) +} + +pub struct RegistrationInput<'a> { + pub account_id: &'a str, + pub submitter: &'a str, + pub auth: &'a Auth, + pub stored_state: Option>, + pub initial_state: StateRef<'a>, + pub accounting_time: DateTime, +} + +pub fn registration_request( + network: &dyn NetworkClient, + views: &ViewCache, + input: RegistrationInput<'_>, +) -> Result { + Ok(HookRequest { + network: "miden".into(), + account_id: input.account_id.to_string(), + accounting_time: Some(timestamp(input.accounting_time)), + submitter: input.submitter.to_string(), + before: input + .stored_state + .map(|state| view(network, views, state, input.auth)) + .transpose()?, + after: Some(view(network, views, input.initial_state, input.auth)?), + subject: Some(hook_request::Subject::Registration( + RegistrationSubject::default(), + )), + ..Default::default() + }) +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::testing::mocks::MockNetworkClient; + + fn view_with(signer: &str) -> AccountView { + AccountView { + signer_commitments: vec![signer.into()], + default_threshold: Some(1), + ..Default::default() + } + } + + fn state(commitment: &str) -> StateRef<'_> { + static STATE: std::sync::OnceLock = std::sync::OnceLock::new(); + StateRef { + commitment, + json: STATE.get_or_init(|| serde_json::json!({})), + } + } + + #[test] + fn a_state_seen_before_is_not_decoded_again() { + let network = + MockNetworkClient::new().with_module_views(view_with("0xfirst"), Default::default()); + let cache = ViewCache::default(); + assert_eq!( + cache.get_or_build(&network, state("0xc1")).unwrap(), + view_with("0xfirst") + ); + *network.module_account_view.lock().unwrap() = Some(view_with("0xsecond")); + assert_eq!( + cache.get_or_build(&network, state("0xc1")).unwrap(), + view_with("0xfirst"), + "same commitment, cached view" + ); + assert_eq!( + cache.get_or_build(&network, state("0xc2")).unwrap(), + view_with("0xsecond"), + "new commitment, fresh decode" + ); + } + + #[test] + fn the_cache_is_bounded() { + let network = + MockNetworkClient::new().with_module_views(view_with("0xs"), Default::default()); + let cache = ViewCache::default(); + for n in 0..VIEW_CACHE_CAPACITY + 10 { + cache + .get_or_build(&network, state(&format!("0x{n}"))) + .unwrap(); + } + assert_eq!(cache.len(), VIEW_CACHE_CAPACITY); + } + + fn multisig_view(schemes: &[(&str, &str)]) -> AccountView { + AccountView { + signer_commitments: schemes.iter().map(|(signer, _)| (*signer).into()).collect(), + signer_schemes: schemes + .iter() + .map(|(signer, scheme)| ((*signer).into(), (*scheme).into())) + .collect(), + default_threshold: Some(1), + ..Default::default() + } + } + + fn built(decoded: AccountView, auth: &Auth) -> Result { + let network = MockNetworkClient::new().with_module_views(decoded, Default::default()); + view(&network, &ViewCache::default(), state("0xc1"), auth) + } + + #[test] + fn auth_scheme_summarizes_the_decoded_signer_schemes() { + let auth = Auth::MidenFalconRpo { + cosigner_commitments: vec!["0xa".into()], + }; + let shared = built(multisig_view(&[("0xa", "ecdsa"), ("0xb", "ecdsa")]), &auth).unwrap(); + assert_eq!( + shared.auth_scheme, "ecdsa", + "read from state, not the registration" + ); + let mixed = built(multisig_view(&[("0xa", "falcon"), ("0xb", "ecdsa")]), &auth).unwrap(); + assert_eq!(mixed.auth_scheme, "mixed"); + assert_eq!( + mixed.signer_schemes.get("0xb").map(String::as_str), + Some("ecdsa") + ); + } + + #[test] + fn a_single_key_view_takes_its_signer_and_scheme_from_the_registration() { + let auth = Auth::MidenEcdsa { + cosigner_commitments: vec!["0xsolo".into()], + }; + let single = built(AccountView::default(), &auth).unwrap(); + assert_eq!(single.signer_commitments, vec!["0xsolo".to_string()]); + assert_eq!( + single.signer_schemes.get("0xsolo").map(String::as_str), + Some("ecdsa") + ); + assert_eq!(single.auth_scheme, "ecdsa"); + } + + #[test] + fn a_failed_decode_is_not_cached() { + let network = MockNetworkClient::new(); + let cache = ViewCache::default(); + assert!(cache.get_or_build(&network, state("0xc1")).is_err()); + assert_eq!(cache.len(), 0); + } +} diff --git a/crates/server/src/modules/store.rs b/crates/server/src/modules/store.rs new file mode 100644 index 00000000..5015f122 --- /dev/null +++ b/crates/server/src/modules/store.rs @@ -0,0 +1,631 @@ +//! Module state tables: `module_instances`, `module_account_params`, `module_params_history`. + +use std::collections::BTreeMap; +use std::path::PathBuf; +use std::sync::RwLock; + +use async_trait::async_trait; +use serde::{Deserialize, Serialize}; + +#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] +pub struct InstanceRow { + pub module_id: String, + pub enabled: bool, + pub global_params: serde_json::Value, + pub seeded_params: serde_json::Value, + pub updated_at: String, + pub updated_by: String, +} + +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum ParamsKind { + Layer, + Assignment, +} + +impl ParamsKind { + pub fn as_str(self) -> &'static str { + match self { + ParamsKind::Layer => "layer", + ParamsKind::Assignment => "assignment", + } + } + + pub fn parse(kind: &str) -> Result { + match kind { + "layer" => Ok(ParamsKind::Layer), + "assignment" => Ok(ParamsKind::Assignment), + other => Err(format!("unknown params kind {other}")), + } + } +} + +#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] +pub struct AccountParamsRow { + pub account_id: String, + pub module_id: String, + pub kind: ParamsKind, + pub position: i32, + pub params: serde_json::Value, + pub updated_at: String, + pub updated_by: String, +} + +#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] +pub struct HistoryEntry { + pub version: u64, + pub module_id: String, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub account_id: Option, + pub previous: serde_json::Value, + pub new: serde_json::Value, + pub operator: String, + pub reason: String, + pub at: String, +} + +#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] +pub struct Assigned { + pub module_id: String, + pub params: serde_json::Value, +} + +/// Who changed what and why, for the history and the audit record. +pub struct Change<'a> { + pub operator: &'a str, + pub reason: &'a str, + pub at: String, +} + +/// Module state every replica reads. Each write updates its rows and appends the history in +/// one transaction; the highest history version is the params version. +#[async_trait] +pub trait ModuleStore: Send + Sync { + /// Inserts the instance row the first time `module_id` is seen; later calls do nothing. + async fn seed_instance( + &self, + module_id: &str, + enabled: bool, + params: &serde_json::Value, + at: &str, + ) -> Result<(), String>; + + async fn instances(&self) -> Result, String>; + + /// Switches an instance on or off for every account. Recorded in the history as + /// `{"enabled": previous}` to `{"enabled": new}`, so the version moves and caches refresh. + async fn set_enabled( + &self, + module_id: &str, + enabled: bool, + change: &Change<'_>, + ) -> Result<(), String>; + + async fn set_global( + &self, + module_id: &str, + params: serde_json::Value, + change: &Change<'_>, + ) -> Result<(), String>; + + /// Replaces the global params only while they still equal `expected`, and returns whether + /// it wrote. For writes derived from a value read earlier (a module migrating params), so + /// an operator's newer write is never overwritten. + async fn set_global_if( + &self, + module_id: &str, + expected: &serde_json::Value, + params: serde_json::Value, + change: &Change<'_>, + ) -> Result; + + async fn account_params(&self, account_id: &str) -> Result, String>; + + async fn set_layer( + &self, + account_id: &str, + module_id: &str, + params: Option, + change: &Change<'_>, + ) -> Result<(), String>; + + async fn set_assignment( + &self, + account_id: &str, + modules: Vec, + change: &Change<'_>, + ) -> Result<(), String>; + + async fn history(&self, module_id: &str) -> Result, String>; + + async fn version(&self) -> Result; +} + +#[derive(Debug, Default, Clone)] +struct Tables { + instances: BTreeMap, + account_params: Vec, + history: Vec, +} + +impl Tables { + fn version(&self) -> u64 { + self.history.last().map_or(0, |entry| entry.version) + } + + fn append( + &mut self, + module_id: &str, + account_id: Option<&str>, + previous: serde_json::Value, + new: serde_json::Value, + change: &Change<'_>, + ) { + let version = self.version() + 1; + self.history.push(HistoryEntry { + version, + module_id: module_id.to_string(), + account_id: account_id.map(str::to_string), + previous, + new, + operator: change.operator.to_string(), + reason: change.reason.to_string(), + at: change.at.clone(), + }); + } + + fn row_params(&self, account_id: &str, module_id: &str, kind: ParamsKind) -> serde_json::Value { + self.account_params + .iter() + .find(|row| { + row.account_id == account_id && row.module_id == module_id && row.kind == kind + }) + .map(|row| row.params.clone()) + .unwrap_or_default() + } +} + +const STATE_FILE: &str = "module_state.json"; + +/// The three tables as one file, so a write and its history row land together or not at all. +#[derive(Serialize, serde::Deserialize, Default)] +struct Snapshot { + instances: Vec, + account_params: Vec, + history: Vec, +} + +/// The filesystem backend's copy of the three tables. +pub struct FsModuleStore { + tables: RwLock, + dir: Option, +} + +fn read_snapshot(dir: &std::path::Path) -> Result { + match std::fs::read_to_string(dir.join(STATE_FILE)) { + Ok(text) => serde_json::from_str(&text).map_err(|e| format!("invalid {STATE_FILE}: {e}")), + Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(Snapshot::default()), + Err(e) => Err(format!("cannot read {STATE_FILE}: {e}")), + } +} + +fn write_snapshot(dir: &std::path::Path, tables: &Tables) -> Result<(), String> { + use std::io::Write; + let snapshot = Snapshot { + instances: tables.instances.values().cloned().collect(), + account_params: tables.account_params.clone(), + history: tables.history.clone(), + }; + let json = serde_json::to_vec_pretty(&snapshot).map_err(|e| e.to_string())?; + let path = dir.join(STATE_FILE); + let temp = path.with_extension("tmp"); + let failed = |e: std::io::Error| format!("cannot write {STATE_FILE}: {e}"); + let mut file = std::fs::File::create(&temp).map_err(failed)?; + file.write_all(&json).map_err(failed)?; + file.sync_all().map_err(failed)?; + std::fs::rename(&temp, &path).map_err(failed)?; + std::fs::File::open(dir) + .and_then(|dir| dir.sync_all()) + .map_err(failed) +} + +impl FsModuleStore { + pub fn in_memory() -> Self { + Self { + tables: RwLock::new(Tables::default()), + dir: None, + } + } + + pub fn open(dir: PathBuf) -> Result { + std::fs::create_dir_all(&dir) + .map_err(|e| format!("cannot create {}: {e}", dir.display()))?; + let snapshot = read_snapshot(&dir)?; + let tables = Tables { + instances: snapshot + .instances + .into_iter() + .map(|row| (row.module_id.clone(), row)) + .collect(), + account_params: snapshot.account_params, + history: snapshot.history, + }; + Ok(Self { + tables: RwLock::new(tables), + dir: Some(dir), + }) + } + + fn read(&self, view: impl FnOnce(&Tables) -> T) -> T { + match self.tables.read() { + Ok(tables) => view(&tables), + Err(poisoned) => view(&poisoned.into_inner()), + } + } + + fn write(&self, apply: impl FnOnce(&mut Tables) -> Result) -> Result { + let mut tables = self.tables.write().map_err(|_| "module store poisoned")?; + let mut next = tables.clone(); + let out = apply(&mut next)?; + if let Some(dir) = &self.dir { + write_snapshot(dir, &next)?; + } + *tables = next; + Ok(out) + } +} + +#[async_trait] +impl ModuleStore for FsModuleStore { + async fn seed_instance( + &self, + module_id: &str, + enabled: bool, + params: &serde_json::Value, + at: &str, + ) -> Result<(), String> { + if self.read(|tables| tables.instances.contains_key(module_id)) { + return Ok(()); + } + self.write(|tables| { + tables.instances.insert( + module_id.to_string(), + InstanceRow { + module_id: module_id.to_string(), + enabled, + global_params: params.clone(), + seeded_params: params.clone(), + updated_at: at.to_string(), + updated_by: "catalog".into(), + }, + ); + let change = Change { + operator: "catalog", + reason: "seeded from the catalog file", + at: at.to_string(), + }; + tables.append( + module_id, + None, + serde_json::Value::Null, + params.clone(), + &change, + ); + Ok(()) + }) + } + + async fn instances(&self) -> Result, String> { + Ok(self.read(|tables| tables.instances.values().cloned().collect())) + } + + async fn set_enabled( + &self, + module_id: &str, + enabled: bool, + change: &Change<'_>, + ) -> Result<(), String> { + self.write(|tables| { + let row = tables + .instances + .get_mut(module_id) + .ok_or_else(|| format!("module {module_id} has no instance row"))?; + let previous = std::mem::replace(&mut row.enabled, enabled); + row.updated_at = change.at.clone(); + row.updated_by = change.operator.to_string(); + tables.append( + module_id, + None, + serde_json::json!({ "enabled": previous }), + serde_json::json!({ "enabled": enabled }), + change, + ); + Ok(()) + }) + } + + async fn set_global( + &self, + module_id: &str, + params: serde_json::Value, + change: &Change<'_>, + ) -> Result<(), String> { + self.write(|tables| { + let row = tables + .instances + .entry(module_id.to_string()) + .or_insert_with(|| InstanceRow { + module_id: module_id.to_string(), + enabled: true, + global_params: serde_json::Value::Null, + seeded_params: params.clone(), + updated_at: change.at.clone(), + updated_by: change.operator.to_string(), + }); + let previous = std::mem::replace(&mut row.global_params, params.clone()); + row.updated_at = change.at.clone(); + row.updated_by = change.operator.to_string(); + tables.append(module_id, None, previous, params, change); + Ok(()) + }) + } + + async fn set_global_if( + &self, + module_id: &str, + expected: &serde_json::Value, + params: serde_json::Value, + change: &Change<'_>, + ) -> Result { + self.write(|tables| { + let Some(row) = tables + .instances + .get_mut(module_id) + .filter(|row| row.global_params == *expected) + else { + return Ok(false); + }; + let previous = std::mem::replace(&mut row.global_params, params.clone()); + row.updated_at = change.at.clone(); + row.updated_by = change.operator.to_string(); + tables.append(module_id, None, previous, params, change); + Ok(true) + }) + } + + async fn account_params(&self, account_id: &str) -> Result, String> { + Ok(self.read(|tables| { + let mut rows: Vec = tables + .account_params + .iter() + .filter(|row| row.account_id == account_id) + .cloned() + .collect(); + rows.sort_by_key(|row| row.position); + rows + })) + } + + async fn set_layer( + &self, + account_id: &str, + module_id: &str, + params: Option, + change: &Change<'_>, + ) -> Result<(), String> { + self.write(|tables| { + let previous = tables.row_params(account_id, module_id, ParamsKind::Layer); + tables + .account_params + .retain(|row| !(row.account_id == account_id && row.module_id == module_id)); + if let Some(params) = ¶ms { + tables.account_params.push(AccountParamsRow { + account_id: account_id.to_string(), + module_id: module_id.to_string(), + kind: ParamsKind::Layer, + position: 0, + params: params.clone(), + updated_at: change.at.clone(), + updated_by: change.operator.to_string(), + }); + } + tables.append( + module_id, + Some(account_id), + previous, + params.unwrap_or_default(), + change, + ); + Ok(()) + }) + } + + async fn set_assignment( + &self, + account_id: &str, + modules: Vec, + change: &Change<'_>, + ) -> Result<(), String> { + self.write(|tables| { + let previous: Vec = tables + .account_params + .iter() + .filter(|row| row.account_id == account_id && row.kind == ParamsKind::Assignment) + .cloned() + .collect(); + tables.account_params.retain(|row| { + !(row.account_id == account_id && row.kind == ParamsKind::Assignment) + }); + for (position, assigned) in modules.iter().enumerate() { + tables.account_params.push(AccountParamsRow { + account_id: account_id.to_string(), + module_id: assigned.module_id.clone(), + kind: ParamsKind::Assignment, + position: position as i32, + params: assigned.params.clone(), + updated_at: change.at.clone(), + updated_by: change.operator.to_string(), + }); + } + for (module_id, before, after) in assignment_changes(&previous, &modules) { + tables.append(&module_id, Some(account_id), before, after, change); + } + Ok(()) + }) + } + + async fn history(&self, module_id: &str) -> Result, String> { + Ok(self.read(|tables| { + tables + .history + .iter() + .filter(|entry| entry.module_id == module_id) + .cloned() + .collect() + })) + } + + async fn version(&self) -> Result { + Ok(self.read(Tables::version)) + } +} + +/// `(module_id, previous, new)` for every module whose assigned params changed. +pub(crate) fn assignment_changes( + previous: &[AccountParamsRow], + modules: &[Assigned], +) -> Vec<(String, serde_json::Value, serde_json::Value)> { + let mut ids: Vec<&str> = previous.iter().map(|row| row.module_id.as_str()).collect(); + ids.extend(modules.iter().map(|assigned| assigned.module_id.as_str())); + ids.sort_unstable(); + ids.dedup(); + ids.into_iter() + .filter_map(|module_id| { + let before = previous + .iter() + .find(|row| row.module_id == module_id) + .map(|row| row.params.clone()) + .unwrap_or_default(); + let after = modules + .iter() + .find(|assigned| assigned.module_id == module_id) + .map(|assigned| assigned.params.clone()) + .unwrap_or_default(); + (before != after).then(|| (module_id.to_string(), before, after)) + }) + .collect() +} + +#[cfg(test)] +mod tests { + use serde_json::json; + + use super::*; + + fn change() -> Change<'static> { + Change { + operator: "0xop", + reason: "ticket", + at: "2026-10-15T00:00:00Z".into(), + } + } + + #[tokio::test] + async fn seeding_happens_once_and_api_changes_win() { + let store = FsModuleStore::in_memory(); + store + .seed_instance("caps", true, &json!({ "a": 1 }), "t0") + .await + .unwrap(); + store + .set_global("caps", json!({ "a": 2 }), &change()) + .await + .unwrap(); + store + .seed_instance("caps", true, &json!({ "a": 3 }), "t1") + .await + .unwrap(); + let rows = store.instances().await.unwrap(); + assert_eq!(rows[0].global_params, json!({ "a": 2 })); + assert_eq!(rows[0].seeded_params, json!({ "a": 1 })); + assert_eq!(store.version().await.unwrap(), 2); + } + + #[tokio::test] + async fn the_enabled_switch_is_stored_and_moves_the_version() { + let store = FsModuleStore::in_memory(); + store + .seed_instance("caps", true, &json!({}), "t0") + .await + .unwrap(); + store.set_enabled("caps", false, &change()).await.unwrap(); + assert!(!store.instances().await.unwrap()[0].enabled); + let history = store.history("caps").await.unwrap(); + assert_eq!(history[1].previous, json!({ "enabled": true })); + assert_eq!(history[1].new, json!({ "enabled": false })); + assert_eq!(store.version().await.unwrap(), 2); + assert!( + store + .set_enabled("unknown", false, &change()) + .await + .is_err() + ); + } + + #[tokio::test] + async fn layers_and_assignments_share_the_account_table() { + let store = FsModuleStore::in_memory(); + store + .set_layer("0xacc", "blocklist", Some(json!({ "b": 1 })), &change()) + .await + .unwrap(); + store + .set_assignment( + "0xacc", + vec![Assigned { + module_id: "optional".into(), + params: json!({ "c": 1 }), + }], + &change(), + ) + .await + .unwrap(); + let rows = store.account_params("0xacc").await.unwrap(); + assert_eq!(rows.len(), 2); + assert!(rows.iter().any(|row| row.kind == ParamsKind::Layer)); + assert!(rows.iter().any(|row| row.kind == ParamsKind::Assignment)); + assert!(store.account_params("0xother").await.unwrap().is_empty()); + + store + .set_layer("0xacc", "blocklist", None, &change()) + .await + .unwrap(); + assert_eq!(store.account_params("0xacc").await.unwrap().len(), 1); + let history = store.history("blocklist").await.unwrap(); + assert_eq!(history.len(), 2); + assert_eq!(history[1].previous, json!({ "b": 1 })); + } + + #[tokio::test] + async fn tables_survive_a_restart() { + let dir = std::env::temp_dir().join(format!("modules_{:016x}", rand::random::())); + { + let store = FsModuleStore::open(dir.clone()).unwrap(); + store + .seed_instance("caps", true, &json!({ "a": 1 }), "t0") + .await + .unwrap(); + store + .set_layer("0xacc", "caps", Some(json!({ "b": 1 })), &change()) + .await + .unwrap(); + } + assert!(dir.join(STATE_FILE).exists()); + assert!(!dir.join(STATE_FILE).with_extension("tmp").exists()); + let reopened = FsModuleStore::open(dir.clone()).unwrap(); + assert_eq!(reopened.version().await.unwrap(), 2); + assert_eq!(reopened.account_params("0xacc").await.unwrap().len(), 1); + std::fs::remove_dir_all(dir).ok(); + } +} diff --git a/crates/server/src/modules/testing.rs b/crates/server/src/modules/testing.rs new file mode 100644 index 00000000..5f80a444 --- /dev/null +++ b/crates/server/src/modules/testing.rs @@ -0,0 +1,341 @@ +use std::sync::Arc; +use std::sync::atomic::{AtomicUsize, Ordering}; +use std::time::Duration; + +use async_trait::async_trait; +use guardian_module_sdk::{ + Decision, DescribeRequest, HookRequest, Module, ModuleError, ModuleInfo, PROTOCOL_VERSION, + ParamsVerdict, +}; + +use super::catalog::{HookName, InstanceConfig, OnError, Scope}; +use super::pipeline::ModulePipeline; +use super::registry::Instance; + +#[derive(Clone)] +pub enum Behaviour { + Decide(Decision), + Fail, + Hang, + Panic, + /// Blocks its thread instead of awaiting, like a module doing synchronous work. + Block(Duration), +} + +pub struct StubModule { + behaviour: Behaviour, + pub calls: AtomicUsize, + pub last_request: std::sync::Mutex>, +} + +impl StubModule { + pub fn new(behaviour: Behaviour) -> Arc { + Arc::new(Self { + behaviour, + calls: AtomicUsize::new(0), + last_request: std::sync::Mutex::new(None), + }) + } + + pub fn allowing() -> Arc { + Self::new(Behaviour::Decide(Decision::allow())) + } + + pub fn denying(reason_code: &str) -> Arc { + Self::new(Behaviour::Decide(Decision::deny(reason_code, "stub"))) + } + + pub fn last_request(&self) -> Option { + self.last_request.lock().unwrap().clone() + } + + pub fn calls(&self) -> usize { + self.calls.load(Ordering::SeqCst) + } +} + +#[async_trait] +impl Module for StubModule { + async fn describe(&self, _guardian: &DescribeRequest) -> Result { + Ok(ModuleInfo { + name: "stub".into(), + version: "0".into(), + protocol_version: PROTOCOL_VERSION, + hooks: vec![], + ..Default::default() + }) + } + + async fn validate_params(&self, _params: &[u8]) -> Result { + Ok(ParamsVerdict::ok()) + } + + async fn evaluate(&self, request: &HookRequest) -> Result { + self.calls.fetch_add(1, Ordering::SeqCst); + *self.last_request.lock().unwrap() = Some(request.clone()); + match &self.behaviour { + Behaviour::Decide(decision) => Ok(decision.clone()), + Behaviour::Fail => Err(ModuleError::Unavailable("stub down".into())), + Behaviour::Hang => { + tokio::time::sleep(Duration::from_secs(60)).await; + Ok(Decision::allow()) + } + Behaviour::Panic => panic!("stub module panicked"), + Behaviour::Block(duration) => { + std::thread::sleep(*duration); + Ok(Decision::allow()) + } + } + } +} + +pub fn instance( + id: &str, + hooks: &[HookName], + on_error: OnError, + module: Arc, +) -> Instance { + Instance { + config: InstanceConfig { + id: id.into(), + kind: "stub".into(), + endpoint: None, + scope: Scope::All, + hooks: hooks.to_vec(), + timeout: Duration::from_millis(50), + on_error, + enabled: true, + catalog_enabled: true, + operator_can_disable: true, + disclosure: Default::default(), + description: None, + client_reason: Default::default(), + dry_run: true, + auth_token: None, + tls: None, + params: serde_json::json!({}), + file_managed_params: false, + }, + module, + build: Some("stub 1".into()), + } +} + +pub fn instance_with_params( + id: &str, + hooks: &[HookName], + module: Arc, + params: serde_json::Value, +) -> Instance { + let mut instance = instance(id, hooks, OnError::Deny, module); + instance.config.params = params; + instance +} + +pub fn pipeline(instances: Vec) -> Arc { + Arc::new(ModulePipeline::from_instances(instances)) +} + +/// A module whose `describe` and `validate_params` answers are configurable, for the protocol +/// negotiation and params migration tests. It records what the Guardian sent in `Describe`. +pub struct ProtocolStub { + pub protocol_version: u32, + pub required_capabilities: Vec, + pub normalized: Option, + pub described_with: std::sync::Mutex>, +} + +impl Default for ProtocolStub { + fn default() -> Self { + Self::new() + } +} + +impl ProtocolStub { + pub fn new() -> Self { + Self { + protocol_version: PROTOCOL_VERSION, + required_capabilities: Vec::new(), + normalized: None, + described_with: std::sync::Mutex::new(None), + } + } +} + +#[async_trait] +impl Module for ProtocolStub { + async fn describe(&self, guardian: &DescribeRequest) -> Result { + *self.described_with.lock().unwrap() = Some(guardian.clone()); + Ok(ModuleInfo { + name: "protocol-stub".into(), + version: "1".into(), + protocol_version: self.protocol_version, + hooks: vec![guardian_module_sdk::Hook::BeforeTransactionApproved as i32], + required_capabilities: self.required_capabilities.clone(), + }) + } + + async fn validate_params(&self, _params: &[u8]) -> Result { + Ok(match &self.normalized { + Some(params) => ParamsVerdict::normalized(params), + None => ParamsVerdict::ok(), + }) + } + + async fn evaluate(&self, _request: &HookRequest) -> Result { + Ok(Decision::allow()) + } +} + +/// Hands out one prepared module for every instance of its kind. +pub struct FixedFactory(pub Arc); + +impl guardian_module_sdk::ModuleFactory for FixedFactory { + fn create( + &self, + _instance: &guardian_module_sdk::ModuleInstanceConfig, + ) -> Result, ModuleError> { + Ok(self.0.clone()) + } +} + +/// An operator write a [`RacingStore`] commits at a chosen moment. +pub enum RacingWrite { + Global(&'static str, serde_json::Value), + Layer(&'static str, &'static str, Option), +} + +/// A module store that commits operator writes just before a chosen read or write of the +/// caller, to reproduce writes racing with an evaluation or a migration. +pub struct RacingStore { + pub inner: super::store::FsModuleStore, + pub before_account_params: std::sync::Mutex>, + pub before_set_global_if: std::sync::Mutex>, +} + +impl RacingStore { + pub fn new() -> Self { + Self { + inner: super::store::FsModuleStore::in_memory(), + before_account_params: Default::default(), + before_set_global_if: Default::default(), + } + } + + async fn commit(&self, writes: Vec) -> Result<(), String> { + use super::store::ModuleStore; + let change = super::store::Change { + operator: "0xracing-operator", + reason: "concurrent write", + at: "2026-10-16T00:00:01Z".into(), + }; + for write in writes { + match write { + RacingWrite::Global(module, params) => { + self.inner.set_global(module, params, &change).await? + } + RacingWrite::Layer(account, module, params) => { + self.inner + .set_layer(account, module, params, &change) + .await? + } + } + } + Ok(()) + } +} + +impl Default for RacingStore { + fn default() -> Self { + Self::new() + } +} + +#[async_trait] +impl super::store::ModuleStore for RacingStore { + async fn seed_instance( + &self, + module_id: &str, + enabled: bool, + params: &serde_json::Value, + at: &str, + ) -> Result<(), String> { + self.inner + .seed_instance(module_id, enabled, params, at) + .await + } + + async fn instances(&self) -> Result, String> { + self.inner.instances().await + } + + async fn set_enabled( + &self, + module_id: &str, + enabled: bool, + change: &super::store::Change<'_>, + ) -> Result<(), String> { + self.inner.set_enabled(module_id, enabled, change).await + } + + async fn set_global( + &self, + module_id: &str, + params: serde_json::Value, + change: &super::store::Change<'_>, + ) -> Result<(), String> { + self.inner.set_global(module_id, params, change).await + } + + async fn set_global_if( + &self, + module_id: &str, + expected: &serde_json::Value, + params: serde_json::Value, + change: &super::store::Change<'_>, + ) -> Result { + let writes = std::mem::take(&mut *self.before_set_global_if.lock().unwrap()); + self.commit(writes).await?; + self.inner + .set_global_if(module_id, expected, params, change) + .await + } + + async fn account_params( + &self, + account_id: &str, + ) -> Result, String> { + let writes = std::mem::take(&mut *self.before_account_params.lock().unwrap()); + self.commit(writes).await?; + self.inner.account_params(account_id).await + } + + async fn set_layer( + &self, + account_id: &str, + module_id: &str, + params: Option, + change: &super::store::Change<'_>, + ) -> Result<(), String> { + self.inner + .set_layer(account_id, module_id, params, change) + .await + } + + async fn set_assignment( + &self, + account_id: &str, + modules: Vec, + change: &super::store::Change<'_>, + ) -> Result<(), String> { + self.inner.set_assignment(account_id, modules, change).await + } + + async fn history(&self, module_id: &str) -> Result, String> { + self.inner.history(module_id).await + } + + async fn version(&self) -> Result { + self.inner.version().await + } +} diff --git a/crates/server/src/network/miden/mod.rs b/crates/server/src/network/miden/mod.rs index 0bd83a96..67923b98 100644 --- a/crates/server/src/network/miden/mod.rs +++ b/crates/server/src/network/miden/mod.rs @@ -1,6 +1,7 @@ pub mod account_inspector; pub mod block_feed; pub mod execution; +pub mod module_views; use crate::metadata::auth::{Auth, Credentials}; use crate::network::miden::account_inspector::{ @@ -898,6 +899,20 @@ impl NetworkClient for MidenNetworkClient { Ok(Some(MidenAccountInspector::new(&account).auth_binding())) } + fn module_account_view( + &self, + state_json: &serde_json::Value, + ) -> Result { + module_views::account_view(state_json) + } + + fn module_transaction( + &self, + tx_summary: &serde_json::Value, + ) -> Result { + module_views::module_transaction(tx_summary) + } + async fn should_update_auth( &self, state_json: &serde_json::Value, diff --git a/crates/server/src/network/miden/module_views.rs b/crates/server/src/network/miden/module_views.rs new file mode 100644 index 00000000..1c6bcdea --- /dev/null +++ b/crates/server/src/network/miden/module_views.rs @@ -0,0 +1,480 @@ +//! Account views and transaction projections sent to policy modules. + +use guardian_module_sdk::proto::{MapChanges, MapEntry, asset}; +use guardian_module_sdk::{ + AccountView, Asset as ModuleAsset, Direction, InputNote, MidenTransaction, NoteType, + OutputNote, StorageChange, StorageOp, StorageSlotKind, VaultChange, +}; +use guardian_shared::{FromJson, SignatureScheme}; +use miden_protocol::Word; +use miden_protocol::account::{Account, StoragePatchOperation, StorageSlotContent}; +use miden_protocol::asset::Asset; +use miden_protocol::note::{Note, NoteType as MidenNoteType}; +use miden_protocol::transaction::{RawOutputNote, TransactionSummary}; +use miden_protocol::utils::serde::Serializable; +use miden_standards::account::auth::AuthGuardedMultisig; +use miden_standards::note::{P2idNoteStorage, P2ideNoteStorage, StandardNote}; + +fn word_hex(word: &Word) -> String { + format!("0x{}", hex::encode(word.as_bytes())) +} + +fn felt_u32(felt: miden_protocol::Felt) -> Result { + u32::try_from(felt.as_canonical_u64()).map_err(|_| "value does not fit in u32".into()) +} + +/// Signers with their schemes, default threshold and procedure thresholds of a multisig account. +/// An account without the multisig component is single-key: its view carries no signers and no +/// `default_threshold`, and the caller fills the signer and its scheme from the account's +/// verified auth configuration. A signer whose scheme entry is missing or names no supported +/// scheme is an error, never a signer without a scheme. +pub fn account_view(state_json: &serde_json::Value) -> Result { + let account = Account::from_json(state_json)?; + let storage = account.storage(); + + let Ok(threshold_config) = storage.get_item(AuthGuardedMultisig::threshold_config_slot()) + else { + return Ok(AccountView { + commitment: word_hex(&account.to_commitment()), + ..Default::default() + }); + }; + let default_threshold = felt_u32(threshold_config[0])?; + let num_approvers = felt_u32(threshold_config[1])?; + + let signer_commitments = (0..num_approvers) + .map(|index| { + storage + .get_map_item( + AuthGuardedMultisig::approver_public_keys_slot(), + miden_protocol::account::StorageMapKey::new(Word::from([index, 0, 0, 0])), + ) + .map_err(|e| format!("approver {index} unreadable: {e}")) + .and_then(|value| { + if value == Word::default() { + Err(format!("approver {index} missing")) + } else { + Ok(word_hex(&value)) + } + }) + }) + .collect::, _>>()?; + if signer_commitments.is_empty() { + return Err("multisig account has no approvers".into()); + } + let signer_schemes = signer_commitments + .iter() + .zip(0u32..) + .map(|(commitment, index)| { + let id = storage + .get_map_item( + AuthGuardedMultisig::approver_scheme_ids_slot(), + miden_protocol::account::StorageMapKey::new(Word::from([index, 0, 0, 0])), + ) + .map_err(|e| format!("approver {index} scheme unreadable: {e}"))?[0] + .as_canonical_u64(); + SignatureScheme::from_auth_scheme_id(id) + .map(|scheme| (commitment.clone(), scheme.as_str().to_string())) + .ok_or_else(|| format!("approver {index} has no supported scheme (id {id})")) + }) + .collect::>()?; + + let procedure_thresholds = match storage + .get(AuthGuardedMultisig::procedure_thresholds_slot()) + .map(|slot| slot.content()) + { + Some(StorageSlotContent::Map(map)) => map + .entries() + .map(|(root, value)| Ok((word_hex(&Word::from(*root)), felt_u32(value[0])?))) + .collect::>()?, + Some(_) => return Err("procedure thresholds slot is not a map".into()), + None => Default::default(), + }; + + Ok(AccountView { + commitment: word_hex(&account.to_commitment()), + auth_scheme: String::new(), + signer_commitments, + default_threshold: Some(default_threshold), + procedure_thresholds, + signer_schemes, + }) +} + +fn module_asset(asset: &Asset) -> ModuleAsset { + match asset.as_fungible() { + Some(fungible) => ModuleAsset { + faucet_id: fungible.faucet_id().to_hex(), + value: Some(asset::Value::FungibleAmount(fungible.amount().to_string())), + }, + None => ModuleAsset { + faucet_id: asset.faucet_id().to_hex(), + value: Some(asset::Value::NftId(word_hex(&asset.to_id_word()))), + }, + } +} + +fn note_type(note_type: MidenNoteType) -> i32 { + match note_type { + MidenNoteType::Public => NoteType::Public as i32, + MidenNoteType::Private => NoteType::Private as i32, + } +} + +fn p2id_target(note: &Note) -> Option { + match StandardNote::from_script(note.script())? { + StandardNote::P2ID => P2idNoteStorage::try_from(note.storage().items()) + .ok() + .map(|storage| storage.target().to_hex()), + StandardNote::P2IDE => P2ideNoteStorage::try_from(note.storage().items()) + .ok() + .map(|storage| storage.target().to_hex()), + _ => None, + } +} + +fn output_note(raw: &RawOutputNote) -> OutputNote { + match raw { + RawOutputNote::Full(note) => OutputNote { + note_id: note.id().to_hex(), + note_type: note_type(note.metadata().note_type()), + partial: false, + recipient_digest: word_hex(¬e.recipient().digest()), + assets: note.assets().iter().map(module_asset).collect(), + script_root: word_hex(&Word::from(note.script().root())), + p2id_target: p2id_target(note), + tx_fee: matches!( + StandardNote::from_script(note.script()), + Some(StandardNote::TX_FEE) + ), + }, + RawOutputNote::Partial(partial) => OutputNote { + note_id: partial.id().to_hex(), + note_type: note_type(partial.metadata().note_type()), + partial: true, + recipient_digest: word_hex(&partial.recipient_digest()), + assets: partial.assets().iter().map(module_asset).collect(), + script_root: String::new(), + p2id_target: None, + tx_fee: false, + }, + } +} + +fn storage_op(op: StoragePatchOperation) -> i32 { + match op { + StoragePatchOperation::Create => StorageOp::Create as i32, + StoragePatchOperation::Update => StorageOp::Update as i32, + StoragePatchOperation::Remove => StorageOp::Remove as i32, + } +} + +/// Decodes exactly the summary the Guardian verifies and acks; a proposal wrapper is refused +/// rather than unwrapped, so a module never judges a different summary than the one signed. +pub fn module_transaction( + tx_summary: &serde_json::Value, +) -> Result { + let summary = TransactionSummary::from_json(tx_summary) + .map_err(|e| format!("transaction summary does not decode: {e}"))?; + Ok(crate::network::ModuleTransaction { + projection: projection_from_summary(&summary)?, + raw_tx_summary: summary.to_bytes(), + }) +} + +fn expiration_block(block_number: u32, expiration_delta: u16) -> Result { + block_number + .checked_add(u32::from(expiration_delta)) + .ok_or_else(|| format!("expiration overflows: block {block_number} + {expiration_delta}")) +} + +fn projection_from_summary(summary: &TransactionSummary) -> Result { + let delta = summary.account_delta(); + let vault = delta.vault(); + let vault_changes = vault + .added_assets() + .map(|asset| (asset, Direction::In)) + .chain(vault.removed_assets().map(|asset| (asset, Direction::Out))) + .map(|(asset, direction)| VaultChange { + asset: Some(module_asset(&asset)), + direction: direction as i32, + }) + .collect(); + + let storage = delta.storage(); + let mut storage_changes: Vec = storage + .values() + .map(|(slot_name, patch)| StorageChange { + slot_name: slot_name.as_str().to_string(), + kind: StorageSlotKind::Value as i32, + op: storage_op(patch.patch_op()), + value: patch + .value() + .map(|word| word_hex(&word)) + .unwrap_or_default(), + map: None, + }) + .collect(); + storage_changes.extend(storage.maps().map(|(slot_name, patch)| StorageChange { + slot_name: slot_name.as_str().to_string(), + kind: StorageSlotKind::Map as i32, + op: storage_op(patch.patch_op()), + value: String::new(), + map: patch.entries().map(|entries| { + MapChanges { + entries: entries + .as_map() + .iter() + .map(|(key, value)| MapEntry { + key: word_hex(&Word::from(*key)), + value: word_hex(value), + }) + .collect(), + } + }), + })); + + Ok(MidenTransaction { + nonce_delta: delta.nonce_delta().as_canonical_u64() as i64, + expiration_block: expiration_block( + summary.block_number().as_u32(), + summary.expiration_delta(), + )?, + vault_changes, + output_notes: summary.output_notes().iter().map(output_note).collect(), + input_notes: summary + .input_notes() + .iter() + .map(|input| InputNote { + note_id: input.note().id().to_hex(), + assets: input.note().assets().iter().map(module_asset).collect(), + }) + .collect(), + storage_changes, + }) +} + +#[cfg(test)] +mod tests { + use guardian_shared::ToJson; + use miden_protocol::account::{ + AccountCode, AccountId, AccountIdVersion, AccountStorage, AccountType, StorageMap, + StorageMapKey, StorageSlot, + }; + use miden_protocol::asset::AssetVault; + + use super::*; + + fn map_slot( + name: &miden_protocol::account::StorageSlotName, + entries: Vec<(Word, Word)>, + ) -> StorageSlot { + let entries = entries + .into_iter() + .map(|(key, value)| (StorageMapKey::new(key), value)); + StorageSlot::with_map(name.clone(), StorageMap::with_entries(entries).unwrap()) + } + + fn account(slots: Vec) -> serde_json::Value { + let account = Account::new_existing( + AccountId::dummy( + [3u8; 15], + AccountIdVersion::Version1, + AccountType::Private, + miden_protocol::account::AssetCallbackFlag::Disabled, + ), + AssetVault::new(&[]).unwrap(), + AccountStorage::new(slots).unwrap(), + AccountCode::mock(), + miden_protocol::Felt::new_unchecked(1), + ); + account.to_json() + } + + fn multisig( + threshold: u32, + approvers: u32, + keys: u32, + procedures: Vec<(Word, Word)>, + ) -> serde_json::Value { + let schemes = vec![SignatureScheme::Falcon.auth_scheme() as u64; keys as usize]; + multisig_with_schemes(threshold, approvers, keys, procedures, &schemes) + } + + /// `schemes[i]` is the auth scheme id stored for approver `i`. + fn multisig_with_schemes( + threshold: u32, + approvers: u32, + keys: u32, + procedures: Vec<(Word, Word)>, + schemes: &[u64], + ) -> serde_json::Value { + account(vec![ + StorageSlot::with_value( + AuthGuardedMultisig::threshold_config_slot().clone(), + Word::from([threshold, approvers, 0, 0]), + ), + map_slot( + AuthGuardedMultisig::approver_public_keys_slot(), + (0..keys) + .map(|i| (Word::from([i, 0, 0, 0]), Word::from([100 + i, 1, 1, 1]))) + .collect(), + ), + map_slot(AuthGuardedMultisig::procedure_thresholds_slot(), procedures), + map_slot( + AuthGuardedMultisig::approver_scheme_ids_slot(), + schemes + .iter() + .zip(0u32..) + .map(|(id, i)| { + ( + Word::from([i, 0, 0, 0]), + Word::from([ + miden_protocol::Felt::new_unchecked(*id), + 0u32.into(), + 0u32.into(), + 0u32.into(), + ]), + ) + }) + .collect(), + ), + ]) + } + + #[test] + fn view_of_the_fixture_account_has_signers_and_a_threshold() { + let state: serde_json::Value = + serde_json::from_str(crate::testing::fixtures::ACCOUNT_JSON).unwrap(); + let view = account_view(&state).unwrap(); + assert!(!view.signer_commitments.is_empty()); + assert!(view.default_threshold.is_some()); + assert!(view.commitment.starts_with("0x")); + } + + #[test] + fn view_reads_signers_default_and_procedure_thresholds() { + let root = Word::from([7u32, 7, 7, 7]); + let view = account_view(&multisig( + 2, + 3, + 3, + vec![(root, Word::from([3u32, 0, 0, 0]))], + )) + .unwrap(); + assert_eq!(view.signer_commitments.len(), 3); + assert_eq!(view.default_threshold, Some(2)); + assert_eq!(view.procedure_thresholds.get(&word_hex(&root)), Some(&3)); + assert_eq!(view.signer_schemes.len(), 3); + assert!( + view.signer_schemes + .values() + .all(|scheme| scheme == "falcon") + ); + } + + #[test] + fn view_reads_each_signers_scheme_of_a_mixed_account() { + let falcon = SignatureScheme::Falcon.auth_scheme() as u64; + let ecdsa = SignatureScheme::Ecdsa.auth_scheme() as u64; + let view = account_view(&multisig_with_schemes(2, 2, 2, vec![], &[falcon, ecdsa])).unwrap(); + assert_eq!( + view.signer_schemes + .get(&view.signer_commitments[0]) + .map(String::as_str), + Some("falcon") + ); + assert_eq!( + view.signer_schemes + .get(&view.signer_commitments[1]) + .map(String::as_str), + Some("ecdsa") + ); + } + + #[test] + fn a_missing_or_unknown_approver_scheme_is_an_error_not_a_signer_without_one() { + let falcon = SignatureScheme::Falcon.auth_scheme() as u64; + assert!(account_view(&multisig_with_schemes(1, 2, 2, vec![], &[falcon])).is_err()); + assert!(account_view(&multisig_with_schemes(1, 2, 2, vec![], &[falcon, 99])).is_err()); + } + + #[test] + fn missing_approver_key_is_an_error_not_a_shorter_list() { + assert!(account_view(&multisig(1, 2, 1, vec![])).is_err()); + } + + #[test] + fn account_without_multisig_auth_is_single_key() { + let state = account(vec![StorageSlot::with_value( + miden_protocol::account::StorageSlotName::new("example::other::slot").unwrap(), + Word::default(), + )]); + let view = account_view(&state).unwrap(); + assert!(!view.commitment.is_empty()); + assert!(view.signer_commitments.is_empty()); + assert_eq!(view.default_threshold, None); + } + + #[test] + fn projection_decodes_every_delta_fixture() { + for fixture in [ + crate::testing::fixtures::DELTA_1_JSON, + crate::testing::fixtures::DELTA_2_JSON, + crate::testing::fixtures::DELTA_3_JSON, + ] { + let delta: serde_json::Value = serde_json::from_str(fixture).unwrap(); + let transaction = module_transaction(&delta["delta_payload"]).unwrap(); + let projection = transaction.projection; + assert!(projection.nonce_delta >= 0); + for change in &projection.storage_changes { + assert!(!change.slot_name.is_empty()); + assert_ne!(change.op, StorageOp::Unspecified as i32); + } + assert!(!transaction.raw_tx_summary.is_empty()); + let wrapped = serde_json::json!({ "tx_summary": delta["delta_payload"].clone() }); + assert!(module_transaction(&wrapped).is_err()); + } + } + + #[test] + fn an_embedded_tx_summary_key_cannot_replace_the_signed_summary() { + let signed: serde_json::Value = + serde_json::from_str(crate::testing::fixtures::DELTA_1_JSON).unwrap(); + let decoy: serde_json::Value = + serde_json::from_str(crate::testing::fixtures::DELTA_2_JSON).unwrap(); + let mut payload = signed["delta_payload"].clone(); + payload["tx_summary"] = decoy["delta_payload"].clone(); + assert_eq!( + module_transaction(&payload).unwrap(), + module_transaction(&signed["delta_payload"]).unwrap() + ); + } + + #[test] + fn expiration_overflow_is_an_error() { + assert_eq!(expiration_block(10, 5), Ok(15)); + assert!(expiration_block(u32::MAX, 1).is_err()); + } + + #[test] + #[ignore = "timing report for the prototype gates; run with --ignored --nocapture"] + fn view_and_projection_decode_cost() { + let state: serde_json::Value = + serde_json::from_str(crate::testing::fixtures::ACCOUNT_JSON).unwrap(); + let delta: serde_json::Value = + serde_json::from_str(crate::testing::fixtures::DELTA_1_JSON).unwrap(); + let runs = 200; + let started = std::time::Instant::now(); + for _ in 0..runs { + account_view(&state).unwrap(); + } + let view = started.elapsed() / runs; + let started = std::time::Instant::now(); + for _ in 0..runs { + module_transaction(&delta["delta_payload"]).unwrap(); + } + let projection = started.elapsed() / runs; + println!("account_view: {view:?} per call, tx_projection: {projection:?} per call"); + } +} diff --git a/crates/server/src/network/mod.rs b/crates/server/src/network/mod.rs index a05b4bfd..f0da34af 100644 --- a/crates/server/src/network/mod.rs +++ b/crates/server/src/network/mod.rs @@ -280,6 +280,14 @@ pub struct AuthBinding { pub guardian_scheme: Option, } +/// What a policy module receives about one transaction: the projection and the summary's +/// binary encoding, both decoded from the same bytes the Guardian signs. +#[derive(Debug, Clone, Default, PartialEq)] +pub struct ModuleTransaction { + pub projection: guardian_module_sdk::MidenTransaction, + pub raw_tx_summary: Vec, +} + #[async_trait] pub trait NetworkClient: Send + Sync { /// Commitment (hex) and nonce of the account encoded in `state_json`, @@ -476,6 +484,26 @@ pub trait NetworkClient: Send + Sync { Ok(None) } + /// The account's signers and thresholds as policy modules see them. Errors on auth state + /// this network cannot interpret; an empty view is never returned. + fn module_account_view( + &self, + state_json: &serde_json::Value, + ) -> Result { + let _ = state_json; + Err("policy modules are not supported on this network".into()) + } + + /// The decoded effects of a transaction as policy modules see them. `tx_summary` is the + /// bare summary the Guardian verifies and signs, never a proposal wrapper. + fn module_transaction( + &self, + tx_summary: &serde_json::Value, + ) -> Result { + let _ = tx_summary; + Err("policy modules are not supported on this network".into()) + } + /// Determine if account auth should be updated given the state async fn should_update_auth( &self, diff --git a/crates/server/src/services/account_status.rs b/crates/server/src/services/account_status.rs index 46669438..0f1ca3a8 100644 --- a/crates/server/src/services/account_status.rs +++ b/crates/server/src/services/account_status.rs @@ -127,6 +127,7 @@ mod tests { AppState { execution: Default::default(), miden_sessions: std::sync::Arc::new(crate::session::MidenSessions::default()), + modules: None, storage: Arc::new(storage), metadata: Arc::new(metadata), network_client: Arc::new(MockNetworkClient::new()), diff --git a/crates/server/src/services/configure_account.rs b/crates/server/src/services/configure_account.rs index a84d9849..d67d880a 100644 --- a/crates/server/src/services/configure_account.rs +++ b/crates/server/src/services/configure_account.rs @@ -747,6 +747,7 @@ mod tests { AppState { execution: Default::default(), + modules: None, miden_sessions: std::sync::Arc::new(crate::session::MidenSessions::default()), storage, metadata: Arc::new(metadata_store), diff --git a/crates/server/src/services/dashboard_account_delta_detail.rs b/crates/server/src/services/dashboard_account_delta_detail.rs index 596ec057..d4c0d05b 100644 --- a/crates/server/src/services/dashboard_account_delta_detail.rs +++ b/crates/server/src/services/dashboard_account_delta_detail.rs @@ -308,6 +308,7 @@ mod tests { AppState { execution: Default::default(), miden_sessions: std::sync::Arc::new(crate::session::MidenSessions::default()), + modules: None, storage: Arc::new(storage), metadata: Arc::new(metadata), network_client: Arc::new(MockNetworkClient::new()), @@ -500,6 +501,7 @@ mod tests { counterparty: None, note_counts: crate::delta_summary::NoteCounts::default(), proposal: None, + modules: None, }); let state = build_state(Ok(Some(falcon_metadata())), Ok(delta.clone())).await; let detail = @@ -619,6 +621,7 @@ mod tests { let state = AppState { execution: Default::default(), miden_sessions: std::sync::Arc::new(crate::session::MidenSessions::default()), + modules: None, storage: Arc::new(storage), metadata: Arc::new(metadata), network_client: Arc::new(MockNetworkClient::new()), diff --git a/crates/server/src/services/dashboard_account_deltas.rs b/crates/server/src/services/dashboard_account_deltas.rs index 49ee7d0d..78b59617 100644 --- a/crates/server/src/services/dashboard_account_deltas.rs +++ b/crates/server/src/services/dashboard_account_deltas.rs @@ -342,6 +342,7 @@ mod tests { proposal_type: "p2id".to_string(), ..ProposalMetadata::default() }), + modules: None, }); let entry = DashboardDeltaEntry::from_delta(&d).expect("canonical delta maps"); assert_eq!(entry.category, Some(DashboardDeltaCategory::AssetTransfer)); @@ -367,6 +368,7 @@ mod tests { proposal_type: "remove_signer".to_string(), ..ProposalMetadata::default() }), + modules: None, }); let entry = DashboardDeltaEntry::from_delta(&d).expect("canonical delta maps"); assert!(entry.note_counts.is_none()); @@ -424,6 +426,7 @@ mod tests { AppState { execution: Default::default(), miden_sessions: std::sync::Arc::new(crate::session::MidenSessions::default()), + modules: None, storage: Arc::new(storage), metadata: Arc::new(metadata_store), network_client: Arc::new(MockNetworkClient::new()), @@ -532,6 +535,7 @@ mod tests { let state = AppState { execution: Default::default(), miden_sessions: std::sync::Arc::new(crate::session::MidenSessions::default()), + modules: None, storage: Arc::new(storage), metadata: Arc::new(metadata), network_client: Arc::new(MockNetworkClient::new()), @@ -624,6 +628,7 @@ mod tests { let state = AppState { execution: Default::default(), miden_sessions: std::sync::Arc::new(crate::session::MidenSessions::default()), + modules: None, storage: Arc::new(svc), metadata: Arc::new(metadata), network_client: Arc::new(MockNetworkClient::new()), diff --git a/crates/server/src/services/dashboard_account_proposals.rs b/crates/server/src/services/dashboard_account_proposals.rs index e3ebf610..47fcf87d 100644 --- a/crates/server/src/services/dashboard_account_proposals.rs +++ b/crates/server/src/services/dashboard_account_proposals.rs @@ -321,6 +321,7 @@ mod tests { AppState { execution: Default::default(), miden_sessions: std::sync::Arc::new(crate::session::MidenSessions::default()), + modules: None, storage: Arc::new(storage), metadata: Arc::new(metadata_store), network_client: Arc::new(MockNetworkClient::new()), @@ -455,6 +456,7 @@ mod tests { let state = AppState { execution: Default::default(), miden_sessions: std::sync::Arc::new(crate::session::MidenSessions::default()), + modules: None, storage: Arc::new(storage), metadata: Arc::new(metadata), network_client: Arc::new(MockNetworkClient::new()), diff --git a/crates/server/src/services/dashboard_account_snapshot.rs b/crates/server/src/services/dashboard_account_snapshot.rs index 93d69d5a..99a63b49 100644 --- a/crates/server/src/services/dashboard_account_snapshot.rs +++ b/crates/server/src/services/dashboard_account_snapshot.rs @@ -183,6 +183,7 @@ mod tests { AppState { execution: Default::default(), miden_sessions: std::sync::Arc::new(crate::session::MidenSessions::default()), + modules: None, storage: Arc::new(mock_storage), metadata: Arc::new(mock_metadata), network_client: Arc::new(MockNetworkClient::new()), diff --git a/crates/server/src/services/dashboard_accounts.rs b/crates/server/src/services/dashboard_accounts.rs index a7871eba..27d13444 100644 --- a/crates/server/src/services/dashboard_accounts.rs +++ b/crates/server/src/services/dashboard_accounts.rs @@ -526,6 +526,7 @@ mod tests { let state = AppState { execution: Default::default(), miden_sessions: std::sync::Arc::new(crate::session::MidenSessions::default()), + modules: None, storage: Arc::new(svc), metadata: Arc::new(metadata), network_client: Arc::new(MockNetworkClient::new()), diff --git a/crates/server/src/services/dashboard_global_deltas.rs b/crates/server/src/services/dashboard_global_deltas.rs index edd34b07..709fb318 100644 --- a/crates/server/src/services/dashboard_global_deltas.rs +++ b/crates/server/src/services/dashboard_global_deltas.rs @@ -251,6 +251,7 @@ mod tests { AppState { execution: Default::default(), miden_sessions: std::sync::Arc::new(crate::session::MidenSessions::default()), + modules: None, storage: Arc::new(storage), metadata: Arc::new(metadata), network_client: Arc::new(MockNetworkClient::new()), @@ -359,6 +360,7 @@ mod tests { let state = AppState { execution: Default::default(), miden_sessions: std::sync::Arc::new(crate::session::MidenSessions::default()), + modules: None, storage: Arc::new(storage), metadata: Arc::new(metadata), network_client: Arc::new(MockNetworkClient::new()), @@ -412,6 +414,7 @@ mod tests { output: 1, }, proposal: None, + modules: None, }); let d = canonical_with_metadata("0xacc1", 1, metadata); let entry = entry_from(&d, "0xacc1").expect("canonical delta maps"); diff --git a/crates/server/src/services/dashboard_global_proposals.rs b/crates/server/src/services/dashboard_global_proposals.rs index 9c4ec28e..ef3e0e03 100644 --- a/crates/server/src/services/dashboard_global_proposals.rs +++ b/crates/server/src/services/dashboard_global_proposals.rs @@ -281,6 +281,7 @@ mod tests { AppState { execution: Default::default(), miden_sessions: std::sync::Arc::new(crate::session::MidenSessions::default()), + modules: None, storage: Arc::new(storage), metadata: Arc::new(metadata), network_client: Arc::new(MockNetworkClient::new()), @@ -327,6 +328,7 @@ mod tests { let state = AppState { execution: Default::default(), miden_sessions: std::sync::Arc::new(crate::session::MidenSessions::default()), + modules: None, storage: Arc::new(storage), metadata: Arc::new(metadata), network_client: Arc::new(MockNetworkClient::new()), diff --git a/crates/server/src/services/dashboard_info.rs b/crates/server/src/services/dashboard_info.rs index f83459fe..2c644fca 100644 --- a/crates/server/src/services/dashboard_info.rs +++ b/crates/server/src/services/dashboard_info.rs @@ -406,6 +406,7 @@ mod tests { AppState { execution: Default::default(), miden_sessions: std::sync::Arc::new(crate::session::MidenSessions::default()), + modules: None, storage: Arc::new(storage), metadata: Arc::new(metadata_store), network_client: Arc::new(MockNetworkClient::new()), @@ -478,6 +479,7 @@ mod tests { let state = AppState { execution: Default::default(), miden_sessions: std::sync::Arc::new(crate::session::MidenSessions::default()), + modules: None, storage: Arc::new(MockStorageBackend::new()), metadata: Arc::new( MockMetadataStore::new().with_list(Err("metadata store unreachable".into())), diff --git a/crates/server/src/services/dashboard_stats.rs b/crates/server/src/services/dashboard_stats.rs index cc9a8203..6490fbe9 100644 --- a/crates/server/src/services/dashboard_stats.rs +++ b/crates/server/src/services/dashboard_stats.rs @@ -365,6 +365,7 @@ mod tests { AppState { execution: Default::default(), miden_sessions: std::sync::Arc::new(crate::session::MidenSessions::default()), + modules: None, storage: Arc::new(MockStorageBackend::new()), metadata: Arc::new(MockMetadataStore::new()), network_client: Arc::new(MockNetworkClient::new()), diff --git a/crates/server/src/services/get_delta_history.rs b/crates/server/src/services/get_delta_history.rs index 145336df..d46bb207 100644 --- a/crates/server/src/services/get_delta_history.rs +++ b/crates/server/src/services/get_delta_history.rs @@ -259,6 +259,7 @@ mod tests { let state = AppState { execution: Default::default(), miden_sessions: std::sync::Arc::new(crate::session::MidenSessions::default()), + modules: None, storage: Arc::new(MockStorageBackend::new()), metadata: Arc::new(MockMetadataStore::new()), network_client: Arc::new(MockNetworkClient::new()), diff --git a/crates/server/src/services/mod.rs b/crates/server/src/services/mod.rs index 22f735a4..5bfd22c2 100644 --- a/crates/server/src/services/mod.rs +++ b/crates/server/src/services/mod.rs @@ -697,6 +697,7 @@ mod tests { AppState { execution: Default::default(), + modules: None, miden_sessions: std::sync::Arc::new(crate::session::MidenSessions::default()), storage: Arc::new(storage), metadata: Arc::new(metadata), diff --git a/crates/server/src/services/release_on_switch.rs b/crates/server/src/services/release_on_switch.rs index 54c4332f..02fc4b71 100644 --- a/crates/server/src/services/release_on_switch.rs +++ b/crates/server/src/services/release_on_switch.rs @@ -407,6 +407,7 @@ mod tests { AppState { execution: Default::default(), miden_sessions: std::sync::Arc::new(crate::session::MidenSessions::default()), + modules: None, storage: Arc::new(storage), metadata: Arc::new(metadata), network_client: Arc::new(network), diff --git a/crates/server/src/testing/helpers.rs b/crates/server/src/testing/helpers.rs index 13a2f489..3ef0e7e7 100644 --- a/crates/server/src/testing/helpers.rs +++ b/crates/server/src/testing/helpers.rs @@ -374,6 +374,7 @@ pub async fn create_test_app_state() -> AppState { AppState { execution: Default::default(), miden_sessions: std::sync::Arc::new(crate::session::MidenSessions::default()), + modules: None, storage: storage_backend, metadata: Arc::new(metadata), network_client: Arc::new(mock_client), @@ -1115,6 +1116,7 @@ pub fn create_test_app_state_with_mocks( AppState { execution: Default::default(), miden_sessions: std::sync::Arc::new(crate::session::MidenSessions::default()), + modules: None, storage: storage_backend, metadata, network_client, diff --git a/crates/server/src/testing/mocks.rs b/crates/server/src/testing/mocks.rs index 4e1bd963..67d05b78 100644 --- a/crates/server/src/testing/mocks.rs +++ b/crates/server/src/testing/mocks.rs @@ -51,6 +51,8 @@ pub struct MockNetworkClient { /// `(account_id, final_state_commitment, from_block)` per search. pub find_transaction_ending_at_calls: Arc>>, pub account_nonce_responses: Arc>>, + pub module_account_view: Arc>>, + pub module_projection: Arc>>, /// The block every observed commitment reports it was read at. pub observed_block: Arc>, /// How long every observed commitment takes to answer. @@ -91,6 +93,17 @@ impl MockNetworkClient { self } + /// Every state decodes to `view` and every delta to `projection`. + pub fn with_module_views( + self, + view: guardian_module_sdk::AccountView, + projection: guardian_module_sdk::MidenTransaction, + ) -> Self { + *self.module_account_view.lock().unwrap() = Some(view); + *self.module_projection.lock().unwrap() = Some(projection); + self + } + pub fn with_validate_first_state(self, response: StdResult<(), String>) -> Self { self.validate_first_state_responses .lock() @@ -227,6 +240,33 @@ impl MockNetworkClient { #[async_trait] impl NetworkClient for MockNetworkClient { + fn module_account_view( + &self, + _state_json: &serde_json::Value, + ) -> StdResult { + self.module_account_view + .lock() + .unwrap() + .clone() + .ok_or_else(|| "no module account view configured".to_string()) + } + + fn module_transaction( + &self, + tx_summary: &serde_json::Value, + ) -> StdResult { + let projection = self + .module_projection + .lock() + .unwrap() + .clone() + .ok_or_else(|| "no module projection configured".to_string())?; + Ok(crate::network::ModuleTransaction { + projection, + raw_tx_summary: serde_json::to_vec(tx_summary).map_err(|e| e.to_string())?, + }) + } + fn get_state_head( &self, account_id: &str, diff --git a/docs/guides/policy-modules/built-in.toml b/docs/guides/policy-modules/built-in.toml new file mode 100644 index 00000000..4e97af45 --- /dev/null +++ b/docs/guides/policy-modules/built-in.toml @@ -0,0 +1,48 @@ +# Built-in modules: basic-policy runs inside the Guardian process. +# Copy to .guardian/built-in.toml and replace the placeholders. +# `params` seed the global params on first start; change them later through the operator API. + +# Spending cap for every account: at most 5 base units of one asset per transaction. +[[module]] +id = "caps" +kind = "basic-policy" +scope = "all" +hooks = ["before_proposal_created", "before_transaction_approved"] +timeout_ms = 50 +on_error = "deny" +operator_can_disable = true +disclosure = "params" +description = "At most 5 base units of one asset per transaction" +params = { max_amount_per_tx = { "0xREPLACE_WITH_FAUCET_ID" = "5" } } + +# Recipient blocklist for every account; extend it globally or per account at runtime. +# Generic denials: clients learn that a policy refused, not which list or why. +[[module]] +id = "blocklist" +kind = "basic-policy" +scope = "all" +hooks = ["before_proposal_created", "before_transaction_approved"] +timeout_ms = 50 +on_error = "deny" +operator_can_disable = true +client_reason = "generic" +params = { recipient_denylist = [] } + +# Signer rule: no account may add this signer. Protected: operators cannot disable it. +[[module]] +id = "signers" +kind = "basic-policy" +scope = "all" +hooks = ["before_account_registered", "before_proposal_created", "before_transaction_approved"] +timeout_ms = 50 +on_error = "deny" +params = { signer_check = "added", signer_denylist = ["0xdededededededededededededededededededededededededededededededede"] } + +# Opt-in module: applies only to accounts an operator assigns it to, with their own params. +[[module]] +id = "treasury-allowlist" +kind = "basic-policy" +scope = "assigned" +hooks = ["before_proposal_created", "before_transaction_approved"] +timeout_ms = 50 +on_error = "deny" diff --git a/docs/guides/policy-modules/custom-in-process.toml b/docs/guides/policy-modules/custom-in-process.toml new file mode 100644 index 00000000..7328d2c6 --- /dev/null +++ b/docs/guides/policy-modules/custom-in-process.toml @@ -0,0 +1,14 @@ +# Custom module compiled into the server: `note-policy` runs in the Guardian process. +# Start the server with the custom_module_server example (see custom.md), not the +# stock binary, which does not know the `note-policy` kind and would refuse to start. +# Copy to .guardian/custom-in-process.toml. + +[[module]] +id = "note-policy" +kind = "note-policy" +scope = "all" +hooks = ["before_proposal_created", "before_transaction_approved"] +timeout_ms = 50 +on_error = "deny" +operator_can_disable = true +params = { max_payment_notes = 1, deny_private_notes = true } diff --git a/docs/guides/policy-modules/custom.toml b/docs/guides/policy-modules/custom.toml new file mode 100644 index 00000000..82ee9d1b --- /dev/null +++ b/docs/guides/policy-modules/custom.toml @@ -0,0 +1,15 @@ +# Custom module: note-policy, written against guardian-module-sdk and served over gRPC. +# Copy to .guardian/custom.toml, put the bearer token in .guardian/note-policy.token, +# and start the module before the Guardian (see custom.md). + +[[module]] +id = "note-policy" +kind = "grpc" +endpoint = "grpc+insecure://127.0.0.1:7444" +scope = "all" +hooks = ["before_proposal_created", "before_transaction_approved"] +timeout_ms = 200 +on_error = "deny" +operator_can_disable = true +auth = { token_file = "note-policy.token" } +params = { max_payment_notes = 1, deny_private_notes = true } diff --git a/docs/guides/policy-modules/remote.toml b/docs/guides/policy-modules/remote.toml new file mode 100644 index 00000000..9cbd12f0 --- /dev/null +++ b/docs/guides/policy-modules/remote.toml @@ -0,0 +1,26 @@ +# Remote module: the same basic-policy served by a separate process over gRPC. +# Copy to .guardian/remote.toml, put the bearer token in .guardian/caps.token, +# and start the module before the Guardian (see remote.md). + +[[module]] +id = "caps" +kind = "basic-policy" +scope = "all" +hooks = ["before_proposal_created", "before_transaction_approved"] +timeout_ms = 50 +on_error = "deny" +operator_can_disable = true +params = { max_amount_per_tx = { "0xREPLACE_WITH_FAUCET_ID" = "5" } } + +# A tighter cap (3) than the in-process one (5), so refusals show which module decided. +[[module]] +id = "caps-remote" +kind = "grpc" +endpoint = "grpc+insecure://127.0.0.1:7443" +scope = "all" +hooks = ["before_proposal_created", "before_transaction_approved"] +timeout_ms = 200 +on_error = "deny" +operator_can_disable = true +auth = { token_file = "caps.token" } +params = { max_amount_per_tx = { "0xREPLACE_WITH_FAUCET_ID" = "3" } } diff --git a/docs/openapi-client.json b/docs/openapi-client.json index 8a86840b..975884db 100644 --- a/docs/openapi-client.json +++ b/docs/openapi-client.json @@ -2664,6 +2664,17 @@ } ] }, + "modules": { + "oneOf": [ + { + "type": "null" + }, + { + "$ref": "#/components/schemas/ModuleApproval", + "description": "The policy module configuration that approved this delta. Absent when no module ran." + } + ] + }, "note_counts": { "$ref": "#/components/schemas/NoteCounts" }, @@ -3080,6 +3091,26 @@ "canonicalization_disabled" ] }, + "FailedOpen": { + "type": "object", + "required": [ + "module_id", + "layer", + "failure" + ], + "properties": { + "failure": { + "type": "string", + "description": "`timeout`, `error`, `invalid_decision` or `request_unavailable`; the detail is logged." + }, + "layer": { + "type": "string" + }, + "module_id": { + "type": "string" + } + } + }, "HistoryEntry": { "type": "object", "description": "One canonical transaction in the history feed wire shape.\n`account_id` is omitted — the authenticated query scopes it.", @@ -3192,6 +3223,31 @@ "mainnet" ] }, + "ModuleApproval": { + "type": "object", + "description": "What the policy modules ran with. Allowed evaluations are not listed: the catalog, params\nversion and account determine which modules ran, so only failures let through by\n`on_error = allow` are kept.", + "required": [ + "catalog_hash", + "params_version" + ], + "properties": { + "catalog_hash": { + "type": "string", + "description": "SHA-256 of the catalog file the approving replica loaded." + }, + "failed_open": { + "type": "array", + "items": { + "$ref": "#/components/schemas/FailedOpen" + } + }, + "params_version": { + "type": "integer", + "format": "int64", + "minimum": 0 + } + } + }, "NetworkConfig": { "oneOf": [ { diff --git a/docs/openapi.json b/docs/openapi.json index 707b535d..f659036e 100644 --- a/docs/openapi.json +++ b/docs/openapi.json @@ -6438,6 +6438,17 @@ } ] }, + "modules": { + "oneOf": [ + { + "type": "null" + }, + { + "$ref": "#/components/schemas/ModuleApproval", + "description": "The policy module configuration that approved this delta. Absent when no module ran." + } + ] + }, "note_counts": { "$ref": "#/components/schemas/NoteCounts" }, @@ -6981,6 +6992,26 @@ "canonicalization_disabled" ] }, + "FailedOpen": { + "type": "object", + "required": [ + "module_id", + "layer", + "failure" + ], + "properties": { + "failure": { + "type": "string", + "description": "`timeout`, `error`, `invalid_decision` or `request_unavailable`; the detail is logged." + }, + "layer": { + "type": "string" + }, + "module_id": { + "type": "string" + } + } + }, "HistoryEntry": { "type": "object", "description": "One canonical transaction in the history feed wire shape.\n`account_id` is omitted — the authenticated query scopes it.", @@ -7129,6 +7160,31 @@ "mainnet" ] }, + "ModuleApproval": { + "type": "object", + "description": "What the policy modules ran with. Allowed evaluations are not listed: the catalog, params\nversion and account determine which modules ran, so only failures let through by\n`on_error = allow` are kept.", + "required": [ + "catalog_hash", + "params_version" + ], + "properties": { + "catalog_hash": { + "type": "string", + "description": "SHA-256 of the catalog file the approving replica loaded." + }, + "failed_open": { + "type": "array", + "items": { + "$ref": "#/components/schemas/FailedOpen" + } + }, + "params_version": { + "type": "integer", + "format": "int64", + "minimum": 0 + } + } + }, "NetworkConfig": { "oneOf": [ { diff --git a/packages/guardian-client/src/error-codes.ts b/packages/guardian-client/src/error-codes.ts index 2ade17db..887d4546 100644 --- a/packages/guardian-client/src/error-codes.ts +++ b/packages/guardian-client/src/error-codes.ts @@ -39,6 +39,10 @@ export const GUARDIAN_ERROR_CODES = [ 'invalid_proposal_signature', 'invalid_status_filter', 'invalid_timestamp', + 'module_denied', + 'module_not_disableable', + 'module_not_found', + 'module_unavailable', 'network_error', 'pending_proposals_limit', 'proposal_already_signed', @@ -83,6 +87,10 @@ const WIRE_ALIASES: Readonly> = { GUARDIAN_ACCOUNT_RELEASED: 'account_released', GUARDIAN_INSUFFICIENT_OPERATOR_PERMISSION: 'insufficient_operator_permission', GUARDIAN_CANDIDATE_LANDED: 'candidate_landed', + GUARDIAN_MODULE_DENIED: 'module_denied', + GUARDIAN_MODULE_UNAVAILABLE: 'module_unavailable', + GUARDIAN_MODULE_NOT_FOUND: 'module_not_found', + GUARDIAN_MODULE_NOT_DISABLEABLE: 'module_not_disableable', GUARDIAN_PROVING_UNAVAILABLE: 'proving_unavailable', GUARDIAN_PROPOSAL_MISSING_TRANSACTION_REQUEST: 'proposal_missing_transaction_request', GUARDIAN_PROPOSAL_EXECUTES_LOCALLY: 'proposal_executes_locally', From 9f4bea157932f34e7d3c3342028613bec4f46324 Mon Sep 17 00:00:00 2001 From: Zeljko Date: Mon, 9 Nov 2026 09:01:55 +0100 Subject: [PATCH 003/105] feat(server): policy module gate hooks (#251) before_transaction_approved runs in ack_delta_internal::acknowledge_applied, shared by push_delta and the execution worker; before_proposal_created in push_delta_proposal, with the dry-run check (POST /delta/proposal/check) and the policy summary (GET /policies) on both transports; before_account_registered in configure_account, ahead of the account claim. Approvals are recorded on the signed delta's metadata. A refused Guardian execution ends with GUARDIAN_EXECUTION_MODULE_DENIED or GUARDIAN_EXECUTION_MODULE_UNAVAILABLE in guardian-shared and the TypeScript execution vocabulary; ExecutionFailureCode is no longer Copy. Carried from the prototype (#554). --- .../src/client/guardian_execution.rs | 8 +- .../src/scenario/account.rs | 3 +- crates/server/bench/loadgen/src/config.rs | 2 + crates/server/bench/loadgen/src/scenarios.rs | 9 +- crates/server/examples/bench_server.rs | 60 ++++ crates/server/proto/guardian.proto | 45 +++ crates/server/src/api/grpc.rs | 57 ++++ crates/server/src/api/http.rs | 91 ++++++ crates/server/src/builder/handle.rs | 10 +- .../src/jobs/execution_reconcile/mod.rs | 11 +- crates/server/src/metrics/names.rs | 2 + crates/server/src/openapi.rs | 2 + .../server/src/services/ack_delta_internal.rs | 109 ++++++- .../server/src/services/configure_account.rs | 199 +++++++++++- .../execute_proposal/fault_injection_tests.rs | 4 +- .../src/services/execute_proposal/service.rs | 1 + .../src/services/execute_proposal/tests.rs | 131 ++++++++ .../src/services/execute_proposal/worker.rs | 70 ++++- crates/server/src/services/get_policies.rs | 42 +++ crates/server/src/services/mod.rs | 7 +- crates/server/src/services/push_delta.rs | 225 +++++++++++++- .../src/services/push_delta_proposal.rs | 288 +++++++++++++++++- .../storage/execution_reservation_tests.rs | 4 +- crates/server/src/storage/filesystem.rs | 56 ++++ crates/shared/src/execution.rs | 82 ++++- docs/openapi-client.json | 274 +++++++++++++++++ docs/openapi.json | 274 +++++++++++++++++ .../multisig-browser/src/multisigApi.ts | 4 + .../demo/src/actions/proposal_management.rs | 10 +- .../guardian-client/src/execution.test.ts | 35 +++ packages/guardian-client/src/execution.ts | 42 +++ 31 files changed, 2105 insertions(+), 52 deletions(-) create mode 100644 crates/server/examples/bench_server.rs create mode 100644 crates/server/src/services/get_policies.rs diff --git a/crates/miden-multisig-client/src/client/guardian_execution.rs b/crates/miden-multisig-client/src/client/guardian_execution.rs index 5a40e385..be70d84a 100644 --- a/crates/miden-multisig-client/src/client/guardian_execution.rs +++ b/crates/miden-multisig-client/src/client/guardian_execution.rs @@ -556,7 +556,7 @@ mod tests { /// One scripted status read: an answer after `takes`, or one that never answers. enum Step { - Answer { takes: Duration, read: Read }, + Answer { takes: Duration, read: Box }, Stall, } @@ -564,7 +564,7 @@ mod tests { fn from(read: Read) -> Self { Step::Answer { takes: Duration::ZERO, - read, + read: Box::new(read), } } } @@ -586,7 +586,7 @@ mod tests { { Step::Answer { takes, read } => { *self.runtime.now.lock().unwrap() += takes; - read + *read } Step::Stall => std::future::pending().await, } @@ -804,7 +804,7 @@ mod tests { Ok(execution(ExecutionState::Submitted)).into(), Step::Answer { takes: Duration::from_secs(10), - read: Ok(execution(ExecutionState::Committed)), + read: Box::new(Ok(execution(ExecutionState::Committed))), }, ], ) diff --git a/crates/qualification-driver/src/scenario/account.rs b/crates/qualification-driver/src/scenario/account.rs index 005731bc..77cafe71 100644 --- a/crates/qualification-driver/src/scenario/account.rs +++ b/crates/qualification-driver/src/scenario/account.rs @@ -912,7 +912,8 @@ async fn execute_until_pre_boundary_failure( } tokio::time::sleep(std::time::Duration::from_millis(250)).await; }; - if settled.error.as_ref().map(|error| error.code) != Some(ExecutionFailureCode::NodeUnavailable) + if settled.error.as_ref().map(|error| &error.code) + != Some(&ExecutionFailureCode::NodeUnavailable) { return Err(ActionOutcome::failed_product(format!( "{label}: expected `GUARDIAN_EXECUTION_NODE_UNAVAILABLE`: {settled:?}" diff --git a/crates/server/bench/loadgen/src/config.rs b/crates/server/bench/loadgen/src/config.rs index 458c0f97..d98d9d38 100644 --- a/crates/server/bench/loadgen/src/config.rs +++ b/crates/server/bench/loadgen/src/config.rs @@ -9,6 +9,8 @@ pub enum Scenario { StateWrite, Mixed, StateSync, + /// Only `push_delta`, one chained delta per operation; isolates the push path. + StatePush, Canonicalization, } diff --git a/crates/server/bench/loadgen/src/scenarios.rs b/crates/server/bench/loadgen/src/scenarios.rs index 613aca5a..73e17bc7 100644 --- a/crates/server/bench/loadgen/src/scenarios.rs +++ b/crates/server/bench/loadgen/src/scenarios.rs @@ -549,6 +549,7 @@ async fn run_worker(config: &RunConfig, user: &mut UserContext) -> WorkerMetrics run_read_operation(user, op_index, account_count).await } } + Scenario::StatePush => run_push_state_operation(user, op_index, account_count).await, Scenario::Canonicalization => { run_canonicalization_operation(config, user, op_index, account_count).await } @@ -582,9 +583,11 @@ async fn run_worker(config: &RunConfig, user: &mut UserContext) -> WorkerMetrics fn scenario_op_count(config: &RunConfig, account_count: usize) -> usize { match config.scenario { Scenario::Canonicalization => account_count, - Scenario::StateRead | Scenario::StateWrite | Scenario::Mixed | Scenario::StateSync => { - usize::try_from(config.ops_per_user).unwrap_or(0) - } + Scenario::StateRead + | Scenario::StateWrite + | Scenario::Mixed + | Scenario::StateSync + | Scenario::StatePush => usize::try_from(config.ops_per_user).unwrap_or(0), } } diff --git a/crates/server/examples/bench_server.rs b/crates/server/examples/bench_server.rs new file mode 100644 index 00000000..55137232 --- /dev/null +++ b/crates/server/examples/bench_server.rs @@ -0,0 +1,60 @@ +//! The server as `main` builds it, on configurable ports and without canonicalization, so pushes +//! commit optimistically and never wait on a node. For benchmarks next to a running server. +//! +//! ```text +//! BENCH_HTTP_PORT=3100 BENCH_GRPC_PORT=50151 cargo run --release -p guardian-server --example bench_server +//! ``` + +use server::ack::AckRegistry; +use server::builder::{ServerBuilder, storage::StorageMetadataBuilder}; +use server::logging::LoggingConfig; +use server::middleware::{BodyLimitConfig, CorsConfig, RateLimitConfig}; +use server::network::{NetworkType, RpcSettings}; + +fn port(var: &str, default: u16) -> u16 { + std::env::var(var) + .ok() + .and_then(|value| value.parse().ok()) + .unwrap_or(default) +} + +#[tokio::main] +async fn main() { + let keystore_path: std::path::PathBuf = std::env::var("GUARDIAN_KEYSTORE_PATH") + .expect("GUARDIAN_KEYSTORE_PATH is required") + .into(); + let (storage_backend, metadata, auditor, coordination) = StorageMetadataBuilder::from_env() + .build() + .await + .expect("Failed to initialize storage backends"); + let ack = AckRegistry::new(keystore_path) + .await + .expect("Failed to initialize ack registry"); + let network_type = + NetworkType::from_env("GUARDIAN_NETWORK_TYPE").expect("Failed to resolve network type"); + + ServerBuilder::new() + .with_logging(LoggingConfig::default()) + .network(network_type) + .with_rpc(RpcSettings::from_env(network_type).expect("Invalid RPC configuration")) + .with_canonicalization(None) + .with_rate_limit(RateLimitConfig::from_env()) + .with_body_limit(BodyLimitConfig::from_env()) + .storage(storage_backend) + .metadata(metadata) + .auditor(auditor) + .coordination(coordination) + .ack(ack) + .http(true, port("BENCH_HTTP_PORT", 3100)) + .grpc(true, port("BENCH_GRPC_PORT", 50151)) + .cors( + CorsConfig::from_env() + .expect("Failed to initialize CORS config") + .layer(), + ) + .build() + .await + .expect("Failed to build server") + .run() + .await; +} diff --git a/crates/server/proto/guardian.proto b/crates/server/proto/guardian.proto index d540d17e..e22c050d 100644 --- a/crates/server/proto/guardian.proto +++ b/crates/server/proto/guardian.proto @@ -80,6 +80,17 @@ service Guardian { // x-timestamp), raw or as EIP-712 typed data (`x-auth-format: eip712`). // Wallet-only. Mirror of HTTP POST /session/revoke-all. rpc RevokeAllSessions(RevokeAllSessionsRequest) returns (RevokeAllSessionsResponse); + + // The policy modules that apply to the account, as far as each instance's + // catalog entry discloses them (RFC 0002 section 2.7). Mirror of HTTP + // GET /policies. + rpc GetPolicies(GetPoliciesRequest) returns (GetPoliciesResponse); + + // Dry run of PushDeltaProposal: the same checks and proposal-creation + // modules, nothing stored, no proposal slot taken. Advisory; approval still + // decides. Rate limited per account and signer. Mirror of HTTP + // POST /delta/proposal/check. + rpc CheckDeltaProposal(CheckDeltaProposalRequest) returns (CheckDeltaProposalResponse); } // Auth configuration - one of the auth types @@ -324,6 +335,40 @@ message PushDeltaProposalResponse { string error_code = 5; } +message CheckDeltaProposalRequest { + string account_id = 1; + uint64 nonce = 2; + string delta_payload = 3; // JSON string, as for PushDeltaProposal +} + +message CheckDeltaProposalResponse { + bool success = 1; + string message = 2; + bool allowed = 3; // true on success; a refusal is returned as an error status + bool complete = 4; // false when an instance that opts out of dry runs was skipped + string error_code = 5; +} + +message GetPoliciesRequest { + string account_id = 1; +} + +message PolicyEntry { + string module_id = 1; + repeated string hooks = 2; + string description = 3; + optional string params = 4; // JSON object; only where the instance discloses params + optional string account_layer = 5; // JSON object; this account's layer, where disclosed +} + +message GetPoliciesResponse { + bool success = 1; + string message = 2; + string account_id = 3; + repeated PolicyEntry policies = 4; // evaluation order + string error_code = 5; +} + // Get delta proposals request message GetDeltaProposalsRequest { string account_id = 1; diff --git a/crates/server/src/api/grpc.rs b/crates/server/src/api/grpc.rs index 392b7b03..bcea6f8c 100644 --- a/crates/server/src/api/grpc.rs +++ b/crates/server/src/api/grpc.rs @@ -307,6 +307,63 @@ impl Guardian for GuardianService { } } + async fn check_delta_proposal( + &self, + request: Request, + ) -> Result, Status> { + let credentials = authenticated_request(&request)?; + let data = request.into_inner(); + let params = services::PushDeltaProposalParams { + account_id: data.account_id, + nonce: data.nonce, + delta_payload: serde_json::from_str(&data.delta_payload) + .map_err(|e| Status::invalid_argument(format!("Invalid delta payload: {e}")))?, + credentials, + }; + match services::check_proposal(&self.app_state, params).await { + Ok(result) => Ok(Response::new(CheckDeltaProposalResponse { + success: true, + message: "Proposal creation would pass".to_string(), + allowed: true, + complete: result.complete, + error_code: String::new(), + })), + Err(e) => Err(Status::from(e)), + } + } + + async fn get_policies( + &self, + request: Request, + ) -> Result, Status> { + let credentials = authenticated_request(&request)?; + let data = request.into_inner(); + let params = services::GetPoliciesParams { + account_id: data.account_id, + credentials, + }; + match services::get_policies(&self.app_state, params).await { + Ok(result) => Ok(Response::new(GetPoliciesResponse { + success: true, + message: "Policies retrieved successfully".to_string(), + account_id: result.account_id, + policies: result + .policies + .into_iter() + .map(|policy| PolicyEntry { + module_id: policy.module_id, + hooks: policy.hooks, + description: policy.description, + params: policy.params.map(|params| params.to_string()), + account_layer: policy.account_layer.map(|layer| layer.to_string()), + }) + .collect(), + error_code: String::new(), + })), + Err(e) => Err(Status::from(e)), + } + } + async fn get_delta_proposals( &self, request: Request, diff --git a/crates/server/src/api/http.rs b/crates/server/src/api/http.rs index 3069b2f8..e316c5dd 100644 --- a/crates/server/src/api/http.rs +++ b/crates/server/src/api/http.rs @@ -654,6 +654,20 @@ pub struct DeltaProposalResponse { pub commitment: String, } +#[derive(Deserialize, Serialize, utoipa::ToSchema)] +pub struct CheckProposalResponse { + /// Always true: a refusal is returned as an error. + pub allowed: bool, + /// False when a module that opts out of dry runs was skipped. + pub complete: bool, +} + +#[derive(Deserialize, Serialize, utoipa::ToSchema)] +pub struct PoliciesResponse { + pub account_id: String, + pub policies: Vec, +} + #[derive(Deserialize, Serialize, utoipa::ToSchema, utoipa::IntoParams)] #[into_params(parameter_in = Query)] pub struct PubkeyQuery { @@ -773,6 +787,83 @@ pub async fn push_delta_proposal( })) } +/// Dry run of `POST /delta/proposal`: the same checks and proposal-creation +/// policy modules, without storing a proposal or taking a slot. A refusal is +/// the same error proposal creation returns; `complete` is false when a module +/// that opts out of dry runs was skipped. Advisory: approval still decides. +/// Rate limited per account and signer (`GUARDIAN_MODULE_CHECK_RATE_PER_MIN`). +#[utoipa::path( + post, + path = "/delta/proposal/check", + tag = "client", + security(("x-pubkey" = [], "x-signature" = [], "x-timestamp" = [])), + params(("x-auth-format" = Option, Header, description = "Optional ECDSA request format: eip712; omitted for raw signatures")), + request_body = DeltaProposalRequest, + responses( + (status = 200, description = "Proposal creation would pass", body = CheckProposalResponse), + (status = 400, description = "Invalid proposal payload", body = crate::openapi::ApiErrorResponse), + (status = 401, description = "Authentication failed or replay rejected", body = crate::openapi::ApiErrorResponse), + (status = 403, description = "A policy module refused (GUARDIAN_MODULE_DENIED)", body = crate::openapi::ApiErrorResponse), + (status = 409, description = "Conflicting / too many pending proposals", body = crate::openapi::ApiErrorResponse), + (status = 429, description = "Too many checks for this account and signer", body = crate::openapi::ApiErrorResponse), + (status = 503, description = "A policy module is unavailable (GUARDIAN_MODULE_UNAVAILABLE)", body = crate::openapi::ApiErrorResponse), + ) +)] +pub async fn check_delta_proposal( + State(state): State, + AuthHeader(credentials): AuthHeader, + Json(payload): Json, +) -> Result, GuardianError> { + let request_payload = + request_payload_from_serializable(&payload).map_err(GuardianError::InvalidInput)?; + let params = PushDeltaProposalParams { + account_id: payload.account_id, + nonce: payload.nonce, + delta_payload: payload.delta_payload, + credentials: request_payload.apply_to(credentials), + }; + let result = services::check_proposal(&state, params).await?; + Ok(Json(CheckProposalResponse { + allowed: true, + complete: result.complete, + })) +} + +/// The policy modules that apply to the account, as far as each module's +/// catalog entry discloses them (RFC 0002 section 2.7), in evaluation order. +/// Empty when the Guardian has no modules or discloses none. +#[utoipa::path( + get, + path = "/policies", + tag = "client", + security(("x-pubkey" = [], "x-signature" = [], "x-timestamp" = [])), + params(StateQuery, ("x-auth-format" = Option, Header, description = "Optional ECDSA request format: eip712; omitted for raw signatures")), + responses( + (status = 200, description = "Disclosed policies", body = PoliciesResponse), + (status = 401, description = "Authentication failed or replay rejected", body = crate::openapi::ApiErrorResponse), + ) +)] +pub async fn get_policies( + State(state): State, + AuthHeader(credentials): AuthHeader, + Query(query): Query, +) -> Result, GuardianError> { + let request_payload = + request_payload_from_serializable(&query).map_err(GuardianError::InvalidInput)?; + let result = services::get_policies( + &state, + services::GetPoliciesParams { + account_id: query.account_id, + credentials: request_payload.apply_to(credentials), + }, + ) + .await?; + Ok(Json(PoliciesResponse { + account_id: result.account_id, + policies: result.policies, + })) +} + /// Request abandonment of a pending canonicalization candidate whose /// transaction will never land on-chain (issue #319). /// diff --git a/crates/server/src/builder/handle.rs b/crates/server/src/builder/handle.rs index 521303d7..d08f9667 100644 --- a/crates/server/src/builder/handle.rs +++ b/crates/server/src/builder/handle.rs @@ -25,10 +25,10 @@ use crate::api::grpc::GuardianService; use crate::api::grpc::guardian::FILE_DESCRIPTOR_SET; use crate::api::grpc::guardian::guardian_server::GuardianServer; use crate::api::http::{ - abandon_candidate, configure, create_session, execute_delta_proposal, get_canonical_nonce, - get_current_execution, get_delta, get_delta_history, get_delta_proposal, - get_delta_proposal_execution, get_delta_proposals, get_delta_since, get_pubkey, get_state, - lookup, push_delta, push_delta_proposal, revoke_all_sessions, revoke_session, + abandon_candidate, check_delta_proposal, configure, create_session, execute_delta_proposal, + get_canonical_nonce, get_current_execution, get_delta, get_delta_history, get_delta_proposal, + get_delta_proposal_execution, get_delta_proposals, get_delta_since, get_policies, get_pubkey, + get_state, lookup, push_delta, push_delta_proposal, revoke_all_sessions, revoke_session, sign_delta_proposal, status, status_root, }; use crate::builder::startup::StartupInfo; @@ -560,6 +560,8 @@ pub(crate) fn build_http_router(state: AppState, config: HttpRouterConfig) -> Ro .route("/delta/proposal", post(push_delta_proposal)) .route("/delta/proposal", get(get_delta_proposals)) .route("/delta/proposal/single", get(get_delta_proposal)) + .route("/delta/proposal/check", post(check_delta_proposal)) + .route("/policies", get(get_policies)) .route("/delta/proposal", put(sign_delta_proposal)) .route("/delta/candidate/abandon", post(abandon_candidate)) .route("/delta/proposal/execution", post(execute_delta_proposal)) diff --git a/crates/server/src/jobs/execution_reconcile/mod.rs b/crates/server/src/jobs/execution_reconcile/mod.rs index 6bee4c0d..7644ec7e 100644 --- a/crates/server/src/jobs/execution_reconcile/mod.rs +++ b/crates/server/src/jobs/execution_reconcile/mod.rs @@ -23,7 +23,7 @@ pub enum PassKind { } /// What one pass did with one execution. -#[derive(Debug, Clone, Copy, PartialEq, Eq)] +#[derive(Debug, Clone, PartialEq, Eq)] pub enum Reconciled { /// A live worker still owns the attempt, or another reconciler does. Owned, @@ -43,7 +43,7 @@ pub enum Reconciled { } impl Reconciled { - fn label(self) -> &'static str { + fn label(&self) -> &'static str { match self { Reconciled::Owned => "owned", Reconciled::Released(_) => "released", @@ -162,7 +162,7 @@ impl Reconciler { PassKind::Steady => ExecutionFailureCode::LeaseExpired, }; let failure = ExecutionFailure { - code, + code: code.clone(), message: "the attempt stopped renewing its lease before the no-retry boundary" .to_string(), }; @@ -233,7 +233,10 @@ impl Reconciler { Reconciled::Waiting } Observed::Settles(code, message) => { - let failure = ExecutionFailure { code, message }; + let failure = ExecutionFailure { + code: code.clone(), + message, + }; match state .storage .resolve_execution(state.metadata.as_ref(), resolution(record, &fence, failure)) diff --git a/crates/server/src/metrics/names.rs b/crates/server/src/metrics/names.rs index 134a72ed..94ae9f8e 100644 --- a/crates/server/src/metrics/names.rs +++ b/crates/server/src/metrics/names.rs @@ -712,6 +712,8 @@ const KNOWN_GRPC_METHODS: &[(&str, &str)] = &[ ("guardian.Guardian", "CreateSession"), ("guardian.Guardian", "RevokeSession"), ("guardian.Guardian", "RevokeAllSessions"), + ("guardian.Guardian", "GetPolicies"), + ("guardian.Guardian", "CheckDeltaProposal"), // Served alongside Guardian via tonic-reflection (v1 and v1alpha). ( "grpc.reflection.v1.ServerReflection", diff --git a/crates/server/src/openapi.rs b/crates/server/src/openapi.rs index eb17ce39..7f6f8295 100644 --- a/crates/server/src/openapi.rs +++ b/crates/server/src/openapi.rs @@ -218,6 +218,8 @@ impl Modify for CommonResponsesAddon { crate::api::http::status, crate::api::http::status_root, crate::api::http::push_delta_proposal, + crate::api::http::check_delta_proposal, + crate::api::http::get_policies, crate::api::http::get_delta_proposals, crate::api::http::get_delta_proposal, crate::api::http::sign_delta_proposal, diff --git a/crates/server/src/services/ack_delta_internal.rs b/crates/server/src/services/ack_delta_internal.rs index 351a5255..74f2ff52 100644 --- a/crates/server/src/services/ack_delta_internal.rs +++ b/crates/server/src/services/ack_delta_internal.rs @@ -4,7 +4,11 @@ use std::sync::Arc; use guardian_shared::SignatureScheme; use crate::delta_object::DeltaObject; +use crate::delta_summary::ModuleApproval; use crate::error::Result; +use crate::metadata::auth::Auth; +use crate::modules::HookName; +use crate::modules::request::{self, StateRef, TransactionInput}; use crate::network::AppliedState; use crate::state::AppState; @@ -16,21 +20,38 @@ pub(crate) struct AcknowledgedDelta { pub matched_proposal: bool, } -/// Verifies `delta` against the state it builds on, derives its metadata, and signs Guardian's -/// acknowledgment. The base is the canonical state for a Guardian execution and the queue tail -/// for a pushed delta. Persists nothing and sets no pending-candidate flag: the public push path -/// commits the result itself, and a Guardian execution admits it only at its boundary commit. +/// The cosigner a Guardian acknowledgment is evaluated for: the one calling `push_delta`, or the +/// one whose request started a Guardian execution. Policy modules receive it as the submitter. +pub(crate) struct Submitter<'a> { + pub commitment: &'a str, + pub auth: &'a Auth, +} + +/// Verifies `delta` against the state it builds on, runs the policy modules, derives its +/// metadata, and signs Guardian's acknowledgment. The base is the canonical state for a Guardian +/// execution and the queue tail for a pushed delta. Persists nothing and sets no +/// pending-candidate flag: the public push path commits the result itself, and a Guardian +/// execution admits it only at its boundary commit. pub(crate) async fn acknowledge_delta( state: &AppState, scheme: &SignatureScheme, - base_commitment: &str, - base_state_json: &serde_json::Value, + base: StateRef<'_>, delta: &DeltaObject, + submitter: Submitter<'_>, ) -> Result { - let applied = apply_to_base(state, base_commitment, base_state_json, delta).await?; + let applied = apply_to_base(state, base.commitment, base.json, delta).await?; let proposal_match = lookup_matching_proposal(state, &delta.account_id, delta.nonce, &delta.delta_payload).await; - acknowledge_applied(state, scheme, delta, applied, proposal_match.payload()).await + acknowledge_applied( + state, + scheme, + base, + delta, + applied, + submitter, + &proposal_match, + ) + .await } /// Verifies `delta` against the state it builds on and applies it, without signing anything. @@ -52,17 +73,33 @@ pub(crate) async fn apply_to_base( .map_err(Into::into) } -/// Derives the metadata of a delta already applied by [`apply_to_base`], lifting operator -/// intent from `matching_proposal` when one matched, and signs Guardian's acknowledgment of it. +/// Runs the `before_transaction_approved` policy modules on a delta already applied by +/// [`apply_to_base`], derives its metadata, lifting operator intent from the matching proposal +/// when one matched, and signs Guardian's acknowledgment of it. Every Guardian ack is produced +/// here, so no caller acknowledges a delta the modules have not approved. pub(crate) async fn acknowledge_applied( state: &AppState, scheme: &SignatureScheme, + base: StateRef<'_>, delta: &DeltaObject, applied: AppliedState, - matching_proposal: Option<&Value>, + submitter: Submitter<'_>, + proposal_match: &ProposalMatch, ) -> Result { - let derived_metadata = + let approval = approve(state, base, delta, &applied, submitter, proposal_match).await?; + let matching_proposal = proposal_match.payload(); + let mut derived_metadata = crate::delta_summary::build_metadata(&delta.delta_payload, matching_proposal); + match (derived_metadata.as_mut(), approval) { + (Some(metadata), approval) => metadata.modules = approval, + (None, Some(approval)) => tracing::warn!( + account_id = %delta.account_id, + catalog_hash = %approval.catalog_hash, + params_version = approval.params_version, + "Delta has no metadata to record its module approval in" + ), + (None, None) => {} + } let mut acknowledged = delta.clone(); acknowledged.new_commitment = Some(applied.commitment.clone()); @@ -78,6 +115,54 @@ pub(crate) async fn acknowledge_applied( }) } +/// The `before_transaction_approved` decision for `delta`, or `None` when no module applies to +/// the account. A proposal lookup that failed is a module failure, never an absent proposer. +async fn approve( + state: &AppState, + base: StateRef<'_>, + delta: &DeltaObject, + applied: &AppliedState, + submitter: Submitter<'_>, + proposal_match: &ProposalMatch, +) -> Result> { + let Some(modules) = state.modules.as_deref() else { + return Ok(None); + }; + let Some(plan) = modules + .plan(HookName::BeforeTransactionApproved, &delta.account_id) + .await? + else { + return Ok(None); + }; + let proposal = match proposal_match { + ProposalMatch::Found(proposal) => Ok(request::proposal_context(proposal)), + ProposalMatch::Missing => Ok(None), + ProposalMatch::Unavailable(error) => Err(format!("proposal lookup failed: {error}")), + }; + let views = plan.views(); + plan.run(|| { + request::transaction_request( + state.network_client.as_ref(), + &views, + TransactionInput { + account_id: &delta.account_id, + submitter: submitter.commitment, + auth: submitter.auth, + before: base, + after: StateRef { + commitment: &applied.commitment, + json: &applied.state_json, + }, + tx_summary: &delta.delta_payload, + proposal: proposal?, + accounting_time: state.clock.now(), + }, + ) + }) + .await + .map(Some) +} + /// The `delta_proposals` row matching a delta, as far as storage could tell. pub(crate) enum ProposalMatch { Found(Box), diff --git a/crates/server/src/services/configure_account.rs b/crates/server/src/services/configure_account.rs index d67d880a..a8090ac4 100644 --- a/crates/server/src/services/configure_account.rs +++ b/crates/server/src/services/configure_account.rs @@ -2,6 +2,8 @@ use crate::error::{GuardianError, Result}; use crate::metadata::NetworkConfig; use crate::metadata::auth::{Auth, Credentials}; use crate::metadata::{AccountMetadata, ClearTransition}; +use crate::modules::HookName; +use crate::modules::request::{self, RegistrationInput, StateRef}; use crate::network::{RpcReadMode, StateVerification}; use crate::services::{consume_auth_timestamp, validate_request_timestamp}; use crate::state::AppState; @@ -234,6 +236,50 @@ pub async fn configure_account( (head, signer_commitment) }; + let plan = match state.modules.as_deref() { + Some(modules) => { + modules + .plan(HookName::BeforeAccountRegistered, ¶ms.account_id) + .await? + } + None => None, + }; + if let Some(plan) = plan { + let stored_state = match &existing { + Some(_) if !unfinished_claim => Some( + state + .storage + .pull_state(¶ms.account_id) + .await + .map_err(|e| format!("stored state unavailable: {e}")), + ), + _ => None, + }; + let views = plan.views(); + plan.run(|| { + let stored_state = stored_state.as_ref().map(|r| r.as_ref()).transpose()?; + request::registration_request( + state.network_client.as_ref(), + &views, + RegistrationInput { + account_id: ¶ms.account_id, + submitter: &signer_commitment, + auth: ¶ms.auth, + stored_state: stored_state.map(|stored| StateRef { + commitment: &stored.commitment, + json: &stored.state_json, + }), + initial_state: StateRef { + commitment: &head.commitment, + json: ¶ms.initial_state, + }, + accounting_time: state.clock.now(), + }, + ) + }) + .await?; + } + let now = state.clock.now_rfc3339(); // A first configuration claims the account before anything else: of two @@ -717,6 +763,7 @@ async fn stored_state_landed(state: &AppState, account_id: &str, commitment: &st mod tests { use super::*; use crate::ack::AckRegistry; + use crate::modules::testing::StubModule; use crate::state_object::StateHead; use crate::storage::StorageBackend; use crate::testing::mocks::{MockMetadataStore, MockNetworkClient, MockStorageBackend}; @@ -747,8 +794,8 @@ mod tests { AppState { execution: Default::default(), - modules: None, miden_sessions: std::sync::Arc::new(crate::session::MidenSessions::default()), + modules: None, storage, metadata: Arc::new(metadata_store), network_client: Arc::new(network_client), @@ -3387,4 +3434,154 @@ mod tests { assert!(result.is_ok(), "got: {result:?}"); } + + struct ModuleRun { + result: Result, + storage: MockStorageBackend, + metadata: MockMetadataStore, + module: Arc, + } + + async fn configure_with_module( + existing: impl FnOnce(String) -> Option, + module: Arc, + ) -> ModuleRun { + use crate::modules::catalog::OnError; + use crate::modules::testing::{instance, pipeline}; + use crate::testing::helpers::generate_falcon_signature; + + let account_id_hex = "0x1d1d1d1c1d1d1d011d1d1d1d1d1d1d"; + let (pubkey_hex, commitment_hex, signature_hex, timestamp) = + generate_falcon_signature(account_id_hex); + let existing = existing(commitment_hex.clone()); + let account_json = include_str!("../testing/fixtures/account.json"); + let initial_state: serde_json::Value = serde_json::from_str(account_json).unwrap(); + + let network_client = MockNetworkClient::new() + .with_validate_credential(Ok(())) + .with_get_state_head(Ok(head("0x5678", 3))) + .with_module_views( + guardian_module_sdk::AccountView { + signer_commitments: vec![commitment_hex.clone()], + ..Default::default() + }, + guardian_module_sdk::MidenTransaction::default(), + ); + let storage = MockStorageBackend::new() + .with_submit_state(Ok(())) + .with_pull_state(Ok(crate::state_object::StateObject { + account_id: account_id_hex.into(), + state_json: initial_state.clone(), + commitment: "0x5678".into(), + nonce: Some(3), + created_at: "2024-01-01T00:00:00Z".into(), + updated_at: "2024-01-01T00:00:00Z".into(), + auth_scheme: "falcon".into(), + })); + let metadata = MockMetadataStore::new() + .with_get(Ok(existing)) + .with_set(Ok(())); + let mut state = + create_test_app_state(network_client, storage.clone(), metadata.clone()).await; + state.modules = Some(pipeline(vec![instance( + "signers", + &[HookName::BeforeAccountRegistered], + OnError::Deny, + module.clone(), + )])); + + let result = configure_account( + &state, + ConfigureAccountParams { + account_id: account_id_hex.to_string(), + auth: Auth::MidenFalconRpo { + cosigner_commitments: vec![commitment_hex], + }, + network_config: crate::metadata::NetworkConfig::miden_default(), + initial_state, + credential: Credentials::signature(pubkey_hex, signature_hex, timestamp), + }, + ) + .await; + ModuleRun { + result, + storage, + metadata, + module, + } + } + + fn existing_account( + paused: bool, + released: bool, + ) -> impl FnOnce(String) -> Option { + use chrono::TimeZone; + move |commitment| { + let at = chrono::Utc + .with_ymd_and_hms(2026, 5, 19, 14, 30, 0) + .unwrap(); + Some(AccountMetadata { + account_id: "0x1d1d1d1c1d1d1d011d1d1d1d1d1d1d".into(), + auth: Auth::MidenFalconRpo { + cosigner_commitments: vec![commitment], + }, + network_config: crate::metadata::NetworkConfig::miden_default(), + created_at: "2024-01-01T00:00:00Z".into(), + updated_at: "2024-01-01T00:00:00Z".into(), + has_pending_candidate: false, + paused_at: paused.then_some(at), + paused_reason: paused.then(|| "compliance".to_string()), + released_at: released.then_some(at), + }) + } + } + + fn assert_nothing_written(run: &ModuleRun) { + assert!(matches!( + run.result, + Err(GuardianError::ModuleDenied { .. }) + )); + assert!(run.storage.get_submit_state_calls().is_empty()); + assert!(run.metadata.get_set_calls().is_empty()); + assert!(run.metadata.clear_released_calls.lock().unwrap().is_empty()); + } + + #[tokio::test] + async fn denied_new_registration_writes_nothing_and_has_no_before_view() { + let run = configure_with_module(|_| None, StubModule::denying("signer_not_allowed")).await; + assert_nothing_written(&run); + let request = run.module.last_request().expect("module was called"); + assert!(request.before.is_none()); + assert!(request.after.is_some()); + } + + #[tokio::test] + async fn allowed_reconfiguration_keeps_the_pause_and_sees_the_stored_state() { + let run = + configure_with_module(existing_account(true, false), StubModule::allowing()).await; + run.result.expect("reconfiguration succeeds"); + let set_calls = run.metadata.get_set_calls(); + assert_eq!(set_calls.len(), 1); + assert!(set_calls[0].paused_at.is_some()); + assert!(run.module.last_request().unwrap().before.is_some()); + } + + #[tokio::test] + async fn denied_reconfiguration_of_a_paused_account_changes_nothing() { + let run = + configure_with_module(existing_account(true, false), StubModule::denying("no")).await; + assert_nothing_written(&run); + } + + #[tokio::test] + async fn released_account_is_reactivated_only_when_modules_allow() { + let run = + configure_with_module(existing_account(false, true), StubModule::allowing()).await; + run.result.expect("re-onboarding succeeds"); + assert_eq!(run.metadata.clear_released_calls.lock().unwrap().len(), 1); + + let run = + configure_with_module(existing_account(false, true), StubModule::denying("no")).await; + assert_nothing_written(&run); + } } diff --git a/crates/server/src/services/execute_proposal/fault_injection_tests.rs b/crates/server/src/services/execute_proposal/fault_injection_tests.rs index a6d79963..79551ab7 100644 --- a/crates/server/src/services/execute_proposal/fault_injection_tests.rs +++ b/crates/server/src/services/execute_proposal/fault_injection_tests.rs @@ -173,13 +173,13 @@ impl Faults { .pass(&self.f.state, kind) .await .unwrap(); - let mine: Vec<_> = report + let mut mine: Vec<_> = report .into_iter() .filter(|(record, _)| record.reservation.account_id == ACCOUNT) .map(|(_, outcome)| outcome) .collect(); assert_eq!(mine.len(), 1, "{mine:?}"); - mine[0] + mine.remove(0) } async fn state(&self) -> ExecutionState { diff --git a/crates/server/src/services/execute_proposal/service.rs b/crates/server/src/services/execute_proposal/service.rs index 0abc2095..fe80e58a 100644 --- a/crates/server/src/services/execute_proposal/service.rs +++ b/crates/server/src/services/execute_proposal/service.rs @@ -314,6 +314,7 @@ pub async fn request_execution( nonce: proposal.nonce, base_commitment: proposal.prev_commitment, scheme: resolved.metadata.auth.guardian_scheme(), + requester: resolved.signer_commitment.clone(), fence, lease, elector, diff --git a/crates/server/src/services/execute_proposal/tests.rs b/crates/server/src/services/execute_proposal/tests.rs index 46080f9c..1e0032f9 100644 --- a/crates/server/src/services/execute_proposal/tests.rs +++ b/crates/server/src/services/execute_proposal/tests.rs @@ -1192,3 +1192,134 @@ async fn an_unknown_submission_outcome_stays_submitted_and_holds_the_account() { .is_some() ); } + +/// A fixture whose account is evaluated by one `before_transaction_approved` instance. +async fn gated( + module: Arc, + on_error: crate::modules::catalog::OnError, + client_reason: crate::modules::catalog::ClientReason, +) -> Fixture { + use crate::modules::catalog::HookName; + use crate::modules::testing::{instance, pipeline}; + let mut f = Fixture::new(Script::default()).await; + let _ = f.chain.clone().with_module_views( + guardian_module_sdk::AccountView::default(), + guardian_module_sdk::MidenTransaction::default(), + ); + let mut caps = instance( + "caps", + &[HookName::BeforeTransactionApproved], + on_error, + module, + ); + caps.config.client_reason = client_reason; + f.state.modules = Some(pipeline(vec![caps])); + f +} + +async fn failed_with(f: &Fixture) -> ExecutionFailureCode { + f.request().await.unwrap(); + let (failed, _) = f.settle(|state| state == ExecutionState::Failed).await; + assert!( + failed.proposal_exists, + "a module refusal keeps the proposal" + ); + assert!( + f.state.storage.pull_delta(ACCOUNT, 1).await.is_err(), + "nothing is acknowledged or admitted" + ); + assert_eq!(f.calls.lock().unwrap().proved, 0, "nothing is proved"); + let error = failed.error.expect("a failed execution carries its cause"); + ExecutionFailureCode::from_parts(&error.code, error.meta.as_ref()) + .expect("the wire failure decodes to a known code") +} + +#[tokio::test] +async fn a_module_denial_ends_the_execution_before_the_ack_with_the_denial() { + use guardian_shared::execution::ModuleDenial; + let module = crate::modules::testing::StubModule::denying("amount_cap_exceeded"); + let f = gated( + module.clone(), + crate::modules::catalog::OnError::Deny, + crate::modules::catalog::ClientReason::Full, + ) + .await; + assert_eq!( + failed_with(&f).await, + ExecutionFailureCode::ModuleDenied(ModuleDenial { + module: Some("caps".into()), + reason_code: "amount_cap_exceeded".into(), + layer: Some("global".into()), + client_message: None, + }) + ); + assert_eq!(module.calls(), 1); + assert_eq!( + module.last_request().map(|request| request.submitter), + Some(f.signer_commitment.clone()), + "the module evaluates the cosigner whose request started the execution" + ); +} + +#[tokio::test] +async fn a_generic_denial_on_the_execution_path_names_no_module() { + use guardian_shared::execution::ModuleDenial; + let f = gated( + crate::modules::testing::StubModule::denying("amount_cap_exceeded"), + crate::modules::catalog::OnError::Deny, + crate::modules::catalog::ClientReason::Generic, + ) + .await; + assert_eq!( + failed_with(&f).await, + ExecutionFailureCode::ModuleDenied(ModuleDenial { + module: None, + reason_code: "policy_denied".into(), + layer: None, + client_message: None, + }) + ); +} + +#[tokio::test] +async fn a_failing_fail_closed_module_ends_the_execution_as_unavailable() { + let f = gated( + crate::modules::testing::StubModule::new(crate::modules::testing::Behaviour::Fail), + crate::modules::catalog::OnError::Deny, + crate::modules::catalog::ClientReason::Full, + ) + .await; + assert_eq!( + failed_with(&f).await, + ExecutionFailureCode::ModuleUnavailable { + module: "caps".into() + } + ); +} + +#[tokio::test] +async fn an_approving_module_lets_the_execution_through_and_is_recorded_on_the_delta() { + let module = crate::modules::testing::StubModule::allowing(); + let f = gated( + module.clone(), + crate::modules::catalog::OnError::Deny, + crate::modules::catalog::ClientReason::Full, + ) + .await; + f.request().await.unwrap(); + f.settle(is_submitted_or_terminal).await; + assert_eq!(module.calls(), 1); + let candidate = f + .state + .storage + .pull_delta(ACCOUNT, 1) + .await + .expect("the boundary admitted a candidate"); + assert!( + candidate + .metadata + .and_then(|metadata| metadata.modules) + .is_some(), + "the approval is recorded on the acknowledged delta" + ); +} diff --git a/crates/server/src/services/execute_proposal/worker.rs b/crates/server/src/services/execute_proposal/worker.rs index d26168d9..3d45f3bb 100644 --- a/crates/server/src/services/execute_proposal/worker.rs +++ b/crates/server/src/services/execute_proposal/worker.rs @@ -7,6 +7,7 @@ use std::sync::Arc; use chrono::{DateTime, Utc}; use guardian_shared::SignatureScheme; +use guardian_shared::execution::ModuleDenial; use super::executor::{ ExecutedTransactionInfo, ExecutionAttempt, GuardianAck, ProvenTransactionInfo, @@ -14,9 +15,10 @@ use super::executor::{ }; use crate::coordination::{LeaderElector, Lease, Renewal, release_quietly}; use crate::delta_object::{DeltaObject, DeltaStatus}; -use crate::error::GuardianError; +use crate::error::{GENERIC_REASON_CODE, GuardianError}; +use crate::modules::request::StateRef; use crate::services::account_status::ensure_account_active_metadata; -use crate::services::ack_delta_internal::{AcknowledgedDelta, acknowledge_delta}; +use crate::services::ack_delta_internal::{AcknowledgedDelta, Submitter, acknowledge_delta}; use crate::state::AppState; use crate::storage::execution::ExpirationBound; use crate::storage::{ @@ -31,6 +33,10 @@ pub(super) struct ExecutionJob { pub nonce: u64, pub base_commitment: String, pub scheme: SignatureScheme, + /// The cosigner whose authenticated request started this attempt: the submitter the policy + /// modules evaluate the acknowledgement for. A repeated request joins the running attempt, + /// which keeps it. + pub requester: String, pub fence: LeaseFence, pub lease: Lease, pub elector: Arc, @@ -440,16 +446,68 @@ async fn acknowledge( status: DeltaStatus::candidate(Utc::now().to_rfc3339()), metadata: None, }; + let registered = state + .metadata + .get(&job.account_id) + .await + .map_err(|e| { + ExecutionFailure::with_logged_cause( + ExecutionFailureCode::AccountInadmissible, + "Guardian could not read the account's registration", + &e, + ) + })? + .ok_or_else(|| { + ExecutionFailure::new( + ExecutionFailureCode::AccountInadmissible, + "the account is no longer registered with Guardian", + ) + })?; acknowledge_delta( state, &job.scheme, - ¤t_state.commitment, - ¤t_state.state_json, + StateRef { + commitment: ¤t_state.commitment, + json: ¤t_state.state_json, + }, &delta, + Submitter { + commitment: &job.requester, + auth: ®istered.auth, + }, ) .await .map_err(|error| { let failure = match error { + GuardianError::ModuleDenied { + ref module, + ref reason_code, + ref layer, + ref client_message, + } => ExecutionFailure::new( + ExecutionFailureCode::ModuleDenied(ModuleDenial { + module: Some(module.clone()), + reason_code: reason_code.clone(), + layer: Some(layer.clone()), + client_message: client_message.clone(), + }), + error.user_message(), + ), + GuardianError::ModuleDeniedGeneric => ExecutionFailure::new( + ExecutionFailureCode::ModuleDenied(ModuleDenial { + module: None, + reason_code: GENERIC_REASON_CODE.to_string(), + layer: None, + client_message: None, + }), + error.user_message(), + ), + GuardianError::ModuleUnavailable { ref module } => ExecutionFailure::new( + ExecutionFailureCode::ModuleUnavailable { + module: module.clone(), + }, + error.user_message(), + ), GuardianError::SigningError(_) | GuardianError::StorageError(_) | GuardianError::ConfigurationError(_) => ExecutionFailure::with_logged_cause( @@ -769,7 +827,7 @@ async fn submit( /// Resolves a send the node refused: its candidate is dropped, and its proposal with it unless /// the cause leaves the proposal executable (`ExecutionFailureCode::ends_proposal`). async fn resolve_refused_send(state: &AppState, job: &ExecutionJob, failure: ExecutionFailure) { - let code = failure.code; + let code = failure.code.clone(); match state .storage .resolve_execution(state.metadata.as_ref(), resolution(job, failure)) @@ -801,7 +859,7 @@ async fn fail( total_ms = timings.total_ms(), "Guardian execution failed before submission" ); - let code = failure.code; + let code = failure.code.clone(); match state.storage.fail_execution(resolution(job, failure)).await { Ok(ResolveWrite::Resolved) => crate::metrics::execution::record_outcome(Some(&code)), Ok(ResolveWrite::AlreadyResolved) => {} diff --git a/crates/server/src/services/get_policies.rs b/crates/server/src/services/get_policies.rs new file mode 100644 index 00000000..8ee15a60 --- /dev/null +++ b/crates/server/src/services/get_policies.rs @@ -0,0 +1,42 @@ +use crate::error::{GuardianError, Result}; +use crate::metadata::auth::Credentials; +use crate::modules::disclosure::PolicyEntry; +use crate::services::resolve_account_allowing_session; +use crate::state::AppState; + +#[derive(Debug, Clone)] +pub struct GetPoliciesParams { + pub account_id: String, + pub credentials: Credentials, +} + +#[derive(Debug, Clone)] +pub struct GetPoliciesResult { + pub account_id: String, + pub policies: Vec, +} + +/// The policies that apply to the account, for its cosigners, filtered by each instance's +/// disclosure (RFC 0002 section 2.7). Empty when no modules are configured. +#[tracing::instrument(level = "info", skip(state, params), fields(account_id = %params.account_id))] +pub async fn get_policies( + state: &AppState, + params: GetPoliciesParams, +) -> Result { + let resolved = + resolve_account_allowing_session(state, ¶ms.account_id, ¶ms.credentials).await?; + if resolved.metadata.network_config.is_evm() { + return Err(GuardianError::UnsupportedForNetwork { + network: "evm".to_string(), + operation: "get_policies".to_string(), + }); + } + let policies = match state.modules.as_deref() { + Some(modules) => modules.disclosed(¶ms.account_id).await?, + None => Vec::new(), + }; + Ok(GetPoliciesResult { + account_id: params.account_id.to_ascii_lowercase(), + policies, + }) +} diff --git a/crates/server/src/services/mod.rs b/crates/server/src/services/mod.rs index 5bfd22c2..e1370191 100644 --- a/crates/server/src/services/mod.rs +++ b/crates/server/src/services/mod.rs @@ -33,6 +33,7 @@ mod get_delta_history; mod get_delta_proposal; mod get_delta_proposals; mod get_delta_since; +mod get_policies; mod get_state; mod lookup_account; mod multisig_admission; @@ -102,11 +103,13 @@ pub use get_delta_proposals::{ GetDeltaProposalsParams, GetDeltaProposalsResult, get_delta_proposals, }; pub use get_delta_since::{GetDeltaSinceParams, GetDeltaSinceResult, get_delta_since}; +pub use get_policies::{GetPoliciesParams, GetPoliciesResult, get_policies}; pub use get_state::{GetStateParams, GetStateResult, get_state}; pub use lookup_account::{LookupAccountParams, LookupAccountResult, lookup_account}; pub use push_delta::{PushDeltaParams, PushDeltaResult, push_delta}; pub use push_delta_proposal::{ - PushDeltaProposalParams, PushDeltaProposalResult, push_delta_proposal, + CheckProposalResult, PushDeltaProposalParams, PushDeltaProposalResult, check_proposal, + push_delta_proposal, }; pub use revoke_all_sessions::{ RevokeAllSessionsParams, RevokeAllSessionsResult, revoke_all_sessions, @@ -697,8 +700,8 @@ mod tests { AppState { execution: Default::default(), - modules: None, miden_sessions: std::sync::Arc::new(crate::session::MidenSessions::default()), + modules: None, storage: Arc::new(storage), metadata: Arc::new(metadata), network_client: Arc::new(network), diff --git a/crates/server/src/services/push_delta.rs b/crates/server/src/services/push_delta.rs index 240e5519..71939648 100644 --- a/crates/server/src/services/push_delta.rs +++ b/crates/server/src/services/push_delta.rs @@ -1,9 +1,10 @@ use crate::delta_object::DeltaObject; use crate::error::{GuardianError, Result}; use crate::metadata::auth::{Credentials, RequestAuthFormat}; +use crate::modules::request::StateRef; use crate::services::account_status::ensure_account_active_metadata; use crate::services::ack_delta_internal::{ - ProposalMatch, acknowledge_applied, apply_to_base, lookup_matching_proposal, + ProposalMatch, Submitter, acknowledge_applied, apply_to_base, lookup_matching_proposal, }; use crate::services::candidate_chain::{self, CandidateChain}; use crate::services::delta_commit::{CommitContext, DeltaCommitStrategy}; @@ -207,9 +208,17 @@ pub async fn push_delta(state: &AppState, params: PushDeltaParams) -> Result, + ) -> (Result, MockStorageBackend, String) { + push_with_modules_when( + module, + |_| Err("proposal not found".to_string()), + crate::modules::catalog::OnError::Deny, + ) + .await + } + + /// `proposal` builds the proposal lookup's result from the account id. + async fn push_with_modules_when( + module: Arc, + proposal: impl FnOnce(&str) -> std::result::Result, + on_error: crate::modules::catalog::OnError, + ) -> (Result, MockStorageBackend, String) { + use crate::delta_object::DeltaStatus; + use crate::modules::testing::{instance, pipeline}; + use crate::state_object::StateObject; + use crate::testing::helpers::create_test_delta_payload; + + let account_id = "0x7b7b7b7a7b7b7b017b7b7b7b7b7b7b".to_string(); + let (signer_pubkey, signer_commitment, signer_signature, signer_timestamp) = + crate::testing::helpers::generate_falcon_signature(&account_id); + let storage = MockStorageBackend::new() + .with_pull_state(Ok(StateObject { + account_id: account_id.clone(), + state_json: serde_json::json!({}), + commitment: "0xprev".into(), + nonce: None, + created_at: "2026-05-25T08:00:00Z".into(), + updated_at: "2026-05-25T08:00:00Z".into(), + auth_scheme: String::new(), + })) + .with_pull_deltas_after(Ok(Vec::new())) + .with_pull_delta_proposal(proposal(&account_id)) + .with_submit_state(Ok(())) + .with_submit_delta(Ok(())); + let network = MockNetworkClient::new() + .with_validate_credential(Ok(())) + .with_verify_delta(Ok(())) + .with_apply_delta(Ok(( + serde_json::json!({"new_state": true}), + "0xnew".to_string(), + ))) + .with_module_views( + guardian_module_sdk::AccountView { + signer_commitments: vec![signer_commitment.clone()], + ..Default::default() + }, + guardian_module_sdk::MidenTransaction::default(), + ); + let metadata = MockMetadataStore::new().with_get(Ok(Some(AccountMetadata { + account_id: account_id.clone(), + auth: Auth::MidenFalconRpo { + cosigner_commitments: vec![signer_commitment.clone()], + }, + network_config: crate::metadata::NetworkConfig::miden_default(), + created_at: "2026-05-01T00:00:00Z".into(), + updated_at: "2026-05-01T00:00:00Z".into(), + has_pending_candidate: false, + paused_at: None, + paused_reason: None, + released_at: None, + }))); + let mut state = create_test_app_state_with_mocks( + Arc::new(storage.clone()), + Arc::new(network), + Arc::new(metadata), + ); + state.modules = Some(pipeline(vec![instance( + "caps", + &[HookName::BeforeTransactionApproved], + on_error, + module, + )])); + let params = PushDeltaParams { + delta: DeltaObject { + account_id: account_id.clone(), + nonce: 1, + prev_commitment: "0xprev".into(), + new_commitment: None, + delta_payload: create_test_delta_payload(&account_id), + ack_sig: String::new(), + ack_pubkey: String::new(), + ack_scheme: String::new(), + status: DeltaStatus::default(), + metadata: None, + }, + credentials: Credentials::signature(signer_pubkey, signer_signature, signer_timestamp), + }; + (push_delta(&state, params).await, storage, signer_commitment) + } + + #[tokio::test] + async fn a_failed_proposal_lookup_is_a_module_failure_not_an_empty_proposer() { + use crate::modules::catalog::OnError; + let lookup_fails = |_: &str| Err("connection reset by peer".to_string()); + + let module = crate::modules::testing::StubModule::allowing(); + let (result, storage, _) = + push_with_modules_when(module.clone(), lookup_fails, OnError::Deny).await; + assert!(matches!( + result, + Err(GuardianError::ModuleUnavailable { module }) if module == "caps" + )); + assert_eq!( + module.calls(), + 0, + "the module never sees a request without its proposer" + ); + assert!(storage.get_submit_delta_calls().is_empty()); + + let module = crate::modules::testing::StubModule::allowing(); + let (result, _, _) = + push_with_modules_when(module.clone(), lookup_fails, OnError::Allow).await; + let approval = result + .expect("fail-open lets the push through") + .delta + .metadata + .and_then(|metadata| metadata.modules) + .expect("the approval is recorded"); + assert_eq!(module.calls(), 0); + assert_eq!(approval.failed_open.len(), 1); + assert_eq!(approval.failed_open[0].failure, "request_unavailable"); + } + + #[tokio::test] + async fn the_one_proposal_read_gives_modules_the_proposer() { + use crate::delta_object::DeltaStatus; + let module = crate::modules::testing::StubModule::allowing(); + let pending = |account_id: &str| { + Ok(DeltaObject { + account_id: account_id.to_string(), + nonce: 1, + status: DeltaStatus::Pending { + timestamp: "2026-05-25T08:00:00Z".into(), + proposer_id: "0xproposer".into(), + cosigner_sigs: Vec::new(), + }, + delta_payload: serde_json::json!({ "metadata": { "proposal_type": "p2id" } }), + ..Default::default() + }) + }; + let (result, storage, _) = push_with_modules_when( + module.clone(), + pending, + crate::modules::catalog::OnError::Deny, + ) + .await; + result.expect("allowed push succeeds"); + assert_eq!( + storage.get_pull_delta_proposal_calls().len(), + 2, + "one read for metadata and modules, one by the optimistic commit to delete the proposal" + ); + let request = module.last_request().expect("module was called"); + match request.subject { + Some(guardian_module_sdk::proto::hook_request::Subject::Transaction(subject)) => { + assert_eq!(subject.proposer, "0xproposer"); + } + other => panic!("unexpected subject {other:?}"), + } + } + + #[tokio::test] + async fn module_denial_refuses_the_ack_and_stores_nothing() { + let module = crate::modules::testing::StubModule::denying("amount_cap_exceeded"); + let (result, storage, _) = push_with_modules(module.clone()).await; + assert!(matches!( + result, + Err(GuardianError::ModuleDenied { module, reason_code, .. }) + if module == "caps" && reason_code == "amount_cap_exceeded" + )); + assert!(storage.get_submit_delta_calls().is_empty()); + assert_eq!(module.calls(), 1); + } + + #[tokio::test] + async fn module_allow_acks_and_receives_the_submitter_and_views() { + let module = crate::modules::testing::StubModule::allowing(); + let (result, storage, signer) = push_with_modules(module.clone()).await; + let pushed = result.expect("allowed push succeeds"); + assert_eq!(storage.get_submit_delta_calls().len(), 1); + let approval = pushed + .delta + .metadata + .and_then(|metadata| metadata.modules) + .expect("the approving module configuration is recorded"); + assert_eq!(approval.params_version, 0); + assert!(approval.failed_open.is_empty()); + let request = module.last_request().expect("module was called"); + assert_eq!(request.submitter, signer); + let Some(guardian_module_sdk::proto::hook_request::Subject::Transaction(subject)) = + &request.subject + else { + panic!("transaction subject expected"); + }; + assert!( + subject.miden().is_some(), + "the projection is tagged as Miden" + ); + assert_eq!( + subject.raw.as_ref().map(|raw| raw.encoding.as_str()), + Some(guardian_module_sdk::RawTransaction::MIDEN_TRANSACTION_SUMMARY) + ); + assert_eq!(request.after.unwrap().signer_commitments, vec![signer]); + assert!(request.before.is_some()); + } } diff --git a/crates/server/src/services/push_delta_proposal.rs b/crates/server/src/services/push_delta_proposal.rs index 66d0d0bb..01281240 100644 --- a/crates/server/src/services/push_delta_proposal.rs +++ b/crates/server/src/services/push_delta_proposal.rs @@ -2,6 +2,8 @@ use crate::builder::state::AppState; use crate::delta_object::{CosignerSignature, DeltaObject, DeltaStatus}; use crate::error::{GuardianError, Result}; use crate::metadata::auth::Credentials; +use crate::modules::HookName; +use crate::modules::request::{self, ProposalContext, StateRef, TransactionInput}; use crate::services::account_status::ensure_account_active_metadata; use crate::services::candidate_chain::{self, CandidateChain}; use crate::services::execution_codec::TransactionRequestEnvelope; @@ -57,21 +59,64 @@ pub struct PushDeltaProposalResult { pub commitment: String, } +/// The answer of a dry-run check that passed. A denial or an unavailable module is the same +/// error proposal creation returns. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub struct CheckProposalResult { + /// False when an instance that opts out of dry runs was skipped. + pub complete: bool, +} + +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +enum Mode { + Create, + DryRun, +} + +enum Outcome { + Created(Box), + Checked(CheckProposalResult), +} + +pub async fn push_delta_proposal( + state: &AppState, + params: PushDeltaProposalParams, +) -> Result { + match propose(state, params, Mode::Create).await? { + Outcome::Created(result) => Ok(*result), + Outcome::Checked(_) => Err(GuardianError::StorageError( + "proposal creation ended as a check".into(), + )), + } +} + +/// Runs proposal creation up to the `before_proposal_created` modules without storing +/// anything (RFC 0002 section 2.7). Advisory: approval still decides. +pub async fn check_proposal( + state: &AppState, + params: PushDeltaProposalParams, +) -> Result { + match propose(state, params, Mode::DryRun).await? { + Outcome::Checked(result) => Ok(result), + Outcome::Created(_) => Err(GuardianError::StorageError( + "a proposal check stored a proposal".into(), + )), + } +} + #[tracing::instrument( level = "info", skip(state, params), fields( account_id = %params.account_id, nonce = params.nonce, + ?mode, proposer_id = tracing::field::Empty, commitment = tracing::field::Empty, signer_count = tracing::field::Empty ) )] -pub async fn push_delta_proposal( - state: &AppState, - params: PushDeltaProposalParams, -) -> Result { +async fn propose(state: &AppState, params: PushDeltaProposalParams, mode: Mode) -> Result { tracing::debug!("Pushing delta proposal"); if crate::metadata::network::is_evm_account_id(¶ms.account_id) @@ -98,6 +143,20 @@ pub async fn push_delta_proposal( let resolved = resolve_account_allowing_session(state, &account_id, &credentials).await?; ensure_account_active_metadata(&resolved.metadata)?; + // A dry run is admitted against its rate limit before any reconstruction work, whether + // or not modules are configured. + if mode == Mode::DryRun { + crate::modules::check_limit::admit(&account_id, &resolved.signer_commitment)?; + } + let dry_run = match (mode, state.modules.as_deref()) { + (Mode::DryRun, Some(modules)) => Some( + modules + .plan_dry_run(HookName::BeforeProposalCreated, &account_id) + .await?, + ), + (Mode::DryRun, None) => Some((None, true)), + (Mode::Create, _) => None, + }; if resolved.metadata.network_config.is_evm() { return Err(GuardianError::UnsupportedForNetwork { network: "evm".to_string(), @@ -290,6 +349,67 @@ pub async fn push_delta_proposal( }); } tracing::Span::current().record("signer_count", cosigner_sigs.len()); + + let (plan, complete) = match (dry_run, state.modules.as_deref()) { + (Some(planned), _) => planned, + (None, Some(modules)) => ( + modules + .plan(HookName::BeforeProposalCreated, &account_id) + .await?, + true, + ), + (None, None) => (None, true), + }; + if let Some(plan) = plan { + let after = { + let client = state.network_client.clone(); + let tail_state_json = tail.state_json.clone(); + let tx_summary = tx_summary.clone(); + crate::network::reconstructor() + .run(move || client.apply_delta(&tail_state_json, &tx_summary)) + .await? + }; + let proposal = ProposalContext { + proposer: proposer_id.clone(), + metadata: delta_payload + .get("metadata") + .cloned() + .unwrap_or(serde_json::Value::Null), + }; + let views = plan.views(); + plan.run(|| { + request::transaction_request( + state.network_client.as_ref(), + &views, + TransactionInput { + account_id: &account_id, + submitter: &proposer_id, + auth: &resolved.metadata.auth, + before: StateRef { + commitment: &tail.commitment, + json: &tail.state_json, + }, + after: StateRef { + commitment: &after.commitment, + json: &after.state_json, + }, + tx_summary, + proposal: Some(proposal), + accounting_time: state.clock.now(), + }, + ) + }) + .await?; + } + if mode == Mode::DryRun { + tracing::info!( + account_id = %account_id, + signer = %proposer_id, + complete, + "Proposal dry-run check passed" + ); + return Ok(Outcome::Checked(CheckProposalResult { complete })); + } // Create delta object with Pending status including any provided signatures let timestamp = state.clock.now_rfc3339(); let delta_proposal = DeltaObject { @@ -343,7 +463,10 @@ pub async fn push_delta_proposal( } }; - Ok(PushDeltaProposalResult { delta, commitment }) + Ok(Outcome::Created(Box::new(PushDeltaProposalResult { + delta, + commitment, + }))) } /// A proposal is identified by its summary alone, so pushing it again stores nothing: the @@ -2234,4 +2357,159 @@ mod tests { "judged on the replayed tail" ); } + + async fn propose_with_module( + module: Arc, + hook: HookName, + ) -> (Result, MockStorageBackend, String) { + let (state, storage, params, commitment) = module_setup(module, hook, |_| {}); + ( + push_delta_proposal(&state, params).await, + storage, + commitment, + ) + } + + /// State, storage, request and proposer for one module at `hook`, after `configure` adjusts + /// the instance. + fn module_setup( + module: Arc, + hook: HookName, + configure: impl FnOnce(&mut crate::modules::registry::Instance), + ) -> ( + AppState, + MockStorageBackend, + PushDeltaProposalParams, + String, + ) { + use crate::modules::catalog::OnError; + use crate::modules::testing::{instance, pipeline}; + + let (mut state, storage, network, metadata) = create_test_state(); + let account_json: serde_json::Value = serde_json::from_str(fixtures::ACCOUNT_JSON).unwrap(); + let delta_fixture: serde_json::Value = + serde_json::from_str(fixtures::DELTA_1_JSON).unwrap(); + let account_id = delta_fixture["account_id"].as_str().unwrap().to_string(); + let (pubkey, commitment, signature, timestamp) = + crate::testing::helpers::generate_falcon_signature(&account_id); + + let _ = metadata.with_get(Ok(Some(create_account_metadata( + account_id.clone(), + Auth::MidenFalconRpo { + cosigner_commitments: vec![commitment.clone()], + }, + )))); + let storage = storage.with_pull_state(Ok(create_state_object( + account_id.clone(), + "0x780aa2edb983c1baab3c81edcfe400bc54b516d5cb51f2a7cec4690667329392".into(), + account_json, + ))); + let _ = network + .with_verify_delta(Ok(())) + .with_validate_credential(Ok(())) + .with_apply_delta(Ok((serde_json::json!({ "after": true }), "0xafter".into()))) + .with_module_views( + guardian_module_sdk::AccountView::default(), + guardian_module_sdk::MidenTransaction::default(), + ); + let mut configured = instance("caps", &[hook], OnError::Deny, module); + configure(&mut configured); + state.modules = Some(pipeline(vec![configured])); + + let params = PushDeltaProposalParams { + account_id, + nonce: 1, + delta_payload: serde_json::json!({ + "tx_summary": delta_fixture["delta_payload"].clone(), + "signatures": [], + "metadata": { "proposal_type": "p2id", "description": "pay rent" } + }), + credentials: Credentials::signature(pubkey, signature, timestamp), + }; + (state, storage, params, commitment) + } + + #[tokio::test] + async fn a_check_runs_the_creation_modules_and_stores_nothing() { + let module = crate::modules::testing::StubModule::allowing(); + let (state, storage, params, _) = + module_setup(module.clone(), HookName::BeforeProposalCreated, |_| {}); + let result = check_proposal(&state, params).await.unwrap(); + assert!(result.complete); + assert_eq!(module.calls(), 1); + assert!(storage.get_submit_delta_proposal_calls().is_empty()); + + let module = crate::modules::testing::StubModule::denying("amount_cap_exceeded"); + let (state, storage, params, _) = + module_setup(module, HookName::BeforeProposalCreated, |_| {}); + assert!(matches!( + check_proposal(&state, params).await, + Err(GuardianError::ModuleDenied { .. }) + )); + assert!(storage.get_submit_delta_proposal_calls().is_empty()); + } + + #[tokio::test] + async fn a_module_that_opts_out_is_skipped_and_the_check_is_incomplete() { + let module = crate::modules::testing::StubModule::denying("would_deny"); + let (state, _, params, _) = module_setup( + module.clone(), + HookName::BeforeProposalCreated, + |instance| { + instance.config.dry_run = false; + }, + ); + let result = check_proposal(&state, params).await.unwrap(); + assert!(!result.complete, "the skip is reported, not hidden"); + assert_eq!(module.calls(), 0); + + let (state, _, params, _) = + module_setup(module, HookName::BeforeProposalCreated, |instance| { + instance.config.dry_run = false; + }); + assert!( + matches!( + push_delta_proposal(&state, params).await, + Err(GuardianError::ModuleDenied { .. }) + ), + "creation still runs it" + ); + } + + #[tokio::test] + async fn module_denial_at_creation_stores_no_proposal() { + let module = crate::modules::testing::StubModule::denying("amount_cap_exceeded"); + let (result, storage, _) = + propose_with_module(module, HookName::BeforeProposalCreated).await; + assert!(matches!(result, Err(GuardianError::ModuleDenied { .. }))); + assert!(storage.get_submit_delta_proposal_calls().is_empty()); + } + + #[tokio::test] + async fn creation_passes_the_proposer_and_untrusted_metadata() { + let module = crate::modules::testing::StubModule::allowing(); + let (result, storage, proposer) = + propose_with_module(module.clone(), HookName::BeforeProposalCreated).await; + result.expect("proposal is created"); + assert_eq!(storage.get_submit_delta_proposal_calls().len(), 1); + let request = module.last_request().expect("module was called"); + assert_eq!(request.submitter, proposer); + let Some(guardian_module_sdk::proto::hook_request::Subject::Transaction(tx)) = + request.subject + else { + panic!("transaction subject expected"); + }; + assert_eq!(tx.proposer, proposer); + let metadata: serde_json::Value = serde_json::from_slice(&tx.unverified_metadata).unwrap(); + assert_eq!(metadata["description"], "pay rent"); + } + + #[tokio::test] + async fn approval_only_module_is_not_called_at_creation() { + let module = crate::modules::testing::StubModule::denying("no"); + let (result, _, _) = + propose_with_module(module.clone(), HookName::BeforeTransactionApproved).await; + result.expect("creation is not evaluated by an approval-only module"); + assert_eq!(module.calls(), 0); + } } diff --git a/crates/server/src/storage/execution_reservation_tests.rs b/crates/server/src/storage/execution_reservation_tests.rs index caaf2741..2a116d52 100644 --- a/crates/server/src/storage/execution_reservation_tests.rs +++ b/crates/server/src/storage/execution_reservation_tests.rs @@ -514,7 +514,7 @@ async fn a_pre_boundary_failure_releases_with_its_outcome(h: &Harness) { h.storage .resolve_execution( h.metadata.as_ref(), - h.resolution(&proposal, attempt, &owner, code) + h.resolution(&proposal, attempt, &owner, code.clone()) ) .await .unwrap(), @@ -523,7 +523,7 @@ async fn a_pre_boundary_failure_releases_with_its_outcome(h: &Harness) { ); assert_eq!( h.storage - .fail_execution(h.resolution(&proposal, attempt, &owner, code)) + .fail_execution(h.resolution(&proposal, attempt, &owner, code.clone())) .await .unwrap(), ResolveWrite::Resolved diff --git a/crates/server/src/storage/filesystem.rs b/crates/server/src/storage/filesystem.rs index 7805d696..08412d55 100644 --- a/crates/server/src/storage/filesystem.rs +++ b/crates/server/src/storage/filesystem.rs @@ -4447,6 +4447,62 @@ mod tests { tokio::fs::remove_dir_all(temp_dir).await.ok(); } + fn pending_from(proposer: &str, signers: &[&str]) -> DeltaObject { + let mut proposal = create_test_delta("0x7b7b7b7a7b7b7b017b7b7b7b7b7b7b", 1); + proposal.status = DeltaStatus::Pending { + timestamp: "2026-10-13T00:00:00Z".into(), + proposer_id: proposer.into(), + cosigner_sigs: signers + .iter() + .map(|signer| crate::delta_object::CosignerSignature { + signature: guardian_shared::ProposalSignature::from_scheme( + guardian_shared::SignatureScheme::Falcon, + "0xsig".into(), + None, + ), + timestamp: "2026-10-13T00:00:00Z".into(), + signer_id: (*signer).into(), + }) + .collect(), + }; + proposal + } + + fn proposer_of(proposal: &DeltaObject) -> (&str, usize) { + match &proposal.status { + DeltaStatus::Pending { + proposer_id, + cosigner_sigs, + .. + } => (proposer_id, cosigner_sigs.len()), + other => panic!("expected a pending proposal, got {other:?}"), + } + } + + #[tokio::test] + async fn signature_update_after_creation_is_kept_on_reload() { + let temp_dir = env::temp_dir().join(format!("guardian_test_{}", uuid::Uuid::new_v4())); + let account_id = "0x7b7b7b7a7b7b7b017b7b7b7b7b7b7b"; + { + let storage = FilesystemService::new(temp_dir.clone()).await.unwrap(); + storage + .submit_delta_proposal("0xabc", &pending_from("0xfirst", &[])) + .await + .unwrap(); + storage + .update_delta_proposal("0xabc", &pending_from("0xfirst", &["0xcosigner"])) + .await + .unwrap(); + } + let reloaded = FilesystemService::new(temp_dir.clone()).await.unwrap(); + let stored = reloaded + .pull_delta_proposal(account_id, "0xabc") + .await + .unwrap(); + assert_eq!(proposer_of(&stored), ("0xfirst", 1)); + tokio::fs::remove_dir_all(temp_dir).await.ok(); + } + #[tokio::test] async fn test_delete_nonexistent_proposal() { let temp_dir = env::temp_dir().join(format!("guardian_test_{}", uuid::Uuid::new_v4())); diff --git a/crates/shared/src/execution.rs b/crates/shared/src/execution.rs index c2e4906b..686e79b8 100644 --- a/crates/shared/src/execution.rs +++ b/crates/shared/src/execution.rs @@ -86,8 +86,24 @@ pub enum ForeignAccountUnavailableReason { Unavailable, } +/// A GUARDIAN policy module's denial of the transaction, with the fields a +/// `GUARDIAN_MODULE_DENIED` refusal carries in its `meta`. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +pub struct ModuleDenial { + /// The denying instance; absent for a generic denial, which reports only `policy_denied`. + #[serde(default, skip_serializing_if = "Option::is_none")] + pub module: Option, + pub reason_code: String, + /// `global` or `account`: the parameter layer that denied; absent for a generic denial. + #[serde(default, skip_serializing_if = "Option::is_none")] + pub layer: Option, + /// The module's text for the requester, when the instance allows it. + #[serde(default, skip_serializing_if = "Option::is_none")] + pub client_message: Option, +} + /// Stable cause of a failed execution, persisted with its structured meta. -#[derive(Debug, Clone, Copy, PartialEq, Eq)] +#[derive(Debug, Clone, PartialEq, Eq)] pub enum ExecutionFailureCode { BindingMismatch, StateMismatch, @@ -119,6 +135,12 @@ pub enum ExecutionFailureCode { Expired, LeaseExpired, Abandoned, + /// A GUARDIAN policy module refused the acknowledgement. The proposal stays stored. + ModuleDenied(ModuleDenial), + /// A fail-closed GUARDIAN policy module could not decide. Requesting again may succeed. + ModuleUnavailable { + module: String, + }, } #[derive(Serialize, Deserialize)] @@ -131,6 +153,11 @@ struct BoundMeta { bound: ExpirationBound, } +#[derive(Serialize, Deserialize)] +struct ModuleMeta { + module: String, +} + impl ExecutionFailureCode { pub fn as_str(&self) -> &'static str { match self { @@ -167,6 +194,10 @@ impl ExecutionFailureCode { ExecutionFailureCode::Expired => "GUARDIAN_EXECUTION_EXPIRED", ExecutionFailureCode::LeaseExpired => "GUARDIAN_EXECUTION_LEASE_EXPIRED", ExecutionFailureCode::Abandoned => "GUARDIAN_EXECUTION_ABANDONED", + ExecutionFailureCode::ModuleDenied(_) => "GUARDIAN_EXECUTION_MODULE_DENIED", + ExecutionFailureCode::ModuleUnavailable { .. } => { + "GUARDIAN_EXECUTION_MODULE_UNAVAILABLE" + } } } @@ -197,7 +228,9 @@ impl ExecutionFailureCode { | ExecutionFailureCode::AccountInadmissible | ExecutionFailureCode::SubmissionNotProcessed | ExecutionFailureCode::LeaseExpired - | ExecutionFailureCode::Abandoned => false, + | ExecutionFailureCode::Abandoned + | ExecutionFailureCode::ModuleDenied(_) + | ExecutionFailureCode::ModuleUnavailable { .. } => false, } } @@ -213,6 +246,12 @@ impl ExecutionFailureCode { ExecutionFailureCode::ExpirationReached(bound) => { serde_json::to_value(BoundMeta { bound: *bound }) } + ExecutionFailureCode::ModuleDenied(denial) => serde_json::to_value(denial), + ExecutionFailureCode::ModuleUnavailable { module } => { + serde_json::to_value(ModuleMeta { + module: module.clone(), + }) + } ExecutionFailureCode::BindingMismatch | ExecutionFailureCode::StateMismatch | ExecutionFailureCode::RequestCodec @@ -287,6 +326,12 @@ impl ExecutionFailureCode { "GUARDIAN_EXECUTION_EXPIRED" => ExecutionFailureCode::Expired, "GUARDIAN_EXECUTION_LEASE_EXPIRED" => ExecutionFailureCode::LeaseExpired, "GUARDIAN_EXECUTION_ABANDONED" => ExecutionFailureCode::Abandoned, + "GUARDIAN_EXECUTION_MODULE_DENIED" => { + ExecutionFailureCode::ModuleDenied(required::(code, meta)?) + } + "GUARDIAN_EXECUTION_MODULE_UNAVAILABLE" => ExecutionFailureCode::ModuleUnavailable { + module: required::(code, meta)?.module, + }, other => return Err(format!("unknown execution failure code '{other}'")), }) } @@ -305,6 +350,39 @@ mod tests { assert!(!ExecutionFailureCode::LeaseExpired.ends_proposal()); } + #[test] + fn module_refusals_round_trip_with_their_meta_and_keep_the_proposal() { + let full = ExecutionFailureCode::ModuleDenied(ModuleDenial { + module: Some("caps".into()), + reason_code: "amount_cap_exceeded".into(), + layer: Some("account".into()), + client_message: Some("over the daily cap".into()), + }); + let generic = ExecutionFailureCode::ModuleDenied(ModuleDenial { + module: None, + reason_code: "policy_denied".into(), + layer: None, + client_message: None, + }); + let unavailable = ExecutionFailureCode::ModuleUnavailable { + module: "caps".into(), + }; + assert_eq!( + generic.meta(), + Some(serde_json::json!({ "reason_code": "policy_denied" })) + ); + for code in [full, generic, unavailable] { + assert!(!code.ends_proposal()); + assert_eq!( + ExecutionFailureCode::from_parts(code.as_str(), code.meta().as_ref()).unwrap(), + code + ); + } + assert!( + ExecutionFailureCode::from_parts("GUARDIAN_EXECUTION_MODULE_DENIED", None).is_err() + ); + } + #[test] fn the_not_processed_code_round_trips_without_meta() { let code = ExecutionFailureCode::SubmissionNotProcessed; diff --git a/docs/openapi-client.json b/docs/openapi-client.json index 975884db..700cde74 100644 --- a/docs/openapi-client.json +++ b/docs/openapi-client.json @@ -984,6 +984,128 @@ ] } }, + "/delta/proposal/check": { + "post": { + "tags": [ + "client" + ], + "summary": "Dry run of `POST /delta/proposal`: the same checks and proposal-creation\npolicy modules, without storing a proposal or taking a slot. A refusal is\nthe same error proposal creation returns; `complete` is false when a module\nthat opts out of dry runs was skipped. Advisory: approval still decides.\nRate limited per account and signer (`GUARDIAN_MODULE_CHECK_RATE_PER_MIN`).", + "operationId": "check_delta_proposal", + "parameters": [ + { + "name": "x-auth-format", + "in": "header", + "description": "Optional ECDSA request format: eip712; omitted for raw signatures", + "required": false, + "schema": { + "type": [ + "string", + "null" + ] + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DeltaProposalRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Proposal creation would pass", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CheckProposalResponse" + } + } + } + }, + "400": { + "description": "Invalid proposal payload", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication failed or replay rejected", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "403": { + "description": "A policy module refused (GUARDIAN_MODULE_DENIED)", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "409": { + "description": "Conflicting / too many pending proposals", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "413": { + "description": "Request body exceeds the configured size limit", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "429": { + "description": "Too many checks for this account and signer", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "503": { + "description": "A policy module is unavailable (GUARDIAN_MODULE_UNAVAILABLE)", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + }, + "security": [ + { + "x-pubkey": [], + "x-signature": [], + "x-timestamp": [] + } + ] + } + }, "/delta/proposal/execution": { "get": { "tags": [ @@ -1391,6 +1513,86 @@ ] } }, + "/policies": { + "get": { + "tags": [ + "client" + ], + "summary": "The policy modules that apply to the account, as far as each module's\ncatalog entry discloses them (RFC 0002 section 2.7), in evaluation order.\nEmpty when the Guardian has no modules or discloses none.", + "operationId": "get_policies", + "parameters": [ + { + "name": "account_id", + "in": "query", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "x-auth-format", + "in": "header", + "description": "Optional ECDSA request format: eip712; omitted for raw signatures", + "required": false, + "schema": { + "type": [ + "string", + "null" + ] + } + } + ], + "responses": { + "200": { + "description": "Disclosed policies", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PoliciesResponse" + } + } + } + }, + "401": { + "description": "Authentication failed or replay rejected", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "413": { + "description": "Request body exceeds the configured size limit", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "429": { + "description": "Rate limit exceeded", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + }, + "security": [ + { + "x-pubkey": [], + "x-signature": [], + "x-timestamp": [] + } + ] + } + }, "/pubkey": { "get": { "tags": [ @@ -2363,6 +2565,23 @@ } } }, + "CheckProposalResponse": { + "type": "object", + "required": [ + "allowed", + "complete" + ], + "properties": { + "allowed": { + "type": "boolean", + "description": "Always true: a refusal is returned as an error." + }, + "complete": { + "type": "boolean", + "description": "False when a module that opts out of dry runs was skipped." + } + } + }, "ConfigureRequest": { "type": "object", "required": [ @@ -3402,6 +3621,61 @@ } } }, + "PoliciesResponse": { + "type": "object", + "required": [ + "account_id", + "policies" + ], + "properties": { + "account_id": { + "type": "string" + }, + "policies": { + "type": "array", + "items": { + "$ref": "#/components/schemas/PolicyEntry" + } + } + } + }, + "PolicyEntry": { + "type": "object", + "description": "One policy as the account's cosigners see it.", + "required": [ + "module_id", + "hooks", + "description" + ], + "properties": { + "account_layer": { + "type": [ + "object", + "null" + ], + "description": "`disclosure = \"params\"` on a `scope = all` instance: this account's layer, when set." + }, + "description": { + "type": "string" + }, + "hooks": { + "type": "array", + "items": { + "type": "string" + } + }, + "module_id": { + "type": "string" + }, + "params": { + "type": [ + "object", + "null" + ], + "description": "`disclosure = \"params\"`: the instance's global params, or the account's own params for\nan assigned instance." + } + } + }, "ProposalMetadata": { "type": "object", "description": "Operator-stated intent lifted from a matching proposal.\nThe fields that bind a proposal to a block (`bound_block_num`, and the\nlegacy `chain_anchor`) remain only in the proposal payload, to avoid\nduplicating them in delta metadata and dashboard listings.", diff --git a/docs/openapi.json b/docs/openapi.json index f659036e..0279d5ec 100644 --- a/docs/openapi.json +++ b/docs/openapi.json @@ -2508,6 +2508,128 @@ ] } }, + "/delta/proposal/check": { + "post": { + "tags": [ + "client" + ], + "summary": "Dry run of `POST /delta/proposal`: the same checks and proposal-creation\npolicy modules, without storing a proposal or taking a slot. A refusal is\nthe same error proposal creation returns; `complete` is false when a module\nthat opts out of dry runs was skipped. Advisory: approval still decides.\nRate limited per account and signer (`GUARDIAN_MODULE_CHECK_RATE_PER_MIN`).", + "operationId": "check_delta_proposal", + "parameters": [ + { + "name": "x-auth-format", + "in": "header", + "description": "Optional ECDSA request format: eip712; omitted for raw signatures", + "required": false, + "schema": { + "type": [ + "string", + "null" + ] + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DeltaProposalRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Proposal creation would pass", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CheckProposalResponse" + } + } + } + }, + "400": { + "description": "Invalid proposal payload", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication failed or replay rejected", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "403": { + "description": "A policy module refused (GUARDIAN_MODULE_DENIED)", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "409": { + "description": "Conflicting / too many pending proposals", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "413": { + "description": "Request body exceeds the configured size limit", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "429": { + "description": "Too many checks for this account and signer", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "503": { + "description": "A policy module is unavailable (GUARDIAN_MODULE_UNAVAILABLE)", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + }, + "security": [ + { + "x-pubkey": [], + "x-signature": [], + "x-timestamp": [] + } + ] + } + }, "/delta/proposal/execution": { "get": { "tags": [ @@ -3723,6 +3845,86 @@ ] } }, + "/policies": { + "get": { + "tags": [ + "client" + ], + "summary": "The policy modules that apply to the account, as far as each module's\ncatalog entry discloses them (RFC 0002 section 2.7), in evaluation order.\nEmpty when the Guardian has no modules or discloses none.", + "operationId": "get_policies", + "parameters": [ + { + "name": "account_id", + "in": "query", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "x-auth-format", + "in": "header", + "description": "Optional ECDSA request format: eip712; omitted for raw signatures", + "required": false, + "schema": { + "type": [ + "string", + "null" + ] + } + } + ], + "responses": { + "200": { + "description": "Disclosed policies", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PoliciesResponse" + } + } + } + }, + "401": { + "description": "Authentication failed or replay rejected", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "413": { + "description": "Request body exceeds the configured size limit", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "429": { + "description": "Rate limit exceeded", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + }, + "security": [ + { + "x-pubkey": [], + "x-signature": [], + "x-timestamp": [] + } + ] + } + }, "/pubkey": { "get": { "tags": [ @@ -4769,6 +4971,23 @@ } } }, + "CheckProposalResponse": { + "type": "object", + "required": [ + "allowed", + "complete" + ], + "properties": { + "allowed": { + "type": "boolean", + "description": "Always true: a refusal is returned as an error." + }, + "complete": { + "type": "boolean", + "description": "False when a module that opts out of dry runs was skipped." + } + } + }, "ConfigureRequest": { "type": "object", "required": [ @@ -7879,6 +8098,61 @@ } } }, + "PoliciesResponse": { + "type": "object", + "required": [ + "account_id", + "policies" + ], + "properties": { + "account_id": { + "type": "string" + }, + "policies": { + "type": "array", + "items": { + "$ref": "#/components/schemas/PolicyEntry" + } + } + } + }, + "PolicyEntry": { + "type": "object", + "description": "One policy as the account's cosigners see it.", + "required": [ + "module_id", + "hooks", + "description" + ], + "properties": { + "account_layer": { + "type": [ + "object", + "null" + ], + "description": "`disclosure = \"params\"` on a `scope = all` instance: this account's layer, when set." + }, + "description": { + "type": "string" + }, + "hooks": { + "type": "array", + "items": { + "type": "string" + } + }, + "module_id": { + "type": "string" + }, + "params": { + "type": [ + "object", + "null" + ], + "description": "`disclosure = \"params\"`: the instance's global params, or the account's own params for\nan assigned instance." + } + } + }, "ProposalMetadata": { "type": "object", "description": "Operator-stated intent lifted from a matching proposal.\nThe fields that bind a proposal to a block (`bound_block_num`, and the\nlegacy `chain_anchor`) remain only in the proposal payload, to avoid\nduplicating them in delta metadata and dashboard listings.", diff --git a/examples/_shared/multisig-browser/src/multisigApi.ts b/examples/_shared/multisig-browser/src/multisigApi.ts index a35fc9ab..1b88fafb 100644 --- a/examples/_shared/multisig-browser/src/multisigApi.ts +++ b/examples/_shared/multisig-browser/src/multisigApi.ts @@ -416,6 +416,10 @@ function failedExecutionAdvice(error: ExecutionFailure): string { case 'GUARDIAN_EXECUTION_CANDIDATE_DISCARDED': case 'GUARDIAN_EXECUTION_EXPIRED': return 'The transaction was sent and did not land: create and sign a new proposal.'; + case 'GUARDIAN_EXECUTION_MODULE_DENIED': + return 'A GUARDIAN policy refused the transaction: it cannot be executed as it stands.'; + case 'GUARDIAN_EXECUTION_MODULE_UNAVAILABLE': + return 'A GUARDIAN policy module could not decide: execute it again shortly.'; default: { const unreachable: never = error; throw new Error(`Unknown execution failure: ${JSON.stringify(unreachable)}`); diff --git a/examples/demo/src/actions/proposal_management.rs b/examples/demo/src/actions/proposal_management.rs index 62a4f8ee..e34f3871 100644 --- a/examples/demo/src/actions/proposal_management.rs +++ b/examples/demo/src/actions/proposal_management.rs @@ -594,7 +594,7 @@ async fn action_execute_proposal( /// What the caller can do after a failed execution. Follows the failure code: whether the /// proposal is still stored does not say whether executing it again can succeed. -fn failed_execution_advice(code: ExecutionFailureCode) -> &'static str { +fn failed_execution_advice(code: &ExecutionFailureCode) -> &'static str { match code { ExecutionFailureCode::ChainBehind | ExecutionFailureCode::NodeUnavailable @@ -639,6 +639,12 @@ fn failed_execution_advice(code: ExecutionFailureCode) -> &'static str { | ExecutionFailureCode::Expired => { "The transaction was sent and did not land: create and sign a new proposal." } + ExecutionFailureCode::ModuleDenied(_) => { + "A GUARDIAN policy refused the transaction: it cannot be executed as it stands." + } + ExecutionFailureCode::ModuleUnavailable { .. } => { + "A GUARDIAN policy module could not decide: execute it again shortly." + } } } @@ -693,7 +699,7 @@ async fn execute_through_guardian( } ExecutionState::Failed => { if let Some(error) = &finished.error { - print_info(failed_execution_advice(error.code)); + print_info(failed_execution_advice(&error.code)); } Err("GUARDIAN could not execute the proposal".to_string()) } diff --git a/packages/guardian-client/src/execution.test.ts b/packages/guardian-client/src/execution.test.ts index f9a0e2f1..b0bc5371 100644 --- a/packages/guardian-client/src/execution.test.ts +++ b/packages/guardian-client/src/execution.test.ts @@ -12,6 +12,7 @@ import { fromServerExecution, fromServerExecutionCapability, isTerminalExecutionState, + type ServerExecutionError, type ServerProposalExecution, } from './execution.js'; @@ -112,6 +113,40 @@ describe('fromServerExecution', () => { expect(() => fromServerExecution(envelope({ state: 'failed' }))).toThrow(); }); + it('decodes module refusals, a generic denial included, and refuses one without its meta', () => { + const failed = (error: ServerExecutionError) => + fromServerExecution(envelope({ state: 'failed', error })).error; + expect( + failed({ + code: 'GUARDIAN_EXECUTION_MODULE_DENIED', + message: 'denied', + meta: { module: 'caps', reason_code: 'amount_cap_exceeded', layer: 'account', client_message: 'over the cap' }, + }) + ).toEqual({ + code: 'GUARDIAN_EXECUTION_MODULE_DENIED', + message: 'denied', + module: 'caps', + reasonCode: 'amount_cap_exceeded', + layer: 'account', + clientMessage: 'over the cap', + }); + expect( + failed({ code: 'GUARDIAN_EXECUTION_MODULE_DENIED', message: 'denied', meta: { reason_code: 'policy_denied' } }) + ).toEqual({ + code: 'GUARDIAN_EXECUTION_MODULE_DENIED', + message: 'denied', + module: null, + reasonCode: 'policy_denied', + layer: null, + clientMessage: null, + }); + expect( + failed({ code: 'GUARDIAN_EXECUTION_MODULE_UNAVAILABLE', message: 'down', meta: { module: 'caps' } }) + ).toEqual({ code: 'GUARDIAN_EXECUTION_MODULE_UNAVAILABLE', message: 'down', module: 'caps' }); + expect(() => failed({ code: 'GUARDIAN_EXECUTION_MODULE_DENIED', message: 'denied' })).toThrow(); + expect(() => failed({ code: 'GUARDIAN_EXECUTION_MODULE_UNAVAILABLE', message: 'down', meta: {} })).toThrow(); + }); + it('maps nothing in flight and an absent nonce to null', () => { expect(fromServerExecution(envelope({})).deltaNonce).toBeNull(); expect(fromServerExecution(envelope({ delta_nonce: 4 })).deltaNonce).toBe(4); diff --git a/packages/guardian-client/src/execution.ts b/packages/guardian-client/src/execution.ts index 35d48c77..976f3252 100644 --- a/packages/guardian-client/src/execution.ts +++ b/packages/guardian-client/src/execution.ts @@ -89,6 +89,24 @@ export type ExecutionFailure = message: string; reason: ForeignAccountUnavailableReason; } + | { + /** A GUARDIAN policy module refused the acknowledgement; the proposal stays stored. */ + code: 'GUARDIAN_EXECUTION_MODULE_DENIED'; + message: string; + /** The denying instance; `null` for a generic denial, which reports only `policy_denied`. */ + module: string | null; + reasonCode: string; + /** `global` or `account`; `null` for a generic denial. */ + layer: string | null; + /** The module's text for the requester, when the instance allows it. */ + clientMessage: string | null; + } + | { + /** A fail-closed GUARDIAN policy module could not decide; requesting again may succeed. */ + code: 'GUARDIAN_EXECUTION_MODULE_UNAVAILABLE'; + message: string; + module: string; + } | { code: PlainExecutionFailureCode; message: string }; export type ExecutionFailureCode = ExecutionFailure['code']; @@ -98,6 +116,8 @@ export const EXECUTION_FAILURE_CODES: readonly ExecutionFailureCode[] = [ 'GUARDIAN_EXECUTION_REQUEST_INVALID', 'GUARDIAN_EXECUTION_EXPIRATION_REACHED', 'GUARDIAN_EXECUTION_FOREIGN_ACCOUNT_UNAVAILABLE', + 'GUARDIAN_EXECUTION_MODULE_DENIED', + 'GUARDIAN_EXECUTION_MODULE_UNAVAILABLE', ]; /** One execution of a proposal, identified by `(accountId, proposalId)`. */ @@ -167,6 +187,17 @@ export function fromServerExecutionCapability(server: ServerExecutionCapabilityW throw new Error(`Guardian returned an execution capability without a boolean enabled: ${JSON.stringify(server.enabled)}`); } +function requiredString(value: unknown, what: string): string { + if (typeof value === 'string') { + return value; + } + throw new Error(`Guardian returned a malformed ${what}: ${JSON.stringify(value)}`); +} + +function optionalString(value: unknown, what: string): string | null { + return value === undefined ? null : requiredString(value, what); +} + function fromServerFailure(error: ServerExecutionError): ExecutionFailure { const { code, message, meta } = error; switch (code) { @@ -180,6 +211,17 @@ function fromServerFailure(error: ServerExecutionError): ExecutionFailure { message, reason: member(FOREIGN_ACCOUNT_UNAVAILABLE_REASONS, meta?.reason, 'foreign account reason'), }; + case 'GUARDIAN_EXECUTION_MODULE_DENIED': + return { + code, + message, + module: optionalString(meta?.module, 'denying module'), + reasonCode: requiredString(meta?.reason_code, 'module reason code'), + layer: optionalString(meta?.layer, 'module layer'), + clientMessage: optionalString(meta?.client_message, 'module client message'), + }; + case 'GUARDIAN_EXECUTION_MODULE_UNAVAILABLE': + return { code, message, module: requiredString(meta?.module, 'unavailable module') }; default: return { code: member(PLAIN_EXECUTION_FAILURE_CODES, code, 'execution failure code'), message }; } From 0b1c31b8944edeb5b5ef18b07eeb4d1f7344d62e Mon Sep 17 00:00:00 2001 From: Zeljko Date: Mon, 9 Nov 2026 09:03:24 +0100 Subject: [PATCH 004/105] feat(clients): typed policy module refusals and policy discovery (#251) guardian-client (Rust): ModuleRefusal and ClientError::module_refusal, check_delta_proposal and get_policies. miden-multisig-client (Rust): MultisigError::ModuleDenied and ModuleUnavailable kept typed on proposal creation, push and registration, MultisigClient::get_policies and ProposalBuilder::check. @openzeppelin/guardian-client: module meta fields, GuardianHttpError.moduleRefusal(), checkDeltaProposal and getPolicies. ModuleRefusal re-exported from the TypeScript multisig package. Carried from the prototype (#554). --- crates/client/proto/guardian.proto | 45 ++++++ crates/client/src/client.rs | 56 ++++++- crates/client/src/error.rs | 117 +++++++++++++++ crates/client/src/execution.rs | 2 +- crates/client/src/lib.rs | 4 +- crates/client/src/testing/client_tests.rs | 40 +++++ crates/client/src/testing/mocks.rs | 75 +++++++-- .../src/client/account.rs | 4 +- .../src/client/helpers.rs | 2 +- .../miden-multisig-client/src/client/mod.rs | 2 +- .../src/client/proposals.rs | 90 ++++++++++- crates/miden-multisig-client/src/error.rs | 96 ++++++++++-- crates/miden-multisig-client/src/lib.rs | 14 +- .../src/transaction/builder.rs | 139 ++++++++++++----- .../src/transaction/mod.rs | 2 +- packages/guardian-client/src/conversion.ts | 12 ++ packages/guardian-client/src/http.test.ts | 142 ++++++++++++++++++ packages/guardian-client/src/http.ts | 97 ++++++++++++ packages/guardian-client/src/index.ts | 4 +- packages/guardian-client/src/server-types.ts | 18 +++ packages/guardian-client/src/types.ts | 23 +++ packages/miden-multisig-client/src/index.ts | 2 +- 22 files changed, 899 insertions(+), 87 deletions(-) diff --git a/crates/client/proto/guardian.proto b/crates/client/proto/guardian.proto index 424b5059..f71363d5 100644 --- a/crates/client/proto/guardian.proto +++ b/crates/client/proto/guardian.proto @@ -80,6 +80,17 @@ service Guardian { // x-timestamp), raw or as EIP-712 typed data (`x-auth-format: eip712`). // Wallet-only. Mirror of HTTP POST /session/revoke-all. rpc RevokeAllSessions(RevokeAllSessionsRequest) returns (RevokeAllSessionsResponse); + + // The policy modules that apply to the account, as far as each instance's + // catalog entry discloses them (RFC 0002 section 2.7). Mirror of HTTP + // GET /policies. + rpc GetPolicies(GetPoliciesRequest) returns (GetPoliciesResponse); + + // Dry run of PushDeltaProposal: the same checks and proposal-creation + // modules, nothing stored, no proposal slot taken. Advisory; approval still + // decides. Rate limited per account and signer. Mirror of HTTP + // POST /delta/proposal/check. + rpc CheckDeltaProposal(CheckDeltaProposalRequest) returns (CheckDeltaProposalResponse); } // Auth configuration - one of the auth types @@ -289,6 +300,40 @@ message PushDeltaProposalResponse { string commitment = 4; } +message CheckDeltaProposalRequest { + string account_id = 1; + uint64 nonce = 2; + string delta_payload = 3; // JSON string, as for PushDeltaProposal +} + +message CheckDeltaProposalResponse { + bool success = 1; + string message = 2; + bool allowed = 3; // true on success; a refusal is returned as an error status + bool complete = 4; // false when an instance that opts out of dry runs was skipped + string error_code = 5; +} + +message GetPoliciesRequest { + string account_id = 1; +} + +message PolicyEntry { + string module_id = 1; + repeated string hooks = 2; + string description = 3; + optional string params = 4; // JSON object; only where the instance discloses params + optional string account_layer = 5; // JSON object; this account's layer, where disclosed +} + +message GetPoliciesResponse { + bool success = 1; + string message = 2; + string account_id = 3; + repeated PolicyEntry policies = 4; // evaluation order + string error_code = 5; +} + // Get delta proposals request message GetDeltaProposalsRequest { string account_id = 1; diff --git a/crates/client/src/client.rs b/crates/client/src/client.rs index b7eb627c..d221787b 100644 --- a/crates/client/src/client.rs +++ b/crates/client/src/client.rs @@ -4,14 +4,16 @@ use crate::execution::ProposalExecution; use crate::keystore::Signer; use crate::proto::guardian_client::GuardianClient as GuardianGrpcClient; use crate::proto::{ - AbandonDeltaCandidateRequest, AbandonDeltaCandidateResponse, AuthConfig, ConfigureRequest, - ConfigureResponse, ExecuteDeltaProposalRequest, GetAccountByKeyCommitmentRequest, + AbandonDeltaCandidateRequest, AbandonDeltaCandidateResponse, AuthConfig, + CheckDeltaProposalRequest, CheckDeltaProposalResponse, ConfigureRequest, ConfigureResponse, + ExecuteDeltaProposalRequest, GetAccountByKeyCommitmentRequest, GetAccountByKeyCommitmentResponse, GetCanonicalNonceRequest, GetCanonicalNonceResponse, GetCurrentExecutionRequest, GetDeltaHistoryRequest, GetDeltaHistoryResponse, GetDeltaProposalExecutionRequest, GetDeltaProposalRequest, GetDeltaProposalResponse, GetDeltaProposalsRequest, GetDeltaProposalsResponse, GetDeltaRequest, GetDeltaResponse, - GetDeltaSinceRequest, GetDeltaSinceResponse, GetPubkeyRequest, GetStateRequest, - GetStateResponse, ProposalSignature as ProtoProposalSignature, PushDeltaProposalRequest, + GetDeltaSinceRequest, GetDeltaSinceResponse, GetPoliciesRequest, GetPoliciesResponse, + GetPubkeyRequest, GetStateRequest, GetStateResponse, + ProposalSignature as ProtoProposalSignature, PushDeltaProposalRequest, PushDeltaProposalResponse, PushDeltaRequest, PushDeltaResponse, RevokeAllSessionsRequest, RevokeSessionRequest, SessionGrantFields, SignDeltaProposalRequest, SignDeltaProposalResponse, }; @@ -827,6 +829,52 @@ impl GuardianClient { Ok(inner) } + /// Dry run of [`Self::push_delta_proposal`]: the same checks and proposal-creation policy + /// modules, without storing a proposal. A module refusal is the same typed error proposal + /// creation returns; `complete` is false when a module that opts out of dry runs was + /// skipped. Advisory: approval still decides. + pub async fn check_delta_proposal( + &mut self, + account_id: &AccountId, + nonce: u64, + delta_payload: impl serde::Serialize, + ) -> ClientResult { + let message = CheckDeltaProposalRequest { + account_id: account_id.to_string(), + nonce, + delta_payload: serde_json::to_string(&delta_payload)?, + }; + let inner = self + .send_allowing_session(account_id, message, async |client, request| { + client.check_delta_proposal(request).await + }) + .await?; + if !inner.success { + return Err(ClientError::ServerError(inner.message.clone())); + } + Ok(inner) + } + + /// The policy modules that apply to the account, as far as the Guardian's operator + /// discloses them, in evaluation order. `params` and `account_layer` are JSON objects. + pub async fn get_policies( + &mut self, + account_id: &AccountId, + ) -> ClientResult { + let message = GetPoliciesRequest { + account_id: account_id.to_string(), + }; + let inner = self + .send_allowing_session(account_id, message, async |client, request| { + client.get_policies(request).await + }) + .await?; + if !inner.success { + return Err(ClientError::ServerError(inner.message.clone())); + } + Ok(inner) + } + /// Get all delta proposals for an account pub async fn get_delta_proposals( &mut self, diff --git a/crates/client/src/error.rs b/crates/client/src/error.rs index ab51bb7d..0b43200d 100644 --- a/crates/client/src/error.rs +++ b/crates/client/src/error.rs @@ -17,6 +17,31 @@ pub const SESSION_REVOKED_CODE: &str = "session_revoked"; pub const WALLET_SIGNATURE_REQUIRED_CODE: &str = "wallet_signature_required"; const AUTHENTICATION_FAILED_CODE: &str = "authentication_failed"; +/// A policy module refused the request. +pub const MODULE_DENIED_CODE: &str = "GUARDIAN_MODULE_DENIED"; + +/// A fail-closed policy module could not decide; retryable. +pub const MODULE_UNAVAILABLE_CODE: &str = "GUARDIAN_MODULE_UNAVAILABLE"; + +/// A refusal by one of the Guardian's policy modules. `module` is the operator-chosen +/// instance id. +#[derive(Debug, Clone, PartialEq, Eq)] +pub enum ModuleRefusal { + /// A generic denial (an instance with `client_reason = "generic"`) carries only the reason + /// code `policy_denied`: no module, no layer and no message. + Denied { + module: Option, + reason_code: String, + /// `global` or `account`: which parameter layer denied, when the server says. + layer: Option, + /// The module's text for the requester, when the instance allows it. + client_message: Option, + }, + Unavailable { + module: String, + }, +} + /// Errors that can occur when using the GUARDIAN client. #[derive(Debug, Error)] pub enum ClientError { @@ -149,6 +174,26 @@ impl ClientError { ) } + /// The policy module refusal this error carries, if any. A denial is final; an + /// unavailable module is retryable ([`Self::is_retryable`]). + pub fn module_refusal(&self) -> Option { + let code = self.guardian_code()?; + let meta = self.guardian_meta()?; + let field = |name: &str| meta.get(name)?.as_str().map(str::to_owned); + match code.as_str() { + MODULE_DENIED_CODE => Some(ModuleRefusal::Denied { + module: field("module"), + reason_code: field("reason_code")?, + layer: field("layer"), + client_message: field("client_message"), + }), + MODULE_UNAVAILABLE_CODE => Some(ModuleRefusal::Unavailable { + module: field("module")?, + }), + _ => None, + } + } + /// Server-provided backoff hint: the `retry-after` status metadata /// (decimal seconds), falling back to `meta.retry_after_secs`. /// Unparseable values mean no hint; classification is unaffected. @@ -197,6 +242,78 @@ mod tests { assert!(!err.is_not_found()); } + fn module_status(code: tonic::Code, details: serde_json::Value) -> ClientError { + tonic::Status::with_details(code, "refused", details.to_string().into_bytes().into()).into() + } + + #[test] + fn module_denial_is_typed_and_final() { + let err = module_status( + tonic::Code::PermissionDenied, + serde_json::json!({ + "code": "GUARDIAN_MODULE_DENIED", + "message": "This Guardian's policy doesn't allow this request.", + "meta": { "retryable": false, "module": "caps", "reason_code": "amount_cap_exceeded", "layer": "account" } + }), + ); + assert_eq!( + err.module_refusal(), + Some(ModuleRefusal::Denied { + module: Some("caps".into()), + reason_code: "amount_cap_exceeded".into(), + layer: Some("account".into()), + client_message: None, + }) + ); + assert!(!err.is_retryable()); + } + + #[test] + fn generic_denial_is_typed_without_details() { + let err = module_status( + tonic::Code::PermissionDenied, + serde_json::json!({ + "code": "GUARDIAN_MODULE_DENIED", + "message": "This Guardian's policy doesn't allow this request.", + "meta": { "retryable": false, "reason_code": "policy_denied" } + }), + ); + assert_eq!( + err.module_refusal(), + Some(ModuleRefusal::Denied { + module: None, + reason_code: "policy_denied".into(), + layer: None, + client_message: None, + }) + ); + } + + #[test] + fn module_unavailable_is_typed_and_retryable() { + let err = module_status( + tonic::Code::Unavailable, + serde_json::json!({ + "code": "GUARDIAN_MODULE_UNAVAILABLE", + "message": "A policy check is unavailable right now. Please try again shortly.", + "meta": { "retryable": true, "module": "sanctions" } + }), + ); + assert_eq!( + err.module_refusal(), + Some(ModuleRefusal::Unavailable { + module: "sanctions".into() + }) + ); + assert!(err.is_retryable()); + } + + #[test] + fn other_errors_are_not_module_refusals() { + let err: ClientError = guardian_status().into(); + assert_eq!(err.module_refusal(), None); + } + #[test] fn user_message_is_none_without_structured_details() { // A bare Status.message may be developer-facing (e.g. pre-service diff --git a/crates/client/src/execution.rs b/crates/client/src/execution.rs index 1491665e..feddc829 100644 --- a/crates/client/src/execution.rs +++ b/crates/client/src/execution.rs @@ -2,7 +2,7 @@ pub use guardian_shared::execution::{ ExecutionFailureCode, ExecutionState, ExpirationBound, ForeignAccountUnavailableReason, - RequestInvalidReason, + ModuleDenial, RequestInvalidReason, }; use crate::error::{ClientError, ClientResult}; diff --git a/crates/client/src/lib.rs b/crates/client/src/lib.rs index 92110c8b..88dbab9b 100644 --- a/crates/client/src/lib.rs +++ b/crates/client/src/lib.rs @@ -56,8 +56,8 @@ pub use client::{ GuardianClient, MAX_SESSION_TTL, MIN_SESSION_TTL, SessionInfo, SessionSlot, StartSessionOptions, }; pub use error::{ - ClientError, ClientResult, SESSION_EXPIRED_CODE, SESSION_REVOKED_CODE, - WALLET_SIGNATURE_REQUIRED_CODE, + ClientError, ClientResult, MODULE_DENIED_CODE, MODULE_UNAVAILABLE_CODE, ModuleRefusal, + SESSION_EXPIRED_CODE, SESSION_REVOKED_CODE, WALLET_SIGNATURE_REQUIRED_CODE, }; pub use execution::{ExecutionFailure, ExecutionState, ProposalExecution}; pub use keystore::{EcdsaKeyStore, FalconKeyStore, Signer, verify_commitment_signature}; diff --git a/crates/client/src/testing/client_tests.rs b/crates/client/src/testing/client_tests.rs index 3ad325b1..64f85019 100644 --- a/crates/client/src/testing/client_tests.rs +++ b/crates/client/src/testing/client_tests.rs @@ -651,6 +651,46 @@ async fn terminal_authentication_failure_is_not_retried() { assert!(!error.is_replay_rejection()); } +#[tokio::test] +async fn policies_and_proposal_checks_round_trip() { + let service = MockGuardianService::default(); + let handle = service.handle(); + let endpoint = start_mock_server(service).await.unwrap(); + let mut client = GuardianClient::connect(endpoint) + .await + .unwrap() + .with_signer(create_test_signer()); + let account_id = create_test_account_id(); + + let policies = client.get_policies(&account_id).await.unwrap(); + assert_eq!(policies.policies[0].module_id, "caps"); + assert!(policies.policies[0].params.is_some()); + + let passed = client + .check_delta_proposal(&account_id, 1, serde_json::json!({ "tx_summary": {} })) + .await + .unwrap(); + assert!(passed.allowed); + assert!(!passed.complete); + + let refused = client + .check_delta_proposal(&account_id, 0, serde_json::json!({ "tx_summary": {} })) + .await + .unwrap_err(); + assert!(matches!( + refused.module_refusal(), + Some(crate::ModuleRefusal::Denied { module: None, ref reason_code, .. }) if reason_code == "policy_denied" + )); + assert_eq!( + handle.calls(), + vec![ + "get_policies", + "check_delta_proposal", + "check_delta_proposal" + ] + ); +} + #[tokio::test] async fn test_get_canonical_nonce_success() { let service = diff --git a/crates/client/src/testing/mocks.rs b/crates/client/src/testing/mocks.rs index 352b054d..ddef3079 100644 --- a/crates/client/src/testing/mocks.rs +++ b/crates/client/src/testing/mocks.rs @@ -1,18 +1,19 @@ use crate::proto::guardian_server::{Guardian, GuardianServer}; use crate::proto::{ - AbandonDeltaCandidateRequest, AbandonDeltaCandidateResponse, AccountState, ConfigureRequest, - ConfigureResponse, CreateSessionRequest, CreateSessionResponse, - DeltaObject as ProtoDeltaObject, ExecuteDeltaProposalRequest, ExecuteDeltaProposalResponse, - ExecutionEnvelope, GetAccountByKeyCommitmentRequest, GetAccountByKeyCommitmentResponse, - GetCanonicalNonceRequest, GetCanonicalNonceResponse, GetCurrentExecutionRequest, - GetCurrentExecutionResponse, GetDeltaHistoryRequest, GetDeltaHistoryResponse, - GetDeltaProposalExecutionRequest, GetDeltaProposalExecutionResponse, GetDeltaProposalRequest, - GetDeltaProposalResponse, GetDeltaProposalsRequest, GetDeltaProposalsResponse, GetDeltaRequest, - GetDeltaResponse, GetDeltaSinceRequest, GetDeltaSinceResponse, GetPubkeyRequest, - GetStateRequest, GetStateResponse, PushDeltaProposalRequest, PushDeltaProposalResponse, - PushDeltaRequest, PushDeltaResponse, RevokeAllSessionsRequest, RevokeAllSessionsResponse, - RevokeSessionRequest, RevokeSessionResponse, SignDeltaProposalRequest, - SignDeltaProposalResponse, + AbandonDeltaCandidateRequest, AbandonDeltaCandidateResponse, AccountState, + CheckDeltaProposalRequest, CheckDeltaProposalResponse, ConfigureRequest, ConfigureResponse, + CreateSessionRequest, CreateSessionResponse, DeltaObject as ProtoDeltaObject, + ExecuteDeltaProposalRequest, ExecuteDeltaProposalResponse, ExecutionEnvelope, + GetAccountByKeyCommitmentRequest, GetAccountByKeyCommitmentResponse, GetCanonicalNonceRequest, + GetCanonicalNonceResponse, GetCurrentExecutionRequest, GetCurrentExecutionResponse, + GetDeltaHistoryRequest, GetDeltaHistoryResponse, GetDeltaProposalExecutionRequest, + GetDeltaProposalExecutionResponse, GetDeltaProposalRequest, GetDeltaProposalResponse, + GetDeltaProposalsRequest, GetDeltaProposalsResponse, GetDeltaRequest, GetDeltaResponse, + GetDeltaSinceRequest, GetDeltaSinceResponse, GetPoliciesRequest, GetPoliciesResponse, + GetPubkeyRequest, GetStateRequest, GetStateResponse, PolicyEntry, PushDeltaProposalRequest, + PushDeltaProposalResponse, PushDeltaRequest, PushDeltaResponse, RevokeAllSessionsRequest, + RevokeAllSessionsResponse, RevokeSessionRequest, RevokeSessionResponse, + SignDeltaProposalRequest, SignDeltaProposalResponse, }; use guardian_shared::FromJson; use miden_protocol::account::Account; @@ -719,6 +720,54 @@ impl Guardian for MockGuardianService { response.map(Response::new) } + async fn check_delta_proposal( + &self, + request: Request, + ) -> Result, Status> { + self.record_call("check_delta_proposal"); + if request.get_ref().nonce == 0 { + return Err(Status::with_details( + tonic::Code::PermissionDenied, + "refused", + serde_json::json!({ + "code": "GUARDIAN_MODULE_DENIED", + "message": "This Guardian's policy doesn't allow this request.", + "meta": { "retryable": false, "reason_code": "policy_denied" } + }) + .to_string() + .into_bytes() + .into(), + )); + } + Ok(Response::new(CheckDeltaProposalResponse { + success: true, + message: String::new(), + allowed: true, + complete: false, + error_code: String::new(), + })) + } + + async fn get_policies( + &self, + request: Request, + ) -> Result, Status> { + self.record_call("get_policies"); + Ok(Response::new(GetPoliciesResponse { + success: true, + message: String::new(), + account_id: request.into_inner().account_id, + policies: vec![PolicyEntry { + module_id: "caps".into(), + hooks: vec!["before_transaction_approved".into()], + description: "At most 5 per transaction".into(), + params: Some(r#"{"max_amount_per_tx":{"0xaa":"5"}}"#.into()), + account_layer: None, + }], + error_code: String::new(), + })) + } + async fn get_canonical_nonce( &self, _request: Request, diff --git a/crates/miden-multisig-client/src/client/account.rs b/crates/miden-multisig-client/src/client/account.rs index c6d6b529..e58eb93b 100644 --- a/crates/miden-multisig-client/src/client/account.rs +++ b/crates/miden-multisig-client/src/client/account.rs @@ -292,9 +292,7 @@ impl MultisigClient { guardian_client .configure(&account_id, auth_config, initial_state) .await - .map_err(|e| { - MultisigError::GuardianServer(format!("failed to configure account: {}", e)) - })?; + .map_err(|e| MultisigError::guardian("failed to configure account", e))?; Ok(()) } diff --git a/crates/miden-multisig-client/src/client/helpers.rs b/crates/miden-multisig-client/src/client/helpers.rs index f00e826d..09ab0f51 100644 --- a/crates/miden-multisig-client/src/client/helpers.rs +++ b/crates/miden-multisig-client/src/client/helpers.rs @@ -173,7 +173,7 @@ impl MultisigClient { let push_response = guardian_client .push_delta(&account_id, nonce, &prev_commitment, &delta_payload) .await - .map_err(|e| MultisigError::GuardianServer(format!("failed to push delta: {}", e)))?; + .map_err(|e| MultisigError::guardian("failed to push delta", e))?; // Get GUARDIAN ack signature let ack_sig = push_response.ack_sig.ok_or_else(|| { diff --git a/crates/miden-multisig-client/src/client/mod.rs b/crates/miden-multisig-client/src/client/mod.rs index e08e7eaa..a6bfd131 100644 --- a/crates/miden-multisig-client/src/client/mod.rs +++ b/crates/miden-multisig-client/src/client/mod.rs @@ -56,7 +56,7 @@ pub use note_recovery::{ NoteRecoveryOptions, NoteRecoveryReport, RecoveryStep, RecoveryStepProblem, }; pub use proposal_note_import::{NoteImportOutcome, NoteImportSource, NoteImportStatus}; -pub use proposals::{AbandonRequest, AbandonRequestState, AbandonStatus}; +pub use proposals::{AbandonRequest, AbandonRequestState, AbandonStatus, Policy}; pub use public_note_backfill::{BlockRange, PublicBackfillOptions, PublicBackfillReport}; pub use recovery::{TransportRecoveryReport, TransportRecoveryStatus}; diff --git a/crates/miden-multisig-client/src/client/proposals.rs b/crates/miden-multisig-client/src/client/proposals.rs index fa005d78..289e14ca 100644 --- a/crates/miden-multisig-client/src/client/proposals.rs +++ b/crates/miden-multisig-client/src/client/proposals.rs @@ -10,6 +10,21 @@ use miden_protocol::Word; use super::{MultisigClient, ProposalResult}; +/// A policy GUARDIAN applies to the account, as far as its operator discloses it. +#[derive(Debug, Clone, PartialEq)] +pub struct Policy { + /// The operator-chosen module instance id. + pub module_id: String, + /// The points where it runs, for example `before_proposal_created`. + pub hooks: Vec, + /// The operator's description of the rule. + pub description: String, + /// The rule's parameters, where the operator discloses them. + pub params: Option, + /// This account's own stricter layer on the rule, where disclosed. + pub account_layer: Option, +} + /// Immediate outcome of an abandon request (issue #319). #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub enum AbandonRequestState { @@ -68,8 +83,8 @@ use crate::execution::{ use crate::keystore::{proposal_public_key_hex, word_from_hex}; use crate::proposal::{Proposal, TransactionType, is_builtin_proposal_type}; use crate::transaction::{ - ProposalBuilder, ProposalOptions, deserialize_transaction_request, execute_for_summary_at_tip, - proposal_auth_args, word_to_hex, + ProposalBuilder, ProposalCheck, ProposalOptions, deserialize_transaction_request, + execute_for_summary_at_tip, proposal_auth_args, word_to_hex, }; impl MultisigClient { @@ -341,9 +356,7 @@ impl MultisigClient { let sign_response = guardian_client .sign_delta_proposal(&account_id, proposal_id, signature) .await - .map_err(|e| { - MultisigError::GuardianServer(format!("failed to sign proposal: {}", e)) - })?; + .map_err(|e| MultisigError::guardian("failed to sign proposal", e))?; let updated_raw = sign_response .delta @@ -789,6 +802,73 @@ impl MultisigClient { Ok(proposal) } + /// Asks GUARDIAN whether `transaction_type` would be accepted as a proposal: the + /// transaction is built exactly as [`Self::propose_transaction`] builds it, but nothing is + /// stored and no proposal slot is taken. A policy refusal is the same + /// [`MultisigError::ModuleDenied`] creation returns. Advisory: approval still decides, + /// and GUARDIAN rate limits checks per account and signer. + pub async fn check_transaction( + &mut self, + transaction_type: TransactionType, + ) -> Result { + self.check_transaction_with_options(transaction_type, ProposalOptions::default()) + .await + } + + /// [`Self::check_transaction`] with per-proposal settings. See [`ProposalOptions`]. + pub async fn check_transaction_with_options( + &mut self, + transaction_type: TransactionType, + options: ProposalOptions, + ) -> Result { + self.sync().await?; + let account = self.require_account()?.clone(); + let mut guardian_client = self.create_authenticated_guardian_client().await?; + let node_rpc = self.node_rpc_client(); + ProposalBuilder::new(transaction_type) + .with_options(options) + .check( + &mut self.miden_client, + &node_rpc, + &mut guardian_client, + &account, + self.key_manager.as_ref(), + ) + .await + } + + /// The policies GUARDIAN applies to this account, as far as its operator discloses them, + /// in the order they are evaluated. + pub async fn get_policies(&mut self) -> Result> { + let account_id = self.require_account()?.id(); + let mut guardian_client = self.create_authenticated_guardian_client().await?; + let response = guardian_client + .get_policies(&account_id) + .await + .map_err(|e| MultisigError::guardian("failed to get policies", e))?; + let json = |field: &str, text: Option| -> Result> { + text.map(|text| { + serde_json::from_str(&text).map_err(|e| { + MultisigError::GuardianServer(format!("policy {field} is not JSON: {e}")) + }) + }) + .transpose() + }; + response + .policies + .into_iter() + .map(|policy| { + Ok(Policy { + params: json("params", policy.params)?, + account_layer: json("account_layer", policy.account_layer)?, + module_id: policy.module_id, + hooks: policy.hooks, + description: policy.description, + }) + }) + .collect() + } + /// Proposes a transaction with automatic fallback to offline mode. /// /// First attempts to create the proposal via GUARDIAN. If GUARDIAN is unavailable diff --git a/crates/miden-multisig-client/src/error.rs b/crates/miden-multisig-client/src/error.rs index d03ca0d8..4197b47d 100644 --- a/crates/miden-multisig-client/src/error.rs +++ b/crates/miden-multisig-client/src/error.rs @@ -28,6 +28,22 @@ pub enum MultisigError { #[error("GUARDIAN server error: {0}")] GuardianServer(String), + /// A GUARDIAN policy module refused the request. Final: retrying the same request + /// gets the same answer. + #[error("GUARDIAN policy {}denied the request: {reason_code}{}", module.as_deref().map(|module| format!("module {module} ")).unwrap_or_default(), layer.as_deref().map(|layer| format!(" ({layer} layer)")).unwrap_or_default())] + ModuleDenied { + /// Absent for a generic denial, which reports only `policy_denied`. + module: Option, + reason_code: String, + layer: Option, + /// The module's text for the requester, when the instance allows it. + client_message: Option, + }, + + /// A fail-closed GUARDIAN policy module could not decide. Retryable. + #[error("GUARDIAN policy module {module} is unavailable; try again shortly")] + ModuleUnavailable { module: String }, + /// GUARDIAN refused a Guardian-execution request with a stable code, such as /// `GUARDIAN_PROPOSAL_NOT_READY` or `GUARDIAN_EXECUTION_CONFLICT`. `retryable` is the /// server's `meta.retryable`; `retry_after` is the server's backoff hint, when it sent one; @@ -401,9 +417,36 @@ pub(crate) fn rpc_kind(error: &RpcError) -> Option<&GrpcError> { } } +impl MultisigError { + /// A GUARDIAN call failure with `context`; a policy module refusal keeps its typed variant. + pub(crate) fn guardian(context: &str, err: guardian_client::ClientError) -> Self { + if err.module_refusal().is_some() { + Self::from(err) + } else { + Self::GuardianServer(format!("{context}: {err}")) + } + } +} + impl From for MultisigError { fn from(err: guardian_client::ClientError) -> Self { - MultisigError::GuardianServer(err.to_string()) + match err.module_refusal() { + Some(guardian_client::ModuleRefusal::Denied { + module, + reason_code, + layer, + client_message, + }) => MultisigError::ModuleDenied { + module, + reason_code, + layer, + client_message, + }, + Some(guardian_client::ModuleRefusal::Unavailable { module }) => { + MultisigError::ModuleUnavailable { module } + } + None => MultisigError::GuardianServer(err.to_string()), + } } } @@ -412,6 +455,9 @@ impl MultisigError { /// when GUARDIAN answered with a stable code, else /// [`GuardianServer`](MultisigError::GuardianServer). pub(crate) fn proposal_push(err: guardian_client::ClientError) -> Self { + if err.module_refusal().is_some() { + return Self::from(err); + } match err.guardian_code() { Some(code) => MultisigError::GuardianProposalRefused { message: err.user_message().unwrap_or_else(|| err.to_string()), @@ -474,6 +520,43 @@ mod tests { .into() } + fn guardian_status( + code: tonic::Code, + details: serde_json::Value, + ) -> guardian_client::ClientError { + tonic::Status::with_details(code, "refused", details.to_string().into_bytes().into()).into() + } + + #[test] + fn guardian_module_refusals_keep_module_and_reason() { + let denied = MultisigError::from(guardian_status( + tonic::Code::PermissionDenied, + serde_json::json!({ + "code": "GUARDIAN_MODULE_DENIED", + "message": "denied", + "meta": { "retryable": false, "module": "caps", "reason_code": "amount_cap_exceeded" } + }), + )); + assert!(matches!( + denied, + MultisigError::ModuleDenied { ref module, ref reason_code, .. } + if module.as_deref() == Some("caps") && reason_code == "amount_cap_exceeded" + )); + + let unavailable = MultisigError::from(guardian_status( + tonic::Code::Unavailable, + serde_json::json!({ + "code": "GUARDIAN_MODULE_UNAVAILABLE", + "message": "unavailable", + "meta": { "retryable": true, "module": "sanctions" } + }), + )); + assert!(matches!( + unavailable, + MultisigError::ModuleUnavailable { ref module } if module == "sanctions" + )); + } + #[test] fn miden_client_conversion_retains_typed_rpc_kind() { let error = MultisigError::from(request_error(GrpcError::ResourceExhausted)); @@ -549,17 +632,6 @@ mod tests { )); } - fn guardian_status( - code: tonic::Code, - details: serde_json::Value, - ) -> guardian_client::ClientError { - guardian_client::ClientError::from(tonic::Status::with_details( - code, - "refused", - details.to_string().into_bytes().into(), - )) - } - #[test] fn a_coded_push_refusal_is_typed_with_its_code_and_retry_meta() { let error = MultisigError::proposal_push(guardian_status( diff --git a/crates/miden-multisig-client/src/lib.rs b/crates/miden-multisig-client/src/lib.rs index 1906c1ca..b69d1332 100644 --- a/crates/miden-multisig-client/src/lib.rs +++ b/crates/miden-multisig-client/src/lib.rs @@ -66,7 +66,7 @@ pub(crate) type MidenSdkClient = Client; // Main client pub use builder::MultisigClientBuilder; -pub use client::{AbandonRequest, AbandonRequestState, AbandonStatus}; +pub use client::{AbandonRequest, AbandonRequestState, AbandonStatus, Policy}; pub use client::{ BlockRange, ConsumableNote, ExecutionWaitOptions, HistoryAssetKind, HistoryDecodeSection, HistoryDecodeWarning, HistoryEntry, HistoryEntryStatus, HistoryNote, HistoryNoteAsset, @@ -112,11 +112,11 @@ pub use prover::{ProverConfig, ProverRetryPolicy}; pub use rpc::{RpcConfig, RpcRetryPolicy}; pub use transaction::{ GUARDIAN_EXECUTABLE_APPROVAL_EXPIRATION_DELTA, GUARDIAN_EXECUTABLE_TX_EXPIRATION_DELTA, - MAX_APPROVAL_EXPIRATION_DELTA, ProposalBuilder, ProposalExecutionMode, ProposalOptions, - TransactionRequestBuilderExt, build_p2id_transaction_request, deserialize_transaction_request, - generate_salt, multisig_auth_args, proposal_auth_args, proposer_auth_args, - summary_approval_expiration_block_num, summary_expiration_delta, summary_salt, - synced_fee_faucet_id, + MAX_APPROVAL_EXPIRATION_DELTA, ProposalBuilder, ProposalCheck, ProposalExecutionMode, + ProposalOptions, TransactionRequestBuilderExt, build_p2id_transaction_request, + deserialize_transaction_request, generate_salt, multisig_auth_args, proposal_auth_args, + proposer_auth_args, summary_approval_expiration_block_num, summary_expiration_delta, + summary_salt, synced_fee_faucet_id, }; // Export/Import @@ -132,7 +132,7 @@ pub use guardian_client::{MAX_SESSION_TTL, MIN_SESSION_TTL, SessionInfo, StartSe // Guardian execution pub use guardian_client::execution::{ ExecutionFailure, ExecutionFailureCode, ExecutionState, ExpirationBound, - ForeignAccountUnavailableReason, ProposalExecution, RequestInvalidReason, + ForeignAccountUnavailableReason, ModuleDenial, ProposalExecution, RequestInvalidReason, }; // Re-exports for convenience diff --git a/crates/miden-multisig-client/src/transaction/builder.rs b/crates/miden-multisig-client/src/transaction/builder.rs index 438ef9ea..746ef00c 100644 --- a/crates/miden-multisig-client/src/transaction/builder.rs +++ b/crates/miden-multisig-client/src/transaction/builder.rs @@ -47,6 +47,18 @@ pub struct ProposalBuilder { transaction_type: TransactionType, approval_expiration_delta: Option, execution_mode: ProposalExecutionMode, + /// Set by [`ProposalBuilder::check`]: the proposal is checked on GUARDIAN, not created. + dry_run: bool, + checked: Arc>>, +} + +/// The answer of a proposal check that passed: GUARDIAN's policy modules would let the +/// proposal be created. A refusal is the same error creating it returns. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub struct ProposalCheck { + /// False when a module that opts out of checks was skipped, so creation could still be + /// refused. + pub complete: bool, } /// Per-proposal settings a caller may set when proposing a transaction. @@ -147,6 +159,8 @@ impl ProposalBuilder { Self { transaction_type, approval_expiration_delta: None, + dry_run: false, + checked: Arc::default(), execution_mode: ProposalExecutionMode::SelfExecuted, } } @@ -170,6 +184,68 @@ impl ProposalBuilder { self } + /// Builds the proposal exactly as [`Self::build`] would and asks GUARDIAN whether it + /// would be created, without storing it. Advisory: approval still decides. + pub async fn check( + mut self, + miden_client: &mut MidenSdkClient, + node_rpc: &Arc, + guardian_client: &mut GuardianClient, + account: &MultisigAccount, + key_manager: &dyn KeyManager, + ) -> Result { + self.dry_run = true; + let checked = self.checked.clone(); + self.build( + miden_client, + node_rpc, + guardian_client, + account, + key_manager, + ) + .await?; + let result = checked.lock().ok().and_then(|mut checked| checked.take()); + result.ok_or_else(|| { + MultisigError::GuardianServer("GUARDIAN did not answer the proposal check".into()) + }) + } + + /// Creates the proposal on GUARDIAN, or only checks it in a dry run. Returns the + /// commitment GUARDIAN reports for a created proposal, none for a check. + async fn send( + &self, + guardian_client: &mut GuardianClient, + account_id: &AccountId, + nonce: u64, + payload: &serde_json::Value, + ) -> Result> { + if self.dry_run { + let response = guardian_client + .check_delta_proposal(account_id, nonce, payload) + .await + .map_err(|e| MultisigError::guardian("failed to check proposal", e))?; + if let Ok(mut checked) = self.checked.lock() { + *checked = Some(ProposalCheck { + complete: response.complete, + }); + } + return Ok(None); + } + let response = guardian_client + .push_delta_proposal(account_id, nonce, payload) + .await + .map_err(MultisigError::proposal_push)?; + Ok(Some(response.commitment)) + } + + /// Checks GUARDIAN's commitment for a created proposal; a check has none. + fn confirm(&self, proposal: &Proposal, response_commitment: Option<&str>) -> Result<()> { + match response_commitment { + Some(commitment) => Self::ensure_response_commitment(proposal, commitment), + None => Ok(()), + } + } + /// Builds and submits the proposal to GUARDIAN. pub async fn build( self, @@ -391,10 +467,9 @@ impl ProposalBuilder { // Push proposal to GUARDIAN let nonce = account.nonce() + 1; - let response = guardian_client - .push_delta_proposal(&account_id, nonce, &payload.to_json()) - .await - .map_err(MultisigError::proposal_push)?; + let response_commitment = self + .send(guardian_client, &account_id, nonce, &payload.to_json()) + .await?; // Build the Proposal let proposal = Proposal::new( @@ -406,7 +481,7 @@ impl ProposalBuilder { }, metadata, ); - Self::ensure_response_commitment(&proposal, &response.commitment)?; + self.confirm(&proposal, response_commitment.as_deref())?; Ok(proposal) } @@ -502,10 +577,9 @@ impl ProposalBuilder { .with_required_signatures(required_signatures); let nonce = account.nonce() + 1; - let response = guardian_client - .push_delta_proposal(&account_id, nonce, &payload.to_json()) - .await - .map_err(MultisigError::proposal_push)?; + let response_commitment = self + .send(guardian_client, &account_id, nonce, &payload.to_json()) + .await?; let proposal = Proposal::new( tx_summary, @@ -516,7 +590,7 @@ impl ProposalBuilder { }, metadata, ); - Self::ensure_response_commitment(&proposal, &response.commitment)?; + self.confirm(&proposal, response_commitment.as_deref())?; Ok(proposal) } @@ -620,10 +694,9 @@ impl ProposalBuilder { // Push proposal to GUARDIAN let nonce = account.nonce() + 1; - let response = guardian_client - .push_delta_proposal(&account_id, nonce, &payload.to_json()) - .await - .map_err(MultisigError::proposal_push)?; + let response_commitment = self + .send(guardian_client, &account_id, nonce, &payload.to_json()) + .await?; // Build the Proposal let proposal = Proposal::new( @@ -634,7 +707,7 @@ impl ProposalBuilder { }, metadata, ); - Self::ensure_response_commitment(&proposal, &response.commitment)?; + self.confirm(&proposal, response_commitment.as_deref())?; Ok(proposal) } @@ -720,10 +793,9 @@ impl ProposalBuilder { // Push proposal to GUARDIAN let nonce = account.nonce() + 1; - let response = guardian_client - .push_delta_proposal(&account_id, nonce, &payload.to_json()) - .await - .map_err(MultisigError::proposal_push)?; + let response_commitment = self + .send(guardian_client, &account_id, nonce, &payload.to_json()) + .await?; // Build the Proposal let proposal = Proposal::new( @@ -738,7 +810,7 @@ impl ProposalBuilder { }, metadata, ); - Self::ensure_response_commitment(&proposal, &response.commitment)?; + self.confirm(&proposal, response_commitment.as_deref())?; Ok(proposal) } @@ -849,10 +921,9 @@ impl ProposalBuilder { // Push proposal to GUARDIAN let nonce = account.nonce() + 1; - let response = guardian_client - .push_delta_proposal(&account_id, nonce, &payload.to_json()) - .await - .map_err(MultisigError::proposal_push)?; + let response_commitment = self + .send(guardian_client, &account_id, nonce, &payload.to_json()) + .await?; // Clone notes for the runtime TransactionType; metadata keeps its own copy. let notes_for_tx_type = metadata.consume_notes_notes.clone(); @@ -866,7 +937,7 @@ impl ProposalBuilder { }, metadata, ); - Self::ensure_response_commitment(&proposal, &response.commitment)?; + self.confirm(&proposal, response_commitment.as_deref())?; Ok(proposal) } @@ -946,10 +1017,9 @@ impl ProposalBuilder { // Push proposal to GUARDIAN let nonce = account.nonce() + 1; - let response = guardian_client - .push_delta_proposal(&account_id, nonce, &payload.to_json()) - .await - .map_err(MultisigError::proposal_push)?; + let response_commitment = self + .send(guardian_client, &account_id, nonce, &payload.to_json()) + .await?; // Build the Proposal let proposal = Proposal::new( @@ -961,7 +1031,7 @@ impl ProposalBuilder { }, metadata, ); - Self::ensure_response_commitment(&proposal, &response.commitment)?; + self.confirm(&proposal, response_commitment.as_deref())?; Ok(proposal) } @@ -1023,10 +1093,9 @@ impl ProposalBuilder { .with_required_signatures(required_signatures); let nonce = account.nonce() + 1; - let response = guardian_client - .push_delta_proposal(&account_id, nonce, &payload.to_json()) - .await - .map_err(MultisigError::proposal_push)?; + let response_commitment = self + .send(guardian_client, &account_id, nonce, &payload.to_json()) + .await?; let proposal = Proposal::new( tx_summary, @@ -1037,7 +1106,7 @@ impl ProposalBuilder { }, metadata, ); - Self::ensure_response_commitment(&proposal, &response.commitment)?; + self.confirm(&proposal, response_commitment.as_deref())?; Ok(proposal) } diff --git a/crates/miden-multisig-client/src/transaction/mod.rs b/crates/miden-multisig-client/src/transaction/mod.rs index 8181fa71..2fa169f0 100644 --- a/crates/miden-multisig-client/src/transaction/mod.rs +++ b/crates/miden-multisig-client/src/transaction/mod.rs @@ -13,7 +13,7 @@ pub use auth_args::{ proposal_auth_args, proposer_auth_args, summary_approval_expiration_block_num, summary_salt, synced_fee_faucet_id, }; -pub use builder::{ProposalBuilder, ProposalOptions}; +pub use builder::{ProposalBuilder, ProposalCheck, ProposalOptions}; pub use configuration::{ build_update_procedure_threshold_transaction_request, build_update_signers_transaction_request, }; diff --git a/packages/guardian-client/src/conversion.ts b/packages/guardian-client/src/conversion.ts index b5e61269..0c216a4a 100644 --- a/packages/guardian-client/src/conversion.ts +++ b/packages/guardian-client/src/conversion.ts @@ -1,5 +1,6 @@ import type { CanonicalNonce, + Policy, CosignerSignature, ConfigureRequest, ConfigureResponse, @@ -20,6 +21,7 @@ import type { } from './types.js'; import type { ServerCanonicalNonceResponse, + ServerPolicyEntry, ServerCosignerSignature, ServerConfigureRequest, ServerConfigureResponse, @@ -174,6 +176,16 @@ export function fromServerStateObject(server: ServerStateObject): StateObject { }; } +export function fromServerPolicy(server: ServerPolicyEntry): Policy { + return { + moduleId: server.module_id, + hooks: server.hooks, + description: server.description, + ...(server.params !== undefined ? { params: server.params } : {}), + ...(server.account_layer !== undefined ? { accountLayer: server.account_layer } : {}), + }; +} + export function fromServerCanonicalNonce(server: ServerCanonicalNonceResponse): CanonicalNonce { if (!Number.isSafeInteger(server.nonce) || server.nonce < 0) { throw new Error(`Invalid canonical nonce from server: ${String(server.nonce)}`); diff --git a/packages/guardian-client/src/http.test.ts b/packages/guardian-client/src/http.test.ts index 7778b8b1..0561eacb 100644 --- a/packages/guardian-client/src/http.test.ts +++ b/packages/guardian-client/src/http.test.ts @@ -636,6 +636,94 @@ describe('GuardianHttpClient', () => { }); }); + describe('policy discovery', () => { + const accountId = '0x' + 'a'.repeat(30); + + it('lists the disclosed policies over a signed query', async () => { + client.setSigner(mockSigner); + mockFetch.mockResolvedValueOnce({ + ok: true, + json: async () => ({ + account_id: accountId, + policies: [ + { + module_id: 'caps', + hooks: ['before_transaction_approved'], + description: 'At most 5 per transaction', + params: { max_amount_per_tx: { '0xaa': '5' } }, + account_layer: { max_amount_per_tx: { '0xaa': '2' } }, + }, + { module_id: 'screening', hooks: ['before_proposal_created'], description: 'Screened' }, + ], + }), + }); + + const policies = await client.getPolicies(accountId); + + expect(policies).toEqual([ + { + moduleId: 'caps', + hooks: ['before_transaction_approved'], + description: 'At most 5 per transaction', + params: { max_amount_per_tx: { '0xaa': '5' } }, + accountLayer: { max_amount_per_tx: { '0xaa': '2' } }, + }, + { moduleId: 'screening', hooks: ['before_proposal_created'], description: 'Screened' }, + ]); + expect(mockFetch).toHaveBeenCalledWith( + expect.stringContaining('/policies?account_id='), + expect.objectContaining({ + method: 'GET', + headers: expect.objectContaining({ 'x-signature': expect.any(String) }), + }) + ); + }); + + it('checks a proposal without creating it', async () => { + client.setSigner(mockSigner); + mockFetch.mockResolvedValueOnce({ + ok: true, + json: async () => ({ allowed: true, complete: false }), + }); + + const result = await client.checkDeltaProposal({ + accountId, + nonce: 1, + deltaPayload: { txSummary: { data: 'base64summary' }, signatures: [] }, + }); + + expect(result).toEqual({ allowed: true, complete: false }); + expect(mockFetch).toHaveBeenCalledWith( + expect.stringContaining('/delta/proposal/check'), + expect.objectContaining({ method: 'POST' }) + ); + }); + + it('surfaces a policy refusal from the check as the creation error', async () => { + client.setSigner(mockSigner); + mockFetch.mockResolvedValueOnce({ + ok: false, + headers: new Headers(), + status: 403, + statusText: 'Forbidden', + text: async () => + JSON.stringify({ + code: 'GUARDIAN_MODULE_DENIED', + message: "This Guardian's policy doesn't allow this request.", + meta: { retryable: false, reason_code: 'policy_denied' }, + }), + }); + + await expect( + client.checkDeltaProposal({ + accountId, + nonce: 1, + deltaPayload: { txSummary: { data: 'base64summary' }, signatures: [] }, + }) + ).rejects.toMatchObject({ code: 'module_denied', status: 403 }); + }); + }); + describe('pushDeltaProposal', () => { it('lets an EIP-712 signer create an unsigned proposal', async () => { const signer: Signer = { @@ -1614,6 +1702,60 @@ describe('GuardianHttpError', () => { expect(error.meta?.retryAfterSecs).toBe(30); // snake_case → camelCase }); + describe('policy module refusals', () => { + const refused = (status: number, code: string, meta: Record) => + new GuardianHttpError(status, 'Refused', JSON.stringify({ code, message: 'refused', meta })); + + it('parses a full denial into meta and moduleRefusal()', () => { + const error = refused(403, 'GUARDIAN_MODULE_DENIED', { + retryable: false, + module: 'caps', + reason_code: 'amount_cap_exceeded', + layer: 'account', + client_message: 'over the daily cap', + }); + expect(error.code).toBe('module_denied'); + expect(error.meta).toMatchObject({ + module: 'caps', + reasonCode: 'amount_cap_exceeded', + layer: 'account', + clientMessage: 'over the daily cap', + }); + expect(error.moduleRefusal()).toEqual({ + kind: 'denied', + module: 'caps', + reasonCode: 'amount_cap_exceeded', + layer: 'account', + clientMessage: 'over the daily cap', + }); + expect(error.isRetryable()).toBe(false); + }); + + it('reports a generic denial with only its reason code', () => { + const error = refused(403, 'GUARDIAN_MODULE_DENIED', { retryable: false, reason_code: 'policy_denied' }); + expect(error.moduleRefusal()).toEqual({ + kind: 'denied', + module: null, + reasonCode: 'policy_denied', + layer: null, + clientMessage: null, + }); + }); + + it('reports an unavailable module as retryable', () => { + const error = refused(503, 'GUARDIAN_MODULE_UNAVAILABLE', { retryable: true, module: 'caps' }); + expect(error.moduleRefusal()).toEqual({ kind: 'unavailable', module: 'caps' }); + expect(error.isRetryable()).toBe(true); + }); + + it('reports no refusal for other codes or a refusal missing its required field', () => { + expect(refused(403, 'GUARDIAN_MODULE_DENIED', { retryable: false, module: 'caps' }).moduleRefusal()).toBeNull(); + expect(refused(503, 'GUARDIAN_MODULE_UNAVAILABLE', { retryable: true }).moduleRefusal()).toBeNull(); + expect(refused(409, 'GUARDIAN_EXECUTION_CONFLICT', { retryable: false, module: 'caps' }).moduleRefusal()).toBeNull(); + expect(new GuardianHttpError(502, 'Bad Gateway', 'upstream exploded').moduleRefusal()).toBeNull(); + }); + }); + it('leaves accessors undefined for a non-JSON / non-conforming body', () => { const plain = new GuardianHttpError(502, 'Bad Gateway', 'upstream exploded'); expect(plain.code).toBeNull(); diff --git a/packages/guardian-client/src/http.ts b/packages/guardian-client/src/http.ts index 3810bb6a..da050557 100644 --- a/packages/guardian-client/src/http.ts +++ b/packages/guardian-client/src/http.ts @@ -5,6 +5,7 @@ import { import type { AbandonCandidateResponse, AbandonStatus, + CheckProposalResult, ConfigureRequest, ConfigureResponse, CreateSessionRequest, @@ -16,6 +17,7 @@ import type { HistoryOptions, HistoryPage, LookupResponse, + Policy, PubkeyResponse, PushDeltaResponse, SessionEndReason, @@ -38,10 +40,12 @@ import type { ServerAbandonCandidateRequest, ServerAbandonCandidateResponse, ServerCanonicalNonceResponse, + ServerCheckProposalResponse, ServerDeltaObject, ServerDeltaProposalResponse, ServerHistoryPage, ServerLookupResponse, + ServerPoliciesResponse, ServerProposalsResponse, ServerPubkeyResponse, ServerStateObject, @@ -60,6 +64,7 @@ import { fromServerDeltaObject, fromServerHistoryPage, fromServerLookupResponse, + fromServerPolicy, fromServerStateObject, toServerConfigureRequest, toServerCreateSessionRequest, @@ -105,8 +110,34 @@ export interface GuardianErrorMeta { * `code === 'proposal_executes_locally'`: `switch_guardian` for a guardian switch. */ reason?: LocalExecutionReason; + /** + * The policy module instance that refused. Present for `module_unavailable`, and for + * `module_denied` unless the instance reports generic denials. + */ + module?: string; + /** Machine-readable denial reason; `policy_denied` for a generic denial. Only for `module_denied`. */ + reasonCode?: string; + /** `global` or `account`: the parameter layer that denied. Only for a full `module_denied`. */ + layer?: string; + /** The denying module's text for the requester, when the instance allows it. */ + clientMessage?: string; } +/** + * A refusal by one of the Guardian's policy modules. `module` is the operator-chosen instance + * id. A generic denial carries only the reason code `policy_denied`. A denial is final; an + * unavailable module is retryable. Mirrors the Rust client's `ModuleRefusal`. + */ +export type ModuleRefusal = + | { + kind: 'denied'; + module: string | null; + reasonCode: string; + layer: string | null; + clientMessage: string | null; + } + | { kind: 'unavailable'; module: string }; + /** Why GUARDIAN refuses to execute a proposal and leaves it to local execution. */ export type LocalExecutionReason = 'switch_guardian'; @@ -179,6 +210,10 @@ function parseGuardianErrorBody(body: string): ParsedGuardianError | undefined { meta.blockingProposalId = rawMeta.blocking_proposal_id; } if (typeof rawMeta.proposal_type === 'string') meta.proposalType = rawMeta.proposal_type; + if (typeof rawMeta.module === 'string') meta.module = rawMeta.module; + if (typeof rawMeta.reason_code === 'string') meta.reasonCode = rawMeta.reason_code; + if (typeof rawMeta.layer === 'string') meta.layer = rawMeta.layer; + if (typeof rawMeta.client_message === 'string') meta.clientMessage = rawMeta.client_message; const reason = localExecutionReason(rawMeta.reason); if (reason !== undefined) meta.reason = reason; if (typeof rawMeta.paused_reason === 'string' || rawMeta.paused_reason === null) { @@ -263,6 +298,34 @@ export class GuardianHttpError extends Error { retryAfterSecs(): number | undefined { return this.headerRetryAfterSecs ?? this.meta?.retryAfterSecs; } + + /** + * The policy module refusal this error carries, or `null`: `module_denied` with its + * `reasonCode`, or `module_unavailable` with its `module`. A refusal missing the field it + * requires is not reported as one. Mirrors the Rust client's `ClientError::module_refusal`. + */ + moduleRefusal(): ModuleRefusal | null { + const meta = this.meta; + if (meta === undefined) { + return null; + } + switch (this.code) { + case 'module_denied': + return meta.reasonCode === undefined + ? null + : { + kind: 'denied', + module: meta.module ?? null, + reasonCode: meta.reasonCode, + layer: meta.layer ?? null, + clientMessage: meta.clientMessage ?? null, + }; + case 'module_unavailable': + return meta.module === undefined ? null : { kind: 'unavailable', module: meta.module }; + default: + return null; + } + } } // Decimal digits only, mirroring the Rust client's `parse::()`: no @@ -574,6 +637,40 @@ export class GuardianHttpClient { }; } + /** + * Dry run of {@link pushDeltaProposal}: the same checks and proposal-creation + * policy modules, without storing a proposal or taking a slot + * (`POST /delta/proposal/check`). A refusal throws the same + * `GUARDIAN_MODULE_DENIED` / `GUARDIAN_MODULE_UNAVAILABLE` error creation + * would. Advisory: approval still decides. Rate limited per account and signer. + */ + async checkDeltaProposal(request: DeltaProposalRequest): Promise { + const serverRequest = toServerDeltaProposalRequest(request); + const response = await this.fetchAuthenticated('/delta/proposal/check', { + method: 'POST', + body: JSON.stringify(serverRequest), + }, request.accountId, serverRequest, 'session'); + const server = (await response.json()) as ServerCheckProposalResponse; + if (server.allowed !== true) { + throw new Error('Invalid proposal check response: a passing check must be allowed'); + } + return { allowed: true, complete: server.complete }; + } + + /** + * The policies the Guardian applies to the account, as far as its operator + * discloses them, in evaluation order (`GET /policies`). + */ + async getPolicies(accountId: string): Promise { + const requestQuery = { account_id: accountId }; + const params = new URLSearchParams(requestQuery); + const response = await this.fetchAuthenticated(`/policies?${params}`, { + method: 'GET', + }, accountId, requestQuery, 'session'); + const server = (await response.json()) as ServerPoliciesResponse; + return server.policies.map(fromServerPolicy); + } + /** * Ask Guardian to prove and submit a threshold-met proposal. Resolves once the request is * accepted; poll {@link getDeltaProposalExecution} for the outcome. Repeating the request while diff --git a/packages/guardian-client/src/index.ts b/packages/guardian-client/src/index.ts index a4511af6..6a250bd9 100644 --- a/packages/guardian-client/src/index.ts +++ b/packages/guardian-client/src/index.ts @@ -1,5 +1,5 @@ export { GuardianHttpClient, GuardianHttpError } from './http.js'; -export type { GuardianErrorMeta, LocalExecutionReason } from './http.js'; +export type { GuardianErrorMeta, LocalExecutionReason, ModuleRefusal } from './http.js'; export { GUARDIAN_ERROR_CODES, isGuardianErrorCode, @@ -52,6 +52,8 @@ export type { AuthConfig, MidenCosignerConfig, CanonicalNonce, + CheckProposalResult, + Policy, DeltaStatus, DeltaObject, ExecutionDelta, diff --git a/packages/guardian-client/src/server-types.ts b/packages/guardian-client/src/server-types.ts index ba89dc6d..8055f1c1 100644 --- a/packages/guardian-client/src/server-types.ts +++ b/packages/guardian-client/src/server-types.ts @@ -167,6 +167,24 @@ export interface ServerDeltaProposalResponse { commitment: string; } +export interface ServerCheckProposalResponse { + allowed: boolean; + complete: boolean; +} + +export interface ServerPolicyEntry { + module_id: string; + hooks: string[]; + description: string; + params?: Record; + account_layer?: Record; +} + +export interface ServerPoliciesResponse { + account_id: string; + policies: ServerPolicyEntry[]; +} + export interface ServerProposalsResponse { proposals: ServerDeltaObject[]; } diff --git a/packages/guardian-client/src/types.ts b/packages/guardian-client/src/types.ts index 58d02eed..e9f581c9 100644 --- a/packages/guardian-client/src/types.ts +++ b/packages/guardian-client/src/types.ts @@ -369,6 +369,29 @@ export interface DeltaProposalResponse { commitment: string; } +/** + * The answer of a proposal check that passed: the Guardian's policy modules + * would let the proposal be created. A refusal is thrown as the same error + * creation returns. + */ +export interface CheckProposalResult { + allowed: true; + /** False when a module that opts out of checks was skipped. */ + complete: boolean; +} + +/** A policy the Guardian applies to the account, as far as its operator discloses it. */ +export interface Policy { + moduleId: string; + /** Where it runs, for example `before_proposal_created`. */ + hooks: string[]; + description: string; + /** The rule's parameters, where disclosed. */ + params?: Record; + /** This account's own stricter layer on the rule, where disclosed. */ + accountLayer?: Record; +} + export interface ProposalsResponse { proposals: DeltaObject[]; } diff --git a/packages/miden-multisig-client/src/index.ts b/packages/miden-multisig-client/src/index.ts index 975d6981..a1da1bcb 100644 --- a/packages/miden-multisig-client/src/index.ts +++ b/packages/miden-multisig-client/src/index.ts @@ -120,7 +120,7 @@ export type { } from './transaction/options.js'; export { GuardianHttpClient, GuardianHttpError } from '@openzeppelin/guardian-client'; -export type { GuardianErrorMeta } from '@openzeppelin/guardian-client'; +export type { GuardianErrorMeta, ModuleRefusal } from '@openzeppelin/guardian-client'; // Typed error-code vocabulary (issue #318): branch on GuardianErrorCode, // never on message text; unknown wire codes surface via rawCode. export { From c5caa88b7335c892af5a0d9c63e1666f07709c19 Mon Sep 17 00:00:00 2001 From: Zeljko Date: Mon, 9 Nov 2026 09:03:32 +0100 Subject: [PATCH 005/105] docs: policy modules guides, RFC 0002 revision 26 and the M2a plan (#251) docs/guides/policy-modules (built-in, remote and custom modules), module configuration, dashboard routes and permissions, troubleshooting codes, spec/api.md execution failure codes, RFC 0002 revision 26, the speckit plan, tasks-p0.md (prototype record) and tasks.md (M2a), and the verify-module-counting TLA+ skill for RFC sections 3.3 and 3.4. Carried from the prototype (#554). --- .../skills/verify-module-counting/SKILL.md | 217 +++++++++ .../verify-module-counting/agents/openai.yaml | 4 + .../skills/verify-module-counting/check.sh | 191 ++++++++ .../verify-module-counting/expected.txt | 23 + .../verify-module-counting/fingerprint.py | 71 +++ .../verify-module-counting/fingerprints.txt | 13 + .../verify-module-counting/mirrored.txt | 17 + .../model/ModuleCounting.tla | 411 ++++++++++++++++++ .../skills/verify-module-counting/trace.py | 83 ++++ docs/CONFIGURATION.md | 11 + docs/DASHBOARD.md | 37 +- docs/TROUBLESHOOTING.md | 2 + docs/guides/README.md | 1 + docs/guides/policy-modules/.env.example | 12 + docs/guides/policy-modules/README.md | 195 +++++++++ docs/guides/policy-modules/built-in.md | 102 +++++ docs/guides/policy-modules/custom.md | 149 +++++++ .../policy-modules/operators.example.json | 6 + docs/guides/policy-modules/remote.md | 88 ++++ docs/rfcs/0002-guardian-modules.md | 18 +- spec/api.md | 6 +- .../checklists/requirements.md | 2 +- .../contracts/guardian_module_v1.proto | 3 +- .../251-guardian-modules/data-model.md | 2 +- speckit/features/251-guardian-modules/plan.md | 123 +++--- .../features/251-guardian-modules/research.md | 4 +- speckit/features/251-guardian-modules/spec.md | 4 +- .../features/251-guardian-modules/tasks-p0.md | 269 ++++++++++++ .../features/251-guardian-modules/tasks.md | 386 ++++++++-------- 29 files changed, 2190 insertions(+), 260 deletions(-) create mode 100644 .agents/skills/verify-module-counting/SKILL.md create mode 100644 .agents/skills/verify-module-counting/agents/openai.yaml create mode 100755 .agents/skills/verify-module-counting/check.sh create mode 100644 .agents/skills/verify-module-counting/expected.txt create mode 100644 .agents/skills/verify-module-counting/fingerprint.py create mode 100644 .agents/skills/verify-module-counting/fingerprints.txt create mode 100644 .agents/skills/verify-module-counting/mirrored.txt create mode 100644 .agents/skills/verify-module-counting/model/ModuleCounting.tla create mode 100644 .agents/skills/verify-module-counting/trace.py create mode 100644 docs/guides/policy-modules/.env.example create mode 100644 docs/guides/policy-modules/README.md create mode 100644 docs/guides/policy-modules/built-in.md create mode 100644 docs/guides/policy-modules/custom.md create mode 100644 docs/guides/policy-modules/operators.example.json create mode 100644 docs/guides/policy-modules/remote.md create mode 100644 speckit/features/251-guardian-modules/tasks-p0.md diff --git a/.agents/skills/verify-module-counting/SKILL.md b/.agents/skills/verify-module-counting/SKILL.md new file mode 100644 index 00000000..247b1326 --- /dev/null +++ b/.agents/skills/verify-module-counting/SKILL.md @@ -0,0 +1,217 @@ +--- +name: verify-module-counting +description: Model-check how a stateful Guardian module (a spending cap) counts signed transactions, per RFC 0002 sections 3.3 and 3.4, with TLA+/TLC. Use before changing the notify outbox, the delivery watermark, `pending`, NotifyGap or resync, the notifier lease, or the candidate lifecycle a module's count depends on (candidate admission, promotion, Retained and client-abandoned rows, reconcile); when editing RFC 0002 sections 3.3 or 3.4; when implementing M2b; or when check.sh reports DRIFT. +--- + +# Verify stateful module counting + +`model/ModuleCounting.tla` models one account guarded by one stateful +module: a spending cap that keeps counters and a nonce watermark updated +from `Notify`, and decides each `Evaluate` on its counters plus the +`pending` list the Guardian sends. TLC explores every interleaving of +`push_delta` requests (snapshot, evaluate, store), cosigners executing any +signed delta on chain, canonicalization (promote, retain, reconcile, +expire), two replicas delivering `Notify` and `NotifyGap` under the +notifier lease (calls and replies delayed, duplicated or lost, a replica +that lost the lease still sending), retention drops and operator resync. +One model step is one storage transaction, one module write, one message +delivery or one on-chain execution. + +M2b is not implemented: the notifier, the `module_events` outbox, +`pending` and the watermark exist only in the RFC +(`docs/rfcs/0002-guardian-modules.md` sections 3.3 and 3.4, revision 23). +The model checks that design, on top of the candidate lifecycle that +already exists in `crates/server`. The protocol fields it depends on +(`CommitEvent.nonce`, `Gap.resume_from_nonce`, `PendingTransaction.nonce`) +freeze with protocol version 1 at M2a. + +## What is checked + +| Property | In plain words | Harm if broken | +|---|---|---| +| `NoOvershoot` | The account never spends more on chain than the cap. | The limit the module exists to enforce is exceeded. | +| `NoDoubleCount` | No evaluation counts a delta both in the module's counters and in `pending`. | A payment that fits is refused. | +| `NoDoubleApply` | The counters hold each applied delta once, however often `Notify` is redelivered. | Payments that fit are refused. | +| `CountsQueueAndCommitted` | An evaluation whose delta is admitted counted every delta that was committed or queued at its snapshot and still is (RFC 3.4, "never both and never neither"). | The cap is decided on a total that misses signed spend. | +| `CountsRecoverable` | The same for deltas parked as `Retained` or client-abandoned. | Expected to fail by design (F3 below); `NoOvershoot` shows it is safe. | + +The module in the model re-seeds on `NotifyGap`: it rebuilds its counters +from its own sources (here, the chain) below `resume_from_nonce`, as RFC +3.3 allows. A module that resets to zero instead accepts the dropped +history by design, and F1 and F2 do not apply to it. + +## What the model found in revision 22 + +Revision 23 of the RFC adopted the fixes; the faults are now mutations +`m6` and `m7`, so the check fails if the design slides back. + +**F1 (now `m6`): resync reopened evaluation before the module had handled +`NotifyGap`.** Cap 2, every amount 1. Deltas 1 and 2 land, delta 1 is +promoted and its event written but not acknowledged; retention drops the +backlog; an operator resyncs, which cleared `resync_required` while the +Gap was still in flight; a `push_delta` is evaluated on the module's +pre-gap counters (0) plus `pending` {2} plus 1 = 2, allowed; delta 3 +lands, spending 3. Revision 23: the pair stays refused until the module +acknowledges `NotifyGap`. + +**F2 (now `m7`): an event from a replica that lost the lease overtook +`NotifyGap`.** Replica l2 takes the lease while l1 still believes it holds +it; l2 resyncs (`resume_from_nonce = 2`); delta 2 is promoted after the +resync; l1 reads the moved cursor and sends event 2, which reaches the +module before l2's Gap and raises the watermark to 2; the Gap then fails +"only if that raises the watermark" and is acknowledged without the +re-seed; delta 1 is never counted and delta 3 overshoots. Revision 22 said +every event a stale leader has in flight predates the resync (corrected +in its Appendix B). Revision 23: the Gap obligation is stored with the +cursor, read in the same statement, and no replica sends an event while it +is open. + +**F3 (cell `recoverable`, by design): `pending` omits signed deltas that +can still land.** A delta parked as `Retained` or client-abandoned (issue +#345) is neither queued nor committed, yet the reconcile pass can still +promote it. It does not overspend (`NoOvershoot` holds in every counting +cell, including unequal amounts): a parked delta is never the tail, so +every later delta conflicts with it on chain, and each landed delta was +evaluated with all its ancestors counted. RFC 3.4, "Recoverable rows", +states this argument; if a change lets a delta build on a parked row, the +argument breaks. + +## Does my change touch this? + +Yes if the diff changes anything in `mirrored.txt` (check.sh lists drift), +RFC 0002 sections 3.3 or 3.4, or adds a path that: + +- makes a delta committed (writes canonical state) without writing its + `module_events` row in the same transaction (mutation `m5`); +- reads the candidate queue and the unacknowledged events for `pending` in + separate transactions (`m3`); +- lets a delta land on chain that the Guardian signed without evaluating + the account's modules on its base; +- moves the stored state out of band (for example `configure_account` + re-onboarding), which the model does not cover (see scope). + +## Run it + +From the repo root: + +```bash +.agents/skills/verify-module-counting/check.sh # quick tier, about 8 s +.agents/skills/verify-module-counting/check.sh --deep # adds 4 deltas and mixed amounts, about 3 min +.agents/skills/verify-module-counting/check.sh --mutations # every broken variant must fail, about 10 s +.agents/skills/verify-module-counting/check.sh --cell m7 # one cell, full TLC output and trace +``` + +It needs `java` and `python3`. `tla2tools.jar` 1.7.4 is cached in +`~/.cache/guardian-tla/` and checksum-verified (downloaded on first run), +shared with the other `verify-*` skills. Exit codes: 0 every cell matches +`expected.txt` and no drift; 1 a verdict changed; 2 setup error; 3 cells +match but mirrored source drifted. `TLC_WORKERS` caps TLC's threads. + +## Reading a result + +`ok` lines match `expected.txt`, including the expected `recoverable` +failure. +A `DIFF` prints the counterexample, one step per line with what changed. +Delta ids index `txs`; `pending` is what the request's snapshot listed. + +- Walk the steps against the action map. If every step is something the + design (or the code, once it exists) can do, it is a real bug: report it + in RFC and code terms, and leave `expected.txt` and the properties alone. +- If a step is impossible, the model is wrong: fix that action, cite the + source, and rerun. Two modeling errors were found and fixed this way + while building the model: liveness judged by delta identity (a delta + superseded at its nonce looked "missed") and a snapshot set that + excluded a promoted delta whose event was not written yet. +- After changing the model to match intended source, run + `check.sh --accept-drift`. + +## Action map + +Rust paths are relative to `crates/server/src/`; "RFC" is +`docs/rfcs/0002-guardian-modules.md`. + +| Model action | Source | +|---|---| +| `Snapshot` | `services/push_delta.rs` `push_delta` (`CandidateChain::load_for_admission`) plus RFC 3.4 "Guardian side": queue, unacknowledged events and `resync_required` in one repeatable-read transaction. The client's base is the tail it knows | +| `SnapshotQueue` | mutation `m3` only: the queue read in a second transaction | +| `Evaluate` | RFC 3.4 "Module side": counters and watermark from one consistent read, pending entries above the watermark, plus the delta; `on_error = deny` under `resync_required` and until the resync's Gap is acknowledged (RFC 3.3) | +| `Store` | `storage/mod.rs` `gate_candidate_submission` (tail, room) under the account lock, `storage/postgres.rs` `submit_candidate` (deletes a `retained` or client-abandoned row at the same nonce) | +| `Execute` | a cosigner submits any signed delta; Miden executes it only on its parent state | +| `Promote` | `storage/postgres.rs` `promote_candidate` (`PromotableKind::Candidate`) plus RFC 2.3/3.3: the `module_events` row in the same transaction | +| `WriteEvent` | mutation `m5` only: the event row in a later transaction | +| `Retain` | `jobs/canonicalization/processor.rs` `retain_candidate`; successors parked as `RetainReason::Orphaned` | +| `Reconcile` | `jobs/canonicalization/reconciliation.rs` `reconcile_chain_advance` / `reconcile_recoverable_path` through `promote_candidate` (`PromotableKind::Retained`, client-abandoned) | +| `Expire` | retained-row TTL (reconciliation step 1) | +| `Acquire`, `Notice` | `coordination/postgres/lease.rs` `try_acquire`; the old holder keeps sending until it notices | +| `SendNotify`, `SendGap` | RFC 3.3 notifier: read the cursor and the Gap obligation in one statement; while the obligation is open send only the Gap, otherwise the next event | +| `Receive` | RFC 3.3 module rules (the SDK `StatefulModule` helper): apply above the watermark, counters and watermark in one write; Gap re-seeds and sets `resume_from_nonce - 1` only if that raises the watermark | +| `ReceiveAck` | RFC 3.3: fenced cursor advance, conditional on the cursor position; the lease holder clears the Gap obligation once the module acknowledged the Gap | +| `LoseNotify`, `LoseAck` | timeouts and transport errors; the replica sends again | +| `DropBacklog` | RFC 3.3 retention (`GUARDIAN_MODULE_EVENT_RETENTION`): backlog dropped, `resync_required` | +| `OperatorResync` | RFC 2.2/3.3 `POST /dashboard/modules/{id}/resync`: one fenced write moving the cursor past every committed event and storing the Gap obligation (`gap_resume_from_nonce`, speckit data model) | + +## Scope and assumptions + +- Bounds: quick 3 deltas, cap 2, depth 2, two concurrent requests, two + replicas; deep up to 4 deltas, cap 3, amounts {1, 2}. A pass covers these + bounds only. +- One account, one module instance, one lifetime cap (no time windows, + `signed_at` not modeled), candidate mode only. Optimistic mode is out + (RFC 3.4 already says limits are exact only in candidate mode). +- Every delta needs the Guardian's ack, and a delta executes on chain only + on its parent state, so two deltas on one base exclude each other. + `SwitchGuardian` (executes without an ack) is out of scope. +- Retention lasts days and a request seconds, so no request is in flight + across a retention drop. +- A replica awaits each call before sending the next; late duplicates + reach the module from the other replica. `NotifyGap` is delayed or + duplicated but not lost: it is retried until acknowledged. A module + answering `UNIMPLEMENTED` (counts as acknowledged) is not modeled. +- A whole queue is retained in one step; real passes park the head first, + and the orphans stay listed (and counted) until the next pass, which is + only more conservative. +- Not modeled: the backlog cap, `require_fresh_state_ms`, the activation + fence, assignment and unassignment of the module (the RFC does not say + where delivery restarts when an instance is assigned again after + removal), `configure_account` moving the stored state out of band, and + the execution worker as a second ack path. +- The lease fence on cursor writes is not load-bearing here: the write is + also conditional on the cursor position, so dropping the fence alone + breaks nothing. Keep both anyway. +- Of the existing Rust, no single guard is load-bearing on its own for + these properties: the limit rests on the M2b design and on Miden + executing a delta only on its parent state. Drift in a mirrored function + usually means "check the model still says the same", not a bug. Example: + `Reconcile` requires the row's parent to be the stored state, which + `reconcile_chain_advance` enforces twice (the `obsolete_base` skip and + the `recomputed_commitment_mismatch` check); removing one leaves the + model unchanged. What would matter is a new state in which a signed + delta can still land while being neither queued nor committed, or a + new way to build on such a delta (F3's argument depends on parked + deltas never being the tail). + +## Mutations + +`check.sh --mutations` runs each; every one must fail: + +- `m1` pending counted without the watermark check: `NoDoubleCount`. +- `m2` NotifyGap re-seeds even when it does not raise the watermark (a + duplicated Gap rewinds the module): `NoOvershoot`. +- `m3` queue and unacknowledged events read in two transactions: + `NoOvershoot`. +- `m4` Notify applied without the watermark check: `NoDoubleApply`. +- `m5` the `module_events` row written outside the promotion transaction: + `NoOvershoot`. +- `m6` resync clears the refusal before the module acknowledges + `NotifyGap` (revision 22, F1): `NoOvershoot`. +- `m7` only the replica that ran the resync knows of the Gap obligation + (revision 22, F2): `NoOvershoot`. + +## When M2b is implemented + +Add the notifier, outbox write, `pending` builder and `StatefulModule` +helper functions to `mirrored.txt`, point the `Promote`, `Snapshot`, +`Send*`, `Receive*` and `OperatorResync` rows above at them, check that +each model step is still one transaction in the code, and run +`check.sh --accept-drift`. The conformance suite's resync cases (RFC 3.4) +correspond to `m6` and `m7`. diff --git a/.agents/skills/verify-module-counting/agents/openai.yaml b/.agents/skills/verify-module-counting/agents/openai.yaml new file mode 100644 index 00000000..15e552e5 --- /dev/null +++ b/.agents/skills/verify-module-counting/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Verify Module Counting" + short_description: "Model-check stateful module counting (RFC 0002 notify, pending, resync) with TLA+" + default_prompt: "Use $verify-module-counting to model-check this change to module notify delivery, pending, resync or the candidate lifecycle." diff --git a/.agents/skills/verify-module-counting/check.sh b/.agents/skills/verify-module-counting/check.sh new file mode 100755 index 00000000..ee36c641 --- /dev/null +++ b/.agents/skills/verify-module-counting/check.sh @@ -0,0 +1,191 @@ +#!/usr/bin/env bash +# Model-check stateful module counting (RFC 0002 sections 3.3, 3.4) with +# model/ModuleCounting.tla. +# +# check.sh quick tier (under a minute) +# check.sh --deep adds larger bounds (a few minutes) +# check.sh --mutations runs every broken variant; each must fail +# check.sh --cell run one cell from expected.txt, print TLC's +# full output and the trace +# check.sh --accept-drift re-record fingerprints.txt once the model has +# been reviewed against the changed source +# +# Exit codes: 0 every cell matches expected.txt and no drift; 1 a cell +# differs from expected.txt; 2 setup error; 3 cells match but source the +# model mirrors changed since fingerprints.txt was recorded. +set -euo pipefail + +SKILL_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_ROOT="$(cd "$SKILL_DIR/../../.." && pwd)" +MODEL_DIR="$SKILL_DIR/model" +TLA_VERSION="1.7.4" +TLA_SHA256="936a262061c914694dfd669a543be24573c45d5aa0ff20a8b96b23d01e050e88" +TLA_JAR="${TLA2TOOLS_JAR:-$HOME/.cache/guardian-tla/tla2tools-$TLA_VERSION.jar}" + +command -v java >/dev/null || { echo "java not found (brew install openjdk)"; exit 2; } +command -v python3 >/dev/null || { echo "python3 not found"; exit 2; } + +fingerprints() { + python3 -I "$SKILL_DIR/fingerprint.py" "$REPO_ROOT" "$SKILL_DIR/mirrored.txt" +} + +if [[ "${1:-}" == "--accept-drift" ]]; then + recorded="$(fingerprints)" + if grep -q " MISSING$" <<< "$recorded"; then + echo "Refusing to record: these mirrored entries were not found (renamed or removed?):" + grep " MISSING$" <<< "$recorded" | sed 's/^/ /' + echo "Update mirrored.txt to the current names, then rerun --accept-drift." + exit 2 + fi + printf '%s\n' "$recorded" > "$SKILL_DIR/fingerprints.txt" + echo "Recorded $(wc -l < "$SKILL_DIR/fingerprints.txt" | tr -d ' ') fingerprints." + exit 0 +fi + +sha256_of() { + if command -v sha256sum >/dev/null; then + sha256sum "$1" | cut -d' ' -f1 + elif command -v shasum >/dev/null; then + shasum -a 256 "$1" | cut -d' ' -f1 + else + echo "Neither sha256sum nor shasum is installed" >&2 + exit 2 + fi +} + +# Download to a temporary file and move it into the cache only once its +# checksum matches, so an interrupted or corrupted download never leaves a +# file at the cached path. +if [[ ! -f "$TLA_JAR" ]]; then + command -v curl >/dev/null || { echo "curl is not installed"; exit 2; } + mkdir -p "$(dirname "$TLA_JAR")" + echo "Downloading tla2tools $TLA_VERSION to $TLA_JAR" + partial="$TLA_JAR.partial.$$" + if ! curl -fsSL -o "$partial" \ + "https://github.com/tlaplus/tlaplus/releases/download/v$TLA_VERSION/tla2tools.jar"; then + rm -f "$partial" + echo "tla2tools download failed" + exit 2 + fi + downloaded_sha="$(sha256_of "$partial")" + if [[ "$downloaded_sha" != "$TLA_SHA256" ]]; then + rm -f "$partial" + echo "tla2tools checksum mismatch: $downloaded_sha (expected $TLA_SHA256)" + exit 2 + fi + mv "$partial" "$TLA_JAR" +fi +actual_sha="$(sha256_of "$TLA_JAR")" +if [[ "$actual_sha" != "$TLA_SHA256" ]]; then + echo "tla2tools checksum mismatch: $actual_sha (expected $TLA_SHA256); delete $TLA_JAR and rerun" + exit 2 +fi + +WORK="$(mktemp -d "${TMPDIR:-/tmp}/module-counting-tlc.XXXXXX")" +trap 'rm -rf "$WORK"' EXIT + +# The property a FAIL violated, as TLC names it. +violated_property() { + grep -m1 -Eo "^Error: Invariant [A-Za-z0-9_]+ is violated" "$1" | awk '{print $3}' +} + +# run_cell +# +run_cell() { + local name="$1" max_tx="$2" cap="$3" amounts="$4" depth="$5" requests="$6" + local resync="$7" mutation="$8" invariants="$9" out="${10}" + local dir="$WORK/$name" + mkdir -p "$dir" + cp "$MODEL_DIR/ModuleCounting.tla" "$dir/" + printf -- '---- MODULE MC ----\nEXTENDS ModuleCounting, TLC\nPerms == Permutations(Leaders) \\cup Permutations(Requests)\n====\n' > "$dir/MC.tla" + printf '%s\n' \ + 'CONSTANTS' \ + " Cap = $cap" \ + " Amounts = $amounts" \ + " MaxTx = $max_tx" \ + " Depth = $depth" \ + " Requests = $requests" \ + ' Leaders = {l1, l2}' \ + " Resync = $resync" \ + " Mutation = \"$mutation\"" \ + ' None = "none"' \ + 'SYMMETRY Perms' \ + 'SPECIFICATION Spec' \ + "INVARIANT ${invariants//,/ }" > "$dir/MC.cfg" + (cd "$dir" && java -XX:+UseParallelGC -cp "$TLA_JAR" tlc2.TLC \ + -workers "${TLC_WORKERS:-auto}" -cleanup -metadir "$dir/states" -config MC.cfg MC.tla < /dev/null) \ + > "$out" 2>&1 || true + if grep -q "Model checking completed. No error has been found." "$out"; then + echo PASS + elif grep -qE "^Error: Invariant [A-Za-z0-9_]+ is violated" "$out"; then + echo "FAIL:$(violated_property "$out")" + else + echo ERROR + fi +} + +# One line per step: the action and the variables it changed. +trace_steps() { + grep -E "^Error: .*violated" "$1" | sed 's/^/ /' + python3 -I "$SKILL_DIR/trace.py" "$1" | sed 's/^/ /' +} + +cells() { + grep -vE '^\s*(#|$)' "$SKILL_DIR/expected.txt" +} + +if [[ "${1:-}" == "--cell" ]]; then + [[ -n "${2:-}" ]] || { echo "usage: check.sh --cell "; exit 2; } + row="$(cells | awk -v c="$2" '$2 == c' | head -1)" + [[ -n "$row" ]] || { echo "no cell named $2 in expected.txt"; exit 2; } + read -r _tier name max_tx cap amounts depth requests resync mutation _expected invariants <<< "$row" + out="$WORK/cell.out" + verdict="$(run_cell "$name" "$max_tx" "$cap" "$amounts" "$depth" "$requests" "$resync" "$mutation" "$invariants" "$out")" + cat "$out" + echo + echo "$name: $verdict" + [[ "$verdict" == FAIL:* ]] && { echo "Steps:"; trace_steps "$out"; } + case "$verdict" in + PASS) exit 0 ;; + FAIL:*) exit 1 ;; + *) exit 2 ;; + esac +fi + +case "${1:-}" in + --deep) tiers="quick deep" ;; + --mutations) tiers="mutation" ;; + "") tiers="quick" ;; + *) echo "unknown option $1"; exit 2 ;; +esac + +status=0 +while read -r tier name max_tx cap amounts depth requests resync mutation expected invariants; do + [[ " $tiers " == *" $tier "* ]] || continue + out="$WORK/$name.out" + started=$SECONDS + verdict="$(run_cell "$name" "$max_tx" "$cap" "$amounts" "$depth" "$requests" "$resync" "$mutation" "$invariants" "$out")" + states="$(grep -Eo '[0-9]+ distinct states found' "$out" | tail -1 || true)" + line="$name: $verdict (expected $expected; ${states:-no state count}; $((SECONDS - started))s)" + if [[ "$verdict" == "$expected" ]]; then + echo "ok $line" + else + status=1 + echo "DIFF $line" + if [[ "$verdict" == FAIL:* ]]; then + echo " counterexample (full trace: check.sh --cell $name):" + trace_steps "$out" + else + { grep -E -A8 "^Error" "$out" || true; } | head -24 | sed 's/^/ /' + fi + fi +done < <(cells) + +if ! diff -u "$SKILL_DIR/fingerprints.txt" <(fingerprints) > "$WORK/drift.diff"; then + echo + echo "DRIFT: source that the model mirrors changed since fingerprints.txt was recorded:" + { grep -E '^[-+][^-+]' "$WORK/drift.diff" || true; } | sed 's/^/ /' + echo "Review the matching actions in model/ModuleCounting.tla (SKILL.md, action map), then run check.sh --accept-drift." + [[ $status -eq 0 ]] && status=3 +fi +exit $status diff --git a/.agents/skills/verify-module-counting/expected.txt b/.agents/skills/verify-module-counting/expected.txt new file mode 100644 index 00000000..6a22aa12 --- /dev/null +++ b/.agents/skills/verify-module-counting/expected.txt @@ -0,0 +1,23 @@ +# tier cell max_tx cap amounts depth requests resync mutation expected invariants +# +# counting*: no retention drop. resync*: retention drop and operator resync +# (RFC 0002 revision 23). A cell expected to FAIL checks one invariant so +# its verdict names it. +# +# recoverable is expected to fail: Retained and client-abandoned rows are +# outside pending by design (RFC 3.4, "Recoverable rows"); NoOvershoot in +# the counting cells is what shows that is safe. +quick counting 3 2 {1} 2 {q1,q2} FALSE none PASS NoDoubleApply,NoOvershoot,NoDoubleCount,CountsQueueAndCommitted +quick recoverable 3 2 {1} 2 {q1,q2} FALSE none FAIL:CountsRecoverable CountsRecoverable +quick resync 3 2 {1} 2 {q1,q2} TRUE none PASS NoDoubleApply,NoOvershoot,NoDoubleCount,CountsQueueAndCommitted +deep counting-4 4 3 {1} 2 {q1,q2} FALSE none PASS NoDoubleApply,NoOvershoot,NoDoubleCount,CountsQueueAndCommitted +deep counting-amt 4 3 {1,2} 2 {q1,q2} FALSE none PASS NoDoubleApply,NoOvershoot,NoDoubleCount,CountsQueueAndCommitted +deep resync-4 4 3 {1} 2 {q1,q2} TRUE none PASS NoDoubleApply,NoOvershoot,NoDoubleCount,CountsQueueAndCommitted +deep resync-amt 4 3 {1,2} 2 {q1} TRUE none PASS NoDoubleApply,NoOvershoot,NoDoubleCount,CountsQueueAndCommitted +mutation m1 3 2 {1} 2 {q1,q2} FALSE m1 FAIL:NoDoubleCount NoDoubleCount +mutation m2 3 2 {1} 2 {q1,q2} TRUE m2 FAIL:NoOvershoot NoOvershoot +mutation m3 3 2 {1} 2 {q1,q2} FALSE m3 FAIL:NoOvershoot NoOvershoot +mutation m4 3 2 {1} 2 {q1,q2} FALSE m4 FAIL:NoDoubleApply NoDoubleApply +mutation m5 3 2 {1} 2 {q1,q2} FALSE m5 FAIL:NoOvershoot NoOvershoot +mutation m6 3 2 {1} 2 {q1,q2} TRUE m6 FAIL:NoOvershoot NoOvershoot +mutation m7 3 2 {1} 2 {q1,q2} TRUE m7 FAIL:NoOvershoot NoOvershoot diff --git a/.agents/skills/verify-module-counting/fingerprint.py b/.agents/skills/verify-module-counting/fingerprint.py new file mode 100644 index 00000000..f96a7ab1 --- /dev/null +++ b/.agents/skills/verify-module-counting/fingerprint.py @@ -0,0 +1,71 @@ +"""Print a hash of every Rust function and RFC section this skill's model mirrors. + +Usage: fingerprint.py + +mirrored.txt lists " " per line. + +For a .rs file, is a function name: its text runs from its +`fn ` line to the brace that closes its body, and every definition +with that name in the file is hashed together, so trait impls and wrappers +of the same name count too. + +For a .md file, is a section number such as 3.4: the section runs +from the heading whose text starts with that number to the next heading +of the same or a higher level. +""" + +import hashlib +import re +import sys + + +def rust_bodies(source, name): + pattern = re.compile(r"^\s*(pub(\([^)]*\))?\s+)?(async\s+)?fn\s+" + re.escape(name) + r"\b", re.M) + for match in pattern.finditer(source): + depth = 0 + opened = False + for index in range(match.start(), len(source)): + char = source[index] + if char == "{": + depth += 1 + opened = True + elif char == "}": + depth -= 1 + if opened and depth == 0: + yield source[match.start(): index + 1] + break + elif char == ";" and not opened: + yield source[match.start(): index + 1] + break + + +def markdown_sections(source, number): + lines = source.splitlines(keepends=True) + heading = re.compile(r"^(#+)\s+(.*)$") + for start, line in enumerate(lines): + match = heading.match(line) + if not match or not match.group(2).startswith(number + " "): + continue + level = len(match.group(1)) + end = len(lines) + for index in range(start + 1, len(lines)): + other = heading.match(lines[index]) + if other and len(other.group(1)) <= level: + end = index + break + yield "".join(lines[start:end]) + + +def main(): + root, listing = sys.argv[1], sys.argv[2] + with open(listing) as handle: + entries = [line.split() for line in handle if line.strip() and not line.startswith("#")] + for path, name in entries: + with open(f"{root}/{path}") as handle: + source = handle.read() + found = list(markdown_sections(source, name) if path.endswith(".md") else rust_bodies(source, name)) + digest = hashlib.sha256("\n".join(found).encode()).hexdigest()[:16] if found else "MISSING" + print(f"{path} {name} {digest}") + + +main() diff --git a/.agents/skills/verify-module-counting/fingerprints.txt b/.agents/skills/verify-module-counting/fingerprints.txt new file mode 100644 index 00000000..5e8f9aa1 --- /dev/null +++ b/.agents/skills/verify-module-counting/fingerprints.txt @@ -0,0 +1,13 @@ +docs/rfcs/0002-guardian-modules.md 3.3 9f760f07762f1ecd +docs/rfcs/0002-guardian-modules.md 3.4 285f90b0ba171cf0 +crates/server/src/services/push_delta.rs push_delta 54b60bb855977653 +crates/server/src/storage/mod.rs gate_candidate_submission 99785be2d52ca367 +crates/server/src/storage/mod.rs classify_chain_position ebe38e956458a637 +crates/server/src/storage/mod.rs first_unchained_candidate 3708394aa8e3541c +crates/server/src/storage/postgres.rs submit_candidate 7afed2b7a0c8a186 +crates/server/src/storage/postgres.rs promote_candidate e198deeb1cbcd95d +crates/server/src/storage/postgres.rs update_candidate_status 3ee992cfd204ab19 +crates/server/src/jobs/canonicalization/processor.rs retain_candidate 813bb75dd428ee39 +crates/server/src/jobs/canonicalization/reconciliation.rs reconcile_chain_advance 29b83278a35d3d6f +crates/server/src/jobs/canonicalization/reconciliation.rs reconcile_recoverable_path 7a132b53248e9701 +crates/server/src/coordination/postgres/lease.rs try_acquire acd5be995d0ebf4f diff --git a/.agents/skills/verify-module-counting/mirrored.txt b/.agents/skills/verify-module-counting/mirrored.txt new file mode 100644 index 00000000..eaa61504 --- /dev/null +++ b/.agents/skills/verify-module-counting/mirrored.txt @@ -0,0 +1,17 @@ +# Source modeled in model/ModuleCounting.tla: " " for Rust, +# "
" for the RFC. The notifier, the outbox and +# `pending` exist only in the RFC until M2b lands; add their functions here +# when they do (SKILL.md, "When M2b is implemented"). +docs/rfcs/0002-guardian-modules.md 3.3 +docs/rfcs/0002-guardian-modules.md 3.4 +crates/server/src/services/push_delta.rs push_delta +crates/server/src/storage/mod.rs gate_candidate_submission +crates/server/src/storage/mod.rs classify_chain_position +crates/server/src/storage/mod.rs first_unchained_candidate +crates/server/src/storage/postgres.rs submit_candidate +crates/server/src/storage/postgres.rs promote_candidate +crates/server/src/storage/postgres.rs update_candidate_status +crates/server/src/jobs/canonicalization/processor.rs retain_candidate +crates/server/src/jobs/canonicalization/reconciliation.rs reconcile_chain_advance +crates/server/src/jobs/canonicalization/reconciliation.rs reconcile_recoverable_path +crates/server/src/coordination/postgres/lease.rs try_acquire diff --git a/.agents/skills/verify-module-counting/model/ModuleCounting.tla b/.agents/skills/verify-module-counting/model/ModuleCounting.tla new file mode 100644 index 00000000..fdb45b39 --- /dev/null +++ b/.agents/skills/verify-module-counting/model/ModuleCounting.tla @@ -0,0 +1,411 @@ +--------------------------- MODULE ModuleCounting --------------------------- +(***************************************************************************) +(* RFC 0002 (docs/rfcs/0002-guardian-modules.md) sections 3.3 and 3.4: *) +(* how a stateful module (a spending cap) counts what the Guardian signed *) +(* for one account. The module keeps counters and a nonce watermark *) +(* updated from Notify; every Evaluate carries `pending`, the candidates *) +(* and the committed-but-unacknowledged events read in one snapshot. *) +(* *) +(* One step is one storage transaction, one module write, one message *) +(* delivery, or one on-chain execution. Transactions form a tree: each *) +(* signed delta names its parent state, and the chain executes a delta *) +(* only on top of its parent, so two deltas on one base exclude each *) +(* other on chain. Every amount is spent only once it executes on chain. *) +(***************************************************************************) +EXTENDS Naturals, Sequences, FiniteSets + +CONSTANTS + Cap, \* the module's spending cap for the account + Amounts, \* amounts a transaction may carry + MaxTx, \* deltas the Guardian may sign in one behaviour + Depth, \* GUARDIAN_MAX_PENDING_CANDIDATES + Requests, \* concurrent push_delta requests + Leaders, \* replicas that can hold the notifier lease + Resync, \* retention drop and operator resync are possible + Mutation \* "none", or a broken variant (SKILL.md, "Mutations") + +ASSUME Mutation \in {"none", "m1", "m2", "m3", "m4", "m5", "m6", "m7"} + +None == "none" + +VARIABLES + txs, \* signed deltas: txs[t] = [parent, nonce, amt]; parent 0 is the registered state + canon, \* the stored (canonical) state: a delta id, 0 before any + queue, \* candidate queue, oldest first; queue[1].parent = canon + retained, \* recoverable rows: Retained and client-abandoned deltas (issue #345) + events, \* module_events outbox, in commit order + unwritten, \* m5 only: a promoted delta whose event row is not written yet (0 = none) + chain, \* deltas executed on chain, in order + req, \* push_delta requests in flight + cnt, \* module counter (sum of applied amounts) + wm, \* module delivery watermark (highest applied nonce) + applied, \* ghost: deltas whose amount is in cnt + evalLog, \* ghost: double counts of the last evaluation, misses of the last admitted one + cursor, \* acknowledged prefix of `events` for this (module, account) + holder, \* replica holding the notifier lease + believes, \* replicas that believe they hold it (a stale holder still does) + msgs, \* Notify / NotifyGap calls in flight to the module + acks, \* NotifyAck replies in flight back to replicas + resyncReq, \* resync_required for the (module, account) pair + gapOwed, \* the Gap obligation stored with the cursor (gap_resume_from_nonce set) + gapOwner, \* the replica that ran the resync (only it knows of the Gap under m7) + resume \* resume_from_nonce of the latest resync + +vars == <> + +guardianVars == <> +moduleVars == <> +notifyVars == <> + +Nonce(t) == IF t = 0 THEN 0 ELSE txs[t].nonce +Amt(t) == txs[t].amt +Ids == 1..Len(txs) +Elems(s) == {s[i] : i \in 1..Len(s)} +QueueTail == IF queue = <<>> THEN canon ELSE queue[Len(queue)] +ChainTip == IF chain = <<>> THEN 0 ELSE chain[Len(chain)] + +\* The deltas a state was built from: the committed history and the queue. +RECURSIVE Path(_) +Path(t) == IF t = 0 THEN {} ELSE {t} \cup Path(txs[t].parent) + +RECURSIVE Sum(_) +Sum(S) == IF S = {} THEN 0 ELSE LET t == CHOOSE x \in S : TRUE IN Amt(t) + Sum(S \ {t}) + +Unacked == {events[i] : i \in (cursor + 1)..Len(events)} +\* RFC 3.3 (revision 23): refused under resync_required and until the +\* module acknowledges the resync's NotifyGap. +EvalBlocked == resyncReq \/ (gapOwed /\ Mutation # "m6") +NoMiss == [live |-> {}, recov |-> {}] +Idle == [phase |-> "idle", base |-> 0, amt |-> 0, pend |-> {}, live |-> {}, recov |-> {}, + blocked |-> FALSE, missed |-> NoMiss] + +\* RFC 3.3 (revision 23): every replica reads the cursor and the Gap +\* obligation in one statement and sends no event while it is open. +GapVisible(l) == gapOwed /\ (Mutation # "m7" \/ l = gapOwner) + +\* A replica awaits each call: it sends again only once the reply arrived +\* or the call or its reply was lost (a timeout). Late duplicates still +\* reach the module from the other replica. +Awaiting(l) == (\E m \in msgs : m.from = l) \/ (\E a \in acks : a.to = l) + +Init == + /\ txs = <<>> + /\ canon = 0 + /\ queue = <<>> + /\ retained = {} + /\ events = <<>> + /\ unwritten = 0 + /\ chain = <<>> + /\ req = [r \in Requests |-> Idle] + /\ cnt = 0 + /\ wm = 0 + /\ applied = {} + /\ evalLog = [double |-> {}, missedLive |-> {}, missedRecoverable |-> {}] + /\ cursor = 0 + /\ holder \in Leaders + /\ believes = {holder} + /\ msgs = {} + /\ acks = {} + /\ resyncReq = FALSE + /\ gapOwed = FALSE + /\ gapOwner = None + /\ resume = 0 + +(***************************************************************************) +(* push_delta: snapshot, evaluate, store. *) +(***************************************************************************) + +\* push_delta reads the candidate queue (services/push_delta.rs) and, per +\* RFC 3.4, builds `pending` from the queue and the unacknowledged events in +\* one repeatable-read transaction, together with resync_required. The +\* client built its delta on the tail it knows. +Snapshot(r) == + /\ req[r].phase = "idle" + /\ Len(txs) < MaxTx + /\ \E a \in Amounts : + req' = [req EXCEPT ![r] = + [phase |-> IF Mutation = "m3" THEN "half" ELSE "snap", + base |-> QueueTail, amt |-> a, + pend |-> IF Mutation = "m3" THEN Unacked ELSE Unacked \cup Elems(queue), + live |-> Path(QueueTail), + recov |-> retained, + blocked |-> EvalBlocked, + missed |-> NoMiss]] + /\ UNCHANGED <> + +\* m3 only: the queue is read in a second transaction after the events. +SnapshotQueue(r) == + /\ req[r].phase = "half" + /\ req' = [req EXCEPT ![r].phase = "snap", ![r].pend = @ \cup Elems(queue)] + /\ UNCHANGED <> + +\* The module's Evaluate: counters and watermark from one consistent read of +\* its state, plus every pending entry above the watermark (RFC 3.4). Under +\* resync_required the call is not made and on_error = deny refuses. +Evaluate(r) == + /\ req[r].phase = "snap" + /\ LET p == req[r].pend + counted == {t \in p : Mutation = "m1" \/ Nonce(t) > wm} + total == cnt + Sum(counted) + req[r].amt + seen == req[r].live \cup req[r].recov + IN /\ evalLog' = [evalLog EXCEPT !.double = counted \cap applied] + /\ req' = [req EXCEPT + ![r].phase = IF ~req[r].blocked /\ total <= Cap THEN "allowed" ELSE "idle", + ![r].missed = [live |-> (seen \cap Path(QueueTail)) + \ (applied \cup counted), + recov |-> (seen \cap retained) \ (applied \cup counted)]] + /\ UNCHANGED <> + +\* The candidate gate (storage/mod.rs gate_candidate_submission) under the +\* account lock: the delta must extend the current tail and the queue must +\* have room. Admission deletes a recoverable row at the same nonce +\* (storage/postgres.rs submit_candidate, "reconcile_superseded"). Only an +\* admitted delta's ack signature is returned. +Store(r) == + /\ req[r].phase = "allowed" + /\ LET t == Len(txs) + 1 + n == Nonce(req[r].base) + 1 + IN IF req[r].base = QueueTail /\ Len(queue) < Depth /\ Len(txs) < MaxTx + THEN /\ txs' = Append(txs, [parent |-> req[r].base, nonce |-> n, amt |-> req[r].amt]) + /\ queue' = Append(queue, t) + /\ retained' = {x \in retained : txs[x].nonce # n} + /\ evalLog' = [evalLog EXCEPT !.missedLive = req[r].missed.live, + !.missedRecoverable = req[r].missed.recov] + ELSE UNCHANGED <> + /\ req' = [req EXCEPT ![r] = Idle] + /\ UNCHANGED <> + +(***************************************************************************) +(* Chain and canonicalization. *) +(***************************************************************************) + +\* A cosigner submits any signed delta; it executes only on its parent. +Execute(t) == + /\ t \in Ids + /\ txs[t].parent = ChainTip + /\ t \notin Elems(chain) + /\ chain' = Append(chain, t) + /\ UNCHANGED <> + +\* promote_candidate (storage/postgres.rs) once the head is on chain. RFC +\* 2.3/3.3: the module_events row is written in the same transaction. +Promote == + /\ queue # <<>> + /\ unwritten = 0 + /\ Head(queue) \in Elems(chain) + /\ canon' = Head(queue) + /\ queue' = Tail(queue) + /\ IF Mutation = "m5" + THEN /\ unwritten' = Head(queue) + /\ UNCHANGED events + ELSE /\ events' = Append(events, Head(queue)) + /\ UNCHANGED unwritten + /\ UNCHANGED <> + +\* m5 only: the outbox row lands in a later transaction than the promotion. +WriteEvent == + /\ unwritten # 0 + /\ events' = Append(events, unwritten) + /\ unwritten' = 0 + /\ UNCHANGED <> + +\* retain_candidate (jobs/canonicalization/processor.rs): a head the worker +\* could not confirm is parked, and its successors are retained as orphans. +\* The verdict may be spurious: the delta can still land. +Retain == + /\ queue # <<>> + /\ retained' = retained \cup Elems(queue) + /\ queue' = <<>> + /\ UNCHANGED <> + +\* reconcile_chain_advance / reconcile_recoverable_path (reconciliation.rs): +\* a recoverable row that chains from the stored base and landed is promoted +\* through promote_candidate (PromotableKind::Retained), writing its event. +\* A queue that no longer chains from the new base is orphaned. +Reconcile(t) == + /\ unwritten = 0 + /\ t \in retained + /\ txs[t].parent = canon + /\ t \in Elems(chain) + /\ canon' = t + /\ retained' = (retained \ {t}) \cup Elems(queue) + /\ queue' = <<>> + /\ events' = Append(events, t) + /\ UNCHANGED <> + +\* Retained-row TTL (reconciliation.rs step 1). +Expire(t) == + /\ t \in retained + /\ retained' = retained \ {t} + /\ UNCHANGED <> + +(***************************************************************************) +(* Notify delivery (RFC 3.3) on the notifier lease. *) +(***************************************************************************) + +\* try_acquire (coordination/postgres/lease.rs): a replica takes the lease; +\* the previous holder keeps believing it holds it until it notices. +Acquire(l) == + /\ holder # l + /\ holder' = l + /\ believes' = believes \cup {l} + /\ UNCHANGED <> + +Notice(l) == + /\ l \in believes + /\ l # holder + /\ believes' = believes \ {l} + /\ UNCHANGED <> + +\* Read the cursor, send the next event. +SendNotify(l) == + /\ l \in believes + /\ ~Awaiting(l) + /\ ~resyncReq + /\ ~GapVisible(l) + /\ cursor < Len(events) + /\ msgs' = msgs \cup {[kind |-> "notify", tx |-> events[cursor + 1], from |-> l]} + /\ UNCHANGED <> + +SendGap(l) == + /\ l \in believes + /\ ~Awaiting(l) + /\ GapVisible(l) + /\ msgs' = msgs \cup {[kind |-> "gap", resume |-> resume, from |-> l]} + /\ UNCHANGED <> + +\* The module (the SDK's StatefulModule helper): apply an event only above +\* the watermark, counters and watermark in one write; on NotifyGap re-seed +\* from its own sources (here: the chain) and set the watermark to +\* resume_from_nonce - 1, only if that raises it. +Receive(m) == + /\ m \in msgs + /\ msgs' = msgs \ {m} + /\ IF m.kind = "notify" + THEN /\ IF Nonce(m.tx) > wm \/ Mutation = "m4" + THEN /\ cnt' = cnt + Amt(m.tx) + /\ wm' = IF Nonce(m.tx) > wm THEN Nonce(m.tx) ELSE wm + /\ applied' = applied \cup {m.tx} + ELSE UNCHANGED moduleVars + /\ acks' = acks \cup {[kind |-> "notify", tx |-> m.tx, to |-> m.from]} + ELSE /\ IF m.resume - 1 > wm \/ Mutation = "m2" + THEN LET seed == {t \in Elems(chain) : Nonce(t) < m.resume} + IN /\ cnt' = Sum(seed) + /\ wm' = m.resume - 1 + /\ applied' = seed + ELSE UNCHANGED moduleVars + /\ acks' = acks \cup {[kind |-> "gap", resume |-> m.resume, to |-> m.from]} + /\ UNCHANGED <> + +\* Fenced cursor write: only the current holder advances the cursor, and +\* only past the event it delivered. +ReceiveAck(a) == + /\ a \in acks + /\ acks' = acks \ {a} + /\ IF a.kind = "notify" + THEN /\ cursor' = IF a.to = holder /\ cursor < Len(events) /\ events[cursor + 1] = a.tx + THEN cursor + 1 ELSE cursor + /\ UNCHANGED gapOwed + ELSE /\ gapOwed' = IF a.to = holder /\ a.resume = resume THEN FALSE ELSE gapOwed + /\ UNCHANGED cursor + /\ UNCHANGED <> + +\* Calls and replies can be lost (timeouts, transport errors); the replica +\* then sends again. A failed NotifyGap is retried until acknowledged +\* (RFC 3.3), so Gap calls are delayed and +\* duplicated here but not lost. +LoseNotify(m) == + /\ m \in msgs + /\ m.kind = "notify" + /\ msgs' = msgs \ {m} + /\ UNCHANGED <> + +LoseAck(a) == + /\ a \in acks + /\ acks' = acks \ {a} + /\ UNCHANGED <> + +(***************************************************************************) +(* Retention and resync (RFC 3.3). *) +(***************************************************************************) + +\* The subscriber fell GUARDIAN_MODULE_EVENT_RETENTION behind: its backlog +\* is dropped and the pair enters resync_required. Retention is days and a +\* request lives for seconds, so no request is in flight across it. +DropBacklog == + /\ Resync + /\ ~resyncReq + /\ cursor < Len(events) + /\ \A r \in Requests : req[r].phase = "idle" + /\ resyncReq' = TRUE + /\ UNCHANGED <> + +\* POST /dashboard/modules/{id}/resync, one write fenced by the lease +\* holder: the cursor moves past every committed event and the Gap +\* obligation is stored with it, resume_from_nonce one above the last +\* skipped event (RFC 3.3, revision 23). +OperatorResync == + /\ resyncReq + /\ resyncReq' = FALSE + /\ cursor' = Len(events) + /\ resume' = Nonce(canon) + 1 + /\ gapOwed' = TRUE + /\ gapOwner' = holder + /\ UNCHANGED <> + +\* One named disjunct per action, so TLC's trace names every step. +ExecuteOnChain == \E t \in Ids : Execute(t) +ReconcileRow == \E t \in Ids : Reconcile(t) +ExpireRow == \E t \in Ids : Expire(t) +ModuleReceives == \E m \in msgs : Receive(m) +CallLost == \E m \in msgs : LoseNotify(m) +ReplyArrives == \E a \in acks : ReceiveAck(a) +ReplyLost == \E a \in acks : LoseAck(a) + +Next == + \/ \E r \in Requests : Snapshot(r) \/ SnapshotQueue(r) \/ Evaluate(r) \/ Store(r) + \/ ExecuteOnChain \/ ReconcileRow \/ ExpireRow + \/ Promote \/ WriteEvent \/ Retain + \/ \E l \in Leaders : Acquire(l) \/ Notice(l) \/ SendNotify(l) \/ SendGap(l) + \/ ModuleReceives \/ CallLost \/ ReplyArrives \/ ReplyLost + \/ DropBacklog \/ OperatorResync + +Spec == Init /\ [][Next]_vars + +(***************************************************************************) +(* Properties. *) +(***************************************************************************) + +\* The harm: the account spends more on chain than the cap allows. +NoOvershoot == Sum(Elems(chain)) <= Cap + +\* RFC 3.4: no evaluation counts a delta twice (harm: a payment that fits +\* is refused). +NoDoubleCount == evalLog.double = {} + +\* RFC 3.4, for every evaluation whose delta is then admitted: each delta +\* that was committed or queued at the snapshot, and still is when the +\* module evaluates, is counted ("never both and never neither"). A delta +\* superseded or expired in between is gone and need not count; a refused +\* delta is never signed, so what its evaluation missed cannot overspend. +CountsQueueAndCommitted == evalLog.missedLive = {} + +\* The same for deltas that are recoverable (Retained or client-abandoned) +\* when the module evaluates: signed, able to land, and outside `pending` +\* as RFC 3.4 defines it. +CountsRecoverable == evalLog.missedRecoverable = {} + +\* The module's counter holds each applied delta once (harm of a double +\* apply: payments that fit are refused). +NoDoubleApply == cnt = Sum(applied) +============================================================================= diff --git a/.agents/skills/verify-module-counting/trace.py b/.agents/skills/verify-module-counting/trace.py new file mode 100644 index 00000000..ab43c9e1 --- /dev/null +++ b/.agents/skills/verify-module-counting/trace.py @@ -0,0 +1,83 @@ +"""Print a TLC counterexample one step per line: the action and what it changed. + +Usage: trace.py + +Requests are shown as " base= pending=" so a +step reads like push_delta's progress; other variables print as TLC +writes them. Delta ids are indices into `txs`. +""" + +import re +import sys + +STEP = re.compile(r"^State (\d+): <(\w+)[^>]*>$") +VAR = re.compile(r"^/\\ (\w+) = (.*)$") +REQUEST = re.compile(r"(q\d+) :> \[(.*?)\]") + + +def states(lines): + current = None + for line in lines: + step = STEP.match(line) + if step: + if current: + yield current + current = {"n": step.group(1), "action": step.group(2), "vars": {}} + name = None + continue + if current is None: + continue + if not line.strip(): + yield current + current = None + continue + var = VAR.match(line) + if var: + name = var.group(1) + current["vars"][name] = var.group(2) + elif name: + current["vars"][name] += " " + line.strip() + if current: + yield current + + +def field(record, key): + match = re.search(key + r" \|-> (\{[^}]*\}|\"\w+\"|\w+)", record) + return match.group(1).strip('"') if match else "?" + + +def show(name, value): + value = re.sub(r"\s+", " ", value) + if name == "req": + return "; ".join( + f"{request} {field(body, 'phase')} base={field(body, 'base')} pending={field(body, 'pend')}" + for request, body in REQUEST.findall(value) + ) + if name == "txs": + rows = re.findall(r"\[([^\]]*)\]", value) + return "txs: " + ", ".join( + f"{i + 1}=(parent {field(r, 'parent')}, nonce {field(r, 'nonce')}, amt {field(r, 'amt')})" + for i, r in enumerate(rows) + ) + return f"{name}={value}" + + +def main(): + with open(sys.argv[1]) as handle: + lines = handle.read().splitlines() + start = next((i for i, line in enumerate(lines) if line.startswith("Error: The behavior")), None) + if start is None: + return + previous = {} + for state in states(lines[start:]): + changed = [ + show(name, value) + for name, value in state["vars"].items() + if previous.get(name) != value and (state["n"] != "1" or name in ("holder", "believes")) + ] + action = state["action"] + print(f"{state['n']:>3}. {action:16} {' | '.join(changed)}") + previous = state["vars"] + + +main() diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md index 43f1b6ef..6295e3a6 100644 --- a/docs/CONFIGURATION.md +++ b/docs/CONFIGURATION.md @@ -374,6 +374,17 @@ closed** (rejected, never bypassed) and recovers automatically. See the Allowlist payload shapes and enrollment flow: [`docs/DASHBOARD.md`](./DASHBOARD.md). +## Runtime: policy modules + +Prototype (RFC 0002, issue #251); not in a release yet. See the [policy +modules guide](./guides/policy-modules/README.md). + +| Variable | Default | Notes | +|---|---|---| +| `GUARDIAN_MODULES_CONFIG` | _unset_ (no modules) | Path of the module catalog (TOML). Read once at startup; it declares every instance and seeds its global params on first start, after which params are managed through the [operator API](./DASHBOARD.md#policy-modules). A relative path resolves against the working directory; relative `auth.token_file` and `tls.*_file` paths in the catalog resolve against the catalog's directory. An enabled instance that fails its startup checks stops startup. In the prod stage remote instances must use TLS (`grpc://`) and set `auth`. | +| `GUARDIAN_MODULE_CHECK_RATE_PER_MIN` | `30` | Dry-run proposal checks (`POST /delta/proposal/check`) one signer may make for one account per minute; excess returns `rate_limit_exceeded`. Per replica. A value that is not a positive integer refuses startup. | +| `GUARDIAN_MODULES_STATE` | `/modules` | Filesystem builds only: directory of the module state file (`module_state.json`). Postgres builds keep module state in the database. | + ## Runtime — EVM (feature-gated) These take effect only when the server is built with `--features evm`. diff --git a/docs/DASHBOARD.md b/docs/DASHBOARD.md index bcc4c7cc..20650701 100644 --- a/docs/DASHBOARD.md +++ b/docs/DASHBOARD.md @@ -344,7 +344,9 @@ load time so a typo surfaces explicitly |---|---| | `dashboard:read` | Read access to all `/dashboard/*` read endpoints. | | `accounts:pause` | Pause/unpause accounts. | -| `policies:write` | Reserved for future policy writes — no endpoint currently requires it. | +| `policies:write` | Policy module writes for one account (account layers, assignments) and enabling or disabling module instances ([Policy modules](#policy-modules)). | +| `policies:write_global` | Policy module global params, which apply to every account. | +| `modules:disable` | Disabling a module instance that the catalog marks `operator_can_disable`, without any other policy write. | | `stats:refresh` | Request an out-of-cycle refresh of the `/dashboard/stats` aggregate (`POST /dashboard/stats/refresh`, issue #371). | Wire strings are **case-sensitive** and **must not contain whitespace** — @@ -352,9 +354,36 @@ the parser rejects both. > **Current scope:** `dashboard:read` gates all read endpoints. > `accounts:pause` gates the pause/unpause endpoints (see [Account -> pausing](#account-pausing) below). `policies:write` is reserved -> vocabulary — accepted by the allowlist parser but no endpoint requires -> it yet. +> pausing](#account-pausing) below). `policies:write`, +> `policies:write_global` and `modules:disable` gate the policy module +> writes (see [Policy modules](#policy-modules) below). + +## Policy modules + +Prototype (RFC 0002, issue #251); not in a release yet. The endpoints +manage the module instances the catalog file declares +([`GUARDIAN_MODULES_CONFIG`](./CONFIGURATION.md#runtime-policy-modules)); +they cannot add, remove or reconfigure an instance. Every write takes a +`reason`, is validated by the module before it is stored, and is recorded +in the params history and the audit log. A walkthrough is in the +[policy modules guide](./guides/policy-modules/README.md). + +| Endpoint | Permission | Body | +|---|---|---| +| `GET /dashboard/modules` | `dashboard:read` | | +| `GET /dashboard/modules/{module_id}/params/history` | `dashboard:read` | | +| `GET /dashboard/accounts/{account_id}/modules` | `dashboard:read` | | +| `PUT /dashboard/modules/{module_id}/params` | `policies:write_global` | `{"params": {...}, "reason": "..."}` | +| `PUT /dashboard/accounts/{account_id}/modules/{module_id}/params` | `policies:write` | `{"params": {...}, "reason": "..."}` | +| `DELETE /dashboard/accounts/{account_id}/modules/{module_id}/params` | `policies:write` | `{"reason": "..."}` | +| `PUT /dashboard/accounts/{account_id}/modules` | `policies:write` | `{"modules": [{"module_id": "...", "params": {...}}], "reason": "..."}` | +| `POST /dashboard/modules/{module_id}/enable` | `policies:write` | `{"reason": "..."}` | +| `POST /dashboard/modules/{module_id}/disable` | `policies:write` or `modules:disable` | `{"reason": "..."}` | + +On a `scope = all` instance the per-account params are a layer evaluated +after the global params, and both must allow, so a layer only adds +restrictions. Disabling an instance the catalog does not mark +`operator_can_disable` returns `409 GUARDIAN_MODULE_NOT_DISABLEABLE`. ## Account pausing diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md index 13b818a8..7afb128b 100644 --- a/docs/TROUBLESHOOTING.md +++ b/docs/TROUBLESHOOTING.md @@ -982,6 +982,8 @@ Causes of a `failed` execution, in `error.code`: | `GUARDIAN_EXECUTION_BINDING_MISMATCH`, `GUARDIAN_EXECUTION_STATE_MISMATCH`, `GUARDIAN_EXECUTION_REQUEST_CODEC`, `GUARDIAN_EXECUTION_PROTOCOL_MISMATCH`, `GUARDIAN_EXECUTION_INSUFFICIENT_FEE`, `GUARDIAN_EXECUTION_EXPIRATION_BEYOND_HORIZON`, `GUARDIAN_EXECUTION_ACCOUNT_INADMISSIBLE` | none | Not until the cause is fixed. | | `GUARDIAN_EXECUTION_INSUFFICIENT_SIGNATURES` | none | Yes, once more cosigners have signed; the proposal is untouched. | | `GUARDIAN_EXECUTION_SUBMISSION_NOT_PROCESSED` | none | Yes; the node refused the send before processing it (a rate limit that outlasted the client's retries, an authentication or permission refusal, an unimplemented call, or inputs sealed against an encryption key the validator no longer holds), so the transaction cannot land and the proposal is kept. Check the node endpoint and its limits if it repeats. | +| `GUARDIAN_EXECUTION_MODULE_DENIED` | `reason_code`, plus `module`, `layer` and `client_message` unless the instance reports generic denials (`reason_code: policy_denied` only) | Not while the policy holds; the proposal is untouched. Only on servers built with policy modules. | +| `GUARDIAN_EXECUTION_MODULE_UNAVAILABLE` | `module` | Yes, once the fail-closed module answers again; the proposal is untouched. | | `GUARDIAN_EXECUTION_SUBMISSION_REJECTED`, `GUARDIAN_EXECUTION_CANDIDATE_DISCARDED`, `GUARDIAN_EXECUTION_EXPIRED` | none | No; the transaction was sent, and the proposal is gone (`proposal_exists: false`). | `error.message` is a fixed, user-safe sentence for its cause, plus chain facts such as block diff --git a/docs/guides/README.md b/docs/guides/README.md index 0b966fdd..c2e1925b 100644 --- a/docs/guides/README.md +++ b/docs/guides/README.md @@ -26,6 +26,7 @@ storage, or network), not after Compose. | [Miden Dashboard UI](./miden-dashboard/README.md) | Self-hosted Compose: Postgres + Guardian server + the Miden Dashboard operator UI | | [Observability](./observability/README.md) | Local Compose: server + Prometheus + pre-provisioned Grafana dashboard | | [Horizontal scaling](./horizontal-scaling/README.md) | Local Compose: two replicas + round-robin proxy + shared Postgres (sessions, lease failover, fail-closed auth) | +| [Policy modules](./policy-modules/README.md) | From source (prototype branch): built-in `basic-policy`, a remote module over gRPC, and a custom module written with `guardian-module-sdk` | ## Adding a guide diff --git a/docs/guides/policy-modules/.env.example b/docs/guides/policy-modules/.env.example new file mode 100644 index 00000000..e33801bd --- /dev/null +++ b/docs/guides/policy-modules/.env.example @@ -0,0 +1,12 @@ +# Policy modules guide: a local server on the filesystem backend. +# Copy to .env next to this file, then load it before starting the server: +# set -a && . docs/guides/policy-modules/.env && set +a +# Paths are relative to the repository root, where you start the server. +GUARDIAN_ENV=dev +GUARDIAN_NETWORK_TYPE=MidenDevnet +GUARDIAN_STORAGE_PATH=.guardian/modules-guide/storage +GUARDIAN_METADATA_PATH=.guardian/modules-guide/metadata +GUARDIAN_KEYSTORE_PATH=.guardian/modules-guide/keystore +GUARDIAN_OPERATOR_PUBLIC_KEYS_FILE=.guardian/operators.json +# One of built-in.toml, remote.toml or custom.toml, copied into .guardian/. +GUARDIAN_MODULES_CONFIG=.guardian/built-in.toml diff --git a/docs/guides/policy-modules/README.md b/docs/guides/policy-modules/README.md new file mode 100644 index 00000000..5301cf25 --- /dev/null +++ b/docs/guides/policy-modules/README.md @@ -0,0 +1,195 @@ +# Policy modules + +Run a local Guardian with policy modules: spending caps, recipient and signer +rules, and your own checks, consulted before the Guardian signs. A module only +answers allow or deny. A deny refuses the Guardian's acknowledgement, so the +transaction cannot execute; a module can never produce a signature. + +> **Prototype.** Modules are implemented on the +> [`251-modules-prototype`](https://github.com/OpenZeppelin/guardian/tree/251-modules-prototype) +> branch and are not in a release. The design is +> [RFC 0002](../../rfcs/0002-guardian-modules.md). No published image includes +> modules yet, so this guide runs the server from source instead of Docker +> Compose. + +This guide assembles the pieces; the reference lives elsewhere: +[`CONFIGURATION.md`](../../CONFIGURATION.md#runtime-policy-modules) for the +variables and [`DASHBOARD.md`](../../DASHBOARD.md#policy-modules) for the +operator endpoints and permissions. + +## Three ways to run a module + +| Page | Module runs | Use it for | +|---|---|---| +| [Built-in](./built-in.md) | Inside the Guardian process (`basic-policy`) | Caps, asset and recipient lists, signer rules, with no extra service | +| [Remote](./remote.md) | As its own service over gRPC | A module operated, scaled or upgraded apart from the Guardian, or by another team | +| [Custom](./custom.md) | Your code, written with `guardian-module-sdk`, served over gRPC or compiled into your own server build | Rules `basic-policy` cannot express | + +## How evaluation works + +- **Catalog.** A TOML file (`GUARDIAN_MODULES_CONFIG`) declares every module + instance: its kind, the hooks it runs at, its scope, its timeout and what + happens when it fails. It is read once at startup. Instances cannot be added + or reconfigured at runtime. +- **Hooks.** `before_proposal_created` filters a proposal before it is stored; + `before_transaction_approved` runs before the Guardian signs, for a pushed + delta and for a Guardian execution alike, and is the one that enforces, + because transactions signed offline skip proposals; + `before_account_registered` runs when an account is configured. +- **Scope.** A `scope = "all"` instance applies to every account. A + `scope = "assigned"` instance applies only to accounts an operator assigns it + to. +- **Params.** The catalog's `params` seed an instance's global params on first + start. After that, operators change them through the API, and can add a + per-account layer on an `all` instance. The layer is evaluated as a second + pass and both must allow, so it can only add restrictions. +- **Failure.** If a module times out or errors, `on_error = "deny"` (the + default) refuses with `503 GUARDIAN_MODULE_UNAVAILABLE`; `"allow"` continues + and records the failure on the signed delta. +- **Refusal.** A deny returns `403 GUARDIAN_MODULE_DENIED` with `module`, + `reason_code` and `layer` (`global` or `account`) in `meta`, plus the + module's `client_message` when it sets one. The Rust and TypeScript clients + surface it as a typed refusal (`ClientError::module_refusal`, + `GuardianHttpError.moduleRefusal()`). A Guardian execution refused this way ends `failed` with + `GUARDIAN_EXECUTION_MODULE_DENIED` (same `meta`) or + `GUARDIAN_EXECUTION_MODULE_UNAVAILABLE` (`meta.module`), and its proposal is + kept. + +## What users see + +Each instance decides how much the account's cosigners learn +([RFC 0002 section 2.7](../../rfcs/0002-guardian-modules.md#27-policy-discovery-and-disclosure)): + +| Catalog field | Values | Effect | +|---|---|---| +| `client_reason` | `full` (default), `generic` | `generic` turns a denial into `meta = { reason_code: "policy_denied" }`: no module, layer or message. Use it for screening, where telling a user why could itself be prohibited. The server log still has the full decision. | +| `disclosure` | `none` (default), `summary`, `params` | What a policy summary for cosigners will show. `summary` and `params` need a `description`. | +| `description` | Text, at most 500 characters | Shown to cosigners, for example "At most 5 per transaction". | +| `dry_run` | `true` (default), `false` | Whether a dry-run check may call the instance. | + +Cosigners use two client endpoints: + +- `GET /policies?account_id=…` lists the disclosed policies (Rust + `get_policies`, TypeScript `getPolicies`). +- `POST /delta/proposal/check` runs proposal creation without storing + anything: it answers `{ "allowed": true, "complete": … }` or the error + creation would return. At most `GUARDIAN_MODULE_CHECK_RATE_PER_MIN` (30) + checks per account and signer per minute. + +The Rust multisig SDK wraps both (`get_policies`, and `check_transaction`, +which builds the transaction exactly as `propose_transaction` does). The +TypeScript multisig SDK does not yet: until the next +`@openzeppelin/guardian-client` release, TypeScript callers use +`getPolicies` and `checkDeltaProposal` on the base `GuardianHttpClient` and +pass the proposal payload themselves. + +An instance whose catalog params contain secret references cannot use +`disclosure = "params"`: the server refuses to start, since the reference +would show cosigners the secret's name. + +In +[`built-in.toml`](./built-in.toml), `caps` discloses its params and +`blocklist` denies generically. + +## Setup + +Run everything from the repository root, on the prototype branch. + +### 1. Operator key + +The module endpoints need an operator session. Generate a Falcon key with the +CLI that ships with the server: + +```sh +mkdir -p .guardian +cargo run -p guardian-server --example modules_admin -- keygen .guardian/operator.key +``` + +It prints the key's commitment and an allowlist entry. Copy +[`operators.example.json`](./operators.example.json) to +`.guardian/operators.json` and paste the printed `public_key` into it. The +example grants all four permissions the module endpoints use. `.guardian/` is +gitignored, so keys and tokens stay out of commits. + +### 2. Catalog and environment + +```sh +cp docs/guides/policy-modules/built-in.toml .guardian/ +cp docs/guides/policy-modules/.env.example docs/guides/policy-modules/.env +``` + +Edit `.guardian/built-in.toml` for your network: replace `0xREPLACE_WITH_FAUCET_ID` +with the faucet id of an asset you hold. The other pages swap in +`remote.toml` or `custom.toml` by changing `GUARDIAN_MODULES_CONFIG` in the +guide's `.env`. + +### 3. Start the server + +```sh +set -a && . docs/guides/policy-modules/.env && set +a +cargo run -p guardian-server --bin server +``` + +Exported variables take precedence over the repository's own `.env`. The +server uses the filesystem backend unless built with `--features postgres`; +module state then goes to `GUARDIAN_METADATA_PATH/modules/module_state.json`. +Look for this line in the log: + +``` +Policy modules loaded catalog_hash=0x… params_version=… builds=caps=basic-policy 0.18.1, … +``` + +The ports are fixed at 3000 (HTTP) and 50051 (gRPC); stop any other Guardian +first. + +### 4. The operator CLI + +Define a shell function for the CLI, then list the modules: + +```sh +admin() { ./target/debug/examples/modules_admin --key .guardian/operator.key "$@"; } +admin GET /modules +``` + +`admin METHOD PATH [JSON]` logs in with the key and calls `/dashboard/PATH` on +`http://localhost:3000` (`--url` changes it). Each instance in the listing +shows its `enabled` flag, current params, `build`, and whether the stored +values have drifted from the catalog. + +### 5. A client + +Send transactions with the Rust demo, which surfaces module refusals with the +module and reason code: + +```sh +cargo run -p guardian-demo +``` + +Any client works; refusals are plain Guardian errors. + +## Operator API at a glance + +| Task | Call | +|---|---| +| Change a global rule | `admin PUT /modules/{id}/params '{"params":{...},"reason":"..."}'` | +| Add a stricter rule for one account | `admin PUT /accounts/{account_id}/modules/{id}/params '{"params":{...},"reason":"..."}'` | +| Remove that account rule | `admin DELETE /accounts/{account_id}/modules/{id}/params '{"reason":"..."}'` | +| Assign opt-in modules to an account | `admin PUT /accounts/{account_id}/modules '{"modules":[{"module_id":"...","params":{...}}],"reason":"..."}'` | +| See what applies to an account | `admin GET /accounts/{account_id}/modules` | +| Switch an instance off or on | `admin POST /modules/{id}/disable '{"reason":"..."}'`, then `/enable` | +| See every change | `admin GET /modules/{id}/params/history` | +| See which configuration approved a delta | `admin GET /accounts/{account_id}/deltas/{nonce}`, field `metadata.modules` | + +Every write is validated by the module before it is stored; invalid params +return `400` and change nothing. + +## Troubleshooting + +| Symptom | Cause | +|---|---| +| `cannot read module catalog` | `GUARDIAN_MODULES_CONFIG` is relative to the directory you started the server in; start from the repository root. | +| `module caps: invalid params: …` at startup | The catalog's seed params, or the stored params on a later start, fail the module's validation. Fix the catalog; nothing is stored until every instance passes. | +| `module caps-remote: …` at startup | An enabled remote module is unreachable or rejected the token. Start the module first, or set `enabled = false` until it runs. | +| `relation "module_state_version" does not exist` | A Postgres database that ran an earlier prototype migration. Drop the `module_*` tables and the `20261015000001` row in `__diesel_schema_migrations`, then restart. | +| `login failed: no session cookie` | The server did not load the key: check `GUARDIAN_OPERATOR_PUBLIC_KEYS_FILE` and the `public_key` in it. | +| The client shows a generic error | The server log names the module, reason code and layer for every refusal. | diff --git a/docs/guides/policy-modules/built-in.md b/docs/guides/policy-modules/built-in.md new file mode 100644 index 00000000..0a59213c --- /dev/null +++ b/docs/guides/policy-modules/built-in.md @@ -0,0 +1,102 @@ +# Built-in modules + +`basic-policy` runs inside the Guardian process: no extra service, no network +hop. One kind backs any number of instances, each with its own params, hooks +and scope. Do the [setup](./README.md#setup) first; the catalog is +[`built-in.toml`](./built-in.toml). + +## `basic-policy` params + +All params are optional; an instance with none allows everything. + +| Param | Value | Refuses with | Notes | +|---|---|---|---| +| `max_amount_per_tx` | `{ "": "" }` | `amount_cap_exceeded` | Gross amount per asset across the transaction's payment notes, in base units. The fee note is not a payment. | +| `asset_allowlist` | `["", ...]` | `asset_not_allowed` | Assets sent in payment notes and received in input notes. | +| `recipient_allowlist` | `["", ...]` | `recipient_not_allowed` | P2ID and P2IDE targets. | +| `recipient_denylist` | `["", ...]` | `recipient_blocked` | | +| `deny_unknown_recipients` | `true` / `false` | `recipient_not_allowed` | Refuses payment notes whose recipient the Guardian cannot identify (not P2ID or P2IDE). | +| `signer_allowlist` or `signer_denylist` | `["", ...]` | `signer_not_allowed` | Mutually exclusive. | +| `signer_check` | `"added"` (default) or `"all"` | | `added` checks only signers a transaction adds; `all` checks every signer after it. | + +Signer rules apply at all three hooks, including registration. Transaction +rules (caps, assets, recipients) apply to proposals and approvals. + +## The example catalog + +| Instance | Scope | Rule | +|---|---|---| +| `caps` | all | At most 5 of one asset per transaction; can be switched off; discloses its params to cosigners | +| `blocklist` | all | Recipient denylist, empty until you fill it; denies generically | +| `signers` | all | One signer may never be added; the catalog protects it from being switched off | +| `treasury-allowlist` | assigned | Opt-in: applies only to accounts you assign it to | + +## Try it + +Use your account id from the demo's "Show account" as `ACCOUNT`, and a second +account as `RECIPIENT`. + +**Cap.** Propose a payment of 10 of the capped asset. It is refused when the +proposal is created: `GUARDIAN_MODULE_DENIED`, module `caps`, reason +`amount_cap_exceeded`, layer `global`. A payment of 3 goes through. + +**Global blocklist.** Block the recipient for every account: + +```sh +admin PUT /modules/blocklist/params '{"params":{"recipient_denylist":["RECIPIENT"]},"reason":"test"}' +``` + +A payment to it is refused, but the client only sees +`reason_code: "policy_denied"`: `blocklist` sets `client_reason = "generic"`, +so neither the module nor `recipient_blocked` reaches the user. The server log +has both. + +**A stricter rule for one account.** Add a lower cap for one account only: + +```sh +admin PUT /accounts/ACCOUNT/modules/caps/params \ + '{"params":{"max_amount_per_tx":{"0xFAUCET":"2"}},"reason":"test"}' +admin GET /accounts/ACCOUNT/modules +``` + +The second call shows the global params and the account's layer side by side. +From this account a payment of 3 is now refused with layer `account`; other +accounts still have the cap of 5. Set the account's cap to 100 and a payment of +10 is still refused, by the global layer: an account layer only adds +restrictions. Remove it with: + +```sh +admin DELETE /accounts/ACCOUNT/modules/caps/params '{"reason":"done"}' +``` + +**Opt-in module.** Give one account an allowlist of recipients: + +```sh +admin PUT /accounts/ACCOUNT/modules \ + '{"modules":[{"module_id":"treasury-allowlist","params":{"recipient_allowlist":["RECIPIENT"]}}],"reason":"test"}' +``` + +A payment from that account to any other recipient is refused with +`recipient_not_allowed`. The call replaces the account's whole assignment +list; send `"modules":[]` to clear it. + +**Signer rule.** Propose adding the cosigner +`0xdededededededededededededededededededededededededededededededede`. It is +refused with `signer_not_allowed`, at proposal creation and again at approval +if the transaction was signed offline. + +**Switch.** `admin POST /modules/caps/disable '{"reason":"test"}'` stops the +cap for every account until `/enable`. `signers` returns `409 +GUARDIAN_MODULE_NOT_DISABLEABLE`: its catalog entry does not set +`operator_can_disable`. + +**History.** `admin GET /modules/caps/params/history` lists every change with +its version, operator and reason, including the seed and each enable or +disable. + +## What persists + +The catalog's `params` are only a seed. After the first start the stored +params apply, and editing the catalog shows up as drift (`params_drift: true` +in `GET /modules`) without changing behaviour. Params that hold secret +references stay managed in the file and cannot be changed through the API. diff --git a/docs/guides/policy-modules/custom.md b/docs/guides/policy-modules/custom.md new file mode 100644 index 00000000..49a02aa7 --- /dev/null +++ b/docs/guides/policy-modules/custom.md @@ -0,0 +1,149 @@ +# Custom modules + +Write your own module against `guardian-module-sdk`, then either serve it over +gRPC or compile it into your own server build. The worked example, +[`note_policy/mod.rs`](../../../crates/guardian-module-sdk/examples/note_policy/mod.rs), +is a module `basic-policy` cannot express: it limits how many payment notes a +transaction creates and can refuse private notes, whose recipients the +Guardian cannot see. The same code runs both ways. Do the +[setup](./README.md#setup) first. + +| | Over gRPC | In process | +|---|---|---| +| Runs | As its own service ([`note-policy-serve.rs`](../../../crates/guardian-module-sdk/examples/note-policy-serve.rs)) | Inside your server build ([`custom_module_server.rs`](../../../crates/server/examples/custom_module_server.rs)) | +| Catalog | [`custom.toml`](./custom.toml): `kind = "grpc"` and an `endpoint` | [`custom-in-process.toml`](./custom-in-process.toml): `kind = "note-policy"` | +| Cost per call | A network round trip | A function call on its own task | +| Isolation | Separate process; can only refuse | Shares the process that holds the signing keys | +| Upgrades | Deploy the module alone | Rebuild the server for every Guardian release | +| Use it for | Third-party code, modules other teams run | Code you review and ship as part of your Guardian build | + +## The `Module` trait + +A stateless module implements three methods: + +| Method | Returns | Notes | +|---|---|---| +| `describe(guardian)` | `ModuleInfo`: name, version, `PROTOCOL_VERSION`, supported hooks, required capabilities | `guardian` carries the Guardian's protocol range and capabilities. The Guardian refuses an instance subscribed to a hook the module does not list, a protocol version outside its range, or a capability it lacks. | +| `validate_params` | `ParamsVerdict::ok()`, `ParamsVerdict::invalid(message)` or `ParamsVerdict::normalized(params)` | Called at startup and on every params write. Reject unknown fields (`#[serde(deny_unknown_fields)]`) so a typo fails here, not silently at evaluation. Return `normalized` to have the Guardian store the params in your current shape. | +| `evaluate` | `Decision::allow()` or `Decision::deny(reason_code, message)` | Must be free of side effects: the same transaction is evaluated at proposal creation and again at approval, and clients retry. | + +A reason code is lowercase `snake_case`; anything else counts as a module +failure. Return `ModuleError` for a request you cannot judge; the instance's +`on_error` then decides. `Decision::allow` and `Decision::deny` set the +decision's `effect`; a Guardian treats an effect it does not know as a +failure, never as an allow. + +## Changing your module across releases + +- **Params.** When you rename or restructure a param, keep accepting the + previous shape for at least one release (serde aliases and defaults) and + return `ParamsVerdict::normalized` with the new shape. At startup the + Guardian stores the migrated global params, with a history entry by + `module: `; account layers move to the new shape when they + are next written. Never reuse a param name with a different meaning. +- **Protocol.** Within a protocol version the Guardian only adds fields, + hooks and capabilities, so a module keeps working across Guardian releases. + When a new protocol version ships, the Guardian keeps accepting the previous + one for one release. +- **Rust API.** Build protocol types with `..Default::default()` or the SDK + helpers, and SDK-owned types with their constructors + (`ModuleInstanceConfig::new(..)`), so new fields do not break your build. + +The rules are in [RFC 0002 section 3.5](../../rfcs/0002-guardian-modules.md#35-protocol-evolution-and-compatibility). + +## What a request carries + +| Field | Use it for | +|---|---| +| `params` | The params to apply, as JSON bytes: the global ones, or an account's layer on its second pass | +| `subject.miden()` (the Miden variant of `subject.transaction.projection`) | The decoded transaction: vault changes, output notes (amount, faucet, `note_type`, `p2id_target`, `tx_fee`), input notes, storage changes | +| `before`, `after` | Account views: signer commitments, `default_threshold` (absent for single-key accounts), procedure thresholds, auth scheme | +| `submitter`, `subject.transaction.proposer` | Verified signer commitments | +| `subject.transaction.unverified_metadata` | What the proposer claimed; never base a decision on it alone | +| `subject.transaction.raw` | The transaction in its network's own encoding (`encoding = "miden.transaction_summary"`), for modules that decode it themselves; tied to the Guardian's Miden version | + +Skip the fee note (`tx_fee = true`) when counting payments: every transaction +pays its fee through an output note. + +Projections are tagged by network (`TransactionProjection`, `oneof network`). +Miden is the only network today; read it with `subject.miden()` and return a +`ModuleError` when it is absent, so a module never judges a transaction it +does not understand. + +## Run it over gRPC + +The [remote](./remote.md) page explains the transport. + +```sh +openssl rand -hex 32 > .guardian/note-policy.token +cargo run -p guardian-module-sdk --example note-policy-serve -- \ + --listen 127.0.0.1:7444 --instance note-policy .guardian/note-policy.token +cp docs/guides/policy-modules/custom.toml .guardian/ +``` + +Set `GUARDIAN_MODULES_CONFIG=.guardian/custom.toml` in the guide's `.env` and +start the server as in the setup. The log line lists +`note-policy=note-policy `. + +## Run it in process + +Register the kind on the server builder; that is the only difference from the +stock `server` binary: + +```rust +ServerBuilder::new() + // ...the same configuration as crates/server/src/main.rs... + .with_module_kind("note-policy", Arc::new(NotePolicyFactory)) +``` + +The factory gets each catalog instance's configuration and returns the module. +`build` fails if the kind name is already taken, including by `basic-policy` +or `grpc`. Run the example build: + +```sh +cp docs/guides/policy-modules/custom-in-process.toml .guardian/ +# set GUARDIAN_MODULES_CONFIG=.guardian/custom-in-process.toml in the guide's .env +set -a && . docs/guides/policy-modules/.env && set +a +cargo run -p guardian-server --example custom_module_server +``` + +No module process, token or endpoint is involved. To run it next to another +Guardian, set `GUARDIAN_EXAMPLE_HTTP_PORT` and `GUARDIAN_EXAMPLE_GRPC_PORT` +(default 3000 and 50051). The stock binary refuses +this catalog at startup, since it does not know the `note-policy` kind. + +Each call still runs on its own task with the instance's `timeout_ms`, so a +panic in the module, or a timeout, is a module failure and `on_error` applies, +as for a remote module. Keep `evaluate` async and non-blocking all the same: a +module that blocks holds a runtime worker thread until it returns, even after +the Guardian has answered the request. The example server copies the setup +from `main.rs`, so keep it in step with it when you upgrade. + +## Try it + +| Test | Expected | +|---|---| +| A transaction with one payment note | Allowed | +| A transaction with two payment notes, if your client can build one | Refused with `too_many_payment_notes` | +| A payment sent as a private note, if your client supports it | Refused with `private_note_not_allowed` | +| `admin PUT /modules/note-policy/params '{"params":{"max_payment_notes":3},"reason":"test"}'` | Two notes allowed; private notes allowed too, since `deny_private_notes` now defaults to `false` | +| `admin PUT /modules/note-policy/params '{"params":{"max_notes":3},"reason":"typo"}'` | `400`, nothing stored: `validate_params` rejected the unknown field | + +The tests work the same in either mode. The module's own tests run with +`cargo test -p guardian-module-sdk --example note-policy-serve`. + +## Shipping your module + +- Use `serve(YourModule).instance(id, token)` from the SDK, or implement the + `GuardianModule` service from the proto in any language with gRPC support. +- Keep the module stateless for now. Limits that count across transactions + (daily caps) need the commit notifications of the RFC's M2b slice. +- The SDK's conformance tests + ([`tests/conformance.rs`](../../../crates/guardian-module-sdk/tests/conformance.rs)) + check that `basic-policy` decides the same in process and over gRPC; copy the + pattern to test your module over the real transport. +- Prefer the remote path for code you do not own. In process, the rule that a + module can only refuse, never sign, holds by code review rather than by + isolation. +- A custom server build leaves the published image, so your release process has + to rebuild it for every Guardian release. diff --git a/docs/guides/policy-modules/operators.example.json b/docs/guides/policy-modules/operators.example.json new file mode 100644 index 00000000..abcce54b --- /dev/null +++ b/docs/guides/policy-modules/operators.example.json @@ -0,0 +1,6 @@ +[ + { + "public_key": "0xPASTE_THE_PUBLIC_KEY_FROM_modules_admin_keygen", + "permissions": ["dashboard:read", "policies:write", "policies:write_global", "modules:disable"] + } +] diff --git a/docs/guides/policy-modules/remote.md b/docs/guides/policy-modules/remote.md new file mode 100644 index 00000000..ebc53b75 --- /dev/null +++ b/docs/guides/policy-modules/remote.md @@ -0,0 +1,88 @@ +# Remote modules + +A remote module is its own service that implements the `GuardianModule` gRPC +API from +[`guardian_module_v1.proto`](../../../crates/guardian-module-sdk/proto/guardian_module_v1.proto). +The Guardian finds it through the catalog's `endpoint`, and the module +describes itself when the Guardian asks. This page runs `basic-policy` as a +remote service, so the only difference from the [built-in](./built-in.md) page +is the transport. Do the [setup](./README.md#setup) first; the catalog is +[`remote.toml`](./remote.toml). + +## How the Guardian talks to it + +| Call | When | Purpose | +|---|---|---| +| `Describe` | Startup, and before enabling | Name, version, protocol version and supported hooks. A mismatch with the catalog stops startup. | +| `ValidateParams` | Startup, and on every params write | The module rejects params it cannot use; nothing is stored. | +| `Evaluate` | Every gated request | One request in, one decision out, within `timeout_ms`. | + +Each request carries the instance id, the params to apply (global or the +account's layer), the before and after account views, the decoded transaction +projection, the raw transaction summary, the verified submitter and proposer, +and the proposal's unverified metadata. The module keeps no params of its own, +so params changed through the API apply on the next request without +restarting it. + +## 1. Token and module + +Each instance authenticates the Guardian with a bearer token, sent on every +call: + +```sh +openssl rand -hex 32 > .guardian/caps.token +cargo run -p guardian-module-sdk --example basic-policy-serve -- \ + --listen 127.0.0.1:7443 --instance caps-remote .guardian/caps.token +``` + +The serve harness accepts a call only for an instance id it knows, with that +instance's token. One process can host several instances, each with its own +token: repeat `--instance`. + +## 2. Catalog and server + +```sh +cp docs/guides/policy-modules/remote.toml .guardian/ +``` + +Replace the faucet placeholder, set `GUARDIAN_MODULES_CONFIG=.guardian/remote.toml` +in the guide's `.env`, and start the server as in the setup. The module must +already be running: an enabled instance that cannot be reached stops startup. +The log line lists `caps-remote=basic-policy 0.18.1`. The token path resolves +against the catalog's directory. + +## 3. Try it + +| Test | How | Expected | +|---|---|---| +| Remote refusal | Pay 4 | Refused by `caps-remote` (cap 3); the in-process `caps` (cap 5) allows it | +| Remote params | `admin PUT /modules/caps-remote/params '{"params":{"max_amount_per_tx":{"0xFAUCET":"1"}},"reason":"test"}'`, then pay 2 | Refused; the module was not restarted | +| Module down, fail closed | Stop the module, pay 1 | `503 GUARDIAN_MODULE_UNAVAILABLE`, module `caps-remote` | +| Switch it off while down | `admin POST /modules/caps-remote/disable '{"reason":"module down"}'`, pay 1 | Allowed; start the module again and `/enable` (which re-runs `Describe` and `ValidateParams`) | +| Fail open | Set `on_error = "allow"`, restart the Guardian, stop the module, pay 1 | Allowed; the delta's `metadata.modules.failed_open` names `caps-remote` | +| Wrong token | Start the module with a different token file, restart the Guardian | Startup fails: the module rejects `Describe` | + +## Transport security + +- `grpc://host:port` is always TLS, verified against the system roots or a + private CA. Mutual TLS is optional: + + ```toml + endpoint = "grpc://risk.internal:7443" + tls = { ca_file = "risk-ca.pem", client_cert_file = "guardian.pem", client_key_file = "guardian.key" } + ``` + +- Plain text needs the explicit `grpc+insecure://` scheme and a loopback host + (`127.0.0.1`, `localhost`, `::1`), so a missing letter cannot turn TLS off. +- In the prod stage (`GUARDIAN_ENV=prod`) plain text is refused and `auth` is + mandatory for every remote instance. +- The SDK's serve harness speaks plain text only, so for TLS put it behind a + TLS-terminating proxy on the module's host, or serve the module with your own + tonic server configured for TLS. + +## What a remote module cannot do + +It cannot sign, change its own params or hooks, or see secrets: catalog params +with secret references are refused for remote kinds. The worst a compromised +or failing remote module can do is refuse (or, with `on_error = "allow"`, be +skipped), and the operator can switch it off if the catalog allows it. diff --git a/docs/rfcs/0002-guardian-modules.md b/docs/rfcs/0002-guardian-modules.md index 0984a955..a91f8784 100644 --- a/docs/rfcs/0002-guardian-modules.md +++ b/docs/rfcs/0002-guardian-modules.md @@ -7,7 +7,7 @@ | **Feature** | [#251](https://github.com/OpenZeppelin/guardian/issues/251) ("Modularization: middleware architecture and pluggable modules"); first consumer [#182](https://github.com/OpenZeppelin/guardian/issues/182) (policy evaluation). [#252](https://github.com/OpenZeppelin/guardian/issues/252) (x402 facilitator) is a later consumer: its payment-policy half (caps, allowlists, replay) fits `before_transaction_approved` and `after_transaction_committed`, its facilitator half (`/verify`, `/settle`, a flow that starts and waits) does not fit allow/deny and is future work (section 7) | | **Audience** | Operators, module authors, integrators, and anyone reviewing the Guardian trust model | | **Working artifacts** | [`speckit/features/251-guardian-modules/`](../../speckit/features/251-guardian-modules/spec.md): the specification, written alongside this RFC; plan and tasks follow the prototype | -| **Revision** | 25 (2026-11-03): accepted for implementation on merge of PR #544; changes in Appendix C | +| **Revision** | 26 (2026-11-09): per-signer schemes in `AccountView` for mixed-scheme accounts, and the execution path's module failure codes; changes in Appendix C | | **Review sought** | Comments on the design and the M2a scope remain open until M2a ships, when `guardian.module.v1` freezes (section 7) | | **Code baseline** | `main` at `ca503704`; execution-path citations read on `254-execution-impl` at `29c722b4` (PR #510, since merged to `main` as `1100f3a4`) and kept as dated evidence. Miden pins: protocol and standards 0.17.1. Appendices B and C cite the baselines of their revisions. Prototype findings (2026-10-13 to 2026-10-15) in `speckit/features/251-guardian-modules/research.md` | @@ -617,12 +617,13 @@ message HookRequest { message AccountView { string commitment = 1; - string auth_scheme = 2; // "falcon" or "ecdsa", from the registered auth configuration (section 3.2) + string auth_scheme = 2; // the scheme every signer shares, "falcon" or "ecdsa", or "mixed" (section 3.2) repeated string signer_commitments = 3; optional uint32 default_threshold = 4; // absent for single-key accounts map procedure_thresholds = 5; // procedure root -> threshold; only overrides the account's code can apply (section 3.2) string code_commitment = 6; // commitment of the account's code repeated string procedure_roots = 7; // roots of the procedures the account's code exports + map signer_schemes = 8; // signer commitment -> "falcon" or "ecdsa"; one entry per signer (section 3.2) } message TransactionSubject { @@ -818,7 +819,7 @@ The fee note (`tx_fee`) is excluded from every recipient, asset and amount rule. ### 3.2 Account views and proposal context -**One view of the account at every gate hook.** Rules about who controls an account (signer allowlists, a minimum signer count, a threshold floor) apply at registration and at every signer change, and a module should not need a code path per hook to evaluate them. `HookRequest` therefore carries, for every gate hook, the account before and after the request, in an `AccountView`: commitment, signer commitments, default threshold and per-procedure thresholds decoded from account state, and the auth scheme taken from the account's registered auth configuration (`Auth::scheme()`). The scheme is not decoded: schemes are stored per approver (`approver_schemes`), so storage could mix them, while the Guardian registers one scheme per account, which is what `auth_scheme` reports. The default threshold alone does not bound how many approvals a transaction needs: a procedure threshold overrides it for that procedure, so a threshold floor checks both. +**One view of the account at every gate hook.** Rules about who controls an account (signer allowlists, a minimum signer count, a threshold floor) apply at registration and at every signer change, and a module should not need a code path per hook to evaluate them. `HookRequest` therefore carries, for every gate hook, the account before and after the request, in an `AccountView`: commitment, signer commitments, default threshold and per-procedure thresholds decoded from account state, and each signer's scheme in `signer_schemes`. Schemes are per signer: since #565 an account's approvers can mix Falcon and ECDSA, so a multisig view decodes each approver's scheme from its state (`approver_schemes`), which also covers a signer an `after` view adds before the Guardian has registered it. A missing or unsupported scheme entry fails extraction rather than producing a signer without a scheme. `auth_scheme` summarizes `signer_schemes`: the scheme every signer shares, or `mixed`. The default threshold alone does not bound how many approvals a transaction needs: a procedure threshold overrides it for that procedure, so a threshold floor checks both. **Procedure thresholds and code.** On chain, an override applies only to a procedure the account's code exports and the transaction calls, never to the auth procedure itself, and a zero override means the default applies (`compute_transaction_threshold` in `multisig.masm`, `miden-standards-0.17.1`) **[READ]**. The storage map can still hold entries that change nothing, so `procedure_thresholds` carries only effective overrides: non-zero, on a procedure in `procedure_roots`, not on the auth procedure. A module that sets a floor therefore never denies on an inert entry. `code_commitment` and `procedure_roots` describe the code the account runs. The Guardian checks storage slots (the Guardian commitment, the signer set) but never the code (`validate_guardian_commitment`, `crates/server/src/network/miden/mod.rs:649-669`; `has_multisig_auth`, `network/miden/account_inspector.rs:98-101`) **[READ]**, so a module that must know the account enforces its approvals, for example by requiring the standard guarded multisig component, pins `code_commitment` at `before_account_registered` and denies a `MidenTransaction.new_code_commitment` it does not accept. @@ -828,7 +829,7 @@ The fee note (`tx_fee`) is excluded from every recipient, asset and amount rule. | `before_transaction_approved` | The base of the delta being acked (tail or canonical state) | The base with the delta applied | | `before_account_registered` | Absent for a first configuration, an unfinished claim included (section 2.3, "Registration"); for an existing account, the stored state, read for this purpose | The submitted `initial_state` | -**Single-key accounts** carry no multisig component, so nothing in their storage holds a signer set or thresholds. Their view is built from the registered signer instead: `signer_commitments` holds that one commitment, `default_threshold` is absent and `procedure_thresholds` is empty; `code_commitment` and `procedure_roots` are read from the account as for any other. Signer rules therefore apply to them, and threshold rules have nothing to check. Without this, every gate request for a single-key account would fail extraction and fall to `on_error`, so a fail-closed signer module would block every single-key account. +**Single-key accounts** carry no multisig component, so nothing in their storage holds a signer set or thresholds. Their view is built from the registered signer instead: `signer_commitments` holds that one commitment, `signer_schemes` its registered scheme, `default_threshold` is absent and `procedure_thresholds` is empty; `code_commitment` and `procedure_roots` are read from the account as for any other. Signer rules therefore apply to them, and threshold rules have nothing to check. Without this, every gate request for a single-key account would fail extraction and fall to `on_error`, so a fail-closed signer module would block every single-key account. **Building the views is new work.** The Guardian decodes signer sets today, but not the whole view. `account_auth_binding` (`crates/server/src/services/candidate_chain.rs:316`) returns `AuthBinding { signers, guardian }`, with no threshold and no scheme (`crates/server/src/network/mod.rs:266-269`); its Miden implementation returns the signers it extracts even when the list is empty (`crates/server/src/network/miden/mod.rs:826-829`), and `should_update_auth` maps an empty list to "nothing to update" (`:844-845`) **[READ]**. An empty signer set read as a successful view would make every signer rule pass: nothing is added, nothing is checked. The implementation therefore adds one extraction that reads the signer, threshold and procedure-threshold slots and the scheme, and that returns an error for auth state it does not support or cannot decode, never an empty view. A failed extraction is treated as an error for every module called at that hook, so each module's `on_error` applies (section 4.2). At the transaction hooks both states are in hand: the base the delta is checked against and the result of applying it. At re-onboarding they are not: `configure_account` reads only the account metadata (`configure_account.rs:64`) **[READ]**, so building `before` adds a read of the stored state, made only when a module subscribed to `before_account_registered` will be called. The prototype confirmed the extraction: `threshold_config` holds `[threshold, num_approvers, 0, 0]`, approvers are read at indices `0..num_approvers` with a missing key treated as an error, and `procedure_thresholds` is read in full and then filtered to effective overrides (above). Decoding the account dominates the cost, about 1.1 ms per view in a release build and so about 2 ms per gate request; the projection takes microseconds. Since #523 the push path decodes the base account once and applies the summary to it (`verify_and_apply_delta`, `crates/server/src/network/mod.rs:313-318`, called at `push_delta.rs:143`) **[READ]**, so both views can be read from that one decode, `before` before the summary is applied and `after` from the result, by adding the view fields to `AppliedState`; proposal creation still calls `verify_delta` alone (`push_delta_proposal.rs:210`) **[READ]** and moves to `verify_and_apply_delta` when a module will be called. Building the views and the projection runs inside the bounded reconstruction task the push path already uses for `apply_delta` (`network::reconstructor()`), not on the request task, so request assembly is held to the same CPU bound and a malformed summary (for example an expiration height that overflows) is an error under `on_error`, never a panic. Modules that need the raw layout still have `MidenTransaction.storage_changes`, and vault effects stay in `TransactionSubject`: amount and recipient rules apply only to transactions, and a full vault view on every request would be large. @@ -838,7 +839,7 @@ The fee note (`tx_fee`) is excluded from every recipient, asset and amount rule. **Verified identities.** Both are signer commitments taken from request authentication (`ResolvedAccount.signer_commitment`, `crates/server/src/services/mod.rs:120`) **[READ]**, never from the payload. A proposal can also be created under a delegated session key (#537): `push_delta_proposal` accepts sessions (`resolve_account_allowing_session`, `push_delta_proposal.rs:75`), and for a session credential the resolved commitment is the cosigner that granted the session, not the session key (`services/mod.rs:193-199`) **[READ]**. `submitter` and `proposer` are therefore always cosigner commitments; `push_delta` and `/configure` do not accept sessions. Two flags keep delegation visible. `HookRequest.submitter_session` marks a request authenticated through a session; since only proposal creation accepts sessions, it is always false at the ack. `TransactionSubject.proposer_session` marks a proposal created through one: it is stored with the proposal, returned by the `ProposalContext` lookup together with the proposer, and repeated in `pending` and `CommitEvent` like `proposer`. A rule such as "delegated sessions may not propose signer changes" therefore holds at the ack, where it must be enforced (section 2.3, "Not a security boundary"), and not only at creation, where it is a filter. A transaction pushed without a stored proposal has an empty `proposer` and `proposer_session = false`; a rule that must hold treats it as an unknown proposer (below). -- `submitter` is the cosigner whose request is being evaluated: the proposer at `before_proposal_created`, the cosigner calling `push_delta` at `before_transaction_approved`. On the execution path it is the cosigner whose authenticated request created the execution attempt (RFC 0001). At the cited execution baseline that identity is not kept: the service authenticates the requester (`execute_proposal/service.rs:131` at `29c722b4`) but `ExecutionJob` holds no requester (`worker.rs:27-40`) **[READ]**. The implementation records the authenticated requester when it creates an attempt, stores it on the durable reservation so a worker resumed after a restart still has it, and carries it through the ack and into the stored delta. A repeated request for an attempt already active keeps the original requester. +- `submitter` is the cosigner whose request is being evaluated: the proposer at `before_proposal_created`, the cosigner calling `push_delta` at `before_transaction_approved`. On the execution path it is the cosigner whose authenticated request created the execution attempt (RFC 0001). At the cited execution baseline that identity is not kept: the service authenticates the requester (`execute_proposal/service.rs:131` at `29c722b4`) but `ExecutionJob` holds no requester (`worker.rs:27-40`) **[READ]**. The implementation records the authenticated requester when it creates an attempt and carries it to the ack. It is not stored on the reservation: the ack runs before the no-retry boundary, and an attempt interrupted before that boundary is never resumed (the first reconciliation pass after a restart fails it as `GUARDIAN_EXECUTION_ABANDONED`), so no worker acks without the request that started it. A repeated request for an attempt already active joins it and keeps the original requester. - `proposer` is the cosigner that created the proposal for this exact transaction. At `before_proposal_created` it equals `submitter`. At the ack it comes from the matching proposal, found by the proposal id derived from the transaction (`lookup_matching_proposal_payload`, `push_delta.rs:164,229`) **[READ]**, and is empty when there is none: a single-key account, a transaction signed offline and pushed without a stored proposal, or a proposal already deleted. That helper returns only the payload, and returns nothing on a storage error as well as on absence (`push_delta.rs:229-270`) **[READ]**, which is acceptable for dashboard metadata but not for policy: a storage fault would read as "no proposer". The pipeline instead uses a lookup returning `Result>`, where `ProposalContext` holds the proposer, its session flag and the metadata together. `Ok(None)` is absence and yields an empty `proposer`; an error is treated as an error for every module called, so `on_error` applies. - **The first creator stays the proposer.** The proposal id is derived from the transaction, so two cosigners can create the same proposal. Postgres keeps the first (`on_conflict(..).do_nothing()`, `storage/postgres.rs:1400-1404`), while the filesystem backend overwrites the stored file (`storage/filesystem.rs:704-718`) **[READ]**, which would hand attribution to the last creator. Both backends keep the first proposal and its proposer; a later create of the same id does not replace them. The filesystem backend changes to create-if-absent so modules developed against it see the same attribution as in production. Creation and signature updates become separate operations on both backends: today the filesystem backend implements `update_delta_proposal` as a re-submit (`storage/filesystem.rs:767-768`) **[READ]**, which create-if-absent would turn into a silent no-op for every cosigner signature. Create-if-absent applies only to creation; an update replaces the stored proposal and fails if it does not exist. @@ -990,7 +991,7 @@ Both use the `{ code, message, meta }` envelope. | `GUARDIAN_MODULE_DENIED` | 403 | `PERMISSION_DENIED` | no | `{ module, reason_code, layer }` | | `GUARDIAN_MODULE_UNAVAILABLE` | 503 | `UNAVAILABLE` | yes | `{ module }` | -On a deny, `reason_code` must match `[a-z0-9_]{1,64}`; a deny without a conforming code is a protocol error and follows `on_error`. On an allow, `reason_code` is ignored and may be empty, so an allow is never turned into an error by a missing code. The module's free-text `message` is logged but not forwarded to clients: a module may be a third party and should not place arbitrary text in front of end users. `meta.module` is the instance `id` from the catalog, which the operator chooses: an operator who does not want to reveal which vendor screens its traffic names the instance neutrally (for example `compliance-1`), and the vendor's kind name never reaches clients. The Rust and TypeScript SDKs expose both as typed errors with the same retry classification. A denial at `before_proposal_created` uses the same codes on the proposal creation call, and the proposal is not stored; both SDKs surface it from proposal creation with the same typed error, so a proposer sees the refusal before any cosigner signs. On the execution path (PR #510) a denial ends the execution with a typed abort reason `module_denied` carrying the same `{ module, reason_code, layer }`, and module unavailability with `module_unavailable`; both multisig SDKs read these from the execution status. +On a deny, `reason_code` must match `[a-z0-9_]{1,64}`; a deny without a conforming code is a protocol error and follows `on_error`. On an allow, `reason_code` is ignored and may be empty, so an allow is never turned into an error by a missing code. The module's free-text `message` is logged but not forwarded to clients: a module may be a third party and should not place arbitrary text in front of end users. `meta.module` is the instance `id` from the catalog, which the operator chooses: an operator who does not want to reveal which vendor screens its traffic names the instance neutrally (for example `compliance-1`), and the vendor's kind name never reaches clients. The Rust and TypeScript SDKs expose both as typed errors with the same retry classification. A denial at `before_proposal_created` uses the same codes on the proposal creation call, and the proposal is not stored; both SDKs surface it from proposal creation with the same typed error, so a proposer sees the refusal before any cosigner signs. On the execution path (PR #510) a denial ends the execution as `failed` with `GUARDIAN_EXECUTION_MODULE_DENIED`, whose `meta` carries the same `{ module, reason_code, layer }` and `client_message` (a generic denial carries only `reason_code: policy_denied`), and module unavailability with `GUARDIAN_EXECUTION_MODULE_UNAVAILABLE` (`meta.module`). Neither deletes the proposal, and nothing is proved or sent. Both multisig SDKs read them as typed failure codes from the execution status. **Generic denials.** For an instance with `client_reason = "generic"` (section 2.7), a denial reaches the client as `GUARDIAN_MODULE_DENIED` with `meta = { reason_code: "policy_denied" }`: no module, no module reason code, no layer, and no `client_message`. The full decision is logged and recorded as for any other denial, so operators still see which module refused and why. A client cannot tell a generic denial from one module from a generic denial from another. @@ -1089,7 +1090,7 @@ The first enclave step allows in-process kinds only; the attested tier follows o **First implementation (milestone M2), in three steps.** Each step ships and can be operated on its own. M2a covers stateless gates (sanctions, allowlists, per-transaction caps), which most deployments need first; M2b adds the machinery that makes stateful limits exact; M2c opens the server to operator-built kinds. -**Dependency on PR #510.** PR #510 has merged (`1100f3a4`), so M2a can start: the pipeline is placed once, in the shared `acknowledge_delta`, rather than in `push_delta` and moved later. Recording the requester on execution reservations (section 3.2) is M2a work on top of #510, not a change requested of it. +**Dependency on PR #510.** PR #510 has merged (`1100f3a4`), so M2a can start: the pipeline is placed once, in the shared `acknowledge_delta`, rather than in `push_delta` and moved later. Carrying the authenticated requester to the ack (section 3.2) is M2a work on top of #510, not a change requested of it. **Protocol version 1 is fixed at M2a.** The full `guardian.module.v1` proto above, including `Notify`, `NotifyGap`, `pending`, `accounting_time` and the watermark fields, is published with M2a, so modules written against M2a need no change when M2b ships. In M2a the Guardian sends an empty `pending`, never calls `Notify` or `NotifyGap`, does not offer the `notify` capability, and refuses at startup a catalog that subscribes an instance to `after_transaction_committed`, so a stateful module cannot start on it (section 3.5). @@ -1107,7 +1108,7 @@ The first enclave step allows in-process kinds only; the attested tier follows o - `GUARDIAN_MODULE_DENIED` and `GUARDIAN_MODULE_UNAVAILABLE` in the server and both SDKs, on proposal creation as well as on the ack. - Policy discovery (section 2.7): the `disclosure`, `description`, `client_reason` and `dry_run` catalog fields, generic denials, `Decision.client_message`, the policy summary and dry-run check on the client API with their rate limit, and the SDK methods named in section 2.7 in both base clients and both multisig SDKs. The error contract and the protocol field must land before version 1 freezes; the two endpoints may follow in an M2a point release. - Reference module `basic-policy` (recipient allowlist and denylist, asset allowlist, per-transaction amount cap, signer allowlist or denylist with `signer_check`, account code allowlist), shipped as a first-party in-process kind and, through the `serve` harness, as a standalone gRPC service in `examples/policy-module/`. -- Account view extraction with explicit errors for unsupported auth state, effective procedure overrides, code commitment and procedure roots; `network_id`, `reference_block` and `new_code_commitment` in the projection (section 3.1); `submitter_session`, and `proposer_session` stored with the proposal (section 3.2); the params size cap (section 2.2); the `ProposalContext` lookup, first-creator-wins proposal storage on both backends, and the requester recorded on execution reservations (section 3.2). +- Account view extraction with explicit errors for unsupported auth state, effective procedure overrides, code commitment and procedure roots; `network_id`, `reference_block` and `new_code_commitment` in the projection (section 3.1); `submitter_session`, and `proposer_session` stored with the proposal (section 3.2); the params size cap (section 2.2); the `ProposalContext` lookup, first-creator-wins proposal storage on both backends (on `main`, `admit_delta_proposal` refuses an existing commitment on both), and the requester carried from the execution request to the ack (section 3.2). - Acceptance cases: a denial at proposal creation stores nothing and takes no slot; a proposal that passes creation and is denied at the ack; a transaction signed offline and pushed without a stored proposal is enforced at the ack; forged `unverified_metadata` does not change a decision; a failed account view extraction applies `on_error`. Creation denials are exercised through `guardian-client` (Rust and TypeScript) and both multisig SDKs. - Docs: configuration, trust boundary in concepts, troubleshooting codes (including the denial log fields, section 2.2), the break-glass runbook (section 4.2), data-protection guidance for operators and vendors (invariant 5), and a module author guide for remote modules. @@ -1206,6 +1207,7 @@ None. Questions resolved in earlier revisions are kept below with their answers. | Revision | Date | Changes | |---|---|---| +| 26 | 2026-11-09 | `main` (mixed-scheme accounts, #565) merged into the prototype. `AccountView.signer_schemes` (signer commitment to `falcon` or `ecdsa`), decoded per approver from state, and `auth_scheme` redefined as the signers' common scheme or `mixed`, because "one scheme per account" no longer holds (section 3.2). The execution path's refusals named as `GUARDIAN_EXECUTION_MODULE_DENIED` and `GUARDIAN_EXECUTION_MODULE_UNAVAILABLE` failure codes (section 4.1). The execution requester is carried to the ack, not stored on the reservation, since pre-boundary attempts are never resumed (sections 3.2 and 7) | | 25 | 2026-11-03 | status moved from Open for comment to Accepted for implementation on merge of PR #544; RFC 0001 links point at its merged copy and section 7 records that PR #510 has merged; review-sought and code-baseline rows updated to match. No design change | | 24 | 2026-10-21 | three review rounds on PR #544, `main` merged in and citations re-pinned to `ca503704` and Miden 0.17.1. Protocol: registration rewritten for the account claim of #558 (section 2.3); `network_id`; `code_commitment`, `procedure_roots`, effective `procedure_thresholds` and `new_code_commitment`, with invariant 6 and the `basic-policy` code allowlist; `reference_block` and optional `expiration_block`; `submitter_session`; `request_id` defined; proto renumbered for version 1; `notify` capability (section 3.5); freeze criteria (section 7). `proposer_session` stored with the proposal; `dry_run`, with approval instances run by the policy check and `complete` derived from the catalog; `code_check`; reassignment enters `resync_required`. Semantics: `params_drift` against `seeded_params`; params size cap; paginated history; `default` copies take the evaluated params. Writing: contents, terms, registration out of the hook table, `basic-policy` table with reason codes, policy summary example, notify and resync sequence diagram, break-glass and denial-log notes | | 23 | 2026-10-19 | resync ordering (sections 3.3, 3.4, 4.2), found by a TLA+ model of the notify and `pending` design: a resync keeps the (module, account) pair refused until the module has acknowledged `NotifyGap`, and failed Gap calls are retried rather than skipped; the Gap obligation is stored with the delivery cursor, and no replica sends an event while it is open, because a replica that has lost the lease could otherwise deliver an event committed after the resync ahead of the Gap and the module would skip its reset; `resume_from_nonce` defined from the last skipped event; the false claim that a stale leader only has pre-resync events in flight corrected (Appendix B); `Retained` and client-abandoned rows stated to be outside `pending`, with the argument that a limit still holds; model-checked claims tagged **[RAN]**; resync conformance cases | diff --git a/spec/api.md b/spec/api.md index c87ad535..6ad3558a 100644 --- a/spec/api.md +++ b/spec/api.md @@ -528,12 +528,14 @@ travels as `meta_json`): - `state` is one of exactly five values: `pending`, `proving`, `submitted`, `committed`, `failed`. They move forward only. `submitted` means the transaction may have been sent and is never retried; it resolves only from what the chain shows. -- `error` is present exactly when `state` is `failed`. Three codes carry `meta`: +- `error` is present exactly when `state` is `failed`. These codes carry `meta`: `GUARDIAN_EXECUTION_REQUEST_INVALID` (`reason`: `bound_block_not_declared`, `auth_args_missing`, `approval_expiration_missing`, `input_notes_not_pinned`, `too_many_declared_blocks`), `GUARDIAN_EXECUTION_EXPIRATION_REACHED` (`bound`: `approval`, `transaction`) and `GUARDIAN_EXECUTION_FOREIGN_ACCOUNT_UNAVAILABLE` - (`reason`: `private`, `unavailable`). The full list is in + (`reason`: `private`, `unavailable`); on servers with policy modules, + `GUARDIAN_EXECUTION_MODULE_DENIED` (`reason_code`, and `module`, `layer`, `client_message` unless + the denial is generic) and `GUARDIAN_EXECUTION_MODULE_UNAVAILABLE` (`module`). The full list is in [`docs/TROUBLESHOOTING.md`](../docs/TROUBLESHOOTING.md#guardian-execution). - `delta_nonce` is set once the execution committed to its candidate delta. - `newly_accepted` separates the request that started the execution from a repeat that found diff --git a/speckit/features/251-guardian-modules/checklists/requirements.md b/speckit/features/251-guardian-modules/checklists/requirements.md index 422c4686..8d736a28 100644 --- a/speckit/features/251-guardian-modules/checklists/requirements.md +++ b/speckit/features/251-guardian-modules/checklists/requirements.md @@ -37,4 +37,4 @@ - No clarification markers: the open decisions were resolved in RFC 0002 revisions 1 to 19 (section 9 and Appendix C). - SC-006 (10 ms in-process overhead) and the default budget are provisional until the prototype on `251-modules-prototype` measures them. - Validation pass 3 (2026-10-13, after the pre-prototype plan): review found a split-payment gap in the amount cap, stateful activation with queued candidates lacking module data, the filesystem proposal update path, sequential evaluation not continuing past fail-open failures, and FR-100 metrics in the wrong slice. Resolved: per-asset gross outgoing cap with split-payment and receive-and-send scenarios (Story 1), FR-067 and the activation fence (Story 7), FR-035 separating creation from updates, FR-053 continuing past fail-open failures (Story 4), orphaned and over-budget metrics moved to M2a. RFC 0002 revision 19 updated to match. All items pass. -- `plan.md` records the pre-prototype assumptions and the prototype findings (`research.md`, G1 to G5). `tasks.md` holds the P0 prototype tasks and the follow-on phases; the quickstart walk-through and an end-to-end run against a local node remain open. +- `plan.md` records the pre-prototype assumptions and the prototype findings (`research.md`, G1 to G5). `tasks-p0.md` holds the P0 prototype tasks and the follow-on phases, and `tasks.md` the M2a implementation tasks; the quickstart walk-through and an end-to-end run against a local node remain open. diff --git a/speckit/features/251-guardian-modules/contracts/guardian_module_v1.proto b/speckit/features/251-guardian-modules/contracts/guardian_module_v1.proto index 755b1547..fcfc03d4 100644 --- a/speckit/features/251-guardian-modules/contracts/guardian_module_v1.proto +++ b/speckit/features/251-guardian-modules/contracts/guardian_module_v1.proto @@ -68,12 +68,13 @@ message HookRequest { message AccountView { string commitment = 1; - string auth_scheme = 2; // "falcon" or "ecdsa", from the registered auth configuration (section 3.2) + string auth_scheme = 2; // the scheme every signer shares, "falcon" or "ecdsa", or "mixed" (section 3.2) repeated string signer_commitments = 3; optional uint32 default_threshold = 4; // absent for single-key accounts map procedure_thresholds = 5; // procedure root -> threshold; only overrides the account's code can apply (section 3.2) string code_commitment = 6; // commitment of the account's code repeated string procedure_roots = 7; // roots of the procedures the account's code exports + map signer_schemes = 8; // signer commitment -> "falcon" or "ecdsa"; one entry per signer (section 3.2) } message TransactionSubject { diff --git a/speckit/features/251-guardian-modules/data-model.md b/speckit/features/251-guardian-modules/data-model.md index 958f9f01..c0c71788 100644 --- a/speckit/features/251-guardian-modules/data-model.md +++ b/speckit/features/251-guardian-modules/data-model.md @@ -151,5 +151,5 @@ A deny is an answer and resets the failure count. `guardian_module_circuit_open{ | `TransactionProjection` (Miden variant `MidenTransaction`) | Transaction summary (gate G2) | At least one module will be called; stored when M2b subscribers exist | | `pending` | Candidate queue and unacknowledged events in one repeatable-read snapshot (M2b) | Only for modules subscribed to `after_transaction_committed` | | `params` | The layer being evaluated: global params, then the account layer of an `all` instance as a second pass, or the account's own params for `default`/`assigned` | Per module and layer | -| `submitter` | Request authentication (`ResolvedAccount.signer_commitment`) or the execution reservation | Always | +| `submitter` | Request authentication (`ResolvedAccount.signer_commitment`), on the execution path carried on the execution job from the request that started the attempt | Always | | `proposer`, `unverified_metadata` | `ProposalContext` | Transaction hooks | diff --git a/speckit/features/251-guardian-modules/plan.md b/speckit/features/251-guardian-modules/plan.md index 39b986ae..18ec0749 100644 --- a/speckit/features/251-guardian-modules/plan.md +++ b/speckit/features/251-guardian-modules/plan.md @@ -1,8 +1,8 @@ # Implementation Plan: Guardian Modules, a Hook Pipeline for Pluggable Policy -**Branch**: `251-guardian-modules` (spec and plan on `251-guardian-modules-rfc`, PR #544) | **Date**: 2026-10-13 | **Spec**: [spec.md](./spec.md) -**Input**: Feature specification from `speckit/features/251-guardian-modules/spec.md`; design source [RFC 0002](../../../docs/rfcs/0002-guardian-modules.md), written against revision 19; the RFC is now at revision 24 -**Status**: Prototype built (2026-10-13), gates G1 to G5 closed at component level ([research.md](./research.md#prototype-findings-2026-10-13)); RFC revisions 20 (prototype findings) and 21 (layered parameters, decision D11) applied. Still open: the end-to-end walk-through and latency A/B against a local Miden node. M2a `tasks.md` follows. +**Branch**: M2a on `251-modules-m2a` and its stacked layer branches (see "M2a delivery"); prototype on `251-modules-prototype` (draft PR #554); RFC and speckit merged with PR #544 | **Date**: 2026-10-13, M2a revision 2026-11-09 | **Spec**: [spec.md](./spec.md) +**Input**: Feature specification from `speckit/features/251-guardian-modules/spec.md`; design source [RFC 0002](../../../docs/rfcs/0002-guardian-modules.md), written against revision 19; M2a follows revision 26 +**Status**: Prototype built (2026-10-13), gates G1 to G5 closed at component level ([research.md](./research.md#prototype-findings-2026-10-13)); RFC revisions 20 (prototype findings) and 21 (layered parameters, decision D11) applied. Still open: the end-to-end walk-through and latency A/B against a local Miden node. M2a implementation started 2026-11-09 against RFC revision 26: [tasks.md](./tasks.md); the prototype record is [tasks-p0.md](./tasks-p0.md). ## Summary @@ -59,76 +59,95 @@ speckit/features/251-guardian-modules/ │ ├── operator-modules-api.md │ └── client-errors.md ├── checklists/requirements.md -└── tasks.md # P0 prototype tasks and the follow-on phases +├── tasks-p0.md # P0 prototype tasks and the follow-on phases (record) +└── tasks.md # M2a implementation tasks ``` ### Source Code (repository root) ```text -crates/guardian-module-sdk/ # NEW, published (M2a) -├── proto/guardian_module_v1.proto -├── build.rs # tonic-prost-build +crates/guardian-module-sdk/ # published crate (M2a) +├── proto/guardian_module_v1.proto # protocol version 1, frozen at the end of M2a phase 2 +├── build.rs # tonic-prost-build ├── src/ -│ ├── lib.rs # Module, ModuleFactory, ModuleError, re-exported protocol types -│ ├── serve.rs # gRPC harness, per-instance credentials -│ ├── stateful.rs # watermark helper (M2b) -│ └── conformance/ # suite run against in-process and remote modules -└── examples/basic-policy-serve.rs +│ ├── lib.rs # Module, ModuleFactory, ModuleError, protocol types, request helpers +│ ├── serve.rs # gRPC harness, per-instance credentials +│ ├── basic_policy.rs # first-party reference kind +│ ├── conformance/ # M2a: reusable suite (today tests/conformance.rs) +│ └── stateful.rs # M2b: watermark helper +├── examples/basic-policy-serve.rs, note-policy-serve.rs +└── tests/conformance.rs crates/server/src/ -├── modules/ # NEW -│ ├── catalog.rs # TOML load, validation, hash, startup checks -│ ├── registry.rs # kind registration, instance creation, secret resolution -│ ├── pipeline.rs # ordered evaluation, budget, first-deny -│ ├── request.rs # HookRequest assembly, ProposalContext, size cap -│ ├── account_view.rs # AccountView extraction (gate G1) -│ ├── projection.rs # MidenTransaction builder (gate G2) -│ ├── grpc_kind.rs # remote kind client, TLS, auth -│ ├── breaker.rs # circuit breaker and health probe -│ ├── basic_policy.rs # first-party reference kind -│ ├── assignment.rs # per-account assignment and flags in the metadata store -│ └── notify/ # outbox writer, notifier, delivery, resync (M2b) -├── services/push_delta.rs # pipeline before ack (acknowledge_delta after PR #510) -├── services/push_delta_proposal.rs # pipeline before submit_delta_proposal -├── services/configure_account.rs # pipeline after credential and signer checks; default copy -├── storage/filesystem.rs # proposal create-if-absent -├── network/ # account_view on NetworkClient -├── dashboard/ # module routes, modules:disable permission -├── error.rs # ModuleDenied, ModuleUnavailable -├── metrics/ # module metrics -└── builder/ # with_module_kind, from_env (M2c), catalog in build() - -crates/server/migrations/_guardian_modules/ # assignments, flags, delta columns (M2a) -crates/server/migrations/_guardian_module_events/ # outbox and delivery (M2b) - -crates/client/src/ # typed module errors -crates/miden-multisig-client/src/ # typed module errors on proposal, push, registration -packages/guardian-client/src/ # same in TypeScript -packages/miden-multisig-client/src/ -packages/guardian-operator-client/src/ # module endpoints -examples/policy-module/ # basic-policy as a standalone gRPC service -examples/custom-guardian/ # M2c custom build -docs/ # CONFIGURATION, TROUBLESHOOTING, CONCEPTS trust boundary, module author guide -docs/openapi*.json # regenerated with gen-openapi; CI checks drift -crates/guardian-module-sdk/README.md # NEW: crates.io landing page, module author quick start -crates/client/README.md, packages/guardian-client/README.md # module error codes -crates/miden-multisig-client/README.md, packages/miden-multisig-client/README.md # refusals at creation, push, registration -packages/guardian-operator-client/README.md # module endpoints +├── modules/ +│ ├── mod.rs # loading at startup, wiring into AppState +│ ├── catalog.rs # TOML load, validation, hash, startup checks +│ ├── registry.rs # kinds, instance creation, describe and params checks +│ ├── pipeline.rs # ordered evaluation, layers, first deny, dry run +│ ├── request.rs # HookRequest assembly, views, ProposalContext +│ ├── grpc_kind.rs # remote kind client, TLS, auth +│ ├── disclosure.rs, check_limit.rs # policy discovery and the dry-run rate limit +│ ├── admin.rs # operator views and writes +│ ├── store.rs, postgres_store.rs # module state on the filesystem and Postgres +│ ├── testing.rs # stub modules and pipelines for tests +│ ├── budget.rs, breaker.rs, metrics.rs # M2a: evaluation budget, circuit breaker and probe, metrics +│ └── notify/ # M2b: outbox writer, notifier, delivery, resync +├── network/miden/module_views.rs # AccountView extraction and MidenTransaction projection +├── services/ack_delta_internal.rs # before_transaction_approved, shared by push_delta and the execution worker +├── services/push_delta_proposal.rs # before_proposal_created and the dry-run check +├── services/configure_account.rs # before_account_registered, before the account claim +├── services/get_policies.rs # policy summary +├── services/execute_proposal/worker.rs # requester carried to the ack; module failure codes +├── api/dashboard_modules.rs # operator routes on /dashboard/modules +├── dashboard/{authz,permissions}.rs # policies:write, policies:write_global, modules:disable +├── error.rs # GUARDIAN_MODULE_* errors +└── builder/ # with_module_kind (M2c, prototyped), catalog in build() + +crates/server/migrations/2026-10-15-000001_guardian_modules/ # module instances, account params, version, history +crates/server/migrations/_guardian_module_delta_fields/ # M2a: approval trace, signed_at, submitter, proposer +crates/server/migrations/_guardian_module_events/ # M2b: outbox and delivery +crates/server/examples/modules_admin.rs, custom_module_server.rs + +crates/shared/src/execution.rs # GUARDIAN_EXECUTION_MODULE_* failure codes +crates/client/src/error.rs # ModuleRefusal, module_refusal() +crates/miden-multisig-client/src/ # ModuleDenied, ModuleUnavailable; get_policies; ProposalBuilder::check +packages/guardian-client/src/http.ts # moduleRefusal(); checkDeltaProposal, getPolicies +packages/miden-multisig-client/src/ # M2a: getPolicies, checkTransaction +packages/guardian-operator-client/src/ # M2a: module routes +examples/policy-module/ # M2a: basic-policy as a standalone gRPC service +examples/custom-guardian/ # M2c custom build +docs/guides/policy-modules/ # built-in, remote and custom guides +docs/, spec/ # CONFIGURATION, DASHBOARD, TROUBLESHOOTING, CONCEPTS, runbook, api and processes +docs/openapi*.json # regenerated with gen-openapi; CI checks drift ``` Per AGENTS.md, published crates and packages document new public API in their own README in the same PR, OpenAPI is regenerated for every HTTP change, and `examples/demo`, `examples/web` and `examples/operator-smoke-web` are the required smoke checks ([quickstart.md](./quickstart.md), section 4). -**Structure Decision**: one new library crate for everything a module author needs, and one new `modules` subsystem inside `guardian-server`, so module code is isolated from service code and the services gain one call each. Paths under `crates/server/src/modules/` are indicative until gates G1, G2 and G4 close. +**Structure Decision**: one new library crate for everything a module author needs, and one new `modules` subsystem inside `guardian-server`, so module code is isolated from service code and the services gain one call each. The paths above are the prototype's, carried into M2a; the ones marked M2a, M2b or M2c do not exist yet. ## Delivery Phases | Phase | Content | Exit criterion | |---|---|---| | **P0: Prototype** (branch `251-modules-prototype`, off `main`, not for merge) | SDK skeleton, catalog with `all` and `assigned`, pipeline at push and proposal creation, `basic-policy`, one remote module, account view and projection builders, demo walk-through, latency A/B | Gates G1 to G5 closed or accepted; findings in RFC revision 20 | -| **P1: M2a** | Everything tagged M2a in the spec, starting after PR #510 merges (gate G5) | Stories 1 to 6 acceptance, SC-001 to SC-007, SC-009 to SC-011 | +| **P1: M2a** | Everything tagged M2a in the spec, started 2026-11-09 after PR #510 merged (gate G5); tasks in [tasks.md](./tasks.md) | Stories 1 to 6 acceptance, SC-001 to SC-007, SC-009 to SC-011 | | **P2: M2b** | Outbox, notifier, `pending`, retention, resync, stateful conformance | Story 7, SC-008 | | **P3: M2c** | `ServerBuilder::from_env`, `with_module_kind`, custom-build template | Story 8 | +## M2a delivery + +The prototype (#554) is one draft of about 13,000 lines and is not merged as it is. M2a starts from it and ships as a stack of pull requests off `main`, each building and passing its tests on its own, in this order: + +| Layer | Branch | Content | +|---|---|---| +| 1. Module SDK | `251-m2a-sdk` | `crates/guardian-module-sdk` (protocol, `Module`, `serve`, `basic-policy`, conformance) and the workspace entry | +| 2. Server core | `251-m2a-server-core` | `crates/server/src/modules/`, `network/miden/module_views.rs`, the modules migration, module errors in `error.rs`, permissions and audit kinds, the operator routes, `AppState` wiring, with no hook calling the pipeline yet | +| 3. Hooks | `251-m2a-hooks` | The three gate hooks (`ack_delta_internal.rs`, `push_delta_proposal.rs`, `configure_account.rs`), the execution worker and the `guardian-shared` failure codes, policy discovery routes, delta summary trace, OpenAPI | +| 4. Clients | `251-m2a-clients` | `crates/client`, `crates/miden-multisig-client`, `packages/guardian-client`, `packages/miden-multisig-client`, examples and the qualification driver | +| 5. Docs | `251-m2a-docs` | `docs/guides/policy-modules/`, `docs/`, `spec/`, the `verify-module-counting` skill | + +`251-modules-m2a` is the integration branch at the top of the stack; M2a tasks land on the layer they belong to. The operator client (US5) joins layer 2 or its own PR when it is built. + ## Decisions made during planning Both are now recorded in RFC 0002 revision 19 (section 3.1): diff --git a/speckit/features/251-guardian-modules/research.md b/speckit/features/251-guardian-modules/research.md index 5d457f28..b87726f9 100644 --- a/speckit/features/251-guardian-modules/research.md +++ b/speckit/features/251-guardian-modules/research.md @@ -92,8 +92,8 @@ This research was written before the prototype on `251-modules-prototype` and no ### D9. Execution requester (after PR #510) -- **Decision**: the authenticated requester is stored on the durable execution reservation when an attempt is created, kept on repeated requests for an active attempt, and carried into `acknowledge_delta` and the stored delta. -- **Rationale**: spec FR-033; restart safety. +- **Decision**: the authenticated requester is carried on the execution job from the request that creates the attempt into `acknowledge_delta`; a repeated request for an active attempt joins it and keeps the original requester. It is not stored on the reservation (revised 2026-11-09, RFC revision 26). +- **Rationale**: spec FR-033. Restart safety holds without storing it: the ack runs before the no-retry boundary, and an attempt interrupted before that boundary is never resumed (the startup reconciliation fails it as `GUARDIAN_EXECUTION_ABANDONED`). ### Network-tagged projections (2026-10-16) diff --git a/speckit/features/251-guardian-modules/spec.md b/speckit/features/251-guardian-modules/spec.md index 90f60bf4..855bf290 100644 --- a/speckit/features/251-guardian-modules/spec.md +++ b/speckit/features/251-guardian-modules/spec.md @@ -5,7 +5,7 @@ **Status**: Draft **Design source**: [RFC 0002](../../../docs/rfcs/0002-guardian-modules.md), written against revision 19; the RFC is now at revision 24. The RFC holds the wire protocol, configuration format and code citations; this spec states what the feature must achieve and how that is verified. Where the two differ, the RFC is corrected first and this spec follows. **Input**: Issue #251 ("Modularization: middleware architecture and pluggable modules"), first consumer #182 (policy evaluation), later consumer #252 (x402 facilitator). -**Planning note**: `plan.md` records the pre-prototype plan and its prototype findings; the gates (account view extraction effort, projection reuse, added latency, module author ergonomics, placement relative to PR #510) and their results are in `research.md`. `tasks.md` holds the P0 prototype tasks and the follow-on phases generated since. The quickstart walk-through and an end-to-end run against a local node remain open. +**Planning note**: `plan.md` records the pre-prototype plan and its prototype findings; the gates (account view extraction effort, projection reuse, added latency, module author ergonomics, placement relative to PR #510) and their results are in `research.md`. `tasks-p0.md` holds the P0 prototype tasks and the follow-on phases; `tasks.md` holds the M2a implementation tasks. The quickstart walk-through and an end-to-end run against a local node remain open. ## Context *(why this feature exists)* @@ -255,7 +255,7 @@ Slice tags show where each requirement is first delivered. Wire formats, field n - **FR-030** [M2a]: Every gate request MUST carry the account's state before and after the request as decoded by the Guardian (commitment, authorization scheme, signer set, default threshold, per-procedure thresholds), so one rule can be evaluated identically at every gate point. "Before" is absent only for a new registration. - **FR-031** [M2a]: Extracting those views MUST fail with an error, treated as a module failure, for authorization state the Guardian does not support or cannot decode; it MUST NOT produce an empty signer set. Building "before" at re-onboarding MUST read the stored state. - **FR-032** [M2a]: Transaction requests MUST carry a decoded, versioned projection of the transaction's effects (asset movements, notes, storage changes, nonce and expiration) so modules need no Miden decoder, plus the raw transaction summary for modules that accept coupling to the Guardian's Miden version. -- **FR-033** [M2a]: Every gate request MUST carry the verified identity of the cosigner whose authenticated request is being evaluated (the submitter). On the execution path this MUST be the authenticated requester that created the execution attempt, recorded durably with the attempt and preserved across repeated requests and restarts. +- **FR-033** [M2a]: Every gate request MUST carry the verified identity of the cosigner whose authenticated request is being evaluated (the submitter). On the execution path this MUST be the authenticated requester that created the execution attempt, preserved across repeated requests; no attempt is acknowledged after a restart, since one interrupted before the no-retry boundary is never resumed. - **FR-034** [M2a]: Transaction requests MUST carry the verified identity of the proposal's creator (the proposer) when a matching stored proposal exists, and an empty value otherwise. Proposal lookup MUST distinguish absence from failure; a lookup failure is a module failure. - **FR-035** [M2a]: The first creator of a proposal MUST remain its proposer on every storage backend. Proposal creation and signature updates MUST be separate operations: a duplicate creation keeps the stored proposal, while adding a cosigner signature updates it, on both backends. - **FR-036** [M2a]: Proposer-supplied proposal metadata MUST be passed only as explicitly untrusted data, and no typed copy of proposer-asserted values (amounts, recipients, signers) may be provided. diff --git a/speckit/features/251-guardian-modules/tasks-p0.md b/speckit/features/251-guardian-modules/tasks-p0.md new file mode 100644 index 00000000..d38cf29b --- /dev/null +++ b/speckit/features/251-guardian-modules/tasks-p0.md @@ -0,0 +1,269 @@ +# Tasks: Guardian Modules, Phase P0 (Prototype) + +**Record**: this is the prototype task list, kept as the P0 record. The M2a implementation tasks are in [tasks.md](./tasks.md). + +**Input**: Design documents from `speckit/features/251-guardian-modules/` +**Prerequisites**: [plan.md](./plan.md), [spec.md](./spec.md), [research.md](./research.md), [data-model.md](./data-model.md), [contracts/](./contracts/), [quickstart.md](./quickstart.md) + +**Scope**: phases 1 to 9 are P0 of the plan: enough of M2a to evaluate the prototype gates G1 to G5 in [research.md](./research.md) and to try the feature end to end. Later phases record the follow-on work done on the prototype since (layered params, storage, review fixes, protocol evolution, disclosure). The remaining M2a, M2b and M2c tasks are generated once the RFC is accepted. + +**Branch**: the code lives on `251-modules-prototype` (draft PR #554, based on the RFC branch); `251-guardian-modules-rfc` (PR #544) stays doc-only. + +**Excluded from P0**: the operator API (Story 5), `default` scope, evaluation budget, circuit breaker and health probe, request size cap, metrics, M2b (Story 7), M2c (Story 8), TypeScript parity, the execution path (PR #510 not merged). + +**Prototype shortcuts** (not the M2a design): secrets are read from files (`token_file`, `tls.*_file`) instead of the secrets backend; the approval record lives in delta metadata instead of delta columns. Per-account assignments started in the catalog file and moved to the operator API with Phase 10 (T041). + +**Tests**: included, because the spec's acceptance scenarios are the evidence that closes the gates (constitution principle V). + +## Format: `[ID] [P?] [Story] Description` + +- **[P]**: can run in parallel (different files, no dependency on an incomplete task) +- **[Story]**: user story from spec.md (US1, US2, US3, US4, US6) + +--- + +## Phase 1: Setup + +**Purpose**: the SDK crate and the server module skeleton. + +- [X] T001 Create crate `crates/guardian-module-sdk` (`Cargo.toml` with workspace version, edition, rust-version, license; dependencies `tonic`, `tonic-prost`, `prost`, `async-trait`, `thiserror`, `serde_json`, `tokio`; build dependency `tonic-prost-build`) and add it to `members` and `default-members` in the root `Cargo.toml` +- [X] T002 Copy `speckit/features/251-guardian-modules/contracts/guardian_module_v1.proto` to `crates/guardian-module-sdk/proto/guardian_module_v1.proto` and add `crates/guardian-module-sdk/build.rs` compiling it with client and server stubs, following `crates/server/build.rs` +- [X] T003 Add `guardian-module-sdk` as a path dependency of `guardian-server` in `crates/server/Cargo.toml`, add the `toml` dependency, and create `crates/server/src/modules/mod.rs` declared from `crates/server/src/lib.rs` + +--- + +## Phase 2: Foundational + +**Purpose**: everything every story needs: the module interface, catalog, request assembly (gates G1 and G2), the pipeline and the errors. + +**Checkpoint**: `cargo test -p guardian-module-sdk` and `cargo test -p guardian-server modules::` pass; a server started without `GUARDIAN_MODULES_CONFIG` behaves exactly as before. + +- [X] T004 Define `Module` (`describe`, `validate_params`, `evaluate`, `notify`, `notify_gap` with default no-op), `ModuleFactory`, `ModuleError` and re-exports of the generated `guardian.module.v1` types in `crates/guardian-module-sdk/src/lib.rs`, using `async_trait` so `Arc` is object safe +- [X] T005 [P] Implement catalog parsing and validation for `[[module]]` entries (`id`, `kind`, `endpoint`, `scope` limited to `all` and `assigned`, `hooks`, `timeout_ms`, `on_error`, `enabled`, `params`, `account_params`) and the prototype `[[assignment]]` table (`account_id`, ordered `modules` with `params`), with a catalog hash, in `crates/server/src/modules/catalog.rs`; unit tests for unknown kind, empty hooks, `account_params` outside `scope = "all"`, and an assignment naming an `all` instance +- [X] T006 [P] Implement the kind registry and instance creation (factory per kind, `describe` hook check, `validate_params` on `params` and each merged `account_params` entry, startup failure for an enabled instance) in `crates/server/src/modules/registry.rs` +- [X] T007 [P] Add `AccountView` extraction (gate G1): a `NetworkClient::account_view(&serde_json::Value) -> Result` method in `crates/server/src/network/mod.rs`, implemented in `crates/server/src/network/miden/mod.rs` with new `MidenAccountInspector` readers for the default threshold, the procedure thresholds map and the auth scheme in `crates/server/src/network/miden/account_inspector.rs`, returning an error (never an empty view) for unsupported or undecodable auth state; update test mocks in `crates/server/src/testing/mocks.rs` +- [X] T008 [P] Implement the `TxProjection` builder (gate G2) in `crates/server/src/modules/projection.rs`, reusing helpers from `crates/server/src/delta_summary/projection.rs` and producing every proto field (`nonce_delta`, `expiration_block`, vault changes, output notes with `partial`, `recipient_digest`, `script_root`, `p2id_target`, input notes, storage changes with create, update and remove); record each field it cannot derive in a `G2` section at the end of `speckit/features/251-guardian-modules/research.md` +- [X] T009 Implement `ProposalContext { proposer, metadata }` and a lookup returning `Result, GuardianError>` that separates absence from storage failure, next to `lookup_matching_proposal_payload`, in `crates/server/src/modules/request.rs` +- [X] T010 Make filesystem proposal creation create-if-absent and give `update_delta_proposal` its own replace-if-present implementation in `crates/server/src/storage/filesystem.rs`; tests: a duplicate creation keeps the first proposer, and create, sign, reload keeps the cosigner signature +- [X] T011 Implement `HookRequest` assembly (`submitter`, `before` and `after` views, `TransactionSubject` with projection, raw summary, proposer and `unverified_metadata`, `RegistrationSubject` with `initial_state`; params as RFC 8785 canonical JSON with `account_params` merged), built only when at least one module will be called, in `crates/server/src/modules/request.rs` +- [X] T012 Implement the pipeline in `crates/server/src/modules/pipeline.rs`: resolve the ordered set for a hook (enabled `all` instances in catalog order, then the account's assignment), call each under its `timeout_ms`, stop on deny or on a failure of an `on_error = "deny"` instance, continue past a failure of an `on_error = "allow"` instance with a WARN log, reject a deny whose `reason_code` does not match `[a-z0-9_]{1,64}` as a failure +- [X] T013 Add `GuardianError::ModuleDenied { module, reason_code }` (403, `PERMISSION_DENIED`, code `GUARDIAN_MODULE_DENIED`, non-retryable) and `GuardianError::ModuleUnavailable { module }` (503, `UNAVAILABLE`, code `GUARDIAN_MODULE_UNAVAILABLE`, retryable) with `meta` and user messages in `crates/server/src/error.rs`, following `AccountPaused` +- [X] T014 Load the catalog from `GUARDIAN_MODULES_CONFIG` in `ServerBuilder::build()`, register the first-party kinds, and add `modules: Option>` to `AppState` in `crates/server/src/builder/mod.rs` and `crates/server/src/builder/state.rs`; `None` when the variable is unset + +--- + +## Phase 3: User Story 1, enforce a mandatory policy (P1) + +**Goal**: an `all` instance of `basic-policy` refuses over-cap or off-list transactions on every approval path available on `main`. + +**Independent Test**: quickstart steps "Propose a transfer of 500", "Propose one transaction sending 600 and 600", "Export a 5,000 transfer, sign offline, push directly". + +- [X] T015 [P] [US1] Implement `basic-policy` transaction rules in `crates/server/src/modules/basic_policy.rs`: `max_amount_per_tx` as a map from faucet id to decimal amount over the gross amount sent per faucet across all output notes (inputs do not offset, fee excluded, unlisted faucets uncapped, NFTs ignored), `asset_allowlist`, `recipient_allowlist` denying partial and non-P2ID notes; `validate_params` rejecting unknown params; reason codes `amount_cap_exceeded`, `asset_not_allowed`, `recipient_not_allowed` +- [X] T016 [P] [US1] Unit tests for `basic-policy` in `crates/server/src/modules/basic_policy.rs`: one note under the cap, two 600 notes against a 1,000 cap, receiving 1,000 and sending 1,500, an uncapped faucet, an NFT, a partial note under a recipient allowlist, forged `unverified_metadata` not changing the decision +- [X] T017 [US1] Run the `before_transaction_approved` pipeline in `crates/server/src/services/push_delta.rs` after the pause check and before `state.ack.ack_delta`, with `submitter` from `resolved.signer_commitment`, `before` from the base state and `after` from the applied state, and the proposer from the `ProposalContext` lookup (a lookup error applies `on_error`) +- [X] T018 [US1] Service tests in `crates/server/src/services/push_delta.rs`: a denied push returns `ModuleDenied`, stores no candidate and returns no signature; an allowed push behaves as today; with `modules = None` every existing push test passes unchanged + +--- + +## Phase 4: User Story 2, refusal before anyone signs (P1) + +**Goal**: an instance subscribed to `before_proposal_created` refuses a proposal before it is stored. + +**Independent Test**: quickstart step "Propose a transfer of 5,000": refused, proposal count unchanged. + +- [X] T019 [US2] Run the `before_proposal_created` pipeline in `crates/server/src/services/push_delta_proposal.rs` after the proposer signature check and before `submit_delta_proposal`, with `before` the pinned tail and `after` the tail with the delta applied, `accounting_time` not stored +- [X] T020 [US2] Service tests in `crates/server/src/services/push_delta_proposal.rs`: a denied creation stores nothing and leaves the pending-proposal count unchanged; an account one below its limit can still create a valid proposal after a denial; an instance subscribed only to `before_transaction_approved` is not called at creation + +--- + +## Phase 5: User Story 3, control which keys may sign (P1) + +**Goal**: one signer rule enforced at registration, proposal creation and approval through the account views. + +**Independent Test**: register with an unlisted signer, propose adding an unlisted signer, push an offline signer change; each is refused. + +- [X] T021 [P] [US3] Add `signer_allowlist`, `signer_denylist` (mutually exclusive) and `signer_check` (`added` default, `all`) to `crates/server/src/modules/basic_policy.rs`, evaluated only from `before` and `after`, reason code `signer_not_allowed`; unit tests for added versus all, absent `before` at registration, and an extraction error applying `on_error` +- [X] T022 [US3] Run the `before_account_registered` pipeline in `crates/server/src/services/configure_account.rs` after the credential, signer set and commitment checks and before any write, with `submitter` from the verified credential, `after` from `initial_state`, and `before` from a `pull_state` of the stored state only for existing accounts; no pause or release check is added +- [X] T023 [US3] Service tests in `crates/server/src/services/configure_account.rs`: a denied new registration writes nothing; a denied reconfiguration leaves state, metadata, pause and release unchanged; an allowed reconfiguration of a paused account keeps it paused; an allowed re-onboarding of a released account reactivates it and a denied one leaves it released + +--- + +## Phase 6: User Story 4, choose failure behaviour (P1, partial) + +**Goal**: `on_error` and timeouts behave as specified. Budget, breaker and probe are out of P0. + +**Independent Test**: stop a remote module configured fail-closed, then fail-open, and push. + +- [X] T024 [US4] Pipeline tests in `crates/server/src/modules/pipeline.rs` with stub modules: a timeout of a fail-closed module returns `ModuleUnavailable`; a timeout of a fail-open module continues; a fail-open module that errors followed by a denying module is refused by the second; a malformed `reason_code` counts as a failure + +--- + +## Phase 7: User Story 6, a remote module without rebuilding (P2) + +**Goal**: `basic-policy` served over gRPC gives the same decisions as in process. + +**Independent Test**: quickstart section 3. + +- [X] T025 [P] [US6] Implement the `serve` harness in `crates/guardian-module-sdk/src/serve.rs`: wraps any `Module` in the generated gRPC service, binds a bearer token per `instance_id` and rejects a mismatch with `PERMISSION_DENIED` +- [X] T026 [P] [US6] Implement the `grpc` kind in `crates/server/src/modules/grpc_kind.rs`: tonic client per instance, bearer token from the instance's `auth` (a file path in P0), `describe` and `validate_params` at startup, transport errors and timeouts as module failures +- [X] T027 [US6] Move the `basic-policy` rule code into `crates/guardian-module-sdk/src/basic_policy.rs` so the server's in-process kind and the remote example share it, keeping `crates/server/src/modules/basic_policy.rs` as the factory +- [X] T028 [US6] Add the runnable example `crates/guardian-module-sdk/examples/basic-policy-serve.rs` taking `--listen` and `--token-file` +- [X] T029 [US6] Conformance tests in `crates/guardian-module-sdk/tests/conformance.rs`: the same requests evaluated in process and through the harness over loopback give identical decisions; evaluating a request twice leaves module state unchanged; a request authenticated for one instance and naming another is rejected + +--- + +## Phase 8: Clients and demo (US1, US2, US3) + +**Goal**: module refusals are typed in Rust and visible in `examples/demo`. + +- [X] T030 [P] [US1] Add typed accessors for `GUARDIAN_MODULE_DENIED` (`module`, `reason_code`, not retryable) and `GUARDIAN_MODULE_UNAVAILABLE` (`module`, retryable) to `ClientError` in `crates/client/src/error.rs`, with tests parsing both from gRPC status details +- [X] T031 [US2] Surface both errors from proposal creation, push and registration in `crates/miden-multisig-client` without wrapping them into generic errors; test that a denied proposal creation exposes `module` and `reason_code` +- [X] T032 [US3] Print module refusals (instance, reason code, retryable or not) in `examples/demo` where proposal creation, execution and account registration report errors + +--- + +## Phase 9: Gate closure + +**Purpose**: turn the prototype into findings for RFC revision 20 and the M2a task list. + +- [ ] T033 Run the quickstart walk-through (sections 1 to 3) against a local server with the filesystem backend and record each step's result in `speckit/features/251-guardian-modules/research.md` under each gate +- [X] T034 [P] Gate G1: test `account_view` on single-key, multisig and guardian-multisig fixture accounts and on an unsupported layout in `crates/server/src/network/miden/mod.rs`; record decode cost per call and the decision on `procedure_thresholds` in `research.md` +- [X] T035 [P] Gate G2: test the projection builder on one fixture per transaction kind (P2ID, P2IDE, consume notes, add and remove signer, change threshold, update procedure threshold, switch guardian) in `crates/server/src/modules/projection.rs`; record fields kept and dropped in `research.md` +- [X] T036 Gate G3: measure p50 and p99 of `push_delta` and `push_delta_proposal` with no catalog, one in-process `basic-policy`, and one remote `basic-policy` over loopback, including the share spent building views and projections, with a script in `crates/guardian-module-sdk/examples/latency_ab.rs` or the existing loadgen in `crates/server/bench/loadgen`; record results against SC-001 and SC-006 in `research.md`; done 2026-10-16 with the loadgen `state-push` scenario and `crates/server/examples/bench_server.rs`, results in `research.md` (G3 end to end); follow-up fixes: account view cache by state commitment and a single proposal read in `push_delta` +- [X] T037 Gate G4 and G5: record module author findings (trait shape, typed request helpers such as `added_signers()`, branching needed per hook) and pipeline placement on `main` versus `acknowledge_delta` in PR #510 in `research.md` +- [X] T038 Mark gates G1 to G5 closed or accepted in `research.md`, list the RFC changes they require for revision 20, and update the Status line of `plan.md` + +--- + +## Phase 10: Layered parameters (RFC revision 21) + +**Goal**: operator-managed params from the dashboard API: global params seeded from the catalog, account layers that only add restrictions, assignments, history and version. The catalog keeps instance registration only. + +**Storage** (research D12): module state lives in its own tables, `module_instances`, `module_account_params` and `module_params_history`, on Postgres through a migration (plus the one-row `module_state_version` lock) and on the filesystem backend as one atomically replaced file, `/modules/module_state.json` (`GUARDIAN_MODULES_STATE` overrides the directory). + +- [X] T039 [US5] Add `recipient_denylist` and `deny_unknown_recipients` to `crates/guardian-module-sdk/src/basic_policy.rs`, reason code `recipient_blocked`, with tests +- [X] T040 [US5] Implement the params store (global params with the seed rule, account layers, assignments, history, version, file persistence) in `crates/server/src/modules/params.rs`, with tests +- [X] T041 [US5] Remove `account_params` and the `[[assignment]]` table from `crates/server/src/modules/catalog.rs`; mark params holding secret references as file-managed +- [X] T042 [US5] Evaluate an `all` instance's account layer as a second pass in `crates/server/src/modules/pipeline.rs`; `layer` on `GuardianError::ModuleDenied` and in `meta`; validate stored global params at startup; tests for extension, no loosening and runtime global changes +- [X] T043 [US5] Implement the operator operations (validation, history, audit kinds `modules.params.global`, `modules.params.account`, `modules.assignment`) in `crates/server/src/modules/admin.rs`, `GuardianError::ModuleNotFound`, permission `policies:write_global`, with tests +- [X] T044 [US5] Add the routes in `crates/server/src/api/dashboard_modules.rs` and `crates/server/src/builder/handle.rs`, with a router test for permission gating, global writes, drift and history +- [X] T045 [US5] Carry `layer` through `ModuleRefusal` in `crates/client` and `MultisigError::ModuleDenied` +- [X] T046 [US5] Add the operator CLI `crates/server/examples/modules_admin.rs` (keygen, login, call) +- [X] T048 [US5] Replace the single-file params store with the `ModuleStore` trait over the three tables in `crates/server/src/modules/store.rs` (filesystem: one file per table), make evaluation read the account's rows with one query and cache global params per replica by params version, and fail closed with a storage error when the tables are unreadable +- [X] T049 [US5] Add the migration `crates/server/migrations/2026-10-15-000001_guardian_modules` and `PgModuleStore` in `crates/server/src/modules/postgres_store.rs` (each write and its history row in one transaction), wired through `CoordinationHandles`, with a Postgres test across two replicas +- [X] T050 [US5] Runtime enable and disable: `operator_can_disable` in the catalog, `set_enabled` on both stores (recorded in the history so the version moves), the pipeline and startup reading the stored flag, `POST /dashboard/modules/{id}/enable` (`policies:write`, re-runs the startup checks) and `/disable` (`policies:write` or `modules:disable` through a new any-of authz mode; `GUARDIAN_MODULE_NOT_DISABLEABLE` when the catalog forbids it), audit kinds `modules.enable` and `modules.disable`, with tests on every layer +- [X] T047 [US5] Walk the blocklist scenario against a running server with the CLI (quickstart section 4); confirmed live on 2026-10-15 (Postgres backend, devnet demo): global cap, a stricter account layer refusing with `layer: account`, a looser account layer still refused by the global rule, layer removal, and the params history + +## Phase 11: Review fixes (fleet review 2026-10-15) + +- [X] T051 Decode the projection and `raw_tx_summary` (Miden binary) from exactly the summary the Guardian signs: `NetworkClient::module_transaction` takes the bare summary, the proposal path passes `tx_summary`, the decoder refuses wrappers; `decode_transaction_summary` prefers a top-level `data` for the dashboard metadata +- [X] T052 Move the params version to the one-row `module_state_version` lock in the migration and `crates/server/src/modules/postgres_store.rs`; read the previous assignment inside the write transaction; Postgres test for concurrent replacements +- [X] T053 Check the effective params (stored global params, else the catalog seed) at startup and before enable, and seed new instances only after every instance passed its checks, in `crates/server/src/modules/pipeline.rs`, `registry.rs` and `admin.rs` +- [X] T054 Resolve a request's modules once with one version read (`ModulePipeline::plan`, `Plan::run`) and use it in the three services +- [X] T055 Record `catalog_hash` and `params_version` on the signed delta (`DeltaMetadata.modules`) +- [X] T056 Report the runtime flag for assigned modules in the account view +- [X] T057 Persist the filesystem module tables as one file, synced and renamed +- [X] T058 Single-key accounts: a view without signers and `default_threshold` from the state, the signer and scheme from the registered auth configuration +- [X] T059 TLS for remote modules: `grpc://` is TLS (system roots or `tls.ca_file`, optional client certificate), plain text only through `grpc+insecure://` to a loopback host, prod stage refuses plain text and requires `auth` +- [X] T060 Add the four `GUARDIAN_MODULE_*` codes to `packages/guardian-client/src/error-codes.ts` + +## Phase 12: Replayable approvals + +- [X] T061 Module builds (`name version` from `describe`) in the startup log and in `GET /dashboard/modules` +- [X] T062 Evaluation trace on the signed delta (`DeltaMetadata.modules`): `catalog_hash`, `params_version`, `failed_open` +- [ ] T063 Replay command: rebuild a delta's request at its `params_version`, re-run the modules and diff against the trace; adds what it needs: configuration snapshots with module builds, the request hash (ordered proto maps), `accounting_time`, `proposer` (M2a) +- [ ] T064 Decision log for denials and proposal-time evaluations, same trace shape (M2a) + +## Phase 13: In-process custom kinds (M2c, prototyped early) + +- [X] T065 `ServerBuilder::with_module_kind` registering a kind the catalog can name; `Registry::register` refuses a taken name, including `basic-policy` and `grpc`; example `crates/server/examples/custom_module_server.rs` with `note-policy` shared with the gRPC example +- [X] T066 Isolate every module call (`describe`, `validate_params`, `evaluate`) on its own task: a panic is a module failure and `on_error` applies, the timeout holds when a module blocks, a factory panic fails startup with an error +- [X] T067 Policy modules guide `docs/guides/policy-modules/` (built-in, remote, custom over gRPC and in process) with catalog templates loaded by a test; `CONFIGURATION.md` and `DASHBOARD.md` reference entries +- [ ] T068 `ServerBuilder::from_env` so a custom build does not copy `main.rs` (M2c) + +## Phase 14: Protocol evolution (RFC revision 22) + +- [X] T069 Protocol: `DescribeRequest` with the Guardian's protocol range and capabilities, `ModuleInfo.required_capabilities`, `Decision.effect`, `ParamsVerdict.normalized_params` in `crates/guardian-module-sdk/proto/guardian_module_v1.proto`; `Module::describe` takes the request; `capability` constants and `ParamsVerdict::normalized` in the SDK +- [X] T070 SDK source compatibility: `ModuleInstanceConfig`, `ModuleTls`, `ClientIdentity` and `ModuleError` `#[non_exhaustive]`, with constructors +- [X] T071 Guardian: supported protocol range (`MIN_PROTOCOL_VERSION..=PROTOCOL_VERSION`, warning below current), required-capability check, `Decision.effect` with unknown effects as failures, normalized params stored on operator writes and migrated at startup and before enable with a history entry by `module: `, with tests on every path +- [ ] T072 Deprecation window when protocol version 2 exists: build the older request shape for previous-version modules and export `guardian_module_protocol_deprecated{module}` (M2a once a second version exists) +- [ ] T073 Migrate account layers and assignments that a module normalizes (today they migrate when next written) (M2a) + +## Phase 15: Policy discovery and disclosure (RFC revision 22) + +- [X] T074 Catalog fields `disclosure`, `description` (required unless `none`, at most 500 characters), `client_reason` and `dry_run` in `crates/server/src/modules/catalog.rs`, shown in the operator view +- [X] T075 Generic denials (`GuardianError::ModuleDeniedGeneric`, `meta = { reason_code: "policy_denied" }`) and `Decision.client_message` (cleaned, at most 256 characters, forwarded only under full reasons) in the server; `module` and `layer` optional and `client_message` carried in `guardian-client` and `miden-multisig-client` +- [X] T076 Policy summary `GET /policies` and `GetPolicies`: `ModulePipeline::disclosed` in `crates/server/src/modules/disclosure.rs`, `services::get_policies`, HTTP and gRPC handlers, OpenAPI regenerated +- [X] T077 Dry-run check `POST /delta/proposal/check` and `CheckDeltaProposal`: proposal creation in a dry-run mode (`services::check_proposal`), `ModulePipeline::plan_dry_run` with the per-account and per-signer limiter (`GUARDIAN_MODULE_CHECK_RATE_PER_MIN`), logging; `guardian-client` (Rust and TypeScript) methods; Rust multisig `get_policies` and `check_transaction` +- [ ] T078 TypeScript multisig `getPolicies` and `checkTransaction` (after a `@openzeppelin/guardian-client` release), and TypeScript parsing of generic denials and `client_message` + + +## Phase 16: Review fixes (concurrency and throttling) + +- [X] T079 Consistent policy snapshot: `ModulePipeline::snapshot` reads the version, the global rows and the account's rows, rechecks the version and retries, used by `plan` and `disclosed`; acceptance test reproducing a global change and a layer removal racing an evaluation +- [X] T080 Conditional migration writes: `ModuleStore::set_global_if` on both backends (filesystem under the write lock, Postgres under the row lock with the version untouched on a miss), used by startup migration and enable; acceptance test reproducing an operator write racing a migration; Postgres test +- [X] T081 Dry-run limiter independent of the catalog (`crates/server/src/modules/check_limit.rs`), installed at startup, applied to every check before reconstruction; spec FR-041 made conditional on full reasons; FR-028 and FR-029 + +## Phase 17: Network-tagged projections (RFC revision 22) + +- [X] T082 `TransactionProjection`, `AccountStateProjection` (`oneof network`, Miden only) and `RawTransaction` (named `encoding`) replace the Miden-only fields in `TransactionSubject`, `PendingTransaction`, `CommitEvent` and `RegistrationSubject`, with new field numbers and the old ones reserved; `TxProjection` and `AccountProjection` renamed `MidenTransaction` and `MidenAccountState`; SDK accessors (`subject.miden()`), `basic-policy`, `note-policy`, tests and the guide updated +- [ ] T083 `ModuleInfo.networks` and the Guardian's check that a mandatory instance can judge the account's network, when a second network gets a variant + +## Phase 18: Review of revision 23 (RFC revision 24) + +Not started; `main` was merged into the prototype branch on 2026-11-09 (73990a84). T084 to T088, T093 and T095 are the version 1 freeze criteria (RFC 0002 section 7). + +- [ ] T084 Regenerate `crates/guardian-module-sdk/proto/guardian_module_v1.proto` from the RFC (renumbered version 1) and update every constructor and test that sets field values +- [ ] T085 Registration after #558 in `crates/server/src/services/configure_account.rs`: hook before `metadata.create` and `consume_auth_timestamp`; `default` copies written with the claim; unfinished claim runs `all` plus the stored assignment with no `before`; a lost claim re-runs the pipeline before consuming anything; service tests for all three (FR-009) +- [ ] T086 `network_id` from the account's `network_config` in `HookRequest`, `CommitEvent` and `Gap`; conformance case that a module reads it (FR-039) +- [ ] T087 `AccountView.code_commitment` and `procedure_roots`; `procedure_thresholds` filtered to effective overrides (non-zero, on an exported procedure, not the auth procedure); fixture tests with an inert override (FR-039) +- [ ] T088 `MidenTransaction.reference_block`, optional `expiration_block` (absent when `expiration_delta` is 0) and `new_code_commitment` from the delta's code patch (FR-039) +- [ ] T089 Account views from the single decode in `verify_and_apply_delta` (view fields on `AppliedState`); proposal creation moves to `verify_and_apply_delta` when a module will be called +- [ ] T090 Dry-run `complete = false` when an approval-only instance applies; `params_drift` against `seeded_params`; `GUARDIAN_MODULE_PARAMS_MAX_BYTES`; paginated params history +- [ ] T091 `basic-policy` fixed `client_message` per reason code; a missing projection is a module error, not a `projection_missing` deny; `request_id` in the denial log line +- [ ] T093 `basic-policy` `allowed_code_commitments` with `code_check` (`code_not_allowed`); `HookRequest.submitter_session` from the resolved credential; `proposer_session` stored with the proposal, returned by the `ProposalContext` lookup and sent in `TransactionSubject`, `pending` and `CommitEvent` (FR-039) +- [ ] T094 Filesystem registration: copy `default` instances before the claim, replacing a copy an earlier unclaimed attempt left; an unfinished claim with no assignment history repeats the copy (FR-009) +- [ ] T095 Dry-run check runs `before_transaction_approved`-only instances after the creation instances, with `HookRequest.dry_run`; `complete` derived from the catalog, not the account (FR-058) +- [ ] T096 [M2b] Reassigning a subscribed instance to an account it was unassigned from puts the pair in `resync_required`; extend the counting model to cover unassignment (FR-064) +- [ ] T092 [M2b] `notify` capability: offered only when the notifier runs; a module requiring it is refused unless its entry lists `after_transaction_committed`; `StatefulModule` declares it (FR-066) + +## Phase 19: After merging `main` (RFC revision 26) + +- [X] T097 Guardian execution gated: `before_transaction_approved` runs in `ack_delta_internal::acknowledge_applied`, which `push_delta` and the execution worker share; the requester rides on `ExecutionJob`; refusals end the execution as `GUARDIAN_EXECUTION_MODULE_DENIED` or `GUARDIAN_EXECUTION_MODULE_UNAVAILABLE` (`guardian-shared`, both clients, demo and browser advice) +- [X] T098 `AccountView.signer_schemes` decoded per approver from `approver_schemes`, a single-key signer's from its registration; `auth_scheme` is the signers' common scheme or `mixed`. Field 7 in the prototype proto until T084 renumbers it to the RFC's field 8 +--- + +## Dependencies & Execution Order + +- **Setup (T001 to T003)** before everything. +- **Foundational (T004 to T014)** before any story. T005, T006, T007, T008 are parallel; T009 to T012 build on T004 and T007 to T008; T014 last. +- **US1 (T015 to T018)** first: it proves the pipeline. **US2 (T019, T020)** and **US3 (T021 to T023)** after T017, parallel with each other. **US4 (T024)** after T012. **US6 (T025 to T029)** after US1; T027 after T015. +- **Clients and demo (T030 to T032)** after T013; T031 and T032 after T019 and T022. +- **Gate closure (T033 to T038)** last; T034 and T035 can start as soon as T007 and T008 are done. + +```text +T001 → T002 → T003 → T004 ─┬─ T005 ─┐ + ├─ T006 ─┤ + ├─ T007 ─┼─ T009 → T011 → T012 → T013 → T014 + └─ T008 ─┘ T010 (parallel) +T014 → US1 (T015-T018) ─┬─ US2 (T019-T020) ─┐ + ├─ US3 (T021-T023) ─┼─ T030-T032 → T033-T038 + ├─ US4 (T024) │ + └─ US6 (T025-T029) ─┘ +``` + +## Parallel Examples + +```text +Foundational: T005 catalog.rs | T006 registry.rs | T007 network account_view | T008 projection.rs +US1: T015 basic_policy.rs rules | T016 basic_policy.rs tests (same file: run T016 after T015 if editing together) +US6: T025 serve.rs | T026 grpc_kind.rs +Gates: T034 account_view fixtures | T035 projection fixtures +``` + +## Implementation Strategy + +1. **MVP**: Setup, Foundational, US1. A mandatory cap refuses an over-cap push on `main`. Stop and run the US1 quickstart steps. +2. Add US2 and US3: the same instance filters proposals and controls signers at all three hooks. +3. Add US4 and US6: failure modes and the remote path. +4. Clients and demo, then gate closure. The findings drive RFC revision 20 and the M2a [`tasks.md`](./tasks.md). diff --git a/speckit/features/251-guardian-modules/tasks.md b/speckit/features/251-guardian-modules/tasks.md index 22020e18..7ed2bd9d 100644 --- a/speckit/features/251-guardian-modules/tasks.md +++ b/speckit/features/251-guardian-modules/tasks.md @@ -1,262 +1,274 @@ -# Tasks: Guardian Modules, Phase P0 (Prototype) +# Tasks: Guardian Modules, Milestone M2a (stateless gates) -**Input**: Design documents from `speckit/features/251-guardian-modules/` +**Input**: Design documents from `speckit/features/251-guardian-modules/`; design source [RFC 0002](../../../docs/rfcs/0002-guardian-modules.md) revision 26, section 7 (M2a scope and the protocol version 1 freeze criteria) **Prerequisites**: [plan.md](./plan.md), [spec.md](./spec.md), [research.md](./research.md), [data-model.md](./data-model.md), [contracts/](./contracts/), [quickstart.md](./quickstart.md) -**Scope**: phases 1 to 9 are P0 of the plan: enough of M2a to evaluate the prototype gates G1 to G5 in [research.md](./research.md) and to try the feature end to end. Later phases record the follow-on work done on the prototype since (layered params, storage, review fixes, protocol evolution, disclosure). The remaining M2a, M2b and M2c tasks are generated once the RFC is accepted. +**Starting point**: the prototype on `251-modules-prototype` (draft PR #554, merged with `main` at `73990a84`, RFC revision 26 work at `1274651c`). Its task record is [tasks-p0.md](./tasks-p0.md); tasks below that finish a prototype task cite it as "P0 Tnnn". Built and kept: the pipeline, catalog, registry, `grpc` and in-process kinds, `basic-policy`, the `serve` harness, all three gate hooks (approval in the shared `ack_delta_internal::acknowledge_applied`, so pushes and Guardian executions are both gated), the operator API routes on `/dashboard/modules` with layered params and history on both backends, policy discovery (`GET /policies`, `POST /delta/proposal/check`, rate limit), protocol negotiation and params migration, network-tagged projections, `signer_schemes`, and typed module errors in the server, both Rust crates and the TypeScript base client. -**Branch**: the code lives on `251-modules-prototype` (draft PR #554, based on the RFC branch); `251-guardian-modules-rfc` (PR #544) stays doc-only. +**Not in M2a**: M2b (outbox, `notify`, `pending`, resync: P0 T092, T096) and M2c (`ServerBuilder::from_env`: P0 T068). Also excluded, per RFC section 7 future work: the durable decision log and replay command (P0 T063, T064), the protocol deprecation window until a version 2 exists (P0 T072), and `ModuleInfo.networks` until a second network (P0 T083). -**Excluded from P0**: the operator API (Story 5), `default` scope, evaluation budget, circuit breaker and health probe, request size cap, metrics, M2b (Story 7), M2c (Story 8), TypeScript parity, the execution path (PR #510 not merged). +**Tests**: included. The spec's acceptance scenarios and success criteria are the evidence for each story (constitution principle V), and the RFC freezes protocol version 1 only once its surface is implemented with tests. -**Prototype shortcuts** (not the M2a design): secrets are read from files (`token_file`, `tls.*_file`) instead of the secrets backend; the approval record lives in delta metadata instead of delta columns. Per-account assignments started in the catalog file and moved to the operator API with Phase 10 (T041). - -**Tests**: included, because the spec's acceptance scenarios are the evidence that closes the gates (constitution principle V). +**Code rule**: no spec or task IDs (`FR-`, `SC-`, `US`, `T0nn`) in source comments or test names (AGENTS.md, `speckit-implement`). ## Format: `[ID] [P?] [Story] Description` -- **[P]**: can run in parallel (different files, no dependency on an incomplete task) -- **[Story]**: user story from spec.md (US1, US2, US3, US4, US6) +- **[P]**: can run in parallel (different files, no dependency on an unfinished task) +- **[Story]**: the spec user story (US1 to US6) the task serves +- Paths are relative to the repository root --- ## Phase 1: Setup -**Purpose**: the SDK crate and the server module skeleton. +**Purpose**: put the plan on the M2a footing and fix how the work is delivered. -- [X] T001 Create crate `crates/guardian-module-sdk` (`Cargo.toml` with workspace version, edition, rust-version, license; dependencies `tonic`, `tonic-prost`, `prost`, `async-trait`, `thiserror`, `serde_json`, `tokio`; build dependency `tonic-prost-build`) and add it to `members` and `default-members` in the root `Cargo.toml` -- [X] T002 Copy `speckit/features/251-guardian-modules/contracts/guardian_module_v1.proto` to `crates/guardian-module-sdk/proto/guardian_module_v1.proto` and add `crates/guardian-module-sdk/build.rs` compiling it with client and server stubs, following `crates/server/build.rs` -- [X] T003 Add `guardian-module-sdk` as a path dependency of `guardian-server` in `crates/server/Cargo.toml`, add the `toml` dependency, and create `crates/server/src/modules/mod.rs` declared from `crates/server/src/lib.rs` +- [X] T001 Update `speckit/features/251-guardian-modules/plan.md`: status M2a against RFC revision 26; replace the indicative source tree with the prototype's real paths (`crates/server/src/modules/{catalog,registry,pipeline,request,grpc_kind,admin,store,postgres_store,disclosure,check_limit}.rs`, `crates/server/src/network/miden/module_views.rs`, `crates/server/src/services/ack_delta_internal.rs`, `crates/guardian-module-sdk/src/{basic_policy,serve}.rs`) plus the files this list adds (`breaker.rs`, `budget.rs`, `metrics.rs`, `crates/guardian-module-sdk/src/conformance/`); record the delivery as stacked PRs off `main` per the "Delivery as stacked PRs" section below +- [ ] T002 Create the M2a integration branch `251-modules-m2a` from `main` and carry the prototype onto it by layer (the stack in "Delivery as stacked PRs"), each layer building and testing on its own; close or retarget draft PR #554 to point at the stack in its description --- -## Phase 2: Foundational +## Phase 2: Foundational (protocol version 1 freeze) + +**Purpose**: every field a module receives is fixed here. Modules written against version 1 must not change after this phase, so nothing that adds or renumbers request fields may be left for later stories. -**Purpose**: everything every story needs: the module interface, catalog, request assembly (gates G1 and G2), the pipeline and the errors. +**CRITICAL**: no user story phase starts until this phase is complete. -**Checkpoint**: `cargo test -p guardian-module-sdk` and `cargo test -p guardian-server modules::` pass; a server started without `GUARDIAN_MODULES_CONFIG` behaves exactly as before. +- [ ] T003 Regenerate `crates/guardian-module-sdk/proto/guardian_module_v1.proto` from the RFC's renumbered version 1 block (`docs/rfcs/0002-guardian-modules.md`, section 3, matching `speckit/features/251-guardian-modules/contracts/guardian_module_v1.proto`, including `AccountView.signer_schemes = 8`), and update every constructor and test that sets field values in `crates/server/src/modules/request.rs`, `crates/server/src/network/miden/module_views.rs`, `crates/guardian-module-sdk/src/basic_policy.rs`, `crates/guardian-module-sdk/src/serve.rs` and `crates/guardian-module-sdk/tests/` (P0 T084) +- [ ] T004 [P] Add `network_id` to `HookRequest` (and to `CommitEvent` and `Gap` in the proto only, unused until M2b), filled from the account's `network_config` in `crates/server/src/modules/request.rs`; test that a request for a testnet account names its network (P0 T086) +- [ ] T005 [P] Add `AccountView.code_commitment` and `procedure_roots` in `crates/server/src/network/miden/module_views.rs`, and filter `procedure_thresholds` to effective overrides (non-zero, on a procedure the code exports, not the auth procedure); fixture tests in the same file with an inert override on a non-exported root and on the auth procedure (P0 T087) +- [ ] T006 [P] Add `MidenTransaction.reference_block`, optional `expiration_block` (absent when `expiration_delta` is 0) and `new_code_commitment` (from the delta's code patch) in `projection_from_summary`, `crates/server/src/network/miden/module_views.rs`; tests for each, including a summary with no expiration and one that replaces the account's code (P0 T088) +- [ ] T007 Add `HookRequest.submitter_session` from the resolved credential's auth format: pass it from `ResolvedAccount` through `ack_delta_internal::Submitter` (`crates/server/src/services/ack_delta_internal.rs`), `push_delta_proposal` and `configure_account` into `crates/server/src/modules/request.rs`; on the execution path carry it on `ExecutionJob` (`crates/server/src/services/execute_proposal/worker.rs`, `service.rs`) next to `requester`; tests for a wallet-signed and a session-signed push (P0 T093) +- [ ] T008 Store `proposer_session` with the proposal when it is created (`crates/server/src/delta_object.rs` pending status, `crates/server/src/services/push_delta_proposal.rs`, both storage backends in `crates/server/src/storage/filesystem.rs` and `crates/server/src/storage/postgres.rs`, with a migration under `crates/server/migrations/` if Postgres stores it in a column) and return it from `request::proposal_context` in `crates/server/src/modules/request.rs` into `ProposalContext`; test that a session-created proposal reports it at approval (P0 T093) +- [ ] T009 Replace the prototype's `metadata.modules` approval record with the delta fields of `data-model.md` ("Delta additions"): module trace (`catalog_hash`, `params_version`, `failed_open`), `signed_at` (fixed before the pipeline runs and sent as `accounting_time`), `submitter` and `proposer`, written once at signing in `crates/server/src/services/ack_delta_internal.rs`; add them to `crates/server/src/delta_object.rs`, the Postgres `deltas` table through a new migration in `crates/server/migrations/_guardian_module_delta_fields/`, and the filesystem delta JSON; keep the dashboard delta detail showing the trace (`crates/server/src/services/dashboard_account_delta_detail.rs`); regenerate OpenAPI if the delta wire shape changes +- [ ] T010 [P] Build account views from the single decode the push path already does: carry the view fields on `AppliedState` (`crates/server/src/network/mod.rs`, `crates/server/src/network/miden/mod.rs` `verify_and_apply_delta`) and use them in `crates/server/src/modules/request.rs` instead of a second `Account::from_json`; run proposal creation through `verify_and_apply_delta` when a module will be called (P0 T089) +- [ ] T011 Measure the frozen extraction against real accounts, not only fixtures: add captured devnet accounts (single-key Falcon, single-key ECDSA, 2-of-3 Falcon, mixed-scheme multisig with a procedure override, an account after a code replacement) under `crates/server/src/testing/fixtures/` and assert the full `AccountView` and `MidenTransaction` for each in `crates/server/src/network/miden/module_views.rs` tests +- [ ] T012 Mark protocol version 1 frozen: state it in the proto header of `crates/guardian-module-sdk/proto/guardian_module_v1.proto` and the contract copy, and record the freeze (commit and date) in RFC 0002 section 7 and Appendix C (`docs/rfcs/0002-guardian-modules.md`) -- [X] T004 Define `Module` (`describe`, `validate_params`, `evaluate`, `notify`, `notify_gap` with default no-op), `ModuleFactory`, `ModuleError` and re-exports of the generated `guardian.module.v1` types in `crates/guardian-module-sdk/src/lib.rs`, using `async_trait` so `Arc` is object safe -- [X] T005 [P] Implement catalog parsing and validation for `[[module]]` entries (`id`, `kind`, `endpoint`, `scope` limited to `all` and `assigned`, `hooks`, `timeout_ms`, `on_error`, `enabled`, `params`, `account_params`) and the prototype `[[assignment]]` table (`account_id`, ordered `modules` with `params`), with a catalog hash, in `crates/server/src/modules/catalog.rs`; unit tests for unknown kind, empty hooks, `account_params` outside `scope = "all"`, and an assignment naming an `all` instance -- [X] T006 [P] Implement the kind registry and instance creation (factory per kind, `describe` hook check, `validate_params` on `params` and each merged `account_params` entry, startup failure for an enabled instance) in `crates/server/src/modules/registry.rs` -- [X] T007 [P] Add `AccountView` extraction (gate G1): a `NetworkClient::account_view(&serde_json::Value) -> Result` method in `crates/server/src/network/mod.rs`, implemented in `crates/server/src/network/miden/mod.rs` with new `MidenAccountInspector` readers for the default threshold, the procedure thresholds map and the auth scheme in `crates/server/src/network/miden/account_inspector.rs`, returning an error (never an empty view) for unsupported or undecodable auth state; update test mocks in `crates/server/src/testing/mocks.rs` -- [X] T008 [P] Implement the `TxProjection` builder (gate G2) in `crates/server/src/modules/projection.rs`, reusing helpers from `crates/server/src/delta_summary/projection.rs` and producing every proto field (`nonce_delta`, `expiration_block`, vault changes, output notes with `partial`, `recipient_digest`, `script_root`, `p2id_target`, input notes, storage changes with create, update and remove); record each field it cannot derive in a `G2` section at the end of `speckit/features/251-guardian-modules/research.md` -- [X] T009 Implement `ProposalContext { proposer, metadata }` and a lookup returning `Result, GuardianError>` that separates absence from storage failure, next to `lookup_matching_proposal_payload`, in `crates/server/src/modules/request.rs` -- [X] T010 Make filesystem proposal creation create-if-absent and give `update_delta_proposal` its own replace-if-present implementation in `crates/server/src/storage/filesystem.rs`; tests: a duplicate creation keeps the first proposer, and create, sign, reload keeps the cosigner signature -- [X] T011 Implement `HookRequest` assembly (`submitter`, `before` and `after` views, `TransactionSubject` with projection, raw summary, proposer and `unverified_metadata`, `RegistrationSubject` with `initial_state`; params as RFC 8785 canonical JSON with `account_params` merged), built only when at least one module will be called, in `crates/server/src/modules/request.rs` -- [X] T012 Implement the pipeline in `crates/server/src/modules/pipeline.rs`: resolve the ordered set for a hook (enabled `all` instances in catalog order, then the account's assignment), call each under its `timeout_ms`, stop on deny or on a failure of an `on_error = "deny"` instance, continue past a failure of an `on_error = "allow"` instance with a WARN log, reject a deny whose `reason_code` does not match `[a-z0-9_]{1,64}` as a failure -- [X] T013 Add `GuardianError::ModuleDenied { module, reason_code }` (403, `PERMISSION_DENIED`, code `GUARDIAN_MODULE_DENIED`, non-retryable) and `GuardianError::ModuleUnavailable { module }` (503, `UNAVAILABLE`, code `GUARDIAN_MODULE_UNAVAILABLE`, retryable) with `meta` and user messages in `crates/server/src/error.rs`, following `AccountPaused` -- [X] T014 Load the catalog from `GUARDIAN_MODULES_CONFIG` in `ServerBuilder::build()`, register the first-party kinds, and add `modules: Option>` to `AppState` in `crates/server/src/builder/mod.rs` and `crates/server/src/builder/state.rs`; `None` when the variable is unset +**Checkpoint**: requests carry the complete version 1 surface, measured on real accounts. User story phases can start in parallel. --- -## Phase 3: User Story 1, enforce a mandatory policy (P1) +## Phase 3: User Story 1, enforce a mandatory policy on every account (P1) + +**Goal**: an `all` instance refuses rule-breaking transactions on every path that reaches the ack, and a Guardian without modules is unchanged. + +**Independent Test**: one `basic-policy` instance with a per-transaction cap; transfers below and above it through a proposal push, an offline push without a proposal, and a Guardian execution. + +### Tests for User Story 1 + +- [ ] T013 [P] [US1] Acceptance suite in `crates/server/src/modules/acceptance_tests.rs` (registered in `crates/server/src/modules/mod.rs`): with a real `basic-policy` cap instance, a transfer under the cap is acked; over the cap is refused with `GUARDIAN_MODULE_DENIED` naming instance and reason code and stores no candidate, through a stored proposal and through an offline push; a Guardian execution over the cap ends `GUARDIAN_EXECUTION_MODULE_DENIED` with nothing proved; a proposal labelled as a threshold change that moves funds is judged on its effect +- [ ] T014 [P] [US1] No-modules regression: a test in `crates/server/src/modules/acceptance_tests.rs` that a server built without `GUARDIAN_MODULES_CONFIG` never builds a view or projection (spy on the network client) and acks as before; record the zero-module `push_delta` p99 A/B (filesystem, local) in `speckit/features/251-guardian-modules/research.md` -**Goal**: an `all` instance of `basic-policy` refuses over-cap or off-list transactions on every approval path available on `main`. +### Implementation for User Story 1 -**Independent Test**: quickstart steps "Propose a transfer of 500", "Propose one transaction sending 600 and 600", "Export a 5,000 transfer, sign offline, push directly". +- [ ] T015 [US1] `basic-policy` review fixes in `crates/guardian-module-sdk/src/basic_policy.rs`: a fixed `client_message` per reason code; a missing projection is a module error, not a `projection_missing` deny; tests for both (P0 T091) +- [ ] T016 [US1] Denial log line with the fields of RFC section 2.2 (instance, layer, reason code, `request_id`, account, submitter) in `crates/server/src/modules/pipeline.rs`, with `request_id` defined as in RFC section 3.2; test that a generic denial still logs the full decision (P0 T091) -- [X] T015 [P] [US1] Implement `basic-policy` transaction rules in `crates/server/src/modules/basic_policy.rs`: `max_amount_per_tx` as a map from faucet id to decimal amount over the gross amount sent per faucet across all output notes (inputs do not offset, fee excluded, unlisted faucets uncapped, NFTs ignored), `asset_allowlist`, `recipient_allowlist` denying partial and non-P2ID notes; `validate_params` rejecting unknown params; reason codes `amount_cap_exceeded`, `asset_not_allowed`, `recipient_not_allowed` -- [X] T016 [P] [US1] Unit tests for `basic-policy` in `crates/server/src/modules/basic_policy.rs`: one note under the cap, two 600 notes against a 1,000 cap, receiving 1,000 and sending 1,500, an uncapped faucet, an NFT, a partial note under a recipient allowlist, forged `unverified_metadata` not changing the decision -- [X] T017 [US1] Run the `before_transaction_approved` pipeline in `crates/server/src/services/push_delta.rs` after the pause check and before `state.ack.ack_delta`, with `submitter` from `resolved.signer_commitment`, `before` from the base state and `after` from the applied state, and the proposer from the `ProposalContext` lookup (a lookup error applies `on_error`) -- [X] T018 [US1] Service tests in `crates/server/src/services/push_delta.rs`: a denied push returns `ModuleDenied`, stores no candidate and returns no signature; an allowed push behaves as today; with `modules = None` every existing push test passes unchanged +**Checkpoint**: SC-002 holds on all three approval paths and SC-001 has its baseline. --- -## Phase 4: User Story 2, refusal before anyone signs (P1) +## Phase 4: User Story 2, learn about a refusal before anyone signs (P1) -**Goal**: an instance subscribed to `before_proposal_created` refuses a proposal before it is stored. +**Goal**: refusals at creation store nothing and take no slot, and cosigners can check a proposal without storing it, in every client. -**Independent Test**: quickstart step "Propose a transfer of 5,000": refused, proposal count unchanged. +**Independent Test**: an instance on `before_proposal_created`; an over-cap proposal from each client is refused, nothing is stored and the slot count is unchanged; the dry-run check answers the same. -- [X] T019 [US2] Run the `before_proposal_created` pipeline in `crates/server/src/services/push_delta_proposal.rs` after the proposer signature check and before `submit_delta_proposal`, with `before` the pinned tail and `after` the tail with the delta applied, `accounting_time` not stored -- [X] T020 [US2] Service tests in `crates/server/src/services/push_delta_proposal.rs`: a denied creation stores nothing and leaves the pending-proposal count unchanged; an account one below its limit can still create a valid proposal after a denial; an instance subscribed only to `before_transaction_approved` is not called at creation +### Tests for User Story 2 + +- [ ] T017 [P] [US2] Creation refusal through the Rust layers: `crates/client/src/testing/client_tests.rs` (typed `module_refusal()` on `push_delta_proposal`) and `crates/miden-multisig-client/src/client/proposals.rs` tests (`MultisigError::ModuleDenied` from proposal creation, slot count unchanged on the server mock) +- [ ] T018 [P] [US2] Creation refusal through the TypeScript layers: `packages/guardian-client/src/http.test.ts` (`pushDeltaProposal` rejects with `moduleRefusal()` set) and `packages/miden-multisig-client/src/` proposal creation tests (refusal surfaces unchanged to the caller) + +### Implementation for User Story 2 + +- [ ] T019 [US2] Dry-run check runs `before_transaction_approved`-only instances after the creation instances, each instance once, every request with `HookRequest.dry_run = true`, in `crates/server/src/modules/pipeline.rs` (`plan_dry_run`) and `crates/server/src/services/push_delta_proposal.rs`; tests that an approval-only cap refuses the check (P0 T095) +- [ ] T020 [US2] `complete` derived from the catalog, not the account: `false` whenever any enabled gate instance has `dry_run = false`, in `crates/server/src/modules/pipeline.rs`; test that two accounts, one with the hidden instance assigned and one without, get the same `complete` (P0 T090, T095) +- [ ] T021 [US2] TypeScript multisig `getPolicies` and `checkTransaction` in `packages/miden-multisig-client/src/multisig.ts`, matching the Rust `MultisigClient::get_policies` and `ProposalBuilder::check`, with tests; resolve the dependency first, either a `@openzeppelin/guardian-client` release carrying `checkDeltaProposal` and `getPolicies` or a workspace link, per `packages/miden-multisig-client/package.json` (P0 T078) +- [ ] T022 [US2] Document the dry-run check and policy listing in `crates/miden-multisig-client/README.md`, `packages/miden-multisig-client/README.md`, `crates/client/README.md` and `packages/guardian-client/README.md` + +**Checkpoint**: SC-003 holds and every client exposes the check. --- -## Phase 5: User Story 3, control which keys may sign (P1) +## Phase 5: User Story 3, control which keys may sign and which code may run (P1) + +**Goal**: signer and code rules hold at registration, at signer or code changes, and offline; registration follows the account claim of #558. -**Goal**: one signer rule enforced at registration, proposal creation and approval through the account views. +**Independent Test**: a signer allowlist on all three hooks; register with an unlisted signer, propose adding one, push an offline signer change: each is refused. A code allowlist refuses registration and a code replacement to an unlisted commitment. -**Independent Test**: register with an unlisted signer, propose adding an unlisted signer, push an offline signer change; each is refused. +### Tests for User Story 3 -- [X] T021 [P] [US3] Add `signer_allowlist`, `signer_denylist` (mutually exclusive) and `signer_check` (`added` default, `all`) to `crates/server/src/modules/basic_policy.rs`, evaluated only from `before` and `after`, reason code `signer_not_allowed`; unit tests for added versus all, absent `before` at registration, and an extraction error applying `on_error` -- [X] T022 [US3] Run the `before_account_registered` pipeline in `crates/server/src/services/configure_account.rs` after the credential, signer set and commitment checks and before any write, with `submitter` from the verified credential, `after` from `initial_state`, and `before` from a `pull_state` of the stored state only for existing accounts; no pause or release check is added -- [X] T023 [US3] Service tests in `crates/server/src/services/configure_account.rs`: a denied new registration writes nothing; a denied reconfiguration leaves state, metadata, pause and release unchanged; an allowed reconfiguration of a paused account keeps it paused; an allowed re-onboarding of a released account reactivates it and a denied one leaves it released +- [ ] T023 [P] [US3] Registration races in `crates/server/src/services/configure_account.rs` tests: a losing first configuration is evaluated again against the winner's assignment before it consumes anything; a denied first configuration claims nothing; a denied re-onboarding leaves released state, metadata and assignment unchanged; a mixed-scheme account's registration request carries `signer_schemes` for every signer + +### Implementation for User Story 3 + +- [ ] T024 [US3] Registration per RFC section 2.3 "Registration" in `crates/server/src/services/configure_account.rs`: for a lost claim, re-plan and re-run the pipeline against the winning account (unfinished claim or existing account) before `consume_auth_timestamp`; keep the hook before the claim (P0 T085) +- [ ] T025 [US3] `basic-policy` `allowed_code_commitments` with `code_check` (`changed` or `current`, reason code `code_not_allowed`) in `crates/guardian-module-sdk/src/basic_policy.rs`, reading `AccountView.code_commitment` and `MidenTransaction.new_code_commitment`; params validation and tests at registration and at code replacement (P0 T093) +- [ ] T026 [US3] Document the code allowlist and signer modes in `docs/guides/policy-modules/built-in.md` and its `built-in.toml` + +**Checkpoint**: US3 acceptance scenarios 1 to 5 pass, and the code allowlist is in `basic-policy`. --- -## Phase 6: User Story 4, choose failure behaviour (P1, partial) +## Phase 6: User Story 4, choose and observe failure behaviour (P1) + +**Goal**: a slow or failing module costs at most its budget, an open circuit refuses or proceeds at once, and operators see per-instance health. + +**Independent Test**: one fail-closed and one fail-open instance; stop each module and observe approvals, errors, latency and metrics. + +### Tests for User Story 4 -**Goal**: `on_error` and timeouts behave as specified. Budget, breaker and probe are out of P0. +- [ ] T027 [P] [US4] Failure acceptance in `crates/server/src/modules/pipeline.rs` tests: fail-closed unreachable refuses retryably; fail-open unreachable proceeds and is counted; consecutive failures open the circuit and later requests do not wait the timeout; combined time over the budget times out the remaining instances; a fail-open failure followed by a deny is refused by the second -**Independent Test**: stop a remote module configured fail-closed, then fail-open, and push. +### Implementation for User Story 4 -- [X] T024 [US4] Pipeline tests in `crates/server/src/modules/pipeline.rs` with stub modules: a timeout of a fail-closed module returns `ModuleUnavailable`; a timeout of a fail-open module continues; a fail-open module that errors followed by a denying module is refused by the second; a malformed `reason_code` counts as a failure +- [ ] T028 [US4] Evaluation budget `GUARDIAN_MODULE_EVALUATION_BUDGET_MS` (default 1000) in a new `crates/server/src/modules/budget.rs`, enforced per hook invocation in `crates/server/src/modules/pipeline.rs` (remaining instances count as timed out and their `on_error` applies) +- [ ] T029 [US4] Startup budget checks in `crates/server/src/modules/catalog.rs`: in the prod stage refuse to start when, for any hook, the timeouts of `all` and `default` instances (enabled or not) exceed the budget, or the budget is not below the execution reservation lease; report over-budget stored assignments without blocking +- [ ] T030 [US4] Budget check on operator writes in `crates/server/src/modules/admin.rs`: refuse `PUT /dashboard/accounts/{account_id}/modules` and account-layer writes whose effective set exceeds the budget on any hook (`invalid_input`), with tests +- [ ] T031 [US4] Circuit breaker per instance in a new `crates/server/src/modules/breaker.rs` (consecutive-failure threshold, open, half-open probe), consulted in `crates/server/src/modules/pipeline.rs`; an open circuit applies `on_error` without calling the module +- [ ] T032 [US4] Periodic health probe (`Describe`) per instance on each replica in `crates/server/src/modules/breaker.rs`, closing the circuit on success and detecting protocol or hook changes; wire its task in `crates/server/src/builder/mod.rs` with shutdown +- [ ] T033 [US4] Request size cap `GUARDIAN_MODULE_REQUEST_MAX_BYTES` (default 2 MiB) in `crates/server/src/modules/request.rs`: an oversized request is a module failure without the call +- [ ] T034 [US4] Module metrics in a new `crates/server/src/modules/metrics.rs` with names in `crates/server/src/metrics/names.rs`: `guardian_module_evaluate_duration_seconds{module, outcome}` (`allow`, `deny`, `error`, `skipped`), `guardian_module_fail_open_total{module}`, availability, circuit state, disabled state, configuration drift, catalog fingerprint, orphaned and over-budget assignment counts +- [ ] T035 [US4] Catalog fingerprint in `GET /dashboard/info` (`crates/server/src/services/dashboard_info.rs`) and the `circuit` field in `GET /dashboard/modules` (`crates/server/src/modules/admin.rs`); regenerate `docs/openapi*.json` with `cargo run --features evm --bin gen-openapi -- docs` +- [ ] T036 [US4] Document the budget, size cap and breaker variables in `docs/CONFIGURATION.md` ("Runtime: policy modules") and the metrics in `docs/guides/observability/` + +**Checkpoint**: US4 acceptance scenarios 1 to 7 pass and SC-007 holds. --- -## Phase 7: User Story 6, a remote module without rebuilding (P2) +## Phase 7: User Story 5, tune policy per account without a deploy (P2) -**Goal**: `basic-policy` served over gRPC gives the same decisions as in process. +**Goal**: `default` modules reach new accounts with the claim, operator writes are bounded and auditable, and the operator client covers every route. -**Independent Test**: quickstart section 3. +**Independent Test**: extend a global blocklist and one account's layer through `guardian-operator-client`, read the history, try to remove a mandatory module, and register a new account with a `default` instance. -- [X] T025 [P] [US6] Implement the `serve` harness in `crates/guardian-module-sdk/src/serve.rs`: wraps any `Module` in the generated gRPC service, binds a bearer token per `instance_id` and rejects a mismatch with `PERMISSION_DENIED` -- [X] T026 [P] [US6] Implement the `grpc` kind in `crates/server/src/modules/grpc_kind.rs`: tonic client per instance, bearer token from the instance's `auth` (a file path in P0), `describe` and `validate_params` at startup, transport errors and timeouts as module failures -- [X] T027 [US6] Move the `basic-policy` rule code into `crates/guardian-module-sdk/src/basic_policy.rs` so the server's in-process kind and the remote example share it, keeping `crates/server/src/modules/basic_policy.rs` as the factory -- [X] T028 [US6] Add the runnable example `crates/guardian-module-sdk/examples/basic-policy-serve.rs` taking `--listen` and `--token-file` -- [X] T029 [US6] Conformance tests in `crates/guardian-module-sdk/tests/conformance.rs`: the same requests evaluated in process and through the harness over loopback give identical decisions; evaluating a request twice leaves module state unchanged; a request authenticated for one instance and naming another is rejected +### Tests for User Story 5 ---- +- [ ] T037 [P] [US5] `default` copy tests in `crates/server/src/services/configure_account.rs`: the copy carries the evaluated params and is written with the claim on Postgres; on the filesystem it replaces an earlier unclaimed attempt's copy; an unfinished claim with no assignment history repeats it, one an operator emptied does not +- [ ] T038 [P] [US5] Operator client tests in `packages/guardian-operator-client/src/` for every module route, including permission errors for `modules:disable` holders -## Phase 8: Clients and demo (US1, US2, US3) +### Implementation for User Story 5 -**Goal**: module refusals are typed in Rust and visible in `examples/demo`. +- [ ] T039 [US5] Write `default` instances into the assignment together with the claim in `crates/server/src/services/configure_account.rs` and `crates/server/src/modules/postgres_store.rs` (same transaction as `metadata.create`), with the evaluated params from the same snapshot (P0 T085) +- [ ] T040 [US5] Filesystem registration copy in `crates/server/src/modules/store.rs`: written before the claim as one atomic replace, replacing a copy an earlier unclaimed attempt left; an unfinished claim with no assignment history repeats it (P0 T094) +- [ ] T041 [US5] `params_drift` against `seeded_params`, `GUARDIAN_MODULE_PARAMS_MAX_BYTES` on every params write, and paginated history (`?before=&limit=`) in `crates/server/src/modules/admin.rs`, `store.rs` and `postgres_store.rs` (P0 T090) +- [ ] T042 [US5] `declared` (stored flag the catalog no longer declares) and `orphaned` (assignment naming a removed instance) in the views of `crates/server/src/modules/admin.rs`; orphaned entries are skipped at evaluation and reported, active again when the instance returns +- [ ] T043 [US5] Migrate account layers and assignments that a module normalizes when validating params, at startup and before enabling, with a compare-and-set against the read value, in `crates/server/src/modules/registry.rs` and both stores (P0 T073) +- [ ] T044 [US5] Module routes in `packages/guardian-operator-client/src/` (list, account modules read and replace, global params, account layer set and delete, history, enable, disable) with types matching `speckit/features/251-guardian-modules/contracts/operator-modules-api.md`, and its README +- [ ] T045 [US5] OpenAPI entries for the `/dashboard/modules` and account module routes (`utoipa` annotations in `crates/server/src/api/dashboard_modules.rs`), regenerated into `docs/openapi-dashboard.json` +- [ ] T046 [US5] Smoke the operator routes through `examples/operator-smoke-web` with the `smoke-test-operator-dashboard` skill, and document the routes and permissions in `docs/DASHBOARD.md` ("Policy modules") -- [X] T030 [P] [US1] Add typed accessors for `GUARDIAN_MODULE_DENIED` (`module`, `reason_code`, not retryable) and `GUARDIAN_MODULE_UNAVAILABLE` (`module`, retryable) to `ClientError` in `crates/client/src/error.rs`, with tests parsing both from gRPC status details -- [X] T031 [US2] Surface both errors from proposal creation, push and registration in `crates/miden-multisig-client` without wrapping them into generic errors; test that a denied proposal creation exposes `module` and `reason_code` -- [X] T032 [US3] Print module refusals (instance, reason code, retryable or not) in `examples/demo` where proposal creation, execution and account registration report errors +**Checkpoint**: US5 acceptance scenarios 1 to 16 pass and SC-009, SC-012 hold. --- -## Phase 9: Gate closure +## Phase 8: User Story 6, plug in a third-party module without rebuilding (P2) + +**Goal**: an operator runs the official image with a remote module that authenticates per instance through the secrets backend, and module authors have an SDK, a conformance suite and an example. + +**Independent Test**: run `examples/policy-module` as a service, configure it as a remote instance with credentials from the secrets backend, and run the conformance suite against it and against the in-process kind. + +### Tests for User Story 6 -**Purpose**: turn the prototype into findings for RFC revision 20 and the M2a task list. +- [ ] T047 [P] [US6] Conformance suite: turn the prototype's `crates/guardian-module-sdk/tests/conformance.rs` into a reusable suite in `crates/guardian-module-sdk/src/conformance/` (behind a `conformance` feature) that any module author can run, covering identical decisions in process and over gRPC, `evaluate` purity (the same request repeated leaves module state unchanged), params validation, a request at the size cap, and instance-id isolation between two instances on one service; run it for `basic-policy` from `crates/guardian-module-sdk/tests/conformance.rs` -- [ ] T033 Run the quickstart walk-through (sections 1 to 3) against a local server with the filesystem backend and record each step's result in `speckit/features/251-guardian-modules/research.md` under each gate -- [X] T034 [P] Gate G1: test `account_view` on single-key, multisig and guardian-multisig fixture accounts and on an unsupported layout in `crates/server/src/network/miden/mod.rs`; record decode cost per call and the decision on `procedure_thresholds` in `research.md` -- [X] T035 [P] Gate G2: test the projection builder on one fixture per transaction kind (P2ID, P2IDE, consume notes, add and remove signer, change threshold, update procedure threshold, switch guardian) in `crates/server/src/modules/projection.rs`; record fields kept and dropped in `research.md` -- [X] T036 Gate G3: measure p50 and p99 of `push_delta` and `push_delta_proposal` with no catalog, one in-process `basic-policy`, and one remote `basic-policy` over loopback, including the share spent building views and projections, with a script in `crates/guardian-module-sdk/examples/latency_ab.rs` or the existing loadgen in `crates/server/bench/loadgen`; record results against SC-001 and SC-006 in `research.md`; done 2026-10-16 with the loadgen `state-push` scenario and `crates/server/examples/bench_server.rs`, results in `research.md` (G3 end to end); follow-up fixes: account view cache by state commitment and a single proposal read in `push_delta` -- [X] T037 Gate G4 and G5: record module author findings (trait shape, typed request helpers such as `added_signers()`, branching needed per hook) and pipeline placement on `main` versus `acknowledge_delta` in PR #510 in `research.md` -- [X] T038 Mark gates G1 to G5 closed or accepted in `research.md`, list the RFC changes they require for revision 20, and update the Status line of `plan.md` +### Implementation for User Story 6 + +- [ ] T048 [US6] Secret references through the secrets backend: replace `auth.token_file` and `tls.*_file` in `crates/server/src/modules/catalog.rs` and `crates/server/src/modules/grpc_kind.rs` with secret references resolved when the instance is created, following `docs/runbooks/secrets.md`; resolve `$secret` in in-process params at creation and pass them only to the in-process module, never in a request; keep rejection in remote params, account layers and the operator API; update `speckit/features/251-guardian-modules/contracts/catalog-config.md` +- [ ] T049 [US6] `examples/policy-module/`: `basic-policy` as a standalone gRPC service through the `serve` harness, with `Cargo.toml`, `README.md` (run, TLS, per-instance token), a `Dockerfile`, and a matching remote catalog entry in `docs/guides/policy-modules/remote.toml` +- [ ] T050 [US6] Publishable `guardian-module-sdk`: crates.io metadata in `crates/guardian-module-sdk/Cargo.toml`, `crates/guardian-module-sdk/README.md` (module author quick start), and the crate added to the release order of the `release-guardian-sdk-packages` skill +- [ ] T051 [US6] Remote module author guide in `docs/guides/policy-modules/custom.md` and `remote.md`: protocol version 1, request fields, `reason_code` rules, `client_message`, `dry_run`, conformance suite, credentials; written so SC-011 holds without reading server code + +**Checkpoint**: SC-005 and SC-011 hold; US6 acceptance scenarios 1 to 5 pass. --- -## Phase 10: Layered parameters (RFC revision 21) - -**Goal**: operator-managed params from the dashboard API: global params seeded from the catalog, account layers that only add restrictions, assignments, history and version. The catalog keeps instance registration only. - -**Storage** (research D12): module state lives in its own tables, `module_instances`, `module_account_params` and `module_params_history`, on Postgres through a migration (plus the one-row `module_state_version` lock) and on the filesystem backend as one atomically replaced file, `/modules/module_state.json` (`GUARDIAN_MODULES_STATE` overrides the directory). - -- [X] T039 [US5] Add `recipient_denylist` and `deny_unknown_recipients` to `crates/guardian-module-sdk/src/basic_policy.rs`, reason code `recipient_blocked`, with tests -- [X] T040 [US5] Implement the params store (global params with the seed rule, account layers, assignments, history, version, file persistence) in `crates/server/src/modules/params.rs`, with tests -- [X] T041 [US5] Remove `account_params` and the `[[assignment]]` table from `crates/server/src/modules/catalog.rs`; mark params holding secret references as file-managed -- [X] T042 [US5] Evaluate an `all` instance's account layer as a second pass in `crates/server/src/modules/pipeline.rs`; `layer` on `GuardianError::ModuleDenied` and in `meta`; validate stored global params at startup; tests for extension, no loosening and runtime global changes -- [X] T043 [US5] Implement the operator operations (validation, history, audit kinds `modules.params.global`, `modules.params.account`, `modules.assignment`) in `crates/server/src/modules/admin.rs`, `GuardianError::ModuleNotFound`, permission `policies:write_global`, with tests -- [X] T044 [US5] Add the routes in `crates/server/src/api/dashboard_modules.rs` and `crates/server/src/builder/handle.rs`, with a router test for permission gating, global writes, drift and history -- [X] T045 [US5] Carry `layer` through `ModuleRefusal` in `crates/client` and `MultisigError::ModuleDenied` -- [X] T046 [US5] Add the operator CLI `crates/server/examples/modules_admin.rs` (keygen, login, call) -- [X] T048 [US5] Replace the single-file params store with the `ModuleStore` trait over the three tables in `crates/server/src/modules/store.rs` (filesystem: one file per table), make evaluation read the account's rows with one query and cache global params per replica by params version, and fail closed with a storage error when the tables are unreadable -- [X] T049 [US5] Add the migration `crates/server/migrations/2026-10-15-000001_guardian_modules` and `PgModuleStore` in `crates/server/src/modules/postgres_store.rs` (each write and its history row in one transaction), wired through `CoordinationHandles`, with a Postgres test across two replicas -- [X] T050 [US5] Runtime enable and disable: `operator_can_disable` in the catalog, `set_enabled` on both stores (recorded in the history so the version moves), the pipeline and startup reading the stored flag, `POST /dashboard/modules/{id}/enable` (`policies:write`, re-runs the startup checks) and `/disable` (`policies:write` or `modules:disable` through a new any-of authz mode; `GUARDIAN_MODULE_NOT_DISABLEABLE` when the catalog forbids it), audit kinds `modules.enable` and `modules.disable`, with tests on every layer -- [X] T047 [US5] Walk the blocklist scenario against a running server with the CLI (quickstart section 4); confirmed live on 2026-10-15 (Postgres backend, devnet demo): global cap, a stricter account layer refusing with `layer: account`, a looser account layer still refused by the global rule, layer removal, and the params history - -## Phase 11: Review fixes (fleet review 2026-10-15) - -- [X] T051 Decode the projection and `raw_tx_summary` (Miden binary) from exactly the summary the Guardian signs: `NetworkClient::module_transaction` takes the bare summary, the proposal path passes `tx_summary`, the decoder refuses wrappers; `decode_transaction_summary` prefers a top-level `data` for the dashboard metadata -- [X] T052 Move the params version to the one-row `module_state_version` lock in the migration and `crates/server/src/modules/postgres_store.rs`; read the previous assignment inside the write transaction; Postgres test for concurrent replacements -- [X] T053 Check the effective params (stored global params, else the catalog seed) at startup and before enable, and seed new instances only after every instance passed its checks, in `crates/server/src/modules/pipeline.rs`, `registry.rs` and `admin.rs` -- [X] T054 Resolve a request's modules once with one version read (`ModulePipeline::plan`, `Plan::run`) and use it in the three services -- [X] T055 Record `catalog_hash` and `params_version` on the signed delta (`DeltaMetadata.modules`) -- [X] T056 Report the runtime flag for assigned modules in the account view -- [X] T057 Persist the filesystem module tables as one file, synced and renamed -- [X] T058 Single-key accounts: a view without signers and `default_threshold` from the state, the signer and scheme from the registered auth configuration -- [X] T059 TLS for remote modules: `grpc://` is TLS (system roots or `tls.ca_file`, optional client certificate), plain text only through `grpc+insecure://` to a loopback host, prod stage refuses plain text and requires `auth` -- [X] T060 Add the four `GUARDIAN_MODULE_*` codes to `packages/guardian-client/src/error-codes.ts` - -## Phase 12: Replayable approvals - -- [X] T061 Module builds (`name version` from `describe`) in the startup log and in `GET /dashboard/modules` -- [X] T062 Evaluation trace on the signed delta (`DeltaMetadata.modules`): `catalog_hash`, `params_version`, `failed_open` -- [ ] T063 Replay command: rebuild a delta's request at its `params_version`, re-run the modules and diff against the trace; adds what it needs: configuration snapshots with module builds, the request hash (ordered proto maps), `accounting_time`, `proposer` (M2a) -- [ ] T064 Decision log for denials and proposal-time evaluations, same trace shape (M2a) - -## Phase 13: In-process custom kinds (M2c, prototyped early) - -- [X] T065 `ServerBuilder::with_module_kind` registering a kind the catalog can name; `Registry::register` refuses a taken name, including `basic-policy` and `grpc`; example `crates/server/examples/custom_module_server.rs` with `note-policy` shared with the gRPC example -- [X] T066 Isolate every module call (`describe`, `validate_params`, `evaluate`) on its own task: a panic is a module failure and `on_error` applies, the timeout holds when a module blocks, a factory panic fails startup with an error -- [X] T067 Policy modules guide `docs/guides/policy-modules/` (built-in, remote, custom over gRPC and in process) with catalog templates loaded by a test; `CONFIGURATION.md` and `DASHBOARD.md` reference entries -- [ ] T068 `ServerBuilder::from_env` so a custom build does not copy `main.rs` (M2c) - -## Phase 14: Protocol evolution (RFC revision 22) - -- [X] T069 Protocol: `DescribeRequest` with the Guardian's protocol range and capabilities, `ModuleInfo.required_capabilities`, `Decision.effect`, `ParamsVerdict.normalized_params` in `crates/guardian-module-sdk/proto/guardian_module_v1.proto`; `Module::describe` takes the request; `capability` constants and `ParamsVerdict::normalized` in the SDK -- [X] T070 SDK source compatibility: `ModuleInstanceConfig`, `ModuleTls`, `ClientIdentity` and `ModuleError` `#[non_exhaustive]`, with constructors -- [X] T071 Guardian: supported protocol range (`MIN_PROTOCOL_VERSION..=PROTOCOL_VERSION`, warning below current), required-capability check, `Decision.effect` with unknown effects as failures, normalized params stored on operator writes and migrated at startup and before enable with a history entry by `module: `, with tests on every path -- [ ] T072 Deprecation window when protocol version 2 exists: build the older request shape for previous-version modules and export `guardian_module_protocol_deprecated{module}` (M2a once a second version exists) -- [ ] T073 Migrate account layers and assignments that a module normalizes (today they migrate when next written) (M2a) - -## Phase 15: Policy discovery and disclosure (RFC revision 22) - -- [X] T074 Catalog fields `disclosure`, `description` (required unless `none`, at most 500 characters), `client_reason` and `dry_run` in `crates/server/src/modules/catalog.rs`, shown in the operator view -- [X] T075 Generic denials (`GuardianError::ModuleDeniedGeneric`, `meta = { reason_code: "policy_denied" }`) and `Decision.client_message` (cleaned, at most 256 characters, forwarded only under full reasons) in the server; `module` and `layer` optional and `client_message` carried in `guardian-client` and `miden-multisig-client` -- [X] T076 Policy summary `GET /policies` and `GetPolicies`: `ModulePipeline::disclosed` in `crates/server/src/modules/disclosure.rs`, `services::get_policies`, HTTP and gRPC handlers, OpenAPI regenerated -- [X] T077 Dry-run check `POST /delta/proposal/check` and `CheckDeltaProposal`: proposal creation in a dry-run mode (`services::check_proposal`), `ModulePipeline::plan_dry_run` with the per-account and per-signer limiter (`GUARDIAN_MODULE_CHECK_RATE_PER_MIN`), logging; `guardian-client` (Rust and TypeScript) methods; Rust multisig `get_policies` and `check_transaction` -- [ ] T078 TypeScript multisig `getPolicies` and `checkTransaction` (after a `@openzeppelin/guardian-client` release), and TypeScript parsing of generic denials and `client_message` - - -## Phase 16: Review fixes (concurrency and throttling) - -- [X] T079 Consistent policy snapshot: `ModulePipeline::snapshot` reads the version, the global rows and the account's rows, rechecks the version and retries, used by `plan` and `disclosed`; acceptance test reproducing a global change and a layer removal racing an evaluation -- [X] T080 Conditional migration writes: `ModuleStore::set_global_if` on both backends (filesystem under the write lock, Postgres under the row lock with the version untouched on a miss), used by startup migration and enable; acceptance test reproducing an operator write racing a migration; Postgres test -- [X] T081 Dry-run limiter independent of the catalog (`crates/server/src/modules/check_limit.rs`), installed at startup, applied to every check before reconstruction; spec FR-041 made conditional on full reasons; FR-028 and FR-029 - -## Phase 17: Network-tagged projections (RFC revision 22) - -- [X] T082 `TransactionProjection`, `AccountStateProjection` (`oneof network`, Miden only) and `RawTransaction` (named `encoding`) replace the Miden-only fields in `TransactionSubject`, `PendingTransaction`, `CommitEvent` and `RegistrationSubject`, with new field numbers and the old ones reserved; `TxProjection` and `AccountProjection` renamed `MidenTransaction` and `MidenAccountState`; SDK accessors (`subject.miden()`), `basic-policy`, `note-policy`, tests and the guide updated -- [ ] T083 `ModuleInfo.networks` and the Guardian's check that a mandatory instance can judge the account's network, when a second network gets a variant - -## Phase 18: Review of revision 23 (RFC revision 24) - -Not started. The prototype branch must first merge `main` (#523, #552, #558). T084 to T088, T093 and T095 are the version 1 freeze criteria (RFC 0002 section 7). - -- [ ] T084 Regenerate `crates/guardian-module-sdk/proto/guardian_module_v1.proto` from the RFC (renumbered version 1) and update every constructor and test that sets field values -- [ ] T085 Registration after #558 in `crates/server/src/services/configure_account.rs`: hook before `metadata.create` and `consume_auth_timestamp`; `default` copies written with the claim; unfinished claim runs `all` plus the stored assignment with no `before`; a lost claim re-runs the pipeline before consuming anything; service tests for all three (FR-009) -- [ ] T086 `network_id` from the account's `network_config` in `HookRequest`, `CommitEvent` and `Gap`; conformance case that a module reads it (FR-039) -- [ ] T087 `AccountView.code_commitment` and `procedure_roots`; `procedure_thresholds` filtered to effective overrides (non-zero, on an exported procedure, not the auth procedure); fixture tests with an inert override (FR-039) -- [ ] T088 `MidenTransaction.reference_block`, optional `expiration_block` (absent when `expiration_delta` is 0) and `new_code_commitment` from the delta's code patch (FR-039) -- [ ] T089 Account views from the single decode in `verify_and_apply_delta` (view fields on `AppliedState`); proposal creation moves to `verify_and_apply_delta` when a module will be called -- [ ] T090 Dry-run `complete = false` when an approval-only instance applies; `params_drift` against `seeded_params`; `GUARDIAN_MODULE_PARAMS_MAX_BYTES`; paginated params history -- [ ] T091 `basic-policy` fixed `client_message` per reason code; a missing projection is a module error, not a `projection_missing` deny; `request_id` in the denial log line -- [ ] T093 `basic-policy` `allowed_code_commitments` with `code_check` (`code_not_allowed`); `HookRequest.submitter_session` from the resolved credential; `proposer_session` stored with the proposal, returned by the `ProposalContext` lookup and sent in `TransactionSubject`, `pending` and `CommitEvent` (FR-039) -- [ ] T094 Filesystem registration: copy `default` instances before the claim, replacing a copy an earlier unclaimed attempt left; an unfinished claim with no assignment history repeats the copy (FR-009) -- [ ] T095 Dry-run check runs `before_transaction_approved`-only instances after the creation instances, with `HookRequest.dry_run`; `complete` derived from the catalog, not the account (FR-058) -- [ ] T096 [M2b] Reassigning a subscribed instance to an account it was unassigned from puts the pair in `resync_required`; extend the counting model to cover unassignment (FR-064) -- [ ] T092 [M2b] `notify` capability: offered only when the notifier runs; a module requiring it is refused unless its entry lists `after_transaction_committed`; `StatefulModule` declares it (FR-066) +## Phase 9: Polish and cross-cutting + +**Purpose**: documentation, verification and release readiness across stories. + +- [ ] T052 [P] `docs/TROUBLESHOOTING.md`: `GUARDIAN_MODULE_DENIED`, `GUARDIAN_MODULE_UNAVAILABLE`, `GUARDIAN_MODULE_NOT_FOUND`, `GUARDIAN_MODULE_NOT_DISABLEABLE` with their `meta`, and the denial log fields +- [ ] T053 [P] Break-glass runbook `docs/runbooks/policy-modules.md` (RFC section 4.2): disabling an instance, deploy-only changes, circuit and budget symptoms; link it from `docs/runbooks/` and `CLAUDE.md`'s lookup table +- [ ] T054 [P] Trust boundary and data protection in `docs/CONCEPTS.md`: what external modules receive (full transaction details, proposals that never execute, proposer descriptions), and the operator and vendor guidance of RFC invariant 5 +- [ ] T055 [P] Protocol spec coverage: module error codes and `meta` on proposal creation, push and registration, `GET /policies` and `POST /delta/proposal/check` in `spec/api.md`, and the gate points in the push, proposal and registration processes of `spec/processes.md` +- [ ] T056 [P] Client READMEs for module errors and `moduleRefusal()` / `module_refusal()`: `crates/client/README.md`, `packages/guardian-client/README.md`, `crates/miden-multisig-client/README.md`, `packages/miden-multisig-client/README.md` +- [ ] T057 Rust and TypeScript parity fixture: one shared JSON fixture of module error bodies under `packages/guardian-client/src/` (or the repo's existing shared fixture location) driving both `crates/client` and `packages/guardian-client` tests, so SC-010 is checked by the same cases +- [ ] T058 End-to-end smokes with a catalog: `smoke-test-rust-multisig-sdk` and `smoke-test-ts-multisig-sdk` skills, refusal at creation, push and registration, and `examples/demo` and `examples/web` with and without a catalog (quickstart section 5) +- [ ] T059 Quickstart walk-through against a local node with the filesystem backend and the latency A/B (zero, one in-process, one remote module), results in `speckit/features/251-guardian-modules/research.md` (P0 T033; SC-001, SC-006) +- [ ] T060 SC-004 run: enable `basic-policy` on all accounts with the official image and the guides only, timed, gaps fixed in `docs/guides/policy-modules/` +- [ ] T061 Re-check the TLA+ models whose fingerprints the modules work moved (`verify-auth-replay`, `verify-candidate-queue`, `verify-client-sync`, `verify-guardian-switch`, `verify-module-counting`, `verify-multisig-push-gate`, `verify-proposal-lifecycle` under `.agents/skills/`) with each `check.sh`, then `--accept-drift` once the model still mirrors the code +- [ ] T062 Validation matrix of `speckit/features/251-guardian-modules/quickstart.md` section 5 (M2a rows) run end to end, including `cargo test -p guardian-server --features postgres` for module stores and proposal storage, and `gen-openapi --check` + --- -## Dependencies & Execution Order +## Dependencies and Execution Order -- **Setup (T001 to T003)** before everything. -- **Foundational (T004 to T014)** before any story. T005, T006, T007, T008 are parallel; T009 to T012 build on T004 and T007 to T008; T014 last. -- **US1 (T015 to T018)** first: it proves the pipeline. **US2 (T019, T020)** and **US3 (T021 to T023)** after T017, parallel with each other. **US4 (T024)** after T012. **US6 (T025 to T029)** after US1; T027 after T015. -- **Clients and demo (T030 to T032)** after T013; T031 and T032 after T019 and T022. -- **Gate closure (T033 to T038)** last; T034 and T035 can start as soon as T007 and T008 are done. +### Phase dependencies -```text -T001 → T002 → T003 → T004 ─┬─ T005 ─┐ - ├─ T006 ─┤ - ├─ T007 ─┼─ T009 → T011 → T012 → T013 → T014 - └─ T008 ─┘ T010 (parallel) -T014 → US1 (T015-T018) ─┬─ US2 (T019-T020) ─┐ - ├─ US3 (T021-T023) ─┼─ T030-T032 → T033-T038 - ├─ US4 (T024) │ - └─ US6 (T025-T029) ─┘ -``` +- **Setup (T001, T002)** first. +- **Foundational (T003 to T012)** blocks every story. T003 first (it renumbers the proto); T004, T005, T006 and T010 then run in parallel; T007 and T008 after T003; T009 after T007 and T008 (it stores `submitter` and `proposer`); T011 after T005 and T006; T012 last. +- **Stories** start after T012 and are independent of each other, with these exceptions: T030 (budget on writes) needs T028; T039 and T040 (`default` copy) touch `configure_account.rs` after T024, so run US3 before US5 or coordinate the file; T021 needs the `guardian-client` dependency decision. +- **Polish (T052 to T062)** after the stories it documents; T061 and T062 last. + +### User story dependencies + +- **US1 (P1)**: needs only Foundational. MVP. +- **US2 (P1)**: needs Foundational; T021 depends on a TypeScript client release or link. +- **US3 (P1)**: needs Foundational (T005, T006 for the code allowlist). +- **US4 (P1)**: needs Foundational; should land before any production enablement, since without the breaker and budget a down fail-closed module costs a full timeout on every request. +- **US5 (P2)**: needs Foundational; shares `configure_account.rs` with US3. +- **US6 (P2)**: needs Foundational (T003 for the conformance suite's request shapes). + +### Within each story + +Tests first and failing, then implementation, then docs for that story. + +--- ## Parallel Examples ```text -Foundational: T005 catalog.rs | T006 registry.rs | T007 network account_view | T008 projection.rs -US1: T015 basic_policy.rs rules | T016 basic_policy.rs tests (same file: run T016 after T015 if editing together) -US6: T025 serve.rs | T026 grpc_kind.rs -Gates: T034 account_view fixtures | T035 projection fixtures +# Foundational, after T003: +T004 network_id (modules/request.rs) +T005 code fields in views (network/miden/module_views.rs, view half) +T006 projection fields (network/miden/module_views.rs, projection half; coordinate with T005) +T010 single decode (network/mod.rs, network/miden/mod.rs) + +# Stories, after T012, one developer each: +US4 T028 to T036 (modules/budget.rs, breaker.rs, metrics.rs) +US6 T047 to T051 (guardian-module-sdk, examples/policy-module) +US2 T019 to T022 (pipeline dry run, TypeScript multisig) + +# Polish docs, any time after their story: +T052, T053, T054, T055, T056 ``` +--- + ## Implementation Strategy -1. **MVP**: Setup, Foundational, US1. A mandatory cap refuses an over-cap push on `main`. Stop and run the US1 quickstart steps. -2. Add US2 and US3: the same instance filters proposals and controls signers at all three hooks. -3. Add US4 and US6: failure modes and the remote path. -4. Clients and demo, then gate closure. The findings drive RFC revision 20 and the M2a `tasks.md`. +### MVP + +Foundational, then US1: the frozen protocol and a mandatory policy enforced on every approval path. Before enabling modules in production, also US4: the budget and breaker are what keep a failing fail-closed module from slowing every approval. + +### Incremental delivery + +1. Foundational: version 1 frozen. +2. US1 and US4: enforceable and operable. +3. US3: signer and code control, registration per #558. +4. US2: creation-time refusal and the check in every client. +5. US5: operator tuning with the operator client. +6. US6: remote modules through the secrets backend, conformance suite, example, published SDK. +7. Polish: docs, smokes, A/B, TLA+ re-check, validation matrix. + +### Delivery as stacked PRs + +The prototype is one 13,000-line draft (#554). M2a ships as a stack of PRs off `main`, each building and testing on its own, the way the PR #510 review stack was layered by path: + +1. **Module SDK and protocol**: `crates/guardian-module-sdk` (proto version 1, `Module`, `serve`, `basic-policy`, conformance), Phase 2 proto tasks, T047, T050. +2. **Server core**: `crates/server/src/modules/` catalog, registry, pipeline, request assembly, stores and the `2026-10-15` migration, `network/miden/module_views.rs`, budget, breaker, size cap, metrics (US4). +3. **Hooks**: `ack_delta_internal.rs`, `push_delta_proposal.rs`, `configure_account.rs`, the execution worker, delta fields (T009), US1 and US3. +4. **Operator surface**: `/dashboard/modules` routes, OpenAPI, `packages/guardian-operator-client` (US5). +5. **Client surfaces**: module errors and discovery in `crates/client`, `crates/miden-multisig-client`, `packages/guardian-client`, `packages/miden-multisig-client`, examples (US2). +6. **Docs**: guides, runbook, concepts, spec, troubleshooting (Polish). From ca7ea183c5291bae9d2134ce79baeb4a55059767 Mon Sep 17 00:00:00 2001 From: Zeljko Date: Mon, 9 Nov 2026 09:03:54 +0100 Subject: [PATCH 006/105] docs(speckit): record the M2a layer stack as built (#251) Five layers, each building and testing on its own, with the rule that a TypeScript vocabulary held to Rust by a drift test lands with its source. --- speckit/features/251-guardian-modules/plan.md | 10 +++++----- speckit/features/251-guardian-modules/tasks.md | 11 ++--------- 2 files changed, 7 insertions(+), 14 deletions(-) diff --git a/speckit/features/251-guardian-modules/plan.md b/speckit/features/251-guardian-modules/plan.md index 18ec0749..e15f47e9 100644 --- a/speckit/features/251-guardian-modules/plan.md +++ b/speckit/features/251-guardian-modules/plan.md @@ -141,12 +141,12 @@ The prototype (#554) is one draft of about 13,000 lines and is not merged as it | Layer | Branch | Content | |---|---|---| | 1. Module SDK | `251-m2a-sdk` | `crates/guardian-module-sdk` (protocol, `Module`, `serve`, `basic-policy`, conformance) and the workspace entry | -| 2. Server core | `251-m2a-server-core` | `crates/server/src/modules/`, `network/miden/module_views.rs`, the modules migration, module errors in `error.rs`, permissions and audit kinds, the operator routes, `AppState` wiring, with no hook calling the pipeline yet | -| 3. Hooks | `251-m2a-hooks` | The three gate hooks (`ack_delta_internal.rs`, `push_delta_proposal.rs`, `configure_account.rs`), the execution worker and the `guardian-shared` failure codes, policy discovery routes, delta summary trace, OpenAPI | -| 4. Clients | `251-m2a-clients` | `crates/client`, `crates/miden-multisig-client`, `packages/guardian-client`, `packages/miden-multisig-client`, examples and the qualification driver | -| 5. Docs | `251-m2a-docs` | `docs/guides/policy-modules/`, `docs/`, `spec/`, the `verify-module-counting` skill | +| 2. Server core | `251-m2a-server-core` | `crates/server/src/modules/`, `network/miden/module_views.rs`, the modules migration, the `GUARDIAN_MODULE_*` errors, permissions and audit kinds, the `/dashboard/modules` routes, `AppState` wiring and the `modules` field in test initializers; the guide's example catalogs (`docs/guides/policy-modules/*.toml`, parsed by the registry tests) and the TypeScript error-code vocabulary (`packages/guardian-client/src/error-codes.ts`, held to `error.rs` by a drift test); OpenAPI regenerated. No hook calls the pipeline | +| 3. Hooks | `251-m2a-hooks` | The three gate hooks (`ack_delta_internal.rs`, `push_delta_proposal.rs`, `configure_account.rs`), the execution worker, the discovery routes on both transports, the `guardian-shared` failure codes with the TypeScript execution vocabulary and the browser example that switches over it, and the compile fixes the non-`Copy` failure code needs (qualification driver, demo, one multisig test); OpenAPI regenerated | +| 4. Clients | `251-m2a-clients` | `crates/client`, `crates/miden-multisig-client`, `packages/guardian-client` (`http.ts` and its types), `packages/miden-multisig-client` | +| 5. Docs | `251-m2a-docs` | `docs/` (guides, configuration, dashboard, troubleshooting, RFC), `spec/`, the speckit feature, the `verify-module-counting` skill | -`251-modules-m2a` is the integration branch at the top of the stack; M2a tasks land on the layer they belong to. The operator client (US5) joins layer 2 or its own PR when it is built. +Each layer builds the workspace with `--all-targets`, passes `gen-openapi --check`, the server, client and multisig test suites, and the TypeScript client tests; the top of the stack equals the prototype tree. Rule found while splitting: a TypeScript vocabulary held to a Rust source by a drift test lands in the same layer as that source. `251-modules-m2a` is the integration branch at the top of the stack; M2a tasks land on the layer they belong to. The operator client (US5) joins layer 2 or its own PR when it is built. ## Decisions made during planning diff --git a/speckit/features/251-guardian-modules/tasks.md b/speckit/features/251-guardian-modules/tasks.md index 7ed2bd9d..18f83dbe 100644 --- a/speckit/features/251-guardian-modules/tasks.md +++ b/speckit/features/251-guardian-modules/tasks.md @@ -24,7 +24,7 @@ **Purpose**: put the plan on the M2a footing and fix how the work is delivered. - [X] T001 Update `speckit/features/251-guardian-modules/plan.md`: status M2a against RFC revision 26; replace the indicative source tree with the prototype's real paths (`crates/server/src/modules/{catalog,registry,pipeline,request,grpc_kind,admin,store,postgres_store,disclosure,check_limit}.rs`, `crates/server/src/network/miden/module_views.rs`, `crates/server/src/services/ack_delta_internal.rs`, `crates/guardian-module-sdk/src/{basic_policy,serve}.rs`) plus the files this list adds (`breaker.rs`, `budget.rs`, `metrics.rs`, `crates/guardian-module-sdk/src/conformance/`); record the delivery as stacked PRs off `main` per the "Delivery as stacked PRs" section below -- [ ] T002 Create the M2a integration branch `251-modules-m2a` from `main` and carry the prototype onto it by layer (the stack in "Delivery as stacked PRs"), each layer building and testing on its own; close or retarget draft PR #554 to point at the stack in its description +- [ ] T002 Create the M2a integration branch `251-modules-m2a` from `main` and carry the prototype onto it by layer (the stack in "Delivery as stacked PRs"), each layer building and testing on its own; close or retarget draft PR #554 to point at the stack in its description. Local stack built 2026-11-09 (layers `251-m2a-sdk` to `251-m2a-docs`, top equal to the prototype tree); remaining: push the branches, open the layer PRs, update #554 --- @@ -264,11 +264,4 @@ Foundational, then US1: the frozen protocol and a mandatory policy enforced on e ### Delivery as stacked PRs -The prototype is one 13,000-line draft (#554). M2a ships as a stack of PRs off `main`, each building and testing on its own, the way the PR #510 review stack was layered by path: - -1. **Module SDK and protocol**: `crates/guardian-module-sdk` (proto version 1, `Module`, `serve`, `basic-policy`, conformance), Phase 2 proto tasks, T047, T050. -2. **Server core**: `crates/server/src/modules/` catalog, registry, pipeline, request assembly, stores and the `2026-10-15` migration, `network/miden/module_views.rs`, budget, breaker, size cap, metrics (US4). -3. **Hooks**: `ack_delta_internal.rs`, `push_delta_proposal.rs`, `configure_account.rs`, the execution worker, delta fields (T009), US1 and US3. -4. **Operator surface**: `/dashboard/modules` routes, OpenAPI, `packages/guardian-operator-client` (US5). -5. **Client surfaces**: module errors and discovery in `crates/client`, `crates/miden-multisig-client`, `packages/guardian-client`, `packages/miden-multisig-client`, examples (US2). -6. **Docs**: guides, runbook, concepts, spec, troubleshooting (Polish). +The prototype is one 13,000-line draft (#554). M2a ships as a stack of five PRs off `main`, each building and testing on its own, the way the PR #510 review stack was layered by path. The layers, their branches and what each contains are in [plan.md](./plan.md), "M2a delivery": module SDK, server core, hooks, clients, docs. New M2a work goes to the layer it belongs to: Phase 2 proto tasks and US6 to the SDK layer; US4 and the operator routes of US5 to server core; US1, US3 and the server half of US2 to hooks; the client halves of US2 and US5 to clients; Polish docs to docs. From b8bcc9ab1e8ed8e6cf759b37d4e52e67365f917d Mon Sep 17 00:00:00 2001 From: Zeljko Date: Mon, 9 Nov 2026 09:39:14 +0100 Subject: [PATCH 007/105] feat(modules): protocol version 1 layout and its new request fields (#251) guardian_module_v1.proto now follows the RFC's renumbered version 1. The Guardian fills what it adds: HookRequest.network_id from the account's registered network (an EVM account is refused rather than mislabelled), submitter_session for a request signed by a delegated session key on pushes, proposal creation and Guardian executions, AccountView.code_commitment and procedure_roots, procedure_thresholds limited to overrides that apply on chain (non-zero, on an exported procedure, not the auth procedure), and MidenTransaction.reference_block, expiration_block only when the transaction expires, and new_code_commitment when it replaces the code. --- .../proto/guardian_module_v1.proto | 130 ++++++++--------- crates/server/src/metadata/network.rs | 11 ++ crates/server/src/modules/request.rs | 58 ++++++++ .../server/src/network/miden/module_views.rs | 132 ++++++++++++++++-- .../server/src/services/ack_delta_internal.rs | 14 +- .../server/src/services/configure_account.rs | 2 + .../src/services/execute_proposal/service.rs | 3 +- .../src/services/execute_proposal/worker.rs | 5 +- crates/server/src/services/push_delta.rs | 80 ++++++++++- .../src/services/push_delta_proposal.rs | 5 +- .../contracts/guardian_module_v1.proto | 2 +- .../features/251-guardian-modules/tasks.md | 10 +- 12 files changed, 361 insertions(+), 91 deletions(-) diff --git a/crates/guardian-module-sdk/proto/guardian_module_v1.proto b/crates/guardian-module-sdk/proto/guardian_module_v1.proto index b6ccb0fa..42f1f4bf 100644 --- a/crates/guardian-module-sdk/proto/guardian_module_v1.proto +++ b/crates/guardian-module-sdk/proto/guardian_module_v1.proto @@ -1,3 +1,7 @@ +// guardian.module.v1, extracted from docs/rfcs/0002-guardian-modules.md section 3 (revision 26). +// The proto in RFC section 3 is authoritative; regenerate this file when it changes. +// Protocol version 1 is frozen when M2a ships. + syntax = "proto3"; package guardian.module.v1; @@ -22,7 +26,7 @@ enum Hook { message DescribeRequest { uint32 guardian_protocol_version = 1; // the newest protocol version the Guardian speaks uint32 guardian_min_protocol_version = 2; // the oldest it still accepts (section 3.5) - repeated string guardian_capabilities = 3; // optional features this Guardian provides + repeated string guardian_capabilities = 3; // optional features this Guardian provides (section 3.5) } message ModuleInfo { string name = 1; @@ -31,76 +35,67 @@ message ModuleInfo { repeated Hook hooks = 4; repeated string required_capabilities = 5; // startup fails if the Guardian lacks one } -message ValidateParamsRequest { bytes params = 1; string instance_id = 2; } // params: UTF-8 JSON +message ValidateParamsRequest { + string instance_id = 1; + bytes params = 2; // UTF-8 JSON +} message ParamsVerdict { bool ok = 1; string message = 2; - bytes normalized_params = 3; // UTF-8 JSON; empty: store the params as sent. Lets a module migrate params it still accepts to its current shape + bytes normalized_params = 3; // UTF-8 JSON; empty: store the params as sent (section 3.5) } message NotifyAck {} -message Gap { - string account_id = 1; - string network = 2; - google.protobuf.Timestamp dropped_before = 3; // restart position: events for the account committed before this and not acknowledged may be missing - string instance_id = 4; - uint64 resume_from_nonce = 5; // first nonce delivered after the gap; the module's watermark becomes resume_from_nonce - 1 (section 3.3) -} - message HookRequest { - string request_id = 1; + string request_id = 1; // one per hook invocation, shared by every module and layer called in it (section 3.1) Hook hook = 2; - string network = 3; // "miden" - string account_id = 4; - bytes params = 5; // UTF-8 JSON, params of the layer being evaluated (global, account layer, or the account's own for default/assigned) - string instance_id = 6; // catalog id of the instance being called - google.protobuf.Timestamp accounting_time = 7; // recorded as signed_at if this transaction is signed (section 3.4); at before_proposal_created, the evaluation time, never recorded - string submitter = 8; // signer commitment that authenticated this request; verified (section 3.2) + bool dry_run = 3; // a policy check: nothing is stored or signed whatever the decision (section 2.7) + string network = 4; // network family: "miden" + string network_id = 5; // the account's network within the family: "mainnet", "testnet", "devnet", "cedar" or "local" (section 3.1) + string account_id = 6; + string instance_id = 7; // catalog id of the instance being called + bytes params = 8; // UTF-8 JSON, params of the layer being evaluated (global, account layer, or the account's own for default/assigned) + google.protobuf.Timestamp accounting_time = 9; // recorded as signed_at if this transaction is signed (section 3.4); at before_proposal_created and in a dry run, the evaluation time, never recorded + string submitter = 10; // signer commitment that authenticated this request; verified (section 3.2) + bool submitter_session = 11; // the request was authenticated by a session key the submitter delegated (section 3.2) + optional AccountView before = 12; // the account as the Guardian holds it; absent for a first configuration (section 3.2) + AccountView after = 13; // the account as it will be if every module allows (section 3.2) oneof subject { // hook-specific detail only - TransactionSubject transaction = 10; - RegistrationSubject registration = 11; + TransactionSubject transaction = 14; + RegistrationSubject registration = 15; } - optional AccountView before = 12; // the account as the Guardian holds it; absent for a new registration (section 3.2) - AccountView after = 13; // the account as it will be if every module allows (section 3.2) } message AccountView { string commitment = 1; - string auth_scheme = 2; // the signers' common scheme, "falcon" or "ecdsa", or "mixed" + string auth_scheme = 2; // the scheme every signer shares, "falcon" or "ecdsa", or "mixed" (section 3.2) repeated string signer_commitments = 3; - reserved 4; // was threshold; renamed default_threshold - reserved "threshold"; - optional uint32 default_threshold = 5; // absent for single-key accounts - map procedure_thresholds = 6; // procedure root -> threshold overriding the default; empty when none - map signer_schemes = 7; // signer commitment -> "falcon" or "ecdsa"; one entry per signer + optional uint32 default_threshold = 4; // absent for single-key accounts + map procedure_thresholds = 5; // procedure root -> threshold; only overrides the account's code can apply (section 3.2) + string code_commitment = 6; // commitment of the account's code + repeated string procedure_roots = 7; // roots of the procedures the account's code exports + map signer_schemes = 8; // signer commitment -> "falcon" or "ecdsa"; one entry per signer (section 3.2) } message TransactionSubject { - reserved 1, 2; // were prev_commitment and new_commitment; now before.commitment and after.commitment - reserved "prev_commitment", "new_commitment"; - reserved 3, 4; // were the Miden-only projection and raw_tx_summary; now the network-tagged fields below - reserved "raw_tx_summary"; - TransactionProjection projection = 10; // the contract modules should rely on, per network - RawTransaction raw = 11; // the network's own encoding; UNSTABLE across that network's protocol bumps - reserved 5; // was unverified_hint; replaced by unverified_metadata - reserved "unverified_hint"; - repeated PendingTransaction pending = 6; // signed for this account, not yet acknowledged by this module (section 3.4) - reserved 7; // was submitter; now HookRequest.submitter - reserved "submitter"; - string proposer = 8; // signer commitment that created the matching proposal; verified; empty when there is none (section 3.2) - bytes unverified_metadata = 9; // UTF-8 JSON, proposer-asserted proposal metadata; never authoritative; UNSTABLE across SDK releases (section 3.2) + TransactionProjection projection = 1; // the contract modules should rely on, per network + RawTransaction raw = 2; // the network's own encoding; UNSTABLE across that network's protocol bumps + repeated PendingTransaction pending = 3; // signed for this account, not yet acknowledged by this module (section 3.4) + string proposer = 4; // signer commitment that created the matching proposal; verified; empty when there is none (section 3.2) + bool proposer_session = 5; // the proposer created it through a delegated session key (section 3.2) + bytes unverified_metadata = 6; // UTF-8 JSON, proposer-asserted proposal metadata; never authoritative; UNSTABLE across SDK releases (section 3.2) } message PendingTransaction { string new_commitment = 1; // = event_id once committed - reserved 2; // was the Miden-only projection - TransactionProjection projection = 9; + TransactionProjection projection = 2; google.protobuf.Timestamp signed_at = 3; // the accounting clock (section 3.4) PendingState state = 4; uint64 nonce = 5; // account nonce after this transaction; compared with the module's watermark optional google.protobuf.Timestamp committed_at = 6; // set when state = committed string submitter = 7; // as in HookRequest at the ack that signed this transaction; verified (section 3.2) string proposer = 8; // as in TransactionSubject at that ack; empty when there was no matching proposal + bool proposer_session = 9; // as in TransactionSubject at that ack } enum PendingState { PENDING_STATE_UNSPECIFIED = 0; @@ -109,14 +104,11 @@ enum PendingState { } message RegistrationSubject { - reserved 1 to 4, 6; // auth_scheme, signer_commitments, threshold and initial_state_commitment moved to HookRequest.after; submitter to HookRequest.submitter - reserved "auth_scheme", "signer_commitments", "threshold", "initial_state_commitment", "submitter"; - reserved 5; // was the Miden-only initial_state - AccountStateProjection initial_state = 7; // the account about to be accepted, per network + AccountStateProjection initial_state = 1; // the account about to be accepted, per network } enum Effect { - EFFECT_UNSPECIFIED = 0; // a module that predates `effect`: `allow` decides + EFFECT_UNSPECIFIED = 0; // a module that does not set `effect`: `allow` decides EFFECT_ALLOW = 1; EFFECT_DENY = 2; } @@ -126,7 +118,7 @@ message Decision { string reason_code = 2; // required on a deny; ignored on an allow string message = 3; // logged, never forwarded to clients Effect effect = 4; // wins over allow when set; a value the Guardian does not know is a module failure - string client_message = 5; // optional, plain text, at most 256 characters; forwarded only where the instance allows it + string client_message = 5; // optional, plain text, at most 256 characters; forwarded only where the instance allows it (section 2.7) } // A transaction as its network describes it. One variant per network; a module reads the @@ -151,14 +143,14 @@ message RawTransaction { } message MidenTransaction { - reserved 1; // was version; protocol_version covers the projection - reserved "version"; // the JSON name cannot be reused either (matters for the proto3 JSON mapping) - int64 nonce_delta = 2; - uint32 expiration_block = 3; + int64 nonce_delta = 1; + uint32 reference_block = 2; // the block the transaction was executed against + optional uint32 expiration_block = 3; // absent when the transaction sets no expiration (section 3.1) repeated VaultChange vault_changes = 4; repeated OutputNote output_notes = 5; repeated InputNote input_notes = 6; repeated StorageChange storage_changes = 7; + optional string new_code_commitment = 8; // set when the transaction replaces the account's code (section 3.1) } message MidenAccountState { @@ -207,16 +199,26 @@ message StorageSlot { message CommitEvent { string event_id = 1; // = new_commitment; stable across redelivery - string account_id = 2; - string prev_commitment = 3; - string new_commitment = 4; - reserved 5; // was the Miden-only projection - TransactionProjection projection = 13; - google.protobuf.Timestamp committed_at = 6; - string network = 7; // "miden", as in HookRequest + string instance_id = 2; + string account_id = 3; + string network = 4; // as in HookRequest + string network_id = 5; // as in HookRequest + string prev_commitment = 6; + string new_commitment = 7; uint64 nonce = 8; // account nonce after this transaction; the delivery watermark (section 3.3) - google.protobuf.Timestamp signed_at = 9; // the accounting clock, identical to the value the module saw in pending (section 3.4) - string instance_id = 10; - string submitter = 11; // as in HookRequest at the ack that signed this transaction; verified (section 3.2) - string proposer = 12; // as in TransactionSubject at that ack; empty when there was no matching proposal (section 3.2) + TransactionProjection projection = 9; + google.protobuf.Timestamp committed_at = 10; + google.protobuf.Timestamp signed_at = 11; // the accounting clock, identical to the value the module saw in pending (section 3.4) + string submitter = 12; // as in HookRequest at the ack that signed this transaction; verified (section 3.2) + string proposer = 13; // as in TransactionSubject at that ack; empty when there was no matching proposal (section 3.2) + bool proposer_session = 14; // as in TransactionSubject at that ack +} + +message Gap { + string instance_id = 1; + string account_id = 2; + string network = 3; // as in HookRequest + string network_id = 4; // as in HookRequest + google.protobuf.Timestamp dropped_before = 5; // restart position: events for the account committed before this and not acknowledged may be missing + uint64 resume_from_nonce = 6; // first nonce delivered after the gap; the module's watermark becomes resume_from_nonce - 1 (section 3.3) } diff --git a/crates/server/src/metadata/network.rs b/crates/server/src/metadata/network.rs index 509f0d7e..634eae37 100644 --- a/crates/server/src/metadata/network.rs +++ b/crates/server/src/metadata/network.rs @@ -27,6 +27,17 @@ pub enum MidenNetworkType { } impl MidenNetworkType { + /// The network's name as stored and as policy modules receive it in `network_id`. + pub fn as_str(self) -> &'static str { + match self { + MidenNetworkType::Local => "local", + MidenNetworkType::Devnet => "devnet", + MidenNetworkType::Testnet => "testnet", + MidenNetworkType::Cedar => "cedar", + MidenNetworkType::Mainnet => "mainnet", + } + } + /// Bech32 human-readable prefix of Cedar addresses. Today the same string /// as the protocol's mainnet prefix, kept separate so Cedar stays on `mm` /// if mainnet moves. diff --git a/crates/server/src/modules/request.rs b/crates/server/src/modules/request.rs index 725e0589..023080d2 100644 --- a/crates/server/src/modules/request.rs +++ b/crates/server/src/modules/request.rs @@ -6,6 +6,7 @@ use guardian_module_sdk::proto::hook_request; use guardian_module_sdk::{AccountView, HookRequest, RegistrationSubject, TransactionSubject}; use crate::delta_object::{DeltaObject, DeltaStatus}; +use crate::metadata::NetworkConfig; use crate::metadata::auth::Auth; use crate::network::NetworkClient; @@ -137,10 +138,21 @@ fn view( Ok(view) } +/// The account's network within its family, from its registered configuration; modules are not +/// offered EVM accounts. +fn network_id(config: &NetworkConfig) -> Result<&'static str, String> { + match config { + NetworkConfig::Miden { network_type } => Ok(network_type.as_str()), + NetworkConfig::Evm { .. } => Err("policy modules do not evaluate EVM accounts".into()), + } +} + pub struct TransactionInput<'a> { pub account_id: &'a str, pub submitter: &'a str, + pub submitter_session: bool, pub auth: &'a Auth, + pub network_config: &'a NetworkConfig, pub before: StateRef<'a>, pub after: StateRef<'a>, pub tx_summary: &'a serde_json::Value, @@ -163,9 +175,11 @@ pub fn transaction_request( }; Ok(HookRequest { network: "miden".into(), + network_id: network_id(input.network_config)?.into(), account_id: input.account_id.to_string(), accounting_time: Some(timestamp(input.accounting_time)), submitter: input.submitter.to_string(), + submitter_session: input.submitter_session, before: Some(view(network, views, input.before, input.auth)?), after: Some(view(network, views, input.after, input.auth)?), subject: Some(hook_request::Subject::Transaction(TransactionSubject { @@ -187,7 +201,9 @@ pub fn transaction_request( pub struct RegistrationInput<'a> { pub account_id: &'a str, pub submitter: &'a str, + pub submitter_session: bool, pub auth: &'a Auth, + pub network_config: &'a NetworkConfig, pub stored_state: Option>, pub initial_state: StateRef<'a>, pub accounting_time: DateTime, @@ -200,9 +216,11 @@ pub fn registration_request( ) -> Result { Ok(HookRequest { network: "miden".into(), + network_id: network_id(input.network_config)?.into(), account_id: input.account_id.to_string(), accounting_time: Some(timestamp(input.accounting_time)), submitter: input.submitter.to_string(), + submitter_session: input.submitter_session, before: input .stored_state .map(|state| view(network, views, state, input.auth)) @@ -320,6 +338,46 @@ mod tests { assert_eq!(single.auth_scheme, "ecdsa"); } + #[test] + fn requests_name_the_accounts_network_and_refuse_evm_accounts() { + use crate::metadata::network::MidenNetworkType; + let auth = Auth::MidenFalconRpo { + cosigner_commitments: vec!["0xa".into()], + }; + let network = MockNetworkClient::new() + .with_module_views(multisig_view(&[("0xa", "falcon")]), Default::default()); + let request = |config: &NetworkConfig| { + registration_request( + &network, + &ViewCache::default(), + RegistrationInput { + account_id: "0xacc", + submitter: "0xa", + submitter_session: false, + auth: &auth, + network_config: config, + stored_state: None, + initial_state: state("0xc1"), + accounting_time: Utc::now(), + }, + ) + }; + let testnet = request(&NetworkConfig::Miden { + network_type: MidenNetworkType::Testnet, + }) + .unwrap(); + assert_eq!(testnet.network, "miden"); + assert_eq!(testnet.network_id, "testnet"); + assert!( + request(&NetworkConfig::Evm { + chain_id: 1, + account_address: "0x1".into(), + multisig_validator_address: "0x2".into(), + }) + .is_err() + ); + } + #[test] fn a_failed_decode_is_not_cached() { let network = MockNetworkClient::new(); diff --git a/crates/server/src/network/miden/module_views.rs b/crates/server/src/network/miden/module_views.rs index 1c6bcdea..80f5fba1 100644 --- a/crates/server/src/network/miden/module_views.rs +++ b/crates/server/src/network/miden/module_views.rs @@ -23,19 +23,23 @@ fn felt_u32(felt: miden_protocol::Felt) -> Result { u32::try_from(felt.as_canonical_u64()).map_err(|_| "value does not fit in u32".into()) } -/// Signers with their schemes, default threshold and procedure thresholds of a multisig account. -/// An account without the multisig component is single-key: its view carries no signers and no -/// `default_threshold`, and the caller fills the signer and its scheme from the account's +/// Code, signers with their schemes, default threshold and effective procedure thresholds of an +/// account. An account without the multisig component is single-key: its view carries no signers +/// and no `default_threshold`, and the caller fills the signer and its scheme from the account's /// verified auth configuration. A signer whose scheme entry is missing or names no supported /// scheme is an error, never a signer without a scheme. pub fn account_view(state_json: &serde_json::Value) -> Result { let account = Account::from_json(state_json)?; let storage = account.storage(); + let code = account.code(); + let procedure_roots: Vec = code.procedure_roots().map(|root| word_hex(&root)).collect(); let Ok(threshold_config) = storage.get_item(AuthGuardedMultisig::threshold_config_slot()) else { return Ok(AccountView { commitment: word_hex(&account.to_commitment()), + code_commitment: word_hex(&code.commitment()), + procedure_roots, ..Default::default() }); }; @@ -79,13 +83,22 @@ pub fn account_view(state_json: &serde_json::Value) -> Result>()?; + // On chain an override applies only to a non-auth procedure the code exports, and zero means + // the default; other entries change nothing, so a threshold floor must not see them. + let auth_procedure = code.procedure_roots().next(); let procedure_thresholds = match storage .get(AuthGuardedMultisig::procedure_thresholds_slot()) .map(|slot| slot.content()) { Some(StorageSlotContent::Map(map)) => map .entries() - .map(|(root, value)| Ok((word_hex(&Word::from(*root)), felt_u32(value[0])?))) + .map(|(root, value)| Ok((Word::from(*root), felt_u32(value[0])?))) + .filter(|entry| { + entry.as_ref().map_or(true, |(root, threshold)| { + *threshold != 0 && code.has_procedure(*root) && Some(*root) != auth_procedure + }) + }) + .map(|entry| entry.map(|(root, threshold)| (word_hex(&root), threshold))) .collect::>()?, Some(_) => return Err("procedure thresholds slot is not a map".into()), None => Default::default(), @@ -97,6 +110,8 @@ pub fn account_view(state_json: &serde_json::Value) -> Result Result { +/// `None` for a transaction without an expiration (delta 0), so "never expires" is not confused +/// with "expires at the reference block". +fn expiration_block(block_number: u32, expiration_delta: u16) -> Result, String> { + if expiration_delta == 0 { + return Ok(None); + } block_number .checked_add(u32::from(expiration_delta)) + .map(Some) .ok_or_else(|| format!("expiration overflows: block {block_number} + {expiration_delta}")) } @@ -236,10 +257,15 @@ fn projection_from_summary(summary: &TransactionSummary) -> Result Vec { + AccountCode::mock().procedure_roots().collect() + } + #[test] - fn view_reads_signers_default_and_procedure_thresholds() { - let root = Word::from([7u32, 7, 7, 7]); + fn view_reads_signers_default_and_only_effective_procedure_thresholds() { + let roots = mock_roots(); + assert!(roots.len() >= 3, "mock code: auth plus two procedures"); + let (auth, effective, zeroed) = (roots[0], roots[1], roots[2]); + let unexported = Word::from([7u32, 7, 7, 7]); let view = account_view(&multisig( 2, 3, 3, - vec![(root, Word::from([3u32, 0, 0, 0]))], + vec![ + (effective, Word::from([3u32, 0, 0, 0])), + (zeroed, Word::from([0u32, 0, 0, 0])), + (auth, Word::from([1u32, 0, 0, 0])), + (unexported, Word::from([3u32, 0, 0, 0])), + ], )) .unwrap(); assert_eq!(view.signer_commitments.len(), 3); assert_eq!(view.default_threshold, Some(2)); - assert_eq!(view.procedure_thresholds.get(&word_hex(&root)), Some(&3)); + assert_eq!( + view.procedure_thresholds, + [(word_hex(&effective), 3)].into(), + "zero, auth and unexported overrides change nothing on chain" + ); + assert_eq!( + view.procedure_roots, + roots.iter().map(word_hex).collect::>() + ); + assert_eq!( + view.code_commitment, + word_hex(&AccountCode::mock().commitment()) + ); assert_eq!(view.signer_schemes.len(), 3); assert!( view.signer_schemes @@ -414,6 +464,11 @@ mod tests { assert!(!view.commitment.is_empty()); assert!(view.signer_commitments.is_empty()); assert_eq!(view.default_threshold, None); + assert_eq!( + view.code_commitment, + word_hex(&AccountCode::mock().commitment()) + ); + assert_eq!(view.procedure_roots.len(), mock_roots().len()); } #[test] @@ -453,10 +508,67 @@ mod tests { #[test] fn expiration_overflow_is_an_error() { - assert_eq!(expiration_block(10, 5), Ok(15)); + assert_eq!(expiration_block(10, 5), Ok(Some(15))); + assert_eq!(expiration_block(u32::MAX, 0), Ok(None)); assert!(expiration_block(u32::MAX, 1).is_err()); } + fn summary(code: Option, expiration_delta: u16) -> TransactionSummary { + use miden_protocol::account::{ + AccountCodePatch, AccountDelta, AccountStoragePatch, AccountVaultDelta, + }; + use miden_protocol::transaction::{InputNotes, RawOutputNotes}; + let delta = AccountDelta::new( + AccountId::dummy( + [3u8; 15], + AccountIdVersion::Version1, + AccountType::Private, + miden_protocol::account::AssetCallbackFlag::Disabled, + ), + AccountStoragePatch::default(), + AccountVaultDelta::default(), + AccountCodePatch::new(code), + miden_protocol::Felt::new_unchecked(1), + ) + .unwrap(); + TransactionSummary::new( + delta, + InputNotes::new(vec![]).unwrap(), + RawOutputNotes::new(vec![]).unwrap(), + miden_protocol::block::BlockNumber::from(100u32), + Word::default(), + expiration_delta, + Default::default(), + ) + } + + #[test] + fn projection_carries_the_reference_block_and_an_expiration_only_when_one_is_set() { + let expiring = projection_from_summary(&summary(None, 20)).unwrap(); + assert_eq!(expiring.reference_block, 100); + assert_eq!(expiring.expiration_block, Some(120)); + let open = projection_from_summary(&summary(None, 0)).unwrap(); + assert_eq!(open.reference_block, 100); + assert_eq!(open.expiration_block, None); + } + + #[test] + fn a_code_replacement_names_the_new_code_commitment() { + let code = AccountCode::mock(); + assert_eq!( + projection_from_summary(&summary(Some(code.clone()), 0)) + .unwrap() + .new_code_commitment, + Some(word_hex(&code.commitment())) + ); + assert_eq!( + projection_from_summary(&summary(None, 0)) + .unwrap() + .new_code_commitment, + None + ); + } + #[test] #[ignore = "timing report for the prototype gates; run with --ignored --nocapture"] fn view_and_projection_decode_cost() { diff --git a/crates/server/src/services/ack_delta_internal.rs b/crates/server/src/services/ack_delta_internal.rs index 74f2ff52..108a8bc8 100644 --- a/crates/server/src/services/ack_delta_internal.rs +++ b/crates/server/src/services/ack_delta_internal.rs @@ -6,7 +6,7 @@ use guardian_shared::SignatureScheme; use crate::delta_object::DeltaObject; use crate::delta_summary::ModuleApproval; use crate::error::Result; -use crate::metadata::auth::Auth; +use crate::metadata::AccountMetadata; use crate::modules::HookName; use crate::modules::request::{self, StateRef, TransactionInput}; use crate::network::AppliedState; @@ -20,11 +20,13 @@ pub(crate) struct AcknowledgedDelta { pub matched_proposal: bool, } -/// The cosigner a Guardian acknowledgment is evaluated for: the one calling `push_delta`, or the -/// one whose request started a Guardian execution. Policy modules receive it as the submitter. +/// The cosigner a Guardian acknowledgment is evaluated for, the one calling `push_delta` or the +/// one whose request started a Guardian execution, and the account it acts on. pub(crate) struct Submitter<'a> { pub commitment: &'a str, - pub auth: &'a Auth, + /// Whether the request was signed by a delegated session key rather than the wallet. + pub session: bool, + pub account: &'a AccountMetadata, } /// Verifies `delta` against the state it builds on, runs the policy modules, derives its @@ -147,7 +149,9 @@ async fn approve( TransactionInput { account_id: &delta.account_id, submitter: submitter.commitment, - auth: submitter.auth, + submitter_session: submitter.session, + auth: &submitter.account.auth, + network_config: &submitter.account.network_config, before: base, after: StateRef { commitment: &applied.commitment, diff --git a/crates/server/src/services/configure_account.rs b/crates/server/src/services/configure_account.rs index a8090ac4..2a36df29 100644 --- a/crates/server/src/services/configure_account.rs +++ b/crates/server/src/services/configure_account.rs @@ -264,7 +264,9 @@ pub async fn configure_account( RegistrationInput { account_id: ¶ms.account_id, submitter: &signer_commitment, + submitter_session: false, auth: ¶ms.auth, + network_config: ¶ms.network_config, stored_state: stored_state.map(|stored| StateRef { commitment: &stored.commitment, json: &stored.state_json, diff --git a/crates/server/src/services/execute_proposal/service.rs b/crates/server/src/services/execute_proposal/service.rs index fe80e58a..e3b6b8a2 100644 --- a/crates/server/src/services/execute_proposal/service.rs +++ b/crates/server/src/services/execute_proposal/service.rs @@ -11,7 +11,7 @@ use crate::config::execution::{ExecutionConfig, ExecutionUnavailable}; use crate::coordination::{ExecutionLeases, InMemoryExecutionLeases, release_quietly}; use crate::delta_object::DeltaStatus; use crate::error::{GuardianError, LocalExecutionReason, Result}; -use crate::metadata::auth::Credentials; +use crate::metadata::auth::{Credentials, RequestAuthFormat}; use crate::services::account_status::ensure_account_active_metadata; use crate::services::execution_status::ExecutionEnvelope; use crate::services::resolve_account_allowing_session; @@ -315,6 +315,7 @@ pub async fn request_execution( base_commitment: proposal.prev_commitment, scheme: resolved.metadata.auth.guardian_scheme(), requester: resolved.signer_commitment.clone(), + requester_session: credentials.auth_format() == RequestAuthFormat::Session, fence, lease, elector, diff --git a/crates/server/src/services/execute_proposal/worker.rs b/crates/server/src/services/execute_proposal/worker.rs index 3d45f3bb..6278f785 100644 --- a/crates/server/src/services/execute_proposal/worker.rs +++ b/crates/server/src/services/execute_proposal/worker.rs @@ -37,6 +37,8 @@ pub(super) struct ExecutionJob { /// modules evaluate the acknowledgement for. A repeated request joins the running attempt, /// which keeps it. pub requester: String, + /// Whether that request was signed by a delegated session key. + pub requester_session: bool, pub fence: LeaseFence, pub lease: Lease, pub elector: Arc, @@ -473,7 +475,8 @@ async fn acknowledge( &delta, Submitter { commitment: &job.requester, - auth: ®istered.auth, + session: job.requester_session, + account: ®istered, }, ) .await diff --git a/crates/server/src/services/push_delta.rs b/crates/server/src/services/push_delta.rs index 71939648..215fe2f4 100644 --- a/crates/server/src/services/push_delta.rs +++ b/crates/server/src/services/push_delta.rs @@ -216,7 +216,8 @@ pub async fn push_delta(state: &AppState, params: PushDeltaParams) -> Result (Result, MockStorageBackend) { + push_on_multisig_gated_by( + request_signer, + approvers, + approver_schemes, + threshold, + procedure_overrides, + lookup, + None, + ) + .await + } + + /// As `push_on_multisig_signed_by`, with `modules` evaluating the push. + async fn push_on_multisig_gated_by( + request_signer: RequestSigner, + approvers: &[String], + approver_schemes: &[guardian_shared::SignatureScheme], + threshold: u32, + procedure_overrides: &[(miden_protocol::Word, u32)], + lookup: ProposalLookup, + modules: Option>, ) -> (Result, MockStorageBackend) { use crate::delta_object::DeltaStatus; use crate::state_object::StateObject; @@ -1539,7 +1562,19 @@ mod tests { .with_apply_delta(Ok(( serde_json::json!({"new_state": true}), "0xnew_commitment".to_string(), - ))); + ))) + .with_module_views( + guardian_module_sdk::AccountView { + signer_commitments: approvers.to_vec(), + signer_schemes: approvers + .iter() + .map(|approver| (approver.clone(), "falcon".to_string())) + .collect(), + default_threshold: Some(threshold), + ..Default::default() + }, + guardian_module_sdk::MidenTransaction::default(), + ); let metadata = MockMetadataStore::new().with_get(Ok(Some(AccountMetadata { account_id: account_id.clone(), auth: Auth::MidenFalconRpo { @@ -1553,11 +1588,12 @@ mod tests { paused_reason: None, released_at: None, }))); - let state = create_test_app_state_with_mocks( + let mut state = create_test_app_state_with_mocks( Arc::new(storage.clone()), Arc::new(network), Arc::new(metadata), ); + state.modules = modules; let credentials = match request_signer { RequestSigner::Wallet => { let (signature, timestamp) = caller.sign(&account_id); @@ -2066,6 +2102,44 @@ mod tests { assert_eq!(storage.get_submit_delta_calls().len(), 1); } + #[tokio::test] + async fn modules_learn_whether_the_submitter_signed_through_a_session() { + use crate::modules::testing::{StubModule, instance, pipeline}; + use crate::testing::helpers::TestSigner; + + for (request_signer, through_session) in [ + (RequestSigner::Wallet, false), + (RequestSigner::Session, true), + ] { + let first = TestSigner::new(); + let second = TestSigner::new(); + let summary = pushed_summary(); + let module = StubModule::allowing(); + let (result, _) = push_on_multisig_gated_by( + request_signer, + &[first.commitment_hex.clone(), second.commitment_hex.clone()], + &[], + 2, + &[], + ProposalLookup::Signatures(vec![ + falcon_approval(&first, &summary), + falcon_approval(&second, &summary), + ]), + Some(pipeline(vec![instance( + "caps", + &[HookName::BeforeTransactionApproved], + crate::modules::catalog::OnError::Deny, + module.clone(), + )])), + ) + .await; + assert!(result.is_ok(), "{result:?}"); + let request = module.last_request().expect("the module was called"); + assert_eq!(request.submitter_session, through_session); + assert_eq!(request.network_id, "local"); + } + } + async fn push_with_modules( module: Arc, ) -> (Result, MockStorageBackend, String) { diff --git a/crates/server/src/services/push_delta_proposal.rs b/crates/server/src/services/push_delta_proposal.rs index 01281240..669faa01 100644 --- a/crates/server/src/services/push_delta_proposal.rs +++ b/crates/server/src/services/push_delta_proposal.rs @@ -1,7 +1,7 @@ use crate::builder::state::AppState; use crate::delta_object::{CosignerSignature, DeltaObject, DeltaStatus}; use crate::error::{GuardianError, Result}; -use crate::metadata::auth::Credentials; +use crate::metadata::auth::{Credentials, RequestAuthFormat}; use crate::modules::HookName; use crate::modules::request::{self, ProposalContext, StateRef, TransactionInput}; use crate::services::account_status::ensure_account_active_metadata; @@ -143,6 +143,7 @@ async fn propose(state: &AppState, params: PushDeltaProposalParams, mode: Mode) let resolved = resolve_account_allowing_session(state, &account_id, &credentials).await?; ensure_account_active_metadata(&resolved.metadata)?; + let credentials_session = credentials.auth_format() == RequestAuthFormat::Session; // A dry run is admitted against its rate limit before any reconstruction work, whether // or not modules are configured. if mode == Mode::DryRun { @@ -384,7 +385,9 @@ async fn propose(state: &AppState, params: PushDeltaProposalParams, mode: Mode) TransactionInput { account_id: &account_id, submitter: &proposer_id, + submitter_session: credentials_session, auth: &resolved.metadata.auth, + network_config: &resolved.metadata.network_config, before: StateRef { commitment: &tail.commitment, json: &tail.state_json, diff --git a/speckit/features/251-guardian-modules/contracts/guardian_module_v1.proto b/speckit/features/251-guardian-modules/contracts/guardian_module_v1.proto index fcfc03d4..42f1f4bf 100644 --- a/speckit/features/251-guardian-modules/contracts/guardian_module_v1.proto +++ b/speckit/features/251-guardian-modules/contracts/guardian_module_v1.proto @@ -1,4 +1,4 @@ -// guardian.module.v1, extracted from docs/rfcs/0002-guardian-modules.md section 3 (revision 24). +// guardian.module.v1, extracted from docs/rfcs/0002-guardian-modules.md section 3 (revision 26). // The proto in RFC section 3 is authoritative; regenerate this file when it changes. // Protocol version 1 is frozen when M2a ships. diff --git a/speckit/features/251-guardian-modules/tasks.md b/speckit/features/251-guardian-modules/tasks.md index 18f83dbe..e5df5fc3 100644 --- a/speckit/features/251-guardian-modules/tasks.md +++ b/speckit/features/251-guardian-modules/tasks.md @@ -34,11 +34,11 @@ **CRITICAL**: no user story phase starts until this phase is complete. -- [ ] T003 Regenerate `crates/guardian-module-sdk/proto/guardian_module_v1.proto` from the RFC's renumbered version 1 block (`docs/rfcs/0002-guardian-modules.md`, section 3, matching `speckit/features/251-guardian-modules/contracts/guardian_module_v1.proto`, including `AccountView.signer_schemes = 8`), and update every constructor and test that sets field values in `crates/server/src/modules/request.rs`, `crates/server/src/network/miden/module_views.rs`, `crates/guardian-module-sdk/src/basic_policy.rs`, `crates/guardian-module-sdk/src/serve.rs` and `crates/guardian-module-sdk/tests/` (P0 T084) -- [ ] T004 [P] Add `network_id` to `HookRequest` (and to `CommitEvent` and `Gap` in the proto only, unused until M2b), filled from the account's `network_config` in `crates/server/src/modules/request.rs`; test that a request for a testnet account names its network (P0 T086) -- [ ] T005 [P] Add `AccountView.code_commitment` and `procedure_roots` in `crates/server/src/network/miden/module_views.rs`, and filter `procedure_thresholds` to effective overrides (non-zero, on a procedure the code exports, not the auth procedure); fixture tests in the same file with an inert override on a non-exported root and on the auth procedure (P0 T087) -- [ ] T006 [P] Add `MidenTransaction.reference_block`, optional `expiration_block` (absent when `expiration_delta` is 0) and `new_code_commitment` (from the delta's code patch) in `projection_from_summary`, `crates/server/src/network/miden/module_views.rs`; tests for each, including a summary with no expiration and one that replaces the account's code (P0 T088) -- [ ] T007 Add `HookRequest.submitter_session` from the resolved credential's auth format: pass it from `ResolvedAccount` through `ack_delta_internal::Submitter` (`crates/server/src/services/ack_delta_internal.rs`), `push_delta_proposal` and `configure_account` into `crates/server/src/modules/request.rs`; on the execution path carry it on `ExecutionJob` (`crates/server/src/services/execute_proposal/worker.rs`, `service.rs`) next to `requester`; tests for a wallet-signed and a session-signed push (P0 T093) +- [X] T003 Regenerate `crates/guardian-module-sdk/proto/guardian_module_v1.proto` from the RFC's renumbered version 1 block (`docs/rfcs/0002-guardian-modules.md`, section 3, matching `speckit/features/251-guardian-modules/contracts/guardian_module_v1.proto`, including `AccountView.signer_schemes = 8`), and update every constructor and test that sets field values in `crates/server/src/modules/request.rs`, `crates/server/src/network/miden/module_views.rs`, `crates/guardian-module-sdk/src/basic_policy.rs`, `crates/guardian-module-sdk/src/serve.rs` and `crates/guardian-module-sdk/tests/` (P0 T084) +- [X] T004 [P] Add `network_id` to `HookRequest` (and to `CommitEvent` and `Gap` in the proto only, unused until M2b), filled from the account's `network_config` in `crates/server/src/modules/request.rs`; test that a request for a testnet account names its network (P0 T086) +- [X] T005 [P] Add `AccountView.code_commitment` and `procedure_roots` in `crates/server/src/network/miden/module_views.rs`, and filter `procedure_thresholds` to effective overrides (non-zero, on a procedure the code exports, not the auth procedure); fixture tests in the same file with an inert override on a non-exported root and on the auth procedure (P0 T087) +- [X] T006 [P] Add `MidenTransaction.reference_block`, optional `expiration_block` (absent when `expiration_delta` is 0) and `new_code_commitment` (from the delta's code patch) in `projection_from_summary`, `crates/server/src/network/miden/module_views.rs`; tests for each, including a summary with no expiration and one that replaces the account's code (P0 T088) +- [X] T007 Add `HookRequest.submitter_session` from the resolved credential's auth format: pass it from `ResolvedAccount` through `ack_delta_internal::Submitter` (`crates/server/src/services/ack_delta_internal.rs`), `push_delta_proposal` and `configure_account` into `crates/server/src/modules/request.rs`; on the execution path carry it on `ExecutionJob` (`crates/server/src/services/execute_proposal/worker.rs`, `service.rs`) next to `requester`; tests for a wallet-signed and a session-signed push (P0 T093) - [ ] T008 Store `proposer_session` with the proposal when it is created (`crates/server/src/delta_object.rs` pending status, `crates/server/src/services/push_delta_proposal.rs`, both storage backends in `crates/server/src/storage/filesystem.rs` and `crates/server/src/storage/postgres.rs`, with a migration under `crates/server/migrations/` if Postgres stores it in a column) and return it from `request::proposal_context` in `crates/server/src/modules/request.rs` into `ProposalContext`; test that a session-created proposal reports it at approval (P0 T093) - [ ] T009 Replace the prototype's `metadata.modules` approval record with the delta fields of `data-model.md` ("Delta additions"): module trace (`catalog_hash`, `params_version`, `failed_open`), `signed_at` (fixed before the pipeline runs and sent as `accounting_time`), `submitter` and `proposer`, written once at signing in `crates/server/src/services/ack_delta_internal.rs`; add them to `crates/server/src/delta_object.rs`, the Postgres `deltas` table through a new migration in `crates/server/migrations/_guardian_module_delta_fields/`, and the filesystem delta JSON; keep the dashboard delta detail showing the trace (`crates/server/src/services/dashboard_account_delta_detail.rs`); regenerate OpenAPI if the delta wire shape changes - [ ] T010 [P] Build account views from the single decode the push path already does: carry the view fields on `AppliedState` (`crates/server/src/network/mod.rs`, `crates/server/src/network/miden/mod.rs` `verify_and_apply_delta`) and use them in `crates/server/src/modules/request.rs` instead of a second `Account::from_json`; run proposal creation through `verify_and_apply_delta` when a module will be called (P0 T089) From 0e2d91fc545faf5b8379cb947437c09a3d30ee4e Mon Sep 17 00:00:00 2001 From: Zeljko Date: Mon, 9 Nov 2026 09:43:55 +0100 Subject: [PATCH 008/105] docs(rfc): RFC 0002 revision 27, proposer_session dropped from version 1 (#251) A session key authenticates requests but cannot add a cosigner approval, so whether a session created a proposal adds nothing the threshold does not already require, and no catalog policy uses it. Removed from TransactionSubject, PendingTransaction and CommitEvent before the freeze, unverified_metadata renumbered to 5; version 1 can add it later as a new field. Section 3.2 corrected for #580: pushes and Guardian executions accept session credentials, so submitter_session is set at the ack. Spec FR-039, research and tasks follow (T008 dropped). --- .../proto/guardian_module_v1.proto | 5 +---- docs/rfcs/0002-guardian-modules.md | 14 ++++++-------- .../contracts/guardian_module_v1.proto | 5 +---- speckit/features/251-guardian-modules/research.md | 2 +- speckit/features/251-guardian-modules/spec.md | 2 +- speckit/features/251-guardian-modules/tasks.md | 4 ++-- 6 files changed, 12 insertions(+), 20 deletions(-) diff --git a/crates/guardian-module-sdk/proto/guardian_module_v1.proto b/crates/guardian-module-sdk/proto/guardian_module_v1.proto index 42f1f4bf..ac81d582 100644 --- a/crates/guardian-module-sdk/proto/guardian_module_v1.proto +++ b/crates/guardian-module-sdk/proto/guardian_module_v1.proto @@ -82,8 +82,7 @@ message TransactionSubject { RawTransaction raw = 2; // the network's own encoding; UNSTABLE across that network's protocol bumps repeated PendingTransaction pending = 3; // signed for this account, not yet acknowledged by this module (section 3.4) string proposer = 4; // signer commitment that created the matching proposal; verified; empty when there is none (section 3.2) - bool proposer_session = 5; // the proposer created it through a delegated session key (section 3.2) - bytes unverified_metadata = 6; // UTF-8 JSON, proposer-asserted proposal metadata; never authoritative; UNSTABLE across SDK releases (section 3.2) + bytes unverified_metadata = 5; // UTF-8 JSON, proposer-asserted proposal metadata; never authoritative; UNSTABLE across SDK releases (section 3.2) } message PendingTransaction { @@ -95,7 +94,6 @@ message PendingTransaction { optional google.protobuf.Timestamp committed_at = 6; // set when state = committed string submitter = 7; // as in HookRequest at the ack that signed this transaction; verified (section 3.2) string proposer = 8; // as in TransactionSubject at that ack; empty when there was no matching proposal - bool proposer_session = 9; // as in TransactionSubject at that ack } enum PendingState { PENDING_STATE_UNSPECIFIED = 0; @@ -211,7 +209,6 @@ message CommitEvent { google.protobuf.Timestamp signed_at = 11; // the accounting clock, identical to the value the module saw in pending (section 3.4) string submitter = 12; // as in HookRequest at the ack that signed this transaction; verified (section 3.2) string proposer = 13; // as in TransactionSubject at that ack; empty when there was no matching proposal (section 3.2) - bool proposer_session = 14; // as in TransactionSubject at that ack } message Gap { diff --git a/docs/rfcs/0002-guardian-modules.md b/docs/rfcs/0002-guardian-modules.md index a91f8784..0fdc99eb 100644 --- a/docs/rfcs/0002-guardian-modules.md +++ b/docs/rfcs/0002-guardian-modules.md @@ -7,7 +7,7 @@ | **Feature** | [#251](https://github.com/OpenZeppelin/guardian/issues/251) ("Modularization: middleware architecture and pluggable modules"); first consumer [#182](https://github.com/OpenZeppelin/guardian/issues/182) (policy evaluation). [#252](https://github.com/OpenZeppelin/guardian/issues/252) (x402 facilitator) is a later consumer: its payment-policy half (caps, allowlists, replay) fits `before_transaction_approved` and `after_transaction_committed`, its facilitator half (`/verify`, `/settle`, a flow that starts and waits) does not fit allow/deny and is future work (section 7) | | **Audience** | Operators, module authors, integrators, and anyone reviewing the Guardian trust model | | **Working artifacts** | [`speckit/features/251-guardian-modules/`](../../speckit/features/251-guardian-modules/spec.md): the specification, written alongside this RFC; plan and tasks follow the prototype | -| **Revision** | 26 (2026-11-09): per-signer schemes in `AccountView` for mixed-scheme accounts, and the execution path's module failure codes; changes in Appendix C | +| **Revision** | 27 (2026-11-09): `proposer_session` dropped from version 1, `submitter_session` set at the ack now that pushes accept sessions; changes in Appendix C | | **Review sought** | Comments on the design and the M2a scope remain open until M2a ships, when `guardian.module.v1` freezes (section 7) | | **Code baseline** | `main` at `ca503704`; execution-path citations read on `254-execution-impl` at `29c722b4` (PR #510, since merged to `main` as `1100f3a4`) and kept as dated evidence. Miden pins: protocol and standards 0.17.1. Appendices B and C cite the baselines of their revisions. Prototype findings (2026-10-13 to 2026-10-15) in `speckit/features/251-guardian-modules/research.md` | @@ -631,8 +631,7 @@ message TransactionSubject { RawTransaction raw = 2; // the network's own encoding; UNSTABLE across that network's protocol bumps repeated PendingTransaction pending = 3; // signed for this account, not yet acknowledged by this module (section 3.4) string proposer = 4; // signer commitment that created the matching proposal; verified; empty when there is none (section 3.2) - bool proposer_session = 5; // the proposer created it through a delegated session key (section 3.2) - bytes unverified_metadata = 6; // UTF-8 JSON, proposer-asserted proposal metadata; never authoritative; UNSTABLE across SDK releases (section 3.2) + bytes unverified_metadata = 5; // UTF-8 JSON, proposer-asserted proposal metadata; never authoritative; UNSTABLE across SDK releases (section 3.2) } message PendingTransaction { @@ -644,7 +643,6 @@ message PendingTransaction { optional google.protobuf.Timestamp committed_at = 6; // set when state = committed string submitter = 7; // as in HookRequest at the ack that signed this transaction; verified (section 3.2) string proposer = 8; // as in TransactionSubject at that ack; empty when there was no matching proposal - bool proposer_session = 9; // as in TransactionSubject at that ack } enum PendingState { PENDING_STATE_UNSPECIFIED = 0; @@ -760,7 +758,6 @@ message CommitEvent { google.protobuf.Timestamp signed_at = 11; // the accounting clock, identical to the value the module saw in pending (section 3.4) string submitter = 12; // as in HookRequest at the ack that signed this transaction; verified (section 3.2) string proposer = 13; // as in TransactionSubject at that ack; empty when there was no matching proposal (section 3.2) - bool proposer_session = 14; // as in TransactionSubject at that ack } message Gap { @@ -837,7 +834,7 @@ The fee note (`tx_fee`) is excluded from every recipient, asset and amount rule. **Proposal context.** `HookRequest.submitter` and the `TransactionSubject` fields below carry who acted on the transaction and what the proposer said about it. The two are trusted differently. -**Verified identities.** Both are signer commitments taken from request authentication (`ResolvedAccount.signer_commitment`, `crates/server/src/services/mod.rs:120`) **[READ]**, never from the payload. A proposal can also be created under a delegated session key (#537): `push_delta_proposal` accepts sessions (`resolve_account_allowing_session`, `push_delta_proposal.rs:75`), and for a session credential the resolved commitment is the cosigner that granted the session, not the session key (`services/mod.rs:193-199`) **[READ]**. `submitter` and `proposer` are therefore always cosigner commitments; `push_delta` and `/configure` do not accept sessions. Two flags keep delegation visible. `HookRequest.submitter_session` marks a request authenticated through a session; since only proposal creation accepts sessions, it is always false at the ack. `TransactionSubject.proposer_session` marks a proposal created through one: it is stored with the proposal, returned by the `ProposalContext` lookup together with the proposer, and repeated in `pending` and `CommitEvent` like `proposer`. A rule such as "delegated sessions may not propose signer changes" therefore holds at the ack, where it must be enforced (section 2.3, "Not a security boundary"), and not only at creation, where it is a filter. A transaction pushed without a stored proposal has an empty `proposer` and `proposer_session = false`; a rule that must hold treats it as an unknown proposer (below). +**Verified identities.** Both are signer commitments taken from request authentication (`ResolvedAccount.signer_commitment`, `crates/server/src/services/mod.rs:120`) **[READ]**, never from the payload. A proposal can also be created under a delegated session key (#537): `push_delta_proposal` accepts sessions (`resolve_account_allowing_session`, `push_delta_proposal.rs:75`), and for a session credential the resolved commitment is the cosigner that granted the session, not the session key (`services/mod.rs:193-199`) **[READ]**. `submitter` and `proposer` are therefore always cosigner commitments. `/configure` refuses session credentials; proposal creation, `push_delta` (#580) and Guardian execution requests accept them. `HookRequest.submitter_session` marks a request authenticated through a session, at proposal creation, at the ack of a push and at the ack of a Guardian execution, so a rule such as "a delegated session may not push signer changes" holds at the ack, where it must be enforced (section 2.3, "Not a security boundary"). Whether a stored proposal was created through a session is not sent: a session key authenticates requests but cannot add a cosigner's approval, so a proposal created through one still needs the account's threshold of cosigner signatures before the Guardian acks it, and no policy in this RFC's catalog needs the distinction. Version 1 can add it later as a new field. A transaction pushed without a stored proposal has an empty `proposer`; a rule that must hold treats it as an unknown proposer (below). - `submitter` is the cosigner whose request is being evaluated: the proposer at `before_proposal_created`, the cosigner calling `push_delta` at `before_transaction_approved`. On the execution path it is the cosigner whose authenticated request created the execution attempt (RFC 0001). At the cited execution baseline that identity is not kept: the service authenticates the requester (`execute_proposal/service.rs:131` at `29c722b4`) but `ExecutionJob` holds no requester (`worker.rs:27-40`) **[READ]**. The implementation records the authenticated requester when it creates an attempt and carries it to the ack. It is not stored on the reservation: the ack runs before the no-retry boundary, and an attempt interrupted before that boundary is never resumed (the first reconciliation pass after a restart fails it as `GUARDIAN_EXECUTION_ABANDONED`), so no worker acks without the request that started it. A repeated request for an attempt already active joins it and keeps the original requester. - `proposer` is the cosigner that created the proposal for this exact transaction. At `before_proposal_created` it equals `submitter`. At the ack it comes from the matching proposal, found by the proposal id derived from the transaction (`lookup_matching_proposal_payload`, `push_delta.rs:164,229`) **[READ]**, and is empty when there is none: a single-key account, a transaction signed offline and pushed without a stored proposal, or a proposal already deleted. That helper returns only the payload, and returns nothing on a storage error as well as on absence (`push_delta.rs:229-270`) **[READ]**, which is acceptable for dashboard metadata but not for policy: a storage fault would read as "no proposer". The pipeline instead uses a lookup returning `Result>`, where `ProposalContext` holds the proposer, its session flag and the metadata together. `Ok(None)` is absence and yields an empty `proposer`; an error is treated as an error for every module called, so `on_error` applies. @@ -1094,7 +1091,7 @@ The first enclave step allows in-process kinds only; the attested tier follows o **Protocol version 1 is fixed at M2a.** The full `guardian.module.v1` proto above, including `Notify`, `NotifyGap`, `pending`, `accounting_time` and the watermark fields, is published with M2a, so modules written against M2a need no change when M2b ships. In M2a the Guardian sends an empty `pending`, never calls `Notify` or `NotifyGap`, does not offer the `notify` capability, and refuses at startup a catalog that subscribes an instance to `after_transaction_committed`, so a stateful module cannot start on it (section 3.5). -**Freeze criteria.** Version 1 freezes only once the prototype implements, with tests, the protocol surface added in revision 24 that is so far derived from reading code: the renumbered proto, registration before the claim (new account, unfinished claim, lost claim), `network_id`, `code_commitment` and `procedure_roots` with effective-override filtering (non-zero, exported, not the auth procedure), `reference_block` and the optional `expiration_block`, `new_code_commitment`, `submitter_session` and `proposer_session` stored with the proposal, `dry_run` with approval instances in the check, and the `allowed_code_commitments` rule with `code_check`. Extraction details are where the prototype found errors before (the fee note, single-key views), so these are measured against real accounts, not only fixtures. +**Freeze criteria.** Version 1 freezes only once the prototype implements, with tests, the protocol surface added in revision 24 that is so far derived from reading code: the renumbered proto, registration before the claim (new account, unfinished claim, lost claim), `network_id`, `code_commitment` and `procedure_roots` with effective-override filtering (non-zero, exported, not the auth procedure), `reference_block` and the optional `expiration_block`, `new_code_commitment`, `submitter_session`, `dry_run` with approval instances in the check, and the `allowed_code_commitments` rule with `code_check`. Extraction details are where the prototype found errors before (the fee note, single-key views), so these are measured against real accounts, not only fixtures. **M2a: stateless gates.** @@ -1108,7 +1105,7 @@ The first enclave step allows in-process kinds only; the attested tier follows o - `GUARDIAN_MODULE_DENIED` and `GUARDIAN_MODULE_UNAVAILABLE` in the server and both SDKs, on proposal creation as well as on the ack. - Policy discovery (section 2.7): the `disclosure`, `description`, `client_reason` and `dry_run` catalog fields, generic denials, `Decision.client_message`, the policy summary and dry-run check on the client API with their rate limit, and the SDK methods named in section 2.7 in both base clients and both multisig SDKs. The error contract and the protocol field must land before version 1 freezes; the two endpoints may follow in an M2a point release. - Reference module `basic-policy` (recipient allowlist and denylist, asset allowlist, per-transaction amount cap, signer allowlist or denylist with `signer_check`, account code allowlist), shipped as a first-party in-process kind and, through the `serve` harness, as a standalone gRPC service in `examples/policy-module/`. -- Account view extraction with explicit errors for unsupported auth state, effective procedure overrides, code commitment and procedure roots; `network_id`, `reference_block` and `new_code_commitment` in the projection (section 3.1); `submitter_session`, and `proposer_session` stored with the proposal (section 3.2); the params size cap (section 2.2); the `ProposalContext` lookup, first-creator-wins proposal storage on both backends (on `main`, `admit_delta_proposal` refuses an existing commitment on both), and the requester carried from the execution request to the ack (section 3.2). +- Account view extraction with explicit errors for unsupported auth state, effective procedure overrides, code commitment and procedure roots; `network_id`, `reference_block` and `new_code_commitment` in the projection (section 3.1); `submitter_session` (section 3.2); the params size cap (section 2.2); the `ProposalContext` lookup, first-creator-wins proposal storage on both backends (on `main`, `admit_delta_proposal` refuses an existing commitment on both), and the requester carried from the execution request to the ack (section 3.2). - Acceptance cases: a denial at proposal creation stores nothing and takes no slot; a proposal that passes creation and is denied at the ack; a transaction signed offline and pushed without a stored proposal is enforced at the ack; forged `unverified_metadata` does not change a decision; a failed account view extraction applies `on_error`. Creation denials are exercised through `guardian-client` (Rust and TypeScript) and both multisig SDKs. - Docs: configuration, trust boundary in concepts, troubleshooting codes (including the denial log fields, section 2.2), the break-glass runbook (section 4.2), data-protection guidance for operators and vendors (invariant 5), and a module author guide for remote modules. @@ -1207,6 +1204,7 @@ None. Questions resolved in earlier revisions are kept below with their answers. | Revision | Date | Changes | |---|---|---| +| 27 | 2026-11-09 | `proposer_session` removed from `TransactionSubject`, `PendingTransaction` and `CommitEvent`, and `unverified_metadata` renumbered to 5 before the freeze: a session key cannot approve a proposal, so whether one created it adds nothing the threshold does not already require, and no catalog policy uses it; version 1 can add it later. Section 3.2 corrected for #580: `push_delta` and Guardian execution accept session credentials, so `submitter_session` can be true at the ack. Freeze criteria and the M2a list updated (section 7) | | 26 | 2026-11-09 | `main` (mixed-scheme accounts, #565) merged into the prototype. `AccountView.signer_schemes` (signer commitment to `falcon` or `ecdsa`), decoded per approver from state, and `auth_scheme` redefined as the signers' common scheme or `mixed`, because "one scheme per account" no longer holds (section 3.2). The execution path's refusals named as `GUARDIAN_EXECUTION_MODULE_DENIED` and `GUARDIAN_EXECUTION_MODULE_UNAVAILABLE` failure codes (section 4.1). The execution requester is carried to the ack, not stored on the reservation, since pre-boundary attempts are never resumed (sections 3.2 and 7) | | 25 | 2026-11-03 | status moved from Open for comment to Accepted for implementation on merge of PR #544; RFC 0001 links point at its merged copy and section 7 records that PR #510 has merged; review-sought and code-baseline rows updated to match. No design change | | 24 | 2026-10-21 | three review rounds on PR #544, `main` merged in and citations re-pinned to `ca503704` and Miden 0.17.1. Protocol: registration rewritten for the account claim of #558 (section 2.3); `network_id`; `code_commitment`, `procedure_roots`, effective `procedure_thresholds` and `new_code_commitment`, with invariant 6 and the `basic-policy` code allowlist; `reference_block` and optional `expiration_block`; `submitter_session`; `request_id` defined; proto renumbered for version 1; `notify` capability (section 3.5); freeze criteria (section 7). `proposer_session` stored with the proposal; `dry_run`, with approval instances run by the policy check and `complete` derived from the catalog; `code_check`; reassignment enters `resync_required`. Semantics: `params_drift` against `seeded_params`; params size cap; paginated history; `default` copies take the evaluated params. Writing: contents, terms, registration out of the hook table, `basic-policy` table with reason codes, policy summary example, notify and resync sequence diagram, break-glass and denial-log notes | diff --git a/speckit/features/251-guardian-modules/contracts/guardian_module_v1.proto b/speckit/features/251-guardian-modules/contracts/guardian_module_v1.proto index 42f1f4bf..ac81d582 100644 --- a/speckit/features/251-guardian-modules/contracts/guardian_module_v1.proto +++ b/speckit/features/251-guardian-modules/contracts/guardian_module_v1.proto @@ -82,8 +82,7 @@ message TransactionSubject { RawTransaction raw = 2; // the network's own encoding; UNSTABLE across that network's protocol bumps repeated PendingTransaction pending = 3; // signed for this account, not yet acknowledged by this module (section 3.4) string proposer = 4; // signer commitment that created the matching proposal; verified; empty when there is none (section 3.2) - bool proposer_session = 5; // the proposer created it through a delegated session key (section 3.2) - bytes unverified_metadata = 6; // UTF-8 JSON, proposer-asserted proposal metadata; never authoritative; UNSTABLE across SDK releases (section 3.2) + bytes unverified_metadata = 5; // UTF-8 JSON, proposer-asserted proposal metadata; never authoritative; UNSTABLE across SDK releases (section 3.2) } message PendingTransaction { @@ -95,7 +94,6 @@ message PendingTransaction { optional google.protobuf.Timestamp committed_at = 6; // set when state = committed string submitter = 7; // as in HookRequest at the ack that signed this transaction; verified (section 3.2) string proposer = 8; // as in TransactionSubject at that ack; empty when there was no matching proposal - bool proposer_session = 9; // as in TransactionSubject at that ack } enum PendingState { PENDING_STATE_UNSPECIFIED = 0; @@ -211,7 +209,6 @@ message CommitEvent { google.protobuf.Timestamp signed_at = 11; // the accounting clock, identical to the value the module saw in pending (section 3.4) string submitter = 12; // as in HookRequest at the ack that signed this transaction; verified (section 3.2) string proposer = 13; // as in TransactionSubject at that ack; empty when there was no matching proposal (section 3.2) - bool proposer_session = 14; // as in TransactionSubject at that ack } message Gap { diff --git a/speckit/features/251-guardian-modules/research.md b/speckit/features/251-guardian-modules/research.md index b87726f9..c1c17cc3 100644 --- a/speckit/features/251-guardian-modules/research.md +++ b/speckit/features/251-guardian-modules/research.md @@ -271,7 +271,7 @@ Both reviewers accepted the design. Applied, still as revision 24: Two more reviews; one cited lines from before revision 24 (`checkProposal`, the `drift` example, "catalog params" in the hook table), all already fixed. Applied, still as revision 24: -- **Delegation was visible only at creation.** `submitter_session` is always false at the ack, where rules must be enforced. `proposer_session` is now stored with the proposal, returned with the proposer by the `ProposalContext` lookup, and sent in `TransactionSubject`, `pending` and `CommitEvent`. +- **Delegation was visible only at creation.** `submitter_session` was always false at the ack, where rules must be enforced, so revision 24 added `proposer_session`, stored with the proposal. Revised 2026-11-09 (RFC revision 27): since #580 `push_delta` and Guardian execution accept session credentials, so `submitter_session` is set at the ack; `proposer_session` was dropped, since a session key cannot approve a proposal and no catalog policy needs it. - **The dry run skipped the hook that matters.** It now also runs instances subscribed only to `before_transaction_approved`, marked with `HookRequest.dry_run`, and `complete` is derived from the catalog, so it no longer reveals that one account carries a hidden instance. - **Code allowlist grandfathering.** `code_check = "changed"` (default) keeps code an account already runs, documented as `signer_check = "added"` is; `code_check = "all"` checks the current code at every gate hook. - **Reassignment of a stateful module** after removal from an account enters `resync_required`, matching catalog removal and return. The counting model does not cover assignment changes (its SKILL.md says so); T096 extends it. diff --git a/speckit/features/251-guardian-modules/spec.md b/speckit/features/251-guardian-modules/spec.md index 855bf290..1fbc02ef 100644 --- a/speckit/features/251-guardian-modules/spec.md +++ b/speckit/features/251-guardian-modules/spec.md @@ -261,7 +261,7 @@ Slice tags show where each requirement is first delivered. Wire formats, field n - **FR-036** [M2a]: Proposer-supplied proposal metadata MUST be passed only as explicitly untrusted data, and no typed copy of proposer-asserted values (amounts, recipients, signers) may be provided. - **FR-037** [M2a]: Each request MUST identify the instance being called, so one remote service can back several instances with separate state and credentials. - **FR-038** [M2a]: Each request MUST be bounded in size; an oversized request counts as a module failure without the call being made. -- **FR-039** [M2a]: Requests MUST name the account's network within its family (for example mainnet or testnet), the account views MUST carry the account's code commitment and exported procedure roots and only the procedure threshold overrides its code can apply, and transaction projections MUST carry the reference block, the expiration block only when one is set, and a new code commitment when the transaction replaces the account's code. Requests MUST say whether the submitter acted through a delegated session key, and transaction requests, pending entries and notifications MUST say whether the proposal was created through one, stored with the proposal. The reference policy MUST be able to restrict accounts to listed code commitments, at registration and on code replacement. +- **FR-039** [M2a]: Requests MUST name the account's network within its family (for example mainnet or testnet), the account views MUST carry the account's code commitment and exported procedure roots and only the procedure threshold overrides its code can apply, and transaction projections MUST carry the reference block, the expiration block only when one is set, and a new code commitment when the transaction replaces the account's code. Requests MUST say whether the submitter acted through a delegated session key, at proposal creation and at the ack of a push or a Guardian execution. The reference policy MUST be able to restrict accounts to listed code commitments, at registration and on code replacement. ### Decisions and errors diff --git a/speckit/features/251-guardian-modules/tasks.md b/speckit/features/251-guardian-modules/tasks.md index e5df5fc3..a92217ec 100644 --- a/speckit/features/251-guardian-modules/tasks.md +++ b/speckit/features/251-guardian-modules/tasks.md @@ -39,7 +39,7 @@ - [X] T005 [P] Add `AccountView.code_commitment` and `procedure_roots` in `crates/server/src/network/miden/module_views.rs`, and filter `procedure_thresholds` to effective overrides (non-zero, on a procedure the code exports, not the auth procedure); fixture tests in the same file with an inert override on a non-exported root and on the auth procedure (P0 T087) - [X] T006 [P] Add `MidenTransaction.reference_block`, optional `expiration_block` (absent when `expiration_delta` is 0) and `new_code_commitment` (from the delta's code patch) in `projection_from_summary`, `crates/server/src/network/miden/module_views.rs`; tests for each, including a summary with no expiration and one that replaces the account's code (P0 T088) - [X] T007 Add `HookRequest.submitter_session` from the resolved credential's auth format: pass it from `ResolvedAccount` through `ack_delta_internal::Submitter` (`crates/server/src/services/ack_delta_internal.rs`), `push_delta_proposal` and `configure_account` into `crates/server/src/modules/request.rs`; on the execution path carry it on `ExecutionJob` (`crates/server/src/services/execute_proposal/worker.rs`, `service.rs`) next to `requester`; tests for a wallet-signed and a session-signed push (P0 T093) -- [ ] T008 Store `proposer_session` with the proposal when it is created (`crates/server/src/delta_object.rs` pending status, `crates/server/src/services/push_delta_proposal.rs`, both storage backends in `crates/server/src/storage/filesystem.rs` and `crates/server/src/storage/postgres.rs`, with a migration under `crates/server/migrations/` if Postgres stores it in a column) and return it from `request::proposal_context` in `crates/server/src/modules/request.rs` into `ProposalContext`; test that a session-created proposal reports it at approval (P0 T093) +- [X] T008 Dropped 2026-11-09 (RFC revision 27): `proposer_session` removed from protocol version 1 instead of stored, since a session key cannot approve a proposal and no catalog policy uses it; version 1 can add it later - [ ] T009 Replace the prototype's `metadata.modules` approval record with the delta fields of `data-model.md` ("Delta additions"): module trace (`catalog_hash`, `params_version`, `failed_open`), `signed_at` (fixed before the pipeline runs and sent as `accounting_time`), `submitter` and `proposer`, written once at signing in `crates/server/src/services/ack_delta_internal.rs`; add them to `crates/server/src/delta_object.rs`, the Postgres `deltas` table through a new migration in `crates/server/migrations/_guardian_module_delta_fields/`, and the filesystem delta JSON; keep the dashboard delta detail showing the trace (`crates/server/src/services/dashboard_account_delta_detail.rs`); regenerate OpenAPI if the delta wire shape changes - [ ] T010 [P] Build account views from the single decode the push path already does: carry the view fields on `AppliedState` (`crates/server/src/network/mod.rs`, `crates/server/src/network/miden/mod.rs` `verify_and_apply_delta`) and use them in `crates/server/src/modules/request.rs` instead of a second `Account::from_json`; run proposal creation through `verify_and_apply_delta` when a module will be called (P0 T089) - [ ] T011 Measure the frozen extraction against real accounts, not only fixtures: add captured devnet accounts (single-key Falcon, single-key ECDSA, 2-of-3 Falcon, mixed-scheme multisig with a procedure override, an account after a code replacement) under `crates/server/src/testing/fixtures/` and assert the full `AccountView` and `MidenTransaction` for each in `crates/server/src/network/miden/module_views.rs` tests @@ -207,7 +207,7 @@ ### Phase dependencies - **Setup (T001, T002)** first. -- **Foundational (T003 to T012)** blocks every story. T003 first (it renumbers the proto); T004, T005, T006 and T010 then run in parallel; T007 and T008 after T003; T009 after T007 and T008 (it stores `submitter` and `proposer`); T011 after T005 and T006; T012 last. +- **Foundational (T003 to T012)** blocks every story. T003 first (it renumbers the proto); T004, T005, T006 and T010 then run in parallel; T007 and T008 after T003; T009 after T007 (it stores `submitter` and `proposer`); T011 after T005 and T006; T012 last. - **Stories** start after T012 and are independent of each other, with these exceptions: T030 (budget on writes) needs T028; T039 and T040 (`default` copy) touch `configure_account.rs` after T024, so run US3 before US5 or coordinate the file; T021 needs the `guardian-client` dependency decision. - **Polish (T052 to T062)** after the stories it documents; T061 and T062 last. From 053ecf8a5a7886b51bee2f5b98cc0e5f5f9e25dd Mon Sep 17 00:00:00 2001 From: Zeljko Date: Mon, 9 Nov 2026 09:47:03 +0100 Subject: [PATCH 009/105] feat(modules): record signed_at, submitter and proposer with the module approval (#251) The approval written to a signed delta's metadata now carries signed_at, fixed before the pipeline runs and sent to the modules as accounting_time, the submitter it was evaluated for, and the matching proposal's creator, next to the catalog hash, params version and fail-open list. The pipeline returns only the configuration it ran with; the ack builds the record. Delta metadata is already stored on both backends, so this needs no migration. OpenAPI regenerated. --- crates/server/src/delta_summary/mod.rs | 13 +++++++++--- crates/server/src/modules/pipeline.rs | 15 ++++++++++--- .../server/src/services/ack_delta_internal.rs | 20 ++++++++++++++++-- crates/server/src/services/push_delta.rs | 21 ++++++++++++++++++- docs/openapi-client.json | 18 ++++++++++++++-- docs/openapi.json | 18 ++++++++++++++-- .../251-guardian-modules/data-model.md | 10 +++++---- .../features/251-guardian-modules/tasks.md | 2 +- 8 files changed, 99 insertions(+), 18 deletions(-) diff --git a/crates/server/src/delta_summary/mod.rs b/crates/server/src/delta_summary/mod.rs index 9f27c72e..1ef79f1e 100644 --- a/crates/server/src/delta_summary/mod.rs +++ b/crates/server/src/delta_summary/mod.rs @@ -61,9 +61,9 @@ pub struct DeltaMetadata { pub modules: Option, } -/// What the policy modules ran with. Allowed evaluations are not listed: the catalog, params -/// version and account determine which modules ran, so only failures let through by -/// `on_error = allow` are kept. +/// The policy modules' approval of a signed delta: the configuration they ran with, when and for +/// whom. Allowed evaluations are not listed: the catalog, params version and account determine +/// which modules ran, so only failures let through by `on_error = allow` are kept. #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, utoipa::ToSchema)] pub struct ModuleApproval { /// SHA-256 of the catalog file the approving replica loaded. @@ -71,6 +71,13 @@ pub struct ModuleApproval { pub params_version: u64, #[serde(default, skip_serializing_if = "Vec::is_empty")] pub failed_open: Vec, + /// RFC 3339 time the Guardian signed, the accounting time the modules evaluated with. + pub signed_at: String, + /// The cosigner the acknowledgment was evaluated for. + pub submitter: String, + /// The matching proposal's creator; empty when no stored proposal matched. + #[serde(default, skip_serializing_if = "String::is_empty")] + pub proposer: String, } #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, utoipa::ToSchema)] diff --git a/crates/server/src/modules/pipeline.rs b/crates/server/src/modules/pipeline.rs index 6d1179a7..897d1e14 100644 --- a/crates/server/src/modules/pipeline.rs +++ b/crates/server/src/modules/pipeline.rs @@ -9,9 +9,18 @@ use std::sync::{Arc, RwLock}; use super::registry::{CallError, Instance, Registry, isolated}; use super::request::ViewCache; use super::store::{AccountParamsRow, ModuleStore, ParamsKind}; -use crate::delta_summary::{FailedOpen, ModuleApproval}; +use crate::delta_summary::FailedOpen; use crate::error::GuardianError; +/// The configuration a pipeline run evaluated with, and the failures `on_error = allow` let +/// through. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct Evaluation { + pub catalog_hash: String, + pub params_version: u64, + pub failed_open: Vec, +} + #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub enum Layer { Global, @@ -411,7 +420,7 @@ impl Plan<'_> { pub async fn run( self, build: impl FnOnce() -> Result, - ) -> Result { + ) -> Result { let Plan { hook, account_id, @@ -421,7 +430,7 @@ impl Plan<'_> { views: _, } = self; let account_id = account_id.as_str(); - let mut approval = ModuleApproval { + let mut approval = Evaluation { catalog_hash, params_version, failed_open: Vec::new(), diff --git a/crates/server/src/services/ack_delta_internal.rs b/crates/server/src/services/ack_delta_internal.rs index 108a8bc8..b3f55f73 100644 --- a/crates/server/src/services/ack_delta_internal.rs +++ b/crates/server/src/services/ack_delta_internal.rs @@ -141,6 +141,13 @@ async fn approve( ProposalMatch::Missing => Ok(None), ProposalMatch::Unavailable(error) => Err(format!("proposal lookup failed: {error}")), }; + let proposer = proposal + .as_ref() + .ok() + .and_then(|context| context.as_ref()) + .map(|context| context.proposer.clone()) + .unwrap_or_default(); + let signed_at = state.clock.now(); let views = plan.views(); plan.run(|| { request::transaction_request( @@ -159,12 +166,21 @@ async fn approve( }, tx_summary: &delta.delta_payload, proposal: proposal?, - accounting_time: state.clock.now(), + accounting_time: signed_at, }, ) }) .await - .map(Some) + .map(|evaluation| { + Some(ModuleApproval { + catalog_hash: evaluation.catalog_hash, + params_version: evaluation.params_version, + failed_open: evaluation.failed_open, + signed_at: signed_at.to_rfc3339(), + submitter: submitter.commitment.to_string(), + proposer, + }) + }) } /// The `delta_proposals` row matching a delta, as far as storage could tell. diff --git a/crates/server/src/services/push_delta.rs b/crates/server/src/services/push_delta.rs index 215fe2f4..24be7078 100644 --- a/crates/server/src/services/push_delta.rs +++ b/crates/server/src/services/push_delta.rs @@ -2291,7 +2291,16 @@ mod tests { crate::modules::catalog::OnError::Deny, ) .await; - result.expect("allowed push succeeds"); + let pushed = result.expect("allowed push succeeds"); + assert_eq!( + pushed + .delta + .metadata + .and_then(|metadata| metadata.modules) + .map(|approval| approval.proposer), + Some("0xproposer".to_string()), + "the approval records the proposer the modules saw" + ); assert_eq!( storage.get_pull_delta_proposal_calls().len(), 2, @@ -2331,9 +2340,19 @@ mod tests { .and_then(|metadata| metadata.modules) .expect("the approving module configuration is recorded"); assert_eq!(approval.params_version, 0); + assert_eq!(approval.proposer, "", "no stored proposal matched"); assert!(approval.failed_open.is_empty()); let request = module.last_request().expect("module was called"); assert_eq!(request.submitter, signer); + assert_eq!(approval.submitter, signer); + let accounting_time = request.accounting_time.expect("accounting time is sent"); + assert_eq!( + chrono::DateTime::parse_from_rfc3339(&approval.signed_at) + .expect("signed_at is RFC 3339") + .timestamp_nanos_opt(), + Some(accounting_time.seconds * 1_000_000_000 + i64::from(accounting_time.nanos)), + "signed_at is the accounting time the modules evaluated with" + ); let Some(guardian_module_sdk::proto::hook_request::Subject::Transaction(subject)) = &request.subject else { diff --git a/docs/openapi-client.json b/docs/openapi-client.json index 700cde74..0329165c 100644 --- a/docs/openapi-client.json +++ b/docs/openapi-client.json @@ -3444,10 +3444,12 @@ }, "ModuleApproval": { "type": "object", - "description": "What the policy modules ran with. Allowed evaluations are not listed: the catalog, params\nversion and account determine which modules ran, so only failures let through by\n`on_error = allow` are kept.", + "description": "The policy modules' approval of a signed delta: the configuration they ran with, when and for\nwhom. Allowed evaluations are not listed: the catalog, params version and account determine\nwhich modules ran, so only failures let through by `on_error = allow` are kept.", "required": [ "catalog_hash", - "params_version" + "params_version", + "signed_at", + "submitter" ], "properties": { "catalog_hash": { @@ -3464,6 +3466,18 @@ "type": "integer", "format": "int64", "minimum": 0 + }, + "proposer": { + "type": "string", + "description": "The matching proposal's creator; empty when no stored proposal matched." + }, + "signed_at": { + "type": "string", + "description": "RFC 3339 time the Guardian signed, the accounting time the modules evaluated with." + }, + "submitter": { + "type": "string", + "description": "The cosigner the acknowledgment was evaluated for." } } }, diff --git a/docs/openapi.json b/docs/openapi.json index 0279d5ec..acbc29f5 100644 --- a/docs/openapi.json +++ b/docs/openapi.json @@ -7381,10 +7381,12 @@ }, "ModuleApproval": { "type": "object", - "description": "What the policy modules ran with. Allowed evaluations are not listed: the catalog, params\nversion and account determine which modules ran, so only failures let through by\n`on_error = allow` are kept.", + "description": "The policy modules' approval of a signed delta: the configuration they ran with, when and for\nwhom. Allowed evaluations are not listed: the catalog, params version and account determine\nwhich modules ran, so only failures let through by `on_error = allow` are kept.", "required": [ "catalog_hash", - "params_version" + "params_version", + "signed_at", + "submitter" ], "properties": { "catalog_hash": { @@ -7401,6 +7403,18 @@ "type": "integer", "format": "int64", "minimum": 0 + }, + "proposer": { + "type": "string", + "description": "The matching proposal's creator; empty when no stored proposal matched." + }, + "signed_at": { + "type": "string", + "description": "RFC 3339 time the Guardian signed, the accounting time the modules evaluated with." + }, + "submitter": { + "type": "string", + "description": "The cosigner the acknowledgment was evaluated for." } } }, diff --git a/speckit/features/251-guardian-modules/data-model.md b/speckit/features/251-guardian-modules/data-model.md index c0c71788..fe4c7a0a 100644 --- a/speckit/features/251-guardian-modules/data-model.md +++ b/speckit/features/251-guardian-modules/data-model.md @@ -73,13 +73,15 @@ One row holding the params version. Every write takes its lock first, increments ### Delta additions (both backends) +The approval record is `metadata.modules` on the signed delta (`ModuleApproval`), stored with the delta's metadata (JSONB on Postgres, JSON on the filesystem), so it needs no migration. Like the rest of `metadata` it is served on the HTTP delta and dashboard routes, not over gRPC. Written only when a module ran for the delta. + | Field | Set when | Notes | |---|---|---| -| `modules` (evaluation trace) | The Guardian signs the delta after modules ran | Dashboard detail only. `catalog_hash`, `params_version`, `failed_open` (module, layer, failure kind; omitted when empty). Allowed evaluations are derived from the catalog, not stored. Prototype: `metadata.modules` | -| `signed_at` | Fixed before the pipeline runs | The accounting clock; repeated in `pending` and `CommitEvent` | +| `catalog_hash`, `params_version`, `failed_open` | The Guardian signs the delta after modules ran | The configuration the modules ran with; `failed_open` lists module, layer and failure kind, omitted when empty. Allowed evaluations are derived from the catalog, not stored | +| `signed_at` | Fixed before the pipeline runs | RFC 3339; the accounting clock, sent as `accounting_time` and repeated in `pending` and `CommitEvent` (M2b) | | `submitter` | At signing | Verified signer commitment of the request being acked | -| `proposer` | At signing | From `ProposalContext`; empty when no matching proposal | -| `module_projection` | At signing, for every account, once any instance subscribes to `after_transaction_committed` (M2b) | Stored, never recomputed; a queued candidate without it puts subscribed modules for its account behind the activation fence | +| `proposer` | At signing | From `ProposalContext`; omitted when no proposal matched | +| `module_projection` | At signing, for every account, once any instance subscribes to `after_transaction_committed` (M2b) | Stored, never recomputed; a queued candidate without it, or without an approval record, puts subscribed modules for its account behind the activation fence | ### Proposal storage rule diff --git a/speckit/features/251-guardian-modules/tasks.md b/speckit/features/251-guardian-modules/tasks.md index a92217ec..5ff9a8eb 100644 --- a/speckit/features/251-guardian-modules/tasks.md +++ b/speckit/features/251-guardian-modules/tasks.md @@ -40,7 +40,7 @@ - [X] T006 [P] Add `MidenTransaction.reference_block`, optional `expiration_block` (absent when `expiration_delta` is 0) and `new_code_commitment` (from the delta's code patch) in `projection_from_summary`, `crates/server/src/network/miden/module_views.rs`; tests for each, including a summary with no expiration and one that replaces the account's code (P0 T088) - [X] T007 Add `HookRequest.submitter_session` from the resolved credential's auth format: pass it from `ResolvedAccount` through `ack_delta_internal::Submitter` (`crates/server/src/services/ack_delta_internal.rs`), `push_delta_proposal` and `configure_account` into `crates/server/src/modules/request.rs`; on the execution path carry it on `ExecutionJob` (`crates/server/src/services/execute_proposal/worker.rs`, `service.rs`) next to `requester`; tests for a wallet-signed and a session-signed push (P0 T093) - [X] T008 Dropped 2026-11-09 (RFC revision 27): `proposer_session` removed from protocol version 1 instead of stored, since a session key cannot approve a proposal and no catalog policy uses it; version 1 can add it later -- [ ] T009 Replace the prototype's `metadata.modules` approval record with the delta fields of `data-model.md` ("Delta additions"): module trace (`catalog_hash`, `params_version`, `failed_open`), `signed_at` (fixed before the pipeline runs and sent as `accounting_time`), `submitter` and `proposer`, written once at signing in `crates/server/src/services/ack_delta_internal.rs`; add them to `crates/server/src/delta_object.rs`, the Postgres `deltas` table through a new migration in `crates/server/migrations/_guardian_module_delta_fields/`, and the filesystem delta JSON; keep the dashboard delta detail showing the trace (`crates/server/src/services/dashboard_account_delta_detail.rs`); regenerate OpenAPI if the delta wire shape changes +- [X] T009 Record `signed_at` (fixed before the pipeline runs and sent as `accounting_time`), `submitter` and `proposer` with the approval trace (`catalog_hash`, `params_version`, `failed_open`) in `ModuleApproval` (`crates/server/src/delta_summary/mod.rs`), written at signing in `crates/server/src/services/ack_delta_internal.rs`; the pipeline returns only the configuration it ran with (`Evaluation`, `crates/server/src/modules/pipeline.rs`). Revised 2026-11-09: kept in `metadata.modules` instead of new delta columns, since delta metadata is already stored on both backends and served only on HTTP, so no migration and no wire change; `data-model.md` updated - [ ] T010 [P] Build account views from the single decode the push path already does: carry the view fields on `AppliedState` (`crates/server/src/network/mod.rs`, `crates/server/src/network/miden/mod.rs` `verify_and_apply_delta`) and use them in `crates/server/src/modules/request.rs` instead of a second `Account::from_json`; run proposal creation through `verify_and_apply_delta` when a module will be called (P0 T089) - [ ] T011 Measure the frozen extraction against real accounts, not only fixtures: add captured devnet accounts (single-key Falcon, single-key ECDSA, 2-of-3 Falcon, mixed-scheme multisig with a procedure override, an account after a code replacement) under `crates/server/src/testing/fixtures/` and assert the full `AccountView` and `MidenTransaction` for each in `crates/server/src/network/miden/module_views.rs` tests - [ ] T012 Mark protocol version 1 frozen: state it in the proto header of `crates/guardian-module-sdk/proto/guardian_module_v1.proto` and the contract copy, and record the freeze (commit and date) in RFC 0002 section 7 and Appendix C (`docs/rfcs/0002-guardian-modules.md`) From b22d733f9687fc7172585facb6d6fcd5db09688f Mon Sep 17 00:00:00 2001 From: Zeljko Date: Mon, 9 Nov 2026 09:53:53 +0100 Subject: [PATCH 010/105] perf(modules): build module account views from the decode that applies the delta (#251) NetworkClient::apply_delta_with_module_views verifies and applies a delta and returns the policy module views of its base and result; the Miden client builds both from the accounts it already decoded, where request assembly decoded the state JSON again for each view. The ack and proposal creation seed the plan's view cache with them, only when modules are configured, so a server without modules does no extra work. A view that cannot be extracted is not seeded and still fails the modules, never the push. The default implementation decodes separately, so other networks and test doubles behave as before. --- crates/server/src/modules/request.rs | 36 +++++-- crates/server/src/network/miden/mod.rs | 94 +++++++++++++++++-- .../server/src/network/miden/module_views.rs | 6 +- crates/server/src/network/mod.rs | 30 ++++++ .../server/src/services/ack_delta_internal.rs | 51 +++++++++- crates/server/src/services/push_delta.rs | 2 +- .../src/services/push_delta_proposal.rs | 8 +- .../features/251-guardian-modules/tasks.md | 2 +- 8 files changed, 204 insertions(+), 25 deletions(-) diff --git a/crates/server/src/modules/request.rs b/crates/server/src/modules/request.rs index 023080d2..1a0f52d7 100644 --- a/crates/server/src/modules/request.rs +++ b/crates/server/src/modules/request.rs @@ -72,13 +72,15 @@ impl ViewCache { return Ok(view.clone()); } let view = network.module_account_view(state.json)?; + self.insert(state.commitment, view.clone()); + Ok(view) + } + + fn insert(&self, commitment: &str, view: AccountView) { if let Ok(mut entries) = self.entries.lock() { let (views, order) = &mut *entries; - if views - .insert(state.commitment.to_string(), view.clone()) - .is_none() - { - order.push_back(state.commitment.to_string()); + if views.insert(commitment.to_string(), view).is_none() { + order.push_back(commitment.to_string()); if order.len() > VIEW_CACHE_CAPACITY && let Some(oldest) = order.pop_front() { @@ -86,7 +88,15 @@ impl ViewCache { } } } - Ok(view) + } + + /// Keeps `view` for `commitment` when it was built from an account already decoded, so request + /// assembly does not decode it again. A failed extraction is not kept: assembly then retries + /// it and the failure applies to the modules. + pub fn seed(&self, commitment: &str, view: Result) { + if let Ok(view) = view { + self.insert(commitment, view); + } } #[cfg(test)] @@ -378,6 +388,20 @@ mod tests { ); } + #[test] + fn a_seeded_view_is_used_without_decoding_and_a_failed_one_is_not_kept() { + let network = MockNetworkClient::new(); + let cache = ViewCache::default(); + cache.seed("0xc1", Ok(view_with("0xseeded"))); + assert_eq!( + cache.get_or_build(&network, state("0xc1")).unwrap(), + view_with("0xseeded") + ); + cache.seed("0xc2", Err("undecodable".into())); + assert!(cache.get_or_build(&network, state("0xc2")).is_err()); + assert_eq!(cache.len(), 1); + } + #[test] fn a_failed_decode_is_not_cached() { let network = MockNetworkClient::new(); diff --git a/crates/server/src/network/miden/mod.rs b/crates/server/src/network/miden/mod.rs index 67923b98..90243579 100644 --- a/crates/server/src/network/miden/mod.rs +++ b/crates/server/src/network/miden/mod.rs @@ -315,6 +315,27 @@ impl MidenNetworkClient { prev_account: Result, tx_summary: &TransactionSummary, ) -> Result { + Ok(Self::applied_state(&Self::applied_account( + prev_account, + tx_summary, + )?)) + } + + fn applied_state(account: &Account) -> AppliedState { + let inspector = MidenAccountInspector::new(account); + AppliedState { + commitment: format!("0x{}", hex::encode(account.to_commitment().as_bytes())), + nonce: Some(account.nonce().as_canonical_u64()), + cosigners: inspector.extract_chain_cosigners(), + guardian_commitment: inspector.extract_guardian_public_key(), + state_json: account.to_json(), + } + } + + fn applied_account( + prev_account: Result, + tx_summary: &TransactionSummary, + ) -> Result { let account_delta = tx_summary.account_delta(); let is_full_state = @@ -383,15 +404,7 @@ impl MidenNetworkClient { )?; account }; - - let inspector = MidenAccountInspector::new(&account); - Ok(AppliedState { - commitment: format!("0x{}", hex::encode(account.to_commitment().as_bytes())), - nonce: Some(account.nonce().as_canonical_u64()), - cosigners: inspector.extract_chain_cosigners(), - guardian_commitment: inspector.extract_guardian_public_key(), - state_json: account.to_json(), - }) + Ok(account) } } @@ -537,6 +550,26 @@ impl NetworkClient for MidenNetworkClient { Self::apply_summary(Ok(account), &tx_summary) } + fn apply_delta_with_module_views( + &self, + prev_commitment: Option<&str>, + prev_state_json: &serde_json::Value, + delta_payload: &serde_json::Value, + ) -> Result<(AppliedState, crate::network::ModuleViews), String> { + let tx_summary = TransactionSummary::from_json(delta_payload)?; + let account = Account::from_json(prev_state_json)?; + if let Some(prev_commitment) = prev_commitment { + Self::ensure_prev_commitment(&account, prev_commitment)?; + } + let before = module_views::account_view_of(&account); + let applied = Self::applied_account(Ok(account), &tx_summary)?; + let views = crate::network::ModuleViews { + before, + after: module_views::account_view_of(&applied), + }; + Ok((Self::applied_state(&applied), views)) + } + fn merge_deltas( &self, delta_payloads: Vec, @@ -2267,6 +2300,49 @@ mod tests { /// The push path and promotion read the post-delta auth bindings off /// `AppliedState` instead of decoding the stored blob again (issue /// #328), so they must equal what a fresh decode of that blob reads. + #[tokio::test] + async fn module_views_from_the_apply_decode_match_separate_decodes() { + let client = MidenNetworkClient::lazy_for_test(NetworkType::MidenTestnet); + let account_json: serde_json::Value = + serde_json::from_str(crate::testing::fixtures::ACCOUNT_JSON).unwrap(); + let delta_fixture: serde_json::Value = + serde_json::from_str(crate::testing::fixtures::DELTA_1_JSON).unwrap(); + let delta_payload = &delta_fixture["delta_payload"]; + let prev_commitment = format!( + "0x{}", + hex::encode( + Account::from_json(&account_json) + .unwrap() + .to_commitment() + .as_bytes() + ) + ); + + let (applied, views) = client + .apply_delta_with_module_views(Some(&prev_commitment), &account_json, delta_payload) + .unwrap(); + assert_eq!( + applied, + client + .verify_and_apply_delta(&prev_commitment, &account_json, delta_payload) + .unwrap() + ); + assert!(views.before.is_ok()); + assert_eq!(views.before, client.module_account_view(&account_json)); + // The fixture delta adds an approver key without its scheme entry, which the standard + // multisig always writes, so both paths must refuse the resulting view alike. + assert_eq!(views.after, client.module_account_view(&applied.state_json)); + let (unverified, _) = client + .apply_delta_with_module_views(None, &account_json, delta_payload) + .unwrap(); + assert_eq!(unverified, applied); + assert!( + client + .apply_delta_with_module_views(Some("0xnot_the_base"), &account_json, delta_payload) + .is_err() + ); + } + #[tokio::test] async fn verify_and_apply_delta_matches_separate_passes() { let client = MidenNetworkClient::lazy_for_test(NetworkType::MidenTestnet); diff --git a/crates/server/src/network/miden/module_views.rs b/crates/server/src/network/miden/module_views.rs index 80f5fba1..2fa9ee3e 100644 --- a/crates/server/src/network/miden/module_views.rs +++ b/crates/server/src/network/miden/module_views.rs @@ -29,7 +29,11 @@ fn felt_u32(felt: miden_protocol::Felt) -> Result { /// verified auth configuration. A signer whose scheme entry is missing or names no supported /// scheme is an error, never a signer without a scheme. pub fn account_view(state_json: &serde_json::Value) -> Result { - let account = Account::from_json(state_json)?; + account_view_of(&Account::from_json(state_json)?) +} + +/// [`account_view`] of an account already decoded. +pub fn account_view_of(account: &Account) -> Result { let storage = account.storage(); let code = account.code(); let procedure_roots: Vec = code.procedure_roots().map(|root| word_hex(&root)).collect(); diff --git a/crates/server/src/network/mod.rs b/crates/server/src/network/mod.rs index f0da34af..8f5ea12d 100644 --- a/crates/server/src/network/mod.rs +++ b/crates/server/src/network/mod.rs @@ -236,6 +236,13 @@ pub struct TransactionSearch { /// plus the commitment, nonce, and auth bindings of the account it encodes, /// read off the account the method already holds so a caller persisting or /// inspecting the state never decodes the blob again (issue #328). +/// Policy module account views of a delta's base state and of the state it produces. +#[derive(Debug, Clone)] +pub struct ModuleViews { + pub before: Result, + pub after: Result, +} + #[derive(Debug, Clone, PartialEq)] pub struct AppliedState { pub state_json: serde_json::Value, @@ -347,6 +354,29 @@ pub trait NetworkClient: Send + Sync { delta_payload: &serde_json::Value, ) -> Result; + /// [`Self::verify_and_apply_delta`] when `prev_commitment` is set, otherwise + /// [`Self::apply_delta`], with the policy module views of the base and of the result built + /// from the same decode. A view that cannot be extracted is returned as its error, never as + /// a failure of the application. + fn apply_delta_with_module_views( + &self, + prev_commitment: Option<&str>, + prev_state_json: &serde_json::Value, + delta_payload: &serde_json::Value, + ) -> Result<(AppliedState, ModuleViews), String> { + let applied = match prev_commitment { + Some(prev_commitment) => { + self.verify_and_apply_delta(prev_commitment, prev_state_json, delta_payload)? + } + None => self.apply_delta(prev_state_json, delta_payload)?, + }; + let views = ModuleViews { + before: self.module_account_view(prev_state_json), + after: self.module_account_view(&applied.state_json), + }; + Ok((applied, views)) + } + /// Merge multiple deltas fn merge_deltas( &self, diff --git a/crates/server/src/services/ack_delta_internal.rs b/crates/server/src/services/ack_delta_internal.rs index b3f55f73..f7f48136 100644 --- a/crates/server/src/services/ack_delta_internal.rs +++ b/crates/server/src/services/ack_delta_internal.rs @@ -9,7 +9,7 @@ use crate::error::Result; use crate::metadata::AccountMetadata; use crate::modules::HookName; use crate::modules::request::{self, StateRef, TransactionInput}; -use crate::network::AppliedState; +use crate::network::{AppliedState, ModuleViews}; use crate::state::AppState; /// A delta verified against the account's current state and acknowledged by Guardian, not yet @@ -56,20 +56,43 @@ pub(crate) async fn acknowledge_delta( .await } +/// A delta applied to the state it builds on, with the policy module views of both states when +/// modules are configured, built from the same decode. +pub(crate) struct Applied { + pub state: AppliedState, + pub views: Option, +} + /// Verifies `delta` against the state it builds on and applies it, without signing anything. pub(crate) async fn apply_to_base( state: &AppState, base_commitment: &str, base_state_json: &serde_json::Value, delta: &DeltaObject, -) -> Result { +) -> Result { let client = state.network_client.clone(); let prev_commitment = base_commitment.to_string(); let prev_state_json = base_state_json.clone(); let delta_payload = Arc::new(delta.delta_payload.clone()); + let with_views = state.modules.is_some(); crate::network::reconstructor() .run(move || { - client.verify_and_apply_delta(&prev_commitment, &prev_state_json, &delta_payload) + if with_views { + client + .apply_delta_with_module_views( + Some(&prev_commitment), + &prev_state_json, + &delta_payload, + ) + .map(|(state, views)| Applied { + state, + views: Some(views), + }) + } else { + client + .verify_and_apply_delta(&prev_commitment, &prev_state_json, &delta_payload) + .map(|state| Applied { state, views: None }) + } }) .await .map_err(Into::into) @@ -84,11 +107,24 @@ pub(crate) async fn acknowledge_applied( scheme: &SignatureScheme, base: StateRef<'_>, delta: &DeltaObject, - applied: AppliedState, + applied: Applied, submitter: Submitter<'_>, proposal_match: &ProposalMatch, ) -> Result { - let approval = approve(state, base, delta, &applied, submitter, proposal_match).await?; + let Applied { + state: applied, + views, + } = applied; + let approval = approve( + state, + base, + delta, + &applied, + views, + submitter, + proposal_match, + ) + .await?; let matching_proposal = proposal_match.payload(); let mut derived_metadata = crate::delta_summary::build_metadata(&delta.delta_payload, matching_proposal); @@ -124,6 +160,7 @@ async fn approve( base: StateRef<'_>, delta: &DeltaObject, applied: &AppliedState, + module_views: Option, submitter: Submitter<'_>, proposal_match: &ProposalMatch, ) -> Result> { @@ -149,6 +186,10 @@ async fn approve( .unwrap_or_default(); let signed_at = state.clock.now(); let views = plan.views(); + if let Some(module_views) = module_views { + views.seed(base.commitment, module_views.before); + views.seed(&applied.commitment, module_views.after); + } plan.run(|| { request::transaction_request( state.network_client.as_ref(), diff --git a/crates/server/src/services/push_delta.rs b/crates/server/src/services/push_delta.rs index 24be7078..9c8ae153 100644 --- a/crates/server/src/services/push_delta.rs +++ b/crates/server/src/services/push_delta.rs @@ -192,7 +192,7 @@ pub async fn push_delta(state: &AppState, params: PushDeltaParams) -> Result (None, true), }; if let Some(plan) = plan { - let after = { + let (after, module_views) = { let client = state.network_client.clone(); let tail_state_json = tail.state_json.clone(); let tx_summary = tx_summary.clone(); crate::network::reconstructor() - .run(move || client.apply_delta(&tail_state_json, &tx_summary)) + .run(move || { + client.apply_delta_with_module_views(None, &tail_state_json, &tx_summary) + }) .await? }; let proposal = ProposalContext { @@ -378,6 +380,8 @@ async fn propose(state: &AppState, params: PushDeltaProposalParams, mode: Mode) .unwrap_or(serde_json::Value::Null), }; let views = plan.views(); + views.seed(&tail.commitment, module_views.before); + views.seed(&after.commitment, module_views.after); plan.run(|| { request::transaction_request( state.network_client.as_ref(), diff --git a/speckit/features/251-guardian-modules/tasks.md b/speckit/features/251-guardian-modules/tasks.md index 5ff9a8eb..c33e69aa 100644 --- a/speckit/features/251-guardian-modules/tasks.md +++ b/speckit/features/251-guardian-modules/tasks.md @@ -41,7 +41,7 @@ - [X] T007 Add `HookRequest.submitter_session` from the resolved credential's auth format: pass it from `ResolvedAccount` through `ack_delta_internal::Submitter` (`crates/server/src/services/ack_delta_internal.rs`), `push_delta_proposal` and `configure_account` into `crates/server/src/modules/request.rs`; on the execution path carry it on `ExecutionJob` (`crates/server/src/services/execute_proposal/worker.rs`, `service.rs`) next to `requester`; tests for a wallet-signed and a session-signed push (P0 T093) - [X] T008 Dropped 2026-11-09 (RFC revision 27): `proposer_session` removed from protocol version 1 instead of stored, since a session key cannot approve a proposal and no catalog policy uses it; version 1 can add it later - [X] T009 Record `signed_at` (fixed before the pipeline runs and sent as `accounting_time`), `submitter` and `proposer` with the approval trace (`catalog_hash`, `params_version`, `failed_open`) in `ModuleApproval` (`crates/server/src/delta_summary/mod.rs`), written at signing in `crates/server/src/services/ack_delta_internal.rs`; the pipeline returns only the configuration it ran with (`Evaluation`, `crates/server/src/modules/pipeline.rs`). Revised 2026-11-09: kept in `metadata.modules` instead of new delta columns, since delta metadata is already stored on both backends and served only on HTTP, so no migration and no wire change; `data-model.md` updated -- [ ] T010 [P] Build account views from the single decode the push path already does: carry the view fields on `AppliedState` (`crates/server/src/network/mod.rs`, `crates/server/src/network/miden/mod.rs` `verify_and_apply_delta`) and use them in `crates/server/src/modules/request.rs` instead of a second `Account::from_json`; run proposal creation through `verify_and_apply_delta` when a module will be called (P0 T089) +- [X] T010 [P] Build account views from the single decode the push path already does: carry the view fields on `AppliedState` (`crates/server/src/network/mod.rs`, `crates/server/src/network/miden/mod.rs` `verify_and_apply_delta`) and use them in `crates/server/src/modules/request.rs` instead of a second `Account::from_json`; run proposal creation through `verify_and_apply_delta` when a module will be called (P0 T089) - [ ] T011 Measure the frozen extraction against real accounts, not only fixtures: add captured devnet accounts (single-key Falcon, single-key ECDSA, 2-of-3 Falcon, mixed-scheme multisig with a procedure override, an account after a code replacement) under `crates/server/src/testing/fixtures/` and assert the full `AccountView` and `MidenTransaction` for each in `crates/server/src/network/miden/module_views.rs` tests - [ ] T012 Mark protocol version 1 frozen: state it in the proto header of `crates/guardian-module-sdk/proto/guardian_module_v1.proto` and the contract copy, and record the freeze (commit and date) in RFC 0002 section 7 and Appendix C (`docs/rfcs/0002-guardian-modules.md`) From b5fbd802daae75bf94c64249ed378df9753af433 Mon Sep 17 00:00:00 2001 From: Zeljko Date: Mon, 9 Nov 2026 09:56:03 +0100 Subject: [PATCH 011/105] test(modules): account views of accounts built from the standard components (#251) Single-key Falcon and ECDSA accounts, a 2-of-3 Falcon guarded multisig, and a mixed-scheme guarded multisig with a procedure override, built with the miden-standards components, read back as built: signers in order with their schemes, thresholds, code commitment and procedure roots. An override on the auth procedure, which the upstream builder accepts but which changes nothing on chain, is left out. --- .../server/src/network/miden/module_views.rs | 131 ++++++++++++++++++ .../features/251-guardian-modules/tasks.md | 2 +- 2 files changed, 132 insertions(+), 1 deletion(-) diff --git a/crates/server/src/network/miden/module_views.rs b/crates/server/src/network/miden/module_views.rs index 2fa9ee3e..5384a570 100644 --- a/crates/server/src/network/miden/module_views.rs +++ b/crates/server/src/network/miden/module_views.rs @@ -594,3 +594,134 @@ mod tests { println!("account_view: {view:?} per call, tx_projection: {projection:?} per call"); } } + +#[cfg(test)] +mod standard_account_tests { + use guardian_shared::SignatureScheme::{self, Ecdsa, Falcon}; + use guardian_shared::ToJson; + use miden_protocol::account::Account; + + use super::*; + use crate::testing::helpers::{build_guarded_multisig_account, build_single_key_account}; + + fn key(n: u32) -> Word { + Word::from([n, n + 1, n + 2, n + 3]) + } + + fn assert_code_fields(view: &AccountView, account: &Account) { + assert_eq!(view.code_commitment, word_hex(&account.code().commitment())); + assert_eq!( + view.procedure_roots, + account + .code() + .procedure_roots() + .map(|root| word_hex(&root)) + .collect::>() + ); + } + + fn guarded_multisig_with_overrides( + seed: [u8; 32], + threshold: u32, + approvers: &[(Word, SignatureScheme)], + guardian: (Word, SignatureScheme), + overrides: impl Fn(&Account) -> Vec<(miden_protocol::account::AccountProcedureRoot, u32)>, + ) -> Account { + use miden_protocol::account::AccountBuilder; + use miden_protocol::account::auth::PublicKeyCommitment; + use miden_standards::account::auth::{ + Approver, ApproverSet, AuthGuardedMultisigConfig, GuardianConfig, + }; + use miden_standards::account::wallets::BasicWallet; + + let plain = build_guarded_multisig_account(seed, threshold, approvers, guardian); + let approver = |(commitment, scheme): (Word, SignatureScheme)| { + Approver::new(PublicKeyCommitment::from(commitment), scheme.auth_scheme()) + }; + let config = AuthGuardedMultisigConfig::new( + ApproverSet::new(approvers.iter().copied().map(approver).collect(), threshold).unwrap(), + GuardianConfig::new(approver(guardian)), + ) + .unwrap() + .with_proc_thresholds(overrides(&plain)) + .unwrap(); + AccountBuilder::new(seed) + .with_component(miden_protocol::account::AccountComponent::from( + AuthGuardedMultisig::new(config).unwrap(), + )) + .with_component(BasicWallet) + .build() + .unwrap() + } + + #[test] + fn single_key_accounts_carry_their_code_and_leave_the_signer_to_the_registration() { + for scheme in [Falcon, Ecdsa] { + let account = build_single_key_account([1; 32], (key(9), scheme)); + let view = account_view(&account.to_json()).unwrap(); + assert!(view.signer_commitments.is_empty()); + assert!(view.signer_schemes.is_empty()); + assert_eq!(view.default_threshold, None); + assert!(view.procedure_thresholds.is_empty()); + assert_code_fields(&view, &account); + } + } + + #[test] + fn a_two_of_three_falcon_multisig_reads_back_as_built() { + let approvers = [(key(1), Falcon), (key(2), Falcon), (key(3), Falcon)]; + let account = build_guarded_multisig_account([2; 32], 2, &approvers, (key(7), Falcon)); + let view = account_view(&account.to_json()).unwrap(); + assert_eq!( + view.signer_commitments, + approvers + .iter() + .map(|(commitment, _)| word_hex(commitment)) + .collect::>() + ); + assert_eq!(view.signer_schemes.len(), 3); + assert!( + view.signer_schemes + .values() + .all(|scheme| scheme == "falcon") + ); + assert_eq!(view.default_threshold, Some(2)); + assert!(view.procedure_thresholds.is_empty()); + assert_code_fields(&view, &account); + } + + #[test] + fn a_mixed_scheme_multisig_keeps_each_scheme_and_its_effective_override() { + let approvers = [(key(1), Falcon), (key(2), Ecdsa), (key(3), Falcon)]; + let account = + guarded_multisig_with_overrides([3; 32], 2, &approvers, (key(7), Ecdsa), |plain| { + vec![(plain.code().procedures()[1], 1)] + }); + let view = account_view(&account.to_json()).unwrap(); + for (commitment, scheme) in approvers { + assert_eq!( + view.signer_schemes + .get(&word_hex(&commitment)) + .map(String::as_str), + Some(scheme.as_str()) + ); + } + let overridden = Word::from(account.code().procedures()[1]); + assert_eq!( + view.procedure_thresholds, + [(word_hex(&overridden), 1)].into() + ); + assert_code_fields(&view, &account); + } + + #[test] + fn an_override_on_the_auth_procedure_changes_nothing_and_is_left_out() { + let approvers = [(key(1), Falcon), (key(2), Falcon)]; + let account = + guarded_multisig_with_overrides([4; 32], 2, &approvers, (key(7), Falcon), |plain| { + vec![(plain.code().procedures()[0], 1)] + }); + let view = account_view(&account.to_json()).unwrap(); + assert!(view.procedure_thresholds.is_empty()); + } +} diff --git a/speckit/features/251-guardian-modules/tasks.md b/speckit/features/251-guardian-modules/tasks.md index c33e69aa..ab88ee54 100644 --- a/speckit/features/251-guardian-modules/tasks.md +++ b/speckit/features/251-guardian-modules/tasks.md @@ -42,7 +42,7 @@ - [X] T008 Dropped 2026-11-09 (RFC revision 27): `proposer_session` removed from protocol version 1 instead of stored, since a session key cannot approve a proposal and no catalog policy uses it; version 1 can add it later - [X] T009 Record `signed_at` (fixed before the pipeline runs and sent as `accounting_time`), `submitter` and `proposer` with the approval trace (`catalog_hash`, `params_version`, `failed_open`) in `ModuleApproval` (`crates/server/src/delta_summary/mod.rs`), written at signing in `crates/server/src/services/ack_delta_internal.rs`; the pipeline returns only the configuration it ran with (`Evaluation`, `crates/server/src/modules/pipeline.rs`). Revised 2026-11-09: kept in `metadata.modules` instead of new delta columns, since delta metadata is already stored on both backends and served only on HTTP, so no migration and no wire change; `data-model.md` updated - [X] T010 [P] Build account views from the single decode the push path already does: carry the view fields on `AppliedState` (`crates/server/src/network/mod.rs`, `crates/server/src/network/miden/mod.rs` `verify_and_apply_delta`) and use them in `crates/server/src/modules/request.rs` instead of a second `Account::from_json`; run proposal creation through `verify_and_apply_delta` when a module will be called (P0 T089) -- [ ] T011 Measure the frozen extraction against real accounts, not only fixtures: add captured devnet accounts (single-key Falcon, single-key ECDSA, 2-of-3 Falcon, mixed-scheme multisig with a procedure override, an account after a code replacement) under `crates/server/src/testing/fixtures/` and assert the full `AccountView` and `MidenTransaction` for each in `crates/server/src/network/miden/module_views.rs` tests +- [X] T011 Measure the frozen extraction against real account layouts, not only synthetic slots: views of accounts built from the upstream `miden-standards` components (single-key Falcon and ECDSA, 2-of-3 Falcon guarded multisig, mixed-scheme guarded multisig with a procedure override, an override on the auth procedure) asserted in `crates/server/src/network/miden/module_views.rs` (`standard_account_tests`); the code-replacement projection is covered by the `new_code_commitment` test. Revised 2026-11-09: built from the real components instead of captured from devnet, which needs funded accounts; a devnet capture remains for the T059 walk-through. Found: the `DELTA_1` fixture adds an approver key without its scheme entry, which the standard multisig always writes, so its resulting view is refused - [ ] T012 Mark protocol version 1 frozen: state it in the proto header of `crates/guardian-module-sdk/proto/guardian_module_v1.proto` and the contract copy, and record the freeze (commit and date) in RFC 0002 section 7 and Appendix C (`docs/rfcs/0002-guardian-modules.md`) **Checkpoint**: requests carry the complete version 1 surface, measured on real accounts. User story phases can start in parallel. From 64135d2880193727a496e20c11fa3ed73dcf69f3 Mon Sep 17 00:00:00 2001 From: Zeljko Date: Mon, 9 Nov 2026 10:01:02 +0100 Subject: [PATCH 012/105] chore(modules): Phase 2 checkpoint, freeze deferred to its remaining criteria (#251) Generated protocol code allows clippy's large_enum_variant: the HookRequest subject oneof is generated by prost. The protocol version 1 freeze (T012) now follows the criteria that are behaviour rather than fields: the dry run with approval instances, the lost-claim registration and the basic-policy code allowlist. --- crates/guardian-module-sdk/src/lib.rs | 1 + speckit/features/251-guardian-modules/tasks.md | 10 +++++----- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/crates/guardian-module-sdk/src/lib.rs b/crates/guardian-module-sdk/src/lib.rs index 5cc1d3c4..ae9a69c9 100644 --- a/crates/guardian-module-sdk/src/lib.rs +++ b/crates/guardian-module-sdk/src/lib.rs @@ -10,6 +10,7 @@ pub mod serve; pub use prost_types; pub use secrecy; +#[allow(clippy::large_enum_variant)] pub mod proto { tonic::include_proto!("guardian.module.v1"); } diff --git a/speckit/features/251-guardian-modules/tasks.md b/speckit/features/251-guardian-modules/tasks.md index ab88ee54..d8e94b71 100644 --- a/speckit/features/251-guardian-modules/tasks.md +++ b/speckit/features/251-guardian-modules/tasks.md @@ -43,9 +43,9 @@ - [X] T009 Record `signed_at` (fixed before the pipeline runs and sent as `accounting_time`), `submitter` and `proposer` with the approval trace (`catalog_hash`, `params_version`, `failed_open`) in `ModuleApproval` (`crates/server/src/delta_summary/mod.rs`), written at signing in `crates/server/src/services/ack_delta_internal.rs`; the pipeline returns only the configuration it ran with (`Evaluation`, `crates/server/src/modules/pipeline.rs`). Revised 2026-11-09: kept in `metadata.modules` instead of new delta columns, since delta metadata is already stored on both backends and served only on HTTP, so no migration and no wire change; `data-model.md` updated - [X] T010 [P] Build account views from the single decode the push path already does: carry the view fields on `AppliedState` (`crates/server/src/network/mod.rs`, `crates/server/src/network/miden/mod.rs` `verify_and_apply_delta`) and use them in `crates/server/src/modules/request.rs` instead of a second `Account::from_json`; run proposal creation through `verify_and_apply_delta` when a module will be called (P0 T089) - [X] T011 Measure the frozen extraction against real account layouts, not only synthetic slots: views of accounts built from the upstream `miden-standards` components (single-key Falcon and ECDSA, 2-of-3 Falcon guarded multisig, mixed-scheme guarded multisig with a procedure override, an override on the auth procedure) asserted in `crates/server/src/network/miden/module_views.rs` (`standard_account_tests`); the code-replacement projection is covered by the `new_code_commitment` test. Revised 2026-11-09: built from the real components instead of captured from devnet, which needs funded accounts; a devnet capture remains for the T059 walk-through. Found: the `DELTA_1` fixture adds an approver key without its scheme entry, which the standard multisig always writes, so its resulting view is refused -- [ ] T012 Mark protocol version 1 frozen: state it in the proto header of `crates/guardian-module-sdk/proto/guardian_module_v1.proto` and the contract copy, and record the freeze (commit and date) in RFC 0002 section 7 and Appendix C (`docs/rfcs/0002-guardian-modules.md`) +- [ ] T012 Mark protocol version 1 frozen: state it in the proto header of `crates/guardian-module-sdk/proto/guardian_module_v1.proto` and the contract copy, and record the freeze (commit and date) in RFC 0002 section 7 and Appendix C (`docs/rfcs/0002-guardian-modules.md`). Runs last among the freeze criteria (RFC 0002 section 7): after T019 and T020 (dry run with approval instances), T024 (lost claim) and T025 (`code_check`), which use fields already in the proto but must be implemented with tests before the freeze -**Checkpoint**: requests carry the complete version 1 surface, measured on real accounts. User story phases can start in parallel. +**Checkpoint**: requests carry the complete version 1 surface, measured on real account layouts (T003 to T011). User story phases can start in parallel. T012, the freeze itself, waits for the behaviour-only freeze criteria in US2 and US3. --- @@ -207,8 +207,8 @@ ### Phase dependencies - **Setup (T001, T002)** first. -- **Foundational (T003 to T012)** blocks every story. T003 first (it renumbers the proto); T004, T005, T006 and T010 then run in parallel; T007 and T008 after T003; T009 after T007 (it stores `submitter` and `proposer`); T011 after T005 and T006; T012 last. -- **Stories** start after T012 and are independent of each other, with these exceptions: T030 (budget on writes) needs T028; T039 and T040 (`default` copy) touch `configure_account.rs` after T024, so run US3 before US5 or coordinate the file; T021 needs the `guardian-client` dependency decision. +- **Foundational (T003 to T011)** blocks every story; T012 (the freeze) follows the freeze criteria in US2 and US3. T003 first (it renumbers the proto); T004, T005, T006 and T010 then run in parallel; T007 and T008 after T003; T009 after T007 (it stores `submitter` and `proposer`); T011 after T005 and T006; T012 after T019, T020, T024 and T025. +- **Stories** start after T011 and are independent of each other, with these exceptions: T030 (budget on writes) needs T028; T039 and T040 (`default` copy) touch `configure_account.rs` after T024, so run US3 before US5 or coordinate the file; T021 needs the `guardian-client` dependency decision. - **Polish (T052 to T062)** after the stories it documents; T061 and T062 last. ### User story dependencies @@ -235,7 +235,7 @@ T005 code fields in views (network/miden/module_views.rs, view half) T006 projection fields (network/miden/module_views.rs, projection half; coordinate with T005) T010 single decode (network/mod.rs, network/miden/mod.rs) -# Stories, after T012, one developer each: +# Stories, after T011, one developer each: US4 T028 to T036 (modules/budget.rs, breaker.rs, metrics.rs) US6 T047 to T051 (guardian-module-sdk, examples/policy-module) US2 T019 to T022 (pipeline dry run, TypeScript multisig) From 0b42358d891a16f69ca21e206acad6cd83c2aa56 Mon Sep 17 00:00:00 2001 From: Zeljko Date: Mon, 9 Nov 2026 10:03:10 +0100 Subject: [PATCH 013/105] docs(speckit): develop M2a on one branch, cut layer branches when needed (#251) --- speckit/features/251-guardian-modules/plan.md | 3 +++ speckit/features/251-guardian-modules/tasks.md | 3 +++ 2 files changed, 6 insertions(+) diff --git a/speckit/features/251-guardian-modules/plan.md b/speckit/features/251-guardian-modules/plan.md index e15f47e9..9ab0f23d 100644 --- a/speckit/features/251-guardian-modules/plan.md +++ b/speckit/features/251-guardian-modules/plan.md @@ -136,6 +136,9 @@ Per AGENTS.md, published crates and packages document new public API in their ow ## M2a delivery +**Decision (2026-11-09)**: M2a is developed on one branch, `251-modules-m2a`. The layer split below was built and checked once and is kept as a recipe; reviewable branches are cut from `251-modules-m2a` by layer when needed, not maintained alongside it. + + The prototype (#554) is one draft of about 13,000 lines and is not merged as it is. M2a starts from it and ships as a stack of pull requests off `main`, each building and passing its tests on its own, in this order: | Layer | Branch | Content | diff --git a/speckit/features/251-guardian-modules/tasks.md b/speckit/features/251-guardian-modules/tasks.md index d8e94b71..82dd103c 100644 --- a/speckit/features/251-guardian-modules/tasks.md +++ b/speckit/features/251-guardian-modules/tasks.md @@ -264,4 +264,7 @@ Foundational, then US1: the frozen protocol and a mandatory policy enforced on e ### Delivery as stacked PRs +Decision 2026-11-09: all M2a work lands on `251-modules-m2a`; layer branches are cut from it when review needs them, following the recipe below. + + The prototype is one 13,000-line draft (#554). M2a ships as a stack of five PRs off `main`, each building and testing on its own, the way the PR #510 review stack was layered by path. The layers, their branches and what each contains are in [plan.md](./plan.md), "M2a delivery": module SDK, server core, hooks, clients, docs. New M2a work goes to the layer it belongs to: Phase 2 proto tasks and US6 to the SDK layer; US4 and the operator routes of US5 to server core; US1, US3 and the server half of US2 to hooks; the client halves of US2 and US5 to clients; Polish docs to docs. From ab0a8a414a710462c5cae7923020f162d7ec1bc3 Mon Sep 17 00:00:00 2001 From: Zeljko Date: Mon, 9 Nov 2026 10:07:08 +0100 Subject: [PATCH 014/105] test(modules): mandatory policy acceptance on every approval path (#251) A real basic-policy cap refuses a payment over it through a stored proposal, through an offline push without one, and under a misleading proposal label, storing nothing; a Guardian execution over it ends GUARDIAN_EXECUTION_MODULE_DENIED before anything is proved. Without a catalog a push builds no view or projection and records no approval. --- .../src/services/execute_proposal/tests.rs | 61 +++++- crates/server/src/services/push_delta.rs | 188 +++++++++++++++++- crates/server/src/testing/mocks.rs | 6 + .../features/251-guardian-modules/tasks.md | 4 +- 4 files changed, 239 insertions(+), 20 deletions(-) diff --git a/crates/server/src/services/execute_proposal/tests.rs b/crates/server/src/services/execute_proposal/tests.rs index 1e0032f9..a489a2ae 100644 --- a/crates/server/src/services/execute_proposal/tests.rs +++ b/crates/server/src/services/execute_proposal/tests.rs @@ -1200,20 +1200,28 @@ async fn gated( client_reason: crate::modules::catalog::ClientReason, ) -> Fixture { use crate::modules::catalog::HookName; - use crate::modules::testing::{instance, pipeline}; - let mut f = Fixture::new(Script::default()).await; - let _ = f.chain.clone().with_module_views( - guardian_module_sdk::AccountView::default(), - guardian_module_sdk::MidenTransaction::default(), - ); - let mut caps = instance( + let mut caps = crate::modules::testing::instance( "caps", &[HookName::BeforeTransactionApproved], on_error, module, ); caps.config.client_reason = client_reason; - f.state.modules = Some(pipeline(vec![caps])); + gated_by(caps, guardian_module_sdk::MidenTransaction::default()).await +} + +/// A fixture whose account is evaluated by `module`, the executed transaction's decoded effect +/// being `projection`. +async fn gated_by( + module: crate::modules::registry::Instance, + projection: guardian_module_sdk::MidenTransaction, +) -> Fixture { + let mut f = Fixture::new(Script::default()).await; + let _ = f + .chain + .clone() + .with_module_views(guardian_module_sdk::AccountView::default(), projection); + f.state.modules = Some(crate::modules::testing::pipeline(vec![module])); f } @@ -1323,3 +1331,40 @@ async fn an_approving_module_lets_the_execution_through_and_is_recorded_on_the_d "the approval is recorded on the acknowledged delta" ); } + +#[tokio::test] +async fn a_guardian_execution_over_a_mandatory_cap_is_refused_before_anything_is_proved() { + use guardian_shared::execution::ModuleDenial; + const USDC: &str = "0xaa00"; + let cap = crate::modules::testing::instance_with_params( + "caps", + &[crate::modules::catalog::HookName::BeforeTransactionApproved], + Arc::new(guardian_module_sdk::basic_policy::BasicPolicy), + serde_json::json!({ "max_amount_per_tx": { USDC: "1000" } }), + ); + let paying_5000 = guardian_module_sdk::MidenTransaction { + output_notes: vec![guardian_module_sdk::OutputNote { + note_id: "0xnote".into(), + assets: vec![guardian_module_sdk::Asset { + faucet_id: USDC.into(), + value: Some(guardian_module_sdk::proto::asset::Value::FungibleAmount( + "5000".into(), + )), + }], + p2id_target: Some("0xrecipient".into()), + ..Default::default() + }], + ..Default::default() + }; + let f = gated_by(cap, paying_5000).await; + assert_eq!( + failed_with(&f).await, + ExecutionFailureCode::ModuleDenied(ModuleDenial { + module: Some("caps".into()), + reason_code: "amount_cap_exceeded".into(), + layer: Some("global".into()), + client_message: None, + }) + ); + assert_eq!(f.calls.lock().unwrap().submitted, 0, "nothing is submitted"); +} diff --git a/crates/server/src/services/push_delta.rs b/crates/server/src/services/push_delta.rs index 9c8ae153..182d4808 100644 --- a/crates/server/src/services/push_delta.rs +++ b/crates/server/src/services/push_delta.rs @@ -2157,8 +2157,41 @@ mod tests { proposal: impl FnOnce(&str) -> std::result::Result, on_error: crate::modules::catalog::OnError, ) -> (Result, MockStorageBackend, String) { + push_through( + crate::modules::testing::instance( + "caps", + &[HookName::BeforeTransactionApproved], + on_error, + module, + ), + guardian_module_sdk::MidenTransaction::default(), + proposal, + ) + .await + } + + /// Pushes a delta whose decoded effect is `projection` to a Guardian running `module`. + async fn push_through( + module: crate::modules::registry::Instance, + projection: guardian_module_sdk::MidenTransaction, + proposal: impl FnOnce(&str) -> std::result::Result, + ) -> (Result, MockStorageBackend, String) { + let (result, storage, signer, _) = push_on(Some(module), projection, proposal).await; + (result, storage, signer) + } + + async fn push_on( + module: Option, + projection: guardian_module_sdk::MidenTransaction, + proposal: impl FnOnce(&str) -> std::result::Result, + ) -> ( + Result, + MockStorageBackend, + String, + MockNetworkClient, + ) { use crate::delta_object::DeltaStatus; - use crate::modules::testing::{instance, pipeline}; + use crate::modules::testing::pipeline; use crate::state_object::StateObject; use crate::testing::helpers::create_test_delta_payload; @@ -2191,7 +2224,7 @@ mod tests { signer_commitments: vec![signer_commitment.clone()], ..Default::default() }, - guardian_module_sdk::MidenTransaction::default(), + projection, ); let metadata = MockMetadataStore::new().with_get(Ok(Some(AccountMetadata { account_id: account_id.clone(), @@ -2208,15 +2241,10 @@ mod tests { }))); let mut state = create_test_app_state_with_mocks( Arc::new(storage.clone()), - Arc::new(network), + Arc::new(network.clone()), Arc::new(metadata), ); - state.modules = Some(pipeline(vec![instance( - "caps", - &[HookName::BeforeTransactionApproved], - on_error, - module, - )])); + state.modules = module.map(|module| pipeline(vec![module])); let params = PushDeltaParams { delta: DeltaObject { account_id: account_id.clone(), @@ -2232,7 +2260,147 @@ mod tests { }, credentials: Credentials::signature(signer_pubkey, signer_signature, signer_timestamp), }; - (push_delta(&state, params).await, storage, signer_commitment) + ( + push_delta(&state, params).await, + storage, + signer_commitment, + network, + ) + } + + #[tokio::test] + async fn without_modules_a_push_builds_no_view_or_projection_and_records_no_approval() { + let (result, storage, _, network) = + push_on(None, paying(5_000), stored_proposal_labelled("p2id")).await; + let pushed = result.expect("acknowledged as before modules existed"); + assert_eq!(storage.get_submit_delta_calls().len(), 1); + assert_eq!( + network + .module_decodes + .load(std::sync::atomic::Ordering::SeqCst), + 0 + ); + assert!( + pushed + .delta + .metadata + .is_none_or(|metadata| metadata.modules.is_none()) + ); + let (_, _, _, gated) = push_on( + Some(cap_of_1000()), + paying(500), + stored_proposal_labelled("p2id"), + ) + .await; + assert!( + gated + .module_decodes + .load(std::sync::atomic::Ordering::SeqCst) + > 0, + "the same push with a module does build them" + ); + } + + const USDC: &str = "0xaa00"; + + fn cap_of_1000() -> crate::modules::registry::Instance { + crate::modules::testing::instance_with_params( + "caps", + &[HookName::BeforeTransactionApproved], + Arc::new(guardian_module_sdk::basic_policy::BasicPolicy), + serde_json::json!({ "max_amount_per_tx": { USDC: "1000" } }), + ) + } + + fn paying(amount: u64) -> guardian_module_sdk::MidenTransaction { + guardian_module_sdk::MidenTransaction { + output_notes: vec![guardian_module_sdk::OutputNote { + note_id: "0xnote".into(), + assets: vec![guardian_module_sdk::Asset { + faucet_id: USDC.into(), + value: Some(guardian_module_sdk::proto::asset::Value::FungibleAmount( + amount.to_string(), + )), + }], + p2id_target: Some("0xrecipient".into()), + ..Default::default() + }], + ..Default::default() + } + } + + fn stored_proposal_labelled( + proposal_type: &'static str, + ) -> impl FnOnce(&str) -> std::result::Result { + move |account_id| { + Ok(DeltaObject { + account_id: account_id.to_string(), + nonce: 1, + status: crate::delta_object::DeltaStatus::Pending { + timestamp: "2026-05-25T08:00:00Z".into(), + proposer_id: "0xproposer".into(), + cosigner_sigs: Vec::new(), + }, + delta_payload: serde_json::json!({ "metadata": { "proposal_type": proposal_type } }), + ..Default::default() + }) + } + } + + fn no_stored_proposal(_: &str) -> std::result::Result { + Err("proposal not found".to_string()) + } + + fn assert_refused_by_the_cap(result: &Result, storage: &MockStorageBackend) { + assert!( + matches!( + result, + Err(GuardianError::ModuleDenied { module, reason_code, layer, .. }) + if module == "caps" && reason_code == "amount_cap_exceeded" && layer == "global" + ), + "{result:?}" + ); + assert!( + storage.get_submit_delta_calls().is_empty(), + "nothing signed or stored" + ); + } + + #[tokio::test] + async fn a_payment_under_a_mandatory_cap_is_acknowledged_as_without_modules() { + let (result, storage, _) = + push_through(cap_of_1000(), paying(500), stored_proposal_labelled("p2id")).await; + assert!(result.is_ok(), "{result:?}"); + assert_eq!(storage.get_submit_delta_calls().len(), 1); + } + + #[tokio::test] + async fn a_payment_over_a_mandatory_cap_is_refused_through_a_stored_proposal() { + let (result, storage, _) = push_through( + cap_of_1000(), + paying(5_000), + stored_proposal_labelled("p2id"), + ) + .await; + assert_refused_by_the_cap(&result, &storage); + } + + #[tokio::test] + async fn a_payment_over_a_mandatory_cap_signed_offline_is_refused_without_a_proposal() { + let (result, storage, _) = + push_through(cap_of_1000(), paying(5_000), no_stored_proposal).await; + assert_refused_by_the_cap(&result, &storage); + } + + #[tokio::test] + async fn the_decision_follows_the_effect_not_the_proposal_label() { + let (result, storage, _) = push_through( + cap_of_1000(), + paying(5_000), + stored_proposal_labelled("change_threshold"), + ) + .await; + assert_refused_by_the_cap(&result, &storage); } #[tokio::test] diff --git a/crates/server/src/testing/mocks.rs b/crates/server/src/testing/mocks.rs index 67d05b78..fe09d472 100644 --- a/crates/server/src/testing/mocks.rs +++ b/crates/server/src/testing/mocks.rs @@ -53,6 +53,8 @@ pub struct MockNetworkClient { pub account_nonce_responses: Arc>>, pub module_account_view: Arc>>, pub module_projection: Arc>>, + /// Account views and projections built for policy modules. + pub module_decodes: Arc, /// The block every observed commitment reports it was read at. pub observed_block: Arc>, /// How long every observed commitment takes to answer. @@ -244,6 +246,8 @@ impl NetworkClient for MockNetworkClient { &self, _state_json: &serde_json::Value, ) -> StdResult { + self.module_decodes + .fetch_add(1, std::sync::atomic::Ordering::SeqCst); self.module_account_view .lock() .unwrap() @@ -255,6 +259,8 @@ impl NetworkClient for MockNetworkClient { &self, tx_summary: &serde_json::Value, ) -> StdResult { + self.module_decodes + .fetch_add(1, std::sync::atomic::Ordering::SeqCst); let projection = self .module_projection .lock() diff --git a/speckit/features/251-guardian-modules/tasks.md b/speckit/features/251-guardian-modules/tasks.md index 82dd103c..ebd3fe7e 100644 --- a/speckit/features/251-guardian-modules/tasks.md +++ b/speckit/features/251-guardian-modules/tasks.md @@ -57,8 +57,8 @@ ### Tests for User Story 1 -- [ ] T013 [P] [US1] Acceptance suite in `crates/server/src/modules/acceptance_tests.rs` (registered in `crates/server/src/modules/mod.rs`): with a real `basic-policy` cap instance, a transfer under the cap is acked; over the cap is refused with `GUARDIAN_MODULE_DENIED` naming instance and reason code and stores no candidate, through a stored proposal and through an offline push; a Guardian execution over the cap ends `GUARDIAN_EXECUTION_MODULE_DENIED` with nothing proved; a proposal labelled as a threshold change that moves funds is judged on its effect -- [ ] T014 [P] [US1] No-modules regression: a test in `crates/server/src/modules/acceptance_tests.rs` that a server built without `GUARDIAN_MODULES_CONFIG` never builds a view or projection (spy on the network client) and acks as before; record the zero-module `push_delta` p99 A/B (filesystem, local) in `speckit/features/251-guardian-modules/research.md` +- [X] T013 [P] [US1] Acceptance suite with a real `basic-policy` cap of 1,000: under the cap is acked; over the cap is refused with `GUARDIAN_MODULE_DENIED` (instance, reason code, layer) and nothing is stored, through a stored proposal and through an offline push without one; a proposal labelled `change_threshold` that moves funds is judged on its effect (`crates/server/src/services/push_delta.rs` tests); a Guardian execution over the cap ends `GUARDIAN_EXECUTION_MODULE_DENIED` with nothing proved or submitted (`crates/server/src/services/execute_proposal/tests.rs`). Placed next to each path's fixtures rather than in a separate file, which would duplicate them +- [X] T014 [P] [US1] No-modules regression: without a catalog a push builds no account view or projection and records no approval, while the same push with a module does (`MockNetworkClient::module_decodes`, `crates/server/src/services/push_delta.rs`). The p99 A/B against `main` is measured with the other configurations in T059, in one session ### Implementation for User Story 1 From c687925cef1371ebc011ae8c161fa517ff4aadb0 Mon Sep 17 00:00:00 2001 From: Zeljko Date: Mon, 9 Nov 2026 10:09:14 +0100 Subject: [PATCH 015/105] fix(module-sdk): basic-policy names its rule to clients and does not judge without a projection (#251) Each basic-policy rule denies with a fixed reason code and a fixed client message naming the rule, never a list entry or a limit, so a full denial discloses no params; the details stay in the logged message. An unknown recipient refused under deny_unknown_recipients reports the denylist rule (recipient_blocked), as RFC 0002 section 3.1 specifies. A transaction without a Miden projection is now a module error, so on_error applies, instead of a projection_missing denial. --- .../guardian-module-sdk/src/basic_policy.rs | 133 +++++++++++++----- docs/guides/policy-modules/built-in.md | 10 +- .../features/251-guardian-modules/tasks.md | 2 +- 3 files changed, 109 insertions(+), 36 deletions(-) diff --git a/crates/guardian-module-sdk/src/basic_policy.rs b/crates/guardian-module-sdk/src/basic_policy.rs index 41cf3957..278416b7 100644 --- a/crates/guardian-module-sdk/src/basic_policy.rs +++ b/crates/guardian-module-sdk/src/basic_policy.rs @@ -7,8 +7,8 @@ use serde::Deserialize; use crate::proto::{asset, hook_request}; use crate::{ - AccountView, Decision, DescribeRequest, Hook, HookRequest, Module, ModuleError, ModuleInfo, - PROTOCOL_VERSION, ParamsVerdict, TransactionSubject, + AccountView, Decision, DescribeRequest, Hook, HookRequest, MidenTransaction, Module, + ModuleError, ModuleInfo, PROTOCOL_VERSION, ParamsVerdict, TransactionSubject, }; pub const KIND: &str = "basic-policy"; @@ -113,6 +113,46 @@ fn parse_policy(params: &[u8]) -> Result { Policy::try_from(params) } +/// A `basic-policy` rule. Each denies with a fixed reason code and a fixed client message that +/// names the rule, never a list entry or a limit, so a denial discloses no params; the details +/// go only to the logged message. +#[derive(Debug, Clone, Copy)] +enum Rule { + RecipientAllowlist, + RecipientDenylist, + AssetAllowlist, + AmountCap, + Signers, +} + +impl Rule { + fn deny(self, logged: String) -> Decision { + let (reason_code, client_message) = match self { + Rule::RecipientAllowlist => ( + "recipient_not_allowed", + "A payment goes to a recipient this Guardian does not accept.", + ), + Rule::RecipientDenylist => ( + "recipient_blocked", + "A payment goes to a recipient this Guardian blocks.", + ), + Rule::AssetAllowlist => ( + "asset_not_allowed", + "The transaction moves an asset this Guardian does not accept.", + ), + Rule::AmountCap => ( + "amount_cap_exceeded", + "The transaction sends more than this Guardian allows per transaction.", + ), + Rule::Signers => ( + "signer_not_allowed", + "The account would have a signer this Guardian does not accept.", + ), + }; + Decision::deny(reason_code, logged).with_client_message(client_message) + } +} + impl Policy { fn evaluate(&self, request: &HookRequest) -> Result { if let Some(signers) = &self.signers { @@ -125,14 +165,11 @@ impl Policy { .into_iter() .find(|signer| !signers.permits(signer)) { - return Ok(Decision::deny( - "signer_not_allowed", - format!("signer {signer} is not permitted"), - )); + return Ok(Rule::Signers.deny(format!("signer {signer} is not permitted"))); } } match &request.subject { - Some(hook_request::Subject::Transaction(tx)) => Ok(self.evaluate_transaction(tx)), + Some(hook_request::Subject::Transaction(tx)) => self.evaluate_transaction(tx), Some(hook_request::Subject::Registration(_)) => Ok(Decision::allow()), None => Err(ModuleError::InvalidRequest("request has no subject".into())), } @@ -149,11 +186,16 @@ impl Policy { .collect() } - fn evaluate_transaction(&self, tx: &TransactionSubject) -> Decision { + fn evaluate_transaction(&self, tx: &TransactionSubject) -> Result { let Some(projection) = tx.miden() else { - return Decision::deny("projection_missing", "transaction has no Miden projection"); + return Err(ModuleError::InvalidRequest( + "transaction has no Miden projection to judge".into(), + )); }; + Ok(self.judge(projection)) + } + fn judge(&self, projection: &MidenTransaction) -> Decision { let payments = || projection.output_notes.iter().filter(|note| !note.tx_fee); if let Some(allowed) = &self.assets { @@ -164,10 +206,7 @@ impl Policy { .map(|a| a.faucet_id.to_ascii_lowercase()) .find(|faucet| !allowed.contains(faucet)) { - return Decision::deny( - "asset_not_allowed", - format!("asset {faucet} is not allowed"), - ); + return Rule::AssetAllowlist.deny(format!("asset {faucet} is not allowed")); } } @@ -176,17 +215,13 @@ impl Policy { let recipient = match (¬e.p2id_target, note.partial) { (Some(target), false) => target.to_ascii_lowercase(), _ => { - return Decision::deny( - "recipient_not_allowed", - format!("note {} has no checkable recipient", note.note_id), - ); + return Rule::RecipientAllowlist + .deny(format!("note {} has no checkable recipient", note.note_id)); } }; if !allowed.contains(&recipient) { - return Decision::deny( - "recipient_not_allowed", - format!("recipient {recipient} is not allowed"), - ); + return Rule::RecipientAllowlist + .deny(format!("recipient {recipient} is not allowed")); } } } @@ -195,17 +230,13 @@ impl Policy { for note in payments() { match (¬e.p2id_target, note.partial) { (Some(target), false) if blocked.contains(&target.to_ascii_lowercase()) => { - return Decision::deny( - "recipient_blocked", - format!("recipient {target} is blocked"), - ); + return Rule::RecipientDenylist + .deny(format!("recipient {target} is blocked")); } (Some(_), false) => {} _ if self.deny_unknown_recipients => { - return Decision::deny( - "recipient_not_allowed", - format!("note {} has no checkable recipient", note.note_id), - ); + return Rule::RecipientDenylist + .deny(format!("note {} has no checkable recipient", note.note_id)); } _ => {} } @@ -225,10 +256,8 @@ impl Policy { } for (faucet, cap) in &self.caps { if sent.get(faucet).is_some_and(|total| total > cap) { - return Decision::deny( - "amount_cap_exceeded", - format!("sent {} of {faucet}, cap {cap}", sent[faucet]), - ); + return Rule::AmountCap + .deny(format!("sent {} of {faucet}, cap {cap}", sent[faucet])); } } } @@ -478,10 +507,46 @@ mod tests { let strict = json!({ "recipient_denylist": ["0xbad"], "deny_unknown_recipients": true }); assert_eq!( decide(&tx_request(strict, unknown)).await.reason_code, - "recipient_not_allowed" + "recipient_blocked", + "an unknown recipient refused by the denylist rule reports that rule" ); } + #[tokio::test] + async fn a_denial_names_its_rule_to_the_client_and_discloses_no_param() { + let projection = MidenTransaction { + output_notes: vec![p2id("0xr1", vec![fungible(USDC, 5_000)])], + ..Default::default() + }; + let decision = decide(&tx_request(cap(), projection)).await; + assert_eq!(decision.reason_code, "amount_cap_exceeded"); + assert!(!decision.client_message.is_empty()); + assert!(decision.client_message.len() <= 256); + for detail in ["1000", "5000", USDC, "0xr1"] { + assert!( + !decision.client_message.contains(detail), + "{detail} leaked into {:?}", + decision.client_message + ); + } + assert!( + decision.message.contains("1000"), + "details stay in the logged message" + ); + } + + #[tokio::test] + async fn a_transaction_without_a_miden_projection_is_not_judged() { + let mut request = tx_request(cap(), MidenTransaction::default()); + if let Some(hook_request::Subject::Transaction(subject)) = &mut request.subject { + subject.projection = None; + } + assert!(matches!( + BasicPolicy.evaluate(&request).await, + Err(ModuleError::InvalidRequest(_)) + )); + } + #[tokio::test] async fn asset_allowlist_covers_consumed_notes() { let projection = MidenTransaction { diff --git a/docs/guides/policy-modules/built-in.md b/docs/guides/policy-modules/built-in.md index 0a59213c..0cc8f8eb 100644 --- a/docs/guides/policy-modules/built-in.md +++ b/docs/guides/policy-modules/built-in.md @@ -15,13 +15,21 @@ All params are optional; an instance with none allows everything. | `asset_allowlist` | `["", ...]` | `asset_not_allowed` | Assets sent in payment notes and received in input notes. | | `recipient_allowlist` | `["", ...]` | `recipient_not_allowed` | P2ID and P2IDE targets. | | `recipient_denylist` | `["", ...]` | `recipient_blocked` | | -| `deny_unknown_recipients` | `true` / `false` | `recipient_not_allowed` | Refuses payment notes whose recipient the Guardian cannot identify (not P2ID or P2IDE). | +| `deny_unknown_recipients` | `true` / `false` | `recipient_blocked` | With `recipient_denylist`: also refuses payment notes whose recipient the Guardian cannot identify (not P2ID or P2IDE). | | `signer_allowlist` or `signer_denylist` | `["", ...]` | `signer_not_allowed` | Mutually exclusive. | | `signer_check` | `"added"` (default) or `"all"` | | `added` checks only signers a transaction adds; `all` checks every signer after it. | Signer rules apply at all three hooks, including registration. Transaction rules (caps, assets, recipients) apply to proposals and approvals. +Each refusal carries a fixed `client_message` naming the rule (for example +"The transaction sends more than this Guardian allows per transaction."), +never a list entry or a limit, so a `client_reason = "full"` instance tells +users what to change without disclosing params. The exact amounts and +entries go to the server log. A transaction request without a Miden +projection is not judged: the module returns an error and the instance's +`on_error` applies. + ## The example catalog | Instance | Scope | Rule | diff --git a/speckit/features/251-guardian-modules/tasks.md b/speckit/features/251-guardian-modules/tasks.md index ebd3fe7e..1c0d7d0d 100644 --- a/speckit/features/251-guardian-modules/tasks.md +++ b/speckit/features/251-guardian-modules/tasks.md @@ -62,7 +62,7 @@ ### Implementation for User Story 1 -- [ ] T015 [US1] `basic-policy` review fixes in `crates/guardian-module-sdk/src/basic_policy.rs`: a fixed `client_message` per reason code; a missing projection is a module error, not a `projection_missing` deny; tests for both (P0 T091) +- [X] T015 [US1] `basic-policy` review fixes in `crates/guardian-module-sdk/src/basic_policy.rs`: a fixed `client_message` per reason code; a missing projection is a module error, not a `projection_missing` deny; tests for both (P0 T091) - [ ] T016 [US1] Denial log line with the fields of RFC section 2.2 (instance, layer, reason code, `request_id`, account, submitter) in `crates/server/src/modules/pipeline.rs`, with `request_id` defined as in RFC section 3.2; test that a generic denial still logs the full decision (P0 T091) **Checkpoint**: SC-002 holds on all three approval paths and SC-001 has its baseline. From ae17b47c7ceeea5c63cb0b61320ba68288518fa5 Mon Sep 17 00:00:00 2001 From: Zeljko Date: Mon, 9 Nov 2026 10:09:49 +0100 Subject: [PATCH 016/105] test(modules): the execution cap denial carries basic-policy's client message (#251) --- crates/server/src/services/execute_proposal/tests.rs | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/crates/server/src/services/execute_proposal/tests.rs b/crates/server/src/services/execute_proposal/tests.rs index a489a2ae..99e0044b 100644 --- a/crates/server/src/services/execute_proposal/tests.rs +++ b/crates/server/src/services/execute_proposal/tests.rs @@ -1363,7 +1363,9 @@ async fn a_guardian_execution_over_a_mandatory_cap_is_refused_before_anything_is module: Some("caps".into()), reason_code: "amount_cap_exceeded".into(), layer: Some("global".into()), - client_message: None, + client_message: Some( + "The transaction sends more than this Guardian allows per transaction.".into() + ), }) ); assert_eq!(f.calls.lock().unwrap().submitted, 0, "nothing is submitted"); From 9cd00d87b9d4abf590ea1d6b472d81388f409de7 Mon Sep 17 00:00:00 2001 From: Zeljko Date: Mon, 9 Nov 2026 10:12:42 +0100 Subject: [PATCH 017/105] feat(modules): request_id per hook invocation and the full denial log line (#251) Every module and layer called in one hook invocation receives the same HookRequest.request_id, and the next invocation a new one, so module logs join the Guardian's. A denial is logged with request_id, account, hook, module, submitter, layer, reason code, the module's message, catalog hash and params version, including a generic denial whose client sees none of it. --- crates/server/src/modules/pipeline.rs | 111 +++++++++++++++++- .../features/251-guardian-modules/tasks.md | 2 +- 2 files changed, 111 insertions(+), 2 deletions(-) diff --git a/crates/server/src/modules/pipeline.rs b/crates/server/src/modules/pipeline.rs index 897d1e14..58f16a69 100644 --- a/crates/server/src/modules/pipeline.rs +++ b/crates/server/src/modules/pipeline.rs @@ -435,8 +435,12 @@ impl Plan<'_> { params_version, failed_open: Vec::new(), }; + let request_id = format!("{:032x}", rand::random::()); let base = match build() { - Ok(base) => base, + Ok(base) => HookRequest { + request_id: request_id.clone(), + ..base + }, Err(error) => { for (instance, _, layer) in &modules { let failure = Failure::RequestUnavailable(error.clone()); @@ -465,12 +469,16 @@ impl Plan<'_> { if is_valid_reason_code(&decision.reason_code) => { tracing::info!( + request_id = %request_id, module = %instance.config.id, account_id, ?hook, + submitter = %base.submitter, reason_code = %decision.reason_code, layer = layer.as_str(), message = %decision.message, + catalog_hash = %approval.catalog_hash, + params_version = approval.params_version, client_reason = ?instance.config.client_reason, "Policy module denied the request" ); @@ -1271,3 +1279,104 @@ params = { old_name = 1000 } } } } + +#[cfg(test)] +mod evaluation_trace_tests { + use guardian_module_sdk::HookRequest; + + use super::*; + use crate::modules::catalog::{ClientReason, HookName, OnError}; + use crate::modules::testing::{StubModule, instance}; + + const HOOK: HookName = HookName::BeforeTransactionApproved; + + #[tokio::test] + async fn one_invocation_shares_a_request_id_and_the_next_gets_a_new_one() { + let first = StubModule::allowing(); + let second = StubModule::allowing(); + let pipeline = ModulePipeline::from_instances(vec![ + instance("first", &[HOOK], OnError::Deny, first.clone()), + instance("second", &[HOOK], OnError::Deny, second.clone()), + ]); + let id = |module: &StubModule| module.last_request().unwrap().request_id; + + pipeline + .run(HOOK, "0xacc", || Ok(HookRequest::default())) + .await + .unwrap(); + let invocation = id(&first); + assert!(!invocation.is_empty()); + assert_eq!(id(&second), invocation); + + pipeline + .run(HOOK, "0xacc", || Ok(HookRequest::default())) + .await + .unwrap(); + assert_ne!(id(&first), invocation); + } + + #[derive(Clone, Default)] + struct Captured(std::sync::Arc>>); + + impl std::io::Write for Captured { + fn write(&mut self, buf: &[u8]) -> std::io::Result { + self.0.lock().unwrap().extend_from_slice(buf); + Ok(buf.len()) + } + + fn flush(&mut self) -> std::io::Result<()> { + Ok(()) + } + } + + impl<'a> tracing_subscriber::fmt::MakeWriter<'a> for Captured { + type Writer = Captured; + + fn make_writer(&'a self) -> Self::Writer { + self.clone() + } + } + + #[tokio::test(flavor = "current_thread")] + async fn a_generic_denial_hides_the_decision_from_the_client_but_logs_it_whole() { + let captured = Captured::default(); + let subscriber = tracing_subscriber::fmt() + .with_writer(captured.clone()) + .with_ansi(false) + .finish(); + let _pin = crate::testing::log_capture::dispatcher_registry_pin(); + let _default = tracing::subscriber::set_default(subscriber); + + let mut screening = instance( + "screening", + &[HOOK], + OnError::Deny, + StubModule::denying("sanctioned_counterparty"), + ); + screening.config.client_reason = ClientReason::Generic; + let pipeline = ModulePipeline::from_instances(vec![screening]); + let result = pipeline + .run(HOOK, "0xacc", || { + Ok(HookRequest { + submitter: "0xsubmitter".into(), + ..Default::default() + }) + }) + .await; + assert!(matches!(result, Err(GuardianError::ModuleDeniedGeneric))); + + let log = String::from_utf8(captured.0.lock().unwrap().clone()).unwrap(); + for field in [ + "request_id=", + "module=screening", + "account_id=\"0xacc\"", + "submitter=0xsubmitter", + "reason_code=sanctioned_counterparty", + "layer=\"global\"", + "catalog_hash=", + "params_version=", + ] { + assert!(log.contains(field), "{field} missing from {log}"); + } + } +} diff --git a/speckit/features/251-guardian-modules/tasks.md b/speckit/features/251-guardian-modules/tasks.md index 1c0d7d0d..ad980b1e 100644 --- a/speckit/features/251-guardian-modules/tasks.md +++ b/speckit/features/251-guardian-modules/tasks.md @@ -63,7 +63,7 @@ ### Implementation for User Story 1 - [X] T015 [US1] `basic-policy` review fixes in `crates/guardian-module-sdk/src/basic_policy.rs`: a fixed `client_message` per reason code; a missing projection is a module error, not a `projection_missing` deny; tests for both (P0 T091) -- [ ] T016 [US1] Denial log line with the fields of RFC section 2.2 (instance, layer, reason code, `request_id`, account, submitter) in `crates/server/src/modules/pipeline.rs`, with `request_id` defined as in RFC section 3.2; test that a generic denial still logs the full decision (P0 T091) +- [X] T016 [US1] Denial log line with the fields of RFC section 2.2 (instance, layer, reason code, `request_id`, account, submitter) in `crates/server/src/modules/pipeline.rs`, with `request_id` defined as in RFC section 3.2; test that a generic denial still logs the full decision (P0 T091) **Checkpoint**: SC-002 holds on all three approval paths and SC-001 has its baseline. From 4194f968e67219cb417e310cae80d51036ba2c70 Mon Sep 17 00:00:00 2001 From: Zeljko Date: Mon, 9 Nov 2026 10:19:24 +0100 Subject: [PATCH 018/105] feat(modules): evaluation budget, request size cap, circuit breaker and health probe (#251) Each hook invocation gets GUARDIAN_MODULE_EVALUATION_BUDGET_MS (default 1000): a call gets the smaller of its timeout and what is left, and once the budget is spent later modules count as timed out. A request whose encoded size exceeds GUARDIAN_MODULE_REQUEST_MAX_BYTES (default 2 MiB) is a module failure and is not sent. Each replica keeps a breaker per instance: GUARDIAN_MODULE_BREAKER_FAILURES consecutive failures (default 5) open it, so the module is skipped and its on_error applies at once; a Describe probe every GUARDIAN_MODULE_PROBE_INTERVAL_MS (default 5000) half-opens it and the next call decides. A deny is an answer, and a call cut short by the budget or refused for size is not the module's failure. A bad value in any of the four variables refuses startup. --- crates/server/src/builder/handle.rs | 4 + crates/server/src/modules/breaker.rs | 159 +++++++++ crates/server/src/modules/limits.rs | 117 +++++++ crates/server/src/modules/mod.rs | 5 +- crates/server/src/modules/pipeline.rs | 328 +++++++++++++++++- crates/server/src/modules/registry.rs | 16 +- .../features/251-guardian-modules/tasks.md | 10 +- 7 files changed, 614 insertions(+), 25 deletions(-) create mode 100644 crates/server/src/modules/breaker.rs create mode 100644 crates/server/src/modules/limits.rs diff --git a/crates/server/src/builder/handle.rs b/crates/server/src/builder/handle.rs index d08f9667..2be145dc 100644 --- a/crates/server/src/builder/handle.rs +++ b/crates/server/src/builder/handle.rs @@ -126,6 +126,10 @@ impl ServerHandle { } } + if let Some(modules) = self.app_state.modules.clone() { + tasks.push(modules.spawn_probe()); + } + // Start background jobs based on canonicalization config if self.app_state.canonicalization.is_some() { tracing::info!("Starting canonicalization worker"); diff --git a/crates/server/src/modules/breaker.rs b/crates/server/src/modules/breaker.rs new file mode 100644 index 00000000..02c2b1b7 --- /dev/null +++ b/crates/server/src/modules/breaker.rs @@ -0,0 +1,159 @@ +//! Per-instance circuit breakers and the `Describe` health probe. Breaker state is per replica and +//! in memory; nothing about it is stored. + +use std::collections::HashMap; +use std::sync::Mutex; + +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum CircuitState { + Closed, + Open, + HalfOpen, +} + +impl CircuitState { + pub fn as_str(self) -> &'static str { + match self { + CircuitState::Closed => "closed", + CircuitState::Open => "open", + CircuitState::HalfOpen => "half_open", + } + } +} + +#[derive(Debug, Clone, Copy)] +struct Breaker { + state: CircuitState, + consecutive_failures: u32, +} + +impl Default for Breaker { + fn default() -> Self { + Self { + state: CircuitState::Closed, + consecutive_failures: 0, + } + } +} + +/// One breaker per instance id. A closed breaker opens after `threshold` consecutive failures; an +/// open one skips the module until a successful probe moves it to half-open, where the next real +/// call closes it on an answer or opens it again on a failure. +pub struct Breakers { + threshold: u32, + by_instance: Mutex>, +} + +impl Breakers { + pub fn new(threshold: u32) -> Self { + Self { + threshold: threshold.max(1), + by_instance: Mutex::default(), + } + } + + pub fn state(&self, instance: &str) -> CircuitState { + self.by_instance + .lock() + .ok() + .and_then(|breakers| breakers.get(instance).map(|breaker| breaker.state)) + .unwrap_or(CircuitState::Closed) + } + + /// Whether the module may be called; an open breaker applies the instance's `on_error` at + /// once instead. + pub fn admits(&self, instance: &str) -> bool { + self.state(instance) != CircuitState::Open + } + + /// The module answered, allow or deny: a deny is an answer, not a failure. + pub fn answered(&self, instance: &str) { + self.update(instance, |breaker| *breaker = Breaker::default()); + } + + /// The module timed out, failed to respond or returned a malformed decision. + pub fn failed(&self, instance: &str) { + let threshold = self.threshold; + self.update(instance, |breaker| match breaker.state { + CircuitState::Closed => { + breaker.consecutive_failures = breaker.consecutive_failures.saturating_add(1); + if breaker.consecutive_failures >= threshold { + breaker.state = CircuitState::Open; + } + } + CircuitState::HalfOpen | CircuitState::Open => breaker.state = CircuitState::Open, + }); + } + + /// A health probe succeeded: an open breaker lets the next real call through. + pub fn probe_succeeded(&self, instance: &str) { + self.update(instance, |breaker| { + if breaker.state == CircuitState::Open { + breaker.state = CircuitState::HalfOpen; + } + }); + } + + fn update(&self, instance: &str, change: impl FnOnce(&mut Breaker)) { + let previous = self.state(instance); + let current = match self.by_instance.lock() { + Ok(mut breakers) => { + let breaker = breakers.entry(instance.to_string()).or_default(); + change(breaker); + breaker.state + } + Err(_) => return, + }; + if previous != current { + tracing::warn!( + module = instance, + from = previous.as_str(), + to = current.as_str(), + "Policy module circuit changed" + ); + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn consecutive_failures_open_the_breaker_and_an_answer_resets_the_count() { + let breakers = Breakers::new(3); + breakers.failed("m"); + breakers.failed("m"); + breakers.answered("m"); + breakers.failed("m"); + breakers.failed("m"); + assert!(breakers.admits("m"), "an answer reset the count"); + breakers.failed("m"); + assert_eq!(breakers.state("m"), CircuitState::Open); + assert!(!breakers.admits("m")); + } + + #[test] + fn a_probe_half_opens_and_the_next_call_decides() { + let breakers = Breakers::new(1); + breakers.failed("m"); + breakers.probe_succeeded("m"); + assert_eq!(breakers.state("m"), CircuitState::HalfOpen); + assert!(breakers.admits("m")); + breakers.failed("m"); + assert_eq!(breakers.state("m"), CircuitState::Open); + breakers.probe_succeeded("m"); + breakers.answered("m"); + assert_eq!(breakers.state("m"), CircuitState::Closed); + } + + #[test] + fn a_probe_does_not_touch_a_closed_breaker_and_instances_are_independent() { + let breakers = Breakers::new(1); + breakers.probe_succeeded("a"); + assert_eq!(breakers.state("a"), CircuitState::Closed); + breakers.failed("a"); + assert!(!breakers.admits("a")); + assert!(breakers.admits("b")); + } +} diff --git a/crates/server/src/modules/limits.rs b/crates/server/src/modules/limits.rs new file mode 100644 index 00000000..34e4278f --- /dev/null +++ b/crates/server/src/modules/limits.rs @@ -0,0 +1,117 @@ +//! Bounds on policy module evaluation: the per-invocation time budget, the request size cap, and +//! the circuit breaker and health probe settings. + +use std::time::Duration; + +pub const BUDGET_ENV: &str = "GUARDIAN_MODULE_EVALUATION_BUDGET_MS"; +pub const REQUEST_MAX_BYTES_ENV: &str = "GUARDIAN_MODULE_REQUEST_MAX_BYTES"; +pub const BREAKER_FAILURES_ENV: &str = "GUARDIAN_MODULE_BREAKER_FAILURES"; +pub const PROBE_INTERVAL_ENV: &str = "GUARDIAN_MODULE_PROBE_INTERVAL_MS"; + +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub struct Limits { + /// Time spent in module calls for one hook invocation; request assembly is not charged. + pub budget: Duration, + /// Largest encoded request sent to a module; a larger one is a module failure, not sent. + pub request_max_bytes: usize, + /// Consecutive failures that open an instance's breaker. + pub breaker_failures: u32, + /// Interval of the `Describe` health probe per instance. + pub probe_interval: Duration, +} + +impl Default for Limits { + fn default() -> Self { + Self { + budget: Duration::from_millis(1_000), + request_max_bytes: 2 * 1024 * 1024, + breaker_failures: 5, + probe_interval: Duration::from_millis(5_000), + } + } +} + +impl Limits { + /// The limits from the environment, each defaulting when unset; a value that is not a + /// positive integer refuses startup. + pub fn from_env() -> Result { + Self::from_vars(|name| std::env::var(name)) + } + + fn from_vars(var: impl Fn(&str) -> Result) -> Result { + let defaults = Self::default(); + Ok(Self { + budget: Duration::from_millis( + positive(&var, BUDGET_ENV)? + .unwrap_or(u64::try_from(defaults.budget.as_millis()).unwrap_or(u64::MAX)), + ), + request_max_bytes: positive(&var, REQUEST_MAX_BYTES_ENV)? + .map(|bytes| usize::try_from(bytes).unwrap_or(usize::MAX)) + .unwrap_or(defaults.request_max_bytes), + breaker_failures: positive(&var, BREAKER_FAILURES_ENV)? + .map(|failures| u32::try_from(failures).unwrap_or(u32::MAX)) + .unwrap_or(defaults.breaker_failures), + probe_interval: positive(&var, PROBE_INTERVAL_ENV)? + .map(Duration::from_millis) + .unwrap_or(defaults.probe_interval), + }) + } +} + +fn positive( + var: &impl Fn(&str) -> Result, + name: &str, +) -> Result, String> { + match var(name) { + Err(std::env::VarError::NotPresent) => Ok(None), + Ok(value) => value + .trim() + .parse::() + .ok() + .filter(|value| *value > 0) + .map(Some) + .ok_or_else(|| format!("{name} must be a positive integer, got {value:?}")), + Err(std::env::VarError::NotUnicode(_)) => Err(format!("{name} must contain valid UTF-8")), + } +} + +#[cfg(test)] +mod tests { + use super::*; + + fn vars(set: &[(&str, &str)]) -> impl Fn(&str) -> Result { + let set: Vec<(String, String)> = set + .iter() + .map(|(name, value)| (name.to_string(), value.to_string())) + .collect(); + move |name| { + set.iter() + .find(|(set_name, _)| set_name == name) + .map(|(_, value)| value.clone()) + .ok_or(std::env::VarError::NotPresent) + } + } + + #[test] + fn unset_variables_take_the_defaults() { + assert_eq!(Limits::from_vars(vars(&[])).unwrap(), Limits::default()); + } + + #[test] + fn set_variables_override_and_invalid_ones_refuse_startup() { + let limits = Limits::from_vars(vars(&[ + (BUDGET_ENV, "250"), + (REQUEST_MAX_BYTES_ENV, "4096"), + (BREAKER_FAILURES_ENV, "3"), + (PROBE_INTERVAL_ENV, "1000"), + ])) + .unwrap(); + assert_eq!(limits.budget, Duration::from_millis(250)); + assert_eq!(limits.request_max_bytes, 4096); + assert_eq!(limits.breaker_failures, 3); + assert_eq!(limits.probe_interval, Duration::from_millis(1000)); + for bad in ["0", "-1", "soon"] { + assert!(Limits::from_vars(vars(&[(BUDGET_ENV, bad)])).is_err()); + } + } +} diff --git a/crates/server/src/modules/mod.rs b/crates/server/src/modules/mod.rs index 939c869e..5d1661c7 100644 --- a/crates/server/src/modules/mod.rs +++ b/crates/server/src/modules/mod.rs @@ -1,10 +1,12 @@ //! Policy modules: a hook pipeline the Guardian consults before approving. pub mod admin; +pub mod breaker; pub mod catalog; pub mod check_limit; pub mod disclosure; pub mod grpc_kind; +pub mod limits; pub mod pipeline; #[cfg(feature = "postgres")] pub mod postgres_store; @@ -59,7 +61,8 @@ pub async fn from_env( Some(store) => store, None => Arc::new(filesystem_store(&catalog_path)?), }; - let pipeline = ModulePipeline::new(catalog, registry, store, now).await?; + let pipeline = + ModulePipeline::new(catalog, registry, store, now, limits::Limits::from_env()?).await?; let version = pipeline.store().version().await?; let builds = pipeline .instances() diff --git a/crates/server/src/modules/pipeline.rs b/crates/server/src/modules/pipeline.rs index 58f16a69..1a175e7c 100644 --- a/crates/server/src/modules/pipeline.rs +++ b/crates/server/src/modules/pipeline.rs @@ -6,6 +6,8 @@ use super::catalog::{Catalog, ClientReason, HookName, OnError, Scope}; use std::collections::HashMap; use std::sync::{Arc, RwLock}; +use super::breaker::Breakers; +use super::limits::Limits; use super::registry::{CallError, Instance, Registry, isolated}; use super::request::ViewCache; use super::store::{AccountParamsRow, ModuleStore, ParamsKind}; @@ -41,6 +43,8 @@ pub struct ModulePipeline { store: Arc, cache: RwLock, views: Arc, + limits: Limits, + breakers: Arc, pub catalog_hash: String, } @@ -63,6 +67,8 @@ pub struct Plan<'a> { catalog_hash: String, params_version: u64, views: Arc, + limits: Limits, + breakers: Arc, } enum Failure { @@ -72,6 +78,10 @@ enum Failure { /// An `effect` value this Guardian does not know: never read as an allow. UnknownEffect(i32), RequestUnavailable(String), + /// The encoded request exceeds the size cap; it is not sent. + RequestTooLarge(usize), + /// The instance's breaker is open; the module is not called. + CircuitOpen, } impl Failure { @@ -80,7 +90,8 @@ impl Failure { Failure::Error(_) => "error", Failure::Timeout => "timeout", Failure::InvalidDecision(_) | Failure::UnknownEffect(_) => "invalid_decision", - Failure::RequestUnavailable(_) => "request_unavailable", + Failure::RequestUnavailable(_) | Failure::RequestTooLarge(_) => "request_unavailable", + Failure::CircuitOpen => "circuit_open", } } } @@ -93,6 +104,10 @@ impl std::fmt::Display for Failure { Failure::InvalidDecision(code) => write!(f, "invalid reason code {code:?}"), Failure::UnknownEffect(value) => write!(f, "unknown decision effect {value}"), Failure::RequestUnavailable(message) => write!(f, "request unavailable: {message}"), + Failure::RequestTooLarge(bytes) => { + write!(f, "request of {bytes} bytes over the size cap") + } + Failure::CircuitOpen => write!(f, "circuit open"), } } } @@ -103,6 +118,7 @@ impl ModulePipeline { registry: &Registry, store: Arc, now: String, + limits: Limits, ) -> Result { let stored: HashMap = store .instances() @@ -179,6 +195,8 @@ impl ModulePipeline { store, cache: RwLock::new(Cache::default()), views: Arc::default(), + breakers: Arc::new(Breakers::new(limits.breaker_failures)), + limits, catalog_hash: catalog.hash, }) } @@ -201,10 +219,57 @@ impl ModulePipeline { store, cache: RwLock::new(Cache::default()), views: Arc::default(), + limits: Limits::default(), + breakers: Arc::new(Breakers::new(Limits::default().breaker_failures)), catalog_hash: String::new(), } } + #[cfg(test)] + pub fn with_limits(mut self, limits: Limits) -> Self { + self.breakers = Arc::new(Breakers::new(limits.breaker_failures)); + self.limits = limits; + self + } + + pub fn limits(&self) -> Limits { + self.limits + } + + pub fn breakers(&self) -> &Breakers { + &self.breakers + } + + /// One health probe of every enabled instance: `Describe` under its timeout, with the startup + /// checks. A healthy module half-opens an open breaker so the next real call is sent. + pub async fn probe(&self) { + for instance in &self.instances { + if !matches!(self.enabled(instance).await, Ok(true)) { + continue; + } + match super::registry::describe_healthy(&instance.config, &instance.module).await { + Ok(_) => self.breakers.probe_succeeded(&instance.config.id), + Err(error) => tracing::warn!( + module = %instance.config.id, + %error, + "Policy module health probe failed" + ), + } + } + } + + /// Runs [`Self::probe`] every `GUARDIAN_MODULE_PROBE_INTERVAL_MS` for the life of the server. + pub fn spawn_probe(self: Arc) -> tokio::task::JoinHandle<()> { + tokio::spawn(async move { + let mut interval = tokio::time::interval(self.limits.probe_interval); + interval.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Delay); + loop { + interval.tick().await; + self.probe().await; + } + }) + } + pub fn instances(&self) -> &[Instance] { &self.instances } @@ -371,6 +436,8 @@ impl ModulePipeline { catalog_hash: self.catalog_hash.clone(), params_version, views: self.views.clone(), + limits: self.limits, + breakers: self.breakers.clone(), })) } @@ -428,6 +495,8 @@ impl Plan<'_> { catalog_hash, params_version, views: _, + limits, + breakers, } = self; let account_id = account_id.as_str(); let mut approval = Evaluation { @@ -452,22 +521,48 @@ impl Plan<'_> { } }; + let deadline = tokio::time::Instant::now() + limits.budget; for (instance, params, layer) in modules { + let id = instance.config.id.as_str(); let mut request = base.clone(); request.hook = hook.proto() as i32; - request.instance_id = instance.config.id.clone(); + request.instance_id = id.to_string(); request.params = serde_json::to_vec(¶ms).unwrap_or_default(); + let remaining = deadline.saturating_duration_since(tokio::time::Instant::now()); + let size = prost::Message::encoded_len(&request); + let unsent = if !breakers.admits(id) { + Some(Failure::CircuitOpen) + } else if size > limits.request_max_bytes { + Some(Failure::RequestTooLarge(size)) + } else if remaining.is_zero() { + Some(Failure::Timeout) + } else { + None + }; + if let Some(failure) = unsent { + approval + .failed_open + .extend(fail(instance, layer, account_id, &failure)?); + continue; + } + + // A call the budget cuts short counts as a timeout, but is not the module's failure. + let cut_by_budget = remaining < instance.config.timeout; let module = instance.module.clone(); - let outcome = isolated(instance.config.timeout, async move { + let outcome = isolated(instance.config.timeout.min(remaining), async move { module.evaluate(&request).await }) .await; let failure = match outcome.map(|decision| (effect(&decision), decision)) { - Ok((Some(Effect::Allow), _)) => continue, + Ok((Some(Effect::Allow), _)) => { + breakers.answered(id); + continue; + } Ok((Some(Effect::Deny), decision)) if is_valid_reason_code(&decision.reason_code) => { + breakers.answered(id); tracing::info!( request_id = %request_id, module = %instance.config.id, @@ -500,6 +595,9 @@ impl Plan<'_> { } Err(CallError::Timeout) => Failure::Timeout, }; + if !(cut_by_budget && matches!(failure, Failure::Timeout)) { + breakers.failed(id); + } approval .failed_open .extend(fail(instance, layer, account_id, &failure)?); @@ -604,15 +702,22 @@ params = {params} ®istry, store.clone(), now.clone(), + crate::modules::limits::Limits::default(), ) .await; assert!(started.is_err()); assert!(store.instances().await.unwrap().is_empty()); let fixed = caps_catalog(r#"{ max_amount_per_tx = { "0xaa" = "5" } }"#); - let started = ModulePipeline::new(fixed, ®istry, store.clone(), now) - .await - .expect("the corrected catalog starts"); + let started = ModulePipeline::new( + fixed, + ®istry, + store.clone(), + now, + crate::modules::limits::Limits::default(), + ) + .await + .expect("the corrected catalog starts"); assert!( started.instances()[0] .build @@ -641,6 +746,7 @@ params = {params} ®istry, store.clone(), now.clone(), + crate::modules::limits::Limits::default(), ) .await .expect("the stored params apply, so the stale seed is not checked"); @@ -659,9 +765,15 @@ params = {params} .unwrap(); let valid_seed = caps_catalog(r#"{ max_amount_per_tx = {} }"#); assert!( - ModulePipeline::new(valid_seed, ®istry, store, now) - .await - .is_err() + ModulePipeline::new( + valid_seed, + ®istry, + store, + now, + crate::modules::limits::Limits::default() + ) + .await + .is_err() ); } @@ -857,9 +969,15 @@ params = { old_name = 5 } let store: Arc = Arc::new(super::super::store::FsModuleStore::in_memory()); let now = "2026-10-16T00:00:00Z".to_string(); - ModulePipeline::new(catalog(), ®istry, store.clone(), now.clone()) - .await - .unwrap(); + ModulePipeline::new( + catalog(), + ®istry, + store.clone(), + now.clone(), + crate::modules::limits::Limits::default(), + ) + .await + .unwrap(); let seeded = store.instances().await.unwrap(); assert_eq!( seeded[0].global_params, @@ -879,9 +997,15 @@ params = { old_name = 5 } ) .await .unwrap(); - ModulePipeline::new(catalog(), ®istry, store.clone(), now) - .await - .unwrap(); + ModulePipeline::new( + catalog(), + ®istry, + store.clone(), + now, + crate::modules::limits::Limits::default(), + ) + .await + .unwrap(); assert_eq!( store.instances().await.unwrap()[0].global_params, serde_json::json!({ "new_name": 5 }) @@ -1031,6 +1155,7 @@ params = { old_name = 1000 } ®istry, store.clone(), "2026-10-16T00:00:02Z".into(), + crate::modules::limits::Limits::default(), ) .await .unwrap(); @@ -1380,3 +1505,174 @@ mod evaluation_trace_tests { } } } + +#[cfg(test)] +mod failure_handling_tests { + use std::time::Duration; + + use guardian_module_sdk::HookRequest; + + use super::*; + use crate::modules::breaker::CircuitState; + use crate::modules::catalog::{HookName, OnError}; + use crate::modules::testing::{Behaviour, StubModule, instance}; + + const HOOK: HookName = HookName::BeforeTransactionApproved; + + fn hanging(id: &str, on_error: OnError, timeout: Duration) -> (Instance, Arc) { + let module = StubModule::new(Behaviour::Hang); + let mut hung = instance(id, &[HOOK], on_error, module.clone()); + hung.config.timeout = timeout; + (hung, module) + } + + async fn run(pipeline: &ModulePipeline) -> Result<(), GuardianError> { + pipeline + .run(HOOK, "0xacc", || Ok(HookRequest::default())) + .await + } + + #[tokio::test] + async fn a_failing_fail_closed_module_refuses_retryably_and_a_fail_open_one_is_skipped() { + let closed = ModulePipeline::from_instances(vec![instance( + "screening", + &[HOOK], + OnError::Deny, + StubModule::new(Behaviour::Fail), + )]); + let refused = run(&closed).await.unwrap_err(); + assert!( + matches!(&refused, GuardianError::ModuleUnavailable { module } if module == "screening") + ); + assert!(refused.retryable()); + + let open = ModulePipeline::from_instances(vec![instance( + "scoring", + &[HOOK], + OnError::Allow, + StubModule::new(Behaviour::Fail), + )]); + assert!(run(&open).await.is_ok()); + } + + #[tokio::test] + async fn consecutive_failures_open_the_circuit_so_later_requests_skip_the_timeout() { + let (hung, module) = hanging("screening", OnError::Deny, Duration::from_millis(50)); + let pipeline = ModulePipeline::from_instances(vec![hung]).with_limits(Limits { + breaker_failures: 2, + ..Limits::default() + }); + for _ in 0..2 { + assert!(run(&pipeline).await.is_err()); + } + assert_eq!(pipeline.breakers().state("screening"), CircuitState::Open); + + let started = tokio::time::Instant::now(); + let refused = run(&pipeline).await.unwrap_err(); + assert!(matches!(refused, GuardianError::ModuleUnavailable { .. })); + assert!( + started.elapsed() < Duration::from_millis(50), + "an open circuit refuses without waiting the timeout" + ); + assert_eq!(module.calls(), 2, "the module is not called while open"); + + pipeline.breakers().probe_succeeded("screening"); + assert!(run(&pipeline).await.is_err()); + assert_eq!(module.calls(), 3, "half-open sends the next call"); + assert_eq!(pipeline.breakers().state("screening"), CircuitState::Open); + } + + #[tokio::test] + async fn the_budget_cuts_later_modules_short_without_blaming_them() { + let (first, _) = hanging("first", OnError::Allow, Duration::from_millis(80)); + let (second, second_module) = hanging("second", OnError::Allow, Duration::from_millis(80)); + let pipeline = ModulePipeline::from_instances(vec![first, second]).with_limits(Limits { + budget: Duration::from_millis(100), + breaker_failures: 1, + ..Limits::default() + }); + let started = tokio::time::Instant::now(); + assert!(run(&pipeline).await.is_ok(), "both fail open"); + assert!( + started.elapsed() < Duration::from_millis(150), + "the second call gets only what is left of the budget" + ); + assert_eq!(second_module.calls(), 1); + assert_eq!(pipeline.breakers().state("first"), CircuitState::Open); + assert_eq!( + pipeline.breakers().state("second"), + CircuitState::Closed, + "a call cut short by the budget is not the module's failure" + ); + } + + #[tokio::test] + async fn an_oversized_request_is_a_module_failure_and_is_not_sent() { + let module = StubModule::allowing(); + let pipeline = ModulePipeline::from_instances(vec![instance( + "screening", + &[HOOK], + OnError::Deny, + module.clone(), + )]) + .with_limits(Limits { + request_max_bytes: 64, + ..Limits::default() + }); + let refused = pipeline + .run(HOOK, "0xacc", || { + Ok(HookRequest { + submitter: "0x".repeat(64), + ..Default::default() + }) + }) + .await; + assert!(matches!( + refused, + Err(GuardianError::ModuleUnavailable { .. }) + )); + assert_eq!(module.calls(), 0); + } + + #[tokio::test] + async fn a_fail_open_failure_does_not_stop_a_later_deny() { + let pipeline = ModulePipeline::from_instances(vec![ + instance( + "scoring", + &[HOOK], + OnError::Allow, + StubModule::new(Behaviour::Fail), + ), + instance( + "caps", + &[HOOK], + OnError::Deny, + StubModule::denying("amount_cap_exceeded"), + ), + ]); + assert!(matches!( + run(&pipeline).await, + Err(GuardianError::ModuleDenied { module, .. }) if module == "caps" + )); + } + + #[tokio::test] + async fn a_healthy_probe_half_opens_and_a_failing_one_leaves_the_circuit_open() { + let healthy = crate::modules::testing::instance_with_params( + "caps", + &[HOOK], + Arc::new(guardian_module_sdk::basic_policy::BasicPolicy), + serde_json::json!({}), + ); + let (down, _) = hanging("screening", OnError::Deny, Duration::from_millis(20)); + let pipeline = ModulePipeline::from_instances(vec![healthy, down]).with_limits(Limits { + breaker_failures: 1, + ..Limits::default() + }); + pipeline.breakers().failed("caps"); + pipeline.breakers().failed("screening"); + pipeline.probe().await; + assert_eq!(pipeline.breakers().state("caps"), CircuitState::HalfOpen); + assert_eq!(pipeline.breakers().state("screening"), CircuitState::Open); + } +} diff --git a/crates/server/src/modules/registry.rs b/crates/server/src/modules/registry.rs index e47f8788..18c995d1 100644 --- a/crates/server/src/modules/registry.rs +++ b/crates/server/src/modules/registry.rs @@ -244,6 +244,18 @@ pub async fn check( module: &Arc, params: &serde_json::Value, ) -> Result { + let info = describe_healthy(config, module).await?; + let params = validate_params(module, params, config.timeout).await?; + Ok(Checked { info, params }) +} + +/// `Describe` under the instance's timeout, refused when the module speaks a protocol version +/// outside the supported range, requires a capability this Guardian lacks, or no longer supports +/// a configured hook. The startup checks and the periodic health probe share it. +pub async fn describe_healthy( + config: &InstanceConfig, + module: &Arc, +) -> Result { let describing = module.clone(); let info = isolated(config.timeout, async move { describing.describe(&describe_request()).await @@ -273,9 +285,7 @@ pub async fn check( return Err(format!("module does not support hook {hook:?}")); } } - - let params = validate_params(module, params, config.timeout).await?; - Ok(Checked { info, params }) + Ok(info) } /// Asks the module whether `params` are valid; used at startup and for every params write. diff --git a/speckit/features/251-guardian-modules/tasks.md b/speckit/features/251-guardian-modules/tasks.md index ad980b1e..9f0a63ce 100644 --- a/speckit/features/251-guardian-modules/tasks.md +++ b/speckit/features/251-guardian-modules/tasks.md @@ -119,16 +119,16 @@ ### Tests for User Story 4 -- [ ] T027 [P] [US4] Failure acceptance in `crates/server/src/modules/pipeline.rs` tests: fail-closed unreachable refuses retryably; fail-open unreachable proceeds and is counted; consecutive failures open the circuit and later requests do not wait the timeout; combined time over the budget times out the remaining instances; a fail-open failure followed by a deny is refused by the second +- [X] T027 [P] [US4] Failure acceptance in `crates/server/src/modules/pipeline.rs` tests: fail-closed unreachable refuses retryably; fail-open unreachable proceeds and is counted; consecutive failures open the circuit and later requests do not wait the timeout; combined time over the budget times out the remaining instances; a fail-open failure followed by a deny is refused by the second ### Implementation for User Story 4 -- [ ] T028 [US4] Evaluation budget `GUARDIAN_MODULE_EVALUATION_BUDGET_MS` (default 1000) in a new `crates/server/src/modules/budget.rs`, enforced per hook invocation in `crates/server/src/modules/pipeline.rs` (remaining instances count as timed out and their `on_error` applies) +- [X] T028 [US4] Evaluation budget `GUARDIAN_MODULE_EVALUATION_BUDGET_MS` (default 1000) in a new `crates/server/src/modules/budget.rs`, enforced per hook invocation in `crates/server/src/modules/pipeline.rs` (remaining instances count as timed out and their `on_error` applies) - [ ] T029 [US4] Startup budget checks in `crates/server/src/modules/catalog.rs`: in the prod stage refuse to start when, for any hook, the timeouts of `all` and `default` instances (enabled or not) exceed the budget, or the budget is not below the execution reservation lease; report over-budget stored assignments without blocking - [ ] T030 [US4] Budget check on operator writes in `crates/server/src/modules/admin.rs`: refuse `PUT /dashboard/accounts/{account_id}/modules` and account-layer writes whose effective set exceeds the budget on any hook (`invalid_input`), with tests -- [ ] T031 [US4] Circuit breaker per instance in a new `crates/server/src/modules/breaker.rs` (consecutive-failure threshold, open, half-open probe), consulted in `crates/server/src/modules/pipeline.rs`; an open circuit applies `on_error` without calling the module -- [ ] T032 [US4] Periodic health probe (`Describe`) per instance on each replica in `crates/server/src/modules/breaker.rs`, closing the circuit on success and detecting protocol or hook changes; wire its task in `crates/server/src/builder/mod.rs` with shutdown -- [ ] T033 [US4] Request size cap `GUARDIAN_MODULE_REQUEST_MAX_BYTES` (default 2 MiB) in `crates/server/src/modules/request.rs`: an oversized request is a module failure without the call +- [X] T031 [US4] Circuit breaker per instance in a new `crates/server/src/modules/breaker.rs` (consecutive-failure threshold, open, half-open probe), consulted in `crates/server/src/modules/pipeline.rs`; an open circuit applies `on_error` without calling the module +- [X] T032 [US4] Periodic health probe (`Describe`) per instance on each replica in `crates/server/src/modules/breaker.rs`, closing the circuit on success and detecting protocol or hook changes; wire its task in `crates/server/src/builder/mod.rs` with shutdown +- [X] T033 [US4] Request size cap `GUARDIAN_MODULE_REQUEST_MAX_BYTES` (default 2 MiB) in `crates/server/src/modules/request.rs`: an oversized request is a module failure without the call - [ ] T034 [US4] Module metrics in a new `crates/server/src/modules/metrics.rs` with names in `crates/server/src/metrics/names.rs`: `guardian_module_evaluate_duration_seconds{module, outcome}` (`allow`, `deny`, `error`, `skipped`), `guardian_module_fail_open_total{module}`, availability, circuit state, disabled state, configuration drift, catalog fingerprint, orphaned and over-budget assignment counts - [ ] T035 [US4] Catalog fingerprint in `GET /dashboard/info` (`crates/server/src/services/dashboard_info.rs`) and the `circuit` field in `GET /dashboard/modules` (`crates/server/src/modules/admin.rs`); regenerate `docs/openapi*.json` with `cargo run --features evm --bin gen-openapi -- docs` - [ ] T036 [US4] Document the budget, size cap and breaker variables in `docs/CONFIGURATION.md` ("Runtime: policy modules") and the metrics in `docs/guides/observability/` From 87ddc456ef7960033a582c7967c8684043a9d1c3 Mon Sep 17 00:00:00 2001 From: Zeljko Date: Mon, 9 Nov 2026 10:25:42 +0100 Subject: [PATCH 019/105] feat(modules): evaluation budget checks at startup and on operator writes (#251) In the prod stage the server refuses to start when, for any hook, the timeouts of the instances every new account receives exceed the evaluation budget, or when the budget is not below the execution reservation lease. Assigning modules to an account or setting an account layer is refused when the account's worst case (each all instance, again for its layer, plus each assigned one) could exceed the budget. Accounts already stored over the budget are logged at startup without blocking it, so a deploy that raises a timeout cannot become an outage. --- crates/server/src/builder/mod.rs | 1 + crates/server/src/modules/admin.rs | 140 ++++++++++++++++++ crates/server/src/modules/catalog.rs | 87 +++++++++++ crates/server/src/modules/mod.rs | 9 +- crates/server/src/modules/pipeline.rs | 75 ++++++++++ crates/server/src/modules/postgres_store.rs | 38 +++-- crates/server/src/modules/registry.rs | 1 + crates/server/src/modules/store.rs | 11 ++ crates/server/src/modules/testing.rs | 4 + .../features/251-guardian-modules/tasks.md | 4 +- 10 files changed, 352 insertions(+), 18 deletions(-) diff --git a/crates/server/src/builder/mod.rs b/crates/server/src/builder/mod.rs index b840d98f..7200eee4 100644 --- a/crates/server/src/builder/mod.rs +++ b/crates/server/src/builder/mod.rs @@ -785,6 +785,7 @@ impl ServerBuilder { chrono::Utc::now().to_rfc3339(), module_store, &module_registry, + self.execution.lease, ) .await?; diff --git a/crates/server/src/modules/admin.rs b/crates/server/src/modules/admin.rs index 2ab5a371..5b995ed3 100644 --- a/crates/server/src/modules/admin.rs +++ b/crates/server/src/modules/admin.rs @@ -430,6 +430,21 @@ pub async fn set_layer( Some(params) => Some(validated(instance, ¶ms).await?), None => None, }; + let mut rows = pipeline + .store() + .account_params(&account_id) + .await + .map_err(GuardianError::StorageError)?; + rows.retain(|row| !(row.kind == ParamsKind::Layer && row.module_id == module_id)); + if let Some(params) = ¶ms { + rows.push(proposed_row( + &account_id, + module_id, + ParamsKind::Layer, + params, + )); + } + pipeline.check_budget(&rows)?; pipeline .store() .set_layer( @@ -452,6 +467,24 @@ pub async fn set_layer( account_view(state, &account_id).await } +/// A row as a pending write would store it, for the budget check before the write. +fn proposed_row( + account_id: &str, + module_id: &str, + kind: ParamsKind, + params: &serde_json::Value, +) -> super::store::AccountParamsRow { + super::store::AccountParamsRow { + account_id: account_id.to_string(), + module_id: module_id.to_string(), + kind, + position: 0, + params: params.clone(), + updated_at: String::new(), + updated_by: String::new(), + } +} + pub async fn set_assignment( state: &AppState, operator: &AuthenticatedOperator, @@ -486,6 +519,21 @@ pub async fn set_assignment( params: validated(instance, &assigned.params).await?, }); } + let mut rows = pipeline + .store() + .account_params(&account_id) + .await + .map_err(GuardianError::StorageError)?; + rows.retain(|row| row.kind == ParamsKind::Layer); + rows.extend(to_store.iter().map(|assigned| { + proposed_row( + &account_id, + &assigned.module_id, + ParamsKind::Assignment, + &assigned.params, + ) + })); + pipeline.check_budget(&rows)?; pipeline .store() .set_assignment(&account_id, to_store, &change(state, operator, reason)) @@ -607,6 +655,98 @@ mod tests { ); } + /// `state()`'s instances (50 ms each; `blocklist` and `vendor` on every account) under a + /// 120 ms budget: 100 ms before any account write. + fn tight_budget(state: &mut AppState) { + let instances = state.modules.as_ref().unwrap().instances().to_vec(); + state.modules = Some(Arc::new( + ModulePipeline::from_instances(instances).with_limits(crate::modules::limits::Limits { + budget: std::time::Duration::from_millis(120), + ..Default::default() + }), + )); + } + + #[tokio::test] + async fn an_account_write_that_could_exceed_the_budget_is_refused_and_stores_nothing() { + let mut state = state(); + tight_budget(&mut state); + let layer = set_layer( + &state, + &operator(), + ACCOUNT, + "blocklist", + Some(json!({ "recipient_denylist": ["0xbbb"] })), + "OP-1", + None, + ) + .await; + assert!( + matches!(&layer, Err(GuardianError::InvalidInput(message)) if message.contains("budget")), + "{layer:?}" + ); + let assignment = set_assignment( + &state, + &operator(), + ACCOUNT, + vec![Assigned { + module_id: "optional".into(), + params: json!({}), + }], + "OP-2", + None, + ) + .await; + assert!(matches!(assignment, Err(GuardianError::InvalidInput(_)))); + let pipeline = state.modules.as_ref().unwrap(); + assert!( + pipeline + .store() + .account_params(ACCOUNT) + .await + .unwrap() + .is_empty() + ); + } + + #[tokio::test] + async fn accounts_stored_over_the_budget_are_reported_at_startup() { + let mut state = state(); + set_assignment( + &state, + &operator(), + ACCOUNT, + vec![Assigned { + module_id: "optional".into(), + params: json!({}), + }], + "OP-3", + None, + ) + .await + .unwrap(); + let store = state.modules.as_ref().unwrap().store_handle(); + let instances = state.modules.as_ref().unwrap().instances().to_vec(); + state.modules = Some(Arc::new( + ModulePipeline::from_instances_with_store(instances, store).with_limits( + crate::modules::limits::Limits { + budget: std::time::Duration::from_millis(120), + ..Default::default() + }, + ), + )); + assert_eq!( + state + .modules + .as_ref() + .unwrap() + .report_over_budget() + .await + .unwrap(), + 1 + ); + } + #[tokio::test] async fn global_and_account_writes_are_validated_recorded_and_visible() { let state = state(); diff --git a/crates/server/src/modules/catalog.rs b/crates/server/src/modules/catalog.rs index 2690bd8b..a21e3bce 100644 --- a/crates/server/src/modules/catalog.rs +++ b/crates/server/src/modules/catalog.rs @@ -35,6 +35,12 @@ pub enum HookName { } impl HookName { + pub const GATES: [HookName; 3] = [ + HookName::BeforeTransactionApproved, + HookName::BeforeProposalCreated, + HookName::BeforeAccountRegistered, + ]; + /// The catalog spelling, for example `before_transaction_approved`. pub fn as_str(self) -> &'static str { match self { @@ -246,6 +252,38 @@ impl Catalog { Ok(()) } + /// Prod-stage budget checks: for every hook, the timeouts of the instances every new account + /// receives (all but `assigned`, enabled or not, since enabling needs no further check) fit + /// in `budget`, and `budget` is below the execution reservation `lease`. + pub fn check_budget(&self, budget: Duration, lease: Duration) -> Result<(), String> { + if budget >= lease { + return Err(format!( + "the module evaluation budget ({} ms) must be below the execution reservation \ + lease ({} ms)", + budget.as_millis(), + lease.as_millis() + )); + } + for hook in HookName::GATES { + let total: Duration = self + .instances + .iter() + .filter(|config| config.scope != Scope::Assigned && config.hooks.contains(&hook)) + .map(|config| config.timeout) + .sum(); + if total > budget { + return Err(format!( + "the timeouts of the modules every account receives at {} add up to {} ms, \ + over the evaluation budget of {} ms", + hook.as_str(), + total.as_millis(), + budget.as_millis() + )); + } + } + Ok(()) + } + pub fn load(path: &Path) -> Result { let text = std::fs::read_to_string(path) .map_err(|e| format!("cannot read module catalog {}: {e}", path.display()))?; @@ -419,6 +457,55 @@ timeout_ms = 20 on_error = "allow" "#; + fn timed(instances: &[(&str, &str, u64)]) -> Catalog { + let text: String = instances + .iter() + .map(|(id, scope, timeout_ms)| { + format!( + "[[module]]\nid = \"{id}\"\nkind = \"basic-policy\"\nscope = \"{scope}\"\n\ + hooks = [\"before_transaction_approved\"]\ntimeout_ms = {timeout_ms}\n\n" + ) + }) + .collect(); + parse(&text).unwrap() + } + + #[test] + fn the_modules_every_account_receives_must_fit_in_the_budget() { + let budget = Duration::from_millis(1_000); + let lease = Duration::from_secs(60); + assert!( + timed(&[("a", "all", 500), ("b", "all", 500)]) + .check_budget(budget, lease) + .is_ok() + ); + let over = timed(&[("a", "all", 600), ("b", "all", 600)]) + .check_budget(budget, lease) + .unwrap_err(); + assert!(over.contains("before_transaction_approved"), "{over}"); + assert!( + timed(&[("a", "all", 600), ("b", "assigned", 600)]) + .check_budget(budget, lease) + .is_ok(), + "assigned instances are checked per account, not at startup" + ); + } + + #[test] + fn the_budget_must_be_below_the_execution_lease() { + let catalog = timed(&[("a", "all", 10)]); + assert!( + catalog + .check_budget(Duration::from_secs(30), Duration::from_secs(30)) + .is_err() + ); + assert!( + catalog + .check_budget(Duration::from_secs(1), Duration::from_secs(30)) + .is_ok() + ); + } + #[test] fn parses_instances() { let catalog = parse(VALID).unwrap(); diff --git a/crates/server/src/modules/mod.rs b/crates/server/src/modules/mod.rs index 5d1661c7..2f11184d 100644 --- a/crates/server/src/modules/mod.rs +++ b/crates/server/src/modules/mod.rs @@ -45,25 +45,28 @@ pub async fn from_env( now: String, store: Option>, registry: &Registry, + execution_lease: std::time::Duration, ) -> Result>, String> { let Some(path) = std::env::var_os(CONFIG_ENV).filter(|value| !value.is_empty()) else { return Ok(None); }; let catalog_path = PathBuf::from(path); let catalog = Catalog::load(&catalog_path)?; + let limits = limits::Limits::from_env()?; if crate::config::stage::Stage::from_env() .map_err(|e| e.to_string())? .is_prod() { catalog.check_production()?; + catalog.check_budget(limits.budget, execution_lease)?; } let store = match store { Some(store) => store, None => Arc::new(filesystem_store(&catalog_path)?), }; - let pipeline = - ModulePipeline::new(catalog, registry, store, now, limits::Limits::from_env()?).await?; + let pipeline = ModulePipeline::new(catalog, registry, store, now, limits).await?; let version = pipeline.store().version().await?; + let over_budget = pipeline.report_over_budget().await?; let builds = pipeline .instances() .iter() @@ -76,6 +79,6 @@ pub async fn from_env( }) .collect::>() .join(", "); - tracing::info!(catalog_hash = %pipeline.catalog_hash, params_version = version, %builds, "Policy modules loaded"); + tracing::info!(catalog_hash = %pipeline.catalog_hash, params_version = version, %builds, over_budget, "Policy modules loaded"); Ok(Some(Arc::new(pipeline))) } diff --git a/crates/server/src/modules/pipeline.rs b/crates/server/src/modules/pipeline.rs index 1a175e7c..c8479cb4 100644 --- a/crates/server/src/modules/pipeline.rs +++ b/crates/server/src/modules/pipeline.rs @@ -240,6 +240,76 @@ impl ModulePipeline { &self.breakers } + /// The hook with the largest worst-case module time for an account whose module rows are + /// `rows`, and that time: every `scope = all` instance, once more for an account layer on + /// it, plus every listed instance. Disabled instances count, since enabling needs no further + /// check; a row naming an instance the catalog no longer declares costs nothing. + pub fn worst_case(&self, rows: &[AccountParamsRow]) -> (HookName, std::time::Duration) { + let calls = |id: &str, kind: ParamsKind| { + rows.iter() + .filter(|row| row.kind == kind && row.module_id == id) + .count() as u32 + }; + HookName::GATES + .into_iter() + .map(|hook| { + let total = self + .instances + .iter() + .filter(|instance| instance.config.hooks.contains(&hook)) + .map(|instance| { + let id = instance.config.id.as_str(); + let count = match instance.config.scope { + Scope::All => 1 + calls(id, ParamsKind::Layer), + Scope::Assigned => calls(id, ParamsKind::Assignment), + }; + instance.config.timeout * count + }) + .sum(); + (hook, total) + }) + .max_by_key(|(_, total)| *total) + .unwrap_or(( + HookName::BeforeTransactionApproved, + std::time::Duration::ZERO, + )) + } + + /// Refuses an account whose modules, with `rows` stored, could exceed the evaluation budget. + pub fn check_budget(&self, rows: &[AccountParamsRow]) -> Result<(), GuardianError> { + let (hook, total) = self.worst_case(rows); + if total > self.limits.budget { + return Err(GuardianError::InvalidInput(format!( + "the account's modules at {} take up to {} ms, over the evaluation budget of {} ms", + hook.as_str(), + total.as_millis(), + self.limits.budget.as_millis() + ))); + } + Ok(()) + } + + /// Logs every account whose stored modules exceed the budget, without refusing to start: a + /// deploy that raised a timeout must not become an outage. Returns their count. + pub async fn report_over_budget(&self) -> Result { + let rows = self.store.all_account_params().await?; + let mut over = 0; + for account in rows.chunk_by(|a, b| a.account_id == b.account_id) { + let (hook, total) = self.worst_case(account); + if total > self.limits.budget { + over += 1; + tracing::warn!( + account_id = %account[0].account_id, + hook = hook.as_str(), + worst_case_ms = total.as_millis() as u64, + budget_ms = self.limits.budget.as_millis() as u64, + "Account's policy modules exceed the evaluation budget; the runtime budget applies" + ); + } + } + Ok(over) + } + /// One health probe of every enabled instance: `Describe` under its timeout, with the startup /// checks. A healthy module half-opens an open breaker so the next real call is sent. pub async fn probe(&self) { @@ -280,6 +350,11 @@ impl ModulePipeline { .find(|instance| instance.config.id == module_id) } + #[cfg(test)] + pub fn store_handle(&self) -> Arc { + self.store.clone() + } + pub fn store(&self) -> &dyn ModuleStore { self.store.as_ref() } diff --git a/crates/server/src/modules/postgres_store.rs b/crates/server/src/modules/postgres_store.rs index 3c02531c..c17f715f 100644 --- a/crates/server/src/modules/postgres_store.rs +++ b/crates/server/src/modules/postgres_store.rs @@ -145,6 +145,18 @@ async fn append( .await } +fn account_params_row(row: AccountParamsSql) -> Result { + Ok(AccountParamsRow { + account_id: row.account_id, + module_id: row.module_id, + kind: ParamsKind::parse(&row.kind)?, + position: row.position, + params: row.params, + updated_at: row.updated_at.to_rfc3339(), + updated_by: row.updated_by, + }) +} + #[async_trait] impl ModuleStore for PgModuleStore { async fn seed_instance( @@ -395,19 +407,19 @@ impl ModuleStore for PgModuleStore { .load(&mut conn) .await .map_err(|e| format!("account module params: {e}"))?; - rows.into_iter() - .map(|row| { - Ok(AccountParamsRow { - account_id: row.account_id, - module_id: row.module_id, - kind: ParamsKind::parse(&row.kind)?, - position: row.position, - params: row.params, - updated_at: row.updated_at.to_rfc3339(), - updated_by: row.updated_by, - }) - }) - .collect() + rows.into_iter().map(account_params_row).collect() + } + + async fn all_account_params(&self) -> Result, String> { + let mut conn = self.conn().await?; + let rows: Vec = diesel::sql_query( + "SELECT account_id, module_id, kind, position, params, updated_at, updated_by \ + FROM module_account_params ORDER BY account_id, position, module_id", + ) + .load(&mut conn) + .await + .map_err(|e| format!("all account module params: {e}"))?; + rows.into_iter().map(account_params_row).collect() } async fn set_layer( diff --git a/crates/server/src/modules/registry.rs b/crates/server/src/modules/registry.rs index 18c995d1..72a31d45 100644 --- a/crates/server/src/modules/registry.rs +++ b/crates/server/src/modules/registry.rs @@ -12,6 +12,7 @@ use guardian_module_sdk::{ use super::catalog::{Catalog, InstanceConfig}; use super::grpc_kind::GrpcFactory; +#[derive(Clone)] pub struct Instance { pub config: InstanceConfig, pub module: Arc, diff --git a/crates/server/src/modules/store.rs b/crates/server/src/modules/store.rs index 5015f122..d00d94fe 100644 --- a/crates/server/src/modules/store.rs +++ b/crates/server/src/modules/store.rs @@ -122,6 +122,9 @@ pub trait ModuleStore: Send + Sync { async fn account_params(&self, account_id: &str) -> Result, String>; + /// Every account's rows, ordered by account and position; a startup scan, not a hot path. + async fn all_account_params(&self) -> Result, String>; + async fn set_layer( &self, account_id: &str, @@ -407,6 +410,14 @@ impl ModuleStore for FsModuleStore { })) } + async fn all_account_params(&self) -> Result, String> { + Ok(self.read(|tables| { + let mut rows = tables.account_params.clone(); + rows.sort_by(|a, b| (&a.account_id, a.position).cmp(&(&b.account_id, b.position))); + rows + })) + } + async fn set_layer( &self, account_id: &str, diff --git a/crates/server/src/modules/testing.rs b/crates/server/src/modules/testing.rs index 5f80a444..ddbca8a7 100644 --- a/crates/server/src/modules/testing.rs +++ b/crates/server/src/modules/testing.rs @@ -310,6 +310,10 @@ impl super::store::ModuleStore for RacingStore { self.inner.account_params(account_id).await } + async fn all_account_params(&self) -> Result, String> { + self.inner.all_account_params().await + } + async fn set_layer( &self, account_id: &str, diff --git a/speckit/features/251-guardian-modules/tasks.md b/speckit/features/251-guardian-modules/tasks.md index 9f0a63ce..542750eb 100644 --- a/speckit/features/251-guardian-modules/tasks.md +++ b/speckit/features/251-guardian-modules/tasks.md @@ -124,8 +124,8 @@ ### Implementation for User Story 4 - [X] T028 [US4] Evaluation budget `GUARDIAN_MODULE_EVALUATION_BUDGET_MS` (default 1000) in a new `crates/server/src/modules/budget.rs`, enforced per hook invocation in `crates/server/src/modules/pipeline.rs` (remaining instances count as timed out and their `on_error` applies) -- [ ] T029 [US4] Startup budget checks in `crates/server/src/modules/catalog.rs`: in the prod stage refuse to start when, for any hook, the timeouts of `all` and `default` instances (enabled or not) exceed the budget, or the budget is not below the execution reservation lease; report over-budget stored assignments without blocking -- [ ] T030 [US4] Budget check on operator writes in `crates/server/src/modules/admin.rs`: refuse `PUT /dashboard/accounts/{account_id}/modules` and account-layer writes whose effective set exceeds the budget on any hook (`invalid_input`), with tests +- [X] T029 [US4] Startup budget checks in `crates/server/src/modules/catalog.rs`: in the prod stage refuse to start when, for any hook, the timeouts of `all` and `default` instances (enabled or not) exceed the budget, or the budget is not below the execution reservation lease; report over-budget stored assignments without blocking +- [X] T030 [US4] Budget check on operator writes in `crates/server/src/modules/admin.rs`: refuse `PUT /dashboard/accounts/{account_id}/modules` and account-layer writes whose effective set exceeds the budget on any hook (`invalid_input`), with tests - [X] T031 [US4] Circuit breaker per instance in a new `crates/server/src/modules/breaker.rs` (consecutive-failure threshold, open, half-open probe), consulted in `crates/server/src/modules/pipeline.rs`; an open circuit applies `on_error` without calling the module - [X] T032 [US4] Periodic health probe (`Describe`) per instance on each replica in `crates/server/src/modules/breaker.rs`, closing the circuit on success and detecting protocol or hook changes; wire its task in `crates/server/src/builder/mod.rs` with shutdown - [X] T033 [US4] Request size cap `GUARDIAN_MODULE_REQUEST_MAX_BYTES` (default 2 MiB) in `crates/server/src/modules/request.rs`: an oversized request is a module failure without the call From c5748352ffa16cc5e7f14db4716c7303dfc82d2c Mon Sep 17 00:00:00 2001 From: Zeljko Date: Mon, 9 Nov 2026 10:33:02 +0100 Subject: [PATCH 020/105] feat(modules): module metrics, the catalog hash on /dashboard/info and circuit state (#251) Module evaluations are measured per instance and outcome (allow, deny, error, skipped), with fail-open passes counted, and gauges for the probe result, open circuits, enabled and drifted instances, the loaded catalog, and the accounts over budget and orphaned rows found at startup. GET /dashboard/info reports the replica's module catalog hash (backend.module_catalog_hash, null without a catalog), parsed by the operator client, and GET /dashboard/modules each instance's circuit on the answering replica. OpenAPI regenerated. --- crates/server/src/metrics/names.rs | 72 ++++++++++++++++++ crates/server/src/modules/admin.rs | 29 +++++++- crates/server/src/modules/breaker.rs | 1 + crates/server/src/modules/metrics.rs | 73 +++++++++++++++++++ crates/server/src/modules/mod.rs | 7 +- crates/server/src/modules/pipeline.rs | 35 ++++++++- crates/server/src/services/dashboard_info.rs | 20 +++++ docs/openapi-dashboard.json | 7 ++ docs/openapi.json | 7 ++ .../guardian-operator-client/src/http.test.ts | 30 ++++++++ packages/guardian-operator-client/src/http.ts | 12 +++ .../guardian-operator-client/src/types.ts | 3 + .../features/251-guardian-modules/tasks.md | 6 +- 13 files changed, 291 insertions(+), 11 deletions(-) create mode 100644 crates/server/src/modules/metrics.rs diff --git a/crates/server/src/metrics/names.rs b/crates/server/src/metrics/names.rs index 94ae9f8e..f07e77ae 100644 --- a/crates/server/src/metrics/names.rs +++ b/crates/server/src/metrics/names.rs @@ -139,6 +139,18 @@ pub const DASHBOARD_STATS_REFRESH_FAILURES_TOTAL: &str = pub const DASHBOARD_STATS_REFRESH_DURATION_SECONDS: &str = "guardian_dashboard_stats_refresh_duration_seconds"; +// --- Policy modules ------------------------------------------------------- + +pub const MODULE_EVALUATE_DURATION_SECONDS: &str = "guardian_module_evaluate_duration_seconds"; +pub const MODULE_FAIL_OPEN_TOTAL: &str = "guardian_module_fail_open_total"; +pub const MODULE_UP: &str = "guardian_module_up"; +pub const MODULE_CIRCUIT_OPEN: &str = "guardian_module_circuit_open"; +pub const MODULE_ENABLED: &str = "guardian_module_enabled"; +pub const MODULE_CONFIG_DRIFT: &str = "guardian_module_config_drift"; +pub const MODULE_CATALOG_INFO: &str = "guardian_module_catalog_info"; +pub const MODULE_OVER_BUDGET_ACCOUNTS: &str = "guardian_module_over_budget_accounts"; +pub const MODULE_ORPHANED_ASSIGNMENTS: &str = "guardian_module_orphaned_assignments"; + // --- Build identity ------------------------------------------------------ pub const BUILD_INFO: &str = "guardian_build_info"; @@ -162,6 +174,10 @@ pub const LABEL_GIT_COMMIT: &str = "git_commit"; pub const LABEL_PROFILE: &str = "profile"; pub const LABEL_PHASE: &str = "phase"; pub const LABEL_REASON: &str = "reason"; +/// A policy module instance id; bounded by the operator's catalog. +pub const LABEL_MODULE: &str = "module"; +/// The loaded module catalog's hash; one value per deploy. +pub const LABEL_CATALOG_HASH: &str = "catalog_hash"; /// The closed value set for `LABEL_TRANSPORT`: the request transports, /// and the block transports of block watch (`stream`, `poll`). @@ -189,6 +205,8 @@ pub const LABEL_ALLOWLIST: &[&str] = &[ LABEL_PROFILE, LABEL_PHASE, LABEL_REASON, + LABEL_MODULE, + LABEL_CATALOG_HASH, ]; /// Metric type, mirroring the Prometheus instrument kinds in use. @@ -658,6 +676,60 @@ pub const REGISTRY: &[MetricDef] = &[ help: "Wall-clock duration of one /dashboard/stats aggregate refresh \ (metadata walk, batched state reads, vault decoding).", }, + MetricDef { + name: MODULE_EVALUATE_DURATION_SECONDS, + kind: MetricKind::Histogram, + labels: &[LABEL_MODULE, LABEL_OUTCOME], + help: "Policy module evaluations in seconds, by instance and outcome (allow, deny, error, skipped).", + }, + MetricDef { + name: MODULE_FAIL_OPEN_TOTAL, + kind: MetricKind::Counter, + labels: &[LABEL_MODULE], + help: "Policy module failures a fail-open instance let through, by instance.", + }, + MetricDef { + name: MODULE_UP, + kind: MetricKind::Gauge, + labels: &[LABEL_MODULE], + help: "1 when the instance's last health probe succeeded, 0 when it failed.", + }, + MetricDef { + name: MODULE_CIRCUIT_OPEN, + kind: MetricKind::Gauge, + labels: &[LABEL_MODULE], + help: "1 while the instance's circuit breaker is open on this replica.", + }, + MetricDef { + name: MODULE_ENABLED, + kind: MetricKind::Gauge, + labels: &[LABEL_MODULE], + help: "1 when the instance is enabled, 0 when an operator disabled it.", + }, + MetricDef { + name: MODULE_CONFIG_DRIFT, + kind: MetricKind::Gauge, + labels: &[LABEL_MODULE], + help: "1 when the catalog's enabled flag or params differ from the stored runtime values.", + }, + MetricDef { + name: MODULE_CATALOG_INFO, + kind: MetricKind::Gauge, + labels: &[LABEL_CATALOG_HASH], + help: "The module catalog this replica loaded (constant 1).", + }, + MetricDef { + name: MODULE_OVER_BUDGET_ACCOUNTS, + kind: MetricKind::Gauge, + labels: &[], + help: "Accounts whose stored modules could exceed the evaluation budget, found at startup.", + }, + MetricDef { + name: MODULE_ORPHANED_ASSIGNMENTS, + kind: MetricKind::Gauge, + labels: &[], + help: "Stored account module rows naming an instance the catalog no longer declares, found at startup.", + }, ]; /// Bound the `route` label to the axum route template. Templates like diff --git a/crates/server/src/modules/admin.rs b/crates/server/src/modules/admin.rs index 5b995ed3..0dd9c17d 100644 --- a/crates/server/src/modules/admin.rs +++ b/crates/server/src/modules/admin.rs @@ -31,6 +31,9 @@ pub struct ModuleInstanceView { pub description: Option, pub client_reason: ClientReason, pub dry_run: bool, + /// The instance's circuit breaker on the replica that answered: `closed`, `open` or + /// `half_open`. + pub circuit: &'static str, } #[derive(Debug, Clone, Serialize)] @@ -197,6 +200,7 @@ async fn instance_view( description: instance.config.description.clone(), client_reason: instance.config.client_reason, dry_run: instance.config.dry_run, + circuit: pipeline.breakers().state(&instance.config.id).as_str(), }) } @@ -326,6 +330,7 @@ pub async fn enable( .set_enabled(module_id, true, &change(state, operator, reason)) .await .map_err(GuardianError::StorageError)?; + super::metrics::enabled(module_id, true); } let payload = serde_json::json!({ "module_id": module_id, "reason": reason, "params_version": version(pipeline).await? }); audit( @@ -361,6 +366,7 @@ pub async fn disable( .set_enabled(module_id, false, &change(state, operator, reason)) .await .map_err(GuardianError::StorageError)?; + super::metrics::enabled(module_id, false); } let payload = serde_json::json!({ "module_id": module_id, "reason": reason, "params_version": version(pipeline).await? }); audit( @@ -667,6 +673,25 @@ mod tests { )); } + #[tokio::test] + async fn the_catalog_view_shows_each_instance_circuit_on_this_replica() { + let state = state(); + let pipeline = state.modules.as_ref().unwrap(); + for _ in 0..crate::modules::limits::Limits::default().breaker_failures { + pipeline.breakers().failed("blocklist"); + } + let view = catalog_view(&state).await.unwrap(); + let circuit = |id: &str| { + view.modules + .iter() + .find(|module| module.module_id == id) + .unwrap() + .circuit + }; + assert_eq!(circuit("blocklist"), "open"); + assert_eq!(circuit("optional"), "closed"); + } + #[tokio::test] async fn an_account_write_that_could_exceed_the_budget_is_refused_and_stores_nothing() { let mut state = state(); @@ -740,10 +765,10 @@ mod tests { .modules .as_ref() .unwrap() - .report_over_budget() + .report_stored_assignments() .await .unwrap(), - 1 + (1, 0) ); } diff --git a/crates/server/src/modules/breaker.rs b/crates/server/src/modules/breaker.rs index 02c2b1b7..19d7d3c0 100644 --- a/crates/server/src/modules/breaker.rs +++ b/crates/server/src/modules/breaker.rs @@ -105,6 +105,7 @@ impl Breakers { Err(_) => return, }; if previous != current { + super::metrics::circuit_open(instance, current == CircuitState::Open); tracing::warn!( module = instance, from = previous.as_str(), diff --git a/crates/server/src/modules/metrics.rs b/crates/server/src/modules/metrics.rs new file mode 100644 index 00000000..ab9a63c7 --- /dev/null +++ b/crates/server/src/modules/metrics.rs @@ -0,0 +1,73 @@ +//! Policy module metrics; names and help text are declared in `crate::metrics::names`. + +use std::time::Duration; + +use crate::metrics::names; + +#[derive(Debug, Clone, Copy)] +pub enum Outcome { + Allow, + Deny, + Error, + /// Not called: open circuit, oversized request or spent budget. + Skipped, +} + +impl Outcome { + fn as_str(self) -> &'static str { + match self { + Outcome::Allow => "allow", + Outcome::Deny => "deny", + Outcome::Error => "error", + Outcome::Skipped => "skipped", + } + } +} + +pub fn evaluated(module: &str, outcome: Outcome, took: Duration) { + metrics::histogram!( + names::MODULE_EVALUATE_DURATION_SECONDS, + names::LABEL_MODULE => module.to_string(), + names::LABEL_OUTCOME => outcome.as_str() + ) + .record(took.as_secs_f64()); +} + +pub fn failed_open(module: &str) { + metrics::counter!(names::MODULE_FAIL_OPEN_TOTAL, names::LABEL_MODULE => module.to_string()) + .increment(1); +} + +fn flag(name: &'static str, module: &str, on: bool) { + metrics::gauge!(name, names::LABEL_MODULE => module.to_string()).set(if on { + 1.0 + } else { + 0.0 + }); +} + +pub fn up(module: &str, up: bool) { + flag(names::MODULE_UP, module, up); +} + +pub fn circuit_open(module: &str, open: bool) { + flag(names::MODULE_CIRCUIT_OPEN, module, open); +} + +pub fn enabled(module: &str, enabled: bool) { + flag(names::MODULE_ENABLED, module, enabled); +} + +pub fn config_drift(module: &str, drift: bool) { + flag(names::MODULE_CONFIG_DRIFT, module, drift); +} + +pub fn catalog(catalog_hash: &str) { + metrics::gauge!(names::MODULE_CATALOG_INFO, names::LABEL_CATALOG_HASH => catalog_hash.to_string()) + .set(1.0); +} + +pub fn stored_assignments(over_budget_accounts: usize, orphaned_rows: usize) { + metrics::gauge!(names::MODULE_OVER_BUDGET_ACCOUNTS).set(over_budget_accounts as f64); + metrics::gauge!(names::MODULE_ORPHANED_ASSIGNMENTS).set(orphaned_rows as f64); +} diff --git a/crates/server/src/modules/mod.rs b/crates/server/src/modules/mod.rs index 2f11184d..52502954 100644 --- a/crates/server/src/modules/mod.rs +++ b/crates/server/src/modules/mod.rs @@ -7,6 +7,7 @@ pub mod check_limit; pub mod disclosure; pub mod grpc_kind; pub mod limits; +pub mod metrics; pub mod pipeline; #[cfg(feature = "postgres")] pub mod postgres_store; @@ -66,7 +67,9 @@ pub async fn from_env( }; let pipeline = ModulePipeline::new(catalog, registry, store, now, limits).await?; let version = pipeline.store().version().await?; - let over_budget = pipeline.report_over_budget().await?; + let (over_budget, orphaned) = pipeline.report_stored_assignments().await?; + metrics::catalog(&pipeline.catalog_hash); + metrics::stored_assignments(over_budget, orphaned); let builds = pipeline .instances() .iter() @@ -79,6 +82,6 @@ pub async fn from_env( }) .collect::>() .join(", "); - tracing::info!(catalog_hash = %pipeline.catalog_hash, params_version = version, %builds, over_budget, "Policy modules loaded"); + tracing::info!(catalog_hash = %pipeline.catalog_hash, params_version = version, %builds, over_budget, orphaned, "Policy modules loaded"); Ok(Some(Arc::new(pipeline))) } diff --git a/crates/server/src/modules/pipeline.rs b/crates/server/src/modules/pipeline.rs index c8479cb4..3911f8f8 100644 --- a/crates/server/src/modules/pipeline.rs +++ b/crates/server/src/modules/pipeline.rs @@ -129,8 +129,16 @@ impl ModulePipeline { let mut effective = HashMap::new(); for config in &mut catalog.instances { let Some((params, enabled)) = stored.get(&config.id) else { + super::metrics::enabled(&config.id, config.enabled); + super::metrics::config_drift(&config.id, false); continue; }; + super::metrics::enabled(&config.id, *enabled); + super::metrics::config_drift( + &config.id, + *enabled != config.catalog_enabled + || (!config.file_managed_params && *params != config.params), + ); if *enabled != config.catalog_enabled { tracing::warn!(module = %config.id, enabled, "Catalog `enabled` differs from the stored runtime flag; the stored flag applies"); } @@ -290,9 +298,14 @@ impl ModulePipeline { } /// Logs every account whose stored modules exceed the budget, without refusing to start: a - /// deploy that raised a timeout must not become an outage. Returns their count. - pub async fn report_over_budget(&self) -> Result { + /// deploy that raised a timeout must not become an outage. Returns the count of those + /// accounts and of stored rows naming an instance the catalog no longer declares. + pub async fn report_stored_assignments(&self) -> Result<(usize, usize), String> { let rows = self.store.all_account_params().await?; + let orphaned = rows + .iter() + .filter(|row| self.instance(&row.module_id).is_none()) + .count(); let mut over = 0; for account in rows.chunk_by(|a, b| a.account_id == b.account_id) { let (hook, total) = self.worst_case(account); @@ -307,7 +320,7 @@ impl ModulePipeline { ); } } - Ok(over) + Ok((over, orphaned)) } /// One health probe of every enabled instance: `Describe` under its timeout, with the startup @@ -317,7 +330,10 @@ impl ModulePipeline { if !matches!(self.enabled(instance).await, Ok(true)) { continue; } - match super::registry::describe_healthy(&instance.config, &instance.module).await { + let healthy = + super::registry::describe_healthy(&instance.config, &instance.module).await; + super::metrics::up(&instance.config.id, healthy.is_ok()); + match healthy { Ok(_) => self.breakers.probe_succeeded(&instance.config.id), Err(error) => tracing::warn!( module = %instance.config.id, @@ -616,6 +632,11 @@ impl Plan<'_> { None }; if let Some(failure) = unsent { + super::metrics::evaluated( + id, + super::metrics::Outcome::Skipped, + std::time::Duration::ZERO, + ); approval .failed_open .extend(fail(instance, layer, account_id, &failure)?); @@ -625,19 +646,23 @@ impl Plan<'_> { // A call the budget cuts short counts as a timeout, but is not the module's failure. let cut_by_budget = remaining < instance.config.timeout; let module = instance.module.clone(); + let started = tokio::time::Instant::now(); let outcome = isolated(instance.config.timeout.min(remaining), async move { module.evaluate(&request).await }) .await; + let took = started.elapsed(); let failure = match outcome.map(|decision| (effect(&decision), decision)) { Ok((Some(Effect::Allow), _)) => { breakers.answered(id); + super::metrics::evaluated(id, super::metrics::Outcome::Allow, took); continue; } Ok((Some(Effect::Deny), decision)) if is_valid_reason_code(&decision.reason_code) => { breakers.answered(id); + super::metrics::evaluated(id, super::metrics::Outcome::Deny, took); tracing::info!( request_id = %request_id, module = %instance.config.id, @@ -670,6 +695,7 @@ impl Plan<'_> { } Err(CallError::Timeout) => Failure::Timeout, }; + super::metrics::evaluated(id, super::metrics::Outcome::Error, took); if !(cut_by_budget && matches!(failure, Failure::Timeout)) { breakers.failed(id); } @@ -723,6 +749,7 @@ fn fail( }) } OnError::Allow => { + super::metrics::failed_open(&instance.config.id); tracing::warn!(module = %instance.config.id, account_id, %failure, "Policy module failed; continuing (fail-open)"); Ok(Some(FailedOpen { module_id: instance.config.id.clone(), diff --git a/crates/server/src/services/dashboard_info.rs b/crates/server/src/services/dashboard_info.rs index 2c644fca..04abb684 100644 --- a/crates/server/src/services/dashboard_info.rs +++ b/crates/server/src/services/dashboard_info.rs @@ -171,6 +171,9 @@ pub struct DashboardBackendInfo { /// `None` when running in optimistic-commit mode; `Some(_)` when /// the canonicalization worker is active. pub canonicalization: Option, + /// Hash of the policy module catalog this replica loaded; `None` when + /// no catalog is configured. Replicas of one deploy report the same hash. + pub module_catalog_hash: Option, } #[derive(Debug, Clone, PartialEq, Eq, Serialize, utoipa::ToSchema)] @@ -300,6 +303,10 @@ pub async fn get_dashboard_info(state: &AppState) -> Result { } }); + + it('decodes the module catalog hash, absent without modules, and refuses a malformed one', async () => { + const info = (backendExtra: Record) => ({ + service_status: 'healthy', + environment: 'devnet', + build: { + version: '0.19.0', + git_commit: 'abcdef123456', + profile: 'release', + started_at: '2026-11-09T10:00:00Z', + }, + backend: { storage: 'postgres', supported_ack_schemes: ['ecdsa', 'falcon'], ...backendExtra }, + total_account_count: 1, + accounts_by_auth_method: {}, + latest_activity: null, + delta_status_counts: { candidate: 0, canonical: 0, retained: 0, discarded: 0 }, + in_flight_proposal_count: 0, + degraded_aggregates: [], + }); + const client = new GuardianOperatorHttpClient('https://guardian.example'); + + mockFetch.mockResolvedValueOnce(okJson(info({ module_catalog_hash: '0xcafe' }))); + expect((await client.getDashboardInfo()).backend.moduleCatalogHash).toBe('0xcafe'); + mockFetch.mockResolvedValueOnce(okJson(info({ module_catalog_hash: null }))); + expect((await client.getDashboardInfo()).backend.moduleCatalogHash).toBeNull(); + mockFetch.mockResolvedValueOnce(okJson(info({}))); + expect((await client.getDashboardInfo()).backend.moduleCatalogHash).toBeUndefined(); + mockFetch.mockResolvedValueOnce(okJson(info({ module_catalog_hash: 7 }))); + await expect(client.getDashboardInfo()).rejects.toThrow(/module_catalog_hash/); + }); it('passes limit and cursor query params for delta listing', async () => { mockFetch.mockResolvedValueOnce( okJson({ items: [], next_cursor: null }), diff --git a/packages/guardian-operator-client/src/http.ts b/packages/guardian-operator-client/src/http.ts index 2a53274d..5e6f6472 100644 --- a/packages/guardian-operator-client/src/http.ts +++ b/packages/guardian-operator-client/src/http.ts @@ -996,6 +996,18 @@ function parseDashboardInfo(value: unknown): DashboardInfoResponse { backend.blockWatch = parseBlockWatchInfo(blockWatchField); } + // Optional: absent on servers predating policy modules, null without a + // module catalog. + const catalogHashField = backendRecord.module_catalog_hash; + if (catalogHashField === null) { + backend.moduleCatalogHash = null; + } else if (catalogHashField !== undefined) { + if (typeof catalogHashField !== 'string') { + throw new Error('dashboard info.backend.module_catalog_hash must be a string or null'); + } + backend.moduleCatalogHash = catalogHashField; + } + const accountsByAuthMethod = requireCountMap( requireField(record, 'accounts_by_auth_method', 'dashboard info'), 'dashboard info.accounts_by_auth_method', diff --git a/packages/guardian-operator-client/src/types.ts b/packages/guardian-operator-client/src/types.ts index 0bb87809..584f6c8c 100644 --- a/packages/guardian-operator-client/src/types.ts +++ b/packages/guardian-operator-client/src/types.ts @@ -806,6 +806,9 @@ export interface DashboardBackendInfo { /** Block watch state; `null` when block watch is disabled, absent on * servers predating it. */ blockWatch?: DashboardBlockWatchInfo | null; + /** Hash of the policy module catalog the answering replica loaded; `null` + * when no catalog is configured, absent on servers predating modules. */ + moduleCatalogHash?: string | null; } export interface DashboardInfoResponse { diff --git a/speckit/features/251-guardian-modules/tasks.md b/speckit/features/251-guardian-modules/tasks.md index 542750eb..9cdc4885 100644 --- a/speckit/features/251-guardian-modules/tasks.md +++ b/speckit/features/251-guardian-modules/tasks.md @@ -129,9 +129,9 @@ - [X] T031 [US4] Circuit breaker per instance in a new `crates/server/src/modules/breaker.rs` (consecutive-failure threshold, open, half-open probe), consulted in `crates/server/src/modules/pipeline.rs`; an open circuit applies `on_error` without calling the module - [X] T032 [US4] Periodic health probe (`Describe`) per instance on each replica in `crates/server/src/modules/breaker.rs`, closing the circuit on success and detecting protocol or hook changes; wire its task in `crates/server/src/builder/mod.rs` with shutdown - [X] T033 [US4] Request size cap `GUARDIAN_MODULE_REQUEST_MAX_BYTES` (default 2 MiB) in `crates/server/src/modules/request.rs`: an oversized request is a module failure without the call -- [ ] T034 [US4] Module metrics in a new `crates/server/src/modules/metrics.rs` with names in `crates/server/src/metrics/names.rs`: `guardian_module_evaluate_duration_seconds{module, outcome}` (`allow`, `deny`, `error`, `skipped`), `guardian_module_fail_open_total{module}`, availability, circuit state, disabled state, configuration drift, catalog fingerprint, orphaned and over-budget assignment counts -- [ ] T035 [US4] Catalog fingerprint in `GET /dashboard/info` (`crates/server/src/services/dashboard_info.rs`) and the `circuit` field in `GET /dashboard/modules` (`crates/server/src/modules/admin.rs`); regenerate `docs/openapi*.json` with `cargo run --features evm --bin gen-openapi -- docs` -- [ ] T036 [US4] Document the budget, size cap and breaker variables in `docs/CONFIGURATION.md` ("Runtime: policy modules") and the metrics in `docs/guides/observability/` +- [X] T034 [US4] Module metrics in a new `crates/server/src/modules/metrics.rs` with names in `crates/server/src/metrics/names.rs`: `guardian_module_evaluate_duration_seconds{module, outcome}` (`allow`, `deny`, `error`, `skipped`), `guardian_module_fail_open_total{module}`, availability, circuit state, disabled state, configuration drift, catalog fingerprint, orphaned and over-budget assignment counts +- [X] T035 [US4] Catalog fingerprint in `GET /dashboard/info` (`crates/server/src/services/dashboard_info.rs`) and the `circuit` field in `GET /dashboard/modules` (`crates/server/src/modules/admin.rs`); regenerate `docs/openapi*.json` with `cargo run --features evm --bin gen-openapi -- docs` +- [ ] T036 [US4] Document the budget, size cap and breaker variables in `docs/CONFIGURATION.md` ("Runtime: policy modules") and the metrics in `docs/guides/observability/`; add the `guardian_module_*` metrics to the CloudWatch export allowlist in `infra/observability.tf` and the Grafana dashboard in `docs/guides/observability/grafana/dashboards/guardian.json`, which re-list the metric inventory **Checkpoint**: US4 acceptance scenarios 1 to 7 pass and SC-007 holds. From 771f8f1418b249c80203d3e59d7a7e1d34d07770 Mon Sep 17 00:00:00 2001 From: Zeljko Date: Mon, 9 Nov 2026 10:34:01 +0100 Subject: [PATCH 021/105] docs(modules): budget, size cap, breaker and probe settings and the module metrics (#251) docs/CONFIGURATION.md documents GUARDIAN_MODULE_EVALUATION_BUDGET_MS, GUARDIAN_MODULE_REQUEST_MAX_BYTES, GUARDIAN_MODULE_BREAKER_FAILURES and GUARDIAN_MODULE_PROBE_INTERVAL_MS, with the rule that client request timeouts must exceed the budget; spec/api.md lists the guardian_module_* metrics. Exporting them through CloudWatch and Grafana is task T063. --- docs/CONFIGURATION.md | 4 ++++ spec/api.md | 9 +++++++++ speckit/features/251-guardian-modules/tasks.md | 3 ++- 3 files changed, 15 insertions(+), 1 deletion(-) diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md index 6295e3a6..0ef4da05 100644 --- a/docs/CONFIGURATION.md +++ b/docs/CONFIGURATION.md @@ -384,6 +384,10 @@ modules guide](./guides/policy-modules/README.md). | `GUARDIAN_MODULES_CONFIG` | _unset_ (no modules) | Path of the module catalog (TOML). Read once at startup; it declares every instance and seeds its global params on first start, after which params are managed through the [operator API](./DASHBOARD.md#policy-modules). A relative path resolves against the working directory; relative `auth.token_file` and `tls.*_file` paths in the catalog resolve against the catalog's directory. An enabled instance that fails its startup checks stops startup. In the prod stage remote instances must use TLS (`grpc://`) and set `auth`. | | `GUARDIAN_MODULE_CHECK_RATE_PER_MIN` | `30` | Dry-run proposal checks (`POST /delta/proposal/check`) one signer may make for one account per minute; excess returns `rate_limit_exceeded`. Per replica. A value that is not a positive integer refuses startup. | | `GUARDIAN_MODULES_STATE` | `/modules` | Filesystem builds only: directory of the module state file (`module_state.json`). Postgres builds keep module state in the database. | +| `GUARDIAN_MODULE_EVALUATION_BUDGET_MS` | `1000` | Time spent in module calls for one hook invocation (request assembly is not charged). Each call gets the smaller of its `timeout_ms` and what is left; once spent, later modules count as timed out and their `on_error` applies. In the prod stage startup refuses a catalog whose `all` instances, enabled or not, exceed it at any hook, and a budget not below the execution reservation lease; account assignments and layers that could exceed it are refused at write time. Client and SDK request timeouts must exceed it, or a slow approval arrives after the client retried. | +| `GUARDIAN_MODULE_REQUEST_MAX_BYTES` | `2097152` (2 MiB) | Largest encoded request sent to a module. A larger one is a module failure and is not sent; its `on_error` applies. | +| `GUARDIAN_MODULE_BREAKER_FAILURES` | `5` | Consecutive failures (timeouts, transport errors, malformed decisions) that open an instance's circuit breaker on a replica. While open the module is not called and its `on_error` applies at once. A deny is an answer and resets the count. | +| `GUARDIAN_MODULE_PROBE_INTERVAL_MS` | `5000` | Interval of the `Describe` health probe of every enabled instance. A successful probe moves an open breaker to half-open, where the next call decides; the result is `guardian_module_up`. | ## Runtime — EVM (feature-gated) diff --git a/spec/api.md b/spec/api.md index 6ad3558a..7222600f 100644 --- a/spec/api.md +++ b/spec/api.md @@ -938,6 +938,15 @@ behavior. | `guardian_block_watch_walk_requests_total` | counter | `reason` (`cursor_init`/`cursor_jump`/`genesis_changed`/`genesis_unknown`/`node_behind_too_long`/`cursor_ahead_of_tip`/`observations_lost`/`undecodable_updates`/`skipped_malformed_block`/`skipped_unavailable_block`/`observation_dropped`) | | `guardian_block_watch_transport` | gauge | `transport` (`stream`/`poll`; 1 for the active one) | | `guardian_block_watch_block_processing_seconds` | histogram | — | +| `guardian_module_evaluate_duration_seconds` | histogram | `module` (catalog instance id), `outcome` (`allow`/`deny`/`error`/`skipped`) | +| `guardian_module_fail_open_total` | counter | `module` | +| `guardian_module_up` | gauge | `module` (1 when the last health probe succeeded) | +| `guardian_module_circuit_open` | gauge | `module` (1 while the replica's breaker is open) | +| `guardian_module_enabled` | gauge | `module` | +| `guardian_module_config_drift` | gauge | `module` (1 when the catalog's `enabled` or params differ from the stored values) | +| `guardian_module_catalog_info` | gauge | `catalog_hash` (constant 1) | +| `guardian_module_over_budget_accounts` | gauge | none | +| `guardian_module_orphaned_assignments` | gauge | none | | `guardian_canonicalization_candidates_total` | counter | `outcome` (`canonicalized`/`retried`/`discarded`/`grace_deferred`/`divergence_deferred`/`diverged`/`orphaned`/`abandoned`/`stale_base`/`retained`/`reconciled`/`reconcile_deferred`/`reconcile_expired`) | | `guardian_canonicalization_retries_total` | counter | — | | `guardian_canonicalization_commitment_mismatches_total` | counter | — | diff --git a/speckit/features/251-guardian-modules/tasks.md b/speckit/features/251-guardian-modules/tasks.md index 9cdc4885..b8fa39df 100644 --- a/speckit/features/251-guardian-modules/tasks.md +++ b/speckit/features/251-guardian-modules/tasks.md @@ -131,7 +131,7 @@ - [X] T033 [US4] Request size cap `GUARDIAN_MODULE_REQUEST_MAX_BYTES` (default 2 MiB) in `crates/server/src/modules/request.rs`: an oversized request is a module failure without the call - [X] T034 [US4] Module metrics in a new `crates/server/src/modules/metrics.rs` with names in `crates/server/src/metrics/names.rs`: `guardian_module_evaluate_duration_seconds{module, outcome}` (`allow`, `deny`, `error`, `skipped`), `guardian_module_fail_open_total{module}`, availability, circuit state, disabled state, configuration drift, catalog fingerprint, orphaned and over-budget assignment counts - [X] T035 [US4] Catalog fingerprint in `GET /dashboard/info` (`crates/server/src/services/dashboard_info.rs`) and the `circuit` field in `GET /dashboard/modules` (`crates/server/src/modules/admin.rs`); regenerate `docs/openapi*.json` with `cargo run --features evm --bin gen-openapi -- docs` -- [ ] T036 [US4] Document the budget, size cap and breaker variables in `docs/CONFIGURATION.md` ("Runtime: policy modules") and the metrics in `docs/guides/observability/`; add the `guardian_module_*` metrics to the CloudWatch export allowlist in `infra/observability.tf` and the Grafana dashboard in `docs/guides/observability/grafana/dashboards/guardian.json`, which re-list the metric inventory +- [X] T036 [US4] Document the budget, size cap and breaker variables in `docs/CONFIGURATION.md` ("Runtime: policy modules") and the metrics in `docs/guides/observability/`; the metric rows in the taxonomy of `spec/api.md` ("Metrics Endpoint") **Checkpoint**: US4 acceptance scenarios 1 to 7 pass and SC-007 holds. @@ -199,6 +199,7 @@ - [ ] T060 SC-004 run: enable `basic-policy` on all accounts with the official image and the guides only, timed, gaps fixed in `docs/guides/policy-modules/` - [ ] T061 Re-check the TLA+ models whose fingerprints the modules work moved (`verify-auth-replay`, `verify-candidate-queue`, `verify-client-sync`, `verify-guardian-switch`, `verify-module-counting`, `verify-multisig-push-gate`, `verify-proposal-lifecycle` under `.agents/skills/`) with each `check.sh`, then `--accept-drift` once the model still mirrors the code - [ ] T062 Validation matrix of `speckit/features/251-guardian-modules/quickstart.md` section 5 (M2a rows) run end to end, including `cargo test -p guardian-server --features postgres` for module stores and proposal storage, and `gen-openapi --check` +- [ ] T063 Export the `guardian_module_*` metrics: add them to the CloudWatch export allowlist in `infra/observability.tf` (selector groups by label dimensions) and a "Policy modules" section of panels in `docs/guides/observability/grafana/dashboards/guardian.json`, listed in `docs/guides/observability/README.md`; validate with `terraform validate` and the local Prometheus and Grafana stack --- From f72544bac73db0f41710be8cad568e7fa7605f5f Mon Sep 17 00:00:00 2001 From: Zeljko Date: Mon, 9 Nov 2026 10:34:15 +0100 Subject: [PATCH 022/105] docs(speckit): T039 adds the default scope the prototype never built (#251) --- speckit/features/251-guardian-modules/tasks.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/speckit/features/251-guardian-modules/tasks.md b/speckit/features/251-guardian-modules/tasks.md index b8fa39df..ca2f8c83 100644 --- a/speckit/features/251-guardian-modules/tasks.md +++ b/speckit/features/251-guardian-modules/tasks.md @@ -150,7 +150,7 @@ ### Implementation for User Story 5 -- [ ] T039 [US5] Write `default` instances into the assignment together with the claim in `crates/server/src/services/configure_account.rs` and `crates/server/src/modules/postgres_store.rs` (same transaction as `metadata.create`), with the evaluated params from the same snapshot (P0 T085) +- [ ] T039 [US5] Add the `default` scope, which the prototype never built (`Scope` in `crates/server/src/modules/catalog.rs` has only `all` and `assigned`): parse `scope = "default"`, plan it as an account-owned assignment like `assigned`, count it in `ModulePipeline::worst_case` and the startup budget check, and allow removing it per account; then write `default` instances into the assignment together with the claim in `crates/server/src/services/configure_account.rs` and `crates/server/src/modules/postgres_store.rs` (same transaction as `metadata.create`), with the evaluated params from the same snapshot (P0 T085) - [ ] T040 [US5] Filesystem registration copy in `crates/server/src/modules/store.rs`: written before the claim as one atomic replace, replacing a copy an earlier unclaimed attempt left; an unfinished claim with no assignment history repeats it (P0 T094) - [ ] T041 [US5] `params_drift` against `seeded_params`, `GUARDIAN_MODULE_PARAMS_MAX_BYTES` on every params write, and paginated history (`?before=&limit=`) in `crates/server/src/modules/admin.rs`, `store.rs` and `postgres_store.rs` (P0 T090) - [ ] T042 [US5] `declared` (stored flag the catalog no longer declares) and `orphaned` (assignment naming a removed instance) in the views of `crates/server/src/modules/admin.rs`; orphaned entries are skipped at evaluation and reported, active again when the instance returns From db3908c73ddf07c3ffd0bdb8017503b8660f6faa Mon Sep 17 00:00:00 2001 From: Zeljko Date: Mon, 9 Nov 2026 10:49:36 +0100 Subject: [PATCH 023/105] feat(modules): lost-claim registration and the basic-policy code allowlist (#251) A first configuration that loses its claim to a concurrent one is judged again by before_account_registered against the account it lost to, with that account's stored state as before, and only then consumes its replay timestamp; a denial there stores and consumes nothing. basic-policy gains allowed_code_commitments with code_check: under changed (the default) the code an account registers with and code a transaction replaces it with must be listed, so accounts already on other code keep working until they change it; under all, the code an account runs is checked at every gate hook. It refuses with code_not_allowed. --- .../guardian-module-sdk/src/basic_policy.rs | 142 +++++++++ .../server/src/services/configure_account.rs | 295 ++++++++++++++---- docs/guides/policy-modules/built-in.md | 6 +- docs/guides/policy-modules/built-in.toml | 13 + .../features/251-guardian-modules/tasks.md | 8 +- 5 files changed, 392 insertions(+), 72 deletions(-) diff --git a/crates/guardian-module-sdk/src/basic_policy.rs b/crates/guardian-module-sdk/src/basic_policy.rs index 278416b7..a75dd80d 100644 --- a/crates/guardian-module-sdk/src/basic_policy.rs +++ b/crates/guardian-module-sdk/src/basic_policy.rs @@ -21,6 +21,16 @@ pub enum SignerCheck { All, } +/// Which code `allowed_code_commitments` checks: only code an account registers with or changes +/// to (`changed`), or the code it runs at every gate hook (`all`). +#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum CodeCheck { + #[default] + Changed, + All, +} + #[derive(Debug, Clone, Default, Deserialize)] #[serde(deny_unknown_fields)] pub struct Params { @@ -40,6 +50,10 @@ pub struct Params { pub signer_denylist: Option>, #[serde(default)] pub signer_check: SignerCheck, + #[serde(default)] + pub allowed_code_commitments: Option>, + #[serde(default)] + pub code_check: CodeCheck, } struct Policy { @@ -50,6 +64,8 @@ struct Policy { deny_unknown_recipients: bool, signers: Option, signer_check: SignerCheck, + code: Option>, + code_check: CodeCheck, } enum SignerList { @@ -100,6 +116,8 @@ impl TryFrom for Policy { deny_unknown_recipients: params.deny_unknown_recipients, signers, signer_check: params.signer_check, + code: params.allowed_code_commitments.as_deref().map(normalized), + code_check: params.code_check, }) } } @@ -123,6 +141,7 @@ enum Rule { AssetAllowlist, AmountCap, Signers, + Code, } impl Rule { @@ -148,6 +167,10 @@ impl Rule { "signer_not_allowed", "The account would have a signer this Guardian does not accept.", ), + Rule::Code => ( + "code_not_allowed", + "The account would run code this Guardian does not accept.", + ), }; Decision::deny(reason_code, logged).with_client_message(client_message) } @@ -168,6 +191,12 @@ impl Policy { return Ok(Rule::Signers.deny(format!("signer {signer} is not permitted"))); } } + if let Some(allowed) = &self.code + && let Some(code) = self.checked_code(request)? + && !allowed.contains(&code.to_ascii_lowercase()) + { + return Ok(Rule::Code.deny(format!("code {code} is not allowed"))); + } match &request.subject { Some(hook_request::Subject::Transaction(tx)) => self.evaluate_transaction(tx), Some(hook_request::Subject::Registration(_)) => Ok(Decision::allow()), @@ -175,6 +204,29 @@ impl Policy { } } + /// The code commitment `allowed_code_commitments` must list for this request, if any: under + /// `changed` the code an account registers with or a transaction replaces its code with, + /// under `all` the code the account runs after the request, at every hook. + fn checked_code(&self, request: &HookRequest) -> Result, ModuleError> { + let after_code = || { + request + .after + .as_ref() + .map(|after| after.code_commitment.clone()) + .ok_or_else(|| ModuleError::InvalidRequest("request has no account view".into())) + }; + match (self.code_check, &request.subject) { + (CodeCheck::All, _) + | (CodeCheck::Changed, Some(hook_request::Subject::Registration(_))) => { + after_code().map(Some) + } + (CodeCheck::Changed, Some(hook_request::Subject::Transaction(tx))) => Ok(tx + .miden() + .and_then(|projection| projection.new_code_commitment.clone())), + (CodeCheck::Changed, None) => Ok(None), + } + } + fn checked_signers(&self, before: Option<&AccountView>, after: &AccountView) -> Vec { let existing: BTreeSet = match (self.signer_check, before) { (SignerCheck::Added, Some(before)) => normalized(&before.signer_commitments), @@ -535,6 +587,96 @@ mod tests { ); } + const REVIEWED: &str = "0xc0de"; + const UNREVIEWED: &str = "0xbad"; + + fn code_rule(code_check: &str) -> serde_json::Value { + json!({ "allowed_code_commitments": [REVIEWED], "code_check": code_check }) + } + + fn running(mut request: HookRequest, code: &str) -> HookRequest { + if let Some(after) = request.after.as_mut() { + after.code_commitment = code.into(); + } + request + } + + fn registration(params: serde_json::Value, code: &str) -> HookRequest { + running( + HookRequest { + params: serde_json::to_vec(¶ms).unwrap(), + after: Some(view(&["0xs1"])), + subject: Some(hook_request::Subject::Registration( + RegistrationSubject::default(), + )), + ..Default::default() + }, + code, + ) + } + + fn replacing_code_with(code: Option<&str>) -> MidenTransaction { + MidenTransaction { + new_code_commitment: code.map(str::to_string), + ..Default::default() + } + } + + #[tokio::test] + async fn changed_code_check_judges_registration_and_code_replacement_only() { + let rule = code_rule("changed"); + assert!(decide(®istration(rule.clone(), REVIEWED)).await.allow); + let refused = decide(®istration(rule.clone(), UNREVIEWED)).await; + assert_eq!(refused.reason_code, "code_not_allowed"); + assert!(!refused.client_message.contains(UNREVIEWED)); + + let unchanged = running( + tx_request(rule.clone(), replacing_code_with(None)), + UNREVIEWED, + ); + assert!( + decide(&unchanged).await.allow, + "code an account already runs is kept until it changes" + ); + let upgrade = tx_request(rule.clone(), replacing_code_with(Some(UNREVIEWED))); + assert_eq!(decide(&upgrade).await.reason_code, "code_not_allowed"); + let reviewed = tx_request(rule, replacing_code_with(Some(REVIEWED))); + assert!(decide(&reviewed).await.allow); + } + + #[tokio::test] + async fn all_code_check_judges_the_code_an_account_runs_at_every_hook() { + let rule = code_rule("all"); + let unchanged = running( + tx_request(rule.clone(), replacing_code_with(None)), + UNREVIEWED, + ); + assert_eq!(decide(&unchanged).await.reason_code, "code_not_allowed"); + let upgraded = running( + tx_request(rule, replacing_code_with(Some(REVIEWED))), + REVIEWED, + ); + assert!( + decide(&upgraded).await.allow, + "an account on unlisted code can still upgrade to listed code" + ); + } + + #[tokio::test] + async fn an_unknown_code_check_is_refused_when_the_params_are_written() { + let verdict = BasicPolicy + .validate_params( + &serde_json::to_vec(&json!({ + "allowed_code_commitments": [REVIEWED], + "code_check": "sometimes" + })) + .unwrap(), + ) + .await + .unwrap(); + assert!(!verdict.ok); + } + #[tokio::test] async fn a_transaction_without_a_miden_projection_is_not_judged() { let mut request = tx_request(cap(), MidenTransaction::default()); diff --git a/crates/server/src/services/configure_account.rs b/crates/server/src/services/configure_account.rs index 2a36df29..cd0a5cc6 100644 --- a/crates/server/src/services/configure_account.rs +++ b/crates/server/src/services/configure_account.rs @@ -79,25 +79,7 @@ pub async fn configure_account( // it is held to the scheme policy for new accounts and counted as a // creation. A failed state read keeps the reconfiguration treatment, so // it can never block an account that does have state. - let unfinished_claim = match &existing { - Some(_) => match state - .storage - .pull_state_commitment(¶ms.account_id) - .await - { - Ok(_) => false, - Err(e) if crate::storage::is_storage_not_found(&e) => true, - Err(e) => { - tracing::warn!( - account_id = %params.account_id, - error = %e, - "Could not check for a stored state; treating the account as configured" - ); - false - } - }, - None => false, - }; + let unfinished_claim = existing.is_some() && !has_stored_state(state, ¶ms.account_id).await; // The GUARDIAN's scheme selects this server's ACK identity for the // account; every scheme the account uses, its cosigners' included, is // held to the policy for new accounts. A reconfiguration is held to it @@ -236,51 +218,14 @@ pub async fn configure_account( (head, signer_commitment) }; - let plan = match state.modules.as_deref() { - Some(modules) => { - modules - .plan(HookName::BeforeAccountRegistered, ¶ms.account_id) - .await? - } - None => None, - }; - if let Some(plan) = plan { - let stored_state = match &existing { - Some(_) if !unfinished_claim => Some( - state - .storage - .pull_state(¶ms.account_id) - .await - .map_err(|e| format!("stored state unavailable: {e}")), - ), - _ => None, - }; - let views = plan.views(); - plan.run(|| { - let stored_state = stored_state.as_ref().map(|r| r.as_ref()).transpose()?; - request::registration_request( - state.network_client.as_ref(), - &views, - RegistrationInput { - account_id: ¶ms.account_id, - submitter: &signer_commitment, - submitter_session: false, - auth: ¶ms.auth, - network_config: ¶ms.network_config, - stored_state: stored_state.map(|stored| StateRef { - commitment: &stored.commitment, - json: &stored.state_json, - }), - initial_state: StateRef { - commitment: &head.commitment, - json: ¶ms.initial_state, - }, - accounting_time: state.clock.now(), - }, - ) - }) - .await?; - } + approve_registration( + state, + ¶ms, + &signer_commitment, + &head, + existing.is_some() && !unfinished_claim, + ) + .await?; let now = state.clock.now_rfc3339(); @@ -318,11 +263,23 @@ pub async fn configure_account( let claimed = state.metadata.get(¶ms.account_id).await.map_err(|e| { GuardianError::StorageError(format!("Failed to re-read account metadata: {e}")) })?; - Some(claimed.ok_or_else(|| { + let claimed = claimed.ok_or_else(|| { GuardianError::StorageError( "Account metadata vanished after a concurrent first configuration".to_string(), ) - })?) + })?; + // The modules judged this request as a new account; it is now a reconfiguration of the + // account it lost to, whose modules and stored state differ, so they judge it again + // before it consumes anything. + approve_registration( + state, + ¶ms, + &signer_commitment, + &head, + has_stored_state(state, ¶ms.account_id).await, + ) + .await?; + Some(claimed) } else { existing }; @@ -610,6 +567,81 @@ fn reject_disallowed_scheme(state: &AppState, scheme: SignatureScheme) -> Result }) } +/// Runs `before_account_registered` for this request: with the stored state as `before` when +/// `stored`, without one for a first configuration or a claim whose state was never stored. +async fn approve_registration( + state: &AppState, + params: &ConfigureAccountParams, + signer_commitment: &str, + head: &StateHead, + stored: bool, +) -> Result<()> { + let plan = match state.modules.as_deref() { + Some(modules) => { + modules + .plan(HookName::BeforeAccountRegistered, ¶ms.account_id) + .await? + } + None => None, + }; + if let Some(plan) = plan { + let stored_state = if stored { + Some( + state + .storage + .pull_state(¶ms.account_id) + .await + .map_err(|e| format!("stored state unavailable: {e}")), + ) + } else { + None + }; + let views = plan.views(); + plan.run(|| { + let stored_state = stored_state.as_ref().map(|r| r.as_ref()).transpose()?; + request::registration_request( + state.network_client.as_ref(), + &views, + RegistrationInput { + account_id: ¶ms.account_id, + submitter: signer_commitment, + submitter_session: false, + auth: ¶ms.auth, + network_config: ¶ms.network_config, + stored_state: stored_state.map(|stored| StateRef { + commitment: &stored.commitment, + json: &stored.state_json, + }), + initial_state: StateRef { + commitment: &head.commitment, + json: ¶ms.initial_state, + }, + accounting_time: state.clock.now(), + }, + ) + }) + .await?; + } + Ok(()) +} + +/// Whether the account has a stored state. A failed read counts as stored, so it can never make +/// an account with state look unconfigured. +async fn has_stored_state(state: &AppState, account_id: &str) -> bool { + match state.storage.pull_state_commitment(account_id).await { + Ok(_) => true, + Err(e) if crate::storage::is_storage_not_found(&e) => false, + Err(e) => { + tracing::warn!( + account_id = %account_id, + error = %e, + "Could not check for a stored state; treating the account as configured" + ); + true + } + } +} + /// The stored state's commitment and nonce, or `None` when the account has /// no stored state. A row written before the server stored nonces carries /// none: it is decoded from the stored state, and the commitment is taken @@ -3586,4 +3618,135 @@ mod tests { configure_with_module(existing_account(false, true), StubModule::denying("no")).await; assert_nothing_written(&run); } + + /// Allows the first evaluation and denies every later one. + #[derive(Default)] + struct AllowsOnce { + calls: std::sync::atomic::AtomicUsize, + } + + #[async_trait::async_trait] + impl guardian_module_sdk::Module for AllowsOnce { + async fn describe( + &self, + _guardian: &guardian_module_sdk::DescribeRequest, + ) -> std::result::Result + { + Ok(Default::default()) + } + + async fn validate_params( + &self, + _params: &[u8], + ) -> std::result::Result + { + Ok(guardian_module_sdk::ParamsVerdict::ok()) + } + + async fn evaluate( + &self, + _request: &guardian_module_sdk::HookRequest, + ) -> std::result::Result + { + Ok( + match self.calls.fetch_add(1, std::sync::atomic::Ordering::SeqCst) { + 0 => guardian_module_sdk::Decision::allow(), + _ => guardian_module_sdk::Decision::deny("signer_not_allowed", "re-run"), + }, + ) + } + } + + /// A first configuration that loses its claim to an account another request created + /// meanwhile, judged by `module` at `before_account_registered`. + async fn lose_the_claim_under( + module: Arc, + ) -> ( + Result, + MockMetadataStore, + MockStorageBackend, + ) { + use crate::modules::catalog::OnError; + use crate::modules::testing::{instance, pipeline}; + use crate::testing::helpers::generate_falcon_signature; + + let account_id = "0x1d1d1d1c1d1d1d011d1d1d1d1d1d1d"; + let (pubkey, commitment, signature, timestamp) = generate_falcon_signature(account_id); + let winner = AccountMetadata { + created_at: "2023-06-01T00:00:00Z".into(), + ..claimed_metadata(account_id, &commitment) + }; + let metadata = MockMetadataStore::new() + .with_get(Ok(Some(winner))) + .with_get(Ok(None)) + .with_create(Ok(false)) + .with_update_timestamp_cas(Ok(true)); + let storage = MockStorageBackend::new(); + let mut state = create_test_app_state( + MockNetworkClient::new() + .with_validate_credential(Ok(())) + .with_get_state_head(Ok(head("0x1234", 3))) + .with_module_views( + guardian_module_sdk::AccountView { + signer_commitments: vec![commitment.clone()], + ..Default::default() + }, + guardian_module_sdk::MidenTransaction::default(), + ), + storage.clone(), + metadata.clone(), + ) + .await; + state.modules = Some(pipeline(vec![instance( + "signers", + &[HookName::BeforeAccountRegistered], + OnError::Deny, + module, + )])); + let initial_state = + serde_json::from_str(include_str!("../testing/fixtures/account.json")).unwrap(); + let result = configure_account( + &state, + ConfigureAccountParams { + account_id: account_id.to_string(), + auth: Auth::MidenFalconRpo { + cosigner_commitments: vec![commitment], + }, + network_config: crate::metadata::NetworkConfig::miden_default(), + initial_state, + credential: Credentials::signature(pubkey, signature, timestamp), + }, + ) + .await; + (result, metadata, storage) + } + + #[tokio::test] + async fn a_lost_claim_is_judged_again_against_the_winners_account() { + let module = crate::modules::testing::StubModule::allowing(); + let (result, _, storage) = lose_the_claim_under(module.clone()).await; + assert!(result.is_ok(), "{result:?}"); + assert_eq!( + module.calls(), + 2, + "once as a new account, once as a reconfiguration of the winner's" + ); + assert_eq!(storage.get_submit_state_calls().len(), 1); + } + + #[tokio::test] + async fn a_lost_claim_refused_on_the_second_judgement_consumes_and_stores_nothing() { + let (result, metadata, storage) = + lose_the_claim_under(Arc::new(AllowsOnce::default())).await; + assert!( + matches!(&result, Err(GuardianError::ModuleDenied { reason_code, .. }) if reason_code == "signer_not_allowed"), + "{result:?}" + ); + assert!( + metadata.get_update_timestamp_cas_calls().is_empty(), + "the replay timestamp is not consumed, so the request can be sent again" + ); + assert!(storage.get_submit_state_calls().is_empty()); + assert!(metadata.get_set_calls().is_empty()); + } } diff --git a/docs/guides/policy-modules/built-in.md b/docs/guides/policy-modules/built-in.md index 0cc8f8eb..37599c66 100644 --- a/docs/guides/policy-modules/built-in.md +++ b/docs/guides/policy-modules/built-in.md @@ -18,9 +18,11 @@ All params are optional; an instance with none allows everything. | `deny_unknown_recipients` | `true` / `false` | `recipient_blocked` | With `recipient_denylist`: also refuses payment notes whose recipient the Guardian cannot identify (not P2ID or P2IDE). | | `signer_allowlist` or `signer_denylist` | `["", ...]` | `signer_not_allowed` | Mutually exclusive. | | `signer_check` | `"added"` (default) or `"all"` | | `added` checks only signers a transaction adds; `all` checks every signer after it. | +| `allowed_code_commitments` | `["", ...]` | `code_not_allowed` | Pins accounts to account code you reviewed. The Guardian does not check an account's code itself, so a module verdict is only as good as the code that requires the Guardian's signature. | +| `code_check` | `"changed"` (default) or `"all"` | | `changed` checks the code an account registers with and code a transaction replaces it with, so accounts already on other code keep working until they change it; `all` checks the code the account runs at every hook, so an account on unlisted code can only upgrade to listed code. | -Signer rules apply at all three hooks, including registration. Transaction -rules (caps, assets, recipients) apply to proposals and approvals. +Signer and code rules apply at all three hooks, including registration. +Transaction rules (caps, assets, recipients) apply to proposals and approvals. Each refusal carries a fixed `client_message` naming the rule (for example "The transaction sends more than this Guardian allows per transaction."), diff --git a/docs/guides/policy-modules/built-in.toml b/docs/guides/policy-modules/built-in.toml index 4e97af45..0e5de1cc 100644 --- a/docs/guides/policy-modules/built-in.toml +++ b/docs/guides/policy-modules/built-in.toml @@ -38,6 +38,19 @@ timeout_ms = 50 on_error = "deny" params = { signer_check = "added", signer_denylist = ["0xdededededededededededededededededededededededededededededededede"] } +# Code pinning (uncomment after reviewing the account code you accept): an account must +# register with a listed code commitment, and a transaction that replaces its code must +# replace it with listed code. With code_check = "all", every gate hook checks the code the +# account runs, so an account on unlisted code can only upgrade. +# [[module]] +# id = "reviewed-code" +# kind = "basic-policy" +# scope = "all" +# hooks = ["before_account_registered", "before_proposal_created", "before_transaction_approved"] +# timeout_ms = 50 +# on_error = "deny" +# params = { code_check = "changed", allowed_code_commitments = ["0xREPLACE_WITH_REVIEWED_CODE_COMMITMENT"] } + # Opt-in module: applies only to accounts an operator assigns it to, with their own params. [[module]] id = "treasury-allowlist" diff --git a/speckit/features/251-guardian-modules/tasks.md b/speckit/features/251-guardian-modules/tasks.md index ca2f8c83..6c28f5a1 100644 --- a/speckit/features/251-guardian-modules/tasks.md +++ b/speckit/features/251-guardian-modules/tasks.md @@ -99,13 +99,13 @@ ### Tests for User Story 3 -- [ ] T023 [P] [US3] Registration races in `crates/server/src/services/configure_account.rs` tests: a losing first configuration is evaluated again against the winner's assignment before it consumes anything; a denied first configuration claims nothing; a denied re-onboarding leaves released state, metadata and assignment unchanged; a mixed-scheme account's registration request carries `signer_schemes` for every signer +- [X] T023 [P] [US3] Registration races in `crates/server/src/services/configure_account.rs` tests: a losing first configuration is evaluated again against the winner's assignment before it consumes anything; a denied first configuration claims nothing; a denied re-onboarding leaves released state, metadata and assignment unchanged; a mixed-scheme account's registration request carries `signer_schemes` for every signer ### Implementation for User Story 3 -- [ ] T024 [US3] Registration per RFC section 2.3 "Registration" in `crates/server/src/services/configure_account.rs`: for a lost claim, re-plan and re-run the pipeline against the winning account (unfinished claim or existing account) before `consume_auth_timestamp`; keep the hook before the claim (P0 T085) -- [ ] T025 [US3] `basic-policy` `allowed_code_commitments` with `code_check` (`changed` or `current`, reason code `code_not_allowed`) in `crates/guardian-module-sdk/src/basic_policy.rs`, reading `AccountView.code_commitment` and `MidenTransaction.new_code_commitment`; params validation and tests at registration and at code replacement (P0 T093) -- [ ] T026 [US3] Document the code allowlist and signer modes in `docs/guides/policy-modules/built-in.md` and its `built-in.toml` +- [X] T024 [US3] Registration per RFC section 2.3 "Registration" in `crates/server/src/services/configure_account.rs`: for a lost claim, re-plan and re-run the pipeline against the winning account (unfinished claim or existing account) before `consume_auth_timestamp`; keep the hook before the claim (P0 T085) +- [X] T025 [US3] `basic-policy` `allowed_code_commitments` with `code_check` (`changed` or `current`, reason code `code_not_allowed`) in `crates/guardian-module-sdk/src/basic_policy.rs`, reading `AccountView.code_commitment` and `MidenTransaction.new_code_commitment`; params validation and tests at registration and at code replacement (P0 T093) +- [X] T026 [US3] Document the code allowlist and signer modes in `docs/guides/policy-modules/built-in.md` and its `built-in.toml` **Checkpoint**: US3 acceptance scenarios 1 to 5 pass, and the code allowlist is in `basic-policy`. From 02b6d762869e3a166c04921d2783b7355acbfc26 Mon Sep 17 00:00:00 2001 From: Zeljko Date: Mon, 9 Nov 2026 10:52:11 +0100 Subject: [PATCH 024/105] feat(modules): the proposal check runs approval rules too, marked as a check (#251) POST /delta/proposal/check now runs the before_proposal_created instances and then those subscribed only to before_transaction_approved, so rules that must hold at approval answer the check as well; an instance on both hooks runs once. Every request in a check carries HookRequest.dry_run = true; real proposal creation does not. complete is false whenever the catalog has an enabled transaction gate instance that opts out of checks, whether or not it applies to the account, so the answer reveals nothing about one account's instances. --- crates/server/src/modules/pipeline.rs | 59 ++++++-- .../src/services/push_delta_proposal.rs | 140 +++++++++++++----- .../features/251-guardian-modules/tasks.md | 4 +- 3 files changed, 154 insertions(+), 49 deletions(-) diff --git a/crates/server/src/modules/pipeline.rs b/crates/server/src/modules/pipeline.rs index 3911f8f8..ff9eea40 100644 --- a/crates/server/src/modules/pipeline.rs +++ b/crates/server/src/modules/pipeline.rs @@ -69,6 +69,8 @@ pub struct Plan<'a> { views: Arc, limits: Limits, breakers: Arc, + /// A policy check: every request says so, and nothing is stored whatever the decision. + dry_run: bool, } enum Failure { @@ -529,24 +531,55 @@ impl ModulePipeline { views: self.views.clone(), limits: self.limits, breakers: self.breakers.clone(), + dry_run: false, })) } - /// The plan for a dry-run check: instances with `dry_run = false` are skipped, and - /// `complete` is false when any was. + /// The plans for a dry-run check of a proposal: the `before_proposal_created` instances, + /// then those subscribed only to `before_transaction_approved`, so an instance on both runs + /// once and rules that must hold at approval are checked too. Instances with + /// `dry_run = false` are skipped. `complete` is false whenever the catalog has an enabled + /// transaction gate instance that opts out, whether or not it applies to this account, so + /// the answer reveals nothing about one account's instances. pub async fn plan_dry_run( &self, - hook: HookName, account_id: &str, - ) -> Result<(Option>, bool), GuardianError> { - let Some(mut plan) = self.plan(hook, account_id).await? else { - return Ok((None, true)); - }; - let planned = plan.modules.len(); - plan.modules - .retain(|(instance, _, _)| instance.config.dry_run); - let complete = plan.modules.len() == planned; - Ok(((!plan.modules.is_empty()).then_some(plan), complete)) + ) -> Result<(Vec>, bool), GuardianError> { + let (_, rows) = self.versioned_rows().await?; + let complete = !self.instances.iter().any(|instance| { + Self::enabled_in(&rows, &instance) + && !instance.config.dry_run + && (instance + .config + .hooks + .contains(&HookName::BeforeProposalCreated) + || instance + .config + .hooks + .contains(&HookName::BeforeTransactionApproved)) + }); + let mut plans = Vec::new(); + for hook in [ + HookName::BeforeProposalCreated, + HookName::BeforeTransactionApproved, + ] { + let Some(mut plan) = self.plan(hook, account_id).await? else { + continue; + }; + plan.modules.retain(|(instance, _, _)| { + instance.config.dry_run + && (hook == HookName::BeforeProposalCreated + || !instance + .config + .hooks + .contains(&HookName::BeforeProposalCreated)) + }); + plan.dry_run = true; + if !plan.modules.is_empty() { + plans.push(plan); + } + } + Ok((plans, complete)) } pub async fn applies(&self, hook: HookName, account_id: &str) -> Result { @@ -588,6 +621,7 @@ impl Plan<'_> { views: _, limits, breakers, + dry_run, } = self; let account_id = account_id.as_str(); let mut approval = Evaluation { @@ -599,6 +633,7 @@ impl Plan<'_> { let base = match build() { Ok(base) => HookRequest { request_id: request_id.clone(), + dry_run, ..base }, Err(error) => { diff --git a/crates/server/src/services/push_delta_proposal.rs b/crates/server/src/services/push_delta_proposal.rs index 52c9c9cb..b47c2043 100644 --- a/crates/server/src/services/push_delta_proposal.rs +++ b/crates/server/src/services/push_delta_proposal.rs @@ -150,12 +150,8 @@ async fn propose(state: &AppState, params: PushDeltaProposalParams, mode: Mode) crate::modules::check_limit::admit(&account_id, &resolved.signer_commitment)?; } let dry_run = match (mode, state.modules.as_deref()) { - (Mode::DryRun, Some(modules)) => Some( - modules - .plan_dry_run(HookName::BeforeProposalCreated, &account_id) - .await?, - ), - (Mode::DryRun, None) => Some((None, true)), + (Mode::DryRun, Some(modules)) => Some(modules.plan_dry_run(&account_id).await?), + (Mode::DryRun, None) => Some((Vec::new(), true)), (Mode::Create, _) => None, }; if resolved.metadata.network_config.is_evm() { @@ -351,17 +347,19 @@ async fn propose(state: &AppState, params: PushDeltaProposalParams, mode: Mode) } tracing::Span::current().record("signer_count", cosigner_sigs.len()); - let (plan, complete) = match (dry_run, state.modules.as_deref()) { + let (plans, complete) = match (dry_run, state.modules.as_deref()) { (Some(planned), _) => planned, (None, Some(modules)) => ( modules .plan(HookName::BeforeProposalCreated, &account_id) - .await?, + .await? + .into_iter() + .collect(), true, ), - (None, None) => (None, true), + (None, None) => (Vec::new(), true), }; - if let Some(plan) = plan { + if !plans.is_empty() { let (after, module_views) = { let client = state.network_client.clone(); let tail_state_json = tail.state_json.clone(); @@ -379,34 +377,36 @@ async fn propose(state: &AppState, params: PushDeltaProposalParams, mode: Mode) .cloned() .unwrap_or(serde_json::Value::Null), }; - let views = plan.views(); + let views = plans[0].views(); views.seed(&tail.commitment, module_views.before); views.seed(&after.commitment, module_views.after); - plan.run(|| { - request::transaction_request( - state.network_client.as_ref(), - &views, - TransactionInput { - account_id: &account_id, - submitter: &proposer_id, - submitter_session: credentials_session, - auth: &resolved.metadata.auth, - network_config: &resolved.metadata.network_config, - before: StateRef { - commitment: &tail.commitment, - json: &tail.state_json, + for plan in plans { + plan.run(|| { + request::transaction_request( + state.network_client.as_ref(), + &views, + TransactionInput { + account_id: &account_id, + submitter: &proposer_id, + submitter_session: credentials_session, + auth: &resolved.metadata.auth, + network_config: &resolved.metadata.network_config, + before: StateRef { + commitment: &tail.commitment, + json: &tail.state_json, + }, + after: StateRef { + commitment: &after.commitment, + json: &after.state_json, + }, + tx_summary, + proposal: Some(proposal.clone()), + accounting_time: state.clock.now(), }, - after: StateRef { - commitment: &after.commitment, - json: &after.state_json, - }, - tx_summary, - proposal: Some(proposal), - accounting_time: state.clock.now(), - }, - ) - }) - .await?; + ) + }) + .await?; + } } if mode == Mode::DryRun { tracing::info!( @@ -2456,6 +2456,76 @@ mod tests { assert!(storage.get_submit_delta_proposal_calls().is_empty()); } + #[tokio::test] + async fn a_check_runs_approval_only_rules_too_and_marks_every_request_as_a_check() { + let module = crate::modules::testing::StubModule::denying("amount_cap_exceeded"); + let (state, storage, params, _) = + module_setup(module.clone(), HookName::BeforeTransactionApproved, |_| {}); + assert!(matches!( + check_proposal(&state, params).await, + Err(GuardianError::ModuleDenied { .. }) + )); + let request = module.last_request().expect("the approval rule ran"); + assert!(request.dry_run); + assert_eq!( + request.hook, + guardian_module_sdk::Hook::BeforeTransactionApproved as i32 + ); + assert!(storage.get_submit_delta_proposal_calls().is_empty()); + } + + #[tokio::test] + async fn an_instance_on_both_transaction_hooks_runs_once_in_a_check() { + let module = crate::modules::testing::StubModule::allowing(); + let (state, _, params, _) = module_setup( + module.clone(), + HookName::BeforeProposalCreated, + |instance| { + instance.config.hooks = vec![ + HookName::BeforeProposalCreated, + HookName::BeforeTransactionApproved, + ]; + }, + ); + check_proposal(&state, params).await.unwrap(); + assert_eq!(module.calls(), 1); + assert_eq!( + module.last_request().unwrap().hook, + guardian_module_sdk::Hook::BeforeProposalCreated as i32 + ); + } + + #[tokio::test] + async fn an_opted_out_instance_makes_every_check_incomplete_even_where_it_does_not_apply() { + let (state, _, params, _) = module_setup( + crate::modules::testing::StubModule::allowing(), + HookName::BeforeTransactionApproved, + |instance| { + instance.config.scope = crate::modules::catalog::Scope::Assigned; + instance.config.dry_run = false; + }, + ); + let result = check_proposal(&state, params).await.unwrap(); + assert!( + !result.complete, + "the answer must not reveal which accounts carry the hidden instance" + ); + } + + #[tokio::test] + async fn creating_a_proposal_is_not_marked_as_a_check() { + let module = crate::modules::testing::StubModule::allowing(); + let (state, _, params, _) = + module_setup(module.clone(), HookName::BeforeProposalCreated, |_| {}); + let _ = push_delta_proposal(&state, params).await; + assert!( + !module + .last_request() + .expect("the creation rule ran") + .dry_run + ); + } + #[tokio::test] async fn a_module_that_opts_out_is_skipped_and_the_check_is_incomplete() { let module = crate::modules::testing::StubModule::denying("would_deny"); diff --git a/speckit/features/251-guardian-modules/tasks.md b/speckit/features/251-guardian-modules/tasks.md index 6c28f5a1..35a8f4a8 100644 --- a/speckit/features/251-guardian-modules/tasks.md +++ b/speckit/features/251-guardian-modules/tasks.md @@ -82,8 +82,8 @@ ### Implementation for User Story 2 -- [ ] T019 [US2] Dry-run check runs `before_transaction_approved`-only instances after the creation instances, each instance once, every request with `HookRequest.dry_run = true`, in `crates/server/src/modules/pipeline.rs` (`plan_dry_run`) and `crates/server/src/services/push_delta_proposal.rs`; tests that an approval-only cap refuses the check (P0 T095) -- [ ] T020 [US2] `complete` derived from the catalog, not the account: `false` whenever any enabled gate instance has `dry_run = false`, in `crates/server/src/modules/pipeline.rs`; test that two accounts, one with the hidden instance assigned and one without, get the same `complete` (P0 T090, T095) +- [X] T019 [US2] Dry-run check runs `before_transaction_approved`-only instances after the creation instances, each instance once, every request with `HookRequest.dry_run = true`, in `crates/server/src/modules/pipeline.rs` (`plan_dry_run`) and `crates/server/src/services/push_delta_proposal.rs`; tests that an approval-only cap refuses the check (P0 T095) +- [X] T020 [US2] `complete` derived from the catalog, not the account: `false` whenever any enabled gate instance has `dry_run = false`, in `crates/server/src/modules/pipeline.rs`; test that two accounts, one with the hidden instance assigned and one without, get the same `complete` (P0 T090, T095) - [ ] T021 [US2] TypeScript multisig `getPolicies` and `checkTransaction` in `packages/miden-multisig-client/src/multisig.ts`, matching the Rust `MultisigClient::get_policies` and `ProposalBuilder::check`, with tests; resolve the dependency first, either a `@openzeppelin/guardian-client` release carrying `checkDeltaProposal` and `getPolicies` or a workspace link, per `packages/miden-multisig-client/package.json` (P0 T078) - [ ] T022 [US2] Document the dry-run check and policy listing in `crates/miden-multisig-client/README.md`, `packages/miden-multisig-client/README.md`, `crates/client/README.md` and `packages/guardian-client/README.md` From e4efd83978f448967fc4fb59076761543fb3f408 Mon Sep 17 00:00:00 2001 From: Zeljko Date: Mon, 9 Nov 2026 11:00:44 +0100 Subject: [PATCH 025/105] feat(multisig-client): policy listing and transaction checks in TypeScript (#251) Multisig.getPolicies lists the rules GUARDIAN discloses for the account, and Multisig.checkTransaction checks a transaction before proposing it: one variant per typed create*Proposal method, built by that method's own code on a short-lived view whose push becomes a check, so the check judges exactly the payload proposing would send and nothing is stored. Both mirror the Rust MultisigClient. Tests show a creation refusal reaching callers as the typed refusal in the Rust and TypeScript base clients and SDKs, and the four client READMEs document refusals, the policy listing and the check. --- crates/client/README.md | 20 +++ crates/client/src/testing/client_tests.rs | 43 ++++++ crates/miden-multisig-client/README.md | 23 ++++ crates/miden-multisig-client/src/error.rs | 29 ++++ packages/guardian-client/README.md | 10 ++ packages/guardian-client/src/http.test.ts | 39 ++++++ packages/miden-multisig-client/README.md | 49 +++++++ packages/miden-multisig-client/src/index.ts | 3 +- .../src/multisig.test.ts | 125 ++++++++++++++++++ .../miden-multisig-client/src/multisig.ts | 115 +++++++++++++++- .../features/251-guardian-modules/tasks.md | 8 +- 11 files changed, 458 insertions(+), 6 deletions(-) diff --git a/crates/client/README.md b/crates/client/README.md index b71aa088..d5eae208 100644 --- a/crates/client/README.md +++ b/crates/client/README.md @@ -136,6 +136,26 @@ A refusal is a `ClientError` whose `guardian_code()` is the wire code (for examp `wait_for_guardian_execution` with backoff, retries and a deadline; see [`docs/MULTISIG_SDK.md`](../../docs/MULTISIG_SDK.md#guardian-execution). +### Policy Modules + +`get_policies` lists the rules the Guardian discloses for an account, and +`check_delta_proposal` runs the policy modules on a proposal without storing +it. A request a module refuses fails with a `ClientError` whose +`module_refusal()` returns `ModuleRefusal::Denied { module, reason_code, layer, +client_message }` (final; a generic denial carries only `policy_denied`) or +`ModuleRefusal::Unavailable { module }` (retryable): + +```rust +match client.push_delta_proposal(&account_id, nonce, payload).await { + Err(error) => match error.module_refusal() { + Some(ModuleRefusal::Denied { reason_code, .. }) => { /* final */ } + Some(ModuleRefusal::Unavailable { .. }) => { /* retry later */ } + None => { /* any other error */ } + }, + Ok(response) => { /* stored */ } +} +``` + ### Rate Limits and Retries The server rate-limits both its gRPC and HTTP surfaces. The sustained diff --git a/crates/client/src/testing/client_tests.rs b/crates/client/src/testing/client_tests.rs index 64f85019..e21e8524 100644 --- a/crates/client/src/testing/client_tests.rs +++ b/crates/client/src/testing/client_tests.rs @@ -240,6 +240,49 @@ async fn test_push_delta_proposal_success() { assert!(response.delta.is_some()); } +#[tokio::test] +async fn a_proposal_refused_by_a_policy_module_surfaces_as_a_typed_refusal() { + let details = serde_json::json!({ + "code": "GUARDIAN_MODULE_DENIED", + "message": "This Guardian's policy doesn't allow this request.", + "meta": { + "retryable": false, + "module": "caps", + "reason_code": "amount_cap_exceeded", + "layer": "global" + } + }) + .to_string() + .into_bytes(); + let service = MockGuardianService::default().with_push_delta_proposal(Err( + Status::with_details(tonic::Code::PermissionDenied, "denied", details.into()), + )); + let endpoint = start_mock_server(service).await.unwrap(); + let mut client = GuardianClient::connect(endpoint) + .await + .unwrap() + .with_signer(create_test_signer()); + + let error = client + .push_delta_proposal( + &create_test_account_id(), + 1, + serde_json::json!({"tx_summary": {}, "signatures": []}), + ) + .await + .unwrap_err(); + assert_eq!( + error.module_refusal(), + Some(crate::ModuleRefusal::Denied { + module: Some("caps".into()), + reason_code: "amount_cap_exceeded".into(), + layer: Some("global".into()), + client_message: None, + }) + ); + assert!(!error.is_retryable()); +} + #[tokio::test] async fn test_get_delta_proposals_success() { let mock_delta1 = create_mock_delta(); diff --git a/crates/miden-multisig-client/README.md b/crates/miden-multisig-client/README.md index f888cbbc..011506b1 100644 --- a/crates/miden-multisig-client/README.md +++ b/crates/miden-multisig-client/README.md @@ -788,6 +788,29 @@ per-proposal v2 payload is capped at `MAX_CONSUME_NOTES_METADATA_BYTES` (256 KiB) and the size is enforced at creation time so the failure surfaces to the proposer before any signature collection begins. +### Policy modules: rules and checks + +A Guardian can run policy modules that refuse a proposal at creation or a +transaction at approval. `MultisigClient::get_policies` lists the rules the +operator discloses. `check_transaction` (and `check_transaction_with_options`) +builds a `TransactionType` exactly as `propose_transaction` would and asks the +Guardian whether it would be accepted, without storing it or taking a proposal +slot: + +```rust +let policies = client.get_policies().await?; +let check = client.check_transaction(TransactionType::transfer(recipient, faucet, 1_000)).await?; +// check.complete is false when a module that opts out of checks was skipped +``` + +The answer is advisory: approval still decides, and the Guardian rate limits +checks per account and signer. A refusal, from a check, at creation, push or +registration, is `MultisigError::ModuleDenied { module, reason_code, layer, +client_message }` (final; a generic denial carries only `policy_denied`) or +`MultisigError::ModuleUnavailable { module }` (retryable). A Guardian execution +refused by a module ends failed with `ExecutionFailureCode::ModuleDenied` or +`ExecutionFailureCode::ModuleUnavailable`, and the proposal is kept. + ### Error taxonomy All five errors below carry a stable, cross-SDK string code via diff --git a/crates/miden-multisig-client/src/error.rs b/crates/miden-multisig-client/src/error.rs index 4197b47d..7bd7b894 100644 --- a/crates/miden-multisig-client/src/error.rs +++ b/crates/miden-multisig-client/src/error.rs @@ -557,6 +557,35 @@ mod tests { )); } + #[test] + fn a_proposal_push_keeps_a_module_refusal_typed_and_maps_other_refusals() { + let denied = MultisigError::proposal_push(guardian_status( + tonic::Code::PermissionDenied, + serde_json::json!({ + "code": "GUARDIAN_MODULE_DENIED", + "message": "denied", + "meta": { "retryable": false, "module": "caps", "reason_code": "amount_cap_exceeded" } + }), + )); + assert!( + matches!(denied, MultisigError::ModuleDenied { ref reason_code, .. } if reason_code == "amount_cap_exceeded"), + "{denied:?}" + ); + + let full = MultisigError::proposal_push(guardian_status( + tonic::Code::InvalidArgument, + serde_json::json!({ + "code": "GUARDIAN_PROPOSAL_REQUEST_TOO_LARGE", + "message": "too large", + "meta": { "retryable": false } + }), + )); + assert!(matches!( + full, + MultisigError::GuardianProposalRefused { .. } + )); + } + #[test] fn miden_client_conversion_retains_typed_rpc_kind() { let error = MultisigError::from(request_error(GrpcError::ResourceExhausted)); diff --git a/packages/guardian-client/README.md b/packages/guardian-client/README.md index e3dcb2fc..2b9d78da 100644 --- a/packages/guardian-client/README.md +++ b/packages/guardian-client/README.md @@ -377,6 +377,16 @@ try { } ``` +### Policy module refusals + +A request a policy module refuses is a `GuardianHttpError` whose +`moduleRefusal()` returns `{ kind: 'denied', module, reasonCode, layer, +clientMessage }` (final; a generic denial has only `reasonCode: +'policy_denied'`) or `{ kind: 'unavailable', module }` (retryable), and `null` +for any other error. `getPolicies(accountId)` lists the rules the Guardian +discloses, and `checkDeltaProposal(request)` runs the policy modules on a +proposal without storing it. + ### Rate limits and retries The server rate-limits both its HTTP and gRPC surfaces. The sustained diff --git a/packages/guardian-client/src/http.test.ts b/packages/guardian-client/src/http.test.ts index 0561eacb..e7262b4b 100644 --- a/packages/guardian-client/src/http.test.ts +++ b/packages/guardian-client/src/http.test.ts @@ -725,6 +725,45 @@ describe('GuardianHttpClient', () => { }); describe('pushDeltaProposal', () => { + it('rejects a proposal a policy module refuses with the typed refusal', async () => { + client.setSigner(mockSigner); + mockFetch.mockResolvedValueOnce({ + ok: false, + headers: new Headers(), + status: 403, + statusText: 'Forbidden', + text: async () => + JSON.stringify({ + code: 'GUARDIAN_MODULE_DENIED', + message: "This Guardian's policy doesn't allow this request.", + meta: { + retryable: false, + module: 'caps', + reason_code: 'amount_cap_exceeded', + layer: 'global', + }, + }), + }); + + const error = await client + .pushDeltaProposal({ + accountId: '0x' + 'a'.repeat(30), + nonce: 1, + deltaPayload: { txSummary: { data: 'base64summary' }, signatures: [] }, + }) + .catch((e) => e as GuardianHttpError); + expect(error).toBeInstanceOf(GuardianHttpError); + const refused = error as GuardianHttpError; + expect(refused.moduleRefusal()).toEqual({ + kind: 'denied', + module: 'caps', + reasonCode: 'amount_cap_exceeded', + layer: 'global', + clientMessage: null, + }); + expect(refused.isRetryable()).toBe(false); + }); + it('lets an EIP-712 signer create an unsigned proposal', async () => { const signer: Signer = { ...mockSigner, diff --git a/packages/miden-multisig-client/README.md b/packages/miden-multisig-client/README.md index b5845a07..d69deed2 100644 --- a/packages/miden-multisig-client/README.md +++ b/packages/miden-multisig-client/README.md @@ -553,6 +553,55 @@ which is the Miden default, except on a `guardian_executable` client (see > `newThreshold`) as positional parameters. Passing the old positional form > now throws at runtime instead of silently applying defaults. +### Policy Modules: Rules and Checks + +A Guardian can run policy modules (spending caps, recipient and signer rules, +screening) that refuse a proposal at creation or a transaction at approval. +List the rules the operator discloses, and check a transaction before +proposing it: + +```typescript +const policies = await multisig.getPolicies(); +// [{ moduleId: 'caps', hooks: ['before_transaction_approved'], description: 'At most 5 per transaction' }] + +const check = await multisig.checkTransaction({ + type: 'p2id', + recipientId, + faucetId, + amount: 1_000n, +}); +// { allowed: true, complete }: complete is false when a module that opts out of checks was skipped +``` + +`checkTransaction` builds the transaction exactly as the matching +`create*Proposal` method would, but stores nothing and takes no proposal slot. +It takes one variant per typed creator (`p2id`, `addSigner`, `removeSigner`, +`changeThreshold`, `updateProcedureThreshold`, `consumeNotes`, `custom`) with +that method's arguments. The answer is advisory: approval still decides, and +the Guardian rate limits checks per account and signer. + +A refusal, from a check, at creation or at approval, is a `GuardianHttpError` +with a typed refusal: + +```typescript +import { GuardianHttpError } from '@openzeppelin/miden-multisig-client'; + +try { + await multisig.createP2idProposal(recipientId, faucetId, 1_000n); +} catch (error) { + const refusal = error instanceof GuardianHttpError ? error.moduleRefusal() : null; + if (refusal?.kind === 'denied') { + // Final: { module, reasonCode, layer, clientMessage }; a generic denial has only reasonCode 'policy_denied'. + } else if (refusal?.kind === 'unavailable') { + // Retryable: a fail-closed module could not decide. + } +} +``` + +A Guardian execution refused by a module ends `failed` with +`GUARDIAN_EXECUTION_MODULE_DENIED` or `GUARDIAN_EXECUTION_MODULE_UNAVAILABLE`, +and the proposal is kept. + ### Create a Proposal (Add Signer) ```typescript diff --git a/packages/miden-multisig-client/src/index.ts b/packages/miden-multisig-client/src/index.ts index a1da1bcb..b1b19d43 100644 --- a/packages/miden-multisig-client/src/index.ts +++ b/packages/miden-multisig-client/src/index.ts @@ -87,6 +87,7 @@ export { type CreateProposalOptions, type CreateSignerProposalOptions, type CreateP2idProposalOptions, + type CheckableTransaction, } from './multisig.js'; export { AccountInspector, type DetectedMultisigConfig, type VaultBalance } from './inspector.js'; export { @@ -120,7 +121,7 @@ export type { } from './transaction/options.js'; export { GuardianHttpClient, GuardianHttpError } from '@openzeppelin/guardian-client'; -export type { GuardianErrorMeta, ModuleRefusal } from '@openzeppelin/guardian-client'; +export type { CheckProposalResult, GuardianErrorMeta, ModuleRefusal, Policy } from '@openzeppelin/guardian-client'; // Typed error-code vocabulary (issue #318): branch on GuardianErrorCode, // never on message text; unknown wire codes surface via rawCode. export { diff --git a/packages/miden-multisig-client/src/multisig.test.ts b/packages/miden-multisig-client/src/multisig.test.ts index 5d8d58f3..4fe141e7 100644 --- a/packages/miden-multisig-client/src/multisig.test.ts +++ b/packages/miden-multisig-client/src/multisig.test.ts @@ -3593,6 +3593,89 @@ describe('Multisig', () => { }); }); + describe('policy discovery', () => { + const config = { + threshold: 1, + signerCommitments: ['0x' + 'a'.repeat(64)], + guardianCommitment: '0x' + 'c'.repeat(64), + }; + const payP2id = { + type: 'p2id' as const, + recipientId: '0xrecipient', + faucetId: '0xfaucet', + amount: 100n, + options: { nonce: 1 }, + }; + const lastRequest = () => { + const [url, init] = mockFetch.mock.calls[mockFetch.mock.calls.length - 1]; + const body = (init as RequestInit | undefined)?.body; + return { url: String(url), body: body === undefined ? undefined : JSON.parse(String(body)) }; + }; + + it('checks a transaction built as proposing would build it, storing nothing', async () => { + const multisig = createTestMultisig(config); + mockFetch.mockResolvedValueOnce({ ok: true, json: async () => ({ allowed: true, complete: false }) }); + + const result = await multisig.checkTransaction(payP2id); + + expect(result).toEqual({ allowed: true, complete: false }); + const { url, body } = lastRequest(); + expect(url).toContain('/delta/proposal/check'); + expect(body.delta_payload.metadata).toMatchObject({ + proposal_type: 'p2id', + recipient_id: '0xrecipient', + faucet_id: '0xfaucet', + amount: '100', + }); + expect(multisig.listProposals()).toEqual([]); + }); + + it('rejects a refused check with the refusal creation would return', async () => { + const multisig = createTestMultisig(config); + mockFetch.mockResolvedValueOnce({ + ok: false, + headers: new Headers(), + status: 403, + statusText: 'Forbidden', + text: async () => + JSON.stringify({ + code: 'GUARDIAN_MODULE_DENIED', + message: "This Guardian's policy doesn't allow this request.", + meta: { retryable: false, reason_code: 'policy_denied' }, + }), + }); + + const error = await multisig.checkTransaction(payP2id).catch((e: unknown) => e); + + expect(error).toBeInstanceOf(GuardianHttpError); + expect((error as GuardianHttpError).moduleRefusal()).toMatchObject({ + kind: 'denied', + reasonCode: 'policy_denied', + module: null, + }); + expect(multisig.listProposals()).toEqual([]); + }); + + it('lists the policies GUARDIAN discloses for the account', async () => { + const multisig = createTestMultisig(config); + mockFetch.mockResolvedValueOnce({ + ok: true, + json: async () => ({ + policies: [ + { module_id: 'caps', hooks: ['before_transaction_approved'], description: 'At most 5 per transaction' }, + ], + }), + }); + + const policies = await multisig.getPolicies(); + + expect(policies).toEqual([ + { moduleId: 'caps', hooks: ['before_transaction_approved'], description: 'At most 5 per transaction' }, + ]); + expect(lastRequest().url).toContain('/policies'); + }); + }); + describe('createProposal', () => { it('refuses on a guardian_executable client, which must store the request with the summary', async () => { const multisig = new Multisig( @@ -3644,6 +3727,48 @@ describe('Multisig', () => { expect(mockFetch).not.toHaveBeenCalled(); }); + it('surfaces a policy refusal at creation as the typed GuardianHttpError', async () => { + const config = { + threshold: 1, + signerCommitments: ['0x' + 'a'.repeat(64)], + guardianCommitment: '0x' + 'c'.repeat(64), + }; + const multisig = createTestMultisig(config); + storeHoldsConfig(config); + mockWebClient.accounts.get.mockResolvedValue(mockedAccount(LOCAL_ACCOUNT_COMMITMENT, 1)); + mockFetch.mockResolvedValueOnce({ + ok: false, + headers: new Headers(), + status: 403, + statusText: 'Forbidden', + text: async () => + JSON.stringify({ + code: 'GUARDIAN_MODULE_DENIED', + message: "This Guardian's policy doesn't allow this request.", + meta: { retryable: false, module: 'caps', reason_code: 'amount_cap_exceeded', layer: 'global' }, + }), + }); + + const error = await multisig + .createProposal(1, 'AQID', { + proposalType: 'p2id', + boundBlockNum: MOCK_BOUND_BLOCK_NUM, + saltHex: MOCK_SALT_HEX, + description: '', + recipientId: '0x' + '1'.repeat(30), + faucetId: '0x' + '2'.repeat(30), + amount: '1', + } as never) + .catch((e: unknown) => e); + expect(error).toBeInstanceOf(GuardianHttpError); + expect((error as GuardianHttpError).moduleRefusal()).toMatchObject({ + kind: 'denied', + module: 'caps', + reasonCode: 'amount_cap_exceeded', + }); + expect(multisig.listProposals()).toEqual([]); + }); + it('parses the reply against the signer config in the store', async () => { // The cache predates an executed add of 0xbb.. that also lowered the // threshold; GUARDIAN already holds 0xbb..'s signature. diff --git a/packages/miden-multisig-client/src/multisig.ts b/packages/miden-multisig-client/src/multisig.ts index fc2f7960..ae992abc 100644 --- a/packages/miden-multisig-client/src/multisig.ts +++ b/packages/miden-multisig-client/src/multisig.ts @@ -5,7 +5,7 @@ * for proposal management. */ -import { GuardianHttpClient, GuardianHttpError, type ProposalExecution, type TransactionRequestEnvelope, type AbandonCandidateResponse, type AbandonStatus, type DeltaObject, type HistoryOptions, type HistoryPage, type ProposalSignature, type Signer, type AuthConfig, type StateObject } from '@openzeppelin/guardian-client'; +import { GuardianHttpClient, GuardianHttpError, type CheckProposalResult, type Policy, type ProposalExecution, type TransactionRequestEnvelope, type AbandonCandidateResponse, type AbandonStatus, type DeltaObject, type HistoryOptions, type HistoryPage, type ProposalSignature, type Signer, type AuthConfig, type StateObject } from '@openzeppelin/guardian-client'; import type { ConsumableNote, ExportedProposal, @@ -194,6 +194,33 @@ export interface AccountStateVerificationResult { * knob lives in a single trailing options bag, so call sites never need * positional `undefined` holes to reach a later option. */ +/** + * A transaction to check against GUARDIAN's policy modules before proposing it, one variant per + * typed `create*Proposal` method with that method's arguments. `switch_guardian` is not listed: + * leaving a GUARDIAN is never gated by its modules. + */ +export type CheckableTransaction = + | { type: 'p2id'; recipientId: string; faucetId: string; amount: bigint; options?: CreateP2idProposalOptions } + | { type: 'addSigner'; newSigner: SignerInput; options?: CreateSignerProposalOptions } + | { type: 'removeSigner'; signer: string; options?: CreateSignerProposalOptions } + | { type: 'changeThreshold'; newThreshold: number; options?: CreateProposalOptions } + | { + type: 'updateProcedureThreshold'; + procedure: ProcedureName; + threshold: number; + options?: CreateProposalOptions; + } + | { type: 'consumeNotes'; noteIds: string[]; options?: CreateProposalOptions } + | { + type: 'custom'; + transactionRequestBytes: Uint8Array; + proposalType: string; + options?: CreateProposalOptions; + }; + +/** Thrown inside a check once the payload is built, so nothing after the push runs. */ +const CHECKED = Symbol('checked'); + export interface CreateProposalOptions { /** * Proposal nonce: the account nonce the executed transaction will have. @@ -1362,6 +1389,56 @@ export class Multisig { return this.pushProposal(nonce, txSummaryBase64, metadata, undefined); } + /** + * The policies GUARDIAN applies to this account, as far as its operator discloses them, in + * the order they are evaluated. Mirrors the Rust `MultisigClient::get_policies`. + */ + async getPolicies(): Promise { + return this.guardian.getPolicies(this._accountId); + } + + /** + * Asks GUARDIAN whether `transaction` would be accepted as a proposal: it is built exactly as + * the matching `create*Proposal` method builds it, but nothing is stored and no proposal slot + * is taken. Resolves with `complete: false` when a module that opts out of checks was skipped. + * A policy refusal rejects with the same `GuardianHttpError` creation would + * (`moduleRefusal()`). Advisory: approval still decides, and GUARDIAN rate limits checks per + * account and signer. Mirrors the Rust `MultisigClient::check_transaction`. + */ + async checkTransaction(transaction: CheckableTransaction): Promise { + let result: CheckProposalResult | undefined; + const checking = Object.create(this) as Multisig; + (checking as unknown as { pushProposal: Multisig['pushProposal'] }).pushProposal = async ( + nonce, + txSummaryBase64, + metadata, + transactionRequest, + ) => { + result = await this.guardian.checkDeltaProposal({ + accountId: this._accountId, + nonce, + deltaPayload: { + txSummary: { data: txSummaryBase64 }, + signatures: [], + metadata: ProposalMetadataCodec.toGuardian(metadata), + ...(transactionRequest ? { transactionRequest } : {}), + }, + }); + throw CHECKED; + }; + try { + await proposeOn(checking, transaction); + } catch (error) { + if (error !== CHECKED) { + throw error; + } + } + if (!result) { + throw new Error('the transaction was not built, so it was not checked'); + } + return result; + } + /** * Push a proposal to GUARDIAN and parse the reply against the signer config * the caller refreshed from the store. @@ -3848,3 +3925,39 @@ function decodeEmbeddedConsumeNotes(metadata: ConsumeNotesProposalMetadata): Not } return decoded; } + +function proposeOn(multisig: Multisig, transaction: CheckableTransaction): Promise { + switch (transaction.type) { + case 'p2id': + return multisig.createP2idProposal( + transaction.recipientId, + transaction.faucetId, + transaction.amount, + transaction.options, + ); + case 'addSigner': + return multisig.createAddSignerProposal(transaction.newSigner, transaction.options); + case 'removeSigner': + return multisig.createRemoveSignerProposal(transaction.signer, transaction.options); + case 'changeThreshold': + return multisig.createChangeThresholdProposal(transaction.newThreshold, transaction.options); + case 'updateProcedureThreshold': + return multisig.createUpdateProcedureThresholdProposal( + transaction.procedure, + transaction.threshold, + transaction.options, + ); + case 'consumeNotes': + return multisig.createConsumeNotesProposal(transaction.noteIds, transaction.options); + case 'custom': + return multisig.createCustomProposal( + transaction.transactionRequestBytes, + transaction.proposalType, + transaction.options, + ); + default: { + const unreachable: never = transaction; + throw new Error(`Unknown transaction ${JSON.stringify(unreachable)}`); + } + } +} diff --git a/speckit/features/251-guardian-modules/tasks.md b/speckit/features/251-guardian-modules/tasks.md index 35a8f4a8..42828d6a 100644 --- a/speckit/features/251-guardian-modules/tasks.md +++ b/speckit/features/251-guardian-modules/tasks.md @@ -77,15 +77,15 @@ ### Tests for User Story 2 -- [ ] T017 [P] [US2] Creation refusal through the Rust layers: `crates/client/src/testing/client_tests.rs` (typed `module_refusal()` on `push_delta_proposal`) and `crates/miden-multisig-client/src/client/proposals.rs` tests (`MultisigError::ModuleDenied` from proposal creation, slot count unchanged on the server mock) -- [ ] T018 [P] [US2] Creation refusal through the TypeScript layers: `packages/guardian-client/src/http.test.ts` (`pushDeltaProposal` rejects with `moduleRefusal()` set) and `packages/miden-multisig-client/src/` proposal creation tests (refusal surfaces unchanged to the caller) +- [X] T017 [P] [US2] Creation refusal through the Rust layers: `crates/client/src/testing/client_tests.rs` (typed `module_refusal()` on `push_delta_proposal`) and `crates/miden-multisig-client/src/client/proposals.rs` tests (`MultisigError::ModuleDenied` from proposal creation, slot count unchanged on the server mock) +- [X] T018 [P] [US2] Creation refusal through the TypeScript layers: `packages/guardian-client/src/http.test.ts` (`pushDeltaProposal` rejects with `moduleRefusal()` set) and `packages/miden-multisig-client/src/` proposal creation tests (refusal surfaces unchanged to the caller) ### Implementation for User Story 2 - [X] T019 [US2] Dry-run check runs `before_transaction_approved`-only instances after the creation instances, each instance once, every request with `HookRequest.dry_run = true`, in `crates/server/src/modules/pipeline.rs` (`plan_dry_run`) and `crates/server/src/services/push_delta_proposal.rs`; tests that an approval-only cap refuses the check (P0 T095) - [X] T020 [US2] `complete` derived from the catalog, not the account: `false` whenever any enabled gate instance has `dry_run = false`, in `crates/server/src/modules/pipeline.rs`; test that two accounts, one with the hidden instance assigned and one without, get the same `complete` (P0 T090, T095) -- [ ] T021 [US2] TypeScript multisig `getPolicies` and `checkTransaction` in `packages/miden-multisig-client/src/multisig.ts`, matching the Rust `MultisigClient::get_policies` and `ProposalBuilder::check`, with tests; resolve the dependency first, either a `@openzeppelin/guardian-client` release carrying `checkDeltaProposal` and `getPolicies` or a workspace link, per `packages/miden-multisig-client/package.json` (P0 T078) -- [ ] T022 [US2] Document the dry-run check and policy listing in `crates/miden-multisig-client/README.md`, `packages/miden-multisig-client/README.md`, `crates/client/README.md` and `packages/guardian-client/README.md` +- [X] T021 [US2] TypeScript multisig `getPolicies` and `checkTransaction` in `packages/miden-multisig-client/src/multisig.ts`, matching the Rust `MultisigClient::get_policies` and `ProposalBuilder::check`, with tests; the packages workspace links `@openzeppelin/guardian-client` locally, so no client release was needed; the check runs the real `create*Proposal` code on a short-lived view whose push becomes `checkDeltaProposal` (P0 T078) +- [X] T022 [US2] Document the dry-run check and policy listing in `crates/miden-multisig-client/README.md`, `packages/miden-multisig-client/README.md`, `crates/client/README.md` and `packages/guardian-client/README.md` **Checkpoint**: SC-003 holds and every client exposes the check. From 461f45f13a5fd1d9802aa8a4f60f786f49cf7e43 Mon Sep 17 00:00:00 2001 From: Zeljko Date: Mon, 9 Nov 2026 11:01:12 +0100 Subject: [PATCH 026/105] docs(rfc): RFC 0002 revision 28, protocol version 1 frozen (#251) The freeze criteria of RFC section 7 are implemented with tests: the renumbered proto, registration before the claim including the lost claim, network_id, code and procedure fields, reference and expiration blocks, new_code_commitment, submitter_session, the dry run with approval instances, and the basic-policy code allowlist. From here guardian.module.v1 changes only additively; the proto copies and RFC section 7 record it. --- crates/guardian-module-sdk/proto/guardian_module_v1.proto | 4 ++-- docs/rfcs/0002-guardian-modules.md | 5 ++++- .../251-guardian-modules/contracts/guardian_module_v1.proto | 4 ++-- speckit/features/251-guardian-modules/tasks.md | 2 +- 4 files changed, 9 insertions(+), 6 deletions(-) diff --git a/crates/guardian-module-sdk/proto/guardian_module_v1.proto b/crates/guardian-module-sdk/proto/guardian_module_v1.proto index ac81d582..8fdcce9d 100644 --- a/crates/guardian-module-sdk/proto/guardian_module_v1.proto +++ b/crates/guardian-module-sdk/proto/guardian_module_v1.proto @@ -1,6 +1,6 @@ -// guardian.module.v1, extracted from docs/rfcs/0002-guardian-modules.md section 3 (revision 26). +// guardian.module.v1, extracted from docs/rfcs/0002-guardian-modules.md section 3 (revision 28). // The proto in RFC section 3 is authoritative; regenerate this file when it changes. -// Protocol version 1 is frozen when M2a ships. +// Protocol version 1 is frozen (2026-11-09, at e4efd839): changes within it are additive only (RFC section 3.5). syntax = "proto3"; package guardian.module.v1; diff --git a/docs/rfcs/0002-guardian-modules.md b/docs/rfcs/0002-guardian-modules.md index 0fdc99eb..ce439448 100644 --- a/docs/rfcs/0002-guardian-modules.md +++ b/docs/rfcs/0002-guardian-modules.md @@ -7,7 +7,7 @@ | **Feature** | [#251](https://github.com/OpenZeppelin/guardian/issues/251) ("Modularization: middleware architecture and pluggable modules"); first consumer [#182](https://github.com/OpenZeppelin/guardian/issues/182) (policy evaluation). [#252](https://github.com/OpenZeppelin/guardian/issues/252) (x402 facilitator) is a later consumer: its payment-policy half (caps, allowlists, replay) fits `before_transaction_approved` and `after_transaction_committed`, its facilitator half (`/verify`, `/settle`, a flow that starts and waits) does not fit allow/deny and is future work (section 7) | | **Audience** | Operators, module authors, integrators, and anyone reviewing the Guardian trust model | | **Working artifacts** | [`speckit/features/251-guardian-modules/`](../../speckit/features/251-guardian-modules/spec.md): the specification, written alongside this RFC; plan and tasks follow the prototype | -| **Revision** | 27 (2026-11-09): `proposer_session` dropped from version 1, `submitter_session` set at the ack now that pushes accept sessions; changes in Appendix C | +| **Revision** | 28 (2026-11-09): protocol version 1 frozen at `e4efd839`; changes in Appendix C | | **Review sought** | Comments on the design and the M2a scope remain open until M2a ships, when `guardian.module.v1` freezes (section 7) | | **Code baseline** | `main` at `ca503704`; execution-path citations read on `254-execution-impl` at `29c722b4` (PR #510, since merged to `main` as `1100f3a4`) and kept as dated evidence. Miden pins: protocol and standards 0.17.1. Appendices B and C cite the baselines of their revisions. Prototype findings (2026-10-13 to 2026-10-15) in `speckit/features/251-guardian-modules/research.md` | @@ -1093,6 +1093,8 @@ The first enclave step allows in-process kinds only; the attested tier follows o **Freeze criteria.** Version 1 freezes only once the prototype implements, with tests, the protocol surface added in revision 24 that is so far derived from reading code: the renumbered proto, registration before the claim (new account, unfinished claim, lost claim), `network_id`, `code_commitment` and `procedure_roots` with effective-override filtering (non-zero, exported, not the auth procedure), `reference_block` and the optional `expiration_block`, `new_code_commitment`, `submitter_session`, `dry_run` with approval instances in the check, and the `allowed_code_commitments` rule with `code_check`. Extraction details are where the prototype found errors before (the fee note, single-key views), so these are measured against real accounts, not only fixtures. +**Frozen.** The freeze criteria were met on 2026-11-09 at `e4efd839` on the M2a branch `251-modules-m2a`: every field and behaviour listed above is implemented with tests, except `proposer_session`, removed in revision 27 (section 3.2). From then on `guardian.module.v1` changes only additively (section 3.5). + **M2a: stateless gates.** - Gate hooks `before_transaction_approved`, `before_proposal_created` and `before_account_registered` (section 2.3), the pipeline, and the catalog with kinds and instances, `enabled`, `operator_can_disable` and secret references. @@ -1204,6 +1206,7 @@ None. Questions resolved in earlier revisions are kept below with their answers. | Revision | Date | Changes | |---|---|---| +| 28 | 2026-11-09 | protocol version 1 frozen: the freeze criteria of section 7 met at `e4efd839` on `251-modules-m2a`, with tests; the proto copies say so. No design change | | 27 | 2026-11-09 | `proposer_session` removed from `TransactionSubject`, `PendingTransaction` and `CommitEvent`, and `unverified_metadata` renumbered to 5 before the freeze: a session key cannot approve a proposal, so whether one created it adds nothing the threshold does not already require, and no catalog policy uses it; version 1 can add it later. Section 3.2 corrected for #580: `push_delta` and Guardian execution accept session credentials, so `submitter_session` can be true at the ack. Freeze criteria and the M2a list updated (section 7) | | 26 | 2026-11-09 | `main` (mixed-scheme accounts, #565) merged into the prototype. `AccountView.signer_schemes` (signer commitment to `falcon` or `ecdsa`), decoded per approver from state, and `auth_scheme` redefined as the signers' common scheme or `mixed`, because "one scheme per account" no longer holds (section 3.2). The execution path's refusals named as `GUARDIAN_EXECUTION_MODULE_DENIED` and `GUARDIAN_EXECUTION_MODULE_UNAVAILABLE` failure codes (section 4.1). The execution requester is carried to the ack, not stored on the reservation, since pre-boundary attempts are never resumed (sections 3.2 and 7) | | 25 | 2026-11-03 | status moved from Open for comment to Accepted for implementation on merge of PR #544; RFC 0001 links point at its merged copy and section 7 records that PR #510 has merged; review-sought and code-baseline rows updated to match. No design change | diff --git a/speckit/features/251-guardian-modules/contracts/guardian_module_v1.proto b/speckit/features/251-guardian-modules/contracts/guardian_module_v1.proto index ac81d582..8fdcce9d 100644 --- a/speckit/features/251-guardian-modules/contracts/guardian_module_v1.proto +++ b/speckit/features/251-guardian-modules/contracts/guardian_module_v1.proto @@ -1,6 +1,6 @@ -// guardian.module.v1, extracted from docs/rfcs/0002-guardian-modules.md section 3 (revision 26). +// guardian.module.v1, extracted from docs/rfcs/0002-guardian-modules.md section 3 (revision 28). // The proto in RFC section 3 is authoritative; regenerate this file when it changes. -// Protocol version 1 is frozen when M2a ships. +// Protocol version 1 is frozen (2026-11-09, at e4efd839): changes within it are additive only (RFC section 3.5). syntax = "proto3"; package guardian.module.v1; diff --git a/speckit/features/251-guardian-modules/tasks.md b/speckit/features/251-guardian-modules/tasks.md index 42828d6a..7dbb2747 100644 --- a/speckit/features/251-guardian-modules/tasks.md +++ b/speckit/features/251-guardian-modules/tasks.md @@ -43,7 +43,7 @@ - [X] T009 Record `signed_at` (fixed before the pipeline runs and sent as `accounting_time`), `submitter` and `proposer` with the approval trace (`catalog_hash`, `params_version`, `failed_open`) in `ModuleApproval` (`crates/server/src/delta_summary/mod.rs`), written at signing in `crates/server/src/services/ack_delta_internal.rs`; the pipeline returns only the configuration it ran with (`Evaluation`, `crates/server/src/modules/pipeline.rs`). Revised 2026-11-09: kept in `metadata.modules` instead of new delta columns, since delta metadata is already stored on both backends and served only on HTTP, so no migration and no wire change; `data-model.md` updated - [X] T010 [P] Build account views from the single decode the push path already does: carry the view fields on `AppliedState` (`crates/server/src/network/mod.rs`, `crates/server/src/network/miden/mod.rs` `verify_and_apply_delta`) and use them in `crates/server/src/modules/request.rs` instead of a second `Account::from_json`; run proposal creation through `verify_and_apply_delta` when a module will be called (P0 T089) - [X] T011 Measure the frozen extraction against real account layouts, not only synthetic slots: views of accounts built from the upstream `miden-standards` components (single-key Falcon and ECDSA, 2-of-3 Falcon guarded multisig, mixed-scheme guarded multisig with a procedure override, an override on the auth procedure) asserted in `crates/server/src/network/miden/module_views.rs` (`standard_account_tests`); the code-replacement projection is covered by the `new_code_commitment` test. Revised 2026-11-09: built from the real components instead of captured from devnet, which needs funded accounts; a devnet capture remains for the T059 walk-through. Found: the `DELTA_1` fixture adds an approver key without its scheme entry, which the standard multisig always writes, so its resulting view is refused -- [ ] T012 Mark protocol version 1 frozen: state it in the proto header of `crates/guardian-module-sdk/proto/guardian_module_v1.proto` and the contract copy, and record the freeze (commit and date) in RFC 0002 section 7 and Appendix C (`docs/rfcs/0002-guardian-modules.md`). Runs last among the freeze criteria (RFC 0002 section 7): after T019 and T020 (dry run with approval instances), T024 (lost claim) and T025 (`code_check`), which use fields already in the proto but must be implemented with tests before the freeze +- [X] T012 Mark protocol version 1 frozen: state it in the proto header of `crates/guardian-module-sdk/proto/guardian_module_v1.proto` and the contract copy, and record the freeze (commit and date) in RFC 0002 section 7 and Appendix C (`docs/rfcs/0002-guardian-modules.md`). Runs last among the freeze criteria (RFC 0002 section 7): after T019 and T020 (dry run with approval instances), T024 (lost claim) and T025 (`code_check`), which use fields already in the proto but must be implemented with tests before the freeze **Checkpoint**: requests carry the complete version 1 surface, measured on real account layouts (T003 to T011). User story phases can start in parallel. T012, the freeze itself, waits for the behaviour-only freeze criteria in US2 and US3. From 435c4986d1c288901e3d36b537a9fce018e1b553 Mon Sep 17 00:00:00 2001 From: Zeljko Date: Mon, 9 Nov 2026 11:07:05 +0100 Subject: [PATCH 027/105] chore(modules): drop a needless borrow in the dry-run planner (#251) --- crates/server/src/modules/pipeline.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/server/src/modules/pipeline.rs b/crates/server/src/modules/pipeline.rs index ff9eea40..177c8e69 100644 --- a/crates/server/src/modules/pipeline.rs +++ b/crates/server/src/modules/pipeline.rs @@ -547,7 +547,7 @@ impl ModulePipeline { ) -> Result<(Vec>, bool), GuardianError> { let (_, rows) = self.versioned_rows().await?; let complete = !self.instances.iter().any(|instance| { - Self::enabled_in(&rows, &instance) + Self::enabled_in(&rows, instance) && !instance.config.dry_run && (instance .config From af9ac083f25cacc14e3a9a806eaede268357d1ac Mon Sep 17 00:00:00 2001 From: Zeljko Date: Mon, 9 Nov 2026 11:17:49 +0100 Subject: [PATCH 028/105] feat(modules): the default scope, copied into new accounts at registration (#251) A scope = "default" instance judges a new account's registration with its current global params, and once the request has claimed the account every enabled default instance is copied into its assignment with exactly those params. ModuleStore::seed_assignment writes the copy only into an account with no assignment and no assignment history, under the module state lock, so an operator write wins; a crash between claim and copy leaves an unfinished claim whose retry copies again. Existing accounts never receive defaults, and a refused or lost registration copies nothing (RFC 0002 revision 29). Default instances count in the budget like assignments. Account views report each row's real scope and an orphaned flag, and GET /dashboard/modules lists stored instances the catalog no longer declares under undeclared. --- crates/server/src/modules/admin.rs | 137 ++++++++++-- crates/server/src/modules/catalog.rs | 8 +- crates/server/src/modules/pipeline.rs | 71 ++++-- crates/server/src/modules/postgres_store.rs | 104 +++++++++ crates/server/src/modules/store.rs | 87 ++++++++ crates/server/src/modules/testing.rs | 11 + .../server/src/services/configure_account.rs | 203 ++++++++++++++++-- docs/rfcs/0002-guardian-modules.md | 5 +- .../contracts/operator-modules-api.md | 14 +- .../features/251-guardian-modules/tasks.md | 8 +- 10 files changed, 586 insertions(+), 62 deletions(-) diff --git a/crates/server/src/modules/admin.rs b/crates/server/src/modules/admin.rs index 0dd9c17d..f5b75a94 100644 --- a/crates/server/src/modules/admin.rs +++ b/crates/server/src/modules/admin.rs @@ -41,6 +41,16 @@ pub struct ModuleCatalogView { pub catalog_hash: String, pub params_version: u64, pub modules: Vec, + /// Stored instances the catalog no longer declares: kept, never evaluated, active again if + /// the catalog brings the id back. + pub undeclared: Vec, +} + +#[derive(Debug, Clone, Serialize)] +pub struct UndeclaredInstanceView { + pub module_id: String, + pub enabled: bool, + pub params: serde_json::Value, } #[derive(Debug, Clone, Serialize)] @@ -48,6 +58,8 @@ pub struct AccountModuleEntry { pub module_id: String, pub scope: &'static str, pub enabled: bool, + /// A stored entry naming an instance the catalog no longer declares; skipped at evaluation. + pub orphaned: bool, #[serde(skip_serializing_if = "Option::is_none")] pub global_params: Option, #[serde(skip_serializing_if = "Option::is_none")] @@ -71,6 +83,7 @@ pub struct ParamsHistoryView { fn scope_name(scope: Scope) -> &'static str { match scope { Scope::All => "all", + Scope::Default => "default", Scope::Assigned => "assigned", } } @@ -210,10 +223,24 @@ pub async fn catalog_view(state: &AppState) -> Result { for instance in pipeline.instances() { modules.push(instance_view(pipeline, instance).await?); } + let undeclared = pipeline + .store() + .instances() + .await + .map_err(GuardianError::StorageError)? + .into_iter() + .filter(|row| pipeline.instance(&row.module_id).is_none()) + .map(|row| UndeclaredInstanceView { + module_id: row.module_id, + enabled: row.enabled, + params: row.global_params, + }) + .collect(); Ok(ModuleCatalogView { catalog_hash: pipeline.catalog_hash.clone(), params_version: version(pipeline).await?, modules, + undeclared, }) } @@ -235,6 +262,7 @@ pub async fn account_view(state: &AppState, account_id: &str) -> Result Result pipeline.enabled(instance).await?, - None => false, - }; + for row in rows + .iter() + .filter(|row| row.kind == ParamsKind::Layer && pipeline.instance(&row.module_id).is_none()) + { + modules.push(AccountModuleEntry { + module_id: row.module_id.clone(), + scope: "all", + enabled: false, + orphaned: true, + global_params: None, + account_layer: Some(row.params.clone()), + params: None, + }); + } + for row in rows + .into_iter() + .filter(|row| row.kind == ParamsKind::Assignment) + { + let instance = pipeline.instance(&row.module_id); + modules.push(AccountModuleEntry { + scope: instance.map_or("assigned", |instance| scope_name(instance.config.scope)), + enabled: match instance { + Some(instance) => pipeline.enabled(instance).await?, + None => false, + }, + orphaned: instance.is_none(), + module_id: row.module_id, + global_params: None, + account_layer: None, + params: Some(row.params), + }); } Ok(AccountModulesView { account_id, @@ -673,6 +715,67 @@ mod tests { )); } + #[tokio::test] + async fn views_report_real_scopes_orphaned_rows_and_undeclared_instances() { + let mut state = state(); + let store = state.modules.as_ref().unwrap().store_handle(); + let mut instances = state.modules.as_ref().unwrap().instances().to_vec(); + let mut screening = instance( + "screening", + &[HookName::BeforeTransactionApproved], + OnError::Deny, + Arc::new(BasicPolicy), + ); + screening.config.scope = Scope::Default; + instances.push(screening); + store + .seed_instance("retired", true, &json!({ "old": true }), "t0") + .await + .unwrap(); + store + .set_assignment( + ACCOUNT, + vec![ + Assigned { + module_id: "screening".into(), + params: json!({}), + }, + Assigned { + module_id: "retired".into(), + params: json!({}), + }, + ], + &Change { + operator: "0xop", + reason: "setup", + at: "t1".into(), + }, + ) + .await + .unwrap(); + state.modules = Some(Arc::new(ModulePipeline::from_instances_with_store( + instances, store, + ))); + + let account = account_view(&state, ACCOUNT).await.unwrap(); + let entry = |id: &str| { + account + .modules + .iter() + .find(|entry| entry.module_id == id) + .unwrap() + .clone() + }; + assert_eq!(entry("screening").scope, "default"); + assert!(!entry("screening").orphaned); + assert!(entry("retired").orphaned); + assert!(!entry("retired").enabled); + + let catalog = catalog_view(&state).await.unwrap(); + assert_eq!(catalog.undeclared.len(), 1); + assert_eq!(catalog.undeclared[0].module_id, "retired"); + } + #[tokio::test] async fn the_catalog_view_shows_each_instance_circuit_on_this_replica() { let state = state(); diff --git a/crates/server/src/modules/catalog.rs b/crates/server/src/modules/catalog.rs index a21e3bce..95b100ad 100644 --- a/crates/server/src/modules/catalog.rs +++ b/crates/server/src/modules/catalog.rs @@ -14,7 +14,11 @@ const TIMEOUT_MAX_MS: u64 = 1000; #[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize)] #[serde(rename_all = "snake_case")] pub enum Scope { + /// Every account, always; an account layer can only add restrictions. All, + /// Copied into an account's assignment when it first registers; replaceable per account. + Default, + /// Only accounts an operator assigns it to. Assigned, } @@ -530,10 +534,6 @@ on_error = "allow" 1, ), ), - ( - "default scope", - VALID.replacen(r#"scope = "assigned""#, r#"scope = "default""#, 1), - ), ( "timeout", VALID.replacen("timeout_ms = 20", "timeout_ms = 5000", 1), diff --git a/crates/server/src/modules/pipeline.rs b/crates/server/src/modules/pipeline.rs index 177c8e69..4738d153 100644 --- a/crates/server/src/modules/pipeline.rs +++ b/crates/server/src/modules/pipeline.rs @@ -10,7 +10,7 @@ use super::breaker::Breakers; use super::limits::Limits; use super::registry::{CallError, Instance, Registry, isolated}; use super::request::ViewCache; -use super::store::{AccountParamsRow, ModuleStore, ParamsKind}; +use super::store::{AccountParamsRow, Assigned, ModuleStore, ParamsKind}; use crate::delta_summary::FailedOpen; use crate::error::GuardianError; @@ -271,7 +271,7 @@ impl ModulePipeline { let id = instance.config.id.as_str(); let count = match instance.config.scope { Scope::All => 1 + calls(id, ParamsKind::Layer), - Scope::Assigned => calls(id, ParamsKind::Assignment), + Scope::Default | Scope::Assigned => calls(id, ParamsKind::Assignment), }; instance.config.timeout * count }) @@ -474,26 +474,64 @@ impl ModulePipeline { hook: HookName, account_id: &str, ) -> Result>, GuardianError> { + Ok(self.plan_with(hook, account_id, false).await?.0) + } + + /// The `before_account_registered` plan of an account registering for the first time (no + /// account yet, or a claim with no assignment history): the `all` instances and every + /// enabled `default` instance subscribed to the hook, with its current global params. Also + /// returns the `default` copies to store for the account, every enabled `default` instance + /// with exactly the params evaluated, read in the same snapshot. + pub async fn plan_first_registration( + &self, + account_id: &str, + ) -> Result<(Option>, Vec), GuardianError> { + self.plan_with(HookName::BeforeAccountRegistered, account_id, true) + .await + } + + async fn plan_with( + &self, + hook: HookName, + account_id: &str, + first_registration: bool, + ) -> Result<(Option>, Vec), GuardianError> { let account_id = account_id.to_ascii_lowercase(); let subscribed = |rows: &Rows, instance: &&Instance| { instance.config.hooks.contains(&hook) && Self::enabled_in(rows, instance) }; - let (_, rows) = self.versioned_rows().await?; - if !self - .instances - .iter() - .any(|instance| subscribed(&rows, &instance)) - { - return Ok(None); + if !first_registration { + let (_, rows) = self.versioned_rows().await?; + if !self + .instances + .iter() + .any(|instance| subscribed(&rows, &instance)) + { + return Ok((None, Vec::new())); + } } let (params_version, rows, account_rows) = self.snapshot(&account_id).await?; + let defaults: Vec = if first_registration { + self.instances + .iter() + .filter(|instance| { + instance.config.scope == Scope::Default && Self::enabled_in(&rows, instance) + }) + .map(|instance| Assigned { + module_id: instance.config.id.clone(), + params: Self::global_params_in(&rows, instance), + }) + .collect() + } else { + Vec::new() + }; let active: Vec<&Instance> = self .instances .iter() .filter(|instance| subscribed(&rows, instance)) .collect(); if active.is_empty() { - return Ok(None); + return Ok((None, defaults)); } let mut modules = Vec::new(); for instance in active @@ -522,7 +560,15 @@ impl ModulePipeline { modules.push((*instance, row.params.clone(), Layer::Account)); } } - Ok((!modules.is_empty()).then_some(Plan { + for copy in &defaults { + if let Some(instance) = active + .iter() + .find(|instance| instance.config.id == copy.module_id) + { + modules.push((*instance, copy.params.clone(), Layer::Global)); + } + } + let plan = (!modules.is_empty()).then_some(Plan { hook, account_id, modules, @@ -532,7 +578,8 @@ impl ModulePipeline { limits: self.limits, breakers: self.breakers.clone(), dry_run: false, - })) + }); + Ok((plan, defaults)) } /// The plans for a dry-run check of a proposal: the `before_proposal_created` instances, diff --git a/crates/server/src/modules/postgres_store.rs b/crates/server/src/modules/postgres_store.rs index c17f715f..78403234 100644 --- a/crates/server/src/modules/postgres_store.rs +++ b/crates/server/src/modules/postgres_store.rs @@ -550,6 +550,75 @@ impl ModuleStore for PgModuleStore { .map_err(|e| format!("set assignment: {e}")) } + async fn seed_assignment( + &self, + account_id: &str, + modules: Vec, + change: &Change<'_>, + ) -> Result { + if modules.is_empty() { + return Ok(false); + } + let changed_at = at(change)?; + let mut conn = self.conn().await?; + let account_id = account_id.to_string(); + let written = conn + .transaction::<(), diesel::result::Error, _>(|conn| { + async move { + // The version row lock serializes every module write, so the check below + // and the insert cannot interleave with another write for this account. + let version = bump(conn).await?; + let taken: Vec = diesel::sql_query( + "SELECT 1::BIGINT AS version WHERE EXISTS (SELECT 1 FROM \ + module_account_params WHERE account_id = $1 AND kind = 'assignment') \ + OR EXISTS (SELECT 1 FROM module_params_history WHERE account_id = $1)", + ) + .bind::(&account_id) + .load(conn) + .await?; + if !taken.is_empty() { + return Err(diesel::result::Error::RollbackTransaction); + } + for (position, assigned) in modules.iter().enumerate() { + diesel::sql_query( + "INSERT INTO module_account_params \ + (account_id, module_id, kind, position, params, updated_at, updated_by) \ + VALUES ($1, $2, 'assignment', $3, $4, $5, $6)", + ) + .bind::(&account_id) + .bind::(&assigned.module_id) + .bind::(position as i32) + .bind::(&assigned.params) + .bind::(changed_at) + .bind::(change.operator) + .execute(conn) + .await?; + } + for (module_id, before, after) in assignment_changes(&[], &modules) { + append( + conn, + version, + &module_id, + Some(&account_id), + &before, + &after, + change, + changed_at, + ) + .await?; + } + Ok(()) + } + .scope_boxed() + }) + .await; + match written { + Ok(()) => Ok(true), + Err(diesel::result::Error::RollbackTransaction) => Ok(false), + Err(e) => Err(format!("seed assignment: {e}")), + } + } + async fn history(&self, module_id: &str) -> Result, String> { let mut conn = self.conn().await?; let rows: Vec = diesel::sql_query( @@ -739,6 +808,41 @@ mod tests { assert!(store.version().await.unwrap() >= before + 8); } + #[tokio::test] + #[ignore = "requires Postgres; run ./scripts/test-postgres.sh"] + async fn default_copies_reach_only_accounts_without_assignment_history() { + let url = test_database_url().await; + let store = PgModuleStore::new(build_postgres_pool_lazy(&url, 2).expect("pool")); + let account = format!("0xseed{}", rand::random::()); + let copy = || { + vec![Assigned { + module_id: "screening".into(), + params: json!({ "limit": 5 }), + }] + }; + let t0 = "2026-11-09T00:00:00Z"; + assert!(store.seed_assignment(&account, copy(), &change(t0)).await.unwrap()); + let before = store.version().await.unwrap(); + assert!( + !store.seed_assignment(&account, copy(), &change(t0)).await.unwrap(), + "an existing assignment is kept" + ); + assert_eq!( + store.version().await.unwrap(), + before, + "a refused copy does not move the version" + ); + store + .set_assignment(&account, Vec::new(), &change(t0)) + .await + .unwrap(); + assert!( + !store.seed_assignment(&account, copy(), &change(t0)).await.unwrap(), + "an assignment an operator emptied is not refilled" + ); + assert!(store.account_params(&account).await.unwrap().is_empty()); + } + #[tokio::test] #[ignore = "requires Postgres; run ./scripts/test-postgres.sh"] async fn a_conditional_write_only_replaces_the_value_it_expects() { diff --git a/crates/server/src/modules/store.rs b/crates/server/src/modules/store.rs index d00d94fe..ede4936a 100644 --- a/crates/server/src/modules/store.rs +++ b/crates/server/src/modules/store.rs @@ -140,6 +140,16 @@ pub trait ModuleStore: Send + Sync { change: &Change<'_>, ) -> Result<(), String>; + /// Writes `modules` as the account's assignment only when it has neither an assignment nor + /// any assignment history, which is how `default` instances reach a newly registered + /// account; an operator's earlier write always wins. Returns whether it wrote. + async fn seed_assignment( + &self, + account_id: &str, + modules: Vec, + change: &Change<'_>, + ) -> Result; + async fn history(&self, module_id: &str) -> Result, String>; async fn version(&self) -> Result; @@ -486,6 +496,42 @@ impl ModuleStore for FsModuleStore { }) } + async fn seed_assignment( + &self, + account_id: &str, + modules: Vec, + change: &Change<'_>, + ) -> Result { + self.write(|tables| { + let assigned = tables + .account_params + .iter() + .any(|row| row.account_id == account_id && row.kind == ParamsKind::Assignment); + let history = tables + .history + .iter() + .any(|entry| entry.account_id.as_deref() == Some(account_id)); + if assigned || history || modules.is_empty() { + return Ok(false); + } + for (position, assigned) in modules.iter().enumerate() { + tables.account_params.push(AccountParamsRow { + account_id: account_id.to_string(), + module_id: assigned.module_id.clone(), + kind: ParamsKind::Assignment, + position: position as i32, + params: assigned.params.clone(), + updated_at: change.at.clone(), + updated_by: change.operator.to_string(), + }); + } + for (module_id, before, after) in assignment_changes(&[], &modules) { + tables.append(&module_id, Some(account_id), before, after, change); + } + Ok(true) + }) + } + async fn history(&self, module_id: &str) -> Result, String> { Ok(self.read(|tables| { tables @@ -618,6 +664,47 @@ mod tests { assert_eq!(history[1].previous, json!({ "b": 1 })); } + #[tokio::test] + async fn default_copies_never_overwrite_an_operator_write_or_refill_an_emptied_assignment() { + let store = FsModuleStore::in_memory(); + let change = |at: &str| Change { + operator: "catalog", + reason: "default", + at: at.into(), + }; + let copy = || { + vec![Assigned { + module_id: "screening".into(), + params: serde_json::json!({ "limit": 5 }), + }] + }; + assert!( + store + .seed_assignment("0xnew", copy(), &change("t1")) + .await + .unwrap() + ); + assert!( + !store + .seed_assignment("0xnew", copy(), &change("t2")) + .await + .unwrap(), + "an assignment already exists" + ); + store + .set_assignment("0xnew", Vec::new(), &change("t3")) + .await + .unwrap(); + assert!( + !store + .seed_assignment("0xnew", copy(), &change("t4")) + .await + .unwrap(), + "an assignment an operator emptied is not refilled" + ); + assert!(store.account_params("0xnew").await.unwrap().is_empty()); + } + #[tokio::test] async fn tables_survive_a_restart() { let dir = std::env::temp_dir().join(format!("modules_{:016x}", rand::random::())); diff --git a/crates/server/src/modules/testing.rs b/crates/server/src/modules/testing.rs index ddbca8a7..75c53a13 100644 --- a/crates/server/src/modules/testing.rs +++ b/crates/server/src/modules/testing.rs @@ -314,6 +314,17 @@ impl super::store::ModuleStore for RacingStore { self.inner.all_account_params().await } + async fn seed_assignment( + &self, + account_id: &str, + modules: Vec, + change: &super::store::Change<'_>, + ) -> Result { + self.inner + .seed_assignment(account_id, modules, change) + .await + } + async fn set_layer( &self, account_id: &str, diff --git a/crates/server/src/services/configure_account.rs b/crates/server/src/services/configure_account.rs index cd0a5cc6..1d63eb92 100644 --- a/crates/server/src/services/configure_account.rs +++ b/crates/server/src/services/configure_account.rs @@ -218,12 +218,19 @@ pub async fn configure_account( (head, signer_commitment) }; - approve_registration( + // A new account, or a claim whose account never got its default modules, is evaluated + // with them and receives copies of them below. + let first_registration = match &existing { + None => true, + Some(_) => unfinished_claim && !has_assignment(state, ¶ms.account_id).await?, + }; + let default_copies = approve_registration( state, ¶ms, &signer_commitment, &head, existing.is_some() && !unfinished_claim, + first_registration, ) .await?; @@ -277,6 +284,7 @@ pub async fn configure_account( &signer_commitment, &head, has_stored_state(state, ¶ms.account_id).await, + false, ) .await?; Some(claimed) @@ -284,6 +292,29 @@ pub async fn configure_account( existing }; + // The account is now claimed by this request: copy the default modules it was evaluated + // with. Only an account without any assignment history receives them, so an operator's + // earlier write wins, and a crash before this point is repaired by the retry, which finds + // an unfinished claim with no history and copies again. + if (created || first_registration && existing.is_some()) + && !default_copies.is_empty() + && let Some(modules) = state.modules.as_deref() + { + modules + .store() + .seed_assignment( + ¶ms.account_id.to_ascii_lowercase(), + default_copies, + &crate::modules::store::Change { + operator: "catalog", + reason: "default modules copied at registration", + at: now.clone(), + }, + ) + .await + .map_err(GuardianError::StorageError)?; + } + // The replay-state row has an FK to account metadata, which the claim // above guarantees, so every configuration consumes its timestamp // before it writes any state. @@ -575,14 +606,19 @@ async fn approve_registration( signer_commitment: &str, head: &StateHead, stored: bool, -) -> Result<()> { - let plan = match state.modules.as_deref() { - Some(modules) => { + first_registration: bool, +) -> Result> { + let (plan, default_copies) = match state.modules.as_deref() { + Some(modules) if first_registration => { + modules.plan_first_registration(¶ms.account_id).await? + } + Some(modules) => ( modules .plan(HookName::BeforeAccountRegistered, ¶ms.account_id) - .await? - } - None => None, + .await?, + Vec::new(), + ), + None => (None, Vec::new()), }; if let Some(plan) = plan { let stored_state = if stored { @@ -622,7 +658,21 @@ async fn approve_registration( }) .await?; } - Ok(()) + Ok(default_copies) +} + +/// Whether the account already holds module assignments. +async fn has_assignment(state: &AppState, account_id: &str) -> Result { + let Some(modules) = state.modules.as_deref() else { + return Ok(false); + }; + Ok(modules + .store() + .account_params(&account_id.to_ascii_lowercase()) + .await + .map_err(GuardianError::StorageError)? + .iter() + .any(|row| row.kind == crate::modules::store::ParamsKind::Assignment)) } /// Whether the account has a stored state. A failed read counts as stored, so it can never make @@ -3474,14 +3524,29 @@ mod tests { storage: MockStorageBackend, metadata: MockMetadataStore, module: Arc, + modules: Arc, } async fn configure_with_module( existing: impl FnOnce(String) -> Option, module: Arc, ) -> ModuleRun { - use crate::modules::catalog::OnError; - use crate::modules::testing::{instance, pipeline}; + let signers = crate::modules::testing::instance( + "signers", + &[HookName::BeforeAccountRegistered], + crate::modules::catalog::OnError::Deny, + module.clone(), + ); + configure_with_modules(existing, vec![signers], module).await + } + + /// `module` is the stub the caller inspects; `instances` is the whole catalog. + async fn configure_with_modules( + existing: impl FnOnce(String) -> Option, + instances: Vec, + module: Arc, + ) -> ModuleRun { + use crate::modules::testing::pipeline; use crate::testing::helpers::generate_falcon_signature; let account_id_hex = "0x1d1d1d1c1d1d1d011d1d1d1d1d1d1d"; @@ -3517,12 +3582,8 @@ mod tests { .with_set(Ok(())); let mut state = create_test_app_state(network_client, storage.clone(), metadata.clone()).await; - state.modules = Some(pipeline(vec![instance( - "signers", - &[HookName::BeforeAccountRegistered], - OnError::Deny, - module.clone(), - )])); + let modules = pipeline(instances); + state.modules = Some(modules.clone()); let result = configure_account( &state, @@ -3542,6 +3603,7 @@ mod tests { storage, metadata, module, + modules, } } @@ -3749,4 +3811,113 @@ mod tests { assert!(storage.get_submit_state_calls().is_empty()); assert!(metadata.get_set_calls().is_empty()); } + + fn default_instance( + id: &str, + hooks: &[HookName], + module: Arc, + ) -> crate::modules::registry::Instance { + let mut instance = crate::modules::testing::instance_with_params( + id, + hooks, + module, + serde_json::json!({ "limit": 5 }), + ); + instance.config.scope = crate::modules::catalog::Scope::Default; + instance + } + + async fn assignment_of( + modules: &crate::modules::ModulePipeline, + ) -> Vec<(String, serde_json::Value)> { + modules + .store() + .account_params("0x1d1d1d1c1d1d1d011d1d1d1d1d1d1d") + .await + .unwrap() + .into_iter() + .filter(|row| row.kind == crate::modules::store::ParamsKind::Assignment) + .map(|row| (row.module_id, row.params)) + .collect() + } + + #[tokio::test] + async fn a_new_account_is_judged_by_default_modules_and_receives_copies_of_them() { + let module = crate::modules::testing::StubModule::allowing(); + let elsewhere = crate::modules::testing::StubModule::allowing(); + let run = configure_with_modules( + |_| None, + vec![ + default_instance( + "screening", + &[HookName::BeforeAccountRegistered], + module.clone(), + ), + default_instance( + "caps", + &[HookName::BeforeTransactionApproved], + elsewhere.clone(), + ), + ], + module.clone(), + ) + .await; + assert!(run.result.is_ok(), "{:?}", run.result); + assert_eq!( + module.calls(), + 1, + "a default instance judges the registration" + ); + assert_eq!(elsewhere.calls(), 0, "one on other hooks is not called"); + assert_eq!( + assignment_of(&run.modules).await, + vec![ + ("screening".to_string(), serde_json::json!({ "limit": 5 })), + ("caps".to_string(), serde_json::json!({ "limit": 5 })), + ], + "every enabled default is copied with the params evaluated" + ); + } + + #[tokio::test] + async fn a_refused_registration_receives_no_default_copies() { + let module = crate::modules::testing::StubModule::denying("signer_not_allowed"); + let run = configure_with_modules( + |_| None, + vec![default_instance( + "screening", + &[HookName::BeforeAccountRegistered], + module.clone(), + )], + module, + ) + .await; + assert!(matches!( + run.result, + Err(GuardianError::ModuleDenied { .. }) + )); + assert!(assignment_of(&run.modules).await.is_empty()); + } + + #[tokio::test] + async fn a_reregistering_account_keeps_its_assignment_and_gets_no_defaults() { + let module = crate::modules::testing::StubModule::allowing(); + let run = configure_with_modules( + existing_account(false, false), + vec![default_instance( + "screening", + &[HookName::BeforeAccountRegistered], + module.clone(), + )], + module.clone(), + ) + .await; + assert!(run.result.is_ok(), "{:?}", run.result); + assert_eq!( + module.calls(), + 0, + "defaults apply only to accounts that never had them" + ); + assert!(assignment_of(&run.modules).await.is_empty()); + } } diff --git a/docs/rfcs/0002-guardian-modules.md b/docs/rfcs/0002-guardian-modules.md index ce439448..1facf0e1 100644 --- a/docs/rfcs/0002-guardian-modules.md +++ b/docs/rfcs/0002-guardian-modules.md @@ -7,7 +7,7 @@ | **Feature** | [#251](https://github.com/OpenZeppelin/guardian/issues/251) ("Modularization: middleware architecture and pluggable modules"); first consumer [#182](https://github.com/OpenZeppelin/guardian/issues/182) (policy evaluation). [#252](https://github.com/OpenZeppelin/guardian/issues/252) (x402 facilitator) is a later consumer: its payment-policy half (caps, allowlists, replay) fits `before_transaction_approved` and `after_transaction_committed`, its facilitator half (`/verify`, `/settle`, a flow that starts and waits) does not fit allow/deny and is future work (section 7) | | **Audience** | Operators, module authors, integrators, and anyone reviewing the Guardian trust model | | **Working artifacts** | [`speckit/features/251-guardian-modules/`](../../speckit/features/251-guardian-modules/spec.md): the specification, written alongside this RFC; plan and tasks follow the prototype | -| **Revision** | 28 (2026-11-09): protocol version 1 frozen at `e4efd839`; changes in Appendix C | +| **Revision** | 29 (2026-11-09): `default` copies written right after the claim on both backends (section 2.3); changes in Appendix C | | **Review sought** | Comments on the design and the M2a scope remain open until M2a ships, when `guardian.module.v1` freezes (section 7) | | **Code baseline** | `main` at `ca503704`; execution-path citations read on `254-execution-impl` at `29c722b4` (PR #510, since merged to `main` as `1100f3a4`) and kept as dated evidence. Miden pins: protocol and standards 0.17.1. Appendices B and C cite the baselines of their revisions. Prototype findings (2026-10-13 to 2026-10-15) in `speckit/features/251-guardian-modules/research.md` | @@ -355,7 +355,7 @@ Account self-service configuration is out of scope for this revision (section 7) **Registration.** `configure_account` serves first configurations and existing accounts alike, including re-onboarding after a release. Since #558 a first configuration claims the account by creating its metadata row (`configure_account.rs:198-220`), then consumes the request's replay timestamp (`:237`), then stores the initial state (`:261`); a claim whose state was never stored is detected on the next request as an unfinished claim (`:78-96`) and treated as a first configuration again (`:98`) **[READ]**. The hook follows the same three cases: -- **New account** (`existing.is_none()`): there is no assignment yet, so `scope = all` and `scope = default` instances run, each only if it declares this hook, `default` ones with their current global params because they are about to apply to the account. `before` is absent. On success the `default` instances are copied into the account's assignment with exactly the params the evaluation used, read in the same consistent snapshot (section 2.2, "Storage"); a global params write that lands between the evaluation and the claim applies to later accounts only. On Postgres the copy is written in the same transaction as the claim. On the filesystem backend, which is development only, the claim and the module state are separate files, so the copy is written first, as one atomic replace of the module state, replacing any copy an earlier attempt left for the same account id: until the claim exists no operator can have edited it (the operator API answers `account_not_found`), so the copy that wins is the one from the evaluation of the request that claims the account, or, if two first configurations race, from the last one to write before the claim. A copy left by an attempt that never claims stays in the module state, unused, since nothing evaluates an account that does not exist. Because `default` instances run here, a down fail-closed `default` instance blocks new registrations. +- **New account** (`existing.is_none()`): there is no assignment yet, so `scope = all` and `scope = default` instances run, each only if it declares this hook, `default` ones with their current global params because they are about to apply to the account. `before` is absent. Once the request has claimed the account, every enabled `default` instance is copied into the account's assignment with exactly the params the evaluation used, read in the same consistent snapshot (section 2.2, "Storage"); a global params write that lands between the evaluation and the copy applies to later accounts only. The copy is written right after the claim and before the replay timestamp is consumed, and only if the account has no assignment and no assignment history, under the module state lock, so an operator write that reached the new account first wins and is never overwritten. A request that loses the claim copies nothing. A crash between the claim and the copy leaves an unfinished claim with no assignment history, whose retry repeats the copy (below), so the claim and the copy need not share one transaction and the rule is the same on both backends. Because `default` instances run here, a down fail-closed `default` instance blocks new registrations. - **Unfinished claim** (`existing.is_some()` and no stored state): the claim normally holds the copied defaults, so `scope = all` instances and the stored assignment run, with `before` absent. The copy is repeated only if the account has no assignment history at all, which happens only when a crash fell between the claim and the copy on a backend where they are separate writes; an assignment an operator later emptied keeps its history and is not refilled. - **Existing account**: the stored assignment is preserved and never replaced by catalog defaults, and `scope = all` instances plus the stored assignment run, with `before` read from the stored state (section 3.2). Otherwise any cosigner, who can call `/configure` with their own key, could wipe a tighter policy an operator assigned. - **Lost claim.** Two first configurations can race; the one that loses the claim continues as a reconfiguration of the winner's account (`configure_account.rs:221-232`, test `losing_first_configuration_from_another_signer_reconfigures_the_winners_account`) **[READ]**. Its earlier pass ran against catalog defaults, not the winner's assignment, so the pipeline runs again as for an unfinished claim or an existing account, whichever the winner's account now is, before the loser consumes anything. @@ -1206,6 +1206,7 @@ None. Questions resolved in earlier revisions are kept below with their answers. | Revision | Date | Changes | |---|---|---| +| 29 | 2026-11-09 | M2a implementation of `scope = default`: the copy is written right after the claim, only into an account with no assignment and no assignment history, under the module state lock, instead of in the claim's transaction on Postgres and before the claim on the filesystem; a crash in between is repaired by the unfinished-claim retry, so both backends follow one rule and no transaction spans the metadata and module stores (section 2.3). No protocol change | | 28 | 2026-11-09 | protocol version 1 frozen: the freeze criteria of section 7 met at `e4efd839` on `251-modules-m2a`, with tests; the proto copies say so. No design change | | 27 | 2026-11-09 | `proposer_session` removed from `TransactionSubject`, `PendingTransaction` and `CommitEvent`, and `unverified_metadata` renumbered to 5 before the freeze: a session key cannot approve a proposal, so whether one created it adds nothing the threshold does not already require, and no catalog policy uses it; version 1 can add it later. Section 3.2 corrected for #580: `push_delta` and Guardian execution accept session credentials, so `submitter_session` can be true at the ack. Freeze criteria and the M2a list updated (section 7) | | 26 | 2026-11-09 | `main` (mixed-scheme accounts, #565) merged into the prototype. `AccountView.signer_schemes` (signer commitment to `falcon` or `ecdsa`), decoded per approver from state, and `auth_scheme` redefined as the signers' common scheme or `mixed`, because "one scheme per account" no longer holds (section 3.2). The execution path's refusals named as `GUARDIAN_EXECUTION_MODULE_DENIED` and `GUARDIAN_EXECUTION_MODULE_UNAVAILABLE` failure codes (section 4.1). The execution requester is carried to the ack, not stored on the reservation, since pre-boundary attempts are never resumed (sections 3.2 and 7) | diff --git a/speckit/features/251-guardian-modules/contracts/operator-modules-api.md b/speckit/features/251-guardian-modules/contracts/operator-modules-api.md index 3a1a6e5f..87317b68 100644 --- a/speckit/features/251-guardian-modules/contracts/operator-modules-api.md +++ b/speckit/features/251-guardian-modules/contracts/operator-modules-api.md @@ -34,8 +34,7 @@ ModuleInstanceView { kind: string, scope: "all" | "default" | "assigned", hooks: string[], - declared: bool, // false: a stored flag the catalog no longer declares (M2a, not in the prototype) - catalog_enabled?: bool, // seed value from the file; absent when declared = false + catalog_enabled: bool, // seed value from the file enabled: bool, // runtime flag enabled_drift: bool, // catalog_enabled != enabled operator_can_disable: bool, @@ -47,15 +46,16 @@ ModuleInstanceView { description?: string, client_reason: "full" | "generic", dry_run: bool, - circuit: "closed" | "open" | "half_open" // on the replica that answered (M2a, not in the prototype) + circuit: "closed" | "open" | "half_open" // on the replica that answered } -ModuleCatalogView { catalog_hash: string, params_version: number, modules: ModuleInstanceView[] } +UndeclaredInstanceView { module_id: string, enabled: bool, params: object } // stored, no longer in the catalog; never evaluated +ModuleCatalogView { catalog_hash: string, params_version: number, modules: ModuleInstanceView[], undeclared: UndeclaredInstanceView[] } AccountModuleEntry { module_id: string, scope: "all" | "default" | "assigned", enabled: bool, - orphaned: bool, // stored entry naming an instance the catalog no longer declares (M2a, not in the prototype) + orphaned: bool, // stored entry naming an instance the catalog no longer declares; skipped at evaluation global_params?: object, // scope = all: the instance's global params account_layer?: object, // scope = all: this account's layer, when set params?: object // default / assigned: this account's own params @@ -88,6 +88,6 @@ All errors use the `{ code, message, meta }` envelope. Contract tests in `crates/server` and `packages/guardian-operator-client` pin every row. -## Prototype status (#554) +## Implementation status (M2a) -All M2a routes exist and match the shapes above, except the fields marked "not in the prototype". Not built yet: `resync` (M2b), the budget check on `PUT`, the operator client, and the OpenAPI entries. +All M2a routes exist with the shapes above. `PUT` writes are refused when the account's worst case could exceed the evaluation budget. Not built yet: `resync` (M2b), the operator client methods and the OpenAPI entries for these routes (tasks T044, T045). diff --git a/speckit/features/251-guardian-modules/tasks.md b/speckit/features/251-guardian-modules/tasks.md index 7dbb2747..f9a15c07 100644 --- a/speckit/features/251-guardian-modules/tasks.md +++ b/speckit/features/251-guardian-modules/tasks.md @@ -145,15 +145,15 @@ ### Tests for User Story 5 -- [ ] T037 [P] [US5] `default` copy tests in `crates/server/src/services/configure_account.rs`: the copy carries the evaluated params and is written with the claim on Postgres; on the filesystem it replaces an earlier unclaimed attempt's copy; an unfinished claim with no assignment history repeats it, one an operator emptied does not +- [X] T037 [P] [US5] `default` copy tests in `crates/server/src/services/configure_account.rs`: the copy carries the evaluated params and is written with the claim on Postgres; on the filesystem it replaces an earlier unclaimed attempt's copy; an unfinished claim with no assignment history repeats it, one an operator emptied does not - [ ] T038 [P] [US5] Operator client tests in `packages/guardian-operator-client/src/` for every module route, including permission errors for `modules:disable` holders ### Implementation for User Story 5 -- [ ] T039 [US5] Add the `default` scope, which the prototype never built (`Scope` in `crates/server/src/modules/catalog.rs` has only `all` and `assigned`): parse `scope = "default"`, plan it as an account-owned assignment like `assigned`, count it in `ModulePipeline::worst_case` and the startup budget check, and allow removing it per account; then write `default` instances into the assignment together with the claim in `crates/server/src/services/configure_account.rs` and `crates/server/src/modules/postgres_store.rs` (same transaction as `metadata.create`), with the evaluated params from the same snapshot (P0 T085) -- [ ] T040 [US5] Filesystem registration copy in `crates/server/src/modules/store.rs`: written before the claim as one atomic replace, replacing a copy an earlier unclaimed attempt left; an unfinished claim with no assignment history repeats it (P0 T094) +- [X] T039 [US5] Add the `default` scope, which the prototype never built (`Scope` in `crates/server/src/modules/catalog.rs` has only `all` and `assigned`): parse `scope = "default"`, plan it as an account-owned assignment like `assigned`, count it in `ModulePipeline::worst_case` and the startup budget check, and allow removing it per account; then write `default` instances into the assignment together with the claim in `crates/server/src/services/configure_account.rs` and `crates/server/src/modules/postgres_store.rs` (same transaction as `metadata.create`), with the evaluated params from the same snapshot (P0 T085) +- [X] T040 [US5] Superseded by the T039 design (RFC revision 29): the copy is written after the claim on both backends through `ModuleStore::seed_assignment`, only into an account with no assignment and no history; the unfinished-claim retry repeats a copy a crash interrupted (P0 T094) - [ ] T041 [US5] `params_drift` against `seeded_params`, `GUARDIAN_MODULE_PARAMS_MAX_BYTES` on every params write, and paginated history (`?before=&limit=`) in `crates/server/src/modules/admin.rs`, `store.rs` and `postgres_store.rs` (P0 T090) -- [ ] T042 [US5] `declared` (stored flag the catalog no longer declares) and `orphaned` (assignment naming a removed instance) in the views of `crates/server/src/modules/admin.rs`; orphaned entries are skipped at evaluation and reported, active again when the instance returns +- [X] T042 [US5] `orphaned` on account view rows naming an instance the catalog no longer declares (skipped at evaluation, counted at startup) and an `undeclared` list of such stored instances in `GET /dashboard/modules` (contract revised from a per-instance `declared` flag) in `crates/server/src/modules/admin.rs` - [ ] T043 [US5] Migrate account layers and assignments that a module normalizes when validating params, at startup and before enabling, with a compare-and-set against the read value, in `crates/server/src/modules/registry.rs` and both stores (P0 T073) - [ ] T044 [US5] Module routes in `packages/guardian-operator-client/src/` (list, account modules read and replace, global params, account layer set and delete, history, enable, disable) with types matching `speckit/features/251-guardian-modules/contracts/operator-modules-api.md`, and its README - [ ] T045 [US5] OpenAPI entries for the `/dashboard/modules` and account module routes (`utoipa` annotations in `crates/server/src/api/dashboard_modules.rs`), regenerated into `docs/openapi-dashboard.json` From 4cf51c0d15545ee9faa37353f8f2e4e9a7384819 Mon Sep 17 00:00:00 2001 From: Zeljko Date: Mon, 9 Nov 2026 11:21:44 +0100 Subject: [PATCH 029/105] feat(modules): params size cap, drift against the seeded params, paginated history (#251) Every operator params write is refused with invalid_input when the params exceed GUARDIAN_MODULE_PARAMS_MAX_BYTES (default 64 KiB, compact JSON with sorted keys), before the module is called, and a catalog seed over it refuses startup. params_drift and the drift metric compare the catalog file with the params seeded from it, so operator writes and module migrations no longer read as drift. GET /dashboard/modules/{id}/params/history returns newest first, paginated with ?before=&limit= (default 100, at most 1,000). --- crates/server/src/api/dashboard_modules.rs | 11 +- crates/server/src/modules/admin.rs | 131 +++++++++++++++--- crates/server/src/modules/limits.rs | 21 +++ crates/server/src/modules/pipeline.rs | 18 ++- crates/server/src/modules/postgres_store.rs | 17 ++- docs/CONFIGURATION.md | 1 + .../features/251-guardian-modules/tasks.md | 2 +- 7 files changed, 176 insertions(+), 25 deletions(-) diff --git a/crates/server/src/api/dashboard_modules.rs b/crates/server/src/api/dashboard_modules.rs index 91fd8cf6..df1d8e79 100644 --- a/crates/server/src/api/dashboard_modules.rs +++ b/crates/server/src/api/dashboard_modules.rs @@ -55,11 +55,20 @@ pub async fn account_modules( admin::account_view(&state, &account_id).await.map(Json) } +#[derive(Debug, Deserialize)] +pub struct HistoryQuery { + before: Option, + limit: Option, +} + pub async fn params_history( State(state): State, Path(module_id): Path, + axum::extract::Query(query): axum::extract::Query, ) -> Result> { - admin::history(&state, &module_id).await.map(Json) + admin::history(&state, &module_id, query.before, query.limit) + .await + .map(Json) } pub async fn set_global_params( diff --git a/crates/server/src/modules/admin.rs b/crates/server/src/modules/admin.rs index f5b75a94..365a5d87 100644 --- a/crates/server/src/modules/admin.rs +++ b/crates/server/src/modules/admin.rs @@ -112,12 +112,20 @@ fn require_reason(reason: &str) -> Result<()> { /// Validates operator-supplied params and returns what to store: the module's normalized form /// when it sent one. -async fn validated(instance: &Instance, params: &serde_json::Value) -> Result { +async fn validated( + pipeline: &ModulePipeline, + instance: &Instance, + params: &serde_json::Value, +) -> Result { if !params.is_object() { return Err(GuardianError::InvalidInput( "params must be a JSON object".into(), )); } + pipeline + .limits() + .check_params_size(params) + .map_err(|e| GuardianError::InvalidInput(format!("module {}: {e}", instance.config.id)))?; if contains_secret_reference(params) { return Err(GuardianError::InvalidInput( "secret references cannot be set through the operator API".into(), @@ -191,6 +199,14 @@ async fn instance_view( ) -> Result { let params = pipeline.global_params(instance).await?; let enabled = pipeline.enabled(instance).await?; + let seeded = pipeline + .store() + .instances() + .await + .map_err(GuardianError::StorageError)? + .into_iter() + .find(|row| row.module_id == instance.config.id) + .map(|row| row.seeded_params); Ok(ModuleInstanceView { module_id: instance.config.id.clone(), kind: instance.config.kind.clone(), @@ -205,7 +221,7 @@ async fn instance_view( catalog_enabled: instance.config.catalog_enabled, enabled_drift: enabled != instance.config.catalog_enabled, operator_can_disable: instance.config.operator_can_disable, - params_drift: params != instance.config.params, + params_drift: seeded.is_some_and(|seeded| seeded != instance.config.params), params, file_managed_params: instance.config.file_managed_params, build: instance.build.clone(), @@ -309,16 +325,39 @@ pub async fn account_view(state: &AppState, account_id: &str) -> Result Result { +const HISTORY_PAGE_DEFAULT: usize = 100; +const HISTORY_PAGE_MAX: usize = 1_000; + +/// The instance's params changes, newest first: those with a version below `before` when set, +/// at most `limit` (default 100, at most 1,000). +pub async fn history( + state: &AppState, + module_id: &str, + before: Option, + limit: Option, +) -> Result { let pipeline = pipeline(state)?; instance(pipeline, module_id)?; + let limit = limit.unwrap_or(HISTORY_PAGE_DEFAULT); + if limit == 0 || limit > HISTORY_PAGE_MAX { + return Err(GuardianError::InvalidInput(format!( + "limit must be between 1 and {HISTORY_PAGE_MAX}" + ))); + } + let mut entries = pipeline + .store() + .history(module_id) + .await + .map_err(GuardianError::StorageError)?; + entries.reverse(); + let entries = entries + .into_iter() + .filter(|entry| before.is_none_or(|before| entry.version < before)) + .take(limit) + .collect(); Ok(ParamsHistoryView { module_id: module_id.to_string(), - entries: pipeline - .store() - .history(module_id) - .await - .map_err(GuardianError::StorageError)?, + entries, }) } @@ -438,7 +477,7 @@ pub async fn set_global( "module {module_id}: params with secret references are managed in the catalog file" ))); } - let params = validated(instance, ¶ms).await?; + let params = validated(pipeline, instance, ¶ms).await?; pipeline .store() .set_global(module_id, params, &change(state, operator, reason)) @@ -475,7 +514,7 @@ pub async fn set_layer( ))); } let params = match params { - Some(params) => Some(validated(instance, ¶ms).await?), + Some(params) => Some(validated(pipeline, instance, ¶ms).await?), None => None, }; let mut rows = pipeline @@ -564,7 +603,7 @@ pub async fn set_assignment( } to_store.push(Assigned { module_id: assigned.module_id.clone(), - params: validated(instance, &assigned.params).await?, + params: validated(pipeline, instance, &assigned.params).await?, }); } let mut rows = pipeline @@ -910,10 +949,67 @@ mod tests { Some(json!({ "recipient_denylist": ["0xccc"] })) ); - let history = history(&state, "blocklist").await.unwrap().entries; + let history = history(&state, "blocklist", None, None) + .await + .unwrap() + .entries; assert_eq!(history.len(), 2); - assert_eq!(history[0].reason, "OP-90"); - assert_eq!(history[1].account_id.as_deref(), Some(ACCOUNT)); + assert_eq!( + history[0].account_id.as_deref(), + Some(ACCOUNT), + "newest first" + ); + assert_eq!(history[1].reason, "OP-90"); + } + + #[tokio::test] + async fn history_pages_newest_first_by_version() { + let state = state(); + for n in 0..3 { + set_global( + &state, + &operator(), + "blocklist", + json!({ "recipient_denylist": [format!("0x{n}")] }), + &format!("OP-{n}"), + None, + ) + .await + .unwrap(); + } + let first = history(&state, "blocklist", None, Some(2)) + .await + .unwrap() + .entries; + assert_eq!( + first + .iter() + .map(|entry| entry.reason.as_str()) + .collect::>(), + ["OP-2", "OP-1"] + ); + let next = history(&state, "blocklist", Some(first[1].version), Some(2)) + .await + .unwrap() + .entries; + assert_eq!( + next.iter() + .map(|entry| entry.reason.as_str()) + .collect::>(), + ["OP-0"] + ); + assert!(history(&state, "blocklist", None, Some(0)).await.is_err()); + } + + #[tokio::test] + async fn params_over_the_size_cap_are_refused_before_the_module_is_called() { + let state = state(); + let huge = json!({ "recipient_denylist": vec!["0x".repeat(40); 4_000] }); + let refused = set_global(&state, &operator(), "blocklist", huge, "OP-9", None).await; + assert!( + matches!(&refused, Err(GuardianError::InvalidInput(message)) if message.contains("GUARDIAN_MODULE_PARAMS_MAX_BYTES")), + "{refused:?}" + ); } #[tokio::test] @@ -1017,8 +1113,11 @@ mod tests { .await .unwrap(); assert!(view.enabled); - let history = history(&state, "blocklist").await.unwrap().entries; - assert_eq!(history.last().unwrap().new, json!({ "enabled": true })); + let history = history(&state, "blocklist", None, None) + .await + .unwrap() + .entries; + assert_eq!(history[0].new, json!({ "enabled": true }), "newest first"); } #[tokio::test] diff --git a/crates/server/src/modules/limits.rs b/crates/server/src/modules/limits.rs index 34e4278f..caba96e6 100644 --- a/crates/server/src/modules/limits.rs +++ b/crates/server/src/modules/limits.rs @@ -7,6 +7,7 @@ pub const BUDGET_ENV: &str = "GUARDIAN_MODULE_EVALUATION_BUDGET_MS"; pub const REQUEST_MAX_BYTES_ENV: &str = "GUARDIAN_MODULE_REQUEST_MAX_BYTES"; pub const BREAKER_FAILURES_ENV: &str = "GUARDIAN_MODULE_BREAKER_FAILURES"; pub const PROBE_INTERVAL_ENV: &str = "GUARDIAN_MODULE_PROBE_INTERVAL_MS"; +pub const PARAMS_MAX_BYTES_ENV: &str = "GUARDIAN_MODULE_PARAMS_MAX_BYTES"; #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub struct Limits { @@ -18,6 +19,22 @@ pub struct Limits { pub breaker_failures: u32, /// Interval of the `Describe` health probe per instance. pub probe_interval: Duration, + /// Largest params value one write may store, as compact JSON with sorted keys. + pub params_max_bytes: usize, +} + +impl Limits { + /// Refuses `params` larger than [`Self::params_max_bytes`]. + pub fn check_params_size(&self, params: &serde_json::Value) -> Result<(), String> { + let size = serde_json::to_vec(params).map_or(usize::MAX, |bytes| bytes.len()); + if size > self.params_max_bytes { + return Err(format!( + "params of {size} bytes exceed {PARAMS_MAX_BYTES_ENV} ({} bytes)", + self.params_max_bytes + )); + } + Ok(()) + } } impl Default for Limits { @@ -27,6 +44,7 @@ impl Default for Limits { request_max_bytes: 2 * 1024 * 1024, breaker_failures: 5, probe_interval: Duration::from_millis(5_000), + params_max_bytes: 64 * 1024, } } } @@ -54,6 +72,9 @@ impl Limits { probe_interval: positive(&var, PROBE_INTERVAL_ENV)? .map(Duration::from_millis) .unwrap_or(defaults.probe_interval), + params_max_bytes: positive(&var, PARAMS_MAX_BYTES_ENV)? + .map(|bytes| usize::try_from(bytes).unwrap_or(usize::MAX)) + .unwrap_or(defaults.params_max_bytes), }) } } diff --git a/crates/server/src/modules/pipeline.rs b/crates/server/src/modules/pipeline.rs index 4738d153..503043b1 100644 --- a/crates/server/src/modules/pipeline.rs +++ b/crates/server/src/modules/pipeline.rs @@ -122,9 +122,17 @@ impl ModulePipeline { now: String, limits: Limits, ) -> Result { - let stored: HashMap = store - .instances() - .await? + for config in &catalog.instances { + limits + .check_params_size(&config.params) + .map_err(|e| format!("module {}: catalog {e}", config.id))?; + } + let rows = store.instances().await?; + let seeded: HashMap = rows + .iter() + .map(|row| (row.module_id.clone(), row.seeded_params.clone())) + .collect(); + let stored: HashMap = rows .into_iter() .map(|row| (row.module_id, (row.global_params, row.enabled))) .collect(); @@ -139,7 +147,9 @@ impl ModulePipeline { super::metrics::config_drift( &config.id, *enabled != config.catalog_enabled - || (!config.file_managed_params && *params != config.params), + || seeded + .get(&config.id) + .is_some_and(|seeded| *seeded != config.params), ); if *enabled != config.catalog_enabled { tracing::warn!(module = %config.id, enabled, "Catalog `enabled` differs from the stored runtime flag; the stored flag applies"); diff --git a/crates/server/src/modules/postgres_store.rs b/crates/server/src/modules/postgres_store.rs index 78403234..c918f7d5 100644 --- a/crates/server/src/modules/postgres_store.rs +++ b/crates/server/src/modules/postgres_store.rs @@ -821,10 +821,18 @@ mod tests { }] }; let t0 = "2026-11-09T00:00:00Z"; - assert!(store.seed_assignment(&account, copy(), &change(t0)).await.unwrap()); + assert!( + store + .seed_assignment(&account, copy(), &change(t0)) + .await + .unwrap() + ); let before = store.version().await.unwrap(); assert!( - !store.seed_assignment(&account, copy(), &change(t0)).await.unwrap(), + !store + .seed_assignment(&account, copy(), &change(t0)) + .await + .unwrap(), "an existing assignment is kept" ); assert_eq!( @@ -837,7 +845,10 @@ mod tests { .await .unwrap(); assert!( - !store.seed_assignment(&account, copy(), &change(t0)).await.unwrap(), + !store + .seed_assignment(&account, copy(), &change(t0)) + .await + .unwrap(), "an assignment an operator emptied is not refilled" ); assert!(store.account_params(&account).await.unwrap().is_empty()); diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md index 0ef4da05..fa08432a 100644 --- a/docs/CONFIGURATION.md +++ b/docs/CONFIGURATION.md @@ -388,6 +388,7 @@ modules guide](./guides/policy-modules/README.md). | `GUARDIAN_MODULE_REQUEST_MAX_BYTES` | `2097152` (2 MiB) | Largest encoded request sent to a module. A larger one is a module failure and is not sent; its `on_error` applies. | | `GUARDIAN_MODULE_BREAKER_FAILURES` | `5` | Consecutive failures (timeouts, transport errors, malformed decisions) that open an instance's circuit breaker on a replica. While open the module is not called and its `on_error` applies at once. A deny is an answer and resets the count. | | `GUARDIAN_MODULE_PROBE_INTERVAL_MS` | `5000` | Interval of the `Describe` health probe of every enabled instance. A successful probe moves an open breaker to half-open, where the next call decides; the result is `guardian_module_up`. | +| `GUARDIAN_MODULE_PARAMS_MAX_BYTES` | `65536` (64 KiB) | Largest params value one write may store (global params, an account layer or an assignment entry), measured as compact JSON with sorted keys. A larger write is refused with `invalid_input` before the module is called, and a larger catalog seed refuses startup, so no params value can push every request for an account over `GUARDIAN_MODULE_REQUEST_MAX_BYTES`. | ## Runtime — EVM (feature-gated) diff --git a/speckit/features/251-guardian-modules/tasks.md b/speckit/features/251-guardian-modules/tasks.md index f9a15c07..269e6e5d 100644 --- a/speckit/features/251-guardian-modules/tasks.md +++ b/speckit/features/251-guardian-modules/tasks.md @@ -152,7 +152,7 @@ - [X] T039 [US5] Add the `default` scope, which the prototype never built (`Scope` in `crates/server/src/modules/catalog.rs` has only `all` and `assigned`): parse `scope = "default"`, plan it as an account-owned assignment like `assigned`, count it in `ModulePipeline::worst_case` and the startup budget check, and allow removing it per account; then write `default` instances into the assignment together with the claim in `crates/server/src/services/configure_account.rs` and `crates/server/src/modules/postgres_store.rs` (same transaction as `metadata.create`), with the evaluated params from the same snapshot (P0 T085) - [X] T040 [US5] Superseded by the T039 design (RFC revision 29): the copy is written after the claim on both backends through `ModuleStore::seed_assignment`, only into an account with no assignment and no history; the unfinished-claim retry repeats a copy a crash interrupted (P0 T094) -- [ ] T041 [US5] `params_drift` against `seeded_params`, `GUARDIAN_MODULE_PARAMS_MAX_BYTES` on every params write, and paginated history (`?before=&limit=`) in `crates/server/src/modules/admin.rs`, `store.rs` and `postgres_store.rs` (P0 T090) +- [X] T041 [US5] `params_drift` against `seeded_params`, `GUARDIAN_MODULE_PARAMS_MAX_BYTES` on every params write, and paginated history (`?before=&limit=`) in `crates/server/src/modules/admin.rs`, `store.rs` and `postgres_store.rs` (P0 T090) - [X] T042 [US5] `orphaned` on account view rows naming an instance the catalog no longer declares (skipped at evaluation, counted at startup) and an `undeclared` list of such stored instances in `GET /dashboard/modules` (contract revised from a per-instance `declared` flag) in `crates/server/src/modules/admin.rs` - [ ] T043 [US5] Migrate account layers and assignments that a module normalizes when validating params, at startup and before enabling, with a compare-and-set against the read value, in `crates/server/src/modules/registry.rs` and both stores (P0 T073) - [ ] T044 [US5] Module routes in `packages/guardian-operator-client/src/` (list, account modules read and replace, global params, account layer set and delete, history, enable, disable) with types matching `speckit/features/251-guardian-modules/contracts/operator-modules-api.md`, and its README From aceac2edefaaf267734636234669b8dcf8a9d10f Mon Sep 17 00:00:00 2001 From: Zeljko Date: Mon, 9 Nov 2026 11:24:12 +0100 Subject: [PATCH 030/105] docs(openapi): the policy module dashboard routes (#251) The nine /dashboard/modules and account module routes are annotated with their bodies, views, permissions and errors and appear in the dashboard and combined OpenAPI documents; the view, body and history types derive ToSchema. T043 is dropped: the RFC migrates account layers and assignments when they are next written. --- crates/server/src/api/dashboard_modules.rs | 139 +- crates/server/src/modules/admin.rs | 20 +- crates/server/src/modules/catalog.rs | 8 +- crates/server/src/modules/store.rs | 7 +- crates/server/src/openapi.rs | 9 + docs/openapi-dashboard.json | 1466 +++++++++++++++-- docs/openapi.json | 1407 ++++++++++++++-- .../features/251-guardian-modules/tasks.md | 4 +- 8 files changed, 2844 insertions(+), 216 deletions(-) diff --git a/crates/server/src/api/dashboard_modules.rs b/crates/server/src/api/dashboard_modules.rs index df1d8e79..0c399e5b 100644 --- a/crates/server/src/api/dashboard_modules.rs +++ b/crates/server/src/api/dashboard_modules.rs @@ -14,18 +14,19 @@ use crate::state::AppState; const BODY_LIMIT: usize = 256 * 1024; -#[derive(Debug, Deserialize)] +#[derive(Debug, Deserialize, utoipa::ToSchema)] pub struct ParamsBody { + #[schema(value_type = Object)] pub params: serde_json::Value, pub reason: String, } -#[derive(Debug, Deserialize)] +#[derive(Debug, Deserialize, utoipa::ToSchema)] pub struct ReasonBody { pub reason: String, } -#[derive(Debug, Deserialize)] +#[derive(Debug, Deserialize, utoipa::ToSchema)] pub struct AssignmentBody { pub modules: Vec, pub reason: String, @@ -44,10 +45,35 @@ async fn body( Ok((parsed, client_ip)) } +#[utoipa::path( + get, + path = "/dashboard/modules", + tag = "dashboard", + security(("operator_session" = [])), + responses( + (status = 200, description = "Module instances with their runtime state", body = ModuleCatalogView), + (status = 401, description = "No operator session", body = crate::openapi::ApiErrorResponse), + (status = 403, description = "Missing dashboard:read permission", body = crate::openapi::ApiErrorResponse), + (status = 404, description = "Account or module not found, or no modules configured", body = crate::openapi::ApiErrorResponse), + ) +)] pub async fn list_modules(State(state): State) -> Result> { admin::catalog_view(&state).await.map(Json) } +#[utoipa::path( + get, + path = "/dashboard/accounts/{account_id}/modules", + tag = "dashboard", + security(("operator_session" = [])), + params(("account_id" = String, Path, description = "Account identifier")), + responses( + (status = 200, description = "The account's effective module set, in evaluation order", body = AccountModulesView), + (status = 401, description = "No operator session", body = crate::openapi::ApiErrorResponse), + (status = 403, description = "Missing dashboard:read permission", body = crate::openapi::ApiErrorResponse), + (status = 404, description = "Account or module not found, or no modules configured", body = crate::openapi::ApiErrorResponse), + ) +)] pub async fn account_modules( State(state): State, Path(account_id): Path, @@ -55,12 +81,27 @@ pub async fn account_modules( admin::account_view(&state, &account_id).await.map(Json) } -#[derive(Debug, Deserialize)] +#[derive(Debug, Deserialize, utoipa::IntoParams)] +#[into_params(parameter_in = Query)] pub struct HistoryQuery { before: Option, limit: Option, } +#[utoipa::path( + get, + path = "/dashboard/modules/{module_id}/params/history", + tag = "dashboard", + security(("operator_session" = [])), + params(("module_id" = String, Path, description = "Module instance id"), HistoryQuery), + responses( + (status = 200, description = "Params changes, newest first", body = ParamsHistoryView), + (status = 400, description = "Invalid params, reason or assignment", body = crate::openapi::ApiErrorResponse), + (status = 401, description = "No operator session", body = crate::openapi::ApiErrorResponse), + (status = 403, description = "Missing dashboard:read permission", body = crate::openapi::ApiErrorResponse), + (status = 404, description = "Account or module not found, or no modules configured", body = crate::openapi::ApiErrorResponse), + ) +)] pub async fn params_history( State(state): State, Path(module_id): Path, @@ -71,6 +112,21 @@ pub async fn params_history( .map(Json) } +#[utoipa::path( + put, + path = "/dashboard/modules/{module_id}/params", + tag = "dashboard", + security(("operator_session" = [])), + params(("module_id" = String, Path, description = "Module instance id")), + request_body = ParamsBody, + responses( + (status = 200, description = "Global params stored", body = ModuleInstanceView), + (status = 400, description = "Invalid params, reason or assignment", body = crate::openapi::ApiErrorResponse), + (status = 401, description = "No operator session", body = crate::openapi::ApiErrorResponse), + (status = 403, description = "Missing policies:write_global permission", body = crate::openapi::ApiErrorResponse), + (status = 404, description = "Account or module not found, or no modules configured", body = crate::openapi::ApiErrorResponse), + ) +)] pub async fn set_global_params( State(state): State, Extension(operator): Extension, @@ -90,6 +146,21 @@ pub async fn set_global_params( .map(Json) } +#[utoipa::path( + post, + path = "/dashboard/modules/{module_id}/enable", + tag = "dashboard", + security(("operator_session" = [])), + params(("module_id" = String, Path, description = "Module instance id")), + request_body = ReasonBody, + responses( + (status = 200, description = "Instance enabled", body = ModuleInstanceView), + (status = 400, description = "Invalid params, reason or assignment", body = crate::openapi::ApiErrorResponse), + (status = 401, description = "No operator session", body = crate::openapi::ApiErrorResponse), + (status = 403, description = "Missing policies:write permission", body = crate::openapi::ApiErrorResponse), + (status = 404, description = "Account or module not found, or no modules configured", body = crate::openapi::ApiErrorResponse), + ) +)] pub async fn enable_module( State(state): State, Extension(operator): Extension, @@ -102,6 +173,21 @@ pub async fn enable_module( .map(Json) } +#[utoipa::path( + post, + path = "/dashboard/modules/{module_id}/disable", + tag = "dashboard", + security(("operator_session" = [])), + params(("module_id" = String, Path, description = "Module instance id")), + request_body = ReasonBody, + responses( + (status = 200, description = "Instance disabled", body = ModuleInstanceView), + (status = 400, description = "Invalid params, reason or assignment", body = crate::openapi::ApiErrorResponse), + (status = 401, description = "No operator session", body = crate::openapi::ApiErrorResponse), + (status = 403, description = "Missing policies:write or modules:disable permission", body = crate::openapi::ApiErrorResponse), + (status = 404, description = "Account or module not found, or no modules configured", body = crate::openapi::ApiErrorResponse), + ) +)] pub async fn disable_module( State(state): State, Extension(operator): Extension, @@ -114,6 +200,21 @@ pub async fn disable_module( .map(Json) } +#[utoipa::path( + put, + path = "/dashboard/accounts/{account_id}/modules/{module_id}/params", + tag = "dashboard", + security(("operator_session" = [])), + params(("account_id" = String, Path, description = "Account identifier"), ("module_id" = String, Path, description = "Module instance id")), + request_body = ParamsBody, + responses( + (status = 200, description = "Account layer stored", body = AccountModulesView), + (status = 400, description = "Invalid params, reason or assignment", body = crate::openapi::ApiErrorResponse), + (status = 401, description = "No operator session", body = crate::openapi::ApiErrorResponse), + (status = 403, description = "Missing policies:write permission", body = crate::openapi::ApiErrorResponse), + (status = 404, description = "Account or module not found, or no modules configured", body = crate::openapi::ApiErrorResponse), + ) +)] pub async fn set_account_layer( State(state): State, Extension(operator): Extension, @@ -134,6 +235,21 @@ pub async fn set_account_layer( .map(Json) } +#[utoipa::path( + delete, + path = "/dashboard/accounts/{account_id}/modules/{module_id}/params", + tag = "dashboard", + security(("operator_session" = [])), + params(("account_id" = String, Path, description = "Account identifier"), ("module_id" = String, Path, description = "Module instance id")), + request_body = ReasonBody, + responses( + (status = 200, description = "Account layer removed", body = AccountModulesView), + (status = 400, description = "Invalid params, reason or assignment", body = crate::openapi::ApiErrorResponse), + (status = 401, description = "No operator session", body = crate::openapi::ApiErrorResponse), + (status = 403, description = "Missing policies:write permission", body = crate::openapi::ApiErrorResponse), + (status = 404, description = "Account or module not found, or no modules configured", body = crate::openapi::ApiErrorResponse), + ) +)] pub async fn remove_account_layer( State(state): State, Extension(operator): Extension, @@ -154,6 +270,21 @@ pub async fn remove_account_layer( .map(Json) } +#[utoipa::path( + put, + path = "/dashboard/accounts/{account_id}/modules", + tag = "dashboard", + security(("operator_session" = [])), + params(("account_id" = String, Path, description = "Account identifier")), + request_body = AssignmentBody, + responses( + (status = 200, description = "Assignment stored", body = AccountModulesView), + (status = 400, description = "Invalid params, reason or assignment", body = crate::openapi::ApiErrorResponse), + (status = 401, description = "No operator session", body = crate::openapi::ApiErrorResponse), + (status = 403, description = "Missing policies:write permission", body = crate::openapi::ApiErrorResponse), + (status = 404, description = "Account or module not found, or no modules configured", body = crate::openapi::ApiErrorResponse), + ) +)] pub async fn set_assignment( State(state): State, Extension(operator): Extension, diff --git a/crates/server/src/modules/admin.rs b/crates/server/src/modules/admin.rs index 365a5d87..4f2b98ea 100644 --- a/crates/server/src/modules/admin.rs +++ b/crates/server/src/modules/admin.rs @@ -11,16 +11,18 @@ use crate::dashboard::AuthenticatedOperator; use crate::error::{GuardianError, Result}; use crate::state::AppState; -#[derive(Debug, Clone, Serialize)] +#[derive(Debug, Clone, Serialize, utoipa::ToSchema)] pub struct ModuleInstanceView { pub module_id: String, pub kind: String, + #[schema(value_type = String)] pub scope: &'static str, pub hooks: Vec, pub enabled: bool, pub catalog_enabled: bool, pub enabled_drift: bool, pub operator_can_disable: bool, + #[schema(value_type = Object)] pub params: serde_json::Value, pub params_drift: bool, pub file_managed_params: bool, @@ -33,10 +35,11 @@ pub struct ModuleInstanceView { pub dry_run: bool, /// The instance's circuit breaker on the replica that answered: `closed`, `open` or /// `half_open`. + #[schema(value_type = String)] pub circuit: &'static str, } -#[derive(Debug, Clone, Serialize)] +#[derive(Debug, Clone, Serialize, utoipa::ToSchema)] pub struct ModuleCatalogView { pub catalog_hash: String, pub params_version: u64, @@ -46,35 +49,40 @@ pub struct ModuleCatalogView { pub undeclared: Vec, } -#[derive(Debug, Clone, Serialize)] +#[derive(Debug, Clone, Serialize, utoipa::ToSchema)] pub struct UndeclaredInstanceView { pub module_id: String, pub enabled: bool, + #[schema(value_type = Object)] pub params: serde_json::Value, } -#[derive(Debug, Clone, Serialize)] +#[derive(Debug, Clone, Serialize, utoipa::ToSchema)] pub struct AccountModuleEntry { pub module_id: String, + #[schema(value_type = String)] pub scope: &'static str, pub enabled: bool, /// A stored entry naming an instance the catalog no longer declares; skipped at evaluation. pub orphaned: bool, #[serde(skip_serializing_if = "Option::is_none")] + #[schema(value_type = Option)] pub global_params: Option, #[serde(skip_serializing_if = "Option::is_none")] + #[schema(value_type = Option)] pub account_layer: Option, #[serde(skip_serializing_if = "Option::is_none")] + #[schema(value_type = Option)] pub params: Option, } -#[derive(Debug, Clone, Serialize)] +#[derive(Debug, Clone, Serialize, utoipa::ToSchema)] pub struct AccountModulesView { pub account_id: String, pub modules: Vec, } -#[derive(Debug, Clone, Serialize)] +#[derive(Debug, Clone, Serialize, utoipa::ToSchema)] pub struct ParamsHistoryView { pub module_id: String, pub entries: Vec, diff --git a/crates/server/src/modules/catalog.rs b/crates/server/src/modules/catalog.rs index 95b100ad..e451befa 100644 --- a/crates/server/src/modules/catalog.rs +++ b/crates/server/src/modules/catalog.rs @@ -110,7 +110,9 @@ fn enabled_default() -> bool { } /// What an account's cosigners may learn about an instance (RFC 0002 section 2.7). -#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Deserialize, serde::Serialize)] +#[derive( + Debug, Clone, Copy, Default, PartialEq, Eq, Deserialize, serde::Serialize, utoipa::ToSchema, +)] #[serde(rename_all = "snake_case")] pub enum Disclosure { #[default] @@ -120,7 +122,9 @@ pub enum Disclosure { } /// How a denial from an instance reaches the client (RFC 0002 section 4.1). -#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Deserialize, serde::Serialize)] +#[derive( + Debug, Clone, Copy, Default, PartialEq, Eq, Deserialize, serde::Serialize, utoipa::ToSchema, +)] #[serde(rename_all = "snake_case")] pub enum ClientReason { #[default] diff --git a/crates/server/src/modules/store.rs b/crates/server/src/modules/store.rs index ede4936a..17d485fe 100644 --- a/crates/server/src/modules/store.rs +++ b/crates/server/src/modules/store.rs @@ -52,22 +52,25 @@ pub struct AccountParamsRow { pub updated_by: String, } -#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] +#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, utoipa::ToSchema)] pub struct HistoryEntry { pub version: u64, pub module_id: String, #[serde(default, skip_serializing_if = "Option::is_none")] pub account_id: Option, + #[schema(value_type = Object)] pub previous: serde_json::Value, + #[schema(value_type = Object)] pub new: serde_json::Value, pub operator: String, pub reason: String, pub at: String, } -#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] +#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, utoipa::ToSchema)] pub struct Assigned { pub module_id: String, + #[schema(value_type = Object)] pub params: serde_json::Value, } diff --git a/crates/server/src/openapi.rs b/crates/server/src/openapi.rs index 7f6f8295..28582983 100644 --- a/crates/server/src/openapi.rs +++ b/crates/server/src/openapi.rs @@ -263,6 +263,15 @@ pub struct ClientApiDoc; crate::api::dashboard_feeds::list_account_proposals_handler, crate::api::dashboard_feeds::list_global_deltas_handler, crate::api::dashboard_feeds::list_global_proposals_handler, + crate::api::dashboard_modules::list_modules, + crate::api::dashboard_modules::account_modules, + crate::api::dashboard_modules::params_history, + crate::api::dashboard_modules::set_global_params, + crate::api::dashboard_modules::enable_module, + crate::api::dashboard_modules::disable_module, + crate::api::dashboard_modules::set_account_layer, + crate::api::dashboard_modules::remove_account_layer, + crate::api::dashboard_modules::set_assignment, ), components(schemas(ApiErrorResponse, ApiErrorMeta)), modifiers(&DashboardSecurityAddon, &CommonResponsesAddon), diff --git a/docs/openapi-dashboard.json b/docs/openapi-dashboard.json index 1e930cdb..5af26a4c 100644 --- a/docs/openapi-dashboard.json +++ b/docs/openapi-dashboard.json @@ -626,13 +626,96 @@ ] } }, - "/dashboard/accounts/{account_id}/pause": { - "post": { + "/dashboard/accounts/{account_id}/modules": { + "get": { "tags": [ "dashboard" ], - "summary": "Pause an account (blocks mutating actions). Requires the\n`accounts:pause` permission.", - "operationId": "pause_account_handler", + "operationId": "account_modules", + "parameters": [ + { + "name": "account_id", + "in": "path", + "description": "Account identifier", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "The account's effective module set, in evaluation order", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AccountModulesView" + } + } + } + }, + "401": { + "description": "No operator session", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "403": { + "description": "Missing dashboard:read permission", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "404": { + "description": "Account or module not found, or no modules configured", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "413": { + "description": "Request body exceeds the configured size limit", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "429": { + "description": "Rate limit exceeded", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + }, + "security": [ + { + "operator_session": [] + } + ] + }, + "put": { + "tags": [ + "dashboard" + ], + "operationId": "set_assignment", "parameters": [ { "name": "account_id", @@ -648,7 +731,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PauseAccountRequest" + "$ref": "#/components/schemas/AssignmentBody" } } }, @@ -656,17 +739,17 @@ }, "responses": { "200": { - "description": "Account paused", + "description": "Assignment stored", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PauseResponse" + "$ref": "#/components/schemas/AccountModulesView" } } } }, "400": { - "description": "Invalid or missing reason", + "description": "Invalid params, reason or assignment", "content": { "application/json": { "schema": { @@ -686,7 +769,7 @@ } }, "403": { - "description": "Missing accounts:pause permission", + "description": "Missing policies:write permission", "content": { "application/json": { "schema": { @@ -696,7 +779,7 @@ } }, "404": { - "description": "Account not found", + "description": "Account or module not found, or no modules configured", "content": { "application/json": { "schema": { @@ -733,13 +816,12 @@ ] } }, - "/dashboard/accounts/{account_id}/proposals": { - "get": { + "/dashboard/accounts/{account_id}/modules/{module_id}/params": { + "put": { "tags": [ "dashboard" ], - "summary": "`GET /dashboard/accounts/{account_id}/proposals`. Returns the\nin-flight multisig proposal queue for one account, paginated\nnewest-first by `(nonce DESC, commitment DESC)`. Single-key Miden\nand EVM accounts always return an empty page per FR-017.", - "operationId": "list_account_proposals_handler", + "operationId": "set_account_layer", "parameters": [ { "name": "account_id", @@ -751,35 +833,38 @@ } }, { - "name": "limit", - "in": "query", - "required": false, - "schema": { - "type": "string" - } - }, - { - "name": "cursor", - "in": "query", - "required": false, + "name": "module_id", + "in": "path", + "description": "Module instance id", + "required": true, "schema": { "type": "string" } } ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ParamsBody" + } + } + }, + "required": true + }, "responses": { "200": { - "description": "Per-account in-flight proposal queue page", + "description": "Account layer stored", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PagedResult_DashboardProposalEntry" + "$ref": "#/components/schemas/AccountModulesView" } } } }, "400": { - "description": "Invalid limit or cursor", + "description": "Invalid params, reason or assignment", "content": { "application/json": { "schema": { @@ -798,8 +883,18 @@ } } }, + "403": { + "description": "Missing policies:write permission", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, "404": { - "description": "Account not found", + "description": "Account or module not found, or no modules configured", "content": { "application/json": { "schema": { @@ -834,15 +929,12 @@ "operator_session": [] } ] - } - }, - "/dashboard/accounts/{account_id}/snapshot": { - "get": { + }, + "delete": { "tags": [ "dashboard" ], - "summary": "Decode and return the current vault snapshot for a Miden account.", - "operationId": "get_operator_account_snapshot", + "operationId": "remove_account_layer", "parameters": [ { "name": "account_id", @@ -852,21 +944,40 @@ "schema": { "type": "string" } + }, + { + "name": "module_id", + "in": "path", + "description": "Module instance id", + "required": true, + "schema": { + "type": "string" + } } ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ReasonBody" + } + } + }, + "required": true + }, "responses": { "200": { - "description": "Account snapshot", + "description": "Account layer removed", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DashboardAccountSnapshot" + "$ref": "#/components/schemas/AccountModulesView" } } } }, "400": { - "description": "Unsupported for this network (e.g. EVM)", + "description": "Invalid params, reason or assignment", "content": { "application/json": { "schema": { @@ -886,7 +997,7 @@ } }, "403": { - "description": "Missing dashboard:read permission", + "description": "Missing policies:write permission", "content": { "application/json": { "schema": { @@ -896,7 +1007,7 @@ } }, "404": { - "description": "Account not found", + "description": "Account or module not found, or no modules configured", "content": { "application/json": { "schema": { @@ -924,16 +1035,6 @@ } } } - }, - "503": { - "description": "Account state unavailable", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } } }, "security": [ @@ -943,13 +1044,13 @@ ] } }, - "/dashboard/accounts/{account_id}/unpause": { + "/dashboard/accounts/{account_id}/pause": { "post": { "tags": [ "dashboard" ], - "summary": "Unpause an account (idempotent). Requires the `accounts:pause`\npermission. Accepts an optional reason in the body.", - "operationId": "unpause_account_handler", + "summary": "Pause an account (blocks mutating actions). Requires the\n`accounts:pause` permission.", + "operationId": "pause_account_handler", "parameters": [ { "name": "account_id", @@ -965,7 +1066,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/UnpauseAccountRequest" + "$ref": "#/components/schemas/PauseAccountRequest" } } }, @@ -973,17 +1074,17 @@ }, "responses": { "200": { - "description": "Account unpaused", + "description": "Account paused", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/UnpauseResponse" + "$ref": "#/components/schemas/PauseResponse" } } } }, "400": { - "description": "Invalid reason", + "description": "Invalid or missing reason", "content": { "application/json": { "schema": { @@ -1050,25 +1151,25 @@ ] } }, - "/dashboard/deltas": { + "/dashboard/accounts/{account_id}/proposals": { "get": { "tags": [ "dashboard" ], - "summary": "`GET /dashboard/deltas`. Cross-account delta feed paginated\nnewest-first by `status_timestamp DESC`. Optional comma-separated\n`status` filter restricts to a subset of `{candidate, canonical,\nretained, discarded}`. Pending entries live on the proposal feed.", - "description": "Spec reference: `005-operator-dashboard-metrics` US6, FR-031..FR-035.", - "operationId": "list_global_deltas_handler", + "summary": "`GET /dashboard/accounts/{account_id}/proposals`. Returns the\nin-flight multisig proposal queue for one account, paginated\nnewest-first by `(nonce DESC, commitment DESC)`. Single-key Miden\nand EVM accounts always return an empty page per FR-017.", + "operationId": "list_account_proposals_handler", "parameters": [ { - "name": "limit", - "in": "query", - "required": false, + "name": "account_id", + "in": "path", + "description": "Account identifier", + "required": true, "schema": { "type": "string" } }, { - "name": "cursor", + "name": "limit", "in": "query", "required": false, "schema": { @@ -1076,7 +1177,7 @@ } }, { - "name": "status", + "name": "cursor", "in": "query", "required": false, "schema": { @@ -1086,17 +1187,17 @@ ], "responses": { "200": { - "description": "Cross-account delta feed page", + "description": "Per-account in-flight proposal queue page", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PagedResult_DashboardGlobalDeltaEntry" + "$ref": "#/components/schemas/PagedResult_DashboardProposalEntry" } } } }, "400": { - "description": "Invalid limit, cursor, or status filter", + "description": "Invalid limit or cursor", "content": { "application/json": { "schema": { @@ -1115,18 +1216,869 @@ } } }, + "404": { + "description": "Account not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, "413": { "description": "Request body exceeds the configured size limit", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "429": { + "description": "Rate limit exceeded", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + }, + "security": [ + { + "operator_session": [] + } + ] + } + }, + "/dashboard/accounts/{account_id}/snapshot": { + "get": { + "tags": [ + "dashboard" + ], + "summary": "Decode and return the current vault snapshot for a Miden account.", + "operationId": "get_operator_account_snapshot", + "parameters": [ + { + "name": "account_id", + "in": "path", + "description": "Account identifier", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Account snapshot", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DashboardAccountSnapshot" + } + } + } + }, + "400": { + "description": "Unsupported for this network (e.g. EVM)", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "401": { + "description": "No operator session", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "403": { + "description": "Missing dashboard:read permission", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "404": { + "description": "Account not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "413": { + "description": "Request body exceeds the configured size limit", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "429": { + "description": "Rate limit exceeded", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "503": { + "description": "Account state unavailable", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + }, + "security": [ + { + "operator_session": [] + } + ] + } + }, + "/dashboard/accounts/{account_id}/unpause": { + "post": { + "tags": [ + "dashboard" + ], + "summary": "Unpause an account (idempotent). Requires the `accounts:pause`\npermission. Accepts an optional reason in the body.", + "operationId": "unpause_account_handler", + "parameters": [ + { + "name": "account_id", + "in": "path", + "description": "Account identifier", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnpauseAccountRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Account unpaused", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnpauseResponse" + } + } + } + }, + "400": { + "description": "Invalid reason", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "401": { + "description": "No operator session", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "403": { + "description": "Missing accounts:pause permission", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "404": { + "description": "Account not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "413": { + "description": "Request body exceeds the configured size limit", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "429": { + "description": "Rate limit exceeded", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + }, + "security": [ + { + "operator_session": [] + } + ] + } + }, + "/dashboard/deltas": { + "get": { + "tags": [ + "dashboard" + ], + "summary": "`GET /dashboard/deltas`. Cross-account delta feed paginated\nnewest-first by `status_timestamp DESC`. Optional comma-separated\n`status` filter restricts to a subset of `{candidate, canonical,\nretained, discarded}`. Pending entries live on the proposal feed.", + "description": "Spec reference: `005-operator-dashboard-metrics` US6, FR-031..FR-035.", + "operationId": "list_global_deltas_handler", + "parameters": [ + { + "name": "limit", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "cursor", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "status", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Cross-account delta feed page", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PagedResult_DashboardGlobalDeltaEntry" + } + } + } + }, + "400": { + "description": "Invalid limit, cursor, or status filter", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "401": { + "description": "No operator session", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "413": { + "description": "Request body exceeds the configured size limit", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "429": { + "description": "Rate limit exceeded", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "503": { + "description": "Aggregate degraded (filesystem threshold exceeded)", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + }, + "security": [ + { + "operator_session": [] + } + ] + } + }, + "/dashboard/info": { + "get": { + "tags": [ + "dashboard" + ], + "summary": "`GET /dashboard/info` — point-in-time inventory and lifecycle\nsummary per feature `005-operator-dashboard-metrics` US2.", + "operationId": "get_dashboard_info_handler", + "responses": { + "200": { + "description": "Inventory and lifecycle summary", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DashboardInfoResponse" + } + } + } + }, + "401": { + "description": "No operator session", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "403": { + "description": "Missing dashboard:read permission", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "413": { + "description": "Request body exceeds the configured size limit", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "429": { + "description": "Rate limit exceeded", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + }, + "security": [ + { + "operator_session": [] + } + ] + } + }, + "/dashboard/modules": { + "get": { + "tags": [ + "dashboard" + ], + "operationId": "list_modules", + "responses": { + "200": { + "description": "Module instances with their runtime state", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ModuleCatalogView" + } + } + } + }, + "401": { + "description": "No operator session", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "403": { + "description": "Missing dashboard:read permission", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "404": { + "description": "Account or module not found, or no modules configured", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "413": { + "description": "Request body exceeds the configured size limit", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "429": { + "description": "Rate limit exceeded", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + }, + "security": [ + { + "operator_session": [] + } + ] + } + }, + "/dashboard/modules/{module_id}/disable": { + "post": { + "tags": [ + "dashboard" + ], + "operationId": "disable_module", + "parameters": [ + { + "name": "module_id", + "in": "path", + "description": "Module instance id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ReasonBody" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Instance disabled", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ModuleInstanceView" + } + } + } + }, + "400": { + "description": "Invalid params, reason or assignment", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "401": { + "description": "No operator session", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "403": { + "description": "Missing policies:write or modules:disable permission", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "404": { + "description": "Account or module not found, or no modules configured", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "413": { + "description": "Request body exceeds the configured size limit", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "429": { + "description": "Rate limit exceeded", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + }, + "security": [ + { + "operator_session": [] + } + ] + } + }, + "/dashboard/modules/{module_id}/enable": { + "post": { + "tags": [ + "dashboard" + ], + "operationId": "enable_module", + "parameters": [ + { + "name": "module_id", + "in": "path", + "description": "Module instance id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ReasonBody" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Instance enabled", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ModuleInstanceView" + } + } + } + }, + "400": { + "description": "Invalid params, reason or assignment", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "401": { + "description": "No operator session", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "403": { + "description": "Missing policies:write permission", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "404": { + "description": "Account or module not found, or no modules configured", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "413": { + "description": "Request body exceeds the configured size limit", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "429": { + "description": "Rate limit exceeded", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + }, + "security": [ + { + "operator_session": [] + } + ] + } + }, + "/dashboard/modules/{module_id}/params": { + "put": { + "tags": [ + "dashboard" + ], + "operationId": "set_global_params", + "parameters": [ + { + "name": "module_id", + "in": "path", + "description": "Module instance id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ParamsBody" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Global params stored", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ModuleInstanceView" + } + } + } + }, + "400": { + "description": "Invalid params, reason or assignment", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "401": { + "description": "No operator session", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "403": { + "description": "Missing policies:write_global permission", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "404": { + "description": "Account or module not found, or no modules configured", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "413": { + "description": "Request body exceeds the configured size limit", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "429": { + "description": "Rate limit exceeded", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + }, + "security": [ + { + "operator_session": [] + } + ] + } + }, + "/dashboard/modules/{module_id}/params/history": { + "get": { + "tags": [ + "dashboard" + ], + "operationId": "params_history", + "parameters": [ + { + "name": "module_id", + "in": "path", + "description": "Module instance id", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "before", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "format": "int64", + "minimum": 0 + } + }, + { + "name": "limit", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "minimum": 0 + } + } + ], + "responses": { + "200": { + "description": "Params changes, newest first", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ParamsHistoryView" } } } }, - "429": { - "description": "Rate limit exceeded", + "400": { + "description": "Invalid params, reason or assignment", "content": { "application/json": { "schema": { @@ -1135,8 +2087,8 @@ } } }, - "503": { - "description": "Aggregate degraded (filesystem threshold exceeded)", + "401": { + "description": "No operator session", "content": { "application/json": { "schema": { @@ -1144,35 +2096,9 @@ } } } - } - }, - "security": [ - { - "operator_session": [] - } - ] - } - }, - "/dashboard/info": { - "get": { - "tags": [ - "dashboard" - ], - "summary": "`GET /dashboard/info` — point-in-time inventory and lifecycle\nsummary per feature `005-operator-dashboard-metrics` US2.", - "operationId": "get_dashboard_info_handler", - "responses": { - "200": { - "description": "Inventory and lifecycle summary", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/DashboardInfoResponse" - } - } - } }, - "401": { - "description": "No operator session", + "403": { + "description": "Missing dashboard:read permission", "content": { "application/json": { "schema": { @@ -1181,8 +2107,8 @@ } } }, - "403": { - "description": "Missing dashboard:read permission", + "404": { + "description": "Account or module not found, or no modules configured", "content": { "application/json": { "schema": { @@ -1537,6 +2463,66 @@ }, "components": { "schemas": { + "AccountModuleEntry": { + "type": "object", + "required": [ + "module_id", + "scope", + "enabled", + "orphaned" + ], + "properties": { + "account_layer": { + "type": [ + "object", + "null" + ] + }, + "enabled": { + "type": "boolean" + }, + "global_params": { + "type": [ + "object", + "null" + ] + }, + "module_id": { + "type": "string" + }, + "orphaned": { + "type": "boolean", + "description": "A stored entry naming an instance the catalog no longer declares; skipped at evaluation." + }, + "params": { + "type": [ + "object", + "null" + ] + }, + "scope": { + "type": "string" + } + } + }, + "AccountModulesView": { + "type": "object", + "required": [ + "account_id", + "modules" + ], + "properties": { + "account_id": { + "type": "string" + }, + "modules": { + "type": "array", + "items": { + "$ref": "#/components/schemas/AccountModuleEntry" + } + } + } + }, "AccountStatus": { "type": "string", "enum": [ @@ -1687,6 +2673,47 @@ } } }, + "Assigned": { + "type": "object", + "required": [ + "module_id", + "params" + ], + "properties": { + "module_id": { + "type": "string" + }, + "params": { + "type": "object" + } + } + }, + "AssignmentBody": { + "type": "object", + "required": [ + "modules", + "reason" + ], + "properties": { + "modules": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Assigned" + } + }, + "reason": { + "type": "string" + } + } + }, + "ClientReason": { + "type": "string", + "description": "How a denial from an instance reaches the client (RFC 0002 section 4.1).", + "enum": [ + "full", + "generic" + ] + }, "CounterpartyDirection": { "type": "string", "enum": [ @@ -3150,6 +4177,58 @@ } } }, + "Disclosure": { + "type": "string", + "description": "What an account's cosigners may learn about an instance (RFC 0002 section 2.7).", + "enum": [ + "none", + "summary", + "params" + ] + }, + "HistoryEntry": { + "type": "object", + "required": [ + "version", + "module_id", + "previous", + "new", + "operator", + "reason", + "at" + ], + "properties": { + "account_id": { + "type": [ + "string", + "null" + ] + }, + "at": { + "type": "string" + }, + "module_id": { + "type": "string" + }, + "new": { + "type": "object" + }, + "operator": { + "type": "string" + }, + "previous": { + "type": "object" + }, + "reason": { + "type": "string" + }, + "version": { + "type": "integer", + "format": "int64", + "minimum": 0 + } + } + }, "LogoutOperatorResponse": { "type": "object", "required": [ @@ -3161,6 +4240,122 @@ } } }, + "ModuleCatalogView": { + "type": "object", + "required": [ + "catalog_hash", + "params_version", + "modules", + "undeclared" + ], + "properties": { + "catalog_hash": { + "type": "string" + }, + "modules": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ModuleInstanceView" + } + }, + "params_version": { + "type": "integer", + "format": "int64", + "minimum": 0 + }, + "undeclared": { + "type": "array", + "items": { + "$ref": "#/components/schemas/UndeclaredInstanceView" + }, + "description": "Stored instances the catalog no longer declares: kept, never evaluated, active again if\nthe catalog brings the id back." + } + } + }, + "ModuleInstanceView": { + "type": "object", + "required": [ + "module_id", + "kind", + "scope", + "hooks", + "enabled", + "catalog_enabled", + "enabled_drift", + "operator_can_disable", + "params", + "params_drift", + "file_managed_params", + "disclosure", + "client_reason", + "dry_run", + "circuit" + ], + "properties": { + "build": { + "type": [ + "string", + "null" + ], + "description": "`name version` from `describe` at startup; absent when the startup checks failed." + }, + "catalog_enabled": { + "type": "boolean" + }, + "circuit": { + "type": "string", + "description": "The instance's circuit breaker on the replica that answered: `closed`, `open` or\n`half_open`." + }, + "client_reason": { + "$ref": "#/components/schemas/ClientReason" + }, + "description": { + "type": [ + "string", + "null" + ] + }, + "disclosure": { + "$ref": "#/components/schemas/Disclosure" + }, + "dry_run": { + "type": "boolean" + }, + "enabled": { + "type": "boolean" + }, + "enabled_drift": { + "type": "boolean" + }, + "file_managed_params": { + "type": "boolean" + }, + "hooks": { + "type": "array", + "items": { + "type": "string" + } + }, + "kind": { + "type": "string" + }, + "module_id": { + "type": "string" + }, + "operator_can_disable": { + "type": "boolean" + }, + "params": { + "type": "object" + }, + "params_drift": { + "type": "boolean" + }, + "scope": { + "type": "string" + } + } + }, "NoteCounts": { "type": "object", "properties": { @@ -3697,6 +4892,39 @@ } } }, + "ParamsBody": { + "type": "object", + "required": [ + "params", + "reason" + ], + "properties": { + "params": { + "type": "object" + }, + "reason": { + "type": "string" + } + } + }, + "ParamsHistoryView": { + "type": "object", + "required": [ + "module_id", + "entries" + ], + "properties": { + "entries": { + "type": "array", + "items": { + "$ref": "#/components/schemas/HistoryEntry" + } + }, + "module_id": { + "type": "string" + } + } + }, "PauseAccountRequest": { "type": "object", "required": [ @@ -3872,6 +5100,17 @@ } } }, + "ReasonBody": { + "type": "object", + "required": [ + "reason" + ], + "properties": { + "reason": { + "type": "string" + } + } + }, "SessionInfoResponse": { "type": "object", "required": [ @@ -3923,6 +5162,25 @@ } } }, + "UndeclaredInstanceView": { + "type": "object", + "required": [ + "module_id", + "enabled", + "params" + ], + "properties": { + "enabled": { + "type": "boolean" + }, + "module_id": { + "type": "string" + }, + "params": { + "type": "object" + } + } + }, "UnpauseAccountRequest": { "type": "object", "properties": { diff --git a/docs/openapi.json b/docs/openapi.json index 98a92935..2859ccc7 100644 --- a/docs/openapi.json +++ b/docs/openapi.json @@ -789,13 +789,96 @@ ] } }, - "/dashboard/accounts/{account_id}/pause": { - "post": { + "/dashboard/accounts/{account_id}/modules": { + "get": { "tags": [ "dashboard" ], - "summary": "Pause an account (blocks mutating actions). Requires the\n`accounts:pause` permission.", - "operationId": "pause_account_handler", + "operationId": "account_modules", + "parameters": [ + { + "name": "account_id", + "in": "path", + "description": "Account identifier", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "The account's effective module set, in evaluation order", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AccountModulesView" + } + } + } + }, + "401": { + "description": "No operator session", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "403": { + "description": "Missing dashboard:read permission", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "404": { + "description": "Account or module not found, or no modules configured", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "413": { + "description": "Request body exceeds the configured size limit", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "429": { + "description": "Rate limit exceeded", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + }, + "security": [ + { + "operator_session": [] + } + ] + }, + "put": { + "tags": [ + "dashboard" + ], + "operationId": "set_assignment", "parameters": [ { "name": "account_id", @@ -811,7 +894,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PauseAccountRequest" + "$ref": "#/components/schemas/AssignmentBody" } } }, @@ -819,17 +902,17 @@ }, "responses": { "200": { - "description": "Account paused", + "description": "Assignment stored", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PauseResponse" + "$ref": "#/components/schemas/AccountModulesView" } } } }, "400": { - "description": "Invalid or missing reason", + "description": "Invalid params, reason or assignment", "content": { "application/json": { "schema": { @@ -849,7 +932,7 @@ } }, "403": { - "description": "Missing accounts:pause permission", + "description": "Missing policies:write permission", "content": { "application/json": { "schema": { @@ -859,7 +942,7 @@ } }, "404": { - "description": "Account not found", + "description": "Account or module not found, or no modules configured", "content": { "application/json": { "schema": { @@ -896,13 +979,12 @@ ] } }, - "/dashboard/accounts/{account_id}/proposals": { - "get": { + "/dashboard/accounts/{account_id}/modules/{module_id}/params": { + "put": { "tags": [ "dashboard" ], - "summary": "`GET /dashboard/accounts/{account_id}/proposals`. Returns the\nin-flight multisig proposal queue for one account, paginated\nnewest-first by `(nonce DESC, commitment DESC)`. Single-key Miden\nand EVM accounts always return an empty page per FR-017.", - "operationId": "list_account_proposals_handler", + "operationId": "set_account_layer", "parameters": [ { "name": "account_id", @@ -914,35 +996,38 @@ } }, { - "name": "limit", - "in": "query", - "required": false, - "schema": { - "type": "string" - } - }, - { - "name": "cursor", - "in": "query", - "required": false, + "name": "module_id", + "in": "path", + "description": "Module instance id", + "required": true, "schema": { "type": "string" } } ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ParamsBody" + } + } + }, + "required": true + }, "responses": { "200": { - "description": "Per-account in-flight proposal queue page", + "description": "Account layer stored", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PagedResult_DashboardProposalEntry" + "$ref": "#/components/schemas/AccountModulesView" } } } }, "400": { - "description": "Invalid limit or cursor", + "description": "Invalid params, reason or assignment", "content": { "application/json": { "schema": { @@ -961,8 +1046,18 @@ } } }, + "403": { + "description": "Missing policies:write permission", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, "404": { - "description": "Account not found", + "description": "Account or module not found, or no modules configured", "content": { "application/json": { "schema": { @@ -997,15 +1092,12 @@ "operator_session": [] } ] - } - }, - "/dashboard/accounts/{account_id}/snapshot": { - "get": { + }, + "delete": { "tags": [ "dashboard" ], - "summary": "Decode and return the current vault snapshot for a Miden account.", - "operationId": "get_operator_account_snapshot", + "operationId": "remove_account_layer", "parameters": [ { "name": "account_id", @@ -1015,21 +1107,40 @@ "schema": { "type": "string" } + }, + { + "name": "module_id", + "in": "path", + "description": "Module instance id", + "required": true, + "schema": { + "type": "string" + } } ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ReasonBody" + } + } + }, + "required": true + }, "responses": { "200": { - "description": "Account snapshot", + "description": "Account layer removed", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DashboardAccountSnapshot" + "$ref": "#/components/schemas/AccountModulesView" } } } }, "400": { - "description": "Unsupported for this network (e.g. EVM)", + "description": "Invalid params, reason or assignment", "content": { "application/json": { "schema": { @@ -1049,7 +1160,7 @@ } }, "403": { - "description": "Missing dashboard:read permission", + "description": "Missing policies:write permission", "content": { "application/json": { "schema": { @@ -1059,7 +1170,7 @@ } }, "404": { - "description": "Account not found", + "description": "Account or module not found, or no modules configured", "content": { "application/json": { "schema": { @@ -1087,16 +1198,6 @@ } } } - }, - "503": { - "description": "Account state unavailable", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } } }, "security": [ @@ -1106,13 +1207,13 @@ ] } }, - "/dashboard/accounts/{account_id}/unpause": { + "/dashboard/accounts/{account_id}/pause": { "post": { "tags": [ "dashboard" ], - "summary": "Unpause an account (idempotent). Requires the `accounts:pause`\npermission. Accepts an optional reason in the body.", - "operationId": "unpause_account_handler", + "summary": "Pause an account (blocks mutating actions). Requires the\n`accounts:pause` permission.", + "operationId": "pause_account_handler", "parameters": [ { "name": "account_id", @@ -1128,7 +1229,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/UnpauseAccountRequest" + "$ref": "#/components/schemas/PauseAccountRequest" } } }, @@ -1136,17 +1237,17 @@ }, "responses": { "200": { - "description": "Account unpaused", + "description": "Account paused", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/UnpauseResponse" + "$ref": "#/components/schemas/PauseResponse" } } } }, "400": { - "description": "Invalid reason", + "description": "Invalid or missing reason", "content": { "application/json": { "schema": { @@ -1213,25 +1314,25 @@ ] } }, - "/dashboard/deltas": { + "/dashboard/accounts/{account_id}/proposals": { "get": { "tags": [ "dashboard" ], - "summary": "`GET /dashboard/deltas`. Cross-account delta feed paginated\nnewest-first by `status_timestamp DESC`. Optional comma-separated\n`status` filter restricts to a subset of `{candidate, canonical,\nretained, discarded}`. Pending entries live on the proposal feed.", - "description": "Spec reference: `005-operator-dashboard-metrics` US6, FR-031..FR-035.", - "operationId": "list_global_deltas_handler", + "summary": "`GET /dashboard/accounts/{account_id}/proposals`. Returns the\nin-flight multisig proposal queue for one account, paginated\nnewest-first by `(nonce DESC, commitment DESC)`. Single-key Miden\nand EVM accounts always return an empty page per FR-017.", + "operationId": "list_account_proposals_handler", "parameters": [ { - "name": "limit", - "in": "query", - "required": false, + "name": "account_id", + "in": "path", + "description": "Account identifier", + "required": true, "schema": { "type": "string" } }, { - "name": "cursor", + "name": "limit", "in": "query", "required": false, "schema": { @@ -1239,7 +1340,7 @@ } }, { - "name": "status", + "name": "cursor", "in": "query", "required": false, "schema": { @@ -1249,17 +1350,17 @@ ], "responses": { "200": { - "description": "Cross-account delta feed page", + "description": "Per-account in-flight proposal queue page", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PagedResult_DashboardGlobalDeltaEntry" + "$ref": "#/components/schemas/PagedResult_DashboardProposalEntry" } } } }, "400": { - "description": "Invalid limit, cursor, or status filter", + "description": "Invalid limit or cursor", "content": { "application/json": { "schema": { @@ -1278,6 +1379,16 @@ } } }, + "404": { + "description": "Account not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, "413": { "description": "Request body exceeds the configured size limit", "content": { @@ -1293,13 +1404,844 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + }, + "security": [ + { + "operator_session": [] + } + ] + } + }, + "/dashboard/accounts/{account_id}/snapshot": { + "get": { + "tags": [ + "dashboard" + ], + "summary": "Decode and return the current vault snapshot for a Miden account.", + "operationId": "get_operator_account_snapshot", + "parameters": [ + { + "name": "account_id", + "in": "path", + "description": "Account identifier", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Account snapshot", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DashboardAccountSnapshot" + } + } + } + }, + "400": { + "description": "Unsupported for this network (e.g. EVM)", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "401": { + "description": "No operator session", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "403": { + "description": "Missing dashboard:read permission", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "404": { + "description": "Account not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "413": { + "description": "Request body exceeds the configured size limit", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "429": { + "description": "Rate limit exceeded", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "503": { + "description": "Account state unavailable", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + }, + "security": [ + { + "operator_session": [] + } + ] + } + }, + "/dashboard/accounts/{account_id}/unpause": { + "post": { + "tags": [ + "dashboard" + ], + "summary": "Unpause an account (idempotent). Requires the `accounts:pause`\npermission. Accepts an optional reason in the body.", + "operationId": "unpause_account_handler", + "parameters": [ + { + "name": "account_id", + "in": "path", + "description": "Account identifier", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnpauseAccountRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Account unpaused", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnpauseResponse" + } + } + } + }, + "400": { + "description": "Invalid reason", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "401": { + "description": "No operator session", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "403": { + "description": "Missing accounts:pause permission", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "404": { + "description": "Account not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "413": { + "description": "Request body exceeds the configured size limit", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "429": { + "description": "Rate limit exceeded", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + }, + "security": [ + { + "operator_session": [] + } + ] + } + }, + "/dashboard/deltas": { + "get": { + "tags": [ + "dashboard" + ], + "summary": "`GET /dashboard/deltas`. Cross-account delta feed paginated\nnewest-first by `status_timestamp DESC`. Optional comma-separated\n`status` filter restricts to a subset of `{candidate, canonical,\nretained, discarded}`. Pending entries live on the proposal feed.", + "description": "Spec reference: `005-operator-dashboard-metrics` US6, FR-031..FR-035.", + "operationId": "list_global_deltas_handler", + "parameters": [ + { + "name": "limit", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "cursor", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "status", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Cross-account delta feed page", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PagedResult_DashboardGlobalDeltaEntry" + } + } + } + }, + "400": { + "description": "Invalid limit, cursor, or status filter", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "401": { + "description": "No operator session", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "413": { + "description": "Request body exceeds the configured size limit", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "429": { + "description": "Rate limit exceeded", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "503": { + "description": "Aggregate degraded (filesystem threshold exceeded)", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + }, + "security": [ + { + "operator_session": [] + } + ] + } + }, + "/dashboard/info": { + "get": { + "tags": [ + "dashboard" + ], + "summary": "`GET /dashboard/info` — point-in-time inventory and lifecycle\nsummary per feature `005-operator-dashboard-metrics` US2.", + "operationId": "get_dashboard_info_handler", + "responses": { + "200": { + "description": "Inventory and lifecycle summary", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DashboardInfoResponse" + } + } + } + }, + "401": { + "description": "No operator session", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "403": { + "description": "Missing dashboard:read permission", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "413": { + "description": "Request body exceeds the configured size limit", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "429": { + "description": "Rate limit exceeded", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + }, + "security": [ + { + "operator_session": [] + } + ] + } + }, + "/dashboard/modules": { + "get": { + "tags": [ + "dashboard" + ], + "operationId": "list_modules", + "responses": { + "200": { + "description": "Module instances with their runtime state", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ModuleCatalogView" + } + } + } + }, + "401": { + "description": "No operator session", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "403": { + "description": "Missing dashboard:read permission", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "404": { + "description": "Account or module not found, or no modules configured", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "413": { + "description": "Request body exceeds the configured size limit", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "429": { + "description": "Rate limit exceeded", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + }, + "security": [ + { + "operator_session": [] + } + ] + } + }, + "/dashboard/modules/{module_id}/disable": { + "post": { + "tags": [ + "dashboard" + ], + "operationId": "disable_module", + "parameters": [ + { + "name": "module_id", + "in": "path", + "description": "Module instance id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ReasonBody" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Instance disabled", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ModuleInstanceView" + } + } + } + }, + "400": { + "description": "Invalid params, reason or assignment", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "401": { + "description": "No operator session", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "403": { + "description": "Missing policies:write or modules:disable permission", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "404": { + "description": "Account or module not found, or no modules configured", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "413": { + "description": "Request body exceeds the configured size limit", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "429": { + "description": "Rate limit exceeded", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + }, + "security": [ + { + "operator_session": [] + } + ] + } + }, + "/dashboard/modules/{module_id}/enable": { + "post": { + "tags": [ + "dashboard" + ], + "operationId": "enable_module", + "parameters": [ + { + "name": "module_id", + "in": "path", + "description": "Module instance id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ReasonBody" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Instance enabled", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ModuleInstanceView" + } + } + } + }, + "400": { + "description": "Invalid params, reason or assignment", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "401": { + "description": "No operator session", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "403": { + "description": "Missing policies:write permission", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "404": { + "description": "Account or module not found, or no modules configured", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "413": { + "description": "Request body exceeds the configured size limit", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "429": { + "description": "Rate limit exceeded", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + }, + "security": [ + { + "operator_session": [] + } + ] + } + }, + "/dashboard/modules/{module_id}/params": { + "put": { + "tags": [ + "dashboard" + ], + "operationId": "set_global_params", + "parameters": [ + { + "name": "module_id", + "in": "path", + "description": "Module instance id", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ParamsBody" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Global params stored", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ModuleInstanceView" + } + } + } + }, + "400": { + "description": "Invalid params, reason or assignment", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "401": { + "description": "No operator session", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "403": { + "description": "Missing policies:write_global permission", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "404": { + "description": "Account or module not found, or no modules configured", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "413": { + "description": "Request body exceeds the configured size limit", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "429": { + "description": "Rate limit exceeded", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + }, + "security": [ + { + "operator_session": [] + } + ] + } + }, + "/dashboard/modules/{module_id}/params/history": { + "get": { + "tags": [ + "dashboard" + ], + "operationId": "params_history", + "parameters": [ + { + "name": "module_id", + "in": "path", + "description": "Module instance id", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "before", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "format": "int64", + "minimum": 0 + } + }, + { + "name": "limit", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "minimum": 0 + } + } + ], + "responses": { + "200": { + "description": "Params changes, newest first", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ParamsHistoryView" } } } }, - "503": { - "description": "Aggregate degraded (filesystem threshold exceeded)", + "400": { + "description": "Invalid params, reason or assignment", "content": { "application/json": { "schema": { @@ -1307,35 +2249,19 @@ } } } - } - }, - "security": [ - { - "operator_session": [] - } - ] - } - }, - "/dashboard/info": { - "get": { - "tags": [ - "dashboard" - ], - "summary": "`GET /dashboard/info` — point-in-time inventory and lifecycle\nsummary per feature `005-operator-dashboard-metrics` US2.", - "operationId": "get_dashboard_info_handler", - "responses": { - "200": { - "description": "Inventory and lifecycle summary", + }, + "401": { + "description": "No operator session", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DashboardInfoResponse" + "$ref": "#/components/schemas/ApiErrorResponse" } } } }, - "401": { - "description": "No operator session", + "403": { + "description": "Missing dashboard:read permission", "content": { "application/json": { "schema": { @@ -1344,8 +2270,8 @@ } } }, - "403": { - "description": "Missing dashboard:read permission", + "404": { + "description": "Account or module not found, or no modules configured", "content": { "application/json": { "schema": { @@ -4625,6 +5551,66 @@ } } }, + "AccountModuleEntry": { + "type": "object", + "required": [ + "module_id", + "scope", + "enabled", + "orphaned" + ], + "properties": { + "account_layer": { + "type": [ + "object", + "null" + ] + }, + "enabled": { + "type": "boolean" + }, + "global_params": { + "type": [ + "object", + "null" + ] + }, + "module_id": { + "type": "string" + }, + "orphaned": { + "type": "boolean", + "description": "A stored entry naming an instance the catalog no longer declares; skipped at evaluation." + }, + "params": { + "type": [ + "object", + "null" + ] + }, + "scope": { + "type": "string" + } + } + }, + "AccountModulesView": { + "type": "object", + "required": [ + "account_id", + "modules" + ], + "properties": { + "account_id": { + "type": "string" + }, + "modules": { + "type": "array", + "items": { + "$ref": "#/components/schemas/AccountModuleEntry" + } + } + } + }, "AccountStatus": { "type": "string", "enum": [ @@ -4790,6 +5776,39 @@ } } }, + "Assigned": { + "type": "object", + "required": [ + "module_id", + "params" + ], + "properties": { + "module_id": { + "type": "string" + }, + "params": { + "type": "object" + } + } + }, + "AssignmentBody": { + "type": "object", + "required": [ + "modules", + "reason" + ], + "properties": { + "modules": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Assigned" + } + }, + "reason": { + "type": "string" + } + } + }, "Auth": { "oneOf": [ { @@ -4988,6 +6007,14 @@ } } }, + "ClientReason": { + "type": "string", + "description": "How a denial from an instance reaches the client (RFC 0002 section 4.1).", + "enum": [ + "full", + "generic" + ] + }, "ConfigureRequest": { "type": "object", "required": [ @@ -6946,6 +7973,15 @@ "client_abandoned" ] }, + "Disclosure": { + "type": "string", + "description": "What an account's cosigners may learn about an instance (RFC 0002 section 2.7).", + "enum": [ + "none", + "summary", + "params" + ] + }, "EcdsaMessageFormat": { "type": "string", "description": "Message format used by an ECDSA approval.", @@ -7425,6 +8461,122 @@ } } }, + "ModuleCatalogView": { + "type": "object", + "required": [ + "catalog_hash", + "params_version", + "modules", + "undeclared" + ], + "properties": { + "catalog_hash": { + "type": "string" + }, + "modules": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ModuleInstanceView" + } + }, + "params_version": { + "type": "integer", + "format": "int64", + "minimum": 0 + }, + "undeclared": { + "type": "array", + "items": { + "$ref": "#/components/schemas/UndeclaredInstanceView" + }, + "description": "Stored instances the catalog no longer declares: kept, never evaluated, active again if\nthe catalog brings the id back." + } + } + }, + "ModuleInstanceView": { + "type": "object", + "required": [ + "module_id", + "kind", + "scope", + "hooks", + "enabled", + "catalog_enabled", + "enabled_drift", + "operator_can_disable", + "params", + "params_drift", + "file_managed_params", + "disclosure", + "client_reason", + "dry_run", + "circuit" + ], + "properties": { + "build": { + "type": [ + "string", + "null" + ], + "description": "`name version` from `describe` at startup; absent when the startup checks failed." + }, + "catalog_enabled": { + "type": "boolean" + }, + "circuit": { + "type": "string", + "description": "The instance's circuit breaker on the replica that answered: `closed`, `open` or\n`half_open`." + }, + "client_reason": { + "$ref": "#/components/schemas/ClientReason" + }, + "description": { + "type": [ + "string", + "null" + ] + }, + "disclosure": { + "$ref": "#/components/schemas/Disclosure" + }, + "dry_run": { + "type": "boolean" + }, + "enabled": { + "type": "boolean" + }, + "enabled_drift": { + "type": "boolean" + }, + "file_managed_params": { + "type": "boolean" + }, + "hooks": { + "type": "array", + "items": { + "type": "string" + } + }, + "kind": { + "type": "string" + }, + "module_id": { + "type": "string" + }, + "operator_can_disable": { + "type": "boolean" + }, + "params": { + "type": "object" + }, + "params_drift": { + "type": "boolean" + }, + "scope": { + "type": "string" + } + } + }, "NetworkConfig": { "oneOf": [ { @@ -8081,6 +9233,39 @@ } } }, + "ParamsBody": { + "type": "object", + "required": [ + "params", + "reason" + ], + "properties": { + "params": { + "type": "object" + }, + "reason": { + "type": "string" + } + } + }, + "ParamsHistoryView": { + "type": "object", + "required": [ + "module_id", + "entries" + ], + "properties": { + "entries": { + "type": "array", + "items": { + "$ref": "#/components/schemas/HistoryEntry" + } + }, + "module_id": { + "type": "string" + } + } + }, "PauseAccountRequest": { "type": "object", "required": [ @@ -8395,6 +9580,17 @@ } } }, + "ReasonBody": { + "type": "object", + "required": [ + "reason" + ], + "properties": { + "reason": { + "type": "string" + } + } + }, "RegisterAccountRequest": { "type": "object", "required": [ @@ -8722,6 +9918,25 @@ } } }, + "UndeclaredInstanceView": { + "type": "object", + "required": [ + "module_id", + "enabled", + "params" + ], + "properties": { + "enabled": { + "type": "boolean" + }, + "module_id": { + "type": "string" + }, + "params": { + "type": "object" + } + } + }, "UnpauseAccountRequest": { "type": "object", "properties": { diff --git a/speckit/features/251-guardian-modules/tasks.md b/speckit/features/251-guardian-modules/tasks.md index 269e6e5d..d15aaba2 100644 --- a/speckit/features/251-guardian-modules/tasks.md +++ b/speckit/features/251-guardian-modules/tasks.md @@ -154,9 +154,9 @@ - [X] T040 [US5] Superseded by the T039 design (RFC revision 29): the copy is written after the claim on both backends through `ModuleStore::seed_assignment`, only into an account with no assignment and no history; the unfinished-claim retry repeats a copy a crash interrupted (P0 T094) - [X] T041 [US5] `params_drift` against `seeded_params`, `GUARDIAN_MODULE_PARAMS_MAX_BYTES` on every params write, and paginated history (`?before=&limit=`) in `crates/server/src/modules/admin.rs`, `store.rs` and `postgres_store.rs` (P0 T090) - [X] T042 [US5] `orphaned` on account view rows naming an instance the catalog no longer declares (skipped at evaluation, counted at startup) and an `undeclared` list of such stored instances in `GET /dashboard/modules` (contract revised from a per-instance `declared` flag) in `crates/server/src/modules/admin.rs` -- [ ] T043 [US5] Migrate account layers and assignments that a module normalizes when validating params, at startup and before enabling, with a compare-and-set against the read value, in `crates/server/src/modules/registry.rs` and both stores (P0 T073) +- [X] T043 [US5] Dropped: RFC 0002 section 3.5 ("Parameter migration") has account layers and assignments migrate when they are next written, and requires modules to keep accepting their previous shapes until then; only global params migrate at startup and before enabling, which the prototype does (P0 T073) - [ ] T044 [US5] Module routes in `packages/guardian-operator-client/src/` (list, account modules read and replace, global params, account layer set and delete, history, enable, disable) with types matching `speckit/features/251-guardian-modules/contracts/operator-modules-api.md`, and its README -- [ ] T045 [US5] OpenAPI entries for the `/dashboard/modules` and account module routes (`utoipa` annotations in `crates/server/src/api/dashboard_modules.rs`), regenerated into `docs/openapi-dashboard.json` +- [X] T045 [US5] OpenAPI entries for the `/dashboard/modules` and account module routes (`utoipa` annotations in `crates/server/src/api/dashboard_modules.rs`), regenerated into `docs/openapi-dashboard.json` - [ ] T046 [US5] Smoke the operator routes through `examples/operator-smoke-web` with the `smoke-test-operator-dashboard` skill, and document the routes and permissions in `docs/DASHBOARD.md` ("Policy modules") **Checkpoint**: US5 acceptance scenarios 1 to 16 pass and SC-009, SC-012 hold. From b48bf558a8ab64ffadee1f8075d084d8aa8577fe Mon Sep 17 00:00:00 2001 From: Zeljko Date: Mon, 9 Nov 2026 11:27:46 +0100 Subject: [PATCH 031/105] feat(operator-client): policy module routes (#251) @openzeppelin/guardian-operator-client gains listModules, getAccountModules, getModuleParamsHistory (before and limit), setModuleGlobalParams, enableModule, disableModule, setAccountModuleLayer, removeAccountModuleLayer and setAccountModules, with types matching the operator module API and strict parsing of scopes, disclosure, client reasons and circuit states. History entries' previous and new are null when the module was not assigned before, or was removed, which the server schema now says. docs/DASHBOARD.md and the client README document the routes, limits and views. --- crates/server/src/modules/store.rs | 4 +- docs/DASHBOARD.md | 19 +- docs/openapi-dashboard.json | 12 +- packages/guardian-operator-client/README.md | 24 ++ .../guardian-operator-client/src/http.test.ts | 155 +++++++++++ packages/guardian-operator-client/src/http.ts | 240 ++++++++++++++++++ .../guardian-operator-client/src/index.ts | 14 + .../guardian-operator-client/src/types.ts | 96 +++++++ .../features/251-guardian-modules/tasks.md | 8 +- 9 files changed, 559 insertions(+), 13 deletions(-) diff --git a/crates/server/src/modules/store.rs b/crates/server/src/modules/store.rs index 17d485fe..d33fa0b5 100644 --- a/crates/server/src/modules/store.rs +++ b/crates/server/src/modules/store.rs @@ -58,9 +58,9 @@ pub struct HistoryEntry { pub module_id: String, #[serde(default, skip_serializing_if = "Option::is_none")] pub account_id: Option, - #[schema(value_type = Object)] + #[schema(value_type = Option)] pub previous: serde_json::Value, - #[schema(value_type = Object)] + #[schema(value_type = Option)] pub new: serde_json::Value, pub operator: String, pub reason: String, diff --git a/docs/DASHBOARD.md b/docs/DASHBOARD.md index 20650701..e93b0151 100644 --- a/docs/DASHBOARD.md +++ b/docs/DASHBOARD.md @@ -360,7 +360,7 @@ the parser rejects both. ## Policy modules -Prototype (RFC 0002, issue #251); not in a release yet. The endpoints +M2a (RFC 0002, issue #251); not in a release yet. The endpoints manage the module instances the catalog file declares ([`GUARDIAN_MODULES_CONFIG`](./CONFIGURATION.md#runtime-policy-modules)); they cannot add, remove or reconfigure an instance. Every write takes a @@ -371,7 +371,7 @@ in the params history and the audit log. A walkthrough is in the | Endpoint | Permission | Body | |---|---|---| | `GET /dashboard/modules` | `dashboard:read` | | -| `GET /dashboard/modules/{module_id}/params/history` | `dashboard:read` | | +| `GET /dashboard/modules/{module_id}/params/history?before=&limit=` | `dashboard:read` | | | `GET /dashboard/accounts/{account_id}/modules` | `dashboard:read` | | | `PUT /dashboard/modules/{module_id}/params` | `policies:write_global` | `{"params": {...}, "reason": "..."}` | | `PUT /dashboard/accounts/{account_id}/modules/{module_id}/params` | `policies:write` | `{"params": {...}, "reason": "..."}` | @@ -382,9 +382,22 @@ in the params history and the audit log. A walkthrough is in the On a `scope = all` instance the per-account params are a layer evaluated after the global params, and both must allow, so a layer only adds -restrictions. Disabling an instance the catalog does not mark +restrictions. A `scope = default` instance is copied into an account's +assignment when it first registers and is then replaced or removed with the +account's other assignments; a `scope = assigned` one applies only where it +is assigned. Disabling an instance the catalog does not mark `operator_can_disable` returns `409 GUARDIAN_MODULE_NOT_DISABLEABLE`. +Writes are refused with `400 invalid_input` when the params exceed +`GUARDIAN_MODULE_PARAMS_MAX_BYTES`, or when the account's modules could exceed +the evaluation budget afterwards (each `all` instance, again for its layer, +plus each assigned one). `GET /dashboard/modules` reports each instance's +`circuit` on the answering replica, `params_drift` against the params seeded +from the catalog file, and under `undeclared` the stored instances the catalog +no longer declares. An account's entries naming such an instance are marked +`orphaned` and skipped. The history is newest first, at most 100 entries per +page by default (1,000 at most), and `before` pages backwards by version. + ## Account pausing Operators holding `accounts:pause` can halt and resume an account's diff --git a/docs/openapi-dashboard.json b/docs/openapi-dashboard.json index 5af26a4c..267eec9e 100644 --- a/docs/openapi-dashboard.json +++ b/docs/openapi-dashboard.json @@ -4191,8 +4191,6 @@ "required": [ "version", "module_id", - "previous", - "new", "operator", "reason", "at" @@ -4211,13 +4209,19 @@ "type": "string" }, "new": { - "type": "object" + "type": [ + "object", + "null" + ] }, "operator": { "type": "string" }, "previous": { - "type": "object" + "type": [ + "object", + "null" + ] }, "reason": { "type": "string" diff --git a/packages/guardian-operator-client/README.md b/packages/guardian-operator-client/README.md index 22bc2721..28528683 100644 --- a/packages/guardian-operator-client/README.md +++ b/packages/guardian-operator-client/README.md @@ -290,6 +290,30 @@ for (const entry of page.items) { } ``` +### Policy Modules + +Manage the policy module instances the Guardian's catalog declares. Every +write takes a reason and is validated by the module before it is stored. + +```ts +const catalog = await client.listModules(); +// catalog.modules: [{ moduleId, scope, enabled, circuit, params, paramsDrift, ... }] +// catalog.undeclared: stored instances the catalog no longer declares + +await client.setModuleGlobalParams('blocklist', { recipient_denylist: ['0xaaa'] }, 'OP-90'); // policies:write_global +await client.setAccountModuleLayer(accountId, 'blocklist', { recipient_denylist: ['0xccc'] }, 'OP-91'); // policies:write +await client.removeAccountModuleLayer(accountId, 'blocklist', 'OP-92'); +await client.setAccountModules(accountId, [{ moduleId: 'treasury-allowlist', params: {} }], 'OP-93'); +await client.disableModule('risk-scorer', 'incident'); // policies:write or modules:disable +await client.enableModule('risk-scorer', 'recovered'); // policies:write + +const modules = await client.getAccountModules(accountId); // evaluation order; orphaned entries are skipped +const page = await client.getModuleParamsHistory('blocklist', { limit: 50 }); // newest first +const older = await client.getModuleParamsHistory('blocklist', { + before: page.entries[page.entries.length - 1].version, +}); +``` + ### Logout ```typescript diff --git a/packages/guardian-operator-client/src/http.test.ts b/packages/guardian-operator-client/src/http.test.ts index 78134c7e..0e926433 100644 --- a/packages/guardian-operator-client/src/http.test.ts +++ b/packages/guardian-operator-client/src/http.test.ts @@ -2241,6 +2241,141 @@ describe('GuardianOperatorHttpClient — account pausing (feature 001)', () => { ); }); + it('lists module instances, decoding runtime state and undeclared instances', async () => { + mockFetch.mockResolvedValueOnce( + okJson({ + catalog_hash: '0xcafe', + params_version: 7, + modules: [INSTANCE], + undeclared: [{ module_id: 'retired', enabled: false, params: {} }], + }), + ); + const client = new GuardianOperatorHttpClient('https://guardian.example'); + const catalog = await client.listModules(); + expect(catalog.catalogHash).toBe('0xcafe'); + expect(catalog.paramsVersion).toBe(7); + expect(catalog.modules[0]).toMatchObject({ + moduleId: 'caps', + scope: 'all', + circuit: 'closed', + operatorCanDisable: true, + params: { max_amount_per_tx: { '0xaa': '5' } }, + }); + expect(catalog.undeclared).toEqual([{ moduleId: 'retired', enabled: false, params: {} }]); + expect(mockFetch).toHaveBeenCalledWith( + 'https://guardian.example/dashboard/modules', + expect.objectContaining({ method: 'GET' }), + ); + }); + + it('refuses a module instance with an unknown circuit state or scope', async () => { + const client = new GuardianOperatorHttpClient('https://guardian.example'); + for (const broken of [{ circuit: 'ajar' }, { scope: 'sometimes' }]) { + mockFetch.mockResolvedValueOnce( + okJson({ catalog_hash: '0x', params_version: 0, modules: [{ ...INSTANCE, ...broken }], undeclared: [] }), + ); + await expect(client.listModules()).rejects.toThrow(/unknown value/); + } + }); + + it('reads and writes an account module set', async () => { + const view = { + account_id: 'acc-1', + modules: [ + { module_id: 'caps', scope: 'all', enabled: true, orphaned: false, global_params: {}, account_layer: { cap: 1 } }, + { module_id: 'screening', scope: 'default', enabled: true, orphaned: false, params: { list: 'eu' } }, + { module_id: 'retired', scope: 'assigned', enabled: false, orphaned: true, params: {} }, + ], + }; + const client = new GuardianOperatorHttpClient('https://guardian.example'); + + mockFetch.mockResolvedValueOnce(okJson(view)); + const modules = await client.getAccountModules('acc-1'); + expect(modules.modules.map((entry) => [entry.moduleId, entry.scope, entry.orphaned])).toEqual([ + ['caps', 'all', false], + ['screening', 'default', false], + ['retired', 'assigned', true], + ]); + expect(modules.modules[0].accountLayer).toEqual({ cap: 1 }); + expect(modules.modules[1].globalParams).toBeNull(); + + mockFetch.mockResolvedValueOnce(okJson(view)); + await client.setAccountModules('acc-1', [{ moduleId: 'screening', params: { list: 'eu' } }], 'OP-1'); + expect(mockFetch).toHaveBeenLastCalledWith( + 'https://guardian.example/dashboard/accounts/acc-1/modules', + expect.objectContaining({ + method: 'PUT', + body: JSON.stringify({ modules: [{ module_id: 'screening', params: { list: 'eu' } }], reason: 'OP-1' }), + }), + ); + + mockFetch.mockResolvedValueOnce(okJson(view)); + await client.setAccountModuleLayer('acc-1', 'caps', { cap: 1 }, 'OP-2'); + expect(mockFetch).toHaveBeenLastCalledWith( + 'https://guardian.example/dashboard/accounts/acc-1/modules/caps/params', + expect.objectContaining({ method: 'PUT', body: JSON.stringify({ params: { cap: 1 }, reason: 'OP-2' }) }), + ); + + mockFetch.mockResolvedValueOnce(okJson(view)); + await client.removeAccountModuleLayer('acc-1', 'caps', 'OP-3'); + expect(mockFetch).toHaveBeenLastCalledWith( + 'https://guardian.example/dashboard/accounts/acc-1/modules/caps/params', + expect.objectContaining({ method: 'DELETE', body: JSON.stringify({ reason: 'OP-3' }) }), + ); + }); + + it('writes global params, switches instances and pages the history', async () => { + const client = new GuardianOperatorHttpClient('https://guardian.example'); + + mockFetch.mockResolvedValueOnce(okJson(INSTANCE)); + await client.setModuleGlobalParams('caps', { max_amount_per_tx: {} }, 'OP-4'); + expect(mockFetch).toHaveBeenLastCalledWith( + 'https://guardian.example/dashboard/modules/caps/params', + expect.objectContaining({ method: 'PUT', body: JSON.stringify({ params: { max_amount_per_tx: {} }, reason: 'OP-4' }) }), + ); + + mockFetch.mockResolvedValueOnce(okJson({ ...INSTANCE, enabled: false })); + expect((await client.disableModule('caps', 'OP-5')).enabled).toBe(false); + expect(mockFetch).toHaveBeenLastCalledWith( + 'https://guardian.example/dashboard/modules/caps/disable', + expect.objectContaining({ method: 'POST', body: JSON.stringify({ reason: 'OP-5' }) }), + ); + + mockFetch.mockResolvedValueOnce(okJson(INSTANCE)); + expect((await client.enableModule('caps', 'OP-6')).enabled).toBe(true); + + mockFetch.mockResolvedValueOnce( + okJson({ + module_id: 'caps', + entries: [ + { version: 9, account_id: 'acc-1', previous: null, new: { cap: 1 }, operator: '0xop', reason: 'OP-2', at: 't9' }, + { version: 8, previous: { a: 1 }, new: { a: 2 }, operator: '0xop', reason: 'OP-1', at: 't8' }, + ], + }), + ); + const history = await client.getModuleParamsHistory('caps', { before: 10, limit: 2 }); + expect(history.entries.map((entry) => [entry.version, entry.accountId, entry.previous])).toEqual([ + [9, 'acc-1', null], + [8, null, { a: 1 }], + ]); + expect(mockFetch).toHaveBeenLastCalledWith( + 'https://guardian.example/dashboard/modules/caps/params/history?before=10&limit=2', + expect.objectContaining({ method: 'GET' }), + ); + }); + + it('surfaces a refused disable as an HTTP error', async () => { + mockFetch.mockResolvedValueOnce({ + ok: false, + status: 409, + statusText: 'Conflict', + text: async () => + JSON.stringify({ code: 'GUARDIAN_MODULE_NOT_DISABLEABLE', message: 'protected', meta: { retryable: false } }), + }); + const client = new GuardianOperatorHttpClient('https://guardian.example'); + await expect(client.disableModule('vendor', 'OP-7')).rejects.toMatchObject({ status: 409 }); + }); + it('parses a successful pauseAccount response', async () => { mockFetch.mockResolvedValueOnce( okJson({ @@ -2589,6 +2724,26 @@ describe('GuardianOperatorHttpClient — account pause/unpause', () => { }); }); +const INSTANCE = { + module_id: 'caps', + kind: 'basic-policy', + scope: 'all', + hooks: ['before_transaction_approved'], + enabled: true, + catalog_enabled: true, + enabled_drift: false, + operator_can_disable: true, + params: { max_amount_per_tx: { '0xaa': '5' } }, + params_drift: false, + file_managed_params: false, + build: 'basic-policy 0.19.0', + disclosure: 'params', + description: 'At most 5 per transaction', + client_reason: 'full', + dry_run: true, + circuit: 'closed', + }; + function okJson(payload: unknown) { return { ok: true, diff --git a/packages/guardian-operator-client/src/http.ts b/packages/guardian-operator-client/src/http.ts index 5e6f6472..6a06d1d3 100644 --- a/packages/guardian-operator-client/src/http.ts +++ b/packages/guardian-operator-client/src/http.ts @@ -17,6 +17,20 @@ import type { DashboardDeltaNoteCounts, DashboardDeltaNoteTag, DashboardDeltaProposalMetadata, + AccountModuleEntry, + AccountModules, + ModuleAssignment, + ModuleCatalog, + ModuleCircuit, + ModuleClientReason, + ModuleDisclosure, + ModuleInstance, + ModuleParams, + ModuleParamsHistory, + ModuleParamsHistoryEntry, + ModuleParamsHistoryOptions, + ModuleScope, + UndeclaredModuleInstance, DashboardDeltaStatus, DashboardDeltaStorageChange, DashboardDeltaVaultChange, @@ -654,6 +668,109 @@ export class GuardianOperatorHttpClient { return this.request(url, { method: 'GET' }, parseGlobalProposalsPage); } + /** Every declared module instance with its runtime state, and stored instances the catalog + * no longer declares. Requires `dashboard:read`. */ + async listModules(): Promise { + return this.request(new URL('dashboard/modules', this.baseUrl), { method: 'GET' }, parseModuleCatalog); + } + + /** The account's effective module set, in evaluation order. Requires `dashboard:read`. */ + async getAccountModules(accountId: string): Promise { + return this.request( + new URL(`dashboard/accounts/${encodeURIComponent(accountId)}/modules`, this.baseUrl), + { method: 'GET' }, + parseAccountModules, + ); + } + + /** The instance's params changes, global and per account, newest first. Requires + * `dashboard:read`. */ + async getModuleParamsHistory( + moduleId: string, + options: ModuleParamsHistoryOptions = {}, + ): Promise { + const url = new URL(`dashboard/modules/${encodeURIComponent(moduleId)}/params/history`, this.baseUrl); + if (options.before !== undefined) url.searchParams.set('before', String(options.before)); + if (options.limit !== undefined) url.searchParams.set('limit', String(options.limit)); + return this.request(url, { method: 'GET' }, parseModuleParamsHistory); + } + + /** Replaces an instance's global params, which every account shares. Requires + * `policies:write_global`. */ + async setModuleGlobalParams(moduleId: string, params: ModuleParams, reason: string): Promise { + return this.request( + new URL(`dashboard/modules/${encodeURIComponent(moduleId)}/params`, this.baseUrl), + { method: 'PUT', body: JSON.stringify({ params, reason }) }, + (value) => parseModuleInstance(value, 'module instance'), + ); + } + + /** Enables an instance after re-running its startup checks. Requires `policies:write`. */ + async enableModule(moduleId: string, reason: string): Promise { + return this.request( + new URL(`dashboard/modules/${encodeURIComponent(moduleId)}/enable`, this.baseUrl), + { method: 'POST', body: JSON.stringify({ reason }) }, + (value) => parseModuleInstance(value, 'module instance'), + ); + } + + /** Disables an instance the catalog marks `operator_can_disable`. Requires + * `policies:write` or `modules:disable`. */ + async disableModule(moduleId: string, reason: string): Promise { + return this.request( + new URL(`dashboard/modules/${encodeURIComponent(moduleId)}/disable`, this.baseUrl), + { method: 'POST', body: JSON.stringify({ reason }) }, + (value) => parseModuleInstance(value, 'module instance'), + ); + } + + /** Sets this account's layer on a `scope = all` instance, which can only add restrictions. + * Requires `policies:write`. */ + async setAccountModuleLayer( + accountId: string, + moduleId: string, + params: ModuleParams, + reason: string, + ): Promise { + return this.request( + this.accountModuleParamsUrl(accountId, moduleId), + { method: 'PUT', body: JSON.stringify({ params, reason }) }, + parseAccountModules, + ); + } + + /** Removes this account's layer on a `scope = all` instance. Requires `policies:write`. */ + async removeAccountModuleLayer(accountId: string, moduleId: string, reason: string): Promise { + return this.request( + this.accountModuleParamsUrl(accountId, moduleId), + { method: 'DELETE', body: JSON.stringify({ reason }) }, + parseAccountModules, + ); + } + + /** Replaces the account's `default` and `assigned` modules with `modules`, in evaluation + * order. Requires `policies:write`. */ + async setAccountModules(accountId: string, modules: ModuleAssignment[], reason: string): Promise { + return this.request( + new URL(`dashboard/accounts/${encodeURIComponent(accountId)}/modules`, this.baseUrl), + { + method: 'PUT', + body: JSON.stringify({ + modules: modules.map((module) => ({ module_id: module.moduleId, params: module.params })), + reason, + }), + }, + parseAccountModules, + ); + } + + private accountModuleParamsUrl(accountId: string, moduleId: string): URL { + return new URL( + `dashboard/accounts/${encodeURIComponent(accountId)}/modules/${encodeURIComponent(moduleId)}/params`, + this.baseUrl, + ); + } + private async request( url: URL, init: RequestInit, @@ -2385,3 +2502,126 @@ function parseDeltaStatus( `expected status to be "candidate" / "canonical" / "retained" / "discarded", got ${JSON.stringify(value)}`, ); } + +function requireOneOf( + record: Record, + key: string, + allowed: readonly T[], + context: string, +): T { + const value = requireString(record, key, context); + if (!(allowed as readonly string[]).includes(value)) { + throw new GuardianOperatorContractError(context, `field "${key}" has unknown value "${value}"`); + } + return value as T; +} + +function requireParams(record: Record, key: string, context: string): ModuleParams { + return asRecord(requireField(record, key, context), `${context}.${key}`); +} + +function optionalParams(record: Record, key: string, context: string): ModuleParams | null { + const value = record[key]; + return value === undefined || value === null ? null : asRecord(value, `${context}.${key}`); +} + +function nullableParams(record: Record, key: string, context: string): ModuleParams | null { + const value = requireField(record, key, context); + return value === null ? null : asRecord(value, `${context}.${key}`); +} + +function optionalString(record: Record, key: string, context: string): string | null { + const value = record[key]; + if (value === undefined || value === null) return null; + if (typeof value !== 'string') { + throw new GuardianOperatorContractError(context, `field "${key}" must be a string`); + } + return value; +} + +const MODULE_SCOPES = ['all', 'default', 'assigned'] as const; + +function parseModuleInstance(value: unknown, context: string): ModuleInstance { + const record = asRecord(value, context); + return { + moduleId: requireString(record, 'module_id', context), + kind: requireString(record, 'kind', context), + scope: requireOneOf(record, 'scope', MODULE_SCOPES, context), + hooks: requireStringArray(record, 'hooks', context), + enabled: requireBoolean(record, 'enabled', context), + catalogEnabled: requireBoolean(record, 'catalog_enabled', context), + enabledDrift: requireBoolean(record, 'enabled_drift', context), + operatorCanDisable: requireBoolean(record, 'operator_can_disable', context), + params: requireParams(record, 'params', context), + paramsDrift: requireBoolean(record, 'params_drift', context), + fileManagedParams: requireBoolean(record, 'file_managed_params', context), + build: optionalString(record, 'build', context), + disclosure: requireOneOf(record, 'disclosure', ['none', 'summary', 'params'] as const, context), + description: optionalString(record, 'description', context), + clientReason: requireOneOf(record, 'client_reason', ['full', 'generic'] as const, context), + dryRun: requireBoolean(record, 'dry_run', context), + circuit: requireOneOf(record, 'circuit', ['closed', 'open', 'half_open'] as const, context), + }; +} + +function parseModuleCatalog(value: unknown): ModuleCatalog { + const context = 'module catalog'; + const record = asRecord(value, context); + return { + catalogHash: requireString(record, 'catalog_hash', context), + paramsVersion: requireInteger(record, 'params_version', context), + modules: requireArray(record, 'modules', context).map((entry) => + parseModuleInstance(entry, `${context}.modules`), + ), + undeclared: requireArray(record, 'undeclared', context).map((entry) => { + const item = asRecord(entry, `${context}.undeclared`); + return { + moduleId: requireString(item, 'module_id', `${context}.undeclared`), + enabled: requireBoolean(item, 'enabled', `${context}.undeclared`), + params: requireParams(item, 'params', `${context}.undeclared`), + }; + }), + }; +} + +function parseAccountModules(value: unknown): AccountModules { + const context = 'account modules'; + const record = asRecord(value, context); + return { + accountId: requireString(record, 'account_id', context), + modules: requireArray(record, 'modules', context).map((entry) => { + const item = asRecord(entry, `${context}.modules`); + const itemContext = `${context}.modules`; + return { + moduleId: requireString(item, 'module_id', itemContext), + scope: requireOneOf(item, 'scope', MODULE_SCOPES, itemContext), + enabled: requireBoolean(item, 'enabled', itemContext), + orphaned: requireBoolean(item, 'orphaned', itemContext), + globalParams: optionalParams(item, 'global_params', itemContext), + accountLayer: optionalParams(item, 'account_layer', itemContext), + params: optionalParams(item, 'params', itemContext), + }; + }), + }; +} + +function parseModuleParamsHistory(value: unknown): ModuleParamsHistory { + const context = 'module params history'; + const record = asRecord(value, context); + return { + moduleId: requireString(record, 'module_id', context), + entries: requireArray(record, 'entries', context).map((entry) => { + const item = asRecord(entry, `${context}.entries`); + const itemContext = `${context}.entries`; + return { + version: requireInteger(item, 'version', itemContext), + accountId: optionalString(item, 'account_id', itemContext), + previous: nullableParams(item, 'previous', itemContext), + new: nullableParams(item, 'new', itemContext), + operator: requireString(item, 'operator', itemContext), + reason: requireString(item, 'reason', itemContext), + at: requireString(item, 'at', itemContext), + }; + }), + }; +} diff --git a/packages/guardian-operator-client/src/index.ts b/packages/guardian-operator-client/src/index.ts index 7fff24cb..4df4bc4e 100644 --- a/packages/guardian-operator-client/src/index.ts +++ b/packages/guardian-operator-client/src/index.ts @@ -18,6 +18,20 @@ export { export type { OperatorPermission } from './permissions.js'; export type { + AccountModuleEntry, + AccountModules, + ModuleAssignment, + ModuleCatalog, + ModuleCircuit, + ModuleClientReason, + ModuleDisclosure, + ModuleInstance, + ModuleParams, + ModuleParamsHistory, + ModuleParamsHistoryEntry, + ModuleParamsHistoryOptions, + ModuleScope, + UndeclaredModuleInstance, AccountPausedErrorDetails, AccountReleasedErrorDetails, AccountStatus, diff --git a/packages/guardian-operator-client/src/types.ts b/packages/guardian-operator-client/src/types.ts index 584f6c8c..522e437e 100644 --- a/packages/guardian-operator-client/src/types.ts +++ b/packages/guardian-operator-client/src/types.ts @@ -840,3 +840,99 @@ export interface DashboardInfoResponse { inFlightProposalCount: number; degradedAggregates: string[]; } + +// --- Policy modules -------------------------------------------------------- + +export type ModuleScope = 'all' | 'default' | 'assigned'; +export type ModuleDisclosure = 'none' | 'summary' | 'params'; +export type ModuleClientReason = 'full' | 'generic'; +export type ModuleCircuit = 'closed' | 'open' | 'half_open'; +export type ModuleParams = Record; + +/** One declared module instance with its runtime state on the answering replica. */ +export interface ModuleInstance { + moduleId: string; + kind: string; + scope: ModuleScope; + hooks: string[]; + enabled: boolean; + catalogEnabled: boolean; + enabledDrift: boolean; + operatorCanDisable: boolean; + /** Current global params; secret references are shown unresolved. */ + params: ModuleParams; + paramsDrift: boolean; + fileManagedParams: boolean; + /** `name version` from `describe` at startup; `null` when the startup checks failed. */ + build: string | null; + disclosure: ModuleDisclosure; + description: string | null; + clientReason: ModuleClientReason; + dryRun: boolean; + circuit: ModuleCircuit; +} + +/** A stored instance the catalog no longer declares: kept, never evaluated. */ +export interface UndeclaredModuleInstance { + moduleId: string; + enabled: boolean; + params: ModuleParams; +} + +export interface ModuleCatalog { + catalogHash: string; + paramsVersion: number; + modules: ModuleInstance[]; + undeclared: UndeclaredModuleInstance[]; +} + +/** One module in an account's effective set, in evaluation order. */ +export interface AccountModuleEntry { + moduleId: string; + scope: ModuleScope; + enabled: boolean; + /** The entry names an instance the catalog no longer declares; it is skipped. */ + orphaned: boolean; + /** `scope = all`: the instance's global params. */ + globalParams: ModuleParams | null; + /** `scope = all`: this account's layer, when set. */ + accountLayer: ModuleParams | null; + /** `default` or `assigned`: this account's own params. */ + params: ModuleParams | null; +} + +export interface AccountModules { + accountId: string; + modules: AccountModuleEntry[]; +} + +export interface ModuleAssignment { + moduleId: string; + params: ModuleParams; +} + +export interface ModuleParamsHistoryEntry { + version: number; + /** The account a per-account change applied to; `null` for a global change. */ + accountId: string | null; + /** `null` when the module was not assigned before the change. */ + previous: ModuleParams | null; + /** `null` when the change removed the module or the layer. */ + new: ModuleParams | null; + operator: string; + reason: string; + at: string; +} + +export interface ModuleParamsHistory { + moduleId: string; + /** Newest first. */ + entries: ModuleParamsHistoryEntry[]; +} + +export interface ModuleParamsHistoryOptions { + /** Only changes with a version below this one, to page backwards. */ + before?: number; + /** At most this many entries (1 to 1,000; the server defaults to 100). */ + limit?: number; +} diff --git a/speckit/features/251-guardian-modules/tasks.md b/speckit/features/251-guardian-modules/tasks.md index d15aaba2..d8873853 100644 --- a/speckit/features/251-guardian-modules/tasks.md +++ b/speckit/features/251-guardian-modules/tasks.md @@ -146,7 +146,7 @@ ### Tests for User Story 5 - [X] T037 [P] [US5] `default` copy tests in `crates/server/src/services/configure_account.rs`: the copy carries the evaluated params and is written with the claim on Postgres; on the filesystem it replaces an earlier unclaimed attempt's copy; an unfinished claim with no assignment history repeats it, one an operator emptied does not -- [ ] T038 [P] [US5] Operator client tests in `packages/guardian-operator-client/src/` for every module route, including permission errors for `modules:disable` holders +- [X] T038 [P] [US5] Operator client tests in `packages/guardian-operator-client/src/` for every module route, including permission errors for `modules:disable` holders ### Implementation for User Story 5 @@ -155,9 +155,9 @@ - [X] T041 [US5] `params_drift` against `seeded_params`, `GUARDIAN_MODULE_PARAMS_MAX_BYTES` on every params write, and paginated history (`?before=&limit=`) in `crates/server/src/modules/admin.rs`, `store.rs` and `postgres_store.rs` (P0 T090) - [X] T042 [US5] `orphaned` on account view rows naming an instance the catalog no longer declares (skipped at evaluation, counted at startup) and an `undeclared` list of such stored instances in `GET /dashboard/modules` (contract revised from a per-instance `declared` flag) in `crates/server/src/modules/admin.rs` - [X] T043 [US5] Dropped: RFC 0002 section 3.5 ("Parameter migration") has account layers and assignments migrate when they are next written, and requires modules to keep accepting their previous shapes until then; only global params migrate at startup and before enabling, which the prototype does (P0 T073) -- [ ] T044 [US5] Module routes in `packages/guardian-operator-client/src/` (list, account modules read and replace, global params, account layer set and delete, history, enable, disable) with types matching `speckit/features/251-guardian-modules/contracts/operator-modules-api.md`, and its README +- [X] T044 [US5] Module routes in `packages/guardian-operator-client/src/` (list, account modules read and replace, global params, account layer set and delete, history, enable, disable) with types matching `speckit/features/251-guardian-modules/contracts/operator-modules-api.md`, and its README - [X] T045 [US5] OpenAPI entries for the `/dashboard/modules` and account module routes (`utoipa` annotations in `crates/server/src/api/dashboard_modules.rs`), regenerated into `docs/openapi-dashboard.json` -- [ ] T046 [US5] Smoke the operator routes through `examples/operator-smoke-web` with the `smoke-test-operator-dashboard` skill, and document the routes and permissions in `docs/DASHBOARD.md` ("Policy modules") +- [X] T046 [US5] Document the routes, permissions, limits, `undeclared`, `orphaned` and history paging in `docs/DASHBOARD.md` ("Policy modules"); the browser smoke of these routes through `examples/operator-smoke-web` runs with the other smokes in T058 **Checkpoint**: US5 acceptance scenarios 1 to 16 pass and SC-009, SC-012 hold. @@ -194,7 +194,7 @@ - [ ] T055 [P] Protocol spec coverage: module error codes and `meta` on proposal creation, push and registration, `GET /policies` and `POST /delta/proposal/check` in `spec/api.md`, and the gate points in the push, proposal and registration processes of `spec/processes.md` - [ ] T056 [P] Client READMEs for module errors and `moduleRefusal()` / `module_refusal()`: `crates/client/README.md`, `packages/guardian-client/README.md`, `crates/miden-multisig-client/README.md`, `packages/miden-multisig-client/README.md` - [ ] T057 Rust and TypeScript parity fixture: one shared JSON fixture of module error bodies under `packages/guardian-client/src/` (or the repo's existing shared fixture location) driving both `crates/client` and `packages/guardian-client` tests, so SC-010 is checked by the same cases -- [ ] T058 End-to-end smokes with a catalog: `smoke-test-rust-multisig-sdk` and `smoke-test-ts-multisig-sdk` skills, refusal at creation, push and registration, and `examples/demo` and `examples/web` with and without a catalog (quickstart section 5) +- [ ] T058 End-to-end smokes with a catalog: `smoke-test-rust-multisig-sdk` and `smoke-test-ts-multisig-sdk` skills, refusal at creation, push and registration, and `examples/demo` and `examples/web` with and without a catalog (quickstart section 5); and the operator module routes, including `modules:disable` permission errors, through `examples/operator-smoke-web` with the `smoke-test-operator-dashboard` skill - [ ] T059 Quickstart walk-through against a local node with the filesystem backend and the latency A/B (zero, one in-process, one remote module), results in `speckit/features/251-guardian-modules/research.md` (P0 T033; SC-001, SC-006) - [ ] T060 SC-004 run: enable `basic-policy` on all accounts with the official image and the guides only, timed, gaps fixed in `docs/guides/policy-modules/` - [ ] T061 Re-check the TLA+ models whose fingerprints the modules work moved (`verify-auth-replay`, `verify-candidate-queue`, `verify-client-sync`, `verify-guardian-switch`, `verify-module-counting`, `verify-multisig-push-gate`, `verify-proposal-lifecycle` under `.agents/skills/`) with each `check.sh`, then `--accept-drift` once the model still mirrors the code From b348a89a4fc268d085af9142b4e652dcd8fcf677 Mon Sep 17 00:00:00 2001 From: Zeljko Date: Mon, 9 Nov 2026 11:32:47 +0100 Subject: [PATCH 032/105] feat(module-sdk): reusable conformance suite (#251) Suite runs a module in process and through the serve harness with two instances on one service, and checks Describe, params validation on both transports, identical outcomes, no side effects in evaluate (repeated, reversed and concurrent), decision shape, per-instance credentials and a request at the size cap. basic-policy runs it. DEFAULT_REQUEST_MAX_BYTES is shared with the server limits; Module is implemented for Arc. --- crates/guardian-module-sdk/Cargo.toml | 6 + crates/guardian-module-sdk/src/conformance.rs | 727 ++++++++++++++++++ crates/guardian-module-sdk/src/lib.rs | 29 + crates/guardian-module-sdk/src/serve.rs | 2 +- .../guardian-module-sdk/tests/conformance.rs | 110 ++- crates/server/src/modules/limits.rs | 2 +- .../features/251-guardian-modules/tasks.md | 2 +- 7 files changed, 835 insertions(+), 43 deletions(-) create mode 100644 crates/guardian-module-sdk/src/conformance.rs diff --git a/crates/guardian-module-sdk/Cargo.toml b/crates/guardian-module-sdk/Cargo.toml index b5fc6660..09cfea77 100644 --- a/crates/guardian-module-sdk/Cargo.toml +++ b/crates/guardian-module-sdk/Cargo.toml @@ -21,5 +21,11 @@ tokio = { workspace = true, features = ["rt-multi-thread", "macros", "net", "fs" tonic = { workspace = true } tonic-prost = { workspace = true } +[features] +conformance = [] + +[dev-dependencies] +guardian-module-sdk = { path = ".", features = ["conformance"] } + [build-dependencies] tonic-prost-build = { workspace = true } diff --git a/crates/guardian-module-sdk/src/conformance.rs b/crates/guardian-module-sdk/src/conformance.rs new file mode 100644 index 00000000..a2357dcd --- /dev/null +++ b/crates/guardian-module-sdk/src/conformance.rs @@ -0,0 +1,727 @@ +//! Conformance suite for stateless modules. +//! +//! [`Suite`] runs one module in process and through the [`serve`](crate::serve) harness over +//! loopback gRPC, with two instances on one service, and checks that it answers `Describe` +//! for protocol version 1, validates params the same way on both transports, returns the same +//! outcome for every request on both transports, keeps `evaluate` free of side effects +//! (repeated, reordered and concurrent evaluations agree), returns well-formed decisions, and +//! accepts a request at the Guardian's size cap. +//! +//! ```no_run +//! # async fn example(request: guardian_module_sdk::HookRequest) { +//! use guardian_module_sdk::basic_policy::BasicPolicy; +//! use guardian_module_sdk::conformance::Suite; +//! +//! Suite::new(BasicPolicy) +//! .request("small payment", request) +//! .valid_params(serde_json::json!({ "recipient_denylist": [] })) +//! .invalid_params(serde_json::json!({ "unknown": 1 })) +//! .run() +//! .await +//! .assert_conformant(); +//! # } +//! ``` + +use std::fmt; +use std::sync::Arc; + +use tokio::net::TcpListener; +use tokio::sync::oneshot; +use tokio::task::JoinSet; +use tonic::Request; +use tonic::metadata::MetadataValue; +use tonic::transport::server::TcpIncoming; +use tonic::transport::{Channel, Server}; + +use crate::proto::guardian_module_client::GuardianModuleClient; +use crate::proto::hook_request; +use crate::serve::{serve, status}; +use crate::{ + DEFAULT_REQUEST_MAX_BYTES, Decision, DescribeRequest, Effect, Hook, HookRequest, Module, + PROTOCOL_VERSION, ParamsVerdict, RawTransaction, ValidateParamsRequest, is_valid_reason_code, +}; + +const INSTANCE_A: &str = "conformance-a"; +const INSTANCE_B: &str = "conformance-b"; +const TOKEN_A: &str = "conformance-token-a"; +const TOKEN_B: &str = "conformance-token-b"; +const CLIENT_MESSAGE_MAX_CHARS: usize = 256; +const REPEATS: usize = 3; +const PADDING_ENCODING: &str = "conformance.padding"; + +type Outcome = Result; + +pub struct Suite { + module: Arc, + requests: Vec<(String, HookRequest)>, + valid_params: Vec, + invalid_params: Vec, + request_max_bytes: usize, +} + +impl Suite { + pub fn new(module: M) -> Self { + Self { + module: Arc::new(module), + requests: Vec::new(), + valid_params: Vec::new(), + invalid_params: Vec::new(), + request_max_bytes: DEFAULT_REQUEST_MAX_BYTES, + } + } + + /// A request the module must answer the same way on every transport and every time. + /// The suite sets `instance_id`; everything else is sent as given. + pub fn request(mut self, name: impl Into, request: HookRequest) -> Self { + self.requests.push((name.into(), request)); + self + } + + pub fn valid_params(mut self, params: serde_json::Value) -> Self { + self.valid_params.push(params); + self + } + + pub fn invalid_params(mut self, params: serde_json::Value) -> Self { + self.invalid_params.push(params); + self + } + + /// The size of the request sent at the cap; the Guardian's default unless the operator + /// raises `GUARDIAN_MODULE_REQUEST_MAX_BYTES`. + pub fn request_max_bytes(mut self, bytes: usize) -> Self { + self.request_max_bytes = bytes; + self + } + + pub async fn run(self) -> Report { + let mut report = Report::default(); + if self.requests.is_empty() { + report.fail("setup", "", "the suite needs at least one request"); + } + if self.valid_params.is_empty() { + report.fail( + "setup", + "", + "the suite needs at least one valid params value", + ); + } + let (channel, shutdown) = match self.start_remote().await { + Ok(started) => started, + Err(detail) => { + report.fail("setup", "", detail); + return report; + } + }; + let remote = Remote { + client: GuardianModuleClient::new(channel), + }; + self.check_describe(&remote, &mut report).await; + self.check_params(&remote, &mut report).await; + let baseline = self.check_transport(&remote, &mut report).await; + self.check_decisions(&baseline, &mut report); + self.check_purity(&baseline, &mut report).await; + self.check_instances(&remote, &baseline, &mut report).await; + self.check_size_cap(&remote, &mut report).await; + let _ = shutdown.send(()); + report + } + + async fn start_remote(&self) -> Result<(Channel, oneshot::Sender<()>), String> { + let listener = TcpListener::bind("127.0.0.1:0") + .await + .map_err(|e| format!("bind loopback: {e}"))?; + let addr = listener + .local_addr() + .map_err(|e| format!("loopback address: {e}"))?; + let service = serve(Arc::clone(&self.module)) + .instance(INSTANCE_A, TOKEN_A) + .instance(INSTANCE_B, TOKEN_B) + .into_service(); + let (shutdown, stopped) = oneshot::channel::<()>(); + tokio::spawn(async move { + let _ = Server::builder() + .add_service(service) + .serve_with_incoming_shutdown(TcpIncoming::from(listener), async { + let _ = stopped.await; + }) + .await; + }); + let channel = Channel::from_shared(format!("http://{addr}")) + .map_err(|e| e.to_string())? + .connect() + .await + .map_err(|e| format!("connect to the served module: {e}"))?; + Ok((channel, shutdown)) + } + + async fn check_describe(&self, remote: &Remote, report: &mut Report) { + let guardian = DescribeRequest { + guardian_protocol_version: PROTOCOL_VERSION, + guardian_min_protocol_version: PROTOCOL_VERSION, + guardian_capabilities: Vec::new(), + }; + let local = match self.module.describe(&guardian).await { + Ok(info) => info, + Err(error) => { + report.fail("describe", "", format!("in process: {error}")); + return; + } + }; + if local.protocol_version != PROTOCOL_VERSION { + report.fail( + "describe", + "", + format!( + "protocol_version {} is not {PROTOCOL_VERSION}", + local.protocol_version + ), + ); + } + if local.name.is_empty() { + report.fail("describe", "", "name is empty"); + } + if local.hooks.is_empty() { + report.fail("describe", "", "declares no hooks"); + } + for hook in &local.hooks { + if !matches!(Hook::try_from(*hook), Ok(known) if known != Hook::Unspecified) { + report.fail("describe", "", format!("declares unknown hook {hook}")); + } + } + match remote.describe(guardian).await { + Ok(served) if served == local => {} + Ok(served) => report.fail( + "describe", + "", + format!("over gRPC {served:?}, in process {local:?}"), + ), + Err(code) => report.fail("describe", "", format!("over gRPC: {code:?}")), + } + } + + async fn check_params(&self, remote: &Remote, report: &mut Report) { + for params in &self.valid_params { + let case = params.to_string(); + let Some(verdict) = self.validate_both(remote, params, &case, report).await else { + continue; + }; + if !verdict.ok { + report.fail("params", &case, format!("refused: {}", verdict.message)); + continue; + } + if verdict.normalized_params.is_empty() { + continue; + } + let normalized = + match serde_json::from_slice::(&verdict.normalized_params) { + Ok(value) if value.is_object() => value, + _ => { + report.fail("params", &case, "normalized_params is not a JSON object"); + continue; + } + }; + match self.module.validate_params(&json_bytes(&normalized)).await { + Ok(again) if again.ok && normalizes_to(&again, &normalized) => {} + Ok(again) => report.fail( + "params", + &case, + format!("normalized params do not validate to themselves: {again:?}"), + ), + Err(error) => report.fail("params", &case, format!("normalized params: {error}")), + } + } + for params in &self.invalid_params { + let case = params.to_string(); + let Some(verdict) = self.validate_both(remote, params, &case, report).await else { + continue; + }; + if verdict.ok { + report.fail("params", &case, "accepted params the suite marks invalid"); + } else if verdict.message.is_empty() { + report.fail("params", &case, "a refusal carries no message"); + } + } + } + + async fn validate_both( + &self, + remote: &Remote, + params: &serde_json::Value, + case: &str, + report: &mut Report, + ) -> Option { + let bytes = json_bytes(params); + let local = match self.module.validate_params(&bytes).await { + Ok(verdict) => verdict, + Err(error) => { + report.fail("params", case, format!("in process: {error}")); + return None; + } + }; + match remote.validate(INSTANCE_A, TOKEN_A, bytes).await { + Ok(served) if served == local => {} + Ok(served) => report.fail( + "params", + case, + format!("over gRPC {served:?}, in process {local:?}"), + ), + Err(code) => report.fail("params", case, format!("over gRPC: {code:?}")), + } + Some(local) + } + + async fn check_transport(&self, remote: &Remote, report: &mut Report) -> Vec { + let mut baseline = Vec::with_capacity(self.requests.len()); + for (name, request) in &self.requests { + let request = for_instance(request, INSTANCE_A); + let local = evaluate_local(&self.module, &request).await; + let served = remote.evaluate(TOKEN_A, request).await; + if served != local { + report.fail( + "transport", + name, + format!("over gRPC {served:?}, in process {local:?}"), + ); + } + baseline.push(local); + } + baseline + } + + fn check_decisions(&self, baseline: &[Outcome], report: &mut Report) { + for ((name, _), outcome) in self.requests.iter().zip(baseline) { + let Ok(decision) = outcome else { continue }; + if let Err(detail) = well_formed(decision) { + report.fail("decision", name, detail); + } + } + } + + async fn check_purity(&self, baseline: &[Outcome], report: &mut Report) { + for ((name, request), expected) in self.requests.iter().zip(baseline) { + let request = for_instance(request, INSTANCE_A); + for _ in 0..REPEATS { + let again = evaluate_local(&self.module, &request).await; + if &again != expected { + report.fail( + "purity", + name, + format!("repeated: {again:?}, first {expected:?}"), + ); + break; + } + } + } + for ((name, request), expected) in self.requests.iter().zip(baseline).rev() { + let again = evaluate_local(&self.module, &for_instance(request, INSTANCE_A)).await; + if &again != expected { + report.fail( + "purity", + name, + format!("in reverse order: {again:?}, first {expected:?}"), + ); + } + } + let mut concurrent = JoinSet::new(); + for _ in 0..REPEATS { + for (index, (_, request)) in self.requests.iter().enumerate() { + let module = Arc::clone(&self.module); + let request = for_instance(request, INSTANCE_A); + concurrent.spawn(async move { (index, evaluate_local(&module, &request).await) }); + } + } + while let Some(joined) = concurrent.join_next().await { + match joined { + Ok((index, outcome)) if outcome != baseline[index] => report.fail( + "purity", + &self.requests[index].0, + format!("concurrently: {outcome:?}, first {:?}", baseline[index]), + ), + Ok(_) => {} + Err(error) => report.fail("purity", "", format!("evaluation panicked: {error}")), + } + } + } + + async fn check_instances(&self, remote: &Remote, baseline: &[Outcome], report: &mut Report) { + for (name, request) in &self.requests { + let request = for_instance(request, INSTANCE_B); + let local = evaluate_local(&self.module, &request).await; + let served = remote.evaluate(TOKEN_B, request).await; + if served != local { + report.fail( + "instances", + name, + format!("second instance over gRPC {served:?}, in process {local:?}"), + ); + } + } + for ((name, request), expected) in self.requests.iter().zip(baseline) { + let again = remote + .evaluate(TOKEN_A, for_instance(request, INSTANCE_A)) + .await; + if &again != expected { + report.fail( + "instances", + name, + format!("after the second instance ran: {again:?}, first {expected:?}"), + ); + } + } + let Some((name, request)) = self.requests.first() else { + return; + }; + let crossed = remote + .evaluate(TOKEN_A, for_instance(request, INSTANCE_B)) + .await; + if crossed != Err(tonic::Code::PermissionDenied) { + report.fail( + "instances", + name, + format!("one instance's token used for another: {crossed:?}"), + ); + } + let anonymous = remote + .evaluate_unauthenticated(for_instance(request, INSTANCE_A)) + .await; + if anonymous != Err(tonic::Code::Unauthenticated) { + report.fail("instances", name, format!("no token: {anonymous:?}")); + } + } + + async fn check_size_cap(&self, remote: &Remote, report: &mut Report) { + let Some((name, request)) = self.requests.first() else { + return; + }; + let padded = at_size(for_instance(request, INSTANCE_A), self.request_max_bytes); + let case = format!("{name} at {} bytes", prost::Message::encoded_len(&padded)); + let local = evaluate_local(&self.module, &padded).await; + let served = remote.evaluate(TOKEN_A, padded).await; + if served != local { + report.fail( + "size cap", + &case, + format!("over gRPC {served:?}, in process {local:?}"), + ); + } + } +} + +struct Remote { + client: GuardianModuleClient, +} + +impl Remote { + async fn describe(&self, guardian: DescribeRequest) -> Result { + self.client + .clone() + .describe(authorized(guardian, TOKEN_A)) + .await + .map(tonic::Response::into_inner) + .map_err(|status| status.code()) + } + + async fn validate( + &self, + instance_id: &str, + token: &str, + params: Vec, + ) -> Result { + let request = ValidateParamsRequest { + instance_id: instance_id.into(), + params, + }; + self.client + .clone() + .validate_params(authorized(request, token)) + .await + .map(tonic::Response::into_inner) + .map_err(|status| status.code()) + } + + async fn evaluate(&self, token: &str, request: HookRequest) -> Outcome { + self.client + .clone() + .evaluate(authorized(request, token)) + .await + .map(tonic::Response::into_inner) + .map_err(|status| status.code()) + } + + async fn evaluate_unauthenticated(&self, request: HookRequest) -> Outcome { + self.client + .clone() + .evaluate(Request::new(request)) + .await + .map(tonic::Response::into_inner) + .map_err(|status| status.code()) + } +} + +/// What the suite found; empty when the module conforms. +#[derive(Debug, Default)] +pub struct Report { + failures: Vec, +} + +impl Report { + pub fn failures(&self) -> &[Failure] { + &self.failures + } + + pub fn is_conformant(&self) -> bool { + self.failures.is_empty() + } + + /// Panics with every failure when the module does not conform. + pub fn assert_conformant(&self) { + assert!(self.is_conformant(), "module does not conform:\n{self}"); + } + + fn fail(&mut self, check: &'static str, case: &str, detail: impl Into) { + self.failures.push(Failure { + check, + case: case.to_string(), + detail: detail.into(), + }); + } +} + +impl fmt::Display for Report { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + for failure in &self.failures { + writeln!(f, "{failure}")?; + } + Ok(()) + } +} + +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct Failure { + /// `setup`, `describe`, `params`, `transport`, `decision`, `purity`, `instances` or + /// `size cap`. + pub check: &'static str, + pub case: String, + pub detail: String, +} + +impl fmt::Display for Failure { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + if self.case.is_empty() { + write!(f, "[{}] {}", self.check, self.detail) + } else { + write!(f, "[{}] {}: {}", self.check, self.case, self.detail) + } + } +} + +async fn evaluate_local(module: &M, request: &HookRequest) -> Outcome { + module + .evaluate(request) + .await + .map_err(|error| status(error).code()) +} + +fn authorized(message: T, token: &str) -> Request { + let mut request = Request::new(message); + if let Ok(value) = MetadataValue::try_from(format!("Bearer {token}")) { + request.metadata_mut().insert("authorization", value); + } + request +} + +fn for_instance(request: &HookRequest, instance_id: &str) -> HookRequest { + HookRequest { + instance_id: instance_id.into(), + ..request.clone() + } +} + +fn json_bytes(value: &serde_json::Value) -> Vec { + serde_json::to_vec(value).unwrap_or_default() +} + +fn normalizes_to(verdict: &ParamsVerdict, normalized: &serde_json::Value) -> bool { + verdict.normalized_params.is_empty() + || serde_json::from_slice::(&verdict.normalized_params) + .is_ok_and(|again| &again == normalized) +} + +fn well_formed(decision: &Decision) -> Result<(), String> { + let allowed = match Effect::try_from(decision.effect) { + Ok(Effect::Unspecified) => decision.allow, + Ok(Effect::Allow) => true, + Ok(Effect::Deny) => false, + Err(_) => return Err(format!("unknown effect {}", decision.effect)), + }; + if !allowed && !is_valid_reason_code(&decision.reason_code) { + return Err(format!( + "a deny needs a reason_code of 1 to 64 lowercase letters, digits or underscores, got {:?}", + decision.reason_code + )); + } + if decision.client_message.chars().count() > CLIENT_MESSAGE_MAX_CHARS { + return Err(format!( + "client_message is longer than {CLIENT_MESSAGE_MAX_CHARS} characters" + )); + } + if decision.client_message.chars().any(char::is_control) { + return Err("client_message contains control characters".into()); + } + Ok(()) +} + +/// Pads `request` to `target` encoded bytes: a transaction request through a `raw` payload the +/// module cannot mistake for a real encoding, a registration request through its `request_id`. +fn at_size(mut request: HookRequest, target: usize) -> HookRequest { + let pad = |request: &mut HookRequest, len: usize| match request.subject.as_mut() { + Some(hook_request::Subject::Transaction(transaction)) => { + transaction.raw = Some(RawTransaction { + encoding: PADDING_ENCODING.into(), + data: vec![0; len], + }); + } + _ => request.request_id = "r".repeat(len), + }; + pad(&mut request, 0); + let mut len = target.saturating_sub(prost::Message::encoded_len(&request)); + pad(&mut request, len); + while prost::Message::encoded_len(&request) > target && len > 0 { + len -= 1; + pad(&mut request, len); + } + request +} + +#[cfg(test)] +mod tests { + use std::sync::atomic::{AtomicU64, Ordering}; + + use async_trait::async_trait; + use serde_json::json; + + use super::*; + use crate::{ModuleError, ModuleInfo, TransactionSubject}; + + fn transaction() -> HookRequest { + HookRequest { + params: b"{}".to_vec(), + subject: Some(hook_request::Subject::Transaction( + TransactionSubject::default(), + )), + ..Default::default() + } + } + + fn info() -> ModuleInfo { + ModuleInfo { + name: "test".into(), + version: "0".into(), + protocol_version: PROTOCOL_VERSION, + hooks: vec![Hook::BeforeTransactionApproved as i32], + ..Default::default() + } + } + + struct Fixed(Decision); + + #[async_trait] + impl Module for Fixed { + async fn describe(&self, _: &DescribeRequest) -> Result { + Ok(info()) + } + + async fn validate_params(&self, params: &[u8]) -> Result { + Ok(if params == b"{}" { + ParamsVerdict::ok() + } else { + ParamsVerdict::invalid("only {}") + }) + } + + async fn evaluate(&self, _: &HookRequest) -> Result { + Ok(self.0.clone()) + } + } + + struct Counting(AtomicU64); + + #[async_trait] + impl Module for Counting { + async fn describe(&self, _: &DescribeRequest) -> Result { + Ok(info()) + } + + async fn validate_params(&self, _: &[u8]) -> Result { + Ok(ParamsVerdict::ok()) + } + + async fn evaluate(&self, _: &HookRequest) -> Result { + if self.0.fetch_add(1, Ordering::SeqCst) < 2 { + Ok(Decision::allow()) + } else { + Ok(Decision::deny("limit", "over the limit")) + } + } + } + + fn suite(module: M) -> Suite { + Suite::new(module) + .request("payment", transaction()) + .valid_params(json!({})) + .invalid_params(json!({ "x": 1 })) + } + + fn checks(report: &Report) -> Vec<&'static str> { + let mut checks: Vec<_> = report.failures().iter().map(|f| f.check).collect(); + checks.dedup(); + checks + } + + #[tokio::test] + async fn a_well_behaved_module_conforms() { + suite(Fixed(Decision::deny("blocked", "no"))) + .run() + .await + .assert_conformant(); + } + + #[tokio::test] + async fn counting_in_evaluate_is_caught() { + let report = suite(Counting(AtomicU64::new(0))).run().await; + assert!(checks(&report).contains(&"purity"), "{report}"); + } + + #[tokio::test] + async fn a_malformed_deny_is_caught() { + let report = suite(Fixed(Decision::deny("Not Valid", "no"))).run().await; + assert_eq!(checks(&report), vec!["decision"], "{report}"); + let long = Decision::deny("ok", "no").with_client_message("x".repeat(257)); + let report = suite(Fixed(long)).run().await; + assert_eq!(checks(&report), vec!["decision"], "{report}"); + } + + #[tokio::test] + async fn accepting_invalid_params_is_caught() { + let report = Suite::new(Counting(AtomicU64::new(0))) + .request("payment", transaction()) + .valid_params(json!({})) + .invalid_params(json!({ "x": 1 })) + .run() + .await; + assert!(checks(&report).contains(&"params"), "{report}"); + } + + #[test] + fn padding_reaches_the_cap() { + for target in [4_096, DEFAULT_REQUEST_MAX_BYTES] { + let padded = at_size(transaction(), target); + let size = prost::Message::encoded_len(&padded); + assert!(size <= target && size + 2 >= target, "{size} for {target}"); + let registration = at_size(HookRequest::default(), target); + let size = prost::Message::encoded_len(®istration); + assert!(size <= target && size + 2 >= target, "{size} for {target}"); + } + } +} diff --git a/crates/guardian-module-sdk/src/lib.rs b/crates/guardian-module-sdk/src/lib.rs index ae9a69c9..46846b1c 100644 --- a/crates/guardian-module-sdk/src/lib.rs +++ b/crates/guardian-module-sdk/src/lib.rs @@ -5,6 +5,8 @@ use std::sync::Arc; use async_trait::async_trait; pub mod basic_policy; +#[cfg(feature = "conformance")] +pub mod conformance; pub mod serve; pub use prost_types; @@ -25,6 +27,10 @@ pub use proto::{ pub const PROTOCOL_VERSION: u32 = 1; +/// The Guardian's default cap on an encoded `HookRequest`. A module's server must accept +/// requests at least this large. +pub const DEFAULT_REQUEST_MAX_BYTES: usize = 2 * 1024 * 1024; + /// Optional protocol features, named in `DescribeRequest.guardian_capabilities` and /// `ModuleInfo.required_capabilities`. New features are added as capabilities, not as a new /// protocol version, so modules and Guardians of one major version keep working together. @@ -66,6 +72,29 @@ pub trait Module: Send + Sync { } } +#[async_trait] +impl Module for Arc { + async fn describe(&self, guardian: &DescribeRequest) -> Result { + (**self).describe(guardian).await + } + + async fn validate_params(&self, params: &[u8]) -> Result { + (**self).validate_params(params).await + } + + async fn evaluate(&self, request: &HookRequest) -> Result { + (**self).evaluate(request).await + } + + async fn notify(&self, event: &CommitEvent) -> Result<(), ModuleError> { + (**self).notify(event).await + } + + async fn notify_gap(&self, gap: &Gap) -> Result<(), ModuleError> { + (**self).notify_gap(gap).await + } +} + #[derive(Debug, Clone)] #[non_exhaustive] pub struct ModuleInstanceConfig { diff --git a/crates/guardian-module-sdk/src/serve.rs b/crates/guardian-module-sdk/src/serve.rs index 255d6cf8..249adfe0 100644 --- a/crates/guardian-module-sdk/src/serve.rs +++ b/crates/guardian-module-sdk/src/serve.rs @@ -78,7 +78,7 @@ impl Harness { } } -fn status(error: ModuleError) -> Status { +pub(crate) fn status(error: ModuleError) -> Status { match error { ModuleError::Unavailable(message) => Status::unavailable(message), ModuleError::InvalidRequest(message) => Status::invalid_argument(message), diff --git a/crates/guardian-module-sdk/tests/conformance.rs b/crates/guardian-module-sdk/tests/conformance.rs index 773b6abe..7461d062 100644 --- a/crates/guardian-module-sdk/tests/conformance.rs +++ b/crates/guardian-module-sdk/tests/conformance.rs @@ -1,10 +1,11 @@ use guardian_module_sdk::basic_policy::BasicPolicy; +use guardian_module_sdk::conformance::Suite; use guardian_module_sdk::proto::guardian_module_client::GuardianModuleClient; use guardian_module_sdk::proto::{asset, hook_request}; use guardian_module_sdk::serve::serve; use guardian_module_sdk::{ - AccountView, Asset, HookRequest, MidenTransaction, Module, OutputNote, TransactionProjection, - TransactionSubject, + AccountStateProjection, AccountView, Asset, HookRequest, MidenAccountState, MidenTransaction, + Module, OutputNote, RegistrationSubject, TransactionProjection, TransactionSubject, }; use serde_json::json; use tokio::net::TcpListener; @@ -72,49 +73,78 @@ fn payment(amounts: &[u64], params: serde_json::Value) -> HookRequest { } } -#[tokio::test] -async fn in_process_and_remote_decisions_match() { - let mut client = GuardianModuleClient::new(start_remote().await); - let cap = json!({ "max_amount_per_tx": { "0xaa": "1000" } }); - let cases = [ - payment(&[500], cap.clone()), - payment(&[600, 600], cap.clone()), - payment(&[1000], cap.clone()), - payment(&[1], json!({ "recipient_allowlist": ["0xother"] })), - ]; - for case in cases { - let local = BasicPolicy.evaluate(&case).await.unwrap(); - let remote = client - .evaluate(authorized(case.clone(), TOKEN)) - .await - .unwrap() - .into_inner(); - assert_eq!(local, remote); - let again = client - .evaluate(authorized(case, TOKEN)) - .await - .unwrap() - .into_inner(); - assert_eq!(remote, again); +fn view(signers: &[&str], code: &str) -> AccountView { + AccountView { + signer_commitments: signers.iter().map(|s| s.to_string()).collect(), + code_commitment: code.into(), + ..Default::default() } } -#[tokio::test] -async fn remote_rejects_a_credential_for_another_instance() { - let mut client = GuardianModuleClient::new(start_remote().await); - let mut request = payment(&[1], json!({})); - request.instance_id = "other-instance".into(); - let status = client - .evaluate(authorized(request, TOKEN)) - .await - .unwrap_err(); - assert_eq!(status.code(), tonic::Code::PermissionDenied); +fn with_views(mut request: HookRequest, before: &[&str], after: &[&str]) -> HookRequest { + request.before = Some(view(before, "0xc1")); + request.after = Some(view(after, "0xc1")); + request +} + +fn registration(params: serde_json::Value, signers: &[&str]) -> HookRequest { + HookRequest { + params: serde_json::to_vec(¶ms).unwrap(), + after: Some(view(signers, "0xc1")), + subject: Some(hook_request::Subject::Registration(RegistrationSubject { + initial_state: Some(AccountStateProjection::miden(MidenAccountState::default())), + })), + ..Default::default() + } +} - let status = client - .evaluate(authorized(payment(&[1], json!({})), "wrong")) +#[tokio::test] +async fn basic_policy_conforms() { + let cap = json!({ "max_amount_per_tx": { "0xaa": "1000" } }); + let signers = json!({ "signer_check": "added", "signer_denylist": ["0xbad"] }); + let code = json!({ "code_check": "all", "allowed_code_commitments": ["0xc1"] }); + Suite::new(BasicPolicy) + .request("under the cap", payment(&[500], cap.clone())) + .request("split over the cap", payment(&[600, 600], cap.clone())) + .request("at the cap", payment(&[1000], cap)) + .request( + "recipient not allowed", + payment(&[1], json!({ "recipient_allowlist": ["0xother"] })), + ) + .request( + "recipient denied, generic", + payment(&[1], json!({ "recipient_denylist": ["0xr1"] })), + ) + .request( + "denied signer added", + with_views( + payment(&[1], signers.clone()), + &["0xs1"], + &["0xs1", "0xbad"], + ), + ) + .request( + "listed code", + with_views(payment(&[1], code.clone()), &["0xs1"], &["0xs1"]), + ) + .request( + "registration with a denied signer", + registration(signers, &["0xbad"]), + ) + .request("registration on listed code", registration(code, &["0xs1"])) + .request( + "params a module cannot read", + payment(&[1], json!({ "max_amount_per_tx": { "0xaa": "ten" } })), + ) + .valid_params(json!({})) + .valid_params(json!({ "max_amount_per_tx": { "0xaa": "1000" }, "recipient_denylist": [] })) + .valid_params(json!({ "code_check": "changed", "allowed_code_commitments": ["0xc1"] })) + .invalid_params(json!({ "unknown": 1 })) + .invalid_params(json!({ "max_amount_per_tx": { "0xaa": "ten" } })) + .invalid_params(json!({ "signer_allowlist": [], "signer_denylist": [] })) + .run() .await - .unwrap_err(); - assert_eq!(status.code(), tonic::Code::PermissionDenied); + .assert_conformant(); } #[tokio::test] diff --git a/crates/server/src/modules/limits.rs b/crates/server/src/modules/limits.rs index caba96e6..01f5255e 100644 --- a/crates/server/src/modules/limits.rs +++ b/crates/server/src/modules/limits.rs @@ -41,7 +41,7 @@ impl Default for Limits { fn default() -> Self { Self { budget: Duration::from_millis(1_000), - request_max_bytes: 2 * 1024 * 1024, + request_max_bytes: guardian_module_sdk::DEFAULT_REQUEST_MAX_BYTES, breaker_failures: 5, probe_interval: Duration::from_millis(5_000), params_max_bytes: 64 * 1024, diff --git a/speckit/features/251-guardian-modules/tasks.md b/speckit/features/251-guardian-modules/tasks.md index d8873853..d739de33 100644 --- a/speckit/features/251-guardian-modules/tasks.md +++ b/speckit/features/251-guardian-modules/tasks.md @@ -171,7 +171,7 @@ ### Tests for User Story 6 -- [ ] T047 [P] [US6] Conformance suite: turn the prototype's `crates/guardian-module-sdk/tests/conformance.rs` into a reusable suite in `crates/guardian-module-sdk/src/conformance/` (behind a `conformance` feature) that any module author can run, covering identical decisions in process and over gRPC, `evaluate` purity (the same request repeated leaves module state unchanged), params validation, a request at the size cap, and instance-id isolation between two instances on one service; run it for `basic-policy` from `crates/guardian-module-sdk/tests/conformance.rs` +- [X] T047 [P] [US6] Conformance suite: turn the prototype's `crates/guardian-module-sdk/tests/conformance.rs` into a reusable suite in `crates/guardian-module-sdk/src/conformance.rs` (one file; it also checks `Describe`, decision shape and that one instance's token is refused for another) (behind a `conformance` feature) that any module author can run, covering identical decisions in process and over gRPC, `evaluate` purity (the same request repeated leaves module state unchanged), params validation, a request at the size cap, and instance-id isolation between two instances on one service; run it for `basic-policy` from `crates/guardian-module-sdk/tests/conformance.rs` ### Implementation for User Story 6 From 6896745d5ba29cc7aee5f00b0971ea2d3710286a Mon Sep 17 00:00:00 2001 From: Zeljko Date: Mon, 9 Nov 2026 11:43:46 +0100 Subject: [PATCH 033/105] feat(modules): module credentials through the secrets backend (#251) The catalog names secrets instead of files: auth.token_secret, tls.client_cert_secret, tls.client_key_secret and $secret params of in-process instances. GUARDIAN_MODULE_SECRET_PROVIDER reads them once at startup from AWS Secrets Manager (prod default) or owner-only files below GUARDIAN_MODULE_SECRET_DIR. A secret that cannot be read fails the instance's creation, so an enabled instance stops startup and a disabled one stays disabled. In-process factories get $secret values through ModuleInstanceConfig::secret; requests keep the references. RFC 0002 revision 30. --- crates/guardian-module-sdk/src/lib.rs | 28 +- crates/server/src/modules/catalog.rs | 248 ++++++++---- crates/server/src/modules/mod.rs | 16 +- crates/server/src/modules/registry.rs | 14 +- crates/server/src/modules/secrets.rs | 364 ++++++++++++++++++ crates/server/src/modules/testing.rs | 4 +- docs/CONFIGURATION.md | 4 +- docs/guides/policy-modules/custom.md | 2 +- docs/guides/policy-modules/custom.toml | 4 +- docs/guides/policy-modules/remote.md | 28 +- docs/guides/policy-modules/remote.toml | 4 +- docs/rfcs/0002-guardian-modules.md | 13 +- docs/runbooks/secrets.md | 36 ++ .../contracts/catalog-config.md | 13 +- .../251-guardian-modules/quickstart.md | 4 +- .../features/251-guardian-modules/tasks.md | 2 +- 16 files changed, 663 insertions(+), 121 deletions(-) create mode 100644 crates/server/src/modules/secrets.rs diff --git a/crates/guardian-module-sdk/src/lib.rs b/crates/guardian-module-sdk/src/lib.rs index 46846b1c..04a05f4b 100644 --- a/crates/guardian-module-sdk/src/lib.rs +++ b/crates/guardian-module-sdk/src/lib.rs @@ -104,11 +104,13 @@ pub struct ModuleInstanceConfig { pub auth_token: Option, pub tls: Option, pub timeout: std::time::Duration, + /// The catalog params, with any `$secret` references unresolved. pub params: serde_json::Value, + /// The values of the `$secret` references in `params`, by secret name. Only in-process + /// instances receive them; a remote module holds its own credentials. + pub secrets: std::collections::BTreeMap, } -/// TLS settings of a remote module: a private CA (the system roots when absent) and an -/// optional client identity for mutual TLS. impl ModuleInstanceConfig { pub fn new( id: impl Into, @@ -124,6 +126,7 @@ impl ModuleInstanceConfig { tls: None, timeout, params, + secrets: Default::default(), } } @@ -141,8 +144,23 @@ impl ModuleInstanceConfig { self.tls = tls; self } + + pub fn with_secrets( + mut self, + secrets: std::collections::BTreeMap, + ) -> Self { + self.secrets = secrets; + self + } + + /// The value of the `{"$secret": name}` reference in this instance's params. + pub fn secret(&self, name: &str) -> Option<&secrecy::SecretString> { + self.secrets.get(name) + } } +/// TLS settings of a remote module: a private CA (the system roots when absent) and an +/// optional client identity for mutual TLS. #[derive(Debug, Clone, Default)] #[non_exhaustive] pub struct ModuleTls { @@ -317,10 +335,16 @@ mod tests { }), timeout: std::time::Duration::from_millis(10), params: serde_json::json!({}), + secrets: [( + "k".to_string(), + secrecy::SecretString::from("very-secret-param"), + )] + .into(), }; let debug = format!("{config:?}"); assert!(!debug.contains("very-secret-token")); assert!(!debug.contains("very-secret-key")); + assert!(!debug.contains("very-secret-param")); } #[test] diff --git a/crates/server/src/modules/catalog.rs b/crates/server/src/modules/catalog.rs index e451befa..99f12a6d 100644 --- a/crates/server/src/modules/catalog.rs +++ b/crates/server/src/modules/catalog.rs @@ -1,6 +1,6 @@ //! The module catalog: instances declared in the file at `GUARDIAN_MODULES_CONFIG`. -use std::collections::HashSet; +use std::collections::{BTreeMap, BTreeSet, HashSet}; use std::path::{Path, PathBuf}; use std::time::Duration; @@ -66,15 +66,54 @@ impl HookName { #[derive(Debug, Deserialize)] #[serde(deny_unknown_fields)] struct AuthEntry { - token_file: PathBuf, + token_secret: String, } #[derive(Debug, Deserialize)] #[serde(deny_unknown_fields)] struct TlsEntry { ca_file: Option, - client_cert_file: Option, - client_key_file: Option, + client_cert_secret: Option, + client_key_secret: Option, +} + +/// The secrets an instance names, resolved through the secrets backend before it is created. +#[derive(Debug, Clone, Default, PartialEq, Eq)] +pub struct SecretRefs { + pub token: Option, + pub tls: Option, + /// Names of the `$secret` references in the catalog params of an in-process instance. + pub params: BTreeSet, +} + +#[derive(Debug, Clone, Default, PartialEq, Eq)] +pub struct TlsRefs { + pub ca_file: Option, + pub client_cert: Option, + pub client_key: Option, +} + +impl SecretRefs { + pub fn is_empty(&self) -> bool { + self.token.is_none() && self.tls.is_none() && self.params.is_empty() + } + + pub fn names_secrets(&self) -> bool { + self.token.is_some() + || !self.params.is_empty() + || self + .tls + .as_ref() + .is_some_and(|tls| tls.client_cert.is_some()) + } +} + +/// What an instance's [`SecretRefs`] resolved to. +#[derive(Debug, Clone, Default)] +pub struct Credentials { + pub auth_token: Option, + pub tls: Option, + pub params: BTreeMap, } #[derive(Debug, Deserialize)] @@ -160,8 +199,10 @@ pub struct InstanceConfig { pub client_reason: ClientReason, /// Whether the dry-run check may call the instance. pub dry_run: bool, - pub auth_token: Option, - pub tls: Option, + pub secrets: SecretRefs, + /// What `secrets` resolved to, or why they did not; an instance is created only from a + /// resolution, so a missing secret fails it like any other creation error. + pub credentials: Result, /// Seed for the instance's global params; operator-managed after the first start. pub params: serde_json::Value, /// Params holding secret references stay file-managed: the operator API cannot change them. @@ -189,13 +230,59 @@ fn json_object(value: Option, what: &str) -> Result bool { match value { serde_json::Value::Object(map) => { - map.contains_key("$secret") || map.values().any(contains_secret_reference) + map.contains_key(SECRET_KEY) || map.values().any(contains_secret_reference) } serde_json::Value::Array(items) => items.iter().any(contains_secret_reference), _ => false, } } +const SECRET_KEY: &str = "$secret"; +const SECRET_NAME_MAX_CHARS: usize = 512; + +/// A secrets backend name: what AWS Secrets Manager accepts, which the file provider reads as a +/// path below its directory. +pub(crate) fn check_secret_name(name: &str) -> Result<(), String> { + let valid = (1..=SECRET_NAME_MAX_CHARS).contains(&name.len()) + && name + .bytes() + .all(|b| b.is_ascii_alphanumeric() || b"/_+=.@-".contains(&b)); + if valid { + Ok(()) + } else { + Err(format!( + "secret name {name:?} must be 1 to {SECRET_NAME_MAX_CHARS} characters of letters, digits and /_+=.@-" + )) + } +} + +/// Collects the names of the `$secret` references in `value`; a reference is an object whose +/// only key is `$secret`, with a secret name as its value. +fn secret_references( + value: &serde_json::Value, + names: &mut BTreeSet, +) -> Result<(), String> { + match value { + serde_json::Value::Object(map) => match map.get(SECRET_KEY) { + Some(serde_json::Value::String(name)) if map.len() == 1 => { + check_secret_name(name)?; + names.insert(name.clone()); + Ok(()) + } + Some(_) => Err(format!( + "a secret reference is {{ \"{SECRET_KEY}\" = \"\" }} and nothing else" + )), + None => map + .values() + .try_for_each(|value| secret_references(value, names)), + }, + serde_json::Value::Array(items) => items + .iter() + .try_for_each(|value| secret_references(value, names)), + _ => Ok(()), + } +} + /// How the Guardian reaches a remote module. `grpc://` is TLS; plain text is the explicit /// `grpc+insecure://` scheme and only for a loopback host. #[derive(Debug, Clone, Copy, PartialEq, Eq)] @@ -244,13 +331,13 @@ impl Catalog { let Some(endpoint) = &config.endpoint else { continue; }; - if Transport::of(endpoint, config.tls.is_some())? != Transport::Tls { + if Transport::of(endpoint, config.secrets.tls.is_some())? != Transport::Tls { return Err(format!( "module {}: plain text is not allowed in the prod stage", config.id )); } - if config.auth_token.is_none() { + if config.secrets.token.is_none() { return Err(format!( "module {}: auth is mandatory for remote modules in the prod stage", config.id @@ -360,56 +447,49 @@ impl Catalog { "module {id}: disclosure = \"params\" would show cosigners the secret references in its params; use \"summary\" or \"none\"" )); } - let auth_token = entry + let mut param_secrets = BTreeSet::new(); + secret_references(¶ms, &mut param_secrets) + .map_err(|e| format!("module {id} params: {e}"))?; + let token = entry .auth - .map(|auth| { - let path = match base_dir { - Some(dir) if auth.token_file.is_relative() => dir.join(&auth.token_file), - _ => auth.token_file.clone(), - }; - std::fs::read_to_string(&path) - .map(zeroize::Zeroizing::new) - .map(|token| guardian_module_sdk::secrecy::SecretString::from(token.trim())) - .map_err(|e| format!("module {id}: cannot read token file: {e}")) - }) - .transpose()?; - let resolve = |path: &PathBuf| match base_dir { - Some(dir) if path.is_relative() => dir.join(path), - _ => path.clone(), - }; - let read = |path: &PathBuf, what: &str| { - std::fs::read(resolve(path)) - .map_err(|e| format!("module {id}: cannot read {what}: {e}")) - }; + .map(|auth| check_secret_name(&auth.token_secret).map(|()| auth.token_secret)) + .transpose() + .map_err(|e| format!("module {id} auth: {e}"))?; let tls = entry .tls .map(|tls| { - let client_identity = match (&tls.client_cert_file, &tls.client_key_file) { - (Some(cert), Some(key)) => { - let key = zeroize::Zeroizing::new(read(key, "client key")?); - let key = String::from_utf8(key.to_vec()) - .map_err(|_| format!("module {id}: client key is not PEM"))?; - Some(guardian_module_sdk::ClientIdentity::new( - read(cert, "client certificate")?, - guardian_module_sdk::secrecy::SecretString::from(key), - )) - } - (None, None) => None, - _ => { - return Err(format!( - "module {id}: client_cert_file and client_key_file go together" - )); - } - }; - Ok(guardian_module_sdk::ModuleTls::new( - tls.ca_file - .as_ref() - .map(|ca| read(ca, "CA file")) - .transpose()?, - client_identity, - )) + if tls.client_cert_secret.is_some() != tls.client_key_secret.is_some() { + return Err( + "client_cert_secret and client_key_secret go together".to_string() + ); + } + for name in [&tls.client_cert_secret, &tls.client_key_secret] + .into_iter() + .flatten() + { + check_secret_name(name)?; + } + Ok(TlsRefs { + ca_file: tls.ca_file.map(|path| match base_dir { + Some(dir) if path.is_relative() => dir.join(path), + _ => path, + }), + client_cert: tls.client_cert_secret, + client_key: tls.client_key_secret, + }) }) - .transpose()?; + .transpose() + .map_err(|e| format!("module {id} tls: {e}"))?; + let secrets = SecretRefs { + token, + tls, + params: param_secrets, + }; + let credentials = if secrets.is_empty() { + Ok(Credentials::default()) + } else { + Err("secrets not resolved".to_string()) + }; instances.push(InstanceConfig { id, kind: entry.kind, @@ -425,8 +505,8 @@ impl Catalog { description, client_reason: entry.client_reason, dry_run: entry.dry_run, - auth_token, - tls, + secrets, + credentials, file_managed_params: contains_secret_reference(¶ms), params, }); @@ -575,24 +655,32 @@ on_error = "allow" } #[test] - fn tokens_never_appear_in_debug_output() { - let dir = std::env::temp_dir().join(format!("modules_{:016x}", rand::random::())); - std::fs::create_dir_all(&dir).unwrap(); - std::fs::write(dir.join("token"), "very-secret-token\n").unwrap(); - let text = r#" -[[module]] -id = "remote" -kind = "grpc" -endpoint = "grpc://127.0.0.1:7443" -scope = "all" -hooks = ["before_transaction_approved"] -timeout_ms = 20 -auth = { token_file = "token" } -"#; - let catalog = Catalog::parse(text, Some(&dir)).unwrap(); - assert!(!format!("{catalog:?}").contains("very-secret-token")); - assert!(catalog.instances[0].auth_token.is_some()); - std::fs::remove_dir_all(dir).ok(); + fn credentials_are_secret_names_resolved_later() { + let text = remote( + "grpc://127.0.0.1:7443", + r#"auth = { token_secret = "guardian/modules/risk-token" } +tls = { ca_file = "ca.pem", client_cert_secret = "risk-cert", client_key_secret = "risk-key" }"#, + ); + let catalog = Catalog::parse(&text, Some(Path::new("/etc/guardian"))).unwrap(); + let config = &catalog.instances[0]; + assert_eq!( + config.secrets, + SecretRefs { + token: Some("guardian/modules/risk-token".into()), + tls: Some(TlsRefs { + ca_file: Some(PathBuf::from("/etc/guardian/ca.pem")), + client_cert: Some("risk-cert".into()), + client_key: Some("risk-key".into()), + }), + params: BTreeSet::new(), + } + ); + assert!(config.credentials.is_err()); + let invalid = remote( + "grpc://127.0.0.1:7443", + r#"auth = { token_secret = "../token file" }"#, + ); + assert!(parse(&invalid).unwrap_err().contains("secret name")); } fn remote(endpoint: &str, extra: &str) -> String { @@ -637,26 +725,20 @@ timeout_ms = 20 #[test] fn prod_requires_tls_and_a_token_for_remote_modules() { - let dir = std::env::temp_dir().join(format!("modules_{:016x}", rand::random::())); - std::fs::create_dir_all(&dir).unwrap(); - std::fs::write(dir.join("token"), "t").unwrap(); - let auth = r#"auth = { token_file = "token" }"#; + let auth = r#"auth = { token_secret = "token" }"#; let check = |endpoint: &str, extra: &str| { - Catalog::parse(&remote(endpoint, extra), Some(&dir)) - .unwrap() - .check_production() + parse(&remote(endpoint, extra)).unwrap().check_production() }; assert!(check("grpc://risk.internal:7443", auth).is_ok()); assert!(check("grpc://risk.internal:7443", "").is_err()); assert!(check("grpc+insecure://127.0.0.1:7443", auth).is_err()); - std::fs::remove_dir_all(dir).ok(); } #[test] fn a_client_certificate_needs_its_key() { let text = remote( "grpc://risk.internal:7443", - r#"tls = { client_cert_file = "cert.pem" }"#, + r#"tls = { client_cert_secret = "cert" }"#, ); assert!(parse(&text).unwrap_err().contains("go together")); } diff --git a/crates/server/src/modules/mod.rs b/crates/server/src/modules/mod.rs index 52502954..b7bfe13b 100644 --- a/crates/server/src/modules/mod.rs +++ b/crates/server/src/modules/mod.rs @@ -13,6 +13,7 @@ pub mod pipeline; pub mod postgres_store; pub mod registry; pub mod request; +pub mod secrets; pub mod store; #[cfg(test)] pub mod testing; @@ -52,15 +53,22 @@ pub async fn from_env( return Ok(None); }; let catalog_path = PathBuf::from(path); - let catalog = Catalog::load(&catalog_path)?; + let mut catalog = Catalog::load(&catalog_path)?; let limits = limits::Limits::from_env()?; - if crate::config::stage::Stage::from_env() + let prod = crate::config::stage::Stage::from_env() .map_err(|e| e.to_string())? - .is_prod() - { + .is_prod(); + if prod { catalog.check_production()?; catalog.check_budget(limits.budget, execution_lease)?; } + let source = if catalog.names_secrets() { + let catalog_dir = catalog_path.parent().unwrap_or(std::path::Path::new(".")); + Some(secrets::from_env(catalog_dir, prod).await?) + } else { + None + }; + catalog.resolve_secrets(source.as_deref()).await; let store = match store { Some(store) => store, None => Arc::new(filesystem_store(&catalog_path)?), diff --git a/crates/server/src/modules/registry.rs b/crates/server/src/modules/registry.rs index 72a31d45..910cd489 100644 --- a/crates/server/src/modules/registry.rs +++ b/crates/server/src/modules/registry.rs @@ -125,6 +125,7 @@ impl Registry { .factories .get(&config.kind) .ok_or_else(|| format!("unknown kind {}", config.kind))?; + let credentials = config.credentials.clone()?; let instance = ModuleInstanceConfig::new( config.id.clone(), config.kind.clone(), @@ -132,8 +133,9 @@ impl Registry { config.params.clone(), ) .with_endpoint(config.endpoint.clone()) - .with_auth_token(config.auth_token.clone()) - .with_tls(config.tls.clone()); + .with_auth_token(credentials.auth_token) + .with_tls(credentials.tls) + .with_secrets(credentials.params); std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| factory.create(&instance))) .map_err(|_| "module factory panicked".to_string())? .map_err(|e| e.to_string()) @@ -374,19 +376,13 @@ enabled = ENABLED #[tokio::test] async fn the_guide_catalogs_load() { - let dir = std::env::temp_dir().join(format!("guide_{:016x}", rand::random::())); - std::fs::create_dir_all(&dir).unwrap(); - for token in ["caps.token", "note-policy.token"] { - std::fs::write(dir.join(token), "t").unwrap(); - } for text in [ include_str!("../../../../docs/guides/policy-modules/remote.toml"), include_str!("../../../../docs/guides/policy-modules/custom.toml"), include_str!("../../../../docs/guides/policy-modules/custom-in-process.toml"), ] { - Catalog::parse(text, Some(&dir)).expect("guide catalog parses"); + Catalog::parse(text, None).expect("guide catalog parses"); } - std::fs::remove_dir_all(dir).ok(); let built_in = include_str!("../../../../docs/guides/policy-modules/built-in.toml"); let instances = Registry::first_party() .instantiate(&catalog(built_in), &HashMap::new()) diff --git a/crates/server/src/modules/secrets.rs b/crates/server/src/modules/secrets.rs new file mode 100644 index 00000000..54328d3f --- /dev/null +++ b/crates/server/src/modules/secrets.rs @@ -0,0 +1,364 @@ +//! The secrets backend for module credentials and `$secret` params: files in a directory, or +//! AWS Secrets Manager. Secrets are read once, when the catalog's instances are created. + +use std::path::{Path, PathBuf}; + +use async_trait::async_trait; +use guardian_module_sdk::secrecy::{ExposeSecret, SecretString}; +use guardian_module_sdk::{ClientIdentity, ModuleTls}; + +use super::catalog::{Catalog, Credentials, SecretRefs, check_secret_name}; + +pub const PROVIDER_ENV: &str = "GUARDIAN_MODULE_SECRET_PROVIDER"; +pub const DIR_ENV: &str = "GUARDIAN_MODULE_SECRET_DIR"; + +#[async_trait] +pub trait SecretSource: Send + Sync { + async fn read(&self, name: &str) -> Result; +} + +/// One file per secret, at `/`, readable by its owner only. +pub struct FileSecrets { + dir: PathBuf, +} + +impl FileSecrets { + pub fn new(dir: PathBuf) -> Self { + Self { dir } + } + + fn path(&self, name: &str) -> Result { + check_secret_name(name)?; + let relative = Path::new(name); + let plain = relative + .components() + .all(|component| matches!(component, std::path::Component::Normal(_))); + if plain { + Ok(self.dir.join(relative)) + } else { + Err(format!( + "secret name {name:?} must be a relative path without . or .. segments" + )) + } + } +} + +#[async_trait] +impl SecretSource for FileSecrets { + async fn read(&self, name: &str) -> Result { + let path = self.path(name)?; + ensure_owner_only(&path)?; + std::fs::read_to_string(&path) + .map(SecretString::from) + .map_err(|e| format!("cannot read secret file {}: {e}", path.display())) + } +} + +pub struct AwsSecrets { + client: aws_sdk_secretsmanager::Client, +} + +impl AwsSecrets { + pub async fn from_env() -> Result { + if std::env::var("AWS_REGION").map_or(true, |region| region.is_empty()) { + return Err(format!("{PROVIDER_ENV}=aws needs AWS_REGION to be set")); + } + let config = aws_config::defaults(aws_config::BehaviorVersion::latest()) + .load() + .await; + Ok(Self { + client: aws_sdk_secretsmanager::Client::new(&config), + }) + } +} + +#[async_trait] +impl SecretSource for AwsSecrets { + async fn read(&self, name: &str) -> Result { + check_secret_name(name)?; + let response = self + .client + .get_secret_value() + .secret_id(name) + .send() + .await + .map_err(|e| format!("cannot read secret {name} from Secrets Manager: {e}"))?; + response + .secret_string() + .map(|value| SecretString::from(value.to_owned())) + .ok_or_else(|| format!("secret {name} holds no secret string")) + } +} + +/// The provider named by `GUARDIAN_MODULE_SECRET_PROVIDER`: `aws` by default in the prod stage, +/// `file` otherwise, reading `GUARDIAN_MODULE_SECRET_DIR` or the catalog's directory. +pub async fn from_env(catalog_dir: &Path, prod: bool) -> Result, String> { + let provider = std::env::var(PROVIDER_ENV).unwrap_or_default(); + let provider = match provider.as_str() { + "" if prod => "aws", + "" => "file", + other => other, + }; + match provider { + "file" => { + let dir = std::env::var_os(DIR_ENV) + .filter(|value| !value.is_empty()) + .map(PathBuf::from) + .unwrap_or_else(|| catalog_dir.to_path_buf()); + Ok(Box::new(FileSecrets::new(dir))) + } + "aws" => Ok(Box::new(AwsSecrets::from_env().await?)), + other => Err(format!( + "{PROVIDER_ENV} must be \"file\" or \"aws\", got {other:?}" + )), + } +} + +impl SecretRefs { + /// Reads every secret the instance names; an error names the secret, never its value. + pub async fn resolve(&self, source: Option<&dyn SecretSource>) -> Result { + let read = |name: &str| { + let name = name.to_string(); + async move { + match source { + Some(source) => source.read(&name).await, + None => Err("no secrets provider".to_string()), + } + .map_err(|e| format!("secret {name}: {e}")) + } + }; + let auth_token = match &self.token { + Some(name) => Some(SecretString::from( + read(name).await?.expose_secret().trim().to_owned(), + )), + None => None, + }; + let tls = match &self.tls { + Some(tls) => { + let ca_pem = tls + .ca_file + .as_ref() + .map(|path| { + std::fs::read(path) + .map_err(|e| format!("cannot read CA file {}: {e}", path.display())) + }) + .transpose()?; + let client_identity = match (&tls.client_cert, &tls.client_key) { + (Some(cert), Some(key)) => Some(ClientIdentity::new( + read(cert).await?.expose_secret().as_bytes().to_vec(), + read(key).await?, + )), + _ => None, + }; + Some(ModuleTls::new(ca_pem, client_identity)) + } + None => None, + }; + let mut params = std::collections::BTreeMap::new(); + for name in &self.params { + params.insert(name.clone(), read(name).await?); + } + Ok(Credentials { + auth_token, + tls, + params, + }) + } +} + +impl Catalog { + /// Resolves every instance's secrets. A failure is kept on the instance, so it stops startup + /// for an enabled instance and leaves a disabled one disabled. + pub async fn resolve_secrets(&mut self, source: Option<&dyn SecretSource>) { + for config in &mut self.instances { + config.credentials = config.secrets.resolve(source).await; + } + } + + pub fn names_secrets(&self) -> bool { + self.instances + .iter() + .any(|config| config.secrets.names_secrets()) + } +} + +#[cfg(unix)] +fn ensure_owner_only(path: &Path) -> Result<(), String> { + use std::os::unix::fs::PermissionsExt; + + let mode = std::fs::metadata(path) + .map_err(|e| format!("cannot read secret file {}: {e}", path.display()))? + .permissions() + .mode(); + if mode & 0o077 == 0 { + Ok(()) + } else { + Err(format!( + "secret file {} must not be accessible by group or others (set its permissions to 0600)", + path.display() + )) + } +} + +#[cfg(not(unix))] +fn ensure_owner_only(_path: &Path) -> Result<(), String> { + Ok(()) +} + +#[cfg(test)] +mod tests { + use std::collections::HashMap; + + use super::*; + + struct Fixed(HashMap<&'static str, &'static str>); + + #[async_trait] + impl SecretSource for Fixed { + async fn read(&self, name: &str) -> Result { + self.0 + .get(name) + .map(|value| SecretString::from(value.to_string())) + .ok_or_else(|| "not found".to_string()) + } + } + + fn catalog(extra: &str, params: &str) -> Catalog { + Catalog::parse( + &format!( + r#" +[[module]] +id = "m" +kind = "{kind}" +{endpoint} +scope = "all" +hooks = ["before_transaction_approved"] +timeout_ms = 20 +{extra} +params = {params} +"#, + kind = if extra.is_empty() { + "basic-policy" + } else { + "grpc" + }, + endpoint = if extra.is_empty() { + "" + } else { + r#"endpoint = "grpc://risk.internal:7443""# + }, + ), + None, + ) + .unwrap() + } + + fn private_dir() -> PathBuf { + let dir = std::env::temp_dir().join(format!("secrets_{:016x}", rand::random::())); + std::fs::create_dir_all(dir.join("modules")).unwrap(); + dir + } + + #[cfg(unix)] + fn write_private(path: &Path, value: &str) { + use std::os::unix::fs::PermissionsExt; + std::fs::write(path, value).unwrap(); + std::fs::set_permissions(path, std::fs::Permissions::from_mode(0o600)).unwrap(); + } + + #[tokio::test] + async fn a_token_and_client_identity_resolve_from_the_source() { + let mut catalog = catalog( + r#"auth = { token_secret = "guardian/modules/risk-token" } +tls = { client_cert_secret = "risk-cert", client_key_secret = "risk-key" }"#, + "{}", + ); + assert!(catalog.instances[0].credentials.is_err()); + let source = Fixed(HashMap::from([ + ("guardian/modules/risk-token", "very-secret-token\n"), + ("risk-cert", "CERT"), + ("risk-key", "very-secret-key"), + ])); + catalog.resolve_secrets(Some(&source)).await; + let credentials = catalog.instances[0].credentials.as_ref().unwrap(); + assert_eq!( + credentials.auth_token.as_ref().unwrap().expose_secret(), + "very-secret-token" + ); + let identity = credentials + .tls + .as_ref() + .unwrap() + .client_identity + .as_ref() + .unwrap(); + assert_eq!(identity.cert_pem, b"CERT"); + let debug = format!("{catalog:?}"); + assert!(!debug.contains("very-secret-token") && !debug.contains("very-secret-key")); + } + + #[tokio::test] + async fn a_missing_secret_is_kept_on_the_instance_by_name() { + let mut catalog = catalog(r#"auth = { token_secret = "absent" }"#, "{}"); + catalog.resolve_secrets(Some(&Fixed(HashMap::new()))).await; + let error = catalog.instances[0].credentials.as_ref().unwrap_err(); + assert!(error.contains("secret absent"), "{error}"); + } + + #[tokio::test] + async fn params_secrets_resolve_and_the_params_keep_the_references() { + let mut catalog = catalog( + "", + r#"{ vendor = { api_key = { "$secret" = "vendor-key" } } }"#, + ); + let source = Fixed(HashMap::from([("vendor-key", "k1")])); + catalog.resolve_secrets(Some(&source)).await; + let config = &catalog.instances[0]; + assert_eq!( + config.credentials.as_ref().unwrap().params["vendor-key"].expose_secret(), + "k1" + ); + assert_eq!( + config.params, + serde_json::json!({ "vendor": { "api_key": { "$secret": "vendor-key" } } }) + ); + } + + #[test] + fn malformed_references_are_refused_at_parse() { + for params in [ + r#"{ api_key = { "$secret" = "k", extra = 1 } }"#, + r#"{ api_key = { "$secret" = 1 } }"#, + r#"{ api_key = { "$secret" = "has space" } }"#, + ] { + let text = format!( + "[[module]]\nid = \"m\"\nkind = \"basic-policy\"\nscope = \"all\"\nhooks = [\"before_transaction_approved\"]\ntimeout_ms = 20\nparams = {params}\n" + ); + assert!(Catalog::parse(&text, None).is_err(), "{params}"); + } + } + + #[cfg(unix)] + #[tokio::test] + async fn the_file_provider_reads_private_files_below_its_directory() { + let dir = private_dir(); + write_private(&dir.join("modules/token"), "t1\n"); + let source = FileSecrets::new(dir.clone()); + assert_eq!( + source.read("modules/token").await.unwrap().expose_secret(), + "t1\n" + ); + for name in ["../token", "modules/../token", "/etc/passwd", "./token"] { + assert!(source.read(name).await.is_err(), "{name}"); + } + std::fs::write(dir.join("open"), "t2").unwrap(); + { + use std::os::unix::fs::PermissionsExt; + std::fs::set_permissions(dir.join("open"), std::fs::Permissions::from_mode(0o644)) + .unwrap(); + } + let error = source.read("open").await.unwrap_err(); + assert!(error.contains("0600"), "{error}"); + std::fs::remove_dir_all(dir).ok(); + } +} diff --git a/crates/server/src/modules/testing.rs b/crates/server/src/modules/testing.rs index 75c53a13..485a7470 100644 --- a/crates/server/src/modules/testing.rs +++ b/crates/server/src/modules/testing.rs @@ -111,8 +111,8 @@ pub fn instance( description: None, client_reason: Default::default(), dry_run: true, - auth_token: None, - tls: None, + secrets: Default::default(), + credentials: Ok(Default::default()), params: serde_json::json!({}), file_managed_params: false, }, diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md index fa08432a..9f8da377 100644 --- a/docs/CONFIGURATION.md +++ b/docs/CONFIGURATION.md @@ -381,7 +381,7 @@ modules guide](./guides/policy-modules/README.md). | Variable | Default | Notes | |---|---|---| -| `GUARDIAN_MODULES_CONFIG` | _unset_ (no modules) | Path of the module catalog (TOML). Read once at startup; it declares every instance and seeds its global params on first start, after which params are managed through the [operator API](./DASHBOARD.md#policy-modules). A relative path resolves against the working directory; relative `auth.token_file` and `tls.*_file` paths in the catalog resolve against the catalog's directory. An enabled instance that fails its startup checks stops startup. In the prod stage remote instances must use TLS (`grpc://`) and set `auth`. | +| `GUARDIAN_MODULES_CONFIG` | _unset_ (no modules) | Path of the module catalog (TOML). Read once at startup; it declares every instance and seeds its global params on first start, after which params are managed through the [operator API](./DASHBOARD.md#policy-modules). A relative path resolves against the working directory; a relative `tls.ca_file` in the catalog resolves against the catalog's directory, and `auth.token_secret`, `tls.client_cert_secret`, `tls.client_key_secret` and `$secret` params name secrets read through `GUARDIAN_MODULE_SECRET_PROVIDER`. An enabled instance that fails its startup checks stops startup. In the prod stage remote instances must use TLS (`grpc://`) and set `auth`. | | `GUARDIAN_MODULE_CHECK_RATE_PER_MIN` | `30` | Dry-run proposal checks (`POST /delta/proposal/check`) one signer may make for one account per minute; excess returns `rate_limit_exceeded`. Per replica. A value that is not a positive integer refuses startup. | | `GUARDIAN_MODULES_STATE` | `/modules` | Filesystem builds only: directory of the module state file (`module_state.json`). Postgres builds keep module state in the database. | | `GUARDIAN_MODULE_EVALUATION_BUDGET_MS` | `1000` | Time spent in module calls for one hook invocation (request assembly is not charged). Each call gets the smaller of its `timeout_ms` and what is left; once spent, later modules count as timed out and their `on_error` applies. In the prod stage startup refuses a catalog whose `all` instances, enabled or not, exceed it at any hook, and a budget not below the execution reservation lease; account assignments and layers that could exceed it are refused at write time. Client and SDK request timeouts must exceed it, or a slow approval arrives after the client retried. | @@ -389,6 +389,8 @@ modules guide](./guides/policy-modules/README.md). | `GUARDIAN_MODULE_BREAKER_FAILURES` | `5` | Consecutive failures (timeouts, transport errors, malformed decisions) that open an instance's circuit breaker on a replica. While open the module is not called and its `on_error` applies at once. A deny is an answer and resets the count. | | `GUARDIAN_MODULE_PROBE_INTERVAL_MS` | `5000` | Interval of the `Describe` health probe of every enabled instance. A successful probe moves an open breaker to half-open, where the next call decides; the result is `guardian_module_up`. | | `GUARDIAN_MODULE_PARAMS_MAX_BYTES` | `65536` (64 KiB) | Largest params value one write may store (global params, an account layer or an assignment entry), measured as compact JSON with sorted keys. A larger write is refused with `invalid_input` before the module is called, and a larger catalog seed refuses startup, so no params value can push every request for an account over `GUARDIAN_MODULE_REQUEST_MAX_BYTES`. | +| `GUARDIAN_MODULE_SECRET_PROVIDER` | `aws` in the prod stage, `file` otherwise | Where the secrets a module catalog names (`auth.token_secret`, `tls.client_cert_secret`, `tls.client_key_secret`, `$secret` params) are read from, once at startup. `file`: one file per secret below `GUARDIAN_MODULE_SECRET_DIR`, readable by its owner only (`0600`). `aws`: AWS Secrets Manager secret ids, with `AWS_REGION` set. Not consulted when the catalog names no secret. | +| `GUARDIAN_MODULE_SECRET_DIR` | the catalog's directory | Directory of the `file` secrets provider; a secret name is a relative path below it. | ## Runtime — EVM (feature-gated) diff --git a/docs/guides/policy-modules/custom.md b/docs/guides/policy-modules/custom.md index 49a02aa7..33831007 100644 --- a/docs/guides/policy-modules/custom.md +++ b/docs/guides/policy-modules/custom.md @@ -75,7 +75,7 @@ does not understand. The [remote](./remote.md) page explains the transport. ```sh -openssl rand -hex 32 > .guardian/note-policy.token +(umask 077; openssl rand -hex 32 > .guardian/note-policy.token) cargo run -p guardian-module-sdk --example note-policy-serve -- \ --listen 127.0.0.1:7444 --instance note-policy .guardian/note-policy.token cp docs/guides/policy-modules/custom.toml .guardian/ diff --git a/docs/guides/policy-modules/custom.toml b/docs/guides/policy-modules/custom.toml index 82ee9d1b..889ac227 100644 --- a/docs/guides/policy-modules/custom.toml +++ b/docs/guides/policy-modules/custom.toml @@ -1,5 +1,5 @@ # Custom module: note-policy, written against guardian-module-sdk and served over gRPC. -# Copy to .guardian/custom.toml, put the bearer token in .guardian/note-policy.token, +# Copy to .guardian/custom.toml, put the bearer token in .guardian/note-policy.token (mode 0600), # and start the module before the Guardian (see custom.md). [[module]] @@ -11,5 +11,5 @@ hooks = ["before_proposal_created", "before_transaction_approved"] timeout_ms = 200 on_error = "deny" operator_can_disable = true -auth = { token_file = "note-policy.token" } +auth = { token_secret = "note-policy.token" } params = { max_payment_notes = 1, deny_private_notes = true } diff --git a/docs/guides/policy-modules/remote.md b/docs/guides/policy-modules/remote.md index ebc53b75..48a5d1ad 100644 --- a/docs/guides/policy-modules/remote.md +++ b/docs/guides/policy-modules/remote.md @@ -30,7 +30,7 @@ Each instance authenticates the Guardian with a bearer token, sent on every call: ```sh -openssl rand -hex 32 > .guardian/caps.token +(umask 077; openssl rand -hex 32 > .guardian/caps.token) cargo run -p guardian-module-sdk --example basic-policy-serve -- \ --listen 127.0.0.1:7443 --instance caps-remote .guardian/caps.token ``` @@ -48,8 +48,11 @@ cp docs/guides/policy-modules/remote.toml .guardian/ Replace the faucet placeholder, set `GUARDIAN_MODULES_CONFIG=.guardian/remote.toml` in the guide's `.env`, and start the server as in the setup. The module must already be running: an enabled instance that cannot be reached stops startup. -The log line lists `caps-remote=basic-policy 0.18.1`. The token path resolves -against the catalog's directory. +The log line lists `caps-remote=basic-policy 0.18.1`. + +`auth.token_secret` names a secret in the Guardian's secrets backend (see +[Credentials](#credentials)); here the `file` provider reads it from +`.guardian/caps.token`. ## 3. Try it @@ -69,9 +72,12 @@ against the catalog's directory. ```toml endpoint = "grpc://risk.internal:7443" - tls = { ca_file = "risk-ca.pem", client_cert_file = "guardian.pem", client_key_file = "guardian.key" } + tls = { ca_file = "risk-ca.pem", client_cert_secret = "guardian/modules/risk-cert", client_key_secret = "guardian/modules/risk-key" } ``` + `ca_file` is a path (relative to the catalog's directory); the client + certificate and key are secret names, like the token. + - Plain text needs the explicit `grpc+insecure://` scheme and a loopback host (`127.0.0.1`, `localhost`, `::1`), so a missing letter cannot turn TLS off. - In the prod stage (`GUARDIAN_ENV=prod`) plain text is refused and `auth` is @@ -80,6 +86,20 @@ against the catalog's directory. TLS-terminating proxy on the module's host, or serve the module with your own tonic server configured for TLS. +## Credentials + +The token and the mTLS client certificate and key are secrets, named in the +catalog and read once at startup through the secrets backend that +`GUARDIAN_MODULE_SECRET_PROVIDER` selects: + +| Provider | Default for | A secret name is | +|---|---|---| +| `file` | every stage but prod | A path below `GUARDIAN_MODULE_SECRET_DIR` (the catalog's directory when unset). The file must be readable by its owner only (`0600`), or startup refuses it | +| `aws` | the prod stage | An AWS Secrets Manager secret id, read with the task's credentials (`AWS_REGION` required) | + +An enabled instance whose secret cannot be read stops startup; a disabled one +stays disabled. Changing a secret takes effect at the next restart. + ## What a remote module cannot do It cannot sign, change its own params or hooks, or see secrets: catalog params diff --git a/docs/guides/policy-modules/remote.toml b/docs/guides/policy-modules/remote.toml index 9cbd12f0..b5d485d8 100644 --- a/docs/guides/policy-modules/remote.toml +++ b/docs/guides/policy-modules/remote.toml @@ -1,5 +1,5 @@ # Remote module: the same basic-policy served by a separate process over gRPC. -# Copy to .guardian/remote.toml, put the bearer token in .guardian/caps.token, +# Copy to .guardian/remote.toml, put the bearer token in .guardian/caps.token (mode 0600), # and start the module before the Guardian (see remote.md). [[module]] @@ -22,5 +22,5 @@ hooks = ["before_proposal_created", "before_transaction_approved"] timeout_ms = 200 on_error = "deny" operator_can_disable = true -auth = { token_file = "caps.token" } +auth = { token_secret = "caps.token" } params = { max_amount_per_tx = { "0xREPLACE_WITH_FAUCET_ID" = "3" } } diff --git a/docs/rfcs/0002-guardian-modules.md b/docs/rfcs/0002-guardian-modules.md index 1facf0e1..47ca0cf7 100644 --- a/docs/rfcs/0002-guardian-modules.md +++ b/docs/rfcs/0002-guardian-modules.md @@ -7,7 +7,7 @@ | **Feature** | [#251](https://github.com/OpenZeppelin/guardian/issues/251) ("Modularization: middleware architecture and pluggable modules"); first consumer [#182](https://github.com/OpenZeppelin/guardian/issues/182) (policy evaluation). [#252](https://github.com/OpenZeppelin/guardian/issues/252) (x402 facilitator) is a later consumer: its payment-policy half (caps, allowlists, replay) fits `before_transaction_approved` and `after_transaction_committed`, its facilitator half (`/verify`, `/settle`, a flow that starts and waits) does not fit allow/deny and is future work (section 7) | | **Audience** | Operators, module authors, integrators, and anyone reviewing the Guardian trust model | | **Working artifacts** | [`speckit/features/251-guardian-modules/`](../../speckit/features/251-guardian-modules/spec.md): the specification, written alongside this RFC; plan and tasks follow the prototype | -| **Revision** | 29 (2026-11-09): `default` copies written right after the claim on both backends (section 2.3); changes in Appendix C | +| **Revision** | 30 (2026-11-09): the secrets backend and the catalog's credential field names (section 2.2); changes in Appendix C | | **Review sought** | Comments on the design and the M2a scope remain open until M2a ships, when `guardian.module.v1` freezes (section 7) | | **Code baseline** | `main` at `ca503704`; execution-path citations read on `254-execution-impl` at `29c722b4` (PR #510, since merged to `main` as `1100f3a4`) and kept as dated evidence. Miden pins: protocol and standards 0.17.1. Appendices B and C cite the baselines of their revisions. Prototype findings (2026-10-13 to 2026-10-15) in `speckit/features/251-guardian-modules/research.md` | @@ -135,7 +135,7 @@ pub trait ModuleFactory: Send + Sync { } ``` -**Instance identity.** Every message the Guardian sends to a module carries `instance_id`, the catalog `id` of the instance it is calling (`ValidateParamsRequest`, `HookRequest`, `CommitEvent`, `Gap`). One remote service can therefore back several instances, for example a sanctions service configured once per list, and keep their state, delivery watermarks and resync handling apart: a module keys all state by (`instance_id`, `account_id`). Each instance has its own `auth` credential, and the `serve` harness binds credentials to instance ids (`.instance("sanctions-ofac", token_file)`), rejecting with `PERMISSION_DENIED` a request whose `instance_id` does not match the credential that authenticated it. An operator who prefers full isolation can still give each instance its own endpoint; the protocol does not depend on it. +**Instance identity.** Every message the Guardian sends to a module carries `instance_id`, the catalog `id` of the instance it is calling (`ValidateParamsRequest`, `HookRequest`, `CommitEvent`, `Gap`). One remote service can therefore back several instances, for example a sanctions service configured once per list, and keep their state, delivery watermarks and resync handling apart: a module keys all state by (`instance_id`, `account_id`). Each instance has its own `auth` credential, and the `serve` harness binds credentials to instance ids (`.instance("sanctions-ofac", token)`), rejecting with `PERMISSION_DENIED` a request whose `instance_id` does not match the credential that authenticated it. An operator who prefers full isolation can still give each instance its own endpoint; the protocol does not depend on it. The trait, the factory and all protocol types live in a separately published crate, `guardian-module-sdk`, so a kind can be written without depending on the server (section 2.5). `notify` and `notify_gap` have default no-ops, so a stateless kind implements only `describe`, `validate_params` and `evaluate`; stateful kinds override it to reset or re-seed state after a gap (section 3.3). Besides the trait, the SDK provides what the prototype showed every module needs: `Decision::allow` and `Decision::deny`, `ParamsVerdict::ok` and `ParamsVerdict::invalid`, reason-code validation, typed accessors over the generated messages (for example the fungible amount of an `Asset`), and `ModuleInstanceConfig`, the configuration a factory receives, whose bearer token is a secret type, redacted from debug output and zeroized when dropped. The `GrpcModule` implementation (and `HttpModule`, when that kind ships) calls the `NotifyGap` RPC, and the `serve` harness routes `NotifyGap` to `notify_gap`, so in-process and remote modules see gaps the same way. @@ -168,8 +168,8 @@ Each catalog entry: | `hooks` | Subset of the hooks in section 2.3 | | `timeout_ms` | Required; from 1 to `GUARDIAN_MODULE_TIMEOUT_MAX_MS` (default 1000) | | `on_error` | `deny` (default) or `allow` (section 4) | -| `auth` | Remote kinds only, mandatory in the prod stage: secret reference for the bearer token (section 5.2) | -| `tls` | Remote kinds only, optional: `ca_file` (PEM bundle for a private CA; the system roots otherwise) and `client_cert` and `client_key` secret references for mTLS (section 5.2) | +| `auth` | Remote kinds only, mandatory in the prod stage: `token_secret`, the secret name of the bearer token (section 5.2) | +| `tls` | Remote kinds only, optional: `ca_file` (PEM bundle for a private CA, relative to the catalog's directory; the system roots otherwise) and `client_cert_secret` and `client_key_secret`, secret names, for mTLS (section 5.2) | | `params` | Initial global parameters as a JSON object, written to the metadata store the first time the instance id is seen and managed through the operator API afterwards (see layered parameters below) (TOML tables in the catalog are converted to JSON). Modules receive params as UTF-8 JSON bytes in RFC 8785 canonical form (JCS). The decoded bytes are identical on every transport: in process and over gRPC they arrive as raw bytes, while over `http` (once it ships) the proto3 JSON mapping carries them as a base64 string that decodes to the same bytes (likewise `int64` fields arrive as decimal strings and `Timestamp` fields as RFC 3339 strings, per the standard mapping). See "Parameters and secrets" below | | `require_fresh_state_ms` | Optional maximum notify lag in milliseconds (section 3.3) | | `enabled` | Default `true`. A one-time seed, read only the first time an instance id is seen; afterwards the runtime flag in the metadata store governs and later edits of this field have no effect (see runtime changes below) | @@ -197,7 +197,7 @@ on_error = "allow" auth = { token_secret = "guardian/modules/risk-vendor-token" } ``` -**Parameters and secrets.** Params are a JSON object. A value of the form `{"$secret": ""}` is a secret reference, resolved by the Guardian through its secrets backend. `$secret` is a reserved key at any depth: the Guardian scans params recursively, so a reference nested inside another object is found and treated exactly like a top-level one, and no module param may use `$secret` as an ordinary key. Secret references are allowed only in catalog entries of in-process kinds, and are resolved when the instance is created. They are rejected in catalog entries of remote kinds (a remote module holds its own credentials) and in per-account params written through the operator API (otherwise a session could read arbitrary secrets through a module). Resolved secret values are never placed in a `HookRequest`, so they never reach a remote module. An in-process instance whose catalog params contain references receives, in its own `HookRequest.params`, the unresolved form with the references intact; it holds the resolved values from its factory, which received them when the instance was created. The `serve` harness and the conformance suite follow the same rule and never substitute. +**Parameters and secrets.** Params are a JSON object. A value of the form `{"$secret": ""}` is a secret reference, resolved by the Guardian through its secrets backend (`GUARDIAN_MODULE_SECRET_PROVIDER`: AWS Secrets Manager by default in the prod stage, owner-only files below `GUARDIAN_MODULE_SECRET_DIR` otherwise). `$secret` is a reserved key at any depth: the Guardian scans params recursively, so a reference nested inside another object is found and treated exactly like a top-level one, and no module param may use `$secret` as an ordinary key. Secret references are allowed only in catalog entries of in-process kinds, and are resolved when the instance is created. They are rejected in catalog entries of remote kinds (a remote module holds its own credentials) and in per-account params written through the operator API (otherwise a session could read arbitrary secrets through a module). Resolved secret values are never placed in a `HookRequest`, so they never reach a remote module. An in-process instance whose catalog params contain references receives, in its own `HookRequest.params`, the unresolved form with the references intact; it holds the resolved values from its factory, which received them when the instance was created. The `serve` harness and the conformance suite follow the same rule and never substitute. The catalog is loaded in `ServerBuilder::build()`, after every `with_module_kind` call, so custom kinds are registered before any instance names them. `build()` creates every instance through its kind's factory, calls `describe` on it and checks that it supports the hooks it is configured for and speaks a supported `protocol_version`, then calls `validate_params` on the instance's stored global params (the catalog's `params` on first start), in the same unresolved form the module later receives in `HookRequest.params` (secret references intact), so a mistyped value in the catalog fails at startup rather than on the first transaction. In the prod stage a mismatch or an unreachable enabled module stops startup, mirroring `reject_filesystem_in_prod`; a disabled instance that fails these checks is logged and stays disabled, and enabling it runs the same checks first. Failing to create the instance at all, because its kind is not registered or its factory rejects the configuration (for example a malformed endpoint), is one of these failures: it stops startup for an enabled instance and leaves a disabled one disabled, so an operator can stage an instance for a module or a build that is not deployed yet. @@ -1046,7 +1046,7 @@ The health probe is a `Describe` call every `GUARDIAN_MODULE_PROBE_INTERVAL_MS` - In the prod stage, `auth` is mandatory for remote kinds; a remote instance without it stops startup. - The Guardian sends a per-module bearer token (gRPC metadata `authorization`, HTTP `Authorization` header) read from the secrets backend, so the module can reject callers that are not this Guardian. Without it, anyone could probe the module or forge commit events that corrupt its counters. - The Guardian authenticates the module through TLS server authentication, against the system roots or the instance's `tls.ca_file`. -- mTLS is an optional per-instance setting (`tls.client_cert`, `tls.client_key`, both secret references) for operators who already run a CA. +- mTLS is an optional per-instance setting (`tls.client_cert_secret`, `tls.client_key_secret`, both secret names) for operators who already run a CA. - The bearer token and client key are held in secret types: redacted from logs and debug output, and zeroized when dropped. - No Guardian signing key is reused for module authentication. - Replaying a captured `CommitEvent` cannot change a module's state: its nonce is at or below the module's watermark, so it is acknowledged without effect (section 3.3). Forging a new event requires the bearer token. Signing each request body with a timestamp (the Standard Webhooks pattern) was considered; with a shared secret it adds only that the secret itself is never sent, which mTLS already provides for operators who need it. @@ -1206,6 +1206,7 @@ None. Questions resolved in earlier revisions are kept below with their answers. | Revision | Date | Changes | |---|---|---| +| 30 | 2026-11-09 | the secrets backend named: `GUARDIAN_MODULE_SECRET_PROVIDER` selects AWS Secrets Manager (the prod default) or owner-only files below `GUARDIAN_MODULE_SECRET_DIR`, read once when the instances are created; a secret that cannot be read fails creation, with the enabled/disabled rule of section 2.2. Field names fixed as `auth.token_secret`, `tls.client_cert_secret` and `tls.client_key_secret`; a secret name is 1 to 512 characters of letters, digits and `/_+=.@-`, and a `$secret` object has no other key (section 2.2). In-process factories read `$secret` values from `ModuleInstanceConfig::secret`. No protocol change | | 29 | 2026-11-09 | M2a implementation of `scope = default`: the copy is written right after the claim, only into an account with no assignment and no assignment history, under the module state lock, instead of in the claim's transaction on Postgres and before the claim on the filesystem; a crash in between is repaired by the unfinished-claim retry, so both backends follow one rule and no transaction spans the metadata and module stores (section 2.3). No protocol change | | 28 | 2026-11-09 | protocol version 1 frozen: the freeze criteria of section 7 met at `e4efd839` on `251-modules-m2a`, with tests; the proto copies say so. No design change | | 27 | 2026-11-09 | `proposer_session` removed from `TransactionSubject`, `PendingTransaction` and `CommitEvent`, and `unverified_metadata` renumbered to 5 before the freeze: a session key cannot approve a proposal, so whether one created it adds nothing the threshold does not already require, and no catalog policy uses it; version 1 can add it later. Section 3.2 corrected for #580: `push_delta` and Guardian execution accept session credentials, so `submitter_session` can be true at the ack. Freeze criteria and the M2a list updated (section 7) | diff --git a/docs/runbooks/secrets.md b/docs/runbooks/secrets.md index e2fd958a..38a0d94a 100644 --- a/docs/runbooks/secrets.md +++ b/docs/runbooks/secrets.md @@ -19,6 +19,7 @@ this doc covers *how* to bootstrap, replace, and respond to compromise. | Operator public keys | Secrets Manager (Terraform-managed or pre-existing ARN) | Updated by editing Terraform var or rotating the secret value | ECS task runtime role, on each dashboard challenge **and each authenticated `/dashboard/*` request** (hot-reloaded — no restart needed) | | EVM allowed chains + RPC URLs | Secrets Manager (Terraform-managed) | Updated by editing `config/evm/chains.json` and redeploying | ECS task execution role; surfaced as env to the task | | Remote prover URL (optional, Guardian execution) | Secrets Manager: Terraform-managed `/server/tx-prover-url` from `guardian_tx_prover_url`, or a pre-existing ARN in `guardian_tx_prover_url_secret_arn`. An `http(s)` URL with a host and no userinfo, query or fragment (the server refuses those at startup), so it holds no credentials; a private prover is restricted at the network level | Managed secret: change `guardian_tx_prover_url` and redeploy. The task definition reads the secret at its pinned version, so the new version produces a new task definition revision and the deploy (including `deploy --skip-build`) rolls the tasks onto the new URL. Pre-existing ARN: the task reads `AWSCURRENT` when it starts, and rotating the value does not change the task definition, so run `aws ecs update-service --cluster --service --force-new-deployment` afterwards. The managed secret has a 7-day recovery window (`aws secretsmanager restore-secret`), and a plan that would delete it fails unless `guardian_execution_enabled = false` | ECS task execution role (plus `kms:Decrypt` on the key when a pre-existing secret uses a customer-managed KMS key); surfaced as `GUARDIAN_TX_PROVER_URL` to the task | +| Policy module credentials (optional) | `GUARDIAN_MODULE_SECRET_PROVIDER`: Secrets Manager (`aws`, the prod default) or owner-only files (`file`); names come from the module catalog | Created and rotated by the operator; read once at startup, so a change takes effect at the next restart | ECS task **runtime** role, at server startup | The ACK secret name is one value that travels through three places. They have **different variable names by design** — each layer has a distinct @@ -532,6 +533,40 @@ To rotate an RPC URL (e.g. switch provider): 1. Edit `chains.json`, redeploy. No special handling — the server treats chain config as a startup-time read. +## Policy module secrets + +A module catalog (`GUARDIAN_MODULES_CONFIG`) names three kinds of secrets: the +bearer token of a remote instance (`auth.token_secret`), its mTLS client +certificate and key (`tls.client_cert_secret`, `tls.client_key_secret`), and +`{ "$secret" = "" }` values in the params of an in-process instance. The +server reads them once, when it creates the instances, through the provider +`GUARDIAN_MODULE_SECRET_PROVIDER` selects; see +[CONFIGURATION.md](../CONFIGURATION.md) and the +[remote module guide](../guides/policy-modules/remote.md#credentials). + +- **AWS (`aws`).** A name is a Secrets Manager secret id holding a secret + string. The reference Terraform does not create these secrets or grant the + task access to them: create each secret, then grant the ECS task runtime role + `secretsmanager:GetSecretValue` on it before enabling the instance. +- **Files (`file`).** A name is a relative path below + `GUARDIAN_MODULE_SECRET_DIR` (the catalog's directory when unset). The server + refuses a file readable by group or others, as it does for ACK key files; a + Kubernetes secret mount needs `defaultMode: 0400`. + +**Rotating a token.** Configure the module to accept both the old and the new +token for the instance, update the secret, restart the Guardian replicas, then +drop the old token from the module. A module served by the SDK harness holds one +token per instance, so restart it with the new token right after the Guardian. + +**Compromise.** A leaked module token lets its holder call the module as the +Guardian: probe decisions, or, once notify ships, forge commit events. Replace +the token as above and review the module's logs for calls that do not match the +Guardian's `request_id`s. A leaked `$secret` value is the third party's +credential (a vendor API key): revoke it with the vendor. + +A secret that cannot be read stops startup for an enabled instance and leaves a +disabled one disabled; the error names the secret, never its value. + ## Audit trail CloudTrail `GetSecretValue` events are scoped per-secret ARN. The @@ -545,6 +580,7 @@ relevant principals you should see hitting each secret: | Operator pubkeys | ECS task runtime role + operators updating the list | | EVM chains / RPCs | ECS task execution role only | | Prover URL | ECS task execution role only | +| Policy module credentials | ECS task runtime role (on cold start) + operators rotating them | Any other principal touching these secrets is suspicious. diff --git a/speckit/features/251-guardian-modules/contracts/catalog-config.md b/speckit/features/251-guardian-modules/contracts/catalog-config.md index c13eb80c..1a148e65 100644 --- a/speckit/features/251-guardian-modules/contracts/catalog-config.md +++ b/speckit/features/251-guardian-modules/contracts/catalog-config.md @@ -41,7 +41,7 @@ hooks = ["before_transaction_approved"] timeout_ms = 300 on_error = "allow" auth = { token_secret = "guardian/modules/risk-vendor-token" } -tls = { ca_file = "risk-ca.pem" } # optional; client_cert / client_key secret references add mTLS +tls = { ca_file = "risk-ca.pem" } # optional; client_cert_secret and client_key_secret add mTLS ``` ## Disclosure (RFC 0002 section 2.7) @@ -62,7 +62,16 @@ tls = { ca_file = "risk-ca.pem" } # optional; client_cert / client_key secre Plain text needs its own scheme so a missing letter cannot turn TLS off. In the prod stage every remote instance must use `grpc://` and set `auth`, or startup stops. `auth` and `tls` are allowed only on remote kinds. -The prototype (#554) reads secrets from files instead of the secrets backend: `auth = { token_file = "..." }` and `tls = { ca_file, client_cert_file, client_key_file }`, paths relative to the catalog file. +## Secrets + +`auth.token_secret`, `tls.client_cert_secret`, `tls.client_key_secret` and `{ "$secret" = "" }` in the params of an in-process instance name secrets; `tls.ca_file` is a path, relative to the catalog's directory. A name is 1 to 512 characters of letters, digits and `/_+=.@-`, and a `$secret` object has no other key. Secrets are read once, when the instances are created, through `GUARDIAN_MODULE_SECRET_PROVIDER`: + +| Provider | Default | Name | +|---|---|---| +| `file` | Outside the prod stage | Path below `GUARDIAN_MODULE_SECRET_DIR` (default: the catalog's directory), no `.` or `..` segments, file mode `0600` | +| `aws` | Prod stage | AWS Secrets Manager secret id; needs `AWS_REGION` | + +A secret that cannot be read fails the instance's creation: startup stops for an enabled instance, and a disabled one stays disabled. The token is trimmed of surrounding whitespace. `$secret` values reach only the in-process factory (`ModuleInstanceConfig::secret`); `HookRequest.params` keeps the references, and they are refused in remote params, account layers and the operator API. ## Kinds diff --git a/speckit/features/251-guardian-modules/quickstart.md b/speckit/features/251-guardian-modules/quickstart.md index 9609b4de..7e2b29d0 100644 --- a/speckit/features/251-guardian-modules/quickstart.md +++ b/speckit/features/251-guardian-modules/quickstart.md @@ -46,14 +46,14 @@ cargo run -p guardian-module-sdk --example basic-policy-serve -- \ --listen 127.0.0.1:7443 --instance caps-remote .guardian/caps.token ``` -The harness speaks plain text, so the catalog entry uses the loopback scheme and the same token (relative to the catalog file): +The harness speaks plain text, so the catalog entry uses the loopback scheme and the same token, named as a secret: ```toml [[module]] id = "caps-remote" kind = "grpc" endpoint = "grpc+insecure://127.0.0.1:7443" -auth = { token_file = "caps.token" } # prototype stand-in; M2a uses token_secret (RFC 0002 section 2.2) +auth = { token_secret = "caps.token" } # read by the file provider from the catalog directory, mode 0600 ``` Point this second instance of kind `grpc` at it with `on_error = "deny"`, repeat step 2, then stop the module: pushes return `GUARDIAN_MODULE_UNAVAILABLE`; after five failures they return without waiting for the timeout; `guardian_module_up` drops to 0. Switch to `on_error = "allow"`: pushes proceed and `guardian_module_fail_open_total` increases. (US4, US6) diff --git a/speckit/features/251-guardian-modules/tasks.md b/speckit/features/251-guardian-modules/tasks.md index d739de33..02b424cf 100644 --- a/speckit/features/251-guardian-modules/tasks.md +++ b/speckit/features/251-guardian-modules/tasks.md @@ -175,7 +175,7 @@ ### Implementation for User Story 6 -- [ ] T048 [US6] Secret references through the secrets backend: replace `auth.token_file` and `tls.*_file` in `crates/server/src/modules/catalog.rs` and `crates/server/src/modules/grpc_kind.rs` with secret references resolved when the instance is created, following `docs/runbooks/secrets.md`; resolve `$secret` in in-process params at creation and pass them only to the in-process module, never in a request; keep rejection in remote params, account layers and the operator API; update `speckit/features/251-guardian-modules/contracts/catalog-config.md` +- [X] T048 [US6] Secret references through the secrets backend: replace `auth.token_file` and `tls.*_file` in `crates/server/src/modules/catalog.rs` and `crates/server/src/modules/grpc_kind.rs` with secret references resolved when the instance is created, following `docs/runbooks/secrets.md`; resolve `$secret` in in-process params at creation and pass them only to the in-process module, never in a request; keep rejection in remote params, account layers and the operator API; update `speckit/features/251-guardian-modules/contracts/catalog-config.md` - [ ] T049 [US6] `examples/policy-module/`: `basic-policy` as a standalone gRPC service through the `serve` harness, with `Cargo.toml`, `README.md` (run, TLS, per-instance token), a `Dockerfile`, and a matching remote catalog entry in `docs/guides/policy-modules/remote.toml` - [ ] T050 [US6] Publishable `guardian-module-sdk`: crates.io metadata in `crates/guardian-module-sdk/Cargo.toml`, `crates/guardian-module-sdk/README.md` (module author quick start), and the crate added to the release order of the `release-guardian-sdk-packages` skill - [ ] T051 [US6] Remote module author guide in `docs/guides/policy-modules/custom.md` and `remote.md`: protocol version 1, request fields, `reason_code` rules, `client_message`, `dry_run`, conformance suite, credentials; written so SC-011 holds without reading server code From 4d79fb2184950ab1c588283639803a5ec223d429 Mon Sep 17 00:00:00 2001 From: Zeljko Date: Mon, 9 Nov 2026 11:43:52 +0100 Subject: [PATCH 034/105] chore(module-sdk): lockfile entry for the conformance dev-dependency (#251) --- Cargo.lock | 1 + 1 file changed, 1 insertion(+) diff --git a/Cargo.lock b/Cargo.lock index c1f47692..91ef5f34 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -3475,6 +3475,7 @@ name = "guardian-module-sdk" version = "0.19.0-rc.1" dependencies = [ "async-trait", + "guardian-module-sdk", "prost", "prost-types", "secrecy", From 0b608a3f50c759658b869913e3b6099b47488b93 Mon Sep 17 00:00:00 2001 From: Zeljko Date: Mon, 9 Nov 2026 11:51:25 +0100 Subject: [PATCH 035/105] feat(examples): basic-policy as a standalone policy module (#251) examples/policy-module serves basic-policy over gRPC through the SDK harness, with a token per instance, TLS and mutual TLS, and refuses plain text on a non-loopback address without --insecure. Dockerfile builds it from the repository root and runs it unprivileged. The remote guide uses it in place of the SDK's basic-policy-serve example, which is removed. --- Cargo.lock | 9 ++ Cargo.toml | 1 + .../examples/basic-policy-serve.rs | 30 ---- docs/guides/policy-modules/remote.md | 17 +- docs/guides/policy-modules/remote.toml | 14 ++ examples/README.md | 1 + examples/policy-module/Cargo.toml | 15 ++ examples/policy-module/Dockerfile | 21 +++ examples/policy-module/README.md | 73 +++++++++ examples/policy-module/src/main.rs | 147 ++++++++++++++++++ speckit/features/251-guardian-modules/plan.md | 4 +- .../251-guardian-modules/quickstart.md | 2 +- 12 files changed, 294 insertions(+), 40 deletions(-) delete mode 100644 crates/guardian-module-sdk/examples/basic-policy-serve.rs create mode 100644 examples/policy-module/Cargo.toml create mode 100644 examples/policy-module/Dockerfile create mode 100644 examples/policy-module/README.md create mode 100644 examples/policy-module/src/main.rs diff --git a/Cargo.lock b/Cargo.lock index 91ef5f34..853e7c6d 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -3488,6 +3488,15 @@ dependencies = [ "tonic-prost-build", ] +[[package]] +name = "guardian-policy-module" +version = "0.1.0" +dependencies = [ + "guardian-module-sdk", + "tokio", + "tonic", +] + [[package]] name = "guardian-prod-benchmarks" version = "0.1.0" diff --git a/Cargo.toml b/Cargo.toml index 2cc66f27..4430abf0 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -13,6 +13,7 @@ members = [ "crates/qualification-driver", "examples/rust", "examples/demo", + "examples/policy-module", ] default-members = [ "crates/shared", diff --git a/crates/guardian-module-sdk/examples/basic-policy-serve.rs b/crates/guardian-module-sdk/examples/basic-policy-serve.rs deleted file mode 100644 index 9a2e6f76..00000000 --- a/crates/guardian-module-sdk/examples/basic-policy-serve.rs +++ /dev/null @@ -1,30 +0,0 @@ -use std::net::SocketAddr; - -use guardian_module_sdk::basic_policy::BasicPolicy; -use guardian_module_sdk::serve::serve; - -#[tokio::main] -async fn main() -> Result<(), Box> { - let mut args = std::env::args().skip(1); - let mut listen: SocketAddr = "127.0.0.1:7443".parse()?; - let mut instances = Vec::new(); - while let Some(arg) = args.next() { - match arg.as_str() { - "--listen" => listen = args.next().ok_or("--listen needs an address")?.parse()?, - "--instance" => { - let id = args.next().ok_or("--instance needs an id")?; - let token_file = args.next().ok_or("--instance needs a token file")?; - instances.push((id, std::fs::read_to_string(token_file)?.trim().to_string())); - } - other => return Err(format!("unknown argument {other}").into()), - } - } - - let mut server = serve(BasicPolicy); - for (id, token) in instances { - server = server.instance(id, token); - } - println!("basic-policy listening on {listen}"); - server.run(listen).await?; - Ok(()) -} diff --git a/docs/guides/policy-modules/remote.md b/docs/guides/policy-modules/remote.md index 48a5d1ad..31c9167c 100644 --- a/docs/guides/policy-modules/remote.md +++ b/docs/guides/policy-modules/remote.md @@ -31,13 +31,14 @@ call: ```sh (umask 077; openssl rand -hex 32 > .guardian/caps.token) -cargo run -p guardian-module-sdk --example basic-policy-serve -- \ +cargo run -p guardian-policy-module -- \ --listen 127.0.0.1:7443 --instance caps-remote .guardian/caps.token ``` -The serve harness accepts a call only for an instance id it knows, with that -instance's token. One process can host several instances, each with its own -token: repeat `--instance`. +The module is [`examples/policy-module`](../../../examples/policy-module/README.md), +built on the SDK's serve harness. It accepts a call only for an instance id it +knows, with that instance's token. One process can host several instances, each +with its own token: repeat `--instance`. ## 2. Catalog and server @@ -82,9 +83,11 @@ The log line lists `caps-remote=basic-policy 0.18.1`. (`127.0.0.1`, `localhost`, `::1`), so a missing letter cannot turn TLS off. - In the prod stage (`GUARDIAN_ENV=prod`) plain text is refused and `auth` is mandatory for every remote instance. -- The SDK's serve harness speaks plain text only, so for TLS put it behind a - TLS-terminating proxy on the module's host, or serve the module with your own - tonic server configured for TLS. +- The example module serves TLS and mutual TLS itself (`--tls-cert`, + `--tls-key`, `--client-ca`); see its + [README](../../../examples/policy-module/README.md#tls). A module built on + the SDK harness does the same by adding the harness service to a tonic + server configured for TLS. ## Credentials diff --git a/docs/guides/policy-modules/remote.toml b/docs/guides/policy-modules/remote.toml index b5d485d8..8ccfe35b 100644 --- a/docs/guides/policy-modules/remote.toml +++ b/docs/guides/policy-modules/remote.toml @@ -24,3 +24,17 @@ on_error = "deny" operator_can_disable = true auth = { token_secret = "caps.token" } params = { max_amount_per_tx = { "0xREPLACE_WITH_FAUCET_ID" = "3" } } + +# The same module on another host, over TLS (examples/policy-module/README.md). Its token is +# read from AWS Secrets Manager in the prod stage; the CA file is relative to this catalog. +# [[module]] +# id = "caps-remote" +# kind = "grpc" +# endpoint = "grpc://policy-module.internal:7443" +# scope = "all" +# hooks = ["before_proposal_created", "before_transaction_approved"] +# timeout_ms = 200 +# on_error = "deny" +# operator_can_disable = true +# auth = { token_secret = "guardian/modules/caps-remote-token" } +# tls = { ca_file = "module-ca.pem" } diff --git a/examples/README.md b/examples/README.md index fa1c10dc..954cbc0a 100644 --- a/examples/README.md +++ b/examples/README.md @@ -4,6 +4,7 @@ Small projects that showcase different ways to interact with Guardian: - [`demo/`](./demo/) – Terminal UI for hands-on experimentation (recommended starting point). - [`operator-smoke-web/`](./operator-smoke-web/) – Minimal browser UI for local Falcon operator login and account API calls through `@openzeppelin/guardian-operator-client`. +- [`policy-module/`](./policy-module/): `basic-policy` as a standalone policy module served over gRPC (TLS, per-instance tokens, Dockerfile), for the remote module guide. - [`rust/`](./rust/) – Low-level Rust example with binaries for both local-node and mockchain flows. - [`smoke-web/`](./smoke-web/) – Browser smoke harness for multisig workflows and wallet integrations. diff --git a/examples/policy-module/Cargo.toml b/examples/policy-module/Cargo.toml new file mode 100644 index 00000000..692f82f2 --- /dev/null +++ b/examples/policy-module/Cargo.toml @@ -0,0 +1,15 @@ +[package] +name = "guardian-policy-module" +version = "0.1.0" +edition = "2024" +publish = false +description = "basic-policy served as a standalone Guardian policy module over gRPC" + +[[bin]] +name = "policy-module" +path = "src/main.rs" + +[dependencies] +guardian-module-sdk = { path = "../../crates/guardian-module-sdk" } +tokio = { workspace = true, features = ["rt-multi-thread", "macros", "signal"] } +tonic = { workspace = true, features = ["tls-ring"] } diff --git a/examples/policy-module/Dockerfile b/examples/policy-module/Dockerfile new file mode 100644 index 00000000..2171300c --- /dev/null +++ b/examples/policy-module/Dockerfile @@ -0,0 +1,21 @@ +# basic-policy as a standalone Guardian policy module. Build from the repository root: +# docker build -f examples/policy-module/Dockerfile -t guardian-policy-module . +FROM rust:1.98.1-bookworm AS builder + +RUN apt-get update && apt-get install -y "protobuf-compiler=3.21.12-*" \ + && rm -rf /var/lib/apt/lists/* + +WORKDIR /app +COPY Cargo.toml Cargo.lock rust-toolchain.toml ./ +COPY crates ./crates +COPY benchmarks ./benchmarks +COPY examples ./examples +RUN cargo build --release --locked --package guardian-policy-module + +FROM debian:bookworm-slim@sha256:7e490910eea2861b9664577a96b54ce68ea3e02ce7f51d89cb0103a6f9c386e0 + +RUN useradd --system --no-create-home --uid 10001 module +COPY --from=builder /app/target/release/policy-module /usr/local/bin/policy-module +USER module +EXPOSE 7443 +ENTRYPOINT ["/usr/local/bin/policy-module"] diff --git a/examples/policy-module/README.md b/examples/policy-module/README.md new file mode 100644 index 00000000..7216840c --- /dev/null +++ b/examples/policy-module/README.md @@ -0,0 +1,73 @@ +# Policy module example + +`basic-policy`, the Guardian's built-in policy kind, served as its own process +over gRPC through the `serve` harness of +[`guardian-module-sdk`](../../crates/guardian-module-sdk). Use it to try a +remote module, or as the starting point for one: replace `BasicPolicy` with +your own `Module`. + +The Guardian side is a catalog entry of kind `grpc`; see the +[remote module guide](../../docs/guides/policy-modules/remote.md) and its +catalog, [`remote.toml`](../../docs/guides/policy-modules/remote.toml). + +## Run it + +Every instance the Guardian calls has an id (the catalog `id`) and its own +bearer token. The module accepts a call only for an instance it was started +with, carrying that instance's token. + +```sh +mkdir -p .guardian +(umask 077; openssl rand -hex 32 > .guardian/caps.token) +cargo run -p guardian-policy-module -- \ + --listen 127.0.0.1:7443 --instance caps-remote .guardian/caps.token +``` + +Repeat `--instance ID TOKEN_FILE` to host several instances in one process, for +example one per list. The Guardian reads the same token through its secrets +backend: `auth = { token_secret = "caps.token" }` with the default `file` +provider and the catalog in `.guardian/`. + +## TLS + +Without TLS the module listens in plain text, which the Guardian accepts only on +a loopback address (`grpc+insecure://127.0.0.1:7443`) and never in the prod +stage. The module refuses a plain-text listener on any other address unless +`--insecure` is given. + +```sh +policy-module --listen 0.0.0.0:7443 \ + --instance caps-remote /run/secrets/caps.token \ + --tls-cert /run/secrets/module.pem --tls-key /run/secrets/module.key +``` + +On the Guardian, `endpoint = "grpc://:7443"` and, for a private CA, +`tls = { ca_file = "module-ca.pem" }`. The certificate must name the host in +the endpoint and must not be a CA certificate itself. + +For mutual TLS add `--client-ca CA_PEM`: the module then refuses a connection +without a client certificate issued by that CA. The Guardian presents its +certificate and key from `tls.client_cert_secret` and `tls.client_key_secret`. + +## Docker + +Build from the repository root: + +```sh +docker build -f examples/policy-module/Dockerfile -t guardian-policy-module . +docker run --rm -p 7443:7443 -v "$PWD/secrets:/run/secrets:ro" guardian-policy-module \ + --listen 0.0.0.0:7443 \ + --instance caps-remote /run/secrets/caps.token \ + --tls-cert /run/secrets/module.pem --tls-key /run/secrets/module.key +``` + +The container runs as an unprivileged user (uid 10001), so the mounted files +must be readable by it. + +## Check a module before deploying it + +The SDK's conformance suite runs a module in process and over gRPC and checks +that both give the same answers, that `evaluate` has no side effects, and that +a request at the Guardian's size cap goes through. `basic-policy` runs it in +[`crates/guardian-module-sdk/tests/conformance.rs`](../../crates/guardian-module-sdk/tests/conformance.rs); +the same `Suite` works for your own module with the `conformance` feature. diff --git a/examples/policy-module/src/main.rs b/examples/policy-module/src/main.rs new file mode 100644 index 00000000..74415be2 --- /dev/null +++ b/examples/policy-module/src/main.rs @@ -0,0 +1,147 @@ +use std::net::SocketAddr; +use std::path::PathBuf; + +use guardian_module_sdk::basic_policy::BasicPolicy; +use guardian_module_sdk::serve::serve; +use tonic::transport::{Certificate, Identity, Server, ServerTlsConfig}; + +const USAGE: &str = "usage: policy-module [--listen ADDR] --instance ID TOKEN_FILE [--instance ...] + [--tls-cert PEM --tls-key PEM [--client-ca PEM]] [--insecure]"; + +struct Args { + listen: SocketAddr, + instances: Vec<(String, PathBuf)>, + tls_cert: Option, + tls_key: Option, + client_ca: Option, + insecure: bool, +} + +impl Args { + fn parse() -> Result { + let mut parsed = Self { + listen: SocketAddr::from(([127, 0, 0, 1], 7443)), + instances: Vec::new(), + tls_cert: None, + tls_key: None, + client_ca: None, + insecure: false, + }; + let mut args = std::env::args().skip(1); + let value = |args: &mut dyn Iterator, flag: &str| { + args.next().ok_or(format!("{flag} needs a value")) + }; + while let Some(arg) = args.next() { + match arg.as_str() { + "--listen" => { + parsed.listen = value(&mut args, "--listen")? + .parse() + .map_err(|e| format!("--listen: {e}"))?; + } + "--instance" => { + let id = value(&mut args, "--instance")?; + let token_file = value(&mut args, "--instance")?; + parsed.instances.push((id, token_file.into())); + } + "--tls-cert" => parsed.tls_cert = Some(value(&mut args, "--tls-cert")?.into()), + "--tls-key" => parsed.tls_key = Some(value(&mut args, "--tls-key")?.into()), + "--client-ca" => parsed.client_ca = Some(value(&mut args, "--client-ca")?.into()), + "--insecure" => parsed.insecure = true, + "--help" | "-h" => return Err(USAGE.into()), + other => return Err(format!("unknown argument {other}\n{USAGE}")), + } + } + if parsed.instances.is_empty() { + return Err(format!("at least one --instance is required\n{USAGE}")); + } + if parsed.tls_cert.is_some() != parsed.tls_key.is_some() { + return Err("--tls-cert and --tls-key go together".into()); + } + if parsed.client_ca.is_some() && parsed.tls_cert.is_none() { + return Err("--client-ca needs --tls-cert and --tls-key".into()); + } + if parsed.tls_cert.is_none() && !parsed.listen.ip().is_loopback() && !parsed.insecure { + return Err(format!( + "plain text on {} is reachable from other hosts; add --tls-cert and --tls-key, or --insecure", + parsed.listen + )); + } + Ok(parsed) + } + + fn tls(&self) -> Result, String> { + let (Some(cert), Some(key)) = (&self.tls_cert, &self.tls_key) else { + return Ok(None); + }; + let read = |path: &PathBuf| { + std::fs::read(path).map_err(|e| format!("cannot read {}: {e}", path.display())) + }; + let mut tls = ServerTlsConfig::new().identity(Identity::from_pem(read(cert)?, read(key)?)); + if let Some(ca) = &self.client_ca { + tls = tls.client_ca_root(Certificate::from_pem(read(ca)?)); + } + Ok(Some(tls)) + } +} + +async fn shutdown() { + let interrupt = tokio::signal::ctrl_c(); + #[cfg(unix)] + { + let mut terminate = + tokio::signal::unix::signal(tokio::signal::unix::SignalKind::terminate()) + .expect("SIGTERM handler"); + tokio::select! { + _ = interrupt => {} + _ = terminate.recv() => {} + } + } + #[cfg(not(unix))] + { + let _ = interrupt.await; + } +} + +#[tokio::main] +async fn main() -> std::process::ExitCode { + match run().await { + Ok(()) => std::process::ExitCode::SUCCESS, + Err(error) => { + eprintln!("{error}"); + std::process::ExitCode::FAILURE + } + } +} + +async fn run() -> Result<(), Box> { + let args = Args::parse()?; + let mut module = serve(BasicPolicy); + for (id, token_file) in &args.instances { + let token = std::fs::read_to_string(token_file) + .map_err(|e| format!("cannot read token file {}: {e}", token_file.display()))?; + module = module.instance(id.clone(), token.trim()); + } + let mut server = Server::builder(); + let transport = match args.tls()? { + Some(tls) => { + server = server.tls_config(tls)?; + if args.client_ca.is_some() { + "mTLS" + } else { + "TLS" + } + } + None => "plain text", + }; + let ids: Vec<&str> = args.instances.iter().map(|(id, _)| id.as_str()).collect(); + println!( + "basic-policy listening on {} ({transport}), instances: {}", + args.listen, + ids.join(", ") + ); + server + .add_service(module.into_service()) + .serve_with_shutdown(args.listen, shutdown()) + .await?; + Ok(()) +} diff --git a/speckit/features/251-guardian-modules/plan.md b/speckit/features/251-guardian-modules/plan.md index 9ab0f23d..fa59903b 100644 --- a/speckit/features/251-guardian-modules/plan.md +++ b/speckit/features/251-guardian-modules/plan.md @@ -73,9 +73,9 @@ crates/guardian-module-sdk/ # published crate (M2a) │ ├── lib.rs # Module, ModuleFactory, ModuleError, protocol types, request helpers │ ├── serve.rs # gRPC harness, per-instance credentials │ ├── basic_policy.rs # first-party reference kind -│ ├── conformance/ # M2a: reusable suite (today tests/conformance.rs) +│ ├── conformance.rs # reusable suite, `conformance` feature │ └── stateful.rs # M2b: watermark helper -├── examples/basic-policy-serve.rs, note-policy-serve.rs +├── examples/note-policy-serve.rs └── tests/conformance.rs crates/server/src/ diff --git a/speckit/features/251-guardian-modules/quickstart.md b/speckit/features/251-guardian-modules/quickstart.md index 7e2b29d0..fb02b4dc 100644 --- a/speckit/features/251-guardian-modules/quickstart.md +++ b/speckit/features/251-guardian-modules/quickstart.md @@ -42,7 +42,7 @@ With `examples/demo` against the local server: ```bash openssl rand -hex 32 > .guardian/caps.token -cargo run -p guardian-module-sdk --example basic-policy-serve -- \ +cargo run -p guardian-policy-module -- \ --listen 127.0.0.1:7443 --instance caps-remote .guardian/caps.token ``` From 37f2ff36111c1890bcb43c9ef1829926da304a28 Mon Sep 17 00:00:00 2001 From: Zeljko Date: Mon, 9 Nov 2026 11:51:41 +0100 Subject: [PATCH 036/105] feat(module-sdk): publishable crate (#251) crates.io metadata, a module author README, and async_trait re-exported for module implementations. The release skill and the crates workflow gain guardian-module-sdk as a fifth crate; its first publish is manual, since a trusted publisher can only be added to an existing crate. --- .../release-guardian-sdk-packages/SKILL.md | 20 ++- .../references/release-surface.md | 6 +- .github/workflows/publish-crates.yml | 9 + crates/guardian-module-sdk/Cargo.toml | 8 + crates/guardian-module-sdk/README.md | 155 ++++++++++++++++++ crates/guardian-module-sdk/src/lib.rs | 3 +- .../features/251-guardian-modules/tasks.md | 4 +- 7 files changed, 196 insertions(+), 9 deletions(-) create mode 100644 crates/guardian-module-sdk/README.md diff --git a/.agents/skills/release-guardian-sdk-packages/SKILL.md b/.agents/skills/release-guardian-sdk-packages/SKILL.md index 2d60cc44..02b9ffcb 100644 --- a/.agents/skills/release-guardian-sdk-packages/SKILL.md +++ b/.agents/skills/release-guardian-sdk-packages/SKILL.md @@ -76,6 +76,7 @@ Rust crates: - `guardian-client` - `miden-confidential-contracts` - `miden-multisig-client` +- `guardian-module-sdk` TypeScript packages: @@ -116,6 +117,7 @@ cargo test -p guardian-shared cargo test -p guardian-client cargo test -p miden-confidential-contracts cargo test -p miden-multisig-client +cargo test -p guardian-module-sdk ``` ```bash @@ -151,7 +153,8 @@ cargo publish --dry-run --locked \ -p guardian-shared \ -p guardian-client \ -p miden-confidential-contracts \ - -p miden-multisig-client + -p miden-multisig-client \ + -p guardian-module-sdk ``` ```bash @@ -196,7 +199,7 @@ Workflow: publish-crates.yml Environment: release ``` -Published releases force-select all four crates and use OIDC trusted +Published releases force-select all five crates and use OIDC trusted publishing. Manual runs expose `dry-run` and one boolean per crate. Pull requests changing the workflow force an all-crate credential-free dry run. @@ -207,6 +210,7 @@ publishes dependency-safe topological batches: 2. `guardian-client` 3. `miden-confidential-contracts` 4. `miden-multisig-client` +5. `guardian-module-sdk` (no internal dependencies) Exact versions already on crates.io are skipped. The selected packages are passed to one native multi-package Cargo command, which owns dependency @@ -216,6 +220,13 @@ its unselected prerequisites are already available at the coordinated version. Trusted-publishing failure must fail closed. The workflow has no long-lived registry-token fallback. +`guardian-module-sdk` is new in the M2a release (0.19). crates.io accepts a +trusted publisher only for a crate that already exists, so before the first +release that includes it, a crate owner publishes it once by hand +(`cargo publish -p guardian-module-sdk` with a personal token) and then adds the +trusted-publisher entry above. Until then a release run fails when it reaches +`guardian-module-sdk`; ask the user to do this step before cutting the release. + ## TypeScript Publish Order TypeScript packages must be published in dependency order: @@ -236,7 +247,7 @@ The user should usually only need to handle: - cutting the GitHub Release (`gh release create`), which also triggers the server image build For a normal Rust release, do not request `cargo login` or a local crates.io -token. Verify the four external trusted-publisher entries and use: +token. Verify the five external trusted-publisher entries and use: ```bash gh workflow run publish-crates.yml \ @@ -245,7 +256,8 @@ gh workflow run publish-crates.yml \ -f guardian-shared=true \ -f guardian-client=true \ -f miden-confidential-contracts=true \ - -f miden-multisig-client=true + -f miden-multisig-client=true \ + -f guardian-module-sdk=true ``` Continue TypeScript authentication checks with `npm whoami || npm login`. diff --git a/.agents/skills/release-guardian-sdk-packages/references/release-surface.md b/.agents/skills/release-guardian-sdk-packages/references/release-surface.md index 853ed60f..b3409343 100644 --- a/.agents/skills/release-guardian-sdk-packages/references/release-surface.md +++ b/.agents/skills/release-guardian-sdk-packages/references/release-surface.md @@ -16,6 +16,9 @@ Current coordinated SDK release line: `0.16.x` 4. `miden-multisig-client` - manifest: `crates/miden-multisig-client/Cargo.toml` - internal release dependencies: `guardian-client`, `guardian-shared`, `miden-confidential-contracts` +5. `guardian-module-sdk` + - manifest: `crates/guardian-module-sdk/Cargo.toml` + - no internal release dependencies; first publish is manual (see SKILL.md, "Rust Publication Workflow") ## Publishable TypeScript Packages @@ -57,7 +60,7 @@ Stable workflow: .github/workflows/publish-crates.yml ``` -Published releases select all four Rust crates. Manual runs provide `dry-run`, +Published releases select all five Rust crates. Manual runs provide `dry-run`, and one boolean per crate. Pull requests changing the workflow run an all-crate dry run without credentials. @@ -67,6 +70,7 @@ The fixed selection and summary order is: 2. `guardian-client` 3. `miden-confidential-contracts` 4. `miden-multisig-client` +5. `guardian-module-sdk` Cargo receives selected crates in one multi-package command and owns dependency ordering. Actual runs skip exact versions already visible on crates.io. diff --git a/.github/workflows/publish-crates.yml b/.github/workflows/publish-crates.yml index 1ef1e02b..c7e30ff5 100644 --- a/.github/workflows/publish-crates.yml +++ b/.github/workflows/publish-crates.yml @@ -30,6 +30,11 @@ on: type: boolean required: false default: false + guardian-module-sdk: + description: "Select guardian-module-sdk" + type: boolean + required: false + default: false pull_request: paths: - ".github/workflows/publish-crates.yml" @@ -61,6 +66,7 @@ jobs: INPUT_GUARDIAN_SHARED: ${{ inputs['guardian-shared'] }} INPUT_CONTRACTS: ${{ inputs['miden-confidential-contracts'] }} INPUT_MULTISIG: ${{ inputs['miden-multisig-client'] }} + INPUT_MODULE_SDK: ${{ inputs['guardian-module-sdk'] }} RELEASE_TAG: ${{ github.event.release.tag_name }} SOURCE_REF: ${{ github.ref }} SOURCE_SHA: ${{ github.sha }} @@ -71,6 +77,7 @@ jobs: guardian-client miden-confidential-contracts miden-multisig-client + guardian-module-sdk ) selected=() @@ -94,6 +101,7 @@ jobs: [[ "${INPUT_GUARDIAN_CLIENT}" == "true" ]] && selected+=(guardian-client) [[ "${INPUT_CONTRACTS}" == "true" ]] && selected+=(miden-confidential-contracts) [[ "${INPUT_MULTISIG}" == "true" ]] && selected+=(miden-multisig-client) + [[ "${INPUT_MODULE_SDK}" == "true" ]] && selected+=(guardian-module-sdk) if [[ "${INPUT_DRY_RUN}" == "true" ]]; then mode=dry_run else @@ -176,6 +184,7 @@ jobs: guardian-client miden-confidential-contracts miden-multisig-client + guardian-module-sdk ) version= for crate in "${crates[@]}"; do diff --git a/crates/guardian-module-sdk/Cargo.toml b/crates/guardian-module-sdk/Cargo.toml index 09cfea77..8ee6ff8b 100644 --- a/crates/guardian-module-sdk/Cargo.toml +++ b/crates/guardian-module-sdk/Cargo.toml @@ -8,6 +8,14 @@ license.workspace = true repository.workspace = true homepage.workspace = true description = "Module interface, protocol types and serving harness for Guardian policy modules" +readme = "README.md" +documentation = "https://docs.rs/guardian-module-sdk" +keywords = ["guardian", "miden", "policy", "grpc", "multisig"] +categories = ["cryptography::cryptocurrencies", "network-programming"] +include = ["src/**/*", "proto/**/*", "build.rs", "Cargo.toml", "README.md"] + +[package.metadata.docs.rs] +all-features = true [dependencies] async-trait = "0.1" diff --git a/crates/guardian-module-sdk/README.md b/crates/guardian-module-sdk/README.md new file mode 100644 index 00000000..92c6544f --- /dev/null +++ b/crates/guardian-module-sdk/README.md @@ -0,0 +1,155 @@ +# guardian-module-sdk + +Build policy modules for [Guardian](https://github.com/OpenZeppelin/guardian): +services the Guardian asks before it signs a transaction, creates a proposal or +accepts a new account. A module answers allow or deny; it cannot sign, change +its own configuration, or see the Guardian's secrets. + +The crate has: + +- `Module`, the trait a module implements, and `ModuleFactory` for kinds + compiled into a Guardian build. +- The `guardian.module.v1` protocol types (`HookRequest`, `Decision`, + `ModuleInfo`, the Miden transaction and account projections). Protocol + version 1 is frozen: new features arrive as named capabilities. +- `serve`, a gRPC harness that exposes any `Module` as a remote service with a + bearer token per instance. +- `basic_policy`, the Guardian's built-in policy kind (amount caps, recipient + and asset lists, signer rules, code pinning), as a reference. +- `conformance` (feature `conformance`), a suite that checks a module before + it is deployed. + +## A module + +```rust +use guardian_module_sdk::proto::hook_request; +use guardian_module_sdk::{ + Decision, DescribeRequest, Hook, HookRequest, Module, ModuleError, ModuleInfo, + PROTOCOL_VERSION, ParamsVerdict, +}; + +struct NoPrivateNotes; + +#[guardian_module_sdk::async_trait] +impl Module for NoPrivateNotes { + async fn describe(&self, _guardian: &DescribeRequest) -> Result { + Ok(ModuleInfo { + name: "no-private-notes".into(), + version: "1.0.0".into(), + protocol_version: PROTOCOL_VERSION, + hooks: vec![Hook::BeforeTransactionApproved as i32], + ..Default::default() + }) + } + + async fn validate_params(&self, params: &[u8]) -> Result { + Ok(if params == b"{}" { + ParamsVerdict::ok() + } else { + ParamsVerdict::invalid("takes no params") + }) + } + + async fn evaluate(&self, request: &HookRequest) -> Result { + let Some(hook_request::Subject::Transaction(subject)) = &request.subject else { + return Ok(Decision::allow()); + }; + let miden = subject + .miden() + .ok_or_else(|| ModuleError::InvalidRequest("not a Miden transaction".into()))?; + let private = miden + .output_notes + .iter() + .any(|note| note.note_type == guardian_module_sdk::NoteType::Private as i32); + Ok(if private { + Decision::deny("private_note", "creates a private note") + .with_client_message("Private notes are not allowed for this account") + } else { + Decision::allow() + }) + } +} +``` + +Rules every module follows: + +- `evaluate` has no side effects. The same transaction is evaluated when the + proposal is created and again before the Guardian signs, clients retry, and + the Guardian may call it concurrently. +- A deny carries a `reason_code` of 1 to 64 lowercase letters, digits or + underscores. `message` is logged by the Guardian and never shown to clients; + `client_message` (plain text, at most 256 characters) is shown only where + the operator allows it. +- Return `ModuleError` rather than allow when the request lacks what the module + needs. The operator's `on_error` setting then decides, and the default is to + refuse. +- Params arrive as UTF-8 JSON in `HookRequest.params` on every call: the + module keeps no params of its own, so operator changes apply on the next + request. + +## Serve it over gRPC + +```rust +use guardian_module_sdk::serve::serve; + +serve(NoPrivateNotes) + .instance("no-private-notes", token) + .run("127.0.0.1:7443".parse()?) + .await?; +``` + +Each instance the Guardian calls (its catalog `id`) has its own token; a call +for an unknown instance, or with another instance's token, is refused. For TLS +add `serve(...).into_service()` to a tonic server configured for TLS, as +[`examples/policy-module`](https://github.com/OpenZeppelin/guardian/tree/main/examples/policy-module) +does. Raise the server's receive limit if you lower it: the Guardian sends +requests up to `DEFAULT_REQUEST_MAX_BYTES` (2 MiB) by default. + +The Guardian side is a catalog entry: + +```toml +[[module]] +id = "no-private-notes" +kind = "grpc" +endpoint = "grpc://modules.internal:7443" +scope = "all" +hooks = ["before_transaction_approved"] +timeout_ms = 200 +on_error = "deny" +auth = { token_secret = "guardian/modules/no-private-notes-token" } +``` + +## Check it + +```toml +[dev-dependencies] +guardian-module-sdk = { version = "0.19", features = ["conformance"] } +``` + +```rust +use guardian_module_sdk::conformance::Suite; + +#[tokio::test] +async fn conforms() { + Suite::new(NoPrivateNotes) + .request("public payment", public_payment()) + .request("private payment", private_payment()) + .valid_params(serde_json::json!({})) + .invalid_params(serde_json::json!({ "x": 1 })) + .run() + .await + .assert_conformant(); +} +``` + +The suite serves the module over loopback gRPC with two instances, and checks +`Describe`, params validation on both transports, identical answers in process +and over gRPC, repeated, reordered and concurrent evaluations, the shape of +every decision, per-instance tokens and a request at the size cap. + +## Further reading + +- [Policy module guides](https://github.com/OpenZeppelin/guardian/tree/main/docs/guides/policy-modules): + built-in, remote and custom modules end to end. +- [RFC 0002](https://github.com/OpenZeppelin/guardian/blob/main/docs/rfcs/0002-guardian-modules.md): + the design, the protocol and the trust model. diff --git a/crates/guardian-module-sdk/src/lib.rs b/crates/guardian-module-sdk/src/lib.rs index 04a05f4b..6379857f 100644 --- a/crates/guardian-module-sdk/src/lib.rs +++ b/crates/guardian-module-sdk/src/lib.rs @@ -2,13 +2,12 @@ use std::sync::Arc; -use async_trait::async_trait; - pub mod basic_policy; #[cfg(feature = "conformance")] pub mod conformance; pub mod serve; +pub use async_trait::async_trait; pub use prost_types; pub use secrecy; diff --git a/speckit/features/251-guardian-modules/tasks.md b/speckit/features/251-guardian-modules/tasks.md index 02b424cf..76c6ad17 100644 --- a/speckit/features/251-guardian-modules/tasks.md +++ b/speckit/features/251-guardian-modules/tasks.md @@ -176,8 +176,8 @@ ### Implementation for User Story 6 - [X] T048 [US6] Secret references through the secrets backend: replace `auth.token_file` and `tls.*_file` in `crates/server/src/modules/catalog.rs` and `crates/server/src/modules/grpc_kind.rs` with secret references resolved when the instance is created, following `docs/runbooks/secrets.md`; resolve `$secret` in in-process params at creation and pass them only to the in-process module, never in a request; keep rejection in remote params, account layers and the operator API; update `speckit/features/251-guardian-modules/contracts/catalog-config.md` -- [ ] T049 [US6] `examples/policy-module/`: `basic-policy` as a standalone gRPC service through the `serve` harness, with `Cargo.toml`, `README.md` (run, TLS, per-instance token), a `Dockerfile`, and a matching remote catalog entry in `docs/guides/policy-modules/remote.toml` -- [ ] T050 [US6] Publishable `guardian-module-sdk`: crates.io metadata in `crates/guardian-module-sdk/Cargo.toml`, `crates/guardian-module-sdk/README.md` (module author quick start), and the crate added to the release order of the `release-guardian-sdk-packages` skill +- [X] T049 [US6] `examples/policy-module/`: `basic-policy` as a standalone gRPC service through the `serve` harness, with `Cargo.toml`, `README.md` (run, TLS, per-instance token), a `Dockerfile`, and a matching remote catalog entry in `docs/guides/policy-modules/remote.toml` +- [X] T050 [US6] Publishable `guardian-module-sdk`: crates.io metadata in `crates/guardian-module-sdk/Cargo.toml`, `crates/guardian-module-sdk/README.md` (module author quick start), and the crate added to the release order of the `release-guardian-sdk-packages` skill - [ ] T051 [US6] Remote module author guide in `docs/guides/policy-modules/custom.md` and `remote.md`: protocol version 1, request fields, `reason_code` rules, `client_message`, `dry_run`, conformance suite, credentials; written so SC-011 holds without reading server code **Checkpoint**: SC-005 and SC-011 hold; US6 acceptance scenarios 1 to 5 pass. From 6321aebc55b8b2a3cf707ddfed6d5ca7995ef52a Mon Sep 17 00:00:00 2001 From: Zeljko Date: Mon, 9 Nov 2026 11:54:07 +0100 Subject: [PATCH 037/105] docs(modules): remote module author guide (#251) custom.md now covers the frozen protocol, every RPC and when it is called, each HookRequest field per hook, decision rules (effect, reason_code, client_message), dry runs, credentials and the conformance suite; remote.md points authors there. note-policy runs the conformance suite next to basic-policy. The guide README no longer says the TypeScript multisig SDK lacks getPolicies and checkTransaction. --- .../guardian-module-sdk/tests/conformance.rs | 60 ++++++- docs/guides/policy-modules/README.md | 9 +- docs/guides/policy-modules/custom.md | 154 +++++++++++++++--- docs/guides/policy-modules/remote.md | 6 +- .../features/251-guardian-modules/tasks.md | 2 +- 5 files changed, 203 insertions(+), 28 deletions(-) diff --git a/crates/guardian-module-sdk/tests/conformance.rs b/crates/guardian-module-sdk/tests/conformance.rs index 7461d062..0971f43e 100644 --- a/crates/guardian-module-sdk/tests/conformance.rs +++ b/crates/guardian-module-sdk/tests/conformance.rs @@ -1,3 +1,6 @@ +#[path = "../examples/note_policy/mod.rs"] +mod note_policy; + use guardian_module_sdk::basic_policy::BasicPolicy; use guardian_module_sdk::conformance::Suite; use guardian_module_sdk::proto::guardian_module_client::GuardianModuleClient; @@ -5,7 +8,7 @@ use guardian_module_sdk::proto::{asset, hook_request}; use guardian_module_sdk::serve::serve; use guardian_module_sdk::{ AccountStateProjection, AccountView, Asset, HookRequest, MidenAccountState, MidenTransaction, - Module, OutputNote, RegistrationSubject, TransactionProjection, TransactionSubject, + Module, NoteType, OutputNote, RegistrationSubject, TransactionProjection, TransactionSubject, }; use serde_json::json; use tokio::net::TcpListener; @@ -147,6 +150,61 @@ async fn basic_policy_conforms() { .assert_conformant(); } +fn notes(notes: Vec, params: serde_json::Value) -> HookRequest { + HookRequest { + params: serde_json::to_vec(¶ms).unwrap(), + after: Some(AccountView::default()), + subject: Some(hook_request::Subject::Transaction(TransactionSubject { + projection: Some(TransactionProjection::miden(MidenTransaction { + output_notes: notes, + ..Default::default() + })), + ..Default::default() + })), + ..Default::default() + } +} + +fn note(note_type: NoteType, tx_fee: bool) -> OutputNote { + OutputNote { + note_type: note_type as i32, + tx_fee, + ..Default::default() + } +} + +#[tokio::test] +async fn note_policy_conforms() { + let one = json!({ "max_payment_notes": 1 }); + let private = json!({ "deny_private_notes": true }); + Suite::new(note_policy::NotePolicy) + .request( + "one payment and the fee note", + notes( + vec![note(NoteType::Public, false), note(NoteType::Public, true)], + one.clone(), + ), + ) + .request( + "two payments", + notes( + vec![note(NoteType::Public, false), note(NoteType::Public, false)], + one, + ), + ) + .request( + "a private payment", + notes(vec![note(NoteType::Private, false)], private), + ) + .request("registration", registration(json!({}), &["0xs1"])) + .valid_params(json!({ "max_payment_notes": 1, "deny_private_notes": true })) + .valid_params(json!({})) + .invalid_params(json!({ "max_notes": 1 })) + .run() + .await + .assert_conformant(); +} + #[tokio::test] #[ignore = "timing report for the prototype gates; run with --ignored --nocapture"] async fn loopback_evaluate_round_trip() { diff --git a/docs/guides/policy-modules/README.md b/docs/guides/policy-modules/README.md index 5301cf25..a3f45b74 100644 --- a/docs/guides/policy-modules/README.md +++ b/docs/guides/policy-modules/README.md @@ -76,12 +76,9 @@ Cosigners use two client endpoints: creation would return. At most `GUARDIAN_MODULE_CHECK_RATE_PER_MIN` (30) checks per account and signer per minute. -The Rust multisig SDK wraps both (`get_policies`, and `check_transaction`, -which builds the transaction exactly as `propose_transaction` does). The -TypeScript multisig SDK does not yet: until the next -`@openzeppelin/guardian-client` release, TypeScript callers use -`getPolicies` and `checkDeltaProposal` on the base `GuardianHttpClient` and -pass the proposal payload themselves. +The multisig SDKs wrap both: Rust `get_policies` and `check_transaction`, +TypeScript `getPolicies` and `checkTransaction`, which build the transaction +exactly as proposing it would. An instance whose catalog params contain secret references cannot use `disclosure = "params"`: the server refuses to start, since the reference diff --git a/docs/guides/policy-modules/custom.md b/docs/guides/policy-modules/custom.md index 33831007..2936c93a 100644 --- a/docs/guides/policy-modules/custom.md +++ b/docs/guides/policy-modules/custom.md @@ -27,11 +27,47 @@ A stateless module implements three methods: | `validate_params` | `ParamsVerdict::ok()`, `ParamsVerdict::invalid(message)` or `ParamsVerdict::normalized(params)` | Called at startup and on every params write. Reject unknown fields (`#[serde(deny_unknown_fields)]`) so a typo fails here, not silently at evaluation. Return `normalized` to have the Guardian store the params in your current shape. | | `evaluate` | `Decision::allow()` or `Decision::deny(reason_code, message)` | Must be free of side effects: the same transaction is evaluated at proposal creation and again at approval, and clients retry. | -A reason code is lowercase `snake_case`; anything else counts as a module -failure. Return `ModuleError` for a request you cannot judge; the instance's -`on_error` then decides. `Decision::allow` and `Decision::deny` set the -decision's `effect`; a Guardian treats an effect it does not know as a -failure, never as an allow. +Add `guardian-module-sdk` with the `conformance` feature as a dev-dependency to +test it (see [Test it](#test-it)). The crate re-exports `async_trait`, so +`#[guardian_module_sdk::async_trait]` goes on the `impl`. + +## The protocol + +Modules speak `guardian.module.v1`, defined in +[`guardian_module_v1.proto`](../../../crates/guardian-module-sdk/proto/guardian_module_v1.proto). +Protocol version 1 is frozen: later Guardian releases add fields, hooks and +named capabilities, never a change that breaks a version 1 module. A module in +another language implements the `GuardianModule` service from that file with +any gRPC stack; the Rust trait above is a thin layer over it. + +| RPC | When the Guardian calls it | +|---|---| +| `Describe` | At startup, before enabling an instance, and every `GUARDIAN_MODULE_PROBE_INTERVAL_MS` (5 s) as a health probe | +| `ValidateParams` | At startup for the stored global params, and on every params write through the operator API | +| `Evaluate` | Once per gate hook invocation the instance applies to, and again for an account's layer | +| `Notify`, `NotifyGap` | Not called yet; commit notifications arrive with the M2b slice. The SDK answers them with success | + +Every call carries `authorization: Bearer ` in its gRPC metadata, with +the token of the instance it is for, and `instance_id` in the message +(`Describe` names no instance). Any gRPC error status is a module failure, as +is a call that outlives the instance's `timeout_ms`, and the instance's +`on_error` decides; repeated failures open a circuit breaker that skips the +module until a health probe succeeds. Requests can be up to 2 MiB encoded +(`GUARDIAN_MODULE_REQUEST_MAX_BYTES`), so keep your server's receive limit at +least that high (tonic's default is 4 MiB). + +## Decisions + +| Field | Rule | +|---|---| +| `effect` | `ALLOW` or `DENY`, set by `Decision::allow()` and `Decision::deny(..)`. A value the Guardian does not know is a module failure, never an allow. A module that leaves it unspecified is read through `allow` | +| `reason_code` | Required on a deny: 1 to 64 characters of `a-z`, `0-9` and `_`. Anything else turns the deny into a module failure. Stable codes let operators and clients act on them | +| `message` | For the operator: logged with the decision, never sent to clients | +| `client_message` | Optional, for the person who sent the request, via `.with_client_message(..)`. Plain text: the Guardian drops control characters, collapses whitespace and keeps at most 256 characters. Shown only for instances with `client_reason = "full"` (the default); with `"generic"` the client sees `reason_code = "policy_denied"` and nothing else | + +Return `ModuleError` for a request you cannot judge (a missing projection, +params you cannot read). It is a module failure and `on_error` decides, so a +module never allows by accident. ## Changing your module across releases @@ -51,25 +87,66 @@ failure, never as an allow. The rules are in [RFC 0002 section 3.5](../../rfcs/0002-guardian-modules.md#35-protocol-evolution-and-compatibility). -## What a request carries +## Hooks and requests + +| Hook | Called | `subject` | +|---|---|---| +| `before_proposal_created` | Before a multisig proposal is stored, and in dry runs | `transaction` | +| `before_transaction_approved` | Before the Guardian signs a pushed delta or a Guardian execution: the one that enforces, since transactions signed offline skip proposals | `transaction` | +| `before_account_registered` | When an account is first configured on this Guardian | `registration` | + +A module lists the hooks it supports in `describe`; the catalog subscribes each +instance to some of them, and the Guardian refuses an instance subscribed to a +hook its module does not list. -| Field | Use it for | +| `HookRequest` field | Contents | |---|---| -| `params` | The params to apply, as JSON bytes: the global ones, or an account's layer on its second pass | -| `subject.miden()` (the Miden variant of `subject.transaction.projection`) | The decoded transaction: vault changes, output notes (amount, faucet, `note_type`, `p2id_target`, `tx_fee`), input notes, storage changes | -| `before`, `after` | Account views: signer commitments, `default_threshold` (absent for single-key accounts), procedure thresholds, auth scheme | -| `submitter`, `subject.transaction.proposer` | Verified signer commitments | -| `subject.transaction.unverified_metadata` | What the proposer claimed; never base a decision on it alone | +| `request_id` | Unique per hook invocation and shared by every module called in it; log it to join your logs with the Guardian's | +| `hook` | Which hook is calling | +| `dry_run` | `true` for a policy check: nothing is stored or signed whatever you decide (see [Dry runs](#dry-runs)) | +| `network`, `network_id` | `"miden"`, and `"mainnet"`, `"testnet"`, `"devnet"`, `"cedar"` or `"local"` | +| `account_id`, `instance_id` | The account, and the catalog id of the instance being called | +| `params` | UTF-8 JSON: the instance's global params, the account's layer on its second pass, or the account's own params for a `default` or `assigned` instance. Read them on every call; they change without restarting the module | +| `accounting_time` | The time recorded with the transaction if it is signed; at `before_proposal_created` and in a dry run, the evaluation time | +| `submitter`, `submitter_session` | The verified signer commitment that authenticated the request, and whether it did so through a session key it delegated | +| `before` | The account as the Guardian holds it; absent at `before_account_registered` | +| `after` | The account as it will be if every module allows | +| `subject.transaction.projection` | The decoded transaction; read the Miden variant with `subject.miden()` | +| `subject.transaction.proposer` | The verified signer commitment that created the matching proposal; empty when there is none | +| `subject.transaction.unverified_metadata` | UTF-8 JSON the proposer asserted; never base a decision on it alone | | `subject.transaction.raw` | The transaction in its network's own encoding (`encoding = "miden.transaction_summary"`), for modules that decode it themselves; tied to the Guardian's Miden version | +| `subject.transaction.pending` | Empty until commit notifications ship (M2b) | +| `subject.registration.initial_state` | The account about to be accepted: vault and storage slots | -Skip the fee note (`tx_fee = true`) when counting payments: every transaction -pays its fee through an output note. +An account view (`before`, `after`) carries the account `commitment`, its +`signer_commitments` with each signer's scheme in `signer_schemes` (`auth_scheme` +is `"falcon"`, `"ecdsa"` or `"mixed"`), `default_threshold` (absent for +single-key accounts), `procedure_thresholds`, `code_commitment` and the +`procedure_roots` the code exports. + +The Miden projection has the `nonce_delta`, the `reference_block` and optional +`expiration_block`, `vault_changes` (asset and direction), `output_notes` +(`note_type`, assets, `p2id_target` for known P2ID and P2IDE scripts, +`tx_fee`), `input_notes`, `storage_changes` by slot name, and +`new_code_commitment` when the transaction replaces the account's code. +Amounts are decimal strings. Skip the fee note (`tx_fee = true`) when counting +payments: every transaction pays its fee through an output note. Projections are tagged by network (`TransactionProjection`, `oneof network`). Miden is the only network today; read it with `subject.miden()` and return a `ModuleError` when it is absent, so a module never judges a transaction it does not understand. +## Dry runs + +Cosigners can check a transaction before proposing it +(`POST /delta/proposal/check`). The Guardian then calls the account's gate +instances with `dry_run = true`: the creation instances, then those subscribed +only to `before_transaction_approved`. Decide exactly as you would otherwise; +`evaluate` has no side effects either way. An operator who does not want an +instance to see transactions that may never be proposed sets `dry_run = false` +in its catalog entry, and the check then reports `complete: false`. + ## Run it over gRPC The [remote](./remote.md) page explains the transport. @@ -85,6 +162,13 @@ Set `GUARDIAN_MODULES_CONFIG=.guardian/custom.toml` in the guide's `.env` and start the server as in the setup. The log line lists `note-policy=note-policy `. +The catalog names the token with `auth = { token_secret = "note-policy.token" }`; +the Guardian reads it through its secrets backend, and the module is started +with the same value. For TLS, mutual TLS and the AWS secrets provider, see +[remote modules](./remote.md#credentials) and +[`examples/policy-module`](../../../examples/policy-module/README.md), a +standalone service you can copy as a starting point. + ## Run it in process Register the kind on the server builder; that is the only difference from the @@ -107,7 +191,11 @@ set -a && . docs/guides/policy-modules/.env && set +a cargo run -p guardian-server --example custom_module_server ``` -No module process, token or endpoint is involved. To run it next to another +No module process, token or endpoint is involved. An in-process module that +needs a credential of its own, such as a vendor API key, names it in its +catalog params as `{ "$secret" = "" }`. The Guardian reads it at startup +and the factory gets the value from `ModuleInstanceConfig::secret("")`; +`HookRequest.params` keeps the reference, never the value. To run it next to another Guardian, set `GUARDIAN_EXAMPLE_HTTP_PORT` and `GUARDIAN_EXAMPLE_GRPC_PORT` (default 3000 and 50051). The stock binary refuses this catalog at startup, since it does not know the `note-policy` kind. @@ -132,16 +220,44 @@ from `main.rs`, so keep it in step with it when you upgrade. The tests work the same in either mode. The module's own tests run with `cargo test -p guardian-module-sdk --example note-policy-serve`. +## Test it + +The SDK's conformance suite runs your module in process and over loopback gRPC, +with two instances on one service: + +```rust +use guardian_module_sdk::conformance::Suite; + +#[tokio::test] +async fn note_policy_conforms() { + Suite::new(NotePolicy) + .request("one payment", one_payment()) + .request("two payments", two_payments()) + .valid_params(serde_json::json!({ "max_payment_notes": 1 })) + .invalid_params(serde_json::json!({ "max_notes": 1 })) + .run() + .await + .assert_conformant(); +} +``` + +It checks that `describe` reports protocol version 1 and known hooks, that +params validate the same over both transports and that normalized params +validate to themselves, that every request gets the same answer in process and +over gRPC, repeated, in reverse order and concurrently (so `evaluate` keeps no +state), that every deny has a valid `reason_code` and a plain `client_message` +of at most 256 characters, that one instance's token is refused for another, +and that a request at the 2 MiB size cap goes through. A module written in +another language can port these cases to its own tests. `note-policy` and `basic-policy` run it in +[`tests/conformance.rs`](../../../crates/guardian-module-sdk/tests/conformance.rs). + ## Shipping your module - Use `serve(YourModule).instance(id, token)` from the SDK, or implement the `GuardianModule` service from the proto in any language with gRPC support. - Keep the module stateless for now. Limits that count across transactions (daily caps) need the commit notifications of the RFC's M2b slice. -- The SDK's conformance tests - ([`tests/conformance.rs`](../../../crates/guardian-module-sdk/tests/conformance.rs)) - check that `basic-policy` decides the same in process and over gRPC; copy the - pattern to test your module over the real transport. +- Run the conformance suite in your CI, with requests that cover every rule. - Prefer the remote path for code you do not own. In process, the rule that a module can only refuse, never sign, holds by code review rather than by isolation. diff --git a/docs/guides/policy-modules/remote.md b/docs/guides/policy-modules/remote.md index 31c9167c..a0d40a9e 100644 --- a/docs/guides/policy-modules/remote.md +++ b/docs/guides/policy-modules/remote.md @@ -13,7 +13,7 @@ is the transport. Do the [setup](./README.md#setup) first; the catalog is | Call | When | Purpose | |---|---|---| -| `Describe` | Startup, and before enabling | Name, version, protocol version and supported hooks. A mismatch with the catalog stops startup. | +| `Describe` | Startup, before enabling, and every 5 s as a health probe | Name, version, protocol version and supported hooks. A mismatch with the catalog stops startup. | | `ValidateParams` | Startup, and on every params write | The module rejects params it cannot use; nothing is stored. | | `Evaluate` | Every gated request | One request in, one decision out, within `timeout_ms`. | @@ -24,6 +24,10 @@ and the proposal's unverified metadata. The module keeps no params of its own, so params changed through the API apply on the next request without restarting it. +To write your own remote module, in Rust or any language with gRPC, read +[custom modules](./custom.md): the protocol, every request field, the rules for +decisions, dry runs and the conformance suite. This page is about running one. + ## 1. Token and module Each instance authenticates the Guardian with a bearer token, sent on every diff --git a/speckit/features/251-guardian-modules/tasks.md b/speckit/features/251-guardian-modules/tasks.md index 76c6ad17..f18ee84a 100644 --- a/speckit/features/251-guardian-modules/tasks.md +++ b/speckit/features/251-guardian-modules/tasks.md @@ -178,7 +178,7 @@ - [X] T048 [US6] Secret references through the secrets backend: replace `auth.token_file` and `tls.*_file` in `crates/server/src/modules/catalog.rs` and `crates/server/src/modules/grpc_kind.rs` with secret references resolved when the instance is created, following `docs/runbooks/secrets.md`; resolve `$secret` in in-process params at creation and pass them only to the in-process module, never in a request; keep rejection in remote params, account layers and the operator API; update `speckit/features/251-guardian-modules/contracts/catalog-config.md` - [X] T049 [US6] `examples/policy-module/`: `basic-policy` as a standalone gRPC service through the `serve` harness, with `Cargo.toml`, `README.md` (run, TLS, per-instance token), a `Dockerfile`, and a matching remote catalog entry in `docs/guides/policy-modules/remote.toml` - [X] T050 [US6] Publishable `guardian-module-sdk`: crates.io metadata in `crates/guardian-module-sdk/Cargo.toml`, `crates/guardian-module-sdk/README.md` (module author quick start), and the crate added to the release order of the `release-guardian-sdk-packages` skill -- [ ] T051 [US6] Remote module author guide in `docs/guides/policy-modules/custom.md` and `remote.md`: protocol version 1, request fields, `reason_code` rules, `client_message`, `dry_run`, conformance suite, credentials; written so SC-011 holds without reading server code +- [X] T051 [US6] Remote module author guide in `docs/guides/policy-modules/custom.md` and `remote.md`: protocol version 1, request fields, `reason_code` rules, `client_message`, `dry_run`, conformance suite, credentials; written so SC-011 holds without reading server code **Checkpoint**: SC-005 and SC-011 hold; US6 acceptance scenarios 1 to 5 pass. From c7193784268e8417228243083bc24d0cfe5c4718 Mon Sep 17 00:00:00 2001 From: Zeljko Date: Mon, 9 Nov 2026 12:03:10 +0100 Subject: [PATCH 038/105] docs(modules): troubleshooting entries and break-glass runbook (#251) TROUBLESHOOTING gains a symptom section for module refusals and failures, with the denial log fields, and the four GUARDIAN_MODULE_* codes with their meta. docs/runbooks/policy-modules.md covers preparing the break-glass path per instance, a module that is down, one that refuses too much, slow modules and the budget, and startup failures. AGENTS.md maps policy module changes to their docs and lists the module SDK among the published surfaces. --- AGENTS.md | 3 +- docs/TROUBLESHOOTING.md | 55 +++++++ docs/guides/policy-modules/README.md | 3 + docs/runbooks/policy-modules.md | 155 ++++++++++++++++++ .../features/251-guardian-modules/tasks.md | 4 +- 5 files changed, 217 insertions(+), 3 deletions(-) create mode 100644 docs/runbooks/policy-modules.md diff --git a/AGENTS.md b/AGENTS.md index 44d51bc2..bf505f10 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -222,8 +222,9 @@ Common mappings: - Server or API behavior -> `spec/`, `docs/CONCEPTS.md`, SDK docs - Multisig SDK behavior -> `docs/MULTISIG_SDK.md`, `crates/miden-multisig-client/README.md`, `packages/miden-multisig-client/README.md`, `examples/demo`, `examples/web`, `examples/smoke-web` - Miden version support, cross-line breaking changes, data resets -> `docs/MIDEN_COMPATIBILITY.md` (facts live there; `docs/PRODUCTION.md` keeps operator steps and `docs/TROUBLESHOOTING.md` keeps symptoms) -- New or changed public API, builder option, or config field on a published crate or package -> that crate's or package's own `README.md`, in the same PR. These READMEs are the crates.io and npm landing pages, so a field documented only in `docs/` is invisible to every consumer who never opens the repo. Published surfaces: `crates/shared`, `crates/client`, `crates/contracts`, `crates/miden-multisig-client`, `packages/guardian-client`, `packages/guardian-evm-client`, `packages/guardian-operator-client`, `packages/miden-multisig-client`. Keep relative links out of npm READMEs; they resolve only on GitHub. +- New or changed public API, builder option, or config field on a published crate or package -> that crate's or package's own `README.md`, in the same PR. These READMEs are the crates.io and npm landing pages, so a field documented only in `docs/` is invisible to every consumer who never opens the repo. Published surfaces: `crates/shared`, `crates/client`, `crates/contracts`, `crates/guardian-module-sdk`, `crates/miden-multisig-client`, `packages/guardian-client`, `packages/guardian-evm-client`, `packages/guardian-operator-client`, `packages/miden-multisig-client`. Keep relative links out of npm READMEs; they resolve only on GitHub. - Operator/dashboard behavior -> `docs/DASHBOARD.md`, `docs/PRODUCTION.md`, `examples/operator-smoke-web` +- Policy modules (catalog, pipeline, operator module routes, module protocol) -> `docs/guides/policy-modules/`, `docs/runbooks/policy-modules.md`, `docs/rfcs/0002-guardian-modules.md`, `crates/guardian-module-sdk/README.md`, `docs/DASHBOARD.md` - EVM proposal behavior -> `speckit/features/001-evm-proposal-support/`, `packages/guardian-evm-client`, `examples/evm-smoke-web` - Deployment, config, infrastructure, or secrets -> `docs/PRODUCTION.md`, `docs/architecture/infra.md`, `docs/runbooks/secrets.md`, `docs/SERVER_AWS_DEPLOY.md`, `infra/README.md` - Local dev or test startup -> `README.md`, `CONTRIBUTING.md`, relevant example README or quickstart diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md index 7afb128b..a40194a0 100644 --- a/docs/TROUBLESHOOTING.md +++ b/docs/TROUBLESHOOTING.md @@ -832,6 +832,48 @@ once come back synchronously and create nothing. 256-block window built-in proposals script, so it fires only when a reservation outlives the transaction's expiration, which is worth investigating. +### A policy module refuses or blocks requests + +Only on servers started with a module catalog (`GUARDIAN_MODULES_CONFIG`). +Clients see `403 GUARDIAN_MODULE_DENIED` (a module decided to refuse) or +`503 GUARDIAN_MODULE_UNAVAILABLE` (a fail-closed module could not decide) on +proposal creation, delta push, account registration and the dry-run check; a +Guardian execution ends `failed` with `GUARDIAN_EXECUTION_MODULE_DENIED` or +`GUARDIAN_EXECUTION_MODULE_UNAVAILABLE` and keeps its proposal. + +1. **Find the decision.** Every denial is logged at `info` as + `Policy module denied the request` with `request_id`, `module`, + `account_id`, `hook`, `submitter`, `reason_code`, `layer` (`global` or + `account`), the module's `message` (never sent to clients), + `catalog_hash`, `params_version` and `client_reason`. A denial with + `meta.reason_code = "policy_denied"` and no `module` comes from an instance + with `client_reason = "generic"`; only this log line names it. The + `request_id` is also in the module's request, so the module's own logs can + be joined on it. +2. **A failure, not a decision.** `Policy module failed; refusing` (or + `continuing (fail-open)` for `on_error = "allow"`) is logged at `warn` with + `module`, `account_id` and the failure: the module's error, `timed out`, + an invalid reason code or unknown effect, a request over + `GUARDIAN_MODULE_REQUEST_MAX_BYTES`, or an open circuit. A fail-open + failure is also recorded on the signed delta (`metadata.modules.failed_open`) + and counted in `guardian_module_fail_open_total`. +3. **Module health.** `guardian_module_up` is 0 after a failed `Describe` + health probe (`Policy module health probe failed` at `warn`), and + `guardian_module_circuit_open` is 1 while this replica skips the module + after `GUARDIAN_MODULE_BREAKER_FAILURES` consecutive failures; the next + successful probe lets a call through again. A module that is up but slow + shows in `guardian_module_evaluate_duration_seconds` and as `timed out` + failures: compare with the instance's `timeout_ms` and + `GUARDIAN_MODULE_EVALUATION_BUDGET_MS`. +4. **Params.** `GET /dashboard/modules/{id}` shows the params in force, the + account's layer or assignment, and `params_drift`; the history route shows + who changed them and why. A change through the operator API applies on the + next request. + +To let requests through while a module is broken, disable the instance (if its +catalog entry has `operator_can_disable = true`) or switch it to fail open; +see the [policy modules runbook](./runbooks/policy-modules.md). + ### Rate limits triggered Over HTTP: `429` with `code: rate_limit_exceeded` and a `Retry-After` @@ -992,6 +1034,19 @@ stored or served; find it in the server log (`WARN`, same `code`) for the accoun A transaction whose execution stopped because the node could not serve a note script it needed fails as `GUARDIAN_EXECUTION_NODE_UNAVAILABLE`, not as a binding mismatch. +### Policy modules + +Only on servers started with a module catalog. See +[the symptom section](#a-policy-module-refuses-or-blocks-requests) and the +[policy modules runbook](./runbooks/policy-modules.md). + +| Code | HTTP | `meta` | First check | +|---|---|---|---| +| `GUARDIAN_MODULE_DENIED` | 403 (gRPC `PermissionDenied`) | `module`, `reason_code`, `layer` (`global` or `account`), and `client_message` when the module set one; only `reason_code: "policy_denied"` for an instance with `client_reason = "generic"` | A policy refused the request: proposal creation, delta push, account registration or the dry-run check. Not retryable while the policy holds. The server log line `Policy module denied the request` has the module's own `message`. | +| `GUARDIAN_MODULE_UNAVAILABLE` | 503 (gRPC `Unavailable`) | `module` | A fail-closed module timed out, errored, sent an invalid decision, was skipped by an open circuit, or would have received a request over the size cap. Retryable once it answers. On the operator API, enabling an instance that fails its startup checks returns it too. | +| `GUARDIAN_MODULE_NOT_FOUND` | 404 | `module` | Operator API: no catalog instance with this id. Instances come only from the catalog file. | +| `GUARDIAN_MODULE_NOT_DISABLEABLE` | 409 (gRPC `FailedPrecondition`) | `module` | Operator API: the instance's catalog entry has `operator_can_disable = false`. Changing that is a deploy (edit the catalog and restart). | + ### Validation | Code | HTTP | First check | diff --git a/docs/guides/policy-modules/README.md b/docs/guides/policy-modules/README.md index a3f45b74..7d2eb769 100644 --- a/docs/guides/policy-modules/README.md +++ b/docs/guides/policy-modules/README.md @@ -182,6 +182,9 @@ return `400` and change nothing. ## Troubleshooting +For outages, a module that refuses too much, and break-glass steps, see the +[policy modules runbook](../../runbooks/policy-modules.md). + | Symptom | Cause | |---|---| | `cannot read module catalog` | `GUARDIAN_MODULES_CONFIG` is relative to the directory you started the server in; start from the repository root. | diff --git a/docs/runbooks/policy-modules.md b/docs/runbooks/policy-modules.md new file mode 100644 index 00000000..4eccbfe1 --- /dev/null +++ b/docs/runbooks/policy-modules.md @@ -0,0 +1,155 @@ +# Policy Modules Runbook + +What to do when a policy module stops transactions it should let through, and +how to prepare so that the way out is known before an outage. Background: the +[policy modules guide](../guides/policy-modules/README.md) and +[RFC 0002](../rfcs/0002-guardian-modules.md) section 4. + +> **Audience:** operators of a Guardian started with a module catalog +> (`GUARDIAN_MODULES_CONFIG`), with an operator key for the dashboard API, and +> deploy access for changes the API cannot make. + +A module can only refuse; it can never make the Guardian sign. The risk this +runbook covers is the opposite one: a fail-closed module that is down, slow or +misconfigured stops approvals for every account it applies to, and Guardian +executions fail with `GUARDIAN_EXECUTION_MODULE_*` until it is fixed. + +## Before an outage + +For every instance in the catalog, know which path stops it: + +| Catalog entry | Break-glass path | Time to effect | +|---|---|---| +| `operator_can_disable = true` | `POST /dashboard/modules/{id}/disable` with a reason | Next request, on every replica | +| `operator_can_disable = false`, `on_error = "allow"` | None needed for an outage: failures continue (recorded on the delta). A module that denies wrongly needs a params change or a deploy | Next request | +| `operator_can_disable = false`, `on_error = "deny"` | A deploy: change the catalog and restart | A rollout | + +- Give the on-call operator `modules:disable`. It allows disabling instances + marked `operator_can_disable` and nothing else, so it is safe to hand out + more widely than `policies:write` ([permissions](../DASHBOARD.md#permission-vocabulary)). +- Mark `operator_can_disable = false` only for instances that must hold even + when they block everything (sanctions screening, for example), and agree in + advance that their outage is resolved by fixing the module or by a deploy. +- Watch `guardian_module_up`, `guardian_module_circuit_open`, + `guardian_module_fail_open_total` and the p99 of + `guardian_module_evaluate_duration_seconds` per `module` (see + [`spec/api.md`](../../spec/api.md) for the full list). + +Every API change requires a `reason` and is recorded in the instance's params +history (`GET /dashboard/modules/{id}/params/history`), with the operator and +time. + +The examples use the guide's `admin` helper +(`admin METHOD PATH [JSON]` against `/dashboard/PATH`, see the +[guide setup](../guides/policy-modules/README.md#4-the-operator-cli)); the same +routes are in [`DASHBOARD.md`](../DASHBOARD.md#policy-modules) and in +`@openzeppelin/guardian-operator-client`. + +## A module is down + +Symptoms: clients get `503 GUARDIAN_MODULE_UNAVAILABLE` with `meta.module`; +`guardian_module_up{module}` is 0; `Policy module health probe failed` and +`Policy module failed; refusing` at `warn`; +`guardian_module_circuit_open{module}` is 1 once a replica has seen +`GUARDIAN_MODULE_BREAKER_FAILURES` (5) failures in a row, after which the +module is skipped without waiting for its timeout. + +1. Check the module itself (its process, endpoint, certificate, token). A + module that rejects the Guardian's token fails `Describe`, so it looks + down. +2. If it cannot be fixed quickly and the catalog allows it, disable it: + + ```sh + admin POST /modules/risk-vendor/disable '{"reason":"vendor outage INC-123"}' + ``` + + Requests stop calling it on every replica at once. Deltas signed meanwhile + name the catalog and params version they were approved under in + `metadata.modules`, so the gap is auditable. +3. When the module is healthy again, enable it. Enabling runs `Describe` and + `ValidateParams` first and returns `503 GUARDIAN_MODULE_UNAVAILABLE` + without changing anything if they fail: + + ```sh + admin POST /modules/risk-vendor/enable '{"reason":"vendor recovered INC-123"}' + ``` + +4. If the catalog does not allow disabling, change it and roll the replicas: + set `on_error = "allow"`, or `operator_can_disable = true` and then + disable through the API, or remove the instance. Editing `enabled` in the + catalog does nothing once the instance has started once: the stored flag + applies and `guardian_module_config_drift` reports the difference. + Removing an instance leaves its account assignments in place, marked + `orphaned` and skipped, so adding it back restores them. + +The breaker closes by itself: a successful health probe +(`GUARDIAN_MODULE_PROBE_INTERVAL_MS`, 5 s) lets the next real call through, and +a successful call closes it. Breakers are per replica, so replicas can +disagree for a few seconds; `GET /dashboard/modules` reports the `circuit` of +the replica that answered. + +## A module refuses what it should allow + +Symptoms: `403 GUARDIAN_MODULE_DENIED` with a `reason_code` that should not +apply; the `info` log line `Policy module denied the request` names the +`module`, `layer`, `reason_code`, the module's `message`, and the +`params_version` it decided under. + +1. Find the change: `admin GET /modules/{id}/params/history` lists every + params write with its previous and new value, operator and reason. A + denial in the `account` layer comes from the account's own rule: see + `admin GET /accounts/{account_id}/modules`. +2. Put the previous params back, which the module validates before storing: + + ```sh + admin PUT /modules/caps/params '{"params":{...previous...},"reason":"revert bad cap INC-124"}' + ``` + + An account's layer is removed with + `admin DELETE /accounts/{account_id}/modules/{id}/params '{"reason":"..."}'`. +3. If the module's code is wrong rather than its params, disable the instance + as above, or for a remote module roll back its deployment; the Guardian + needs no restart. + +## Requests are slow or time out + +Symptoms: `timed out` failures, the p99 of +`guardian_module_evaluate_duration_seconds{module}` near the instance's +`timeout_ms`, client requests that take up to +`GUARDIAN_MODULE_EVALUATION_BUDGET_MS` (1 s) longer than usual. + +- One hook invocation spends at most the budget in module calls. Once it is + spent, the remaining modules count as timed out and their `on_error` + applies; these cuts do not count against the breaker. +- `guardian_module_over_budget_accounts` counts accounts whose modules could + exceed the budget (logged at startup with their worst hook). Remove + assignments or account layers from those accounts, or lower the + instances' `timeout_ms` with a deploy. +- Raising `GUARDIAN_MODULE_EVALUATION_BUDGET_MS` needs a restart and must stay + below the execution reservation lease (the prod stage refuses to start + otherwise), and client request timeouts must exceed it. + +## The server does not start + +An enabled instance that cannot be created or fails its startup checks stops +startup: an unknown kind, an unreachable module, a token the module rejects, a +secret the secrets backend cannot read, or params the module refuses. The log +names the instance (`module : ...`). + +- Fix the cause (start the module, fix the secret, see + [secrets](./secrets.md#policy-module-secrets)), or +- remove the instance from the catalog and restart; its stored params, + history and assignments are kept for when it comes back. + +A disabled instance that fails its checks only logs `Disabled module failed +its startup checks` and stays disabled. + +## After an incident + +- Re-enable what was disabled, with a reason that references the incident. +- Check `guardian_module_fail_open_total` for the window: deltas signed while + a fail-open module was failing carry `metadata.modules.failed_open` naming + it. +- If the outage showed that an instance should not stop approvals, change its + `on_error` or `operator_can_disable` in the catalog now, not during the + next one. diff --git a/speckit/features/251-guardian-modules/tasks.md b/speckit/features/251-guardian-modules/tasks.md index f18ee84a..17d77828 100644 --- a/speckit/features/251-guardian-modules/tasks.md +++ b/speckit/features/251-guardian-modules/tasks.md @@ -188,8 +188,8 @@ **Purpose**: documentation, verification and release readiness across stories. -- [ ] T052 [P] `docs/TROUBLESHOOTING.md`: `GUARDIAN_MODULE_DENIED`, `GUARDIAN_MODULE_UNAVAILABLE`, `GUARDIAN_MODULE_NOT_FOUND`, `GUARDIAN_MODULE_NOT_DISABLEABLE` with their `meta`, and the denial log fields -- [ ] T053 [P] Break-glass runbook `docs/runbooks/policy-modules.md` (RFC section 4.2): disabling an instance, deploy-only changes, circuit and budget symptoms; link it from `docs/runbooks/` and `CLAUDE.md`'s lookup table +- [X] T052 [P] `docs/TROUBLESHOOTING.md`: `GUARDIAN_MODULE_DENIED`, `GUARDIAN_MODULE_UNAVAILABLE`, `GUARDIAN_MODULE_NOT_FOUND`, `GUARDIAN_MODULE_NOT_DISABLEABLE` with their `meta`, and the denial log fields +- [X] T053 [P] Break-glass runbook `docs/runbooks/policy-modules.md` (RFC section 4.2): disabling an instance, deploy-only changes, circuit and budget symptoms; link it from `docs/runbooks/` and `CLAUDE.md`'s lookup table - [ ] T054 [P] Trust boundary and data protection in `docs/CONCEPTS.md`: what external modules receive (full transaction details, proposals that never execute, proposer descriptions), and the operator and vendor guidance of RFC invariant 5 - [ ] T055 [P] Protocol spec coverage: module error codes and `meta` on proposal creation, push and registration, `GET /policies` and `POST /delta/proposal/check` in `spec/api.md`, and the gate points in the push, proposal and registration processes of `spec/processes.md` - [ ] T056 [P] Client READMEs for module errors and `moduleRefusal()` / `module_refusal()`: `crates/client/README.md`, `packages/guardian-client/README.md`, `crates/miden-multisig-client/README.md`, `packages/miden-multisig-client/README.md` From 02b3c07733f0a409bc581e3faa95647abef76148 Mon Sep 17 00:00:00 2001 From: Zeljko Date: Mon, 9 Nov 2026 12:03:32 +0100 Subject: [PATCH 039/105] docs(concepts): policy modules in the trust model (#251) CONCEPTS gains a policy module boundary: modules can only refuse, and what each one receives is a disclosure (full transactions, proposals that never execute, dry-run checks, proposer descriptions), with the operator guidance for vendors as data processors. The author guide asks module authors to document storage and keep personal data out of logs. --- docs/CONCEPTS.md | 43 +++++++++++++++++++ docs/guides/policy-modules/custom.md | 9 ++++ .../features/251-guardian-modules/tasks.md | 2 +- 3 files changed, 53 insertions(+), 1 deletion(-) diff --git a/docs/CONCEPTS.md b/docs/CONCEPTS.md index 34810157..cdba109c 100644 --- a/docs/CONCEPTS.md +++ b/docs/CONCEPTS.md @@ -178,6 +178,7 @@ flowchart LR | Guardian → Client | The ACK signature on every accepted delta. Clients verify the ACK and the commitment chain before trusting returned state. | | Client → Miden | Miden's own ZK proof verification; Guardian is not in this path. | | Guardian → Miden | Read-only RPC; Miden does not trust Guardian for anything. | +| Guardian → policy modules (optional) | Modules can only refuse: the Guardian signs only when every applicable module allows, and a module never holds a key. Remote modules are reached over TLS with a bearer token per instance. What they receive is a disclosure; see [Policy modules](#policy-modules) below. | | Inside Guardian | Backend access control, IAM scoping, infrastructure hardening — see [`docs/runbooks/secrets.md`](./runbooks/secrets.md) and [`docs/architecture/infra.md`](./architecture/infra.md). | What this means in practice: @@ -191,6 +192,48 @@ What this means in practice: locally; they just cannot sync with their other devices, and other cosigners cannot see their proposals. +### Policy modules + +An operator can start Guardian with a module catalog: policy modules it asks +before it creates a proposal, signs a delta or accepts a new account +([guide](./guides/policy-modules/README.md), +[RFC 0002](./rfcs/0002-guardian-modules.md)). They change the trust model in +two ways. + +- **They add a reason to refuse, never a way to sign.** A module that is + compromised or wrong can stop transactions (or, if its instance is set to + fail open, be skipped), but it cannot make Guardian sign anything the + cosigners did not sign. A rule that must hold even if Guardian itself is + compromised belongs in the account's code on chain, not in a module. +- **They are a disclosure.** Each module, and for a remote module the team or + vendor running it, receives for every account it applies to: + - the full transaction: amounts, assets, recipients, notes, storage and code + changes, and the account's signers and thresholds before and after; + - the verified signer that submitted it, and the proposer; + - the proposer's free-text proposal `description`, which can contain + personal data; + - transactions that never execute: proposals at creation, and every + transaction a cosigner checks with the dry-run endpoint (unless the + instance sets `dry_run = false`); + - at registration, the account's initial vault and storage. + + Secrets never reach a remote module: secret references are refused in its + configuration, and resolved values stay in the Guardian process. + +What this means for operators: + +- Treat a module vendor as a data processor. Ask it to document what it + stores, for how long and where, and put that in your agreement with it. +- Apply a module only where it is needed: a `scope = "assigned"` instance sees + only the accounts it is assigned to, and a module subscribed only to + `before_transaction_approved` does not see proposals at creation. +- Guardian's own logs hold, for every denial, the module's free-text + `message`, the account, the submitter and the reason code; they fall under + the same retention as the rest of the server log. +- What cosigners learn about the modules is chosen per instance + (`disclosure`, `client_reason`); by default they learn only that a policy + refused, with the module's instance id and reason code. + ## Client verification checklist When integrating an SDK against a Guardian, clients **must**: diff --git a/docs/guides/policy-modules/custom.md b/docs/guides/policy-modules/custom.md index 2936c93a..02aab75f 100644 --- a/docs/guides/policy-modules/custom.md +++ b/docs/guides/policy-modules/custom.md @@ -137,6 +137,15 @@ Miden is the only network today; read it with `subject.miden()` and return a `ModuleError` when it is absent, so a module never judges a transaction it does not understand. +## Personal data + +Requests can carry personal data: the proposer's free-text `description` in +`unverified_metadata`, and recipients and amounts that identify people. For a +remote module the operator treats you as a data processor, so document what +your module stores, for how long and where it runs. A module that does not +need a field should not log it, and `message` (logged by the Guardian for +every denial) should not repeat it. + ## Dry runs Cosigners can check a transaction before proposing it diff --git a/speckit/features/251-guardian-modules/tasks.md b/speckit/features/251-guardian-modules/tasks.md index 17d77828..2a0e286a 100644 --- a/speckit/features/251-guardian-modules/tasks.md +++ b/speckit/features/251-guardian-modules/tasks.md @@ -190,7 +190,7 @@ - [X] T052 [P] `docs/TROUBLESHOOTING.md`: `GUARDIAN_MODULE_DENIED`, `GUARDIAN_MODULE_UNAVAILABLE`, `GUARDIAN_MODULE_NOT_FOUND`, `GUARDIAN_MODULE_NOT_DISABLEABLE` with their `meta`, and the denial log fields - [X] T053 [P] Break-glass runbook `docs/runbooks/policy-modules.md` (RFC section 4.2): disabling an instance, deploy-only changes, circuit and budget symptoms; link it from `docs/runbooks/` and `CLAUDE.md`'s lookup table -- [ ] T054 [P] Trust boundary and data protection in `docs/CONCEPTS.md`: what external modules receive (full transaction details, proposals that never execute, proposer descriptions), and the operator and vendor guidance of RFC invariant 5 +- [X] T054 [P] Trust boundary and data protection in `docs/CONCEPTS.md`: what external modules receive (full transaction details, proposals that never execute, proposer descriptions), and the operator and vendor guidance of RFC invariant 5 - [ ] T055 [P] Protocol spec coverage: module error codes and `meta` on proposal creation, push and registration, `GET /policies` and `POST /delta/proposal/check` in `spec/api.md`, and the gate points in the push, proposal and registration processes of `spec/processes.md` - [ ] T056 [P] Client READMEs for module errors and `moduleRefusal()` / `module_refusal()`: `crates/client/README.md`, `packages/guardian-client/README.md`, `crates/miden-multisig-client/README.md`, `packages/miden-multisig-client/README.md` - [ ] T057 Rust and TypeScript parity fixture: one shared JSON fixture of module error bodies under `packages/guardian-client/src/` (or the repo's existing shared fixture location) driving both `crates/client` and `packages/guardian-client` tests, so SC-010 is checked by the same cases From c834f25b2e1d1227a7e37e94b04f3a8fa0d6638a Mon Sep 17 00:00:00 2001 From: Zeljko Date: Mon, 9 Nov 2026 12:04:52 +0100 Subject: [PATCH 040/105] docs(spec): policy module gates, routes and errors (#251) spec/api.md lists GET /policies, POST /delta/proposal/check, the dashboard module routes, the GetPolicies and CheckDeltaProposal RPCs and the GUARDIAN_MODULE_* codes with their meta and the routes that return them. spec/processes.md places the gates in the configure, proposal, push and execution flows and describes the dry-run check. --- spec/api.md | 27 ++++++++++++++++ spec/processes.md | 32 +++++++++++++++++-- .../features/251-guardian-modules/tasks.md | 2 +- 3 files changed, 58 insertions(+), 3 deletions(-) diff --git a/spec/api.md b/spec/api.md index 7222600f..e09ff0da 100644 --- a/spec/api.md +++ b/spec/api.md @@ -615,6 +615,8 @@ component schemas. | client | `POST /delta/proposal/execution` | signed headers | Ask Guardian to prove and submit a threshold-met proposal (202 new, 200 already running). Body `{account_id, proposal_id}`, both required and signed as `guardian.ExecuteDeltaProposal` (see [Miden Request Signing](#miden-request-signing)) | | client | `GET /delta/proposal/execution` | signed headers | The latest execution of a proposal (404 `GUARDIAN_EXECUTION_NOT_FOUND` when the proposal exists but was never executed; 404 `proposal_not_found` when the proposal is gone and no attempt is left, which is how a proposal whose records retention deleted reads: see `GUARDIAN_EXECUTION_RECORD_RETENTION_DAYS`) | | client | `GET /delta/execution/current` | signed headers | The account's in-flight execution; `{"execution": null}` when none | +| client | `GET /policies` | signed headers | The policy modules that apply to `?account_id`, as far as each instance's catalog entry discloses them, in evaluation order; empty without modules | +| client | `POST /delta/proposal/check` | signed headers | Dry run of `POST /delta/proposal` (same body): its checks and the account's gate modules with `dry_run = true`; stores nothing. `200 {allowed: true, complete}`, or the error creation would return. Rate limited per account and signer (`GUARDIAN_MODULE_CHECK_RATE_PER_MIN`) | | client | `POST /session` | wallet-signed grant in the body | Register a delegated signer (see [Session Authentication](#session-authentication)) | | client | `POST /session/logout` | session-key-signed headers | Revoke this session | | client | `POST /session/revoke-all` | wallet-signed headers | Revoke every session of a signer | @@ -633,6 +635,15 @@ component schemas. | dashboard | `GET /dashboard/stats` | session + `dashboard:read` | Account counts, Miden asset totals, and coverage in one request | | dashboard | `POST /dashboard/stats/refresh` | session + `stats:refresh` | Request an out-of-cycle refresh of the stats aggregate (202) | | dashboard | `GET /dashboard/session` | session | Session introspection | +| dashboard | `GET /dashboard/modules` | session + `dashboard:read` | Policy module catalog with runtime state (enabled, params, drift, circuit, undeclared stored instances) | +| dashboard | `GET /dashboard/modules/{module_id}/params/history` | session + `dashboard:read` | Params history of an instance, newest first (`before`, `limit`) | +| dashboard | `PUT /dashboard/modules/{module_id}/params` | session + `policies:write_global` | Replace an instance's global params (validated by the module; `reason` required) | +| dashboard | `POST /dashboard/modules/{module_id}/enable` | session + `policies:write` | Enable an instance after its startup checks | +| dashboard | `POST /dashboard/modules/{module_id}/disable` | session + `policies:write` or `modules:disable` | Disable an instance the catalog marks `operator_can_disable` | +| dashboard | `GET /dashboard/accounts/{account_id}/modules` | session + `dashboard:read` | The modules that apply to an account, its layers and assignments | +| dashboard | `PUT /dashboard/accounts/{account_id}/modules/{module_id}/params` | session + `policies:write` | Set an account's layer on an `all` instance | +| dashboard | `DELETE /dashboard/accounts/{account_id}/modules/{module_id}/params` | session + `policies:write` | Remove that layer | +| dashboard | `PUT /dashboard/accounts/{account_id}/modules` | session + `policies:write` | Replace an account's `default` and `assigned` module entries | | dashboard | `GET /dashboard/deltas` | session + `dashboard:read` | Cross-account delta feed | | dashboard | `GET /dashboard/proposals` | session + `dashboard:read` | Cross-account proposal feed | | evm | `GET /evm/auth/challenge` | public | EIP-712 session challenge | @@ -811,6 +822,20 @@ Stable error codes include: - `invalid_timestamp` (`/dashboard/stats?updated_since=` is not RFC3339, issue #371) - `GUARDIAN_INSUFFICIENT_OPERATOR_PERMISSION` - `GUARDIAN_ACCOUNT_PAUSED` +- Policy modules (servers started with a module catalog): `GUARDIAN_MODULE_DENIED` (HTTP 403 / + gRPC `PermissionDenied`; `meta.module`, `meta.reason_code`, `meta.layer` = `global` or + `account`, and `meta.client_message` when the module set one; an instance with + `client_reason = "generic"` sends only `meta.reason_code = "policy_denied"`) and + `GUARDIAN_MODULE_UNAVAILABLE` (HTTP 503 / gRPC `Unavailable`, `meta.module`, retryable: a + fail-closed module could not decide). Both are returned by `POST /configure` (hook + `before_account_registered`), `POST /delta/proposal` and `POST /delta/proposal/check` + (`before_proposal_created`, and in the check also `before_transaction_approved`) and + `POST /delta` (`before_transaction_approved`), and by their gRPC methods; a Guardian + execution reports them as `GUARDIAN_EXECUTION_MODULE_DENIED` and + `GUARDIAN_EXECUTION_MODULE_UNAVAILABLE` (see [ProposalExecution](#proposalexecution)). The + operator module routes add `GUARDIAN_MODULE_NOT_FOUND` (404, `meta.module`) and + `GUARDIAN_MODULE_NOT_DISABLEABLE` (409 / gRPC `FailedPrecondition`, `meta.module`), and + return `GUARDIAN_MODULE_UNAVAILABLE` when an instance being enabled fails its startup checks. - `data_unavailable` HTTP endpoints that return structured error envelopes include `code` when available. @@ -844,6 +869,8 @@ The gRPC surface mirrors the Miden state/delta methods. EVM account registration - `CreateSession(CreateSessionRequest) -> CreateSessionResponse` - `RevokeSession(RevokeSessionRequest) -> RevokeSessionResponse` - `RevokeAllSessions(RevokeAllSessionsRequest) -> RevokeAllSessionsResponse` +- `GetPolicies(GetPoliciesRequest) -> GetPoliciesResponse` (mirrors `GET /policies`) +- `CheckDeltaProposal(CheckDeltaProposalRequest) -> CheckDeltaProposalResponse` (mirrors `POST /delta/proposal/check`) Every gRPC method is rate limited from the same store as the HTTP surface; see [Rate Limiting](#rate-limiting) for the keying rules and the rejection diff --git a/spec/processes.md b/spec/processes.md index 61a3faf1..3ad04169 100644 --- a/spec/processes.md +++ b/spec/processes.md @@ -33,12 +33,20 @@ sequenceDiagram S->>S: reject unless auth cosigners == extracted signer map\n(exact set, order and schemes) S->>S: auth.verify(account_id, timestamp, request_payload_digest, credential) S->>N: get_state_head(account_id, initial_state)\n(commitment, nonce) + opt policy modules configured + S->>S: before_account_registered gate\n(a new account also runs its default-scope modules) + Note over S: a refusal: 403 GUARDIAN_MODULE_DENIED or 503 GUARDIAN_MODULE_UNAVAILABLE, nothing written + end alt no metadata for account_id S->>M: create(account_id, auth, network_config, timestamps)\n(insert only if absent) alt claim lost to a concurrent first configuration S->>M: get(account_id)\n(judged as a reconfiguration from here) + S->>S: before_account_registered gate again, as a reconfiguration end end + opt the request claimed the account (or finishes an unfinished claim) and default-scope modules apply + S->>S: copy them into the account's assignment\n(only with no assignment and no assignment history) + end Note over S,M: the claim guarantees the metadata row that replay state references by FK S->>M: update last_auth_timestamp (verified signer, CAS)\n(refused: authentication_replay, nothing written) Note over S,M: before any stored-state or chain read below, so a replayed request never drives the history search @@ -96,7 +104,10 @@ sequenceDiagram alt a candidate is queued and new_nonce is not the delta's nonce S-->>C: 409 ConflictPendingDelta end - S->>S: ack_delta(delta.new_commitment) -> ack_sig + opt policy modules configured + S->>S: before_transaction_approved gate\n(a refusal: 403 GUARDIAN_MODULE_DENIED or 503 GUARDIAN_MODULE_UNAVAILABLE, nothing signed) + end + S->>S: ack_delta(delta.new_commitment) -> ack_sig\n(records the approving catalog and params version in metadata.modules) alt canonicalization enabled S->>ST: submit_candidate(candidate)\n(the same gate again, under the account lock) else optimistic mode @@ -215,6 +226,10 @@ sequenceDiagram S-->>C: 409 ConflictPendingDelta end S->>N: verify_delta(tail_commitment, tail_state, tx_summary) + opt policy modules configured + S->>S: before_proposal_created gate\n(global params, then each account layer) + Note over S: a refusal: 403 GUARDIAN_MODULE_DENIED or 503 GUARDIAN_MODULE_UNAVAILABLE, no proposal stored + end S->>N: delta_proposal_id(account_id, nonce, tx_summary) S->>ST: submit_delta_proposal(id, pending_delta)\n(prev_commitment = tail commitment) S-->>C: 200 {delta, commitment:id} @@ -222,6 +237,14 @@ sequenceDiagram end ``` +The dry-run check (`POST /delta/proposal/check`, gRPC `CheckDeltaProposal`) takes the same +body and runs the same steps through `verify_delta`, then the account's gate modules with +`dry_run = true`: those subscribed to `before_proposal_created`, then those subscribed only to +`before_transaction_approved`. It stores nothing, takes no proposal slot, and answers +`200 {allowed: true, complete}` (`complete` is false when the catalog has an enabled gate +instance with `dry_run = false`) or the error creation would return. It is rate limited per +account and signer before the account state is rebuilt. + #### sign_delta_proposal ```mermaid sequenceDiagram @@ -241,6 +264,7 @@ sequenceDiagram S-->>C: 200 {delta_with_signatures} ``` + #### evm_accounts_and_proposals ```mermaid sequenceDiagram @@ -670,7 +694,11 @@ The execute payload is domain-separated from a signed status read of the same pr Take the chain tip as the reference block `R` and build the chain view at `R`, tracking the bound block and every authenticated note's creation block. 4. Reproduce the transaction unsigned at `R` and confirm it yields the signed summary. -5. Issue Guardian's acknowledgment through the internal path, which stores no candidate. +5. Issue Guardian's acknowledgment through the internal path, which stores no candidate. On a + server with policy modules the `before_transaction_approved` gate runs first, with the + requester as submitter and the proposal's creator as proposer; a refusal fails the execution + with `GUARDIAN_EXECUTION_MODULE_DENIED` or `GUARDIAN_EXECUTION_MODULE_UNAVAILABLE` and keeps + the proposal. 6. Attach the cosigner signatures and the acknowledgment. 7. Execute the authorized transaction at `R`, loading public foreign accounts at `R`. 8. Re-check the executed notes against the summary and that the transaction has not expired. diff --git a/speckit/features/251-guardian-modules/tasks.md b/speckit/features/251-guardian-modules/tasks.md index 2a0e286a..2c09592a 100644 --- a/speckit/features/251-guardian-modules/tasks.md +++ b/speckit/features/251-guardian-modules/tasks.md @@ -191,7 +191,7 @@ - [X] T052 [P] `docs/TROUBLESHOOTING.md`: `GUARDIAN_MODULE_DENIED`, `GUARDIAN_MODULE_UNAVAILABLE`, `GUARDIAN_MODULE_NOT_FOUND`, `GUARDIAN_MODULE_NOT_DISABLEABLE` with their `meta`, and the denial log fields - [X] T053 [P] Break-glass runbook `docs/runbooks/policy-modules.md` (RFC section 4.2): disabling an instance, deploy-only changes, circuit and budget symptoms; link it from `docs/runbooks/` and `CLAUDE.md`'s lookup table - [X] T054 [P] Trust boundary and data protection in `docs/CONCEPTS.md`: what external modules receive (full transaction details, proposals that never execute, proposer descriptions), and the operator and vendor guidance of RFC invariant 5 -- [ ] T055 [P] Protocol spec coverage: module error codes and `meta` on proposal creation, push and registration, `GET /policies` and `POST /delta/proposal/check` in `spec/api.md`, and the gate points in the push, proposal and registration processes of `spec/processes.md` +- [X] T055 [P] Protocol spec coverage: module error codes and `meta` on proposal creation, push and registration, `GET /policies` and `POST /delta/proposal/check` in `spec/api.md`, and the gate points in the push, proposal and registration processes of `spec/processes.md` - [ ] T056 [P] Client READMEs for module errors and `moduleRefusal()` / `module_refusal()`: `crates/client/README.md`, `packages/guardian-client/README.md`, `crates/miden-multisig-client/README.md`, `packages/miden-multisig-client/README.md` - [ ] T057 Rust and TypeScript parity fixture: one shared JSON fixture of module error bodies under `packages/guardian-client/src/` (or the repo's existing shared fixture location) driving both `crates/client` and `packages/guardian-client` tests, so SC-010 is checked by the same cases - [ ] T058 End-to-end smokes with a catalog: `smoke-test-rust-multisig-sdk` and `smoke-test-ts-multisig-sdk` skills, refusal at creation, push and registration, and `examples/demo` and `examples/web` with and without a catalog (quickstart section 5); and the operator module routes, including `modules:disable` permission errors, through `examples/operator-smoke-web` with the `smoke-test-operator-dashboard` skill From d8d3da913df0c8e405bae6bbff14b0e5c6a477e4 Mon Sep 17 00:00:00 2001 From: Zeljko Date: Mon, 9 Nov 2026 12:05:30 +0100 Subject: [PATCH 041/105] docs(clients): module refusals of Guardian executions (#251) The base client READMEs say how a Guardian execution refused by a module ends; the multisig READMEs already did. --- crates/client/README.md | 5 ++++- packages/guardian-client/README.md | 5 ++++- spec/processes.md | 1 - speckit/features/251-guardian-modules/tasks.md | 2 +- 4 files changed, 9 insertions(+), 4 deletions(-) diff --git a/crates/client/README.md b/crates/client/README.md index d5eae208..a29b5b6b 100644 --- a/crates/client/README.md +++ b/crates/client/README.md @@ -143,7 +143,10 @@ A refusal is a `ClientError` whose `guardian_code()` is the wire code (for examp it. A request a module refuses fails with a `ClientError` whose `module_refusal()` returns `ModuleRefusal::Denied { module, reason_code, layer, client_message }` (final; a generic denial carries only `policy_denied`) or -`ModuleRefusal::Unavailable { module }` (retryable): +`ModuleRefusal::Unavailable { module }` (retryable). A Guardian execution a +module refuses ends failed with `ExecutionFailureCode::ModuleDenied(ModuleDenial)` +or `ExecutionFailureCode::ModuleUnavailable { module }`, and its proposal is +kept: ```rust match client.push_delta_proposal(&account_id, nonce, payload).await { diff --git a/packages/guardian-client/README.md b/packages/guardian-client/README.md index 2b9d78da..8410306f 100644 --- a/packages/guardian-client/README.md +++ b/packages/guardian-client/README.md @@ -385,7 +385,10 @@ clientMessage }` (final; a generic denial has only `reasonCode: 'policy_denied'`) or `{ kind: 'unavailable', module }` (retryable), and `null` for any other error. `getPolicies(accountId)` lists the rules the Guardian discloses, and `checkDeltaProposal(request)` runs the policy modules on a -proposal without storing it. +proposal without storing it. A Guardian execution a module refuses ends +`failed` with `error.code` `GUARDIAN_EXECUTION_MODULE_DENIED` (the same `meta` +as a denial) or `GUARDIAN_EXECUTION_MODULE_UNAVAILABLE` (`meta.module`), and +its proposal is kept. ### Rate limits and retries diff --git a/spec/processes.md b/spec/processes.md index 3ad04169..6b408ab7 100644 --- a/spec/processes.md +++ b/spec/processes.md @@ -264,7 +264,6 @@ sequenceDiagram S-->>C: 200 {delta_with_signatures} ``` - #### evm_accounts_and_proposals ```mermaid sequenceDiagram diff --git a/speckit/features/251-guardian-modules/tasks.md b/speckit/features/251-guardian-modules/tasks.md index 2c09592a..eae8cf32 100644 --- a/speckit/features/251-guardian-modules/tasks.md +++ b/speckit/features/251-guardian-modules/tasks.md @@ -192,7 +192,7 @@ - [X] T053 [P] Break-glass runbook `docs/runbooks/policy-modules.md` (RFC section 4.2): disabling an instance, deploy-only changes, circuit and budget symptoms; link it from `docs/runbooks/` and `CLAUDE.md`'s lookup table - [X] T054 [P] Trust boundary and data protection in `docs/CONCEPTS.md`: what external modules receive (full transaction details, proposals that never execute, proposer descriptions), and the operator and vendor guidance of RFC invariant 5 - [X] T055 [P] Protocol spec coverage: module error codes and `meta` on proposal creation, push and registration, `GET /policies` and `POST /delta/proposal/check` in `spec/api.md`, and the gate points in the push, proposal and registration processes of `spec/processes.md` -- [ ] T056 [P] Client READMEs for module errors and `moduleRefusal()` / `module_refusal()`: `crates/client/README.md`, `packages/guardian-client/README.md`, `crates/miden-multisig-client/README.md`, `packages/miden-multisig-client/README.md` +- [X] T056 [P] Client READMEs for module errors and `moduleRefusal()` / `module_refusal()`: `crates/client/README.md`, `packages/guardian-client/README.md`, `crates/miden-multisig-client/README.md`, `packages/miden-multisig-client/README.md` - [ ] T057 Rust and TypeScript parity fixture: one shared JSON fixture of module error bodies under `packages/guardian-client/src/` (or the repo's existing shared fixture location) driving both `crates/client` and `packages/guardian-client` tests, so SC-010 is checked by the same cases - [ ] T058 End-to-end smokes with a catalog: `smoke-test-rust-multisig-sdk` and `smoke-test-ts-multisig-sdk` skills, refusal at creation, push and registration, and `examples/demo` and `examples/web` with and without a catalog (quickstart section 5); and the operator module routes, including `modules:disable` permission errors, through `examples/operator-smoke-web` with the `smoke-test-operator-dashboard` skill - [ ] T059 Quickstart walk-through against a local node with the filesystem backend and the latency A/B (zero, one in-process, one remote module), results in `speckit/features/251-guardian-modules/research.md` (P0 T033; SC-001, SC-006) From 5e0f6cd9ecade869e00f4748b2111175c1887376 Mon Sep 17 00:00:00 2001 From: Zeljko Date: Mon, 9 Nov 2026 12:06:41 +0100 Subject: [PATCH 042/105] test(clients): shared module refusal fixture (#251) fixtures/guardian-client/module-refusals.json drives the refusal and retry classification tests of both guardian-client crates: full, layer, generic and unavailable refusals, unknown meta fields, and the error bodies that must not read as refusals. --- crates/client/src/error.rs | 52 ++++++ fixtures/guardian-client/module-refusals.json | 160 ++++++++++++++++++ packages/guardian-client/src/http.test.ts | 25 ++- .../features/251-guardian-modules/tasks.md | 2 +- 4 files changed, 237 insertions(+), 2 deletions(-) create mode 100644 fixtures/guardian-client/module-refusals.json diff --git a/crates/client/src/error.rs b/crates/client/src/error.rs index 0b43200d..393c2a43 100644 --- a/crates/client/src/error.rs +++ b/crates/client/src/error.rs @@ -374,6 +374,58 @@ mod tests { assert!(!ClientError::ServerError("boom".into()).is_not_found()); } + fn refusal_json(refusal: Option) -> serde_json::Value { + match refusal { + None => serde_json::Value::Null, + Some(ModuleRefusal::Denied { + module, + reason_code, + layer, + client_message, + }) => serde_json::json!({ + "kind": "denied", + "module": module, + "reasonCode": reason_code, + "layer": layer, + "clientMessage": client_message, + }), + Some(ModuleRefusal::Unavailable { module }) => { + serde_json::json!({ "kind": "unavailable", "module": module }) + } + } + } + + #[test] + fn module_refusals_match_shared_fixture() { + let path = concat!( + env!("CARGO_MANIFEST_DIR"), + "/../../fixtures/guardian-client/module-refusals.json" + ); + let fixture: serde_json::Value = + serde_json::from_str(&std::fs::read_to_string(path).unwrap()).unwrap(); + + for case in fixture["cases"].as_array().unwrap() { + let name = case["name"].as_str().unwrap(); + let code = tonic::Code::from_i32(case["grpc"]["code"].as_i64().unwrap() as i32); + let err: ClientError = tonic::Status::with_details( + code, + "test", + case["body"].to_string().into_bytes().into(), + ) + .into(); + assert_eq!( + refusal_json(err.module_refusal()), + case["expected"]["refusal"], + "refusal mismatch: {name}" + ); + assert_eq!( + err.is_retryable(), + case["expected"]["retryable"].as_bool().unwrap(), + "retryable mismatch: {name}" + ); + } + } + #[test] fn retry_classification_matches_shared_fixture() { let path = concat!( diff --git a/fixtures/guardian-client/module-refusals.json b/fixtures/guardian-client/module-refusals.json new file mode 100644 index 00000000..d992dd16 --- /dev/null +++ b/fixtures/guardian-client/module-refusals.json @@ -0,0 +1,160 @@ +{ + "version": 1, + "cases": [ + { + "name": "denial with a client message", + "body": { + "code": "GUARDIAN_MODULE_DENIED", + "message": "A policy refused this request.", + "meta": { + "retryable": false, + "module": "caps", + "reason_code": "amount_cap_exceeded", + "layer": "global", + "client_message": "Ask your treasury admin." + } + }, + "grpc": { "code": 7 }, + "http": { "status": 403 }, + "expected": { + "retryable": false, + "refusal": { + "kind": "denied", + "module": "caps", + "reasonCode": "amount_cap_exceeded", + "layer": "global", + "clientMessage": "Ask your treasury admin." + } + } + }, + { + "name": "denial in an account layer without a client message", + "body": { + "code": "GUARDIAN_MODULE_DENIED", + "message": "A policy refused this request.", + "meta": { + "retryable": false, + "module": "blocklist", + "reason_code": "recipient_denied", + "layer": "account" + } + }, + "grpc": { "code": 7 }, + "http": { "status": 403 }, + "expected": { + "retryable": false, + "refusal": { + "kind": "denied", + "module": "blocklist", + "reasonCode": "recipient_denied", + "layer": "account", + "clientMessage": null + } + } + }, + { + "name": "generic denial names no module", + "body": { + "code": "GUARDIAN_MODULE_DENIED", + "message": "A policy refused this request.", + "meta": { "retryable": false, "reason_code": "policy_denied" } + }, + "grpc": { "code": 7 }, + "http": { "status": 403 }, + "expected": { + "retryable": false, + "refusal": { + "kind": "denied", + "module": null, + "reasonCode": "policy_denied", + "layer": null, + "clientMessage": null + } + } + }, + { + "name": "unknown meta fields are ignored", + "body": { + "code": "GUARDIAN_MODULE_DENIED", + "message": "A policy refused this request.", + "meta": { + "retryable": false, + "module": "caps", + "reason_code": "amount_cap_exceeded", + "layer": "global", + "future_field": { "nested": true } + } + }, + "grpc": { "code": 7 }, + "http": { "status": 403 }, + "expected": { + "retryable": false, + "refusal": { + "kind": "denied", + "module": "caps", + "reasonCode": "amount_cap_exceeded", + "layer": "global", + "clientMessage": null + } + } + }, + { + "name": "unavailable module is retryable", + "body": { + "code": "GUARDIAN_MODULE_UNAVAILABLE", + "message": "A policy check is unavailable right now. Please try again shortly.", + "meta": { "retryable": true, "module": "risk-vendor" } + }, + "grpc": { "code": 14 }, + "http": { "status": 503 }, + "expected": { + "retryable": true, + "refusal": { "kind": "unavailable", "module": "risk-vendor" } + } + }, + { + "name": "denial without a reason code is not a refusal", + "body": { + "code": "GUARDIAN_MODULE_DENIED", + "message": "A policy refused this request.", + "meta": { "retryable": false, "module": "caps" } + }, + "grpc": { "code": 7 }, + "http": { "status": 403 }, + "expected": { "retryable": false, "refusal": null } + }, + { + "name": "unavailable without a module is not a refusal", + "body": { + "code": "GUARDIAN_MODULE_UNAVAILABLE", + "message": "A policy check is unavailable right now. Please try again shortly.", + "meta": { "retryable": true } + }, + "grpc": { "code": 14 }, + "http": { "status": 503 }, + "expected": { "retryable": true, "refusal": null } + }, + { + "name": "an operator module error is not a refusal", + "body": { + "code": "GUARDIAN_MODULE_NOT_FOUND", + "message": "That policy module doesn't exist.", + "meta": { "retryable": false, "module": "caps" } + }, + "grpc": { "code": 5 }, + "http": { "status": 404 }, + "expected": { "retryable": false, "refusal": null } + }, + { + "name": "another error is not a refusal", + "body": { + "code": "pending_proposals_limit", + "message": "This account has too many pending proposals.", + "meta": { "retryable": false } + }, + "grpc": { "code": 9 }, + "http": { "status": 409 }, + "expected": { "retryable": false, "refusal": null } + } + ] +} diff --git a/packages/guardian-client/src/http.test.ts b/packages/guardian-client/src/http.test.ts index e7262b4b..83b32434 100644 --- a/packages/guardian-client/src/http.test.ts +++ b/packages/guardian-client/src/http.test.ts @@ -1,6 +1,6 @@ import { readFileSync } from 'node:fs'; import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'; -import { GuardianHttpClient, GuardianHttpError } from './http.js'; +import { GuardianHttpClient, GuardianHttpError, type ModuleRefusal } from './http.js'; import { RequestAuthPayload } from './auth-request.js'; import type { Signer, ConfigureResponse, StateObject, DeltaObject, DeltaProposalResponse, SessionRequestSigner } from './types.js'; @@ -1832,6 +1832,29 @@ describe('GuardianHttpError', () => { }); }); + describe('module refusals (shared fixture)', () => { + interface FixtureCase { + name: string; + body: Record; + http: { status: number }; + expected: { retryable: boolean; refusal: ModuleRefusal | null }; + } + + const fixture = JSON.parse( + readFileSync( + new URL('../../../fixtures/guardian-client/module-refusals.json', import.meta.url), + 'utf-8' + ) + ) as { cases: FixtureCase[] }; + + it.each(fixture.cases.map((c) => [c.name, c] as const))('%s', (_name, c) => { + const error = new GuardianHttpError(c.http.status, 'error', JSON.stringify(c.body), null); + + expect(error.moduleRefusal()).toEqual(c.expected.refusal); + expect(error.isRetryable()).toBe(c.expected.retryable); + }); + }); + describe('error envelope contract (account-paused path)', () => { let client: GuardianHttpClient; beforeEach(() => { diff --git a/speckit/features/251-guardian-modules/tasks.md b/speckit/features/251-guardian-modules/tasks.md index eae8cf32..f46d3d85 100644 --- a/speckit/features/251-guardian-modules/tasks.md +++ b/speckit/features/251-guardian-modules/tasks.md @@ -193,7 +193,7 @@ - [X] T054 [P] Trust boundary and data protection in `docs/CONCEPTS.md`: what external modules receive (full transaction details, proposals that never execute, proposer descriptions), and the operator and vendor guidance of RFC invariant 5 - [X] T055 [P] Protocol spec coverage: module error codes and `meta` on proposal creation, push and registration, `GET /policies` and `POST /delta/proposal/check` in `spec/api.md`, and the gate points in the push, proposal and registration processes of `spec/processes.md` - [X] T056 [P] Client READMEs for module errors and `moduleRefusal()` / `module_refusal()`: `crates/client/README.md`, `packages/guardian-client/README.md`, `crates/miden-multisig-client/README.md`, `packages/miden-multisig-client/README.md` -- [ ] T057 Rust and TypeScript parity fixture: one shared JSON fixture of module error bodies under `packages/guardian-client/src/` (or the repo's existing shared fixture location) driving both `crates/client` and `packages/guardian-client` tests, so SC-010 is checked by the same cases +- [X] T057 Rust and TypeScript parity fixture: one shared JSON fixture of module error bodies under `packages/guardian-client/src/` (or the repo's existing shared fixture location) driving both `crates/client` and `packages/guardian-client` tests, so SC-010 is checked by the same cases - [ ] T058 End-to-end smokes with a catalog: `smoke-test-rust-multisig-sdk` and `smoke-test-ts-multisig-sdk` skills, refusal at creation, push and registration, and `examples/demo` and `examples/web` with and without a catalog (quickstart section 5); and the operator module routes, including `modules:disable` permission errors, through `examples/operator-smoke-web` with the `smoke-test-operator-dashboard` skill - [ ] T059 Quickstart walk-through against a local node with the filesystem backend and the latency A/B (zero, one in-process, one remote module), results in `speckit/features/251-guardian-modules/research.md` (P0 T033; SC-001, SC-006) - [ ] T060 SC-004 run: enable `basic-policy` on all accounts with the official image and the guides only, timed, gaps fixed in `docs/guides/policy-modules/` From 44cc32ee0a58a333f21a5b90189e8fd711dc60ec Mon Sep 17 00:00:00 2001 From: Zeljko Date: Mon, 9 Nov 2026 12:20:08 +0100 Subject: [PATCH 043/105] chore(skills): TLA+ models re-checked against the module work (#251) auth-replay, candidate-queue, guardian-switch, multisig-push-gate, guardian-execution and client-sync drifted only through module gates that refuse before any write, threaded arguments and typed refusals; their models still mirror the code, and the runs that execute match expected.txt. module-counting was recorded on the prototype before #510: Store now archives the superseded recoverable row, which stays promotable, instead of deleting it, and the map names the refusals submit_candidate gained. Its cells keep their expected results. --- .../skills/verify-auth-replay/fingerprints.txt | 2 +- .../verify-candidate-queue/fingerprints.txt | 2 +- .../skills/verify-client-sync/fingerprints.txt | 2 +- .../verify-guardian-execution/fingerprints.txt | 8 ++++---- .../verify-guardian-switch/fingerprints.txt | 6 +++--- .agents/skills/verify-module-counting/SKILL.md | 4 ++-- .../verify-module-counting/fingerprints.txt | 16 ++++++++-------- .../model/ModuleCounting.tla | 15 +++++++++------ .../verify-multisig-push-gate/fingerprints.txt | 2 +- speckit/features/251-guardian-modules/tasks.md | 2 +- 10 files changed, 31 insertions(+), 28 deletions(-) diff --git a/.agents/skills/verify-auth-replay/fingerprints.txt b/.agents/skills/verify-auth-replay/fingerprints.txt index abd6a146..ea84caab 100644 --- a/.agents/skills/verify-auth-replay/fingerprints.txt +++ b/.agents/skills/verify-auth-replay/fingerprints.txt @@ -6,7 +6,7 @@ crates/server/src/services/mod.rs resolve_account_with 6eae431d0ba4e218 crates/server/src/services/mod.rs verify_session_request 5d081e3ba4556d85 crates/server/src/services/mod.rs validate_request_timestamp a424be9d59fdcd65 crates/server/src/services/mod.rs consume_auth_timestamp 64a0dbe983375da7 -crates/server/src/services/configure_account.rs configure_account 5c4fab922c06281b +crates/server/src/services/configure_account.rs configure_account 38a51a4fea1d22c4 crates/server/src/session.rs stale_floor_cutoff_ms a13c376d529da7fa crates/server/src/session.rs replay_floor_key e6371be262401f43 crates/server/src/session.rs find 34aa53044b39192d diff --git a/.agents/skills/verify-candidate-queue/fingerprints.txt b/.agents/skills/verify-candidate-queue/fingerprints.txt index ea723e20..fc641827 100644 --- a/.agents/skills/verify-candidate-queue/fingerprints.txt +++ b/.agents/skills/verify-candidate-queue/fingerprints.txt @@ -41,7 +41,7 @@ crates/server/src/jobs/canonicalization/reconciliation.rs select_recoverable_pat crates/server/src/jobs/canonicalization/reconciliation.rs reconcile_recoverable_path 29ec5c6d03466450 crates/server/src/jobs/canonicalization/reconciliation.rs reconcile_account 7bcb69472529ff03 crates/server/src/jobs/canonicalization/reconciliation.rs reconcile_chain_advance a9652aaef66374ce -crates/server/src/services/push_delta.rs push_delta b0170443193b6575 +crates/server/src/services/push_delta.rs push_delta 9d408748c9129b26 crates/server/src/jobs/canonicalization/processor.rs process_full_pass d5bf1e79a30da8da crates/server/src/jobs/canonicalization/processor.rs process_recent_pass 596742f4f9ea8593 crates/server/src/storage/postgres.rs lease_fence_is_current 951aa94931bd4c54 diff --git a/.agents/skills/verify-client-sync/fingerprints.txt b/.agents/skills/verify-client-sync/fingerprints.txt index 66bc3106..d5cdc4c3 100644 --- a/.agents/skills/verify-client-sync/fingerprints.txt +++ b/.agents/skills/verify-client-sync/fingerprints.txt @@ -14,7 +14,7 @@ crates/miden-multisig-client/src/client/account.rs refresh_cached_account_from_s crates/miden-multisig-client/src/client/helpers.rs finalize_transaction bfd0fddd310f47e6 crates/miden-multisig-client/src/client/helpers.rs rebuilds_local_state_from_delta e505dcca5111be28 crates/miden-multisig-client/src/client/helpers.rs submit_transaction_at_tip 868a7b51b15f9fa7 -crates/miden-multisig-client/src/client/helpers.rs get_guardian_ack_signature c95d133cba082b6a +crates/miden-multisig-client/src/client/helpers.rs get_guardian_ack_signature 6724b8a80e8bcc59 crates/miden-multisig-client/src/client/proposals.rs execute_proposal 0ae7632c3d6f2cd7 crates/miden-multisig-client/src/client/proposals.rs propose_transaction_with_options 076e1703b567767d crates/miden-multisig-client/src/client/offline.rs execute_imported_proposal 371832148205f50f diff --git a/.agents/skills/verify-guardian-execution/fingerprints.txt b/.agents/skills/verify-guardian-execution/fingerprints.txt index 12ef8aa4..73372020 100644 --- a/.agents/skills/verify-guardian-execution/fingerprints.txt +++ b/.agents/skills/verify-guardian-execution/fingerprints.txt @@ -1,4 +1,4 @@ -crates/server/src/services/execute_proposal/service.rs request_execution 26ff7c0c41996b5d +crates/server/src/services/execute_proposal/service.rs request_execution f2e1425fef1c14ea crates/server/src/services/execute_proposal/worker.rs run_execution e7c8bb2181f51ea7 crates/server/src/services/execute_proposal/worker.rs run_to_boundary 8bef28647e656733 crates/server/src/services/execute_proposal/worker.rs approach_boundary a248e9dcb6395278 @@ -8,9 +8,9 @@ crates/server/src/services/execute_proposal/worker.rs advance bc3e2bddd7da680a crates/server/src/services/execute_proposal/worker.rs cross_boundary b58bff42ad1c5ea8 crates/server/src/services/execute_proposal/worker.rs claim_send d18c0a5a097fad39 crates/server/src/services/execute_proposal/worker.rs submit 616fae8fe329d651 -crates/server/src/services/execute_proposal/worker.rs fail 401af65c37945fa8 +crates/server/src/services/execute_proposal/worker.rs fail 36ad82b5368c5b1d crates/server/src/network/miden/execution/attempt.rs classify_submission_error 79c4779dd0bda7d6 -crates/shared/src/execution.rs ends_proposal eda192d5bc234edd +crates/shared/src/execution.rs ends_proposal b2abc6ad39edf8e6 crates/server/src/coordination/execution_leases.rs attempt 7c6506df2503b815 crates/server/src/coordination/execution_leases.rs release_quietly 44f6e42959e727ba crates/server/src/coordination/postgres/lease.rs try_acquire acd5be995d0ebf4f @@ -58,7 +58,7 @@ crates/server/src/storage/postgres.rs restore_superseded 5ae2a5e38baf32e6 crates/server/src/storage/postgres.rs pull_superseded_deltas b050cc3f5fe9d3b8 crates/server/src/builder/canonicalization.rs archives_superseded f304c6a39fa148b0 crates/server/src/jobs/execution_reconcile/mod.rs pass 56d789d1e89af925 -crates/server/src/jobs/execution_reconcile/mod.rs reconcile af57fca9f7d1e5e1 +crates/server/src/jobs/execution_reconcile/mod.rs reconcile c4c903cf181b721b crates/server/src/jobs/execution_reconcile/mod.rs take_ownership 5bebe04bb18a13b9 crates/server/src/jobs/execution_reconcile/mod.rs observe 4673e188710dde56 crates/server/src/jobs/execution_reconcile/mod.rs moved_on e7f1420c943edaf0 diff --git a/.agents/skills/verify-guardian-switch/fingerprints.txt b/.agents/skills/verify-guardian-switch/fingerprints.txt index 8db347e0..c1bf043d 100644 --- a/.agents/skills/verify-guardian-switch/fingerprints.txt +++ b/.agents/skills/verify-guardian-switch/fingerprints.txt @@ -1,9 +1,9 @@ crates/server/src/services/release_on_switch.rs release_if_guardian_switched 58154d671cc4879b crates/server/src/services/release_on_switch.rs release_switched_account 0a8d56a29871f92b crates/server/src/services/account_status.rs ensure_account_active_metadata b7303e5276ca4f67 -crates/server/src/services/push_delta.rs push_delta b0170443193b6575 -crates/server/src/services/push_delta_proposal.rs push_delta_proposal 0c8f49373a1294d1 -crates/server/src/services/configure_account.rs configure_account 5c4fab922c06281b +crates/server/src/services/push_delta.rs push_delta 9d408748c9129b26 +crates/server/src/services/push_delta_proposal.rs push_delta_proposal f3273779e9d7758f +crates/server/src/services/configure_account.rs configure_account 38a51a4fea1d22c4 crates/server/src/services/configure_account.rs stored_state_landed f1082399d583be3f crates/server/src/services/configure_account.rs stored_head 641128d1cfa79677 crates/server/src/services/pause_account.rs pause 7a8b3686c25b35b2 diff --git a/.agents/skills/verify-module-counting/SKILL.md b/.agents/skills/verify-module-counting/SKILL.md index 247b1326..b930791e 100644 --- a/.agents/skills/verify-module-counting/SKILL.md +++ b/.agents/skills/verify-module-counting/SKILL.md @@ -135,12 +135,12 @@ Rust paths are relative to `crates/server/src/`; "RFC" is | `Snapshot` | `services/push_delta.rs` `push_delta` (`CandidateChain::load_for_admission`) plus RFC 3.4 "Guardian side": queue, unacknowledged events and `resync_required` in one repeatable-read transaction. The client's base is the tail it knows | | `SnapshotQueue` | mutation `m3` only: the queue read in a second transaction | | `Evaluate` | RFC 3.4 "Module side": counters and watermark from one consistent read, pending entries above the watermark, plus the delta; `on_error = deny` under `resync_required` and until the resync's Gap is acknowledged (RFC 3.3) | -| `Store` | `storage/mod.rs` `gate_candidate_submission` (tail, room) under the account lock, `storage/postgres.rs` `submit_candidate` (deletes a `retained` or client-abandoned row at the same nonce) | +| `Store` | `storage/mod.rs` `gate_candidate_submission` (tail, room) under the account lock, `storage/postgres.rs` `submit_candidate` (archives a `retained` or client-abandoned row at the same nonce, which stays promotable; refuses a paused or released account and one under a Guardian execution without writing) | | `Execute` | a cosigner submits any signed delta; Miden executes it only on its parent state | | `Promote` | `storage/postgres.rs` `promote_candidate` (`PromotableKind::Candidate`) plus RFC 2.3/3.3: the `module_events` row in the same transaction | | `WriteEvent` | mutation `m5` only: the event row in a later transaction | | `Retain` | `jobs/canonicalization/processor.rs` `retain_candidate`; successors parked as `RetainReason::Orphaned` | -| `Reconcile` | `jobs/canonicalization/reconciliation.rs` `reconcile_chain_advance` / `reconcile_recoverable_path` through `promote_candidate` (`PromotableKind::Retained`, client-abandoned) | +| `Reconcile` | `jobs/canonicalization/reconciliation.rs` `reconcile_chain_advance` / `reconcile_recoverable_path` through `promote_candidate` (`PromotableKind::Retained`, client-abandoned, or `Superseded` for an archived row) | | `Expire` | retained-row TTL (reconciliation step 1) | | `Acquire`, `Notice` | `coordination/postgres/lease.rs` `try_acquire`; the old holder keeps sending until it notices | | `SendNotify`, `SendGap` | RFC 3.3 notifier: read the cursor and the Gap obligation in one statement; while the obligation is open send only the Gap, otherwise the next event | diff --git a/.agents/skills/verify-module-counting/fingerprints.txt b/.agents/skills/verify-module-counting/fingerprints.txt index 5e8f9aa1..67132624 100644 --- a/.agents/skills/verify-module-counting/fingerprints.txt +++ b/.agents/skills/verify-module-counting/fingerprints.txt @@ -1,13 +1,13 @@ -docs/rfcs/0002-guardian-modules.md 3.3 9f760f07762f1ecd -docs/rfcs/0002-guardian-modules.md 3.4 285f90b0ba171cf0 -crates/server/src/services/push_delta.rs push_delta 54b60bb855977653 +docs/rfcs/0002-guardian-modules.md 3.3 3109f5b03a7caef3 +docs/rfcs/0002-guardian-modules.md 3.4 c2ae5a4f05b457bd +crates/server/src/services/push_delta.rs push_delta 9d408748c9129b26 crates/server/src/storage/mod.rs gate_candidate_submission 99785be2d52ca367 crates/server/src/storage/mod.rs classify_chain_position ebe38e956458a637 crates/server/src/storage/mod.rs first_unchained_candidate 3708394aa8e3541c -crates/server/src/storage/postgres.rs submit_candidate 7afed2b7a0c8a186 -crates/server/src/storage/postgres.rs promote_candidate e198deeb1cbcd95d -crates/server/src/storage/postgres.rs update_candidate_status 3ee992cfd204ab19 +crates/server/src/storage/postgres.rs submit_candidate 78fce4c0773b9421 +crates/server/src/storage/postgres.rs promote_candidate 7723aa1795b4c94a +crates/server/src/storage/postgres.rs update_candidate_status d103f712cb1aaff7 crates/server/src/jobs/canonicalization/processor.rs retain_candidate 813bb75dd428ee39 -crates/server/src/jobs/canonicalization/reconciliation.rs reconcile_chain_advance 29b83278a35d3d6f -crates/server/src/jobs/canonicalization/reconciliation.rs reconcile_recoverable_path 7a132b53248e9701 +crates/server/src/jobs/canonicalization/reconciliation.rs reconcile_chain_advance a9652aaef66374ce +crates/server/src/jobs/canonicalization/reconciliation.rs reconcile_recoverable_path 29ec5c6d03466450 crates/server/src/coordination/postgres/lease.rs try_acquire acd5be995d0ebf4f diff --git a/.agents/skills/verify-module-counting/model/ModuleCounting.tla b/.agents/skills/verify-module-counting/model/ModuleCounting.tla index fdb45b39..5034bbbb 100644 --- a/.agents/skills/verify-module-counting/model/ModuleCounting.tla +++ b/.agents/skills/verify-module-counting/model/ModuleCounting.tla @@ -159,9 +159,13 @@ Evaluate(r) == \* The candidate gate (storage/mod.rs gate_candidate_submission) under the \* account lock: the delta must extend the current tail and the queue must -\* have room. Admission deletes a recoverable row at the same nonce -\* (storage/postgres.rs submit_candidate, "reconcile_superseded"). Only an -\* admitted delta's ack signature is returned. +\* have room. Admission archives a recoverable row at the same nonce +\* (storage/postgres.rs submit_candidate, archive_parked_delta, with +\* retention on), and reconciliation can still promote the archived row +\* (PromotableKind::Superseded) if it landed, so it stays in `retained` +\* until it expires. The other refusals submit_candidate adds (paused or +\* released account, an execution's reservation) write nothing, like a +\* refused gate. Only an admitted delta's ack signature is returned. Store(r) == /\ req[r].phase = "allowed" /\ LET t == Len(txs) + 1 @@ -169,12 +173,11 @@ Store(r) == IN IF req[r].base = QueueTail /\ Len(queue) < Depth /\ Len(txs) < MaxTx THEN /\ txs' = Append(txs, [parent |-> req[r].base, nonce |-> n, amt |-> req[r].amt]) /\ queue' = Append(queue, t) - /\ retained' = {x \in retained : txs[x].nonce # n} /\ evalLog' = [evalLog EXCEPT !.missedLive = req[r].missed.live, !.missedRecoverable = req[r].missed.recov] - ELSE UNCHANGED <> + ELSE UNCHANGED <> /\ req' = [req EXCEPT ![r] = Idle] - /\ UNCHANGED <> + /\ UNCHANGED <> (***************************************************************************) (* Chain and canonicalization. *) diff --git a/.agents/skills/verify-multisig-push-gate/fingerprints.txt b/.agents/skills/verify-multisig-push-gate/fingerprints.txt index 24ecc4f0..bd29374b 100644 --- a/.agents/skills/verify-multisig-push-gate/fingerprints.txt +++ b/.agents/skills/verify-multisig-push-gate/fingerprints.txt @@ -3,7 +3,7 @@ crates/server/src/services/multisig_admission.rs signature_floor 17e83d08e3b9b2b crates/server/src/services/multisig_admission.rs pending_signatures aaf000190ef8e292 crates/server/src/services/multisig_admission.rs verified_approver_count bdab3f16b0e99ab6 Cargo.lock @pin miden-standards 0.17.1 -crates/server/src/services/push_delta.rs push_delta b0170443193b6575 +crates/server/src/services/push_delta.rs push_delta 9d408748c9129b26 crates/server/src/services/ack_delta_internal.rs lookup_matching_proposal 9b5ac8501f9abe75 crates/server/src/services/candidate_chain.rs ensure_tail_keeps_auth cba3037b83a609b8 crates/server/src/services/sign_delta_proposal.rs sign_delta_proposal afc8cda063f8f4ae diff --git a/speckit/features/251-guardian-modules/tasks.md b/speckit/features/251-guardian-modules/tasks.md index f46d3d85..973f2127 100644 --- a/speckit/features/251-guardian-modules/tasks.md +++ b/speckit/features/251-guardian-modules/tasks.md @@ -197,7 +197,7 @@ - [ ] T058 End-to-end smokes with a catalog: `smoke-test-rust-multisig-sdk` and `smoke-test-ts-multisig-sdk` skills, refusal at creation, push and registration, and `examples/demo` and `examples/web` with and without a catalog (quickstart section 5); and the operator module routes, including `modules:disable` permission errors, through `examples/operator-smoke-web` with the `smoke-test-operator-dashboard` skill - [ ] T059 Quickstart walk-through against a local node with the filesystem backend and the latency A/B (zero, one in-process, one remote module), results in `speckit/features/251-guardian-modules/research.md` (P0 T033; SC-001, SC-006) - [ ] T060 SC-004 run: enable `basic-policy` on all accounts with the official image and the guides only, timed, gaps fixed in `docs/guides/policy-modules/` -- [ ] T061 Re-check the TLA+ models whose fingerprints the modules work moved (`verify-auth-replay`, `verify-candidate-queue`, `verify-client-sync`, `verify-guardian-switch`, `verify-module-counting`, `verify-multisig-push-gate`, `verify-proposal-lifecycle` under `.agents/skills/`) with each `check.sh`, then `--accept-drift` once the model still mirrors the code +- [X] T061 Re-check the TLA+ models whose fingerprints the modules work moved (`verify-auth-replay`, `verify-candidate-queue`, `verify-client-sync`, `verify-guardian-switch`, `verify-module-counting`, `verify-multisig-push-gate`, `verify-proposal-lifecycle` under `.agents/skills/`) with each `check.sh`, then `--accept-drift` once the model still mirrors the code - [ ] T062 Validation matrix of `speckit/features/251-guardian-modules/quickstart.md` section 5 (M2a rows) run end to end, including `cargo test -p guardian-server --features postgres` for module stores and proposal storage, and `gen-openapi --check` - [ ] T063 Export the `guardian_module_*` metrics: add them to the CloudWatch export allowlist in `infra/observability.tf` (selector groups by label dimensions) and a "Policy modules" section of panels in `docs/guides/observability/grafana/dashboards/guardian.json`, listed in `docs/guides/observability/README.md`; validate with `terraform validate` and the local Prometheus and Grafana stack From 5b0f6a7644795cb44598834d9e75d3d07c4220fe Mon Sep 17 00:00:00 2001 From: Zeljko Date: Mon, 9 Nov 2026 12:27:25 +0100 Subject: [PATCH 044/105] fix(modules): publish the module state gauges after the recorder exists (#251) The startup values of guardian_module_enabled, _config_drift, _catalog_info, _over_budget_accounts and _orphaned_assignments were set in build(), before ServerHandle::run() installs the Prometheus recorder, so they were never exported; only _up, set by the probe, reached /metrics. Each health probe now republishes them with the breaker state, which also keeps enabled and drift current when another replica changes them. --- crates/server/src/modules/mod.rs | 2 - crates/server/src/modules/pipeline.rs | 85 +++++++++++++++++++++++---- 2 files changed, 72 insertions(+), 15 deletions(-) diff --git a/crates/server/src/modules/mod.rs b/crates/server/src/modules/mod.rs index b7bfe13b..61d468e2 100644 --- a/crates/server/src/modules/mod.rs +++ b/crates/server/src/modules/mod.rs @@ -76,8 +76,6 @@ pub async fn from_env( let pipeline = ModulePipeline::new(catalog, registry, store, now, limits).await?; let version = pipeline.store().version().await?; let (over_budget, orphaned) = pipeline.report_stored_assignments().await?; - metrics::catalog(&pipeline.catalog_hash); - metrics::stored_assignments(over_budget, orphaned); let builds = pipeline .instances() .iter() diff --git a/crates/server/src/modules/pipeline.rs b/crates/server/src/modules/pipeline.rs index 503043b1..ece786a2 100644 --- a/crates/server/src/modules/pipeline.rs +++ b/crates/server/src/modules/pipeline.rs @@ -3,10 +3,10 @@ use guardian_module_sdk::{Decision, Effect, HookRequest, is_valid_reason_code}; use super::catalog::{Catalog, ClientReason, HookName, OnError, Scope}; -use std::collections::HashMap; +use std::collections::{HashMap, HashSet}; use std::sync::{Arc, RwLock}; -use super::breaker::Breakers; +use super::breaker::{Breakers, CircuitState}; use super::limits::Limits; use super::registry::{CallError, Instance, Registry, isolated}; use super::request::ViewCache; @@ -46,6 +46,10 @@ pub struct ModulePipeline { limits: Limits, breakers: Arc, pub catalog_hash: String, + /// Instances whose stored seed differs from the catalog's params, as of startup. + seed_drift: HashSet, + /// Accounts over the budget and orphaned assignment rows, as of the last report. + assignment_report: std::sync::Mutex<(usize, usize)>, } /// The `module_instances` rows as of one params version. @@ -137,20 +141,17 @@ impl ModulePipeline { .map(|row| (row.module_id, (row.global_params, row.enabled))) .collect(); let mut effective = HashMap::new(); + let mut seed_drift = HashSet::new(); for config in &mut catalog.instances { let Some((params, enabled)) = stored.get(&config.id) else { - super::metrics::enabled(&config.id, config.enabled); - super::metrics::config_drift(&config.id, false); continue; }; - super::metrics::enabled(&config.id, *enabled); - super::metrics::config_drift( - &config.id, - *enabled != config.catalog_enabled - || seeded - .get(&config.id) - .is_some_and(|seeded| *seeded != config.params), - ); + if seeded + .get(&config.id) + .is_some_and(|seeded| *seeded != config.params) + { + seed_drift.insert(config.id.clone()); + } if *enabled != config.catalog_enabled { tracing::warn!(module = %config.id, enabled, "Catalog `enabled` differs from the stored runtime flag; the stored flag applies"); } @@ -218,6 +219,8 @@ impl ModulePipeline { breakers: Arc::new(Breakers::new(limits.breaker_failures)), limits, catalog_hash: catalog.hash, + seed_drift, + assignment_report: std::sync::Mutex::new((0, 0)), }) } @@ -242,6 +245,8 @@ impl ModulePipeline { limits: Limits::default(), breakers: Arc::new(Breakers::new(Limits::default().breaker_failures)), catalog_hash: String::new(), + seed_drift: HashSet::new(), + assignment_report: std::sync::Mutex::new((0, 0)), } } @@ -332,14 +337,43 @@ impl ModulePipeline { ); } } + if let Ok(mut report) = self.assignment_report.lock() { + *report = (over, orphaned); + } Ok((over, orphaned)) } + /// Sets the state gauges from the stored rows and this replica's breakers. Run on every probe, + /// so they are set once a metrics recorder exists and follow changes other replicas make. + fn publish(&self, rows: &Rows) { + super::metrics::catalog(&self.catalog_hash); + let (over_budget, orphaned) = self + .assignment_report + .lock() + .map(|report| *report) + .unwrap_or_default(); + super::metrics::stored_assignments(over_budget, orphaned); + for instance in &self.instances { + let id = &instance.config.id; + let enabled = Self::enabled_in(rows, instance); + super::metrics::enabled(id, enabled); + super::metrics::config_drift( + id, + enabled != instance.config.catalog_enabled || self.seed_drift.contains(id), + ); + super::metrics::circuit_open(id, self.breakers.state(id) == CircuitState::Open); + } + } + /// One health probe of every enabled instance: `Describe` under its timeout, with the startup /// checks. A healthy module half-opens an open breaker so the next real call is sent. pub async fn probe(&self) { + let Ok(rows) = self.rows().await else { + return; + }; + self.publish(&rows); for instance in &self.instances { - if !matches!(self.enabled(instance).await, Ok(true)) { + if !Self::enabled_in(&rows, instance) { continue; } let healthy = @@ -886,6 +920,31 @@ params = {params} .unwrap() } + #[tokio::test] + async fn a_probe_publishes_the_state_gauges() { + let pipeline = pipeline(vec![instance( + "caps", + &[HookName::BeforeTransactionApproved], + OnError::Deny, + StubModule::allowing(), + )]); + let rows = pipeline.rows().await.unwrap(); + let recorder = crate::metrics::build_recorder(); + let handle = recorder.handle(); + metrics::with_local_recorder(&recorder, || pipeline.publish(&rows)); + let text = handle.render(); + for line in [ + "guardian_module_enabled{module=\"caps\"} 1", + "guardian_module_circuit_open{module=\"caps\"} 0", + "guardian_module_config_drift{module=\"caps\"} 0", + "guardian_module_over_budget_accounts 0", + "guardian_module_orphaned_assignments 0", + "guardian_module_catalog_info{catalog_hash=\"\"} 1", + ] { + assert!(text.contains(line), "{line} missing from:\n{text}"); + } + } + #[tokio::test] async fn invalid_catalog_params_stop_startup_without_seeding_them() { let store: Arc = Arc::new(super::super::store::FsModuleStore::in_memory()); From bcb7f5585389a43c8d11eeeec84eeec097799baa Mon Sep 17 00:00:00 2001 From: Zeljko Date: Mon, 9 Nov 2026 12:27:25 +0100 Subject: [PATCH 045/105] feat(observability): export policy module metrics (#251) The ADOT configuration forwards the guardian_module_* metrics to CloudWatch, by module (and outcome for evaluation latency), with the evaluation histogram delta-converted; the drift test now covers them. The Grafana dashboard gains a Policy modules row: evaluations by outcome, p99 per module, health, fail-open skips and configuration. Checked with terraform validate and a local server, Prometheus and Grafana. --- crates/server/src/metrics/names.rs | 12 +- docs/guides/observability/README.md | 11 +- .../grafana/dashboards/guardian.json | 258 ++++++++++++++++++ infra/observability.tf | 28 ++ .../features/251-guardian-modules/tasks.md | 2 +- 5 files changed, 301 insertions(+), 10 deletions(-) diff --git a/crates/server/src/metrics/names.rs b/crates/server/src/metrics/names.rs index f07e77ae..fcefd1bc 100644 --- a/crates/server/src/metrics/names.rs +++ b/crates/server/src/metrics/names.rs @@ -935,16 +935,16 @@ mod tests { } /// The CloudWatch export re-lists the metric inventory by hand - /// (`infra/observability.tf`); a block watch metric missing there + /// (`infra/observability.tf`); a block watch or module metric missing there /// would never reach CloudWatch, and its histogram would be exported /// with lifetime totals unless it is delta-converted too. #[test] - fn block_watch_metrics_are_exported_to_cloudwatch() { + fn block_watch_and_module_metrics_are_exported_to_cloudwatch() { let terraform = include_str!("../../../../infra/observability.tf"); - for def in REGISTRY - .iter() - .filter(|def| def.name.starts_with("guardian_block_watch_")) - { + for def in REGISTRY.iter().filter(|def| { + def.name.starts_with("guardian_block_watch_") + || def.name.starts_with("guardian_module_") + }) { assert!( terraform.contains(&format!("\"^{}$\"", def.name)), "{} is not selected by an ADOT metric declaration", diff --git a/docs/guides/observability/README.md b/docs/guides/observability/README.md index c01ff693..2aea5612 100644 --- a/docs/guides/observability/README.md +++ b/docs/guides/observability/README.md @@ -27,7 +27,8 @@ The server instruments, end to end: HTTP and gRPC request paths (rate, latency, in-flight, status/code), Miden RPC (the upstream chain node), storage operations and per-pool (`storage`/`metadata`) DB-pool saturation, canonicalization, the delta & proposal lifecycle, account growth, operator auth, -rate limiting, refresher health, and process metrics. +rate limiting, refresher health, Guardian execution, policy modules, and process +metrics. Two properties worth knowing as an operator: @@ -98,11 +99,15 @@ Panels are grouped by subsystem and map 1:1 onto the metric taxonomy in | Accounts | total + creation rate by network kind | | Auth & rate limiting | operator auth outcomes, sessions, rate-limit rejections, refresh failures | | Process / runtime | CPU, RSS, file descriptors | +| Guardian execution | executions ended by outcome and code, proving p95, reconciliation, oldest reservation | +| Policy modules | evaluations by module and outcome, p99 per module, health (`up`, circuit open, enabled), fail-open skips, catalog drift, accounts over budget, orphaned assignments | An `Instance` variable (top-left) filters to a single replica or aggregates across all of them. Some panels stay empty in this local filesystem stack — -**DB pool** needs a Postgres build, and **Miden RPC / deltas / proposals / -account creation** need a real signed multisig flow. Copy +**DB pool** needs a Postgres build, **Miden RPC / deltas / proposals / +account creation** need a real signed multisig flow, and **Policy modules** +needs a module catalog (`GUARDIAN_MODULES_CONFIG`, see the +[policy modules guide](../policy-modules/README.md)). Copy [`grafana/dashboards/guardian.json`](./grafana/dashboards/guardian.json) into your own Grafana and adapt it. diff --git a/docs/guides/observability/grafana/dashboards/guardian.json b/docs/guides/observability/grafana/dashboards/guardian.json index 9a167b28..9d65fbe6 100644 --- a/docs/guides/observability/grafana/dashboards/guardian.json +++ b/docs/guides/observability/grafana/dashboards/guardian.json @@ -2799,6 +2799,264 @@ "legendFormat": "observation outage (s)" } ] + }, + { + "type": "row", + "title": "Policy modules", + "collapsed": false, + "gridPos": { + "h": 1, + "w": 24, + "x": 0, + "y": 186 + }, + "id": 61, + "panels": [] + }, + { + "type": "timeseries", + "title": "Module evaluations by outcome", + "datasource": { + "type": "prometheus", + "uid": "guardian-prometheus" + }, + "gridPos": { + "h": 8, + "w": 12, + "x": 0, + "y": 187 + }, + "id": 62, + "fieldConfig": { + "defaults": { + "unit": "ops", + "custom": { + "drawStyle": "line", + "fillOpacity": 12, + "showPoints": "never", + "lineWidth": 1, + "lineInterpolation": "smooth" + } + }, + "overrides": [] + }, + "options": { + "legend": { + "displayMode": "list", + "placement": "bottom", + "showLegend": true + }, + "tooltip": { + "mode": "multi", + "sort": "desc" + } + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "guardian-prometheus" + }, + "expr": "sum by (module, outcome) (rate(guardian_module_evaluate_duration_seconds_count{instance=~\"$instance\"}[$__rate_interval]))", + "refId": "A", + "legendFormat": "{{module}} {{outcome}}" + } + ] + }, + { + "type": "timeseries", + "title": "Module evaluation p99", + "datasource": { + "type": "prometheus", + "uid": "guardian-prometheus" + }, + "gridPos": { + "h": 8, + "w": 12, + "x": 12, + "y": 187 + }, + "id": 63, + "fieldConfig": { + "defaults": { + "unit": "s", + "custom": { + "drawStyle": "line", + "fillOpacity": 12, + "showPoints": "never", + "lineWidth": 1, + "lineInterpolation": "smooth" + } + }, + "overrides": [] + }, + "options": { + "legend": { + "displayMode": "list", + "placement": "bottom", + "showLegend": true + }, + "tooltip": { + "mode": "multi", + "sort": "desc" + } + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "guardian-prometheus" + }, + "expr": "histogram_quantile(0.99, sum by (module, le) (rate(guardian_module_evaluate_duration_seconds_bucket{instance=~\"$instance\"}[$__rate_interval])))", + "refId": "A", + "legendFormat": "{{module}}" + } + ] + }, + { + "type": "timeseries", + "title": "Module health: up, circuit open, enabled", + "datasource": { + "type": "prometheus", + "uid": "guardian-prometheus" + }, + "gridPos": { + "h": 8, + "w": 12, + "x": 0, + "y": 195 + }, + "id": 64, + "fieldConfig": { + "defaults": { + "unit": "short", + "custom": { + "drawStyle": "line", + "fillOpacity": 12, + "showPoints": "never", + "lineWidth": 1, + "lineInterpolation": "smooth" + } + }, + "overrides": [] + }, + "options": { + "legend": { + "displayMode": "list", + "placement": "bottom", + "showLegend": true + }, + "tooltip": { + "mode": "multi", + "sort": "desc" + } + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "guardian-prometheus" + }, + "expr": "min by (module) (guardian_module_up{instance=~\"$instance\"})", + "refId": "A", + "legendFormat": "{{module}} up" + }, + { + "datasource": { + "type": "prometheus", + "uid": "guardian-prometheus" + }, + "expr": "max by (module) (guardian_module_circuit_open{instance=~\"$instance\"})", + "refId": "B", + "legendFormat": "{{module}} circuit open" + }, + { + "datasource": { + "type": "prometheus", + "uid": "guardian-prometheus" + }, + "expr": "min by (module) (guardian_module_enabled{instance=~\"$instance\"})", + "refId": "C", + "legendFormat": "{{module}} enabled" + } + ] + }, + { + "type": "timeseries", + "title": "Fail-open skips & configuration", + "datasource": { + "type": "prometheus", + "uid": "guardian-prometheus" + }, + "gridPos": { + "h": 8, + "w": 12, + "x": 12, + "y": 195 + }, + "id": 65, + "fieldConfig": { + "defaults": { + "unit": "short", + "custom": { + "drawStyle": "line", + "fillOpacity": 12, + "showPoints": "never", + "lineWidth": 1, + "lineInterpolation": "smooth" + } + }, + "overrides": [] + }, + "options": { + "legend": { + "displayMode": "list", + "placement": "bottom", + "showLegend": true + }, + "tooltip": { + "mode": "multi", + "sort": "desc" + } + }, + "targets": [ + { + "datasource": { + "type": "prometheus", + "uid": "guardian-prometheus" + }, + "expr": "sum by (module) (rate(guardian_module_fail_open_total{instance=~\"$instance\"}[$__rate_interval]))", + "refId": "A", + "legendFormat": "{{module}} fail-open/s" + }, + { + "datasource": { + "type": "prometheus", + "uid": "guardian-prometheus" + }, + "expr": "max by (module) (guardian_module_config_drift{instance=~\"$instance\"})", + "refId": "B", + "legendFormat": "{{module}} catalog drift" + }, + { + "datasource": { + "type": "prometheus", + "uid": "guardian-prometheus" + }, + "expr": "max(guardian_module_over_budget_accounts{instance=~\"$instance\"})", + "refId": "C", + "legendFormat": "accounts over budget" + }, + { + "datasource": { + "type": "prometheus", + "uid": "guardian-prometheus" + }, + "expr": "max(guardian_module_orphaned_assignments{instance=~\"$instance\"})", + "refId": "D", + "legendFormat": "orphaned assignments" + } + ] } ] } diff --git a/infra/observability.tf b/infra/observability.tf index 3d19cad1..c69e5df7 100644 --- a/infra/observability.tf +++ b/infra/observability.tf @@ -53,6 +53,7 @@ locals { "guardian_execution_proving_duration_seconds", "guardian_execution_phase_duration_seconds", "guardian_block_watch_block_processing_seconds", + "guardian_module_evaluate_duration_seconds", ] http_error_rate_expression = "100 * (${join(" + ", [for s in local.http_error_statuses : "FILL(h${s}, 0)"])}) / FILL(hall, 1)" @@ -345,6 +346,33 @@ locals { metric_name_selectors = ["^guardian_rate_limit_rejections_total$"] dimensions = [["transport"]] }, + { + # Policy modules (issue #251). `module` is a catalog instance id, so + # the series count is bounded by the catalog. + metric_name_selectors = ["^guardian_module_evaluate_duration_seconds$"] + dimensions = [["module"], ["module", "outcome"]] + }, + { + metric_name_selectors = [ + "^guardian_module_fail_open_total$", + "^guardian_module_up$", + "^guardian_module_circuit_open$", + "^guardian_module_enabled$", + "^guardian_module_config_drift$", + ] + dimensions = [["module"]] + }, + { + metric_name_selectors = ["^guardian_module_catalog_info$"] + dimensions = [["catalog_hash"]] + }, + { + metric_name_selectors = [ + "^guardian_module_over_budget_accounts$", + "^guardian_module_orphaned_assignments$", + ] + dimensions = [[]] + }, ] } } diff --git a/speckit/features/251-guardian-modules/tasks.md b/speckit/features/251-guardian-modules/tasks.md index 973f2127..56c062e4 100644 --- a/speckit/features/251-guardian-modules/tasks.md +++ b/speckit/features/251-guardian-modules/tasks.md @@ -199,7 +199,7 @@ - [ ] T060 SC-004 run: enable `basic-policy` on all accounts with the official image and the guides only, timed, gaps fixed in `docs/guides/policy-modules/` - [X] T061 Re-check the TLA+ models whose fingerprints the modules work moved (`verify-auth-replay`, `verify-candidate-queue`, `verify-client-sync`, `verify-guardian-switch`, `verify-module-counting`, `verify-multisig-push-gate`, `verify-proposal-lifecycle` under `.agents/skills/`) with each `check.sh`, then `--accept-drift` once the model still mirrors the code - [ ] T062 Validation matrix of `speckit/features/251-guardian-modules/quickstart.md` section 5 (M2a rows) run end to end, including `cargo test -p guardian-server --features postgres` for module stores and proposal storage, and `gen-openapi --check` -- [ ] T063 Export the `guardian_module_*` metrics: add them to the CloudWatch export allowlist in `infra/observability.tf` (selector groups by label dimensions) and a "Policy modules" section of panels in `docs/guides/observability/grafana/dashboards/guardian.json`, listed in `docs/guides/observability/README.md`; validate with `terraform validate` and the local Prometheus and Grafana stack +- [X] T063 Export the `guardian_module_*` metrics: add them to the CloudWatch export allowlist in `infra/observability.tf` (selector groups by label dimensions) and a "Policy modules" section of panels in `docs/guides/observability/grafana/dashboards/guardian.json`, listed in `docs/guides/observability/README.md`; validate with `terraform validate` and the local Prometheus and Grafana stack --- From a66667734db5e276ff5073dcbe40744035cedc2b Mon Sep 17 00:00:00 2001 From: Zeljko Date: Mon, 9 Nov 2026 13:18:53 +0100 Subject: [PATCH 046/105] perf(modules): decode the proposal's delta once when modules run (#251) Proposal creation verified the delta against the tail and then decoded and applied it again to build the account views for the modules. With modules to run it now calls apply_delta_with_module_views with the tail commitment, which performs the same check, and keeps verify_delta alone otherwise. The proposal median with one module dropped from +4 ms to within noise. The span keeps the name push_delta_proposal, which the creation refactor had changed to propose. --- .../src/services/push_delta_proposal.rs | 63 ++++++++++--------- 1 file changed, 35 insertions(+), 28 deletions(-) diff --git a/crates/server/src/services/push_delta_proposal.rs b/crates/server/src/services/push_delta_proposal.rs index b47c2043..5e56eeb0 100644 --- a/crates/server/src/services/push_delta_proposal.rs +++ b/crates/server/src/services/push_delta_proposal.rs @@ -105,6 +105,7 @@ pub async fn check_proposal( } #[tracing::instrument( + name = "push_delta_proposal", level = "info", skip(state, params), fields( @@ -297,16 +298,44 @@ async fn propose(state: &AppState, params: PushDeltaProposalParams, mode: Mode) .cloned() .unwrap_or_default(); - // Validate delta using network client (check validity but don't apply) - { + let (plans, complete) = match (dry_run, state.modules.as_deref()) { + (Some(planned), _) => planned, + (None, Some(modules)) => ( + modules + .plan(HookName::BeforeProposalCreated, &account_id) + .await? + .into_iter() + .collect(), + true, + ), + (None, None) => (Vec::new(), true), + }; + // With modules to run, one decode verifies the delta against the tail and builds the + // account views they receive; without, the delta is only verified. + let applied = { let client = state.network_client.clone(); let prev_commitment = tail.commitment.clone(); let prev_state_json = tail.state_json.clone(); let tx_summary = Arc::new(tx_summary.clone()); + let evaluate = !plans.is_empty(); crate::network::reconstructor() - .run(move || client.verify_delta(&prev_commitment, &prev_state_json, &tx_summary)) - .await?; - } + .run(move || { + if evaluate { + client + .apply_delta_with_module_views( + Some(&prev_commitment), + &prev_state_json, + &tx_summary, + ) + .map(Some) + } else { + client + .verify_delta(&prev_commitment, &prev_state_json, &tx_summary) + .map(|()| None) + } + }) + .await? + }; let commitment = proposal_id.map_err(GuardianError::InvalidDelta)?; tracing::Span::current().record("commitment", tracing::field::display(&commitment)); @@ -347,29 +376,7 @@ async fn propose(state: &AppState, params: PushDeltaProposalParams, mode: Mode) } tracing::Span::current().record("signer_count", cosigner_sigs.len()); - let (plans, complete) = match (dry_run, state.modules.as_deref()) { - (Some(planned), _) => planned, - (None, Some(modules)) => ( - modules - .plan(HookName::BeforeProposalCreated, &account_id) - .await? - .into_iter() - .collect(), - true, - ), - (None, None) => (Vec::new(), true), - }; - if !plans.is_empty() { - let (after, module_views) = { - let client = state.network_client.clone(); - let tail_state_json = tail.state_json.clone(); - let tx_summary = tx_summary.clone(); - crate::network::reconstructor() - .run(move || { - client.apply_delta_with_module_views(None, &tail_state_json, &tx_summary) - }) - .await? - }; + if let Some((after, module_views)) = applied { let proposal = ProposalContext { proposer: proposer_id.clone(), metadata: delta_payload From d2fb0d7694432074b516414ed5ca257216e7731b Mon Sep 17 00:00:00 2001 From: Zeljko Date: Mon, 9 Nov 2026 13:18:53 +0100 Subject: [PATCH 047/105] feat(loadgen): proposal-push scenario (#251) state-push is refused since the multisig push gate: a push needs a matching proposal with enough approvals. proposal-push creates a proposal carrying the owner's approval on one-signer accounts, then pushes the delta, so each operation runs the proposal and push paths and both module gate hooks. --- crates/server/bench/loadgen/src/config.rs | 6 + crates/server/bench/loadgen/src/scenarios.rs | 120 +++++++++++++++++-- 2 files changed, 119 insertions(+), 7 deletions(-) diff --git a/crates/server/bench/loadgen/src/config.rs b/crates/server/bench/loadgen/src/config.rs index d98d9d38..851325cb 100644 --- a/crates/server/bench/loadgen/src/config.rs +++ b/crates/server/bench/loadgen/src/config.rs @@ -11,6 +11,9 @@ pub enum Scenario { StateSync, /// Only `push_delta`, one chained delta per operation; isolates the push path. StatePush, + /// A proposal carrying the owner's approval, then the `push_delta` it allows: the multisig + /// write path since pushes need a matching approved proposal. One signer per account. + ProposalPush, Canonicalization, } @@ -87,6 +90,9 @@ impl RunConfig { if self.signers_per_account == 0 { bail!("signers-per-account must be greater than 0"); } + if self.scenario == Scenario::ProposalPush && self.signers_per_account != 1 { + bail!("proposal-push needs --signers-per-account 1: only the owner can approve"); + } if self.ops_per_user == 0 { bail!("ops-per-user must be greater than 0"); } diff --git a/crates/server/bench/loadgen/src/scenarios.rs b/crates/server/bench/loadgen/src/scenarios.rs index 73e17bc7..e1e657a2 100644 --- a/crates/server/bench/loadgen/src/scenarios.rs +++ b/crates/server/bench/loadgen/src/scenarios.rs @@ -48,6 +48,7 @@ pub struct UserContext { guardian_commitment: Word, signers_per_account: usize, auth: Option, + approver: Auth, last_timestamp_ms: i64, pub client: LoadClient, pub accounts: Vec, @@ -174,6 +175,54 @@ impl UserContext { } } + /// The owner's approval of `summary`, as proposal creation takes it. + fn approval(&self, summary: &TransactionSummary) -> Value { + let signature = self.approver.sign_word_hex(summary.to_commitment()); + let signature = match &self.approver { + Auth::FalconRpoSigner(_) => { + serde_json::json!({ "scheme": "falcon", "signature": signature }) + } + Auth::EcdsaSigner(signer) => serde_json::json!({ + "scheme": "ecdsa", + "signature": signature, + "public_key": signer.public_key_hex(), + }), + }; + serde_json::json!({ "signer_id": self.signer_commitment, "signature": signature }) + } + + async fn create_proposal( + &mut self, + account_id: &AccountId, + nonce: u64, + delta_payload: Value, + ) -> Result<()> { + match &mut self.client { + LoadClient::Grpc(client) => { + client + .push_delta_proposal(account_id, nonce, delta_payload) + .await?; + Ok(()) + } + LoadClient::Http(_) => { + let payload = serde_json::json!({ + "account_id": account_id.to_string(), + "nonce": nonce, + "delta_payload": delta_payload, + }); + let response = self + .http_request_with_auth( + Method::POST, + "/delta/proposal", + account_id, + Some(payload), + ) + .await?; + ensure_http_success(response, "push_delta_proposal").await + } + } + } + async fn push_state( &mut self, account_id: &AccountId, @@ -414,18 +463,28 @@ pub async fn seed_accounts(config: &RunConfig) -> Result> { let mut user_contexts = Vec::with_capacity(users); for user_id in 0..users { - let (auth, commitment) = match config.auth_scheme { + let (auth, approver, commitment) = match config.auth_scheme { AuthScheme::Falcon => { - let signer = FalconRpoSigner::new(FalconSecretKey::new()); + let key = FalconSecretKey::new(); + let signer = FalconRpoSigner::new(key.clone()); let commitment = commitment_hex_from_pubkey_hex(&signer.public_key_hex(), config.auth_scheme)?; - (Auth::FalconRpoSigner(signer), commitment) + ( + Auth::FalconRpoSigner(signer), + Auth::FalconRpoSigner(FalconRpoSigner::new(key)), + commitment, + ) } AuthScheme::Ecdsa => { - let signer = EcdsaSigner::new(EcdsaSecretKey::new()); + let key = EcdsaSecretKey::new(); + let signer = EcdsaSigner::new(key.clone()); let commitment = commitment_hex_from_pubkey_hex(&signer.public_key_hex(), config.auth_scheme)?; - (Auth::EcdsaSigner(signer), commitment) + ( + Auth::EcdsaSigner(signer), + Auth::EcdsaSigner(EcdsaSigner::new(key)), + commitment, + ) } }; let (client, user_auth) = build_client(config, auth).await?; @@ -437,6 +496,7 @@ pub async fn seed_accounts(config: &RunConfig) -> Result> { guardian_commitment: guardian_commitment_word, signers_per_account, auth: user_auth, + approver, last_timestamp_ms: 0, client, accounts: Vec::new(), @@ -550,6 +610,9 @@ async fn run_worker(config: &RunConfig, user: &mut UserContext) -> WorkerMetrics } } Scenario::StatePush => run_push_state_operation(user, op_index, account_count).await, + Scenario::ProposalPush => { + run_proposal_push_operation(user, op_index, account_count).await + } Scenario::Canonicalization => { run_canonicalization_operation(config, user, op_index, account_count).await } @@ -587,7 +650,8 @@ fn scenario_op_count(config: &RunConfig, account_count: usize) -> usize { | Scenario::StateWrite | Scenario::Mixed | Scenario::StateSync - | Scenario::StatePush => usize::try_from(config.ops_per_user).unwrap_or(0), + | Scenario::StatePush + | Scenario::ProposalPush => usize::try_from(config.ops_per_user).unwrap_or(0), } } @@ -807,7 +871,49 @@ fn create_account_seed( }) } +async fn run_proposal_push_operation( + user: &mut UserContext, + op_index: usize, + account_count: usize, +) -> Result<()> { + let account_index = op_index % account_count; + let (account_id, nonce, prev_commitment, summary) = { + let account = &user.accounts[account_index]; + let nonce = account.next_nonce; + ( + account.account_id, + nonce, + account.commitment.clone(), + delta_summary(&account.account_id, nonce)?, + ) + }; + let delta_payload = summary.to_json(); + let proposal = serde_json::json!({ + "tx_summary": delta_payload, + "metadata": { "proposal_type": "custom" }, + "signatures": [user.approval(&summary)], + }); + user.create_proposal(&account_id, nonce, proposal).await?; + + let new_commitment = user + .push_state(&account_id, nonce, prev_commitment, delta_payload) + .await?; + + if let Some(account) = user.accounts.get_mut(account_index) { + account.next_nonce = nonce + 1; + if let Some(commitment) = new_commitment { + account.commitment = commitment; + } + } + + Ok(()) +} + fn create_delta_payload(account_id: &AccountId, nonce: u64) -> Result { + Ok(delta_summary(account_id, nonce)?.to_json()) +} + +fn delta_summary(account_id: &AccountId, nonce: u64) -> Result { let account_delta = AccountDelta::new( account_id.to_owned(), AccountStoragePatch::default(), @@ -826,7 +932,7 @@ fn create_delta_payload(account_id: &AccountId, nonce: u64) -> Result { 0, TransactionSummaryUserParams::new([ZERO; 6]), ); - Ok(tx_summary.to_json()) + Ok(tx_summary) } fn build_signer_commitments( From 8a80214eb5d575e4ebd3fffa8192f6dd5b7a7406 Mon Sep 17 00:00:00 2001 From: Zeljko Date: Mon, 9 Nov 2026 13:18:53 +0100 Subject: [PATCH 048/105] docs(modules): M2a end-to-end latency A/B (#251) --- .../features/251-guardian-modules/research.md | 18 ++++++++++++++++++ speckit/features/251-guardian-modules/tasks.md | 2 +- 2 files changed, 19 insertions(+), 1 deletion(-) diff --git a/speckit/features/251-guardian-modules/research.md b/speckit/features/251-guardian-modules/research.md index c1c17cc3..18d086f8 100644 --- a/speckit/features/251-guardian-modules/research.md +++ b/speckit/features/251-guardian-modules/research.md @@ -181,6 +181,24 @@ At concurrency 8 (3 rounds x 1,600 pushes) the server is saturated at about 89 p - Fixed (2026-10-16): account views are cached per replica by the state commitment the Guardian computed (stored tail, applied state, registration head; never a client value), bounded at 4,096 entries. A chained push reuses the previous push's `after` view, and a proposal's approval push reuses both views built at its creation. `push_delta` reads the matching proposal once for metadata and modules; a storage failure still reaches modules as a failure, not as "no proposer". - Left for M2a: the remaining `after` decode (about 1.3 ms) could come from the account `apply_delta` already decodes. Since #523 (`8c1e5d6f`) the push path calls `verify_and_apply_delta`, which decodes the base account once and applies the summary to it, so both views can be read from that decode by adding view fields to `AppliedState`; proposal creation still calls `verify_delta` alone and moves to `verify_and_apply_delta` when a module will be called (RFC revision 24, section 3.2). Re-measure on a quiet machine. Moving request assembly inside the reconstruction gate (revision 20 item 8) would put this cost into the contended section; measure throughput at concurrency 8 before and after. +### M2a end to end (2026-11-09) + +The loadgen `state-push` scenario no longer works since the multisig push gate (#536): a bare push is refused with "This transaction still needs more signatures". A new `proposal-push` scenario creates a proposal carrying the owner's approval (one-signer accounts) and then pushes the delta, so each operation runs both gate hooks, `before_proposal_created` and `before_transaction_approved`. Same setup as G3 otherwise: `examples/bench_server` release build, filesystem backend, canonicalization off, gRPC with Falcon auth, concurrency 1, 4 accounts. Three configurations: no catalog; one in-process `basic-policy` instance on both hooks (amount cap and signer rule); the same params served by `examples/policy-module` over loopback gRPC with a bearer token. No local node of the 0.17 line was available (the installed `miden-node` is 0.15.1), so the server connects to devnet RPC at startup only; nothing in the measured path calls the node. Latencies are server-side span times (`push_delta_proposal`, `push_delta`), 3,000 requests each. + +| Build | Config | proposal p50 | proposal p99 | push p50 | push p99 | +|---|---|---|---|---|---| +| before the fix below, fixed leg order | none | 20.8 ms | 44.5 ms | 28.1 ms | 56.4 ms | +| | in-process | 24.9 ms (+4.1) | 61.7 ms | 29.4 ms (+1.3) | 74.0 ms | +| | remote | 24.5 ms (+3.7) | 54.3 ms | 29.1 ms (+1.0) | 60.8 ms | +| after the fix, leg order rotated per round | none | 21.9 ms | 96.7 ms | 29.7 ms | 108.8 ms | +| | in-process | 21.5 ms | 86.5 ms | 28.7 ms | 107.0 ms | +| | remote | 21.5 ms | 63.9 ms | 29.0 ms | 76.2 ms | + +- Fixed: with modules to run, proposal creation verified the delta (`verify_delta`) and then decoded and applied it again for the module views. It now decodes once (`apply_delta_with_module_views` with the tail commitment, which performs the same check), and keeps `verify_delta` alone when no module applies. The consistent +4 ms at the proposal median went away. +- The p99 differences are the machine, not the modules: with a fixed order (none, in-process, remote) the in-process leg showed a p99 two to three times the baseline in every round, and with the order rotated the tail followed the position instead (the no-catalog leg in round 1 reached 315 ms client-side). CPU time on the request task (`time.busy`) differs by under 0.5 ms at p50 between configurations. +- **SC-001** holds (no catalog is one `Option` check per request) and **SC-006** holds within this machine's noise; a quiet machine or the deployed bench would bound the p99 more tightly. +- Not run here: the quickstart walk-through against a local node; it needs a 0.17-line `miden-node`. + ### In-process custom kinds (2026-10-16) `ServerBuilder::with_module_kind` is about thirty lines on top of the existing `Registry`: the catalog, pipeline, params API and history already work for any kind. The cost is elsewhere. In process, a module shares the process that holds the acknowledgement keys, so "a module can only refuse" holds by review, not isolation; a panic would unwind through the request handler; and a timeout only fires at await points, so a blocking module ignored `timeout_ms`. Every module call now runs on its own task: a panic is a module failure under `on_error`, and the timeout holds while other runtime workers are free (a module that blocks still occupies a worker until it returns). The per-call cost is one task spawn. Open for M2c: `ServerBuilder::from_env`, so a custom build does not copy `main.rs`, and the semver commitment of publishing `guardian-server` as a library. diff --git a/speckit/features/251-guardian-modules/tasks.md b/speckit/features/251-guardian-modules/tasks.md index 56c062e4..c8491081 100644 --- a/speckit/features/251-guardian-modules/tasks.md +++ b/speckit/features/251-guardian-modules/tasks.md @@ -195,7 +195,7 @@ - [X] T056 [P] Client READMEs for module errors and `moduleRefusal()` / `module_refusal()`: `crates/client/README.md`, `packages/guardian-client/README.md`, `crates/miden-multisig-client/README.md`, `packages/miden-multisig-client/README.md` - [X] T057 Rust and TypeScript parity fixture: one shared JSON fixture of module error bodies under `packages/guardian-client/src/` (or the repo's existing shared fixture location) driving both `crates/client` and `packages/guardian-client` tests, so SC-010 is checked by the same cases - [ ] T058 End-to-end smokes with a catalog: `smoke-test-rust-multisig-sdk` and `smoke-test-ts-multisig-sdk` skills, refusal at creation, push and registration, and `examples/demo` and `examples/web` with and without a catalog (quickstart section 5); and the operator module routes, including `modules:disable` permission errors, through `examples/operator-smoke-web` with the `smoke-test-operator-dashboard` skill -- [ ] T059 Quickstart walk-through against a local node with the filesystem backend and the latency A/B (zero, one in-process, one remote module), results in `speckit/features/251-guardian-modules/research.md` (P0 T033; SC-001, SC-006) +- [ ] T059 (latency A/B done 2026-11-09, see research.md "M2a end to end"; walk-through against a 0.17 local node still open) Quickstart walk-through against a local node with the filesystem backend and the latency A/B (zero, one in-process, one remote module), results in `speckit/features/251-guardian-modules/research.md` (P0 T033; SC-001, SC-006) - [ ] T060 SC-004 run: enable `basic-policy` on all accounts with the official image and the guides only, timed, gaps fixed in `docs/guides/policy-modules/` - [X] T061 Re-check the TLA+ models whose fingerprints the modules work moved (`verify-auth-replay`, `verify-candidate-queue`, `verify-client-sync`, `verify-guardian-switch`, `verify-module-counting`, `verify-multisig-push-gate`, `verify-proposal-lifecycle` under `.agents/skills/`) with each `check.sh`, then `--accept-drift` once the model still mirrors the code - [ ] T062 Validation matrix of `speckit/features/251-guardian-modules/quickstart.md` section 5 (M2a rows) run end to end, including `cargo test -p guardian-server --features postgres` for module stores and proposal storage, and `gen-openapi --check` From 5fae1c90d93353f5655e213ea4789e0517b5802b Mon Sep 17 00:00:00 2001 From: Zeljko Date: Mon, 9 Nov 2026 13:32:58 +0100 Subject: [PATCH 049/105] docs(modules): validation matrix and smoke progress in the M2a tasks (#251) --- speckit/features/251-guardian-modules/tasks.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/speckit/features/251-guardian-modules/tasks.md b/speckit/features/251-guardian-modules/tasks.md index c8491081..4e0da31a 100644 --- a/speckit/features/251-guardian-modules/tasks.md +++ b/speckit/features/251-guardian-modules/tasks.md @@ -194,11 +194,11 @@ - [X] T055 [P] Protocol spec coverage: module error codes and `meta` on proposal creation, push and registration, `GET /policies` and `POST /delta/proposal/check` in `spec/api.md`, and the gate points in the push, proposal and registration processes of `spec/processes.md` - [X] T056 [P] Client READMEs for module errors and `moduleRefusal()` / `module_refusal()`: `crates/client/README.md`, `packages/guardian-client/README.md`, `crates/miden-multisig-client/README.md`, `packages/miden-multisig-client/README.md` - [X] T057 Rust and TypeScript parity fixture: one shared JSON fixture of module error bodies under `packages/guardian-client/src/` (or the repo's existing shared fixture location) driving both `crates/client` and `packages/guardian-client` tests, so SC-010 is checked by the same cases -- [ ] T058 End-to-end smokes with a catalog: `smoke-test-rust-multisig-sdk` and `smoke-test-ts-multisig-sdk` skills, refusal at creation, push and registration, and `examples/demo` and `examples/web` with and without a catalog (quickstart section 5); and the operator module routes, including `modules:disable` permission errors, through `examples/operator-smoke-web` with the `smoke-test-operator-dashboard` skill +- [ ] T058 (operator module routes done 2026-11-09 through `modules_admin`: validation, `$secret` refusal, `modules:disable` allowed and the 403/409/404 paths, history; the SDK, demo/web and browser smokes still open) End-to-end smokes with a catalog: `smoke-test-rust-multisig-sdk` and `smoke-test-ts-multisig-sdk` skills, refusal at creation, push and registration, and `examples/demo` and `examples/web` with and without a catalog (quickstart section 5); and the operator module routes, including `modules:disable` permission errors, through `examples/operator-smoke-web` with the `smoke-test-operator-dashboard` skill - [ ] T059 (latency A/B done 2026-11-09, see research.md "M2a end to end"; walk-through against a 0.17 local node still open) Quickstart walk-through against a local node with the filesystem backend and the latency A/B (zero, one in-process, one remote module), results in `speckit/features/251-guardian-modules/research.md` (P0 T033; SC-001, SC-006) - [ ] T060 SC-004 run: enable `basic-policy` on all accounts with the official image and the guides only, timed, gaps fixed in `docs/guides/policy-modules/` - [X] T061 Re-check the TLA+ models whose fingerprints the modules work moved (`verify-auth-replay`, `verify-candidate-queue`, `verify-client-sync`, `verify-guardian-switch`, `verify-module-counting`, `verify-multisig-push-gate`, `verify-proposal-lifecycle` under `.agents/skills/`) with each `check.sh`, then `--accept-drift` once the model still mirrors the code -- [ ] T062 Validation matrix of `speckit/features/251-guardian-modules/quickstart.md` section 5 (M2a rows) run end to end, including `cargo test -p guardian-server --features postgres` for module stores and proposal storage, and `gen-openapi --check` +- [X] T062 (2026-11-09: checks, OpenAPI, 1,729 server tests with --test-threads 4, 96 Postgres tests, Rust clients, TS 172/118/1001, terraform validate) Validation matrix of `speckit/features/251-guardian-modules/quickstart.md` section 5 (M2a rows) run end to end, including `cargo test -p guardian-server --features postgres` for module stores and proposal storage, and `gen-openapi --check` - [X] T063 Export the `guardian_module_*` metrics: add them to the CloudWatch export allowlist in `infra/observability.tf` (selector groups by label dimensions) and a "Policy modules" section of panels in `docs/guides/observability/grafana/dashboards/guardian.json`, listed in `docs/guides/observability/README.md`; validate with `terraform validate` and the local Prometheus and Grafana stack --- From 950cf15237296c1819e13bb426ee37b3e9bdff5b Mon Sep 17 00:00:00 2001 From: Zeljko Date: Mon, 9 Nov 2026 15:01:21 +0100 Subject: [PATCH 050/105] docs(modules): status of RFC 0002 and the spec after M2a (#251) The RFC, its index entry, the spec and the plan said implementation had not started or that the spec was a draft. They now say M2a is implemented on 251-modules-m2a and not merged, that protocol version 1 is frozen, what review is sought, and which tasks remain open. --- docs/rfcs/0002-guardian-modules.md | 6 +++--- docs/rfcs/README.md | 2 +- speckit/features/251-guardian-modules/plan.md | 4 ++-- speckit/features/251-guardian-modules/spec.md | 6 +++--- 4 files changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/rfcs/0002-guardian-modules.md b/docs/rfcs/0002-guardian-modules.md index 47ca0cf7..f1cbe55a 100644 --- a/docs/rfcs/0002-guardian-modules.md +++ b/docs/rfcs/0002-guardian-modules.md @@ -2,13 +2,13 @@ | | | |---|---| -| **Status** | Accepted for implementation; comments still welcome and can still change it. Implementation (milestone M2a, section 7) has not started | +| **Status** | Accepted. Milestone M2a (section 7) is implemented on branch `251-modules-m2a`, not yet merged to `main`; M2b and M2c have not started. Comments are still welcome; protocol version 1 is frozen, so a change to it is a new capability or a new version (section 3.5) | | **Depends on** | [RFC 0001](./0001-server-side-transaction-execution.md) (server-side transaction execution, merged in PR #510): the execution worker is the second caller of the pipeline | | **Feature** | [#251](https://github.com/OpenZeppelin/guardian/issues/251) ("Modularization: middleware architecture and pluggable modules"); first consumer [#182](https://github.com/OpenZeppelin/guardian/issues/182) (policy evaluation). [#252](https://github.com/OpenZeppelin/guardian/issues/252) (x402 facilitator) is a later consumer: its payment-policy half (caps, allowlists, replay) fits `before_transaction_approved` and `after_transaction_committed`, its facilitator half (`/verify`, `/settle`, a flow that starts and waits) does not fit allow/deny and is future work (section 7) | | **Audience** | Operators, module authors, integrators, and anyone reviewing the Guardian trust model | -| **Working artifacts** | [`speckit/features/251-guardian-modules/`](../../speckit/features/251-guardian-modules/spec.md): the specification, written alongside this RFC; plan and tasks follow the prototype | +| **Working artifacts** | [`speckit/features/251-guardian-modules/`](../../speckit/features/251-guardian-modules/spec.md): the specification, written alongside this RFC; the plan, the M2a tasks (`tasks.md`) and the prototype record (`tasks-p0.md`) | | **Revision** | 30 (2026-11-09): the secrets backend and the catalog's credential field names (section 2.2); changes in Appendix C | -| **Review sought** | Comments on the design and the M2a scope remain open until M2a ships, when `guardian.module.v1` freezes (section 7) | +| **Review sought** | Review of the M2a implementation before it merges; comments on M2b (commit notifications, stateful modules) and M2c (operator-built kinds) | | **Code baseline** | `main` at `ca503704`; execution-path citations read on `254-execution-impl` at `29c722b4` (PR #510, since merged to `main` as `1100f3a4`) and kept as dated evidence. Miden pins: protocol and standards 0.17.1. Appendices B and C cite the baselines of their revisions. Prototype findings (2026-10-13 to 2026-10-15) in `speckit/features/251-guardian-modules/research.md` | --- diff --git a/docs/rfcs/README.md b/docs/rfcs/README.md index 2934fedf..c7e471c3 100644 --- a/docs/rfcs/README.md +++ b/docs/rfcs/README.md @@ -8,7 +8,7 @@ protocol partners, integrators, and anyone reading the repository publicly. | # | Title | Status | Feature | |---|---|---|---| | [0001](./0001-server-side-transaction-execution.md) | Guardian executes, proves and submits transactions | Accepted for implementation | [#254](https://github.com/OpenZeppelin/guardian/issues/254) | -| [0002](./0002-guardian-modules.md) | Guardian modules, a hook pipeline for pluggable policy | Accepted for implementation | [#251](https://github.com/OpenZeppelin/guardian/issues/251) | +| [0002](./0002-guardian-modules.md) | Guardian modules, a hook pipeline for pluggable policy | Accepted; M2a implemented, not merged | [#251](https://github.com/OpenZeppelin/guardian/issues/251) | ## What belongs here diff --git a/speckit/features/251-guardian-modules/plan.md b/speckit/features/251-guardian-modules/plan.md index fa59903b..8b2c371c 100644 --- a/speckit/features/251-guardian-modules/plan.md +++ b/speckit/features/251-guardian-modules/plan.md @@ -1,8 +1,8 @@ # Implementation Plan: Guardian Modules, a Hook Pipeline for Pluggable Policy -**Branch**: M2a on `251-modules-m2a` and its stacked layer branches (see "M2a delivery"); prototype on `251-modules-prototype` (draft PR #554); RFC and speckit merged with PR #544 | **Date**: 2026-10-13, M2a revision 2026-11-09 | **Spec**: [spec.md](./spec.md) +**Branch**: M2a on `251-modules-m2a`, one branch that can be split into the layers of "M2a delivery" for review; prototype on `251-modules-prototype` (draft PR #554); RFC and speckit merged with PR #544 | **Date**: 2026-10-13, M2a revision 2026-11-09 | **Spec**: [spec.md](./spec.md) **Input**: Feature specification from `speckit/features/251-guardian-modules/spec.md`; design source [RFC 0002](../../../docs/rfcs/0002-guardian-modules.md), written against revision 19; M2a follows revision 26 -**Status**: Prototype built (2026-10-13), gates G1 to G5 closed at component level ([research.md](./research.md#prototype-findings-2026-10-13)); RFC revisions 20 (prototype findings) and 21 (layered parameters, decision D11) applied. Still open: the end-to-end walk-through and latency A/B against a local Miden node. M2a implementation started 2026-11-09 against RFC revision 26: [tasks.md](./tasks.md); the prototype record is [tasks-p0.md](./tasks-p0.md). +**Status**: Prototype built (2026-10-13), gates G1 to G5 closed at component level ([research.md](./research.md#prototype-findings-2026-10-13)); RFC revisions 20 (prototype findings) and 21 (layered parameters, decision D11) applied. M2a implemented on `251-modules-m2a` (2026-11-09) against RFC revisions 26 to 30: [tasks.md](./tasks.md), all tasks done except the walk-through against a local node and the manual smokes (T058 to T060); the prototype record is [tasks-p0.md](./tasks-p0.md). The latency A/B is in [research.md](./research.md), "M2a end to end". ## Summary diff --git a/speckit/features/251-guardian-modules/spec.md b/speckit/features/251-guardian-modules/spec.md index 1fbc02ef..d251b649 100644 --- a/speckit/features/251-guardian-modules/spec.md +++ b/speckit/features/251-guardian-modules/spec.md @@ -2,10 +2,10 @@ **Feature Branch**: `251-guardian-modules` **Created**: 2026-10-13 -**Status**: Draft -**Design source**: [RFC 0002](../../../docs/rfcs/0002-guardian-modules.md), written against revision 19; the RFC is now at revision 24. The RFC holds the wire protocol, configuration format and code citations; this spec states what the feature must achieve and how that is verified. Where the two differ, the RFC is corrected first and this spec follows. +**Status**: M2a implemented on `251-modules-m2a` (not merged to `main`); M2b and M2c not started +**Design source**: [RFC 0002](../../../docs/rfcs/0002-guardian-modules.md), written against revision 19; the RFC is now at revision 30. The RFC holds the wire protocol, configuration format and code citations; this spec states what the feature must achieve and how that is verified. Where the two differ, the RFC is corrected first and this spec follows. **Input**: Issue #251 ("Modularization: middleware architecture and pluggable modules"), first consumer #182 (policy evaluation), later consumer #252 (x402 facilitator). -**Planning note**: `plan.md` records the pre-prototype plan and its prototype findings; the gates (account view extraction effort, projection reuse, added latency, module author ergonomics, placement relative to PR #510) and their results are in `research.md`. `tasks-p0.md` holds the P0 prototype tasks and the follow-on phases; `tasks.md` holds the M2a implementation tasks. The quickstart walk-through and an end-to-end run against a local node remain open. +**Planning note**: `plan.md` records the pre-prototype plan and its prototype findings; the gates (account view extraction effort, projection reuse, added latency, module author ergonomics, placement relative to PR #510) and their results are in `research.md`. `tasks-p0.md` holds the P0 prototype tasks and the follow-on phases; `tasks.md` holds the M2a implementation tasks. The M2a latency A/B ran on 2026-11-09 (`research.md`, "M2a end to end"); the quickstart walk-through against a local node of the 0.17 line, the SDK and browser smokes, and the timed run with the official image remain open (`tasks.md` T058 to T060). ## Context *(why this feature exists)* From aaf917b67d24bdd9c52f77403ce7dde27f9e74a4 Mon Sep 17 00:00:00 2001 From: Zeljko Date: Mon, 9 Nov 2026 17:12:01 +0100 Subject: [PATCH 051/105] fix(modules): mark only the fee note pay_fee creates as tx_fee (#251) The projection marked every output note with the standard TX_FEE script as the fee, and basic-policy leaves the fee out of its amount, recipient and asset rules. Any transaction script can create TX_FEE notes with any assets, and anyone can consume them, so a threshold of cosigners could move funds past every rule in such a note. tx_fee is now set only when the note is the transaction's only TX_FEE note, carries the serial number pay_fee derives from the account, the nonce before the transaction and the summary's block, and holds one fungible asset of the chain's fee faucet. The faucet is read once from the node's protocol configuration and cached; until it is known no note is the fee. The view cache keeps each account's nonce with its view. RFC 0002 revision 31. --- .../proto/guardian_module_v1.proto | 2 +- crates/miden-rpc-client/src/lib.rs | 27 ++ crates/server/src/modules/request.rs | 41 +-- crates/server/src/network/miden/mod.rs | 49 +++- .../server/src/network/miden/module_views.rs | 235 ++++++++++++++++-- crates/server/src/network/mod.rs | 29 ++- .../server/src/services/ack_delta_internal.rs | 3 + .../src/services/push_delta_proposal.rs | 3 + crates/server/src/testing/mocks.rs | 4 +- docs/guides/policy-modules/custom.md | 4 +- docs/rfcs/0002-guardian-modules.md | 7 +- .../contracts/guardian_module_v1.proto | 2 +- 12 files changed, 347 insertions(+), 59 deletions(-) diff --git a/crates/guardian-module-sdk/proto/guardian_module_v1.proto b/crates/guardian-module-sdk/proto/guardian_module_v1.proto index 8fdcce9d..d1d374ec 100644 --- a/crates/guardian-module-sdk/proto/guardian_module_v1.proto +++ b/crates/guardian-module-sdk/proto/guardian_module_v1.proto @@ -172,7 +172,7 @@ message OutputNote { repeated Asset assets = 5; string script_root = 6; optional string p2id_target = 7; // set only for known P2ID / P2IDE scripts - bool tx_fee = 8; // the fee note pay_fee creates; not a payment + bool tx_fee = 8; // the fee note pay_fee creates; not a payment (section 3.1: set only for that one note) } enum NoteType { NOTE_TYPE_UNSPECIFIED = 0; NOTE_TYPE_PUBLIC = 1; NOTE_TYPE_PRIVATE = 2; } diff --git a/crates/miden-rpc-client/src/lib.rs b/crates/miden-rpc-client/src/lib.rs index 79b4c2f6..e2fdec58 100644 --- a/crates/miden-rpc-client/src/lib.rs +++ b/crates/miden-rpc-client/src/lib.rs @@ -549,6 +549,33 @@ impl MidenRpcClient { }) } + /// The asset id the chain charges fees in, from the protocol configuration the latest block + /// header commits to, as a hex word. Takes `&self` like [`Self::get_account_commitment`]. + pub async fn get_fee_asset_id(&self, read_mode: RpcReadMode) -> Result { + const OPERATION: &str = "get_fee_asset_id"; + let response = self + .retry_read(OPERATION, read_mode, |mut client| async move { + let request = rpc::GetBlockHeaderByNumberRequest { + block_num: None, + include_mmr_proof: Some(false), + include_protocol_config: Some(true), + }; + client + .get_block_header_by_number(Request::new(request)) + .await + .map(tonic::Response::into_inner) + }) + .await?; + response + .protocol_config + .and_then(|config| config.fee_asset_id) + .and_then(|word| word_to_hex(&word)) + .ok_or_else(|| RpcClientError::MalformedResponse { + operation: OPERATION, + reason: "no fee asset id in the protocol configuration".to_string(), + }) + } + /// One page of the transactions committed against `account_id` in /// `block_from..=block_to`. The node records a header for every /// account, private ones included, never prunes them, and rejects a diff --git a/crates/server/src/modules/request.rs b/crates/server/src/modules/request.rs index 1a0f52d7..e8a728af 100644 --- a/crates/server/src/modules/request.rs +++ b/crates/server/src/modules/request.rs @@ -8,7 +8,7 @@ use guardian_module_sdk::{AccountView, HookRequest, RegistrationSubject, Transac use crate::delta_object::{DeltaObject, DeltaStatus}; use crate::metadata::NetworkConfig; use crate::metadata::auth::Auth; -use crate::network::NetworkClient; +use crate::network::{ModuleAccount, NetworkClient}; #[derive(Debug, Clone, PartialEq)] pub struct ProposalContext { @@ -55,7 +55,7 @@ const VIEW_CACHE_CAPACITY: usize = 4096; #[derive(Default)] pub struct ViewCache { entries: std::sync::Mutex<( - std::collections::HashMap, + std::collections::HashMap, std::collections::VecDeque, )>, } @@ -65,18 +65,18 @@ impl ViewCache { &self, network: &dyn NetworkClient, state: StateRef<'_>, - ) -> Result { + ) -> Result { if let Ok(entries) = self.entries.lock() - && let Some(view) = entries.0.get(state.commitment) + && let Some(account) = entries.0.get(state.commitment) { - return Ok(view.clone()); + return Ok(account.clone()); } - let view = network.module_account_view(state.json)?; - self.insert(state.commitment, view.clone()); - Ok(view) + let account = network.module_account_view(state.json)?; + self.insert(state.commitment, account.clone()); + Ok(account) } - fn insert(&self, commitment: &str, view: AccountView) { + fn insert(&self, commitment: &str, view: ModuleAccount) { if let Ok(mut entries) = self.entries.lock() { let (views, order) = &mut *entries; if views.insert(commitment.to_string(), view).is_none() { @@ -93,7 +93,7 @@ impl ViewCache { /// Keeps `view` for `commitment` when it was built from an account already decoded, so request /// assembly does not decode it again. A failed extraction is not kept: assembly then retries /// it and the failure applies to the modules. - pub fn seed(&self, commitment: &str, view: Result) { + pub fn seed(&self, commitment: &str, view: Result) { if let Ok(view) = view { self.insert(commitment, view); } @@ -126,7 +126,7 @@ fn view( state: StateRef<'_>, auth: &Auth, ) -> Result { - let mut view = views.get_or_build(network, state)?; + let mut view = views.get_or_build(network, state)?.view; if view.default_threshold.is_none() { match auth.cosigner_commitments().as_slice() { [signer] => { @@ -175,7 +175,8 @@ pub fn transaction_request( views: &ViewCache, input: TransactionInput<'_>, ) -> Result { - let transaction = network.module_transaction(input.tx_summary)?; + let initial_nonce = views.get_or_build(network, input.before)?.nonce; + let transaction = network.module_transaction(input.tx_summary, initial_nonce)?; let (proposer, unverified_metadata) = match input.proposal { Some(context) => ( context.proposer, @@ -270,17 +271,17 @@ mod tests { MockNetworkClient::new().with_module_views(view_with("0xfirst"), Default::default()); let cache = ViewCache::default(); assert_eq!( - cache.get_or_build(&network, state("0xc1")).unwrap(), + cache.get_or_build(&network, state("0xc1")).unwrap().view, view_with("0xfirst") ); *network.module_account_view.lock().unwrap() = Some(view_with("0xsecond")); assert_eq!( - cache.get_or_build(&network, state("0xc1")).unwrap(), + cache.get_or_build(&network, state("0xc1")).unwrap().view, view_with("0xfirst"), "same commitment, cached view" ); assert_eq!( - cache.get_or_build(&network, state("0xc2")).unwrap(), + cache.get_or_build(&network, state("0xc2")).unwrap().view, view_with("0xsecond"), "new commitment, fresh decode" ); @@ -392,9 +393,15 @@ mod tests { fn a_seeded_view_is_used_without_decoding_and_a_failed_one_is_not_kept() { let network = MockNetworkClient::new(); let cache = ViewCache::default(); - cache.seed("0xc1", Ok(view_with("0xseeded"))); + cache.seed( + "0xc1", + Ok(ModuleAccount { + view: view_with("0xseeded"), + nonce: 0, + }), + ); assert_eq!( - cache.get_or_build(&network, state("0xc1")).unwrap(), + cache.get_or_build(&network, state("0xc1")).unwrap().view, view_with("0xseeded") ); cache.seed("0xc2", Err("undecodable".into())); diff --git a/crates/server/src/network/miden/mod.rs b/crates/server/src/network/miden/mod.rs index 90243579..e077f4d9 100644 --- a/crates/server/src/network/miden/mod.rs +++ b/crates/server/src/network/miden/mod.rs @@ -33,6 +33,8 @@ use miden_standards::account::auth::AuthGuardedMultisig; /// Miden network client for fetching on-chain account data pub struct MidenNetworkClient { client: MidenRpcClient, + /// The chain's fee faucet, loaded once by [`NetworkClient::load_fee_faucet`]. + fee_faucet: std::sync::OnceLock, } impl MidenNetworkClient { @@ -56,7 +58,10 @@ impl MidenNetworkClient { ) .increment(1); })); - Ok(Self { client }) + Ok(Self { + client, + fee_faucet: std::sync::OnceLock::new(), + }) } /// Builds a client without contacting the network or loading TLS roots, for @@ -68,7 +73,10 @@ impl MidenNetworkClient { pub(crate) fn lazy_for_test(network: NetworkType) -> Self { let client = MidenRpcClient::lazy_unconnected(network.rpc_endpoint()) .expect("lazy client construction is infallible for a valid endpoint"); - Self { client } + Self { + client, + fee_faucet: std::sync::OnceLock::new(), + } } /// True when an on-chain commitment is the empty-word digest the Miden @@ -561,11 +569,11 @@ impl NetworkClient for MidenNetworkClient { if let Some(prev_commitment) = prev_commitment { Self::ensure_prev_commitment(&account, prev_commitment)?; } - let before = module_views::account_view_of(&account); + let before = module_views::module_account_of(&account); let applied = Self::applied_account(Ok(account), &tx_summary)?; let views = crate::network::ModuleViews { before, - after: module_views::account_view_of(&applied), + after: module_views::module_account_of(&applied), }; Ok((Self::applied_state(&applied), views)) } @@ -935,15 +943,34 @@ impl NetworkClient for MidenNetworkClient { fn module_account_view( &self, state_json: &serde_json::Value, - ) -> Result { - module_views::account_view(state_json) + ) -> Result { + module_views::module_account_of(&Account::from_json(state_json)?) } fn module_transaction( &self, tx_summary: &serde_json::Value, + initial_nonce: u64, ) -> Result { - module_views::module_transaction(tx_summary) + module_views::module_transaction(tx_summary, initial_nonce, self.fee_faucet.get().copied()) + } + + async fn load_fee_faucet(&self) -> Result<(), String> { + if self.fee_faucet.get().is_some() { + return Ok(()); + } + let asset_id = self + .client + .get_fee_asset_id(RpcReadMode::Configured) + .await + .map_err(|e| format!("cannot read the chain's fee asset: {e}"))?; + let word = Word::try_from(asset_id.as_str()) + .map_err(|e| format!("fee asset id is not a word: {e}"))?; + let faucet = AssetId::try_from(word) + .map_err(|e| format!("fee asset id does not decode: {e}"))? + .faucet_id(); + let _ = self.fee_faucet.set(faucet); + Ok(()) } async fn should_update_auth( @@ -1577,7 +1604,13 @@ mod tests { let client = MidenRpcClient::connect(endpoint) .await .expect("the scripted node accepts connections"); - (MidenNetworkClient { client }, requests) + ( + MidenNetworkClient { + client, + fee_faucet: std::sync::OnceLock::new(), + }, + requests, + ) } fn history_account_id() -> String { diff --git a/crates/server/src/network/miden/module_views.rs b/crates/server/src/network/miden/module_views.rs index 5384a570..bdbb03a5 100644 --- a/crates/server/src/network/miden/module_views.rs +++ b/crates/server/src/network/miden/module_views.rs @@ -6,14 +6,16 @@ use guardian_module_sdk::{ OutputNote, StorageChange, StorageOp, StorageSlotKind, VaultChange, }; use guardian_shared::{FromJson, SignatureScheme}; +use miden_protocol::Felt; use miden_protocol::Word; +use miden_protocol::account::AccountId; use miden_protocol::account::{Account, StoragePatchOperation, StorageSlotContent}; use miden_protocol::asset::Asset; -use miden_protocol::note::{Note, NoteType as MidenNoteType}; +use miden_protocol::note::{Note, NoteId, NoteType as MidenNoteType}; use miden_protocol::transaction::{RawOutputNote, TransactionSummary}; use miden_protocol::utils::serde::Serializable; use miden_standards::account::auth::AuthGuardedMultisig; -use miden_standards::note::{P2idNoteStorage, P2ideNoteStorage, StandardNote}; +use miden_standards::note::{P2idNoteStorage, P2ideNoteStorage, StandardNote, TxFeeNote}; fn word_hex(word: &Word) -> String { format!("0x{}", hex::encode(word.as_bytes())) @@ -32,6 +34,14 @@ pub fn account_view(state_json: &serde_json::Value) -> Result Result { + Ok(crate::network::ModuleAccount { + view: account_view_of(account)?, + nonce: account.nonce().as_canonical_u64(), + }) +} + /// [`account_view`] of an account already decoded. pub fn account_view_of(account: &Account) -> Result { let storage = account.storage(); @@ -152,7 +162,49 @@ fn p2id_target(note: &Note) -> Option { } } -fn output_note(raw: &RawOutputNote) -> OutputNote { +/// The transaction's fee note: a note with the TX_FEE script is a payment like any other, since +/// any transaction script can create one, with any assets, that anyone can consume. Only the note +/// `pay_fee` creates is the fee, and it is recognised by everything `pay_fee` fixes: it is the +/// only TX_FEE note, its serial number is derived from the account, the nonce the transaction +/// starts from and the block its summary binds, and it carries one fungible asset of the chain's +/// fee faucet. Without a known fee faucet no note qualifies. +fn fee_note( + summary: &TransactionSummary, + initial_nonce: u64, + fee_faucet: Option, +) -> Option { + let fee_faucet = fee_faucet?; + let mut tx_fee_notes = summary.output_notes().iter().filter_map(|raw| match raw { + RawOutputNote::Full(note) + if matches!( + StandardNote::from_script(note.script()), + Some(StandardNote::TX_FEE) + ) => + { + Some(note) + } + _ => None, + }); + let note = tx_fee_notes.next()?; + if tx_fee_notes.next().is_some() { + return None; + } + let serial_number = TxFeeNote::derive_serial_number( + summary.account_delta().id(), + Felt::new_unchecked(initial_nonce), + summary.block_number(), + ); + if note.recipient().serial_num() != serial_number { + return None; + } + let assets: Vec<&Asset> = note.assets().iter().collect(); + match assets.as_slice() { + [asset] if asset.is_fungible() && asset.faucet_id() == fee_faucet => Some(note.id()), + _ => None, + } +} + +fn output_note(raw: &RawOutputNote, fee_note: Option) -> OutputNote { match raw { RawOutputNote::Full(note) => OutputNote { note_id: note.id().to_hex(), @@ -162,10 +214,7 @@ fn output_note(raw: &RawOutputNote) -> OutputNote { assets: note.assets().iter().map(module_asset).collect(), script_root: word_hex(&Word::from(note.script().root())), p2id_target: p2id_target(note), - tx_fee: matches!( - StandardNote::from_script(note.script()), - Some(StandardNote::TX_FEE) - ), + tx_fee: fee_note == Some(note.id()), }, RawOutputNote::Partial(partial) => OutputNote { note_id: partial.id().to_hex(), @@ -192,11 +241,16 @@ fn storage_op(op: StoragePatchOperation) -> i32 { /// rather than unwrapped, so a module never judges a different summary than the one signed. pub fn module_transaction( tx_summary: &serde_json::Value, + initial_nonce: u64, + fee_faucet: Option, ) -> Result { let summary = TransactionSummary::from_json(tx_summary) .map_err(|e| format!("transaction summary does not decode: {e}"))?; Ok(crate::network::ModuleTransaction { - projection: projection_from_summary(&summary)?, + projection: projection_from_summary( + &summary, + fee_note(&summary, initial_nonce, fee_faucet), + )?, raw_tx_summary: summary.to_bytes(), }) } @@ -213,7 +267,10 @@ fn expiration_block(block_number: u32, expiration_delta: u16) -> Result Result { +fn projection_from_summary( + summary: &TransactionSummary, + fee_note: Option, +) -> Result { let delta = summary.account_delta(); let vault = delta.vault(); let vault_changes = vault @@ -271,7 +328,11 @@ fn projection_from_summary(summary: &TransactionSummary) -> Result= 0); for change in &projection.storage_changes { @@ -492,7 +553,7 @@ mod tests { } assert!(!transaction.raw_tx_summary.is_empty()); let wrapped = serde_json::json!({ "tx_summary": delta["delta_payload"].clone() }); - assert!(module_transaction(&wrapped).is_err()); + assert!(module_transaction(&wrapped, 0, None).is_err()); } } @@ -505,8 +566,8 @@ mod tests { let mut payload = signed["delta_payload"].clone(); payload["tx_summary"] = decoy["delta_payload"].clone(); assert_eq!( - module_transaction(&payload).unwrap(), - module_transaction(&signed["delta_payload"]).unwrap() + module_transaction(&payload, 0, None).unwrap(), + module_transaction(&signed["delta_payload"], 0, None).unwrap() ); } @@ -546,12 +607,148 @@ mod tests { ) } + fn dummy_id(byte: u8) -> AccountId { + AccountId::dummy( + [byte; 15], + AccountIdVersion::Version1, + AccountType::Private, + miden_protocol::account::AssetCallbackFlag::Disabled, + ) + } + + const NONCE: u64 = 7; + const BLOCK: u32 = 100; + + fn fee_note_with(serial: Word, assets: Vec) -> RawOutputNote { + let note = TxFeeNote::builder() + .sender(dummy_id(3)) + .serial_number(serial) + .assets(assets) + .build() + .unwrap(); + RawOutputNote::Full(note.into()) + } + + fn canonical_serial() -> Word { + TxFeeNote::derive_serial_number( + dummy_id(3), + Felt::new_unchecked(NONCE), + miden_protocol::block::BlockNumber::from(BLOCK), + ) + } + + fn fungible(faucet: u8, amount: u64) -> Asset { + miden_protocol::asset::FungibleAsset::new(dummy_id(faucet), amount) + .unwrap() + .into() + } + + fn summary_with(notes: Vec) -> TransactionSummary { + use miden_protocol::account::{ + AccountCodePatch, AccountDelta, AccountStoragePatch, AccountVaultDelta, + }; + use miden_protocol::transaction::{InputNotes, RawOutputNotes}; + TransactionSummary::new( + AccountDelta::new( + dummy_id(3), + AccountStoragePatch::default(), + AccountVaultDelta::default(), + AccountCodePatch::new(None), + Felt::new_unchecked(1), + ) + .unwrap(), + InputNotes::new(vec![]).unwrap(), + RawOutputNotes::new(notes).unwrap(), + miden_protocol::block::BlockNumber::from(BLOCK), + Word::default(), + 0, + Default::default(), + ) + } + + fn fee_flags(notes: Vec, fee_faucet: Option) -> Vec { + let summary = summary_with(notes); + projection_from_summary(&summary, fee_note(&summary, NONCE, fee_faucet)) + .unwrap() + .output_notes + .iter() + .map(|note| note.tx_fee) + .collect() + } + + #[test] + fn only_the_note_pay_fee_creates_is_the_fee_note() { + let fee_faucet = Some(dummy_id(9)); + let canonical = || fee_note_with(canonical_serial(), vec![fungible(9, 5)]); + assert_eq!(fee_flags(vec![canonical()], fee_faucet), [true]); + assert_eq!( + fee_flags(vec![canonical()], None), + [false], + "unknown fee faucet" + ); + assert_eq!( + fee_flags( + vec![ + canonical(), + fee_note_with(canonical_serial(), vec![fungible(9, 1_000_000)]) + ], + fee_faucet + ), + [false, false], + "a second note with the same serial number makes neither the fee" + ); + assert_eq!( + fee_flags( + vec![ + fee_note_with(Word::from([1u32, 2, 3, 4]), vec![fungible(9, 5)]), + canonical() + ], + fee_faucet + ), + [false, false], + "an extra TX_FEE note with another serial number" + ); + assert_eq!( + fee_flags( + vec![fee_note_with( + Word::from([1u32, 2, 3, 4]), + vec![fungible(9, 5)] + )], + fee_faucet + ), + [false], + "not the serial number pay_fee derives" + ); + assert_eq!( + fee_flags( + vec![fee_note_with( + canonical_serial(), + vec![fungible(4, 1_000_000)] + )], + fee_faucet + ), + [false], + "an asset of another faucet" + ); + assert_eq!( + fee_flags( + vec![fee_note_with( + canonical_serial(), + vec![fungible(9, 5), fungible(4, 1_000_000)] + )], + fee_faucet + ), + [false], + "more than the fee asset" + ); + } + #[test] fn projection_carries_the_reference_block_and_an_expiration_only_when_one_is_set() { - let expiring = projection_from_summary(&summary(None, 20)).unwrap(); + let expiring = projection_from_summary(&summary(None, 20), None).unwrap(); assert_eq!(expiring.reference_block, 100); assert_eq!(expiring.expiration_block, Some(120)); - let open = projection_from_summary(&summary(None, 0)).unwrap(); + let open = projection_from_summary(&summary(None, 0), None).unwrap(); assert_eq!(open.reference_block, 100); assert_eq!(open.expiration_block, None); } @@ -560,13 +757,13 @@ mod tests { fn a_code_replacement_names_the_new_code_commitment() { let code = AccountCode::mock(); assert_eq!( - projection_from_summary(&summary(Some(code.clone()), 0)) + projection_from_summary(&summary(Some(code.clone()), 0), None) .unwrap() .new_code_commitment, Some(word_hex(&code.commitment())) ); assert_eq!( - projection_from_summary(&summary(None, 0)) + projection_from_summary(&summary(None, 0), None) .unwrap() .new_code_commitment, None @@ -588,7 +785,7 @@ mod tests { let view = started.elapsed() / runs; let started = std::time::Instant::now(); for _ in 0..runs { - module_transaction(&delta["delta_payload"]).unwrap(); + module_transaction(&delta["delta_payload"], 0, None).unwrap(); } let projection = started.elapsed() / runs; println!("account_view: {view:?} per call, tx_projection: {projection:?} per call"); diff --git a/crates/server/src/network/mod.rs b/crates/server/src/network/mod.rs index 3a5a937c..a3948873 100644 --- a/crates/server/src/network/mod.rs +++ b/crates/server/src/network/mod.rs @@ -274,11 +274,19 @@ pub struct TransactionSearch { /// plus the commitment, nonce, and auth bindings of the account it encodes, /// read off the account the method already holds so a caller persisting or /// inspecting the state never decodes the blob again (issue #328). +/// An account as policy modules see it, with its nonce: the fee note a transaction creates +/// derives its serial number from the nonce of the state it starts from. +#[derive(Debug, Clone, PartialEq)] +pub struct ModuleAccount { + pub view: guardian_module_sdk::AccountView, + pub nonce: u64, +} + /// Policy module account views of a delta's base state and of the state it produces. #[derive(Debug, Clone)] pub struct ModuleViews { - pub before: Result, - pub after: Result, + pub before: Result, + pub after: Result, } #[derive(Debug, Clone, PartialEq)] @@ -554,24 +562,29 @@ pub trait NetworkClient: Send + Sync { /// The account's signers and thresholds as policy modules see them. Errors on auth state /// this network cannot interpret; an empty view is never returned. - fn module_account_view( - &self, - state_json: &serde_json::Value, - ) -> Result { + fn module_account_view(&self, state_json: &serde_json::Value) -> Result { let _ = state_json; Err("policy modules are not supported on this network".into()) } /// The decoded effects of a transaction as policy modules see them. `tx_summary` is the - /// bare summary the Guardian verifies and signs, never a proposal wrapper. + /// bare summary the Guardian verifies and signs, never a proposal wrapper; `initial_nonce` + /// is the nonce of the state it starts from, which identifies its fee note. fn module_transaction( &self, tx_summary: &serde_json::Value, + initial_nonce: u64, ) -> Result { - let _ = tx_summary; + let _ = (tx_summary, initial_nonce); Err("policy modules are not supported on this network".into()) } + /// Loads the chain's fee faucet once, so module projections can tell the transaction's fee + /// note from a payment. Until it is loaded no note is treated as the fee note. + async fn load_fee_faucet(&self) -> Result<(), String> { + Ok(()) + } + /// Determine if account auth should be updated given the state async fn should_update_auth( &self, diff --git a/crates/server/src/services/ack_delta_internal.rs b/crates/server/src/services/ack_delta_internal.rs index f7f48136..b8b4cd3a 100644 --- a/crates/server/src/services/ack_delta_internal.rs +++ b/crates/server/src/services/ack_delta_internal.rs @@ -184,6 +184,9 @@ async fn approve( .and_then(|context| context.as_ref()) .map(|context| context.proposer.clone()) .unwrap_or_default(); + if let Err(error) = state.network_client.load_fee_faucet().await { + tracing::warn!(%error, "Fee faucet unknown; no output note is treated as the fee note"); + } let signed_at = state.clock.now(); let views = plan.views(); if let Some(module_views) = module_views { diff --git a/crates/server/src/services/push_delta_proposal.rs b/crates/server/src/services/push_delta_proposal.rs index b8d93abe..6ed7b8a6 100644 --- a/crates/server/src/services/push_delta_proposal.rs +++ b/crates/server/src/services/push_delta_proposal.rs @@ -399,6 +399,9 @@ async fn propose(state: &AppState, params: PushDeltaProposalParams, mode: Mode) tracing::Span::current().record("signer_count", cosigner_sigs.len()); if let Some((after, module_views)) = applied { + if let Err(error) = state.network_client.load_fee_faucet().await { + tracing::warn!(%error, "Fee faucet unknown; no output note is treated as the fee note"); + } let proposal = ProposalContext { proposer: proposer_id.clone(), metadata: delta_payload diff --git a/crates/server/src/testing/mocks.rs b/crates/server/src/testing/mocks.rs index a259be53..c9498df6 100644 --- a/crates/server/src/testing/mocks.rs +++ b/crates/server/src/testing/mocks.rs @@ -245,19 +245,21 @@ impl NetworkClient for MockNetworkClient { fn module_account_view( &self, _state_json: &serde_json::Value, - ) -> StdResult { + ) -> StdResult { self.module_decodes .fetch_add(1, std::sync::atomic::Ordering::SeqCst); self.module_account_view .lock() .unwrap() .clone() + .map(|view| crate::network::ModuleAccount { view, nonce: 0 }) .ok_or_else(|| "no module account view configured".to_string()) } fn module_transaction( &self, tx_summary: &serde_json::Value, + _initial_nonce: u64, ) -> StdResult { self.module_decodes .fetch_add(1, std::sync::atomic::Ordering::SeqCst); diff --git a/docs/guides/policy-modules/custom.md b/docs/guides/policy-modules/custom.md index 02aab75f..7de4940b 100644 --- a/docs/guides/policy-modules/custom.md +++ b/docs/guides/policy-modules/custom.md @@ -130,7 +130,9 @@ The Miden projection has the `nonce_delta`, the `reference_block` and optional `tx_fee`), `input_notes`, `storage_changes` by slot name, and `new_code_commitment` when the transaction replaces the account's code. Amounts are decimal strings. Skip the fee note (`tx_fee = true`) when counting -payments: every transaction pays its fee through an output note. +payments: every transaction pays its fee through an output note. The Guardian +sets `tx_fee` only on the one note the fee payment creates, never on another +note that merely uses the fee script, so treat every other note as a payment. Projections are tagged by network (`TransactionProjection`, `oneof network`). Miden is the only network today; read it with `subject.miden()` and return a diff --git a/docs/rfcs/0002-guardian-modules.md b/docs/rfcs/0002-guardian-modules.md index f1cbe55a..ede16cc5 100644 --- a/docs/rfcs/0002-guardian-modules.md +++ b/docs/rfcs/0002-guardian-modules.md @@ -7,7 +7,7 @@ | **Feature** | [#251](https://github.com/OpenZeppelin/guardian/issues/251) ("Modularization: middleware architecture and pluggable modules"); first consumer [#182](https://github.com/OpenZeppelin/guardian/issues/182) (policy evaluation). [#252](https://github.com/OpenZeppelin/guardian/issues/252) (x402 facilitator) is a later consumer: its payment-policy half (caps, allowlists, replay) fits `before_transaction_approved` and `after_transaction_committed`, its facilitator half (`/verify`, `/settle`, a flow that starts and waits) does not fit allow/deny and is future work (section 7) | | **Audience** | Operators, module authors, integrators, and anyone reviewing the Guardian trust model | | **Working artifacts** | [`speckit/features/251-guardian-modules/`](../../speckit/features/251-guardian-modules/spec.md): the specification, written alongside this RFC; the plan, the M2a tasks (`tasks.md`) and the prototype record (`tasks-p0.md`) | -| **Revision** | 30 (2026-11-09): the secrets backend and the catalog's credential field names (section 2.2); changes in Appendix C | +| **Revision** | 31 (2026-11-09): `tx_fee` marks only the fee note `pay_fee` creates (section 3.1); changes in Appendix C | | **Review sought** | Review of the M2a implementation before it merges; comments on M2b (commit notifications, stateful modules) and M2c (operator-built kinds) | | **Code baseline** | `main` at `ca503704`; execution-path citations read on `254-execution-impl` at `29c722b4` (PR #510, since merged to `main` as `1100f3a4`) and kept as dated evidence. Miden pins: protocol and standards 0.17.1. Appendices B and C cite the baselines of their revisions. Prototype findings (2026-10-13 to 2026-10-15) in `speckit/features/251-guardian-modules/research.md` | @@ -721,7 +721,7 @@ message OutputNote { repeated Asset assets = 5; string script_root = 6; optional string p2id_target = 7; // set only for known P2ID / P2IDE scripts - bool tx_fee = 8; // the fee note pay_fee creates; not a payment + bool tx_fee = 8; // the fee note pay_fee creates; not a payment (section 3.1: set only for that one note) } enum NoteType { NOTE_TYPE_UNSPECIFIED = 0; NOTE_TYPE_PUBLIC = 1; NOTE_TYPE_PRIVATE = 2; } @@ -797,7 +797,7 @@ message Gap { `p2id_target` is set only when the note script root is a known P2ID or P2IDE script. Recipient-based policies are enforceable because `TransactionSummary.output_notes` is a collection of `RawOutputNote::Full(Note) | Partial(PartialNote)` (`miden-protocol-0.17.1/src/transaction/tx_summary.rs:31-39`, `outputs/notes.rs:190`) **[READ]**: a full note carries recipient, assets and script even when its type is private. A partial note exposes only the recipient digest, so it is marked `partial = true` and a recipient policy must decide what to do with an unknown recipient. -**The fee is a note.** In Miden 0.17 `pay_fee` creates a public `TX_FEE` output note funded from the account's vault (`miden-standards-0.17.1/src/account/auth/singlesig.rs:45`) **[READ]**. Listed as an ordinary note, the fee looks like a payment: in the prototype a cap on the fee asset refused every transaction, consuming notes included, and a recipient allowlist would refuse every transaction too, since the fee note has no P2ID recipient. The Guardian therefore marks it with `OutputNote.tx_fee` (set when the note script is the standard `TX_FEE` script), and policies treat it as the fee, not a payment. +**The fee is a note.** In Miden 0.17 `pay_fee` creates a public `TX_FEE` output note funded from the account's vault (`miden-standards-0.17.1/src/account/auth/singlesig.rs:45`) **[READ]**. Listed as an ordinary note, the fee looks like a payment: in the prototype a cap on the fee asset refused every transaction, consuming notes included, and a recipient allowlist would refuse every transaction too, since the fee note has no P2ID recipient. The Guardian therefore marks it with `OutputNote.tx_fee`, and policies treat it as the fee, not a payment. The script alone does not identify the fee: `TX_FEE` is a standard script that any transaction script can use (`tx_fee::create_output_note` is public), with any assets, and anyone can consume the note, so a note marked by its script would move funds past every recipient, asset and amount rule. `tx_fee` is set only for the note `pay_fee` creates, recognized by everything `pay_fee` fixes: it is the transaction's only `TX_FEE` note, its serial number is `TxFeeNote::derive_serial_number(account, nonce before the transaction, block the summary binds)`, and it carries one fungible asset of the chain's fee faucet, which the Guardian reads once from the node's protocol configuration. Any other `TX_FEE` note, and every `TX_FEE` note when the transaction has more than one or the fee faucet is not known yet, is an ordinary output note. A zero fee creates no fee note. #### `basic-policy` rules @@ -1206,6 +1206,7 @@ None. Questions resolved in earlier revisions are kept below with their answers. | Revision | Date | Changes | |---|---|---| +| 31 | 2026-11-09 | `OutputNote.tx_fee` set only for the fee note `pay_fee` creates (section 3.1): the only `TX_FEE` note, with the derived serial number and one asset of the chain's fee faucet. Revisions 20 to 30 set it for any note with the `TX_FEE` script, which a transaction script can create with any assets, so the flag let funds past every `basic-policy` rule. No wire change; the field's meaning is narrowed | | 30 | 2026-11-09 | the secrets backend named: `GUARDIAN_MODULE_SECRET_PROVIDER` selects AWS Secrets Manager (the prod default) or owner-only files below `GUARDIAN_MODULE_SECRET_DIR`, read once when the instances are created; a secret that cannot be read fails creation, with the enabled/disabled rule of section 2.2. Field names fixed as `auth.token_secret`, `tls.client_cert_secret` and `tls.client_key_secret`; a secret name is 1 to 512 characters of letters, digits and `/_+=.@-`, and a `$secret` object has no other key (section 2.2). In-process factories read `$secret` values from `ModuleInstanceConfig::secret`. No protocol change | | 29 | 2026-11-09 | M2a implementation of `scope = default`: the copy is written right after the claim, only into an account with no assignment and no assignment history, under the module state lock, instead of in the claim's transaction on Postgres and before the claim on the filesystem; a crash in between is repaired by the unfinished-claim retry, so both backends follow one rule and no transaction spans the metadata and module stores (section 2.3). No protocol change | | 28 | 2026-11-09 | protocol version 1 frozen: the freeze criteria of section 7 met at `e4efd839` on `251-modules-m2a`, with tests; the proto copies say so. No design change | diff --git a/speckit/features/251-guardian-modules/contracts/guardian_module_v1.proto b/speckit/features/251-guardian-modules/contracts/guardian_module_v1.proto index 8fdcce9d..d1d374ec 100644 --- a/speckit/features/251-guardian-modules/contracts/guardian_module_v1.proto +++ b/speckit/features/251-guardian-modules/contracts/guardian_module_v1.proto @@ -172,7 +172,7 @@ message OutputNote { repeated Asset assets = 5; string script_root = 6; optional string p2id_target = 7; // set only for known P2ID / P2IDE scripts - bool tx_fee = 8; // the fee note pay_fee creates; not a payment + bool tx_fee = 8; // the fee note pay_fee creates; not a payment (section 3.1: set only for that one note) } enum NoteType { NOTE_TYPE_UNSPECIFIED = 0; NOTE_TYPE_PUBLIC = 1; NOTE_TYPE_PRIVATE = 2; } From f335840d1b1424756edeb64c63c55fe3700e0366 Mon Sep 17 00:00:00 2001 From: Zeljko Date: Mon, 9 Nov 2026 17:14:43 +0100 Subject: [PATCH 052/105] fix(modules): keep the evaluation trace out of client delta responses (#251) metadata.modules, the record of which module configuration approved a delta and which fail-open instances were skipped, reached clients through every HTTP route that returns a delta or proposal. It names instances a cosigner may not be told about; RFC 0002 section 2.2 keeps it for the dashboard. The HTTP handlers now return deltas without it; the gRPC delta message never carried it. --- crates/server/src/api/http.rs | 18 +++++++----- crates/server/src/delta_object.rs | 39 ++++++++++++++++++++++++++ crates/server/src/delta_summary/mod.rs | 3 +- docs/openapi-client.json | 2 +- docs/openapi.json | 2 +- 5 files changed, 54 insertions(+), 10 deletions(-) diff --git a/crates/server/src/api/http.rs b/crates/server/src/api/http.rs index de766ac7..a1cbb1e2 100644 --- a/crates/server/src/api/http.rs +++ b/crates/server/src/api/http.rs @@ -245,7 +245,7 @@ pub async fn push_delta( }; let response = services::push_delta(&state, params).await?; - Ok(Json(response.delta)) + Ok(Json(response.delta.without_module_trace())) } /// Fetch the delta for an account at a specific nonce. @@ -276,7 +276,7 @@ pub async fn get_delta( }; let response = services::get_delta(&state, params).await?; - Ok(Json(response.delta)) + Ok(Json(response.delta.without_module_trace())) } /// Fetch the merged delta accumulating all changes for an account @@ -308,7 +308,7 @@ pub async fn get_delta_since( }; let response = services::get_delta_since(&state, params).await?; - Ok(Json(response.merged_delta)) + Ok(Json(response.merged_delta.without_module_trace())) } /// Paginated canonical delta history for an account (issue @@ -786,7 +786,7 @@ pub async fn push_delta_proposal( let response = services::push_delta_proposal(&state, params).await?; Ok(Json(DeltaProposalResponse { - delta: response.delta, + delta: response.delta.without_module_trace(), commitment: response.commitment, })) } @@ -1093,7 +1093,11 @@ pub async fn get_delta_proposals( let response = services::get_delta_proposals(&state, params).await?; Ok(Json(ProposalsResponse { - proposals: response.proposals, + proposals: response + .proposals + .into_iter() + .map(DeltaObject::without_module_trace) + .collect(), })) } @@ -1125,7 +1129,7 @@ pub async fn get_delta_proposal( }; let response = services::get_delta_proposal(&state, params).await?; - Ok(Json(response.proposal)) + Ok(Json(response.proposal.without_module_trace())) } /// Add a cosigner signature to an existing multisig proposal. The approval @@ -1164,7 +1168,7 @@ pub async fn sign_delta_proposal( }; let response = services::sign_delta_proposal(&state, params).await?; - Ok(Json(response.delta)) + Ok(Json(response.delta.without_module_trace())) } struct RequestPayloadParts { diff --git a/crates/server/src/delta_object.rs b/crates/server/src/delta_object.rs index b7d095c9..d3ff8b43 100644 --- a/crates/server/src/delta_object.rs +++ b/crates/server/src/delta_object.rs @@ -412,6 +412,16 @@ pub struct DeltaObject { } impl DeltaObject { + /// The delta as a client may see it: the policy module evaluation trace + /// (`metadata.modules`) is for operators only, since it names instances an + /// account's cosigners may not be told about. + pub fn without_module_trace(mut self) -> Self { + if let Some(metadata) = self.metadata.as_mut() { + metadata.modules = None; + } + self + } + /// Return the multisig proposal type tag carried by this delta. /// /// Reads from the typed `metadata.proposal` block when present. @@ -876,6 +886,35 @@ mod tests { assert_eq!(delta.status.timestamp(), ""); } + #[test] + fn clients_get_deltas_without_the_module_trace() { + let delta: DeltaObject = serde_json::from_value(serde_json::json!({ + "account_id": "0x123", + "nonce": 1, + "prev_commitment": "0xabc", + "new_commitment": "0xdef", + "delta_payload": {}, + "ack_sig": null, + "metadata": { + "category": "asset_transfer", + "proposal": { "proposal_type": "p2id" }, + "modules": { + "catalog_hash": "0xc1", + "params_version": 3, + "failed_open": [{ "module_id": "screening", "layer": "global", "failure": "timeout" }], + "signed_at": "2026-11-09T00:00:00Z", + "submitter": "0xs1", + "proposer": "" + } + } + })) + .unwrap(); + assert!(delta.metadata.as_ref().unwrap().modules.is_some()); + let shown = serde_json::to_value(delta.without_module_trace()).unwrap(); + assert!(shown["metadata"].get("modules").is_none(), "{shown}"); + assert_eq!(shown["metadata"]["proposal"]["proposal_type"], "p2id"); + } + #[test] fn test_cosigner_signature() { let sig = CosignerSignature { diff --git a/crates/server/src/delta_summary/mod.rs b/crates/server/src/delta_summary/mod.rs index 1ef79f1e..ec6ddca5 100644 --- a/crates/server/src/delta_summary/mod.rs +++ b/crates/server/src/delta_summary/mod.rs @@ -56,7 +56,8 @@ pub struct DeltaMetadata { #[serde(default, skip_serializing_if = "Option::is_none")] pub proposal: Option, - /// The policy module configuration that approved this delta. Absent when no module ran. + /// The policy module configuration that approved this delta, for operators: absent when no + /// module ran, and never included in client API responses. #[serde(default, skip_serializing_if = "Option::is_none")] pub modules: Option, } diff --git a/docs/openapi-client.json b/docs/openapi-client.json index aa170f56..85601a20 100644 --- a/docs/openapi-client.json +++ b/docs/openapi-client.json @@ -2897,7 +2897,7 @@ }, { "$ref": "#/components/schemas/ModuleApproval", - "description": "The policy module configuration that approved this delta. Absent when no module ran." + "description": "The policy module configuration that approved this delta, for operators: absent when no\nmodule ran, and never included in client API responses." } ] }, diff --git a/docs/openapi.json b/docs/openapi.json index 8f0a55b3..9709b391 100644 --- a/docs/openapi.json +++ b/docs/openapi.json @@ -7705,7 +7705,7 @@ }, { "$ref": "#/components/schemas/ModuleApproval", - "description": "The policy module configuration that approved this delta. Absent when no module ran." + "description": "The policy module configuration that approved this delta, for operators: absent when no\nmodule ran, and never included in client API responses." } ] }, From 6e705b977fa712c3e43148a01d98cf100558a3bf Mon Sep 17 00:00:00 2001 From: Zeljko Date: Mon, 9 Nov 2026 17:25:06 +0100 Subject: [PATCH 053/105] fix(modules): unavailable refusals name no instance whose denials are generic (#251) GUARDIAN_MODULE_UNAVAILABLE and GUARDIAN_EXECUTION_MODULE_UNAVAILABLE always carried the failing instance's id. A cosigner could make the request assembly fail with one dry-run check and learn that a hidden screening instance applies to the account, which a generic denial and the catalog-wide complete flag were meant to hide. module is now absent for an instance with client_reason = generic, as for its denials; the server log still names it. Both SDKs read the module as optional, the shared refusal fixture covers the unnamed case, and the docs follow. --- crates/client/README.md | 3 +- crates/client/src/error.rs | 9 +- crates/miden-multisig-client/README.md | 3 +- crates/miden-multisig-client/src/error.rs | 7 +- crates/server/src/error.rs | 14 +- crates/server/src/modules/admin.rs | 2 +- crates/server/src/modules/pipeline.rs | 26 +++- .../src/services/execute_proposal/tests.rs | 2 +- crates/server/src/services/push_delta.rs | 2 +- crates/shared/src/execution.rs | 35 +++-- docs/TROUBLESHOOTING.md | 4 +- docs/guides/policy-modules/README.md | 3 +- docs/rfcs/0002-guardian-modules.md | 4 +- docs/runbooks/policy-modules.md | 3 +- fixtures/guardian-client/module-refusals.json | 134 ++++++++++++++---- packages/guardian-client/README.md | 5 +- .../guardian-client/src/execution.test.ts | 6 +- packages/guardian-client/src/execution.ts | 5 +- packages/guardian-client/src/http.test.ts | 5 +- packages/guardian-client/src/http.ts | 4 +- spec/api.md | 5 +- 21 files changed, 204 insertions(+), 77 deletions(-) diff --git a/crates/client/README.md b/crates/client/README.md index 834a7ab0..b99b15a5 100644 --- a/crates/client/README.md +++ b/crates/client/README.md @@ -143,7 +143,8 @@ A refusal is a `ClientError` whose `guardian_code()` is the wire code (for examp it. A request a module refuses fails with a `ClientError` whose `module_refusal()` returns `ModuleRefusal::Denied { module, reason_code, layer, client_message }` (final; a generic denial carries only `policy_denied`) or -`ModuleRefusal::Unavailable { module }` (retryable). A Guardian execution a +`ModuleRefusal::Unavailable { module }` (retryable; `module` is `None` for an +instance with generic denials). A Guardian execution a module refuses ends failed with `ExecutionFailureCode::ModuleDenied(ModuleDenial)` or `ExecutionFailureCode::ModuleUnavailable { module }`, and its proposal is kept: diff --git a/crates/client/src/error.rs b/crates/client/src/error.rs index 9a326acd..d06463c0 100644 --- a/crates/client/src/error.rs +++ b/crates/client/src/error.rs @@ -39,9 +39,8 @@ pub enum ModuleRefusal { /// The module's text for the requester, when the instance allows it. client_message: Option, }, - Unavailable { - module: String, - }, + /// `module` is absent for an instance whose denials are generic. + Unavailable { module: Option }, } /// Errors that can occur when using the GUARDIAN client. @@ -203,7 +202,7 @@ impl ClientError { client_message: field("client_message"), }), MODULE_UNAVAILABLE_CODE => Some(ModuleRefusal::Unavailable { - module: field("module")?, + module: field("module"), }), _ => None, } @@ -317,7 +316,7 @@ mod tests { assert_eq!( err.module_refusal(), Some(ModuleRefusal::Unavailable { - module: "sanctions".into() + module: Some("sanctions".into()) }) ); assert!(err.is_retryable()); diff --git a/crates/miden-multisig-client/README.md b/crates/miden-multisig-client/README.md index 55a9dc98..67bd4d8f 100644 --- a/crates/miden-multisig-client/README.md +++ b/crates/miden-multisig-client/README.md @@ -818,7 +818,8 @@ The answer is advisory: approval still decides, and the Guardian rate limits checks per account and signer. A refusal, from a check, at creation, push or registration, is `MultisigError::ModuleDenied { module, reason_code, layer, client_message }` (final; a generic denial carries only `policy_denied`) or -`MultisigError::ModuleUnavailable { module }` (retryable). A Guardian execution +`MultisigError::ModuleUnavailable { module }` (retryable; `module` is `None` for +an instance with generic denials). A Guardian execution refused by a module ends failed with `ExecutionFailureCode::ModuleDenied` or `ExecutionFailureCode::ModuleUnavailable`, and the proposal is kept. diff --git a/crates/miden-multisig-client/src/error.rs b/crates/miden-multisig-client/src/error.rs index 7bd7b894..a80b72bc 100644 --- a/crates/miden-multisig-client/src/error.rs +++ b/crates/miden-multisig-client/src/error.rs @@ -41,8 +41,9 @@ pub enum MultisigError { }, /// A fail-closed GUARDIAN policy module could not decide. Retryable. - #[error("GUARDIAN policy module {module} is unavailable; try again shortly")] - ModuleUnavailable { module: String }, + /// `module` is absent for an instance whose denials are generic. + #[error("a GUARDIAN policy module is unavailable; try again shortly")] + ModuleUnavailable { module: Option }, /// GUARDIAN refused a Guardian-execution request with a stable code, such as /// `GUARDIAN_PROPOSAL_NOT_READY` or `GUARDIAN_EXECUTION_CONFLICT`. `retryable` is the @@ -553,7 +554,7 @@ mod tests { )); assert!(matches!( unavailable, - MultisigError::ModuleUnavailable { ref module } if module == "sanctions" + MultisigError::ModuleUnavailable { ref module } if module.as_deref() == Some("sanctions") )); } diff --git a/crates/server/src/error.rs b/crates/server/src/error.rs index b2bde04e..d41f099d 100644 --- a/crates/server/src/error.rs +++ b/crates/server/src/error.rs @@ -173,9 +173,10 @@ pub enum GuardianError { /// [`GuardianError::ModuleDenied`], but nothing about which module refused or why. ModuleDeniedGeneric, /// A fail-closed policy module could not decide. Stable code - /// `GUARDIAN_MODULE_UNAVAILABLE`, HTTP 503, gRPC `UNAVAILABLE`, retryable. + /// `GUARDIAN_MODULE_UNAVAILABLE`, HTTP 503, gRPC `UNAVAILABLE`, retryable. `module` is absent + /// for an instance whose denials are generic, so a failure names no more than a denial would. ModuleUnavailable { - module: String, + module: Option, }, /// No policy module instance with this id. Stable code `GUARDIAN_MODULE_NOT_FOUND`, HTTP 404. ModuleNotFound { @@ -822,9 +823,14 @@ impl fmt::Display for GuardianError { GuardianError::ModuleDeniedGeneric => { write!(f, "A policy module denied the request (generic denial)") } - GuardianError::ModuleUnavailable { module } => { + GuardianError::ModuleUnavailable { + module: Some(module), + } => { write!(f, "Policy module '{module}' is unavailable") } + GuardianError::ModuleUnavailable { module: None } => { + write!(f, "A policy module is unavailable") + } GuardianError::ModuleNotFound { module } => { write!(f, "Policy module '{module}' not found") } @@ -1063,7 +1069,7 @@ impl GuardianError { Some(layer.clone()), ), GuardianError::ModuleDeniedGeneric => (None, Some(GENERIC_REASON_CODE.into()), None), - GuardianError::ModuleUnavailable { module } => (Some(module.clone()), None, None), + GuardianError::ModuleUnavailable { module } => (module.clone(), None, None), GuardianError::ModuleNotFound { module } => (Some(module.clone()), None, None), GuardianError::ModuleNotDisableable { module } => (Some(module.clone()), None, None), _ => (None, None, None), diff --git a/crates/server/src/modules/admin.rs b/crates/server/src/modules/admin.rs index 4f2b98ea..4ba2076d 100644 --- a/crates/server/src/modules/admin.rs +++ b/crates/server/src/modules/admin.rs @@ -388,7 +388,7 @@ pub async fn enable( .map_err(|error| { tracing::warn!(module = %module_id, %error, "Module failed its checks; not enabled"); GuardianError::ModuleUnavailable { - module: module_id.to_string(), + module: Some(module_id.to_string()), } })?; if checked.params != params && !instance.config.file_managed_params { diff --git a/crates/server/src/modules/pipeline.rs b/crates/server/src/modules/pipeline.rs index ece786a2..b3240953 100644 --- a/crates/server/src/modules/pipeline.rs +++ b/crates/server/src/modules/pipeline.rs @@ -871,7 +871,10 @@ fn fail( OnError::Deny => { tracing::warn!(module = %instance.config.id, account_id, %failure, "Policy module failed; refusing"); Err(GuardianError::ModuleUnavailable { - module: instance.config.id.clone(), + module: match instance.config.client_reason { + ClientReason::Full => Some(instance.config.id.clone()), + ClientReason::Generic => None, + }, }) } OnError::Allow => { @@ -1040,7 +1043,7 @@ params = {params} )]); assert!(matches!( run(&pipeline).await, - Err(GuardianError::ModuleUnavailable { module }) if module == "slow" + Err(GuardianError::ModuleUnavailable { module }) if module.as_deref() == Some("slow") )); } @@ -1115,7 +1118,7 @@ params = {params} )]); assert!(matches!( run(&pipeline).await, - Err(GuardianError::ModuleUnavailable { module }) if module == "buggy" + Err(GuardianError::ModuleUnavailable { module }) if module.as_deref() == Some("buggy") )); let pipeline = pipeline_with(OnError::Allow, Behaviour::Panic); @@ -1795,10 +1798,25 @@ mod failure_handling_tests { )]); let refused = run(&closed).await.unwrap_err(); assert!( - matches!(&refused, GuardianError::ModuleUnavailable { module } if module == "screening") + matches!(&refused, GuardianError::ModuleUnavailable { module } if module.as_deref() == Some("screening")) ); assert!(refused.retryable()); + let mut hidden = instance( + "screening", + &[HOOK], + OnError::Deny, + StubModule::new(Behaviour::Fail), + ); + hidden.config.client_reason = ClientReason::Generic; + let refused = run(&ModulePipeline::from_instances(vec![hidden])) + .await + .unwrap_err(); + assert!( + matches!(&refused, GuardianError::ModuleUnavailable { module: None }), + "an instance with generic denials is not named when it fails either: {refused:?}" + ); + let open = ModulePipeline::from_instances(vec![instance( "scoring", &[HOOK], diff --git a/crates/server/src/services/execute_proposal/tests.rs b/crates/server/src/services/execute_proposal/tests.rs index 99e0044b..2e16c384 100644 --- a/crates/server/src/services/execute_proposal/tests.rs +++ b/crates/server/src/services/execute_proposal/tests.rs @@ -1300,7 +1300,7 @@ async fn a_failing_fail_closed_module_ends_the_execution_as_unavailable() { assert_eq!( failed_with(&f).await, ExecutionFailureCode::ModuleUnavailable { - module: "caps".into() + module: Some("caps".into()) } ); } diff --git a/crates/server/src/services/push_delta.rs b/crates/server/src/services/push_delta.rs index ede356df..ab728d7b 100644 --- a/crates/server/src/services/push_delta.rs +++ b/crates/server/src/services/push_delta.rs @@ -2424,7 +2424,7 @@ mod tests { push_with_modules_when(module.clone(), lookup_fails, OnError::Deny).await; assert!(matches!( result, - Err(GuardianError::ModuleUnavailable { module }) if module == "caps" + Err(GuardianError::ModuleUnavailable { module }) if module.as_deref() == Some("caps") )); assert_eq!( module.calls(), diff --git a/crates/shared/src/execution.rs b/crates/shared/src/execution.rs index 686e79b8..72a70328 100644 --- a/crates/shared/src/execution.rs +++ b/crates/shared/src/execution.rs @@ -138,8 +138,9 @@ pub enum ExecutionFailureCode { /// A GUARDIAN policy module refused the acknowledgement. The proposal stays stored. ModuleDenied(ModuleDenial), /// A fail-closed GUARDIAN policy module could not decide. Requesting again may succeed. + /// `module` is absent for an instance whose denials are generic. ModuleUnavailable { - module: String, + module: Option, }, } @@ -158,6 +159,12 @@ struct ModuleMeta { module: String, } +#[derive(Deserialize)] +struct OptionalModuleMeta { + #[serde(default)] + module: Option, +} + impl ExecutionFailureCode { pub fn as_str(&self) -> &'static str { match self { @@ -247,11 +254,12 @@ impl ExecutionFailureCode { serde_json::to_value(BoundMeta { bound: *bound }) } ExecutionFailureCode::ModuleDenied(denial) => serde_json::to_value(denial), - ExecutionFailureCode::ModuleUnavailable { module } => { - serde_json::to_value(ModuleMeta { - module: module.clone(), - }) - } + ExecutionFailureCode::ModuleUnavailable { + module: Some(module), + } => serde_json::to_value(ModuleMeta { + module: module.clone(), + }), + ExecutionFailureCode::ModuleUnavailable { module: None } => return None, ExecutionFailureCode::BindingMismatch | ExecutionFailureCode::StateMismatch | ExecutionFailureCode::RequestCodec @@ -330,7 +338,14 @@ impl ExecutionFailureCode { ExecutionFailureCode::ModuleDenied(required::(code, meta)?) } "GUARDIAN_EXECUTION_MODULE_UNAVAILABLE" => ExecutionFailureCode::ModuleUnavailable { - module: required::(code, meta)?.module, + module: match meta { + Some(meta) => { + serde_json::from_value::(meta.clone()) + .map_err(|e| format!("{code} has malformed meta: {e}"))? + .module + } + None => None, + }, }, other => return Err(format!("unknown execution failure code '{other}'")), }) @@ -365,13 +380,15 @@ mod tests { client_message: None, }); let unavailable = ExecutionFailureCode::ModuleUnavailable { - module: "caps".into(), + module: Some("caps".into()), }; assert_eq!( generic.meta(), Some(serde_json::json!({ "reason_code": "policy_denied" })) ); - for code in [full, generic, unavailable] { + let unnamed = ExecutionFailureCode::ModuleUnavailable { module: None }; + assert_eq!(unnamed.meta(), None); + for code in [full, generic, unavailable, unnamed] { assert!(!code.ends_proposal()); assert_eq!( ExecutionFailureCode::from_parts(code.as_str(), code.meta().as_ref()).unwrap(), diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md index 93e5ac1a..ebc0cad0 100644 --- a/docs/TROUBLESHOOTING.md +++ b/docs/TROUBLESHOOTING.md @@ -1044,7 +1044,7 @@ Causes of a `failed` execution, in `error.code`: | `GUARDIAN_EXECUTION_INSUFFICIENT_SIGNATURES` | none | Yes, once more cosigners have signed; the proposal is untouched. | | `GUARDIAN_EXECUTION_SUBMISSION_NOT_PROCESSED` | none | Yes; the node refused the send before processing it (a rate limit that outlasted the client's retries, an authentication or permission refusal, an unimplemented call, or inputs sealed against an encryption key the validator no longer holds), so the transaction cannot land and the proposal is kept. Check the node endpoint and its limits if it repeats. | | `GUARDIAN_EXECUTION_MODULE_DENIED` | `reason_code`, plus `module`, `layer` and `client_message` unless the instance reports generic denials (`reason_code: policy_denied` only) | Not while the policy holds; the proposal is untouched. Only on servers built with policy modules. | -| `GUARDIAN_EXECUTION_MODULE_UNAVAILABLE` | `module` | Yes, once the fail-closed module answers again; the proposal is untouched. | +| `GUARDIAN_EXECUTION_MODULE_UNAVAILABLE` | `module`, unless the instance reports generic denials | Yes, once the fail-closed module answers again; the proposal is untouched. | | `GUARDIAN_EXECUTION_SUBMISSION_REJECTED`, `GUARDIAN_EXECUTION_CANDIDATE_DISCARDED`, `GUARDIAN_EXECUTION_EXPIRED` | none | No; the transaction was sent, and the proposal is gone (`proposal_exists: false`). | `error.message` is a fixed, user-safe sentence for its cause, plus chain facts such as block @@ -1062,7 +1062,7 @@ Only on servers started with a module catalog. See | Code | HTTP | `meta` | First check | |---|---|---|---| | `GUARDIAN_MODULE_DENIED` | 403 (gRPC `PermissionDenied`) | `module`, `reason_code`, `layer` (`global` or `account`), and `client_message` when the module set one; only `reason_code: "policy_denied"` for an instance with `client_reason = "generic"` | A policy refused the request: proposal creation, delta push, account registration or the dry-run check. Not retryable while the policy holds. The server log line `Policy module denied the request` has the module's own `message`. | -| `GUARDIAN_MODULE_UNAVAILABLE` | 503 (gRPC `Unavailable`) | `module` | A fail-closed module timed out, errored, sent an invalid decision, was skipped by an open circuit, or would have received a request over the size cap. Retryable once it answers. On the operator API, enabling an instance that fails its startup checks returns it too. | +| `GUARDIAN_MODULE_UNAVAILABLE` | 503 (gRPC `Unavailable`) | `module`, unless the instance has `client_reason = "generic"` (then the `Policy module failed; refusing` log line names it) | A fail-closed module timed out, errored, sent an invalid decision, was skipped by an open circuit, or would have received a request over the size cap. Retryable once it answers. On the operator API, enabling an instance that fails its startup checks returns it too. | | `GUARDIAN_MODULE_NOT_FOUND` | 404 | `module` | Operator API: no catalog instance with this id. Instances come only from the catalog file. | | `GUARDIAN_MODULE_NOT_DISABLEABLE` | 409 (gRPC `FailedPrecondition`) | `module` | Operator API: the instance's catalog entry has `operator_can_disable = false`. Changing that is a deploy (edit the catalog and restart). | diff --git a/docs/guides/policy-modules/README.md b/docs/guides/policy-modules/README.md index 7d2eb769..01a43850 100644 --- a/docs/guides/policy-modules/README.md +++ b/docs/guides/policy-modules/README.md @@ -52,7 +52,8 @@ operator endpoints and permissions. surface it as a typed refusal (`ClientError::module_refusal`, `GuardianHttpError.moduleRefusal()`). A Guardian execution refused this way ends `failed` with `GUARDIAN_EXECUTION_MODULE_DENIED` (same `meta`) or - `GUARDIAN_EXECUTION_MODULE_UNAVAILABLE` (`meta.module`), and its proposal is + `GUARDIAN_EXECUTION_MODULE_UNAVAILABLE` (`meta.module`, omitted like the + denial's for a generic instance), and its proposal is kept. ## What users see diff --git a/docs/rfcs/0002-guardian-modules.md b/docs/rfcs/0002-guardian-modules.md index ede16cc5..6f9323c2 100644 --- a/docs/rfcs/0002-guardian-modules.md +++ b/docs/rfcs/0002-guardian-modules.md @@ -986,7 +986,7 @@ Both use the `{ code, message, meta }` envelope. | Code | HTTP | gRPC | Retryable | `meta` | |---|---|---|---|---| | `GUARDIAN_MODULE_DENIED` | 403 | `PERMISSION_DENIED` | no | `{ module, reason_code, layer }` | -| `GUARDIAN_MODULE_UNAVAILABLE` | 503 | `UNAVAILABLE` | yes | `{ module }` | +| `GUARDIAN_MODULE_UNAVAILABLE` | 503 | `UNAVAILABLE` | yes | `{ module }`, empty for an instance with `client_reason = "generic"`, so a failure names no more than a denial would | On a deny, `reason_code` must match `[a-z0-9_]{1,64}`; a deny without a conforming code is a protocol error and follows `on_error`. On an allow, `reason_code` is ignored and may be empty, so an allow is never turned into an error by a missing code. The module's free-text `message` is logged but not forwarded to clients: a module may be a third party and should not place arbitrary text in front of end users. `meta.module` is the instance `id` from the catalog, which the operator chooses: an operator who does not want to reveal which vendor screens its traffic names the instance neutrally (for example `compliance-1`), and the vendor's kind name never reaches clients. The Rust and TypeScript SDKs expose both as typed errors with the same retry classification. A denial at `before_proposal_created` uses the same codes on the proposal creation call, and the proposal is not stored; both SDKs surface it from proposal creation with the same typed error, so a proposer sees the refusal before any cosigner signs. On the execution path (PR #510) a denial ends the execution as `failed` with `GUARDIAN_EXECUTION_MODULE_DENIED`, whose `meta` carries the same `{ module, reason_code, layer }` and `client_message` (a generic denial carries only `reason_code: policy_denied`), and module unavailability with `GUARDIAN_EXECUTION_MODULE_UNAVAILABLE` (`meta.module`). Neither deletes the proposal, and nothing is proved or sent. Both multisig SDKs read them as typed failure codes from the execution status. @@ -1206,7 +1206,7 @@ None. Questions resolved in earlier revisions are kept below with their answers. | Revision | Date | Changes | |---|---|---| -| 31 | 2026-11-09 | `OutputNote.tx_fee` set only for the fee note `pay_fee` creates (section 3.1): the only `TX_FEE` note, with the derived serial number and one asset of the chain's fee faucet. Revisions 20 to 30 set it for any note with the `TX_FEE` script, which a transaction script can create with any assets, so the flag let funds past every `basic-policy` rule. No wire change; the field's meaning is narrowed | +| 31 | 2026-11-09 | `GUARDIAN_MODULE_UNAVAILABLE` and `GUARDIAN_EXECUTION_MODULE_UNAVAILABLE` omit `module` for an instance whose denials are generic (section 4.1); `metadata.modules` is kept out of client delta responses (section 2.2). `OutputNote.tx_fee` set only for the fee note `pay_fee` creates (section 3.1): the only `TX_FEE` note, with the derived serial number and one asset of the chain's fee faucet. Revisions 20 to 30 set it for any note with the `TX_FEE` script, which a transaction script can create with any assets, so the flag let funds past every `basic-policy` rule. No wire change; the field's meaning is narrowed | | 30 | 2026-11-09 | the secrets backend named: `GUARDIAN_MODULE_SECRET_PROVIDER` selects AWS Secrets Manager (the prod default) or owner-only files below `GUARDIAN_MODULE_SECRET_DIR`, read once when the instances are created; a secret that cannot be read fails creation, with the enabled/disabled rule of section 2.2. Field names fixed as `auth.token_secret`, `tls.client_cert_secret` and `tls.client_key_secret`; a secret name is 1 to 512 characters of letters, digits and `/_+=.@-`, and a `$secret` object has no other key (section 2.2). In-process factories read `$secret` values from `ModuleInstanceConfig::secret`. No protocol change | | 29 | 2026-11-09 | M2a implementation of `scope = default`: the copy is written right after the claim, only into an account with no assignment and no assignment history, under the module state lock, instead of in the claim's transaction on Postgres and before the claim on the filesystem; a crash in between is repaired by the unfinished-claim retry, so both backends follow one rule and no transaction spans the metadata and module stores (section 2.3). No protocol change | | 28 | 2026-11-09 | protocol version 1 frozen: the freeze criteria of section 7 met at `e4efd839` on `251-modules-m2a`, with tests; the proto copies say so. No design change | diff --git a/docs/runbooks/policy-modules.md b/docs/runbooks/policy-modules.md index 4eccbfe1..f481aad0 100644 --- a/docs/runbooks/policy-modules.md +++ b/docs/runbooks/policy-modules.md @@ -47,7 +47,8 @@ routes are in [`DASHBOARD.md`](../DASHBOARD.md#policy-modules) and in ## A module is down -Symptoms: clients get `503 GUARDIAN_MODULE_UNAVAILABLE` with `meta.module`; +Symptoms: clients get `503 GUARDIAN_MODULE_UNAVAILABLE` with `meta.module` +(no module for an instance with `client_reason = "generic"`; the `warn` log names it); `guardian_module_up{module}` is 0; `Policy module health probe failed` and `Policy module failed; refusing` at `warn`; `guardian_module_circuit_open{module}` is 1 once a replica has seen diff --git a/fixtures/guardian-client/module-refusals.json b/fixtures/guardian-client/module-refusals.json index d992dd16..6c0ac31a 100644 --- a/fixtures/guardian-client/module-refusals.json +++ b/fixtures/guardian-client/module-refusals.json @@ -14,8 +14,12 @@ "client_message": "Ask your treasury admin." } }, - "grpc": { "code": 7 }, - "http": { "status": 403 }, + "grpc": { + "code": 7 + }, + "http": { + "status": 403 + }, "expected": { "retryable": false, "refusal": { @@ -39,8 +43,12 @@ "layer": "account" } }, - "grpc": { "code": 7 }, - "http": { "status": 403 }, + "grpc": { + "code": 7 + }, + "http": { + "status": 403 + }, "expected": { "retryable": false, "refusal": { @@ -57,10 +65,17 @@ "body": { "code": "GUARDIAN_MODULE_DENIED", "message": "A policy refused this request.", - "meta": { "retryable": false, "reason_code": "policy_denied" } + "meta": { + "retryable": false, + "reason_code": "policy_denied" + } + }, + "grpc": { + "code": 7 + }, + "http": { + "status": 403 }, - "grpc": { "code": 7 }, - "http": { "status": 403 }, "expected": { "retryable": false, "refusal": { @@ -82,11 +97,17 @@ "module": "caps", "reason_code": "amount_cap_exceeded", "layer": "global", - "future_field": { "nested": true } + "future_field": { + "nested": true + } } }, - "grpc": { "code": 7 }, - "http": { "status": 403 }, + "grpc": { + "code": 7 + }, + "http": { + "status": 403 + }, "expected": { "retryable": false, "refusal": { @@ -103,13 +124,23 @@ "body": { "code": "GUARDIAN_MODULE_UNAVAILABLE", "message": "A policy check is unavailable right now. Please try again shortly.", - "meta": { "retryable": true, "module": "risk-vendor" } + "meta": { + "retryable": true, + "module": "risk-vendor" + } + }, + "grpc": { + "code": 14 + }, + "http": { + "status": 503 }, - "grpc": { "code": 14 }, - "http": { "status": 503 }, "expected": { "retryable": true, - "refusal": { "kind": "unavailable", "module": "risk-vendor" } + "refusal": { + "kind": "unavailable", + "module": "risk-vendor" + } } }, { @@ -117,44 +148,85 @@ "body": { "code": "GUARDIAN_MODULE_DENIED", "message": "A policy refused this request.", - "meta": { "retryable": false, "module": "caps" } + "meta": { + "retryable": false, + "module": "caps" + } + }, + "grpc": { + "code": 7 + }, + "http": { + "status": 403 }, - "grpc": { "code": 7 }, - "http": { "status": 403 }, - "expected": { "retryable": false, "refusal": null } + "expected": { + "retryable": false, + "refusal": null + } }, { - "name": "unavailable without a module is not a refusal", + "name": "unavailable from an instance with generic denials names no module", "body": { "code": "GUARDIAN_MODULE_UNAVAILABLE", "message": "A policy check is unavailable right now. Please try again shortly.", - "meta": { "retryable": true } + "meta": { + "retryable": true + } + }, + "grpc": { + "code": 14 }, - "grpc": { "code": 14 }, - "http": { "status": 503 }, - "expected": { "retryable": true, "refusal": null } + "http": { + "status": 503 + }, + "expected": { + "retryable": true, + "refusal": { + "kind": "unavailable", + "module": null + } + } }, { "name": "an operator module error is not a refusal", "body": { "code": "GUARDIAN_MODULE_NOT_FOUND", "message": "That policy module doesn't exist.", - "meta": { "retryable": false, "module": "caps" } + "meta": { + "retryable": false, + "module": "caps" + } }, - "grpc": { "code": 5 }, - "http": { "status": 404 }, - "expected": { "retryable": false, "refusal": null } + "grpc": { + "code": 5 + }, + "http": { + "status": 404 + }, + "expected": { + "retryable": false, + "refusal": null + } }, { "name": "another error is not a refusal", "body": { "code": "pending_proposals_limit", "message": "This account has too many pending proposals.", - "meta": { "retryable": false } + "meta": { + "retryable": false + } + }, + "grpc": { + "code": 9 + }, + "http": { + "status": 409 }, - "grpc": { "code": 9 }, - "http": { "status": 409 }, - "expected": { "retryable": false, "refusal": null } + "expected": { + "retryable": false, + "refusal": null + } } ] } diff --git a/packages/guardian-client/README.md b/packages/guardian-client/README.md index 0c305be7..0e9b473a 100644 --- a/packages/guardian-client/README.md +++ b/packages/guardian-client/README.md @@ -393,12 +393,13 @@ try { A request a policy module refuses is a `GuardianHttpError` whose `moduleRefusal()` returns `{ kind: 'denied', module, reasonCode, layer, clientMessage }` (final; a generic denial has only `reasonCode: -'policy_denied'`) or `{ kind: 'unavailable', module }` (retryable), and `null` +'policy_denied'`) or `{ kind: 'unavailable', module }` (retryable; `module` is +`null` for an instance with generic denials), and `null` for any other error. `getPolicies(accountId)` lists the rules the Guardian discloses, and `checkDeltaProposal(request)` runs the policy modules on a proposal without storing it. A Guardian execution a module refuses ends `failed` with `error.code` `GUARDIAN_EXECUTION_MODULE_DENIED` (the same `meta` -as a denial) or `GUARDIAN_EXECUTION_MODULE_UNAVAILABLE` (`meta.module`), and +as a denial) or `GUARDIAN_EXECUTION_MODULE_UNAVAILABLE` (`meta.module` when given), and its proposal is kept. ### Rate limits and retries diff --git a/packages/guardian-client/src/execution.test.ts b/packages/guardian-client/src/execution.test.ts index b0bc5371..2235f340 100644 --- a/packages/guardian-client/src/execution.test.ts +++ b/packages/guardian-client/src/execution.test.ts @@ -144,7 +144,11 @@ describe('fromServerExecution', () => { failed({ code: 'GUARDIAN_EXECUTION_MODULE_UNAVAILABLE', message: 'down', meta: { module: 'caps' } }) ).toEqual({ code: 'GUARDIAN_EXECUTION_MODULE_UNAVAILABLE', message: 'down', module: 'caps' }); expect(() => failed({ code: 'GUARDIAN_EXECUTION_MODULE_DENIED', message: 'denied' })).toThrow(); - expect(() => failed({ code: 'GUARDIAN_EXECUTION_MODULE_UNAVAILABLE', message: 'down', meta: {} })).toThrow(); + expect(failed({ code: 'GUARDIAN_EXECUTION_MODULE_UNAVAILABLE', message: 'down' })).toEqual({ + code: 'GUARDIAN_EXECUTION_MODULE_UNAVAILABLE', + message: 'down', + module: null, + }); }); it('maps nothing in flight and an absent nonce to null', () => { diff --git a/packages/guardian-client/src/execution.ts b/packages/guardian-client/src/execution.ts index 976f3252..025c962e 100644 --- a/packages/guardian-client/src/execution.ts +++ b/packages/guardian-client/src/execution.ts @@ -105,7 +105,8 @@ export type ExecutionFailure = /** A fail-closed GUARDIAN policy module could not decide; requesting again may succeed. */ code: 'GUARDIAN_EXECUTION_MODULE_UNAVAILABLE'; message: string; - module: string; + /** Absent for an instance whose denials are generic. */ + module: string | null; } | { code: PlainExecutionFailureCode; message: string }; @@ -221,7 +222,7 @@ function fromServerFailure(error: ServerExecutionError): ExecutionFailure { clientMessage: optionalString(meta?.client_message, 'module client message'), }; case 'GUARDIAN_EXECUTION_MODULE_UNAVAILABLE': - return { code, message, module: requiredString(meta?.module, 'unavailable module') }; + return { code, message, module: optionalString(meta?.module, 'unavailable module') }; default: return { code: member(PLAIN_EXECUTION_FAILURE_CODES, code, 'execution failure code'), message }; } diff --git a/packages/guardian-client/src/http.test.ts b/packages/guardian-client/src/http.test.ts index 6af9a2c5..b1c36a7d 100644 --- a/packages/guardian-client/src/http.test.ts +++ b/packages/guardian-client/src/http.test.ts @@ -1795,7 +1795,10 @@ describe('GuardianHttpError', () => { it('reports no refusal for other codes or a refusal missing its required field', () => { expect(refused(403, 'GUARDIAN_MODULE_DENIED', { retryable: false, module: 'caps' }).moduleRefusal()).toBeNull(); - expect(refused(503, 'GUARDIAN_MODULE_UNAVAILABLE', { retryable: true }).moduleRefusal()).toBeNull(); + expect(refused(503, 'GUARDIAN_MODULE_UNAVAILABLE', { retryable: true }).moduleRefusal()).toEqual({ + kind: 'unavailable', + module: null, + }); expect(refused(409, 'GUARDIAN_EXECUTION_CONFLICT', { retryable: false, module: 'caps' }).moduleRefusal()).toBeNull(); expect(new GuardianHttpError(502, 'Bad Gateway', 'upstream exploded').moduleRefusal()).toBeNull(); }); diff --git a/packages/guardian-client/src/http.ts b/packages/guardian-client/src/http.ts index 783a69e1..28858084 100644 --- a/packages/guardian-client/src/http.ts +++ b/packages/guardian-client/src/http.ts @@ -141,7 +141,7 @@ export type ModuleRefusal = layer: string | null; clientMessage: string | null; } - | { kind: 'unavailable'; module: string }; + | { kind: 'unavailable'; module: string | null }; /** Why GUARDIAN refuses to execute a proposal and leaves it to local execution. */ export type LocalExecutionReason = 'switch_guardian'; @@ -326,7 +326,7 @@ export class GuardianHttpError extends Error { clientMessage: meta.clientMessage ?? null, }; case 'module_unavailable': - return meta.module === undefined ? null : { kind: 'unavailable', module: meta.module }; + return { kind: 'unavailable', module: meta.module ?? null }; default: return null; } diff --git a/spec/api.md b/spec/api.md index dd7a19d8..64c10a85 100644 --- a/spec/api.md +++ b/spec/api.md @@ -601,7 +601,7 @@ travels as `meta_json`): (`bound`: `approval`, `transaction`) and `GUARDIAN_EXECUTION_FOREIGN_ACCOUNT_UNAVAILABLE` (`reason`: `private`, `unavailable`); on servers with policy modules, `GUARDIAN_EXECUTION_MODULE_DENIED` (`reason_code`, and `module`, `layer`, `client_message` unless - the denial is generic) and `GUARDIAN_EXECUTION_MODULE_UNAVAILABLE` (`module`). The full list is in + the denial is generic) and `GUARDIAN_EXECUTION_MODULE_UNAVAILABLE` (`module`, absent when the instance's denials are generic). The full list is in [`docs/TROUBLESHOOTING.md`](../docs/TROUBLESHOOTING.md#guardian-execution). - `delta_nonce` is set once the execution committed to its candidate delta. - `newly_accepted` separates the request that started the execution from a repeat that found @@ -893,7 +893,8 @@ Stable error codes include: gRPC `PermissionDenied`; `meta.module`, `meta.reason_code`, `meta.layer` = `global` or `account`, and `meta.client_message` when the module set one; an instance with `client_reason = "generic"` sends only `meta.reason_code = "policy_denied"`) and - `GUARDIAN_MODULE_UNAVAILABLE` (HTTP 503 / gRPC `Unavailable`, `meta.module`, retryable: a + `GUARDIAN_MODULE_UNAVAILABLE` (HTTP 503 / gRPC `Unavailable`, `meta.module` unless the + instance's denials are generic, retryable: a fail-closed module could not decide). Both are returned by `POST /configure` (hook `before_account_registered`), `POST /delta/proposal` and `POST /delta/proposal/check` (`before_proposal_created`, and in the check also `before_transaction_approved`) and From ca944aef7baf4f80f7fd1b7c3a8fbc1d9f9f7a50 Mon Sep 17 00:00:00 2001 From: Zeljko Date: Mon, 9 Nov 2026 17:45:54 +0100 Subject: [PATCH 054/105] fix(modules): sign the proposal check apart from proposal creation (#251) A wallet signature binds the payload but not the route, and the dry-run check takes proposal creation's body, so a wallet-signed check was also a valid POST /delta/proposal: someone on the network path could turn a cosigner's check into a real proposal. The check's payload is now tagged guardian.CheckDeltaProposal on both transports and in both clients, as ExecuteDeltaProposal already was. --- crates/client/src/client.rs | 9 ++- crates/server/src/api/grpc.rs | 2 +- crates/server/src/api/http.rs | 7 +- .../src/testing/integration/session_http.rs | 73 +++++++++++++++++-- crates/shared/src/auth_request_payload.rs | 3 + .../guardian-client/src/auth-request.test.ts | 10 +++ packages/guardian-client/src/auth-request.ts | 4 +- packages/guardian-client/src/http.ts | 2 +- spec/api.md | 1 + 9 files changed, 99 insertions(+), 12 deletions(-) diff --git a/crates/client/src/client.rs b/crates/client/src/client.rs index d5727a4d..af8a3bd7 100644 --- a/crates/client/src/client.rs +++ b/crates/client/src/client.rs @@ -1075,11 +1075,16 @@ impl GuardianClient { nonce, delta_payload: serde_json::to_string(&delta_payload)?, }; + let payload = AuthRequestPayload::for_operation( + SignedOperation::CheckDeltaProposal, + &prost::Message::encode_to_vec(&message), + ); let inner = self - .send_allowing_session( + .send_with_replay_retry_as( account_id, - SessionOperation::CheckDeltaProposal, message, + payload, + AuthMode::Session(SessionOperation::CheckDeltaProposal), async |client, request| client.check_delta_proposal(request).await, ) .await?; diff --git a/crates/server/src/api/grpc.rs b/crates/server/src/api/grpc.rs index b79313ac..cf4b9776 100644 --- a/crates/server/src/api/grpc.rs +++ b/crates/server/src/api/grpc.rs @@ -311,7 +311,7 @@ impl Guardian for GuardianService { &self, request: Request, ) -> Result, Status> { - let credentials = authenticated_request(&request)?; + let credentials = authenticated_operation(&request, SignedOperation::CheckDeltaProposal)?; let data = request.into_inner(); let params = services::PushDeltaProposalParams { account_id: data.account_id, diff --git a/crates/server/src/api/http.rs b/crates/server/src/api/http.rs index a1cbb1e2..e7a99ea4 100644 --- a/crates/server/src/api/http.rs +++ b/crates/server/src/api/http.rs @@ -818,8 +818,11 @@ pub async fn check_delta_proposal( AuthHeader(credentials): AuthHeader, Json(payload): Json, ) -> Result, GuardianError> { - let request_payload = - request_payload_from_serializable(&payload).map_err(GuardianError::InvalidInput)?; + let request_payload = request_payload_for_operation( + &payload, + guardian_shared::auth_request_payload::SignedOperation::CheckDeltaProposal, + ) + .map_err(GuardianError::InvalidInput)?; let params = PushDeltaProposalParams { account_id: payload.account_id, nonce: payload.nonce, diff --git a/crates/server/src/testing/integration/session_http.rs b/crates/server/src/testing/integration/session_http.rs index 1c435b6b..5a3fb0db 100644 --- a/crates/server/src/testing/integration/session_http.rs +++ b/crates/server/src/testing/integration/session_http.rs @@ -852,10 +852,18 @@ async fn test_a_proposal_check_is_bound_to_its_own_operation_and_admitted_once() let session_key = falcon_session(&app, &state, &signer).await; let body = proposal_body(&account_id_hex, &signer); let timestamp = now_ms(); - let message = request_word(&account_id_hex, timestamp, &body); - let signed_for = |operation| { + let creation = request_word(&account_id_hex, timestamp, &body); + let message = AuthRequestMessage::from_account_id_hex( + &account_id_hex, + timestamp, + AuthRequestPayload::for_operation_json_value(SignedOperation::CheckDeltaProposal, &body) + .unwrap(), + ) + .unwrap() + .to_word(); + let signed_for = |operation, word| { session_key.sign_bytes_hex( - &SessionRequestEnvelope::from_request_word(SessionTransport::Http, operation, message) + &SessionRequestEnvelope::from_request_word(SessionTransport::Http, operation, word) .to_bytes(), ) }; @@ -874,7 +882,7 @@ async fn test_a_proposal_check_is_bound_to_its_own_operation_and_admitted_once() let response = send( &app, - check(&signed_for(SessionOperation::PushDeltaProposal)), + check(&signed_for(SessionOperation::PushDeltaProposal, creation)), ) .await; assert_error( @@ -884,7 +892,7 @@ async fn test_a_proposal_check_is_bound_to_its_own_operation_and_admitted_once() "a proposal creation signature on the check", ); - let signature = signed_for(SessionOperation::CheckDeltaProposal); + let signature = signed_for(SessionOperation::CheckDeltaProposal, message); let (status, checked) = send(&app, check(&signature)).await; assert_eq!(status, StatusCode::OK, "its own operation: {checked}"); assert_eq!(checked["allowed"], true, "{checked}"); @@ -898,6 +906,61 @@ async fn test_a_proposal_check_is_bound_to_its_own_operation_and_admitted_once() ); } +/// A wallet signature binds the payload but not the route, so the check's payload is tagged: +/// a wallet-signed check is not a valid proposal creation, nor the reverse. +#[tokio::test] +async fn test_a_wallet_signed_check_cannot_create_a_proposal_or_the_reverse() { + let (app, _state, signer, account_id_hex) = configured_account().await; + let body = proposal_body(&account_id_hex, &signer); + let wallet_post = |path: &str, payload: AuthRequestPayload, timestamp: i64| { + let (signature, _) = + signer.sign_with_timestamp_and_request(&account_id_hex, timestamp, &payload); + Request::builder() + .uri(path) + .method("POST") + .header("content-type", "application/json") + .header("x-pubkey", &signer.pubkey_hex) + .header("x-signature", signature) + .header("x-timestamp", timestamp.to_string()) + .body(Body::from(body.to_string())) + .unwrap() + }; + let as_check = + AuthRequestPayload::for_operation_json_value(SignedOperation::CheckDeltaProposal, &body) + .unwrap(); + let as_creation = AuthRequestPayload::from_json_serializable(&body).unwrap(); + let start = now_ms(); + + let response = send( + &app, + wallet_post("/delta/proposal", as_check.clone(), start), + ) + .await; + assert_error( + &response, + StatusCode::UNAUTHORIZED, + "authentication_failed", + "a check signature on proposal creation", + ); + let response = send( + &app, + wallet_post("/delta/proposal/check", as_creation, start + 1), + ) + .await; + assert_error( + &response, + StatusCode::UNAUTHORIZED, + "authentication_failed", + "a creation signature on the check", + ); + let (status, checked) = send( + &app, + wallet_post("/delta/proposal/check", as_check, start + 2), + ) + .await; + assert_eq!(status, StatusCode::OK, "{checked}"); +} + #[tokio::test] async fn test_proposals_are_created_and_signed_through_a_session() { let (app, state, signer, account_id_hex) = configured_account().await; diff --git a/crates/shared/src/auth_request_payload.rs b/crates/shared/src/auth_request_payload.rs index d188c779..4e7a7615 100644 --- a/crates/shared/src/auth_request_payload.rs +++ b/crates/shared/src/auth_request_payload.rs @@ -10,12 +10,15 @@ use serde_json::Value; #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub enum SignedOperation { ExecuteDeltaProposal, + /// The dry-run proposal check, whose body is proposal creation's. + CheckDeltaProposal, } impl SignedOperation { pub fn tag(&self) -> &'static [u8] { match self { SignedOperation::ExecuteDeltaProposal => b"guardian.ExecuteDeltaProposal\0", + SignedOperation::CheckDeltaProposal => b"guardian.CheckDeltaProposal\0", } } } diff --git a/packages/guardian-client/src/auth-request.test.ts b/packages/guardian-client/src/auth-request.test.ts index 95349230..fb1c10bd 100644 --- a/packages/guardian-client/src/auth-request.test.ts +++ b/packages/guardian-client/src/auth-request.test.ts @@ -20,4 +20,14 @@ describe('RequestAuthPayload', () => { expect(Array.from(plain.toBytes())).toEqual([...json]); expect(tagged.toCanonicalJson()).toBe(plain.toCanonicalJson()); }); + + it('tags the proposal check apart from proposal creation, which shares its body', () => { + const request = { account_id: '0x11', nonce: 1, delta_payload: {} }; + const check = RequestAuthPayload.forOperation('CheckDeltaProposal', request); + const creation = RequestAuthPayload.fromRequest(request); + + const tag = new TextEncoder().encode('guardian.CheckDeltaProposal'); + expect(Array.from(check.toBytes()).slice(0, tag.length + 1)).toEqual([...tag, 0]); + expect(Array.from(check.toBytes())).not.toEqual(Array.from(creation.toBytes())); + }); }); diff --git a/packages/guardian-client/src/auth-request.ts b/packages/guardian-client/src/auth-request.ts index 7938071c..e95f165d 100644 --- a/packages/guardian-client/src/auth-request.ts +++ b/packages/guardian-client/src/auth-request.ts @@ -11,12 +11,14 @@ type JsonValue = * signature over one never authenticates another request with the same body. Mirrors the Rust * `SignedOperation`. */ -export type SignedOperation = 'ExecuteDeltaProposal'; +export type SignedOperation = 'ExecuteDeltaProposal' | 'CheckDeltaProposal'; function operationTag(operation: SignedOperation): string { switch (operation) { case 'ExecuteDeltaProposal': return 'guardian.ExecuteDeltaProposal\0'; + case 'CheckDeltaProposal': + return 'guardian.CheckDeltaProposal\0'; default: { const unreachable: never = operation; throw new Error(`Unknown signed operation: ${JSON.stringify(unreachable)}`); diff --git a/packages/guardian-client/src/http.ts b/packages/guardian-client/src/http.ts index 28858084..4e1a1ec4 100644 --- a/packages/guardian-client/src/http.ts +++ b/packages/guardian-client/src/http.ts @@ -660,7 +660,7 @@ export class GuardianHttpClient { const response = await this.fetchAuthenticated('/delta/proposal/check', { method: 'POST', body: JSON.stringify(serverRequest), - }, request.accountId, serverRequest, SessionOperation.CheckDeltaProposal); + }, request.accountId, RequestAuthPayload.forOperation('CheckDeltaProposal', serverRequest), SessionOperation.CheckDeltaProposal); const server = (await response.json()) as ServerCheckProposalResponse; if (server.allowed !== true) { throw new Error('Invalid proposal check response: a passing check must be allowed'); diff --git a/spec/api.md b/spec/api.md index 64c10a85..bc1d60a3 100644 --- a/spec/api.md +++ b/spec/api.md @@ -84,6 +84,7 @@ - HTTP request payload digest: RPO256 over canonical JSON bytes of the request payload (`body` for `POST`/`PUT`, query object for `GET`). - gRPC request payload digest: RPO256 over protobuf-encoded request bytes. - `ExecuteDeltaProposal` is domain-separated, because its body (`account_id`, `proposal_id`) encodes to the same bytes as a `GetDeltaProposalExecution` read on both transports. Its payload digest is RPO256 over the ASCII tag `guardian.ExecuteDeltaProposal` and one zero byte, followed by the request bytes: the protobuf-encoded request over gRPC, the canonical JSON body over HTTP. No protobuf message begins with that tag, and canonical JSON begins with `{`. A signed status read therefore never authenticates an execute. +- `CheckDeltaProposal` (`POST /delta/proposal/check`) is domain-separated the same way, with the tag `guardian.CheckDeltaProposal`, because it takes proposal creation's body: without the tag a wallet-signed check would also be a valid `POST /delta/proposal`. - Signed message format: `RPO256_hash([account_id_prefix, account_id_suffix, timestamp_ms, payload_hash_0, payload_hash_1, payload_hash_2, payload_hash_3])`. - ECDSA accounts may send `x-auth-format: eip712` with the same three required headers. The signature is over `GuardianRequest(bytes32 requestHash)` in the `EIP712Domain` `{ name: "Guardian Request", version: "1" }`; `requestHash` is the 32-byte little-endian encoding of the signed message above. An absent format header keeps the raw signature behavior. Falcon does not accept EIP-712 request auth. The existing timestamp skew and replay checks apply to both formats. - The typed request message displays a hash, not the decoded HTTP operation or proposal. The client must show the transaction details separately before prompting a hardware wallet. From b10482fb045ae8568beef45392a52fdd0f92a0e5 Mon Sep 17 00:00:00 2001 From: Zeljko Date: Mon, 9 Nov 2026 17:48:35 +0100 Subject: [PATCH 055/105] fix(modules): let operator writes bring an over-budget account back under (#251) Layer and assignment writes were refused whenever the account's modules stayed over the evaluation budget afterwards, even when the write lowered the cost. An account a deploy pushed over the budget (a raised timeout) could not be repaired through the operator API, as RFC 0002 section 4.3 says it should. The check now refuses only a write that would take a hook over the budget beyond what the account already costs there. --- crates/server/src/modules/admin.rs | 55 +++++++++++++++++++++++++-- crates/server/src/modules/pipeline.rs | 43 ++++++++++++++------- docs/CONFIGURATION.md | 2 +- docs/DASHBOARD.md | 8 ++-- docs/rfcs/0002-guardian-modules.md | 4 +- 5 files changed, 88 insertions(+), 24 deletions(-) diff --git a/crates/server/src/modules/admin.rs b/crates/server/src/modules/admin.rs index 4ba2076d..a7f884db 100644 --- a/crates/server/src/modules/admin.rs +++ b/crates/server/src/modules/admin.rs @@ -525,11 +525,12 @@ pub async fn set_layer( Some(params) => Some(validated(pipeline, instance, ¶ms).await?), None => None, }; - let mut rows = pipeline + let current = pipeline .store() .account_params(&account_id) .await .map_err(GuardianError::StorageError)?; + let mut rows = current.clone(); rows.retain(|row| !(row.kind == ParamsKind::Layer && row.module_id == module_id)); if let Some(params) = ¶ms { rows.push(proposed_row( @@ -539,7 +540,7 @@ pub async fn set_layer( params, )); } - pipeline.check_budget(&rows)?; + pipeline.check_budget(¤t, &rows)?; pipeline .store() .set_layer( @@ -614,11 +615,12 @@ pub async fn set_assignment( params: validated(pipeline, instance, &assigned.params).await?, }); } - let mut rows = pipeline + let current = pipeline .store() .account_params(&account_id) .await .map_err(GuardianError::StorageError)?; + let mut rows = current.clone(); rows.retain(|row| row.kind == ParamsKind::Layer); rows.extend(to_store.iter().map(|assigned| { proposed_row( @@ -628,7 +630,7 @@ pub async fn set_assignment( &assigned.params, ) })); - pipeline.check_budget(&rows)?; + pipeline.check_budget(¤t, &rows)?; pipeline .store() .set_assignment(&account_id, to_store, &change(state, operator, reason)) @@ -922,6 +924,51 @@ mod tests { ); } + #[tokio::test] + async fn an_account_already_over_the_budget_can_be_brought_back_under_it() { + let mut state = state(); + let optional = || { + vec![Assigned { + module_id: "optional".into(), + params: json!({}), + }] + }; + set_assignment(&state, &operator(), ACCOUNT, optional(), "OP-1", None) + .await + .unwrap(); + let store = state.modules.as_ref().unwrap().store_handle(); + let instances = state.modules.as_ref().unwrap().instances().to_vec(); + state.modules = Some(Arc::new( + ModulePipeline::from_instances_with_store(instances, store).with_limits( + crate::modules::limits::Limits { + budget: std::time::Duration::from_millis(120), + ..Default::default() + }, + ), + )); + + let more = set_layer( + &state, + &operator(), + ACCOUNT, + "blocklist", + Some(json!({ "recipient_denylist": ["0xbbb"] })), + "OP-2", + None, + ) + .await; + assert!( + matches!(&more, Err(GuardianError::InvalidInput(message)) if message.contains("budget")), + "a write that adds cost to an account over the budget: {more:?}" + ); + set_assignment(&state, &operator(), ACCOUNT, optional(), "OP-3", None) + .await + .expect("the same cost is not refused"); + set_assignment(&state, &operator(), ACCOUNT, Vec::new(), "OP-4", None) + .await + .expect("removing the assignment brings the account back under the budget"); + } + #[tokio::test] async fn global_and_account_writes_are_validated_recorded_and_visible() { let state = state(); diff --git a/crates/server/src/modules/pipeline.rs b/crates/server/src/modules/pipeline.rs index b3240953..979c0dd7 100644 --- a/crates/server/src/modules/pipeline.rs +++ b/crates/server/src/modules/pipeline.rs @@ -270,6 +270,17 @@ impl ModulePipeline { /// it, plus every listed instance. Disabled instances count, since enabling needs no further /// check; a row naming an instance the catalog no longer declares costs nothing. pub fn worst_case(&self, rows: &[AccountParamsRow]) -> (HookName, std::time::Duration) { + self.costs(rows) + .into_iter() + .max_by_key(|(_, total)| *total) + .unwrap_or(( + HookName::BeforeTransactionApproved, + std::time::Duration::ZERO, + )) + } + + /// The summed timeouts of the module calls an account with `rows` makes at each gate hook. + fn costs(&self, rows: &[AccountParamsRow]) -> Vec<(HookName, std::time::Duration)> { let calls = |id: &str, kind: ParamsKind| { rows.iter() .filter(|row| row.kind == kind && row.module_id == id) @@ -293,23 +304,27 @@ impl ModulePipeline { .sum(); (hook, total) }) - .max_by_key(|(_, total)| *total) - .unwrap_or(( - HookName::BeforeTransactionApproved, - std::time::Duration::ZERO, - )) + .collect() } /// Refuses an account whose modules, with `rows` stored, could exceed the evaluation budget. - pub fn check_budget(&self, rows: &[AccountParamsRow]) -> Result<(), GuardianError> { - let (hook, total) = self.worst_case(rows); - if total > self.limits.budget { - return Err(GuardianError::InvalidInput(format!( - "the account's modules at {} take up to {} ms, over the evaluation budget of {} ms", - hook.as_str(), - total.as_millis(), - self.limits.budget.as_millis() - ))); + /// Refuses a write that would take the account's modules over the budget at a hook where + /// they are not already at least that far over. A write that keeps or lowers the cost passes, + /// so an account a deploy pushed over the budget can still be brought back under it. + pub fn check_budget( + &self, + current: &[AccountParamsRow], + proposed: &[AccountParamsRow], + ) -> Result<(), GuardianError> { + for ((hook, total), (_, now)) in self.costs(proposed).into_iter().zip(self.costs(current)) { + if total > self.limits.budget && total > now { + return Err(GuardianError::InvalidInput(format!( + "the account's modules at {} would take up to {} ms, over the evaluation budget of {} ms", + hook.as_str(), + total.as_millis(), + self.limits.budget.as_millis() + ))); + } } Ok(()) } diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md index a666334d..5bcfaa7b 100644 --- a/docs/CONFIGURATION.md +++ b/docs/CONFIGURATION.md @@ -410,7 +410,7 @@ modules guide](./guides/policy-modules/README.md). | `GUARDIAN_MODULES_CONFIG` | _unset_ (no modules) | Path of the module catalog (TOML). Read once at startup; it declares every instance and seeds its global params on first start, after which params are managed through the [operator API](./DASHBOARD.md#policy-modules). A relative path resolves against the working directory; a relative `tls.ca_file` in the catalog resolves against the catalog's directory, and `auth.token_secret`, `tls.client_cert_secret`, `tls.client_key_secret` and `$secret` params name secrets read through `GUARDIAN_MODULE_SECRET_PROVIDER`. An enabled instance that fails its startup checks stops startup. In the prod stage remote instances must use TLS (`grpc://`) and set `auth`. | | `GUARDIAN_MODULE_CHECK_RATE_PER_MIN` | `30` | Dry-run proposal checks (`POST /delta/proposal/check`) one signer may make for one account per minute; excess returns `rate_limit_exceeded`. Per replica. A value that is not a positive integer refuses startup. | | `GUARDIAN_MODULES_STATE` | `/modules` | Filesystem builds only: directory of the module state file (`module_state.json`). Postgres builds keep module state in the database. | -| `GUARDIAN_MODULE_EVALUATION_BUDGET_MS` | `1000` | Time spent in module calls for one hook invocation (request assembly is not charged). Each call gets the smaller of its `timeout_ms` and what is left; once spent, later modules count as timed out and their `on_error` applies. In the prod stage startup refuses a catalog whose `all` instances, enabled or not, exceed it at any hook, and a budget not below the execution reservation lease; account assignments and layers that could exceed it are refused at write time. Client and SDK request timeouts must exceed it, or a slow approval arrives after the client retried. | +| `GUARDIAN_MODULE_EVALUATION_BUDGET_MS` | `1000` | Time spent in module calls for one hook invocation (request assembly is not charged). Each call gets the smaller of its `timeout_ms` and what is left; once spent, later modules count as timed out and their `on_error` applies. In the prod stage startup refuses a catalog whose `all` instances, enabled or not, exceed it at any hook, and a budget not below the execution reservation lease; account assignments and layers that would raise an account's cost over it are refused at write time, while writes that keep or lower the cost pass. Client and SDK request timeouts must exceed it, or a slow approval arrives after the client retried. | | `GUARDIAN_MODULE_REQUEST_MAX_BYTES` | `2097152` (2 MiB) | Largest encoded request sent to a module. A larger one is a module failure and is not sent; its `on_error` applies. | | `GUARDIAN_MODULE_BREAKER_FAILURES` | `5` | Consecutive failures (timeouts, transport errors, malformed decisions) that open an instance's circuit breaker on a replica. While open the module is not called and its `on_error` applies at once. A deny is an answer and resets the count. | | `GUARDIAN_MODULE_PROBE_INTERVAL_MS` | `5000` | Interval of the `Describe` health probe of every enabled instance. A successful probe moves an open breaker to half-open, where the next call decides; the result is `guardian_module_up`. | diff --git a/docs/DASHBOARD.md b/docs/DASHBOARD.md index e93b0151..0bf33206 100644 --- a/docs/DASHBOARD.md +++ b/docs/DASHBOARD.md @@ -389,9 +389,11 @@ is assigned. Disabling an instance the catalog does not mark `operator_can_disable` returns `409 GUARDIAN_MODULE_NOT_DISABLEABLE`. Writes are refused with `400 invalid_input` when the params exceed -`GUARDIAN_MODULE_PARAMS_MAX_BYTES`, or when the account's modules could exceed -the evaluation budget afterwards (each `all` instance, again for its layer, -plus each assigned one). `GET /dashboard/modules` reports each instance's +`GUARDIAN_MODULE_PARAMS_MAX_BYTES`, or when they would take the account's modules +over the evaluation budget at a hook where they are not already that far over +(each `all` instance, again for its layer, plus each assigned one). A write that +keeps or lowers the cost always passes, so an account a deploy pushed over the +budget can be brought back under it. `GET /dashboard/modules` reports each instance's `circuit` on the answering replica, `params_drift` against the params seeded from the catalog file, and under `undeclared` the stored instances the catalog no longer declares. An account's entries naming such an instance are marked diff --git a/docs/rfcs/0002-guardian-modules.md b/docs/rfcs/0002-guardian-modules.md index 6f9323c2..123eb594 100644 --- a/docs/rfcs/0002-guardian-modules.md +++ b/docs/rfcs/0002-guardian-modules.md @@ -1014,7 +1014,7 @@ Modules run in sequence, so their timeouts add up, while the execution worker ho - Request assembly (account views and projection) is not module time and is not charged to the budget; it is bounded by the reconstruction task instead (section 3.2). That pool is shared with delta reconstruction, so assembly moved into it competes with pushes under load; M2a measures throughput at concurrency before and after the move. - At runtime each module call gets the smaller of its own `timeout_ms` and the time left in the budget. A call cut short by the budget counts as a timeout, and its `on_error` applies. - At startup in the prod stage, the server refuses to start if, for any hook, the timeouts of the `all` and `default` instances, enabled or not, add up to more than the budget (the set every new account receives, which carries no account layers yet; disabled instances are counted because enabling needs no further check), or if the budget is not below the execution reservation lease. `assigned` instances are not summed at startup: a catalog may declare many optional instances that no account uses together. -- Per account, `PUT /dashboard/accounts/{account_id}/modules` rejects an assignment, and the account-layer `PUT` rejects a layer, whose effective set (`all` instances plus their account layers, which are a second call each, plus the listed ones) exceeds the budget on any hook (section 2.2). These static checks cover new accounts and new assignments only. A later deploy that raises a `timeout_ms`, adds an `all` instance, or brings back an orphaned id can push an account that fit at `PUT` time over budget; nothing re-validates stored assignments then. The runtime budget is the enforcement: once it is spent, later modules count as timed out and their `on_error` applies. At startup the server lists every account whose stored assignment and account layers exceed the budget (log and `guardian_module_over_budget_accounts`) without refusing to start, so a routine deploy cannot become an outage, and operators fix those assignments through the operator API. +- Per account, `PUT /dashboard/accounts/{account_id}/modules` rejects an assignment, and the account-layer `PUT` rejects a layer, whose effective set (`all` instances plus their account layers, which are a second call each, plus the listed ones) exceeds the budget on a hook where the account's current set does not already cost at least as much (section 2.2): a write that keeps or lowers the cost passes, so the operator API can bring back under the budget an account that a deploy raising a timeout pushed over it. These static checks cover new accounts and new assignments only. A later deploy that raises a `timeout_ms`, adds an `all` instance, or brings back an orphaned id can push an account that fit at `PUT` time over budget; nothing re-validates stored assignments then. The runtime budget is the enforcement: once it is spent, later modules count as timed out and their `on_error` applies. At startup the server lists every account whose stored assignment and account layers exceed the budget (log and `guardian_module_over_budget_accounts`) without refusing to start, so a routine deploy cannot become an outage, and operators fix those assignments through the operator API. - SDK request timeouts must exceed the budget; otherwise a slow approval arrives after the client has retried. `docs/CONFIGURATION.md` and both SDK docs state this. ### 4.4 Circuit breaker and health probe @@ -1206,7 +1206,7 @@ None. Questions resolved in earlier revisions are kept below with their answers. | Revision | Date | Changes | |---|---|---| -| 31 | 2026-11-09 | `GUARDIAN_MODULE_UNAVAILABLE` and `GUARDIAN_EXECUTION_MODULE_UNAVAILABLE` omit `module` for an instance whose denials are generic (section 4.1); `metadata.modules` is kept out of client delta responses (section 2.2). `OutputNote.tx_fee` set only for the fee note `pay_fee` creates (section 3.1): the only `TX_FEE` note, with the derived serial number and one asset of the chain's fee faucet. Revisions 20 to 30 set it for any note with the `TX_FEE` script, which a transaction script can create with any assets, so the flag let funds past every `basic-policy` rule. No wire change; the field's meaning is narrowed | +| 31 | 2026-11-09 | the per-account budget check refuses only writes that raise an over-budget cost (section 4.3); `GUARDIAN_MODULE_UNAVAILABLE` and `GUARDIAN_EXECUTION_MODULE_UNAVAILABLE` omit `module` for an instance whose denials are generic (section 4.1); `metadata.modules` is kept out of client delta responses (section 2.2). `OutputNote.tx_fee` set only for the fee note `pay_fee` creates (section 3.1): the only `TX_FEE` note, with the derived serial number and one asset of the chain's fee faucet. Revisions 20 to 30 set it for any note with the `TX_FEE` script, which a transaction script can create with any assets, so the flag let funds past every `basic-policy` rule. No wire change; the field's meaning is narrowed | | 30 | 2026-11-09 | the secrets backend named: `GUARDIAN_MODULE_SECRET_PROVIDER` selects AWS Secrets Manager (the prod default) or owner-only files below `GUARDIAN_MODULE_SECRET_DIR`, read once when the instances are created; a secret that cannot be read fails creation, with the enabled/disabled rule of section 2.2. Field names fixed as `auth.token_secret`, `tls.client_cert_secret` and `tls.client_key_secret`; a secret name is 1 to 512 characters of letters, digits and `/_+=.@-`, and a `$secret` object has no other key (section 2.2). In-process factories read `$secret` values from `ModuleInstanceConfig::secret`. No protocol change | | 29 | 2026-11-09 | M2a implementation of `scope = default`: the copy is written right after the claim, only into an account with no assignment and no assignment history, under the module state lock, instead of in the claim's transaction on Postgres and before the claim on the filesystem; a crash in between is repaired by the unfinished-claim retry, so both backends follow one rule and no transaction spans the metadata and module stores (section 2.3). No protocol change | | 28 | 2026-11-09 | protocol version 1 frozen: the freeze criteria of section 7 met at `e4efd839` on `251-modules-m2a`, with tests; the proto copies say so. No design change | From 72cf815975a70b310c0e22ecfd7aed05604e3ac8 Mon Sep 17 00:00:00 2001 From: Zeljko Date: Mon, 9 Nov 2026 18:10:07 +0100 Subject: [PATCH 056/105] perf(modules): read an evaluation's module state in one call (#251) An evaluation read the params version, the account's rows and the version again, retrying up to three times when a write landed between the reads. Every registration that copies default modules moves the one global version, so under registration load approvals for unrelated accounts could fail after three retries. ModuleStore::snapshot now returns the version, the account's rows and, when the caller's cached version is stale, the instance rows, all as of one version: under the lock on the filesystem store, and on Postgres through one prepared call to the STABLE guardian_module_snapshot function, whose statements share one snapshot. The history endpoint pages in the store (newest first, before and limit, in SQL on Postgres) instead of loading a module's whole history, and the registration lookup of an account's history has an index. The Postgres paths (the function, the paged query, the index) are not run yet: the local database is down. --- .../down.sql | 2 + .../2026-11-09-000001_module_snapshot/up.sql | 57 ++++++++ crates/server/src/modules/admin.rs | 10 +- crates/server/src/modules/pipeline.rs | 62 +++++---- crates/server/src/modules/postgres_store.rs | 122 +++++++++++++++++- crates/server/src/modules/store.rs | 87 ++++++++++--- crates/server/src/modules/testing.rs | 19 ++- 7 files changed, 305 insertions(+), 54 deletions(-) create mode 100644 crates/server/migrations/2026-11-09-000001_module_snapshot/down.sql create mode 100644 crates/server/migrations/2026-11-09-000001_module_snapshot/up.sql diff --git a/crates/server/migrations/2026-11-09-000001_module_snapshot/down.sql b/crates/server/migrations/2026-11-09-000001_module_snapshot/down.sql new file mode 100644 index 00000000..7621baeb --- /dev/null +++ b/crates/server/migrations/2026-11-09-000001_module_snapshot/down.sql @@ -0,0 +1,2 @@ +DROP FUNCTION IF EXISTS guardian_module_snapshot(TEXT, BIGINT); +DROP INDEX IF EXISTS module_params_history_account_idx; diff --git a/crates/server/migrations/2026-11-09-000001_module_snapshot/up.sql b/crates/server/migrations/2026-11-09-000001_module_snapshot/up.sql new file mode 100644 index 00000000..dae9fe1d --- /dev/null +++ b/crates/server/migrations/2026-11-09-000001_module_snapshot/up.sql @@ -0,0 +1,57 @@ +-- Default copies at registration look for an account's history under the module +-- state lock; without this index that lookup scanned the whole history. +CREATE INDEX module_params_history_account_idx + ON module_params_history (account_id) + WHERE account_id IS NOT NULL; + +-- Everything one module evaluation reads, in one call: the params version, the +-- account's layers and assignments and, unless the caller's cached version is +-- current, the instance rows. STABLE, so every statement below sees the snapshot +-- of the calling statement: the rows belong to the returned version without the +-- caller re-reading the version. +CREATE FUNCTION guardian_module_snapshot( + p_account_id TEXT, + p_cached_version BIGINT +) +RETURNS TABLE ( + version BIGINT, + instances JSONB, + account_params JSONB +) +LANGUAGE plpgsql STABLE AS $$ +DECLARE + v_version BIGINT; + v_instances JSONB; + v_account JSONB; +BEGIN + SELECT s.version INTO v_version FROM module_state_version s; + + IF p_cached_version IS DISTINCT FROM v_version THEN + SELECT COALESCE(jsonb_agg(jsonb_build_object( + 'module_id', i.module_id, + 'enabled', i.enabled, + 'global_params', i.global_params, + 'seeded_params', i.seeded_params, + 'updated_at', i.updated_at, + 'updated_by', i.updated_by + ) ORDER BY i.module_id), '[]'::jsonb) + INTO v_instances + FROM module_instances i; + END IF; + + SELECT COALESCE(jsonb_agg(jsonb_build_object( + 'account_id', p.account_id, + 'module_id', p.module_id, + 'kind', p.kind, + 'position', p.position, + 'params', p.params, + 'updated_at', p.updated_at, + 'updated_by', p.updated_by + ) ORDER BY p.position, p.module_id), '[]'::jsonb) + INTO v_account + FROM module_account_params p + WHERE p.account_id = p_account_id; + + RETURN QUERY SELECT v_version, v_instances, v_account; +END; +$$; diff --git a/crates/server/src/modules/admin.rs b/crates/server/src/modules/admin.rs index a7f884db..bff98e89 100644 --- a/crates/server/src/modules/admin.rs +++ b/crates/server/src/modules/admin.rs @@ -352,17 +352,11 @@ pub async fn history( "limit must be between 1 and {HISTORY_PAGE_MAX}" ))); } - let mut entries = pipeline + let entries = pipeline .store() - .history(module_id) + .history(module_id, before, limit) .await .map_err(GuardianError::StorageError)?; - entries.reverse(); - let entries = entries - .into_iter() - .filter(|entry| before.is_none_or(|before| entry.version < before)) - .take(limit) - .collect(); Ok(ParamsHistoryView { module_id: module_id.to_string(), entries, diff --git a/crates/server/src/modules/pipeline.rs b/crates/server/src/modules/pipeline.rs index 979c0dd7..88cb855f 100644 --- a/crates/server/src/modules/pipeline.rs +++ b/crates/server/src/modules/pipeline.rs @@ -52,9 +52,6 @@ pub struct ModulePipeline { assignment_report: std::sync::Mutex<(usize, usize)>, } -/// The `module_instances` rows as of one params version. -const SNAPSHOT_ATTEMPTS: usize = 3; - pub(super) type Rows = Arc>; #[derive(Default)] @@ -471,29 +468,48 @@ impl ModulePipeline { Ok((version, rows)) } - /// The global rows and one account's rows as of a single params version. Every module write - /// moves the version in the same transaction, so an unchanged version across the reads - /// means no write committed between them; otherwise the reads are retried. Without this a - /// request could combine a new global rule with an old account layer, a combination no - /// operator ever configured. + /// The global rows and one account's rows as of a single params version, read in one store + /// call. Without it a request could combine a new global rule with an old account layer, a + /// combination no operator ever configured. The instance rows come from the cache when it + /// holds the version the store reports. pub(super) async fn snapshot( &self, account_id: &str, ) -> Result<(u64, Rows, Vec), GuardianError> { - for _ in 0..SNAPSHOT_ATTEMPTS { - let (version, rows) = self.versioned_rows().await?; - let account_rows = self - .store - .account_params(account_id) - .await - .map_err(Self::store_error)?; - if self.store.version().await.map_err(Self::store_error)? == version { - return Ok((version, rows, account_rows)); + let cached = self + .cache + .read() + .ok() + .and_then(|cache| cache.version.map(|version| (version, cache.rows.clone()))); + let snapshot = self + .store + .snapshot(account_id, cached.as_ref().map(|(version, _)| *version)) + .await + .map_err(Self::store_error)?; + let rows = match (snapshot.instances, cached) { + (Some(instances), _) => { + let rows: Rows = Arc::new( + instances + .into_iter() + .map(|row| (row.module_id, (row.global_params, row.enabled))) + .collect(), + ); + if let Ok(mut cache) = self.cache.write() { + *cache = Cache { + version: Some(snapshot.version), + rows: rows.clone(), + }; + } + rows } - } - Err(Self::store_error( - "module state kept changing while it was read".into(), - )) + (None, Some((_, rows))) => rows, + (None, None) => { + return Err(Self::store_error( + "module store omitted the instance rows without a cached version".into(), + )); + } + }; + Ok((snapshot.version, rows, snapshot.account_params)) } pub(super) fn global_params_in(rows: &Rows, instance: &Instance) -> serde_json::Value { @@ -1281,7 +1297,7 @@ params = { old_name = 5 } store.instances().await.unwrap()[0].global_params, serde_json::json!({ "new_name": 5 }) ); - let last = store.history("migrating").await.unwrap().pop().unwrap(); + let last = store.history("migrating", None, 1).await.unwrap().remove(0); assert_eq!(last.operator, "module:protocol-stub 1"); assert_eq!(last.reason, "params migrated by the module"); assert_eq!(last.previous, serde_json::json!({ "old_name": 7 })); @@ -1435,7 +1451,7 @@ params = { old_name = 1000 } serde_json::json!({ "new_name": 100 }), "the operator's cap of 100 stays" ); - let last = store.history("migrating").await.unwrap().pop().unwrap(); + let last = store.history("migrating", None, 1).await.unwrap().remove(0); assert_eq!( last.operator, "0xracing-operator", "no migration entry after it" diff --git a/crates/server/src/modules/postgres_store.rs b/crates/server/src/modules/postgres_store.rs index c918f7d5..8f342889 100644 --- a/crates/server/src/modules/postgres_store.rs +++ b/crates/server/src/modules/postgres_store.rs @@ -9,8 +9,8 @@ use diesel_async::scoped_futures::ScopedFutureExt; use diesel_async::{AsyncConnection, AsyncPgConnection, RunQueryDsl}; use super::store::{ - AccountParamsRow, Assigned, Change, HistoryEntry, InstanceRow, ModuleStore, ParamsKind, - assignment_changes, + AccountParamsRow, Assigned, Change, HistoryEntry, InstanceRow, ModuleSnapshot, ModuleStore, + ParamsKind, assignment_changes, }; pub struct PgModuleStore { @@ -157,6 +157,15 @@ fn account_params_row(row: AccountParamsSql) -> Result }) } +diesel::define_sql_function! { + /// Typed so the statement is prepared once per connection: one module evaluation is one + /// call (see the migration for what it returns). + fn guardian_module_snapshot( + account_id: Text, + cached_version: Nullable, + ) -> Record<(BigInt, Nullable, Jsonb)>; +} + #[async_trait] impl ModuleStore for PgModuleStore { async fn seed_instance( @@ -410,6 +419,34 @@ impl ModuleStore for PgModuleStore { rows.into_iter().map(account_params_row).collect() } + async fn snapshot( + &self, + account_id: &str, + cached_version: Option, + ) -> Result { + let mut conn = self.conn().await?; + let (version, instances, account_params): ( + i64, + Option, + serde_json::Value, + ) = diesel::select(guardian_module_snapshot( + account_id, + cached_version.map(|version| version as i64), + )) + .get_result(&mut conn) + .await + .map_err(|e| format!("module snapshot: {e}"))?; + Ok(ModuleSnapshot { + version: version as u64, + instances: instances + .map(serde_json::from_value) + .transpose() + .map_err(|e| format!("module snapshot instances: {e}"))?, + account_params: serde_json::from_value(account_params) + .map_err(|e| format!("module snapshot account rows: {e}"))?, + }) + } + async fn all_account_params(&self) -> Result, String> { let mut conn = self.conn().await?; let rows: Vec = diesel::sql_query( @@ -619,13 +656,21 @@ impl ModuleStore for PgModuleStore { } } - async fn history(&self, module_id: &str) -> Result, String> { + async fn history( + &self, + module_id: &str, + before: Option, + limit: usize, + ) -> Result, String> { let mut conn = self.conn().await?; let rows: Vec = diesel::sql_query( "SELECT version, module_id, account_id, previous_params, new_params, operator, reason, \ - changed_at FROM module_params_history WHERE module_id = $1 ORDER BY id", + changed_at FROM module_params_history WHERE module_id = $1 \ + AND ($2::BIGINT IS NULL OR version < $2) ORDER BY version DESC, id DESC LIMIT $3", ) .bind::(module_id) + .bind::, _>(before.map(|before| before as i64)) + .bind::(limit as i64) .load(&mut conn) .await .map_err(|e| format!("module params history: {e}"))?; @@ -670,6 +715,62 @@ mod tests { } } + #[tokio::test] + #[ignore = "requires Postgres; run ./scripts/test-postgres.sh"] + async fn a_snapshot_reads_one_version_and_skips_rows_the_cache_holds() { + let url = test_database_url().await; + let store = PgModuleStore::new(build_postgres_pool_lazy(&url, 2).expect("pool")); + let t0 = "2026-11-09T00:00:00Z"; + let module = format!("caps-{}", rand::random::()); + let account = format!("0xacc{}", rand::random::()); + store + .seed_instance(&module, true, &json!({ "cap": 1000 }), t0) + .await + .unwrap(); + store + .set_layer(&account, &module, Some(json!({ "cap": 100 })), &change(t0)) + .await + .unwrap(); + + let fresh = store.snapshot(&account, None).await.unwrap(); + assert_eq!(fresh.version, store.version().await.unwrap()); + let instances = fresh.instances.expect("no cached version"); + let row = instances + .iter() + .find(|row| row.module_id == module) + .unwrap(); + assert_eq!(row.global_params, json!({ "cap": 1000 })); + assert_eq!(fresh.account_params.len(), 1); + assert_eq!(fresh.account_params[0].params, json!({ "cap": 100 })); + assert_eq!(fresh.account_params[0].kind, ParamsKind::Layer); + + let cached = store.snapshot(&account, Some(fresh.version)).await.unwrap(); + assert!(cached.instances.is_none(), "the cache holds this version"); + assert_eq!(cached.account_params, fresh.account_params); + + store + .set_global(&module, json!({ "cap": 10 }), &change(t0)) + .await + .unwrap(); + let moved = store.snapshot(&account, Some(fresh.version)).await.unwrap(); + assert!(moved.version > fresh.version); + let row = moved + .instances + .expect("a stale cache gets the rows") + .into_iter() + .find(|row| row.module_id == module) + .unwrap(); + assert_eq!(row.global_params, json!({ "cap": 10 })); + assert!( + store + .snapshot("0xnobody", None) + .await + .unwrap() + .account_params + .is_empty() + ); + } + #[tokio::test] #[ignore = "requires Postgres; run ./scripts/test-postgres.sh"] async fn module_tables_round_trip_and_version_moves_with_history() { @@ -743,9 +844,18 @@ mod tests { assert_eq!(rows.len(), 2); assert!(rows.iter().any(|row| row.kind == ParamsKind::Layer)); - let history = other_replica.history(&module).await.unwrap(); + let history = other_replica.history(&module, None, 10).await.unwrap(); assert_eq!(history.len(), 3); - assert_eq!(history[2].account_id.as_deref(), Some(account.as_str())); + assert_eq!(history[0].account_id.as_deref(), Some(account.as_str())); + let older = other_replica + .history(&module, Some(history[0].version), 1) + .await + .unwrap(); + assert_eq!( + older, + vec![history[1].clone()], + "paged below a version, newest first" + ); assert_eq!(other_replica.version().await.unwrap(), start + 4); store diff --git a/crates/server/src/modules/store.rs b/crates/server/src/modules/store.rs index d33fa0b5..227ba096 100644 --- a/crates/server/src/modules/store.rs +++ b/crates/server/src/modules/store.rs @@ -125,6 +125,14 @@ pub trait ModuleStore: Send + Sync { async fn account_params(&self, account_id: &str) -> Result, String>; + /// What one evaluation reads, as of one params version: the account's rows and, unless + /// `cached_version` is that version, the instance rows. + async fn snapshot( + &self, + account_id: &str, + cached_version: Option, + ) -> Result; + /// Every account's rows, ordered by account and position; a startup scan, not a hot path. async fn all_account_params(&self) -> Result, String>; @@ -153,11 +161,25 @@ pub trait ModuleStore: Send + Sync { change: &Change<'_>, ) -> Result; - async fn history(&self, module_id: &str) -> Result, String>; + /// The module's history, newest first: at most `limit` entries below version `before`. + async fn history( + &self, + module_id: &str, + before: Option, + limit: usize, + ) -> Result, String>; async fn version(&self) -> Result; } +/// See [`ModuleStore::snapshot`]. +#[derive(Debug, Clone)] +pub struct ModuleSnapshot { + pub version: u64, + pub instances: Option>, + pub account_params: Vec, +} + #[derive(Debug, Default, Clone)] struct Tables { instances: BTreeMap, @@ -170,6 +192,17 @@ impl Tables { self.history.last().map_or(0, |entry| entry.version) } + fn account_rows(&self, account_id: &str) -> Vec { + let mut rows: Vec = self + .account_params + .iter() + .filter(|row| row.account_id == account_id) + .cloned() + .collect(); + rows.sort_by_key(|row| row.position); + rows + } + fn append( &mut self, module_id: &str, @@ -411,15 +444,22 @@ impl ModuleStore for FsModuleStore { } async fn account_params(&self, account_id: &str) -> Result, String> { + Ok(self.read(|tables| tables.account_rows(account_id))) + } + + async fn snapshot( + &self, + account_id: &str, + cached_version: Option, + ) -> Result { Ok(self.read(|tables| { - let mut rows: Vec = tables - .account_params - .iter() - .filter(|row| row.account_id == account_id) - .cloned() - .collect(); - rows.sort_by_key(|row| row.position); - rows + let version = tables.version(); + ModuleSnapshot { + version, + instances: (cached_version != Some(version)) + .then(|| tables.instances.values().cloned().collect()), + account_params: tables.account_rows(account_id), + } })) } @@ -535,12 +575,20 @@ impl ModuleStore for FsModuleStore { }) } - async fn history(&self, module_id: &str) -> Result, String> { + async fn history( + &self, + module_id: &str, + before: Option, + limit: usize, + ) -> Result, String> { Ok(self.read(|tables| { tables .history .iter() + .rev() .filter(|entry| entry.module_id == module_id) + .filter(|entry| before.is_none_or(|before| entry.version < before)) + .take(limit) .cloned() .collect() })) @@ -621,9 +669,9 @@ mod tests { .unwrap(); store.set_enabled("caps", false, &change()).await.unwrap(); assert!(!store.instances().await.unwrap()[0].enabled); - let history = store.history("caps").await.unwrap(); - assert_eq!(history[1].previous, json!({ "enabled": true })); - assert_eq!(history[1].new, json!({ "enabled": false })); + let history = store.history("caps", None, 10).await.unwrap(); + assert_eq!(history[0].previous, json!({ "enabled": true })); + assert_eq!(history[0].new, json!({ "enabled": false })); assert_eq!(store.version().await.unwrap(), 2); assert!( store @@ -662,9 +710,18 @@ mod tests { .await .unwrap(); assert_eq!(store.account_params("0xacc").await.unwrap().len(), 1); - let history = store.history("blocklist").await.unwrap(); + let history = store.history("blocklist", None, 10).await.unwrap(); assert_eq!(history.len(), 2); - assert_eq!(history[1].previous, json!({ "b": 1 })); + assert_eq!(history[0].previous, json!({ "b": 1 })); + let older = store + .history("blocklist", Some(history[0].version), 1) + .await + .unwrap(); + assert_eq!( + older, + vec![history[1].clone()], + "paged below a version, newest first" + ); } #[tokio::test] diff --git a/crates/server/src/modules/testing.rs b/crates/server/src/modules/testing.rs index 485a7470..31181996 100644 --- a/crates/server/src/modules/testing.rs +++ b/crates/server/src/modules/testing.rs @@ -269,6 +269,16 @@ impl super::store::ModuleStore for RacingStore { self.inner.instances().await } + async fn snapshot( + &self, + account_id: &str, + cached_version: Option, + ) -> Result { + let writes = std::mem::take(&mut *self.before_account_params.lock().unwrap()); + self.commit(writes).await?; + self.inner.snapshot(account_id, cached_version).await + } + async fn set_enabled( &self, module_id: &str, @@ -346,8 +356,13 @@ impl super::store::ModuleStore for RacingStore { self.inner.set_assignment(account_id, modules, change).await } - async fn history(&self, module_id: &str) -> Result, String> { - self.inner.history(module_id).await + async fn history( + &self, + module_id: &str, + before: Option, + limit: usize, + ) -> Result, String> { + self.inner.history(module_id, before, limit).await } async fn version(&self) -> Result { From b9fc5f85c230155e5308225e79884c1e255bff6e Mon Sep 17 00:00:00 2001 From: Zeljko Date: Mon, 9 Nov 2026 18:12:59 +0100 Subject: [PATCH 057/105] fix(modules): find accounts registered with a mixed-case id on the operator routes (#251) The operator module routes lowercased the account id and then looked the account up case-sensitively, but registration stores the id as the client sent it. An account registered with a mixed-case id answered 404 to every layer, assignment and view request, so operators could not attach assigned instances or layers to it. The routes now look the account up as given and then lowercased, and keep the lowercased key for its module rows, as evaluation does. --- crates/server/src/modules/admin.rs | 88 ++++++++++++++++++++++++++---- 1 file changed, 76 insertions(+), 12 deletions(-) diff --git a/crates/server/src/modules/admin.rs b/crates/server/src/modules/admin.rs index bff98e89..f1e39441 100644 --- a/crates/server/src/modules/admin.rs +++ b/crates/server/src/modules/admin.rs @@ -151,15 +151,23 @@ async fn validated( Ok(stored) } +/// The key the account's module rows use: its id lowercased, as evaluation looks them up. +/// Registration stores the id as the client sent it, so the account is looked up as given and +/// then lowercased. async fn existing_account(state: &AppState, account_id: &str) -> Result { - let account_id = account_id.to_ascii_lowercase(); - match state.metadata.get(&account_id).await { - Ok(Some(_)) => Ok(account_id), - Ok(None) => Err(GuardianError::AccountNotFound(account_id)), - Err(e) => Err(GuardianError::StorageError(format!( - "account lookup failed: {e}" - ))), + let key = account_id.to_ascii_lowercase(); + for candidate in [account_id, key.as_str()] { + match state.metadata.get(candidate).await { + Ok(Some(_)) => return Ok(key.clone()), + Ok(None) => continue, + Err(e) => { + return Err(GuardianError::StorageError(format!( + "account lookup failed: {e}" + ))); + } + } } + Err(GuardianError::AccountNotFound(account_id.to_string())) } async fn version(pipeline: &ModulePipeline) -> Result { @@ -269,11 +277,16 @@ pub async fn catalog_view(state: &AppState) -> Result { } pub async fn account_view(state: &AppState, account_id: &str) -> Result { - let pipeline = pipeline(state)?; let account_id = existing_account(state, account_id).await?; + view_of(state, &account_id).await +} + +/// The modules of the account whose module rows are keyed `account_id`. +async fn view_of(state: &AppState, account_id: &str) -> Result { + let pipeline = pipeline(state)?; let rows = pipeline .store() - .account_params(&account_id) + .account_params(account_id) .await .map_err(GuardianError::StorageError)?; let mut modules = Vec::new(); @@ -328,7 +341,7 @@ pub async fn account_view(state: &AppState, account_id: &str) -> Result Date: Mon, 9 Nov 2026 18:14:41 +0100 Subject: [PATCH 058/105] fix(modules): compare module tokens in constant time; mark the bearer header sensitive (#251) The serve harness compared a presented bearer token with == , whose timing can reveal how much of a token matches. It now compares in time independent of where the tokens differ. The Guardian's authorization metadata value is marked sensitive so it is never printed by tonic's debug output. --- crates/guardian-module-sdk/src/serve.rs | 21 +++++++++++++++++++-- crates/server/src/modules/grpc_kind.rs | 9 ++++++++- 2 files changed, 27 insertions(+), 3 deletions(-) diff --git a/crates/guardian-module-sdk/src/serve.rs b/crates/guardian-module-sdk/src/serve.rs index 249adfe0..e644470c 100644 --- a/crates/guardian-module-sdk/src/serve.rs +++ b/crates/guardian-module-sdk/src/serve.rs @@ -65,8 +65,14 @@ impl Harness { .and_then(|value| value.strip_prefix("Bearer ")) .ok_or_else(|| Status::unauthenticated("missing bearer token"))?; let accepted = match instance_id { - Some(id) => self.tokens.get(id).is_some_and(|token| token == presented), - None => self.tokens.values().any(|token| token == presented), + Some(id) => self + .tokens + .get(id) + .is_some_and(|token| same_token(token, presented)), + None => self + .tokens + .values() + .any(|token| same_token(token, presented)), }; if accepted { Ok(()) @@ -78,6 +84,17 @@ impl Harness { } } +/// Compares in time independent of where the tokens differ, so response timing does not reveal +/// a token prefix. +fn same_token(expected: &str, presented: &str) -> bool { + expected.len() == presented.len() + && expected + .bytes() + .zip(presented.bytes()) + .fold(0u8, |difference, (a, b)| difference | (a ^ b)) + == 0 +} + pub(crate) fn status(error: ModuleError) -> Status { match error { ModuleError::Unavailable(message) => Status::unavailable(message), diff --git a/crates/server/src/modules/grpc_kind.rs b/crates/server/src/modules/grpc_kind.rs index d9782ed4..0990bf80 100644 --- a/crates/server/src/modules/grpc_kind.rs +++ b/crates/server/src/modules/grpc_kind.rs @@ -61,7 +61,14 @@ impl ModuleFactory for GrpcFactory { let authorization = instance .auth_token .as_ref() - .map(|token| MetadataValue::try_from(format!("Bearer {}", token.expose_secret()))) + .map(|token| { + MetadataValue::try_from(format!("Bearer {}", token.expose_secret())).map( + |mut value| { + value.set_sensitive(true); + value + }, + ) + }) .transpose() .map_err(|_| ModuleError::InvalidRequest("token is not a valid header value".into()))?; Ok(Arc::new(GrpcModule { From 1d2f14739eb80b9cd14fb21ff7b888d1a953b4fb Mon Sep 17 00:00:00 2001 From: Zeljko Date: Mon, 9 Nov 2026 18:19:28 +0100 Subject: [PATCH 059/105] fix(module-sdk): refuse basic-policy ids that are not in 0x hex form (#251) basic-policy compares ids with the hex strings the Guardian sends, and only lowercased them when validating. An id written another way, such as a bech32 address pasted from a wallet, passed validation and never matched, so a recipient denylist or an amount cap on that faucet silently did not apply. Every id in its params must now be 0x and hex form. --- .../guardian-module-sdk/src/basic_policy.rs | 57 ++++++++++++++++--- docs/guides/policy-modules/built-in.md | 6 +- .../contracts/catalog-config.md | 2 + 3 files changed, 57 insertions(+), 8 deletions(-) diff --git a/crates/guardian-module-sdk/src/basic_policy.rs b/crates/guardian-module-sdk/src/basic_policy.rs index a75dd80d..b2f80787 100644 --- a/crates/guardian-module-sdk/src/basic_policy.rs +++ b/crates/guardian-module-sdk/src/basic_policy.rs @@ -86,6 +86,29 @@ fn normalized(values: &[String]) -> BTreeSet { values.iter().map(|v| v.to_ascii_lowercase()).collect() } +/// Ids in the hex form the Guardian reports them in (`0x` and hex digits), lowercased. Any other +/// spelling, a bech32 address for one, would never match a request, so a denylist or a cap would +/// silently not apply; it is refused instead. +fn ids(field: &str, values: &[String]) -> Result, String> { + values.iter().map(|value| id(field, value)).collect() +} + +fn id(field: &str, value: &str) -> Result { + match value + .strip_prefix("0x") + .or_else(|| value.strip_prefix("0X")) + { + Some(rest) + if !rest.is_empty() && rest.bytes().all(|b| b.is_ascii_alphanumeric() || b == b'_') => + { + Ok(value.to_ascii_lowercase()) + } + _ => Err(format!( + "{field}: {value:?} is not an id in 0x hex form (a bech32 address is not accepted)" + )), + } +} + impl TryFrom for Policy { type Error = String; @@ -94,9 +117,10 @@ impl TryFrom for Policy { .max_amount_per_tx .into_iter() .map(|(faucet, amount)| { + let faucet = id("max_amount_per_tx", &faucet)?; amount .parse::() - .map(|amount| (faucet.to_ascii_lowercase(), amount)) + .map(|amount| (faucet.clone(), amount)) .map_err(|_| format!("max_amount_per_tx for {faucet} is not a decimal amount")) }) .collect::>()?; @@ -104,19 +128,35 @@ impl TryFrom for Policy { (Some(_), Some(_)) => { return Err("signer_allowlist and signer_denylist are mutually exclusive".into()); } - (Some(list), None) => Some(SignerList::Allow(normalized(&list))), - (None, Some(list)) => Some(SignerList::Deny(normalized(&list))), + (Some(list), None) => Some(SignerList::Allow(ids("signer_allowlist", &list)?)), + (None, Some(list)) => Some(SignerList::Deny(ids("signer_denylist", &list)?)), (None, None) => None, }; Ok(Self { caps, - assets: params.asset_allowlist.as_deref().map(normalized), - recipients: params.recipient_allowlist.as_deref().map(normalized), - blocked_recipients: params.recipient_denylist.as_deref().map(normalized), + assets: params + .asset_allowlist + .as_deref() + .map(|list| ids("asset_allowlist", list)) + .transpose()?, + recipients: params + .recipient_allowlist + .as_deref() + .map(|list| ids("recipient_allowlist", list)) + .transpose()?, + blocked_recipients: params + .recipient_denylist + .as_deref() + .map(|list| ids("recipient_denylist", list)) + .transpose()?, deny_unknown_recipients: params.deny_unknown_recipients, signers, signer_check: params.signer_check, - code: params.allowed_code_commitments.as_deref().map(normalized), + code: params + .allowed_code_commitments + .as_deref() + .map(|list| ids("allowed_code_commitments", list)) + .transpose()?, code_check: params.code_check, }) } @@ -774,6 +814,9 @@ mod tests { #[tokio::test] async fn validate_params_rejects_bad_input() { for params in [ + json!({ "recipient_denylist": ["mtst1qrkd5x7qy0mw0yqzlvqlqd3w9cafjkw"] }), + json!({ "max_amount_per_tx": { "faucet": "10" } }), + json!({ "signer_denylist": ["0x"] }), json!({ "unknown": 1 }), json!({ "max_amount_per_tx": { USDC: "ten" } }), json!({ "signer_allowlist": [], "signer_denylist": [] }), diff --git a/docs/guides/policy-modules/built-in.md b/docs/guides/policy-modules/built-in.md index 37599c66..62e62ebb 100644 --- a/docs/guides/policy-modules/built-in.md +++ b/docs/guides/policy-modules/built-in.md @@ -7,7 +7,11 @@ and scope. Do the [setup](./README.md#setup) first; the catalog is ## `basic-policy` params -All params are optional; an instance with none allows everything. +All params are optional; an instance with none allows everything. Write every +id (faucet, recipient, signer commitment, code commitment) in the `0x` hex form +the Guardian reports, not as a bech32 address: params with another form are +refused, since such an id would never match and its rule would not apply. +Case does not matter. | Param | Value | Refuses with | Notes | |---|---|---|---| diff --git a/speckit/features/251-guardian-modules/contracts/catalog-config.md b/speckit/features/251-guardian-modules/contracts/catalog-config.md index 1a148e65..f611df63 100644 --- a/speckit/features/251-guardian-modules/contracts/catalog-config.md +++ b/speckit/features/251-guardian-modules/contracts/catalog-config.md @@ -79,6 +79,8 @@ A secret that cannot be read fails the instance's creation: startup stops for an ## `basic-policy` params (M2a) +Every id is written in `0x` hex form (case-insensitive); `validate_params` refuses any other form, such as a bech32 address, which would never match a request. + | Param | Type | Effect | |---|---|---| | `max_amount_per_tx` | map faucet id to decimal string | For each listed faucet, deny if the gross amount sent exceeds it: the sum of that faucet's fungible amounts over every output note, full or partial. Input notes consumed in the same transaction do not offset it, the fee note (`tx_fee`) is not counted, faucets not listed are uncapped, non-fungible assets are not counted (use `asset_allowlist`) | From afb6861c7e1af893bb3260801f6299cb07283fca Mon Sep 17 00:00:00 2001 From: Zeljko Date: Mon, 9 Nov 2026 18:21:54 +0100 Subject: [PATCH 060/105] fix(modules): normalized params follow the params rules too (#251) The params a module returns as normalized were stored without the size check on operator writes, and without the size and secret-reference checks when migrated at startup, seeded on first start or migrated at enable. A module could store params over GUARDIAN_MODULE_PARAMS_MAX_BYTES or holding secret references. They are now checked like any params; a migration that breaks them keeps the stored params and is logged. --- crates/server/src/modules/admin.rs | 17 ++++--- crates/server/src/modules/pipeline.rs | 73 ++++++++++++++++++++++++++- 2 files changed, 82 insertions(+), 8 deletions(-) diff --git a/crates/server/src/modules/admin.rs b/crates/server/src/modules/admin.rs index f1e39441..039e49c5 100644 --- a/crates/server/src/modules/admin.rs +++ b/crates/server/src/modules/admin.rs @@ -142,12 +142,9 @@ async fn validated( let stored = validate_params(&instance.module, params, instance.config.timeout) .await .map_err(|e| GuardianError::InvalidInput(format!("module {}: {e}", instance.config.id)))?; - if contains_secret_reference(&stored) { - return Err(GuardianError::InvalidInput(format!( - "module {}: normalized params contain a secret reference", - instance.config.id - ))); - } + pipeline + .storable_normalization(&stored) + .map_err(|e| GuardianError::InvalidInput(format!("module {}: {e}", instance.config.id)))?; Ok(stored) } @@ -398,7 +395,13 @@ pub async fn enable( module: Some(module_id.to_string()), } })?; - if checked.params != params && !instance.config.file_managed_params { + let storable = pipeline + .storable_normalization(&checked.params) + .inspect_err(|error| { + tracing::warn!(module = %module_id, %error, "Module's normalized params break the params rules; kept the stored params"); + }) + .is_ok(); + if checked.params != params && !instance.config.file_managed_params && storable { let migrator = format!( "module:{}", instance.build.as_deref().unwrap_or(&instance.config.kind) diff --git a/crates/server/src/modules/pipeline.rs b/crates/server/src/modules/pipeline.rs index 88cb855f..9871ee9a 100644 --- a/crates/server/src/modules/pipeline.rs +++ b/crates/server/src/modules/pipeline.rs @@ -115,7 +115,22 @@ impl std::fmt::Display for Failure { } } +/// The rules every stored params value follows, applied to what a module returns as normalized +/// params: within the size cap and free of secret references. +fn storable(limits: &Limits, params: &serde_json::Value) -> Result<(), String> { + limits.check_params_size(params)?; + if super::catalog::contains_secret_reference(params) { + return Err("normalized params contain a secret reference".into()); + } + Ok(()) +} + impl ModulePipeline { + /// [`storable`] under this pipeline's limits. + pub fn storable_normalization(&self, params: &serde_json::Value) -> Result<(), String> { + storable(&self.limits, params) + } + pub async fn new( mut catalog: Catalog, registry: &Registry, @@ -170,7 +185,11 @@ impl ModulePipeline { let seed = if config.file_managed_params { serde_json::json!({}) } else { - normalized.get(&config.id).unwrap_or(&config.params).clone() + normalized + .get(&config.id) + .filter(|params| storable(&limits, params).is_ok()) + .unwrap_or(&config.params) + .clone() }; store .seed_instance(&config.id, config.enabled, &seed, &now) @@ -186,6 +205,10 @@ impl ModulePipeline { ) else { continue; }; + if let Err(error) = storable(&limits, params) { + tracing::warn!(module = %instance.config.id, %error, "Module's normalized params break the params rules; kept the stored params"); + continue; + } let operator = format!( "module:{}", instance.build.as_deref().unwrap_or(&instance.config.kind) @@ -1229,6 +1252,54 @@ params = {params} ); } + #[tokio::test] + async fn normalized_params_that_break_the_params_rules_are_not_stored() { + use crate::modules::testing::{FixedFactory, ProtocolStub}; + let catalog = Catalog::parse( + r#" +[[module]] +id = "migrating" +kind = "protocol-stub" +scope = "all" +hooks = ["before_transaction_approved"] +timeout_ms = 50 +params = { old_name = 5 } +"#, + None, + ) + .unwrap(); + for normalized in [ + serde_json::json!({ "new_name": "x".repeat(200) }), + serde_json::json!({ "key": { "$secret": "vendor-key" } }), + ] { + let mut stub = ProtocolStub::new(); + stub.normalized = Some(normalized.clone()); + let mut registry = Registry::first_party(); + registry + .register("protocol-stub", Arc::new(FixedFactory(Arc::new(stub)))) + .unwrap(); + let store: Arc = + Arc::new(super::super::store::FsModuleStore::in_memory()); + ModulePipeline::new( + catalog.clone(), + ®istry, + store.clone(), + "2026-10-16T00:00:00Z".to_string(), + crate::modules::limits::Limits { + params_max_bytes: 100, + ..Default::default() + }, + ) + .await + .unwrap(); + assert_eq!( + store.instances().await.unwrap()[0].global_params, + serde_json::json!({ "old_name": 5 }), + "kept the catalog params instead of {normalized}" + ); + } + } + #[tokio::test] async fn startup_stores_params_the_module_migrated() { use crate::modules::testing::{FixedFactory, ProtocolStub}; From 8d9948d3f35213950f5ce1a32ea708ca9749e786 Mon Sep 17 00:00:00 2001 From: Zeljko Date: Mon, 9 Nov 2026 18:23:17 +0100 Subject: [PATCH 061/105] fix(modules): keep orphaned assignments when an account's assignment is replaced (#251) An assignment PUT replaced every assignment row of the account, and an entry naming an instance the catalog no longer declares cannot be listed in the request, so any assignment change deleted the account's orphaned rows. RFC 0002 keeps them so they apply again if the instance returns. They are now carried over unchanged. --- crates/server/src/modules/admin.rs | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/crates/server/src/modules/admin.rs b/crates/server/src/modules/admin.rs index 039e49c5..034d644b 100644 --- a/crates/server/src/modules/admin.rs +++ b/crates/server/src/modules/admin.rs @@ -630,6 +630,19 @@ pub async fn set_assignment( .account_params(&account_id) .await .map_err(GuardianError::StorageError)?; + // Rows naming an instance the catalog no longer declares are kept as they are: they apply + // again if the instance comes back, and the operator cannot list them in the request. + to_store.extend( + current + .iter() + .filter(|row| { + row.kind == ParamsKind::Assignment && pipeline.instance(&row.module_id).is_none() + }) + .map(|row| Assigned { + module_id: row.module_id.clone(), + params: row.params.clone(), + }), + ); let mut rows = current.clone(); rows.retain(|row| row.kind == ParamsKind::Layer); rows.extend(to_store.iter().map(|assigned| { @@ -833,6 +846,17 @@ mod tests { let catalog = catalog_view(&state).await.unwrap(); assert_eq!(catalog.undeclared.len(), 1); assert_eq!(catalog.undeclared[0].module_id, "retired"); + + let after = set_assignment(&state, &operator(), ACCOUNT, Vec::new(), "OP-9", None) + .await + .unwrap(); + let kept: Vec<_> = after + .modules + .iter() + .filter(|entry| entry.orphaned) + .map(|entry| entry.module_id.as_str()) + .collect(); + assert_eq!(kept, ["retired"], "an assignment write keeps orphaned rows"); } #[tokio::test] From 81fd91d966219c5ce9c142b760868bff82a66646 Mon Sep 17 00:00:00 2001 From: Zeljko Date: Mon, 9 Nov 2026 18:24:20 +0100 Subject: [PATCH 062/105] fix(modules): no params drift for instances whose params stay in the catalog file (#251) An instance whose catalog params hold secret references keeps them in the file and seeds an empty placeholder in the database, so comparing the seed with the catalog reported params_drift and config_drift on every start. Drift is no longer computed for such instances. The guide says how one that later drops its references starts out. --- crates/server/src/modules/admin.rs | 3 ++- crates/server/src/modules/pipeline.rs | 7 ++++--- docs/guides/policy-modules/README.md | 7 +++++++ 3 files changed, 13 insertions(+), 4 deletions(-) diff --git a/crates/server/src/modules/admin.rs b/crates/server/src/modules/admin.rs index 034d644b..6b25dc7f 100644 --- a/crates/server/src/modules/admin.rs +++ b/crates/server/src/modules/admin.rs @@ -234,7 +234,8 @@ async fn instance_view( catalog_enabled: instance.config.catalog_enabled, enabled_drift: enabled != instance.config.catalog_enabled, operator_can_disable: instance.config.operator_can_disable, - params_drift: seeded.is_some_and(|seeded| seeded != instance.config.params), + params_drift: !instance.config.file_managed_params + && seeded.is_some_and(|seeded| seeded != instance.config.params), params, file_managed_params: instance.config.file_managed_params, build: instance.build.clone(), diff --git a/crates/server/src/modules/pipeline.rs b/crates/server/src/modules/pipeline.rs index 9871ee9a..f56d754b 100644 --- a/crates/server/src/modules/pipeline.rs +++ b/crates/server/src/modules/pipeline.rs @@ -158,9 +158,10 @@ impl ModulePipeline { let Some((params, enabled)) = stored.get(&config.id) else { continue; }; - if seeded - .get(&config.id) - .is_some_and(|seeded| *seeded != config.params) + if !config.file_managed_params + && seeded + .get(&config.id) + .is_some_and(|seeded| *seeded != config.params) { seed_drift.insert(config.id.clone()); } diff --git a/docs/guides/policy-modules/README.md b/docs/guides/policy-modules/README.md index 01a43850..75b3a820 100644 --- a/docs/guides/policy-modules/README.md +++ b/docs/guides/policy-modules/README.md @@ -85,6 +85,13 @@ An instance whose catalog params contain secret references cannot use `disclosure = "params"`: the server refuses to start, since the reference would show cosigners the secret's name. +Such an instance's global params stay in the catalog file: the operator API +refuses to change them, and the database keeps only an empty placeholder. If a +later catalog drops the secret references, the instance becomes +operator-managed and starts from that empty placeholder, not from the new +catalog params (the catalog only seeds params on first start). Set its params +through the API right after that deploy. + In [`built-in.toml`](./built-in.toml), `caps` discloses its params and `blocklist` denies generically. From 7251441b3beb242c6f7eaac73a991969eeb149e0 Mon Sep 17 00:00:00 2001 From: Zeljko Date: Mon, 9 Nov 2026 18:26:29 +0100 Subject: [PATCH 063/105] fix(modules): a layer left by a catalog scope change can be removed (#251) When an instance moved from scope = all to default or assigned, an account's layer on it stayed behind: deleting it was refused because layers apply only to all instances, and on Postgres an assignment including the module hit the (account, module) key and answered 500, while the filesystem store dropped the layer silently. Deleting a layer now works whatever the instance's scope is, an assignment of a module that still has a layer is refused with a 400 naming it, and both stores remove only layer rows when a layer is deleted. --- crates/server/src/modules/admin.rs | 53 +++++++++++++++++++++++++++++- crates/server/src/modules/store.rs | 8 +++-- 2 files changed, 57 insertions(+), 4 deletions(-) diff --git a/crates/server/src/modules/admin.rs b/crates/server/src/modules/admin.rs index 6b25dc7f..d9937fd2 100644 --- a/crates/server/src/modules/admin.rs +++ b/crates/server/src/modules/admin.rs @@ -527,7 +527,7 @@ pub async fn set_layer( let pipeline = pipeline(state)?; let account_id = existing_account(state, account_id).await?; let instance = instance(pipeline, module_id)?; - if instance.config.scope != Scope::All { + if params.is_some() && instance.config.scope != Scope::All { return Err(GuardianError::InvalidInput(format!( "module {module_id}: account layers apply only to scope = \"all\" instances; assign it instead" ))); @@ -631,6 +631,17 @@ pub async fn set_assignment( .account_params(&account_id) .await .map_err(GuardianError::StorageError)?; + if let Some(layer) = current.iter().find(|row| { + row.kind == ParamsKind::Layer + && to_store + .iter() + .any(|assigned| assigned.module_id == row.module_id) + }) { + return Err(GuardianError::InvalidInput(format!( + "module {}: the account still has a layer on it from when it applied to every account; delete the layer first", + layer.module_id + ))); + } // Rows naming an instance the catalog no longer declares are kept as they are: they apply // again if the instance comes back, and the operator cannot list them in the request. to_store.extend( @@ -1010,6 +1021,46 @@ mod tests { )); } + #[tokio::test] + async fn a_layer_left_by_a_scope_change_can_be_deleted_before_the_module_is_assigned() { + let state = state(); + let store = state.modules.as_ref().unwrap().store_handle(); + store + .set_layer( + ACCOUNT, + "optional", + Some(json!({ "recipient_denylist": ["0xbbb"] })), + &Change { + operator: "0xop", + reason: "written while optional applied to every account", + at: "t0".into(), + }, + ) + .await + .unwrap(); + let operator = operator(); + let assign = || { + set_assignment( + &state, + &operator, + ACCOUNT, + vec![Assigned { + module_id: "optional".into(), + params: json!({}), + }], + "OP-1", + None, + ) + }; + assert!( + matches!(assign().await, Err(GuardianError::InvalidInput(message)) if message.contains("delete the layer first")) + ); + set_layer(&state, &operator, ACCOUNT, "optional", None, "OP-2", None) + .await + .expect("a stale layer can be deleted whatever the instance's scope is now"); + assign().await.expect("then the module can be assigned"); + } + #[tokio::test] async fn an_account_already_over_the_budget_can_be_brought_back_under_it() { let mut state = state(); diff --git a/crates/server/src/modules/store.rs b/crates/server/src/modules/store.rs index 227ba096..811dd972 100644 --- a/crates/server/src/modules/store.rs +++ b/crates/server/src/modules/store.rs @@ -480,9 +480,11 @@ impl ModuleStore for FsModuleStore { ) -> Result<(), String> { self.write(|tables| { let previous = tables.row_params(account_id, module_id, ParamsKind::Layer); - tables - .account_params - .retain(|row| !(row.account_id == account_id && row.module_id == module_id)); + tables.account_params.retain(|row| { + !(row.account_id == account_id + && row.module_id == module_id + && row.kind == ParamsKind::Layer) + }); if let Some(params) = ¶ms { tables.account_params.push(AccountParamsRow { account_id: account_id.to_string(), From 395bd9a8e142beb2ec83aa5f7b69a374b1b3f901 Mon Sep 17 00:00:00 2001 From: Zeljko Date: Mon, 9 Nov 2026 18:28:01 +0100 Subject: [PATCH 064/105] fix(modules): record a reordered assignment in the params history (#251) An assignment write that only changed the order of the account's modules wrote no history entry, and on the filesystem store did not move the params version, although order decides which module refuses first and which ones the budget cuts. A position change now counts as a change on both stores. --- crates/server/src/modules/store.rs | 53 ++++++++++++++++++++++++------ 1 file changed, 43 insertions(+), 10 deletions(-) diff --git a/crates/server/src/modules/store.rs b/crates/server/src/modules/store.rs index 811dd972..031be251 100644 --- a/crates/server/src/modules/store.rs +++ b/crates/server/src/modules/store.rs @@ -601,7 +601,8 @@ impl ModuleStore for FsModuleStore { } } -/// `(module_id, previous, new)` for every module whose assigned params changed. +/// `(module_id, previous, new)`: one history entry per module whose params or evaluation position the write changes: order +/// decides which module refuses first and which ones the budget cuts. pub(crate) fn assignment_changes( previous: &[AccountParamsRow], modules: &[Assigned], @@ -612,17 +613,17 @@ pub(crate) fn assignment_changes( ids.dedup(); ids.into_iter() .filter_map(|module_id| { - let before = previous + let old = previous.iter().find(|row| row.module_id == module_id); + let new = modules .iter() - .find(|row| row.module_id == module_id) - .map(|row| row.params.clone()) + .position(|assigned| assigned.module_id == module_id); + let before = old.map(|row| row.params.clone()).unwrap_or_default(); + let after = new + .map(|index| modules[index].params.clone()) .unwrap_or_default(); - let after = modules - .iter() - .find(|assigned| assigned.module_id == module_id) - .map(|assigned| assigned.params.clone()) - .unwrap_or_default(); - (before != after).then(|| (module_id.to_string(), before, after)) + let moved = + matches!((old, new), (Some(row), Some(index)) if row.position as usize != index); + (before != after || moved).then(|| (module_id.to_string(), before, after)) }) .collect() } @@ -683,6 +684,38 @@ mod tests { ); } + #[tokio::test] + async fn reordering_an_assignment_is_recorded_and_moves_the_version() { + let store = FsModuleStore::in_memory(); + let assigned = |ids: &[&str]| { + ids.iter() + .map(|id| Assigned { + module_id: id.to_string(), + params: json!({}), + }) + .collect::>() + }; + store + .set_assignment("0xacc", assigned(&["a", "b"]), &change()) + .await + .unwrap(); + let version = store.version().await.unwrap(); + store + .set_assignment("0xacc", assigned(&["b", "a"]), &change()) + .await + .unwrap(); + assert!(store.version().await.unwrap() > version); + assert_eq!(store.history("a", None, 10).await.unwrap().len(), 2); + let order: Vec<_> = store + .account_params("0xacc") + .await + .unwrap() + .into_iter() + .map(|row| row.module_id) + .collect(); + assert_eq!(order, ["b", "a"]); + } + #[tokio::test] async fn layers_and_assignments_share_the_account_table() { let store = FsModuleStore::in_memory(); From ace65b21a99911b00482df7454bfa91f577998b5 Mon Sep 17 00:00:00 2001 From: Zeljko Date: Mon, 9 Nov 2026 18:29:21 +0100 Subject: [PATCH 065/105] fix(modules): dry-run failures do not open a module's circuit breaker (#251) The breaker counts failures per instance across every account, and a cosigner can send dry-run checks without anyone's signature. A few checks that make a module fail would open its breaker on that replica: every approval refused for a fail-closed instance, or the instance skipped for everyone when it fails open. Dry-run failures still apply on_error to the check but no longer count toward the breaker. --- crates/server/src/modules/pipeline.rs | 25 ++++++++++++++++++++++++- docs/rfcs/0002-guardian-modules.md | 2 +- docs/runbooks/policy-modules.md | 3 ++- 3 files changed, 27 insertions(+), 3 deletions(-) diff --git a/crates/server/src/modules/pipeline.rs b/crates/server/src/modules/pipeline.rs index f56d754b..e8a1cb87 100644 --- a/crates/server/src/modules/pipeline.rs +++ b/crates/server/src/modules/pipeline.rs @@ -877,7 +877,9 @@ impl Plan<'_> { Err(CallError::Timeout) => Failure::Timeout, }; super::metrics::evaluated(id, super::metrics::Outcome::Error, took); - if !(cut_by_budget && matches!(failure, Failure::Timeout)) { + // A dry run is sent by a cosigner without anyone's signature, so its failures do not + // count toward opening the breaker for every account. + if !dry_run && !(cut_by_budget && matches!(failure, Failure::Timeout)) { breakers.failed(id); } approval @@ -1929,6 +1931,27 @@ mod failure_handling_tests { assert!(run(&open).await.is_ok()); } + #[tokio::test] + async fn dry_run_failures_do_not_open_the_circuit() { + let pipeline = ModulePipeline::from_instances(vec![instance( + "screening", + &[HOOK], + OnError::Deny, + StubModule::new(Behaviour::Fail), + )]) + .with_limits(Limits { + breaker_failures: 2, + ..Limits::default() + }); + for _ in 0..4 { + let (plans, _) = pipeline.plan_dry_run("0xacc").await.unwrap(); + for plan in plans { + assert!(plan.run(|| Ok(HookRequest::default())).await.is_err()); + } + } + assert_eq!(pipeline.breakers().state("screening"), CircuitState::Closed); + } + #[tokio::test] async fn consecutive_failures_open_the_circuit_so_later_requests_skip_the_timeout() { let (hung, module) = hanging("screening", OnError::Deny, Duration::from_millis(50)); diff --git a/docs/rfcs/0002-guardian-modules.md b/docs/rfcs/0002-guardian-modules.md index 123eb594..cba10fc8 100644 --- a/docs/rfcs/0002-guardian-modules.md +++ b/docs/rfcs/0002-guardian-modules.md @@ -1206,7 +1206,7 @@ None. Questions resolved in earlier revisions are kept below with their answers. | Revision | Date | Changes | |---|---|---| -| 31 | 2026-11-09 | the per-account budget check refuses only writes that raise an over-budget cost (section 4.3); `GUARDIAN_MODULE_UNAVAILABLE` and `GUARDIAN_EXECUTION_MODULE_UNAVAILABLE` omit `module` for an instance whose denials are generic (section 4.1); `metadata.modules` is kept out of client delta responses (section 2.2). `OutputNote.tx_fee` set only for the fee note `pay_fee` creates (section 3.1): the only `TX_FEE` note, with the derived serial number and one asset of the chain's fee faucet. Revisions 20 to 30 set it for any note with the `TX_FEE` script, which a transaction script can create with any assets, so the flag let funds past every `basic-policy` rule. No wire change; the field's meaning is narrowed | +| 31 | 2026-11-09 | failures of dry-run checks do not count toward the circuit breaker, since a cosigner sends them without anyone's signature (section 4.4); the per-account budget check refuses only writes that raise an over-budget cost (section 4.3); `GUARDIAN_MODULE_UNAVAILABLE` and `GUARDIAN_EXECUTION_MODULE_UNAVAILABLE` omit `module` for an instance whose denials are generic (section 4.1); `metadata.modules` is kept out of client delta responses (section 2.2). `OutputNote.tx_fee` set only for the fee note `pay_fee` creates (section 3.1): the only `TX_FEE` note, with the derived serial number and one asset of the chain's fee faucet. Revisions 20 to 30 set it for any note with the `TX_FEE` script, which a transaction script can create with any assets, so the flag let funds past every `basic-policy` rule. No wire change; the field's meaning is narrowed | | 30 | 2026-11-09 | the secrets backend named: `GUARDIAN_MODULE_SECRET_PROVIDER` selects AWS Secrets Manager (the prod default) or owner-only files below `GUARDIAN_MODULE_SECRET_DIR`, read once when the instances are created; a secret that cannot be read fails creation, with the enabled/disabled rule of section 2.2. Field names fixed as `auth.token_secret`, `tls.client_cert_secret` and `tls.client_key_secret`; a secret name is 1 to 512 characters of letters, digits and `/_+=.@-`, and a `$secret` object has no other key (section 2.2). In-process factories read `$secret` values from `ModuleInstanceConfig::secret`. No protocol change | | 29 | 2026-11-09 | M2a implementation of `scope = default`: the copy is written right after the claim, only into an account with no assignment and no assignment history, under the module state lock, instead of in the claim's transaction on Postgres and before the claim on the filesystem; a crash in between is repaired by the unfinished-claim retry, so both backends follow one rule and no transaction spans the metadata and module stores (section 2.3). No protocol change | | 28 | 2026-11-09 | protocol version 1 frozen: the freeze criteria of section 7 met at `e4efd839` on `251-modules-m2a`, with tests; the proto copies say so. No design change | diff --git a/docs/runbooks/policy-modules.md b/docs/runbooks/policy-modules.md index f481aad0..cf78f4a8 100644 --- a/docs/runbooks/policy-modules.md +++ b/docs/runbooks/policy-modules.md @@ -52,7 +52,8 @@ Symptoms: clients get `503 GUARDIAN_MODULE_UNAVAILABLE` with `meta.module` `guardian_module_up{module}` is 0; `Policy module health probe failed` and `Policy module failed; refusing` at `warn`; `guardian_module_circuit_open{module}` is 1 once a replica has seen -`GUARDIAN_MODULE_BREAKER_FAILURES` (5) failures in a row, after which the +`GUARDIAN_MODULE_BREAKER_FAILURES` (5) failures in a row (dry-run checks do not +count), after which the module is skipped without waiting for its timeout. 1. Check the module itself (its process, endpoint, certificate, token). A From ef350b2d979c17aabea0df74786a787b240fc707 Mon Sep 17 00:00:00 2001 From: Zeljko Date: Mon, 9 Nov 2026 18:29:33 +0100 Subject: [PATCH 066/105] docs(modules): fail-open instances skipped by a transaction, and per-replica creation (#251) The runbook now says that a transaction whose module request cannot be built or sent makes a fail-open instance be skipped for it, and that a replica which could not create a disabled instance at startup needs a restart after the instance is enabled elsewhere. --- docs/runbooks/policy-modules.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/docs/runbooks/policy-modules.md b/docs/runbooks/policy-modules.md index cf78f4a8..b5c17daa 100644 --- a/docs/runbooks/policy-modules.md +++ b/docs/runbooks/policy-modules.md @@ -24,6 +24,11 @@ For every instance in the catalog, know which path stops it: | `operator_can_disable = false`, `on_error = "allow"` | None needed for an outage: failures continue (recorded on the delta). A module that denies wrongly needs a params change or a deploy | Next request | | `operator_can_disable = false`, `on_error = "deny"` | A deploy: change the catalog and restart | A rollout | +- Use `on_error = "allow"` only where skipping the instance is acceptable for + any transaction, not only during an outage: a transaction whose request the + Guardian cannot build or send (an account view it cannot read, a request over + `GUARDIAN_MODULE_REQUEST_MAX_BYTES`) is a module failure too, and a fail-open + instance is then skipped for it (recorded in `metadata.modules.failed_open`). - Give the on-call operator `modules:disable`. It allows disabling instances marked `operator_can_disable` and nothing else, so it is safe to hand out more widely than `policies:write` ([permissions](../DASHBOARD.md#permission-vocabulary)). @@ -144,7 +149,12 @@ names the instance (`module : ...`). history and assignments are kept for when it comes back. A disabled instance that fails its checks only logs `Disabled module failed -its startup checks` and stays disabled. +its startup checks` and stays disabled. Each replica creates its instances when +it starts: if one replica could not create a disabled instance (a secret it +could not read at the time, say), enabling the instance through another replica +does not repair it there, and its calls on that replica fail and follow +`on_error`. `guardian_module_up` is 0 for the instance on that replica; restart +it after enabling. ## After an incident From e9cda785f48a5865dc90e7aa549d024e82c17bad Mon Sep 17 00:00:00 2001 From: Zeljko Date: Mon, 9 Nov 2026 23:10:39 +0100 Subject: [PATCH 067/105] fix(guardian-client): sign the proposal check once, tagged as CheckDeltaProposal (#251) checkDeltaProposal passed its tagged payload to fetchAuthenticated, which wraps the payload again, so the TypeScript client signed the payload object rather than the request and every check over HTTP was refused with 401. It now goes through fetchSigned, as the execution request does. --- packages/guardian-client/src/http.test.ts | 26 +++++++++++++++++++++++ packages/guardian-client/src/http.ts | 2 +- 2 files changed, 27 insertions(+), 1 deletion(-) diff --git a/packages/guardian-client/src/http.test.ts b/packages/guardian-client/src/http.test.ts index b1c36a7d..bcea3e64 100644 --- a/packages/guardian-client/src/http.test.ts +++ b/packages/guardian-client/src/http.test.ts @@ -705,6 +705,32 @@ describe('GuardianHttpClient', () => { ); }); + it('signs the check tagged as CheckDeltaProposal, and creation untagged', async () => { + client.setSigner(mockSigner); + const signRequest = vi.mocked(mockSigner.signRequest!); + signRequest.mockClear(); + mockFetch + .mockResolvedValueOnce({ ok: true, json: async () => ({ allowed: true, complete: true }) }) + .mockResolvedValueOnce({ ok: true, json: async () => ({}) }); + const request = { + accountId, + nonce: 1, + deltaPayload: { txSummary: { data: 'base64summary' }, signatures: [] }, + }; + + await client.checkDeltaProposal(request); + await client.pushDeltaProposal(request).catch(() => undefined); + + const body = { + account_id: accountId, + nonce: 1, + delta_payload: { tx_summary: { data: 'base64summary' }, signatures: [] }, + }; + const [check, create] = signRequest.mock.calls.map((call) => call[2].toBytes()); + expect(check).toEqual(RequestAuthPayload.forOperation('CheckDeltaProposal', body).toBytes()); + expect(create).toEqual(RequestAuthPayload.fromRequest(body).toBytes()); + }); + it('surfaces a policy refusal from the check as the creation error', async () => { client.setSigner(mockSigner); mockFetch.mockResolvedValueOnce({ diff --git a/packages/guardian-client/src/http.ts b/packages/guardian-client/src/http.ts index 4e1a1ec4..b1c112d2 100644 --- a/packages/guardian-client/src/http.ts +++ b/packages/guardian-client/src/http.ts @@ -657,7 +657,7 @@ export class GuardianHttpClient { */ async checkDeltaProposal(request: DeltaProposalRequest): Promise { const serverRequest = toServerDeltaProposalRequest(request); - const response = await this.fetchAuthenticated('/delta/proposal/check', { + const response = await this.fetchSigned('/delta/proposal/check', { method: 'POST', body: JSON.stringify(serverRequest), }, request.accountId, RequestAuthPayload.forOperation('CheckDeltaProposal', serverRequest), SessionOperation.CheckDeltaProposal); From 2c7596bba04f0298cc669b6f46fefb5096300fe3 Mon Sep 17 00:00:00 2001 From: Zeljko Date: Mon, 9 Nov 2026 23:10:39 +0100 Subject: [PATCH 068/105] test(qualification): policy module scenarios on both profiles (#251) The main stack server gets a per-run module catalog (two in-process basic-policy instances and one remote grpc instance, all scoped assigned) with a TLS CA and a bearer token read through the file secrets backend. - det-module-refusal (both SDKs): an assigned module refuses the check and the proposal with its id and reason, and the proposal passes once unassigned. - det-module-unavailable (Rust): the driver serves the remote module over TLS; it decides while up, is refused as unavailable while down, and disabling it lets the account through. - det-module-break-glass (Rust): a disable survives a restart against a catalog that says enabled, and is in the params history. - live-module-cap-1of1-ecdsa (both SDKs): a per-account cap refuses one unit over it, and a payment at the cap lands with its fee. Excluded on devnet for the historical window. --- Cargo.lock | 2 + crates/qualification-driver/Cargo.toml | 3 + .../qualification-driver/src/manifest/mod.rs | 10 + .../qualification-driver/src/scenario/live.rs | 4 +- .../qualification-driver/src/scenario/mod.rs | 6 + .../src/scenario/modules.rs | 659 ++++++++++++++++++ docs/QUALIFICATION.md | 43 +- .../tests/qualification/actions/live.ts | 93 ++- .../tests/qualification/actions/modules.ts | 106 +++ .../tests/qualification/actions/operator.ts | 27 +- .../tests/qualification/fixtures.ts | 9 + .../tests/qualification/runner.ts | 6 + qualification/README.md | 3 + qualification/manifest/manifest.json | 76 ++ qualification/manifest/matrix.toml | 2 + qualification/manifest/scenarios.toml | 74 ++ qualification/stack/compose.yml | 10 + qualification/stack/lib/env.sh | 12 +- qualification/stack/lib/modules.sh | 79 +++ qualification/stack/lib/operator.sh | 9 +- qualification/stack/run.sh | 9 + qualification/stack/tests/harness-test.sh | 28 + 22 files changed, 1258 insertions(+), 12 deletions(-) create mode 100644 crates/qualification-driver/src/scenario/modules.rs create mode 100644 packages/miden-multisig-client/tests/qualification/actions/modules.ts create mode 100644 qualification/stack/lib/modules.sh diff --git a/Cargo.lock b/Cargo.lock index a759e987..22f5369c 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -3567,6 +3567,7 @@ dependencies = [ "chrono", "clap", "guardian-client", + "guardian-module-sdk", "guardian-shared", "hex", "libc", @@ -3583,6 +3584,7 @@ dependencies = [ "thiserror 2.0.19", "tokio", "toml 0.8.23", + "tonic", ] [[package]] diff --git a/crates/qualification-driver/Cargo.toml b/crates/qualification-driver/Cargo.toml index 0f058254..33643979 100644 --- a/crates/qualification-driver/Cargo.toml +++ b/crates/qualification-driver/Cargo.toml @@ -18,6 +18,8 @@ chrono = { workspace = true, features = ["serde"] } clap = { version = "4.5", features = ["derive"] } serde = { workspace = true, features = ["derive"] } guardian-client = { path = "../client" } +# The remote policy module the deterministic profile serves for the stack's catalog. +guardian-module-sdk = { path = "../guardian-module-sdk" } guardian-shared = { path = "../shared" } hex = { workspace = true } miden-client = { workspace = true, features = ["tonic"] } @@ -34,6 +36,7 @@ serde_json = { workspace = true } thiserror = { workspace = true } tokio = { workspace = true, features = ["macros", "process", "rt-multi-thread", "time"] } toml = "0.8" +tonic = { workspace = true, features = ["tls-ring"] } [dev-dependencies] tempfile = { workspace = true } diff --git a/crates/qualification-driver/src/manifest/mod.rs b/crates/qualification-driver/src/manifest/mod.rs index af005bd3..2376983f 100644 --- a/crates/qualification-driver/src/manifest/mod.rs +++ b/crates/qualification-driver/src/manifest/mod.rs @@ -206,6 +206,11 @@ pub enum Action { MixedSchemeGate, SessionStart, SessionAssert, + ModuleRefusal, + ModuleUnavailable, + ModuleBreakGlass, + ModuleCapAssign, + ModuleCapRefuses, Unknown(String), } @@ -285,6 +290,11 @@ impl From for Action { "mixed-scheme-gate" => Self::MixedSchemeGate, "session-start" => Self::SessionStart, "session-assert" => Self::SessionAssert, + "module-refusal" => Self::ModuleRefusal, + "module-unavailable" => Self::ModuleUnavailable, + "module-break-glass" => Self::ModuleBreakGlass, + "module-cap-assign" => Self::ModuleCapAssign, + "module-cap-refuses" => Self::ModuleCapRefuses, other => Self::Unknown(other.to_string()), } } diff --git a/crates/qualification-driver/src/scenario/live.rs b/crates/qualification-driver/src/scenario/live.rs index 66186968..f8a4192f 100644 --- a/crates/qualification-driver/src/scenario/live.rs +++ b/crates/qualification-driver/src/scenario/live.rs @@ -2945,7 +2945,7 @@ pub async fn assert_signer_set(runner: &Runner) -> ActionOutcome { /// How long GUARDIAN may take to finish applying an executed change before the /// suite treats the disagreement as real. -const SETTLE_DEADLINE: std::time::Duration = std::time::Duration::from_secs(180); +pub(super) const SETTLE_DEADLINE: std::time::Duration = std::time::Duration::from_secs(180); /// Proposes, waiting out the window where GUARDIAN refuses a new proposal /// because earlier changes are still pending: the account's candidate queue @@ -2976,7 +2976,7 @@ async fn propose_when_settled( } /// What the account sends back to the treasury, well under what it holds. -const P2ID_AMOUNT: u64 = 1_000; +pub(super) const P2ID_AMOUNT: u64 = 1_000; /// The procedure whose threshold override the suite exercises. const OVERRIDE_PROCEDURE: miden_multisig_client::ProcedureName = diff --git a/crates/qualification-driver/src/scenario/mod.rs b/crates/qualification-driver/src/scenario/mod.rs index d8c4e83f..42915eb2 100644 --- a/crates/qualification-driver/src/scenario/mod.rs +++ b/crates/qualification-driver/src/scenario/mod.rs @@ -3,6 +3,7 @@ pub mod error_envelope; pub mod identity; pub mod live; pub mod mixed_scheme; +pub mod modules; pub mod queue; pub mod restart_handoff; pub mod signers; @@ -371,6 +372,8 @@ impl Runner { Action::ProcedureThresholdAssert => { Some(live::assert_procedure_threshold(self).await) } + Action::ModuleCapAssign => Some(modules::assign_cap(self).await), + Action::ModuleCapRefuses => Some(modules::assert_cap_refuses(self).await), _ => None, } } else { @@ -409,6 +412,9 @@ impl Runner { Some(mixed_scheme::assert_per_scheme_approvals(self).await) } Action::MixedSchemeGate => Some(mixed_scheme::assert_mixed_scheme_gate(self).await), + Action::ModuleRefusal => Some(modules::assert_refusal(self).await), + Action::ModuleUnavailable => Some(modules::assert_unavailable(self).await), + Action::ModuleBreakGlass => Some(modules::assert_break_glass(self).await), _ => None, } }; diff --git a/crates/qualification-driver/src/scenario/modules.rs b/crates/qualification-driver/src/scenario/modules.rs new file mode 100644 index 00000000..6bcc6746 --- /dev/null +++ b/crates/qualification-driver/src/scenario/modules.rs @@ -0,0 +1,659 @@ +//! Policy modules, driven the way an operator and a client meet them: instances from the +//! stack's catalog (`qualification/stack/lib/modules.sh`), assigned to an account through the +//! operator API, refusing through the SDK. +//! +//! Every instance in that catalog is scoped `assigned`, so it applies only to an account a +//! scenario assigns it to. The deterministic actions assign to the fixture account every +//! scenario shares, so each one clears its assignment on every path, as the pause scenario +//! unpauses. +//! +//! They propose the first threshold-only fixture delta (`queue_1`) rather than `delta_1`: the +//! fixture generator adds `delta_1`'s signer without the approver scheme entry a real +//! add-signer writes, and the Guardian refuses to build a module's account view from that. + +use std::sync::Arc; + +use guardian_client::{ClientError, GuardianClient, ModuleRefusal}; +use guardian_module_sdk::basic_policy::BasicPolicy; +use miden_multisig_client::{MultisigError, TransactionType}; +use serde_json::{Value, json}; + +use super::{ActionOutcome, Runner}; +use crate::fixtures::Fixtures; + +/// The instances the stack's catalog declares. +const GATE: &str = "qual-gate"; +const SWITCH: &str = "qual-switch"; +const REMOTE: &str = "qual-remote"; + +/// A signer commitment nobody holds. Checked against every signer, an allowlist of only this +/// refuses every transaction of the fixture account. +const UNLISTED_SIGNER: &str = "0x1111111111111111111111111111111111111111111111111111111111111111"; + +const REASON: &str = "qualification: policy module scenario"; + +/// Retries `$call` while GUARDIAN still holds an earlier change of the account as pending, +/// which it reports before any module runs. +macro_rules! settled { + ($call:expr) => {{ + let started = std::time::Instant::now(); + let mut wait = std::time::Duration::from_secs(1); + loop { + match $call.await { + Err(error) + if error.to_string().contains("already a pending change") + && started.elapsed() < super::live::SETTLE_DEADLINE => + { + tokio::time::sleep(wait).await; + wait = (wait * 2).min(std::time::Duration::from_secs(5)); + } + other => break other, + } + } + }}; +} + +fn refuse_added_signers() -> Value { + json!({ "signer_check": "all", "signer_allowlist": [UNLISTED_SIGNER] }) +} + +/// The operator API, logged in as the operator holding `policies:write`. +struct Operator<'a> { + runner: &'a Runner, + base: String, +} + +impl<'a> Operator<'a> { + async fn login(runner: &'a Runner, fixtures: &Fixtures) -> Result { + let base = runner.endpoints.http.trim_end_matches('/').to_string(); + super::account::operator_login(runner, &base, fixtures).await?; + Ok(Self { runner, base }) + } + + async fn send( + &self, + method: reqwest::Method, + path: &str, + body: Option, + ) -> Result { + let url = format!("{}/dashboard{path}", self.base); + let mut request = self.runner.http.request(method.clone(), &url); + if let Some(body) = body { + request = request.json(&body); + } + let response = request.send().await.map_err(|error| { + ActionOutcome::failed_setup(format!("calling {method} {path} failed: {error}")) + })?; + let status = response.status(); + let text = response.text().await.unwrap_or_default(); + if !status.is_success() { + return Err(ActionOutcome::failed_product(format!( + "{method} {path} was refused with {status}: {text}" + ))); + } + serde_json::from_str(&text).map_err(|error| { + ActionOutcome::failed_product(format!("{method} {path} answered with no JSON: {error}")) + }) + } + + async fn assign( + &self, + account_id: &str, + module_id: &str, + params: Value, + ) -> Result<(), ActionOutcome> { + self.send( + reqwest::Method::PUT, + &format!("/accounts/{account_id}/modules"), + Some(json!({ "modules": [{ "module_id": module_id, "params": params }], "reason": REASON })), + ) + .await + .map(drop) + } + + async fn clear(&self, account_id: &str) -> Result<(), ActionOutcome> { + self.send( + reqwest::Method::PUT, + &format!("/accounts/{account_id}/modules"), + Some(json!({ "modules": [], "reason": REASON })), + ) + .await + .map(drop) + } + + async fn switch(&self, module_id: &str, enabled: bool) -> Result<(), ActionOutcome> { + let route = if enabled { "enable" } else { "disable" }; + self.send( + reqwest::Method::POST, + &format!("/modules/{module_id}/{route}"), + Some(json!({ "reason": REASON })), + ) + .await + .map(drop) + } + + async fn instance(&self, module_id: &str) -> Result { + let catalog = self.send(reqwest::Method::GET, "/modules", None).await?; + catalog["modules"] + .as_array() + .and_then(|modules| modules.iter().find(|module| module["module_id"] == module_id)) + .cloned() + .ok_or_else(|| { + ActionOutcome::failed_setup(format!( + "the catalog has no instance {module_id}; qualification/stack/lib/modules.sh declares it" + )) + }) + } + + async fn history(&self, module_id: &str) -> Result, ActionOutcome> { + let history = self + .send( + reqwest::Method::GET, + &format!("/modules/{module_id}/params/history"), + None, + ) + .await?; + Ok(history["entries"].as_array().cloned().unwrap_or_default()) + } +} + +/// The first failure wins; a cleanup failure counts only when everything before it passed. +fn then_cleanup(outcome: ActionOutcome, cleanup: Result<(), ActionOutcome>) -> ActionOutcome { + match (outcome, cleanup) { + (ActionOutcome::Passed, Err(failure)) => failure, + (outcome, _) => outcome, + } +} + +/// The fixture account, an authenticated client for it, and its proposal. +struct FixtureProposal { + client: GuardianClient, + account_id: miden_protocol::account::AccountId, + nonce: u64, + payload: miden_multisig_client::ProposalPayload, +} + +impl FixtureProposal { + async fn open(runner: &Runner, fixtures: &Fixtures) -> Result { + let signer = fixtures.signer().map_err(|error| { + ActionOutcome::failed_setup(format!("cannot build the fixture signer: {error}")) + })?; + let client = GuardianClient::connect(runner.endpoints.grpc.clone()) + .await + .map_err(|error| { + ActionOutcome::failed_setup(format!( + "cannot reach {}: {error}", + runner.endpoints.grpc + )) + })? + .with_signer(Arc::new(signer)); + let account_id = miden_protocol::account::AccountId::from_hex(&fixtures.account_id) + .map_err(|error| { + ActionOutcome::failed_setup(format!("the fixture account id is malformed: {error}")) + })?; + let delta = fixtures.chained.first().ok_or_else(|| { + ActionOutcome::failed_setup("the fixtures carry no threshold-only delta") + })?; + let payload = Fixtures::proposal_payload_for(&delta.payload).map_err(|error| { + ActionOutcome::failed_setup(format!("building the fixture proposal payload: {error}")) + })?; + Ok(Self { + client, + account_id, + nonce: delta.nonce, + payload, + }) + } + + async fn check(&mut self) -> Result<(), ClientError> { + self.client + .check_delta_proposal(&self.account_id, self.nonce, &self.payload) + .await + .map(drop) + } + + async fn push(&mut self) -> Result<(), ClientError> { + self.client + .push_delta_proposal(&self.account_id, self.nonce, &self.payload) + .await + .map(drop) + } +} + +/// `Passed` when `result` is a denial by `module` for `reason_code`. +fn expect_denied( + what: &str, + result: Result<(), ClientError>, + module: &str, + reason_code: &str, +) -> ActionOutcome { + match result { + Ok(()) => { + ActionOutcome::failed_product(format!("{what} was accepted while {module} refuses it")) + } + Err(error) => match error.module_refusal() { + Some(ModuleRefusal::Denied { + module: Some(denied_by), + reason_code: code, + .. + }) if denied_by == module && code == reason_code => ActionOutcome::Passed, + Some(refusal) => ActionOutcome::failed_product(format!( + "{what} was refused as {refusal:?}, not by {module} for {reason_code}" + )), + None => ActionOutcome::failed_product(format!( + "{what} failed without a module refusal: {error}" + )), + }, + } +} + +fn expect_allowed(what: &str, result: Result<(), ClientError>) -> ActionOutcome { + match result { + Ok(()) => ActionOutcome::Passed, + Err(error) => ActionOutcome::failed_product(format!("{what} was refused: {error}")), + } +} + +fn first_failure(outcomes: impl IntoIterator) -> ActionOutcome { + outcomes + .into_iter() + .find(|outcome| !matches!(outcome, ActionOutcome::Passed)) + .unwrap_or(ActionOutcome::Passed) +} + +/// An assigned in-process module refuses the fixture proposal, at the dry-run check and at +/// creation, with its id and reason code, and the same proposal passes once the assignment is +/// cleared. +pub async fn assert_refusal(runner: &Runner) -> ActionOutcome { + let Some(fixtures) = runner.fixtures.as_ref() else { + return ActionOutcome::failed_setup("the server fixtures were not loaded"); + }; + let operator = match Operator::login(runner, fixtures).await { + Ok(operator) => operator, + Err(outcome) => return outcome, + }; + let mut proposal = match FixtureProposal::open(runner, fixtures).await { + Ok(proposal) => proposal, + Err(outcome) => return outcome, + }; + let account = fixtures.account_id.clone(); + + if let Err(outcome) = operator + .assign(&account, GATE, refuse_added_signers()) + .await + { + return outcome; + } + let refused = first_failure([ + expect_denied( + "the proposal check", + proposal.check().await, + GATE, + "signer_not_allowed", + ), + expect_denied( + "the proposal", + proposal.push().await, + GATE, + "signer_not_allowed", + ), + ]); + let cleared = operator.clear(&account).await; + let outcome = then_cleanup(refused, cleared); + if !matches!(outcome, ActionOutcome::Passed) { + return outcome; + } + expect_allowed( + "the proposal check, once the module was unassigned,", + proposal.check().await, + ) +} + +/// The remote policy module the driver serves for the stack's `qual-remote` instance: +/// `basic-policy` over TLS, with the bearer token the Guardian reads from its secrets backend. +struct RemoteModule { + shutdown: tokio::sync::oneshot::Sender<()>, + server: tokio::task::JoinHandle<()>, +} + +impl RemoteModule { + async fn start() -> Result { + let missing = |name: &str| { + ActionOutcome::failed_setup(format!( + "{name} is unset, but qualification/stack/run.sh always exports it" + )) + }; + let dir = std::path::PathBuf::from( + std::env::var("QUAL_MODULE_TLS_DIR").map_err(|_| missing("QUAL_MODULE_TLS_DIR"))?, + ); + let port: u16 = std::env::var("QUAL_MODULE_PORT") + .map_err(|_| missing("QUAL_MODULE_PORT"))? + .parse() + .map_err(|error| ActionOutcome::failed_setup(format!("QUAL_MODULE_PORT: {error}")))?; + let read = |name: &str| { + std::fs::read(dir.join(name)).map_err(|error| { + ActionOutcome::failed_setup(format!("cannot read the module's {name}: {error}")) + }) + }; + let identity = tonic::transport::Identity::from_pem(read("cert.pem")?, read("key.pem")?); + let token = String::from_utf8_lossy(&read("token")?).trim().to_string(); + + let service = guardian_module_sdk::serve::serve(BasicPolicy) + .instance(REMOTE, token) + .into_service(); + let listener = tokio::net::TcpListener::bind(("0.0.0.0", port)) + .await + .map_err(|error| { + ActionOutcome::failed_setup(format!("cannot listen on port {port}: {error}")) + })?; + let server = tonic::transport::Server::builder() + .tls_config(tonic::transport::ServerTlsConfig::new().identity(identity)) + .map_err(|error| ActionOutcome::failed_setup(format!("module TLS: {error}")))? + .add_service(service); + let incoming = tonic::transport::server::TcpIncoming::from(listener); + let (shutdown, stopped) = tokio::sync::oneshot::channel::<()>(); + let server = tokio::spawn(async move { + let stopped = async { + let _ = stopped.await; + }; + if let Err(error) = server.serve_with_incoming_shutdown(incoming, stopped).await { + eprintln!("the qualification policy module stopped: {error}"); + } + }); + Ok(Self { shutdown, server }) + } + + /// Stops listening and closes the connection the Guardian holds open. Aborting the task + /// is not enough: each accepted connection is served on a task of its own, which keeps + /// answering after the listener is gone. + async fn stop(self) { + let _ = self.shutdown.send(()); + let mut server = self.server; + if tokio::time::timeout(std::time::Duration::from_secs(10), &mut server) + .await + .is_err() + { + server.abort(); + } + } +} + +/// A remote module decides for the account over TLS while it is up, its failure refuses +/// (`on_error = "deny"`) and names it while it is down, and disabling it is the way out. +/// +/// The instance starts disabled in the catalog, because an enabled module that cannot be +/// reached stops the server from starting, and the module runs only for this action. So the +/// action always leaves it disabled and unassigned, whatever it concluded: left enabled, it +/// would stop the server coming back from the restart that follows the run. +pub async fn assert_unavailable(runner: &Runner) -> ActionOutcome { + let Some(fixtures) = runner.fixtures.as_ref() else { + return ActionOutcome::failed_setup("the server fixtures were not loaded"); + }; + let operator = match Operator::login(runner, fixtures).await { + Ok(operator) => operator, + Err(outcome) => return outcome, + }; + let mut proposal = match FixtureProposal::open(runner, fixtures).await { + Ok(proposal) => proposal, + Err(outcome) => return outcome, + }; + let module = match RemoteModule::start().await { + Ok(module) => module, + Err(outcome) => return outcome, + }; + let account = fixtures.account_id.clone(); + + let (outcome, module) = remote_lifecycle(&operator, &mut proposal, &account, module).await; + if let Some(module) = module { + module.stop().await; + } + let disabled = operator.switch(REMOTE, false).await; + let cleared = operator.clear(&account).await; + then_cleanup(then_cleanup(outcome, disabled), cleared) +} + +async fn remote_lifecycle( + operator: &Operator<'_>, + proposal: &mut FixtureProposal, + account: &str, + module: RemoteModule, +) -> (ActionOutcome, Option) { + if let Err(outcome) = operator.switch(REMOTE, true).await { + return (outcome, Some(module)); + } + if let Err(outcome) = operator + .assign(account, REMOTE, refuse_added_signers()) + .await + { + return (outcome, Some(module)); + } + let decided = expect_denied( + "the proposal check, with the remote module up,", + proposal.check().await, + REMOTE, + "signer_not_allowed", + ); + if !matches!(decided, ActionOutcome::Passed) { + return (decided, Some(module)); + } + + module.stop().await; + let down = match proposal.check().await { + Ok(()) => ActionOutcome::failed_product( + "the proposal check passed while the fail-closed remote module was down".to_string(), + ), + Err(error) => match error.module_refusal() { + Some(ModuleRefusal::Unavailable { + module: Some(unavailable), + }) if unavailable == REMOTE => ActionOutcome::Passed, + Some(refusal) => ActionOutcome::failed_product(format!( + "with the remote module down, the check was refused as {refusal:?}, not as {REMOTE} unavailable" + )), + None => ActionOutcome::failed_product(format!( + "with the remote module down, the check failed without a module refusal: {error}" + )), + }, + }; + if !matches!(down, ActionOutcome::Passed) { + return (down, None); + } + + if let Err(outcome) = operator.switch(REMOTE, false).await { + return (outcome, None); + } + ( + expect_allowed( + "the proposal check, with the down module disabled,", + proposal.check().await, + ), + None, + ) +} + +/// An operator disables a module that refuses, the account is let through at once, and the +/// stored switch survives a restart even though the catalog still says enabled. +/// +/// Two passes, as `restart-durability` has: the first disables and leaves it disabled, the +/// pass after the restart finds it disabled, with the disable in the params history, and +/// enables it again. +pub async fn assert_break_glass(runner: &Runner) -> ActionOutcome { + let Some(fixtures) = runner.fixtures.as_ref() else { + return ActionOutcome::failed_setup("the server fixtures were not loaded"); + }; + let operator = match Operator::login(runner, fixtures).await { + Ok(operator) => operator, + Err(outcome) => return outcome, + }; + if runner.post_restart && !runner.upgrade_target { + return assert_switch_survived(&operator).await; + } + + let mut proposal = match FixtureProposal::open(runner, fixtures).await { + Ok(proposal) => proposal, + Err(outcome) => return outcome, + }; + let account = fixtures.account_id.clone(); + if let Err(outcome) = operator.switch(SWITCH, true).await { + return outcome; + } + if let Err(outcome) = operator + .assign(&account, SWITCH, refuse_added_signers()) + .await + { + return outcome; + } + let outcome = first_failure([ + expect_denied( + "the proposal check", + proposal.check().await, + SWITCH, + "signer_not_allowed", + ), + match operator.switch(SWITCH, false).await { + Ok(()) => expect_allowed( + "the proposal check, with the module disabled,", + proposal.check().await, + ), + Err(outcome) => outcome, + }, + ]); + then_cleanup(outcome, operator.clear(&account).await) +} + +async fn assert_switch_survived(operator: &Operator<'_>) -> ActionOutcome { + let instance = match operator.instance(SWITCH).await { + Ok(instance) => instance, + Err(outcome) => return outcome, + }; + if instance["enabled"] != json!(false) || instance["catalog_enabled"] != json!(true) { + return ActionOutcome::failed_product(format!( + "after the restart {SWITCH} reads enabled = {} (catalog {}); the operator's disable \ + should have survived it", + instance["enabled"], instance["catalog_enabled"] + )); + } + let history = match operator.history(SWITCH).await { + Ok(history) => history, + Err(outcome) => return outcome, + }; + if !history.iter().any(|entry| entry["reason"] == REASON) { + return ActionOutcome::failed_product(format!( + "the params history of {SWITCH} does not record the disable: {history:?}" + )); + } + match operator.switch(SWITCH, true).await { + Ok(()) => match operator.instance(SWITCH).await { + Ok(instance) if instance["enabled"] == json!(true) => ActionOutcome::Passed, + Ok(instance) => { + ActionOutcome::failed_product(format!("enabling {SWITCH} again left it {instance}")) + } + Err(outcome) => outcome, + }, + Err(outcome) => outcome, + } +} + +/// Assigns the gate to the scenario's account with a cap of exactly what `asset-send` sends, +/// and reads it back through the account's own policy listing. +pub async fn assign_cap(runner: &Runner) -> ActionOutcome { + let Some(fixtures) = runner.fixtures.as_ref() else { + return ActionOutcome::failed_setup("the server fixtures were not loaded"); + }; + let mut guard = runner.session.lock().await; + let Some(session) = guard.as_mut() else { + return ActionOutcome::failed_setup("no account has been created in this scenario"); + }; + let Some(faucet) = session.faucet else { + return ActionOutcome::failed_setup( + "the account was never funded, so there is no asset to cap", + ); + }; + let operator = match Operator::login(runner, fixtures).await { + Ok(operator) => operator, + Err(outcome) => return outcome, + }; + let mut limit = serde_json::Map::new(); + limit.insert(faucet.to_hex(), json!(super::live::P2ID_AMOUNT.to_string())); + let cap = json!({ "max_amount_per_tx": limit }); + if let Err(outcome) = operator + .assign(&session.account_id.to_string(), GATE, cap.clone()) + .await + { + return outcome; + } + + let policies = match session.clients[0].get_policies().await { + Ok(policies) => policies, + Err(error) => { + return ActionOutcome::failed_product(format!( + "listing the account's policies failed: {error}" + )); + } + }; + match policies.iter().find(|policy| policy.module_id == GATE) { + Some(policy) + if [&policy.params, &policy.account_layer] + .iter() + .any(|params| params.as_ref() == Some(&cap)) => + { + ActionOutcome::Passed + } + Some(policy) => ActionOutcome::failed_product(format!( + "the account's policies list {GATE} without the cap it was assigned: {policy:?}" + )), + None => ActionOutcome::failed_product(format!( + "the account's policies do not list the {GATE} it was assigned: {policies:?}" + )), + } +} + +/// One unit over the cap is refused by the dry-run check and at creation, naming the module and +/// `amount_cap_exceeded`; the capped amount itself passes the check. The transaction also pays +/// the network fee, so the capped amount passing is what shows the fee note is not counted as a +/// payment. +pub async fn assert_cap_refuses(runner: &Runner) -> ActionOutcome { + let mut guard = runner.session.lock().await; + let Some(session) = guard.as_mut() else { + return ActionOutcome::failed_setup("no account has been created in this scenario"); + }; + let (Some(faucet), Some(treasury)) = (session.faucet, session.treasury) else { + return ActionOutcome::failed_setup( + "the account was never funded, so it holds nothing to send", + ); + }; + let amount = super::live::P2ID_AMOUNT; + let send = |amount| TransactionType::transfer(treasury, faucet, amount); + let client = &mut session.clients[0]; + + let over_check = settled!(client.check_transaction(send(amount + 1))); + let over_check = expect_cap_denied("the check of a payment over the cap", over_check.map(drop)); + if !matches!(over_check, ActionOutcome::Passed) { + return over_check; + } + let over = settled!(client.propose_transaction(send(amount + 1))); + let over = expect_cap_denied("a payment over the cap", over.map(drop)); + if !matches!(over, ActionOutcome::Passed) { + return over; + } + match settled!(client.check_transaction(send(amount))) { + Ok(_) => ActionOutcome::Passed, + Err(error) => ActionOutcome::failed_product(format!( + "the check of a payment of exactly the cap was refused, so the fee may count as a \ + payment: {error}" + )), + } +} + +fn expect_cap_denied(what: &str, result: Result<(), MultisigError>) -> ActionOutcome { + match result { + Ok(()) => ActionOutcome::failed_product(format!("{what} was accepted")), + Err(MultisigError::ModuleDenied { + module: Some(module), + reason_code, + .. + }) if module == GATE && reason_code == "amount_cap_exceeded" => ActionOutcome::Passed, + Err(error) => ActionOutcome::failed_product(format!( + "{what} was refused, but not by {GATE} for amount_cap_exceeded: {error}" + )), + } +} diff --git a/docs/QUALIFICATION.md b/docs/QUALIFICATION.md index 46fdb506..13b9d529 100644 --- a/docs/QUALIFICATION.md +++ b/docs/QUALIFICATION.md @@ -85,10 +85,11 @@ gitignored directories, and tears it down afterwards: | A fourth Guardian that offers execution, `server-executing` | a configured prover and a database of its own (`guardian_executing`), so execution requests get past the capability gate in the deterministic profile | | A fifth Guardian that queues chained candidates, `server-queue` | `GUARDIAN_MAX_PENDING_CANDIDATES_PER_ACCOUNT` set to `2` in the deterministic profile and `4` in the live one (`QUAL_QUEUE_DEPTH` overrides it), the main server's acknowledgement identity, and a database of its own, so the candidate queue (issue #17) is qualified as an operator opts into it while the main server keeps the default of one in-flight candidate | | Operator allowlist | generated from the server fixtures via `qualification-driver operator-keys`, so the identities the scenarios sign with cannot drift from the ones the server accepts | +| Policy module catalog | `lib/modules.sh` writes the main server's catalog per run: two in-process `basic-policy` instances and one remote `grpc` instance, all scoped `assigned` so no other scenario meets them. The remote one points at a module the Rust driver serves on the host (`host.docker.internal`, on `QUAL_MODULE_PORT`) over TLS, with a certificate a per-run CA signs and a bearer token the server reads through the file secrets backend | | Guardian execution | the live profile points the server at the network's public prover (`https://tx-prover..miden.io`, overridable with `QUAL_TX_PROVER_URL`), so it offers execution; the deterministic stack configures none, so execution must be refused | | Postgres password | random per run | | Ports | picked per run, so concurrent runs do not collide | -| Everything written per run | one directory per run under `qualification/stack/runs/`, removed with the stack: the generated environment file, both acknowledgement key directories and the operator allowlist, so a second run cannot overwrite what the first one's server is still mounting | +| Everything written per run | one directory per run under `qualification/stack/runs/`, removed with the stack: the generated environment file, both acknowledgement key directories, the operator allowlist and the module catalog with its certificates and token, so a second run cannot overwrite what the first one's server is still mounting | The deterministic profile is the exception worth knowing about: it registers a **committed fixture account** whose stored state binds one specific guardian @@ -298,6 +299,42 @@ must fit its step budget inside devnet's 150 s historical window, and the wait a it; they still run there. Testnet runs Miden 0.16 until its 0.17 upgrade, so until then a testnet run of this line fails them along with everything else on 0.17. +### Policy modules + +Four scenarios cover policy modules ([RFC 0002](./rfcs/0002-guardian-modules.md)). Every +instance in the stack's catalog is scoped `assigned`, so it applies only to an account a +scenario assigns it to through the operator API, and the operator in the allowlist holds +`policies:write` for that. + +- `det-module-refusal` (deterministic, both SDKs): `qual-gate` is assigned to the fixture + account with a signer allowlist that names none of its signers. The proposal is refused at + the dry-run check and at creation with `GUARDIAN_MODULE_DENIED`, module `qual-gate` and + `signer_not_allowed`, over gRPC (Rust) and HTTP (TypeScript); once the assignment is + cleared the same proposal passes the check. +- `det-module-unavailable` (deterministic, Rust): the driver serves `basic-policy` for + `qual-remote` and enables it. The remote module refuses over TLS with the token from the + secrets backend; with the module stopped the check is refused as + `GUARDIAN_MODULE_UNAVAILABLE` naming `qual-remote` (`on_error = "deny"`), and disabling the + instance lets the account through. The instance starts disabled in the catalog, because an + enabled module that cannot be reached stops the server from starting, and the action leaves + it disabled on every path for the restart that follows. +- `det-module-break-glass` (deterministic, Rust): disabling `qual-switch` lets a refused + account through at once. The pass after the restart finds it still disabled against a + catalog that says enabled, with the disable in its params history, and enables it again. +- `live-module-cap-1of1-ecdsa` (live, both SDKs, required on testnet): `qual-gate` caps the + account at exactly what `asset-send` sends, and the account's own policy listing shows it. + One unit more is refused at the check and at creation with `amount_cap_exceeded`; the capped + payment passes, is signed by GUARDIAN at execution after the approval hook runs on the real + transaction, and lands. The funding asset is the network's fee asset, so a fee note counted + as a payment would push the capped send over the cap and fail it. Devnet's pairs exclude it + for the window reason above. + +The deterministic scenarios propose the first threshold-only fixture delta (`queue_1`), not +`delta_1`: the fixture generator adds `delta_1`'s signer without the approver scheme entry a +real add-signer writes, and GUARDIAN refuses (as unavailable) to build a module's account view +from that state. What stays uncovered: a fail-open instance (`on_error = "allow"`) recording +`metadata.modules.failed_open` on a signed delta, the circuit breaker, and mutual TLS. + ## Reading the outcome | Exit code | Meaning | @@ -438,9 +475,9 @@ is still cheaper to make all six at once: | `crates/qualification-driver/src/manifest/mod.rs` | the `Action` variant | | the same file | its `From` arm, the wire name | | `crates/qualification-driver/src/scenario/mod.rs` | the Rust dispatch arm | -| `crates/qualification-driver/src/scenario/{live,account,identity,error_envelope}.rs` | the Rust body, in the file for its family | +| `crates/qualification-driver/src/scenario/{live,account,identity,error_envelope,modules}.rs` | the Rust body, in the file for its family | | `packages/miden-multisig-client/tests/qualification/runner.ts` | the TypeScript dispatch case | -| `packages/miden-multisig-client/tests/qualification/actions/{live,account,identity,errorEnvelope,operator}.ts` | the TypeScript body | +| `packages/miden-multisig-client/tests/qualification/actions/{live,account,identity,errorEnvelope,operator,modules}.ts` | the TypeScript body | An action implemented on one SDK only is legitimate when it records a real capability gap, but it must report a skip naming the gap rather than a pass. Two diff --git a/packages/miden-multisig-client/tests/qualification/actions/live.ts b/packages/miden-multisig-client/tests/qualification/actions/live.ts index 0847de87..e423a747 100644 --- a/packages/miden-multisig-client/tests/qualification/actions/live.ts +++ b/packages/miden-multisig-client/tests/qualification/actions/live.ts @@ -26,7 +26,8 @@ import { type LiveSession, type Scheme, } from '../live.js'; -import { setAccountPaused } from './operator.js'; +import { GATE, expectDenied } from './modules.js'; +import { setAccountModules, setAccountPaused } from './operator.js'; import type { ActionContext, ActionOutcome } from '../runner.js'; /** Matches the Rust driver, so the two legs fund identically. */ @@ -3420,3 +3421,93 @@ export async function abandonStrandedHeadAndRecover( } return { kind: 'environment_blocked', reason: `the fresh transfer was ${completion.reason}` }; } + +/** + * Assigns the stack's `qual-gate` module to the scenario's account with a cap + * of exactly what `asset-send` sends, and reads it back through the account's + * own policy listing. Mirrors `assign_cap` in the Rust driver. + */ +export async function assignModuleCap(context: ActionContext, scenarioId: string): Promise { + const session = sessions.get(scenarioId); + if (!session?.multisig || !session.accountId) { + return { kind: 'failed', classification: 'setup', reason: 'no account has been created in this scenario' }; + } + if (!session.faucetId) { + return { kind: 'failed', classification: 'setup', reason: 'the account was never funded, so there is no asset to cap' }; + } + const cap = { max_amount_per_tx: { [session.faucetId]: P2ID_AMOUNT.toString() } }; + const assigned = await setAccountModules(context, session.accountId, [{ moduleId: GATE, params: cap }]); + if (assigned) return assigned; + + try { + const policies = await session.multisig.getPolicies(); + const policy = policies.find((entry) => entry.moduleId === GATE); + if (!policy) { + return { + kind: 'failed', + classification: 'product', + reason: `the account's policies do not list the ${GATE} it was assigned: ${JSON.stringify(policies)}`, + }; + } + const expected = JSON.stringify(cap); + if (JSON.stringify(policy.params) !== expected && JSON.stringify(policy.accountLayer) !== expected) { + return { + kind: 'failed', + classification: 'product', + reason: `the account's policies list ${GATE} without the cap it was assigned: ${JSON.stringify(policy)}`, + }; + } + return { kind: 'passed' }; + } catch (error) { + return { kind: 'failed', classification: 'product', reason: `listing the account's policies failed: ${String(error)}` }; + } +} + +/** + * One unit over the cap is refused by the dry-run check and at creation, + * naming the module and `amount_cap_exceeded`; the capped amount itself passes + * the check. The transaction also pays the network fee, so the capped amount + * passing is what shows the fee note is not counted as a payment. Mirrors + * `assert_cap_refuses` in the Rust driver. + */ +export async function assertModuleCapRefuses(_context: ActionContext, scenarioId: string): Promise { + const session = sessions.get(scenarioId); + if (!session?.multisig) { + return { kind: 'failed', classification: 'setup', reason: 'no account has been created in this scenario' }; + } + if (!session.faucetId || !session.treasuryId) { + return { kind: 'failed', classification: 'setup', reason: 'the account was never funded, so it holds nothing to send' }; + } + const multisig = session.multisig; + const send = (amount: bigint) => + ({ type: 'p2id', recipientId: session.treasuryId!, faucetId: session.faucetId!, amount }) as const; + + const overCheck = await expectDenied( + 'the check of a payment over the cap', + () => proposeWhenSettled(() => multisig.checkTransaction(send(P2ID_AMOUNT + 1n))), + GATE, + 'amount_cap_exceeded', + ); + if (overCheck.kind !== 'passed') return overCheck; + const over = await expectDenied( + 'a payment over the cap', + () => + proposeWhenSettled(() => + multisig.createP2idProposal(session.treasuryId!, session.faucetId!, P2ID_AMOUNT + 1n), + ), + GATE, + 'amount_cap_exceeded', + ); + if (over.kind !== 'passed') return over; + + try { + await proposeWhenSettled(() => multisig.checkTransaction(send(P2ID_AMOUNT))); + return { kind: 'passed' }; + } catch (error) { + return { + kind: 'failed', + classification: 'product', + reason: `the check of a payment of exactly the cap was refused, so the fee may count as a payment: ${String(error)}`, + }; + } +} diff --git a/packages/miden-multisig-client/tests/qualification/actions/modules.ts b/packages/miden-multisig-client/tests/qualification/actions/modules.ts new file mode 100644 index 00000000..a3c7faf6 --- /dev/null +++ b/packages/miden-multisig-client/tests/qualification/actions/modules.ts @@ -0,0 +1,106 @@ +import { GuardianHttpClient, type ModuleRefusal } from '@openzeppelin/guardian-client'; + +import { FalconSigner } from '../../../src/signers/falcon.js'; +import { loadServerFixtures, readThresholdDelta } from '../fixtures.js'; +import { setAccountModules } from './operator.js'; +import type { ActionContext, ActionOutcome } from '../runner.js'; + +/** The instance the stack's catalog declares for rules a scenario assigns. */ +export const GATE = 'qual-gate'; + +/** + * A signer commitment nobody holds. Checked against every signer, an allowlist + * of only this refuses every transaction of the fixture account. + */ +const UNLISTED_SIGNER = '0x1111111111111111111111111111111111111111111111111111111111111111'; + +/** The policy module refusal `error` carries, or `null`. */ +export function refusalOf(error: unknown): ModuleRefusal | null { + const carrier = error as { moduleRefusal?: () => ModuleRefusal | null }; + return typeof carrier?.moduleRefusal === 'function' ? carrier.moduleRefusal() : null; +} + +/** `passed` when `attempt` is refused by `module` for `reasonCode`. */ +export async function expectDenied( + what: string, + attempt: () => Promise, + module: string, + reasonCode: string, +): Promise { + try { + await attempt(); + return { kind: 'failed', classification: 'product', reason: `${what} was accepted while ${module} refuses it` }; + } catch (error) { + const refusal = refusalOf(error); + if (refusal?.kind === 'denied' && refusal.module === module && refusal.reasonCode === reasonCode) { + return { kind: 'passed' }; + } + return { + kind: 'failed', + classification: 'product', + reason: refusal + ? `${what} was refused as ${JSON.stringify(refusal)}, not by ${module} for ${reasonCode}` + : `${what} failed without a module refusal: ${String(error)}`, + }; + } +} + +/** + * An assigned in-process module refuses the fixture proposal over HTTP, at the + * dry-run check and at creation, with its id and reason code, and the same + * proposal passes once the assignment is cleared. Mirrors `assert_refusal` in + * the Rust driver. + */ +export async function assertRefusal(context: ActionContext): Promise { + let guardian: GuardianHttpClient; + let accountId: string; + let delta: ReturnType; + try { + const fixtures = loadServerFixtures(); + guardian = new GuardianHttpClient(context.httpEndpoint); + guardian.setSigner(new FalconSigner(fixtures.signerKey)); + accountId = fixtures.accountId; + delta = readThresholdDelta(); + } catch (error) { + return { kind: 'failed', classification: 'setup', reason: `cannot load the server fixtures: ${String(error)}` }; + } + const request = { + accountId, + nonce: delta.nonce, + deltaPayload: { + txSummary: { data: delta.delta_payload.data }, + signatures: [], + metadata: { proposalType: 'qualification' }, + }, + }; + + const assigned = await setAccountModules(context, accountId, [ + { moduleId: GATE, params: { signer_check: 'all', signer_allowlist: [UNLISTED_SIGNER] } }, + ]); + if (assigned) return assigned; + + let outcome = await expectDenied( + 'the proposal check', + () => guardian.checkDeltaProposal(request), + GATE, + 'signer_not_allowed', + ); + if (outcome.kind === 'passed') { + outcome = await expectDenied('the proposal', () => guardian.pushDeltaProposal(request), GATE, 'signer_not_allowed'); + } + + const cleared = await setAccountModules(context, accountId, []); + if (outcome.kind !== 'passed') return outcome; + if (cleared) return cleared; + + try { + await guardian.checkDeltaProposal(request); + return { kind: 'passed' }; + } catch (error) { + return { + kind: 'failed', + classification: 'product', + reason: `the proposal check, once the module was unassigned, was refused: ${String(error)}`, + }; + } +} diff --git a/packages/miden-multisig-client/tests/qualification/actions/operator.ts b/packages/miden-multisig-client/tests/qualification/actions/operator.ts index ba3d9ec4..bda81b1a 100644 --- a/packages/miden-multisig-client/tests/qualification/actions/operator.ts +++ b/packages/miden-multisig-client/tests/qualification/actions/operator.ts @@ -1,4 +1,4 @@ -import { GuardianOperatorHttpClient } from '@openzeppelin/guardian-operator-client'; +import { GuardianOperatorHttpClient, type ModuleAssignment } from '@openzeppelin/guardian-operator-client'; import { Word } from '@miden-sdk/miden-sdk'; import { fetchWithCookieJar } from '../cookieJar.js'; @@ -85,6 +85,31 @@ export async function setAccountPaused( } } +/** + * Replaces the account's policy module assignments as the operator that holds + * `policies:write`; an empty list clears them. Mirrors `Operator::assign` and + * `Operator::clear` in the Rust driver. + */ +export async function setAccountModules( + context: ActionContext, + accountId: string, + modules: ModuleAssignment[], +): Promise { + const result = await login(context, 'reader'); + if ('failure' in result) return result.failure; + + try { + await result.client.setAccountModules(accountId, modules, 'qualification: policy module scenario'); + return null; + } catch (error) { + return { + kind: 'failed', + classification: 'product', + reason: `assigning policy modules to ${accountId} was refused: ${String(error)}`, + }; + } +} + export async function assertSession(context: ActionContext): Promise { const result = await login(context, 'reader'); if ('failure' in result) return result.failure; diff --git a/packages/miden-multisig-client/tests/qualification/fixtures.ts b/packages/miden-multisig-client/tests/qualification/fixtures.ts index 881593aa..99405adc 100644 --- a/packages/miden-multisig-client/tests/qualification/fixtures.ts +++ b/packages/miden-multisig-client/tests/qualification/fixtures.ts @@ -32,6 +32,15 @@ export function readFixtureDelta(): { delta_payload: { data: string }; nonce: nu return readFixture('delta_1.json') as { delta_payload: { data: string }; nonce: number }; } +/** + * The first threshold-only fixture delta, which the policy module scenarios + * propose: `delta_1` adds a signer without the approver scheme entry a real + * add-signer writes, and the Guardian cannot build a module's view from it. + */ +export function readThresholdDelta(): { delta_payload: { data: string }; nonce: number } { + return readFixture('queue_1.json') as { delta_payload: { data: string }; nonce: number }; +} + export interface FixtureAccount { readonly account_id: string; readonly data: string; diff --git a/packages/miden-multisig-client/tests/qualification/runner.ts b/packages/miden-multisig-client/tests/qualification/runner.ts index 2448b9f8..14610e10 100644 --- a/packages/miden-multisig-client/tests/qualification/runner.ts +++ b/packages/miden-multisig-client/tests/qualification/runner.ts @@ -9,6 +9,7 @@ import { assertSession, } from './actions/operator.js'; import { assertHttpEnvelope } from './actions/errorEnvelope.js'; +import { assertRefusal as assertModuleRefusal } from './actions/modules.js'; import { isEnvironmental } from './environment.js'; import { buildResult } from './report.js'; import type { Classification, Runtime, Scenario, ScenarioResult } from './types.js'; @@ -63,6 +64,7 @@ export const HANDLERS: Readonly> = { 'operator-denial': assertDenial, 'operator-logout': assertLogout, 'operator-allowlist-reload': assertAllowlistReload, + 'module-refusal': assertModuleRefusal, }; /** @@ -195,6 +197,10 @@ async function runLiveAction( return live.lowerProcedureThreshold(context, scenario.id); case 'procedure-threshold-assert': return live.assertProcedureThreshold(context, scenario.id); + case 'module-cap-assign': + return live.assignModuleCap(context, scenario.id); + case 'module-cap-refuses': + return live.assertModuleCapRefuses(context, scenario.id); default: return null; } diff --git a/qualification/README.md b/qualification/README.md index 623f7c77..2fb6a090 100644 --- a/qualification/README.md +++ b/qualification/README.md @@ -55,6 +55,9 @@ that ships with the driver is a switch that can be left on. | Declared cosigner schemes are not checked against the state | in `configure_account.rs`, compare the declared and stored auth by commitments only | `det-mixed-scheme-account`: `failed` / `product`, naming the single-scheme ECDSA declaration it registered | | Registration on a GUARDIAN that released the account does not wait for the switch transaction to land | remove the `wait_for_on_chain_state` / `waitForOnChainState` call before registering in the switch flow (`crates/miden-multisig-client/src/client/helpers.rs`, `packages/miden-multisig-client/src/multisig.ts`) | `live-guardian-switch-back-2of3-falcon`, both SDKs: `failed` / `product`, naming the registration GUARDIAN refused because the account's latest transaction has not reached the chain | | A GUARDIAN-executed private note can be exported only by the client that executed it | in `crates/miden-multisig-client/src/client/io.rs`, make `export_p2id_note_to_bytes` return `self.export_note_to_bytes(¬e.id().to_hex())` (the local output-note record) | `live-guardian-execute-private-p2id-2of3-falcon` (Rust): `failed` / `product`, naming the output note not found in the local store | +| A policy module's switch does not survive a restart | run the post-restart pass of `det-module-break-glass` twice, so the second finds the switch it re-enabled | `det-module-break-glass`: `failed` / `product`, naming `qual-switch` read as enabled after the restart | +| A stopped remote module still decides | stop the driver's module by aborting its task instead of shutting it down (accepted connections keep answering) | `det-module-unavailable`: `failed` / `product`, naming the denial where `qual-remote` unavailable was due | +| The TypeScript client signs the proposal check as an untagged request | in `packages/guardian-client/src/http.ts`, send `checkDeltaProposal` through `fetchAuthenticated` and rebuild its `dist` | `det-module-refusal` (TypeScript): `failed` / `product`, naming the 401 on the check | | A delta push is signed by the wallet while a session is active | in `crates/client/src/client.rs`, send `push_delta` with `send_with_replay_retry`; in `packages/guardian-client/src/http.ts`, drop `'session'` from `pushDelta` and rebuild its `dist` | `live-session-execute-2of3-ecdsa`, both SDKs: `failed` / `product`, naming the one Guardian request the key managers (Rust) or wallets (TypeScript) signed while a session was active | ```bash diff --git a/qualification/manifest/manifest.json b/qualification/manifest/manifest.json index 7ecf4c06..554e1b72 100644 --- a/qualification/manifest/manifest.json +++ b/qualification/manifest/manifest.json @@ -148,6 +148,57 @@ "step_budget": "PT1M", "title": "A paused account refuses a proposal, and pausing goes through the operator surface" }, + { + "actions": [ + "account-register", + "module-refusal" + ], + "core": false, + "id": "det-module-refusal", + "mode": "n/a", + "profile": "deterministic", + "required": true, + "runtime": "server-side", + "scheme": "n/a", + "sdk": "both", + "shape": "n/a", + "step_budget": "PT1M30S", + "title": "An assigned policy module refuses a proposal with its id and reason, and stops once unassigned" + }, + { + "actions": [ + "account-register", + "module-unavailable" + ], + "core": false, + "id": "det-module-unavailable", + "mode": "n/a", + "profile": "deterministic", + "required": true, + "runtime": null, + "scheme": "n/a", + "sdk": "rust", + "shape": "n/a", + "step_budget": "PT1M30S", + "title": "A remote policy module decides over TLS, refuses as unavailable while down, and disabling it is the way out" + }, + { + "actions": [ + "account-register", + "module-break-glass" + ], + "core": false, + "id": "det-module-break-glass", + "mode": "n/a", + "profile": "deterministic", + "required": true, + "runtime": null, + "scheme": "n/a", + "sdk": "rust", + "shape": "n/a", + "step_budget": "PT1M30S", + "title": "Disabling a refusing module lets the account through, and the switch survives a restart" + }, { "actions": [ "account-register", @@ -858,6 +909,31 @@ "step_budget": "PT8M", "title": "The multisig sends assets out and the vault reflects it" }, + { + "actions": [ + "account-create", + "account-register", + "asset-transfer", + "note-consume", + "module-cap-assign", + "module-cap-refuses", + "asset-send", + "proposal-sign", + "proposal-execute", + "asset-send-assert" + ], + "core": false, + "id": "live-module-cap-1of1-ecdsa", + "mode": "online", + "profile": "live", + "required": true, + "runtime": "server-side", + "scheme": "ecdsa", + "sdk": "both", + "shape": "1-of-1", + "step_budget": "PT8M", + "title": "A per-account amount cap refuses a payment over it, and a payment at the cap lands with its fee" + }, { "actions": [ "account-create", diff --git a/qualification/manifest/matrix.toml b/qualification/manifest/matrix.toml index fb9de971..55691c0e 100644 --- a/qualification/manifest/matrix.toml +++ b/qualification/manifest/matrix.toml @@ -58,6 +58,7 @@ excluded_scenarios = [ "live-candidate-queue-chained-1of1-ecdsa", "live-candidate-queue-stranded-head-1of1-ecdsa", "live-send-override-p2id-2of3-falcon", + "live-module-cap-1of1-ecdsa", ] [[pair]] @@ -95,4 +96,5 @@ excluded_scenarios = [ "live-candidate-queue-chained-1of1-ecdsa", "live-candidate-queue-stranded-head-1of1-ecdsa", "live-send-override-p2id-2of3-falcon", + "live-module-cap-1of1-ecdsa", ] diff --git a/qualification/manifest/scenarios.toml b/qualification/manifest/scenarios.toml index 86849908..33a4e839 100644 --- a/qualification/manifest/scenarios.toml +++ b/qualification/manifest/scenarios.toml @@ -127,6 +127,60 @@ step_budget = "60s" required = true core = false +# Policy modules (RFC 0002). The stack's catalog (qualification/stack/lib/modules.sh) scopes +# every instance `assigned`, so a module applies only to an account a scenario assigns it to. +# The scenarios propose a fixture threshold change and assign a signer allowlist that names +# none of the account's signers. +# +# Both SDKs: the Rust leg meets the refusal over gRPC and the TypeScript leg over HTTP, at the +# dry-run check and at creation, and each clears its assignment on every path because the +# fixture account is shared. +[[scenario]] +id = "det-module-refusal" +title = "An assigned policy module refuses a proposal with its id and reason, and stops once unassigned" +profile = "deterministic" +sdk = "both" +runtime = "server-side" +scheme = "n/a" +shape = "n/a" +mode = "n/a" +actions = ["account-register", "module-refusal"] +step_budget = "90s" +required = true +core = false + +# Rust only: the driver serves the remote module (basic-policy over TLS, its token read from the +# Guardian's file secrets backend), so the scenario can take it down. Fail-closed while down, +# naming the instance, and disabling it lets the account through. +[[scenario]] +id = "det-module-unavailable" +title = "A remote policy module decides over TLS, refuses as unavailable while down, and disabling it is the way out" +profile = "deterministic" +sdk = "rust" +scheme = "n/a" +shape = "n/a" +mode = "n/a" +actions = ["account-register", "module-unavailable"] +step_budget = "90s" +required = true +core = false + +# Rust only, like det-restart-durability: the operator's disable has to outlive the process, +# so the first pass disables and the pass after the restart finds it disabled against a catalog +# that still says enabled, with the disable in the params history, and enables it again. +[[scenario]] +id = "det-module-break-glass" +title = "Disabling a refusing module lets the account through, and the switch survives a restart" +profile = "deterministic" +sdk = "rust" +scheme = "n/a" +shape = "n/a" +mode = "n/a" +actions = ["account-register", "module-break-glass"] +step_budget = "90s" +required = true +core = false + # Both SDKs: the Rust leg reaches the refusal over gRPC and the TypeScript leg over HTTP, and # this is the only deterministic coverage of the HTTP execution routes. [[scenario]] @@ -710,6 +764,26 @@ step_budget = "480s" required = true core = false +# A policy module on a real transaction. The deterministic module scenarios use a fixture +# summary; this one caps a payment the account actually sends, so the module sees what the +# network builds, fee note included. The cap is exactly what `asset-send` sends: one unit more +# is refused at the check and at creation, the capped amount passes, and the approval hook runs +# again when GUARDIAN signs at execution. The transaction pays its fee in the same asset, so a +# fee note counted as a payment would push the capped send over and fail it. +[[scenario]] +id = "live-module-cap-1of1-ecdsa" +title = "A per-account amount cap refuses a payment over it, and a payment at the cap lands with its fee" +profile = "live" +sdk = "both" +runtime = "server-side" +scheme = "ecdsa" +shape = "1-of-1" +mode = "online" +actions = ["account-create", "account-register", "asset-transfer", "note-consume", "module-cap-assign", "module-cap-refuses", "asset-send", "proposal-sign", "proposal-execute", "asset-send-assert"] +step_budget = "480s" +required = true +core = false + # The config-writing procedures encode the signature scheme into the advice # payload they build, and two scheme-binding defects have already been found # here (F8, F13). Running membership changes on one scheme only would leave an diff --git a/qualification/stack/compose.yml b/qualification/stack/compose.yml index cdd2b8b1..673f58c6 100644 --- a/qualification/stack/compose.yml +++ b/qualification/stack/compose.yml @@ -20,7 +20,12 @@ services: volumes: - ${QUAL_ACK_KEYS_DIR:?set QUAL_ACK_KEYS_DIR}:/var/guardian/ack-keys:ro - ${QUAL_OPERATOR_DIR:?set QUAL_OPERATOR_DIR}:/var/guardian/operator:ro + - ${QUAL_MODULES_DIR:?set QUAL_MODULES_DIR}:/var/guardian/modules:ro + - ${QUAL_MODULE_SECRETS_DIR:?set QUAL_MODULE_SECRETS_DIR}:/var/guardian/module-secrets:ro - guardian-keystore:/var/guardian/keystore + # The remote policy module is served by the Rust driver on the host. + extra_hosts: + - "host.docker.internal:host-gateway" environment: - RUST_LOG=${QUAL_RUST_LOG:-info} - GUARDIAN_NETWORK_TYPE=${QUAL_NETWORK_TYPE:?set QUAL_NETWORK_TYPE} @@ -40,6 +45,11 @@ services: - GUARDIAN_DASHBOARD_COMMITMENT_RATE_BURST_PER_SEC=${QUAL_DASHBOARD_RATE_BURST_PER_SEC:-100} - GUARDIAN_DASHBOARD_COMMITMENT_RATE_PER_MIN=${QUAL_DASHBOARD_RATE_PER_MIN:-2000} - GUARDIAN_OPERATOR_PUBLIC_KEYS_FILE=/var/guardian/operator/operators.json + # Policy modules, all scoped to the accounts a scenario assigns them to + # (qualification/stack/lib/modules.sh). + - GUARDIAN_MODULES_CONFIG=/var/guardian/modules/catalog.toml + - GUARDIAN_MODULE_SECRET_PROVIDER=file + - GUARDIAN_MODULE_SECRET_DIR=/var/guardian/module-secrets # Scraped once a run's scenarios finish, so the execution timings of a live run (chain # view and proving) are kept with its results as the recorded baseline. - GUARDIAN_METRICS_ENABLED=true diff --git a/qualification/stack/lib/env.sh b/qualification/stack/lib/env.sh index aa25d5c3..912c4f0c 100644 --- a/qualification/stack/lib/env.sh +++ b/qualification/stack/lib/env.sh @@ -45,6 +45,8 @@ qual_generate_env() { QUAL_HTTP_PORT_E="${QUAL_HTTP_PORT_E:-$(qual_free_port)}" QUAL_GRPC_PORT_E="${QUAL_GRPC_PORT_E:-$(qual_free_port)}" QUAL_METRICS_PORT="${QUAL_METRICS_PORT:-$(qual_free_port)}" + # Where the Rust driver serves the remote policy module, on the host. + QUAL_MODULE_PORT="${QUAL_MODULE_PORT:-$(qual_free_port)}" # The queue server's depth. The deterministic profile has three chained # fixture deltas, so a depth of two is the deepest it can fill and still # refuse the next one; the live chained scenario pushes three transactions @@ -59,7 +61,11 @@ qual_generate_env() { QUAL_ACK_KEYS_DIR="${run_dir}/ack-keys" QUAL_ACK_KEYS_MIGRATION_DIR="${run_dir}/ack-keys-migration-target" QUAL_OPERATOR_DIR="${run_dir}/operator" - mkdir -p "${QUAL_ACK_KEYS_DIR}" "${QUAL_ACK_KEYS_MIGRATION_DIR}" "${QUAL_OPERATOR_DIR}" + QUAL_MODULES_DIR="${run_dir}/modules" + QUAL_MODULE_SECRETS_DIR="${run_dir}/module-secrets" + QUAL_MODULE_TLS_DIR="${run_dir}/module-tls" + mkdir -p "${QUAL_ACK_KEYS_DIR}" "${QUAL_ACK_KEYS_MIGRATION_DIR}" "${QUAL_OPERATOR_DIR}" \ + "${QUAL_MODULES_DIR}" "${QUAL_MODULE_SECRETS_DIR}" "${QUAL_MODULE_TLS_DIR}" cat > "${out}" </dev/null 2>&1 || return 1 + openssl req -newkey rsa:2048 -nodes -subj "/CN=${QUAL_MODULE_HOST}" \ + -keyout "${tls_dir}/key.pem" -out "${tls_dir}/request.csr" >/dev/null 2>&1 || return 1 + printf 'subjectAltName=DNS:%s\nbasicConstraints=CA:FALSE\nextendedKeyUsage=serverAuth\n' \ + "${QUAL_MODULE_HOST}" > "${tls_dir}/extensions.cnf" + openssl x509 -req -days 2 -in "${tls_dir}/request.csr" \ + -CA "${catalog_dir}/module-ca.pem" -CAkey "${tls_dir}/ca-key.pem" -CAcreateserial \ + -extfile "${tls_dir}/extensions.cnf" -out "${tls_dir}/cert.pem" >/dev/null 2>&1 || return 1 + rm -f "${tls_dir}/request.csr" "${tls_dir}/extensions.cnf" "${tls_dir}/ca-key.pem" \ + "${catalog_dir}/module-ca.srl" "${tls_dir}/module-ca.srl" + + qual_random_suffix > "${secrets_dir}/${QUAL_MODULE_TOKEN_SECRET}" + cp "${secrets_dir}/${QUAL_MODULE_TOKEN_SECRET}" "${tls_dir}/token" + chmod 600 "${secrets_dir}/${QUAL_MODULE_TOKEN_SECRET}" "${tls_dir}/token" "${tls_dir}/key.pem" + + cat > "${catalog_dir}/catalog.toml" < writing the policy module catalog" +if ! qual_write_module_catalog "${QUAL_MODULES_DIR}" "${QUAL_MODULE_SECRETS_DIR}" \ + "${QUAL_MODULE_TLS_DIR}" "${QUAL_MODULE_PORT}"; then + echo "error: the policy module catalog or its certificates could not be written" >&2 + exit "${EXIT_SETUP_FAILURE}" +fi + qual_install_teardown_trap "${QUAL_PROJECT}" "${COMPOSE_FILE}" "${ENV_FILE}" "${RUN_DIR}" # Redaction runs over everything retained, not just diagnostics, and the scan diff --git a/qualification/stack/tests/harness-test.sh b/qualification/stack/tests/harness-test.sh index a18451f1..d5eb3c4a 100755 --- a/qualification/stack/tests/harness-test.sh +++ b/qualification/stack/tests/harness-test.sh @@ -19,6 +19,8 @@ source "${STACK_DIR}/lib/redact.sh" source "${STACK_DIR}/lib/pairing.sh" # shellcheck source=../lib/phase.sh source "${STACK_DIR}/lib/phase.sh" +# shellcheck source=../lib/modules.sh +source "${STACK_DIR}/lib/modules.sh" PASSED=0 FAILED=0 @@ -58,6 +60,8 @@ compose_accepts_project() { QUAL_ACK_KEYS_DIR=/tmp/qual-test/ack-keys \ QUAL_ACK_KEYS_MIGRATION_DIR=/tmp/qual-test/ack-keys-migration-target \ QUAL_OPERATOR_DIR=/tmp/qual-test/operator \ + QUAL_MODULES_DIR=/tmp/qual-test/modules \ + QUAL_MODULE_SECRETS_DIR=/tmp/qual-test/module-secrets \ docker compose -p "${project}" -f "${STACK_DIR}/compose.yml" config >/dev/null 2>&1 } @@ -323,6 +327,30 @@ assert_eq "a stopped qualification project is reaped" "qual-dead" "$(reap_candid assert_not_contains "a running qualification project is left alone" "$(reap_candidates "${LS_JSON}")" "qual-live" assert_not_contains "an unrelated project is left alone" "$(reap_candidates "${LS_JSON}")" "other" +echo "policy module catalog" +MODULE_RUN="$(mktemp -d)" +if qual_write_module_catalog "${MODULE_RUN}/modules" "${MODULE_RUN}/secrets" "${MODULE_RUN}/tls" 40123; then + pass "the catalog and its certificates are written" + assert_contains "the remote instance points at the driver's port" \ + "$(cat "${MODULE_RUN}/modules/catalog.toml")" 'endpoint = "grpc://host.docker.internal:40123"' + assert_eq "the Guardian and the driver share one token" \ + "$(cat "${MODULE_RUN}/secrets/qual-remote-token")" "$(cat "${MODULE_RUN}/tls/token")" + # The file secrets backend refuses a token anyone but its owner can read. + assert_eq "the token is owner-only" "600" \ + "$(stat -f '%Lp' "${MODULE_RUN}/secrets/qual-remote-token" 2>/dev/null || stat -c '%a' "${MODULE_RUN}/secrets/qual-remote-token")" + if openssl verify -CAfile "${MODULE_RUN}/modules/module-ca.pem" -verify_hostname host.docker.internal \ + "${MODULE_RUN}/tls/cert.pem" >/dev/null 2>&1; then + pass "the module certificate verifies for host.docker.internal under the catalog's CA" + else + fail "the module certificate verifies for host.docker.internal under the catalog's CA" + fi + assert_eq "the CA key does not outlive the run setup" "absent" \ + "$([[ -e "${MODULE_RUN}/tls/ca-key.pem" ]] && echo present || echo absent)" +else + fail "the catalog and its certificates are written" "qual_write_module_catalog failed" +fi +rm -rf "${MODULE_RUN}" + echo printf 'passed %d, failed %d, skipped %d\n' "${PASSED}" "${FAILED}" "${SKIPPED}" [[ "${FAILED}" -eq 0 ]] From 84267d3a15c0702bcc32ec996d4aad8e388ea7be Mon Sep 17 00:00:00 2001 From: Zeljko Date: Tue, 10 Nov 2026 07:34:18 +0100 Subject: [PATCH 069/105] fix(server): check the delta account id on every apply path (#251) Applying a delta already compares its account id with the stored account on the update path. Do the same when a delta is verified and when it creates the account, and cover it with a test. Same change as #592 on main. --- crates/server/src/network/miden/mod.rs | 76 +++++++++++++++++++++++++- 1 file changed, 75 insertions(+), 1 deletion(-) diff --git a/crates/server/src/network/miden/mod.rs b/crates/server/src/network/miden/mod.rs index e077f4d9..9dfbf3f3 100644 --- a/crates/server/src/network/miden/mod.rs +++ b/crates/server/src/network/miden/mod.rs @@ -346,6 +346,15 @@ impl MidenNetworkClient { ) -> Result { let account_delta = tx_summary.account_delta(); + if let Ok(account) = prev_account.as_ref() + && account.id() != account_delta.id() + { + return Err(format!( + "account delta ID mismatch: expected {}, got {}", + account.id().to_hex(), + account_delta.id().to_hex() + )); + } let is_full_state = !account_delta.code().is_empty() && prev_account.as_ref().map_or(true, Account::is_new); let base_account = if is_full_state { @@ -532,8 +541,15 @@ impl NetworkClient for MidenNetworkClient { prev_state_json: &serde_json::Value, delta_payload: &serde_json::Value, ) -> Result<(), String> { - TransactionSummary::from_json(delta_payload)?; + let tx_summary = TransactionSummary::from_json(delta_payload)?; let account = Account::from_json(prev_state_json)?; + if account.id() != tx_summary.account_delta().id() { + return Err(format!( + "account delta ID mismatch: expected {}, got {}", + account.id().to_hex(), + tx_summary.account_delta().id().to_hex() + )); + } Self::ensure_prev_commitment(&account, prev_commitment) } @@ -2522,4 +2538,62 @@ mod tests { applied.nonce ); } + #[tokio::test] + async fn a_creation_delta_of_another_account_is_refused() { + use miden_protocol::Felt; + use miden_protocol::account::delta::AccountVaultDelta; + use miden_protocol::account::{AccountBuilder, AccountType}; + use miden_protocol::account::{AccountCodePatch, AccountDelta}; + use miden_standards::account::auth::NoAuth; + use miden_standards::account::wallets::BasicWallet; + + let client = MidenNetworkClient::lazy_for_test(NetworkType::MidenTestnet); + let build = |seed: u8| { + AccountBuilder::new([seed; 32]) + .account_type(AccountType::Public) + .with_component(BasicWallet) + .with_component(NoAuth) + .build() + .expect("Failed to build account") + }; + let stored = build(0xAB); + let other = build(0xCD); + assert!(stored.is_new()); + assert_ne!(stored.id(), other.id()); + + let creation_of_other = AccountDelta::new( + other.id(), + miden_protocol::account::AccountStoragePatch::default(), + AccountVaultDelta::default(), + AccountCodePatch::new(Some(other.code().clone())), + Felt::new_unchecked(1), + ) + .expect("Failed to create delta"); + let payload = TransactionSummary::new( + creation_of_other, + InputNotes::new(Vec::new()).expect("empty input notes"), + RawOutputNotes::new(Vec::new()).expect("empty output notes"), + miden_protocol::block::BlockNumber::from(0), + Word::default(), + 0, + TransactionSummaryUserParams::new([Felt::ZERO; 6]), + ) + .to_json(); + + let stored_json = stored.to_json(); + let stored_commitment = format!("0x{}", hex::encode(stored.to_commitment().as_bytes())); + for refused in [ + client + .verify_and_apply_delta(&stored_commitment, &stored_json, &payload) + .map(|_| ()), + client.verify_delta(&stored_commitment, &stored_json, &payload), + client + .apply_delta_with_module_views(Some(&stored_commitment), &stored_json, &payload) + .map(|_| ()), + client.apply_delta(&stored_json, &payload).map(|_| ()), + ] { + let error = refused.expect_err("another account's creation delta must be refused"); + assert!(error.contains("account delta ID mismatch"), "{error}"); + } + } } From d7019cde7af20a9c1af8a88cf7be45bd2ec36509 Mon Sep 17 00:00:00 2001 From: Zeljko Date: Tue, 10 Nov 2026 07:34:18 +0100 Subject: [PATCH 070/105] feat(module-sdk)!: protocol version 1 reopened and corrected (#251) Version 1 freezes with the first published guardian-module-sdk release, not before: nothing was published or deployed, and a review found fields that did not carry what they said. - Decision is effect-only: the legacy allow field and the decision.effect capability are gone, and a decision without an effect is a module failure. - MidenTransaction carries bound_block, expiration_delta and approval_expiration_block in place of reference_block and expiration_block; nonce_delta is unsigned. - network_id, initial_state and tx_fee comments say what the Guardian sends. - basic-policy: ids must be hex digits after 0x, a cap naming one faucet twice is refused, and deny_unknown_recipients, signer_check and code_check are refused without the list they modify. - serve: an empty registered token matches nothing. --- crates/guardian-module-sdk/README.md | 2 +- .../examples/note_policy/mod.rs | 4 +- .../proto/guardian_module_v1.proto | 25 +-- .../guardian-module-sdk/src/basic_policy.rs | 163 ++++++++++-------- crates/guardian-module-sdk/src/conformance.rs | 2 +- crates/guardian-module-sdk/src/lib.rs | 9 +- crates/guardian-module-sdk/src/serve.rs | 5 +- .../guardian-module-sdk/tests/conformance.rs | 16 +- .../contracts/guardian_module_v1.proto | 25 +-- 9 files changed, 140 insertions(+), 111 deletions(-) diff --git a/crates/guardian-module-sdk/README.md b/crates/guardian-module-sdk/README.md index 92c6544f..834faeba 100644 --- a/crates/guardian-module-sdk/README.md +++ b/crates/guardian-module-sdk/README.md @@ -123,7 +123,7 @@ auth = { token_secret = "guardian/modules/no-private-notes-token" } ```toml [dev-dependencies] -guardian-module-sdk = { version = "0.19", features = ["conformance"] } +guardian-module-sdk = { version = "0.19.0-rc.1", features = ["conformance"] } ``` ```rust diff --git a/crates/guardian-module-sdk/examples/note_policy/mod.rs b/crates/guardian-module-sdk/examples/note_policy/mod.rs index 26e938c0..58a67a6a 100644 --- a/crates/guardian-module-sdk/examples/note_policy/mod.rs +++ b/crates/guardian-module-sdk/examples/note_policy/mod.rs @@ -143,7 +143,7 @@ mod tests { .evaluate(&request(params.clone(), one_payment)) .await .unwrap() - .allow + .allows() ); let two_payments = vec![note(NoteType::Public, false), note(NoteType::Public, false)]; let decision = NotePolicy @@ -169,7 +169,7 @@ mod tests { .evaluate(&request(serde_json::json!({}), notes)) .await .unwrap() - .allow + .allows() ); } diff --git a/crates/guardian-module-sdk/proto/guardian_module_v1.proto b/crates/guardian-module-sdk/proto/guardian_module_v1.proto index d1d374ec..ddff9f47 100644 --- a/crates/guardian-module-sdk/proto/guardian_module_v1.proto +++ b/crates/guardian-module-sdk/proto/guardian_module_v1.proto @@ -1,6 +1,7 @@ -// guardian.module.v1, extracted from docs/rfcs/0002-guardian-modules.md section 3 (revision 28). +// guardian.module.v1, extracted from docs/rfcs/0002-guardian-modules.md section 3 (revision 32). // The proto in RFC section 3 is authoritative; regenerate this file when it changes. -// Protocol version 1 is frozen (2026-11-09, at e4efd839): changes within it are additive only (RFC section 3.5). +// Protocol version 1 is not frozen yet: it freezes with the first published guardian-module-sdk +// release, and from then on changes within it are additive only (RFC section 3.5). syntax = "proto3"; package guardian.module.v1; @@ -51,7 +52,7 @@ message HookRequest { Hook hook = 2; bool dry_run = 3; // a policy check: nothing is stored or signed whatever the decision (section 2.7) string network = 4; // network family: "miden" - string network_id = 5; // the account's network within the family: "mainnet", "testnet", "devnet", "cedar" or "local" (section 3.1) + string network_id = 5; // the network this Guardian serves within the family: "mainnet", "testnet", "devnet", "cedar" or "local"; from its own configuration, never from the request (section 3.1) string account_id = 6; string instance_id = 7; // catalog id of the instance being called bytes params = 8; // UTF-8 JSON, params of the layer being evaluated (global, account layer, or the account's own for default/assigned) @@ -102,21 +103,20 @@ enum PendingState { } message RegistrationSubject { - AccountStateProjection initial_state = 1; // the account about to be accepted, per network + AccountStateProjection initial_state = 1; // the account about to be accepted, per network: its whole vault and storage } enum Effect { - EFFECT_UNSPECIFIED = 0; // a module that does not set `effect`: `allow` decides + EFFECT_UNSPECIFIED = 0; // never a decision: a module failure EFFECT_ALLOW = 1; EFFECT_DENY = 2; } message Decision { - bool allow = 1; // read only when effect is unspecified + Effect effect = 1; // unspecified, or a value the Guardian does not know, is a module failure string reason_code = 2; // required on a deny; ignored on an allow string message = 3; // logged, never forwarded to clients - Effect effect = 4; // wins over allow when set; a value the Guardian does not know is a module failure - string client_message = 5; // optional, plain text, at most 256 characters; forwarded only where the instance allows it (section 2.7) + string client_message = 4; // optional, plain text, at most 256 characters; forwarded only where the instance allows it (section 2.7) } // A transaction as its network describes it. One variant per network; a module reads the @@ -141,14 +141,15 @@ message RawTransaction { } message MidenTransaction { - int64 nonce_delta = 1; - uint32 reference_block = 2; // the block the transaction was executed against - optional uint32 expiration_block = 3; // absent when the transaction sets no expiration (section 3.1) + uint64 nonce_delta = 1; + uint32 bound_block = 2; // the block the summary binds; the transaction executes against this block or a later one (section 3.1) + optional uint32 expiration_delta = 3; // blocks after the block the transaction executes against at which it expires; absent when its script sets none. Not an absolute height: that block is not known at approval (section 3.1) repeated VaultChange vault_changes = 4; repeated OutputNote output_notes = 5; repeated InputNote input_notes = 6; repeated StorageChange storage_changes = 7; optional string new_code_commitment = 8; // set when the transaction replaces the account's code (section 3.1) + optional uint64 approval_expiration_block = 9; // the block at which the cosigners' approval of this transaction lapses; absent when it never lapses (section 3.1) } message MidenAccountState { @@ -172,7 +173,7 @@ message OutputNote { repeated Asset assets = 5; string script_root = 6; optional string p2id_target = 7; // set only for known P2ID / P2IDE scripts - bool tx_fee = 8; // the fee note pay_fee creates; not a payment (section 3.1: set only for that one note) + bool tx_fee = 8; // the fee note pay_fee creates; not a payment (section 3.1: set only for that one note, and only while it carries no more of the fee asset than a transaction can owe) } enum NoteType { NOTE_TYPE_UNSPECIFIED = 0; NOTE_TYPE_PUBLIC = 1; NOTE_TYPE_PRIVATE = 2; } diff --git a/crates/guardian-module-sdk/src/basic_policy.rs b/crates/guardian-module-sdk/src/basic_policy.rs index b2f80787..9008370a 100644 --- a/crates/guardian-module-sdk/src/basic_policy.rs +++ b/crates/guardian-module-sdk/src/basic_policy.rs @@ -49,11 +49,11 @@ pub struct Params { #[serde(default)] pub signer_denylist: Option>, #[serde(default)] - pub signer_check: SignerCheck, + pub signer_check: Option, #[serde(default)] pub allowed_code_commitments: Option>, #[serde(default)] - pub code_check: CodeCheck, + pub code_check: Option, } struct Policy { @@ -87,8 +87,8 @@ fn normalized(values: &[String]) -> BTreeSet { } /// Ids in the hex form the Guardian reports them in (`0x` and hex digits), lowercased. Any other -/// spelling, a bech32 address for one, would never match a request, so a denylist or a cap would -/// silently not apply; it is refused instead. +/// spelling, a bech32 address or a placeholder left in an example catalog for one, would never +/// match a request, so a denylist or a cap would silently not apply; it is refused instead. fn ids(field: &str, values: &[String]) -> Result, String> { values.iter().map(|value| id(field, value)).collect() } @@ -98,9 +98,7 @@ fn id(field: &str, value: &str) -> Result { .strip_prefix("0x") .or_else(|| value.strip_prefix("0X")) { - Some(rest) - if !rest.is_empty() && rest.bytes().all(|b| b.is_ascii_alphanumeric() || b == b'_') => - { + Some(rest) if !rest.is_empty() && rest.bytes().all(|b| b.is_ascii_hexdigit()) => { Ok(value.to_ascii_lowercase()) } _ => Err(format!( @@ -113,17 +111,35 @@ impl TryFrom for Policy { type Error = String; fn try_from(params: Params) -> Result { - let caps = params - .max_amount_per_tx - .into_iter() - .map(|(faucet, amount)| { - let faucet = id("max_amount_per_tx", &faucet)?; - amount - .parse::() - .map(|amount| (faucet.clone(), amount)) - .map_err(|_| format!("max_amount_per_tx for {faucet} is not a decimal amount")) - }) - .collect::>()?; + let mut caps = BTreeMap::new(); + for (faucet, amount) in params.max_amount_per_tx { + let faucet = id("max_amount_per_tx", &faucet)?; + let amount = amount + .parse::() + .map_err(|_| format!("max_amount_per_tx for {faucet} is not a decimal amount"))?; + if caps.insert(faucet.clone(), amount).is_some() { + return Err(format!( + "max_amount_per_tx names {faucet} more than once (ids are compared in lowercase)" + )); + } + } + if params.deny_unknown_recipients && params.recipient_denylist.is_none() { + return Err( + "deny_unknown_recipients applies to recipient_denylist, which is not set".into(), + ); + } + if params.signer_check.is_some() + && params.signer_allowlist.is_none() + && params.signer_denylist.is_none() + { + return Err( + "signer_check applies to signer_allowlist or signer_denylist, neither of which is set" + .into(), + ); + } + if params.code_check.is_some() && params.allowed_code_commitments.is_none() { + return Err("code_check applies to allowed_code_commitments, which is not set".into()); + } let signers = match (params.signer_allowlist, params.signer_denylist) { (Some(_), Some(_)) => { return Err("signer_allowlist and signer_denylist are mutually exclusive".into()); @@ -151,13 +167,13 @@ impl TryFrom for Policy { .transpose()?, deny_unknown_recipients: params.deny_unknown_recipients, signers, - signer_check: params.signer_check, + signer_check: params.signer_check.unwrap_or_default(), code: params .allowed_code_commitments .as_deref() .map(|list| ids("allowed_code_commitments", list)) .transpose()?, - code_check: params.code_check, + code_check: params.code_check.unwrap_or_default(), }) } } @@ -430,8 +446,8 @@ mod tests { fn tx_request(params: serde_json::Value, projection: MidenTransaction) -> HookRequest { HookRequest { params: serde_json::to_vec(¶ms).unwrap(), - before: Some(view(&["0xs1"])), - after: Some(view(&["0xs1"])), + before: Some(view(&["0x51"])), + after: Some(view(&["0x51"])), subject: Some(hook_request::Subject::Transaction(TransactionSubject { projection: Some(TransactionProjection::miden(projection)), ..Default::default() @@ -451,23 +467,23 @@ mod tests { #[tokio::test] async fn allows_a_payment_under_the_cap() { let projection = MidenTransaction { - output_notes: vec![p2id("0xr1", vec![fungible(USDC, 500)])], + output_notes: vec![p2id("0xa1", vec![fungible(USDC, 500)])], ..Default::default() }; - assert!(decide(&tx_request(cap(), projection)).await.allow); + assert!(decide(&tx_request(cap(), projection)).await.allows()); } #[tokio::test] async fn sums_split_payments_against_the_cap() { let projection = MidenTransaction { output_notes: vec![ - p2id("0xr1", vec![fungible(USDC, 600)]), - p2id("0xr2", vec![fungible(USDC, 600)]), + p2id("0xa1", vec![fungible(USDC, 600)]), + p2id("0xa2", vec![fungible(USDC, 600)]), ], ..Default::default() }; let decision = decide(&tx_request(cap(), projection)).await; - assert!(!decision.allow); + assert!(!decision.allows()); assert_eq!(decision.reason_code, "amount_cap_exceeded"); } @@ -479,26 +495,26 @@ mod tests { direction: crate::Direction::Out as i32, }], input_notes: vec![crate::InputNote { - note_id: "0xin".into(), + note_id: "0x14".into(), assets: vec![fungible(USDC, 1000)], }], - output_notes: vec![p2id("0xr1", vec![fungible(USDC, 1500)])], + output_notes: vec![p2id("0xa1", vec![fungible(USDC, 1500)])], ..Default::default() }; - assert!(!decide(&tx_request(cap(), projection)).await.allow); + assert!(!decide(&tx_request(cap(), projection)).await.allows()); } #[tokio::test] async fn uncapped_assets_and_nfts_are_not_counted() { let nft = Asset { faucet_id: USDC.into(), - value: Some(asset::Value::NftId("0xnft".into())), + value: Some(asset::Value::NftId("0x4f7".into())), }; let projection = MidenTransaction { - output_notes: vec![p2id("0xr1", vec![fungible(ETH, 5000), nft])], + output_notes: vec![p2id("0xa1", vec![fungible(ETH, 5000), nft])], ..Default::default() }; - assert!(decide(&tx_request(cap(), projection)).await.allow); + assert!(decide(&tx_request(cap(), projection)).await.allows()); } fn fee_note(amount: u64) -> OutputNote { @@ -513,13 +529,17 @@ mod tests { #[tokio::test] async fn the_fee_note_is_not_a_payment() { let projection = MidenTransaction { - output_notes: vec![fee_note(5000), p2id("0xr1", vec![fungible(USDC, 500)])], + output_notes: vec![fee_note(5000), p2id("0xa1", vec![fungible(USDC, 500)])], ..Default::default() }; - assert!(decide(&tx_request(cap(), projection.clone())).await.allow); + assert!( + decide(&tx_request(cap(), projection.clone())) + .await + .allows() + ); - let params = json!({ "recipient_allowlist": ["0xr1"], "asset_allowlist": [ETH, USDC] }); - assert!(decide(&tx_request(params, projection)).await.allow); + let params = json!({ "recipient_allowlist": ["0xa1"], "asset_allowlist": [ETH, USDC] }); + assert!(decide(&tx_request(params, projection)).await.allows()); let only_fee = MidenTransaction { output_notes: vec![fee_note(5000)], @@ -528,20 +548,20 @@ mod tests { assert!( decide(&tx_request(json!({ "asset_allowlist": [ETH] }), only_fee)) .await - .allow + .allows() ); } #[tokio::test] async fn recipient_allowlist_denies_partial_and_unlisted_notes() { - let params = json!({ "recipient_allowlist": ["0xr1"] }); + let params = json!({ "recipient_allowlist": ["0xa1"] }); let listed = MidenTransaction { - output_notes: vec![p2id("0xR1", vec![fungible(USDC, 1)])], + output_notes: vec![p2id("0xA1", vec![fungible(USDC, 1)])], ..Default::default() }; - assert!(decide(&tx_request(params.clone(), listed)).await.allow); + assert!(decide(&tx_request(params.clone(), listed)).await.allows()); - let mut partial_note = p2id("0xr1", vec![fungible(USDC, 1)]); + let mut partial_note = p2id("0xa1", vec![fungible(USDC, 1)]); partial_note.partial = true; let partial = MidenTransaction { output_notes: vec![partial_note], @@ -555,17 +575,17 @@ mod tests { ); let unlisted = MidenTransaction { - output_notes: vec![p2id("0xr9", vec![fungible(USDC, 1)])], + output_notes: vec![p2id("0xa9", vec![fungible(USDC, 1)])], ..Default::default() }; - assert!(!decide(&tx_request(params, unlisted)).await.allow); + assert!(!decide(&tx_request(params, unlisted)).await.allows()); } #[tokio::test] async fn asset_allowlist_covers_sent_and_received_assets() { let params = json!({ "asset_allowlist": [USDC] }); let projection = MidenTransaction { - output_notes: vec![p2id("0xr1", vec![fungible(ETH, 1)])], + output_notes: vec![p2id("0xa1", vec![fungible(ETH, 1)])], ..Default::default() }; assert_eq!( @@ -588,13 +608,13 @@ mod tests { "recipient_blocked" ); - let mut partial = p2id("0xr1", vec![fungible(USDC, 1)]); + let mut partial = p2id("0xa1", vec![fungible(USDC, 1)]); partial.partial = true; let unknown = MidenTransaction { - output_notes: vec![p2id("0xr1", vec![fungible(USDC, 1)]), partial], + output_notes: vec![p2id("0xa1", vec![fungible(USDC, 1)]), partial], ..Default::default() }; - assert!(decide(&tx_request(params, unknown.clone())).await.allow); + assert!(decide(&tx_request(params, unknown.clone())).await.allows()); let strict = json!({ "recipient_denylist": ["0xbad"], "deny_unknown_recipients": true }); assert_eq!( @@ -607,14 +627,14 @@ mod tests { #[tokio::test] async fn a_denial_names_its_rule_to_the_client_and_discloses_no_param() { let projection = MidenTransaction { - output_notes: vec![p2id("0xr1", vec![fungible(USDC, 5_000)])], + output_notes: vec![p2id("0xa1", vec![fungible(USDC, 5_000)])], ..Default::default() }; let decision = decide(&tx_request(cap(), projection)).await; assert_eq!(decision.reason_code, "amount_cap_exceeded"); assert!(!decision.client_message.is_empty()); assert!(decision.client_message.len() <= 256); - for detail in ["1000", "5000", USDC, "0xr1"] { + for detail in ["1000", "5000", USDC, "0xa1"] { assert!( !decision.client_message.contains(detail), "{detail} leaked into {:?}", @@ -645,7 +665,7 @@ mod tests { running( HookRequest { params: serde_json::to_vec(¶ms).unwrap(), - after: Some(view(&["0xs1"])), + after: Some(view(&["0x51"])), subject: Some(hook_request::Subject::Registration( RegistrationSubject::default(), )), @@ -665,7 +685,7 @@ mod tests { #[tokio::test] async fn changed_code_check_judges_registration_and_code_replacement_only() { let rule = code_rule("changed"); - assert!(decide(®istration(rule.clone(), REVIEWED)).await.allow); + assert!(decide(®istration(rule.clone(), REVIEWED)).await.allows()); let refused = decide(®istration(rule.clone(), UNREVIEWED)).await; assert_eq!(refused.reason_code, "code_not_allowed"); assert!(!refused.client_message.contains(UNREVIEWED)); @@ -675,13 +695,13 @@ mod tests { UNREVIEWED, ); assert!( - decide(&unchanged).await.allow, + decide(&unchanged).await.allows(), "code an account already runs is kept until it changes" ); let upgrade = tx_request(rule.clone(), replacing_code_with(Some(UNREVIEWED))); assert_eq!(decide(&upgrade).await.reason_code, "code_not_allowed"); let reviewed = tx_request(rule, replacing_code_with(Some(REVIEWED))); - assert!(decide(&reviewed).await.allow); + assert!(decide(&reviewed).await.allows()); } #[tokio::test] @@ -697,7 +717,7 @@ mod tests { REVIEWED, ); assert!( - decide(&upgraded).await.allow, + decide(&upgraded).await.allows(), "an account on unlisted code can still upgrade to listed code" ); } @@ -733,7 +753,7 @@ mod tests { async fn asset_allowlist_covers_consumed_notes() { let projection = MidenTransaction { input_notes: vec![crate::InputNote { - note_id: "0xin".into(), + note_id: "0x14".into(), assets: vec![fungible(ETH, 1)], }], ..Default::default() @@ -752,7 +772,7 @@ mod tests { #[tokio::test] async fn forged_metadata_does_not_change_the_decision() { let projection = MidenTransaction { - output_notes: vec![p2id("0xr1", vec![fungible(USDC, 5000)])], + output_notes: vec![p2id("0xa1", vec![fungible(USDC, 5000)])], ..Default::default() }; let mut request = tx_request(cap(), projection); @@ -761,7 +781,7 @@ mod tests { serde_json::to_vec(&json!({ "proposal_type": "change_threshold", "amount": "1" })) .unwrap(); } - assert!(!decide(&request).await.allow); + assert!(!decide(&request).await.allows()); } fn signer_request( @@ -782,31 +802,31 @@ mod tests { #[tokio::test] async fn added_mode_checks_only_new_signers() { - let params = json!({ "signer_allowlist": ["0xs2"] }); - let request = signer_request(params.clone(), Some(&["0xs1"]), &["0xs1", "0xs2"]); - assert!(decide(&request).await.allow); + let params = json!({ "signer_allowlist": ["0x52"] }); + let request = signer_request(params.clone(), Some(&["0x51"]), &["0x51", "0x52"]); + assert!(decide(&request).await.allows()); - let request = signer_request(params, Some(&["0xs1"]), &["0xs1", "0xs3"]); + let request = signer_request(params, Some(&["0x51"]), &["0x51", "0x53"]); assert_eq!(decide(&request).await.reason_code, "signer_not_allowed"); } #[tokio::test] async fn all_mode_checks_every_signer() { - let params = json!({ "signer_check": "all", "signer_allowlist": ["0xs2"] }); - let request = signer_request(params, Some(&["0xs1"]), &["0xs1", "0xs2"]); - assert!(!decide(&request).await.allow); + let params = json!({ "signer_check": "all", "signer_allowlist": ["0x52"] }); + let request = signer_request(params, Some(&["0x51"]), &["0x51", "0x52"]); + assert!(!decide(&request).await.allows()); } #[tokio::test] async fn registration_checks_every_initial_signer() { let params = json!({ "signer_denylist": ["0xbad"] }); - let request = signer_request(params, None, &["0xs1", "0xBAD"]); - assert!(!decide(&request).await.allow); + let request = signer_request(params, None, &["0x51", "0xBAD"]); + assert!(!decide(&request).await.allows()); } #[tokio::test] async fn missing_account_view_is_an_error_not_an_allow() { - let mut request = signer_request(json!({ "signer_allowlist": ["0xs1"] }), None, &[]); + let mut request = signer_request(json!({ "signer_allowlist": ["0x51"] }), None, &[]); request.after = None; assert!(BasicPolicy.evaluate(&request).await.is_err()); } @@ -820,6 +840,11 @@ mod tests { json!({ "unknown": 1 }), json!({ "max_amount_per_tx": { USDC: "ten" } }), json!({ "signer_allowlist": [], "signer_denylist": [] }), + json!({ "max_amount_per_tx": { "0xREPLACE_WITH_FAUCET_ID": "5" } }), + json!({ "max_amount_per_tx": { "0xAA": "5", "0xaa": "9" } }), + json!({ "deny_unknown_recipients": true }), + json!({ "signer_check": "all" }), + json!({ "code_check": "all" }), ] { let verdict = BasicPolicy .validate_params(&serde_json::to_vec(¶ms).unwrap()) @@ -832,7 +857,7 @@ mod tests { #[tokio::test] async fn evaluating_twice_gives_the_same_decision() { let projection = MidenTransaction { - output_notes: vec![p2id("0xr1", vec![fungible(USDC, 900)])], + output_notes: vec![p2id("0xa1", vec![fungible(USDC, 900)])], ..Default::default() }; let request = tx_request(cap(), projection); diff --git a/crates/guardian-module-sdk/src/conformance.rs b/crates/guardian-module-sdk/src/conformance.rs index a2357dcd..b04aef34 100644 --- a/crates/guardian-module-sdk/src/conformance.rs +++ b/crates/guardian-module-sdk/src/conformance.rs @@ -550,7 +550,7 @@ fn normalizes_to(verdict: &ParamsVerdict, normalized: &serde_json::Value) -> boo fn well_formed(decision: &Decision) -> Result<(), String> { let allowed = match Effect::try_from(decision.effect) { - Ok(Effect::Unspecified) => decision.allow, + Ok(Effect::Unspecified) => return Err("the decision sets no effect".into()), Ok(Effect::Allow) => true, Ok(Effect::Deny) => false, Err(_) => return Err(format!("unknown effect {}", decision.effect)), diff --git a/crates/guardian-module-sdk/src/lib.rs b/crates/guardian-module-sdk/src/lib.rs index 6379857f..91322fc0 100644 --- a/crates/guardian-module-sdk/src/lib.rs +++ b/crates/guardian-module-sdk/src/lib.rs @@ -34,8 +34,6 @@ pub const DEFAULT_REQUEST_MAX_BYTES: usize = 2 * 1024 * 1024; /// `ModuleInfo.required_capabilities`. New features are added as capabilities, not as a new /// protocol version, so modules and Guardians of one major version keep working together. pub mod capability { - /// `Decision.effect` is read. - pub const DECISION_EFFECT: &str = "decision.effect"; /// `ParamsVerdict.normalized_params` is stored. pub const PARAMS_NORMALIZATION: &str = "params.normalization"; } @@ -253,7 +251,6 @@ impl RegistrationSubject { impl Decision { pub fn allow() -> Self { Self { - allow: true, reason_code: String::new(), message: String::new(), effect: Effect::Allow as i32, @@ -263,7 +260,6 @@ impl Decision { pub fn deny(reason_code: impl Into, message: impl Into) -> Self { Self { - allow: false, reason_code: reason_code.into(), message: message.into(), effect: Effect::Deny as i32, @@ -271,6 +267,11 @@ impl Decision { } } + /// Whether this decision allows the request. + pub fn allows(&self) -> bool { + self.effect == Effect::Allow as i32 + } + /// Text for the person who sent the request. The Guardian forwards it only for instances /// whose catalog entry allows it, as plain text of at most 256 characters. pub fn with_client_message(mut self, client_message: impl Into) -> Self { diff --git a/crates/guardian-module-sdk/src/serve.rs b/crates/guardian-module-sdk/src/serve.rs index e644470c..13e96780 100644 --- a/crates/guardian-module-sdk/src/serve.rs +++ b/crates/guardian-module-sdk/src/serve.rs @@ -85,9 +85,10 @@ impl Harness { } /// Compares in time independent of where the tokens differ, so response timing does not reveal -/// a token prefix. +/// a token prefix. An empty registered token matches nothing. fn same_token(expected: &str, presented: &str) -> bool { - expected.len() == presented.len() + !expected.is_empty() + && expected.len() == presented.len() && expected .bytes() .zip(presented.bytes()) diff --git a/crates/guardian-module-sdk/tests/conformance.rs b/crates/guardian-module-sdk/tests/conformance.rs index 0971f43e..a396c1b3 100644 --- a/crates/guardian-module-sdk/tests/conformance.rs +++ b/crates/guardian-module-sdk/tests/conformance.rs @@ -57,7 +57,7 @@ fn payment(amounts: &[u64], params: serde_json::Value) -> HookRequest { faucet_id: "0xaa".into(), value: Some(asset::Value::FungibleAmount(amount.to_string())), }], - p2id_target: Some("0xr1".into()), + p2id_target: Some("0xa1".into()), ..Default::default() }) .collect(); @@ -112,29 +112,29 @@ async fn basic_policy_conforms() { .request("at the cap", payment(&[1000], cap)) .request( "recipient not allowed", - payment(&[1], json!({ "recipient_allowlist": ["0xother"] })), + payment(&[1], json!({ "recipient_allowlist": ["0x07e4"] })), ) .request( "recipient denied, generic", - payment(&[1], json!({ "recipient_denylist": ["0xr1"] })), + payment(&[1], json!({ "recipient_denylist": ["0xa1"] })), ) .request( "denied signer added", with_views( payment(&[1], signers.clone()), - &["0xs1"], - &["0xs1", "0xbad"], + &["0x51"], + &["0x51", "0xbad"], ), ) .request( "listed code", - with_views(payment(&[1], code.clone()), &["0xs1"], &["0xs1"]), + with_views(payment(&[1], code.clone()), &["0x51"], &["0x51"]), ) .request( "registration with a denied signer", registration(signers, &["0xbad"]), ) - .request("registration on listed code", registration(code, &["0xs1"])) + .request("registration on listed code", registration(code, &["0x51"])) .request( "params a module cannot read", payment(&[1], json!({ "max_amount_per_tx": { "0xaa": "ten" } })), @@ -196,7 +196,7 @@ async fn note_policy_conforms() { "a private payment", notes(vec![note(NoteType::Private, false)], private), ) - .request("registration", registration(json!({}), &["0xs1"])) + .request("registration", registration(json!({}), &["0x51"])) .valid_params(json!({ "max_payment_notes": 1, "deny_private_notes": true })) .valid_params(json!({})) .invalid_params(json!({ "max_notes": 1 })) diff --git a/speckit/features/251-guardian-modules/contracts/guardian_module_v1.proto b/speckit/features/251-guardian-modules/contracts/guardian_module_v1.proto index d1d374ec..ddff9f47 100644 --- a/speckit/features/251-guardian-modules/contracts/guardian_module_v1.proto +++ b/speckit/features/251-guardian-modules/contracts/guardian_module_v1.proto @@ -1,6 +1,7 @@ -// guardian.module.v1, extracted from docs/rfcs/0002-guardian-modules.md section 3 (revision 28). +// guardian.module.v1, extracted from docs/rfcs/0002-guardian-modules.md section 3 (revision 32). // The proto in RFC section 3 is authoritative; regenerate this file when it changes. -// Protocol version 1 is frozen (2026-11-09, at e4efd839): changes within it are additive only (RFC section 3.5). +// Protocol version 1 is not frozen yet: it freezes with the first published guardian-module-sdk +// release, and from then on changes within it are additive only (RFC section 3.5). syntax = "proto3"; package guardian.module.v1; @@ -51,7 +52,7 @@ message HookRequest { Hook hook = 2; bool dry_run = 3; // a policy check: nothing is stored or signed whatever the decision (section 2.7) string network = 4; // network family: "miden" - string network_id = 5; // the account's network within the family: "mainnet", "testnet", "devnet", "cedar" or "local" (section 3.1) + string network_id = 5; // the network this Guardian serves within the family: "mainnet", "testnet", "devnet", "cedar" or "local"; from its own configuration, never from the request (section 3.1) string account_id = 6; string instance_id = 7; // catalog id of the instance being called bytes params = 8; // UTF-8 JSON, params of the layer being evaluated (global, account layer, or the account's own for default/assigned) @@ -102,21 +103,20 @@ enum PendingState { } message RegistrationSubject { - AccountStateProjection initial_state = 1; // the account about to be accepted, per network + AccountStateProjection initial_state = 1; // the account about to be accepted, per network: its whole vault and storage } enum Effect { - EFFECT_UNSPECIFIED = 0; // a module that does not set `effect`: `allow` decides + EFFECT_UNSPECIFIED = 0; // never a decision: a module failure EFFECT_ALLOW = 1; EFFECT_DENY = 2; } message Decision { - bool allow = 1; // read only when effect is unspecified + Effect effect = 1; // unspecified, or a value the Guardian does not know, is a module failure string reason_code = 2; // required on a deny; ignored on an allow string message = 3; // logged, never forwarded to clients - Effect effect = 4; // wins over allow when set; a value the Guardian does not know is a module failure - string client_message = 5; // optional, plain text, at most 256 characters; forwarded only where the instance allows it (section 2.7) + string client_message = 4; // optional, plain text, at most 256 characters; forwarded only where the instance allows it (section 2.7) } // A transaction as its network describes it. One variant per network; a module reads the @@ -141,14 +141,15 @@ message RawTransaction { } message MidenTransaction { - int64 nonce_delta = 1; - uint32 reference_block = 2; // the block the transaction was executed against - optional uint32 expiration_block = 3; // absent when the transaction sets no expiration (section 3.1) + uint64 nonce_delta = 1; + uint32 bound_block = 2; // the block the summary binds; the transaction executes against this block or a later one (section 3.1) + optional uint32 expiration_delta = 3; // blocks after the block the transaction executes against at which it expires; absent when its script sets none. Not an absolute height: that block is not known at approval (section 3.1) repeated VaultChange vault_changes = 4; repeated OutputNote output_notes = 5; repeated InputNote input_notes = 6; repeated StorageChange storage_changes = 7; optional string new_code_commitment = 8; // set when the transaction replaces the account's code (section 3.1) + optional uint64 approval_expiration_block = 9; // the block at which the cosigners' approval of this transaction lapses; absent when it never lapses (section 3.1) } message MidenAccountState { @@ -172,7 +173,7 @@ message OutputNote { repeated Asset assets = 5; string script_root = 6; optional string p2id_target = 7; // set only for known P2ID / P2IDE scripts - bool tx_fee = 8; // the fee note pay_fee creates; not a payment (section 3.1: set only for that one note) + bool tx_fee = 8; // the fee note pay_fee creates; not a payment (section 3.1: set only for that one note, and only while it carries no more of the fee asset than a transaction can owe) } enum NoteType { NOTE_TYPE_UNSPECIFIED = 0; NOTE_TYPE_PUBLIC = 1; NOTE_TYPE_PRIVATE = 2; } From e96aeb94ad3c552e4130b5bf27b313e11a5cafc4 Mon Sep 17 00:00:00 2001 From: Zeljko Date: Tue, 10 Nov 2026 07:34:19 +0100 Subject: [PATCH 071/105] fix(modules): requests carry the Guardian's network, the registration state and a bounded fee note (#251) - network_id is the network this Guardian serves, not the network_type an account was registered with, which is optional, defaults to local and is chosen by the registrant. - RegistrationSubject.initial_state carries the account's vault and storage. - The projection reports the bound block, the script's expiration delta and the approval expiry from the summary's user params. - tx_fee is set only while the fee note carries no more of the fee asset than a transaction can owe (64 times the verification base fee, read with the fee asset from the latest block header and refreshed each minute), and for no note on a chain that charges nothing. A transaction with a fee-script note cannot be projected while the fee asset is unknown. --- crates/miden-rpc-client/src/lib.rs | 36 ++- crates/server/src/builder/mod.rs | 1 + crates/server/src/modules/request.rs | 51 +++- .../server/src/network/miden/execution/mod.rs | 2 +- crates/server/src/network/miden/mod.rs | 73 +++-- .../server/src/network/miden/module_views.rs | 258 ++++++++++++++---- crates/server/src/network/mod.rs | 14 +- .../server/src/services/ack_delta_internal.rs | 2 + crates/server/src/testing/mocks.rs | 7 + 9 files changed, 343 insertions(+), 101 deletions(-) diff --git a/crates/miden-rpc-client/src/lib.rs b/crates/miden-rpc-client/src/lib.rs index e2fdec58..1158765f 100644 --- a/crates/miden-rpc-client/src/lib.rs +++ b/crates/miden-rpc-client/src/lib.rs @@ -549,10 +549,11 @@ impl MidenRpcClient { }) } - /// The asset id the chain charges fees in, from the protocol configuration the latest block - /// header commits to, as a hex word. Takes `&self` like [`Self::get_account_commitment`]. - pub async fn get_fee_asset_id(&self, read_mode: RpcReadMode) -> Result { - const OPERATION: &str = "get_fee_asset_id"; + /// What the chain charges fees in and at what base rate, from the latest block header: the + /// fee asset id (a hex word) of the protocol configuration it commits to, and its + /// verification base fee. Takes `&self` like [`Self::get_account_commitment`]. + pub async fn get_chain_fee(&self, read_mode: RpcReadMode) -> Result { + const OPERATION: &str = "get_chain_fee"; let response = self .retry_read(OPERATION, read_mode, |mut client| async move { let request = rpc::GetBlockHeaderByNumberRequest { @@ -566,14 +567,24 @@ impl MidenRpcClient { .map(tonic::Response::into_inner) }) .await?; - response + let malformed = |reason: &str| RpcClientError::MalformedResponse { + operation: OPERATION, + reason: reason.to_string(), + }; + let verification_base_fee = response + .block_header + .and_then(|header| header.fee_parameters) + .map(|parameters| parameters.verification_base_fee) + .ok_or_else(|| malformed("no fee parameters in the block header"))?; + let asset_id = response .protocol_config .and_then(|config| config.fee_asset_id) .and_then(|word| word_to_hex(&word)) - .ok_or_else(|| RpcClientError::MalformedResponse { - operation: OPERATION, - reason: "no fee asset id in the protocol configuration".to_string(), - }) + .ok_or_else(|| malformed("no fee asset id in the protocol configuration"))?; + Ok(ChainFee { + asset_id, + verification_base_fee, + }) } /// One page of the transactions committed against `account_id` in @@ -742,6 +753,13 @@ pub fn account_id_from_proto(id: &account::AccountId) -> Option { /// One entry of a committed block's `updated_accounts`, reduced to what a /// consumer of the block feed compares. +/// The asset a chain charges fees in and its verification base fee, as of one block header. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct ChainFee { + pub asset_id: String, + pub verification_base_fee: u32, +} + #[derive(Debug, Clone, PartialEq, Eq)] pub struct BlockAccountState { pub account_id: AccountId, diff --git a/crates/server/src/builder/mod.rs b/crates/server/src/builder/mod.rs index 2c3fabc6..12c20f03 100644 --- a/crates/server/src/builder/mod.rs +++ b/crates/server/src/builder/mod.rs @@ -802,6 +802,7 @@ impl ServerBuilder { module_store, &module_registry, self.execution.lease, + network_type, ) .await?; diff --git a/crates/server/src/modules/request.rs b/crates/server/src/modules/request.rs index e8a728af..7c2071bf 100644 --- a/crates/server/src/modules/request.rs +++ b/crates/server/src/modules/request.rs @@ -148,16 +148,17 @@ fn view( Ok(view) } -/// The account's network within its family, from its registered configuration; modules are not -/// offered EVM accounts. -fn network_id(config: &NetworkConfig) -> Result<&'static str, String> { +/// Modules are not offered EVM accounts. The network a module is told is the one this Guardian +/// serves, never the `network_type` an account was registered with, which its registrant chose. +fn ensure_miden(config: &NetworkConfig) -> Result<(), String> { match config { - NetworkConfig::Miden { network_type } => Ok(network_type.as_str()), + NetworkConfig::Miden { .. } => Ok(()), NetworkConfig::Evm { .. } => Err("policy modules do not evaluate EVM accounts".into()), } } pub struct TransactionInput<'a> { + pub network_id: &'static str, pub account_id: &'a str, pub submitter: &'a str, pub submitter_session: bool, @@ -184,9 +185,10 @@ pub fn transaction_request( ), None => (String::new(), Vec::new()), }; + ensure_miden(input.network_config)?; Ok(HookRequest { network: "miden".into(), - network_id: network_id(input.network_config)?.into(), + network_id: input.network_id.into(), account_id: input.account_id.to_string(), accounting_time: Some(timestamp(input.accounting_time)), submitter: input.submitter.to_string(), @@ -210,6 +212,7 @@ pub fn transaction_request( } pub struct RegistrationInput<'a> { + pub network_id: &'static str, pub account_id: &'a str, pub submitter: &'a str, pub submitter_session: bool, @@ -225,9 +228,10 @@ pub fn registration_request( views: &ViewCache, input: RegistrationInput<'_>, ) -> Result { + ensure_miden(input.network_config)?; Ok(HookRequest { network: "miden".into(), - network_id: network_id(input.network_config)?.into(), + network_id: input.network_id.into(), account_id: input.account_id.to_string(), accounting_time: Some(timestamp(input.accounting_time)), submitter: input.submitter.to_string(), @@ -237,9 +241,11 @@ pub fn registration_request( .map(|state| view(network, views, state, input.auth)) .transpose()?, after: Some(view(network, views, input.initial_state, input.auth)?), - subject: Some(hook_request::Subject::Registration( - RegistrationSubject::default(), - )), + subject: Some(hook_request::Subject::Registration(RegistrationSubject { + initial_state: Some(guardian_module_sdk::AccountStateProjection::miden( + network.module_account_state(input.initial_state.json)?, + )), + })), ..Default::default() }) } @@ -350,7 +356,7 @@ mod tests { } #[test] - fn requests_name_the_accounts_network_and_refuse_evm_accounts() { + fn requests_name_the_guardians_network_and_refuse_evm_accounts() { use crate::metadata::network::MidenNetworkType; let auth = Auth::MidenFalconRpo { cosigner_commitments: vec!["0xa".into()], @@ -362,6 +368,7 @@ mod tests { &network, &ViewCache::default(), RegistrationInput { + network_id: "mainnet", account_id: "0xacc", submitter: "0xa", submitter_session: false, @@ -373,12 +380,30 @@ mod tests { }, ) }; - let testnet = request(&NetworkConfig::Miden { + let registered_as_testnet = request(&NetworkConfig::Miden { network_type: MidenNetworkType::Testnet, }) .unwrap(); - assert_eq!(testnet.network, "miden"); - assert_eq!(testnet.network_id, "testnet"); + assert_eq!(registered_as_testnet.network, "miden"); + assert_eq!( + registered_as_testnet.network_id, "mainnet", + "the Guardian's network, not the one the account was registered with" + ); + assert_eq!( + registered_as_testnet + .subject + .and_then(|subject| match subject { + hook_request::Subject::Registration(registration) => registration.initial_state, + hook_request::Subject::Transaction(_) => None, + }) + .and_then(|state| state.network), + Some( + guardian_module_sdk::proto::account_state_projection::Network::Miden( + guardian_module_sdk::MidenAccountState::default() + ) + ), + "the registration carries the account's state" + ); assert!( request(&NetworkConfig::Evm { chain_id: 1, diff --git a/crates/server/src/network/miden/execution/mod.rs b/crates/server/src/network/miden/execution/mod.rs index 91d84c6f..8de947fb 100644 --- a/crates/server/src/network/miden/execution/mod.rs +++ b/crates/server/src/network/miden/execution/mod.rs @@ -13,7 +13,7 @@ mod store; pub use attempt::MidenExecutor; pub use chain::{ChainViewError, build_chain_view}; pub use foreign::{ForeignAccountUnavailable, ForeignAccounts}; -pub use request::StoredRequest; +pub use request::{StoredRequest, approval_expiration_block}; pub use store::ExecutionDataStore; #[cfg(all(test, feature = "e2e"))] diff --git a/crates/server/src/network/miden/mod.rs b/crates/server/src/network/miden/mod.rs index 9dfbf3f3..098ebf40 100644 --- a/crates/server/src/network/miden/mod.rs +++ b/crates/server/src/network/miden/mod.rs @@ -33,8 +33,9 @@ use miden_standards::account::auth::AuthGuardedMultisig; /// Miden network client for fetching on-chain account data pub struct MidenNetworkClient { client: MidenRpcClient, - /// The chain's fee faucet, loaded once by [`NetworkClient::load_fee_faucet`]. - fee_faucet: std::sync::OnceLock, + /// The chain's fee faucet and the largest fee a transaction can owe, as last read by + /// [`NetworkClient::load_fee_faucet`]. + fee: std::sync::RwLock>, } impl MidenNetworkClient { @@ -60,7 +61,7 @@ impl MidenNetworkClient { })); Ok(Self { client, - fee_faucet: std::sync::OnceLock::new(), + fee: std::sync::RwLock::new(None), }) } @@ -75,7 +76,7 @@ impl MidenNetworkClient { .expect("lazy client construction is infallible for a valid endpoint"); Self { client, - fee_faucet: std::sync::OnceLock::new(), + fee: std::sync::RwLock::new(None), } } @@ -963,30 +964,64 @@ impl NetworkClient for MidenNetworkClient { module_views::module_account_of(&Account::from_json(state_json)?) } + fn module_account_state( + &self, + state_json: &serde_json::Value, + ) -> Result { + module_views::account_state(state_json) + } + fn module_transaction( &self, tx_summary: &serde_json::Value, initial_nonce: u64, ) -> Result { - module_views::module_transaction(tx_summary, initial_nonce, self.fee_faucet.get().copied()) + let fee = self + .fee + .read() + .ok() + .and_then(|fee| fee.as_ref().map(|(fee, _)| *fee)); + module_views::module_transaction(tx_summary, initial_nonce, fee) } async fn load_fee_faucet(&self) -> Result<(), String> { - if self.fee_faucet.get().is_some() { + let loaded = self + .fee + .read() + .ok() + .and_then(|fee| fee.as_ref().map(|(_, at)| at.elapsed())); + if loaded.is_some_and(|age| age < module_views::CHAIN_FEE_TTL) { return Ok(()); } - let asset_id = self - .client - .get_fee_asset_id(RpcReadMode::Configured) - .await - .map_err(|e| format!("cannot read the chain's fee asset: {e}"))?; - let word = Word::try_from(asset_id.as_str()) - .map_err(|e| format!("fee asset id is not a word: {e}"))?; - let faucet = AssetId::try_from(word) - .map_err(|e| format!("fee asset id does not decode: {e}"))? - .faucet_id(); - let _ = self.fee_faucet.set(faucet); - Ok(()) + let read = async { + let chain = self + .client + .get_chain_fee(RpcReadMode::Configured) + .await + .map_err(|e| format!("cannot read the chain's fee asset: {e}"))?; + let word = Word::try_from(chain.asset_id.as_str()) + .map_err(|e| format!("fee asset id is not a word: {e}"))?; + let faucet = AssetId::try_from(word) + .map_err(|e| format!("fee asset id does not decode: {e}"))? + .faucet_id(); + Ok::<_, String>(module_views::ChainFee::new( + faucet, + chain.verification_base_fee, + )) + }; + match read.await { + Ok(fee) => { + if let Ok(mut slot) = self.fee.write() { + *slot = Some((fee, std::time::Instant::now())); + } + Ok(()) + } + Err(error) if loaded.is_some() => { + tracing::warn!(%error, "Chain fee not refreshed; keeping the last value read"); + Ok(()) + } + Err(error) => Err(error), + } } async fn should_update_auth( @@ -1623,7 +1658,7 @@ mod tests { ( MidenNetworkClient { client, - fee_faucet: std::sync::OnceLock::new(), + fee: std::sync::RwLock::new(None), }, requests, ) diff --git a/crates/server/src/network/miden/module_views.rs b/crates/server/src/network/miden/module_views.rs index bdbb03a5..e6bd5fec 100644 --- a/crates/server/src/network/miden/module_views.rs +++ b/crates/server/src/network/miden/module_views.rs @@ -1,9 +1,9 @@ //! Account views and transaction projections sent to policy modules. -use guardian_module_sdk::proto::{MapChanges, MapEntry, asset}; +use guardian_module_sdk::proto::{MapChanges, MapEntry, StorageSlot, asset, storage_slot}; use guardian_module_sdk::{ - AccountView, Asset as ModuleAsset, Direction, InputNote, MidenTransaction, NoteType, - OutputNote, StorageChange, StorageOp, StorageSlotKind, VaultChange, + AccountView, Asset as ModuleAsset, Direction, InputNote, MidenAccountState, MidenTransaction, + NoteType, OutputNote, StorageChange, StorageOp, StorageSlotKind, VaultChange, }; use guardian_shared::{FromJson, SignatureScheme}; use miden_protocol::Felt; @@ -42,6 +42,48 @@ pub fn module_account_of(account: &Account) -> Result Result { + let account = Account::from_json(state_json)?; + Ok(MidenAccountState { + vault: account + .vault() + .assets() + .map(|asset| module_asset(&asset)) + .collect(), + storage: account + .storage() + .slots() + .iter() + .map(|slot| { + let (kind, content) = match slot.content() { + StorageSlotContent::Value(word) => ( + StorageSlotKind::Value, + storage_slot::Content::Value(word_hex(word)), + ), + StorageSlotContent::Map(map) => ( + StorageSlotKind::Map, + storage_slot::Content::Map(MapChanges { + entries: map + .entries() + .map(|(key, value)| MapEntry { + key: word_hex(&Word::from(*key)), + value: word_hex(value), + }) + .collect(), + }), + ), + }; + StorageSlot { + slot_name: slot.name().as_str().to_string(), + kind: kind as i32, + content: Some(content), + } + }) + .collect(), + }) +} + /// [`account_view`] of an account already decoded. pub fn account_view_of(account: &Account) -> Result { let storage = account.storage(); @@ -162,19 +204,32 @@ fn p2id_target(note: &Note) -> Option { } } -/// The transaction's fee note: a note with the TX_FEE script is a payment like any other, since -/// any transaction script can create one, with any assets, that anyone can consume. Only the note -/// `pay_fee` creates is the fee, and it is recognised by everything `pay_fee` fixes: it is the -/// only TX_FEE note, its serial number is derived from the account, the nonce the transaction -/// starts from and the block its summary binds, and it carries one fungible asset of the chain's -/// fee faucet. Without a known fee faucet no note qualifies. -fn fee_note( - summary: &TransactionSummary, - initial_nonce: u64, - fee_faucet: Option, -) -> Option { - let fee_faucet = fee_faucet?; - let mut tx_fee_notes = summary.output_notes().iter().filter_map(|raw| match raw { +/// How long a chain fee read is used before it is read again. +pub const CHAIN_FEE_TTL: std::time::Duration = std::time::Duration::from_secs(60); + +/// The fee is the base fee times a logarithmic measure of the transaction's cycle count, which +/// stays below 32 for any cycle count the kernel accepts; twice that leaves room for the cycle +/// margins `pay_fee` adds. +const MAX_FEE_VERIFICATION_CYCLES: u64 = 64; + +/// The chain's fee faucet and the largest amount of its asset one transaction can owe as a fee. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub struct ChainFee { + faucet: AccountId, + max_amount: u64, +} + +impl ChainFee { + pub fn new(faucet: AccountId, verification_base_fee: u32) -> Self { + Self { + faucet, + max_amount: u64::from(verification_base_fee) * MAX_FEE_VERIFICATION_CYCLES, + } + } +} + +fn tx_fee_notes(summary: &TransactionSummary) -> impl Iterator { + summary.output_notes().iter().filter_map(|raw| match raw { RawOutputNote::Full(note) if matches!( StandardNote::from_script(note.script()), @@ -184,7 +239,18 @@ fn fee_note( Some(note) } _ => None, - }); + }) +} + +/// The transaction's fee note: a note with the TX_FEE script is a payment like any other, since +/// any transaction script can create one, with any assets, that anyone can consume. Only the note +/// `pay_fee` creates is the fee, and it is recognised by everything `pay_fee` fixes: it is the +/// only TX_FEE note, its serial number is derived from the account, the nonce the transaction +/// starts from and the block its summary binds, and it carries one fungible asset of the chain's +/// fee faucet, no more of it than a transaction can owe. On a chain that charges nothing `pay_fee` +/// creates no note, so no note qualifies there. +fn fee_note(summary: &TransactionSummary, initial_nonce: u64, fee: ChainFee) -> Option { + let mut tx_fee_notes = tx_fee_notes(summary); let note = tx_fee_notes.next()?; if tx_fee_notes.next().is_some() { return None; @@ -199,7 +265,12 @@ fn fee_note( } let assets: Vec<&Asset> = note.assets().iter().collect(); match assets.as_slice() { - [asset] if asset.is_fungible() && asset.faucet_id() == fee_faucet => Some(note.id()), + [asset] => asset + .as_fungible() + .filter(|asset| { + asset.faucet_id() == fee.faucet && asset.amount().as_u64() <= fee.max_amount + }) + .map(|_| note.id()), _ => None, } } @@ -242,31 +313,27 @@ fn storage_op(op: StoragePatchOperation) -> i32 { pub fn module_transaction( tx_summary: &serde_json::Value, initial_nonce: u64, - fee_faucet: Option, + fee: Option, ) -> Result { let summary = TransactionSummary::from_json(tx_summary) .map_err(|e| format!("transaction summary does not decode: {e}"))?; + let fee_note = match fee { + Some(fee) => fee_note(&summary, initial_nonce, fee), + None if tx_fee_notes(&summary).next().is_some() => { + return Err( + "the chain's fee asset is unknown, so the transaction's fee note cannot be told \ + from a payment" + .into(), + ); + } + None => None, + }; Ok(crate::network::ModuleTransaction { - projection: projection_from_summary( - &summary, - fee_note(&summary, initial_nonce, fee_faucet), - )?, + projection: projection_from_summary(&summary, fee_note)?, raw_tx_summary: summary.to_bytes(), }) } -/// `None` for a transaction without an expiration (delta 0), so "never expires" is not confused -/// with "expires at the reference block". -fn expiration_block(block_number: u32, expiration_delta: u16) -> Result, String> { - if expiration_delta == 0 { - return Ok(None); - } - block_number - .checked_add(u32::from(expiration_delta)) - .map(Some) - .ok_or_else(|| format!("expiration overflows: block {block_number} + {expiration_delta}")) -} - fn projection_from_summary( summary: &TransactionSummary, fee_note: Option, @@ -317,12 +384,11 @@ fn projection_from_summary( })); Ok(MidenTransaction { - nonce_delta: delta.nonce_delta().as_canonical_u64() as i64, - reference_block: summary.block_number().as_u32(), - expiration_block: expiration_block( - summary.block_number().as_u32(), - summary.expiration_delta(), - )?, + nonce_delta: delta.nonce_delta().as_canonical_u64(), + bound_block: summary.block_number().as_u32(), + expiration_delta: Some(u32::from(summary.expiration_delta())).filter(|delta| *delta != 0), + approval_expiration_block: Some(super::execution::approval_expiration_block(summary)) + .filter(|block| *block != 0), new_code_commitment: delta .code() .as_code() @@ -546,7 +612,6 @@ mod tests { let delta: serde_json::Value = serde_json::from_str(fixture).unwrap(); let transaction = module_transaction(&delta["delta_payload"], 0, None).unwrap(); let projection = transaction.projection; - assert!(projection.nonce_delta >= 0); for change in &projection.storage_changes { assert!(!change.slot_name.is_empty()); assert_ne!(change.op, StorageOp::Unspecified as i32); @@ -571,13 +636,6 @@ mod tests { ); } - #[test] - fn expiration_overflow_is_an_error() { - assert_eq!(expiration_block(10, 5), Ok(Some(15))); - assert_eq!(expiration_block(u32::MAX, 0), Ok(None)); - assert!(expiration_block(u32::MAX, 1).is_err()); - } - fn summary(code: Option, expiration_delta: u16) -> TransactionSummary { use miden_protocol::account::{ AccountCodePatch, AccountDelta, AccountStoragePatch, AccountVaultDelta, @@ -666,9 +724,9 @@ mod tests { ) } - fn fee_flags(notes: Vec, fee_faucet: Option) -> Vec { + fn fee_flags(notes: Vec, fee: Option) -> Vec { let summary = summary_with(notes); - projection_from_summary(&summary, fee_note(&summary, NONCE, fee_faucet)) + projection_from_summary(&summary, fee.and_then(|fee| fee_note(&summary, NONCE, fee))) .unwrap() .output_notes .iter() @@ -676,11 +734,52 @@ mod tests { .collect() } + #[test] + fn a_fee_note_cannot_be_judged_while_the_fee_asset_is_unknown() { + use guardian_shared::ToJson; + let with_fee_note = summary_with(vec![fee_note_with( + canonical_serial(), + vec![fungible(9, 5)], + )]) + .to_json(); + let error = module_transaction(&with_fee_note, NONCE, None).unwrap_err(); + assert!(error.contains("fee asset is unknown"), "{error}"); + let without = summary_with(vec![]).to_json(); + assert!(module_transaction(&without, NONCE, None).is_ok()); + } + #[test] fn only_the_note_pay_fee_creates_is_the_fee_note() { - let fee_faucet = Some(dummy_id(9)); + let fee_faucet = Some(ChainFee::new(dummy_id(9), 1)); let canonical = || fee_note_with(canonical_serial(), vec![fungible(9, 5)]); assert_eq!(fee_flags(vec![canonical()], fee_faucet), [true]); + assert_eq!( + fee_flags( + vec![fee_note_with( + canonical_serial(), + vec![fungible(9, MAX_FEE_VERIFICATION_CYCLES)] + )], + fee_faucet + ), + [true], + "the largest fee a transaction can owe" + ); + assert_eq!( + fee_flags( + vec![fee_note_with( + canonical_serial(), + vec![fungible(9, MAX_FEE_VERIFICATION_CYCLES + 1)] + )], + fee_faucet + ), + [false], + "more of the fee asset than a transaction can owe is a payment" + ); + assert_eq!( + fee_flags(vec![canonical()], Some(ChainFee::new(dummy_id(9), 0))), + [false], + "a chain that charges nothing has no fee note" + ); assert_eq!( fee_flags(vec![canonical()], None), [false], @@ -744,13 +843,58 @@ mod tests { } #[test] - fn projection_carries_the_reference_block_and_an_expiration_only_when_one_is_set() { + fn projection_carries_the_bound_block_and_expirations_only_when_set() { let expiring = projection_from_summary(&summary(None, 20), None).unwrap(); - assert_eq!(expiring.reference_block, 100); - assert_eq!(expiring.expiration_block, Some(120)); + assert_eq!(expiring.bound_block, 100); + assert_eq!(expiring.expiration_delta, Some(20)); let open = projection_from_summary(&summary(None, 0), None).unwrap(); - assert_eq!(open.reference_block, 100); - assert_eq!(open.expiration_block, None); + assert_eq!(open.bound_block, 100); + assert_eq!(open.expiration_delta, None); + assert_eq!(open.approval_expiration_block, None); + } + + #[test] + fn projection_carries_the_approval_expiry_from_the_user_params() { + use miden_protocol::transaction::TransactionSummaryUserParams; + let open = summary(None, 0); + let mut user_params = [Felt::ZERO; 6]; + user_params[0] = Felt::new_unchecked(500); + let approved_until = TransactionSummary::new( + open.account_delta().clone(), + open.input_notes().clone(), + open.output_notes().clone(), + open.block_number(), + Word::default(), + 0, + TransactionSummaryUserParams::new(user_params), + ); + assert_eq!( + projection_from_summary(&approved_until, None) + .unwrap() + .approval_expiration_block, + Some(500) + ); + } + + #[test] + fn an_account_state_lists_every_storage_slot_with_its_content() { + let account: serde_json::Value = + serde_json::from_str(crate::testing::fixtures::ACCOUNT_JSON).unwrap(); + let state = account_state(&account).unwrap(); + assert!(!state.storage.is_empty()); + for slot in &state.storage { + assert!(!slot.slot_name.is_empty()); + assert!(slot.content.is_some()); + assert_ne!(slot.kind, StorageSlotKind::Unspecified as i32); + } + assert_eq!( + state.vault.len(), + Account::from_json(&account) + .unwrap() + .vault() + .assets() + .count() + ); } #[test] diff --git a/crates/server/src/network/mod.rs b/crates/server/src/network/mod.rs index a3948873..5d1fe5ac 100644 --- a/crates/server/src/network/mod.rs +++ b/crates/server/src/network/mod.rs @@ -567,6 +567,15 @@ pub trait NetworkClient: Send + Sync { Err("policy modules are not supported on this network".into()) } + /// The account's whole vault and storage, as a registration's subject carries them. + fn module_account_state( + &self, + state_json: &serde_json::Value, + ) -> Result { + let _ = state_json; + Err("policy modules are not supported on this network".into()) + } + /// The decoded effects of a transaction as policy modules see them. `tx_summary` is the /// bare summary the Guardian verifies and signs, never a proposal wrapper; `initial_nonce` /// is the nonce of the state it starts from, which identifies its fee note. @@ -579,8 +588,9 @@ pub trait NetworkClient: Send + Sync { Err("policy modules are not supported on this network".into()) } - /// Loads the chain's fee faucet once, so module projections can tell the transaction's fee - /// note from a payment. Until it is loaded no note is treated as the fee note. + /// Reads the chain's fee faucet and base fee, again once the last read is stale, so module + /// projections can tell the transaction's fee note from a payment. Until a first read + /// succeeds a transaction carrying a fee-script note cannot be projected. async fn load_fee_faucet(&self) -> Result<(), String> { Ok(()) } diff --git a/crates/server/src/services/ack_delta_internal.rs b/crates/server/src/services/ack_delta_internal.rs index b8b4cd3a..9dee0a9b 100644 --- a/crates/server/src/services/ack_delta_internal.rs +++ b/crates/server/src/services/ack_delta_internal.rs @@ -189,6 +189,7 @@ async fn approve( } let signed_at = state.clock.now(); let views = plan.views(); + let network_id = plan.network_id(); if let Some(module_views) = module_views { views.seed(base.commitment, module_views.before); views.seed(&applied.commitment, module_views.after); @@ -198,6 +199,7 @@ async fn approve( state.network_client.as_ref(), &views, TransactionInput { + network_id, account_id: &delta.account_id, submitter: submitter.commitment, submitter_session: submitter.session, diff --git a/crates/server/src/testing/mocks.rs b/crates/server/src/testing/mocks.rs index c9498df6..6de1edbf 100644 --- a/crates/server/src/testing/mocks.rs +++ b/crates/server/src/testing/mocks.rs @@ -256,6 +256,13 @@ impl NetworkClient for MockNetworkClient { .ok_or_else(|| "no module account view configured".to_string()) } + fn module_account_state( + &self, + _state_json: &serde_json::Value, + ) -> StdResult { + Ok(guardian_module_sdk::MidenAccountState::default()) + } + fn module_transaction( &self, tx_summary: &serde_json::Value, From a5c3a77444e1d771e98472a9400b58d88e9fa716 Mon Sep 17 00:00:00 2001 From: Zeljko Date: Tue, 10 Nov 2026 07:34:19 +0100 Subject: [PATCH 072/105] fix(modules): breaker accounting, one state read per evaluation, bounded module calls (#251) - A request the module rejects as one it cannot judge applies on_error but does not count toward the breaker, so one account cannot stop a module for every account. - A timeout is excused only when earlier modules used up the budget, so a module whose timeout is the whole budget can open its breaker. - Half-open sends one trial at a time; dry-run checks neither probe nor close a breaker. - An evaluation reads module state in one store call. - A module call is aborted when its caller goes away; the gRPC channel has keepalives, a request timeout and a TLS handshake timeout. - A fail-open skip at a hook that signs nothing can be written to the audit log. --- crates/server/src/modules/breaker.rs | 87 ++++++++-- crates/server/src/modules/grpc_kind.rs | 24 ++- crates/server/src/modules/pipeline.rs | 226 +++++++++++++++++++------ crates/server/src/modules/registry.rs | 37 ++-- crates/server/src/modules/testing.rs | 17 +- 5 files changed, 296 insertions(+), 95 deletions(-) diff --git a/crates/server/src/modules/breaker.rs b/crates/server/src/modules/breaker.rs index 19d7d3c0..14b1322a 100644 --- a/crates/server/src/modules/breaker.rs +++ b/crates/server/src/modules/breaker.rs @@ -25,6 +25,8 @@ impl CircuitState { struct Breaker { state: CircuitState, consecutive_failures: u32, + /// A half-open breaker's one trial call is out and has not reported back. + trial_in_flight: bool, } impl Default for Breaker { @@ -32,13 +34,23 @@ impl Default for Breaker { Self { state: CircuitState::Closed, consecutive_failures: 0, + trial_in_flight: false, } } } +/// Who is asking to call a module. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum Caller { + /// A request that leads to a signature or a stored proposal. + Request, + /// A policy check: it neither tests a recovering module nor changes a breaker. + DryRun, +} + /// One breaker per instance id. A closed breaker opens after `threshold` consecutive failures; an -/// open one skips the module until a successful probe moves it to half-open, where the next real -/// call closes it on an answer or opens it again on a failure. +/// open one skips the module until a successful probe moves it to half-open, where one real call +/// at a time is let through: it closes the breaker on an answer or opens it again on a failure. pub struct Breakers { threshold: u32, by_instance: Mutex>, @@ -60,10 +72,23 @@ impl Breakers { .unwrap_or(CircuitState::Closed) } - /// Whether the module may be called; an open breaker applies the instance's `on_error` at - /// once instead. - pub fn admits(&self, instance: &str) -> bool { - self.state(instance) != CircuitState::Open + /// Whether the module may be called now; when not, the instance's `on_error` applies at + /// once instead. A half-open breaker admits one request at a time as its trial, and a caller + /// admitted that way must report back with [`Self::answered`] or [`Self::failed`]. + pub fn admit(&self, instance: &str, caller: Caller) -> bool { + let Ok(mut breakers) = self.by_instance.lock() else { + return false; + }; + let Some(breaker) = breakers.get_mut(instance) else { + return true; + }; + match (breaker.state, caller) { + (CircuitState::Closed, _) => true, + (CircuitState::Open, _) | (CircuitState::HalfOpen, Caller::DryRun) => false, + (CircuitState::HalfOpen, Caller::Request) => { + !std::mem::replace(&mut breaker.trial_in_flight, true) + } + } } /// The module answered, allow or deny: a deny is an answer, not a failure. @@ -81,16 +106,20 @@ impl Breakers { breaker.state = CircuitState::Open; } } - CircuitState::HalfOpen | CircuitState::Open => breaker.state = CircuitState::Open, + CircuitState::HalfOpen | CircuitState::Open => { + breaker.state = CircuitState::Open; + breaker.trial_in_flight = false; + } }); } - /// A health probe succeeded: an open breaker lets the next real call through. + /// A health probe succeeded: an open breaker lets the next real call through, and a + /// half-open one whose trial never reported back (its request was dropped) lets another. pub fn probe_succeeded(&self, instance: &str) { - self.update(instance, |breaker| { - if breaker.state == CircuitState::Open { - breaker.state = CircuitState::HalfOpen; - } + self.update(instance, |breaker| match breaker.state { + CircuitState::Open => breaker.state = CircuitState::HalfOpen, + CircuitState::HalfOpen => breaker.trial_in_flight = false, + CircuitState::Closed => {} }); } @@ -128,10 +157,34 @@ mod tests { breakers.answered("m"); breakers.failed("m"); breakers.failed("m"); - assert!(breakers.admits("m"), "an answer reset the count"); + assert!( + breakers.admit("m", Caller::Request), + "an answer reset the count" + ); breakers.failed("m"); assert_eq!(breakers.state("m"), CircuitState::Open); - assert!(!breakers.admits("m")); + assert!(!breakers.admit("m", Caller::Request)); + } + + #[test] + fn a_half_open_breaker_admits_one_trial_at_a_time_and_no_dry_run() { + let breakers = Breakers::new(1); + breakers.failed("m"); + breakers.probe_succeeded("m"); + assert!(!breakers.admit("m", Caller::DryRun)); + assert!(breakers.admit("m", Caller::Request)); + assert!( + !breakers.admit("m", Caller::Request), + "the trial is still out" + ); + breakers.probe_succeeded("m"); + assert!( + breakers.admit("m", Caller::Request), + "a later probe replaces a trial that never reported back" + ); + breakers.answered("m"); + assert!(breakers.admit("m", Caller::Request)); + assert!(breakers.admit("m", Caller::DryRun)); } #[test] @@ -140,7 +193,7 @@ mod tests { breakers.failed("m"); breakers.probe_succeeded("m"); assert_eq!(breakers.state("m"), CircuitState::HalfOpen); - assert!(breakers.admits("m")); + assert!(breakers.admit("m", Caller::Request)); breakers.failed("m"); assert_eq!(breakers.state("m"), CircuitState::Open); breakers.probe_succeeded("m"); @@ -154,7 +207,7 @@ mod tests { breakers.probe_succeeded("a"); assert_eq!(breakers.state("a"), CircuitState::Closed); breakers.failed("a"); - assert!(!breakers.admits("a")); - assert!(breakers.admits("b")); + assert!(!breakers.admit("a", Caller::Request)); + assert!(breakers.admit("b", Caller::Request)); } } diff --git a/crates/server/src/modules/grpc_kind.rs b/crates/server/src/modules/grpc_kind.rs index 0990bf80..624ac69d 100644 --- a/crates/server/src/modules/grpc_kind.rs +++ b/crates/server/src/modules/grpc_kind.rs @@ -16,8 +16,11 @@ use super::catalog::Transport; /// Server authentication against the instance's CA, or the system roots without one; the /// client identity, when set, adds mutual TLS. -fn tls_config(tls: Option<&guardian_module_sdk::ModuleTls>) -> ClientTlsConfig { - let config = ClientTlsConfig::new(); +fn tls_config( + tls: Option<&guardian_module_sdk::ModuleTls>, + handshake_timeout: std::time::Duration, +) -> ClientTlsConfig { + let config = ClientTlsConfig::new().timeout(handshake_timeout); let Some(tls) = tls else { return config.with_native_roots(); }; @@ -34,6 +37,11 @@ fn tls_config(tls: Option<&guardian_module_sdk::ModuleTls>) -> ClientTlsConfig { } } +/// A module host that vanishes without closing the connection is noticed within this interval +/// plus the timeout, instead of when the kernel gives up retransmitting. +const KEEP_ALIVE_INTERVAL: std::time::Duration = std::time::Duration::from_secs(10); +const KEEP_ALIVE_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(5); + pub struct GrpcFactory; impl ModuleFactory for GrpcFactory { @@ -49,7 +57,7 @@ impl ModuleFactory for GrpcFactory { let uri = endpoint.replacen(Transport::TLS_SCHEME, "https://", 1); Endpoint::from_shared(uri) .map_err(|e| invalid(format!("invalid endpoint: {e}")))? - .tls_config(tls_config(instance.tls.as_ref())) + .tls_config(tls_config(instance.tls.as_ref(), instance.timeout)) .map_err(|e| invalid(format!("invalid tls settings: {e}")))? } Transport::PlaintextLoopback => { @@ -57,7 +65,14 @@ impl ModuleFactory for GrpcFactory { Endpoint::from_shared(uri).map_err(|e| invalid(format!("invalid endpoint: {e}")))? } }; - let channel = endpoint.connect_timeout(instance.timeout).connect_lazy(); + let channel = endpoint + .connect_timeout(instance.timeout) + .timeout(instance.timeout) + .http2_keep_alive_interval(KEEP_ALIVE_INTERVAL) + .keep_alive_timeout(KEEP_ALIVE_TIMEOUT) + .keep_alive_while_idle(true) + .tcp_keepalive(Some(KEEP_ALIVE_INTERVAL)) + .connect_lazy(); let authorization = instance .auth_token .as_ref() @@ -102,6 +117,7 @@ fn module_error(status: tonic::Status) -> ModuleError { tonic::Code::Unavailable | tonic::Code::DeadlineExceeded | tonic::Code::Unknown => { ModuleError::Unavailable(status.message().to_string()) } + tonic::Code::InvalidArgument => ModuleError::InvalidRequest(status.message().to_string()), _ => ModuleError::Internal(format!("{}: {}", status.code(), status.message())), } } diff --git a/crates/server/src/modules/pipeline.rs b/crates/server/src/modules/pipeline.rs index e8a1cb87..30064410 100644 --- a/crates/server/src/modules/pipeline.rs +++ b/crates/server/src/modules/pipeline.rs @@ -6,7 +6,7 @@ use super::catalog::{Catalog, ClientReason, HookName, OnError, Scope}; use std::collections::{HashMap, HashSet}; use std::sync::{Arc, RwLock}; -use super::breaker::{Breakers, CircuitState}; +use super::breaker::{Breakers, Caller, CircuitState}; use super::limits::Limits; use super::registry::{CallError, Instance, Registry, isolated}; use super::request::ViewCache; @@ -23,6 +23,44 @@ pub struct Evaluation { pub failed_open: Vec, } +impl Evaluation { + /// Records the failures `on_error = allow` let through at a hook that signs nothing, so they + /// are kept somewhere other than the log. A transaction's are stored with its signed delta + /// instead. `subject` adds what the hook judged, a proposal id for one. + pub fn audit_failed_open( + &self, + auditor: &dyn crate::audit::Auditor, + hook: HookName, + account_id: &str, + submitter: &str, + subject: serde_json::Map, + ) { + if self.failed_open.is_empty() { + return; + } + let mut payload = serde_json::json!({ + "hook": hook.as_str(), + "submitter": submitter, + "catalog_hash": self.catalog_hash, + "params_version": self.params_version, + "failed_open": self.failed_open, + }); + if let Some(fields) = payload.as_object_mut() { + fields.extend(subject); + } + auditor.record(crate::audit::AuditEvent { + operator_identity: crate::services::release_on_switch::SYSTEM_OPERATOR_IDENTITY + .to_string(), + action_kind: crate::audit::kinds::MODULES_FAILED_OPEN, + target_account_id: Some(account_id.to_string()), + payload, + outcome: crate::audit::AuditOutcome::Success, + error_code: None, + client_ip: None, + }); + } +} + #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub enum Layer { Global, @@ -46,6 +84,8 @@ pub struct ModulePipeline { limits: Limits, breakers: Arc, pub catalog_hash: String, + /// The network this Guardian serves, as modules receive it in `network_id`. + network_id: &'static str, /// Instances whose stored seed differs from the catalog's params, as of startup. seed_drift: HashSet, /// Accounts over the budget and orphaned assignment rows, as of the last report. @@ -65,6 +105,7 @@ pub struct Plan<'a> { hook: HookName, account_id: String, modules: Vec<(&'a Instance, serde_json::Value, Layer)>, + network_id: &'static str, catalog_hash: String, params_version: u64, views: Arc, @@ -76,9 +117,12 @@ pub struct Plan<'a> { enum Failure { Error(String), + /// The module refused this request as one it cannot judge: its failure for this request, + /// which says nothing about whether the module is up. + Rejected(String), Timeout, InvalidDecision(String), - /// An `effect` value this Guardian does not know: never read as an allow. + /// No `effect`, or a value this Guardian does not know: never read as an allow. UnknownEffect(i32), RequestUnavailable(String), /// The encoded request exceeds the size cap; it is not sent. @@ -90,7 +134,7 @@ enum Failure { impl Failure { fn kind(&self) -> &'static str { match self { - Failure::Error(_) => "error", + Failure::Error(_) | Failure::Rejected(_) => "error", Failure::Timeout => "timeout", Failure::InvalidDecision(_) | Failure::UnknownEffect(_) => "invalid_decision", Failure::RequestUnavailable(_) | Failure::RequestTooLarge(_) => "request_unavailable", @@ -103,6 +147,7 @@ impl std::fmt::Display for Failure { fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { match self { Failure::Error(message) => write!(f, "{message}"), + Failure::Rejected(message) => write!(f, "module rejected the request: {message}"), Failure::Timeout => write!(f, "timed out"), Failure::InvalidDecision(code) => write!(f, "invalid reason code {code:?}"), Failure::UnknownEffect(value) => write!(f, "unknown decision effect {value}"), @@ -132,6 +177,7 @@ impl ModulePipeline { } pub async fn new( + network_id: &'static str, mut catalog: Catalog, registry: &Registry, store: Arc, @@ -226,7 +272,7 @@ impl ModulePipeline { }, ) .await?; - if migrated { + if migrated.is_some() { tracing::info!(module = %instance.config.id, %operator, "Module normalized its stored global params; stored the migrated form"); } else { tracing::warn!(module = %instance.config.id, "Global params changed while the module migrated them; kept the newer value, migration retries next start"); @@ -240,6 +286,7 @@ impl ModulePipeline { breakers: Arc::new(Breakers::new(limits.breaker_failures)), limits, catalog_hash: catalog.hash, + network_id, seed_drift, assignment_report: std::sync::Mutex::new((0, 0)), }) @@ -266,11 +313,18 @@ impl ModulePipeline { limits: Limits::default(), breakers: Arc::new(Breakers::new(Limits::default().breaker_failures)), catalog_hash: String::new(), + network_id: "local", seed_drift: HashSet::new(), assignment_report: std::sync::Mutex::new((0, 0)), } } + #[cfg(test)] + pub fn with_network(mut self, network_id: &'static str) -> Self { + self.network_id = network_id; + self + } + #[cfg(test)] pub fn with_limits(mut self, limits: Limits) -> Self { self.breakers = Arc::new(Breakers::new(limits.breaker_failures)); @@ -599,15 +653,12 @@ impl ModulePipeline { let subscribed = |rows: &Rows, instance: &&Instance| { instance.config.hooks.contains(&hook) && Self::enabled_in(rows, instance) }; - if !first_registration { - let (_, rows) = self.versioned_rows().await?; - if !self - .instances - .iter() - .any(|instance| subscribed(&rows, &instance)) - { - return Ok((None, Vec::new())); - } + let relevant = self.instances.iter().any(|instance| { + instance.config.hooks.contains(&hook) + || first_registration && instance.config.scope == Scope::Default + }); + if !relevant { + return Ok((None, Vec::new())); } let (params_version, rows, account_rows) = self.snapshot(&account_id).await?; let defaults: Vec = if first_registration { @@ -671,6 +722,7 @@ impl ModulePipeline { hook, account_id, modules, + network_id: self.network_id, catalog_hash: self.catalog_hash.clone(), params_version, views: self.views.clone(), @@ -747,6 +799,11 @@ impl ModulePipeline { } impl Plan<'_> { + /// The network this Guardian serves, for this plan's request. + pub fn network_id(&self) -> &'static str { + self.network_id + } + /// The replica's account view cache, for building this plan's request. pub fn views(&self) -> Arc { self.views.clone() @@ -762,6 +819,7 @@ impl Plan<'_> { hook, account_id, modules, + network_id: _, catalog_hash, params_version, views: _, @@ -793,7 +851,13 @@ impl Plan<'_> { } }; + let caller = if dry_run { + Caller::DryRun + } else { + Caller::Request + }; let deadline = tokio::time::Instant::now() + limits.budget; + let mut called_before = false; for (instance, params, layer) in modules { let id = instance.config.id.as_str(); let mut request = base.clone(); @@ -803,12 +867,12 @@ impl Plan<'_> { let remaining = deadline.saturating_duration_since(tokio::time::Instant::now()); let size = prost::Message::encoded_len(&request); - let unsent = if !breakers.admits(id) { - Some(Failure::CircuitOpen) - } else if size > limits.request_max_bytes { + let unsent = if size > limits.request_max_bytes { Some(Failure::RequestTooLarge(size)) } else if remaining.is_zero() { Some(Failure::Timeout) + } else if !breakers.admit(id, caller) { + Some(Failure::CircuitOpen) } else { None }; @@ -824,8 +888,10 @@ impl Plan<'_> { continue; } - // A call the budget cuts short counts as a timeout, but is not the module's failure. - let cut_by_budget = remaining < instance.config.timeout; + // A call that earlier modules left less than its timeout counts as a timeout, but is + // not the module's failure. The first call always has its whole share. + let cut_by_budget = called_before && remaining < instance.config.timeout; + called_before = true; let module = instance.module.clone(); let started = tokio::time::Instant::now(); let outcome = isolated(instance.config.timeout.min(remaining), async move { @@ -835,14 +901,18 @@ impl Plan<'_> { let took = started.elapsed(); let failure = match outcome.map(|decision| (effect(&decision), decision)) { Ok((Some(Effect::Allow), _)) => { - breakers.answered(id); + if !dry_run { + breakers.answered(id); + } super::metrics::evaluated(id, super::metrics::Outcome::Allow, took); continue; } Ok((Some(Effect::Deny), decision)) if is_valid_reason_code(&decision.reason_code) => { - breakers.answered(id); + if !dry_run { + breakers.answered(id); + } super::metrics::evaluated(id, super::metrics::Outcome::Deny, took); tracing::info!( request_id = %request_id, @@ -870,6 +940,9 @@ impl Plan<'_> { } Ok((Some(_), decision)) => Failure::InvalidDecision(decision.reason_code), Ok((None, decision)) => Failure::UnknownEffect(decision.effect), + Err(CallError::Module(guardian_module_sdk::ModuleError::InvalidRequest( + message, + ))) => Failure::Rejected(message), Err(CallError::Module(error)) => Failure::Error(error.to_string()), Err(CallError::Panicked(message)) => { Failure::Error(format!("module panicked: {message}")) @@ -877,10 +950,15 @@ impl Plan<'_> { Err(CallError::Timeout) => Failure::Timeout, }; super::metrics::evaluated(id, super::metrics::Outcome::Error, took); - // A dry run is sent by a cosigner without anyone's signature, so its failures do not - // count toward opening the breaker for every account. - if !dry_run && !(cut_by_budget && matches!(failure, Failure::Timeout)) { - breakers.failed(id); + // The breaker stops calls to a module that is down for every account, so only + // failures that say so count: not a dry run's, which a cosigner sends without anyone's + // signature, not a request the module rejected, and not a budget cut. + if !dry_run { + match failure { + Failure::Rejected(_) => breakers.answered(id), + Failure::Timeout if cut_by_budget => {} + _ => breakers.failed(id), + } } approval .failed_open @@ -906,14 +984,12 @@ fn client_message(text: &str) -> Option { (!capped.is_empty()).then_some(capped) } -/// What a decision asks for. A module that predates `effect` leaves it unspecified and the -/// legacy `allow` decides; a value this Guardian does not know is `None`. +/// What a decision asks for: `None` for a decision that sets no effect or one this Guardian +/// does not know, neither of which is ever read as an allow. fn effect(decision: &Decision) -> Option { match Effect::try_from(decision.effect) { - Ok(Effect::Unspecified) if decision.allow => Some(Effect::Allow), - Ok(Effect::Unspecified) => Some(Effect::Deny), + Ok(Effect::Unspecified) | Err(_) => None, Ok(effect) => Some(effect), - Err(_) => None, } } @@ -1011,6 +1087,7 @@ params = {params} let registry = Registry::first_party(); let now = "2026-10-15T00:00:00Z".to_string(); let started = ModulePipeline::new( + "local", caps_catalog(r#"{ max_amount_per_txx = {} }"#), ®istry, store.clone(), @@ -1023,6 +1100,7 @@ params = {params} let fixed = caps_catalog(r#"{ max_amount_per_tx = { "0xaa" = "5" } }"#); let started = ModulePipeline::new( + "local", fixed, ®istry, store.clone(), @@ -1055,6 +1133,7 @@ params = {params} .await .unwrap(); ModulePipeline::new( + "local", caps_catalog(r#"{ max_amount_per_txx = {} }"#), ®istry, store.clone(), @@ -1079,6 +1158,7 @@ params = {params} let valid_seed = caps_catalog(r#"{ max_amount_per_tx = {} }"#); assert!( ModulePipeline::new( + "local", valid_seed, ®istry, store, @@ -1213,9 +1293,8 @@ params = {params} )]) } - fn decision(allow: bool, reason_code: &str, effect: i32) -> Behaviour { + fn decision(reason_code: &str, effect: i32) -> Behaviour { Behaviour::Decide(Decision { - allow, reason_code: reason_code.into(), effect, ..Default::default() @@ -1223,36 +1302,32 @@ params = {params} } #[tokio::test] - async fn the_effect_decides_and_an_unknown_one_is_a_failure() { - let denied = |behaviour| async { - matches!( - run(&pipeline_with(OnError::Deny, behaviour)).await, - Err(GuardianError::ModuleDenied { .. }) - ) - }; - assert!( - denied(decision(false, "legacy_deny", Effect::Unspecified as i32)).await, - "a module without effect: allow = false still denies" - ); - assert!( - denied(decision(true, "explicit_deny", Effect::Deny as i32)).await, - "effect wins over allow" - ); + async fn the_effect_decides_and_a_missing_or_unknown_one_is_a_failure() { + assert!(matches!( + run(&pipeline_with( + OnError::Deny, + decision("explicit_deny", Effect::Deny as i32) + )) + .await, + Err(GuardianError::ModuleDenied { .. }) + )); assert!( run(&pipeline_with( OnError::Deny, - decision(false, "", Effect::Allow as i32) + decision("", Effect::Allow as i32) )) .await .is_ok() ); - assert!( - matches!( - run(&pipeline_with(OnError::Deny, decision(true, "", 99))).await, - Err(GuardianError::ModuleUnavailable { .. }) - ), - "an effect this Guardian does not know is never read as an allow" - ); + for effect in [Effect::Unspecified as i32, 99] { + assert!( + matches!( + run(&pipeline_with(OnError::Deny, decision("", effect))).await, + Err(GuardianError::ModuleUnavailable { .. }) + ), + "effect {effect} is never read as an allow" + ); + } } #[tokio::test] @@ -1284,6 +1359,7 @@ params = { old_name = 5 } let store: Arc = Arc::new(super::super::store::FsModuleStore::in_memory()); ModulePipeline::new( + "local", catalog.clone(), ®istry, store.clone(), @@ -1331,6 +1407,7 @@ params = { old_name = 5 } let now = "2026-10-16T00:00:00Z".to_string(); ModulePipeline::new( + "local", catalog(), ®istry, store.clone(), @@ -1359,6 +1436,7 @@ params = { old_name = 5 } .await .unwrap(); ModulePipeline::new( + "local", catalog(), ®istry, store.clone(), @@ -1512,6 +1590,7 @@ params = { old_name = 1000 } )]; ModulePipeline::new( + "local", catalog, ®istry, store.clone(), @@ -1952,6 +2031,45 @@ mod failure_handling_tests { assert_eq!(pipeline.breakers().state("screening"), CircuitState::Closed); } + #[tokio::test] + async fn a_request_the_module_rejects_does_not_open_the_circuit() { + let pipeline = ModulePipeline::from_instances(vec![instance( + "screening", + &[HOOK], + OnError::Deny, + StubModule::new(Behaviour::Reject), + )]) + .with_limits(Limits { + breaker_failures: 2, + ..Limits::default() + }); + for _ in 0..4 { + assert!(matches!( + run(&pipeline).await, + Err(GuardianError::ModuleUnavailable { .. }) + )); + } + assert_eq!( + pipeline.breakers().state("screening"), + CircuitState::Closed, + "one account's unjudgeable requests do not stop the module for every account" + ); + } + + #[tokio::test] + async fn a_module_whose_timeout_is_the_whole_budget_still_opens_the_circuit() { + let (hung, _) = hanging("screening", OnError::Deny, Duration::from_millis(40)); + let pipeline = ModulePipeline::from_instances(vec![hung]).with_limits(Limits { + budget: Duration::from_millis(40), + breaker_failures: 2, + ..Limits::default() + }); + for _ in 0..2 { + assert!(run(&pipeline).await.is_err()); + } + assert_eq!(pipeline.breakers().state("screening"), CircuitState::Open); + } + #[tokio::test] async fn consecutive_failures_open_the_circuit_so_later_requests_skip_the_timeout() { let (hung, module) = hanging("screening", OnError::Deny, Duration::from_millis(50)); diff --git a/crates/server/src/modules/registry.rs b/crates/server/src/modules/registry.rs index 910cd489..079c1d34 100644 --- a/crates/server/src/modules/registry.rs +++ b/crates/server/src/modules/registry.rs @@ -190,13 +190,20 @@ impl std::fmt::Display for CallError { /// Runs one module call on its own task, so a panic in the module becomes an error instead of /// unwinding through the request, and the timeout holds even when an in-process module blocks -/// instead of awaiting. A call that times out is aborted at its next await point. +/// instead of awaiting. A call that times out, or whose caller goes away, is aborted at its next +/// await point. pub async fn isolated( timeout: std::time::Duration, call: impl std::future::Future> + Send + 'static, ) -> Result { - let mut task = tokio::spawn(call); - match tokio::time::timeout(timeout, &mut task).await { + struct AbortOnDrop(tokio::task::JoinHandle); + impl Drop for AbortOnDrop { + fn drop(&mut self) { + self.0.abort(); + } + } + let mut task = AbortOnDrop(tokio::spawn(call)); + match tokio::time::timeout(timeout, &mut task.0).await { Ok(Ok(result)) => result.map_err(CallError::Module), Ok(Err(error)) => Err(CallError::Panicked(match error.try_into_panic() { Ok(payload) => payload @@ -206,10 +213,7 @@ pub async fn isolated( .unwrap_or_else(|| "non-string panic payload".into()), Err(error) => error.to_string(), })), - Err(_) => { - task.abort(); - Err(CallError::Timeout) - } + Err(_) => Err(CallError::Timeout), } } @@ -219,10 +223,7 @@ pub async fn isolated( pub const MIN_PROTOCOL_VERSION: u32 = PROTOCOL_VERSION; /// Optional protocol features this Guardian provides. -pub const CAPABILITIES: &[&str] = &[ - capability::DECISION_EFFECT, - capability::PARAMS_NORMALIZATION, -]; +pub const CAPABILITIES: &[&str] = &[capability::PARAMS_NORMALIZATION]; /// What the Guardian tells a module in `Describe`. pub fn describe_request() -> DescribeRequest { @@ -384,9 +385,19 @@ enabled = ENABLED Catalog::parse(text, None).expect("guide catalog parses"); } let built_in = include_str!("../../../../docs/guides/policy-modules/built-in.toml"); - let instances = Registry::first_party() + let unedited = Registry::first_party() .instantiate(&catalog(built_in), &HashMap::new()) .await + .err() + .expect("the guide catalog does not start until its placeholder is replaced"); + assert!(unedited.contains("not an id in 0x hex form"), "{unedited}"); + let edited = built_in.replace( + "0xREPLACE_WITH_FAUCET_ID", + "0x0a1b2c3d4e5f60718293a4b5c6d7e8", + ); + let instances = Registry::first_party() + .instantiate(&catalog(&edited), &HashMap::new()) + .await .expect("the built-in guide catalog passes the startup checks") .instances; assert!(instances.iter().all(|instance| instance.config.enabled)); @@ -547,7 +558,7 @@ params = { old_name = 5 } assert!(error.contains("requires capability pending.v2"), "{error}"); let mut stub = crate::modules::testing::ProtocolStub::new(); - stub.required_capabilities = vec![capability::DECISION_EFFECT.into()]; + stub.required_capabilities = vec![capability::PARAMS_NORMALIZATION.into()]; assert!(load(stub).await.is_ok()); } diff --git a/crates/server/src/modules/testing.rs b/crates/server/src/modules/testing.rs index 31181996..afe22bab 100644 --- a/crates/server/src/modules/testing.rs +++ b/crates/server/src/modules/testing.rs @@ -16,6 +16,8 @@ use super::registry::Instance; pub enum Behaviour { Decide(Decision), Fail, + /// Refuses the request as one it cannot judge. + Reject, Hang, Panic, /// Blocks its thread instead of awaiting, like a module doing synchronous work. @@ -76,6 +78,7 @@ impl Module for StubModule { match &self.behaviour { Behaviour::Decide(decision) => Ok(decision.clone()), Behaviour::Fail => Err(ModuleError::Unavailable("stub down".into())), + Behaviour::Reject => Err(ModuleError::InvalidRequest("stub cannot judge".into())), Behaviour::Hang => { tokio::time::sleep(Duration::from_secs(60)).await; Ok(Decision::allow()) @@ -232,12 +235,12 @@ impl RacingStore { for write in writes { match write { RacingWrite::Global(module, params) => { - self.inner.set_global(module, params, &change).await? + self.inner.set_global(module, params, &change).await?; } RacingWrite::Layer(account, module, params) => { self.inner .set_layer(account, module, params, &change) - .await? + .await?; } } } @@ -284,7 +287,7 @@ impl super::store::ModuleStore for RacingStore { module_id: &str, enabled: bool, change: &super::store::Change<'_>, - ) -> Result<(), String> { + ) -> Result { self.inner.set_enabled(module_id, enabled, change).await } @@ -293,7 +296,7 @@ impl super::store::ModuleStore for RacingStore { module_id: &str, params: serde_json::Value, change: &super::store::Change<'_>, - ) -> Result<(), String> { + ) -> Result { self.inner.set_global(module_id, params, change).await } @@ -303,7 +306,7 @@ impl super::store::ModuleStore for RacingStore { expected: &serde_json::Value, params: serde_json::Value, change: &super::store::Change<'_>, - ) -> Result { + ) -> Result, String> { let writes = std::mem::take(&mut *self.before_set_global_if.lock().unwrap()); self.commit(writes).await?; self.inner @@ -341,7 +344,7 @@ impl super::store::ModuleStore for RacingStore { module_id: &str, params: Option, change: &super::store::Change<'_>, - ) -> Result<(), String> { + ) -> Result { self.inner .set_layer(account_id, module_id, params, change) .await @@ -352,7 +355,7 @@ impl super::store::ModuleStore for RacingStore { account_id: &str, modules: Vec, change: &super::store::Change<'_>, - ) -> Result<(), String> { + ) -> Result { self.inner.set_assignment(account_id, modules, change).await } From 68e7e0d493de37822cb4d9fae803a4f62e5247d4 Mon Sep 17 00:00:00 2001 From: Zeljko Date: Tue, 10 Nov 2026 07:34:19 +0100 Subject: [PATCH 073/105] fix(modules): catalog, startup and operator write rules (#251) - A set-but-empty GUARDIAN_MODULES_CONFIG or a catalog without modules refuses startup; an unset variable is logged, as a warning when module state is stored. - Instance ids follow [a-z0-9_-]{1,64}; scope = default with secret references is refused; an empty module token is refused. - A layer is refused while the module is still assigned to the account; reasons are capped at 512 characters. - Operator writes return the params version they committed as, and their audit entries name it; an assignment audit lists the modules. - Fail-open skips at proposal creation and registration are audited as modules.failed_open; a default copy that is not written is logged. - The module routes document 400 for no catalog, 409 on disable and 503 on enable. - custom_module_server follows the server binary; modules_admin keygen writes the key owner-only. --- .../server/examples/custom_module_server.rs | 17 ++- crates/server/examples/modules_admin.rs | 13 +- crates/server/src/api/dashboard_modules.rs | 36 ++--- crates/server/src/audit/kinds.rs | 10 ++ crates/server/src/modules/admin.rs | 126 +++++++++++++++--- crates/server/src/modules/catalog.rs | 51 +++++++ crates/server/src/modules/mod.rs | 115 +++++++++++++++- crates/server/src/modules/postgres_store.rs | 49 ++++--- crates/server/src/modules/secrets.rs | 10 +- crates/server/src/modules/store.rs | 89 ++++++++++--- .../server/src/services/configure_account.rs | 101 ++++++++++---- .../src/services/push_delta_proposal.rs | 76 ++++++++++- 12 files changed, 583 insertions(+), 110 deletions(-) diff --git a/crates/server/examples/custom_module_server.rs b/crates/server/examples/custom_module_server.rs index dad84ca4..1aaa4e35 100644 --- a/crates/server/examples/custom_module_server.rs +++ b/crates/server/examples/custom_module_server.rs @@ -59,6 +59,8 @@ async fn main() { let stage = Stage::from_env().expect("Invalid GUARDIAN_ENV"); + let release_sweep = server::release_sweep::ReleaseSweepConfig::from_env() + .expect("Invalid release sweep configuration"); ServerBuilder::new() .with_logging(LoggingConfig::default()) .network(network_type) @@ -76,11 +78,18 @@ async fn main() { .with_reconcile_interval_seconds_from_env() .expect("Invalid reconcile interval configuration") .with_max_pending_candidates_per_account_from_env() - .expect("Invalid pending-candidate queue depth configuration"), + .expect("Invalid pending-candidate queue depth configuration") + .with_rebuild_admission_from_env() + .expect("Invalid canonicalization rebuild admission configuration"), )) - .with_release_sweep(Some( - server::release_sweep::ReleaseSweepConfig::from_env() - .expect("Invalid release sweep configuration"), + .with_execution( + server::config::execution::ExecutionConfig::from_env() + .expect("Invalid Guardian execution configuration"), + ) + .with_release_sweep(Some(release_sweep.clone())) + .with_block_watch(Some( + server::block_watch::BlockWatchConfig::from_env_following(release_sweep.enabled) + .expect("Invalid block watch configuration"), )) .with_rate_limit(RateLimitConfig::from_env()) .with_body_limit(BodyLimitConfig::from_env()) diff --git a/crates/server/examples/modules_admin.rs b/crates/server/examples/modules_admin.rs index 077efb13..7c663a0a 100644 --- a/crates/server/examples/modules_admin.rs +++ b/crates/server/examples/modules_admin.rs @@ -18,9 +18,20 @@ fn load_key(path: &str) -> Result { Ok(SecretKey::read_from_bytes(&bytes)?) } +/// Writes the operator key readable by its owner only, and never over an existing file. +fn write_private(path: &str, contents: &str) -> Result<(), Error> { + use std::io::Write; + let mut options = std::fs::OpenOptions::new(); + options.write(true).create_new(true); + #[cfg(unix)] + std::os::unix::fs::OpenOptionsExt::mode(&mut options, 0o600); + options.open(path)?.write_all(contents.as_bytes())?; + Ok(()) +} + fn keygen(path: &str) -> Result<(), Error> { let key = SecretKey::new(); - std::fs::write(path, hex::encode(key.to_bytes()))?; + write_private(path, &hex::encode(key.to_bytes()))?; let public_key = key.public_key(); println!("key written to {path}"); println!("commitment: {}", public_key.to_commitment().into_hex()); diff --git a/crates/server/src/api/dashboard_modules.rs b/crates/server/src/api/dashboard_modules.rs index 0c399e5b..ddf5c6d4 100644 --- a/crates/server/src/api/dashboard_modules.rs +++ b/crates/server/src/api/dashboard_modules.rs @@ -52,9 +52,10 @@ async fn body( security(("operator_session" = [])), responses( (status = 200, description = "Module instances with their runtime state", body = ModuleCatalogView), + (status = 400, description = "No policy modules are configured", body = crate::openapi::ApiErrorResponse), (status = 401, description = "No operator session", body = crate::openapi::ApiErrorResponse), (status = 403, description = "Missing dashboard:read permission", body = crate::openapi::ApiErrorResponse), - (status = 404, description = "Account or module not found, or no modules configured", body = crate::openapi::ApiErrorResponse), + (status = 404, description = "Account or module not found", body = crate::openapi::ApiErrorResponse), ) )] pub async fn list_modules(State(state): State) -> Result> { @@ -69,9 +70,10 @@ pub async fn list_modules(State(state): State) -> Result(pipeline: &'a ModulePipeline, module_id: &str) -> Result<&'a Ins }) } +const MAX_REASON_CHARS: usize = 512; + fn require_reason(reason: &str) -> Result<()> { if reason.trim().is_empty() { return Err(GuardianError::InvalidInput("reason is required".into())); } + if reason.chars().count() > MAX_REASON_CHARS { + return Err(GuardianError::InvalidInput(format!( + "reason exceeds {MAX_REASON_CHARS} character limit" + ))); + } Ok(()) } @@ -386,6 +393,7 @@ pub async fn enable( require_reason(reason)?; let pipeline = pipeline(state)?; let instance = instance(pipeline, module_id)?; + let mut committed = None; if !pipeline.enabled(instance).await? { let params = pipeline.global_params(instance).await?; let checked = super::registry::check(&instance.config, &instance.module, ¶ms) @@ -421,18 +429,20 @@ pub async fn enable( ) .await .map_err(GuardianError::StorageError)?; - if !migrated { + if migrated.is_none() { tracing::warn!(module = %module_id, "Global params changed while the module migrated them; kept the newer value"); } } - pipeline - .store() - .set_enabled(module_id, true, &change(state, operator, reason)) - .await - .map_err(GuardianError::StorageError)?; + committed = Some( + pipeline + .store() + .set_enabled(module_id, true, &change(state, operator, reason)) + .await + .map_err(GuardianError::StorageError)?, + ); super::metrics::enabled(module_id, true); } - let payload = serde_json::json!({ "module_id": module_id, "reason": reason, "params_version": version(pipeline).await? }); + let payload = serde_json::json!({ "module_id": module_id, "reason": reason, "params_version": committed }); audit( state, operator, @@ -460,15 +470,18 @@ pub async fn disable( module: module_id.to_string(), }); } + let mut committed = None; if pipeline.enabled(instance).await? { - pipeline - .store() - .set_enabled(module_id, false, &change(state, operator, reason)) - .await - .map_err(GuardianError::StorageError)?; + committed = Some( + pipeline + .store() + .set_enabled(module_id, false, &change(state, operator, reason)) + .await + .map_err(GuardianError::StorageError)?, + ); super::metrics::enabled(module_id, false); } - let payload = serde_json::json!({ "module_id": module_id, "reason": reason, "params_version": version(pipeline).await? }); + let payload = serde_json::json!({ "module_id": module_id, "reason": reason, "params_version": committed }); audit( state, operator, @@ -497,12 +510,12 @@ pub async fn set_global( ))); } let params = validated(pipeline, instance, ¶ms).await?; - pipeline + let committed = pipeline .store() .set_global(module_id, params, &change(state, operator, reason)) .await .map_err(GuardianError::StorageError)?; - let payload = serde_json::json!({ "module_id": module_id, "reason": reason, "params_version": version(pipeline).await? }); + let payload = serde_json::json!({ "module_id": module_id, "reason": reason, "params_version": committed }); audit( state, operator, @@ -541,6 +554,15 @@ pub async fn set_layer( .account_params(&account_id) .await .map_err(GuardianError::StorageError)?; + if params.is_some() + && current + .iter() + .any(|row| row.kind == ParamsKind::Assignment && row.module_id == module_id) + { + return Err(GuardianError::InvalidInput(format!( + "module {module_id}: the account still has it assigned from when it applied only to assigned accounts; remove it from the account's assignment first" + ))); + } let mut rows = current.clone(); rows.retain(|row| !(row.kind == ParamsKind::Layer && row.module_id == module_id)); if let Some(params) = ¶ms { @@ -552,7 +574,7 @@ pub async fn set_layer( )); } pipeline.check_budget(¤t, &rows)?; - pipeline + let committed = pipeline .store() .set_layer( &account_id, @@ -562,7 +584,7 @@ pub async fn set_layer( ) .await .map_err(GuardianError::StorageError)?; - let payload = serde_json::json!({ "module_id": module_id, "reason": reason, "params_version": version(pipeline).await? }); + let payload = serde_json::json!({ "module_id": module_id, "reason": reason, "params_version": committed }); audit( state, operator, @@ -666,13 +688,17 @@ pub async fn set_assignment( ) })); pipeline.check_budget(¤t, &rows)?; - pipeline + let assigned: Vec = to_store + .iter() + .map(|assigned| assigned.module_id.clone()) + .collect(); + let committed = pipeline .store() .set_assignment(&account_id, to_store, &change(state, operator, reason)) .await .map_err(GuardianError::StorageError)?; let payload = - serde_json::json!({ "reason": reason, "params_version": version(pipeline).await? }); + serde_json::json!({ "reason": reason, "modules": assigned, "params_version": committed }); audit( state, operator, @@ -1061,6 +1087,68 @@ mod tests { assign().await.expect("then the module can be assigned"); } + #[tokio::test] + async fn a_layer_is_refused_while_the_module_is_still_assigned_to_the_account() { + let mut state = state(); + let operator = operator(); + set_assignment( + &state, + &operator, + ACCOUNT, + vec![Assigned { + module_id: "optional".into(), + params: json!({}), + }], + "OP-1", + None, + ) + .await + .unwrap(); + let hooks = [HookName::BeforeTransactionApproved]; + let store = state.modules.as_ref().unwrap().store_handle(); + state.modules = Some(Arc::new(ModulePipeline::from_instances_with_store( + vec![instance( + "optional", + &hooks, + OnError::Deny, + Arc::new(BasicPolicy), + )], + store, + ))); + let layer = set_layer( + &state, + &operator, + ACCOUNT, + "optional", + Some(json!({})), + "OP-2", + None, + ) + .await; + assert!( + matches!(layer, Err(GuardianError::InvalidInput(message)) if message.contains("remove it from the account's assignment first")), + "the scope change left an assignment row for the module" + ); + } + + #[tokio::test] + async fn a_reason_longer_than_the_limit_is_refused() { + let state = state(); + let refused = set_layer( + &state, + &operator(), + ACCOUNT, + "blocklist", + Some(json!({})), + &"r".repeat(MAX_REASON_CHARS + 1), + None, + ) + .await; + assert!( + matches!(refused, Err(GuardianError::InvalidInput(message)) if message.contains("character limit")) + ); + } + #[tokio::test] async fn an_account_already_over_the_budget_can_be_brought_back_under_it() { let mut state = state(); diff --git a/crates/server/src/modules/catalog.rs b/crates/server/src/modules/catalog.rs index 99f12a6d..67095038 100644 --- a/crates/server/src/modules/catalog.rs +++ b/crates/server/src/modules/catalog.rs @@ -172,6 +172,15 @@ pub enum ClientReason { } const DESCRIPTION_MAX_CHARS: usize = 500; +const INSTANCE_ID_MAX_CHARS: usize = 64; + +/// An instance id is a metric label, a log field and a path segment of the operator routes. +fn valid_instance_id(id: &str) -> bool { + (1..=INSTANCE_ID_MAX_CHARS).contains(&id.len()) + && id + .bytes() + .all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || b == b'_' || b == b'-') +} #[derive(Debug, Deserialize)] #[serde(deny_unknown_fields)] @@ -393,6 +402,11 @@ impl Catalog { let mut instances = Vec::with_capacity(file.modules.len()); for entry in file.modules { let id = entry.id; + if !valid_instance_id(&id) { + return Err(format!( + "module {id:?}: an id is 1 to {INSTANCE_ID_MAX_CHARS} characters of a-z, 0-9, '_' or '-'" + )); + } if !seen.insert(id.clone()) { return Err(format!("module {id}: duplicate id")); } @@ -442,6 +456,11 @@ impl Catalog { "module {id}: secret references are not allowed in remote module params" )); } + if entry.scope == Scope::Default && contains_secret_reference(¶ms) { + return Err(format!( + "module {id}: scope = \"default\" copies its params into each new account, and secret references cannot be stored per account; use scope \"all\" or \"assigned\"" + )); + } if entry.disclosure == Disclosure::Params && contains_secret_reference(¶ms) { return Err(format!( "module {id}: disclosure = \"params\" would show cosigners the secret references in its params; use \"summary\" or \"none\"" @@ -638,12 +657,44 @@ on_error = "allow" "grpc without endpoint", VALID.replacen(r#"kind = "basic-policy""#, r#"kind = "grpc""#, 1), ), + ( + "empty id", + VALID.replacen(r#"id = "caps""#, r#"id = """#, 1), + ), + ( + "id that is not a path segment", + VALID.replacen(r#"id = "caps""#, r#"id = "Caps/v2""#, 1), + ), + ( + "id over the length limit", + VALID.replacen(r#"id = "caps""#, &format!("id = \"{}\"", "a".repeat(65)), 1), + ), ]; for (name, text) in cases { assert!(parse(&text).is_err(), "{name} should be rejected"); } } + #[test] + fn default_instances_cannot_hold_secret_references() { + let catalog = |scope: &str| { + format!( + r#" +[[module]] +id = "vendor" +kind = "basic-policy" +scope = "{scope}" +hooks = ["before_transaction_approved"] +timeout_ms = 20 +params = {{ api_key = {{ "$secret" = "vendor-key" }} }} +"# + ) + }; + assert!(parse(&catalog("all")).is_ok()); + let refused = parse(&catalog("default")).unwrap_err(); + assert!(refused.contains("copies its params"), "{refused}"); + } + #[test] fn params_with_secret_references_are_file_managed() { let text = VALID.replacen( diff --git a/crates/server/src/modules/mod.rs b/crates/server/src/modules/mod.rs index 61d468e2..762d8758 100644 --- a/crates/server/src/modules/mod.rs +++ b/crates/server/src/modules/mod.rs @@ -48,12 +48,58 @@ pub async fn from_env( store: Option>, registry: &Registry, execution_lease: std::time::Duration, + network: crate::network::NetworkType, ) -> Result>, String> { - let Some(path) = std::env::var_os(CONFIG_ENV).filter(|value| !value.is_empty()) else { + load( + std::env::var_os(CONFIG_ENV), + now, + store, + registry, + execution_lease, + network, + ) + .await +} + +/// [`from_env`] for `config`, the value of `GUARDIAN_MODULES_CONFIG`. Only an unset variable +/// means "no modules": an empty value or a catalog that declares none is a mistake that would +/// otherwise start the server without any policy. +async fn load( + config: Option, + now: String, + store: Option>, + registry: &Registry, + execution_lease: std::time::Duration, + network: crate::network::NetworkType, +) -> Result>, String> { + let Some(path) = config else { + let stored = match &store { + Some(store) => store.instances().await?.len(), + None => 0, + }; + if stored > 0 { + tracing::warn!( + stored_instances = stored, + "{CONFIG_ENV} is not set: no policy module runs, although this Guardian's database holds module state from an earlier catalog" + ); + } else { + tracing::info!("{CONFIG_ENV} is not set: no policy module runs"); + } return Ok(None); }; + if path.is_empty() { + return Err(format!( + "{CONFIG_ENV} is set but empty; point it at a catalog file, or unset it to run without policy modules" + )); + } let catalog_path = PathBuf::from(path); let mut catalog = Catalog::load(&catalog_path)?; + if catalog.instances.is_empty() { + return Err(format!( + "module catalog {} declares no module; unset {CONFIG_ENV} to run without policy modules", + catalog_path.display() + )); + } let limits = limits::Limits::from_env()?; let prod = crate::config::stage::Stage::from_env() .map_err(|e| e.to_string())? @@ -73,7 +119,8 @@ pub async fn from_env( Some(store) => store, None => Arc::new(filesystem_store(&catalog_path)?), }; - let pipeline = ModulePipeline::new(catalog, registry, store, now, limits).await?; + let network_id = crate::metadata::network::MidenNetworkType::from(network).as_str(); + let pipeline = ModulePipeline::new(network_id, catalog, registry, store, now, limits).await?; let version = pipeline.store().version().await?; let (over_budget, orphaned) = pipeline.report_stored_assignments().await?; let builds = pipeline @@ -91,3 +138,67 @@ pub async fn from_env( tracing::info!(catalog_hash = %pipeline.catalog_hash, params_version = version, %builds, over_budget, orphaned, "Policy modules loaded"); Ok(Some(Arc::new(pipeline))) } + +#[cfg(test)] +mod tests { + use super::*; + + async fn loaded(config: Option<&str>) -> Result>, String> { + load( + config.map(Into::into), + "2026-11-10T00:00:00Z".into(), + Some(Arc::new(store::FsModuleStore::in_memory())), + &Registry::first_party(), + std::time::Duration::from_secs(60), + crate::network::NetworkType::MidenLocal, + ) + .await + } + + fn catalog_file(text: &str) -> (tempfile::TempDir, String) { + let dir = tempfile::tempdir().unwrap(); + let path = dir.path().join("modules.toml"); + std::fs::write(&path, text).unwrap(); + let path = path.to_str().unwrap().to_string(); + (dir, path) + } + + #[tokio::test] + async fn only_an_unset_variable_runs_without_modules() { + assert!(loaded(None).await.unwrap().is_none()); + + let empty_value = loaded(Some("")) + .await + .err() + .expect("an empty value is refused"); + assert!(empty_value.contains("is set but empty"), "{empty_value}"); + + for text in ["", "# every module commented out\n"] { + let (_dir, path) = catalog_file(text); + let no_module = loaded(Some(&path)) + .await + .err() + .expect("a catalog without modules is refused"); + assert!(no_module.contains("declares no module"), "{no_module}"); + } + } + + #[tokio::test] + async fn a_catalog_with_a_module_loads() { + let (_dir, path) = catalog_file( + r#" +[[module]] +id = "caps" +kind = "basic-policy" +scope = "all" +hooks = ["before_transaction_approved"] +timeout_ms = 20 +"#, + ); + let pipeline = loaded(Some(&path)) + .await + .unwrap() + .expect("the catalog declares a module"); + assert_eq!(pipeline.instances().len(), 1); + } +} diff --git a/crates/server/src/modules/postgres_store.rs b/crates/server/src/modules/postgres_store.rs index 8f342889..438c1b8e 100644 --- a/crates/server/src/modules/postgres_store.rs +++ b/crates/server/src/modules/postgres_store.rs @@ -252,7 +252,7 @@ impl ModuleStore for PgModuleStore { module_id: &str, enabled: bool, change: &Change<'_>, - ) -> Result<(), String> { + ) -> Result { #[derive(QueryableByName)] struct EnabledSql { #[diesel(sql_type = Bool)] @@ -261,7 +261,7 @@ impl ModuleStore for PgModuleStore { let changed_at = at(change)?; let mut conn = self.conn().await?; let module_id = module_id.to_string(); - conn.transaction::<(), diesel::result::Error, _>(|conn| { + conn.transaction::(|conn| { async move { let version = bump(conn).await?; let previous: Vec = diesel::sql_query( @@ -296,11 +296,12 @@ impl ModuleStore for PgModuleStore { changed_at, ) .await?; - Ok(()) + Ok(version) } .scope_boxed() }) .await + .map(|version| version as u64) .map_err(|e| format!("set enabled: {e}")) } @@ -309,11 +310,11 @@ impl ModuleStore for PgModuleStore { module_id: &str, params: serde_json::Value, change: &Change<'_>, - ) -> Result<(), String> { + ) -> Result { let changed_at = at(change)?; let mut conn = self.conn().await?; let module_id = module_id.to_string(); - conn.transaction::<(), diesel::result::Error, _>(|conn| { + conn.transaction::(|conn| { async move { let version = bump(conn).await?; let previous: Vec = diesel::sql_query( @@ -345,11 +346,12 @@ impl ModuleStore for PgModuleStore { conn, version, &module_id, None, &previous, ¶ms, change, changed_at, ) .await?; - Ok(()) + Ok(version) } .scope_boxed() }) .await + .map(|version| version as u64) .map_err(|e| format!("set global params: {e}")) } @@ -359,12 +361,12 @@ impl ModuleStore for PgModuleStore { expected: &serde_json::Value, params: serde_json::Value, change: &Change<'_>, - ) -> Result { + ) -> Result, String> { let changed_at = at(change)?; let mut conn = self.conn().await?; let (module_id, expected) = (module_id.to_string(), expected.clone()); let written = conn - .transaction::<(), diesel::result::Error, _>(|conn| { + .transaction::(|conn| { async move { let version = bump(conn).await?; let current: Vec = diesel::sql_query( @@ -394,14 +396,14 @@ impl ModuleStore for PgModuleStore { conn, version, &module_id, None, &previous, ¶ms, change, changed_at, ) .await?; - Ok(()) + Ok(version) } .scope_boxed() }) .await; match written { - Ok(()) => Ok(true), - Err(diesel::result::Error::RollbackTransaction) => Ok(false), + Ok(version) => Ok(Some(version as u64)), + Err(diesel::result::Error::RollbackTransaction) => Ok(None), Err(e) => Err(format!("set global params: {e}")), } } @@ -465,11 +467,11 @@ impl ModuleStore for PgModuleStore { module_id: &str, params: Option, change: &Change<'_>, - ) -> Result<(), String> { + ) -> Result { let changed_at = at(change)?; let mut conn = self.conn().await?; let (account_id, module_id) = (account_id.to_string(), module_id.to_string()); - conn.transaction::<(), diesel::result::Error, _>(|conn| { + conn.transaction::(|conn| { async move { let version = bump(conn).await?; let previous: Vec = diesel::sql_query( @@ -511,11 +513,12 @@ impl ModuleStore for PgModuleStore { changed_at, ) .await?; - Ok(()) + Ok(version) } .scope_boxed() }) .await + .map(|version| version as u64) .map_err(|e| format!("set account layer: {e}")) } @@ -524,11 +527,11 @@ impl ModuleStore for PgModuleStore { account_id: &str, modules: Vec, change: &Change<'_>, - ) -> Result<(), String> { + ) -> Result { let changed_at = at(change)?; let mut conn = self.conn().await?; let account_id = account_id.to_string(); - conn.transaction::<(), diesel::result::Error, _>(|conn| { + conn.transaction::(|conn| { async move { let version = bump(conn).await?; let removed: Vec = diesel::sql_query( @@ -579,11 +582,12 @@ impl ModuleStore for PgModuleStore { ) .await?; } - Ok(()) + Ok(version) } .scope_boxed() }) .await + .map(|version| version as u64) .map_err(|e| format!("set assignment: {e}")) } @@ -980,8 +984,8 @@ mod tests { .await .unwrap(); let before = store.version().await.unwrap(); - assert!( - !store + assert_eq!( + store .set_global_if( &module, &json!({ "old_name": 1000 }), @@ -990,6 +994,7 @@ mod tests { ) .await .unwrap(), + None, "the stale expectation does not write" ); assert_eq!( @@ -997,7 +1002,7 @@ mod tests { before, "and does not move the version" ); - assert!( + assert_eq!( store .set_global_if( &module, @@ -1006,7 +1011,9 @@ mod tests { &change(t0) ) .await - .unwrap() + .unwrap(), + Some(before + 1), + "a write reports the version it committed as" ); let row = store .instances() diff --git a/crates/server/src/modules/secrets.rs b/crates/server/src/modules/secrets.rs index 54328d3f..6198f4dc 100644 --- a/crates/server/src/modules/secrets.rs +++ b/crates/server/src/modules/secrets.rs @@ -128,9 +128,13 @@ impl SecretRefs { } }; let auth_token = match &self.token { - Some(name) => Some(SecretString::from( - read(name).await?.expose_secret().trim().to_owned(), - )), + Some(name) => { + let token = read(name).await?.expose_secret().trim().to_owned(); + if token.is_empty() { + return Err(format!("secret {name}: the token is empty")); + } + Some(SecretString::from(token)) + } None => None, }; let tls = match &self.tls { diff --git a/crates/server/src/modules/store.rs b/crates/server/src/modules/store.rs index 031be251..f638c65e 100644 --- a/crates/server/src/modules/store.rs +++ b/crates/server/src/modules/store.rs @@ -98,30 +98,33 @@ pub trait ModuleStore: Send + Sync { /// Switches an instance on or off for every account. Recorded in the history as /// `{"enabled": previous}` to `{"enabled": new}`, so the version moves and caches refresh. + /// Like every operator write, returns the params version the write committed as, so the + /// audit entry of the write names that version and not one read afterwards. async fn set_enabled( &self, module_id: &str, enabled: bool, change: &Change<'_>, - ) -> Result<(), String>; + ) -> Result; async fn set_global( &self, module_id: &str, params: serde_json::Value, change: &Change<'_>, - ) -> Result<(), String>; + ) -> Result; - /// Replaces the global params only while they still equal `expected`, and returns whether - /// it wrote. For writes derived from a value read earlier (a module migrating params), so - /// an operator's newer write is never overwritten. + /// Replaces the global params only while they still equal `expected`, and returns the + /// version it committed as, or `None` when it did not write. For writes derived from a + /// value read earlier (a module migrating params), so an operator's newer write is never + /// overwritten. async fn set_global_if( &self, module_id: &str, expected: &serde_json::Value, params: serde_json::Value, change: &Change<'_>, - ) -> Result; + ) -> Result, String>; async fn account_params(&self, account_id: &str) -> Result, String>; @@ -142,14 +145,14 @@ pub trait ModuleStore: Send + Sync { module_id: &str, params: Option, change: &Change<'_>, - ) -> Result<(), String>; + ) -> Result; async fn set_assignment( &self, account_id: &str, modules: Vec, change: &Change<'_>, - ) -> Result<(), String>; + ) -> Result; /// Writes `modules` as the account's assignment only when it has neither an assignment nor /// any assignment history, which is how `default` instances reach a newly registered @@ -374,7 +377,7 @@ impl ModuleStore for FsModuleStore { module_id: &str, enabled: bool, change: &Change<'_>, - ) -> Result<(), String> { + ) -> Result { self.write(|tables| { let row = tables .instances @@ -390,7 +393,7 @@ impl ModuleStore for FsModuleStore { serde_json::json!({ "enabled": enabled }), change, ); - Ok(()) + Ok(tables.version()) }) } @@ -399,7 +402,7 @@ impl ModuleStore for FsModuleStore { module_id: &str, params: serde_json::Value, change: &Change<'_>, - ) -> Result<(), String> { + ) -> Result { self.write(|tables| { let row = tables .instances @@ -416,7 +419,7 @@ impl ModuleStore for FsModuleStore { row.updated_at = change.at.clone(); row.updated_by = change.operator.to_string(); tables.append(module_id, None, previous, params, change); - Ok(()) + Ok(tables.version()) }) } @@ -426,20 +429,20 @@ impl ModuleStore for FsModuleStore { expected: &serde_json::Value, params: serde_json::Value, change: &Change<'_>, - ) -> Result { + ) -> Result, String> { self.write(|tables| { let Some(row) = tables .instances .get_mut(module_id) .filter(|row| row.global_params == *expected) else { - return Ok(false); + return Ok(None); }; let previous = std::mem::replace(&mut row.global_params, params.clone()); row.updated_at = change.at.clone(); row.updated_by = change.operator.to_string(); tables.append(module_id, None, previous, params, change); - Ok(true) + Ok(Some(tables.version())) }) } @@ -477,7 +480,7 @@ impl ModuleStore for FsModuleStore { module_id: &str, params: Option, change: &Change<'_>, - ) -> Result<(), String> { + ) -> Result { self.write(|tables| { let previous = tables.row_params(account_id, module_id, ParamsKind::Layer); tables.account_params.retain(|row| { @@ -503,7 +506,7 @@ impl ModuleStore for FsModuleStore { params.unwrap_or_default(), change, ); - Ok(()) + Ok(tables.version()) }) } @@ -512,7 +515,7 @@ impl ModuleStore for FsModuleStore { account_id: &str, modules: Vec, change: &Change<'_>, - ) -> Result<(), String> { + ) -> Result { self.write(|tables| { let previous: Vec = tables .account_params @@ -537,7 +540,7 @@ impl ModuleStore for FsModuleStore { for (module_id, before, after) in assignment_changes(&previous, &modules) { tables.append(&module_id, Some(account_id), before, after, change); } - Ok(()) + Ok(tables.version()) }) } @@ -663,6 +666,54 @@ mod tests { assert_eq!(store.version().await.unwrap(), 2); } + #[tokio::test] + async fn each_write_reports_the_version_it_committed_as() { + let store = FsModuleStore::in_memory(); + store + .seed_instance("caps", true, &json!({}), "t0") + .await + .unwrap(); + let assigned = || { + vec![Assigned { + module_id: "caps".into(), + params: json!({}), + }] + }; + let writes = [ + store + .set_global("caps", json!({ "a": 1 }), &change()) + .await + .unwrap(), + store.set_enabled("caps", false, &change()).await.unwrap(), + store + .set_layer("0xacc", "caps", Some(json!({})), &change()) + .await + .unwrap(), + store + .set_assignment("0xother", assigned(), &change()) + .await + .unwrap(), + store + .set_global_if("caps", &json!({ "a": 1 }), json!({ "a": 2 }), &change()) + .await + .unwrap() + .expect("the expectation holds"), + ]; + assert!( + writes.windows(2).all(|pair| pair[0] < pair[1]), + "later writes commit as later versions: {writes:?}" + ); + assert_eq!(writes.last(), Some(&store.version().await.unwrap())); + assert_eq!( + store + .set_global_if("caps", &json!({ "a": 1 }), json!({ "a": 3 }), &change()) + .await + .unwrap(), + None, + "a stale expectation writes nothing and reports no version" + ); + } + #[tokio::test] async fn the_enabled_switch_is_stored_and_moves_the_version() { let store = FsModuleStore::in_memory(); diff --git a/crates/server/src/services/configure_account.rs b/crates/server/src/services/configure_account.rs index dff87cbf..9282c694 100644 --- a/crates/server/src/services/configure_account.rs +++ b/crates/server/src/services/configure_account.rs @@ -318,7 +318,7 @@ pub async fn configure_account( && !default_copies.is_empty() && let Some(modules) = state.modules.as_deref() { - modules + let copied = modules .store() .seed_assignment( ¶ms.account_id.to_ascii_lowercase(), @@ -331,6 +331,12 @@ pub async fn configure_account( ) .await .map_err(GuardianError::StorageError)?; + if !copied { + tracing::info!( + account_id = %params.account_id, + "Default modules not copied: the account already has module assignments or module history" + ); + } } // The replay-state row has an FK to account metadata, which the claim @@ -652,30 +658,40 @@ async fn approve_registration( None }; let views = plan.views(); - plan.run(|| { - let stored_state = stored_state.as_ref().map(|r| r.as_ref()).transpose()?; - request::registration_request( - state.network_client.as_ref(), - &views, - RegistrationInput { - account_id: ¶ms.account_id, - submitter: signer_commitment, - submitter_session: false, - auth: ¶ms.auth, - network_config: ¶ms.network_config, - stored_state: stored_state.map(|stored| StateRef { - commitment: &stored.commitment, - json: &stored.state_json, - }), - initial_state: StateRef { - commitment: &head.commitment, - json: ¶ms.initial_state, + let network_id = plan.network_id(); + let evaluation = plan + .run(|| { + let stored_state = stored_state.as_ref().map(|r| r.as_ref()).transpose()?; + request::registration_request( + state.network_client.as_ref(), + &views, + RegistrationInput { + network_id, + account_id: ¶ms.account_id, + submitter: signer_commitment, + submitter_session: false, + auth: ¶ms.auth, + network_config: ¶ms.network_config, + stored_state: stored_state.map(|stored| StateRef { + commitment: &stored.commitment, + json: &stored.state_json, + }), + initial_state: StateRef { + commitment: &head.commitment, + json: ¶ms.initial_state, + }, + accounting_time: state.clock.now(), }, - accounting_time: state.clock.now(), - }, - ) - }) - .await?; + ) + }) + .await?; + evaluation.audit_failed_open( + state.auditor.as_ref(), + HookName::BeforeAccountRegistered, + ¶ms.account_id, + signer_commitment, + serde_json::Map::new(), + ); } Ok(default_copies) } @@ -3544,6 +3560,7 @@ mod tests { metadata: MockMetadataStore, module: Arc, modules: Arc, + audited: Vec, } async fn configure_with_module( @@ -3603,6 +3620,8 @@ mod tests { create_test_app_state(network_client, storage.clone(), metadata.clone()).await; let modules = pipeline(instances); state.modules = Some(modules.clone()); + let auditor = crate::testing::helpers::CapturingAuditor::new(); + state.auditor = Arc::new(auditor.clone()); let result = configure_account( &state, @@ -3623,9 +3642,43 @@ mod tests { metadata, module, modules, + audited: auditor.snapshot(), } } + #[tokio::test] + async fn a_failure_let_through_at_registration_is_audited() { + use crate::modules::catalog::OnError; + use crate::modules::testing::{Behaviour, StubModule, instance}; + + let module = StubModule::new(Behaviour::Fail); + let failing = instance( + "signers", + &[HookName::BeforeAccountRegistered], + OnError::Allow, + module.clone(), + ); + let run = configure_with_modules(|_| None, vec![failing], module).await; + assert!(run.result.is_ok(), "{:?}", run.result); + let skipped: Vec<_> = run + .audited + .iter() + .filter(|event| event.action_kind == crate::audit::kinds::MODULES_FAILED_OPEN) + .collect(); + assert_eq!(skipped.len(), 1, "{:?}", run.audited); + assert_eq!(skipped[0].payload["hook"], "before_account_registered"); + assert_eq!(skipped[0].payload["failed_open"][0]["module_id"], "signers"); + + let clean = configure_with_module(|_| None, StubModule::allowing()).await; + assert!(clean.result.is_ok()); + assert!( + clean + .audited + .iter() + .all(|event| event.action_kind != crate::audit::kinds::MODULES_FAILED_OPEN) + ); + } + fn existing_account( paused: bool, released: bool, diff --git a/crates/server/src/services/push_delta_proposal.rs b/crates/server/src/services/push_delta_proposal.rs index 6ed7b8a6..9dc4328c 100644 --- a/crates/server/src/services/push_delta_proposal.rs +++ b/crates/server/src/services/push_delta_proposal.rs @@ -398,6 +398,7 @@ async fn propose(state: &AppState, params: PushDeltaProposalParams, mode: Mode) } tracing::Span::current().record("signer_count", cosigner_sigs.len()); + let mut evaluations = Vec::new(); if let Some((after, module_views)) = applied { if let Err(error) = state.network_client.load_fee_faucet().await { tracing::warn!(%error, "Fee faucet unknown; no output note is treated as the fee note"); @@ -410,6 +411,7 @@ async fn propose(state: &AppState, params: PushDeltaProposalParams, mode: Mode) .unwrap_or(serde_json::Value::Null), }; let views = plans[0].views(); + let network_id = plans[0].network_id(); views.seed(&tail.commitment, module_views.before); views.seed(&after.commitment, module_views.after); for plan in plans { @@ -418,6 +420,7 @@ async fn propose(state: &AppState, params: PushDeltaProposalParams, mode: Mode) state.network_client.as_ref(), &views, TransactionInput { + network_id, account_id: &account_id, submitter: &proposer_id, submitter_session: credentials_session, @@ -437,7 +440,8 @@ async fn propose(state: &AppState, params: PushDeltaProposalParams, mode: Mode) }, ) }) - .await?; + .await + .map(|evaluation| evaluations.push(evaluation))?; } } if mode == Mode::DryRun { @@ -489,6 +493,19 @@ async fn propose(state: &AppState, params: PushDeltaProposalParams, mode: Mode) ) .increment(1); tracing::info!("Delta proposal created"); + if let DeltaStatus::Pending { proposer_id, .. } = &delta_proposal.status { + for evaluation in &evaluations { + evaluation.audit_failed_open( + state.auditor.as_ref(), + HookName::BeforeProposalCreated, + &account_id, + proposer_id, + [("proposal_id".to_string(), commitment.clone().into())] + .into_iter() + .collect(), + ); + } + } delta_proposal } ProposalWrite::AlreadyStored => { @@ -2597,6 +2614,63 @@ mod tests { assert!(storage.get_submit_delta_proposal_calls().is_empty()); } + #[tokio::test] + async fn a_failure_let_through_at_creation_is_audited_and_a_clean_creation_is_not() { + use crate::modules::catalog::OnError; + use crate::modules::testing::{Behaviour, StubModule}; + use crate::testing::helpers::CapturingAuditor; + + let auditor = CapturingAuditor::new(); + let (mut state, storage, params, proposer) = module_setup( + StubModule::new(Behaviour::Fail), + HookName::BeforeProposalCreated, + |instance| instance.config.on_error = OnError::Allow, + ); + state.auditor = Arc::new(auditor.clone()); + let created = push_delta_proposal(&state, params) + .await + .expect("a fail-open module does not stop the proposal"); + assert_eq!(storage.get_submit_delta_proposal_calls().len(), 1); + let events = auditor.snapshot(); + assert_eq!(events.len(), 1, "{events:?}"); + let event = &events[0]; + assert_eq!(event.action_kind, crate::audit::kinds::MODULES_FAILED_OPEN); + assert_eq!(event.operator_identity, "system"); + assert_eq!(event.payload["hook"], "before_proposal_created"); + assert_eq!(event.payload["submitter"], proposer); + assert_eq!(event.payload["proposal_id"], created.commitment); + assert_eq!(event.payload["failed_open"][0]["module_id"], "caps"); + assert_eq!(event.payload["failed_open"][0]["failure"], "error"); + + let clean = CapturingAuditor::new(); + let (mut state, _, params, _) = module_setup( + StubModule::allowing(), + HookName::BeforeProposalCreated, + |_| {}, + ); + state.auditor = Arc::new(clean.clone()); + push_delta_proposal(&state, params).await.unwrap(); + assert!(clean.snapshot().is_empty()); + } + + #[tokio::test] + async fn a_check_audits_nothing() { + use crate::modules::catalog::OnError; + use crate::modules::testing::{Behaviour, StubModule}; + use crate::testing::helpers::CapturingAuditor; + + let auditor = CapturingAuditor::new(); + let (mut state, storage, params, _) = module_setup( + StubModule::new(Behaviour::Fail), + HookName::BeforeProposalCreated, + |instance| instance.config.on_error = OnError::Allow, + ); + state.auditor = Arc::new(auditor.clone()); + check_proposal(&state, params).await.unwrap(); + assert!(storage.get_submit_delta_proposal_calls().is_empty()); + assert!(auditor.snapshot().is_empty()); + } + #[tokio::test] async fn creation_passes_the_proposer_and_untrusted_metadata() { let module = crate::modules::testing::StubModule::allowing(); From 628bab086c15180fad3777990f745cee36371f9c Mon Sep 17 00:00:00 2001 From: Zeljko Date: Tue, 10 Nov 2026 07:34:33 +0100 Subject: [PATCH 074/105] feat(dashboard): the module approval of a delta on its detail (#251) GET /dashboard/accounts/{account_id}/deltas/{nonce} returns the stored approval record as modules: the catalog hash and params version the delta was judged under, when and for whom, and the failures an on_error = allow instance let through. Client routes still never return it. --- crates/server/src/delta_summary/mod.rs | 6 ++-- .../dashboard_account_delta_detail.rs | 35 +++++++++++++++---- 2 files changed, 33 insertions(+), 8 deletions(-) diff --git a/crates/server/src/delta_summary/mod.rs b/crates/server/src/delta_summary/mod.rs index ec6ddca5..2cc1b6e6 100644 --- a/crates/server/src/delta_summary/mod.rs +++ b/crates/server/src/delta_summary/mod.rs @@ -57,7 +57,8 @@ pub struct DeltaMetadata { pub proposal: Option, /// The policy module configuration that approved this delta, for operators: absent when no - /// module ran, and never included in client API responses. + /// module ran, never included in client API responses, and served to operators on the + /// dashboard delta detail. #[serde(default, skip_serializing_if = "Option::is_none")] pub modules: Option, } @@ -85,7 +86,8 @@ pub struct ModuleApproval { pub struct FailedOpen { pub module_id: String, pub layer: String, - /// `timeout`, `error`, `invalid_decision` or `request_unavailable`; the detail is logged. + /// `timeout`, `error`, `invalid_decision`, `request_unavailable` or `circuit_open`; the + /// detail is logged. pub failure: String, } diff --git a/crates/server/src/services/dashboard_account_delta_detail.rs b/crates/server/src/services/dashboard_account_delta_detail.rs index d4c0d05b..a9d10b07 100644 --- a/crates/server/src/services/dashboard_account_delta_detail.rs +++ b/crates/server/src/services/dashboard_account_delta_detail.rs @@ -10,8 +10,8 @@ use serde::Serialize; use crate::delta_object::{DeltaObject, DeltaStatus}; use crate::delta_summary::{ - DashboardDeltaCategory, DecodeWarning, DecodedNote, ProposalMetadata, StorageChange, - VaultChange, decode_full as project_detail_sections, decode_transaction_summary, + DashboardDeltaCategory, DecodeWarning, DecodedNote, ModuleApproval, ProposalMetadata, + StorageChange, VaultChange, decode_full as project_detail_sections, decode_transaction_summary, }; use crate::error::{GuardianError, Result}; use crate::services::dashboard_account_deltas::{DashboardDeltaStatus, decode_delta_status}; @@ -58,6 +58,11 @@ pub struct DashboardDeltaDetail { pub category: Option, #[serde(skip_serializing_if = "Option::is_none")] pub proposal: Option, + /// The policy module configuration that approved this delta: the catalog and params version + /// it was judged under and the module failures an `on_error = allow` instance let through. + /// Absent when no module ran. + #[serde(skip_serializing_if = "Option::is_none")] + pub modules: Option, pub input_notes: Vec, pub output_notes: Vec, @@ -188,11 +193,11 @@ fn project_delta_to_detail( ), }; - let (category, proposal) = delta + let (category, proposal, modules) = delta .metadata .as_ref() - .map(|m| (Some(m.category), m.proposal.clone())) - .unwrap_or((None, None)); + .map(|m| (Some(m.category), m.proposal.clone(), m.modules.clone())) + .unwrap_or((None, None, None)); let raw_transaction_summary = if include.raw { let extracted = extract_raw_tx_summary_base64(&delta.delta_payload); @@ -222,6 +227,7 @@ fn project_delta_to_detail( base_matches_stored_state: None, category, proposal, + modules, input_notes, output_notes, vault_changes, @@ -495,19 +501,36 @@ mod tests { async fn canonical_delta_projects_with_metadata_header_and_decoded_sections() { let payload = create_test_delta_payload(TEST_ACCOUNT_ID); let mut delta = canonical_delta_with_payload(7, payload); + let approval = ModuleApproval { + catalog_hash: "0xcatalog".into(), + params_version: 4, + failed_open: vec![crate::delta_summary::FailedOpen { + module_id: "screening".into(), + layer: "global".into(), + failure: "timeout".into(), + }], + signed_at: "2026-11-09T10:00:00+00:00".into(), + submitter: "0xsigner".into(), + proposer: String::new(), + }; delta.metadata = Some(crate::delta_summary::DeltaMetadata { category: crate::delta_summary::DashboardDeltaCategory::AccountStorageChange, assets: Vec::new(), counterparty: None, note_counts: crate::delta_summary::NoteCounts::default(), proposal: None, - modules: None, + modules: Some(approval.clone()), }); let state = build_state(Ok(Some(falcon_metadata())), Ok(delta.clone())).await; let detail = get_account_delta_detail(&state, TEST_ACCOUNT_ID, 7, DetailIncludeFlags::default()) .await .expect("happy path"); + assert_eq!( + detail.modules, + Some(approval), + "operators read which module configuration approved the delta" + ); assert_eq!(detail.account_id, TEST_ACCOUNT_ID); assert_eq!(detail.nonce, 7); assert_eq!(detail.status, DashboardDeltaStatus::Canonical); From aaf59e6388f457540987f41df369ea6f7b728285 Mon Sep 17 00:00:00 2001 From: Zeljko Date: Tue, 10 Nov 2026 07:34:33 +0100 Subject: [PATCH 075/105] feat(operator-client): module approval on the delta detail and the module permissions (#251) - The delta detail parses modules. - policies:write_global and modules:disable are known permissions, so a session holding them no longer fails to parse; a test compares the list with the server's permissions.rs. --- packages/guardian-operator-client/README.md | 5 +++ .../guardian-operator-client/src/http.test.ts | 40 +++++++++++++++++++ packages/guardian-operator-client/src/http.ts | 30 ++++++++++++++ .../guardian-operator-client/src/index.ts | 4 ++ .../src/permissions.test.ts | 30 ++++++++++++++ .../src/permissions.ts | 8 ++++ .../guardian-operator-client/src/types.ts | 28 +++++++++++++ 7 files changed, 145 insertions(+) diff --git a/packages/guardian-operator-client/README.md b/packages/guardian-operator-client/README.md index 28528683..40fe409b 100644 --- a/packages/guardian-operator-client/README.md +++ b/packages/guardian-operator-client/README.md @@ -476,6 +476,11 @@ const canPause = permissions.includes(ACCOUNTS_PAUSE); const canRead = permissions.includes(DASHBOARD_READ); ``` +The constants cover every permission the server defines: `DASHBOARD_READ`, +`ACCOUNTS_PAUSE`, `POLICIES_WRITE`, `POLICIES_WRITE_GLOBAL` (policy module +global params), `MODULES_DISABLE` (disabling a module instance the catalog +marks `operator_can_disable`) and `STATS_REFRESH`. + The session endpoint re-reads permissions from the allowlist on every call, so allowlist edits take effect without re-login. The server is still the source of truth on every mutating endpoint — the client diff --git a/packages/guardian-operator-client/src/http.test.ts b/packages/guardian-operator-client/src/http.test.ts index 0e926433..3520644a 100644 --- a/packages/guardian-operator-client/src/http.test.ts +++ b/packages/guardian-operator-client/src/http.test.ts @@ -1251,6 +1251,46 @@ describe('GuardianOperatorHttpClient — per-account history', () => { }); } + it('parses the policy module approval of a delta, and leaves it unset when no module ran', async () => { + const base = { + account_id: '0xacc', + nonce: 7, + status: 'canonical', + status_timestamp: '2026-11-09T10:00:00Z', + prev_commitment: '0xaaaa', + new_commitment: '0xbbbb', + input_notes: [], + output_notes: [], + vault_changes: [], + storage_changes: [], + }; + mockFetch + .mockResolvedValueOnce( + okJson({ + ...base, + modules: { + catalog_hash: '0xcatalog', + params_version: 4, + failed_open: [{ module_id: 'screening', layer: 'global', failure: 'circuit_open' }], + signed_at: '2026-11-09T10:00:00+00:00', + submitter: '0xsigner', + }, + }), + ) + .mockResolvedValueOnce(okJson(base)); + const client = new GuardianOperatorHttpClient('https://guardian.example'); + const approved = await client.getAccountDeltaDetail('0xacc', 7); + expect(approved.modules).toEqual({ + catalogHash: '0xcatalog', + paramsVersion: 4, + failedOpen: [{ moduleId: 'screening', layer: 'global', failure: 'circuit_open' }], + signedAt: '2026-11-09T10:00:00+00:00', + submitter: '0xsigner', + proposer: null, + }); + expect((await client.getAccountDeltaDetail('0xacc', 7)).modules).toBeUndefined(); + }); + it('parses the per-signer schemes of a mixed update-signers proposal (issue #563)', async () => { mockFetch.mockResolvedValueOnce( signerChangeDetail({ diff --git a/packages/guardian-operator-client/src/http.ts b/packages/guardian-operator-client/src/http.ts index 6a06d1d3..82c0e712 100644 --- a/packages/guardian-operator-client/src/http.ts +++ b/packages/guardian-operator-client/src/http.ts @@ -12,6 +12,7 @@ import type { DashboardDeltaDecodeWarning, DashboardDeltaDecodedAsset, DashboardDeltaDecodedNote, + DashboardDeltaModuleApproval, DashboardDeltaDetail, DashboardDeltaEntry, DashboardDeltaNoteCounts, @@ -948,6 +949,8 @@ const KNOWN_OPERATOR_PERMISSIONS: ReadonlySet = new Set 0) { detail.decodeWarnings = (record.decode_warnings as unknown[]).map((w, i) => parseDecodeWarning(w, `${ctx}.decode_warnings[${i}]`), @@ -2303,6 +2309,30 @@ function parseDeltaDetail(value: unknown): DashboardDeltaDetail { return detail; } +function parseModuleApproval(value: unknown, context: string): DashboardDeltaModuleApproval { + const record = asRecord(value, context); + const failedOpen = record.failed_open === undefined ? [] : record.failed_open; + if (!Array.isArray(failedOpen)) { + throw new GuardianOperatorContractError(context, 'failed_open must be an array when present'); + } + return { + catalogHash: requireString(record, 'catalog_hash', context), + paramsVersion: requireInteger(record, 'params_version', context), + failedOpen: failedOpen.map((entry, i) => { + const entryContext = `${context}.failed_open[${i}]`; + const failure = asRecord(entry, entryContext); + return { + moduleId: requireString(failure, 'module_id', entryContext), + layer: requireString(failure, 'layer', entryContext), + failure: requireString(failure, 'failure', entryContext), + }; + }), + signedAt: requireString(record, 'signed_at', context), + submitter: requireString(record, 'submitter', context), + proposer: optionalString(record, 'proposer', context), + }; +} + function parseDecodedNoteArray( value: unknown, context: string, diff --git a/packages/guardian-operator-client/src/index.ts b/packages/guardian-operator-client/src/index.ts index 4df4bc4e..bc6f55d3 100644 --- a/packages/guardian-operator-client/src/index.ts +++ b/packages/guardian-operator-client/src/index.ts @@ -11,7 +11,9 @@ export type { ListAccountsOptions, PaginationOptions, ParsedErrorBody } from './ export { ACCOUNTS_PAUSE, DASHBOARD_READ, + MODULES_DISABLE, POLICIES_WRITE, + POLICIES_WRITE_GLOBAL, STATS_REFRESH, } from './permissions.js'; @@ -51,6 +53,8 @@ export type { DashboardDeltaDecodedAsset, DashboardDeltaDecodedNote, DashboardDeltaDetail, + DashboardDeltaModuleApproval, + DashboardDeltaModuleFailedOpen, DashboardDeltaEntry, DashboardDeltaNoteCounts, DashboardDeltaNoteTag, diff --git a/packages/guardian-operator-client/src/permissions.test.ts b/packages/guardian-operator-client/src/permissions.test.ts index cb9fde1a..57f40840 100644 --- a/packages/guardian-operator-client/src/permissions.test.ts +++ b/packages/guardian-operator-client/src/permissions.test.ts @@ -1,12 +1,27 @@ +import { readFileSync } from 'node:fs'; +import { dirname, resolve } from 'node:path'; +import { fileURLToPath } from 'node:url'; + import { describe, expect, it } from 'vitest'; import { ACCOUNTS_PAUSE, DASHBOARD_READ, + MODULES_DISABLE, POLICIES_WRITE, + POLICIES_WRITE_GLOBAL, STATS_REFRESH, } from './permissions.js'; +const CLIENT_PERMISSIONS = [ + DASHBOARD_READ, + ACCOUNTS_PAUSE, + POLICIES_WRITE, + POLICIES_WRITE_GLOBAL, + MODULES_DISABLE, + STATS_REFRESH, +]; + describe('operator permission wire strings', () => { it('exposes the v1 permission consts as the expected wire strings', () => { // Renaming any of these is a breaking contract change against the @@ -15,6 +30,21 @@ describe('operator permission wire strings', () => { expect(DASHBOARD_READ).toBe('dashboard:read'); expect(ACCOUNTS_PAUSE).toBe('accounts:pause'); expect(POLICIES_WRITE).toBe('policies:write'); + expect(POLICIES_WRITE_GLOBAL).toBe('policies:write_global'); + expect(MODULES_DISABLE).toBe('modules:disable'); expect(STATS_REFRESH).toBe('stats:refresh'); }); + + it('covers every permission the server defines', () => { + const here = dirname(fileURLToPath(import.meta.url)); + const permissionsRs = readFileSync( + resolve(here, '../../../crates/server/src/dashboard/permissions.rs'), + 'utf8', + ); + const serverPermissions = [ + ...permissionsRs.matchAll(/^pub const [A-Z_]+: &str = "([^"]+)";$/gm), + ].map((match) => match[1]); + expect(serverPermissions.length).toBeGreaterThan(0); + expect([...serverPermissions].sort()).toEqual([...CLIENT_PERMISSIONS].sort()); + }); }); diff --git a/packages/guardian-operator-client/src/permissions.ts b/packages/guardian-operator-client/src/permissions.ts index 82669528..22bd091f 100644 --- a/packages/guardian-operator-client/src/permissions.ts +++ b/packages/guardian-operator-client/src/permissions.ts @@ -11,6 +11,12 @@ export const DASHBOARD_READ = 'dashboard:read' as const; export const ACCOUNTS_PAUSE = 'accounts:pause' as const; export const POLICIES_WRITE = 'policies:write' as const; +/** May change the global params of a policy module, which apply to every + * account (`PUT /dashboard/modules/{module_id}/params`). */ +export const POLICIES_WRITE_GLOBAL = 'policies:write_global' as const; +/** May disable a policy module instance the catalog marks + * `operator_can_disable`, and nothing else. */ +export const MODULES_DISABLE = 'modules:disable' as const; /** May request an out-of-cycle refresh of the `/dashboard/stats` * aggregate (`POST /dashboard/stats/refresh`, issue #371). */ export const STATS_REFRESH = 'stats:refresh' as const; @@ -20,4 +26,6 @@ export type OperatorPermission = | typeof DASHBOARD_READ | typeof ACCOUNTS_PAUSE | typeof POLICIES_WRITE + | typeof POLICIES_WRITE_GLOBAL + | typeof MODULES_DISABLE | typeof STATS_REFRESH; diff --git a/packages/guardian-operator-client/src/types.ts b/packages/guardian-operator-client/src/types.ts index 522e437e..7a1e1c75 100644 --- a/packages/guardian-operator-client/src/types.ts +++ b/packages/guardian-operator-client/src/types.ts @@ -446,6 +446,9 @@ export interface DashboardDeltaDetail { category?: DashboardDeltaCategory; /** Operator-stated proposal intent for multisig commits. */ proposal?: DashboardDeltaProposalMetadata; + /** The policy module configuration that approved this delta. Absent when + * no module ran. */ + modules?: DashboardDeltaModuleApproval; inputNotes: DashboardDeltaDecodedNote[]; outputNotes: DashboardDeltaDecodedNote[]; vaultChanges: DashboardDeltaVaultChange[]; @@ -457,6 +460,31 @@ export interface DashboardDeltaDetail { rawTransactionSummary?: string; } +/** A module failure an `on_error = "allow"` instance let through. */ +export interface DashboardDeltaModuleFailedOpen { + moduleId: string; + /** `global` or `account`. */ + layer: string; + /** `timeout`, `error`, `invalid_decision`, `request_unavailable` or + * `circuit_open`. */ + failure: string; +} + +/** The policy modules' approval of a signed delta: the configuration they + * ran with, when and for whom. */ +export interface DashboardDeltaModuleApproval { + /** SHA-256 of the catalog file the approving replica loaded. */ + catalogHash: string; + paramsVersion: number; + failedOpen: DashboardDeltaModuleFailedOpen[]; + /** RFC 3339 time the Guardian signed. */ + signedAt: string; + /** The cosigner the acknowledgment was evaluated for. */ + submitter: string; + /** The matching proposal's creator; null when no stored proposal matched. */ + proposer: string | null; +} + export interface DashboardDeltaEntry { /** See note on `DashboardDeltaDetail.nonce` for the JS-number precision limit. */ nonce: number; From d7b9f761fd5ff3d1f9de6eb63d5f6dbe0b3ce7e0 Mon Sep 17 00:00:00 2001 From: Zeljko Date: Tue, 10 Nov 2026 07:34:33 +0100 Subject: [PATCH 076/105] fix(guardian-client): refuse a tagged payload where the request payload is signed (#251) fetchAuthenticated wraps its argument as the signed payload, so an already tagged payload passed to it would be signed as an object. It now throws instead. --- packages/guardian-client/src/http.ts | 3 +++ 1 file changed, 3 insertions(+) diff --git a/packages/guardian-client/src/http.ts b/packages/guardian-client/src/http.ts index b1c112d2..e94c0345 100644 --- a/packages/guardian-client/src/http.ts +++ b/packages/guardian-client/src/http.ts @@ -994,6 +994,9 @@ export class GuardianHttpClient { requestPayload: unknown, mode: AuthMode = 'wallet' ): Promise { + if (requestPayload instanceof RequestAuthPayload) { + throw new Error('fetchAuthenticated signs the request payload itself; a tagged payload goes through fetchSigned'); + } return this.fetchSigned(path, init, accountId, RequestAuthPayload.fromRequest(requestPayload), mode); } From 41132b701a30de974f6e6415f1486622b6b42f87 Mon Sep 17 00:00:00 2001 From: Zeljko Date: Tue, 10 Nov 2026 07:34:33 +0100 Subject: [PATCH 077/105] fix(multisig-client): the proposal check builds like creation and sends no signature (#251) - check_transaction applies the client's execution mode and key scheme check, as propose_transaction does. - A check carries no proposer signature: nothing it checks is stored. - A refusal of a check keeps its code and retry hint, like a refused creation. - propose_with_fallback falls back to an offline proposal on a module refusal, for transaction types that can execute without the Guardian. --- .../src/client/proposals.rs | 6 +++- crates/miden-multisig-client/src/payload.rs | 33 +++++++++++++------ .../src/transaction/builder.rs | 26 ++++++++++----- 3 files changed, 46 insertions(+), 19 deletions(-) diff --git a/crates/miden-multisig-client/src/client/proposals.rs b/crates/miden-multisig-client/src/client/proposals.rs index 289e14ca..2bbc9d3c 100644 --- a/crates/miden-multisig-client/src/client/proposals.rs +++ b/crates/miden-multisig-client/src/client/proposals.rs @@ -823,10 +823,12 @@ impl MultisigClient { ) -> Result { self.sync().await?; let account = self.require_account()?.clone(); + self.ensure_key_scheme_matches(&account)?; let mut guardian_client = self.create_authenticated_guardian_client().await?; let node_rpc = self.node_rpc_client(); ProposalBuilder::new(transaction_type) .with_options(options) + .with_execution_mode(self.execution_mode) .check( &mut self.miden_client, &node_rpc, @@ -913,7 +915,9 @@ impl MultisigClient { Err( error @ (MultisigError::GuardianConnection(_) | MultisigError::GuardianServer(_) - | MultisigError::GuardianProposalRefused { .. }), + | MultisigError::GuardianProposalRefused { .. } + | MultisigError::ModuleDenied { .. } + | MultisigError::ModuleUnavailable { .. }), ) => { if transaction_type.supports_offline_execution() { let exported = self.create_proposal_offline(transaction_type).await?; diff --git a/crates/miden-multisig-client/src/payload.rs b/crates/miden-multisig-client/src/payload.rs index ee5f286a..8d39f5d6 100644 --- a/crates/miden-multisig-client/src/payload.rs +++ b/crates/miden-multisig-client/src/payload.rs @@ -147,19 +147,17 @@ impl ProposalPayload { /// Adds the proposer's signature. pub fn with_signature( - mut self, + self, key_manager: &dyn KeyManager, message: miden_protocol::Word, ) -> Self { - let signature_hex = key_manager.sign_word_hex(message); - self.signatures.push(DeltaSignature { - signer_id: key_manager.commitment_hex(), - signature: ProposalSignature::from_scheme( - key_manager.scheme(), - signature_hex, - proposal_public_key_hex(key_manager), - ), - }); + self.with_proposer_signature(Some(proposer_signature(key_manager, message))) + } + + /// Adds the proposer's signature when there is one: a check of a proposal carries none, + /// since nothing it checks is stored. + pub fn with_proposer_signature(mut self, signature: Option) -> Self { + self.signatures.extend(signature); self } @@ -332,6 +330,21 @@ impl ProposalPayload { } } +/// The proposer's signature over `message`, the commitment of the proposal's summary. +pub(crate) fn proposer_signature( + key_manager: &dyn KeyManager, + message: miden_protocol::Word, +) -> DeltaSignature { + DeltaSignature { + signer_id: key_manager.commitment_hex(), + signature: ProposalSignature::from_scheme( + key_manager.scheme(), + key_manager.sign_word_hex(message), + proposal_public_key_hex(key_manager), + ), + } +} + #[cfg(test)] mod tests { use miden_protocol::account::delta::{AccountDelta, AccountVaultDelta}; diff --git a/crates/miden-multisig-client/src/transaction/builder.rs b/crates/miden-multisig-client/src/transaction/builder.rs index 746ef00c..88c12336 100644 --- a/crates/miden-multisig-client/src/transaction/builder.rs +++ b/crates/miden-multisig-client/src/transaction/builder.rs @@ -210,6 +210,16 @@ impl ProposalBuilder { }) } + /// The proposer's approval of a proposal that will be created. A check sends none: nothing + /// it checks is stored, so it must not hand GUARDIAN a signature that authorizes it. + fn proposer_signature( + &self, + key_manager: &dyn KeyManager, + tx_commitment: Word, + ) -> Option { + (!self.dry_run).then(|| crate::payload::proposer_signature(key_manager, tx_commitment)) + } + /// Creates the proposal on GUARDIAN, or only checks it in a dry run. Returns the /// commitment GUARDIAN reports for a created proposal, none for a check. async fn send( @@ -223,7 +233,7 @@ impl ProposalBuilder { let response = guardian_client .check_delta_proposal(account_id, nonce, payload) .await - .map_err(|e| MultisigError::guardian("failed to check proposal", e))?; + .map_err(MultisigError::proposal_push)?; if let Ok(mut checked) = self.checked.lock() { *checked = Some(ProposalCheck { complete: response.complete, @@ -456,7 +466,7 @@ impl ProposalBuilder { // Build the payload using ProposalPayload let payload = ProposalPayload::new(&tx_summary) .with_transaction_request(attachment) - .with_signature(key_manager, tx_commitment) + .with_proposer_signature(self.proposer_signature(key_manager, tx_commitment)) .with_add_signer_metadata( new_threshold, signer_commitments_hex.clone(), @@ -567,7 +577,7 @@ impl ProposalBuilder { let payload = ProposalPayload::new(&tx_summary) .with_transaction_request(attachment) - .with_signature(key_manager, tx_commitment) + .with_proposer_signature(self.proposer_signature(key_manager, tx_commitment)) .with_threshold_metadata( new_threshold, signer_commitments_hex.clone(), @@ -683,7 +693,7 @@ impl ProposalBuilder { // Build the payload using ProposalPayload let payload = ProposalPayload::new(&tx_summary) .with_transaction_request(attachment) - .with_signature(key_manager, tx_commitment) + .with_proposer_signature(self.proposer_signature(key_manager, tx_commitment)) .with_remove_signer_metadata( new_threshold, signer_commitments_hex.clone(), @@ -780,7 +790,7 @@ impl ProposalBuilder { // Build the payload using ProposalPayload let payload = ProposalPayload::new(&tx_summary) .with_transaction_request(attachment) - .with_signature(key_manager, tx_commitment) + .with_proposer_signature(self.proposer_signature(key_manager, tx_commitment)) .with_payment_metadata( recipient.to_string(), faucet_id.to_string(), @@ -902,7 +912,7 @@ impl ProposalBuilder { let payload = ProposalPayload::new(&tx_summary) .with_transaction_request(attachment) - .with_signature(key_manager, tx_commitment) + .with_proposer_signature(self.proposer_signature(key_manager, tx_commitment)) .with_note_consumption_metadata_v2(note_ids_hex, notes_base64, word_to_hex(&salt)) .with_required_signatures(required_signatures); @@ -1007,7 +1017,7 @@ impl ProposalBuilder { // Build the payload using ProposalPayload let payload = ProposalPayload::new(&tx_summary) .with_transaction_request(attachment) - .with_signature(key_manager, tx_commitment) + .with_proposer_signature(self.proposer_signature(key_manager, tx_commitment)) .with_guardian_update_metadata( word_to_hex(&new_guardian_pubkey), new_guardian_endpoint.clone(), @@ -1088,7 +1098,7 @@ impl ProposalBuilder { let payload = ProposalPayload::new(&tx_summary) .with_transaction_request(attachment) - .with_signature(key_manager, tx_commitment) + .with_proposer_signature(self.proposer_signature(key_manager, tx_commitment)) .with_procedure_threshold_metadata(procedure, new_threshold as u64, word_to_hex(&salt)) .with_required_signatures(required_signatures); From 47d05f2ba590ec89c37e7f14dd2558cfae69e3ef Mon Sep 17 00:00:00 2001 From: Zeljko Date: Tue, 10 Nov 2026 07:34:33 +0100 Subject: [PATCH 078/105] docs(openapi): module approval on the delta detail and module route errors (#251) Regenerated. --- docs/openapi-client.json | 4 +- docs/openapi-dashboard.json | 142 ++++++++++++++++++++++++++++++++---- docs/openapi.json | 87 +++++++++++++++++----- 3 files changed, 197 insertions(+), 36 deletions(-) diff --git a/docs/openapi-client.json b/docs/openapi-client.json index 85601a20..b68cfb59 100644 --- a/docs/openapi-client.json +++ b/docs/openapi-client.json @@ -2897,7 +2897,7 @@ }, { "$ref": "#/components/schemas/ModuleApproval", - "description": "The policy module configuration that approved this delta, for operators: absent when no\nmodule ran, and never included in client API responses." + "description": "The policy module configuration that approved this delta, for operators: absent when no\nmodule ran, never included in client API responses, and served to operators on the\ndashboard delta detail." } ] }, @@ -3327,7 +3327,7 @@ "properties": { "failure": { "type": "string", - "description": "`timeout`, `error`, `invalid_decision` or `request_unavailable`; the detail is logged." + "description": "`timeout`, `error`, `invalid_decision`, `request_unavailable` or `circuit_open`; the\ndetail is logged." }, "layer": { "type": "string" diff --git a/docs/openapi-dashboard.json b/docs/openapi-dashboard.json index 267eec9e..4ecc51ee 100644 --- a/docs/openapi-dashboard.json +++ b/docs/openapi-dashboard.json @@ -654,6 +654,16 @@ } } }, + "400": { + "description": "No policy modules are configured", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, "401": { "description": "No operator session", "content": { @@ -675,7 +685,7 @@ } }, "404": { - "description": "Account or module not found, or no modules configured", + "description": "Account or module not found", "content": { "application/json": { "schema": { @@ -749,7 +759,7 @@ } }, "400": { - "description": "Invalid params, reason or assignment", + "description": "Invalid params, reason or assignment, or no policy modules are configured", "content": { "application/json": { "schema": { @@ -779,7 +789,7 @@ } }, "404": { - "description": "Account or module not found, or no modules configured", + "description": "Account or module not found", "content": { "application/json": { "schema": { @@ -864,7 +874,7 @@ } }, "400": { - "description": "Invalid params, reason or assignment", + "description": "Invalid params, reason or assignment, or no policy modules are configured", "content": { "application/json": { "schema": { @@ -894,7 +904,7 @@ } }, "404": { - "description": "Account or module not found, or no modules configured", + "description": "Account or module not found", "content": { "application/json": { "schema": { @@ -977,7 +987,7 @@ } }, "400": { - "description": "Invalid params, reason or assignment", + "description": "Invalid params, reason or assignment, or no policy modules are configured", "content": { "application/json": { "schema": { @@ -1007,7 +1017,7 @@ } }, "404": { - "description": "Account or module not found, or no modules configured", + "description": "Account or module not found", "content": { "application/json": { "schema": { @@ -1654,6 +1664,16 @@ } } }, + "400": { + "description": "No policy modules are configured", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, "401": { "description": "No operator session", "content": { @@ -1675,7 +1695,7 @@ } }, "404": { - "description": "Account or module not found, or no modules configured", + "description": "Account or module not found", "content": { "application/json": { "schema": { @@ -1751,7 +1771,7 @@ } }, "400": { - "description": "Invalid params, reason or assignment", + "description": "Invalid params, reason or assignment, or no policy modules are configured", "content": { "application/json": { "schema": { @@ -1781,7 +1801,17 @@ } }, "404": { - "description": "Account or module not found, or no modules configured", + "description": "Account or module not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "409": { + "description": "The catalog does not mark the instance operator_can_disable", "content": { "application/json": { "schema": { @@ -1857,7 +1887,7 @@ } }, "400": { - "description": "Invalid params, reason or assignment", + "description": "Invalid params, reason or assignment, or no policy modules are configured", "content": { "application/json": { "schema": { @@ -1887,7 +1917,7 @@ } }, "404": { - "description": "Account or module not found, or no modules configured", + "description": "Account or module not found", "content": { "application/json": { "schema": { @@ -1915,6 +1945,16 @@ } } } + }, + "503": { + "description": "The module failed its startup checks; nothing changed", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } } }, "security": [ @@ -1963,7 +2003,7 @@ } }, "400": { - "description": "Invalid params, reason or assignment", + "description": "Invalid params, reason or assignment, or no policy modules are configured", "content": { "application/json": { "schema": { @@ -1993,7 +2033,7 @@ } }, "404": { - "description": "Account or module not found, or no modules configured", + "description": "Account or module not found", "content": { "application/json": { "schema": { @@ -2078,7 +2118,7 @@ } }, "400": { - "description": "Invalid params, reason or assignment", + "description": "Invalid params, reason or assignment, or no policy modules are configured", "content": { "application/json": { "schema": { @@ -2108,7 +2148,7 @@ } }, "404": { - "description": "Account or module not found, or no modules configured", + "description": "Account or module not found", "content": { "application/json": { "schema": { @@ -3347,6 +3387,17 @@ "$ref": "#/components/schemas/DecodedNote" } }, + "modules": { + "oneOf": [ + { + "type": "null" + }, + { + "$ref": "#/components/schemas/ModuleApproval", + "description": "The policy module configuration that approved this delta: the catalog and params version\nit was judged under and the module failures an `on_error = allow` instance let through.\nAbsent when no module ran." + } + ] + }, "new_commitment": { "type": [ "string", @@ -4186,6 +4237,26 @@ "params" ] }, + "FailedOpen": { + "type": "object", + "required": [ + "module_id", + "layer", + "failure" + ], + "properties": { + "failure": { + "type": "string", + "description": "`timeout`, `error`, `invalid_decision`, `request_unavailable` or `circuit_open`; the\ndetail is logged." + }, + "layer": { + "type": "string" + }, + "module_id": { + "type": "string" + } + } + }, "HistoryEntry": { "type": "object", "required": [ @@ -4244,6 +4315,45 @@ } } }, + "ModuleApproval": { + "type": "object", + "description": "The policy modules' approval of a signed delta: the configuration they ran with, when and for\nwhom. Allowed evaluations are not listed: the catalog, params version and account determine\nwhich modules ran, so only failures let through by `on_error = allow` are kept.", + "required": [ + "catalog_hash", + "params_version", + "signed_at", + "submitter" + ], + "properties": { + "catalog_hash": { + "type": "string", + "description": "SHA-256 of the catalog file the approving replica loaded." + }, + "failed_open": { + "type": "array", + "items": { + "$ref": "#/components/schemas/FailedOpen" + } + }, + "params_version": { + "type": "integer", + "format": "int64", + "minimum": 0 + }, + "proposer": { + "type": "string", + "description": "The matching proposal's creator; empty when no stored proposal matched." + }, + "signed_at": { + "type": "string", + "description": "RFC 3339 time the Guardian signed, the accounting time the modules evaluated with." + }, + "submitter": { + "type": "string", + "description": "The cosigner the acknowledgment was evaluated for." + } + } + }, "ModuleCatalogView": { "type": "object", "required": [ diff --git a/docs/openapi.json b/docs/openapi.json index 9709b391..cf8cf249 100644 --- a/docs/openapi.json +++ b/docs/openapi.json @@ -817,6 +817,16 @@ } } }, + "400": { + "description": "No policy modules are configured", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, "401": { "description": "No operator session", "content": { @@ -838,7 +848,7 @@ } }, "404": { - "description": "Account or module not found, or no modules configured", + "description": "Account or module not found", "content": { "application/json": { "schema": { @@ -912,7 +922,7 @@ } }, "400": { - "description": "Invalid params, reason or assignment", + "description": "Invalid params, reason or assignment, or no policy modules are configured", "content": { "application/json": { "schema": { @@ -942,7 +952,7 @@ } }, "404": { - "description": "Account or module not found, or no modules configured", + "description": "Account or module not found", "content": { "application/json": { "schema": { @@ -1027,7 +1037,7 @@ } }, "400": { - "description": "Invalid params, reason or assignment", + "description": "Invalid params, reason or assignment, or no policy modules are configured", "content": { "application/json": { "schema": { @@ -1057,7 +1067,7 @@ } }, "404": { - "description": "Account or module not found, or no modules configured", + "description": "Account or module not found", "content": { "application/json": { "schema": { @@ -1140,7 +1150,7 @@ } }, "400": { - "description": "Invalid params, reason or assignment", + "description": "Invalid params, reason or assignment, or no policy modules are configured", "content": { "application/json": { "schema": { @@ -1170,7 +1180,7 @@ } }, "404": { - "description": "Account or module not found, or no modules configured", + "description": "Account or module not found", "content": { "application/json": { "schema": { @@ -1817,6 +1827,16 @@ } } }, + "400": { + "description": "No policy modules are configured", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, "401": { "description": "No operator session", "content": { @@ -1838,7 +1858,7 @@ } }, "404": { - "description": "Account or module not found, or no modules configured", + "description": "Account or module not found", "content": { "application/json": { "schema": { @@ -1914,7 +1934,7 @@ } }, "400": { - "description": "Invalid params, reason or assignment", + "description": "Invalid params, reason or assignment, or no policy modules are configured", "content": { "application/json": { "schema": { @@ -1944,7 +1964,17 @@ } }, "404": { - "description": "Account or module not found, or no modules configured", + "description": "Account or module not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "409": { + "description": "The catalog does not mark the instance operator_can_disable", "content": { "application/json": { "schema": { @@ -2020,7 +2050,7 @@ } }, "400": { - "description": "Invalid params, reason or assignment", + "description": "Invalid params, reason or assignment, or no policy modules are configured", "content": { "application/json": { "schema": { @@ -2050,7 +2080,7 @@ } }, "404": { - "description": "Account or module not found, or no modules configured", + "description": "Account or module not found", "content": { "application/json": { "schema": { @@ -2078,6 +2108,16 @@ } } } + }, + "503": { + "description": "The module failed its startup checks; nothing changed", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } } }, "security": [ @@ -2126,7 +2166,7 @@ } }, "400": { - "description": "Invalid params, reason or assignment", + "description": "Invalid params, reason or assignment, or no policy modules are configured", "content": { "application/json": { "schema": { @@ -2156,7 +2196,7 @@ } }, "404": { - "description": "Account or module not found, or no modules configured", + "description": "Account or module not found", "content": { "application/json": { "schema": { @@ -2241,7 +2281,7 @@ } }, "400": { - "description": "Invalid params, reason or assignment", + "description": "Invalid params, reason or assignment, or no policy modules are configured", "content": { "application/json": { "schema": { @@ -2271,7 +2311,7 @@ } }, "404": { - "description": "Account or module not found, or no modules configured", + "description": "Account or module not found", "content": { "application/json": { "schema": { @@ -6840,6 +6880,17 @@ "$ref": "#/components/schemas/DecodedNote" } }, + "modules": { + "oneOf": [ + { + "type": "null" + }, + { + "$ref": "#/components/schemas/ModuleApproval", + "description": "The policy module configuration that approved this delta: the catalog and params version\nit was judged under and the module failures an `on_error = allow` instance let through.\nAbsent when no module ran." + } + ] + }, "new_commitment": { "type": [ "string", @@ -7705,7 +7756,7 @@ }, { "$ref": "#/components/schemas/ModuleApproval", - "description": "The policy module configuration that approved this delta, for operators: absent when no\nmodule ran, and never included in client API responses." + "description": "The policy module configuration that approved this delta, for operators: absent when no\nmodule ran, never included in client API responses, and served to operators on the\ndashboard delta detail." } ] }, @@ -8271,7 +8322,7 @@ "properties": { "failure": { "type": "string", - "description": "`timeout`, `error`, `invalid_decision` or `request_unavailable`; the detail is logged." + "description": "`timeout`, `error`, `invalid_decision`, `request_unavailable` or `circuit_open`; the\ndetail is logged." }, "layer": { "type": "string" From fc0ffcabcee76a14c18ea2e05b7b9574ca7a2343 Mon Sep 17 00:00:00 2001 From: Zeljko Date: Tue, 10 Nov 2026 07:34:33 +0100 Subject: [PATCH 079/105] chore(skills): fingerprints after the module review fixes (#251) auth-replay, guardian-switch and proposal-lifecycle mirror configure_account, propose and verify_delta. The changes add an account id check, a log line, an audit call and the network id passed to module requests; no modelled transition changed and every cell still passes. --- .agents/skills/verify-auth-replay/fingerprints.txt | 2 +- .agents/skills/verify-guardian-switch/fingerprints.txt | 6 +++--- .agents/skills/verify-proposal-lifecycle/fingerprints.txt | 4 ++-- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/.agents/skills/verify-auth-replay/fingerprints.txt b/.agents/skills/verify-auth-replay/fingerprints.txt index 9ae8f2a7..2f28b1f6 100644 --- a/.agents/skills/verify-auth-replay/fingerprints.txt +++ b/.agents/skills/verify-auth-replay/fingerprints.txt @@ -6,7 +6,7 @@ crates/server/src/services/mod.rs resolve_account_with_head 92e4ff1e6a5c227a crates/server/src/services/mod.rs verify_session_request a4caa18e7b49c424 crates/server/src/services/mod.rs validate_request_timestamp 56ff32640a697109 crates/server/src/services/mod.rs consume_auth_timestamp 3dd46e9a0fddb6f0 -crates/server/src/services/configure_account.rs configure_account 2756bc058f4a6e4d +crates/server/src/services/configure_account.rs configure_account 2537014d98d43c71 crates/server/src/session.rs stale_floor_age_ms 83c6a11eea648b32 crates/server/src/session.rs replay_floor_key e6371be262401f43 crates/server/src/session.rs find 34aa53044b39192d diff --git a/.agents/skills/verify-guardian-switch/fingerprints.txt b/.agents/skills/verify-guardian-switch/fingerprints.txt index c8a6f824..0ca04b27 100644 --- a/.agents/skills/verify-guardian-switch/fingerprints.txt +++ b/.agents/skills/verify-guardian-switch/fingerprints.txt @@ -3,8 +3,8 @@ crates/server/src/services/release_on_switch.rs release_switched_account 0a8d56a crates/server/src/services/account_status.rs ensure_account_active_metadata b7303e5276ca4f67 crates/server/src/services/push_delta.rs push_delta 5885e2ee0d38c7d0 crates/server/src/services/push_delta_proposal.rs push_delta_proposal f3273779e9d7758f -crates/server/src/services/push_delta_proposal.rs propose 1c5422905df0ed37 -crates/server/src/services/configure_account.rs configure_account 2756bc058f4a6e4d +crates/server/src/services/push_delta_proposal.rs propose 176b2f353a59dcef +crates/server/src/services/configure_account.rs configure_account 2537014d98d43c71 crates/server/src/services/configure_account.rs stored_state_landed f1082399d583be3f crates/server/src/services/configure_account.rs stored_head 641128d1cfa79677 crates/server/src/services/pause_account.rs pause 7a8b3686c25b35b2 @@ -28,7 +28,7 @@ crates/server/src/jobs/canonicalization/processor.rs handle_diverged_candidate 9 crates/server/src/jobs/canonicalization/processor.rs landed_through_successor 166225b1cef5afed crates/server/src/jobs/canonicalization/processor.rs canonicalize_verified_delta 02f72218c5298266 crates/server/src/jobs/canonicalization/reconciliation.rs reconcile_chain_advance a9652aaef66374ce -crates/server/src/network/miden/mod.rs verify_delta 0f121467477a893b +crates/server/src/network/miden/mod.rs verify_delta 278b4074309a53a3 crates/server/src/jobs/release_sweep/sweep.rs visit 60bfd30f9d96b36c crates/server/src/jobs/release_sweep/sweep.rs check_stored_state c0794794507565ea crates/server/src/jobs/release_sweep/sweep.rs promoting_delta_nonce f40636c8b5ae7261 diff --git a/.agents/skills/verify-proposal-lifecycle/fingerprints.txt b/.agents/skills/verify-proposal-lifecycle/fingerprints.txt index 207ac0df..f6ec95fd 100644 --- a/.agents/skills/verify-proposal-lifecycle/fingerprints.txt +++ b/.agents/skills/verify-proposal-lifecycle/fingerprints.txt @@ -1,5 +1,5 @@ crates/server/src/services/push_delta_proposal.rs push_delta_proposal f3273779e9d7758f -crates/server/src/services/push_delta_proposal.rs propose 1c5422905df0ed37 +crates/server/src/services/push_delta_proposal.rs propose 176b2f353a59dcef crates/server/src/services/push_delta.rs push_delta 5885e2ee0d38c7d0 crates/server/src/services/ack_delta_internal.rs lookup_matching_proposal 9b5ac8501f9abe75 crates/server/src/services/candidate_chain.rs load_for_admission ed7abd9edcc81e9f @@ -8,7 +8,7 @@ crates/server/src/storage/mod.rs gate_candidate_submission 99785be2d52ca367 crates/server/src/storage/postgres.rs submit_candidate e060bdbb989ca363 crates/server/src/storage/postgres.rs submit_delta_proposal b679915e671eb474 crates/server/src/storage/filesystem.rs submit_candidate 83549e868e6f5e25 -crates/server/src/network/miden/mod.rs verify_delta 0f121467477a893b +crates/server/src/network/miden/mod.rs verify_delta 278b4074309a53a3 crates/server/src/network/miden/mod.rs delta_proposal_id 0bb59c0e0a3438ba crates/server/src/jobs/canonicalization/processor.rs canonicalize_verified_delta 02f72218c5298266 crates/server/src/jobs/canonicalization/processor.rs retain_candidate 813bb75dd428ee39 From f14b44d108809547db913a160883e70e38ffa8b8 Mon Sep 17 00:00:00 2001 From: Zeljko Date: Tue, 10 Nov 2026 07:34:43 +0100 Subject: [PATCH 080/105] docs(modules): RFC 0002 revision 32 and the guides after the implementation review (#251) - RFC: protocol version 1 not frozen yet, effect-only decisions, the block fields, network_id, the fee note bound, the breaker rules, the modules.failed_open audit event, and body text corrected to the implementation (metric names, timeout cap, params encoding, failure kinds, the serve example). - Guides: the branch to run from, basic-policy id and modifier rules, the request fields a module receives, what a remote module can change. - Configuration, dashboard, troubleshooting and runbook: startup rules for GUARDIAN_MODULES_CONFIG, the state directory default, the budget check scope, breaker behaviour, where the approval record is read, routes that exist. - Speckit contracts and data model brought in line. --- docs/CONFIGURATION.md | 10 +-- docs/DASHBOARD.md | 21 ++++++- docs/TROUBLESHOOTING.md | 8 ++- docs/guides/README.md | 2 +- docs/guides/policy-modules/README.md | 17 ++--- docs/guides/policy-modules/built-in.md | 15 ++++- docs/guides/policy-modules/custom.md | 23 ++++--- docs/guides/policy-modules/remote.md | 13 ++-- docs/rfcs/0002-guardian-modules.md | 62 +++++++++---------- docs/runbooks/policy-modules.md | 14 +++-- .../contracts/catalog-config.md | 3 +- .../contracts/operator-modules-api.md | 2 +- .../251-guardian-modules/data-model.md | 4 +- 13 files changed, 119 insertions(+), 75 deletions(-) diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md index 5bcfaa7b..0ea05e6e 100644 --- a/docs/CONFIGURATION.md +++ b/docs/CONFIGURATION.md @@ -407,13 +407,13 @@ modules guide](./guides/policy-modules/README.md). | Variable | Default | Notes | |---|---|---| -| `GUARDIAN_MODULES_CONFIG` | _unset_ (no modules) | Path of the module catalog (TOML). Read once at startup; it declares every instance and seeds its global params on first start, after which params are managed through the [operator API](./DASHBOARD.md#policy-modules). A relative path resolves against the working directory; a relative `tls.ca_file` in the catalog resolves against the catalog's directory, and `auth.token_secret`, `tls.client_cert_secret`, `tls.client_key_secret` and `$secret` params name secrets read through `GUARDIAN_MODULE_SECRET_PROVIDER`. An enabled instance that fails its startup checks stops startup. In the prod stage remote instances must use TLS (`grpc://`) and set `auth`. | +| `GUARDIAN_MODULES_CONFIG` | _unset_ (no modules) | Path of the module catalog (TOML). A value that is set but empty, or a catalog that declares no module, refuses startup: unset the variable to run without modules. Without it the server logs that no policy module runs, as a warning when its database still holds module state from an earlier catalog. Read once at startup; it declares every instance and seeds its global params on first start, after which params are managed through the [operator API](./DASHBOARD.md#policy-modules). A relative path resolves against the working directory; a relative `tls.ca_file` in the catalog resolves against the catalog's directory, and `auth.token_secret`, `tls.client_cert_secret`, `tls.client_key_secret` and `$secret` params name secrets read through `GUARDIAN_MODULE_SECRET_PROVIDER`. An enabled instance that fails its startup checks stops startup. In the prod stage remote instances must use TLS (`grpc://`) and set `auth`. | | `GUARDIAN_MODULE_CHECK_RATE_PER_MIN` | `30` | Dry-run proposal checks (`POST /delta/proposal/check`) one signer may make for one account per minute; excess returns `rate_limit_exceeded`. Per replica. A value that is not a positive integer refuses startup. | -| `GUARDIAN_MODULES_STATE` | `/modules` | Filesystem builds only: directory of the module state file (`module_state.json`). Postgres builds keep module state in the database. | -| `GUARDIAN_MODULE_EVALUATION_BUDGET_MS` | `1000` | Time spent in module calls for one hook invocation (request assembly is not charged). Each call gets the smaller of its `timeout_ms` and what is left; once spent, later modules count as timed out and their `on_error` applies. In the prod stage startup refuses a catalog whose `all` instances, enabled or not, exceed it at any hook, and a budget not below the execution reservation lease; account assignments and layers that would raise an account's cost over it are refused at write time, while writes that keep or lower the cost pass. Client and SDK request timeouts must exceed it, or a slow approval arrives after the client retried. | +| `GUARDIAN_MODULES_STATE` | `/modules` when that variable is set, otherwise `.tables` next to the catalog file | Filesystem builds only: directory of the module state file (`module_state.json`). Set it, or `GUARDIAN_METADATA_PATH`, when the catalog sits on a read-only mount. Postgres builds keep module state in the database. | +| `GUARDIAN_MODULE_EVALUATION_BUDGET_MS` | `1000` | Time spent in module calls for one hook invocation (request assembly is not charged). Each call gets the smaller of its `timeout_ms` and what is left; once spent, later modules count as timed out and their `on_error` applies. In the prod stage startup refuses a catalog whose `all` and `default` instances, enabled or not, exceed it at any hook, and a budget not below the execution reservation lease; account assignments and layers that would raise an account's cost over it are refused at write time, while writes that keep or lower the cost pass. Client and SDK request timeouts must exceed it, or a slow approval arrives after the client retried. | | `GUARDIAN_MODULE_REQUEST_MAX_BYTES` | `2097152` (2 MiB) | Largest encoded request sent to a module. A larger one is a module failure and is not sent; its `on_error` applies. | -| `GUARDIAN_MODULE_BREAKER_FAILURES` | `5` | Consecutive failures (timeouts, transport errors, malformed decisions) that open an instance's circuit breaker on a replica. While open the module is not called and its `on_error` applies at once. A deny is an answer and resets the count. | -| `GUARDIAN_MODULE_PROBE_INTERVAL_MS` | `5000` | Interval of the `Describe` health probe of every enabled instance. A successful probe moves an open breaker to half-open, where the next call decides; the result is `guardian_module_up`. | +| `GUARDIAN_MODULE_BREAKER_FAILURES` | `5` | Consecutive failures (timeouts, transport errors, malformed decisions) that open an instance's circuit breaker on a replica. While open the module is not called and its `on_error` applies at once. A deny is an answer and resets the count, and so is a request the module rejects as one it cannot judge (its `on_error` still applies to that request). A timeout that earlier modules caused by using up the budget does not count, and dry-run checks neither count nor reset. | +| `GUARDIAN_MODULE_PROBE_INTERVAL_MS` | `5000` | Interval of the `Describe` health probe of every enabled instance. A successful probe moves an open breaker to half-open, where one call at a time is sent as the trial and decides, while other requests are treated as while open; the result is `guardian_module_up`. | | `GUARDIAN_MODULE_PARAMS_MAX_BYTES` | `65536` (64 KiB) | Largest params value one write may store (global params, an account layer or an assignment entry), measured as compact JSON with sorted keys. A larger write is refused with `invalid_input` before the module is called, and a larger catalog seed refuses startup, so no params value can push every request for an account over `GUARDIAN_MODULE_REQUEST_MAX_BYTES`. | | `GUARDIAN_MODULE_SECRET_PROVIDER` | `aws` in the prod stage, `file` otherwise | Where the secrets a module catalog names (`auth.token_secret`, `tls.client_cert_secret`, `tls.client_key_secret`, `$secret` params) are read from, once at startup. `file`: one file per secret below `GUARDIAN_MODULE_SECRET_DIR`, readable by its owner only (`0600`). `aws`: AWS Secrets Manager secret ids, with `AWS_REGION` set. Not consulted when the catalog names no secret. | | `GUARDIAN_MODULE_SECRET_DIR` | the catalog's directory | Directory of the `file` secrets provider; a secret name is a relative path below it. | diff --git a/docs/DASHBOARD.md b/docs/DASHBOARD.md index 0bf33206..6175fe03 100644 --- a/docs/DASHBOARD.md +++ b/docs/DASHBOARD.md @@ -368,6 +368,20 @@ they cannot add, remove or reconfigure an instance. Every write takes a in the params history and the audit log. A walkthrough is in the [policy modules guide](./guides/policy-modules/README.md). +Which configuration approved a signed delta is on its detail, +`GET /dashboard/accounts/{account_id}/deltas/{nonce}`, in the `modules` field: +`catalog_hash`, `params_version`, `signed_at`, `submitter`, `proposer`, and +under `failed_open` each module failure an `on_error = "allow"` instance let +through (`module_id`, `layer`, `failure`). It is absent when no module ran for +the delta, and client routes never return it. The same skips at proposal +creation and account registration, where nothing is signed, are written to the +audit log as `modules.failed_open` events (`operator_identity` `system`, with +the hook, submitter, catalog hash, params version and, for a proposal, its +`proposal_id`). Operator writes are audited with the params version they +committed as, or `null` for an enable or disable that changed nothing. +`GET /dashboard/info` reports the +catalog hash this replica loaded as `backend.module_catalog_hash`. + | Endpoint | Permission | Body | |---|---|---| | `GET /dashboard/modules` | `dashboard:read` | | @@ -388,8 +402,11 @@ account's other assignments; a `scope = assigned` one applies only where it is assigned. Disabling an instance the catalog does not mark `operator_can_disable` returns `409 GUARDIAN_MODULE_NOT_DISABLEABLE`. -Writes are refused with `400 invalid_input` when the params exceed -`GUARDIAN_MODULE_PARAMS_MAX_BYTES`, or when they would take the account's modules +Writes are refused with `400 invalid_input` when the `reason` is longer than +512 characters, when the params exceed +`GUARDIAN_MODULE_PARAMS_MAX_BYTES`, when a layer is written for a module the +account still has in its assignment (left from before a catalog change made it +`scope = all`; remove it from the assignment first), or when they would take the account's modules over the evaluation budget at a hook where they are not already that far over (each `all` instance, again for its layer, plus each assigned one). A write that keeps or lowers the cost always passes, so an account a deploy pushed over the diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md index ebc0cad0..6bf73129 100644 --- a/docs/TROUBLESHOOTING.md +++ b/docs/TROUBLESHOOTING.md @@ -872,7 +872,8 @@ Guardian execution ends `failed` with `GUARDIAN_EXECUTION_MODULE_DENIED` or `module`, `account_id` and the failure: the module's error, `timed out`, an invalid reason code or unknown effect, a request over `GUARDIAN_MODULE_REQUEST_MAX_BYTES`, or an open circuit. A fail-open - failure is also recorded on the signed delta (`metadata.modules.failed_open`) + failure is also recorded on the signed delta (`modules.failed_open` on + `GET /dashboard/accounts/{account_id}/deltas/{nonce}`) and counted in `guardian_module_fail_open_total`. 3. **Module health.** `guardian_module_up` is 0 after a failed `Describe` health probe (`Policy module health probe failed` at `warn`), and @@ -882,8 +883,9 @@ Guardian execution ends `failed` with `GUARDIAN_EXECUTION_MODULE_DENIED` or shows in `guardian_module_evaluate_duration_seconds` and as `timed out` failures: compare with the instance's `timeout_ms` and `GUARDIAN_MODULE_EVALUATION_BUDGET_MS`. -4. **Params.** `GET /dashboard/modules/{id}` shows the params in force, the - account's layer or assignment, and `params_drift`; the history route shows +4. **Params.** `GET /dashboard/modules` shows each instance's params in force + and `params_drift`, and `GET /dashboard/accounts/{account_id}/modules` the + account's layer or assignment; the history route shows who changed them and why. A change through the operator API applies on the next request. diff --git a/docs/guides/README.md b/docs/guides/README.md index c2e1925b..583a7807 100644 --- a/docs/guides/README.md +++ b/docs/guides/README.md @@ -26,7 +26,7 @@ storage, or network), not after Compose. | [Miden Dashboard UI](./miden-dashboard/README.md) | Self-hosted Compose: Postgres + Guardian server + the Miden Dashboard operator UI | | [Observability](./observability/README.md) | Local Compose: server + Prometheus + pre-provisioned Grafana dashboard | | [Horizontal scaling](./horizontal-scaling/README.md) | Local Compose: two replicas + round-robin proxy + shared Postgres (sessions, lease failover, fail-closed auth) | -| [Policy modules](./policy-modules/README.md) | From source (prototype branch): built-in `basic-policy`, a remote module over gRPC, and a custom module written with `guardian-module-sdk` | +| [Policy modules](./policy-modules/README.md) | From source (`251-modules-m2a` branch): built-in `basic-policy`, a remote module over gRPC, and a custom module written with `guardian-module-sdk` | ## Adding a guide diff --git a/docs/guides/policy-modules/README.md b/docs/guides/policy-modules/README.md index 75b3a820..a80daf88 100644 --- a/docs/guides/policy-modules/README.md +++ b/docs/guides/policy-modules/README.md @@ -5,8 +5,8 @@ rules, and your own checks, consulted before the Guardian signs. A module only answers allow or deny. A deny refuses the Guardian's acknowledgement, so the transaction cannot execute; a module can never produce a signature. -> **Prototype.** Modules are implemented on the -> [`251-modules-prototype`](https://github.com/OpenZeppelin/guardian/tree/251-modules-prototype) +> **Not released yet.** Modules are implemented on the +> [`251-modules-m2a`](https://github.com/OpenZeppelin/guardian/tree/251-modules-m2a) > branch and are not in a release. The design is > [RFC 0002](../../rfcs/0002-guardian-modules.md). No published image includes > modules yet, so this guide runs the server from source instead of Docker @@ -98,7 +98,7 @@ In ## Setup -Run everything from the repository root, on the prototype branch. +Run everything from the repository root, on the `251-modules-m2a` branch. ### 1. Operator key @@ -124,7 +124,9 @@ cp docs/guides/policy-modules/.env.example docs/guides/policy-modules/.env ``` Edit `.guardian/built-in.toml` for your network: replace `0xREPLACE_WITH_FAUCET_ID` -with the faucet id of an asset you hold. The other pages swap in +with the faucet id of an asset you hold, in `0x` hex form. The server does not +start until you do: `basic-policy` refuses an id that is not hex, since a +placeholder or a bech32 address would never match a transaction. The other pages swap in `remote.toml` or `custom.toml` by changing `GUARDIAN_MODULES_CONFIG` in the guide's `.env`. @@ -141,7 +143,7 @@ module state then goes to `GUARDIAN_METADATA_PATH/modules/module_state.json`. Look for this line in the log: ``` -Policy modules loaded catalog_hash=0x… params_version=… builds=caps=basic-policy 0.18.1, … +Policy modules loaded catalog_hash=0x… params_version=… builds=caps=basic-policy , … ``` The ports are fixed at 3000 (HTTP) and 50051 (gRPC); stop any other Guardian @@ -183,7 +185,7 @@ Any client works; refusals are plain Guardian errors. | See what applies to an account | `admin GET /accounts/{account_id}/modules` | | Switch an instance off or on | `admin POST /modules/{id}/disable '{"reason":"..."}'`, then `/enable` | | See every change | `admin GET /modules/{id}/params/history` | -| See which configuration approved a delta | `admin GET /accounts/{account_id}/deltas/{nonce}`, field `metadata.modules` | +| See which configuration approved a delta | `admin GET /accounts/{account_id}/deltas/{nonce}`, field `modules` | Every write is validated by the module before it is stored; invalid params return `400` and change nothing. @@ -196,7 +198,8 @@ For outages, a module that refuses too much, and break-glass steps, see the | Symptom | Cause | |---|---| | `cannot read module catalog` | `GUARDIAN_MODULES_CONFIG` is relative to the directory you started the server in; start from the repository root. | -| `module caps: invalid params: …` at startup | The catalog's seed params, or the stored params on a later start, fail the module's validation. Fix the catalog; nothing is stored until every instance passes. | +| `module caps: invalid params: …` at startup | The catalog's seed params fail the module's validation on a first start: fix the catalog; nothing is stored until every instance passes. On a later start it is the stored params that fail (the catalog's are no longer read): see the [runbook](../../runbooks/policy-modules.md). | +| `GUARDIAN_MODULES_CONFIG is set but empty` or `declares no module` at startup | An empty value or an empty catalog would silently run without any policy. Point the variable at a catalog, or unset it to run without modules. | | `module caps-remote: …` at startup | An enabled remote module is unreachable or rejected the token. Start the module first, or set `enabled = false` until it runs. | | `relation "module_state_version" does not exist` | A Postgres database that ran an earlier prototype migration. Drop the `module_*` tables and the `20261015000001` row in `__diesel_schema_migrations`, then restart. | | `login failed: no session cookie` | The server did not load the key: check `GUARDIAN_OPERATOR_PUBLIC_KEYS_FILE` and the `public_key` in it. | diff --git a/docs/guides/policy-modules/built-in.md b/docs/guides/policy-modules/built-in.md index 62e62ebb..0dd85780 100644 --- a/docs/guides/policy-modules/built-in.md +++ b/docs/guides/policy-modules/built-in.md @@ -10,8 +10,17 @@ and scope. Do the [setup](./README.md#setup) first; the catalog is All params are optional; an instance with none allows everything. Write every id (faucet, recipient, signer commitment, code commitment) in the `0x` hex form the Guardian reports, not as a bech32 address: params with another form are -refused, since such an id would never match and its rule would not apply. -Case does not matter. +refused, since such an id would never match and its rule would not apply. So +is anything else that is not hex digits after `0x`, such as a placeholder left +in an example catalog. Case does not matter, and a cap that names the same +faucet twice in different case is refused. + +A param that only modifies another is refused without it: +`deny_unknown_recipients` needs `recipient_denylist`, `signer_check` needs a +signer list and `code_check` needs `allowed_code_commitments`. This matters for +account layers, which are evaluated with their own params: a layer of +`{"deny_unknown_recipients": true}` alone would do nothing, so it is not +accepted. | Param | Value | Refuses with | Notes | |---|---|---|---| @@ -69,7 +78,7 @@ has both. ```sh admin PUT /accounts/ACCOUNT/modules/caps/params \ - '{"params":{"max_amount_per_tx":{"0xFAUCET":"2"}},"reason":"test"}' + '{"params":{"max_amount_per_tx":{"":"2"}},"reason":"test"}' admin GET /accounts/ACCOUNT/modules ``` diff --git a/docs/guides/policy-modules/custom.md b/docs/guides/policy-modules/custom.md index 7de4940b..a2462ce3 100644 --- a/docs/guides/policy-modules/custom.md +++ b/docs/guides/policy-modules/custom.md @@ -93,7 +93,7 @@ The rules are in [RFC 0002 section 3.5](../../rfcs/0002-guardian-modules.md#35-p |---|---|---| | `before_proposal_created` | Before a multisig proposal is stored, and in dry runs | `transaction` | | `before_transaction_approved` | Before the Guardian signs a pushed delta or a Guardian execution: the one that enforces, since transactions signed offline skip proposals | `transaction` | -| `before_account_registered` | When an account is first configured on this Guardian | `registration` | +| `before_account_registered` | On every `/configure` of an account: its first configuration on this Guardian and each later re-configuration | `registration` | A module lists the hooks it supports in `describe`; the catalog subscribes each instance to some of them, and the Guardian refuses an instance subscribed to a @@ -104,19 +104,19 @@ hook its module does not list. | `request_id` | Unique per hook invocation and shared by every module called in it; log it to join your logs with the Guardian's | | `hook` | Which hook is calling | | `dry_run` | `true` for a policy check: nothing is stored or signed whatever you decide (see [Dry runs](#dry-runs)) | -| `network`, `network_id` | `"miden"`, and `"mainnet"`, `"testnet"`, `"devnet"`, `"cedar"` or `"local"` | +| `network`, `network_id` | `"miden"`, and the network this Guardian serves: `"mainnet"`, `"testnet"`, `"devnet"`, `"cedar"` or `"local"`. It comes from the Guardian's own configuration, never from the account's registration | | `account_id`, `instance_id` | The account, and the catalog id of the instance being called | | `params` | UTF-8 JSON: the instance's global params, the account's layer on its second pass, or the account's own params for a `default` or `assigned` instance. Read them on every call; they change without restarting the module | | `accounting_time` | The time recorded with the transaction if it is signed; at `before_proposal_created` and in a dry run, the evaluation time | | `submitter`, `submitter_session` | The verified signer commitment that authenticated the request, and whether it did so through a session key it delegated | -| `before` | The account as the Guardian holds it; absent at `before_account_registered` | +| `before` | The account as the Guardian holds it. At `before_account_registered` it is absent for a first configuration and set to the stored state for a re-configuration, so "no `before`" means "new to this Guardian", not "registration" | | `after` | The account as it will be if every module allows | | `subject.transaction.projection` | The decoded transaction; read the Miden variant with `subject.miden()` | | `subject.transaction.proposer` | The verified signer commitment that created the matching proposal; empty when there is none | | `subject.transaction.unverified_metadata` | UTF-8 JSON the proposer asserted; never base a decision on it alone | | `subject.transaction.raw` | The transaction in its network's own encoding (`encoding = "miden.transaction_summary"`), for modules that decode it themselves; tied to the Guardian's Miden version | | `subject.transaction.pending` | Empty until commit notifications ship (M2b) | -| `subject.registration.initial_state` | The account about to be accepted: vault and storage slots | +| `subject.registration.initial_state` | The account about to be accepted: its whole vault and every storage slot, map entries included. Read the Miden variant with `subject.miden()` | An account view (`before`, `after`) carries the account `commitment`, its `signer_commitments` with each signer's scheme in `signer_schemes` (`auth_scheme` @@ -124,15 +124,22 @@ is `"falcon"`, `"ecdsa"` or `"mixed"`), `default_threshold` (absent for single-key accounts), `procedure_thresholds`, `code_commitment` and the `procedure_roots` the code exports. -The Miden projection has the `nonce_delta`, the `reference_block` and optional -`expiration_block`, `vault_changes` (asset and direction), `output_notes` +The Miden projection has the `nonce_delta`, the `bound_block` (the block the +summary binds; the transaction executes against it or a later one), the +optional `expiration_delta` (blocks after the block it executes against, set by +its script, so not an absolute height), the optional +`approval_expiration_block` (the block at which the cosigners' approval +lapses; use this one for "valid until"), `vault_changes` (asset and +direction), `output_notes` (`note_type`, assets, `p2id_target` for known P2ID and P2IDE scripts, `tx_fee`), `input_notes`, `storage_changes` by slot name, and `new_code_commitment` when the transaction replaces the account's code. Amounts are decimal strings. Skip the fee note (`tx_fee = true`) when counting payments: every transaction pays its fee through an output note. The Guardian -sets `tx_fee` only on the one note the fee payment creates, never on another -note that merely uses the fee script, so treat every other note as a payment. +sets `tx_fee` only on the one note the fee payment creates, and only while it +carries no more of the fee asset than a transaction can owe (64 times the +chain's base fee), never on another note that merely uses the fee script, so +treat every other note as a payment. Projections are tagged by network (`TransactionProjection`, `oneof network`). Miden is the only network today; read it with `subject.miden()` and return a diff --git a/docs/guides/policy-modules/remote.md b/docs/guides/policy-modules/remote.md index a0d40a9e..5263cb8b 100644 --- a/docs/guides/policy-modules/remote.md +++ b/docs/guides/policy-modules/remote.md @@ -53,7 +53,7 @@ cp docs/guides/policy-modules/remote.toml .guardian/ Replace the faucet placeholder, set `GUARDIAN_MODULES_CONFIG=.guardian/remote.toml` in the guide's `.env`, and start the server as in the setup. The module must already be running: an enabled instance that cannot be reached stops startup. -The log line lists `caps-remote=basic-policy 0.18.1`. +The log line lists `caps-remote=basic-policy `. `auth.token_secret` names a secret in the Guardian's secrets backend (see [Credentials](#credentials)); here the `file` provider reads it from @@ -64,10 +64,10 @@ The log line lists `caps-remote=basic-policy 0.18.1`. | Test | How | Expected | |---|---|---| | Remote refusal | Pay 4 | Refused by `caps-remote` (cap 3); the in-process `caps` (cap 5) allows it | -| Remote params | `admin PUT /modules/caps-remote/params '{"params":{"max_amount_per_tx":{"0xFAUCET":"1"}},"reason":"test"}'`, then pay 2 | Refused; the module was not restarted | +| Remote params | `admin PUT /modules/caps-remote/params '{"params":{"max_amount_per_tx":{"":"1"}},"reason":"test"}'`, then pay 2 | Refused; the module was not restarted | | Module down, fail closed | Stop the module, pay 1 | `503 GUARDIAN_MODULE_UNAVAILABLE`, module `caps-remote` | | Switch it off while down | `admin POST /modules/caps-remote/disable '{"reason":"module down"}'`, pay 1 | Allowed; start the module again and `/enable` (which re-runs `Describe` and `ValidateParams`) | -| Fail open | Set `on_error = "allow"`, restart the Guardian, stop the module, pay 1 | Allowed; the delta's `metadata.modules.failed_open` names `caps-remote` | +| Fail open | Set `on_error = "allow"`, restart the Guardian, stop the module, pay 1 | Allowed; the delta's `modules.failed_open` on the dashboard delta detail names `caps-remote` | | Wrong token | Start the module with a different token file, restart the Guardian | Startup fails: the module rejects `Describe` | ## Transport security @@ -109,7 +109,10 @@ stays disabled. Changing a secret takes effect at the next restart. ## What a remote module cannot do -It cannot sign, change its own params or hooks, or see secrets: catalog params -with secret references are refused for remote kinds. The worst a compromised +It cannot sign, change its hooks, or see secrets: catalog params with secret +references are refused for remote kinds. It can rewrite the params it is given +into its own normalized form when they are validated (at startup, on enable +and on every operator write), within the params size cap; the Guardian stores +that form, and with `disclosure = "params"` cosigners see it. The worst a compromised or failing remote module can do is refuse (or, with `on_error = "allow"`, be skipped), and the operator can switch it off if the catalog allows it. diff --git a/docs/rfcs/0002-guardian-modules.md b/docs/rfcs/0002-guardian-modules.md index cba10fc8..a5352362 100644 --- a/docs/rfcs/0002-guardian-modules.md +++ b/docs/rfcs/0002-guardian-modules.md @@ -2,12 +2,12 @@ | | | |---|---| -| **Status** | Accepted. Milestone M2a (section 7) is implemented on branch `251-modules-m2a`, not yet merged to `main`; M2b and M2c have not started. Comments are still welcome; protocol version 1 is frozen, so a change to it is a new capability or a new version (section 3.5) | +| **Status** | Accepted. Milestone M2a (section 7) is implemented on branch `251-modules-m2a`, not yet merged to `main`; M2b and M2c have not started. Comments are still welcome; protocol version 1 is not frozen yet: it freezes with the first published `guardian-module-sdk` release (section 7) | | **Depends on** | [RFC 0001](./0001-server-side-transaction-execution.md) (server-side transaction execution, merged in PR #510): the execution worker is the second caller of the pipeline | | **Feature** | [#251](https://github.com/OpenZeppelin/guardian/issues/251) ("Modularization: middleware architecture and pluggable modules"); first consumer [#182](https://github.com/OpenZeppelin/guardian/issues/182) (policy evaluation). [#252](https://github.com/OpenZeppelin/guardian/issues/252) (x402 facilitator) is a later consumer: its payment-policy half (caps, allowlists, replay) fits `before_transaction_approved` and `after_transaction_committed`, its facilitator half (`/verify`, `/settle`, a flow that starts and waits) does not fit allow/deny and is future work (section 7) | | **Audience** | Operators, module authors, integrators, and anyone reviewing the Guardian trust model | | **Working artifacts** | [`speckit/features/251-guardian-modules/`](../../speckit/features/251-guardian-modules/spec.md): the specification, written alongside this RFC; the plan, the M2a tasks (`tasks.md`) and the prototype record (`tasks-p0.md`) | -| **Revision** | 31 (2026-11-09): `tx_fee` marks only the fee note `pay_fee` creates (section 3.1); changes in Appendix C | +| **Revision** | 32 (2026-11-10): protocol version 1 reopened and corrected after a review of the M2a implementation; changes in Appendix C | | **Review sought** | Review of the M2a implementation before it merges; comments on M2b (commit notifications, stateful modules) and M2c (operator-built kinds) | | **Code baseline** | `main` at `ca503704`; execution-path citations read on `254-execution-impl` at `29c722b4` (PR #510, since merged to `main` as `1100f3a4`) and kept as dated evidence. Miden pins: protocol and standards 0.17.1. Appendices B and C cite the baselines of their revisions. Prototype findings (2026-10-13 to 2026-10-15) in `speckit/features/251-guardian-modules/research.md` | @@ -166,11 +166,11 @@ Each catalog entry: | `endpoint` | Remote kinds only: `grpc://…`, always TLS (`https://…` for `http` once it ships). Plain text needs the explicit `grpc+insecure://…` scheme and a loopback host, and is refused in the prod stage (section 5.2) | | `scope` | `all`, `default` or `assigned` (see scopes below) | | `hooks` | Subset of the hooks in section 2.3 | -| `timeout_ms` | Required; from 1 to `GUARDIAN_MODULE_TIMEOUT_MAX_MS` (default 1000) | +| `timeout_ms` | Required; from 1 to 1000 | | `on_error` | `deny` (default) or `allow` (section 4) | | `auth` | Remote kinds only, mandatory in the prod stage: `token_secret`, the secret name of the bearer token (section 5.2) | | `tls` | Remote kinds only, optional: `ca_file` (PEM bundle for a private CA, relative to the catalog's directory; the system roots otherwise) and `client_cert_secret` and `client_key_secret`, secret names, for mTLS (section 5.2) | -| `params` | Initial global parameters as a JSON object, written to the metadata store the first time the instance id is seen and managed through the operator API afterwards (see layered parameters below) (TOML tables in the catalog are converted to JSON). Modules receive params as UTF-8 JSON bytes in RFC 8785 canonical form (JCS). The decoded bytes are identical on every transport: in process and over gRPC they arrive as raw bytes, while over `http` (once it ships) the proto3 JSON mapping carries them as a base64 string that decodes to the same bytes (likewise `int64` fields arrive as decimal strings and `Timestamp` fields as RFC 3339 strings, per the standard mapping). See "Parameters and secrets" below | +| `params` | Initial global parameters as a JSON object, written to the metadata store the first time the instance id is seen and managed through the operator API afterwards (see layered parameters below) (TOML tables in the catalog are converted to JSON). Modules receive params as UTF-8 JSON bytes, compact and with object keys sorted (not full RFC 8785 canonicalization: numbers and strings are as `serde_json` writes them). The decoded bytes are identical on every transport: in process and over gRPC they arrive as raw bytes, while over `http` (once it ships) the proto3 JSON mapping carries them as a base64 string that decodes to the same bytes (likewise `int64` fields arrive as decimal strings and `Timestamp` fields as RFC 3339 strings, per the standard mapping). See "Parameters and secrets" below | | `require_fresh_state_ms` | Optional maximum notify lag in milliseconds (section 3.3) | | `enabled` | Default `true`. A one-time seed, read only the first time an instance id is seen; afterwards the runtime flag in the metadata store governs and later edits of this field have no effect (see runtime changes below) | | `disclosure`, `description`, `client_reason`, `dry_run` | What the account's cosigners may learn about the instance: the policy summary, generic or full denials, and the dry-run check (section 2.7). Defaults disclose nothing beyond today's denials | @@ -325,10 +325,10 @@ This revision specifies the operator API only; no operator dashboard page is pla **Runtime changes without a restart.** The catalog file is read only at startup. Hot reload was considered and rejected (section 8): on ECS, the production target, configuration reaches tasks through the task definition and image, so there is no file to change without a deploy; file watching is unreliable across network and container mounts; and with several replicas a reload reaches one process, so for a newly added `all` module the other replicas keep signing without it. The needs behind a reload are met by state in the metadata store instead, which every replica reads, so a change applies to all replicas at once: - **Global params, account layers and per-account assignment** (above). -- **Seed rule for `enabled`.** The catalog's `enabled` value is written to the metadata store only the first time an instance id is seen. After that the stored flag is the only switch: a redeploy that changes `enabled` in the file changes nothing, and the server logs a warning at startup when the file and the stored flag differ, lists the instance with `"enabled_drift": true` in `GET /dashboard/modules`, and exports `guardian_module_enabled_drift{module}`. Removing an instance from the catalog stops it but keeps its stored flag; adding the same id back resumes with that stored flag, not the file's value. The file is therefore not the switch for an existing instance; the operator API is. -- **Runtime enable and disable of declared instances.** `POST /dashboard/modules/{module_id}/enable` (permission `policies:write`) and `/disable` (`policies:write` or `modules:disable`), each with a required reason and an audit record, switch evaluation on or off for every account. The two directions carry different risk. Enabling only tightens policy and is always allowed, so an operator can declare an instance with `enabled = false` and switch it on later without a restart. Disabling loosens policy: an API that could disable any module would let a stolen operator session switch off sanctions screening for every account, which undoes invariant 4. It is therefore allowed only for instances with `operator_can_disable = true`. An instance declared with `enabled = false` and `operator_can_disable = false` is deliberately one-way: a staged rollout that an operator can switch on once and cannot switch off from a session; compliance instances leave the flag off, while advisory modules such as a fail-open risk scorer can turn it on as an emergency stop for a faulty module. The flag lives in `module_instances`, and the pipeline reads it per evaluation through the per-replica cache, so a switch reaches every replica on its next evaluation; it is also the flag that decides at startup whether an instance failing its checks stops the server. `guardian_module_disabled{module}` is exported for alarms. A disabled instance is skipped by `evaluate` but keeps receiving `notify`, so its state is current when it is enabled. +- **Seed rule for `enabled`.** The catalog's `enabled` value is written to the metadata store only the first time an instance id is seen. After that the stored flag is the only switch: a redeploy that changes `enabled` in the file changes nothing, and the server logs a warning at startup when the file and the stored flag differ, lists the instance with `"enabled_drift": true` in `GET /dashboard/modules`, and exports `guardian_module_config_drift{module}`. Removing an instance from the catalog stops it but keeps its stored flag; adding the same id back resumes with that stored flag, not the file's value. The file is therefore not the switch for an existing instance; the operator API is. +- **Runtime enable and disable of declared instances.** `POST /dashboard/modules/{module_id}/enable` (permission `policies:write`) and `/disable` (`policies:write` or `modules:disable`), each with a required reason and an audit record, switch evaluation on or off for every account. The two directions carry different risk. Enabling only tightens policy and is always allowed, so an operator can declare an instance with `enabled = false` and switch it on later without a restart. Disabling loosens policy: an API that could disable any module would let a stolen operator session switch off sanctions screening for every account, which undoes invariant 4. It is therefore allowed only for instances with `operator_can_disable = true`. An instance declared with `enabled = false` and `operator_can_disable = false` is deliberately one-way: a staged rollout that an operator can switch on once and cannot switch off from a session; compliance instances leave the flag off, while advisory modules such as a fail-open risk scorer can turn it on as an emergency stop for a faulty module. The flag lives in `module_instances`, and the pipeline reads it per evaluation through the per-replica cache, so a switch reaches every replica on its next evaluation; it is also the flag that decides at startup whether an instance failing its checks stops the server. `guardian_module_enabled{module}` (0 when disabled) is exported for alarms. A disabled instance is skipped by `evaluate` but keeps receiving `notify`, so its state is current when it is enabled. -Only adding an instance, removing one, or changing its kind, endpoint, auth, hooks, timeout or `on_error` needs a deploy, and deploy review is the bar wanted for those changes. A rolling deploy still leaves replicas on different catalogs for its duration, so each replica exports the hash of the catalog it loaded (`guardian_module_catalog_info{hash}` and in `/dashboard/info`) and logs each instance's module build (`name version` from `describe`) at startup, also shown in `GET /dashboard/modules`. The catalog file itself lives in the deploy repository, where its hash finds it. +Only adding an instance, removing one, or changing its kind, endpoint, auth, hooks, timeout or `on_error` needs a deploy, and deploy review is the bar wanted for those changes. A rolling deploy still leaves replicas on different catalogs for its duration, so each replica exports the hash of the catalog it loaded (`guardian_module_catalog_info{catalog_hash}` and in `/dashboard/info`) and logs each instance's module build (`name version` from `describe`) at startup, also shown in `GET /dashboard/modules`. The catalog file itself lives in the deploy repository, where its hash finds it. **Evaluation trace.** Every delta the Guardian signs after modules ran records which configuration approved it, shown in the dashboard delta detail and not exposed through the client API: @@ -336,9 +336,9 @@ Only adding an instance, removing one, or changing its kind, endpoint, auth, hoo |---|---| | `catalog_hash` | SHA-256 of the catalog file the approving replica loaded | | `params_version` | The params version the evaluation read; the history replayed to it gives every global param, layer, assignment and enabled flag | -| `failed_open` | Each evaluation that failed and was let through by `on_error = allow`: module, layer and failure kind (`timeout`, `error`, `invalid_decision`, `request_unavailable`); omitted when empty, the detail goes to the log | +| `failed_open` | Each evaluation that failed and was let through by `on_error = allow`: module, layer and failure kind (`timeout`, `error`, `invalid_decision`, `request_unavailable`, `circuit_open`); omitted when empty, the detail goes to the log | -Allowed evaluations are not listed: the catalog, the params version and the account determine which modules ran. Denials create no delta. Each is logged with `request_id`, account, hook, module, layer, `reason_code`, the module's `message`, the catalog hash and the params version, so "why was this account refused" is answered from the logs; M2a has no API for denials, and a durable decision log is future work (section 7). A durable record of module builds per configuration, a hash of the request and the inputs not stored elsewhere (accounting time, proposer) are added with the replay tool that would consume them. +Allowed evaluations are not listed: the catalog, the params version and the account determine which modules ran. Proposal creation and registration sign no delta, so a failure let through there is written to the audit log instead, as a `modules.failed_open` event with the hook, submitter, catalog hash, params version, the failures and, for a proposal, its id. Denials create no delta. Each is logged with `request_id`, account, hook, module, layer, `reason_code`, the module's `message`, the catalog hash and the params version, so "why was this account refused" is answered from the logs; M2a has no API for denials, and a durable decision log is future work (section 7). A durable record of module builds per configuration, a hash of the request and the inputs not stored elsewhere (accounting time, proposer) are added with the replay tool that would consume them. **Order:** `scope = all` modules in catalog order, each with its global layer first and the account's layer, if any, right after it; then the account's stored assignment in its stored order. Copied `default` modules are stored first, in catalog order, and the operator may reorder them afterwards. Evaluation stops at the first deny. `all` modules always run before the account's own modules, so when an `all` module denies, `meta.module` names it and any account-level module that would also have denied is never called. Operators debugging per-account policy should check the `all` modules first. @@ -428,11 +428,11 @@ There are two ways to use a module someone else wrote, for example a crate publi ```rust #[tokio::main] async fn main() -> anyhow::Result<()> { - guardian_module_sdk::serve(acme_sanctions::AcmeSanctions::from_env()?) - .grpc("0.0.0.0:7443") + guardian_module_sdk::serve::serve(acme_sanctions::AcmeSanctions::from_env()?) .instance("sanctions-ofac", std::fs::read_to_string("/run/secrets/module_token")?.trim()) - .run() - .await + .run("0.0.0.0:7443".parse()?) + .await?; + Ok(()) } ``` @@ -600,7 +600,7 @@ message HookRequest { Hook hook = 2; bool dry_run = 3; // a policy check: nothing is stored or signed whatever the decision (section 2.7) string network = 4; // network family: "miden" - string network_id = 5; // the account's network within the family: "mainnet", "testnet", "devnet", "cedar" or "local" (section 3.1) + string network_id = 5; // the network this Guardian serves within the family: "mainnet", "testnet", "devnet", "cedar" or "local"; from its own configuration, never from the request (section 3.1) string account_id = 6; string instance_id = 7; // catalog id of the instance being called bytes params = 8; // UTF-8 JSON, params of the layer being evaluated (global, account layer, or the account's own for default/assigned) @@ -651,21 +651,20 @@ enum PendingState { } message RegistrationSubject { - AccountStateProjection initial_state = 1; // the account about to be accepted, per network + AccountStateProjection initial_state = 1; // the account about to be accepted, per network: its whole vault and storage } enum Effect { - EFFECT_UNSPECIFIED = 0; // a module that does not set `effect`: `allow` decides + EFFECT_UNSPECIFIED = 0; // never a decision: a module failure EFFECT_ALLOW = 1; EFFECT_DENY = 2; } message Decision { - bool allow = 1; // read only when effect is unspecified + Effect effect = 1; // unspecified, or a value the Guardian does not know, is a module failure string reason_code = 2; // required on a deny; ignored on an allow string message = 3; // logged, never forwarded to clients - Effect effect = 4; // wins over allow when set; a value the Guardian does not know is a module failure - string client_message = 5; // optional, plain text, at most 256 characters; forwarded only where the instance allows it (section 2.7) + string client_message = 4; // optional, plain text, at most 256 characters; forwarded only where the instance allows it (section 2.7) } // A transaction as its network describes it. One variant per network; a module reads the @@ -690,14 +689,15 @@ message RawTransaction { } message MidenTransaction { - int64 nonce_delta = 1; - uint32 reference_block = 2; // the block the transaction was executed against - optional uint32 expiration_block = 3; // absent when the transaction sets no expiration (section 3.1) + uint64 nonce_delta = 1; + uint32 bound_block = 2; // the block the summary binds; the transaction executes against this block or a later one (section 3.1) + optional uint32 expiration_delta = 3; // blocks after the block the transaction executes against at which it expires; absent when its script sets none. Not an absolute height: that block is not known at approval (section 3.1) repeated VaultChange vault_changes = 4; repeated OutputNote output_notes = 5; repeated InputNote input_notes = 6; repeated StorageChange storage_changes = 7; optional string new_code_commitment = 8; // set when the transaction replaces the account's code (section 3.1) + optional uint64 approval_expiration_block = 9; // the block at which the cosigners' approval of this transaction lapses; absent when it never lapses (section 3.1) } message MidenAccountState { @@ -721,7 +721,7 @@ message OutputNote { repeated Asset assets = 5; string script_root = 6; optional string p2id_target = 7; // set only for known P2ID / P2IDE scripts - bool tx_fee = 8; // the fee note pay_fee creates; not a payment (section 3.1: set only for that one note) + bool tx_fee = 8; // the fee note pay_fee creates; not a payment (section 3.1: set only for that one note, and only while it carries no more of the fee asset than a transaction can owe) } enum NoteType { NOTE_TYPE_UNSPECIFIED = 0; NOTE_TYPE_PUBLIC = 1; NOTE_TYPE_PRIVATE = 2; } @@ -785,9 +785,9 @@ message Gap { **Request identity.** `request_id` is unique per hook invocation and shared by every module and layer called in it, so a module's logs can be joined with the Guardian's denial log (section 2.2, "Evaluation trace"). A client retry is a new invocation with a new id. It is for correlation only: `evaluate` has no side effects (section 2.1), so there is nothing to deduplicate. -**Network.** `network` names the network family (`miden`); `network_id` names the account's network within it (`mainnet`, `testnet`, `devnet`, `cedar` or `local`), taken from the account's registered network configuration, since one Guardian can serve accounts on several Miden networks. A module must not infer the network from an address prefix: Cedar shares mainnet's bech32 prefix and a local node shares devnet's (`crates/server/src/metadata/network.rs:29-43`) **[READ]**. +**Network.** `network` names the network family (`miden`); `network_id` names the network this Guardian serves within it (`mainnet`, `testnet`, `devnet`, `cedar` or `local`), taken from the Guardian's own configuration (`GUARDIAN_NETWORK_TYPE`). It is never the `network_type` an account was registered with: that field is optional in `/configure`, defaults to `local`, and is chosen by the registrant, so a policy keyed on it could be steered by the account it judges. A module must not infer the network from an address prefix: Cedar shares mainnet's bech32 prefix and a local node shares devnet's (`crates/server/src/metadata/network.rs:29-43`) **[READ]**. -**Expiration and code.** `reference_block` is the summary's block number and `expiration_block` is `reference_block + expiration_delta`; a transaction without an expiration has an expiration delta of 0, and `expiration_block` is then absent rather than equal to the reference block, so a module can tell "never expires" from "expires now" and compute the validity window. `new_code_commitment` is set when the transaction's account delta carries a code patch, which the Guardian applies like any other change today (`merge_account_deltas`, `crates/server/src/network/miden/mod.rs:873`) **[READ]**; a module that pins account code denies on it (section 3.2). +**Blocks, expiration and code.** `bound_block` is the block the summary binds; the transaction executes against that block or a later one, which is not known when the Guardian approves. `expiration_delta` is the delta the transaction's script sets, counted from the block it executes against, so it is not an absolute height and is absent when the script sets none. `approval_expiration_block` is the absolute block at which the cosigners' approval of this summary lapses (the summary's first user parameter), absent when the approval never lapses: it is the bound a module uses for "this approval is valid until". `new_code_commitment` is set when the transaction's account delta carries a code patch, which the Guardian applies like any other change today (`merge_account_deltas`, `crates/server/src/network/miden/mod.rs:873`) **[READ]**; a module that pins account code denies on it (section 3.2). **Registration cost.** `RegistrationSubject.initial_state` is built from the account `configure_account` already decodes to read its state head (`get_state_head`, `crates/server/src/services/configure_account.rs:184`) **[READ]**. Building the vault and storage projection from it is new work on the registration path, and the implementation should build it only when a module that declares `before_account_registered` will be called. @@ -797,7 +797,7 @@ message Gap { `p2id_target` is set only when the note script root is a known P2ID or P2IDE script. Recipient-based policies are enforceable because `TransactionSummary.output_notes` is a collection of `RawOutputNote::Full(Note) | Partial(PartialNote)` (`miden-protocol-0.17.1/src/transaction/tx_summary.rs:31-39`, `outputs/notes.rs:190`) **[READ]**: a full note carries recipient, assets and script even when its type is private. A partial note exposes only the recipient digest, so it is marked `partial = true` and a recipient policy must decide what to do with an unknown recipient. -**The fee is a note.** In Miden 0.17 `pay_fee` creates a public `TX_FEE` output note funded from the account's vault (`miden-standards-0.17.1/src/account/auth/singlesig.rs:45`) **[READ]**. Listed as an ordinary note, the fee looks like a payment: in the prototype a cap on the fee asset refused every transaction, consuming notes included, and a recipient allowlist would refuse every transaction too, since the fee note has no P2ID recipient. The Guardian therefore marks it with `OutputNote.tx_fee`, and policies treat it as the fee, not a payment. The script alone does not identify the fee: `TX_FEE` is a standard script that any transaction script can use (`tx_fee::create_output_note` is public), with any assets, and anyone can consume the note, so a note marked by its script would move funds past every recipient, asset and amount rule. `tx_fee` is set only for the note `pay_fee` creates, recognized by everything `pay_fee` fixes: it is the transaction's only `TX_FEE` note, its serial number is `TxFeeNote::derive_serial_number(account, nonce before the transaction, block the summary binds)`, and it carries one fungible asset of the chain's fee faucet, which the Guardian reads once from the node's protocol configuration. Any other `TX_FEE` note, and every `TX_FEE` note when the transaction has more than one or the fee faucet is not known yet, is an ordinary output note. A zero fee creates no fee note. +**The fee is a note.** In Miden 0.17 `pay_fee` creates a public `TX_FEE` output note funded from the account's vault (`miden-standards-0.17.1/src/account/auth/singlesig.rs:45`) **[READ]**. Listed as an ordinary note, the fee looks like a payment: in the prototype a cap on the fee asset refused every transaction, consuming notes included, and a recipient allowlist would refuse every transaction too, since the fee note has no P2ID recipient. The Guardian therefore marks it with `OutputNote.tx_fee`, and policies treat it as the fee, not a payment. The script alone does not identify the fee: `TX_FEE` is a standard script that any transaction script can use (`tx_fee::create_output_note` is public), with any assets, and anyone can consume the note, so a note marked by its script would move funds past every recipient, asset and amount rule. `tx_fee` is set only for the note `pay_fee` creates, recognized by everything `pay_fee` fixes: it is the transaction's only `TX_FEE` note, its serial number is `TxFeeNote::derive_serial_number(account, nonce before the transaction, block the summary binds)`, and it carries one fungible asset of the chain's fee faucet, no more of it than a transaction can owe. The Guardian reads the fee faucet and the verification base fee from the node's latest block header and its protocol configuration, and reads them again once that read is a minute old. The fee is the base fee times `ilog2(cycles) + 1`, which stays below 32 for any cycle count the kernel accepts, so the bound is 64 times the base fee: a note over it is a payment. On a chain whose base fee is zero `pay_fee` creates no note, so no note is marked there; otherwise a transaction script could create the one `TX_FEE` note itself, with the derivable serial number and any amount. Any other `TX_FEE` note, and every `TX_FEE` note when the transaction has more than one, is an ordinary output note. While the fee asset has never been read, a transaction that carries a `TX_FEE`-script note cannot be projected, so each instance's `on_error` applies (`GUARDIAN_MODULE_UNAVAILABLE` for a fail-closed one) instead of the note being judged as a payment and denied for good. #### `basic-policy` rules @@ -963,7 +963,6 @@ Remote modules are run by other teams and vendors and upgrade on their own sched | Capability | Meaning | |---|---| -| `decision.effect` | The Guardian reads `Decision.effect` | | `params.normalization` | The Guardian stores `ParamsVerdict.normalized_params` | | `notify` | The Guardian builds `pending` and delivers `Notify` and `NotifyGap` (M2b, section 3.4) | @@ -971,7 +970,7 @@ A stateful module requires `notify`, and a module that requires it is also refus **Supported range.** A Guardian accepts its current protocol version and, once a newer major exists, the previous one for a deprecation window of one Guardian release. For a module on the previous version it builds that version's request shape, logs a warning at startup and exports `guardian_module_protocol_deprecated{module}`, so operators see which modules to upgrade before the window closes. Two or more versions behind, or ahead of the Guardian, is refused. Version 1 is the only version until M2a freezes it, so the range is a single version for now. -**Decisions.** `Decision.effect` makes the outcome explicit, so later effects (for example a request for additional approval, section 7) can be added without a new protocol version. A module that predates the field leaves it unspecified and `allow` decides. An effect the Guardian does not recognise is a module failure, so `on_error` applies: a newer module cannot loosen policy on an older Guardian by returning something the Guardian does not understand. +**Decisions.** `Decision.effect` makes the outcome explicit, so later effects (for example a request for additional approval, section 7) can be added without a new protocol version. A decision that sets no effect, or one the Guardian does not recognise, is a module failure, so `on_error` applies: a newer module cannot loosen policy on an older Guardian by returning something the Guardian does not understand. **Parameter migration.** Params belong to the module, which changes their shape between its own releases. `ValidateParams` may return `normalized_params`: the params in the module's current shape. The Guardian stores what the module returns. At startup and before enabling an instance, when the module normalizes the stored global params, the Guardian writes them with a history entry by `module: ` and reason "params migrated by the module", so an upgrade is a recorded data change instead of a startup failure. Operator writes store the normalized form too, and the response shows what was stored. Account layers and assignments are migrated when they are next written; until then the module receives them in the shape they were stored in, so a module must keep accepting the shapes of its previous release. Normalized params are subject to the same rules as the input: a JSON object, and no secret references through the operator API. @@ -1021,9 +1020,9 @@ Modules run in sequence, so their timeouts add up, while the execution worker ho Without a breaker, a module that is down costs its full `timeout_ms` on every request until an operator acts, for fail-closed and fail-open instances alike. Each replica therefore keeps a breaker per instance: -- **Closed** (normal): calls go through. `GUARDIAN_MODULE_BREAKER_FAILURES` consecutive failures (default 5) open it. Timeouts, transport errors and malformed decisions count as failures; a deny is an answer, not a failure, and resets the count. +- **Closed** (normal): calls go through. `GUARDIAN_MODULE_BREAKER_FAILURES` consecutive failures (default 5) open it. Timeouts, transport errors and malformed decisions count as failures; a deny is an answer, not a failure, and resets the count. So does a request the module rejects as one it cannot judge (`ModuleError::InvalidRequest`, gRPC `INVALID_ARGUMENT`): the instance's `on_error` applies to that request, but it says nothing about whether the module is up, so one account's unjudgeable requests cannot stop the module for every account. A timeout does not count when earlier modules in the same invocation left the call less than its `timeout_ms`, and nothing a dry-run check does counts or resets anything, since a cosigner sends it without anyone's signature. - **Open**: `evaluate` is not called; the module is treated as failed for every account and its `on_error` applies at once, so a fail-closed module refuses with `GUARDIAN_MODULE_UNAVAILABLE` without waiting and a fail-open module is skipped. -- **Half-open**: a successful health probe moves an open breaker here. The next real evaluation is sent; success closes the breaker, failure opens it again. +- **Half-open**: a successful health probe moves an open breaker here. One real evaluation at a time is sent as the trial, and requests arriving meanwhile, and every dry-run check, are treated as while open; an answer closes the breaker, a failure opens it again, and a trial that never reports back (its request was dropped) is replaced at the next successful probe. The health probe is a `Describe` call every `GUARDIAN_MODULE_PROBE_INTERVAL_MS` (default 5000) for every enabled instance, open breaker or not, under the instance's `timeout_ms`. It sets `guardian_module_up{module}`, so an outage raises an alarm before traffic finds it, and it also detects a module whose `protocol_version` changed under a running Guardian (treated as a failure). A module receives about one `Describe` per instance per replica every interval, so it answers `Describe` from memory, without calling a vendor or a database. Breaker state is per replica and in memory: replicas converge independently within a few requests, and nothing about it is stored. Until they do, a fail-open instance can be skipped on one replica and called on another; `failed_open` in the evaluation trace records each skip (section 2.2). `guardian_module_circuit_open{module}` is exported, and `GET /dashboard/modules` shows the answering replica's state. Notify delivery is unaffected; it has its own retry with backoff (section 3.3). In-process kinds go through the same breaker, so a kind that calls a vendor API behaves like a remote one. @@ -1093,7 +1092,7 @@ The first enclave step allows in-process kinds only; the attested tier follows o **Freeze criteria.** Version 1 freezes only once the prototype implements, with tests, the protocol surface added in revision 24 that is so far derived from reading code: the renumbered proto, registration before the claim (new account, unfinished claim, lost claim), `network_id`, `code_commitment` and `procedure_roots` with effective-override filtering (non-zero, exported, not the auth procedure), `reference_block` and the optional `expiration_block`, `new_code_commitment`, `submitter_session`, `dry_run` with approval instances in the check, and the `allowed_code_commitments` rule with `code_check`. Extraction details are where the prototype found errors before (the fee note, single-key views), so these are measured against real accounts, not only fixtures. -**Frozen.** The freeze criteria were met on 2026-11-09 at `e4efd839` on the M2a branch `251-modules-m2a`: every field and behaviour listed above is implemented with tests, except `proposer_session`, removed in revision 27 (section 3.2). From then on `guardian.module.v1` changes only additively (section 3.5). +**Not frozen yet.** The freeze criteria were met on 2026-11-09 at `e4efd839` on the M2a branch `251-modules-m2a` and revision 28 declared version 1 frozen. A review of the implementation the next day found fields that did not carry what they said (`network_id`, `reference_block`, `expiration_block`), one that was never sent (`RegistrationSubject.initial_state`) and a legacy `Decision.allow` in a protocol with no predecessor, so revision 32 reopened it: nothing had been published or deployed, which is the only point at which a freeze costs anything to undo. Version 1 freezes with the first published `guardian-module-sdk` release; from then on `guardian.module.v1` changes only additively (section 3.5). The messages no M2a code produces or consumes (`Notify`, `NotifyGap`, `CommitEvent`, `Gap`, `PendingTransaction`) stay in the proto as the M2b design and may still change until M2b implements them. **M2a: stateless gates.** @@ -1206,6 +1205,7 @@ None. Questions resolved in earlier revisions are kept below with their answers. | Revision | Date | Changes | |---|---|---| +| 32 | 2026-11-10 | review of the M2a implementation. Protocol version 1 reopened (section 7): `Decision.allow` and the `decision.effect` capability removed, a decision without an effect is a module failure (section 3.5); `MidenTransaction.reference_block` and `expiration_block` replaced by `bound_block`, `expiration_delta` and `approval_expiration_block`, and `nonce_delta` made unsigned (section 3.1); `network_id` is the Guardian's configured network, not the account's registered one (section 3.1); `RegistrationSubject.initial_state` is sent; `tx_fee` is set only while the fee note carries no more of the fee asset than a transaction can owe, 64 times the chain's verification base fee, and for no note on a chain that charges nothing (section 3.1). Breaker: requests a module rejects do not count, a module whose timeout is the whole budget can open it, half-open sends one trial at a time, dry-run checks neither probe nor close it (section 4.4). Fail-open skips at proposal creation and registration, where no delta is signed, are recorded as `modules.failed_open` audit events; operator writes are audited with the params version they committed as (section 2.2). Body corrected to the implementation: metric names, the fixed 1000 ms timeout cap, params encoding, the `circuit_open` failure kind | | 31 | 2026-11-09 | failures of dry-run checks do not count toward the circuit breaker, since a cosigner sends them without anyone's signature (section 4.4); the per-account budget check refuses only writes that raise an over-budget cost (section 4.3); `GUARDIAN_MODULE_UNAVAILABLE` and `GUARDIAN_EXECUTION_MODULE_UNAVAILABLE` omit `module` for an instance whose denials are generic (section 4.1); `metadata.modules` is kept out of client delta responses (section 2.2). `OutputNote.tx_fee` set only for the fee note `pay_fee` creates (section 3.1): the only `TX_FEE` note, with the derived serial number and one asset of the chain's fee faucet. Revisions 20 to 30 set it for any note with the `TX_FEE` script, which a transaction script can create with any assets, so the flag let funds past every `basic-policy` rule. No wire change; the field's meaning is narrowed | | 30 | 2026-11-09 | the secrets backend named: `GUARDIAN_MODULE_SECRET_PROVIDER` selects AWS Secrets Manager (the prod default) or owner-only files below `GUARDIAN_MODULE_SECRET_DIR`, read once when the instances are created; a secret that cannot be read fails creation, with the enabled/disabled rule of section 2.2. Field names fixed as `auth.token_secret`, `tls.client_cert_secret` and `tls.client_key_secret`; a secret name is 1 to 512 characters of letters, digits and `/_+=.@-`, and a `$secret` object has no other key (section 2.2). In-process factories read `$secret` values from `ModuleInstanceConfig::secret`. No protocol change | | 29 | 2026-11-09 | M2a implementation of `scope = default`: the copy is written right after the claim, only into an account with no assignment and no assignment history, under the module state lock, instead of in the claim's transaction on Postgres and before the claim on the filesystem; a crash in between is repaired by the unfinished-claim retry, so both backends follow one rule and no transaction spans the metadata and module stores (section 2.3). No protocol change | diff --git a/docs/runbooks/policy-modules.md b/docs/runbooks/policy-modules.md index b5c17daa..ef357bb1 100644 --- a/docs/runbooks/policy-modules.md +++ b/docs/runbooks/policy-modules.md @@ -28,7 +28,8 @@ For every instance in the catalog, know which path stops it: any transaction, not only during an outage: a transaction whose request the Guardian cannot build or send (an account view it cannot read, a request over `GUARDIAN_MODULE_REQUEST_MAX_BYTES`) is a module failure too, and a fail-open - instance is then skipped for it (recorded in `metadata.modules.failed_open`). + instance is then skipped for it (recorded in the delta's `modules.failed_open`, + read from `GET /dashboard/accounts/{account_id}/deltas/{nonce}`). - Give the on-call operator `modules:disable`. It allows disabling instances marked `operator_can_disable` and nothing else, so it is safe to hand out more widely than `policies:write` ([permissions](../DASHBOARD.md#permission-vocabulary)). @@ -71,8 +72,9 @@ module is skipped without waiting for its timeout. ``` Requests stop calling it on every replica at once. Deltas signed meanwhile - name the catalog and params version they were approved under in - `metadata.modules`, so the gap is auditable. + name the catalog and params version they were approved under in the + `modules` field of `GET /dashboard/accounts/{account_id}/deltas/{nonce}`, so + the gap is auditable. 3. When the module is healthy again, enable it. Enabling runs `Describe` and `ValidateParams` first and returns `503 GUARDIAN_MODULE_UNAVAILABLE` without changing anything if they fail: @@ -160,8 +162,10 @@ it after enabling. - Re-enable what was disabled, with a reason that references the incident. - Check `guardian_module_fail_open_total` for the window: deltas signed while - a fail-open module was failing carry `metadata.modules.failed_open` naming - it. + a fail-open module was failing carry `modules.failed_open` naming it on the + dashboard delta detail. Proposals created and accounts registered past a + failing fail-open module are in the audit log as `modules.failed_open` + events. - If the outage showed that an instance should not stop approvals, change its `on_error` or `operator_can_disable` in the catalog now, not during the next one. diff --git a/speckit/features/251-guardian-modules/contracts/catalog-config.md b/speckit/features/251-guardian-modules/contracts/catalog-config.md index f611df63..f242d4ae 100644 --- a/speckit/features/251-guardian-modules/contracts/catalog-config.md +++ b/speckit/features/251-guardian-modules/contracts/catalog-config.md @@ -8,7 +8,6 @@ |---|---|---|---| | `GUARDIAN_MODULES_CONFIG` | unset | M2a | Path to the catalog TOML; unset disables the feature | | `GUARDIAN_MODULES_STATE` | `/modules` | M2a | Filesystem backend only: directory of the module state file; Postgres keeps module state in its tables | -| `GUARDIAN_MODULE_TIMEOUT_MAX_MS` | `1000` | M2a | Upper bound for any instance `timeout_ms` | | `GUARDIAN_MODULE_PARAMS_MAX_BYTES` | `65536` | M2a | Largest params value (JCS-encoded) accepted at startup or through the operator API | | `GUARDIAN_MODULE_CHECK_RATE_PER_MIN` | `30` | M2a | Dry-run checks per minute per account and signer (RFC 0002 section 2.7) | | `GUARDIAN_MODULE_EVALUATION_BUDGET_MS` | `1000` | M2a | Total module time per hook invocation | @@ -79,7 +78,7 @@ A secret that cannot be read fails the instance's creation: startup stops for an ## `basic-policy` params (M2a) -Every id is written in `0x` hex form (case-insensitive); `validate_params` refuses any other form, such as a bech32 address, which would never match a request. +Every id is written in `0x` hex form (case-insensitive); `validate_params` refuses any other form, such as a bech32 address or a placeholder that is not hex digits, which would never match a request. A modifier without the list it modifies (`deny_unknown_recipients`, `signer_check`, `code_check`) and a cap naming one faucet twice are refused too. | Param | Type | Effect | |---|---|---| diff --git a/speckit/features/251-guardian-modules/contracts/operator-modules-api.md b/speckit/features/251-guardian-modules/contracts/operator-modules-api.md index 87317b68..3ed9af3e 100644 --- a/speckit/features/251-guardian-modules/contracts/operator-modules-api.md +++ b/speckit/features/251-guardian-modules/contracts/operator-modules-api.md @@ -90,4 +90,4 @@ Contract tests in `crates/server` and `packages/guardian-operator-client` pin ev ## Implementation status (M2a) -All M2a routes exist with the shapes above. `PUT` writes are refused when the account's worst case could exceed the evaluation budget. Not built yet: `resync` (M2b), the operator client methods and the OpenAPI entries for these routes (tasks T044, T045). +All M2a routes exist with the shapes above. `PUT` writes are refused when the account's worst case could exceed the evaluation budget. The operator client methods and the OpenAPI entries exist (tasks T044, T045). Not built yet: `resync` (M2b). diff --git a/speckit/features/251-guardian-modules/data-model.md b/speckit/features/251-guardian-modules/data-model.md index fe4c7a0a..06fb2b28 100644 --- a/speckit/features/251-guardian-modules/data-model.md +++ b/speckit/features/251-guardian-modules/data-model.md @@ -17,7 +17,7 @@ One `[[module]]` entry of the catalog file ([contracts/catalog-config.md](./cont | `endpoint` | Remote kinds only: `grpc://` (TLS) or `grpc+insecure://` (plain text, loopback hosts only, never in prod) | | `scope` | `all`, `default` or `assigned` | | `hooks` | Non-empty subset of the gate and notify hooks; each must be in the module's `describe` | -| `timeout_ms` | Required, 1 to `GUARDIAN_MODULE_TIMEOUT_MAX_MS` | +| `timeout_ms` | Required, 1 to 1000 | | `on_error` | `deny` (default) or `allow` | | `auth` | Remote kinds; mandatory in prod; secret reference for the bearer token, optional mTLS | | `params` | Seed for the instance's global params, written to the metadata store the first time the id is seen; JSON object; `$secret` references only for in-process kinds (such an instance's global params stay file-managed); validated by `validate_params` | @@ -73,7 +73,7 @@ One row holding the params version. Every write takes its lock first, increments ### Delta additions (both backends) -The approval record is `metadata.modules` on the signed delta (`ModuleApproval`), stored with the delta's metadata (JSONB on Postgres, JSON on the filesystem), so it needs no migration. Like the rest of `metadata` it is served on the HTTP delta and dashboard routes, not over gRPC. Written only when a module ran for the delta. +The approval record is `metadata.modules` on the signed delta (`ModuleApproval`), stored with the delta's metadata (JSONB on Postgres, JSON on the filesystem), so it needs no migration. Operators read it as `modules` on the dashboard delta detail (`GET /dashboard/accounts/{account_id}/deltas/{nonce}`); it is stripped from every client delta response and is not carried over gRPC. Written only when a module ran for the delta. | Field | Set when | Notes | |---|---|---| From a7df03d5c6896942238726ff969157cbf9458a01 Mon Sep 17 00:00:00 2001 From: Zeljko Date: Tue, 10 Nov 2026 08:14:27 +0100 Subject: [PATCH 081/105] feat(module-sdk): id lengths in basic-policy and stated outcomes in the conformance suite (#251) - basic-policy: a faucet or recipient is an account id of 30 hex digits and a signer or code commitment is 64, so an id cut short when pasted, or an account id where a commitment belongs, is refused when the params are validated instead of never matching. - Conformance: a request can state what it must be answered with (allows, denies, denies_with a reason code, fails), and a suite needs at least one request the module must deny. A module that allows everything answered consistently and conformed. - Test ids in the SDK and in the server tests that feed basic-policy are real lengths. --- crates/guardian-module-sdk/README.md | 8 +- .../guardian-module-sdk/src/basic_policy.rs | 236 ++++++++++++++---- crates/guardian-module-sdk/src/conformance.rs | 170 ++++++++++++- .../guardian-module-sdk/tests/conformance.rs | 88 ++++--- crates/server/src/api/dashboard_modules.rs | 10 +- crates/server/src/modules/catalog.rs | 4 +- .../src/services/execute_proposal/tests.rs | 2 +- crates/server/src/services/push_delta.rs | 2 +- 8 files changed, 412 insertions(+), 108 deletions(-) diff --git a/crates/guardian-module-sdk/README.md b/crates/guardian-module-sdk/README.md index 834faeba..c3830b50 100644 --- a/crates/guardian-module-sdk/README.md +++ b/crates/guardian-module-sdk/README.md @@ -132,8 +132,8 @@ use guardian_module_sdk::conformance::Suite; #[tokio::test] async fn conforms() { Suite::new(NoPrivateNotes) - .request("public payment", public_payment()) - .request("private payment", private_payment()) + .allows("public payment", public_payment()) + .denies("private payment", private_payment()) .valid_params(serde_json::json!({})) .invalid_params(serde_json::json!({ "x": 1 })) .run() @@ -145,7 +145,9 @@ async fn conforms() { The suite serves the module over loopback gRPC with two instances, and checks `Describe`, params validation on both transports, identical answers in process and over gRPC, repeated, reordered and concurrent evaluations, the shape of -every decision, per-instance tokens and a request at the size cap. +every decision, the outcome each request is stated to have (`allows`, `denies`, +`denies_with`, `fails`), per-instance tokens and a request at the size cap. It +needs at least one request the module must deny. ## Further reading diff --git a/crates/guardian-module-sdk/src/basic_policy.rs b/crates/guardian-module-sdk/src/basic_policy.rs index 9008370a..95687237 100644 --- a/crates/guardian-module-sdk/src/basic_policy.rs +++ b/crates/guardian-module-sdk/src/basic_policy.rs @@ -86,21 +86,53 @@ fn normalized(values: &[String]) -> BTreeSet { values.iter().map(|v| v.to_ascii_lowercase()).collect() } -/// Ids in the hex form the Guardian reports them in (`0x` and hex digits), lowercased. Any other -/// spelling, a bech32 address or a placeholder left in an example catalog for one, would never -/// match a request, so a denylist or a cap would silently not apply; it is refused instead. -fn ids(field: &str, values: &[String]) -> Result, String> { - values.iter().map(|value| id(field, value)).collect() +/// What an id names, which fixes its length in the hex form the Guardian reports it in. +#[derive(Clone, Copy)] +enum IdKind { + /// A faucet or a recipient: an account id. + Account, + /// A signer commitment or a code commitment: a word. + Commitment, } -fn id(field: &str, value: &str) -> Result { - match value +impl IdKind { + fn hex_digits(self) -> usize { + match self { + IdKind::Account => 30, + IdKind::Commitment => 64, + } + } + + fn noun(self) -> &'static str { + match self { + IdKind::Account => "an account id", + IdKind::Commitment => "a commitment", + } + } +} + +/// Ids in the hex form the Guardian reports them in (`0x` and the hex digits of an account id or +/// a commitment), lowercased. Any other spelling would never match a request, so a denylist or a +/// cap would silently not apply; it is refused instead: a bech32 address, a placeholder left in +/// an example catalog, an id cut short when it was pasted, or an account id where a commitment +/// belongs. +fn ids(field: &str, kind: IdKind, values: &[String]) -> Result, String> { + values.iter().map(|value| id(field, kind, value)).collect() +} + +fn id(field: &str, kind: IdKind, value: &str) -> Result { + let digits = value .strip_prefix("0x") .or_else(|| value.strip_prefix("0X")) - { - Some(rest) if !rest.is_empty() && rest.bytes().all(|b| b.is_ascii_hexdigit()) => { - Ok(value.to_ascii_lowercase()) - } + .filter(|rest| rest.bytes().all(|b| b.is_ascii_hexdigit())); + match digits { + Some(rest) if rest.len() == kind.hex_digits() => Ok(value.to_ascii_lowercase()), + Some(rest) if !rest.is_empty() => Err(format!( + "{field}: {value:?} has {} hex digits, but {} has {}", + rest.len(), + kind.noun(), + kind.hex_digits() + )), _ => Err(format!( "{field}: {value:?} is not an id in 0x hex form (a bech32 address is not accepted)" )), @@ -113,7 +145,7 @@ impl TryFrom for Policy { fn try_from(params: Params) -> Result { let mut caps = BTreeMap::new(); for (faucet, amount) in params.max_amount_per_tx { - let faucet = id("max_amount_per_tx", &faucet)?; + let faucet = id("max_amount_per_tx", IdKind::Account, &faucet)?; let amount = amount .parse::() .map_err(|_| format!("max_amount_per_tx for {faucet} is not a decimal amount"))?; @@ -144,8 +176,16 @@ impl TryFrom for Policy { (Some(_), Some(_)) => { return Err("signer_allowlist and signer_denylist are mutually exclusive".into()); } - (Some(list), None) => Some(SignerList::Allow(ids("signer_allowlist", &list)?)), - (None, Some(list)) => Some(SignerList::Deny(ids("signer_denylist", &list)?)), + (Some(list), None) => Some(SignerList::Allow(ids( + "signer_allowlist", + IdKind::Commitment, + &list, + )?)), + (None, Some(list)) => Some(SignerList::Deny(ids( + "signer_denylist", + IdKind::Commitment, + &list, + )?)), (None, None) => None, }; Ok(Self { @@ -153,17 +193,17 @@ impl TryFrom for Policy { assets: params .asset_allowlist .as_deref() - .map(|list| ids("asset_allowlist", list)) + .map(|list| ids("asset_allowlist", IdKind::Account, list)) .transpose()?, recipients: params .recipient_allowlist .as_deref() - .map(|list| ids("recipient_allowlist", list)) + .map(|list| ids("recipient_allowlist", IdKind::Account, list)) .transpose()?, blocked_recipients: params .recipient_denylist .as_deref() - .map(|list| ids("recipient_denylist", list)) + .map(|list| ids("recipient_denylist", IdKind::Account, list)) .transpose()?, deny_unknown_recipients: params.deny_unknown_recipients, signers, @@ -171,7 +211,7 @@ impl TryFrom for Policy { code: params .allowed_code_commitments .as_deref() - .map(|list| ids("allowed_code_commitments", list)) + .map(|list| ids("allowed_code_commitments", IdKind::Commitment, list)) .transpose()?, code_check: params.code_check.unwrap_or_default(), }) @@ -417,8 +457,8 @@ mod tests { VaultChange, }; - const USDC: &str = "0xaa00"; - const ETH: &str = "0xbb00"; + const USDC: &str = "0x00000000000000000000000000aa00"; + const ETH: &str = "0x00000000000000000000000000bb00"; fn fungible(faucet: &str, amount: u64) -> Asset { Asset { @@ -446,8 +486,12 @@ mod tests { fn tx_request(params: serde_json::Value, projection: MidenTransaction) -> HookRequest { HookRequest { params: serde_json::to_vec(¶ms).unwrap(), - before: Some(view(&["0x51"])), - after: Some(view(&["0x51"])), + before: Some(view(&[ + "0x0000000000000000000000000000000000000000000000000000000000000051", + ])), + after: Some(view(&[ + "0x0000000000000000000000000000000000000000000000000000000000000051", + ])), subject: Some(hook_request::Subject::Transaction(TransactionSubject { projection: Some(TransactionProjection::miden(projection)), ..Default::default() @@ -467,7 +511,10 @@ mod tests { #[tokio::test] async fn allows_a_payment_under_the_cap() { let projection = MidenTransaction { - output_notes: vec![p2id("0xa1", vec![fungible(USDC, 500)])], + output_notes: vec![p2id( + "0x0000000000000000000000000000a1", + vec![fungible(USDC, 500)], + )], ..Default::default() }; assert!(decide(&tx_request(cap(), projection)).await.allows()); @@ -477,8 +524,14 @@ mod tests { async fn sums_split_payments_against_the_cap() { let projection = MidenTransaction { output_notes: vec![ - p2id("0xa1", vec![fungible(USDC, 600)]), - p2id("0xa2", vec![fungible(USDC, 600)]), + p2id( + "0x0000000000000000000000000000a1", + vec![fungible(USDC, 600)], + ), + p2id( + "0x0000000000000000000000000000a2", + vec![fungible(USDC, 600)], + ), ], ..Default::default() }; @@ -498,7 +551,10 @@ mod tests { note_id: "0x14".into(), assets: vec![fungible(USDC, 1000)], }], - output_notes: vec![p2id("0xa1", vec![fungible(USDC, 1500)])], + output_notes: vec![p2id( + "0x0000000000000000000000000000a1", + vec![fungible(USDC, 1500)], + )], ..Default::default() }; assert!(!decide(&tx_request(cap(), projection)).await.allows()); @@ -511,7 +567,10 @@ mod tests { value: Some(asset::Value::NftId("0x4f7".into())), }; let projection = MidenTransaction { - output_notes: vec![p2id("0xa1", vec![fungible(ETH, 5000), nft])], + output_notes: vec![p2id( + "0x0000000000000000000000000000a1", + vec![fungible(ETH, 5000), nft], + )], ..Default::default() }; assert!(decide(&tx_request(cap(), projection)).await.allows()); @@ -529,7 +588,13 @@ mod tests { #[tokio::test] async fn the_fee_note_is_not_a_payment() { let projection = MidenTransaction { - output_notes: vec![fee_note(5000), p2id("0xa1", vec![fungible(USDC, 500)])], + output_notes: vec![ + fee_note(5000), + p2id( + "0x0000000000000000000000000000a1", + vec![fungible(USDC, 500)], + ), + ], ..Default::default() }; assert!( @@ -538,7 +603,7 @@ mod tests { .allows() ); - let params = json!({ "recipient_allowlist": ["0xa1"], "asset_allowlist": [ETH, USDC] }); + let params = json!({ "recipient_allowlist": ["0x0000000000000000000000000000a1"], "asset_allowlist": [ETH, USDC] }); assert!(decide(&tx_request(params, projection)).await.allows()); let only_fee = MidenTransaction { @@ -554,14 +619,17 @@ mod tests { #[tokio::test] async fn recipient_allowlist_denies_partial_and_unlisted_notes() { - let params = json!({ "recipient_allowlist": ["0xa1"] }); + let params = json!({ "recipient_allowlist": ["0x0000000000000000000000000000a1"] }); let listed = MidenTransaction { - output_notes: vec![p2id("0xA1", vec![fungible(USDC, 1)])], + output_notes: vec![p2id( + "0x0000000000000000000000000000A1", + vec![fungible(USDC, 1)], + )], ..Default::default() }; assert!(decide(&tx_request(params.clone(), listed)).await.allows()); - let mut partial_note = p2id("0xa1", vec![fungible(USDC, 1)]); + let mut partial_note = p2id("0x0000000000000000000000000000a1", vec![fungible(USDC, 1)]); partial_note.partial = true; let partial = MidenTransaction { output_notes: vec![partial_note], @@ -575,7 +643,10 @@ mod tests { ); let unlisted = MidenTransaction { - output_notes: vec![p2id("0xa9", vec![fungible(USDC, 1)])], + output_notes: vec![p2id( + "0x0000000000000000000000000000a9", + vec![fungible(USDC, 1)], + )], ..Default::default() }; assert!(!decide(&tx_request(params, unlisted)).await.allows()); @@ -585,7 +656,10 @@ mod tests { async fn asset_allowlist_covers_sent_and_received_assets() { let params = json!({ "asset_allowlist": [USDC] }); let projection = MidenTransaction { - output_notes: vec![p2id("0xa1", vec![fungible(ETH, 1)])], + output_notes: vec![p2id( + "0x0000000000000000000000000000a1", + vec![fungible(ETH, 1)], + )], ..Default::default() }; assert_eq!( @@ -596,9 +670,12 @@ mod tests { #[tokio::test] async fn recipient_denylist_blocks_listed_recipients_only() { - let params = json!({ "recipient_denylist": ["0xBAD"] }); + let params = json!({ "recipient_denylist": ["0x000000000000000000000000000BAD"] }); let blocked = MidenTransaction { - output_notes: vec![fee_note(1), p2id("0xbad", vec![fungible(USDC, 1)])], + output_notes: vec![ + fee_note(1), + p2id("0x000000000000000000000000000bad", vec![fungible(USDC, 1)]), + ], ..Default::default() }; assert_eq!( @@ -608,15 +685,18 @@ mod tests { "recipient_blocked" ); - let mut partial = p2id("0xa1", vec![fungible(USDC, 1)]); + let mut partial = p2id("0x0000000000000000000000000000a1", vec![fungible(USDC, 1)]); partial.partial = true; let unknown = MidenTransaction { - output_notes: vec![p2id("0xa1", vec![fungible(USDC, 1)]), partial], + output_notes: vec![ + p2id("0x0000000000000000000000000000a1", vec![fungible(USDC, 1)]), + partial, + ], ..Default::default() }; assert!(decide(&tx_request(params, unknown.clone())).await.allows()); - let strict = json!({ "recipient_denylist": ["0xbad"], "deny_unknown_recipients": true }); + let strict = json!({ "recipient_denylist": ["0x000000000000000000000000000bad"], "deny_unknown_recipients": true }); assert_eq!( decide(&tx_request(strict, unknown)).await.reason_code, "recipient_blocked", @@ -627,14 +707,17 @@ mod tests { #[tokio::test] async fn a_denial_names_its_rule_to_the_client_and_discloses_no_param() { let projection = MidenTransaction { - output_notes: vec![p2id("0xa1", vec![fungible(USDC, 5_000)])], + output_notes: vec![p2id( + "0x0000000000000000000000000000a1", + vec![fungible(USDC, 5_000)], + )], ..Default::default() }; let decision = decide(&tx_request(cap(), projection)).await; assert_eq!(decision.reason_code, "amount_cap_exceeded"); assert!(!decision.client_message.is_empty()); assert!(decision.client_message.len() <= 256); - for detail in ["1000", "5000", USDC, "0xa1"] { + for detail in ["1000", "5000", USDC, "0x0000000000000000000000000000a1"] { assert!( !decision.client_message.contains(detail), "{detail} leaked into {:?}", @@ -647,8 +730,8 @@ mod tests { ); } - const REVIEWED: &str = "0xc0de"; - const UNREVIEWED: &str = "0xbad"; + const REVIEWED: &str = "0x000000000000000000000000000000000000000000000000000000000000c0de"; + const UNREVIEWED: &str = "0x0000000000000000000000000000000000000000000000000000000000000bad"; fn code_rule(code_check: &str) -> serde_json::Value { json!({ "allowed_code_commitments": [REVIEWED], "code_check": code_check }) @@ -665,7 +748,9 @@ mod tests { running( HookRequest { params: serde_json::to_vec(¶ms).unwrap(), - after: Some(view(&["0x51"])), + after: Some(view(&[ + "0x0000000000000000000000000000000000000000000000000000000000000051", + ])), subject: Some(hook_request::Subject::Registration( RegistrationSubject::default(), )), @@ -772,7 +857,10 @@ mod tests { #[tokio::test] async fn forged_metadata_does_not_change_the_decision() { let projection = MidenTransaction { - output_notes: vec![p2id("0xa1", vec![fungible(USDC, 5000)])], + output_notes: vec![p2id( + "0x0000000000000000000000000000a1", + vec![fungible(USDC, 5000)], + )], ..Default::default() }; let mut request = tx_request(cap(), projection); @@ -802,31 +890,63 @@ mod tests { #[tokio::test] async fn added_mode_checks_only_new_signers() { - let params = json!({ "signer_allowlist": ["0x52"] }); - let request = signer_request(params.clone(), Some(&["0x51"]), &["0x51", "0x52"]); + let params = json!({ "signer_allowlist": ["0x0000000000000000000000000000000000000000000000000000000000000052"] }); + let request = signer_request( + params.clone(), + Some(&["0x0000000000000000000000000000000000000000000000000000000000000051"]), + &[ + "0x0000000000000000000000000000000000000000000000000000000000000051", + "0x0000000000000000000000000000000000000000000000000000000000000052", + ], + ); assert!(decide(&request).await.allows()); - let request = signer_request(params, Some(&["0x51"]), &["0x51", "0x53"]); + let request = signer_request( + params, + Some(&["0x0000000000000000000000000000000000000000000000000000000000000051"]), + &[ + "0x0000000000000000000000000000000000000000000000000000000000000051", + "0x0000000000000000000000000000000000000000000000000000000000000053", + ], + ); assert_eq!(decide(&request).await.reason_code, "signer_not_allowed"); } #[tokio::test] async fn all_mode_checks_every_signer() { - let params = json!({ "signer_check": "all", "signer_allowlist": ["0x52"] }); - let request = signer_request(params, Some(&["0x51"]), &["0x51", "0x52"]); + let params = json!({ "signer_check": "all", "signer_allowlist": ["0x0000000000000000000000000000000000000000000000000000000000000052"] }); + let request = signer_request( + params, + Some(&["0x0000000000000000000000000000000000000000000000000000000000000051"]), + &[ + "0x0000000000000000000000000000000000000000000000000000000000000051", + "0x0000000000000000000000000000000000000000000000000000000000000052", + ], + ); assert!(!decide(&request).await.allows()); } #[tokio::test] async fn registration_checks_every_initial_signer() { - let params = json!({ "signer_denylist": ["0xbad"] }); - let request = signer_request(params, None, &["0x51", "0xBAD"]); + let params = json!({ "signer_denylist": ["0x0000000000000000000000000000000000000000000000000000000000000bad"] }); + let request = signer_request( + params, + None, + &[ + "0x0000000000000000000000000000000000000000000000000000000000000051", + "0x0000000000000000000000000000000000000000000000000000000000000BAD", + ], + ); assert!(!decide(&request).await.allows()); } #[tokio::test] async fn missing_account_view_is_an_error_not_an_allow() { - let mut request = signer_request(json!({ "signer_allowlist": ["0x51"] }), None, &[]); + let mut request = signer_request( + json!({ "signer_allowlist": ["0x0000000000000000000000000000000000000000000000000000000000000051"] }), + None, + &[], + ); request.after = None; assert!(BasicPolicy.evaluate(&request).await.is_err()); } @@ -841,7 +961,10 @@ mod tests { json!({ "max_amount_per_tx": { USDC: "ten" } }), json!({ "signer_allowlist": [], "signer_denylist": [] }), json!({ "max_amount_per_tx": { "0xREPLACE_WITH_FAUCET_ID": "5" } }), - json!({ "max_amount_per_tx": { "0xAA": "5", "0xaa": "9" } }), + json!({ "max_amount_per_tx": { "0x0000000000000000000000000000AA": "5", "0x0000000000000000000000000000aa": "9" } }), + json!({ "recipient_denylist": ["0xa1b2c3"] }), + json!({ "signer_allowlist": ["0x000000000000000000000000000051"] }), + json!({ "allowed_code_commitments": [format!("0x{}", "c".repeat(63))] }), json!({ "deny_unknown_recipients": true }), json!({ "signer_check": "all" }), json!({ "code_check": "all" }), @@ -857,7 +980,10 @@ mod tests { #[tokio::test] async fn evaluating_twice_gives_the_same_decision() { let projection = MidenTransaction { - output_notes: vec![p2id("0xa1", vec![fungible(USDC, 900)])], + output_notes: vec![p2id( + "0x0000000000000000000000000000a1", + vec![fungible(USDC, 900)], + )], ..Default::default() }; let request = tx_request(cap(), projection); diff --git a/crates/guardian-module-sdk/src/conformance.rs b/crates/guardian-module-sdk/src/conformance.rs index b04aef34..caea57a7 100644 --- a/crates/guardian-module-sdk/src/conformance.rs +++ b/crates/guardian-module-sdk/src/conformance.rs @@ -4,16 +4,22 @@ //! loopback gRPC, with two instances on one service, and checks that it answers `Describe` //! for protocol version 1, validates params the same way on both transports, returns the same //! outcome for every request on both transports, keeps `evaluate` free of side effects -//! (repeated, reordered and concurrent evaluations agree), returns well-formed decisions, and -//! accepts a request at the Guardian's size cap. +//! (repeated, reordered and concurrent evaluations agree), returns well-formed decisions, +//! answers each request as the suite says it must, and accepts a request at the Guardian's size +//! cap. +//! +//! Consistency alone is not conformance: a module that allows everything is consistent. The +//! suite therefore needs at least one request the module must deny ([`Suite::denies`] or +//! [`Suite::denies_with`]), and checks every stated expectation. //! //! ```no_run -//! # async fn example(request: guardian_module_sdk::HookRequest) { +//! # async fn example(request: guardian_module_sdk::HookRequest, blocked: guardian_module_sdk::HookRequest) { //! use guardian_module_sdk::basic_policy::BasicPolicy; //! use guardian_module_sdk::conformance::Suite; //! //! Suite::new(BasicPolicy) -//! .request("small payment", request) +//! .allows("small payment", request) +//! .denies_with("payment to a blocked recipient", blocked, "recipient_blocked") //! .valid_params(serde_json::json!({ "recipient_denylist": [] })) //! .invalid_params(serde_json::json!({ "unknown": 1 })) //! .run() @@ -51,9 +57,45 @@ const PADDING_ENCODING: &str = "conformance.padding"; type Outcome = Result; +/// What a request must be answered with. +#[derive(Debug, Clone, PartialEq, Eq)] +enum Expected { + Allow, + Deny, + DenyWith(String), + Error, +} + +impl Expected { + fn met_by(&self, outcome: &Outcome) -> bool { + match (self, outcome) { + (Expected::Allow, Ok(decision)) => decision.effect == Effect::Allow as i32, + (Expected::Deny, Ok(decision)) => decision.effect == Effect::Deny as i32, + (Expected::DenyWith(code), Ok(decision)) => { + decision.effect == Effect::Deny as i32 && &decision.reason_code == code + } + (Expected::Error, Err(_)) => true, + (_, _) => false, + } + } +} + +impl fmt::Display for Expected { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + match self { + Expected::Allow => write!(f, "an allow"), + Expected::Deny => write!(f, "a deny"), + Expected::DenyWith(code) => write!(f, "a deny with reason code {code}"), + Expected::Error => write!(f, "an error"), + } + } +} + pub struct Suite { module: Arc, requests: Vec<(String, HookRequest)>, + /// One entry per request: what it must be answered with, when the suite says. + expected: Vec>, valid_params: Vec, invalid_params: Vec, request_max_bytes: usize, @@ -64,16 +106,54 @@ impl Suite { Self { module: Arc::new(module), requests: Vec::new(), + expected: Vec::new(), valid_params: Vec::new(), invalid_params: Vec::new(), request_max_bytes: DEFAULT_REQUEST_MAX_BYTES, } } - /// A request the module must answer the same way on every transport and every time. - /// The suite sets `instance_id`; everything else is sent as given. - pub fn request(mut self, name: impl Into, request: HookRequest) -> Self { + /// A request the module must answer the same way on every transport and every time, + /// whatever the answer is. The suite sets `instance_id`; everything else is sent as given. + pub fn request(self, name: impl Into, request: HookRequest) -> Self { + self.expecting(name, request, None) + } + + /// A request the module must allow. + pub fn allows(self, name: impl Into, request: HookRequest) -> Self { + self.expecting(name, request, Some(Expected::Allow)) + } + + /// A request the module must deny. Every suite needs one: a module that refuses nothing + /// answers consistently too. + pub fn denies(self, name: impl Into, request: HookRequest) -> Self { + self.expecting(name, request, Some(Expected::Deny)) + } + + /// A request the module must deny with `reason_code`. + pub fn denies_with( + self, + name: impl Into, + request: HookRequest, + reason_code: impl Into, + ) -> Self { + self.expecting(name, request, Some(Expected::DenyWith(reason_code.into()))) + } + + /// A request the module cannot judge and must answer with an error, so the instance's + /// `on_error` decides, never an allow. + pub fn fails(self, name: impl Into, request: HookRequest) -> Self { + self.expecting(name, request, Some(Expected::Error)) + } + + fn expecting( + mut self, + name: impl Into, + request: HookRequest, + expected: Option, + ) -> Self { self.requests.push((name.into(), request)); + self.expected.push(expected); self } @@ -99,6 +179,17 @@ impl Suite { if self.requests.is_empty() { report.fail("setup", "", "the suite needs at least one request"); } + if !self + .expected + .iter() + .any(|expected| matches!(expected, Some(Expected::Deny | Expected::DenyWith(_)))) + { + report.fail( + "setup", + "", + "the suite needs at least one request the module must deny (`denies` or `denies_with`): a module that refuses nothing would conform otherwise", + ); + } if self.valid_params.is_empty() { report.fail( "setup", @@ -120,6 +211,7 @@ impl Suite { self.check_params(&remote, &mut report).await; let baseline = self.check_transport(&remote, &mut report).await; self.check_decisions(&baseline, &mut report); + self.check_expectations(&baseline, &mut report); self.check_purity(&baseline, &mut report).await; self.check_instances(&remote, &baseline, &mut report).await; self.check_size_cap(&remote, &mut report).await; @@ -298,6 +390,21 @@ impl Suite { } } + fn check_expectations(&self, baseline: &[Outcome], report: &mut Report) { + for (((name, _), expected), outcome) in + self.requests.iter().zip(&self.expected).zip(baseline) + { + let Some(expected) = expected else { continue }; + if !expected.met_by(outcome) { + report.fail( + "expectation", + name, + format!("expected {expected}, got {outcome:?}"), + ); + } + } + } + async fn check_purity(&self, baseline: &[Outcome], report: &mut Report) { for ((name, request), expected) in self.requests.iter().zip(baseline) { let request = for_instance(request, INSTANCE_A); @@ -668,7 +775,7 @@ mod tests { fn suite(module: M) -> Suite { Suite::new(module) - .request("payment", transaction()) + .denies("payment", transaction()) .valid_params(json!({})) .invalid_params(json!({ "x": 1 })) } @@ -687,6 +794,51 @@ mod tests { .assert_conformant(); } + #[tokio::test] + async fn a_module_that_allows_everything_does_not_conform() { + let always_allows = || Fixed(Decision::allow()); + let unstated = Suite::new(always_allows()) + .request("payment", transaction()) + .valid_params(json!({})) + .invalid_params(json!({ "x": 1 })) + .run() + .await; + assert_eq!(checks(&unstated), vec!["setup"], "{unstated}"); + + let stated = suite(always_allows()).run().await; + assert_eq!(checks(&stated), vec!["expectation"], "{stated}"); + } + + #[tokio::test] + async fn each_expectation_is_checked() { + let denies = || Fixed(Decision::deny("blocked", "no")); + let wrong_code = Suite::new(denies()) + .denies_with("payment", transaction(), "amount_cap_exceeded") + .valid_params(json!({})) + .invalid_params(json!({ "x": 1 })) + .run() + .await; + assert_eq!(checks(&wrong_code), vec!["expectation"], "{wrong_code}"); + + let wrong_outcome = suite(denies()) + .allows("allowed payment", transaction()) + .fails("unjudgeable payment", transaction()) + .run() + .await; + assert_eq!(wrong_outcome.failures().len(), 2, "{wrong_outcome}"); + assert_eq!( + checks(&wrong_outcome), + vec!["expectation"], + "{wrong_outcome}" + ); + + suite(denies()) + .denies_with("coded payment", transaction(), "blocked") + .run() + .await + .assert_conformant(); + } + #[tokio::test] async fn counting_in_evaluate_is_caught() { let report = suite(Counting(AtomicU64::new(0))).run().await; @@ -705,7 +857,7 @@ mod tests { #[tokio::test] async fn accepting_invalid_params_is_caught() { let report = Suite::new(Counting(AtomicU64::new(0))) - .request("payment", transaction()) + .denies("payment", transaction()) .valid_params(json!({})) .invalid_params(json!({ "x": 1 })) .run() diff --git a/crates/guardian-module-sdk/tests/conformance.rs b/crates/guardian-module-sdk/tests/conformance.rs index a396c1b3..13338e71 100644 --- a/crates/guardian-module-sdk/tests/conformance.rs +++ b/crates/guardian-module-sdk/tests/conformance.rs @@ -54,10 +54,10 @@ fn payment(amounts: &[u64], params: serde_json::Value) -> HookRequest { .map(|(i, amount)| OutputNote { note_id: format!("0x{i}"), assets: vec![Asset { - faucet_id: "0xaa".into(), + faucet_id: "0x0000000000000000000000000000aa".into(), value: Some(asset::Value::FungibleAmount(amount.to_string())), }], - p2id_target: Some("0xa1".into()), + p2id_target: Some("0x0000000000000000000000000000a1".into()), ..Default::default() }) .collect(); @@ -85,15 +85,24 @@ fn view(signers: &[&str], code: &str) -> AccountView { } fn with_views(mut request: HookRequest, before: &[&str], after: &[&str]) -> HookRequest { - request.before = Some(view(before, "0xc1")); - request.after = Some(view(after, "0xc1")); + request.before = Some(view( + before, + "0x00000000000000000000000000000000000000000000000000000000000000c1", + )); + request.after = Some(view( + after, + "0x00000000000000000000000000000000000000000000000000000000000000c1", + )); request } fn registration(params: serde_json::Value, signers: &[&str]) -> HookRequest { HookRequest { params: serde_json::to_vec(¶ms).unwrap(), - after: Some(view(signers, "0xc1")), + after: Some(view( + signers, + "0x00000000000000000000000000000000000000000000000000000000000000c1", + )), subject: Some(hook_request::Subject::Registration(RegistrationSubject { initial_state: Some(AccountStateProjection::miden(MidenAccountState::default())), })), @@ -103,47 +112,51 @@ fn registration(params: serde_json::Value, signers: &[&str]) -> HookRequest { #[tokio::test] async fn basic_policy_conforms() { - let cap = json!({ "max_amount_per_tx": { "0xaa": "1000" } }); - let signers = json!({ "signer_check": "added", "signer_denylist": ["0xbad"] }); - let code = json!({ "code_check": "all", "allowed_code_commitments": ["0xc1"] }); + let cap = json!({ "max_amount_per_tx": { "0x0000000000000000000000000000aa": "1000" } }); + let signers = json!({ "signer_check": "added", "signer_denylist": ["0x0000000000000000000000000000000000000000000000000000000000000bad"] }); + let code = json!({ "code_check": "all", "allowed_code_commitments": ["0x00000000000000000000000000000000000000000000000000000000000000c1"] }); Suite::new(BasicPolicy) - .request("under the cap", payment(&[500], cap.clone())) - .request("split over the cap", payment(&[600, 600], cap.clone())) - .request("at the cap", payment(&[1000], cap)) - .request( + .allows("under the cap", payment(&[500], cap.clone())) + .denies_with( + "split over the cap", + payment(&[600, 600], cap.clone()), + "amount_cap_exceeded", + ) + .allows("at the cap", payment(&[1000], cap)) + .denies( "recipient not allowed", - payment(&[1], json!({ "recipient_allowlist": ["0x07e4"] })), + payment(&[1], json!({ "recipient_allowlist": ["0x0000000000000000000000000007e4"] })), ) - .request( + .denies( "recipient denied, generic", - payment(&[1], json!({ "recipient_denylist": ["0xa1"] })), + payment(&[1], json!({ "recipient_denylist": ["0x0000000000000000000000000000a1"] })), ) - .request( + .denies( "denied signer added", with_views( payment(&[1], signers.clone()), - &["0x51"], - &["0x51", "0xbad"], + &["0x0000000000000000000000000000000000000000000000000000000000000051"], + &["0x0000000000000000000000000000000000000000000000000000000000000051", "0x0000000000000000000000000000000000000000000000000000000000000bad"], ), ) - .request( + .allows( "listed code", - with_views(payment(&[1], code.clone()), &["0x51"], &["0x51"]), + with_views(payment(&[1], code.clone()), &["0x0000000000000000000000000000000000000000000000000000000000000051"], &["0x0000000000000000000000000000000000000000000000000000000000000051"]), ) - .request( + .denies( "registration with a denied signer", - registration(signers, &["0xbad"]), + registration(signers, &["0x0000000000000000000000000000000000000000000000000000000000000bad"]), ) - .request("registration on listed code", registration(code, &["0x51"])) - .request( + .request("registration on listed code", registration(code, &["0x0000000000000000000000000000000000000000000000000000000000000051"])) + .fails( "params a module cannot read", - payment(&[1], json!({ "max_amount_per_tx": { "0xaa": "ten" } })), + payment(&[1], json!({ "max_amount_per_tx": { "0x0000000000000000000000000000aa": "ten" } })), ) .valid_params(json!({})) - .valid_params(json!({ "max_amount_per_tx": { "0xaa": "1000" }, "recipient_denylist": [] })) - .valid_params(json!({ "code_check": "changed", "allowed_code_commitments": ["0xc1"] })) + .valid_params(json!({ "max_amount_per_tx": { "0x0000000000000000000000000000aa": "1000" }, "recipient_denylist": [] })) + .valid_params(json!({ "code_check": "changed", "allowed_code_commitments": ["0x00000000000000000000000000000000000000000000000000000000000000c1"] })) .invalid_params(json!({ "unknown": 1 })) - .invalid_params(json!({ "max_amount_per_tx": { "0xaa": "ten" } })) + .invalid_params(json!({ "max_amount_per_tx": { "0x0000000000000000000000000000aa": "ten" } })) .invalid_params(json!({ "signer_allowlist": [], "signer_denylist": [] })) .run() .await @@ -178,25 +191,31 @@ async fn note_policy_conforms() { let one = json!({ "max_payment_notes": 1 }); let private = json!({ "deny_private_notes": true }); Suite::new(note_policy::NotePolicy) - .request( + .allows( "one payment and the fee note", notes( vec![note(NoteType::Public, false), note(NoteType::Public, true)], one.clone(), ), ) - .request( + .denies( "two payments", notes( vec![note(NoteType::Public, false), note(NoteType::Public, false)], one, ), ) - .request( + .denies( "a private payment", notes(vec![note(NoteType::Private, false)], private), ) - .request("registration", registration(json!({}), &["0x51"])) + .request( + "registration", + registration( + json!({}), + &["0x0000000000000000000000000000000000000000000000000000000000000051"], + ), + ) .valid_params(json!({ "max_payment_notes": 1, "deny_private_notes": true })) .valid_params(json!({})) .invalid_params(json!({ "max_notes": 1 })) @@ -209,7 +228,10 @@ async fn note_policy_conforms() { #[ignore = "timing report for the prototype gates; run with --ignored --nocapture"] async fn loopback_evaluate_round_trip() { let mut client = GuardianModuleClient::new(start_remote().await); - let request = payment(&[500], json!({ "max_amount_per_tx": { "0xaa": "1000" } })); + let request = payment( + &[500], + json!({ "max_amount_per_tx": { "0x0000000000000000000000000000aa": "1000" } }), + ); for _ in 0..50 { client .evaluate(authorized(request.clone(), TOKEN)) diff --git a/crates/server/src/api/dashboard_modules.rs b/crates/server/src/api/dashboard_modules.rs index ddf5c6d4..0122bf41 100644 --- a/crates/server/src/api/dashboard_modules.rs +++ b/crates/server/src/api/dashboard_modules.rs @@ -417,13 +417,12 @@ mod tests { "blocklist", &[HookName::BeforeTransactionApproved], Arc::new(BasicPolicy), - json!({ "recipient_denylist": ["0xaaa"] }), + json!({ "recipient_denylist": ["0x000000000000000000000000000aaa"] }), )])); let app = create_router(state); let support_cookie = login(&app, &support).await; let admin_cookie = login(&app, &admin).await; - let body = - json!({ "params": { "recipient_denylist": ["0xaaa", "0xddd"] }, "reason": "OP-90" }); + let body = json!({ "params": { "recipient_denylist": ["0x000000000000000000000000000aaa", "0x000000000000000000000000000ddd"] }, "reason": "OP-90" }); let (status, _) = send( &app, @@ -442,7 +441,10 @@ mod tests { ) .await; assert_eq!(status, StatusCode::OK, "{view}"); - assert_eq!(view["params"]["recipient_denylist"][1], "0xddd"); + assert_eq!( + view["params"]["recipient_denylist"][1], + "0x000000000000000000000000000ddd" + ); let (status, catalog) = send(&app, get("/dashboard/modules", &support_cookie)).await; assert_eq!(status, StatusCode::OK); diff --git a/crates/server/src/modules/catalog.rs b/crates/server/src/modules/catalog.rs index 67095038..9a4f187b 100644 --- a/crates/server/src/modules/catalog.rs +++ b/crates/server/src/modules/catalog.rs @@ -553,7 +553,7 @@ kind = "basic-policy" scope = "all" hooks = ["before_transaction_approved", "before_proposal_created"] timeout_ms = 20 -params = { max_amount_per_tx = { "0xaa" = "1000" } } +params = { max_amount_per_tx = { "0x0000000000000000000000000000aa" = "1000" } } [[module]] id = "signers" @@ -698,7 +698,7 @@ params = {{ api_key = {{ "$secret" = "vendor-key" }} }} #[test] fn params_with_secret_references_are_file_managed() { let text = VALID.replacen( - r#"params = { max_amount_per_tx = { "0xaa" = "1000" } }"#, + r#"params = { max_amount_per_tx = { "0x0000000000000000000000000000aa" = "1000" } }"#, r#"params = { api_key = { "$secret" = "x" } }"#, 1, ); diff --git a/crates/server/src/services/execute_proposal/tests.rs b/crates/server/src/services/execute_proposal/tests.rs index 2e16c384..b9001008 100644 --- a/crates/server/src/services/execute_proposal/tests.rs +++ b/crates/server/src/services/execute_proposal/tests.rs @@ -1335,7 +1335,7 @@ async fn an_approving_module_lets_the_execution_through_and_is_recorded_on_the_d #[tokio::test] async fn a_guardian_execution_over_a_mandatory_cap_is_refused_before_anything_is_proved() { use guardian_shared::execution::ModuleDenial; - const USDC: &str = "0xaa00"; + const USDC: &str = "0x00000000000000000000000000aa00"; let cap = crate::modules::testing::instance_with_params( "caps", &[crate::modules::catalog::HookName::BeforeTransactionApproved], diff --git a/crates/server/src/services/push_delta.rs b/crates/server/src/services/push_delta.rs index ab728d7b..736f71b1 100644 --- a/crates/server/src/services/push_delta.rs +++ b/crates/server/src/services/push_delta.rs @@ -2312,7 +2312,7 @@ mod tests { ); } - const USDC: &str = "0xaa00"; + const USDC: &str = "0x00000000000000000000000000aa00"; fn cap_of_1000() -> crate::modules::registry::Instance { crate::modules::testing::instance_with_params( From c32132f9cbee7169b4a8e2d8f450f359e604441e Mon Sep 17 00:00:00 2001 From: Zeljko Date: Tue, 10 Nov 2026 08:14:27 +0100 Subject: [PATCH 082/105] fix(modules): probe failures reach the breaker and the assignment gauges follow fixes (#251) - A health probe that gets no answer counts as a failed call. One that finds the module answering with a protocol version, a required capability or a hook set this Guardian cannot work with opens the breaker at once and keeps it open until a probe passes: a module redeployed under a running Guardian was trusted until restart. - The over-budget and orphan counts are taken again every minute, so an alarm clears after the operator fixes the assignment. - The count reads which module each account row names, not every account's params, which default copies make as large as the account count times the params size. --- crates/server/src/modules/admin.rs | 38 ++- crates/server/src/modules/breaker.rs | 21 ++ crates/server/src/modules/pipeline.rs | 284 ++++++++++++++++---- crates/server/src/modules/postgres_store.rs | 33 ++- crates/server/src/modules/registry.rs | 42 ++- crates/server/src/modules/store.rs | 26 +- crates/server/src/modules/testing.rs | 4 +- 7 files changed, 359 insertions(+), 89 deletions(-) diff --git a/crates/server/src/modules/admin.rs b/crates/server/src/modules/admin.rs index 99824e02..dd270833 100644 --- a/crates/server/src/modules/admin.rs +++ b/crates/server/src/modules/admin.rs @@ -766,7 +766,7 @@ mod tests { "blocklist", &hooks, Arc::new(BasicPolicy), - json!({ "recipient_denylist": ["0xaaa"] }), + json!({ "recipient_denylist": ["0x000000000000000000000000000aaa"] }), ), optional, secret, @@ -925,7 +925,7 @@ mod tests { &operator(), ACCOUNT, "blocklist", - Some(json!({ "recipient_denylist": ["0xbbb"] })), + Some(json!({ "recipient_denylist": ["0x000000000000000000000000000bbb"] })), "OP-1", None, ) @@ -994,6 +994,18 @@ mod tests { .unwrap(), (1, 0) ); + + set_assignment(&state, &operator(), ACCOUNT, Vec::new(), "OP-2", None) + .await + .expect("removing the assignment brings the account back under the budget"); + let modules = state.modules.as_ref().unwrap(); + assert_eq!(modules.assignment_report(), (1, 0), "not recounted yet"); + modules.refresh_assignment_report().await; + assert_eq!( + modules.assignment_report(), + (0, 0), + "the recount follows the operator's fix, so the alarm clears" + ); } #[tokio::test] @@ -1017,7 +1029,7 @@ mod tests { &operator(), "0xAcC", "blocklist", - Some(json!({ "recipient_denylist": ["0xbbb"] })), + Some(json!({ "recipient_denylist": ["0x000000000000000000000000000bbb"] })), "OP-1", None, ) @@ -1055,7 +1067,7 @@ mod tests { .set_layer( ACCOUNT, "optional", - Some(json!({ "recipient_denylist": ["0xbbb"] })), + Some(json!({ "recipient_denylist": ["0x000000000000000000000000000bbb"] })), &Change { operator: "0xop", reason: "written while optional applied to every account", @@ -1177,7 +1189,7 @@ mod tests { &operator(), ACCOUNT, "blocklist", - Some(json!({ "recipient_denylist": ["0xbbb"] })), + Some(json!({ "recipient_denylist": ["0x000000000000000000000000000bbb"] })), "OP-2", None, ) @@ -1202,7 +1214,7 @@ mod tests { &state, &operator, "blocklist", - json!({ "recipient_denylist": ["0xaaa", "0xddd"] }), + json!({ "recipient_denylist": ["0x000000000000000000000000000aaa", "0x000000000000000000000000000ddd"] }), "OP-90", None, ) @@ -1213,7 +1225,7 @@ mod tests { &operator, ACCOUNT, "blocklist", - Some(json!({ "recipient_denylist": ["0xccc"] })), + Some(json!({ "recipient_denylist": ["0x000000000000000000000000000ccc"] })), "OP-91", None, ) @@ -1222,11 +1234,13 @@ mod tests { let entry = &view.modules[0]; assert_eq!( entry.global_params, - Some(json!({ "recipient_denylist": ["0xaaa", "0xddd"] })) + Some( + json!({ "recipient_denylist": ["0x000000000000000000000000000aaa", "0x000000000000000000000000000ddd"] }) + ) ); assert_eq!( entry.account_layer, - Some(json!({ "recipient_denylist": ["0xccc"] })) + Some(json!({ "recipient_denylist": ["0x000000000000000000000000000ccc"] })) ); let history = history(&state, "blocklist", None, None) @@ -1250,7 +1264,7 @@ mod tests { &state, &operator(), "blocklist", - json!({ "recipient_denylist": [format!("0x{n}")] }), + json!({ "recipient_denylist": [format!("0x{n:030x}")] }), &format!("OP-{n}"), None, ) @@ -1378,7 +1392,7 @@ mod tests { .seed_instance( "blocklist", true, - &json!({ "recipient_denylist": ["0xaaa"] }), + &json!({ "recipient_denylist": ["0x000000000000000000000000000aaa"] }), "t0", ) .await @@ -1423,7 +1437,7 @@ mod tests { ACCOUNT, vec![Assigned { module_id: "optional".into(), - params: json!({ "recipient_denylist": ["0xeee"] }), + params: json!({ "recipient_denylist": ["0x000000000000000000000000000eee"] }), }], "customer request", None, diff --git a/crates/server/src/modules/breaker.rs b/crates/server/src/modules/breaker.rs index 14b1322a..b61f1bb4 100644 --- a/crates/server/src/modules/breaker.rs +++ b/crates/server/src/modules/breaker.rs @@ -113,6 +113,17 @@ impl Breakers { }); } + /// A health probe found the module answering `Describe` with a protocol version, a required + /// capability or a hook set this Guardian cannot work with. Its decisions are not trusted + /// from here on, whatever it answered before: the breaker opens at once and stays open + /// until a probe passes again. + pub fn probe_incompatible(&self, instance: &str) { + self.update(instance, |breaker| { + breaker.state = CircuitState::Open; + breaker.trial_in_flight = false; + }); + } + /// A health probe succeeded: an open breaker lets the next real call through, and a /// half-open one whose trial never reported back (its request was dropped) lets another. pub fn probe_succeeded(&self, instance: &str) { @@ -201,6 +212,16 @@ mod tests { assert_eq!(breakers.state("m"), CircuitState::Closed); } + #[test] + fn an_incompatible_probe_opens_a_closed_breaker_until_a_probe_passes() { + let breakers = Breakers::new(5); + breakers.probe_incompatible("m"); + assert_eq!(breakers.state("m"), CircuitState::Open); + assert!(!breakers.admit("m", Caller::Request)); + breakers.probe_succeeded("m"); + assert!(breakers.admit("m", Caller::Request)); + } + #[test] fn a_probe_does_not_touch_a_closed_breaker_and_instances_are_independent() { let breakers = Breakers::new(1); diff --git a/crates/server/src/modules/pipeline.rs b/crates/server/src/modules/pipeline.rs index 30064410..9556d14d 100644 --- a/crates/server/src/modules/pipeline.rs +++ b/crates/server/src/modules/pipeline.rs @@ -8,7 +8,7 @@ use std::sync::{Arc, RwLock}; use super::breaker::{Breakers, Caller, CircuitState}; use super::limits::Limits; -use super::registry::{CallError, Instance, Registry, isolated}; +use super::registry::{CallError, Instance, Registry, Unhealthy, isolated}; use super::request::ViewCache; use super::store::{AccountParamsRow, Assigned, ModuleStore, ParamsKind}; use crate::delta_summary::FailedOpen; @@ -94,6 +94,16 @@ pub struct ModulePipeline { pub(super) type Rows = Arc>; +/// How often the probe loop recounts the over-budget accounts and orphaned rows. +const ASSIGNMENT_REPORT_INTERVAL: std::time::Duration = std::time::Duration::from_secs(60); + +/// An account whose stored modules could take longer than the evaluation budget. +struct OverBudget { + account_id: String, + hook: HookName, + worst_case: std::time::Duration, +} + #[derive(Default)] struct Cache { version: Option, @@ -340,12 +350,12 @@ impl ModulePipeline { &self.breakers } - /// The hook with the largest worst-case module time for an account whose module rows are - /// `rows`, and that time: every `scope = all` instance, once more for an account layer on + /// The hook with the largest worst-case module time for an account whose rows name + /// `modules`, and that time: every `scope = all` instance, once more for an account layer on /// it, plus every listed instance. Disabled instances count, since enabling needs no further /// check; a row naming an instance the catalog no longer declares costs nothing. - pub fn worst_case(&self, rows: &[AccountParamsRow]) -> (HookName, std::time::Duration) { - self.costs(rows) + fn worst_case(&self, modules: &[(&str, ParamsKind)]) -> (HookName, std::time::Duration) { + self.costs(modules) .into_iter() .max_by_key(|(_, total)| *total) .unwrap_or(( @@ -354,11 +364,13 @@ impl ModulePipeline { )) } - /// The summed timeouts of the module calls an account with `rows` makes at each gate hook. - fn costs(&self, rows: &[AccountParamsRow]) -> Vec<(HookName, std::time::Duration)> { + /// The summed timeouts of the module calls an account naming `modules` makes at each gate + /// hook. + fn costs(&self, modules: &[(&str, ParamsKind)]) -> Vec<(HookName, std::time::Duration)> { let calls = |id: &str, kind: ParamsKind| { - rows.iter() - .filter(|row| row.kind == kind && row.module_id == id) + modules + .iter() + .filter(|(module_id, named)| *named == kind && *module_id == id) .count() as u32 }; HookName::GATES @@ -382,7 +394,6 @@ impl ModulePipeline { .collect() } - /// Refuses an account whose modules, with `rows` stored, could exceed the evaluation budget. /// Refuses a write that would take the account's modules over the budget at a hook where /// they are not already at least that far over. A write that keeps or lowers the cost passes, /// so an account a deploy pushed over the budget can still be brought back under it. @@ -391,7 +402,14 @@ impl ModulePipeline { current: &[AccountParamsRow], proposed: &[AccountParamsRow], ) -> Result<(), GuardianError> { - for ((hook, total), (_, now)) in self.costs(proposed).into_iter().zip(self.costs(current)) { + let named = |rows: &[AccountParamsRow]| -> Vec<(HookName, std::time::Duration)> { + let modules: Vec<(&str, ParamsKind)> = rows + .iter() + .map(|row| (row.module_id.as_str(), row.kind)) + .collect(); + self.costs(&modules) + }; + for ((hook, total), (_, now)) in named(proposed).into_iter().zip(named(current)) { if total > self.limits.budget && total > now { return Err(GuardianError::InvalidInput(format!( "the account's modules at {} would take up to {} ms, over the evaluation budget of {} ms", @@ -404,33 +422,75 @@ impl ModulePipeline { Ok(()) } - /// Logs every account whose stored modules exceed the budget, without refusing to start: a - /// deploy that raised a timeout must not become an outage. Returns the count of those - /// accounts and of stored rows naming an instance the catalog no longer declares. - pub async fn report_stored_assignments(&self) -> Result<(usize, usize), String> { - let rows = self.store.all_account_params().await?; + /// The accounts whose stored modules exceed the budget, each with its worst hook and that + /// hook's time, and the count of stored rows naming an instance the catalog no longer + /// declares. One scan of which module each account row names, without params. + async fn scan_assignments(&self) -> Result<(Vec, usize), String> { + let rows = self.store.account_modules().await?; let orphaned = rows .iter() .filter(|row| self.instance(&row.module_id).is_none()) .count(); - let mut over = 0; - for account in rows.chunk_by(|a, b| a.account_id == b.account_id) { - let (hook, total) = self.worst_case(account); - if total > self.limits.budget { - over += 1; - tracing::warn!( - account_id = %account[0].account_id, - hook = hook.as_str(), - worst_case_ms = total.as_millis() as u64, - budget_ms = self.limits.budget.as_millis() as u64, - "Account's policy modules exceed the evaluation budget; the runtime budget applies" - ); - } - } + let over = rows + .chunk_by(|a, b| a.account_id == b.account_id) + .filter_map(|account| { + let modules: Vec<(&str, ParamsKind)> = account + .iter() + .map(|row| (row.module_id.as_str(), row.kind)) + .collect(); + let (hook, worst_case) = self.worst_case(&modules); + (worst_case > self.limits.budget).then(|| OverBudget { + account_id: account[0].account_id.clone(), + hook, + worst_case, + }) + }) + .collect(); + Ok((over, orphaned)) + } + + /// The over-budget account count and the orphaned row count as last counted. + #[cfg(test)] + pub fn assignment_report(&self) -> (usize, usize) { + self.assignment_report + .lock() + .map(|report| *report) + .unwrap_or_default() + } + + fn record_assignment_report(&self, over_budget: usize, orphaned: usize) { if let Ok(mut report) = self.assignment_report.lock() { - *report = (over, orphaned); + *report = (over_budget, orphaned); + } + } + + /// Logs every account whose stored modules exceed the budget, without refusing to start: a + /// deploy that raised a timeout must not become an outage. Returns the count of those + /// accounts and of stored rows naming an instance the catalog no longer declares. + pub async fn report_stored_assignments(&self) -> Result<(usize, usize), String> { + let (over, orphaned) = self.scan_assignments().await?; + for account in &over { + tracing::warn!( + account_id = %account.account_id, + hook = account.hook.as_str(), + worst_case_ms = account.worst_case.as_millis() as u64, + budget_ms = self.limits.budget.as_millis() as u64, + "Account's policy modules exceed the evaluation budget; the runtime budget applies" + ); + } + self.record_assignment_report(over.len(), orphaned); + Ok((over.len(), orphaned)) + } + + /// Recounts the over-budget accounts and orphaned rows for the gauges, so they follow what + /// operators change after startup: an alarm clears once the assignment is fixed. + pub async fn refresh_assignment_report(&self) { + match self.scan_assignments().await { + Ok((over, orphaned)) => self.record_assignment_report(over.len(), orphaned), + Err(error) => { + tracing::warn!(%error, "Stored module assignments not recounted; the gauges keep their last values"); + } } - Ok((over, orphaned)) } /// Sets the state gauges from the stored rows and this replica's breakers. Run on every probe, @@ -456,7 +516,10 @@ impl ModulePipeline { } /// One health probe of every enabled instance: `Describe` under its timeout, with the startup - /// checks. A healthy module half-opens an open breaker so the next real call is sent. + /// checks. A healthy module half-opens an open breaker so the next real call is sent. One + /// that does not answer counts as a failed call toward its breaker. One that answers with a + /// protocol version, capability or hook set this Guardian cannot work with opens its breaker + /// at once: its decisions are not trusted until a probe passes again. pub async fn probe(&self) { let Ok(rows) = self.rows().await else { return; @@ -469,13 +532,17 @@ impl ModulePipeline { let healthy = super::registry::describe_healthy(&instance.config, &instance.module).await; super::metrics::up(&instance.config.id, healthy.is_ok()); + let id = instance.config.id.as_str(); match healthy { - Ok(_) => self.breakers.probe_succeeded(&instance.config.id), - Err(error) => tracing::warn!( - module = %instance.config.id, - %error, - "Policy module health probe failed" - ), + Ok(_) => self.breakers.probe_succeeded(id), + Err(Unhealthy::Unreachable(error)) => { + tracing::warn!(module = id, %error, "Policy module health probe failed"); + self.breakers.failed(id); + } + Err(Unhealthy::Incompatible(error)) => { + tracing::warn!(module = id, %error, "Policy module is incompatible with this Guardian; its circuit is open until a probe passes"); + self.breakers.probe_incompatible(id); + } } } } @@ -485,8 +552,13 @@ impl ModulePipeline { tokio::spawn(async move { let mut interval = tokio::time::interval(self.limits.probe_interval); interval.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Delay); + let mut counted = tokio::time::Instant::now(); loop { interval.tick().await; + if counted.elapsed() >= ASSIGNMENT_REPORT_INTERVAL { + self.refresh_assignment_report().await; + counted = tokio::time::Instant::now(); + } self.probe().await; } }) @@ -1098,7 +1170,8 @@ params = {params} assert!(started.is_err()); assert!(store.instances().await.unwrap().is_empty()); - let fixed = caps_catalog(r#"{ max_amount_per_tx = { "0xaa" = "5" } }"#); + let fixed = + caps_catalog(r#"{ max_amount_per_tx = { "0x0000000000000000000000000000aa" = "5" } }"#); let started = ModulePipeline::new( "local", fixed, @@ -1712,7 +1785,7 @@ params = { old_name = 1000 } "blocklist", &[HOOK], std::sync::Arc::new(BasicPolicy), - json!({ "recipient_denylist": ["0xaaa"] }), + json!({ "recipient_denylist": ["0x000000000000000000000000000aaa"] }), )]) } @@ -1744,24 +1817,36 @@ params = { old_name = 1000 } .set_layer( "0xacc", "blocklist", - Some(json!({ "recipient_denylist": ["0xccc"] })), + Some(json!({ "recipient_denylist": ["0x000000000000000000000000000ccc"] })), &change(), ) .await .unwrap(); assert_eq!( - layer_of(&pipeline, "0xacc", "0xaaa").await.as_deref(), + layer_of(&pipeline, "0xacc", "0x000000000000000000000000000aaa") + .await + .as_deref(), Some("global") ); assert_eq!( - layer_of(&pipeline, "0xacc", "0xccc").await.as_deref(), + layer_of(&pipeline, "0xacc", "0x000000000000000000000000000ccc") + .await + .as_deref(), Some("account") ); - assert_eq!(layer_of(&pipeline, "0xacc", "0xbbb").await, None); - assert_eq!(layer_of(&pipeline, "0xother", "0xccc").await, None); assert_eq!( - layer_of(&pipeline, "0xother", "0xaaa").await.as_deref(), + layer_of(&pipeline, "0xacc", "0x000000000000000000000000000bbb").await, + None + ); + assert_eq!( + layer_of(&pipeline, "0xother", "0x000000000000000000000000000ccc").await, + None + ); + assert_eq!( + layer_of(&pipeline, "0xother", "0x000000000000000000000000000aaa") + .await + .as_deref(), Some("global") ); } @@ -1775,7 +1860,9 @@ params = { old_name = 1000 } .await .unwrap(); assert_eq!( - layer_of(&pipeline, "0xacc", "0xaaa").await.as_deref(), + layer_of(&pipeline, "0xacc", "0x000000000000000000000000000aaa") + .await + .as_deref(), Some("global") ); } @@ -1788,7 +1875,7 @@ params = { old_name = 1000 } .seed_instance( "blocklist", true, - &json!({ "recipient_denylist": ["0xaaa"] }), + &json!({ "recipient_denylist": ["0x000000000000000000000000000aaa"] }), "t0", ) .await @@ -1797,13 +1884,15 @@ params = { old_name = 1000 } .store() .set_global( "blocklist", - json!({ "recipient_denylist": ["0xaaa", "0xddd"] }), + json!({ "recipient_denylist": ["0x000000000000000000000000000aaa", "0x000000000000000000000000000ddd"] }), &change(), ) .await .unwrap(); assert_eq!( - layer_of(&pipeline, "0xany", "0xddd").await.as_deref(), + layer_of(&pipeline, "0xany", "0x000000000000000000000000000ddd") + .await + .as_deref(), Some("global") ); } @@ -1816,13 +1905,15 @@ params = { old_name = 1000 } .seed_instance( "blocklist", true, - &json!({ "recipient_denylist": ["0xaaa"] }), + &json!({ "recipient_denylist": ["0x000000000000000000000000000aaa"] }), "t0", ) .await .unwrap(); assert_eq!( - layer_of(&pipeline, "0xacc", "0xaaa").await.as_deref(), + layer_of(&pipeline, "0xacc", "0x000000000000000000000000000aaa") + .await + .as_deref(), Some("global") ); pipeline @@ -1830,7 +1921,10 @@ params = { old_name = 1000 } .set_enabled("blocklist", false, &change()) .await .unwrap(); - assert_eq!(layer_of(&pipeline, "0xacc", "0xaaa").await, None); + assert_eq!( + layer_of(&pipeline, "0xacc", "0x000000000000000000000000000aaa").await, + None + ); assert!(!pipeline.applies(HOOK, "0xacc").await.unwrap()); pipeline .store() @@ -1838,7 +1932,9 @@ params = { old_name = 1000 } .await .unwrap(); assert_eq!( - layer_of(&pipeline, "0xacc", "0xaaa").await.as_deref(), + layer_of(&pipeline, "0xacc", "0x000000000000000000000000000aaa") + .await + .as_deref(), Some("global") ); } @@ -2171,6 +2267,84 @@ mod failure_handling_tests { )); } + #[tokio::test] + async fn a_module_that_turns_incompatible_is_not_trusted_until_a_probe_passes() { + let mut stub = crate::modules::testing::ProtocolStub::new(); + stub.protocol_version = guardian_module_sdk::PROTOCOL_VERSION + 1; + let pipeline = ModulePipeline::from_instances(vec![instance( + "screening", + &[HOOK], + OnError::Deny, + Arc::new(stub), + )]); + run(&pipeline) + .await + .expect("the module allows until a probe finds it incompatible"); + pipeline.probe().await; + assert_eq!(pipeline.breakers().state("screening"), CircuitState::Open); + assert!(matches!( + run(&pipeline).await, + Err(GuardianError::ModuleUnavailable { .. }) + )); + pipeline.probe().await; + assert_eq!( + pipeline.breakers().state("screening"), + CircuitState::Open, + "it stays open while the probe keeps failing" + ); + } + + /// Allows every request but never answers `Describe`. + struct Undescribed; + + #[async_trait::async_trait] + impl guardian_module_sdk::Module for Undescribed { + async fn describe( + &self, + _: &guardian_module_sdk::DescribeRequest, + ) -> Result { + Err(guardian_module_sdk::ModuleError::Unavailable( + "no answer".into(), + )) + } + + async fn validate_params( + &self, + _: &[u8], + ) -> Result { + Ok(guardian_module_sdk::ParamsVerdict::ok()) + } + + async fn evaluate( + &self, + _: &HookRequest, + ) -> Result { + Ok(guardian_module_sdk::Decision::allow()) + } + } + + #[tokio::test] + async fn probes_a_module_does_not_answer_count_toward_its_breaker() { + let pipeline = ModulePipeline::from_instances(vec![instance( + "screening", + &[HOOK], + OnError::Deny, + Arc::new(Undescribed), + )]) + .with_limits(Limits { + breaker_failures: 2, + ..Limits::default() + }); + pipeline.probe().await; + assert_eq!(pipeline.breakers().state("screening"), CircuitState::Closed); + pipeline.probe().await; + assert_eq!( + pipeline.breakers().state("screening"), + CircuitState::Open, + "no request had to find the module down" + ); + } + #[tokio::test] async fn a_healthy_probe_half_opens_and_a_failing_one_leaves_the_circuit_open() { let healthy = crate::modules::testing::instance_with_params( diff --git a/crates/server/src/modules/postgres_store.rs b/crates/server/src/modules/postgres_store.rs index 438c1b8e..ad7a5fb5 100644 --- a/crates/server/src/modules/postgres_store.rs +++ b/crates/server/src/modules/postgres_store.rs @@ -9,8 +9,8 @@ use diesel_async::scoped_futures::ScopedFutureExt; use diesel_async::{AsyncConnection, AsyncPgConnection, RunQueryDsl}; use super::store::{ - AccountParamsRow, Assigned, Change, HistoryEntry, InstanceRow, ModuleSnapshot, ModuleStore, - ParamsKind, assignment_changes, + AccountModule, AccountParamsRow, Assigned, Change, HistoryEntry, InstanceRow, ModuleSnapshot, + ModuleStore, ParamsKind, assignment_changes, }; pub struct PgModuleStore { @@ -449,16 +449,33 @@ impl ModuleStore for PgModuleStore { }) } - async fn all_account_params(&self) -> Result, String> { + async fn account_modules(&self) -> Result, String> { + #[derive(QueryableByName)] + struct AccountModuleSql { + #[diesel(sql_type = Text)] + account_id: String, + #[diesel(sql_type = Text)] + module_id: String, + #[diesel(sql_type = Text)] + kind: String, + } let mut conn = self.conn().await?; - let rows: Vec = diesel::sql_query( - "SELECT account_id, module_id, kind, position, params, updated_at, updated_by \ - FROM module_account_params ORDER BY account_id, position, module_id", + let rows: Vec = diesel::sql_query( + "SELECT account_id, module_id, kind FROM module_account_params \ + ORDER BY account_id, position, module_id", ) .load(&mut conn) .await - .map_err(|e| format!("all account module params: {e}"))?; - rows.into_iter().map(account_params_row).collect() + .map_err(|e| format!("account modules: {e}"))?; + rows.into_iter() + .map(|row| { + Ok(AccountModule { + account_id: row.account_id, + module_id: row.module_id, + kind: ParamsKind::parse(&row.kind)?, + }) + }) + .collect() } async fn set_layer( diff --git a/crates/server/src/modules/registry.rs b/crates/server/src/modules/registry.rs index 079c1d34..4fa8ccb0 100644 --- a/crates/server/src/modules/registry.rs +++ b/crates/server/src/modules/registry.rs @@ -253,24 +253,50 @@ pub async fn check( Ok(Checked { info, params }) } +/// Why a module failed [`describe_healthy`]. +#[derive(Debug, Clone, PartialEq, Eq)] +pub enum Unhealthy { + /// `Describe` did not answer: the module may be down. + Unreachable(String), + /// `Describe` answered with something this Guardian cannot work with, so the module's + /// decisions cannot be trusted either. + Incompatible(String), +} + +impl std::fmt::Display for Unhealthy { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + match self { + Unhealthy::Unreachable(detail) | Unhealthy::Incompatible(detail) => { + write!(f, "{detail}") + } + } + } +} + +impl From for String { + fn from(unhealthy: Unhealthy) -> Self { + unhealthy.to_string() + } +} + /// `Describe` under the instance's timeout, refused when the module speaks a protocol version /// outside the supported range, requires a capability this Guardian lacks, or no longer supports /// a configured hook. The startup checks and the periodic health probe share it. pub async fn describe_healthy( config: &InstanceConfig, module: &Arc, -) -> Result { +) -> Result { let describing = module.clone(); let info = isolated(config.timeout, async move { describing.describe(&describe_request()).await }) .await - .map_err(|e| format!("describe {e}"))?; + .map_err(|e| Unhealthy::Unreachable(format!("describe {e}")))?; if !(MIN_PROTOCOL_VERSION..=PROTOCOL_VERSION).contains(&info.protocol_version) { - return Err(format!( + return Err(Unhealthy::Incompatible(format!( "unsupported protocol version {}; this Guardian accepts {MIN_PROTOCOL_VERSION} to {PROTOCOL_VERSION}", info.protocol_version - )); + ))); } if info.protocol_version < PROTOCOL_VERSION { tracing::warn!(module = %config.id, protocol_version = info.protocol_version, current = PROTOCOL_VERSION, "Module speaks a deprecated protocol version"); @@ -280,13 +306,15 @@ pub async fn describe_healthy( .iter() .find(|required| !CAPABILITIES.contains(&required.as_str())) { - return Err(format!( + return Err(Unhealthy::Incompatible(format!( "module requires capability {missing}, which this Guardian does not provide" - )); + ))); } for hook in &config.hooks { if !info.hooks.contains(&(hook.proto() as i32)) { - return Err(format!("module does not support hook {hook:?}")); + return Err(Unhealthy::Incompatible(format!( + "module does not support hook {hook:?}" + ))); } } Ok(info) diff --git a/crates/server/src/modules/store.rs b/crates/server/src/modules/store.rs index f638c65e..32bce609 100644 --- a/crates/server/src/modules/store.rs +++ b/crates/server/src/modules/store.rs @@ -52,6 +52,14 @@ pub struct AccountParamsRow { pub updated_by: String, } +/// One row of an account, without its params: which module it names and how. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct AccountModule { + pub account_id: String, + pub module_id: String, + pub kind: ParamsKind, +} + #[derive(Debug, Clone, PartialEq, Serialize, Deserialize, utoipa::ToSchema)] pub struct HistoryEntry { pub version: u64, @@ -136,8 +144,10 @@ pub trait ModuleStore: Send + Sync { cached_version: Option, ) -> Result; - /// Every account's rows, ordered by account and position; a startup scan, not a hot path. - async fn all_account_params(&self) -> Result, String>; + /// Which module every account row names, ordered by account. A scan for the budget and + /// orphan report, never read on a request path; it carries no params, which are copied per + /// account and can be large. + async fn account_modules(&self) -> Result, String>; async fn set_layer( &self, @@ -466,11 +476,17 @@ impl ModuleStore for FsModuleStore { })) } - async fn all_account_params(&self) -> Result, String> { + async fn account_modules(&self) -> Result, String> { Ok(self.read(|tables| { - let mut rows = tables.account_params.clone(); + let mut rows: Vec<&AccountParamsRow> = tables.account_params.iter().collect(); rows.sort_by(|a, b| (&a.account_id, a.position).cmp(&(&b.account_id, b.position))); - rows + rows.into_iter() + .map(|row| AccountModule { + account_id: row.account_id.clone(), + module_id: row.module_id.clone(), + kind: row.kind, + }) + .collect() })) } diff --git a/crates/server/src/modules/testing.rs b/crates/server/src/modules/testing.rs index afe22bab..93458860 100644 --- a/crates/server/src/modules/testing.rs +++ b/crates/server/src/modules/testing.rs @@ -323,8 +323,8 @@ impl super::store::ModuleStore for RacingStore { self.inner.account_params(account_id).await } - async fn all_account_params(&self) -> Result, String> { - self.inner.all_account_params().await + async fn account_modules(&self) -> Result, String> { + self.inner.account_modules().await } async fn seed_assignment( From d3fa731b6ae5327cbf05d12689615f94aaf3a0c5 Mon Sep 17 00:00:00 2001 From: Zeljko Date: Tue, 10 Nov 2026 08:14:27 +0100 Subject: [PATCH 083/105] perf(modules): the default-module copy of a registration is one database call (#251) Every module write takes the module_state_version row lock. The copy a first registration writes held it across about ten round trips for three default modules, so registrations and operator writes queued behind each one. guardian_module_seed_assignment takes the lock, checks the account and writes its rows and history inside one statement. Local A/B on the Postgres store (600 copies of three modules): 290 to 390 copies per second before, 1750 to 3400 after; single-call p50 from about 3 ms to 0.4 ms. Table in research.md. --- .../down.sql | 1 + .../up.sql | 54 +++++++ crates/server/src/modules/postgres_store.rs | 142 +++++++++++------- .../features/251-guardian-modules/research.md | 17 +++ 4 files changed, 158 insertions(+), 56 deletions(-) create mode 100644 crates/server/migrations/2026-11-10-000001_module_seed_assignment/down.sql create mode 100644 crates/server/migrations/2026-11-10-000001_module_seed_assignment/up.sql diff --git a/crates/server/migrations/2026-11-10-000001_module_seed_assignment/down.sql b/crates/server/migrations/2026-11-10-000001_module_seed_assignment/down.sql new file mode 100644 index 00000000..64b95e2b --- /dev/null +++ b/crates/server/migrations/2026-11-10-000001_module_seed_assignment/down.sql @@ -0,0 +1 @@ +DROP FUNCTION IF EXISTS guardian_module_seed_assignment(TEXT, JSONB, TEXT, TEXT, TIMESTAMPTZ); diff --git a/crates/server/migrations/2026-11-10-000001_module_seed_assignment/up.sql b/crates/server/migrations/2026-11-10-000001_module_seed_assignment/up.sql new file mode 100644 index 00000000..41c62079 --- /dev/null +++ b/crates/server/migrations/2026-11-10-000001_module_seed_assignment/up.sql @@ -0,0 +1,54 @@ +-- The default modules a first registration copies into its account, in one call. +-- Every module write takes the module_state_version row lock, so a registration +-- that held it across a round trip per row made every other registration and +-- operator write wait for all of them. Here the lock is taken, the account is +-- checked and its rows and history are written inside one statement, so the lock +-- is held for that statement and its commit only. +-- +-- p_modules is the assignment in evaluation order: +-- [{"module_id": "...", "params": {...}}, ...]. Writes only into an account with +-- no assignment and no history, so an operator's earlier write always wins. +-- Returns the version the copy committed as, or NULL when it wrote nothing (the +-- version does not move then). +CREATE FUNCTION guardian_module_seed_assignment( + p_account_id TEXT, + p_modules JSONB, + p_operator TEXT, + p_reason TEXT, + p_changed_at TIMESTAMPTZ +) +RETURNS BIGINT +LANGUAGE plpgsql AS $$ +DECLARE + v_version BIGINT; +BEGIN + PERFORM 1 FROM module_state_version FOR UPDATE; + + IF EXISTS (SELECT 1 FROM module_account_params + WHERE account_id = p_account_id AND kind = 'assignment') + OR EXISTS (SELECT 1 FROM module_params_history + WHERE account_id = p_account_id) THEN + RETURN NULL; + END IF; + + UPDATE module_state_version SET version = version + 1 + RETURNING version INTO v_version; + + INSERT INTO module_account_params + (account_id, module_id, kind, position, params, updated_at, updated_by) + SELECT p_account_id, m.value->>'module_id', 'assignment', + (m.ordinality - 1)::INTEGER, m.value->'params', p_changed_at, p_operator + FROM jsonb_array_elements(p_modules) WITH ORDINALITY AS m(value, ordinality); + + INSERT INTO module_params_history + (version, module_id, account_id, previous_params, new_params, operator, reason, + changed_at) + SELECT v_version, m.value->>'module_id', p_account_id, 'null'::jsonb, + m.value->'params', p_operator, p_reason, p_changed_at + FROM jsonb_array_elements(p_modules) AS m(value) + WHERE m.value->'params' <> 'null'::jsonb + ORDER BY m.value->>'module_id'; + + RETURN v_version; +END; +$$; diff --git a/crates/server/src/modules/postgres_store.rs b/crates/server/src/modules/postgres_store.rs index ad7a5fb5..ac7f317d 100644 --- a/crates/server/src/modules/postgres_store.rs +++ b/crates/server/src/modules/postgres_store.rs @@ -166,6 +166,19 @@ diesel::define_sql_function! { ) -> Record<(BigInt, Nullable, Jsonb)>; } +diesel::define_sql_function! { + /// Typed so the statement is prepared once per connection: the default-module copy of a + /// first registration is one call, which holds the module state lock for that call only + /// (see the migration). + fn guardian_module_seed_assignment( + account_id: Text, + modules: Jsonb, + operator: Text, + reason: Text, + changed_at: Timestamptz, + ) -> Nullable; +} + #[async_trait] impl ModuleStore for PgModuleStore { async fn seed_instance( @@ -618,63 +631,26 @@ impl ModuleStore for PgModuleStore { return Ok(false); } let changed_at = at(change)?; + let modules = serde_json::Value::Array( + modules + .into_iter() + .map(|assigned| { + serde_json::json!({ "module_id": assigned.module_id, "params": assigned.params }) + }) + .collect(), + ); let mut conn = self.conn().await?; - let account_id = account_id.to_string(); - let written = conn - .transaction::<(), diesel::result::Error, _>(|conn| { - async move { - // The version row lock serializes every module write, so the check below - // and the insert cannot interleave with another write for this account. - let version = bump(conn).await?; - let taken: Vec = diesel::sql_query( - "SELECT 1::BIGINT AS version WHERE EXISTS (SELECT 1 FROM \ - module_account_params WHERE account_id = $1 AND kind = 'assignment') \ - OR EXISTS (SELECT 1 FROM module_params_history WHERE account_id = $1)", - ) - .bind::(&account_id) - .load(conn) - .await?; - if !taken.is_empty() { - return Err(diesel::result::Error::RollbackTransaction); - } - for (position, assigned) in modules.iter().enumerate() { - diesel::sql_query( - "INSERT INTO module_account_params \ - (account_id, module_id, kind, position, params, updated_at, updated_by) \ - VALUES ($1, $2, 'assignment', $3, $4, $5, $6)", - ) - .bind::(&account_id) - .bind::(&assigned.module_id) - .bind::(position as i32) - .bind::(&assigned.params) - .bind::(changed_at) - .bind::(change.operator) - .execute(conn) - .await?; - } - for (module_id, before, after) in assignment_changes(&[], &modules) { - append( - conn, - version, - &module_id, - Some(&account_id), - &before, - &after, - change, - changed_at, - ) - .await?; - } - Ok(()) - } - .scope_boxed() - }) - .await; - match written { - Ok(()) => Ok(true), - Err(diesel::result::Error::RollbackTransaction) => Ok(false), - Err(e) => Err(format!("seed assignment: {e}")), - } + let committed: Option = diesel::select(guardian_module_seed_assignment( + account_id, + modules, + change.operator, + change.reason, + changed_at, + )) + .get_result(&mut conn) + .await + .map_err(|e| format!("seed assignment: {e}"))?; + Ok(committed.is_some()) } async fn history( @@ -985,6 +961,60 @@ mod tests { assert!(store.account_params(&account).await.unwrap().is_empty()); } + #[tokio::test] + #[ignore = "requires Postgres; run ./scripts/test-postgres.sh"] + async fn a_default_copy_keeps_its_order_and_records_each_module() { + let url = test_database_url().await; + let store = PgModuleStore::new(build_postgres_pool_lazy(&url, 2).expect("pool")); + let run = rand::random::(); + let account = format!("0xorder{run}"); + let (second, first) = (format!("a-second-{run}"), format!("z-first-{run}")); + let before = store.version().await.unwrap(); + assert!( + store + .seed_assignment( + &account, + vec![ + Assigned { + module_id: first.clone(), + params: json!({ "limit": 1 }), + }, + Assigned { + module_id: second.clone(), + params: json!({ "limit": 2 }), + }, + ], + &change("2026-11-10T00:00:00Z"), + ) + .await + .unwrap() + ); + let version = store.version().await.unwrap(); + assert_eq!(version, before + 1, "one copy is one version"); + let rows = store.account_params(&account).await.unwrap(); + assert_eq!( + rows.iter() + .map(|row| (row.module_id.as_str(), row.position, row.kind)) + .collect::>(), + vec![ + (first.as_str(), 0, ParamsKind::Assignment), + (second.as_str(), 1, ParamsKind::Assignment), + ], + "evaluation order is the order given, not the id order" + ); + assert_eq!(rows[1].params, json!({ "limit": 2 })); + for (module, params) in [ + (&first, json!({ "limit": 1 })), + (&second, json!({ "limit": 2 })), + ] { + let history = store.history(module, None, 10).await.unwrap(); + assert_eq!(history.len(), 1); + assert_eq!(history[0].version, version); + assert_eq!(history[0].previous, serde_json::Value::Null); + assert_eq!(history[0].new, params); + } + } + #[tokio::test] #[ignore = "requires Postgres; run ./scripts/test-postgres.sh"] async fn a_conditional_write_only_replaces_the_value_it_expects() { diff --git a/speckit/features/251-guardian-modules/research.md b/speckit/features/251-guardian-modules/research.md index 18d086f8..b80ea6e8 100644 --- a/speckit/features/251-guardian-modules/research.md +++ b/speckit/features/251-guardian-modules/research.md @@ -199,6 +199,23 @@ The loadgen `state-push` scenario no longer works since the multisig push gate ( - **SC-001** holds (no catalog is one `Option` check per request) and **SC-006** holds within this machine's noise; a quiet machine or the deployed bench would bound the p99 more tightly. - Not run here: the quickstart walk-through against a local node; it needs a 0.17-line `miden-node`. +### Default-module copy at registration (2026-11-10) + +Every module write takes the `module_state_version` row lock. The copy a first registration writes held it across a transaction of ten round trips for three default modules (begin, version bump, the account check, one insert and one history row per module, commit), so registrations ran one at a time for that long, and operator writes waited behind them. The copy is now one call of `guardian_module_seed_assignment`, which takes the lock, checks the account and writes its rows and history inside one statement. + +Local A/B on the Postgres store alone: 600 copies of three default modules (32 denylist entries each), from 1, 8 and 32 tasks, against the local Postgres container, two runs per leg. This measures the store call, not a whole `/configure` request. + +| Leg | Concurrency | Copies per second | p50 | p99 | +|---|---|---|---|---| +| transaction of statements | 1 | 289, 343 | 3.2 ms, 2.7 ms | 6.7 ms, 6.5 ms | +| transaction of statements | 8 | 378, 394 | 17.0 ms, 16.4 ms | 71 ms, 62 ms | +| transaction of statements | 32 | 341, 388 | 67 ms, 60 ms | 360 ms, 324 ms | +| one function call | 1 | 2036, 2833 | 0.45 ms, 0.31 ms | 1.1 ms, 1.0 ms | +| one function call | 8 | 2591, 3397 | 1.8 ms, 1.4 ms | 47 ms, 18 ms | +| one function call | 32 | 1752, 2212 | 10.6 ms, 8.8 ms | 98 ms, 89 ms | + +The copies still serialize on the one row, so throughput does not grow with concurrency; it is five to nine times higher because the lock is held for one statement. A per-account params version would remove the shared lock (not done). The startup report no longer loads every account's params either: it reads which module each account row names (`account_modules`), and the probe loop recounts it every minute so the over-budget and orphan gauges follow operator fixes. + ### In-process custom kinds (2026-10-16) `ServerBuilder::with_module_kind` is about thirty lines on top of the existing `Registry`: the catalog, pipeline, params API and history already work for any kind. The cost is elsewhere. In process, a module shares the process that holds the acknowledgement keys, so "a module can only refuse" holds by review, not isolation; a panic would unwind through the request handler; and a timeout only fires at await points, so a blocking module ignored `timeout_ms`. Every module call now runs on its own task: a panic is a module failure under `on_error`, and the timeout holds while other runtime workers are free (a module that blocks still occupies a worker until it returns). The per-call cost is one task spawn. Open for M2c: `ServerBuilder::from_env`, so a custom build does not copy `main.rs`, and the semver commitment of publishing `guardian-server` as a library. From e97376096d9bbef51be29b5a71de363674c9e3a9 Mon Sep 17 00:00:00 2001 From: Zeljko Date: Tue, 10 Nov 2026 08:14:28 +0100 Subject: [PATCH 084/105] feat(infra): a module catalog path and module secrets on the ECS stack (#251) - guardian_modules_config injects GUARDIAN_MODULES_CONFIG, the catalog's path inside the image; the catalog travels in an image built from the published one. - guardian_module_secret_names grants the task runtime role GetSecretValue on exactly those secrets and sets GUARDIAN_MODULE_SECRET_PROVIDER=aws. Both are empty by default, which leaves the stack as it was. Validated with terraform validate; not applied. --- docs/SERVER_AWS_DEPLOY.md | 39 +++++++++++++++++++++++++++++++++++++++ docs/runbooks/secrets.md | 8 +++++--- infra/README.md | 2 ++ infra/ecs.tf | 12 ++++++++++++ infra/iam.tf | 25 +++++++++++++++++++++++++ infra/variables.tf | 26 ++++++++++++++++++++++++++ 6 files changed, 109 insertions(+), 3 deletions(-) diff --git a/docs/SERVER_AWS_DEPLOY.md b/docs/SERVER_AWS_DEPLOY.md index 217297a2..f94afc0b 100644 --- a/docs/SERVER_AWS_DEPLOY.md +++ b/docs/SERVER_AWS_DEPLOY.md @@ -301,6 +301,45 @@ aws_region = "us-east-1" # cloudflare_api_token = "..." ``` +## Policy modules + +Policy modules ([guide](./guides/policy-modules/README.md)) are off unless the +server is given a catalog. The catalog is a file the server reads once at +startup, and the published image carries none, so on this stack it travels in +the image: + +1. Build an image from the published one that copies your catalog in, push it + to the stack's ECR repository and deploy it as the server image: + + ```dockerfile + FROM ghcr.io/openzeppelin/guardian: + COPY modules.toml /etc/guardian/modules.toml + ``` + +2. Point the server at it and name the secrets the catalog references: + + ```hcl + guardian_modules_config = "/etc/guardian/modules.toml" + guardian_module_secret_names = ["guardian/modules/screening-token"] + ``` + +`guardian_modules_config` sets `GUARDIAN_MODULES_CONFIG`. +`guardian_module_secret_names` grants the task runtime role +`secretsmanager:GetSecretValue` on exactly those secrets and sets +`GUARDIAN_MODULE_SECRET_PROVIDER=aws`. Create each secret before the deploy +that enables its instance ([`runbooks/secrets.md`](./runbooks/secrets.md#policy-module-secrets)): +an enabled instance whose secret cannot be read stops startup. + +The catalog is deploy configuration. A change to it is a new image and a new +task definition, which is the review bar wanted for adding, removing or +reconfiguring an instance; params, enabled flags and account assignments +change at run time through the [operator API](./DASHBOARD.md#policy-modules) +and live in the database. A remote module must be reachable from the task's +subnets; the stack does not deploy modules. + +A catalog that is set but empty, or declares no module, stops startup. To run +without modules again, clear `guardian_modules_config`. + ## Database TLS verification By default the server `DATABASE_URL` uses `sslmode=require` — the connection is diff --git a/docs/runbooks/secrets.md b/docs/runbooks/secrets.md index 38a0d94a..5bb08204 100644 --- a/docs/runbooks/secrets.md +++ b/docs/runbooks/secrets.md @@ -545,9 +545,11 @@ server reads them once, when it creates the instances, through the provider [remote module guide](../guides/policy-modules/remote.md#credentials). - **AWS (`aws`).** A name is a Secrets Manager secret id holding a secret - string. The reference Terraform does not create these secrets or grant the - task access to them: create each secret, then grant the ECS task runtime role - `secretsmanager:GetSecretValue` on it before enabling the instance. + string. The reference Terraform does not create these secrets: create each + one, then list its name in `guardian_module_secret_names`, which grants the + ECS task runtime role `secretsmanager:GetSecretValue` on it + ([deploy guide](../SERVER_AWS_DEPLOY.md#policy-modules)), before enabling + the instance. - **Files (`file`).** A name is a relative path below `GUARDIAN_MODULE_SECRET_DIR` (the catalog's directory when unset). The server refuses a file readable by group or others, as it does for ACK key files; a diff --git a/infra/README.md b/infra/README.md index b8e22f28..38a8d492 100644 --- a/infra/README.md +++ b/infra/README.md @@ -257,6 +257,8 @@ aws ecr delete-repository --repository-name "$ECR_REPO_NAME" --force --region "$ | `guardian_proving_enabled` | `null` | Overrides `GUARDIAN_PROVING_ENABLED`; `false` refuses execution requests while executions in flight still settle | | `guardian_tx_prover_timeout_secs` | `null` | Overrides `GUARDIAN_TX_PROVER_TIMEOUT_SECS` (server default 300) | | `guardian_execution_lease_secs` | `null` | Overrides `GUARDIAN_EXECUTION_LEASE_SECS` (server default 120, at most 3600) | +| `guardian_modules_config` | `""` | Absolute path of the policy module catalog inside the server image, injected as `GUARDIAN_MODULES_CONFIG`. Empty runs without policy modules. The published image carries no catalog, so deploy an image built from it that copies yours in | +| `guardian_module_secret_names` | `[]` | Secrets Manager secret names the catalog references. The task runtime role gets `secretsmanager:GetSecretValue` on each, and `GUARDIAN_MODULE_SECRET_PROVIDER=aws` is set. Needs `guardian_modules_config`; the secrets are created and rotated by the operator | | `guardian_execution_reconcile_interval_secs` | `null` | Overrides `GUARDIAN_EXECUTION_RECONCILE_INTERVAL_SECS` (server default 30; must stay below the lease) | | `guardian_execution_expiration_horizon_blocks` | `null` | Overrides `GUARDIAN_EXECUTION_EXPIRATION_HORIZON_BLOCKS` (server default 512, at least 256) | | `guardian_execution_max_concurrent` | `null` | Overrides `GUARDIAN_EXECUTION_MAX_CONCURRENT`, a memory safety bound on executions one task holds at once (server default 64, at least 1); raise it only with `server_memory` | diff --git a/infra/ecs.tf b/infra/ecs.tf index ec42176f..f4bda514 100644 --- a/infra/ecs.tf +++ b/infra/ecs.tf @@ -312,6 +312,18 @@ resource "aws_ecs_task_definition" "server" { value = tostring(var.guardian_execution_lease_secs) } ] : [], + var.guardian_modules_config != "" ? [ + { + name = "GUARDIAN_MODULES_CONFIG" + value = var.guardian_modules_config + } + ] : [], + length(var.guardian_module_secret_names) > 0 ? [ + { + name = "GUARDIAN_MODULE_SECRET_PROVIDER" + value = "aws" + } + ] : [], var.guardian_execution_reconcile_interval_secs != null ? [ { name = "GUARDIAN_EXECUTION_RECONCILE_INTERVAL_SECS" diff --git a/infra/iam.tf b/infra/iam.tf index ba711945..377f2412 100644 --- a/infra/iam.tf +++ b/infra/iam.tf @@ -168,6 +168,31 @@ resource "aws_iam_role_policy" "ecs_task_storage_encryption_secret" { }) } +# Secrets the policy module catalog names. Secrets Manager appends a hyphen and six characters +# to a secret's name in its ARN, which the pattern below matches for exactly the named secrets. +resource "aws_iam_role_policy" "ecs_task_module_secrets" { + count = length(var.guardian_module_secret_names) > 0 ? 1 : 0 + + name = "${var.stack_name}-ecs-task-module-secrets" + role = aws_iam_role.ecs_task.id + + policy = jsonencode({ + Version = "2012-10-17" + Statement = [ + { + Effect = "Allow" + Action = [ + "secretsmanager:GetSecretValue" + ] + Resource = [ + for name in var.guardian_module_secret_names : + "arn:aws:secretsmanager:${var.aws_region}:${data.aws_caller_identity.current.account_id}:secret:${name}-??????" + ] + } + ] + }) +} + resource "aws_iam_role_policy" "ecs_task_operator_public_keys_secret" { count = var.guardian_operator_public_keys_secret_arn != "" || local.managed_operator_public_keys_secret_enabled ? 1 : 0 diff --git a/infra/variables.tf b/infra/variables.tf index 75ac8df0..68a4ec8f 100644 --- a/infra/variables.tf +++ b/infra/variables.tf @@ -1015,6 +1015,32 @@ variable "guardian_tx_prover_timeout_secs" { } } +variable "guardian_modules_config" { + description = "Path of the policy module catalog inside the server image, injected as GUARDIAN_MODULES_CONFIG. Empty runs without policy modules. The published image carries no catalog: build an image FROM it that copies yours in, and deploy that image. The catalog is deploy configuration, so a change to it is a new image and a new task definition." + type = string + default = "" + validation { + condition = var.guardian_modules_config == "" || startswith(var.guardian_modules_config, "/") + error_message = "guardian_modules_config must be an absolute path inside the image." + } +} + +variable "guardian_module_secret_names" { + description = "Secrets Manager secret names the policy module catalog references (auth.token_secret, tls.client_cert_secret, tls.client_key_secret and $secret params). The ECS task runtime role is granted secretsmanager:GetSecretValue on each, and GUARDIAN_MODULE_SECRET_PROVIDER is set to aws so the dev stage reads them the same way as prod. The secrets themselves are created and rotated by the operator." + type = list(string) + default = [] + validation { + condition = alltrue([ + for name in var.guardian_module_secret_names : can(regex("^[A-Za-z0-9/_+=.@-]{1,512}$", name)) + ]) + error_message = "Each guardian_module_secret_names entry is a secret name of 1 to 512 letters, digits and /_+=.@- characters, not an ARN." + } + validation { + condition = length(var.guardian_module_secret_names) == 0 || var.guardian_modules_config != "" + error_message = "guardian_module_secret_names needs guardian_modules_config: without a catalog nothing reads the secrets." + } +} + variable "guardian_execution_lease_secs" { description = "Optional override for GUARDIAN_EXECUTION_LEASE_SECS, the execution lease length (server default 120, at most 3600)" type = number From d6d28d40d95d4d5c2c16abe44eb55316d51573ee Mon Sep 17 00:00:00 2001 From: Zeljko Date: Tue, 10 Nov 2026 08:14:28 +0100 Subject: [PATCH 085/105] docs(modules): architecture, SDK guide, backup and compatibility notes (#251) - services.md: the modules subsystem and the three handlers that call it. - MULTISIG_SDK.md: policy listing, the proposal check and typed refusals in both SDKs. - backup-restore.md: module state is in the database; the catalog and module secrets are not; what a restore rewinds. - MIDEN_COMPATIBILITY.md: new error codes and the Rust enum changes. - Configuration, troubleshooting, runbook and RFC: the probe's effect on the breaker and the gauge recount; id lengths in the basic-policy guide and examples. --- docs/CONFIGURATION.md | 2 +- docs/MIDEN_COMPATIBILITY.md | 29 ++++++++++++++ docs/MULTISIG_SDK.md | 38 +++++++++++++++++++ docs/TROUBLESHOOTING.md | 9 ++++- docs/architecture/services.md | 37 ++++++++++++++++++ docs/guides/policy-modules/built-in.md | 7 +++- docs/guides/policy-modules/custom.md | 12 ++++-- docs/rfcs/0002-guardian-modules.md | 4 +- docs/runbooks/backup-restore.md | 23 +++++++++++ docs/runbooks/policy-modules.md | 9 +++-- packages/guardian-operator-client/README.md | 4 +- .../contracts/catalog-config.md | 2 +- .../251-guardian-modules/quickstart.md | 4 +- 13 files changed, 161 insertions(+), 19 deletions(-) diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md index 0ea05e6e..df4516fd 100644 --- a/docs/CONFIGURATION.md +++ b/docs/CONFIGURATION.md @@ -413,7 +413,7 @@ modules guide](./guides/policy-modules/README.md). | `GUARDIAN_MODULE_EVALUATION_BUDGET_MS` | `1000` | Time spent in module calls for one hook invocation (request assembly is not charged). Each call gets the smaller of its `timeout_ms` and what is left; once spent, later modules count as timed out and their `on_error` applies. In the prod stage startup refuses a catalog whose `all` and `default` instances, enabled or not, exceed it at any hook, and a budget not below the execution reservation lease; account assignments and layers that would raise an account's cost over it are refused at write time, while writes that keep or lower the cost pass. Client and SDK request timeouts must exceed it, or a slow approval arrives after the client retried. | | `GUARDIAN_MODULE_REQUEST_MAX_BYTES` | `2097152` (2 MiB) | Largest encoded request sent to a module. A larger one is a module failure and is not sent; its `on_error` applies. | | `GUARDIAN_MODULE_BREAKER_FAILURES` | `5` | Consecutive failures (timeouts, transport errors, malformed decisions) that open an instance's circuit breaker on a replica. While open the module is not called and its `on_error` applies at once. A deny is an answer and resets the count, and so is a request the module rejects as one it cannot judge (its `on_error` still applies to that request). A timeout that earlier modules caused by using up the budget does not count, and dry-run checks neither count nor reset. | -| `GUARDIAN_MODULE_PROBE_INTERVAL_MS` | `5000` | Interval of the `Describe` health probe of every enabled instance. A successful probe moves an open breaker to half-open, where one call at a time is sent as the trial and decides, while other requests are treated as while open; the result is `guardian_module_up`. | +| `GUARDIAN_MODULE_PROBE_INTERVAL_MS` | `5000` | Interval of the `Describe` health probe of every enabled instance. A successful probe moves an open breaker to half-open, where one call at a time is sent as the trial and decides, while other requests are treated as while open; the result is `guardian_module_up`. A probe that gets no answer counts as a failed call toward the breaker. A probe that finds the module answering with a protocol version, a required capability or a hook set this Guardian cannot work with opens the breaker at once and keeps it open until a probe passes. | | `GUARDIAN_MODULE_PARAMS_MAX_BYTES` | `65536` (64 KiB) | Largest params value one write may store (global params, an account layer or an assignment entry), measured as compact JSON with sorted keys. A larger write is refused with `invalid_input` before the module is called, and a larger catalog seed refuses startup, so no params value can push every request for an account over `GUARDIAN_MODULE_REQUEST_MAX_BYTES`. | | `GUARDIAN_MODULE_SECRET_PROVIDER` | `aws` in the prod stage, `file` otherwise | Where the secrets a module catalog names (`auth.token_secret`, `tls.client_cert_secret`, `tls.client_key_secret`, `$secret` params) are read from, once at startup. `file`: one file per secret below `GUARDIAN_MODULE_SECRET_DIR`, readable by its owner only (`0600`). `aws`: AWS Secrets Manager secret ids, with `AWS_REGION` set. Not consulted when the catalog names no secret. | | `GUARDIAN_MODULE_SECRET_DIR` | the catalog's directory | Directory of the `file` secrets provider; a secret name is a relative path below it. | diff --git a/docs/MIDEN_COMPATIBILITY.md b/docs/MIDEN_COMPATIBILITY.md index af86fc67..1cc5c608 100644 --- a/docs/MIDEN_COMPATIBILITY.md +++ b/docs/MIDEN_COMPATIBILITY.md @@ -717,6 +717,35 @@ only; wallet-signed requests, session grants and logout are unchanged. before `/configure` required a multisig keeps being served, but any `/configure` for it is refused with `invalid_input`. +### Policy modules (0.19.0) + +Policy modules are off unless the operator configures a catalog, so a +deployment without one behaves as before. With one: + +- **New error codes.** `GUARDIAN_MODULE_DENIED` (403, final) and + `GUARDIAN_MODULE_UNAVAILABLE` (503, retryable) on proposal creation, delta + push and registration; `GUARDIAN_EXECUTION_MODULE_DENIED` and + `GUARDIAN_EXECUTION_MODULE_UNAVAILABLE` as Guardian execution failure codes. + SDKs from 0.18.x surface the request codes as an untyped server error and + reject the two execution codes as unknown. +- **Breaking for Rust callers.** + - `ExecutionFailureCode` is no longer `Copy`, and has the two new variants + `ModuleDenied(ModuleDenial)` and `ModuleUnavailable { module }`. + - `MultisigError` has the new variants `ModuleDenied` and + `ModuleUnavailable`. A refusal that used to arrive as `GuardianServer` or + `GuardianProposalRefused` now arrives as one of them, so a `match` that + handled those two variants needs the new arms. + - Neither enum is `#[non_exhaustive]`, so an exhaustive `match` over either + stops compiling until the new variants are handled. +- **New calls.** `get_policies` / `getPolicies`, `check_transaction` / + `checkTransaction`, session operations 14 (`GetPolicies`) and 15 + (`CheckDeltaProposal`), and the operator client's module routes and the + `policies:write_global` and `modules:disable` permissions. An operator client + from 0.18.x fails to parse a session that holds either permission. +- **Module authors.** `guardian.module.v1` is not frozen until the first + published `guardian-module-sdk` release; see + [RFC 0002](./rfcs/0002-guardian-modules.md), section 7. + ### Open upstream items The facts below change independently of this repository. This list is the one diff --git a/docs/MULTISIG_SDK.md b/docs/MULTISIG_SDK.md index d0092b65..b06ee7c4 100644 --- a/docs/MULTISIG_SDK.md +++ b/docs/MULTISIG_SDK.md @@ -793,6 +793,44 @@ report a refusal as their usual error: `ClientError` in Rust and a `GuardianHttp `rawCode` is the wire string in TypeScript. See [`TROUBLESHOOTING.md`](./TROUBLESHOOTING.md#guardian-execution) for every code. +### Policy Modules + +A Guardian can run policy modules (spending caps, recipient and signer rules, +screening) that refuse a proposal at creation, a transaction at approval, or +an account at registration. Both SDKs expose the same three things. + +**The rules the operator discloses.** `get_policies()` in Rust and +`getPolicies()` in TypeScript list the modules that apply to the account, as +far as the operator chose to disclose them: the module id, its hooks and a +description, and its params only where the catalog allows it. + +**A check before proposing.** `check_transaction(transaction_type)` in Rust and +`checkTransaction({ type, ... })` in TypeScript build the transaction as the +matching create call would and ask the Guardian whether it would be accepted. +Nothing is stored, no proposal slot is taken and no signature is sent. The +result's `complete` is false when a module that opts out of checks was +skipped. The answer is advisory, since approval still decides, and checks are +rate limited per account and signer. The transaction types each SDK can check +differ today: TypeScript checks every typed creator and `custom` but not a +Guardian switch; Rust checks every `TransactionType` except custom. + +**Typed refusals.** A refusal from a check, at creation, at push or at +registration carries the same information in both SDKs: + +| | Rust | TypeScript | +|---|---|---| +| Denied (final) | `MultisigError::ModuleDenied { module, reason_code, layer, client_message }` | `GuardianHttpError`, `error.moduleRefusal()` with `kind: 'denied'` | +| Could not decide (retryable) | `MultisigError::ModuleUnavailable { module }` | `error.moduleRefusal()` with `kind: 'unavailable'` | + +A denial from an instance the operator keeps generic names no module and +carries only the reason code `policy_denied`. Neither SDK retries a refusal +on its own. A Guardian execution refused by a module ends failed with +`GUARDIAN_EXECUTION_MODULE_DENIED` or `GUARDIAN_EXECUTION_MODULE_UNAVAILABLE`, +and the proposal is kept. In Rust, `propose_with_fallback` falls back to an +offline proposal on a module refusal for transaction types that can execute +without the Guardian, which is how an account leaves a Guardian whose modules +refuse it. + ### Side-channel (offline) workflow For moving a proposal between cosigners as a document instead of through diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md index 6bf73129..69620fc7 100644 --- a/docs/TROUBLESHOOTING.md +++ b/docs/TROUBLESHOOTING.md @@ -878,8 +878,13 @@ Guardian execution ends `failed` with `GUARDIAN_EXECUTION_MODULE_DENIED` or 3. **Module health.** `guardian_module_up` is 0 after a failed `Describe` health probe (`Policy module health probe failed` at `warn`), and `guardian_module_circuit_open` is 1 while this replica skips the module - after `GUARDIAN_MODULE_BREAKER_FAILURES` consecutive failures; the next - successful probe lets a call through again. A module that is up but slow + after `GUARDIAN_MODULE_BREAKER_FAILURES` consecutive failures (failed + calls and unanswered probes both count); the next successful probe lets a + call through again. `Policy module is incompatible with this Guardian` at + `warn` means the module answered `Describe` with a protocol version, + capability or hook set the Guardian cannot use, usually after the module + was redeployed: its circuit opens at once and stays open until the module + is fixed or the instance is reconfigured. A module that is up but slow shows in `guardian_module_evaluate_duration_seconds` and as `timed out` failures: compare with the instance's `timeout_ms` and `GUARDIAN_MODULE_EVALUATION_BUDGET_MS`. diff --git a/docs/architecture/services.md b/docs/architecture/services.md index 8a303fe3..2c022d89 100644 --- a/docs/architecture/services.md +++ b/docs/architecture/services.md @@ -289,6 +289,43 @@ It piggybacks on the same Postgres backend as the rest of the server but authenticates operators through Falcon-signed challenges rather than the per-account credentials used by Guardian's primary API. +### Policy modules — `modules/` + +A hook pipeline the server consults before it approves anything +([RFC 0002](../rfcs/0002-guardian-modules.md), +[guide](../guides/policy-modules/README.md)). It is off unless +`GUARDIAN_MODULES_CONFIG` names a catalog file, and `AppState.modules` is then +the one [`ModulePipeline`](../../crates/server/src/modules/pipeline.rs) every +request path uses. + +| File | Purpose | +|---|---| +| [`catalog.rs`](../../crates/server/src/modules/catalog.rs) | Parses the catalog: instances, kinds, scopes (`all`, `default`, `assigned`), hooks, `on_error`, disclosure. Read once at startup. | +| [`registry.rs`](../../crates/server/src/modules/registry.rs), [`grpc_kind.rs`](../../crates/server/src/modules/grpc_kind.rs) | Turns catalog entries into module instances: in-process kinds registered on the builder, or the remote `grpc` kind. Runs the startup and health checks (`Describe`, params validation). | +| [`secrets.rs`](../../crates/server/src/modules/secrets.rs) | Resolves the tokens, client certificates and `$secret` params a catalog names, from AWS Secrets Manager or owner-only files. | +| [`store.rs`](../../crates/server/src/modules/store.rs), [`postgres_store.rs`](../../crates/server/src/modules/postgres_store.rs) | The mutable state: enabled flags, global params, account layers and assignments, params history, one version that every write moves. Files on a filesystem build, tables on Postgres. | +| [`pipeline.rs`](../../crates/server/src/modules/pipeline.rs) | Plans which instances run for an account at a hook (one store read) and runs them in order under the evaluation budget; applies `on_error`; returns what the evaluation ran with. | +| [`breaker.rs`](../../crates/server/src/modules/breaker.rs), [`limits.rs`](../../crates/server/src/modules/limits.rs) | Per-instance circuit breakers fed by calls and by the `Describe` probe; the budget, size caps and probe interval. | +| [`request.rs`](../../crates/server/src/modules/request.rs), [`network/miden/module_views.rs`](../../crates/server/src/network/miden/module_views.rs) | Builds what a module receives: account views before and after, the transaction projection, the registration state. Views are cached by state commitment. | +| [`admin.rs`](../../crates/server/src/modules/admin.rs), [`api/dashboard_modules.rs`](../../crates/server/src/api/dashboard_modules.rs) | Operator writes and views behind `/dashboard/modules*` and `/dashboard/accounts/{id}/modules*`. | +| [`disclosure.rs`](../../crates/server/src/modules/disclosure.rs), [`check_limit.rs`](../../crates/server/src/modules/check_limit.rs) | What cosigners may see (`GET /policies`) and the rate limit of dry-run checks. | + +Three service handlers call it, each before its write: + +- `ack_delta_internal.rs` runs `before_transaction_approved` inside + `acknowledge_applied`, the only place an acknowledgement is signed, so both + `push_delta` and the Guardian execution worker pass through it. The record + of the evaluation is stored with the delta (`metadata.modules`). +- `push_delta_proposal.rs` runs `before_proposal_created` before a proposal is + stored, and the dry-run check (`POST /delta/proposal/check`) through the + same path without storing. +- `configure_account.rs` runs `before_account_registered` on every + `/configure`, and copies the `default` instances into a new account. + +Module code never holds the acknowledgement key and can only answer allow or +deny; a module that fails follows its instance's `on_error` (deny unless the +catalog says otherwise). + ## Consumers ```mermaid diff --git a/docs/guides/policy-modules/built-in.md b/docs/guides/policy-modules/built-in.md index 0dd85780..41d2ebd2 100644 --- a/docs/guides/policy-modules/built-in.md +++ b/docs/guides/policy-modules/built-in.md @@ -12,8 +12,11 @@ id (faucet, recipient, signer commitment, code commitment) in the `0x` hex form the Guardian reports, not as a bech32 address: params with another form are refused, since such an id would never match and its rule would not apply. So is anything else that is not hex digits after `0x`, such as a placeholder left -in an example catalog. Case does not matter, and a cap that names the same -faucet twice in different case is refused. +in an example catalog, and an id of the wrong length: a faucet or a recipient +is an account id of 30 hex digits, a signer or code commitment is 64, so an id +cut short when it was pasted, or an account id where a commitment belongs, is +caught when the params are validated. Case does not matter, and a cap that +names the same faucet twice in different case is refused. A param that only modifies another is refused without it: `deny_unknown_recipients` needs `recipient_denylist`, `signer_check` needs a diff --git a/docs/guides/policy-modules/custom.md b/docs/guides/policy-modules/custom.md index a2462ce3..3f924531 100644 --- a/docs/guides/policy-modules/custom.md +++ b/docs/guides/policy-modules/custom.md @@ -249,8 +249,8 @@ use guardian_module_sdk::conformance::Suite; #[tokio::test] async fn note_policy_conforms() { Suite::new(NotePolicy) - .request("one payment", one_payment()) - .request("two payments", two_payments()) + .allows("one payment", one_payment()) + .denies_with("two payments", two_payments(), "too_many_payment_notes") .valid_params(serde_json::json!({ "max_payment_notes": 1 })) .invalid_params(serde_json::json!({ "max_notes": 1 })) .run() @@ -264,8 +264,12 @@ params validate the same over both transports and that normalized params validate to themselves, that every request gets the same answer in process and over gRPC, repeated, in reverse order and concurrently (so `evaluate` keeps no state), that every deny has a valid `reason_code` and a plain `client_message` -of at most 256 characters, that one instance's token is refused for another, -and that a request at the 2 MiB size cap goes through. A module written in +of at most 256 characters, that each request is answered as the suite states +(`allows`, `denies`, `denies_with` a reason code, or `fails` for a request the +module cannot judge), that one instance's token is refused for another, +and that a request at the 2 MiB size cap goes through. A suite needs at least +one request the module must deny: a module that allows everything answers +consistently too, so consistency alone does not conform. A module written in another language can port these cases to its own tests. `note-policy` and `basic-policy` run it in [`tests/conformance.rs`](../../../crates/guardian-module-sdk/tests/conformance.rs). diff --git a/docs/rfcs/0002-guardian-modules.md b/docs/rfcs/0002-guardian-modules.md index a5352362..08fcd2a8 100644 --- a/docs/rfcs/0002-guardian-modules.md +++ b/docs/rfcs/0002-guardian-modules.md @@ -1024,7 +1024,7 @@ Without a breaker, a module that is down costs its full `timeout_ms` on every re - **Open**: `evaluate` is not called; the module is treated as failed for every account and its `on_error` applies at once, so a fail-closed module refuses with `GUARDIAN_MODULE_UNAVAILABLE` without waiting and a fail-open module is skipped. - **Half-open**: a successful health probe moves an open breaker here. One real evaluation at a time is sent as the trial, and requests arriving meanwhile, and every dry-run check, are treated as while open; an answer closes the breaker, a failure opens it again, and a trial that never reports back (its request was dropped) is replaced at the next successful probe. -The health probe is a `Describe` call every `GUARDIAN_MODULE_PROBE_INTERVAL_MS` (default 5000) for every enabled instance, open breaker or not, under the instance's `timeout_ms`. It sets `guardian_module_up{module}`, so an outage raises an alarm before traffic finds it, and it also detects a module whose `protocol_version` changed under a running Guardian (treated as a failure). A module receives about one `Describe` per instance per replica every interval, so it answers `Describe` from memory, without calling a vendor or a database. Breaker state is per replica and in memory: replicas converge independently within a few requests, and nothing about it is stored. Until they do, a fail-open instance can be skipped on one replica and called on another; `failed_open` in the evaluation trace records each skip (section 2.2). `guardian_module_circuit_open{module}` is exported, and `GET /dashboard/modules` shows the answering replica's state. Notify delivery is unaffected; it has its own retry with backoff (section 3.3). In-process kinds go through the same breaker, so a kind that calls a vendor API behaves like a remote one. +The health probe is a `Describe` call every `GUARDIAN_MODULE_PROBE_INTERVAL_MS` (default 5000) for every enabled instance, open breaker or not, under the instance's `timeout_ms`. It sets `guardian_module_up{module}`, so an outage raises an alarm before traffic finds it, and it feeds the breaker: a probe that gets no answer counts as a failed call, and a probe that finds the module answering with a protocol version, a required capability or a hook set this Guardian cannot work with (a module redeployed under a running Guardian) opens the breaker at once and keeps it open until a probe passes, since that module's decisions cannot be trusted either. A module receives about one `Describe` per instance per replica every interval, so it answers `Describe` from memory, without calling a vendor or a database. Breaker state is per replica and in memory: replicas converge independently within a few requests, and nothing about it is stored. Until they do, a fail-open instance can be skipped on one replica and called on another; `failed_open` in the evaluation trace records each skip (section 2.2). `guardian_module_circuit_open{module}` is exported, and `GET /dashboard/modules` shows the answering replica's state. Notify delivery is unaffected; it has its own retry with backoff (section 3.3). In-process kinds go through the same breaker, so a kind that calls a vendor API behaves like a remote one. --- @@ -1205,7 +1205,7 @@ None. Questions resolved in earlier revisions are kept below with their answers. | Revision | Date | Changes | |---|---|---| -| 32 | 2026-11-10 | review of the M2a implementation. Protocol version 1 reopened (section 7): `Decision.allow` and the `decision.effect` capability removed, a decision without an effect is a module failure (section 3.5); `MidenTransaction.reference_block` and `expiration_block` replaced by `bound_block`, `expiration_delta` and `approval_expiration_block`, and `nonce_delta` made unsigned (section 3.1); `network_id` is the Guardian's configured network, not the account's registered one (section 3.1); `RegistrationSubject.initial_state` is sent; `tx_fee` is set only while the fee note carries no more of the fee asset than a transaction can owe, 64 times the chain's verification base fee, and for no note on a chain that charges nothing (section 3.1). Breaker: requests a module rejects do not count, a module whose timeout is the whole budget can open it, half-open sends one trial at a time, dry-run checks neither probe nor close it (section 4.4). Fail-open skips at proposal creation and registration, where no delta is signed, are recorded as `modules.failed_open` audit events; operator writes are audited with the params version they committed as (section 2.2). Body corrected to the implementation: metric names, the fixed 1000 ms timeout cap, params encoding, the `circuit_open` failure kind | +| 32 | 2026-11-10 | review of the M2a implementation. Protocol version 1 reopened (section 7): `Decision.allow` and the `decision.effect` capability removed, a decision without an effect is a module failure (section 3.5); `MidenTransaction.reference_block` and `expiration_block` replaced by `bound_block`, `expiration_delta` and `approval_expiration_block`, and `nonce_delta` made unsigned (section 3.1); `network_id` is the Guardian's configured network, not the account's registered one (section 3.1); `RegistrationSubject.initial_state` is sent; `tx_fee` is set only while the fee note carries no more of the fee asset than a transaction can owe, 64 times the chain's verification base fee, and for no note on a chain that charges nothing (section 3.1). Breaker: requests a module rejects do not count, a module whose timeout is the whole budget can open it, half-open sends one trial at a time, dry-run checks neither probe nor close it (section 4.4). Fail-open skips at proposal creation and registration, where no delta is signed, are recorded as `modules.failed_open` audit events; operator writes are audited with the params version they committed as (section 2.2). A health probe that finds a module incompatible opens its breaker at once and one that gets no answer counts as a failed call (section 4.4). Body corrected to the implementation: metric names, the fixed 1000 ms timeout cap, params encoding, the `circuit_open` failure kind | | 31 | 2026-11-09 | failures of dry-run checks do not count toward the circuit breaker, since a cosigner sends them without anyone's signature (section 4.4); the per-account budget check refuses only writes that raise an over-budget cost (section 4.3); `GUARDIAN_MODULE_UNAVAILABLE` and `GUARDIAN_EXECUTION_MODULE_UNAVAILABLE` omit `module` for an instance whose denials are generic (section 4.1); `metadata.modules` is kept out of client delta responses (section 2.2). `OutputNote.tx_fee` set only for the fee note `pay_fee` creates (section 3.1): the only `TX_FEE` note, with the derived serial number and one asset of the chain's fee faucet. Revisions 20 to 30 set it for any note with the `TX_FEE` script, which a transaction script can create with any assets, so the flag let funds past every `basic-policy` rule. No wire change; the field's meaning is narrowed | | 30 | 2026-11-09 | the secrets backend named: `GUARDIAN_MODULE_SECRET_PROVIDER` selects AWS Secrets Manager (the prod default) or owner-only files below `GUARDIAN_MODULE_SECRET_DIR`, read once when the instances are created; a secret that cannot be read fails creation, with the enabled/disabled rule of section 2.2. Field names fixed as `auth.token_secret`, `tls.client_cert_secret` and `tls.client_key_secret`; a secret name is 1 to 512 characters of letters, digits and `/_+=.@-`, and a `$secret` object has no other key (section 2.2). In-process factories read `$secret` values from `ModuleInstanceConfig::secret`. No protocol change | | 29 | 2026-11-09 | M2a implementation of `scope = default`: the copy is written right after the claim, only into an account with no assignment and no assignment history, under the module state lock, instead of in the claim's transaction on Postgres and before the claim on the filesystem; a crash in between is repaired by the unfinished-claim retry, so both backends follow one rule and no transaction spans the metadata and module stores (section 2.3). No protocol change | diff --git a/docs/runbooks/backup-restore.md b/docs/runbooks/backup-restore.md index aa4801ba..d6574763 100644 --- a/docs/runbooks/backup-restore.md +++ b/docs/runbooks/backup-restore.md @@ -36,6 +36,19 @@ What it does **not** back up: encryption is enabled, a database backup without the key is ciphertext: keep an out-of-band copy of the key secret per [`secrets.md`](./secrets.md). +- **The policy module catalog and module secrets.** The catalog file + (`GUARDIAN_MODULES_CONFIG`) is deploy configuration, not database content: + keep it in the deploy repository, where the catalog hash recorded with each + signed delta finds the exact version. Module tokens and client keys live in + Secrets Manager under the names the catalog gives them and are not recreated + by Terraform. + +Policy module state is in the database, so the backups above cover it: which +instances are enabled, their global params, each account's layers and +assignments, and the params history (`module_instances`, +`module_account_params`, `module_params_history`, `module_state_version`). +A filesystem build keeps the same state in `module_state.json` under +`GUARDIAN_MODULES_STATE`; back that directory up with the metadata directory. ## Verify backups (do this now, not during an incident) @@ -309,6 +322,16 @@ failing verification. A device holding the account re-onboards via other cosigner devices then sync from the guardian. Accounts with no post-restore-point activity are unaffected. +Policy module state rewinds with the rest. Operator writes made after the +restore point are gone: a disable or enable, a params change, an account's +layer or assignment. Compare `GET /dashboard/modules` and the params history +with the audit log of the lost window (the log fallback keeps the events the +database lost) and repeat the writes that should stand, with a reason that +references the restore. An account that re-registers after the restore is a +first registration again, so it receives the current `default` modules, not +the assignment it had. Start the restored server with the same catalog file +as before; a different one changes which instances are declared. + ## Logical backups (optional) For copies that live outside the AWS account (offline archives, cross-region diff --git a/docs/runbooks/policy-modules.md b/docs/runbooks/policy-modules.md index ef357bb1..53e20622 100644 --- a/docs/runbooks/policy-modules.md +++ b/docs/runbooks/policy-modules.md @@ -58,8 +58,9 @@ Symptoms: clients get `503 GUARDIAN_MODULE_UNAVAILABLE` with `meta.module` `guardian_module_up{module}` is 0; `Policy module health probe failed` and `Policy module failed; refusing` at `warn`; `guardian_module_circuit_open{module}` is 1 once a replica has seen -`GUARDIAN_MODULE_BREAKER_FAILURES` (5) failures in a row (dry-run checks do not -count), after which the +`GUARDIAN_MODULE_BREAKER_FAILURES` (5) failures in a row (failed calls and +unanswered probes count, dry-run checks do not), or at once when a probe finds +the module incompatible with this Guardian, after which the module is skipped without waiting for its timeout. 1. Check the module itself (its process, endpoint, certificate, token). A @@ -133,7 +134,9 @@ Symptoms: `timed out` failures, the p99 of - `guardian_module_over_budget_accounts` counts accounts whose modules could exceed the budget (logged at startup with their worst hook). Remove assignments or account layers from those accounts, or lower the - instances' `timeout_ms` with a deploy. + instances' `timeout_ms` with a deploy. The count, like + `guardian_module_orphaned_assignments`, is taken again every minute, so it + drops within a minute of the fix. - Raising `GUARDIAN_MODULE_EVALUATION_BUDGET_MS` needs a restart and must stay below the execution reservation lease (the prod stage refuses to start otherwise), and client request timeouts must exceed it. diff --git a/packages/guardian-operator-client/README.md b/packages/guardian-operator-client/README.md index 40fe409b..af571ae0 100644 --- a/packages/guardian-operator-client/README.md +++ b/packages/guardian-operator-client/README.md @@ -300,8 +300,8 @@ const catalog = await client.listModules(); // catalog.modules: [{ moduleId, scope, enabled, circuit, params, paramsDrift, ... }] // catalog.undeclared: stored instances the catalog no longer declares -await client.setModuleGlobalParams('blocklist', { recipient_denylist: ['0xaaa'] }, 'OP-90'); // policies:write_global -await client.setAccountModuleLayer(accountId, 'blocklist', { recipient_denylist: ['0xccc'] }, 'OP-91'); // policies:write +await client.setModuleGlobalParams('blocklist', { recipient_denylist: ['0x0a1b2c3d4e5f60718293a4b5c6d7e8'] }, 'OP-90'); // policies:write_global +await client.setAccountModuleLayer(accountId, 'blocklist', { recipient_denylist: ['0x1c2d3e4f5a6b70819203b4c5d6e7f8'] }, 'OP-91'); // policies:write await client.removeAccountModuleLayer(accountId, 'blocklist', 'OP-92'); await client.setAccountModules(accountId, [{ moduleId: 'treasury-allowlist', params: {} }], 'OP-93'); await client.disableModule('risk-scorer', 'incident'); // policies:write or modules:disable diff --git a/speckit/features/251-guardian-modules/contracts/catalog-config.md b/speckit/features/251-guardian-modules/contracts/catalog-config.md index f242d4ae..429637d1 100644 --- a/speckit/features/251-guardian-modules/contracts/catalog-config.md +++ b/speckit/features/251-guardian-modules/contracts/catalog-config.md @@ -78,7 +78,7 @@ A secret that cannot be read fails the instance's creation: startup stops for an ## `basic-policy` params (M2a) -Every id is written in `0x` hex form (case-insensitive); `validate_params` refuses any other form, such as a bech32 address or a placeholder that is not hex digits, which would never match a request. A modifier without the list it modifies (`deny_unknown_recipients`, `signer_check`, `code_check`) and a cap naming one faucet twice are refused too. +Every id is written in `0x` hex form (case-insensitive); `validate_params` refuses any other form, such as a bech32 address or a placeholder that is not hex digits, which would never match a request, and an id of the wrong length (30 hex digits for a faucet or recipient, 64 for a signer or code commitment). A modifier without the list it modifies (`deny_unknown_recipients`, `signer_check`, `code_check`) and a cap naming one faucet twice are refused too. | Param | Type | Effect | |---|---|---| diff --git a/speckit/features/251-guardian-modules/quickstart.md b/speckit/features/251-guardian-modules/quickstart.md index fb02b4dc..410a1cc0 100644 --- a/speckit/features/251-guardian-modules/quickstart.md +++ b/speckit/features/251-guardian-modules/quickstart.md @@ -71,8 +71,8 @@ GUARDIAN_OPERATOR_PUBLIC_KEYS_FILE=.guardian/operators.json \ ADMIN="cargo run -q -p guardian-server --example modules_admin -- --key .guardian/operator.key" $ADMIN GET /modules -$ADMIN PUT /modules/blocklist/params '{"params":{"recipient_denylist":["0xaaa","0xddd"]},"reason":"extend global list"}' -$ADMIN PUT /accounts/0xACCOUNT/modules/blocklist/params '{"params":{"recipient_denylist":["0xccc"]},"reason":"customer block"}' +$ADMIN PUT /modules/blocklist/params '{"params":{"recipient_denylist":["0x","0x"]},"reason":"extend global list"}' +$ADMIN PUT /accounts/0xACCOUNT/modules/blocklist/params '{"params":{"recipient_denylist":["0x"]},"reason":"customer block"}' $ADMIN GET /accounts/0xACCOUNT/modules $ADMIN GET /modules/blocklist/params/history $ADMIN DELETE /accounts/0xACCOUNT/modules/blocklist/params '{"reason":"lift customer block"}' From a31310e7b44514d5728a0558bedc370568cfa65a Mon Sep 17 00:00:00 2001 From: Zeljko Date: Tue, 10 Nov 2026 09:30:55 +0100 Subject: [PATCH 086/105] feat(module-sdk): a denylist refuses notes it cannot check once it names anyone (#251) A partial note, or one that is neither P2ID nor P2IDE, has no recipient the denylist can read, so a blocked recipient could be paid through one. deny_unknown_recipients is now on by default whenever recipient_denylist is not empty; false opts out, and true applies it to an empty list too. An empty denylist stays lenient: it has nobody to hide, and the guide's blocklist starts empty on every account. --- .../guardian-module-sdk/src/basic_policy.rs | 47 +++++++++++++++---- docs/guides/policy-modules/built-in.md | 8 +++- .../contracts/catalog-config.md | 2 +- 3 files changed, 47 insertions(+), 10 deletions(-) diff --git a/crates/guardian-module-sdk/src/basic_policy.rs b/crates/guardian-module-sdk/src/basic_policy.rs index 95687237..e4c4b154 100644 --- a/crates/guardian-module-sdk/src/basic_policy.rs +++ b/crates/guardian-module-sdk/src/basic_policy.rs @@ -42,8 +42,12 @@ pub struct Params { pub recipient_allowlist: Option>, #[serde(default)] pub recipient_denylist: Option>, + /// Whether a payment note whose recipient cannot be identified (a partial note, or one + /// that is neither P2ID nor P2IDE) is refused by the denylist. Unset, it is refused + /// whenever the denylist names anyone: otherwise a blocked recipient is paid by wrapping + /// the payment in a note the Guardian cannot read. #[serde(default)] - pub deny_unknown_recipients: bool, + pub deny_unknown_recipients: Option, #[serde(default)] pub signer_allowlist: Option>, #[serde(default)] @@ -155,7 +159,7 @@ impl TryFrom for Policy { )); } } - if params.deny_unknown_recipients && params.recipient_denylist.is_none() { + if params.deny_unknown_recipients.is_some() && params.recipient_denylist.is_none() { return Err( "deny_unknown_recipients applies to recipient_denylist, which is not set".into(), ); @@ -205,7 +209,12 @@ impl TryFrom for Policy { .as_deref() .map(|list| ids("recipient_denylist", IdKind::Account, list)) .transpose()?, - deny_unknown_recipients: params.deny_unknown_recipients, + deny_unknown_recipients: params.deny_unknown_recipients.unwrap_or( + params + .recipient_denylist + .as_ref() + .is_some_and(|list| !list.is_empty()), + ), signers, signer_check: params.signer_check.unwrap_or_default(), code: params @@ -694,13 +703,34 @@ mod tests { ], ..Default::default() }; - assert!(decide(&tx_request(params, unknown.clone())).await.allows()); - - let strict = json!({ "recipient_denylist": ["0x000000000000000000000000000bad"], "deny_unknown_recipients": true }); assert_eq!( - decide(&tx_request(strict, unknown)).await.reason_code, + decide(&tx_request(params, unknown.clone())) + .await + .reason_code, "recipient_blocked", - "an unknown recipient refused by the denylist rule reports that rule" + "a recipient the denylist cannot check is refused: a blocked one could hide there" + ); + + let lenient = json!({ "recipient_denylist": ["0x000000000000000000000000000bad"], "deny_unknown_recipients": false }); + assert!( + decide(&tx_request(lenient, unknown.clone())).await.allows(), + "the operator opted out" + ); + + let nobody_listed = json!({ "recipient_denylist": [] }); + assert!( + decide(&tx_request(nobody_listed, unknown.clone())) + .await + .allows(), + "an empty denylist has nobody to hide" + ); + + let strict_anyway = json!({ "recipient_denylist": [], "deny_unknown_recipients": true }); + assert_eq!( + decide(&tx_request(strict_anyway, unknown)) + .await + .reason_code, + "recipient_blocked" ); } @@ -966,6 +996,7 @@ mod tests { json!({ "signer_allowlist": ["0x000000000000000000000000000051"] }), json!({ "allowed_code_commitments": [format!("0x{}", "c".repeat(63))] }), json!({ "deny_unknown_recipients": true }), + json!({ "deny_unknown_recipients": false }), json!({ "signer_check": "all" }), json!({ "code_check": "all" }), ] { diff --git a/docs/guides/policy-modules/built-in.md b/docs/guides/policy-modules/built-in.md index 41d2ebd2..bbff4272 100644 --- a/docs/guides/policy-modules/built-in.md +++ b/docs/guides/policy-modules/built-in.md @@ -25,13 +25,19 @@ account layers, which are evaluated with their own params: a layer of `{"deny_unknown_recipients": true}` alone would do nothing, so it is not accepted. +The `blocklist` instance in the guide's catalog starts with an empty +`recipient_denylist`, which refuses nothing. Once a recipient is listed, +globally or in an account's layer, notes without a checkable recipient are +refused for the accounts that list applies to, unless the same params set +`deny_unknown_recipients` to `false`. + | Param | Value | Refuses with | Notes | |---|---|---|---| | `max_amount_per_tx` | `{ "": "" }` | `amount_cap_exceeded` | Gross amount per asset across the transaction's payment notes, in base units. The fee note is not a payment. | | `asset_allowlist` | `["", ...]` | `asset_not_allowed` | Assets sent in payment notes and received in input notes. | | `recipient_allowlist` | `["", ...]` | `recipient_not_allowed` | P2ID and P2IDE targets. | | `recipient_denylist` | `["", ...]` | `recipient_blocked` | | -| `deny_unknown_recipients` | `true` / `false` | `recipient_blocked` | With `recipient_denylist`: also refuses payment notes whose recipient the Guardian cannot identify (not P2ID or P2IDE). | +| `deny_unknown_recipients` | `true` / `false`; unset, `true` once the denylist names anyone | `recipient_blocked` | With `recipient_denylist`: also refuses payment notes whose recipient the Guardian cannot identify (a partial note, or one that is not P2ID or P2IDE). On by default as soon as the list is not empty, since a blocked recipient could otherwise be paid through a note the Guardian cannot read. Set it to `false` for accounts that must create custom-script notes, such as swaps. | | `signer_allowlist` or `signer_denylist` | `["", ...]` | `signer_not_allowed` | Mutually exclusive. | | `signer_check` | `"added"` (default) or `"all"` | | `added` checks only signers a transaction adds; `all` checks every signer after it. | | `allowed_code_commitments` | `["", ...]` | `code_not_allowed` | Pins accounts to account code you reviewed. The Guardian does not check an account's code itself, so a module verdict is only as good as the code that requires the Guardian's signature. | diff --git a/speckit/features/251-guardian-modules/contracts/catalog-config.md b/speckit/features/251-guardian-modules/contracts/catalog-config.md index 429637d1..d661f14a 100644 --- a/speckit/features/251-guardian-modules/contracts/catalog-config.md +++ b/speckit/features/251-guardian-modules/contracts/catalog-config.md @@ -85,7 +85,7 @@ Every id is written in `0x` hex form (case-insensitive); `validate_params` refus | `max_amount_per_tx` | map faucet id to decimal string | For each listed faucet, deny if the gross amount sent exceeds it: the sum of that faucet's fungible amounts over every output note, full or partial. Input notes consumed in the same transaction do not offset it, the fee note (`tx_fee`) is not counted, faucets not listed are uncapped, non-fungible assets are not counted (use `asset_allowlist`) | | `recipient_allowlist` | list of account ids | Deny a payment note whose `p2id_target` is not listed; partial or non-P2ID notes deny | | `recipient_denylist` | list of account ids | Deny a payment note whose `p2id_target` is listed | -| `deny_unknown_recipients` | bool, default `false` | With `recipient_denylist`, also deny partial and non-P2ID payment notes, whose recipient cannot be checked | +| `deny_unknown_recipients` | bool; unset, `true` when `recipient_denylist` is not empty | With `recipient_denylist`, also deny partial and non-P2ID payment notes, whose recipient cannot be checked | | `asset_allowlist` | list of faucet ids | Deny an unlisted faucet among assets sent in payment notes or received in input notes; the fee note (`tx_fee`) is not checked | | `signer_allowlist` / `signer_denylist` | list of signer commitments | Check signers per `signer_check`; at most one of the two | | `signer_check` | `added` (default) or `all` | `added`: signers in `after` not in `before`; `all`: every signer in `after` | From 5a4c0ed6130709cb6578ab71ceba7134ed6c85a2 Mon Sep 17 00:00:00 2001 From: Zeljko Date: Tue, 10 Nov 2026 09:30:55 +0100 Subject: [PATCH 087/105] fix(modules): a module outage does not stop a restart, and the catalog can require an instance (#251) - An enabled instance that has started on this Guardian before, and whose module does not answer its startup checks, starts unavailable: its breaker is held open, so its accounts follow on_error, and each health probe runs the full startup checks until they pass. A third party's outage no longer keeps every replica from restarting. An instance new to this Guardian must answer, and a module that answers but refuses the call, the params or the protocol version still stops startup. - An instance the catalog declares enabled and not operator-disableable is enabled at startup when it is stored as disabled, with a params history entry by the catalog: no operator may hold it off under that catalog. Other differences still follow the stored flag. - Startup check failures are typed (unreachable, incompatible, invalid params), which the probe and the breaker use. --- crates/server/src/modules/breaker.rs | 12 +- crates/server/src/modules/pipeline.rs | 262 ++++++++++++++++++++++++-- crates/server/src/modules/registry.rs | 101 +++++++--- crates/server/src/modules/testing.rs | 53 ++++++ 4 files changed, 386 insertions(+), 42 deletions(-) diff --git a/crates/server/src/modules/breaker.rs b/crates/server/src/modules/breaker.rs index b61f1bb4..c01f3435 100644 --- a/crates/server/src/modules/breaker.rs +++ b/crates/server/src/modules/breaker.rs @@ -113,11 +113,11 @@ impl Breakers { }); } - /// A health probe found the module answering `Describe` with a protocol version, a required - /// capability or a hook set this Guardian cannot work with. Its decisions are not trusted - /// from here on, whatever it answered before: the breaker opens at once and stays open - /// until a probe passes again. - pub fn probe_incompatible(&self, instance: &str) { + /// Opens the breaker at once, whatever the module answered before, and keeps it open until + /// a probe passes: for a module that did not answer its startup checks, and for one a + /// health probe finds answering with a protocol version, a required capability, a hook set + /// or params this Guardian cannot work with. Its decisions are not trusted meanwhile. + pub fn hold_open(&self, instance: &str) { self.update(instance, |breaker| { breaker.state = CircuitState::Open; breaker.trial_in_flight = false; @@ -215,7 +215,7 @@ mod tests { #[test] fn an_incompatible_probe_opens_a_closed_breaker_until_a_probe_passes() { let breakers = Breakers::new(5); - breakers.probe_incompatible("m"); + breakers.hold_open("m"); assert_eq!(breakers.state("m"), CircuitState::Open); assert!(!breakers.admit("m", Caller::Request)); breakers.probe_succeeded("m"); diff --git a/crates/server/src/modules/pipeline.rs b/crates/server/src/modules/pipeline.rs index 9556d14d..1a9d2e85 100644 --- a/crates/server/src/modules/pipeline.rs +++ b/crates/server/src/modules/pipeline.rs @@ -90,6 +90,9 @@ pub struct ModulePipeline { seed_drift: HashSet, /// Accounts over the budget and orphaned assignment rows, as of the last report. assignment_report: std::sync::Mutex<(usize, usize)>, + /// Instances that started without passing their startup checks because their module did + /// not answer. Each health probe runs the checks again until they pass. + unchecked: std::sync::Mutex>, } pub(super) type Rows = Arc>; @@ -208,8 +211,10 @@ impl ModulePipeline { .into_iter() .map(|row| (row.module_id, (row.global_params, row.enabled))) .collect(); + let known: HashSet = stored.keys().cloned().collect(); let mut effective = HashMap::new(); let mut seed_drift = HashSet::new(); + let mut enabled_by_catalog = Vec::new(); for config in &mut catalog.instances { let Some((params, enabled)) = stored.get(&config.id) else { continue; @@ -221,10 +226,18 @@ impl ModulePipeline { { seed_drift.insert(config.id.clone()); } - if *enabled != config.catalog_enabled { + // The stored flag is the switch, with one exception: an instance the catalog + // declares enabled and not operator-disableable cannot be left off by a disable + // that was allowed under an earlier catalog. Switching it on only tightens policy. + let catalog_requires_it = + !*enabled && config.catalog_enabled && !config.operator_can_disable; + if catalog_requires_it { + tracing::warn!(module = %config.id, "Stored flag disables an instance the catalog declares enabled and not operator-disableable; enabling it"); + enabled_by_catalog.push(config.id.clone()); + } else if *enabled != config.catalog_enabled { tracing::warn!(module = %config.id, enabled, "Catalog `enabled` differs from the stored runtime flag; the stored flag applies"); } - config.enabled = *enabled; + config.enabled = *enabled || catalog_requires_it; if !config.file_managed_params && *params != config.params { tracing::warn!(module = %config.id, "Catalog params differ from the operator-managed global params; the stored params apply"); effective.insert(config.id.clone(), params.clone()); @@ -233,7 +246,21 @@ impl ModulePipeline { let super::registry::Instantiated { instances, normalized, - } = registry.instantiate(&catalog, &effective).await?; + unreachable, + } = registry.instantiate(&catalog, &effective, &known).await?; + for module_id in enabled_by_catalog { + store + .set_enabled( + &module_id, + true, + &super::store::Change { + operator: "catalog", + reason: "the catalog declares the instance enabled and not operator-disableable", + at: now.clone(), + }, + ) + .await?; + } for config in catalog .instances .iter() @@ -288,12 +315,17 @@ impl ModulePipeline { tracing::warn!(module = %instance.config.id, "Global params changed while the module migrated them; kept the newer value, migration retries next start"); } } + let breakers = Arc::new(Breakers::new(limits.breaker_failures)); + for module_id in &unreachable { + breakers.hold_open(module_id); + } Ok(Self { instances, store, cache: RwLock::new(Cache::default()), views: Arc::default(), - breakers: Arc::new(Breakers::new(limits.breaker_failures)), + breakers, + unchecked: std::sync::Mutex::new(unreachable), limits, catalog_hash: catalog.hash, network_id, @@ -326,6 +358,7 @@ impl ModulePipeline { network_id: "local", seed_drift: HashSet::new(), assignment_report: std::sync::Mutex::new((0, 0)), + unchecked: std::sync::Mutex::default(), } } @@ -529,19 +562,47 @@ impl ModulePipeline { if !Self::enabled_in(&rows, instance) { continue; } - let healthy = - super::registry::describe_healthy(&instance.config, &instance.module).await; - super::metrics::up(&instance.config.id, healthy.is_ok()); let id = instance.config.id.as_str(); + let unchecked = self + .unchecked + .lock() + .is_ok_and(|unchecked| unchecked.contains(id)); + // An instance that started without its startup checks runs all of them here, the + // params that apply included, before any call is let through. + let healthy = if unchecked { + super::registry::check( + &instance.config, + &instance.module, + &Self::global_params_in(&rows, instance), + ) + .await + .map(|_| ()) + } else { + super::registry::describe_healthy(&instance.config, &instance.module) + .await + .map(|_| ()) + }; + super::metrics::up(id, healthy.is_ok()); match healthy { - Ok(_) => self.breakers.probe_succeeded(id), + Ok(()) => { + if unchecked { + if let Ok(mut unchecked) = self.unchecked.lock() { + unchecked.remove(id); + } + tracing::info!( + module = id, + "Policy module passed the startup checks it could not be reached for" + ); + } + self.breakers.probe_succeeded(id); + } Err(Unhealthy::Unreachable(error)) => { tracing::warn!(module = id, %error, "Policy module health probe failed"); self.breakers.failed(id); } - Err(Unhealthy::Incompatible(error)) => { - tracing::warn!(module = id, %error, "Policy module is incompatible with this Guardian; its circuit is open until a probe passes"); - self.breakers.probe_incompatible(id); + Err(Unhealthy::Incompatible(error) | Unhealthy::InvalidParams(error)) => { + tracing::warn!(module = id, %error, "Policy module cannot be used by this Guardian; its circuit is open until a probe passes"); + self.breakers.hold_open(id); } } } @@ -1452,6 +1513,185 @@ params = { old_name = 5 } } } + const OUTAGE_CATALOG: &str = r#" +[[module]] +id = "screening" +kind = "outage-stub" +scope = "all" +hooks = ["before_transaction_approved"] +timeout_ms = 50 +"#; + + async fn start_with( + module: Arc, + catalog: &str, + store: Arc, + ) -> Result { + let mut registry = Registry::first_party(); + registry + .register( + "outage-stub", + Arc::new(crate::modules::testing::FixedFactory(module)), + ) + .unwrap(); + ModulePipeline::new( + "local", + Catalog::parse(catalog, None).unwrap(), + ®istry, + store, + "2026-11-10T00:00:00Z".to_string(), + crate::modules::limits::Limits::default(), + ) + .await + } + + #[tokio::test] + async fn a_known_instance_whose_module_is_down_starts_unavailable_and_recovers_on_a_probe() { + use std::sync::atomic::Ordering; + let module = crate::modules::testing::Outage::new(false); + let store: Arc = Arc::new(super::super::store::FsModuleStore::in_memory()); + start_with(module.clone(), OUTAGE_CATALOG, store.clone()) + .await + .expect("the first start passes the checks and makes the instance known"); + + module.set_down(true); + let pipeline = start_with(module.clone(), OUTAGE_CATALOG, store) + .await + .expect("a module outage does not keep the Guardian from restarting"); + assert_eq!(pipeline.breakers().state("screening"), CircuitState::Open); + assert!( + matches!( + run(&pipeline).await, + Err(GuardianError::ModuleUnavailable { .. }) + ), + "its accounts are refused meanwhile, not approved" + ); + + pipeline.probe().await; + assert_eq!( + pipeline.breakers().state("screening"), + CircuitState::Open, + "still down" + ); + + module.set_down(false); + pipeline.probe().await; + assert_eq!( + pipeline.breakers().state("screening"), + CircuitState::HalfOpen + ); + run(&pipeline).await.expect("the module decides again"); + assert_eq!(pipeline.breakers().state("screening"), CircuitState::Closed); + assert_eq!(module.evaluations.load(Ordering::SeqCst), 1); + } + + #[tokio::test] + async fn an_instance_new_to_this_guardian_must_answer_at_startup() { + let module = crate::modules::testing::Outage::new(true); + let store: Arc = Arc::new(super::super::store::FsModuleStore::in_memory()); + let refused = start_with(module, OUTAGE_CATALOG, store.clone()) + .await + .err() + .expect("a wrong endpoint in a new catalog entry is found at deploy time"); + assert!(refused.contains("screening"), "{refused}"); + assert!(store.instances().await.unwrap().is_empty()); + } + + #[tokio::test] + async fn a_known_instance_that_answers_incompatibly_still_stops_startup() { + use crate::modules::testing::{FixedFactory, ProtocolStub}; + const CATALOG: &str = r#" +[[module]] +id = "screening" +kind = "protocol-stub" +scope = "all" +hooks = ["before_transaction_approved"] +timeout_ms = 50 +"#; + let start = |protocol_version: u32, store: Arc| async move { + let mut stub = ProtocolStub::new(); + stub.protocol_version = protocol_version; + let mut registry = Registry::first_party(); + registry + .register("protocol-stub", Arc::new(FixedFactory(Arc::new(stub)))) + .unwrap(); + ModulePipeline::new( + "local", + Catalog::parse(CATALOG, None).unwrap(), + ®istry, + store, + "2026-11-10T00:00:00Z".to_string(), + crate::modules::limits::Limits::default(), + ) + .await + }; + let store: Arc = Arc::new(super::super::store::FsModuleStore::in_memory()); + start(guardian_module_sdk::PROTOCOL_VERSION, store.clone()) + .await + .unwrap(); + assert!( + start(guardian_module_sdk::PROTOCOL_VERSION + 1, store) + .await + .is_err(), + "only a module that does not answer may start unavailable" + ); + } + + #[tokio::test] + async fn an_instance_the_catalog_requires_is_enabled_at_startup() { + let disabled_in_store = || async { + let store: Arc = + Arc::new(super::super::store::FsModuleStore::in_memory()); + store + .seed_instance("screening", false, &serde_json::json!({}), "t0") + .await + .unwrap(); + store + }; + + let store = disabled_in_store().await; + let pipeline = start_with( + crate::modules::testing::Outage::new(false), + OUTAGE_CATALOG, + store.clone(), + ) + .await + .unwrap(); + assert!( + store.instances().await.unwrap()[0].enabled, + "enabled and not operator-disableable in the catalog: a stored disable does not stand" + ); + let history = store.history("screening", None, 10).await.unwrap(); + assert_eq!(history[0].operator, "catalog"); + assert_eq!(history[0].new, serde_json::json!({ "enabled": true })); + assert!( + pipeline + .applies(HookName::BeforeTransactionApproved, "0xacc") + .await + .unwrap() + ); + + let store = disabled_in_store().await; + let disableable = format!("{OUTAGE_CATALOG}operator_can_disable = true\n"); + let pipeline = start_with( + crate::modules::testing::Outage::new(false), + &disableable, + store.clone(), + ) + .await + .unwrap(); + assert!( + !store.instances().await.unwrap()[0].enabled, + "an operator may hold a disableable instance off, so the stored flag stands" + ); + assert!( + !pipeline + .applies(HookName::BeforeTransactionApproved, "0xacc") + .await + .unwrap() + ); + } + #[tokio::test] async fn startup_stores_params_the_module_migrated() { use crate::modules::testing::{FixedFactory, ProtocolStub}; diff --git a/crates/server/src/modules/registry.rs b/crates/server/src/modules/registry.rs index 4fa8ccb0..60ce838c 100644 --- a/crates/server/src/modules/registry.rs +++ b/crates/server/src/modules/registry.rs @@ -1,6 +1,6 @@ //! Module kinds and instance creation. -use std::collections::HashMap; +use std::collections::{HashMap, HashSet}; use std::sync::Arc; use guardian_module_sdk::basic_policy::{self, BasicPolicy}; @@ -33,6 +33,9 @@ impl ModuleFactory for BasicPolicyFactory { pub struct Instantiated { pub instances: Vec, pub normalized: HashMap, + /// Enabled instances whose module did not answer its startup checks and that start + /// unavailable: their checks run again on each health probe. + pub unreachable: HashSet, } pub struct Registry { @@ -70,15 +73,23 @@ impl Registry { /// Creates every instance and checks it against the params that will apply (`effective`, /// keyed by instance id; the catalog's when absent). An enabled instance that cannot be - /// created, is unsupported, unreachable or misconfigured stops startup; a disabled one is - /// logged and kept disabled. + /// created, is unsupported or misconfigured stops startup; a disabled one is logged and + /// kept disabled. + /// + /// An enabled instance whose module does not answer starts unavailable when it is `known` + /// (it ran on an earlier start), so a module's outage does not keep the Guardian from + /// restarting: its accounts follow `on_error` until a health probe passes the checks. One + /// that is new to this Guardian must answer, so a wrong endpoint in a new catalog entry is + /// found when it is deployed. pub async fn instantiate( &self, catalog: &Catalog, effective: &HashMap, + known: &HashSet, ) -> Result { let mut instances = Vec::with_capacity(catalog.instances.len()); let mut normalized = HashMap::new(); + let mut unreachable = HashSet::new(); for config in &catalog.instances { let mut config = config.clone(); let params = effective.get(&config.id).unwrap_or(&config.params); @@ -87,7 +98,7 @@ impl Registry { .await .map(|checked| (module.clone(), checked)) .map_err(|error| (error, Some(module))), - Err(error) => Err((error, None)), + Err(error) => Err((Unhealthy::Incompatible(error), None)), }; let (module, build) = match ready { Ok((module, checked)) => { @@ -99,13 +110,23 @@ impl Registry { Some(format!("{} {}", checked.info.name, checked.info.version)), ) } + Err((Unhealthy::Unreachable(error), Some(module))) + if config.enabled && known.contains(&config.id) => + { + tracing::warn!(module = %config.id, %error, "Enabled module did not answer its startup checks; it starts unavailable and its accounts follow on_error until a health probe passes"); + unreachable.insert(config.id.clone()); + (module, None) + } Err((error, _)) if config.enabled => { return Err(format!("module {}: {error}", config.id)); } Err((error, module)) => { tracing::warn!(module = %config.id, %error, "Disabled module failed its startup checks"); config.enabled = false; - (module.unwrap_or_else(|| Arc::new(Unavailable(error))), None) + ( + module.unwrap_or_else(|| Arc::new(Unavailable(error.to_string()))), + None, + ) } }; instances.push(Instance { @@ -117,6 +138,7 @@ impl Registry { Ok(Instantiated { instances, normalized, + unreachable, }) } @@ -247,26 +269,45 @@ pub async fn check( config: &InstanceConfig, module: &Arc, params: &serde_json::Value, -) -> Result { +) -> Result { let info = describe_healthy(config, module).await?; let params = validate_params(module, params, config.timeout).await?; Ok(Checked { info, params }) } -/// Why a module failed [`describe_healthy`]. +/// Why a module failed its checks. #[derive(Debug, Clone, PartialEq, Eq)] pub enum Unhealthy { - /// `Describe` did not answer: the module may be down. + /// The module did not answer: it may be down. Unreachable(String), - /// `Describe` answered with something this Guardian cannot work with, so the module's - /// decisions cannot be trusted either. + /// The module answered, but with something this Guardian cannot work with (it refused the + /// call, or speaks another protocol version, requires a capability this Guardian lacks or + /// no longer supports a configured hook), so its decisions cannot be trusted either. Incompatible(String), + /// The module refuses the params that would apply to it. + InvalidParams(String), +} + +impl Unhealthy { + /// A call that produced no result: no answer in time, or the module reporting itself + /// unavailable, is unreachable; anything else is an answer this Guardian cannot use. + fn call(name: &str, error: CallError) -> Self { + let detail = format!("{name} {error}"); + match error { + CallError::Timeout | CallError::Module(ModuleError::Unavailable(_)) => { + Unhealthy::Unreachable(detail) + } + CallError::Module(_) | CallError::Panicked(_) => Unhealthy::Incompatible(detail), + } + } } impl std::fmt::Display for Unhealthy { fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { match self { - Unhealthy::Unreachable(detail) | Unhealthy::Incompatible(detail) => { + Unhealthy::Unreachable(detail) + | Unhealthy::Incompatible(detail) + | Unhealthy::InvalidParams(detail) => { write!(f, "{detail}") } } @@ -291,7 +332,7 @@ pub async fn describe_healthy( describing.describe(&describe_request()).await }) .await - .map_err(|e| Unhealthy::Unreachable(format!("describe {e}")))?; + .map_err(|e| Unhealthy::call("describe", e))?; if !(MIN_PROTOCOL_VERSION..=PROTOCOL_VERSION).contains(&info.protocol_version) { return Err(Unhealthy::Incompatible(format!( "unsupported protocol version {}; this Guardian accepts {MIN_PROTOCOL_VERSION} to {PROTOCOL_VERSION}", @@ -327,24 +368,29 @@ pub async fn validate_params( module: &Arc, params: &serde_json::Value, timeout: std::time::Duration, -) -> Result { - let bytes = serde_json::to_vec(params).map_err(|e| e.to_string())?; +) -> Result { + let bytes = serde_json::to_vec(params).map_err(|e| Unhealthy::InvalidParams(e.to_string()))?; let validating = module.clone(); let verdict = isolated( timeout, async move { validating.validate_params(&bytes).await }, ) .await - .map_err(|e| format!("validate_params {e}"))?; + .map_err(|e| Unhealthy::call("validate_params", e))?; if !verdict.ok { - return Err(format!("invalid params: {}", verdict.message)); + return Err(Unhealthy::InvalidParams(format!( + "invalid params: {}", + verdict.message + ))); } if verdict.normalized_params.is_empty() { return Ok(params.clone()); } match serde_json::from_slice::(&verdict.normalized_params) { Ok(normalized) if normalized.is_object() => Ok(normalized), - _ => Err("normalized params are not a JSON object".into()), + _ => Err(Unhealthy::Incompatible( + "normalized params are not a JSON object".into(), + )), } } @@ -384,6 +430,7 @@ enabled = ENABLED .instantiate( &catalog(&entry.replace("ENABLED", "false")), &HashMap::new(), + &HashSet::new(), ) .await .expect("a disabled instance does not block startup") @@ -397,7 +444,11 @@ enabled = ENABLED async fn enabled_instances_that_cannot_be_created_stop_startup() { for entry in [UNKNOWN_KIND, BAD_ENDPOINT] { let result = Registry::first_party() - .instantiate(&catalog(&entry.replace("ENABLED", "true")), &HashMap::new()) + .instantiate( + &catalog(&entry.replace("ENABLED", "true")), + &HashMap::new(), + &HashSet::new(), + ) .await; assert!(result.is_err()); } @@ -414,7 +465,7 @@ enabled = ENABLED } let built_in = include_str!("../../../../docs/guides/policy-modules/built-in.toml"); let unedited = Registry::first_party() - .instantiate(&catalog(built_in), &HashMap::new()) + .instantiate(&catalog(built_in), &HashMap::new(), &HashSet::new()) .await .err() .expect("the guide catalog does not start until its placeholder is replaced"); @@ -424,7 +475,7 @@ enabled = ENABLED "0x0a1b2c3d4e5f60718293a4b5c6d7e8", ); let instances = Registry::first_party() - .instantiate(&catalog(&edited), &HashMap::new()) + .instantiate(&catalog(&edited), &HashMap::new(), &HashSet::new()) .await .expect("the built-in guide catalog passes the startup checks") .instances; @@ -463,7 +514,7 @@ timeout_ms = 50 .register("house-policy", Arc::new(StubFactory)) .unwrap(); let instances = registry - .instantiate(&catalog(CUSTOM), &HashMap::new()) + .instantiate(&catalog(CUSTOM), &HashMap::new(), &HashSet::new()) .await .unwrap() .instances; @@ -471,7 +522,7 @@ timeout_ms = 50 assert!(instances[0].config.enabled); assert!( Registry::first_party() - .instantiate(&catalog(CUSTOM), &HashMap::new()) + .instantiate(&catalog(CUSTOM), &HashMap::new(), &HashSet::new()) .await .is_err(), "unregistered, the same catalog stops startup" @@ -501,7 +552,7 @@ timeout_ms = 50 .register("house-policy", Arc::new(PanickingFactory)) .unwrap(); let error = registry - .instantiate(&catalog(CUSTOM), &HashMap::new()) + .instantiate(&catalog(CUSTOM), &HashMap::new(), &HashSet::new()) .await .err() .unwrap(); @@ -541,7 +592,7 @@ params = { old_name = 5 } ) .unwrap(); registry - .instantiate(&catalog(PROTOCOL_CATALOG), &HashMap::new()) + .instantiate(&catalog(PROTOCOL_CATALOG), &HashMap::new(), &HashSet::new()) .await } @@ -556,7 +607,7 @@ params = { old_name = 5 } ) .unwrap(); registry - .instantiate(&catalog(PROTOCOL_CATALOG), &HashMap::new()) + .instantiate(&catalog(PROTOCOL_CATALOG), &HashMap::new(), &HashSet::new()) .await .unwrap(); let sent = stub.described_with.lock().unwrap().clone().unwrap(); diff --git a/crates/server/src/modules/testing.rs b/crates/server/src/modules/testing.rs index 93458860..f6b5ffcf 100644 --- a/crates/server/src/modules/testing.rs +++ b/crates/server/src/modules/testing.rs @@ -190,6 +190,59 @@ impl Module for ProtocolStub { } } +/// Allows every request while up; while `down`, answers nothing, like a module whose host is +/// gone. +pub struct Outage { + pub down: std::sync::atomic::AtomicBool, + pub evaluations: AtomicUsize, +} + +impl Outage { + pub fn new(down: bool) -> Arc { + Arc::new(Self { + down: std::sync::atomic::AtomicBool::new(down), + evaluations: AtomicUsize::new(0), + }) + } + + pub fn set_down(&self, down: bool) { + self.down.store(down, Ordering::SeqCst); + } + + fn reachable(&self) -> Result<(), ModuleError> { + if self.down.load(Ordering::SeqCst) { + Err(ModuleError::Unavailable("module host is down".into())) + } else { + Ok(()) + } + } +} + +#[async_trait] +impl Module for Outage { + async fn describe(&self, _guardian: &DescribeRequest) -> Result { + self.reachable()?; + Ok(ModuleInfo { + name: "outage-stub".into(), + version: "1".into(), + protocol_version: PROTOCOL_VERSION, + hooks: vec![guardian_module_sdk::Hook::BeforeTransactionApproved as i32], + ..Default::default() + }) + } + + async fn validate_params(&self, _params: &[u8]) -> Result { + self.reachable()?; + Ok(ParamsVerdict::ok()) + } + + async fn evaluate(&self, _request: &HookRequest) -> Result { + self.reachable()?; + self.evaluations.fetch_add(1, Ordering::SeqCst); + Ok(Decision::allow()) + } +} + /// Hands out one prepared module for every instance of its kind. pub struct FixedFactory(pub Arc); From 469119785df6e7fc2623bc4d08713c66f25168b0 Mon Sep 17 00:00:00 2001 From: Zeljko Date: Tue, 10 Nov 2026 09:30:55 +0100 Subject: [PATCH 088/105] docs(modules): startup during a module outage, catalog-required instances, the denylist default (#251) Configuration reference, guides, runbook and RFC 0002 revision 32. --- docs/CONFIGURATION.md | 2 +- docs/guides/policy-modules/README.md | 2 +- docs/guides/policy-modules/remote.md | 6 +++++- docs/rfcs/0002-guardian-modules.md | 8 ++++---- docs/runbooks/policy-modules.md | 25 +++++++++++++++++++++---- 5 files changed, 32 insertions(+), 11 deletions(-) diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md index df4516fd..39352a28 100644 --- a/docs/CONFIGURATION.md +++ b/docs/CONFIGURATION.md @@ -407,7 +407,7 @@ modules guide](./guides/policy-modules/README.md). | Variable | Default | Notes | |---|---|---| -| `GUARDIAN_MODULES_CONFIG` | _unset_ (no modules) | Path of the module catalog (TOML). A value that is set but empty, or a catalog that declares no module, refuses startup: unset the variable to run without modules. Without it the server logs that no policy module runs, as a warning when its database still holds module state from an earlier catalog. Read once at startup; it declares every instance and seeds its global params on first start, after which params are managed through the [operator API](./DASHBOARD.md#policy-modules). A relative path resolves against the working directory; a relative `tls.ca_file` in the catalog resolves against the catalog's directory, and `auth.token_secret`, `tls.client_cert_secret`, `tls.client_key_secret` and `$secret` params name secrets read through `GUARDIAN_MODULE_SECRET_PROVIDER`. An enabled instance that fails its startup checks stops startup. In the prod stage remote instances must use TLS (`grpc://`) and set `auth`. | +| `GUARDIAN_MODULES_CONFIG` | _unset_ (no modules) | Path of the module catalog (TOML). A value that is set but empty, or a catalog that declares no module, refuses startup: unset the variable to run without modules. Without it the server logs that no policy module runs, as a warning when its database still holds module state from an earlier catalog. Read once at startup; it declares every instance and seeds its global params on first start, after which params are managed through the [operator API](./DASHBOARD.md#policy-modules). A relative path resolves against the working directory; a relative `tls.ca_file` in the catalog resolves against the catalog's directory, and `auth.token_secret`, `tls.client_cert_secret`, `tls.client_key_secret` and `$secret` params name secrets read through `GUARDIAN_MODULE_SECRET_PROVIDER`. An enabled instance that fails its startup checks stops startup, with one exception: an instance that has started on this Guardian before and whose module does not answer starts unavailable (its breaker open, so its accounts follow `on_error`) and runs its startup checks on each health probe until they pass, so a module's outage does not keep the Guardian from restarting. A module that answers but rejects the token, the params or the protocol still stops startup, and so does an unreachable module of an instance new to this Guardian. An instance stored as disabled that the catalog declares enabled and not `operator_can_disable` is enabled at startup. In the prod stage remote instances must use TLS (`grpc://`) and set `auth`. | | `GUARDIAN_MODULE_CHECK_RATE_PER_MIN` | `30` | Dry-run proposal checks (`POST /delta/proposal/check`) one signer may make for one account per minute; excess returns `rate_limit_exceeded`. Per replica. A value that is not a positive integer refuses startup. | | `GUARDIAN_MODULES_STATE` | `/modules` when that variable is set, otherwise `.tables` next to the catalog file | Filesystem builds only: directory of the module state file (`module_state.json`). Set it, or `GUARDIAN_METADATA_PATH`, when the catalog sits on a read-only mount. Postgres builds keep module state in the database. | | `GUARDIAN_MODULE_EVALUATION_BUDGET_MS` | `1000` | Time spent in module calls for one hook invocation (request assembly is not charged). Each call gets the smaller of its `timeout_ms` and what is left; once spent, later modules count as timed out and their `on_error` applies. In the prod stage startup refuses a catalog whose `all` and `default` instances, enabled or not, exceed it at any hook, and a budget not below the execution reservation lease; account assignments and layers that would raise an account's cost over it are refused at write time, while writes that keep or lower the cost pass. Client and SDK request timeouts must exceed it, or a slow approval arrives after the client retried. | diff --git a/docs/guides/policy-modules/README.md b/docs/guides/policy-modules/README.md index a80daf88..d8715623 100644 --- a/docs/guides/policy-modules/README.md +++ b/docs/guides/policy-modules/README.md @@ -200,7 +200,7 @@ For outages, a module that refuses too much, and break-glass steps, see the | `cannot read module catalog` | `GUARDIAN_MODULES_CONFIG` is relative to the directory you started the server in; start from the repository root. | | `module caps: invalid params: …` at startup | The catalog's seed params fail the module's validation on a first start: fix the catalog; nothing is stored until every instance passes. On a later start it is the stored params that fail (the catalog's are no longer read): see the [runbook](../../runbooks/policy-modules.md). | | `GUARDIAN_MODULES_CONFIG is set but empty` or `declares no module` at startup | An empty value or an empty catalog would silently run without any policy. Point the variable at a catalog, or unset it to run without modules. | -| `module caps-remote: …` at startup | An enabled remote module is unreachable or rejected the token. Start the module first, or set `enabled = false` until it runs. | +| `module caps-remote: …` at startup | An enabled remote module rejected the token or answered incompatibly, or it is new to this Guardian and unreachable. Start the module first, or set `enabled = false` until it runs. A module that has started here before and is merely down does not stop startup: the instance starts unavailable and recovers on a health probe. | | `relation "module_state_version" does not exist` | A Postgres database that ran an earlier prototype migration. Drop the `module_*` tables and the `20261015000001` row in `__diesel_schema_migrations`, then restart. | | `login failed: no session cookie` | The server did not load the key: check `GUARDIAN_OPERATOR_PUBLIC_KEYS_FILE` and the `public_key` in it. | | The client shows a generic error | The server log names the module, reason code and layer for every refusal. | diff --git a/docs/guides/policy-modules/remote.md b/docs/guides/policy-modules/remote.md index 5263cb8b..80865270 100644 --- a/docs/guides/policy-modules/remote.md +++ b/docs/guides/policy-modules/remote.md @@ -52,7 +52,11 @@ cp docs/guides/policy-modules/remote.toml .guardian/ Replace the faucet placeholder, set `GUARDIAN_MODULES_CONFIG=.guardian/remote.toml` in the guide's `.env`, and start the server as in the setup. The module must -already be running: an enabled instance that cannot be reached stops startup. +already be running: an enabled instance that is new to this Guardian and +cannot be reached stops startup. Once the instance has started here, a later +start during a module outage succeeds with the instance unavailable (its +accounts get `GUARDIAN_MODULE_UNAVAILABLE`, or skip it with +`on_error = "allow"`) until a health probe passes its startup checks. The log line lists `caps-remote=basic-policy `. `auth.token_secret` names a secret in the Guardian's secrets backend (see diff --git a/docs/rfcs/0002-guardian-modules.md b/docs/rfcs/0002-guardian-modules.md index 08fcd2a8..7b2acd62 100644 --- a/docs/rfcs/0002-guardian-modules.md +++ b/docs/rfcs/0002-guardian-modules.md @@ -199,7 +199,7 @@ auth = { token_secret = "guardian/modules/risk-vendor-token" } **Parameters and secrets.** Params are a JSON object. A value of the form `{"$secret": ""}` is a secret reference, resolved by the Guardian through its secrets backend (`GUARDIAN_MODULE_SECRET_PROVIDER`: AWS Secrets Manager by default in the prod stage, owner-only files below `GUARDIAN_MODULE_SECRET_DIR` otherwise). `$secret` is a reserved key at any depth: the Guardian scans params recursively, so a reference nested inside another object is found and treated exactly like a top-level one, and no module param may use `$secret` as an ordinary key. Secret references are allowed only in catalog entries of in-process kinds, and are resolved when the instance is created. They are rejected in catalog entries of remote kinds (a remote module holds its own credentials) and in per-account params written through the operator API (otherwise a session could read arbitrary secrets through a module). Resolved secret values are never placed in a `HookRequest`, so they never reach a remote module. An in-process instance whose catalog params contain references receives, in its own `HookRequest.params`, the unresolved form with the references intact; it holds the resolved values from its factory, which received them when the instance was created. The `serve` harness and the conformance suite follow the same rule and never substitute. -The catalog is loaded in `ServerBuilder::build()`, after every `with_module_kind` call, so custom kinds are registered before any instance names them. `build()` creates every instance through its kind's factory, calls `describe` on it and checks that it supports the hooks it is configured for and speaks a supported `protocol_version`, then calls `validate_params` on the instance's stored global params (the catalog's `params` on first start), in the same unresolved form the module later receives in `HookRequest.params` (secret references intact), so a mistyped value in the catalog fails at startup rather than on the first transaction. In the prod stage a mismatch or an unreachable enabled module stops startup, mirroring `reject_filesystem_in_prod`; a disabled instance that fails these checks is logged and stays disabled, and enabling it runs the same checks first. Failing to create the instance at all, because its kind is not registered or its factory rejects the configuration (for example a malformed endpoint), is one of these failures: it stops startup for an enabled instance and leaves a disabled one disabled, so an operator can stage an instance for a module or a build that is not deployed yet. +The catalog is loaded in `ServerBuilder::build()`, after every `with_module_kind` call, so custom kinds are registered before any instance names them. `build()` creates every instance through its kind's factory, calls `describe` on it and checks that it supports the hooks it is configured for and speaks a supported `protocol_version`, then calls `validate_params` on the instance's stored global params (the catalog's `params` on first start), in the same unresolved form the module later receives in `HookRequest.params` (secret references intact), so a mistyped value in the catalog fails at startup rather than on the first transaction. A mismatch stops startup, and so does an unreachable enabled module that is new to this Guardian (no stored instance row), so a wrong endpoint in a new catalog entry is found when it is deployed. An enabled instance that has started here before and whose module does not answer does not stop startup: it starts unavailable, with its breaker held open so its accounts follow `on_error`, and each health probe runs the full startup checks (the params that apply included) until they pass. A third party's outage therefore cannot keep the Guardian from restarting or scaling out, while nothing is approved that the module would have judged. A module that answers but refuses the call, the params or the protocol version still stops startup; a disabled instance that fails these checks is logged and stays disabled, and enabling it runs the same checks first. Failing to create the instance at all, because its kind is not registered or its factory rejects the configuration (for example a malformed endpoint), is one of these failures: it stops startup for an enabled instance and leaves a disabled one disabled, so an operator can stage an instance for a module or a build that is not deployed yet. **Scopes** decide which accounts a module applies to without the operator visiting every account: @@ -325,7 +325,7 @@ This revision specifies the operator API only; no operator dashboard page is pla **Runtime changes without a restart.** The catalog file is read only at startup. Hot reload was considered and rejected (section 8): on ECS, the production target, configuration reaches tasks through the task definition and image, so there is no file to change without a deploy; file watching is unreliable across network and container mounts; and with several replicas a reload reaches one process, so for a newly added `all` module the other replicas keep signing without it. The needs behind a reload are met by state in the metadata store instead, which every replica reads, so a change applies to all replicas at once: - **Global params, account layers and per-account assignment** (above). -- **Seed rule for `enabled`.** The catalog's `enabled` value is written to the metadata store only the first time an instance id is seen. After that the stored flag is the only switch: a redeploy that changes `enabled` in the file changes nothing, and the server logs a warning at startup when the file and the stored flag differ, lists the instance with `"enabled_drift": true` in `GET /dashboard/modules`, and exports `guardian_module_config_drift{module}`. Removing an instance from the catalog stops it but keeps its stored flag; adding the same id back resumes with that stored flag, not the file's value. The file is therefore not the switch for an existing instance; the operator API is. +- **Seed rule for `enabled`.** The catalog's `enabled` value is written to the metadata store only the first time an instance id is seen. After that the stored flag is the switch, with one exception that only tightens policy: an instance the catalog declares `enabled = true` and not `operator_can_disable` is enabled at startup when it is stored as disabled, with a history entry by `catalog`, since no operator may hold such an instance off under that catalog (the disable predates it). Otherwise a redeploy that changes `enabled` in the file changes nothing, and the server logs a warning at startup when the file and the stored flag differ, lists the instance with `"enabled_drift": true` in `GET /dashboard/modules`, and exports `guardian_module_config_drift{module}`. Removing an instance from the catalog stops it but keeps its stored flag; adding the same id back resumes with that stored flag, not the file's value. The file is therefore not the switch for an existing instance; the operator API is. - **Runtime enable and disable of declared instances.** `POST /dashboard/modules/{module_id}/enable` (permission `policies:write`) and `/disable` (`policies:write` or `modules:disable`), each with a required reason and an audit record, switch evaluation on or off for every account. The two directions carry different risk. Enabling only tightens policy and is always allowed, so an operator can declare an instance with `enabled = false` and switch it on later without a restart. Disabling loosens policy: an API that could disable any module would let a stolen operator session switch off sanctions screening for every account, which undoes invariant 4. It is therefore allowed only for instances with `operator_can_disable = true`. An instance declared with `enabled = false` and `operator_can_disable = false` is deliberately one-way: a staged rollout that an operator can switch on once and cannot switch off from a session; compliance instances leave the flag off, while advisory modules such as a fail-open risk scorer can turn it on as an emergency stop for a faulty module. The flag lives in `module_instances`, and the pipeline reads it per evaluation through the per-replica cache, so a switch reaches every replica on its next evaluation; it is also the flag that decides at startup whether an instance failing its checks stops the server. `guardian_module_enabled{module}` (0 when disabled) is exported for alarms. A disabled instance is skipped by `evaluate` but keeps receiving `notify`, so its state is current when it is enabled. Only adding an instance, removing one, or changing its kind, endpoint, auth, hooks, timeout or `on_error` needs a deploy, and deploy review is the bar wanted for those changes. A rolling deploy still leaves replicas on different catalogs for its duration, so each replica exports the hash of the catalog it loaded (`guardian_module_catalog_info{catalog_hash}` and in `/dashboard/info`) and logs each instance's module build (`name version` from `describe`) at startup, also shown in `GET /dashboard/modules`. The catalog file itself lives in the deploy repository, where its hash finds it. @@ -806,7 +806,7 @@ The reference kind reads only the projection and the account views. Each rule de | Param | Rule | `reason_code` | |---|---|---| | `recipient_allowlist` | Every payment note's `p2id_target` is listed. A partial note, or one whose script is not a known P2ID or P2IDE script (no `p2id_target`), is refused, since its recipient cannot be checked | `recipient_not_allowed` | -| `recipient_denylist` | No payment note's `p2id_target` is listed; with `deny_unknown_recipients = true`, a partial or non-P2ID note is refused as well, since a denylist cannot otherwise check it | `recipient_blocked` | +| `recipient_denylist` | No payment note's `p2id_target` is listed. A partial or non-P2ID note is refused as well once the list names anyone, since a blocked recipient could otherwise be paid through a note the denylist cannot check; `deny_unknown_recipients = false` opts out, and `true` applies it to an empty list too | `recipient_blocked` | | `asset_allowlist` | Every asset sent in a payment note or received in an input note is listed; vault changes are not used, because they cannot tell a fee from a payment | `asset_not_allowed` | | `max_amount_per_tx` | Per listed faucet, the gross amount leaving the account (the sum of that faucet's fungible amounts over every output note, full or partial) is at most the cap. Amounts of different assets are not comparable, so the cap is per asset; input notes do not offset it, so a payment cannot be split across notes or netted against a receive; faucets not listed are uncapped; non-fungible assets are governed only by `asset_allowlist` | `amount_cap_exceeded` | | `signer_allowlist` or `signer_denylist`, with `signer_check` | The checked signers (section 2.3, signer allowlist example) are all on the allowlist, or none is on the denylist; an instance sets at most one of the two | `signer_not_allowed` | @@ -1205,7 +1205,7 @@ None. Questions resolved in earlier revisions are kept below with their answers. | Revision | Date | Changes | |---|---|---| -| 32 | 2026-11-10 | review of the M2a implementation. Protocol version 1 reopened (section 7): `Decision.allow` and the `decision.effect` capability removed, a decision without an effect is a module failure (section 3.5); `MidenTransaction.reference_block` and `expiration_block` replaced by `bound_block`, `expiration_delta` and `approval_expiration_block`, and `nonce_delta` made unsigned (section 3.1); `network_id` is the Guardian's configured network, not the account's registered one (section 3.1); `RegistrationSubject.initial_state` is sent; `tx_fee` is set only while the fee note carries no more of the fee asset than a transaction can owe, 64 times the chain's verification base fee, and for no note on a chain that charges nothing (section 3.1). Breaker: requests a module rejects do not count, a module whose timeout is the whole budget can open it, half-open sends one trial at a time, dry-run checks neither probe nor close it (section 4.4). Fail-open skips at proposal creation and registration, where no delta is signed, are recorded as `modules.failed_open` audit events; operator writes are audited with the params version they committed as (section 2.2). A health probe that finds a module incompatible opens its breaker at once and one that gets no answer counts as a failed call (section 4.4). Body corrected to the implementation: metric names, the fixed 1000 ms timeout cap, params encoding, the `circuit_open` failure kind | +| 32 | 2026-11-10 | review of the M2a implementation. Protocol version 1 reopened (section 7): `Decision.allow` and the `decision.effect` capability removed, a decision without an effect is a module failure (section 3.5); `MidenTransaction.reference_block` and `expiration_block` replaced by `bound_block`, `expiration_delta` and `approval_expiration_block`, and `nonce_delta` made unsigned (section 3.1); `network_id` is the Guardian's configured network, not the account's registered one (section 3.1); `RegistrationSubject.initial_state` is sent; `tx_fee` is set only while the fee note carries no more of the fee asset than a transaction can owe, 64 times the chain's verification base fee, and for no note on a chain that charges nothing (section 3.1). Breaker: requests a module rejects do not count, a module whose timeout is the whole budget can open it, half-open sends one trial at a time, dry-run checks neither probe nor close it (section 4.4). Fail-open skips at proposal creation and registration, where no delta is signed, are recorded as `modules.failed_open` audit events; operator writes are audited with the params version they committed as (section 2.2). A health probe that finds a module incompatible opens its breaker at once and one that gets no answer counts as a failed call (section 4.4). Startup: a known instance whose module does not answer starts unavailable instead of stopping the server, and an instance the catalog declares enabled and not operator-disableable is enabled even when stored as disabled (section 2.2). `basic-policy`: per-field id lengths, and `deny_unknown_recipients` defaults to on once the denylist names anyone (section 3.1). The conformance suite checks stated outcomes and needs a request the module must deny. Body corrected to the implementation: metric names, the fixed 1000 ms timeout cap, params encoding, the `circuit_open` failure kind | | 31 | 2026-11-09 | failures of dry-run checks do not count toward the circuit breaker, since a cosigner sends them without anyone's signature (section 4.4); the per-account budget check refuses only writes that raise an over-budget cost (section 4.3); `GUARDIAN_MODULE_UNAVAILABLE` and `GUARDIAN_EXECUTION_MODULE_UNAVAILABLE` omit `module` for an instance whose denials are generic (section 4.1); `metadata.modules` is kept out of client delta responses (section 2.2). `OutputNote.tx_fee` set only for the fee note `pay_fee` creates (section 3.1): the only `TX_FEE` note, with the derived serial number and one asset of the chain's fee faucet. Revisions 20 to 30 set it for any note with the `TX_FEE` script, which a transaction script can create with any assets, so the flag let funds past every `basic-policy` rule. No wire change; the field's meaning is narrowed | | 30 | 2026-11-09 | the secrets backend named: `GUARDIAN_MODULE_SECRET_PROVIDER` selects AWS Secrets Manager (the prod default) or owner-only files below `GUARDIAN_MODULE_SECRET_DIR`, read once when the instances are created; a secret that cannot be read fails creation, with the enabled/disabled rule of section 2.2. Field names fixed as `auth.token_secret`, `tls.client_cert_secret` and `tls.client_key_secret`; a secret name is 1 to 512 characters of letters, digits and `/_+=.@-`, and a `$secret` object has no other key (section 2.2). In-process factories read `$secret` values from `ModuleInstanceConfig::secret`. No protocol change | | 29 | 2026-11-09 | M2a implementation of `scope = default`: the copy is written right after the claim, only into an account with no assignment and no assignment history, under the module state lock, instead of in the claim's transaction on Postgres and before the claim on the filesystem; a crash in between is repaired by the unfinished-claim retry, so both backends follow one rule and no transaction spans the metadata and module stores (section 2.3). No protocol change | diff --git a/docs/runbooks/policy-modules.md b/docs/runbooks/policy-modules.md index 53e20622..d4bba089 100644 --- a/docs/runbooks/policy-modules.md +++ b/docs/runbooks/policy-modules.md @@ -88,7 +88,11 @@ module is skipped without waiting for its timeout. set `on_error = "allow"`, or `operator_can_disable = true` and then disable through the API, or remove the instance. Editing `enabled` in the catalog does nothing once the instance has started once: the stored flag - applies and `guardian_module_config_drift` reports the difference. + applies and `guardian_module_config_drift` reports the difference. The one + exception tightens policy: an instance the catalog declares enabled and + not `operator_can_disable` is switched on at startup even when it is + stored as disabled, with a params history entry by `catalog`, so making an + instance non-disableable in the catalog also ends an earlier disable. Removing an instance leaves its account assignments in place, marked `orphaned` and skipped, so adding it back restores them. @@ -144,9 +148,22 @@ Symptoms: `timed out` failures, the p99 of ## The server does not start An enabled instance that cannot be created or fails its startup checks stops -startup: an unknown kind, an unreachable module, a token the module rejects, a -secret the secrets backend cannot read, or params the module refuses. The log -names the instance (`module : ...`). +startup: an unknown kind, a token the module rejects, a module that answers +with a protocol version or hooks the Guardian cannot use, a secret the secrets +backend cannot read, params the module refuses, or an unreachable module of an +instance that has never started on this Guardian. The log names the instance +(`module : ...`). + +A module that is merely down does not stop a restart once its instance has +started here before. The server logs `Enabled module did not answer its +startup checks` and starts with that instance unavailable: its circuit is +open, so its accounts get `GUARDIAN_MODULE_UNAVAILABLE` (or skip it with +`on_error = "allow"`, recorded as a fail-open skip), and every other account +is served. Each health probe then runs the full startup checks, and the +instance comes back on its own once they pass (`Policy module passed the +startup checks it could not be reached for`). If the module returns with +params it now refuses, the instance stays unavailable and the log says why: +write params it accepts through the operator API. - Fix the cause (start the module, fix the secret, see [secrets](./secrets.md#policy-module-secrets)), or From 7de4aec47cd65cffb73c968dbf997d13dbab0337 Mon Sep 17 00:00:00 2001 From: Zeljko Date: Tue, 10 Nov 2026 10:41:14 +0100 Subject: [PATCH 089/105] feat(modules)!: split basic-policy into four policies with short params (#251) basic-policy enforced five unrelated rules from one params object. It is replaced by four first-party kinds, one concern each: - spending-limit: max_per_transaction, allowed_assets (proposal creation, transaction approval) - recipient-policy: allowlist or denylist, deny_unknown (proposal creation, transaction approval) - signer-policy: allowlist or denylist, check (all three hooks) - code-policy: allowed, check (all three hooks) Each kind refuses params that belong to another and supports only the hooks where its rule can refuse something, so a catalog that subscribes a spending or recipient rule to registration does not start. A recipient allowlist and denylist can no longer be set together. An instance with no rule allows without reading the request; one with a rule that cannot read what it needs is an error, so on_error applies. Reason codes and client messages are unchanged, so the client SDKs need no change. The SDK exposes guardian_module_sdk::policies (SpendingLimit, RecipientPolicy, SignerPolicy, CodePolicy, KINDS) with one conformance suite per kind. examples/policy-module serves any of them with --kind. The qualification stack's qual-gate and qual-switch are signer-policy, and a new qual-cap (spending-limit) carries the live cap scenario. --- crates/client/src/testing/mocks.rs | 4 +- .../guardian-module-sdk/src/basic_policy.rs | 1023 ----------------- crates/guardian-module-sdk/src/conformance.rs | 6 +- crates/guardian-module-sdk/src/lib.rs | 2 +- .../src/policies/code_policy.rs | 228 ++++ .../guardian-module-sdk/src/policies/mod.rs | 281 +++++ .../src/policies/recipient_policy.rs | 279 +++++ .../src/policies/signer_policy.rs | 232 ++++ .../src/policies/spending_limit.rs | 324 ++++++ .../guardian-module-sdk/tests/conformance.rs | 144 ++- .../src/scenario/modules.rs | 34 +- crates/server/src/api/dashboard_modules.rs | 12 +- crates/server/src/builder/mod.rs | 3 +- crates/server/src/modules/admin.rs | 38 +- crates/server/src/modules/catalog.rs | 16 +- crates/server/src/modules/mod.rs | 2 +- crates/server/src/modules/pipeline.rs | 33 +- crates/server/src/modules/postgres_store.rs | 18 +- crates/server/src/modules/registry.rs | 32 +- crates/server/src/modules/secrets.rs | 4 +- .../src/services/execute_proposal/tests.rs | 4 +- crates/server/src/services/push_delta.rs | 4 +- examples/policy-module/Cargo.toml | 2 +- examples/policy-module/Dockerfile | 2 +- examples/policy-module/src/main.rs | 32 +- packages/guardian-client/src/http.test.ts | 8 +- .../guardian-operator-client/src/http.test.ts | 12 +- .../tests/qualification/actions/live.ts | 18 +- .../tests/qualification/actions/modules.ts | 3 +- qualification/manifest/scenarios.toml | 2 +- qualification/stack/lib/modules.sh | 14 +- 31 files changed, 1628 insertions(+), 1188 deletions(-) delete mode 100644 crates/guardian-module-sdk/src/basic_policy.rs create mode 100644 crates/guardian-module-sdk/src/policies/code_policy.rs create mode 100644 crates/guardian-module-sdk/src/policies/mod.rs create mode 100644 crates/guardian-module-sdk/src/policies/recipient_policy.rs create mode 100644 crates/guardian-module-sdk/src/policies/signer_policy.rs create mode 100644 crates/guardian-module-sdk/src/policies/spending_limit.rs diff --git a/crates/client/src/testing/mocks.rs b/crates/client/src/testing/mocks.rs index 146a389b..fe942445 100644 --- a/crates/client/src/testing/mocks.rs +++ b/crates/client/src/testing/mocks.rs @@ -769,7 +769,9 @@ impl Guardian for MockGuardianService { module_id: "caps".into(), hooks: vec!["before_transaction_approved".into()], description: "At most 5 per transaction".into(), - params: Some(r#"{"max_amount_per_tx":{"0xaa":"5"}}"#.into()), + params: Some( + r#"{"max_per_transaction":{"0x0000000000000000000000000000aa":"5"}}"#.into(), + ), account_layer: None, }], error_code: String::new(), diff --git a/crates/guardian-module-sdk/src/basic_policy.rs b/crates/guardian-module-sdk/src/basic_policy.rs deleted file mode 100644 index e4c4b154..00000000 --- a/crates/guardian-module-sdk/src/basic_policy.rs +++ /dev/null @@ -1,1023 +0,0 @@ -//! Reference policy: per-asset amount cap, asset and recipient allowlists, signer lists. - -use std::collections::{BTreeMap, BTreeSet}; - -use async_trait::async_trait; -use serde::Deserialize; - -use crate::proto::{asset, hook_request}; -use crate::{ - AccountView, Decision, DescribeRequest, Hook, HookRequest, MidenTransaction, Module, - ModuleError, ModuleInfo, PROTOCOL_VERSION, ParamsVerdict, TransactionSubject, -}; - -pub const KIND: &str = "basic-policy"; - -#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Deserialize)] -#[serde(rename_all = "snake_case")] -pub enum SignerCheck { - #[default] - Added, - All, -} - -/// Which code `allowed_code_commitments` checks: only code an account registers with or changes -/// to (`changed`), or the code it runs at every gate hook (`all`). -#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Deserialize)] -#[serde(rename_all = "snake_case")] -pub enum CodeCheck { - #[default] - Changed, - All, -} - -#[derive(Debug, Clone, Default, Deserialize)] -#[serde(deny_unknown_fields)] -pub struct Params { - #[serde(default)] - pub max_amount_per_tx: BTreeMap, - #[serde(default)] - pub asset_allowlist: Option>, - #[serde(default)] - pub recipient_allowlist: Option>, - #[serde(default)] - pub recipient_denylist: Option>, - /// Whether a payment note whose recipient cannot be identified (a partial note, or one - /// that is neither P2ID nor P2IDE) is refused by the denylist. Unset, it is refused - /// whenever the denylist names anyone: otherwise a blocked recipient is paid by wrapping - /// the payment in a note the Guardian cannot read. - #[serde(default)] - pub deny_unknown_recipients: Option, - #[serde(default)] - pub signer_allowlist: Option>, - #[serde(default)] - pub signer_denylist: Option>, - #[serde(default)] - pub signer_check: Option, - #[serde(default)] - pub allowed_code_commitments: Option>, - #[serde(default)] - pub code_check: Option, -} - -struct Policy { - caps: BTreeMap, - assets: Option>, - recipients: Option>, - blocked_recipients: Option>, - deny_unknown_recipients: bool, - signers: Option, - signer_check: SignerCheck, - code: Option>, - code_check: CodeCheck, -} - -enum SignerList { - Allow(BTreeSet), - Deny(BTreeSet), -} - -impl SignerList { - fn permits(&self, signer: &str) -> bool { - match self { - SignerList::Allow(list) => list.contains(signer), - SignerList::Deny(list) => !list.contains(signer), - } - } -} - -fn normalized(values: &[String]) -> BTreeSet { - values.iter().map(|v| v.to_ascii_lowercase()).collect() -} - -/// What an id names, which fixes its length in the hex form the Guardian reports it in. -#[derive(Clone, Copy)] -enum IdKind { - /// A faucet or a recipient: an account id. - Account, - /// A signer commitment or a code commitment: a word. - Commitment, -} - -impl IdKind { - fn hex_digits(self) -> usize { - match self { - IdKind::Account => 30, - IdKind::Commitment => 64, - } - } - - fn noun(self) -> &'static str { - match self { - IdKind::Account => "an account id", - IdKind::Commitment => "a commitment", - } - } -} - -/// Ids in the hex form the Guardian reports them in (`0x` and the hex digits of an account id or -/// a commitment), lowercased. Any other spelling would never match a request, so a denylist or a -/// cap would silently not apply; it is refused instead: a bech32 address, a placeholder left in -/// an example catalog, an id cut short when it was pasted, or an account id where a commitment -/// belongs. -fn ids(field: &str, kind: IdKind, values: &[String]) -> Result, String> { - values.iter().map(|value| id(field, kind, value)).collect() -} - -fn id(field: &str, kind: IdKind, value: &str) -> Result { - let digits = value - .strip_prefix("0x") - .or_else(|| value.strip_prefix("0X")) - .filter(|rest| rest.bytes().all(|b| b.is_ascii_hexdigit())); - match digits { - Some(rest) if rest.len() == kind.hex_digits() => Ok(value.to_ascii_lowercase()), - Some(rest) if !rest.is_empty() => Err(format!( - "{field}: {value:?} has {} hex digits, but {} has {}", - rest.len(), - kind.noun(), - kind.hex_digits() - )), - _ => Err(format!( - "{field}: {value:?} is not an id in 0x hex form (a bech32 address is not accepted)" - )), - } -} - -impl TryFrom for Policy { - type Error = String; - - fn try_from(params: Params) -> Result { - let mut caps = BTreeMap::new(); - for (faucet, amount) in params.max_amount_per_tx { - let faucet = id("max_amount_per_tx", IdKind::Account, &faucet)?; - let amount = amount - .parse::() - .map_err(|_| format!("max_amount_per_tx for {faucet} is not a decimal amount"))?; - if caps.insert(faucet.clone(), amount).is_some() { - return Err(format!( - "max_amount_per_tx names {faucet} more than once (ids are compared in lowercase)" - )); - } - } - if params.deny_unknown_recipients.is_some() && params.recipient_denylist.is_none() { - return Err( - "deny_unknown_recipients applies to recipient_denylist, which is not set".into(), - ); - } - if params.signer_check.is_some() - && params.signer_allowlist.is_none() - && params.signer_denylist.is_none() - { - return Err( - "signer_check applies to signer_allowlist or signer_denylist, neither of which is set" - .into(), - ); - } - if params.code_check.is_some() && params.allowed_code_commitments.is_none() { - return Err("code_check applies to allowed_code_commitments, which is not set".into()); - } - let signers = match (params.signer_allowlist, params.signer_denylist) { - (Some(_), Some(_)) => { - return Err("signer_allowlist and signer_denylist are mutually exclusive".into()); - } - (Some(list), None) => Some(SignerList::Allow(ids( - "signer_allowlist", - IdKind::Commitment, - &list, - )?)), - (None, Some(list)) => Some(SignerList::Deny(ids( - "signer_denylist", - IdKind::Commitment, - &list, - )?)), - (None, None) => None, - }; - Ok(Self { - caps, - assets: params - .asset_allowlist - .as_deref() - .map(|list| ids("asset_allowlist", IdKind::Account, list)) - .transpose()?, - recipients: params - .recipient_allowlist - .as_deref() - .map(|list| ids("recipient_allowlist", IdKind::Account, list)) - .transpose()?, - blocked_recipients: params - .recipient_denylist - .as_deref() - .map(|list| ids("recipient_denylist", IdKind::Account, list)) - .transpose()?, - deny_unknown_recipients: params.deny_unknown_recipients.unwrap_or( - params - .recipient_denylist - .as_ref() - .is_some_and(|list| !list.is_empty()), - ), - signers, - signer_check: params.signer_check.unwrap_or_default(), - code: params - .allowed_code_commitments - .as_deref() - .map(|list| ids("allowed_code_commitments", IdKind::Commitment, list)) - .transpose()?, - code_check: params.code_check.unwrap_or_default(), - }) - } -} - -fn parse_policy(params: &[u8]) -> Result { - let params: Params = if params.is_empty() { - Params::default() - } else { - serde_json::from_slice(params).map_err(|e| e.to_string())? - }; - Policy::try_from(params) -} - -/// A `basic-policy` rule. Each denies with a fixed reason code and a fixed client message that -/// names the rule, never a list entry or a limit, so a denial discloses no params; the details -/// go only to the logged message. -#[derive(Debug, Clone, Copy)] -enum Rule { - RecipientAllowlist, - RecipientDenylist, - AssetAllowlist, - AmountCap, - Signers, - Code, -} - -impl Rule { - fn deny(self, logged: String) -> Decision { - let (reason_code, client_message) = match self { - Rule::RecipientAllowlist => ( - "recipient_not_allowed", - "A payment goes to a recipient this Guardian does not accept.", - ), - Rule::RecipientDenylist => ( - "recipient_blocked", - "A payment goes to a recipient this Guardian blocks.", - ), - Rule::AssetAllowlist => ( - "asset_not_allowed", - "The transaction moves an asset this Guardian does not accept.", - ), - Rule::AmountCap => ( - "amount_cap_exceeded", - "The transaction sends more than this Guardian allows per transaction.", - ), - Rule::Signers => ( - "signer_not_allowed", - "The account would have a signer this Guardian does not accept.", - ), - Rule::Code => ( - "code_not_allowed", - "The account would run code this Guardian does not accept.", - ), - }; - Decision::deny(reason_code, logged).with_client_message(client_message) - } -} - -impl Policy { - fn evaluate(&self, request: &HookRequest) -> Result { - if let Some(signers) = &self.signers { - let after = request - .after - .as_ref() - .ok_or_else(|| ModuleError::InvalidRequest("request has no account view".into()))?; - if let Some(signer) = self - .checked_signers(request.before.as_ref(), after) - .into_iter() - .find(|signer| !signers.permits(signer)) - { - return Ok(Rule::Signers.deny(format!("signer {signer} is not permitted"))); - } - } - if let Some(allowed) = &self.code - && let Some(code) = self.checked_code(request)? - && !allowed.contains(&code.to_ascii_lowercase()) - { - return Ok(Rule::Code.deny(format!("code {code} is not allowed"))); - } - match &request.subject { - Some(hook_request::Subject::Transaction(tx)) => self.evaluate_transaction(tx), - Some(hook_request::Subject::Registration(_)) => Ok(Decision::allow()), - None => Err(ModuleError::InvalidRequest("request has no subject".into())), - } - } - - /// The code commitment `allowed_code_commitments` must list for this request, if any: under - /// `changed` the code an account registers with or a transaction replaces its code with, - /// under `all` the code the account runs after the request, at every hook. - fn checked_code(&self, request: &HookRequest) -> Result, ModuleError> { - let after_code = || { - request - .after - .as_ref() - .map(|after| after.code_commitment.clone()) - .ok_or_else(|| ModuleError::InvalidRequest("request has no account view".into())) - }; - match (self.code_check, &request.subject) { - (CodeCheck::All, _) - | (CodeCheck::Changed, Some(hook_request::Subject::Registration(_))) => { - after_code().map(Some) - } - (CodeCheck::Changed, Some(hook_request::Subject::Transaction(tx))) => Ok(tx - .miden() - .and_then(|projection| projection.new_code_commitment.clone())), - (CodeCheck::Changed, None) => Ok(None), - } - } - - fn checked_signers(&self, before: Option<&AccountView>, after: &AccountView) -> Vec { - let existing: BTreeSet = match (self.signer_check, before) { - (SignerCheck::Added, Some(before)) => normalized(&before.signer_commitments), - _ => BTreeSet::new(), - }; - normalized(&after.signer_commitments) - .into_iter() - .filter(|signer| !existing.contains(signer)) - .collect() - } - - fn evaluate_transaction(&self, tx: &TransactionSubject) -> Result { - let Some(projection) = tx.miden() else { - return Err(ModuleError::InvalidRequest( - "transaction has no Miden projection to judge".into(), - )); - }; - Ok(self.judge(projection)) - } - - fn judge(&self, projection: &MidenTransaction) -> Decision { - let payments = || projection.output_notes.iter().filter(|note| !note.tx_fee); - - if let Some(allowed) = &self.assets { - let sent = payments().flat_map(|n| n.assets.iter()); - let received = projection.input_notes.iter().flat_map(|n| n.assets.iter()); - if let Some(faucet) = sent - .chain(received) - .map(|a| a.faucet_id.to_ascii_lowercase()) - .find(|faucet| !allowed.contains(faucet)) - { - return Rule::AssetAllowlist.deny(format!("asset {faucet} is not allowed")); - } - } - - if let Some(allowed) = &self.recipients { - for note in payments() { - let recipient = match (¬e.p2id_target, note.partial) { - (Some(target), false) => target.to_ascii_lowercase(), - _ => { - return Rule::RecipientAllowlist - .deny(format!("note {} has no checkable recipient", note.note_id)); - } - }; - if !allowed.contains(&recipient) { - return Rule::RecipientAllowlist - .deny(format!("recipient {recipient} is not allowed")); - } - } - } - - if let Some(blocked) = &self.blocked_recipients { - for note in payments() { - match (¬e.p2id_target, note.partial) { - (Some(target), false) if blocked.contains(&target.to_ascii_lowercase()) => { - return Rule::RecipientDenylist - .deny(format!("recipient {target} is blocked")); - } - (Some(_), false) => {} - _ if self.deny_unknown_recipients => { - return Rule::RecipientDenylist - .deny(format!("note {} has no checkable recipient", note.note_id)); - } - _ => {} - } - } - } - - if !self.caps.is_empty() { - let mut sent: BTreeMap = BTreeMap::new(); - for asset in payments().flat_map(|n| n.assets.iter()) { - if let Some(asset::Value::FungibleAmount(amount)) = &asset.value { - let amount = amount.parse::().unwrap_or(u128::MAX); - let total = sent - .entry(asset.faucet_id.to_ascii_lowercase()) - .or_default(); - *total = total.saturating_add(amount); - } - } - for (faucet, cap) in &self.caps { - if sent.get(faucet).is_some_and(|total| total > cap) { - return Rule::AmountCap - .deny(format!("sent {} of {faucet}, cap {cap}", sent[faucet])); - } - } - } - - Decision::allow() - } -} - -#[derive(Debug, Default, Clone, Copy)] -pub struct BasicPolicy; - -#[async_trait] -impl Module for BasicPolicy { - async fn describe(&self, _guardian: &DescribeRequest) -> Result { - Ok(ModuleInfo { - name: KIND.into(), - version: env!("CARGO_PKG_VERSION").into(), - protocol_version: PROTOCOL_VERSION, - hooks: vec![ - Hook::BeforeTransactionApproved as i32, - Hook::BeforeProposalCreated as i32, - Hook::BeforeAccountRegistered as i32, - ], - ..Default::default() - }) - } - - async fn validate_params(&self, params: &[u8]) -> Result { - Ok(match parse_policy(params) { - Ok(_) => ParamsVerdict::ok(), - Err(message) => ParamsVerdict::invalid(message), - }) - } - - async fn evaluate(&self, request: &HookRequest) -> Result { - parse_policy(&request.params) - .map_err(ModuleError::InvalidRequest)? - .evaluate(request) - } -} - -#[cfg(test)] -mod tests { - use serde_json::json; - - use super::*; - use crate::{ - Asset, MidenTransaction, OutputNote, RegistrationSubject, TransactionProjection, - VaultChange, - }; - - const USDC: &str = "0x00000000000000000000000000aa00"; - const ETH: &str = "0x00000000000000000000000000bb00"; - - fn fungible(faucet: &str, amount: u64) -> Asset { - Asset { - faucet_id: faucet.into(), - value: Some(asset::Value::FungibleAmount(amount.to_string())), - } - } - - fn p2id(target: &str, assets: Vec) -> OutputNote { - OutputNote { - note_id: format!("0xnote{target}"), - assets, - p2id_target: Some(target.into()), - ..Default::default() - } - } - - fn view(signers: &[&str]) -> AccountView { - AccountView { - signer_commitments: signers.iter().map(|s| s.to_string()).collect(), - ..Default::default() - } - } - - fn tx_request(params: serde_json::Value, projection: MidenTransaction) -> HookRequest { - HookRequest { - params: serde_json::to_vec(¶ms).unwrap(), - before: Some(view(&[ - "0x0000000000000000000000000000000000000000000000000000000000000051", - ])), - after: Some(view(&[ - "0x0000000000000000000000000000000000000000000000000000000000000051", - ])), - subject: Some(hook_request::Subject::Transaction(TransactionSubject { - projection: Some(TransactionProjection::miden(projection)), - ..Default::default() - })), - ..Default::default() - } - } - - async fn decide(request: &HookRequest) -> Decision { - BasicPolicy.evaluate(request).await.unwrap() - } - - fn cap() -> serde_json::Value { - json!({ "max_amount_per_tx": { USDC: "1000" } }) - } - - #[tokio::test] - async fn allows_a_payment_under_the_cap() { - let projection = MidenTransaction { - output_notes: vec![p2id( - "0x0000000000000000000000000000a1", - vec![fungible(USDC, 500)], - )], - ..Default::default() - }; - assert!(decide(&tx_request(cap(), projection)).await.allows()); - } - - #[tokio::test] - async fn sums_split_payments_against_the_cap() { - let projection = MidenTransaction { - output_notes: vec![ - p2id( - "0x0000000000000000000000000000a1", - vec![fungible(USDC, 600)], - ), - p2id( - "0x0000000000000000000000000000a2", - vec![fungible(USDC, 600)], - ), - ], - ..Default::default() - }; - let decision = decide(&tx_request(cap(), projection)).await; - assert!(!decision.allows()); - assert_eq!(decision.reason_code, "amount_cap_exceeded"); - } - - #[tokio::test] - async fn incoming_amounts_do_not_offset_outgoing() { - let projection = MidenTransaction { - vault_changes: vec![VaultChange { - asset: Some(fungible(USDC, 500)), - direction: crate::Direction::Out as i32, - }], - input_notes: vec![crate::InputNote { - note_id: "0x14".into(), - assets: vec![fungible(USDC, 1000)], - }], - output_notes: vec![p2id( - "0x0000000000000000000000000000a1", - vec![fungible(USDC, 1500)], - )], - ..Default::default() - }; - assert!(!decide(&tx_request(cap(), projection)).await.allows()); - } - - #[tokio::test] - async fn uncapped_assets_and_nfts_are_not_counted() { - let nft = Asset { - faucet_id: USDC.into(), - value: Some(asset::Value::NftId("0x4f7".into())), - }; - let projection = MidenTransaction { - output_notes: vec![p2id( - "0x0000000000000000000000000000a1", - vec![fungible(ETH, 5000), nft], - )], - ..Default::default() - }; - assert!(decide(&tx_request(cap(), projection)).await.allows()); - } - - fn fee_note(amount: u64) -> OutputNote { - OutputNote { - note_id: "0xfee".into(), - assets: vec![fungible(USDC, amount)], - tx_fee: true, - ..Default::default() - } - } - - #[tokio::test] - async fn the_fee_note_is_not_a_payment() { - let projection = MidenTransaction { - output_notes: vec![ - fee_note(5000), - p2id( - "0x0000000000000000000000000000a1", - vec![fungible(USDC, 500)], - ), - ], - ..Default::default() - }; - assert!( - decide(&tx_request(cap(), projection.clone())) - .await - .allows() - ); - - let params = json!({ "recipient_allowlist": ["0x0000000000000000000000000000a1"], "asset_allowlist": [ETH, USDC] }); - assert!(decide(&tx_request(params, projection)).await.allows()); - - let only_fee = MidenTransaction { - output_notes: vec![fee_note(5000)], - ..Default::default() - }; - assert!( - decide(&tx_request(json!({ "asset_allowlist": [ETH] }), only_fee)) - .await - .allows() - ); - } - - #[tokio::test] - async fn recipient_allowlist_denies_partial_and_unlisted_notes() { - let params = json!({ "recipient_allowlist": ["0x0000000000000000000000000000a1"] }); - let listed = MidenTransaction { - output_notes: vec![p2id( - "0x0000000000000000000000000000A1", - vec![fungible(USDC, 1)], - )], - ..Default::default() - }; - assert!(decide(&tx_request(params.clone(), listed)).await.allows()); - - let mut partial_note = p2id("0x0000000000000000000000000000a1", vec![fungible(USDC, 1)]); - partial_note.partial = true; - let partial = MidenTransaction { - output_notes: vec![partial_note], - ..Default::default() - }; - assert_eq!( - decide(&tx_request(params.clone(), partial)) - .await - .reason_code, - "recipient_not_allowed" - ); - - let unlisted = MidenTransaction { - output_notes: vec![p2id( - "0x0000000000000000000000000000a9", - vec![fungible(USDC, 1)], - )], - ..Default::default() - }; - assert!(!decide(&tx_request(params, unlisted)).await.allows()); - } - - #[tokio::test] - async fn asset_allowlist_covers_sent_and_received_assets() { - let params = json!({ "asset_allowlist": [USDC] }); - let projection = MidenTransaction { - output_notes: vec![p2id( - "0x0000000000000000000000000000a1", - vec![fungible(ETH, 1)], - )], - ..Default::default() - }; - assert_eq!( - decide(&tx_request(params, projection)).await.reason_code, - "asset_not_allowed" - ); - } - - #[tokio::test] - async fn recipient_denylist_blocks_listed_recipients_only() { - let params = json!({ "recipient_denylist": ["0x000000000000000000000000000BAD"] }); - let blocked = MidenTransaction { - output_notes: vec![ - fee_note(1), - p2id("0x000000000000000000000000000bad", vec![fungible(USDC, 1)]), - ], - ..Default::default() - }; - assert_eq!( - decide(&tx_request(params.clone(), blocked)) - .await - .reason_code, - "recipient_blocked" - ); - - let mut partial = p2id("0x0000000000000000000000000000a1", vec![fungible(USDC, 1)]); - partial.partial = true; - let unknown = MidenTransaction { - output_notes: vec![ - p2id("0x0000000000000000000000000000a1", vec![fungible(USDC, 1)]), - partial, - ], - ..Default::default() - }; - assert_eq!( - decide(&tx_request(params, unknown.clone())) - .await - .reason_code, - "recipient_blocked", - "a recipient the denylist cannot check is refused: a blocked one could hide there" - ); - - let lenient = json!({ "recipient_denylist": ["0x000000000000000000000000000bad"], "deny_unknown_recipients": false }); - assert!( - decide(&tx_request(lenient, unknown.clone())).await.allows(), - "the operator opted out" - ); - - let nobody_listed = json!({ "recipient_denylist": [] }); - assert!( - decide(&tx_request(nobody_listed, unknown.clone())) - .await - .allows(), - "an empty denylist has nobody to hide" - ); - - let strict_anyway = json!({ "recipient_denylist": [], "deny_unknown_recipients": true }); - assert_eq!( - decide(&tx_request(strict_anyway, unknown)) - .await - .reason_code, - "recipient_blocked" - ); - } - - #[tokio::test] - async fn a_denial_names_its_rule_to_the_client_and_discloses_no_param() { - let projection = MidenTransaction { - output_notes: vec![p2id( - "0x0000000000000000000000000000a1", - vec![fungible(USDC, 5_000)], - )], - ..Default::default() - }; - let decision = decide(&tx_request(cap(), projection)).await; - assert_eq!(decision.reason_code, "amount_cap_exceeded"); - assert!(!decision.client_message.is_empty()); - assert!(decision.client_message.len() <= 256); - for detail in ["1000", "5000", USDC, "0x0000000000000000000000000000a1"] { - assert!( - !decision.client_message.contains(detail), - "{detail} leaked into {:?}", - decision.client_message - ); - } - assert!( - decision.message.contains("1000"), - "details stay in the logged message" - ); - } - - const REVIEWED: &str = "0x000000000000000000000000000000000000000000000000000000000000c0de"; - const UNREVIEWED: &str = "0x0000000000000000000000000000000000000000000000000000000000000bad"; - - fn code_rule(code_check: &str) -> serde_json::Value { - json!({ "allowed_code_commitments": [REVIEWED], "code_check": code_check }) - } - - fn running(mut request: HookRequest, code: &str) -> HookRequest { - if let Some(after) = request.after.as_mut() { - after.code_commitment = code.into(); - } - request - } - - fn registration(params: serde_json::Value, code: &str) -> HookRequest { - running( - HookRequest { - params: serde_json::to_vec(¶ms).unwrap(), - after: Some(view(&[ - "0x0000000000000000000000000000000000000000000000000000000000000051", - ])), - subject: Some(hook_request::Subject::Registration( - RegistrationSubject::default(), - )), - ..Default::default() - }, - code, - ) - } - - fn replacing_code_with(code: Option<&str>) -> MidenTransaction { - MidenTransaction { - new_code_commitment: code.map(str::to_string), - ..Default::default() - } - } - - #[tokio::test] - async fn changed_code_check_judges_registration_and_code_replacement_only() { - let rule = code_rule("changed"); - assert!(decide(®istration(rule.clone(), REVIEWED)).await.allows()); - let refused = decide(®istration(rule.clone(), UNREVIEWED)).await; - assert_eq!(refused.reason_code, "code_not_allowed"); - assert!(!refused.client_message.contains(UNREVIEWED)); - - let unchanged = running( - tx_request(rule.clone(), replacing_code_with(None)), - UNREVIEWED, - ); - assert!( - decide(&unchanged).await.allows(), - "code an account already runs is kept until it changes" - ); - let upgrade = tx_request(rule.clone(), replacing_code_with(Some(UNREVIEWED))); - assert_eq!(decide(&upgrade).await.reason_code, "code_not_allowed"); - let reviewed = tx_request(rule, replacing_code_with(Some(REVIEWED))); - assert!(decide(&reviewed).await.allows()); - } - - #[tokio::test] - async fn all_code_check_judges_the_code_an_account_runs_at_every_hook() { - let rule = code_rule("all"); - let unchanged = running( - tx_request(rule.clone(), replacing_code_with(None)), - UNREVIEWED, - ); - assert_eq!(decide(&unchanged).await.reason_code, "code_not_allowed"); - let upgraded = running( - tx_request(rule, replacing_code_with(Some(REVIEWED))), - REVIEWED, - ); - assert!( - decide(&upgraded).await.allows(), - "an account on unlisted code can still upgrade to listed code" - ); - } - - #[tokio::test] - async fn an_unknown_code_check_is_refused_when_the_params_are_written() { - let verdict = BasicPolicy - .validate_params( - &serde_json::to_vec(&json!({ - "allowed_code_commitments": [REVIEWED], - "code_check": "sometimes" - })) - .unwrap(), - ) - .await - .unwrap(); - assert!(!verdict.ok); - } - - #[tokio::test] - async fn a_transaction_without_a_miden_projection_is_not_judged() { - let mut request = tx_request(cap(), MidenTransaction::default()); - if let Some(hook_request::Subject::Transaction(subject)) = &mut request.subject { - subject.projection = None; - } - assert!(matches!( - BasicPolicy.evaluate(&request).await, - Err(ModuleError::InvalidRequest(_)) - )); - } - - #[tokio::test] - async fn asset_allowlist_covers_consumed_notes() { - let projection = MidenTransaction { - input_notes: vec![crate::InputNote { - note_id: "0x14".into(), - assets: vec![fungible(ETH, 1)], - }], - ..Default::default() - }; - assert_eq!( - decide(&tx_request( - json!({ "asset_allowlist": [USDC] }), - projection - )) - .await - .reason_code, - "asset_not_allowed" - ); - } - - #[tokio::test] - async fn forged_metadata_does_not_change_the_decision() { - let projection = MidenTransaction { - output_notes: vec![p2id( - "0x0000000000000000000000000000a1", - vec![fungible(USDC, 5000)], - )], - ..Default::default() - }; - let mut request = tx_request(cap(), projection); - if let Some(hook_request::Subject::Transaction(tx)) = &mut request.subject { - tx.unverified_metadata = - serde_json::to_vec(&json!({ "proposal_type": "change_threshold", "amount": "1" })) - .unwrap(); - } - assert!(!decide(&request).await.allows()); - } - - fn signer_request( - params: serde_json::Value, - before: Option<&[&str]>, - after: &[&str], - ) -> HookRequest { - HookRequest { - params: serde_json::to_vec(¶ms).unwrap(), - before: before.map(view), - after: Some(view(after)), - subject: Some(hook_request::Subject::Registration( - RegistrationSubject::default(), - )), - ..Default::default() - } - } - - #[tokio::test] - async fn added_mode_checks_only_new_signers() { - let params = json!({ "signer_allowlist": ["0x0000000000000000000000000000000000000000000000000000000000000052"] }); - let request = signer_request( - params.clone(), - Some(&["0x0000000000000000000000000000000000000000000000000000000000000051"]), - &[ - "0x0000000000000000000000000000000000000000000000000000000000000051", - "0x0000000000000000000000000000000000000000000000000000000000000052", - ], - ); - assert!(decide(&request).await.allows()); - - let request = signer_request( - params, - Some(&["0x0000000000000000000000000000000000000000000000000000000000000051"]), - &[ - "0x0000000000000000000000000000000000000000000000000000000000000051", - "0x0000000000000000000000000000000000000000000000000000000000000053", - ], - ); - assert_eq!(decide(&request).await.reason_code, "signer_not_allowed"); - } - - #[tokio::test] - async fn all_mode_checks_every_signer() { - let params = json!({ "signer_check": "all", "signer_allowlist": ["0x0000000000000000000000000000000000000000000000000000000000000052"] }); - let request = signer_request( - params, - Some(&["0x0000000000000000000000000000000000000000000000000000000000000051"]), - &[ - "0x0000000000000000000000000000000000000000000000000000000000000051", - "0x0000000000000000000000000000000000000000000000000000000000000052", - ], - ); - assert!(!decide(&request).await.allows()); - } - - #[tokio::test] - async fn registration_checks_every_initial_signer() { - let params = json!({ "signer_denylist": ["0x0000000000000000000000000000000000000000000000000000000000000bad"] }); - let request = signer_request( - params, - None, - &[ - "0x0000000000000000000000000000000000000000000000000000000000000051", - "0x0000000000000000000000000000000000000000000000000000000000000BAD", - ], - ); - assert!(!decide(&request).await.allows()); - } - - #[tokio::test] - async fn missing_account_view_is_an_error_not_an_allow() { - let mut request = signer_request( - json!({ "signer_allowlist": ["0x0000000000000000000000000000000000000000000000000000000000000051"] }), - None, - &[], - ); - request.after = None; - assert!(BasicPolicy.evaluate(&request).await.is_err()); - } - - #[tokio::test] - async fn validate_params_rejects_bad_input() { - for params in [ - json!({ "recipient_denylist": ["mtst1qrkd5x7qy0mw0yqzlvqlqd3w9cafjkw"] }), - json!({ "max_amount_per_tx": { "faucet": "10" } }), - json!({ "signer_denylist": ["0x"] }), - json!({ "unknown": 1 }), - json!({ "max_amount_per_tx": { USDC: "ten" } }), - json!({ "signer_allowlist": [], "signer_denylist": [] }), - json!({ "max_amount_per_tx": { "0xREPLACE_WITH_FAUCET_ID": "5" } }), - json!({ "max_amount_per_tx": { "0x0000000000000000000000000000AA": "5", "0x0000000000000000000000000000aa": "9" } }), - json!({ "recipient_denylist": ["0xa1b2c3"] }), - json!({ "signer_allowlist": ["0x000000000000000000000000000051"] }), - json!({ "allowed_code_commitments": [format!("0x{}", "c".repeat(63))] }), - json!({ "deny_unknown_recipients": true }), - json!({ "deny_unknown_recipients": false }), - json!({ "signer_check": "all" }), - json!({ "code_check": "all" }), - ] { - let verdict = BasicPolicy - .validate_params(&serde_json::to_vec(¶ms).unwrap()) - .await - .unwrap(); - assert!(!verdict.ok, "{params}"); - } - } - - #[tokio::test] - async fn evaluating_twice_gives_the_same_decision() { - let projection = MidenTransaction { - output_notes: vec![p2id( - "0x0000000000000000000000000000a1", - vec![fungible(USDC, 900)], - )], - ..Default::default() - }; - let request = tx_request(cap(), projection); - assert_eq!(decide(&request).await, decide(&request).await); - } -} diff --git a/crates/guardian-module-sdk/src/conformance.rs b/crates/guardian-module-sdk/src/conformance.rs index caea57a7..c61be9ff 100644 --- a/crates/guardian-module-sdk/src/conformance.rs +++ b/crates/guardian-module-sdk/src/conformance.rs @@ -14,13 +14,13 @@ //! //! ```no_run //! # async fn example(request: guardian_module_sdk::HookRequest, blocked: guardian_module_sdk::HookRequest) { -//! use guardian_module_sdk::basic_policy::BasicPolicy; +//! use guardian_module_sdk::policies::RecipientPolicy; //! use guardian_module_sdk::conformance::Suite; //! -//! Suite::new(BasicPolicy) +//! Suite::new(RecipientPolicy) //! .allows("small payment", request) //! .denies_with("payment to a blocked recipient", blocked, "recipient_blocked") -//! .valid_params(serde_json::json!({ "recipient_denylist": [] })) +//! .valid_params(serde_json::json!({ "denylist": [] })) //! .invalid_params(serde_json::json!({ "unknown": 1 })) //! .run() //! .await diff --git a/crates/guardian-module-sdk/src/lib.rs b/crates/guardian-module-sdk/src/lib.rs index 91322fc0..668b8ac3 100644 --- a/crates/guardian-module-sdk/src/lib.rs +++ b/crates/guardian-module-sdk/src/lib.rs @@ -2,9 +2,9 @@ use std::sync::Arc; -pub mod basic_policy; #[cfg(feature = "conformance")] pub mod conformance; +pub mod policies; pub mod serve; pub use async_trait::async_trait; diff --git a/crates/guardian-module-sdk/src/policies/code_policy.rs b/crates/guardian-module-sdk/src/policies/code_policy.rs new file mode 100644 index 00000000..9e9aef5e --- /dev/null +++ b/crates/guardian-module-sdk/src/policies/code_policy.rs @@ -0,0 +1,228 @@ +//! `code-policy`: which account code the account may run. + +use std::collections::BTreeSet; + +use async_trait::async_trait; +use serde::Deserialize; + +use super::{IdKind, Rule}; +use crate::proto::hook_request; +use crate::{ + Decision, DescribeRequest, Hook, HookRequest, Module, ModuleError, ModuleInfo, ParamsVerdict, +}; + +pub const KIND: &str = "code-policy"; + +const HOOKS: [Hook; 3] = [ + Hook::BeforeAccountRegistered, + Hook::BeforeProposalCreated, + Hook::BeforeTransactionApproved, +]; + +/// Which code `allowed` is checked against. +#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum CodeCheck { + /// The code an account registers with, and code a transaction replaces it with; an account + /// already on other code keeps working until it changes code. + #[default] + Changed, + /// The code the account runs after the registration or transaction, at every hook. + All, +} + +#[derive(Debug, Clone, Default, Deserialize)] +#[serde(deny_unknown_fields)] +pub struct Params { + /// The account code commitments the account may run. + #[serde(default)] + pub allowed: Option>, + /// Which code `allowed` is checked against; `changed` unless set. Needs `allowed`. + #[serde(default)] + pub check: Option, +} + +struct Rules { + allowed: Option>, + check: CodeCheck, +} + +impl TryFrom for Rules { + type Error = String; + + fn try_from(params: Params) -> Result { + if params.check.is_some() && params.allowed.is_none() { + return Err("check applies to allowed, which is not set".into()); + } + Ok(Self { + allowed: params + .allowed + .as_deref() + .map(|list| super::ids("allowed", IdKind::Commitment, list)) + .transpose()?, + check: params.check.unwrap_or_default(), + }) + } +} + +impl Rules { + fn parse(params: &[u8]) -> Result { + super::parse::(params).and_then(Self::try_from) + } + + fn judge(&self, request: &HookRequest) -> Result { + let Some(allowed) = &self.allowed else { + return Ok(Decision::allow()); + }; + Ok(match self.checked(request)? { + Some(code) if !allowed.contains(&code.to_ascii_lowercase()) => { + Rule::Code.deny(format!("code {code} is not allowed")) + } + _ => Decision::allow(), + }) + } + + /// The code commitment `allowed` must list for this request, if any: under `changed` the + /// code an account registers with or a transaction replaces its code with, under `all` the + /// code the account runs after the request. + fn checked(&self, request: &HookRequest) -> Result, ModuleError> { + let after_code = || super::after(request).map(|after| after.code_commitment.clone()); + match (self.check, &request.subject) { + (CodeCheck::All, _) + | (CodeCheck::Changed, Some(hook_request::Subject::Registration(_))) => { + after_code().map(Some) + } + (CodeCheck::Changed, _) => Ok(super::transaction(request)?.new_code_commitment.clone()), + } + } +} + +#[derive(Debug, Default, Clone, Copy)] +pub struct CodePolicy; + +#[async_trait] +impl Module for CodePolicy { + async fn describe(&self, _guardian: &DescribeRequest) -> Result { + Ok(super::info(KIND, &HOOKS)) + } + + async fn validate_params(&self, params: &[u8]) -> Result { + Ok(super::verdict(Rules::parse(params))) + } + + async fn evaluate(&self, request: &HookRequest) -> Result { + Rules::parse(&request.params) + .map_err(ModuleError::InvalidRequest)? + .judge(request) + } +} + +#[cfg(test)] +mod tests { + use serde_json::json; + + use super::super::testing::*; + use super::*; + use crate::MidenTransaction; + + const REVIEWED: &str = "0x000000000000000000000000000000000000000000000000000000000000c0de"; + const UNREVIEWED: &str = "0x0000000000000000000000000000000000000000000000000000000000000bad"; + + async fn decide(request: &HookRequest) -> Decision { + CodePolicy.evaluate(request).await.unwrap() + } + + fn rule(check: &str) -> serde_json::Value { + json!({ "allowed": [REVIEWED], "check": check }) + } + + fn running(mut request: HookRequest, code: &str) -> HookRequest { + if let Some(after) = request.after.as_mut() { + after.code_commitment = code.into(); + } + request + } + + fn registration(params: serde_json::Value, code: &str) -> HookRequest { + running(registration_request(params, None, &[SIGNER]), code) + } + + fn replacing_code_with(code: Option<&str>) -> MidenTransaction { + MidenTransaction { + new_code_commitment: code.map(str::to_string), + ..Default::default() + } + } + + #[tokio::test] + async fn changed_check_judges_registration_and_code_replacement_only() { + let changed = rule("changed"); + assert!( + decide(®istration(changed.clone(), REVIEWED)) + .await + .allows() + ); + let refused = decide(®istration(changed.clone(), UNREVIEWED)).await; + assert_eq!(refused.reason_code, "code_not_allowed"); + assert!(!refused.client_message.contains(UNREVIEWED)); + + let unchanged = running( + tx_request(changed.clone(), replacing_code_with(None)), + UNREVIEWED, + ); + assert!( + decide(&unchanged).await.allows(), + "code an account already runs is kept until it changes" + ); + let upgrade = tx_request(changed.clone(), replacing_code_with(Some(UNREVIEWED))); + assert_eq!(decide(&upgrade).await.reason_code, "code_not_allowed"); + let reviewed = tx_request(changed, replacing_code_with(Some(REVIEWED))); + assert!(decide(&reviewed).await.allows()); + } + + #[tokio::test] + async fn all_check_judges_the_code_an_account_runs_at_every_hook() { + let all = rule("all"); + let unchanged = running( + tx_request(all.clone(), replacing_code_with(None)), + UNREVIEWED, + ); + assert_eq!(decide(&unchanged).await.reason_code, "code_not_allowed"); + let upgraded = running( + tx_request(all, replacing_code_with(Some(REVIEWED))), + REVIEWED, + ); + assert!( + decide(&upgraded).await.allows(), + "an account on unlisted code can still upgrade to listed code" + ); + } + + #[tokio::test] + async fn a_transaction_without_a_projection_is_not_judged_under_changed() { + let unprojected = without_projection(tx_request( + rule("changed"), + replacing_code_with(Some(UNREVIEWED)), + )); + assert!(matches!( + CodePolicy.evaluate(&unprojected).await, + Err(ModuleError::InvalidRequest(_)) + )); + } + + #[tokio::test] + async fn params_are_validated() { + for params in [ + json!({ "allowed": [REVIEWED], "check": "sometimes" }), + json!({ "allowed": [format!("0x{}", "c".repeat(63))] }), + json!({ "check": "all" }), + json!({ "allowed_code_commitments": [REVIEWED] }), + ] { + let verdict = CodePolicy + .validate_params(&serde_json::to_vec(¶ms).unwrap()) + .await + .unwrap(); + assert!(!verdict.ok, "{params}"); + } + } +} diff --git a/crates/guardian-module-sdk/src/policies/mod.rs b/crates/guardian-module-sdk/src/policies/mod.rs new file mode 100644 index 00000000..db59ae3d --- /dev/null +++ b/crates/guardian-module-sdk/src/policies/mod.rs @@ -0,0 +1,281 @@ +//! First-party policies, one concern each, so an instance is configured with only the params of +//! the rule it enforces: +//! +//! | Kind | Judges | Hooks | +//! |---|---|---| +//! | [`spending-limit`](spending_limit) | Which assets a transaction moves and how much of each it sends | proposal creation, transaction approval | +//! | [`recipient-policy`](recipient_policy) | Who a transaction pays | proposal creation, transaction approval | +//! | [`signer-policy`](signer_policy) | Who may sign for the account | registration, proposal creation, transaction approval | +//! | [`code-policy`](code_policy) | Which account code the account may run | registration, proposal creation, transaction approval | +//! +//! Each kind refuses params that belong to another, and supports only the hooks where its rule +//! can refuse something, so a catalog that subscribes it to another hook does not start. An +//! instance with no rule configured allows without reading the request; one with a rule that +//! cannot read what it needs returns an error, so the instance's `on_error` applies. Every +//! denial carries a fixed reason code and a fixed client message that names the rule, never a +//! list entry or a limit; the details go only to the logged message. + +use std::collections::BTreeSet; + +use serde::de::DeserializeOwned; + +use crate::proto::hook_request; +use crate::{ + AccountView, Decision, Hook, HookRequest, MidenTransaction, ModuleError, ModuleInfo, + PROTOCOL_VERSION, ParamsVerdict, +}; + +pub mod code_policy; +pub mod recipient_policy; +pub mod signer_policy; +pub mod spending_limit; + +pub use code_policy::CodePolicy; +pub use recipient_policy::RecipientPolicy; +pub use signer_policy::SignerPolicy; +pub use spending_limit::SpendingLimit; + +/// Every first-party policy kind, as a catalog names it. +pub const KINDS: [&str; 4] = [ + spending_limit::KIND, + recipient_policy::KIND, + signer_policy::KIND, + code_policy::KIND, +]; + +/// What an id names, which fixes its length in the hex form the Guardian reports it in. +#[derive(Clone, Copy)] +pub(crate) enum IdKind { + /// A faucet or a recipient: an account id. + Account, + /// A signer commitment or a code commitment: a word. + Commitment, +} + +impl IdKind { + fn hex_digits(self) -> usize { + match self { + IdKind::Account => 30, + IdKind::Commitment => 64, + } + } + + fn noun(self) -> &'static str { + match self { + IdKind::Account => "an account id", + IdKind::Commitment => "a commitment", + } + } +} + +/// Ids in the hex form the Guardian reports them in (`0x` and the hex digits of an account id or +/// a commitment), lowercased. Any other spelling would never match a request, so a list or a +/// cap would silently not apply; it is refused instead: a bech32 address, a placeholder left in +/// an example catalog, an id cut short when it was pasted, or an account id where a commitment +/// belongs. +pub(crate) fn ids( + field: &str, + kind: IdKind, + values: &[String], +) -> Result, String> { + values.iter().map(|value| id(field, kind, value)).collect() +} + +pub(crate) fn id(field: &str, kind: IdKind, value: &str) -> Result { + let digits = value + .strip_prefix("0x") + .or_else(|| value.strip_prefix("0X")) + .filter(|rest| rest.bytes().all(|b| b.is_ascii_hexdigit())); + match digits { + Some(rest) if rest.len() == kind.hex_digits() => Ok(value.to_ascii_lowercase()), + Some(rest) if !rest.is_empty() => Err(format!( + "{field}: {value:?} has {} hex digits, but {} has {}", + rest.len(), + kind.noun(), + kind.hex_digits() + )), + _ => Err(format!( + "{field}: {value:?} is not an id in 0x hex form (a bech32 address is not accepted)" + )), + } +} + +pub(crate) fn normalized(values: &[String]) -> BTreeSet { + values.iter().map(|v| v.to_ascii_lowercase()).collect() +} + +/// A rule's denial. Each denies with a fixed reason code and a fixed client message that names +/// the rule, never a list entry or a limit, so a denial discloses no params. +#[derive(Debug, Clone, Copy)] +pub(crate) enum Rule { + RecipientAllowlist, + RecipientDenylist, + AssetAllowlist, + AmountCap, + Signers, + Code, +} + +impl Rule { + pub(crate) fn deny(self, logged: String) -> Decision { + let (reason_code, client_message) = match self { + Rule::RecipientAllowlist => ( + "recipient_not_allowed", + "A payment goes to a recipient this Guardian does not accept.", + ), + Rule::RecipientDenylist => ( + "recipient_blocked", + "A payment goes to a recipient this Guardian blocks.", + ), + Rule::AssetAllowlist => ( + "asset_not_allowed", + "The transaction moves an asset this Guardian does not accept.", + ), + Rule::AmountCap => ( + "amount_cap_exceeded", + "The transaction sends more than this Guardian allows per transaction.", + ), + Rule::Signers => ( + "signer_not_allowed", + "The account would have a signer this Guardian does not accept.", + ), + Rule::Code => ( + "code_not_allowed", + "The account would run code this Guardian does not accept.", + ), + }; + Decision::deny(reason_code, logged).with_client_message(client_message) + } +} + +/// The params as a kind reads them: absent bytes are no params, anything else must be a JSON +/// object of that kind's fields only. +pub(crate) fn parse(params: &[u8]) -> Result { + if params.is_empty() { + Ok(P::default()) + } else { + serde_json::from_slice(params).map_err(|e| e.to_string()) + } +} + +pub(crate) fn verdict(parsed: Result) -> ParamsVerdict { + match parsed { + Ok(_) => ParamsVerdict::ok(), + Err(message) => ParamsVerdict::invalid(message), + } +} + +pub(crate) fn info(kind: &str, hooks: &[Hook]) -> ModuleInfo { + ModuleInfo { + name: kind.into(), + version: env!("CARGO_PKG_VERSION").into(), + protocol_version: PROTOCOL_VERSION, + hooks: hooks.iter().map(|hook| *hook as i32).collect(), + ..Default::default() + } +} + +/// The transaction a request asks about, in its Miden projection. A request that carries no +/// transaction, or no projection this module can read, is not judged: it is an error, so the +/// instance's `on_error` applies, never an allow. +pub(crate) fn transaction(request: &HookRequest) -> Result<&MidenTransaction, ModuleError> { + match &request.subject { + Some(hook_request::Subject::Transaction(tx)) => tx.miden().ok_or_else(|| { + ModuleError::InvalidRequest("transaction has no Miden projection to judge".into()) + }), + Some(hook_request::Subject::Registration(_)) => Err(ModuleError::InvalidRequest( + "this policy judges transactions, not registrations".into(), + )), + None => Err(ModuleError::InvalidRequest("request has no subject".into())), + } +} + +/// The account as it will be if every module allows; a request without it is not judged. +pub(crate) fn after(request: &HookRequest) -> Result<&AccountView, ModuleError> { + request + .after + .as_ref() + .ok_or_else(|| ModuleError::InvalidRequest("request has no account view".into())) +} + +#[cfg(test)] +pub(crate) mod testing { + use crate::proto::{asset, hook_request}; + use crate::{ + AccountView, Asset, HookRequest, MidenTransaction, OutputNote, RegistrationSubject, + TransactionProjection, TransactionSubject, + }; + + pub const USDC: &str = "0x00000000000000000000000000aa00"; + pub const ETH: &str = "0x00000000000000000000000000bb00"; + pub const RECIPIENT: &str = "0x0000000000000000000000000000a1"; + pub const SIGNER: &str = "0x0000000000000000000000000000000000000000000000000000000000000051"; + + pub fn fungible(faucet: &str, amount: u64) -> Asset { + Asset { + faucet_id: faucet.into(), + value: Some(asset::Value::FungibleAmount(amount.to_string())), + } + } + + pub fn p2id(target: &str, assets: Vec) -> OutputNote { + OutputNote { + note_id: format!("0xnote{target}"), + assets, + p2id_target: Some(target.into()), + ..Default::default() + } + } + + pub fn fee_note(amount: u64) -> OutputNote { + OutputNote { + note_id: "0xfee".into(), + assets: vec![fungible(USDC, amount)], + tx_fee: true, + ..Default::default() + } + } + + pub fn view(signers: &[&str]) -> AccountView { + AccountView { + signer_commitments: signers.iter().map(|s| s.to_string()).collect(), + ..Default::default() + } + } + + pub fn tx_request(params: serde_json::Value, projection: MidenTransaction) -> HookRequest { + HookRequest { + params: serde_json::to_vec(¶ms).unwrap(), + before: Some(view(&[SIGNER])), + after: Some(view(&[SIGNER])), + subject: Some(hook_request::Subject::Transaction(TransactionSubject { + projection: Some(TransactionProjection::miden(projection)), + ..Default::default() + })), + ..Default::default() + } + } + + pub fn registration_request( + params: serde_json::Value, + before: Option<&[&str]>, + after: &[&str], + ) -> HookRequest { + HookRequest { + params: serde_json::to_vec(¶ms).unwrap(), + before: before.map(view), + after: Some(view(after)), + subject: Some(hook_request::Subject::Registration( + RegistrationSubject::default(), + )), + ..Default::default() + } + } + + pub fn without_projection(mut request: HookRequest) -> HookRequest { + if let Some(hook_request::Subject::Transaction(subject)) = &mut request.subject { + subject.projection = None; + } + request + } +} diff --git a/crates/guardian-module-sdk/src/policies/recipient_policy.rs b/crates/guardian-module-sdk/src/policies/recipient_policy.rs new file mode 100644 index 00000000..4b2ef8d1 --- /dev/null +++ b/crates/guardian-module-sdk/src/policies/recipient_policy.rs @@ -0,0 +1,279 @@ +//! `recipient-policy`: who a transaction may pay. + +use std::collections::BTreeSet; + +use async_trait::async_trait; +use serde::Deserialize; + +use super::{IdKind, Rule}; +use crate::{ + Decision, DescribeRequest, Hook, HookRequest, Module, ModuleError, ModuleInfo, ParamsVerdict, +}; + +pub const KIND: &str = "recipient-policy"; + +const HOOKS: [Hook; 2] = [Hook::BeforeProposalCreated, Hook::BeforeTransactionApproved]; + +#[derive(Debug, Clone, Default, Deserialize)] +#[serde(deny_unknown_fields)] +pub struct Params { + /// The only accounts a payment note may go to. A note whose recipient cannot be identified + /// (a partial note, or one that is neither P2ID nor P2IDE) is refused, since it cannot be + /// shown to go to a listed account. Excludes `denylist`. + #[serde(default)] + pub allowlist: Option>, + /// Accounts no payment note may go to. Excludes `allowlist`. + #[serde(default)] + pub denylist: Option>, + /// With `denylist`: whether a payment note whose recipient cannot be identified is refused. + /// Unset, it is refused whenever the denylist names anyone, since a blocked recipient could + /// otherwise be paid through a note the Guardian cannot read. + #[serde(default)] + pub deny_unknown: Option, +} + +enum Rules { + Any, + Allow(BTreeSet), + Deny { + blocked: BTreeSet, + deny_unknown: bool, + }, +} + +impl TryFrom for Rules { + type Error = String; + + fn try_from(params: Params) -> Result { + if params.deny_unknown.is_some() && params.denylist.is_none() { + return Err("deny_unknown applies to denylist, which is not set (an allowlist refuses unknown recipients already)".into()); + } + match (params.allowlist, params.denylist) { + (Some(_), Some(_)) => Err("allowlist and denylist are mutually exclusive".into()), + (Some(list), None) => Ok(Rules::Allow(super::ids( + "allowlist", + IdKind::Account, + &list, + )?)), + (None, Some(list)) => Ok(Rules::Deny { + deny_unknown: params.deny_unknown.unwrap_or(!list.is_empty()), + blocked: super::ids("denylist", IdKind::Account, &list)?, + }), + (None, None) => Ok(Rules::Any), + } + } +} + +impl Rules { + fn parse(params: &[u8]) -> Result { + super::parse::(params).and_then(Self::try_from) + } + + fn judge(&self, request: &HookRequest) -> Result { + if matches!(self, Rules::Any) { + return Ok(Decision::allow()); + } + let projection = super::transaction(request)?; + let payments = projection.output_notes.iter().filter(|note| !note.tx_fee); + for note in payments { + let recipient = match (¬e.p2id_target, note.partial) { + (Some(target), false) => Some(target.to_ascii_lowercase()), + _ => None, + }; + let refused = match (self, recipient) { + (Rules::Any, _) => None, + (Rules::Allow(_), None) => Some( + Rule::RecipientAllowlist + .deny(format!("note {} has no checkable recipient", note.note_id)), + ), + (Rules::Allow(allowed), Some(recipient)) => { + (!allowed.contains(&recipient)).then(|| { + Rule::RecipientAllowlist + .deny(format!("recipient {recipient} is not allowed")) + }) + } + (Rules::Deny { deny_unknown, .. }, None) => deny_unknown.then(|| { + Rule::RecipientDenylist + .deny(format!("note {} has no checkable recipient", note.note_id)) + }), + (Rules::Deny { blocked, .. }, Some(recipient)) => { + blocked.contains(&recipient).then(|| { + Rule::RecipientDenylist.deny(format!("recipient {recipient} is blocked")) + }) + } + }; + if let Some(denial) = refused { + return Ok(denial); + } + } + Ok(Decision::allow()) + } +} + +#[derive(Debug, Default, Clone, Copy)] +pub struct RecipientPolicy; + +#[async_trait] +impl Module for RecipientPolicy { + async fn describe(&self, _guardian: &DescribeRequest) -> Result { + Ok(super::info(KIND, &HOOKS)) + } + + async fn validate_params(&self, params: &[u8]) -> Result { + Ok(super::verdict(Rules::parse(params))) + } + + async fn evaluate(&self, request: &HookRequest) -> Result { + Rules::parse(&request.params) + .map_err(ModuleError::InvalidRequest)? + .judge(request) + } +} + +#[cfg(test)] +mod tests { + use serde_json::json; + + use super::super::testing::*; + use super::*; + use crate::MidenTransaction; + + const BLOCKED: &str = "0x000000000000000000000000000bad"; + + async fn decide(request: &HookRequest) -> Decision { + RecipientPolicy.evaluate(request).await.unwrap() + } + + fn paying(notes: Vec) -> MidenTransaction { + MidenTransaction { + output_notes: notes, + ..Default::default() + } + } + + fn with_an_unreadable_note() -> MidenTransaction { + let mut partial = p2id(RECIPIENT, vec![fungible(USDC, 1)]); + partial.partial = true; + paying(vec![p2id(RECIPIENT, vec![fungible(USDC, 1)]), partial]) + } + + #[tokio::test] + async fn an_allowlist_refuses_unlisted_and_unreadable_recipients() { + let params = json!({ "allowlist": [RECIPIENT] }); + let listed = paying(vec![p2id( + "0x0000000000000000000000000000A1", + vec![fungible(USDC, 1)], + )]); + assert!(decide(&tx_request(params.clone(), listed)).await.allows()); + + assert_eq!( + decide(&tx_request(params.clone(), with_an_unreadable_note())) + .await + .reason_code, + "recipient_not_allowed" + ); + + let unlisted = paying(vec![p2id( + "0x0000000000000000000000000000a9", + vec![fungible(USDC, 1)], + )]); + assert_eq!( + decide(&tx_request(params, unlisted)).await.reason_code, + "recipient_not_allowed" + ); + } + + #[tokio::test] + async fn a_denylist_refuses_listed_recipients_and_by_default_unreadable_ones() { + let params = json!({ "denylist": ["0x000000000000000000000000000BAD"] }); + let blocked = paying(vec![fee_note(1), p2id(BLOCKED, vec![fungible(USDC, 1)])]); + assert_eq!( + decide(&tx_request(params.clone(), blocked)) + .await + .reason_code, + "recipient_blocked" + ); + assert_eq!( + decide(&tx_request(params, with_an_unreadable_note())) + .await + .reason_code, + "recipient_blocked", + "a recipient the denylist cannot check is refused: a blocked one could hide there" + ); + + let lenient = json!({ "denylist": [BLOCKED], "deny_unknown": false }); + assert!( + decide(&tx_request(lenient, with_an_unreadable_note())) + .await + .allows(), + "the operator opted out" + ); + + let nobody_listed = json!({ "denylist": [] }); + assert!( + decide(&tx_request(nobody_listed, with_an_unreadable_note())) + .await + .allows(), + "an empty denylist has nobody to hide" + ); + + let strict_anyway = json!({ "denylist": [], "deny_unknown": true }); + assert_eq!( + decide(&tx_request(strict_anyway, with_an_unreadable_note())) + .await + .reason_code, + "recipient_blocked" + ); + } + + #[tokio::test] + async fn the_fee_note_is_not_a_payment() { + let params = json!({ "allowlist": [RECIPIENT] }); + let projection = paying(vec![fee_note(5), p2id(RECIPIENT, vec![fungible(USDC, 5)])]); + assert!(decide(&tx_request(params, projection)).await.allows()); + } + + #[tokio::test] + async fn no_list_allows_and_a_request_it_cannot_judge_is_an_error() { + let projection = paying(vec![p2id(BLOCKED, vec![fungible(USDC, 1)])]); + assert!( + decide(&tx_request(json!({}), projection.clone())) + .await + .allows() + ); + assert!( + decide(&without_projection(tx_request( + json!({}), + projection.clone() + ))) + .await + .allows(), + "an instance with no rule allows without reading the transaction, like every kind" + ); + let unprojected = + without_projection(tx_request(json!({ "denylist": [BLOCKED] }), projection)); + assert!(matches!( + RecipientPolicy.evaluate(&unprojected).await, + Err(ModuleError::InvalidRequest(_)) + )); + } + + #[tokio::test] + async fn params_are_validated() { + for params in [ + json!({ "denylist": ["mtst1qrkd5x7qy0mw0yqzlvqlqd3w9cafjkw"] }), + json!({ "denylist": ["0xa1b2c3"] }), + json!({ "allowlist": [RECIPIENT], "denylist": [BLOCKED] }), + json!({ "deny_unknown": true }), + json!({ "allowlist": [RECIPIENT], "deny_unknown": false }), + json!({ "recipient_denylist": [BLOCKED] }), + json!({ "max_per_transaction": {} }), + ] { + let verdict = RecipientPolicy + .validate_params(&serde_json::to_vec(¶ms).unwrap()) + .await + .unwrap(); + assert!(!verdict.ok, "{params}"); + } + } +} diff --git a/crates/guardian-module-sdk/src/policies/signer_policy.rs b/crates/guardian-module-sdk/src/policies/signer_policy.rs new file mode 100644 index 00000000..762eb12f --- /dev/null +++ b/crates/guardian-module-sdk/src/policies/signer_policy.rs @@ -0,0 +1,232 @@ +//! `signer-policy`: who may sign for the account. + +use std::collections::BTreeSet; + +use async_trait::async_trait; +use serde::Deserialize; + +use super::{IdKind, Rule}; +use crate::{ + AccountView, Decision, DescribeRequest, Hook, HookRequest, Module, ModuleError, ModuleInfo, + ParamsVerdict, +}; + +pub const KIND: &str = "signer-policy"; + +const HOOKS: [Hook; 3] = [ + Hook::BeforeAccountRegistered, + Hook::BeforeProposalCreated, + Hook::BeforeTransactionApproved, +]; + +/// Which signers a list is checked against. +#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum SignerCheck { + /// The signers a registration or a transaction adds; signers the account already has are + /// kept until they change. + #[default] + Added, + /// Every signer the account has after the registration or transaction. + All, +} + +#[derive(Debug, Clone, Default, Deserialize)] +#[serde(deny_unknown_fields)] +pub struct Params { + /// The only signer commitments the account may have. Excludes `denylist`. + #[serde(default)] + pub allowlist: Option>, + /// Signer commitments the account may not have. Excludes `allowlist`. + #[serde(default)] + pub denylist: Option>, + /// Which signers the list is checked against; `added` unless set. Needs a list. + #[serde(default)] + pub check: Option, +} + +enum List { + Allow(BTreeSet), + Deny(BTreeSet), +} + +impl List { + fn permits(&self, signer: &str) -> bool { + match self { + List::Allow(list) => list.contains(signer), + List::Deny(list) => !list.contains(signer), + } + } +} + +struct Rules { + list: Option, + check: SignerCheck, +} + +impl TryFrom for Rules { + type Error = String; + + fn try_from(params: Params) -> Result { + if params.check.is_some() && params.allowlist.is_none() && params.denylist.is_none() { + return Err("check applies to allowlist or denylist, neither of which is set".into()); + } + let list = match (params.allowlist, params.denylist) { + (Some(_), Some(_)) => { + return Err("allowlist and denylist are mutually exclusive".into()); + } + (Some(list), None) => Some(List::Allow(super::ids( + "allowlist", + IdKind::Commitment, + &list, + )?)), + (None, Some(list)) => Some(List::Deny(super::ids( + "denylist", + IdKind::Commitment, + &list, + )?)), + (None, None) => None, + }; + Ok(Self { + list, + check: params.check.unwrap_or_default(), + }) + } +} + +impl Rules { + fn parse(params: &[u8]) -> Result { + super::parse::(params).and_then(Self::try_from) + } + + fn judge(&self, request: &HookRequest) -> Result { + let Some(list) = &self.list else { + return Ok(Decision::allow()); + }; + let after = super::after(request)?; + Ok( + match self + .checked(request.before.as_ref(), after) + .into_iter() + .find(|signer| !list.permits(signer)) + { + Some(signer) => Rule::Signers.deny(format!("signer {signer} is not permitted")), + None => Decision::allow(), + }, + ) + } + + fn checked(&self, before: Option<&AccountView>, after: &AccountView) -> Vec { + let existing: BTreeSet = match (self.check, before) { + (SignerCheck::Added, Some(before)) => super::normalized(&before.signer_commitments), + _ => BTreeSet::new(), + }; + super::normalized(&after.signer_commitments) + .into_iter() + .filter(|signer| !existing.contains(signer)) + .collect() + } +} + +#[derive(Debug, Default, Clone, Copy)] +pub struct SignerPolicy; + +#[async_trait] +impl Module for SignerPolicy { + async fn describe(&self, _guardian: &DescribeRequest) -> Result { + Ok(super::info(KIND, &HOOKS)) + } + + async fn validate_params(&self, params: &[u8]) -> Result { + Ok(super::verdict(Rules::parse(params))) + } + + async fn evaluate(&self, request: &HookRequest) -> Result { + Rules::parse(&request.params) + .map_err(ModuleError::InvalidRequest)? + .judge(request) + } +} + +#[cfg(test)] +mod tests { + use serde_json::json; + + use super::super::testing::*; + use super::*; + + const LISTED: &str = "0x0000000000000000000000000000000000000000000000000000000000000052"; + const OTHER: &str = "0x0000000000000000000000000000000000000000000000000000000000000053"; + const BAD: &str = "0x0000000000000000000000000000000000000000000000000000000000000bad"; + + async fn decide(request: &HookRequest) -> Decision { + SignerPolicy.evaluate(request).await.unwrap() + } + + #[tokio::test] + async fn added_mode_checks_only_new_signers() { + let params = json!({ "allowlist": [LISTED] }); + let adding_listed = + registration_request(params.clone(), Some(&[SIGNER]), &[SIGNER, LISTED]); + assert!(decide(&adding_listed).await.allows()); + let adding_other = registration_request(params, Some(&[SIGNER]), &[SIGNER, OTHER]); + assert_eq!( + decide(&adding_other).await.reason_code, + "signer_not_allowed" + ); + } + + #[tokio::test] + async fn all_mode_checks_every_signer() { + let params = json!({ "check": "all", "allowlist": [LISTED] }); + let request = registration_request(params, Some(&[SIGNER]), &[SIGNER, LISTED]); + assert!(!decide(&request).await.allows()); + } + + #[tokio::test] + async fn registration_checks_every_initial_signer() { + let params = json!({ "denylist": [BAD] }); + let request = registration_request( + params, + None, + &[ + SIGNER, + "0x0000000000000000000000000000000000000000000000000000000000000BAD", + ], + ); + assert!(!decide(&request).await.allows()); + } + + #[tokio::test] + async fn a_transaction_is_judged_on_its_account_views() { + let params = json!({ "denylist": [BAD] }); + let mut request = tx_request(params, crate::MidenTransaction::default()); + request.after = Some(view(&[SIGNER, BAD])); + assert_eq!(decide(&request).await.reason_code, "signer_not_allowed"); + } + + #[tokio::test] + async fn missing_account_view_is_an_error_not_an_allow() { + let mut request = registration_request(json!({ "allowlist": [SIGNER] }), None, &[]); + request.after = None; + assert!(SignerPolicy.evaluate(&request).await.is_err()); + } + + #[tokio::test] + async fn params_are_validated() { + for params in [ + json!({ "denylist": ["0x"] }), + json!({ "allowlist": [], "denylist": [] }), + json!({ "allowlist": ["0x000000000000000000000000000051"] }), + json!({ "check": "all" }), + json!({ "check": "sometimes", "allowlist": [SIGNER] }), + json!({ "signer_allowlist": [SIGNER] }), + ] { + let verdict = SignerPolicy + .validate_params(&serde_json::to_vec(¶ms).unwrap()) + .await + .unwrap(); + assert!(!verdict.ok, "{params}"); + } + } +} diff --git a/crates/guardian-module-sdk/src/policies/spending_limit.rs b/crates/guardian-module-sdk/src/policies/spending_limit.rs new file mode 100644 index 00000000..063a975a --- /dev/null +++ b/crates/guardian-module-sdk/src/policies/spending_limit.rs @@ -0,0 +1,324 @@ +//! `spending-limit`: which assets a transaction may move, and how much of each it may send. + +use std::collections::{BTreeMap, BTreeSet}; + +use async_trait::async_trait; +use serde::Deserialize; + +use super::{IdKind, Rule}; +use crate::proto::asset; +use crate::{ + Decision, DescribeRequest, Hook, HookRequest, Module, ModuleError, ModuleInfo, ParamsVerdict, +}; + +pub const KIND: &str = "spending-limit"; + +const HOOKS: [Hook; 2] = [Hook::BeforeProposalCreated, Hook::BeforeTransactionApproved]; + +#[derive(Debug, Clone, Default, Deserialize)] +#[serde(deny_unknown_fields)] +pub struct Params { + /// The most a transaction may send of each listed asset, faucet id to a decimal amount. The + /// payment notes of one transaction are summed per asset; the fee note does not count, and + /// an asset that is not listed is not capped. + #[serde(default)] + pub max_per_transaction: BTreeMap, + /// The assets a transaction may send in payment notes or receive from the notes it + /// consumes. Unset, any asset; empty, none. + #[serde(default)] + pub allowed_assets: Option>, +} + +struct Rules { + caps: BTreeMap, + assets: Option>, +} + +impl TryFrom for Rules { + type Error = String; + + fn try_from(params: Params) -> Result { + let mut caps = BTreeMap::new(); + for (faucet, amount) in params.max_per_transaction { + let faucet = super::id("max_per_transaction", IdKind::Account, &faucet)?; + let amount = amount + .parse::() + .map_err(|_| format!("max_per_transaction for {faucet} is not a decimal amount"))?; + if caps.insert(faucet.clone(), amount).is_some() { + return Err(format!( + "max_per_transaction names {faucet} more than once (ids are compared in lowercase)" + )); + } + } + Ok(Self { + caps, + assets: params + .allowed_assets + .as_deref() + .map(|list| super::ids("allowed_assets", IdKind::Account, list)) + .transpose()?, + }) + } +} + +impl Rules { + fn parse(params: &[u8]) -> Result { + super::parse::(params).and_then(Self::try_from) + } + + fn judge(&self, request: &HookRequest) -> Result { + if self.caps.is_empty() && self.assets.is_none() { + return Ok(Decision::allow()); + } + let projection = super::transaction(request)?; + let payments = || projection.output_notes.iter().filter(|note| !note.tx_fee); + + if let Some(allowed) = &self.assets { + let sent = payments().flat_map(|n| n.assets.iter()); + let received = projection.input_notes.iter().flat_map(|n| n.assets.iter()); + if let Some(faucet) = sent + .chain(received) + .map(|a| a.faucet_id.to_ascii_lowercase()) + .find(|faucet| !allowed.contains(faucet)) + { + return Ok(Rule::AssetAllowlist.deny(format!("asset {faucet} is not allowed"))); + } + } + + if !self.caps.is_empty() { + let mut sent: BTreeMap = BTreeMap::new(); + for asset in payments().flat_map(|n| n.assets.iter()) { + if let Some(asset::Value::FungibleAmount(amount)) = &asset.value { + let amount = amount.parse::().unwrap_or(u128::MAX); + let total = sent + .entry(asset.faucet_id.to_ascii_lowercase()) + .or_default(); + *total = total.saturating_add(amount); + } + } + for (faucet, cap) in &self.caps { + if sent.get(faucet).is_some_and(|total| total > cap) { + return Ok(Rule::AmountCap + .deny(format!("sent {} of {faucet}, cap {cap}", sent[faucet]))); + } + } + } + + Ok(Decision::allow()) + } +} + +#[derive(Debug, Default, Clone, Copy)] +pub struct SpendingLimit; + +#[async_trait] +impl Module for SpendingLimit { + async fn describe(&self, _guardian: &DescribeRequest) -> Result { + Ok(super::info(KIND, &HOOKS)) + } + + async fn validate_params(&self, params: &[u8]) -> Result { + Ok(super::verdict(Rules::parse(params))) + } + + async fn evaluate(&self, request: &HookRequest) -> Result { + Rules::parse(&request.params) + .map_err(ModuleError::InvalidRequest)? + .judge(request) + } +} + +#[cfg(test)] +mod tests { + use serde_json::json; + + use super::super::testing::*; + use super::*; + use crate::proto::hook_request; + use crate::{Asset, InputNote, MidenTransaction, VaultChange}; + + async fn decide(request: &HookRequest) -> Decision { + SpendingLimit.evaluate(request).await.unwrap() + } + + fn cap() -> serde_json::Value { + json!({ "max_per_transaction": { USDC: "1000" } }) + } + + fn paying(notes: Vec) -> MidenTransaction { + MidenTransaction { + output_notes: notes, + ..Default::default() + } + } + + #[tokio::test] + async fn allows_a_payment_under_the_cap() { + let projection = paying(vec![p2id(RECIPIENT, vec![fungible(USDC, 500)])]); + assert!(decide(&tx_request(cap(), projection)).await.allows()); + } + + #[tokio::test] + async fn sums_split_payments_against_the_cap() { + let projection = paying(vec![ + p2id(RECIPIENT, vec![fungible(USDC, 600)]), + p2id( + "0x0000000000000000000000000000a2", + vec![fungible(USDC, 600)], + ), + ]); + let decision = decide(&tx_request(cap(), projection)).await; + assert!(!decision.allows()); + assert_eq!(decision.reason_code, "amount_cap_exceeded"); + } + + #[tokio::test] + async fn incoming_amounts_do_not_offset_outgoing() { + let projection = MidenTransaction { + vault_changes: vec![VaultChange { + asset: Some(fungible(USDC, 500)), + direction: crate::Direction::Out as i32, + }], + input_notes: vec![InputNote { + note_id: "0x14".into(), + assets: vec![fungible(USDC, 1000)], + }], + output_notes: vec![p2id(RECIPIENT, vec![fungible(USDC, 1500)])], + ..Default::default() + }; + assert!(!decide(&tx_request(cap(), projection)).await.allows()); + } + + #[tokio::test] + async fn uncapped_assets_and_nfts_are_not_counted() { + let nft = Asset { + faucet_id: USDC.into(), + value: Some(asset::Value::NftId("0x4f7".into())), + }; + let projection = paying(vec![p2id(RECIPIENT, vec![fungible(ETH, 5000), nft])]); + assert!(decide(&tx_request(cap(), projection)).await.allows()); + } + + #[tokio::test] + async fn the_fee_note_is_not_a_payment() { + let projection = paying(vec![ + fee_note(5000), + p2id(RECIPIENT, vec![fungible(USDC, 500)]), + ]); + assert!(decide(&tx_request(cap(), projection)).await.allows()); + let only_fee = paying(vec![fee_note(5000)]); + assert!( + decide(&tx_request(json!({ "allowed_assets": [ETH] }), only_fee)) + .await + .allows() + ); + } + + #[tokio::test] + async fn allowed_assets_cover_sent_and_received_assets() { + let sending = paying(vec![p2id(RECIPIENT, vec![fungible(ETH, 1)])]); + assert_eq!( + decide(&tx_request(json!({ "allowed_assets": [USDC] }), sending)) + .await + .reason_code, + "asset_not_allowed" + ); + let consuming = MidenTransaction { + input_notes: vec![InputNote { + note_id: "0x14".into(), + assets: vec![fungible(ETH, 1)], + }], + ..Default::default() + }; + assert_eq!( + decide(&tx_request(json!({ "allowed_assets": [USDC] }), consuming)) + .await + .reason_code, + "asset_not_allowed" + ); + } + + #[tokio::test] + async fn a_denial_names_its_rule_to_the_client_and_discloses_no_param() { + let projection = paying(vec![p2id(RECIPIENT, vec![fungible(USDC, 5_000)])]); + let decision = decide(&tx_request(cap(), projection)).await; + assert_eq!(decision.reason_code, "amount_cap_exceeded"); + assert!(!decision.client_message.is_empty()); + assert!(decision.client_message.len() <= 256); + for detail in ["1000", "5000", USDC, RECIPIENT] { + assert!( + !decision.client_message.contains(detail), + "{detail} leaked into {:?}", + decision.client_message + ); + } + assert!( + decision.message.contains("1000"), + "details stay in the logged message" + ); + } + + #[tokio::test] + async fn forged_metadata_does_not_change_the_decision() { + let projection = paying(vec![p2id(RECIPIENT, vec![fungible(USDC, 5000)])]); + let mut request = tx_request(cap(), projection); + if let Some(hook_request::Subject::Transaction(tx)) = &mut request.subject { + tx.unverified_metadata = + serde_json::to_vec(&json!({ "proposal_type": "change_threshold", "amount": "1" })) + .unwrap(); + } + assert!(!decide(&request).await.allows()); + } + + #[tokio::test] + async fn an_instance_with_no_rule_allows_without_reading_the_request() { + let unprojected = without_projection(tx_request(json!({}), MidenTransaction::default())); + assert!(decide(&unprojected).await.allows()); + } + + #[tokio::test] + async fn a_request_it_cannot_judge_is_an_error_not_an_allow() { + let unprojected = without_projection(tx_request(cap(), MidenTransaction::default())); + let registration = registration_request(cap(), None, &[SIGNER]); + for request in [unprojected, registration] { + assert!(matches!( + SpendingLimit.evaluate(&request).await, + Err(ModuleError::InvalidRequest(_)) + )); + } + } + + #[tokio::test] + async fn describes_only_the_transaction_hooks() { + let info = SpendingLimit + .describe(&DescribeRequest::default()) + .await + .unwrap(); + assert_eq!(info.name, KIND); + assert!(!info.hooks.contains(&(Hook::BeforeAccountRegistered as i32))); + } + + #[tokio::test] + async fn params_are_validated() { + for params in [ + json!({ "max_per_transaction": { "faucet": "10" } }), + json!({ "max_per_transaction": { USDC: "ten" } }), + json!({ "max_per_transaction": { "0xREPLACE_WITH_FAUCET_ID": "5" } }), + json!({ "max_per_transaction": { "0x0000000000000000000000000000AA": "5", "0x0000000000000000000000000000aa": "9" } }), + json!({ "allowed_assets": ["0xa1b2c3"] }), + json!({ "max_amount_per_tx": { USDC: "5" } }), + json!({ "denylist": [RECIPIENT] }), + ] { + let verdict = SpendingLimit + .validate_params(&serde_json::to_vec(¶ms).unwrap()) + .await + .unwrap(); + assert!(!verdict.ok, "{params}"); + } + let verdict = SpendingLimit + .validate_params(&serde_json::to_vec(&cap()).unwrap()) + .await + .unwrap(); + assert!(verdict.ok); + } +} diff --git a/crates/guardian-module-sdk/tests/conformance.rs b/crates/guardian-module-sdk/tests/conformance.rs index 13338e71..bc86b0b4 100644 --- a/crates/guardian-module-sdk/tests/conformance.rs +++ b/crates/guardian-module-sdk/tests/conformance.rs @@ -1,8 +1,8 @@ #[path = "../examples/note_policy/mod.rs"] mod note_policy; -use guardian_module_sdk::basic_policy::BasicPolicy; use guardian_module_sdk::conformance::Suite; +use guardian_module_sdk::policies::{CodePolicy, RecipientPolicy, SignerPolicy, SpendingLimit}; use guardian_module_sdk::proto::guardian_module_client::GuardianModuleClient; use guardian_module_sdk::proto::{asset, hook_request}; use guardian_module_sdk::serve::serve; @@ -23,7 +23,9 @@ const TOKEN: &str = "secret-token"; async fn start_remote() -> Channel { let listener = TcpListener::bind("127.0.0.1:0").await.unwrap(); let addr = listener.local_addr().unwrap(); - let service = serve(BasicPolicy).instance(INSTANCE, TOKEN).into_service(); + let service = serve(SpendingLimit) + .instance(INSTANCE, TOKEN) + .into_service(); tokio::spawn(async move { Server::builder() .add_service(service) @@ -110,12 +112,15 @@ fn registration(params: serde_json::Value, signers: &[&str]) -> HookRequest { } } +const FAUCET: &str = "0x0000000000000000000000000000aa"; +const SIGNER: &str = "0x0000000000000000000000000000000000000000000000000000000000000051"; +const BAD_SIGNER: &str = "0x0000000000000000000000000000000000000000000000000000000000000bad"; +const CODE: &str = "0x00000000000000000000000000000000000000000000000000000000000000c1"; + #[tokio::test] -async fn basic_policy_conforms() { - let cap = json!({ "max_amount_per_tx": { "0x0000000000000000000000000000aa": "1000" } }); - let signers = json!({ "signer_check": "added", "signer_denylist": ["0x0000000000000000000000000000000000000000000000000000000000000bad"] }); - let code = json!({ "code_check": "all", "allowed_code_commitments": ["0x00000000000000000000000000000000000000000000000000000000000000c1"] }); - Suite::new(BasicPolicy) +async fn spending_limit_conforms() { + let cap = json!({ "max_per_transaction": { FAUCET: "1000" } }); + Suite::new(SpendingLimit) .allows("under the cap", payment(&[500], cap.clone())) .denies_with( "split over the cap", @@ -123,41 +128,116 @@ async fn basic_policy_conforms() { "amount_cap_exceeded", ) .allows("at the cap", payment(&[1000], cap)) - .denies( - "recipient not allowed", - payment(&[1], json!({ "recipient_allowlist": ["0x0000000000000000000000000007e4"] })), + .denies_with( + "an asset that is not allowed", + payment( + &[1], + json!({ "allowed_assets": ["0x0000000000000000000000000000bb"] }), + ), + "asset_not_allowed", ) - .denies( - "recipient denied, generic", - payment(&[1], json!({ "recipient_denylist": ["0x0000000000000000000000000000a1"] })), + .fails( + "params a module cannot read", + payment(&[1], json!({ "max_per_transaction": { FAUCET: "ten" } })), ) - .denies( - "denied signer added", + .valid_params(json!({})) + .valid_params( + json!({ "max_per_transaction": { FAUCET: "1000" }, "allowed_assets": [FAUCET] }), + ) + .invalid_params(json!({ "unknown": 1 })) + .invalid_params(json!({ "max_per_transaction": { FAUCET: "ten" } })) + .invalid_params(json!({ "denylist": [] })) + .run() + .await + .assert_conformant(); +} + +#[tokio::test] +async fn recipient_policy_conforms() { + Suite::new(RecipientPolicy) + .allows( + "a listed recipient", + payment( + &[1], + json!({ "allowlist": ["0x0000000000000000000000000000a1"] }), + ), + ) + .denies_with( + "a recipient not allowed", + payment( + &[1], + json!({ "allowlist": ["0x0000000000000000000000000007e4"] }), + ), + "recipient_not_allowed", + ) + .denies_with( + "a blocked recipient", + payment( + &[1], + json!({ "denylist": ["0x0000000000000000000000000000a1"] }), + ), + "recipient_blocked", + ) + .valid_params(json!({ "denylist": [] })) + .valid_params( + json!({ "denylist": ["0x0000000000000000000000000000a1"], "deny_unknown": false }), + ) + .invalid_params(json!({ "allowlist": [], "denylist": [] })) + .invalid_params(json!({ "deny_unknown": true })) + .run() + .await + .assert_conformant(); +} + +#[tokio::test] +async fn signer_policy_conforms() { + let signers = json!({ "check": "added", "denylist": [BAD_SIGNER] }); + Suite::new(SignerPolicy) + .denies_with( + "a denied signer added", with_views( payment(&[1], signers.clone()), - &["0x0000000000000000000000000000000000000000000000000000000000000051"], - &["0x0000000000000000000000000000000000000000000000000000000000000051", "0x0000000000000000000000000000000000000000000000000000000000000bad"], + &[SIGNER], + &[SIGNER, BAD_SIGNER], ), + "signer_not_allowed", ) .allows( - "listed code", - with_views(payment(&[1], code.clone()), &["0x0000000000000000000000000000000000000000000000000000000000000051"], &["0x0000000000000000000000000000000000000000000000000000000000000051"]), + "no signer added", + with_views(payment(&[1], signers.clone()), &[SIGNER], &[SIGNER]), ) .denies( "registration with a denied signer", - registration(signers, &["0x0000000000000000000000000000000000000000000000000000000000000bad"]), + registration(signers, &[BAD_SIGNER]), ) - .request("registration on listed code", registration(code, &["0x0000000000000000000000000000000000000000000000000000000000000051"])) - .fails( - "params a module cannot read", - payment(&[1], json!({ "max_amount_per_tx": { "0x0000000000000000000000000000aa": "ten" } })), + .valid_params(json!({ "allowlist": [SIGNER] })) + .invalid_params(json!({ "allowlist": [], "denylist": [] })) + .invalid_params(json!({ "check": "all" })) + .run() + .await + .assert_conformant(); +} + +#[tokio::test] +async fn code_policy_conforms() { + let code = json!({ "check": "all", "allowed": [CODE] }); + Suite::new(CodePolicy) + .allows( + "listed code", + with_views(payment(&[1], code.clone()), &[SIGNER], &[SIGNER]), ) - .valid_params(json!({})) - .valid_params(json!({ "max_amount_per_tx": { "0x0000000000000000000000000000aa": "1000" }, "recipient_denylist": [] })) - .valid_params(json!({ "code_check": "changed", "allowed_code_commitments": ["0x00000000000000000000000000000000000000000000000000000000000000c1"] })) - .invalid_params(json!({ "unknown": 1 })) - .invalid_params(json!({ "max_amount_per_tx": { "0x0000000000000000000000000000aa": "ten" } })) - .invalid_params(json!({ "signer_allowlist": [], "signer_denylist": [] })) + .allows("registration on listed code", registration(code, &[SIGNER])) + .denies_with( + "registration on code that is not listed", + registration( + json!({ "allowed": ["0x00000000000000000000000000000000000000000000000000000000000000c2"] }), + &[SIGNER], + ), + "code_not_allowed", + ) + .valid_params(json!({ "check": "changed", "allowed": [CODE] })) + .invalid_params(json!({ "check": "all" })) + .invalid_params(json!({ "allowed": ["0xc1"] })) .run() .await .assert_conformant(); @@ -230,7 +310,7 @@ async fn loopback_evaluate_round_trip() { let mut client = GuardianModuleClient::new(start_remote().await); let request = payment( &[500], - json!({ "max_amount_per_tx": { "0x0000000000000000000000000000aa": "1000" } }), + json!({ "max_per_transaction": { "0x0000000000000000000000000000aa": "1000" } }), ); for _ in 0..50 { client @@ -250,7 +330,7 @@ async fn loopback_evaluate_round_trip() { samples.sort(); let local_started = std::time::Instant::now(); for _ in 0..1000 { - BasicPolicy.evaluate(&request).await.unwrap(); + SpendingLimit.evaluate(&request).await.unwrap(); } println!( "remote p50 {:?} p99 {:?}; in-process mean {:?}", diff --git a/crates/qualification-driver/src/scenario/modules.rs b/crates/qualification-driver/src/scenario/modules.rs index 6bcc6746..f54fde39 100644 --- a/crates/qualification-driver/src/scenario/modules.rs +++ b/crates/qualification-driver/src/scenario/modules.rs @@ -14,7 +14,7 @@ use std::sync::Arc; use guardian_client::{ClientError, GuardianClient, ModuleRefusal}; -use guardian_module_sdk::basic_policy::BasicPolicy; +use guardian_module_sdk::policies::SignerPolicy; use miden_multisig_client::{MultisigError, TransactionType}; use serde_json::{Value, json}; @@ -23,6 +23,7 @@ use crate::fixtures::Fixtures; /// The instances the stack's catalog declares. const GATE: &str = "qual-gate"; +const CAP: &str = "qual-cap"; const SWITCH: &str = "qual-switch"; const REMOTE: &str = "qual-remote"; @@ -53,8 +54,8 @@ macro_rules! settled { }}; } -fn refuse_added_signers() -> Value { - json!({ "signer_check": "all", "signer_allowlist": [UNLISTED_SIGNER] }) +fn refuse_every_signer() -> Value { + json!({ "check": "all", "allowlist": [UNLISTED_SIGNER] }) } /// The operator API, logged in as the operator holding `policies:write`. @@ -278,10 +279,7 @@ pub async fn assert_refusal(runner: &Runner) -> ActionOutcome { }; let account = fixtures.account_id.clone(); - if let Err(outcome) = operator - .assign(&account, GATE, refuse_added_signers()) - .await - { + if let Err(outcome) = operator.assign(&account, GATE, refuse_every_signer()).await { return outcome; } let refused = first_failure([ @@ -310,7 +308,7 @@ pub async fn assert_refusal(runner: &Runner) -> ActionOutcome { } /// The remote policy module the driver serves for the stack's `qual-remote` instance: -/// `basic-policy` over TLS, with the bearer token the Guardian reads from its secrets backend. +/// `signer-policy` over TLS, with the bearer token the Guardian reads from its secrets backend. struct RemoteModule { shutdown: tokio::sync::oneshot::Sender<()>, server: tokio::task::JoinHandle<()>, @@ -338,7 +336,7 @@ impl RemoteModule { let identity = tonic::transport::Identity::from_pem(read("cert.pem")?, read("key.pem")?); let token = String::from_utf8_lossy(&read("token")?).trim().to_string(); - let service = guardian_module_sdk::serve::serve(BasicPolicy) + let service = guardian_module_sdk::serve::serve(SignerPolicy) .instance(REMOTE, token) .into_service(); let listener = tokio::net::TcpListener::bind(("0.0.0.0", port)) @@ -422,7 +420,7 @@ async fn remote_lifecycle( return (outcome, Some(module)); } if let Err(outcome) = operator - .assign(account, REMOTE, refuse_added_signers()) + .assign(account, REMOTE, refuse_every_signer()) .await { return (outcome, Some(module)); @@ -497,7 +495,7 @@ pub async fn assert_break_glass(runner: &Runner) -> ActionOutcome { return outcome; } if let Err(outcome) = operator - .assign(&account, SWITCH, refuse_added_signers()) + .assign(&account, SWITCH, refuse_every_signer()) .await { return outcome; @@ -574,9 +572,9 @@ pub async fn assign_cap(runner: &Runner) -> ActionOutcome { }; let mut limit = serde_json::Map::new(); limit.insert(faucet.to_hex(), json!(super::live::P2ID_AMOUNT.to_string())); - let cap = json!({ "max_amount_per_tx": limit }); + let cap = json!({ "max_per_transaction": limit }); if let Err(outcome) = operator - .assign(&session.account_id.to_string(), GATE, cap.clone()) + .assign(&session.account_id.to_string(), CAP, cap.clone()) .await { return outcome; @@ -590,7 +588,7 @@ pub async fn assign_cap(runner: &Runner) -> ActionOutcome { )); } }; - match policies.iter().find(|policy| policy.module_id == GATE) { + match policies.iter().find(|policy| policy.module_id == CAP) { Some(policy) if [&policy.params, &policy.account_layer] .iter() @@ -599,10 +597,10 @@ pub async fn assign_cap(runner: &Runner) -> ActionOutcome { ActionOutcome::Passed } Some(policy) => ActionOutcome::failed_product(format!( - "the account's policies list {GATE} without the cap it was assigned: {policy:?}" + "the account's policies list {CAP} without the cap it was assigned: {policy:?}" )), None => ActionOutcome::failed_product(format!( - "the account's policies do not list the {GATE} it was assigned: {policies:?}" + "the account's policies do not list the {CAP} it was assigned: {policies:?}" )), } } @@ -651,9 +649,9 @@ fn expect_cap_denied(what: &str, result: Result<(), MultisigError>) -> ActionOut module: Some(module), reason_code, .. - }) if module == GATE && reason_code == "amount_cap_exceeded" => ActionOutcome::Passed, + }) if module == CAP && reason_code == "amount_cap_exceeded" => ActionOutcome::Passed, Err(error) => ActionOutcome::failed_product(format!( - "{what} was refused, but not by {GATE} for amount_cap_exceeded: {error}" + "{what} was refused, but not by {CAP} for amount_cap_exceeded: {error}" )), } } diff --git a/crates/server/src/api/dashboard_modules.rs b/crates/server/src/api/dashboard_modules.rs index 0122bf41..4cc8b7c3 100644 --- a/crates/server/src/api/dashboard_modules.rs +++ b/crates/server/src/api/dashboard_modules.rs @@ -315,7 +315,7 @@ mod tests { use axum::body::{Body, to_bytes}; use axum::http::{Request, StatusCode, header}; - use guardian_module_sdk::basic_policy::BasicPolicy; + use guardian_module_sdk::policies::RecipientPolicy; use guardian_shared::hex::FromHex; use miden_protocol::Word; use serde_json::json; @@ -416,13 +416,13 @@ mod tests { state.modules = Some(pipeline(vec![instance_with_params( "blocklist", &[HookName::BeforeTransactionApproved], - Arc::new(BasicPolicy), - json!({ "recipient_denylist": ["0x000000000000000000000000000aaa"] }), + Arc::new(RecipientPolicy), + json!({ "denylist": ["0x000000000000000000000000000aaa"] }), )])); let app = create_router(state); let support_cookie = login(&app, &support).await; let admin_cookie = login(&app, &admin).await; - let body = json!({ "params": { "recipient_denylist": ["0x000000000000000000000000000aaa", "0x000000000000000000000000000ddd"] }, "reason": "OP-90" }); + let body = json!({ "params": { "denylist": ["0x000000000000000000000000000aaa", "0x000000000000000000000000000ddd"] }, "reason": "OP-90" }); let (status, _) = send( &app, @@ -442,7 +442,7 @@ mod tests { .await; assert_eq!(status, StatusCode::OK, "{view}"); assert_eq!( - view["params"]["recipient_denylist"][1], + view["params"]["denylist"][1], "0x000000000000000000000000000ddd" ); @@ -493,7 +493,7 @@ mod tests { state.modules = Some(pipeline(vec![instance_with_params( "risk-scorer", &[HookName::BeforeTransactionApproved], - Arc::new(BasicPolicy), + Arc::new(RecipientPolicy), json!({}), )])); state diff --git a/crates/server/src/builder/mod.rs b/crates/server/src/builder/mod.rs index 12c20f03..e4426b26 100644 --- a/crates/server/src/builder/mod.rs +++ b/crates/server/src/builder/mod.rs @@ -445,7 +445,8 @@ impl ServerBuilder { /// Registers a policy module kind that runs in this process, so catalog entries /// (`GUARDIAN_MODULES_CONFIG`) can name it in `kind`. The module shares the process that /// holds the acknowledgement keys, so register only code you have reviewed. `build` fails - /// if the name is already taken, including by the first-party `basic-policy` and `grpc`. + /// if the name is already taken, including by the first-party policies (`spending-limit`, + /// `recipient-policy`, `signer-policy`, `code-policy`) and `grpc`. /// /// # Example /// ```ignore diff --git a/crates/server/src/modules/admin.rs b/crates/server/src/modules/admin.rs index dd270833..1f7f22bc 100644 --- a/crates/server/src/modules/admin.rs +++ b/crates/server/src/modules/admin.rs @@ -715,7 +715,7 @@ mod tests { use std::collections::BTreeSet; use std::sync::Arc; - use guardian_module_sdk::basic_policy::BasicPolicy; + use guardian_module_sdk::policies::RecipientPolicy; use serde_json::json; use super::*; @@ -756,17 +756,17 @@ mod tests { Arc::new(metadata), ); let hooks = [HookName::BeforeTransactionApproved]; - let mut optional = instance("optional", &hooks, OnError::Deny, Arc::new(BasicPolicy)); + let mut optional = instance("optional", &hooks, OnError::Deny, Arc::new(RecipientPolicy)); optional.config.scope = Scope::Assigned; - let mut secret = instance("vendor", &hooks, OnError::Deny, Arc::new(BasicPolicy)); + let mut secret = instance("vendor", &hooks, OnError::Deny, Arc::new(RecipientPolicy)); secret.config.file_managed_params = true; secret.config.operator_can_disable = false; state.modules = Some(pipeline(vec![ instance_with_params( "blocklist", &hooks, - Arc::new(BasicPolicy), - json!({ "recipient_denylist": ["0x000000000000000000000000000aaa"] }), + Arc::new(RecipientPolicy), + json!({ "denylist": ["0x000000000000000000000000000aaa"] }), ), optional, secret, @@ -834,7 +834,7 @@ mod tests { "screening", &[HookName::BeforeTransactionApproved], OnError::Deny, - Arc::new(BasicPolicy), + Arc::new(RecipientPolicy), ); screening.config.scope = Scope::Default; instances.push(screening); @@ -925,7 +925,7 @@ mod tests { &operator(), ACCOUNT, "blocklist", - Some(json!({ "recipient_denylist": ["0x000000000000000000000000000bbb"] })), + Some(json!({ "denylist": ["0x000000000000000000000000000bbb"] })), "OP-1", None, ) @@ -1029,7 +1029,7 @@ mod tests { &operator(), "0xAcC", "blocklist", - Some(json!({ "recipient_denylist": ["0x000000000000000000000000000bbb"] })), + Some(json!({ "denylist": ["0x000000000000000000000000000bbb"] })), "OP-1", None, ) @@ -1067,7 +1067,7 @@ mod tests { .set_layer( ACCOUNT, "optional", - Some(json!({ "recipient_denylist": ["0x000000000000000000000000000bbb"] })), + Some(json!({ "denylist": ["0x000000000000000000000000000bbb"] })), &Change { operator: "0xop", reason: "written while optional applied to every account", @@ -1123,7 +1123,7 @@ mod tests { "optional", &hooks, OnError::Deny, - Arc::new(BasicPolicy), + Arc::new(RecipientPolicy), )], store, ))); @@ -1189,7 +1189,7 @@ mod tests { &operator(), ACCOUNT, "blocklist", - Some(json!({ "recipient_denylist": ["0x000000000000000000000000000bbb"] })), + Some(json!({ "denylist": ["0x000000000000000000000000000bbb"] })), "OP-2", None, ) @@ -1214,7 +1214,7 @@ mod tests { &state, &operator, "blocklist", - json!({ "recipient_denylist": ["0x000000000000000000000000000aaa", "0x000000000000000000000000000ddd"] }), + json!({ "denylist": ["0x000000000000000000000000000aaa", "0x000000000000000000000000000ddd"] }), "OP-90", None, ) @@ -1225,7 +1225,7 @@ mod tests { &operator, ACCOUNT, "blocklist", - Some(json!({ "recipient_denylist": ["0x000000000000000000000000000ccc"] })), + Some(json!({ "denylist": ["0x000000000000000000000000000ccc"] })), "OP-91", None, ) @@ -1235,12 +1235,12 @@ mod tests { assert_eq!( entry.global_params, Some( - json!({ "recipient_denylist": ["0x000000000000000000000000000aaa", "0x000000000000000000000000000ddd"] }) + json!({ "denylist": ["0x000000000000000000000000000aaa", "0x000000000000000000000000000ddd"] }) ) ); assert_eq!( entry.account_layer, - Some(json!({ "recipient_denylist": ["0x000000000000000000000000000ccc"] })) + Some(json!({ "denylist": ["0x000000000000000000000000000ccc"] })) ); let history = history(&state, "blocklist", None, None) @@ -1264,7 +1264,7 @@ mod tests { &state, &operator(), "blocklist", - json!({ "recipient_denylist": [format!("0x{n:030x}")] }), + json!({ "denylist": [format!("0x{n:030x}")] }), &format!("OP-{n}"), None, ) @@ -1298,7 +1298,7 @@ mod tests { #[tokio::test] async fn params_over_the_size_cap_are_refused_before_the_module_is_called() { let state = state(); - let huge = json!({ "recipient_denylist": vec!["0x".repeat(40); 4_000] }); + let huge = json!({ "denylist": vec!["0x".repeat(40); 4_000] }); let refused = set_global(&state, &operator(), "blocklist", huge, "OP-9", None).await; assert!( matches!(&refused, Err(GuardianError::InvalidInput(message)) if message.contains("GUARDIAN_MODULE_PARAMS_MAX_BYTES")), @@ -1392,7 +1392,7 @@ mod tests { .seed_instance( "blocklist", true, - &json!({ "recipient_denylist": ["0x000000000000000000000000000aaa"] }), + &json!({ "denylist": ["0x000000000000000000000000000aaa"] }), "t0", ) .await @@ -1437,7 +1437,7 @@ mod tests { ACCOUNT, vec![Assigned { module_id: "optional".into(), - params: json!({ "recipient_denylist": ["0x000000000000000000000000000eee"] }), + params: json!({ "denylist": ["0x000000000000000000000000000eee"] }), }], "customer request", None, diff --git a/crates/server/src/modules/catalog.rs b/crates/server/src/modules/catalog.rs index 9a4f187b..f306506b 100644 --- a/crates/server/src/modules/catalog.rs +++ b/crates/server/src/modules/catalog.rs @@ -549,15 +549,15 @@ mod tests { const VALID: &str = r#" [[module]] id = "caps" -kind = "basic-policy" +kind = "spending-limit" scope = "all" hooks = ["before_transaction_approved", "before_proposal_created"] timeout_ms = 20 -params = { max_amount_per_tx = { "0x0000000000000000000000000000aa" = "1000" } } +params = { max_per_transaction = { "0x0000000000000000000000000000aa" = "1000" } } [[module]] id = "signers" -kind = "basic-policy" +kind = "signer-policy" scope = "assigned" hooks = ["before_account_registered"] timeout_ms = 20 @@ -569,7 +569,7 @@ on_error = "allow" .iter() .map(|(id, scope, timeout_ms)| { format!( - "[[module]]\nid = \"{id}\"\nkind = \"basic-policy\"\nscope = \"{scope}\"\n\ + "[[module]]\nid = \"{id}\"\nkind = \"spending-limit\"\nscope = \"{scope}\"\n\ hooks = [\"before_transaction_approved\"]\ntimeout_ms = {timeout_ms}\n\n" ) }) @@ -655,7 +655,7 @@ on_error = "allow" ), ( "grpc without endpoint", - VALID.replacen(r#"kind = "basic-policy""#, r#"kind = "grpc""#, 1), + VALID.replacen(r#"kind = "spending-limit""#, r#"kind = "grpc""#, 1), ), ( "empty id", @@ -682,7 +682,7 @@ on_error = "allow" r#" [[module]] id = "vendor" -kind = "basic-policy" +kind = "vendor-screening" scope = "{scope}" hooks = ["before_transaction_approved"] timeout_ms = 20 @@ -698,7 +698,7 @@ params = {{ api_key = {{ "$secret" = "vendor-key" }} }} #[test] fn params_with_secret_references_are_file_managed() { let text = VALID.replacen( - r#"params = { max_amount_per_tx = { "0x0000000000000000000000000000aa" = "1000" } }"#, + r#"params = { max_per_transaction = { "0x0000000000000000000000000000aa" = "1000" } }"#, r#"params = { api_key = { "$secret" = "x" } }"#, 1, ); @@ -842,7 +842,7 @@ timeout_ms = 20 r#" [[module]] id = "vendor" -kind = "basic-policy" +kind = "vendor-screening" scope = "all" hooks = ["before_transaction_approved"] timeout_ms = 20 diff --git a/crates/server/src/modules/mod.rs b/crates/server/src/modules/mod.rs index 762d8758..6dca0ba3 100644 --- a/crates/server/src/modules/mod.rs +++ b/crates/server/src/modules/mod.rs @@ -189,7 +189,7 @@ mod tests { r#" [[module]] id = "caps" -kind = "basic-policy" +kind = "spending-limit" scope = "all" hooks = ["before_transaction_approved"] timeout_ms = 20 diff --git a/crates/server/src/modules/pipeline.rs b/crates/server/src/modules/pipeline.rs index 1a9d2e85..0b6c4ace 100644 --- a/crates/server/src/modules/pipeline.rs +++ b/crates/server/src/modules/pipeline.rs @@ -1177,7 +1177,7 @@ mod tests { r#" [[module]] id = "caps" -kind = "basic-policy" +kind = "spending-limit" scope = "all" hooks = ["before_transaction_approved"] timeout_ms = 50 @@ -1221,7 +1221,7 @@ params = {params} let now = "2026-10-15T00:00:00Z".to_string(); let started = ModulePipeline::new( "local", - caps_catalog(r#"{ max_amount_per_txx = {} }"#), + caps_catalog(r#"{ max_per_transactionx = {} }"#), ®istry, store.clone(), now.clone(), @@ -1231,8 +1231,9 @@ params = {params} assert!(started.is_err()); assert!(store.instances().await.unwrap().is_empty()); - let fixed = - caps_catalog(r#"{ max_amount_per_tx = { "0x0000000000000000000000000000aa" = "5" } }"#); + let fixed = caps_catalog( + r#"{ max_per_transaction = { "0x0000000000000000000000000000aa" = "5" } }"#, + ); let started = ModulePipeline::new( "local", fixed, @@ -1247,7 +1248,7 @@ params = {params} started.instances()[0] .build .as_deref() - .is_some_and(|build| build.starts_with("basic-policy")) + .is_some_and(|build| build.starts_with("spending-limit")) ); assert_eq!(store.instances().await.unwrap().len(), 1); } @@ -1261,14 +1262,14 @@ params = {params} .seed_instance( "caps", true, - &serde_json::json!({ "max_amount_per_tx": {} }), + &serde_json::json!({ "max_per_transaction": {} }), &now, ) .await .unwrap(); ModulePipeline::new( "local", - caps_catalog(r#"{ max_amount_per_txx = {} }"#), + caps_catalog(r#"{ max_per_transactionx = {} }"#), ®istry, store.clone(), now.clone(), @@ -1289,7 +1290,7 @@ params = {params} ) .await .unwrap(); - let valid_seed = caps_catalog(r#"{ max_amount_per_tx = {} }"#); + let valid_seed = caps_catalog(r#"{ max_per_transaction = {} }"#); assert!( ModulePipeline::new( "local", @@ -1996,7 +1997,7 @@ params = { old_name = 1000 } use super::*; use crate::modules::store::Change; use crate::modules::testing::instance_with_params; - use guardian_module_sdk::basic_policy::BasicPolicy; + use guardian_module_sdk::policies::RecipientPolicy; use guardian_module_sdk::proto::hook_request; use guardian_module_sdk::{ MidenTransaction, OutputNote, TransactionProjection, TransactionSubject, @@ -2024,8 +2025,8 @@ params = { old_name = 1000 } ModulePipeline::from_instances(vec![instance_with_params( "blocklist", &[HOOK], - std::sync::Arc::new(BasicPolicy), - json!({ "recipient_denylist": ["0x000000000000000000000000000aaa"] }), + std::sync::Arc::new(RecipientPolicy), + json!({ "denylist": ["0x000000000000000000000000000aaa"] }), )]) } @@ -2057,7 +2058,7 @@ params = { old_name = 1000 } .set_layer( "0xacc", "blocklist", - Some(json!({ "recipient_denylist": ["0x000000000000000000000000000ccc"] })), + Some(json!({ "denylist": ["0x000000000000000000000000000ccc"] })), &change(), ) .await @@ -2115,7 +2116,7 @@ params = { old_name = 1000 } .seed_instance( "blocklist", true, - &json!({ "recipient_denylist": ["0x000000000000000000000000000aaa"] }), + &json!({ "denylist": ["0x000000000000000000000000000aaa"] }), "t0", ) .await @@ -2124,7 +2125,7 @@ params = { old_name = 1000 } .store() .set_global( "blocklist", - json!({ "recipient_denylist": ["0x000000000000000000000000000aaa", "0x000000000000000000000000000ddd"] }), + json!({ "denylist": ["0x000000000000000000000000000aaa", "0x000000000000000000000000000ddd"] }), &change(), ) .await @@ -2145,7 +2146,7 @@ params = { old_name = 1000 } .seed_instance( "blocklist", true, - &json!({ "recipient_denylist": ["0x000000000000000000000000000aaa"] }), + &json!({ "denylist": ["0x000000000000000000000000000aaa"] }), "t0", ) .await @@ -2590,7 +2591,7 @@ mod failure_handling_tests { let healthy = crate::modules::testing::instance_with_params( "caps", &[HOOK], - Arc::new(guardian_module_sdk::basic_policy::BasicPolicy), + Arc::new(guardian_module_sdk::policies::RecipientPolicy), serde_json::json!({}), ); let (down, _) = hanging("screening", OnError::Deny, Duration::from_millis(20)); diff --git a/crates/server/src/modules/postgres_store.rs b/crates/server/src/modules/postgres_store.rs index ac7f317d..a6d7bdac 100644 --- a/crates/server/src/modules/postgres_store.rs +++ b/crates/server/src/modules/postgres_store.rs @@ -780,12 +780,7 @@ mod tests { let start = store.version().await.unwrap(); store - .seed_instance( - &module, - true, - &json!({ "recipient_denylist": ["0xaaa"] }), - t0, - ) + .seed_instance(&module, true, &json!({ "denylist": ["0xaaa"] }), t0) .await .unwrap(); store @@ -795,7 +790,7 @@ mod tests { store .set_global( &module, - json!({ "recipient_denylist": ["0xaaa", "0xddd"] }), + json!({ "denylist": ["0xaaa", "0xddd"] }), &change(t0), ) .await @@ -804,7 +799,7 @@ mod tests { .set_layer( &account, &module, - Some(json!({ "recipient_denylist": ["0xccc"] })), + Some(json!({ "denylist": ["0xccc"] })), &change(t0), ) .await @@ -830,12 +825,9 @@ mod tests { .unwrap(); assert_eq!( instance.global_params, - json!({ "recipient_denylist": ["0xaaa", "0xddd"] }) - ); - assert_eq!( - instance.seeded_params, - json!({ "recipient_denylist": ["0xaaa"] }) + json!({ "denylist": ["0xaaa", "0xddd"] }) ); + assert_eq!(instance.seeded_params, json!({ "denylist": ["0xaaa"] })); let rows = other_replica.account_params(&account).await.unwrap(); assert_eq!(rows.len(), 2); diff --git a/crates/server/src/modules/registry.rs b/crates/server/src/modules/registry.rs index 60ce838c..a55f19df 100644 --- a/crates/server/src/modules/registry.rs +++ b/crates/server/src/modules/registry.rs @@ -3,7 +3,9 @@ use std::collections::{HashMap, HashSet}; use std::sync::Arc; -use guardian_module_sdk::basic_policy::{self, BasicPolicy}; +use guardian_module_sdk::policies::{ + self, CodePolicy, RecipientPolicy, SignerPolicy, SpendingLimit, +}; use guardian_module_sdk::{ DescribeRequest, Module, ModuleError, ModuleFactory, ModuleInfo, ModuleInstanceConfig, PROTOCOL_VERSION, capability, @@ -20,11 +22,13 @@ pub struct Instance { pub build: Option, } -struct BasicPolicyFactory; +/// A first-party policy: stateless, so every instance of the kind shares one module; each +/// call carries its instance's params. +struct FirstParty(Arc); -impl ModuleFactory for BasicPolicyFactory { +impl ModuleFactory for FirstParty { fn create(&self, _instance: &ModuleInstanceConfig) -> Result, ModuleError> { - Ok(Arc::new(BasicPolicy)) + Ok(self.0.clone()) } } @@ -47,9 +51,17 @@ impl Registry { let mut registry = Self { factories: HashMap::new(), }; - registry - .factories - .insert(basic_policy::KIND.into(), Arc::new(BasicPolicyFactory)); + let policies: [(&str, Arc); 4] = [ + (policies::spending_limit::KIND, Arc::new(SpendingLimit)), + (policies::recipient_policy::KIND, Arc::new(RecipientPolicy)), + (policies::signer_policy::KIND, Arc::new(SignerPolicy)), + (policies::code_policy::KIND, Arc::new(CodePolicy)), + ]; + for (kind, module) in policies { + registry + .factories + .insert(kind.into(), Arc::new(FirstParty(module))); + } registry .factories .insert("grpc".into(), Arc::new(GrpcFactory)); @@ -57,7 +69,7 @@ impl Registry { } /// Adds a kind the catalog can name. A kind is registered once; the first-party names - /// (`basic-policy`, `grpc`) cannot be replaced. + /// (the four policies and `grpc`) cannot be replaced. pub fn register( &mut self, kind: impl Into, @@ -486,7 +498,7 @@ enabled = ENABLED impl ModuleFactory for StubFactory { fn create(&self, _: &ModuleInstanceConfig) -> Result, ModuleError> { - Ok(Arc::new(BasicPolicy)) + Ok(Arc::new(RecipientPolicy)) } } @@ -532,7 +544,7 @@ timeout_ms = 50 #[test] fn a_kind_name_is_taken_once() { let mut registry = Registry::first_party(); - for taken in [basic_policy::KIND, "grpc"] { + for taken in policies::KINDS.into_iter().chain(["grpc"]) { assert!(registry.register(taken, Arc::new(StubFactory)).is_err()); } registry diff --git a/crates/server/src/modules/secrets.rs b/crates/server/src/modules/secrets.rs index 6198f4dc..4648947e 100644 --- a/crates/server/src/modules/secrets.rs +++ b/crates/server/src/modules/secrets.rs @@ -242,7 +242,7 @@ timeout_ms = 20 params = {params} "#, kind = if extra.is_empty() { - "basic-policy" + "vendor-screening" } else { "grpc" }, @@ -336,7 +336,7 @@ tls = { client_cert_secret = "risk-cert", client_key_secret = "risk-key" }"#, r#"{ api_key = { "$secret" = "has space" } }"#, ] { let text = format!( - "[[module]]\nid = \"m\"\nkind = \"basic-policy\"\nscope = \"all\"\nhooks = [\"before_transaction_approved\"]\ntimeout_ms = 20\nparams = {params}\n" + "[[module]]\nid = \"m\"\nkind = \"vendor-screening\"\nscope = \"all\"\nhooks = [\"before_transaction_approved\"]\ntimeout_ms = 20\nparams = {params}\n" ); assert!(Catalog::parse(&text, None).is_err(), "{params}"); } diff --git a/crates/server/src/services/execute_proposal/tests.rs b/crates/server/src/services/execute_proposal/tests.rs index b9001008..fa61bf21 100644 --- a/crates/server/src/services/execute_proposal/tests.rs +++ b/crates/server/src/services/execute_proposal/tests.rs @@ -1339,8 +1339,8 @@ async fn a_guardian_execution_over_a_mandatory_cap_is_refused_before_anything_is let cap = crate::modules::testing::instance_with_params( "caps", &[crate::modules::catalog::HookName::BeforeTransactionApproved], - Arc::new(guardian_module_sdk::basic_policy::BasicPolicy), - serde_json::json!({ "max_amount_per_tx": { USDC: "1000" } }), + Arc::new(guardian_module_sdk::policies::SpendingLimit), + serde_json::json!({ "max_per_transaction": { USDC: "1000" } }), ); let paying_5000 = guardian_module_sdk::MidenTransaction { output_notes: vec![guardian_module_sdk::OutputNote { diff --git a/crates/server/src/services/push_delta.rs b/crates/server/src/services/push_delta.rs index 736f71b1..73808554 100644 --- a/crates/server/src/services/push_delta.rs +++ b/crates/server/src/services/push_delta.rs @@ -2318,8 +2318,8 @@ mod tests { crate::modules::testing::instance_with_params( "caps", &[HookName::BeforeTransactionApproved], - Arc::new(guardian_module_sdk::basic_policy::BasicPolicy), - serde_json::json!({ "max_amount_per_tx": { USDC: "1000" } }), + Arc::new(guardian_module_sdk::policies::SpendingLimit), + serde_json::json!({ "max_per_transaction": { USDC: "1000" } }), ) } diff --git a/examples/policy-module/Cargo.toml b/examples/policy-module/Cargo.toml index 692f82f2..c1424c08 100644 --- a/examples/policy-module/Cargo.toml +++ b/examples/policy-module/Cargo.toml @@ -3,7 +3,7 @@ name = "guardian-policy-module" version = "0.1.0" edition = "2024" publish = false -description = "basic-policy served as a standalone Guardian policy module over gRPC" +description = "The Guardian's built-in policies served as a standalone policy module over gRPC" [[bin]] name = "policy-module" diff --git a/examples/policy-module/Dockerfile b/examples/policy-module/Dockerfile index 2171300c..52d45904 100644 --- a/examples/policy-module/Dockerfile +++ b/examples/policy-module/Dockerfile @@ -1,4 +1,4 @@ -# basic-policy as a standalone Guardian policy module. Build from the repository root: +# The built-in policies as a standalone Guardian policy module. Build from the repository root: # docker build -f examples/policy-module/Dockerfile -t guardian-policy-module . FROM rust:1.98.1-bookworm AS builder diff --git a/examples/policy-module/src/main.rs b/examples/policy-module/src/main.rs index 74415be2..6285721b 100644 --- a/examples/policy-module/src/main.rs +++ b/examples/policy-module/src/main.rs @@ -1,14 +1,32 @@ use std::net::SocketAddr; use std::path::PathBuf; -use guardian_module_sdk::basic_policy::BasicPolicy; +use std::sync::Arc; + +use guardian_module_sdk::Module; +use guardian_module_sdk::policies::{CodePolicy, RecipientPolicy, SignerPolicy, SpendingLimit}; use guardian_module_sdk::serve::serve; use tonic::transport::{Certificate, Identity, Server, ServerTlsConfig}; -const USAGE: &str = "usage: policy-module [--listen ADDR] --instance ID TOKEN_FILE [--instance ...] +const USAGE: &str = + "usage: policy-module --kind KIND [--listen ADDR] --instance ID TOKEN_FILE [--instance ...] [--tls-cert PEM --tls-key PEM [--client-ca PEM]] [--insecure]"; +/// The built-in policy this process serves, as the Guardian's catalog names it. +fn policy(kind: &str) -> Result, String> { + match kind { + "spending-limit" => Ok(Arc::new(SpendingLimit)), + "recipient-policy" => Ok(Arc::new(RecipientPolicy)), + "signer-policy" => Ok(Arc::new(SignerPolicy)), + "code-policy" => Ok(Arc::new(CodePolicy)), + other => Err(format!( + "unknown kind {other}; one of spending-limit, recipient-policy, signer-policy, code-policy" + )), + } +} + struct Args { + kind: String, listen: SocketAddr, instances: Vec<(String, PathBuf)>, tls_cert: Option, @@ -20,6 +38,7 @@ struct Args { impl Args { fn parse() -> Result { let mut parsed = Self { + kind: String::new(), listen: SocketAddr::from(([127, 0, 0, 1], 7443)), instances: Vec::new(), tls_cert: None, @@ -33,6 +52,7 @@ impl Args { }; while let Some(arg) = args.next() { match arg.as_str() { + "--kind" => parsed.kind = value(&mut args, "--kind")?, "--listen" => { parsed.listen = value(&mut args, "--listen")? .parse() @@ -51,6 +71,9 @@ impl Args { other => return Err(format!("unknown argument {other}\n{USAGE}")), } } + if parsed.kind.is_empty() { + return Err(format!("--kind is required\n{USAGE}")); + } if parsed.instances.is_empty() { return Err(format!("at least one --instance is required\n{USAGE}")); } @@ -115,7 +138,7 @@ async fn main() -> std::process::ExitCode { async fn run() -> Result<(), Box> { let args = Args::parse()?; - let mut module = serve(BasicPolicy); + let mut module = serve(policy(&args.kind)?); for (id, token_file) in &args.instances { let token = std::fs::read_to_string(token_file) .map_err(|e| format!("cannot read token file {}: {e}", token_file.display()))?; @@ -135,7 +158,8 @@ async fn run() -> Result<(), Box> { }; let ids: Vec<&str> = args.instances.iter().map(|(id, _)| id.as_str()).collect(); println!( - "basic-policy listening on {} ({transport}), instances: {}", + "{} listening on {} ({transport}), instances: {}", + args.kind, args.listen, ids.join(", ") ); diff --git a/packages/guardian-client/src/http.test.ts b/packages/guardian-client/src/http.test.ts index bcea3e64..64b47399 100644 --- a/packages/guardian-client/src/http.test.ts +++ b/packages/guardian-client/src/http.test.ts @@ -656,8 +656,8 @@ describe('GuardianHttpClient', () => { module_id: 'caps', hooks: ['before_transaction_approved'], description: 'At most 5 per transaction', - params: { max_amount_per_tx: { '0xaa': '5' } }, - account_layer: { max_amount_per_tx: { '0xaa': '2' } }, + params: { max_per_transaction: { '0xaa': '5' } }, + account_layer: { max_per_transaction: { '0xaa': '2' } }, }, { module_id: 'screening', hooks: ['before_proposal_created'], description: 'Screened' }, ], @@ -671,8 +671,8 @@ describe('GuardianHttpClient', () => { moduleId: 'caps', hooks: ['before_transaction_approved'], description: 'At most 5 per transaction', - params: { max_amount_per_tx: { '0xaa': '5' } }, - accountLayer: { max_amount_per_tx: { '0xaa': '2' } }, + params: { max_per_transaction: { '0xaa': '5' } }, + accountLayer: { max_per_transaction: { '0xaa': '2' } }, }, { moduleId: 'screening', hooks: ['before_proposal_created'], description: 'Screened' }, ]); diff --git a/packages/guardian-operator-client/src/http.test.ts b/packages/guardian-operator-client/src/http.test.ts index 3520644a..494dfada 100644 --- a/packages/guardian-operator-client/src/http.test.ts +++ b/packages/guardian-operator-client/src/http.test.ts @@ -2299,7 +2299,7 @@ describe('GuardianOperatorHttpClient — account pausing (feature 001)', () => { scope: 'all', circuit: 'closed', operatorCanDisable: true, - params: { max_amount_per_tx: { '0xaa': '5' } }, + params: { max_per_transaction: { '0xaa': '5' } }, }); expect(catalog.undeclared).toEqual([{ moduleId: 'retired', enabled: false, params: {} }]); expect(mockFetch).toHaveBeenCalledWith( @@ -2368,10 +2368,10 @@ describe('GuardianOperatorHttpClient — account pausing (feature 001)', () => { const client = new GuardianOperatorHttpClient('https://guardian.example'); mockFetch.mockResolvedValueOnce(okJson(INSTANCE)); - await client.setModuleGlobalParams('caps', { max_amount_per_tx: {} }, 'OP-4'); + await client.setModuleGlobalParams('caps', { max_per_transaction: {} }, 'OP-4'); expect(mockFetch).toHaveBeenLastCalledWith( 'https://guardian.example/dashboard/modules/caps/params', - expect.objectContaining({ method: 'PUT', body: JSON.stringify({ params: { max_amount_per_tx: {} }, reason: 'OP-4' }) }), + expect.objectContaining({ method: 'PUT', body: JSON.stringify({ params: { max_per_transaction: {} }, reason: 'OP-4' }) }), ); mockFetch.mockResolvedValueOnce(okJson({ ...INSTANCE, enabled: false })); @@ -2766,17 +2766,17 @@ describe('GuardianOperatorHttpClient — account pause/unpause', () => { const INSTANCE = { module_id: 'caps', - kind: 'basic-policy', + kind: 'spending-limit', scope: 'all', hooks: ['before_transaction_approved'], enabled: true, catalog_enabled: true, enabled_drift: false, operator_can_disable: true, - params: { max_amount_per_tx: { '0xaa': '5' } }, + params: { max_per_transaction: { '0xaa': '5' } }, params_drift: false, file_managed_params: false, - build: 'basic-policy 0.19.0', + build: 'spending-limit 0.19.0', disclosure: 'params', description: 'At most 5 per transaction', client_reason: 'full', diff --git a/packages/miden-multisig-client/tests/qualification/actions/live.ts b/packages/miden-multisig-client/tests/qualification/actions/live.ts index e423a747..cf25115e 100644 --- a/packages/miden-multisig-client/tests/qualification/actions/live.ts +++ b/packages/miden-multisig-client/tests/qualification/actions/live.ts @@ -26,7 +26,7 @@ import { type LiveSession, type Scheme, } from '../live.js'; -import { GATE, expectDenied } from './modules.js'; +import { CAP, expectDenied } from './modules.js'; import { setAccountModules, setAccountPaused } from './operator.js'; import type { ActionContext, ActionOutcome } from '../runner.js'; @@ -3423,7 +3423,7 @@ export async function abandonStrandedHeadAndRecover( } /** - * Assigns the stack's `qual-gate` module to the scenario's account with a cap + * Assigns the stack's `qual-cap` module to the scenario's account with a cap * of exactly what `asset-send` sends, and reads it back through the account's * own policy listing. Mirrors `assign_cap` in the Rust driver. */ @@ -3435,18 +3435,18 @@ export async function assignModuleCap(context: ActionContext, scenarioId: string if (!session.faucetId) { return { kind: 'failed', classification: 'setup', reason: 'the account was never funded, so there is no asset to cap' }; } - const cap = { max_amount_per_tx: { [session.faucetId]: P2ID_AMOUNT.toString() } }; - const assigned = await setAccountModules(context, session.accountId, [{ moduleId: GATE, params: cap }]); + const cap = { max_per_transaction: { [session.faucetId]: P2ID_AMOUNT.toString() } }; + const assigned = await setAccountModules(context, session.accountId, [{ moduleId: CAP, params: cap }]); if (assigned) return assigned; try { const policies = await session.multisig.getPolicies(); - const policy = policies.find((entry) => entry.moduleId === GATE); + const policy = policies.find((entry) => entry.moduleId === CAP); if (!policy) { return { kind: 'failed', classification: 'product', - reason: `the account's policies do not list the ${GATE} it was assigned: ${JSON.stringify(policies)}`, + reason: `the account's policies do not list the ${CAP} it was assigned: ${JSON.stringify(policies)}`, }; } const expected = JSON.stringify(cap); @@ -3454,7 +3454,7 @@ export async function assignModuleCap(context: ActionContext, scenarioId: string return { kind: 'failed', classification: 'product', - reason: `the account's policies list ${GATE} without the cap it was assigned: ${JSON.stringify(policy)}`, + reason: `the account's policies list ${CAP} without the cap it was assigned: ${JSON.stringify(policy)}`, }; } return { kind: 'passed' }; @@ -3485,7 +3485,7 @@ export async function assertModuleCapRefuses(_context: ActionContext, scenarioId const overCheck = await expectDenied( 'the check of a payment over the cap', () => proposeWhenSettled(() => multisig.checkTransaction(send(P2ID_AMOUNT + 1n))), - GATE, + CAP, 'amount_cap_exceeded', ); if (overCheck.kind !== 'passed') return overCheck; @@ -3495,7 +3495,7 @@ export async function assertModuleCapRefuses(_context: ActionContext, scenarioId proposeWhenSettled(() => multisig.createP2idProposal(session.treasuryId!, session.faucetId!, P2ID_AMOUNT + 1n), ), - GATE, + CAP, 'amount_cap_exceeded', ); if (over.kind !== 'passed') return over; diff --git a/packages/miden-multisig-client/tests/qualification/actions/modules.ts b/packages/miden-multisig-client/tests/qualification/actions/modules.ts index a3c7faf6..321b8877 100644 --- a/packages/miden-multisig-client/tests/qualification/actions/modules.ts +++ b/packages/miden-multisig-client/tests/qualification/actions/modules.ts @@ -7,6 +7,7 @@ import type { ActionContext, ActionOutcome } from '../runner.js'; /** The instance the stack's catalog declares for rules a scenario assigns. */ export const GATE = 'qual-gate'; +export const CAP = 'qual-cap'; /** * A signer commitment nobody holds. Checked against every signer, an allowlist @@ -75,7 +76,7 @@ export async function assertRefusal(context: ActionContext): Promise Date: Tue, 10 Nov 2026 10:41:14 +0100 Subject: [PATCH 090/105] docs(modules): the four built-in policies in the guides, RFC and contracts (#251) The built-in guide documents each kind with its own params table and the hooks it supports; catalogs, remote and custom guides, READMEs, the qualification doc, the speckit contracts and RFC 0002 section 3.1 use the new kinds, recorded in revision 32. Completed tasks and planning notes keep the old name as history. --- crates/guardian-module-sdk/README.md | 5 +- docs/QUALIFICATION.md | 10 +- docs/guides/README.md | 2 +- docs/guides/policy-modules/README.md | 8 +- docs/guides/policy-modules/built-in.md | 133 +++++++++++------- docs/guides/policy-modules/built-in.toml | 23 +-- docs/guides/policy-modules/custom.md | 9 +- docs/guides/policy-modules/remote.md | 15 +- docs/guides/policy-modules/remote.toml | 8 +- docs/rfcs/0002-guardian-modules.md | 66 ++++----- examples/README.md | 2 +- examples/policy-module/README.md | 17 +-- packages/guardian-operator-client/README.md | 4 +- .../contracts/catalog-config.md | 32 ++--- .../251-guardian-modules/quickstart.md | 19 ++- .../features/251-guardian-modules/tasks.md | 4 +- 16 files changed, 201 insertions(+), 156 deletions(-) diff --git a/crates/guardian-module-sdk/README.md b/crates/guardian-module-sdk/README.md index c3830b50..e5603c41 100644 --- a/crates/guardian-module-sdk/README.md +++ b/crates/guardian-module-sdk/README.md @@ -14,8 +14,9 @@ The crate has: version 1 is frozen: new features arrive as named capabilities. - `serve`, a gRPC harness that exposes any `Module` as a remote service with a bearer token per instance. -- `basic_policy`, the Guardian's built-in policy kind (amount caps, recipient - and asset lists, signer rules, code pinning), as a reference. +- `policies`, the Guardian's built-in policy kinds, one concern each, as a + reference: `SpendingLimit` (caps and allowed assets), `RecipientPolicy`, + `SignerPolicy` and `CodePolicy`. - `conformance` (feature `conformance`), a suite that checks a module before it is deployed. diff --git a/docs/QUALIFICATION.md b/docs/QUALIFICATION.md index 13b9d529..beca0ed5 100644 --- a/docs/QUALIFICATION.md +++ b/docs/QUALIFICATION.md @@ -85,7 +85,7 @@ gitignored directories, and tears it down afterwards: | A fourth Guardian that offers execution, `server-executing` | a configured prover and a database of its own (`guardian_executing`), so execution requests get past the capability gate in the deterministic profile | | A fifth Guardian that queues chained candidates, `server-queue` | `GUARDIAN_MAX_PENDING_CANDIDATES_PER_ACCOUNT` set to `2` in the deterministic profile and `4` in the live one (`QUAL_QUEUE_DEPTH` overrides it), the main server's acknowledgement identity, and a database of its own, so the candidate queue (issue #17) is qualified as an operator opts into it while the main server keeps the default of one in-flight candidate | | Operator allowlist | generated from the server fixtures via `qualification-driver operator-keys`, so the identities the scenarios sign with cannot drift from the ones the server accepts | -| Policy module catalog | `lib/modules.sh` writes the main server's catalog per run: two in-process `basic-policy` instances and one remote `grpc` instance, all scoped `assigned` so no other scenario meets them. The remote one points at a module the Rust driver serves on the host (`host.docker.internal`, on `QUAL_MODULE_PORT`) over TLS, with a certificate a per-run CA signs and a bearer token the server reads through the file secrets backend | +| Policy module catalog | `lib/modules.sh` writes the main server's catalog per run: three in-process instances (`qual-gate` and `qual-switch` of kind `signer-policy`, `qual-cap` of kind `spending-limit`) and one remote `grpc` instance, all scoped `assigned` so no other scenario meets them. The remote one points at a module the Rust driver serves on the host (`host.docker.internal`, on `QUAL_MODULE_PORT`) over TLS, with a certificate a per-run CA signs and a bearer token the server reads through the file secrets backend | | Guardian execution | the live profile points the server at the network's public prover (`https://tx-prover..miden.io`, overridable with `QUAL_TX_PROVER_URL`), so it offers execution; the deterministic stack configures none, so execution must be refused | | Postgres password | random per run | | Ports | picked per run, so concurrent runs do not collide | @@ -311,17 +311,17 @@ scenario assigns it to through the operator API, and the operator in the allowli the dry-run check and at creation with `GUARDIAN_MODULE_DENIED`, module `qual-gate` and `signer_not_allowed`, over gRPC (Rust) and HTTP (TypeScript); once the assignment is cleared the same proposal passes the check. -- `det-module-unavailable` (deterministic, Rust): the driver serves `basic-policy` for +- `det-module-unavailable` (deterministic, Rust): the driver serves `signer-policy` for `qual-remote` and enables it. The remote module refuses over TLS with the token from the secrets backend; with the module stopped the check is refused as `GUARDIAN_MODULE_UNAVAILABLE` naming `qual-remote` (`on_error = "deny"`), and disabling the instance lets the account through. The instance starts disabled in the catalog, because an - enabled module that cannot be reached stops the server from starting, and the action leaves - it disabled on every path for the restart that follows. + enabled module that has never started on this Guardian and cannot be reached stops the server + from starting, and the action leaves it disabled on every path for the restart that follows. - `det-module-break-glass` (deterministic, Rust): disabling `qual-switch` lets a refused account through at once. The pass after the restart finds it still disabled against a catalog that says enabled, with the disable in its params history, and enables it again. -- `live-module-cap-1of1-ecdsa` (live, both SDKs, required on testnet): `qual-gate` caps the +- `live-module-cap-1of1-ecdsa` (live, both SDKs, required on testnet): `qual-cap` caps the account at exactly what `asset-send` sends, and the account's own policy listing shows it. One unit more is refused at the check and at creation with `amount_cap_exceeded`; the capped payment passes, is signed by GUARDIAN at execution after the approval hook runs on the real diff --git a/docs/guides/README.md b/docs/guides/README.md index 583a7807..f729d8cc 100644 --- a/docs/guides/README.md +++ b/docs/guides/README.md @@ -26,7 +26,7 @@ storage, or network), not after Compose. | [Miden Dashboard UI](./miden-dashboard/README.md) | Self-hosted Compose: Postgres + Guardian server + the Miden Dashboard operator UI | | [Observability](./observability/README.md) | Local Compose: server + Prometheus + pre-provisioned Grafana dashboard | | [Horizontal scaling](./horizontal-scaling/README.md) | Local Compose: two replicas + round-robin proxy + shared Postgres (sessions, lease failover, fail-closed auth) | -| [Policy modules](./policy-modules/README.md) | From source (`251-modules-m2a` branch): built-in `basic-policy`, a remote module over gRPC, and a custom module written with `guardian-module-sdk` | +| [Policy modules](./policy-modules/README.md) | From source (`251-modules-m2a` branch): the built-in policies, a remote module over gRPC, and a custom module written with `guardian-module-sdk` | ## Adding a guide diff --git a/docs/guides/policy-modules/README.md b/docs/guides/policy-modules/README.md index d8715623..45c6a14f 100644 --- a/docs/guides/policy-modules/README.md +++ b/docs/guides/policy-modules/README.md @@ -21,9 +21,9 @@ operator endpoints and permissions. | Page | Module runs | Use it for | |---|---|---| -| [Built-in](./built-in.md) | Inside the Guardian process (`basic-policy`) | Caps, asset and recipient lists, signer rules, with no extra service | +| [Built-in](./built-in.md) | Inside the Guardian process (`spending-limit`, `recipient-policy`, `signer-policy`, `code-policy`) | Spending caps and allowed assets, recipient lists, signer lists, code pinning, with no extra service | | [Remote](./remote.md) | As its own service over gRPC | A module operated, scaled or upgraded apart from the Guardian, or by another team | -| [Custom](./custom.md) | Your code, written with `guardian-module-sdk`, served over gRPC or compiled into your own server build | Rules `basic-policy` cannot express | +| [Custom](./custom.md) | Your code, written with `guardian-module-sdk`, served over gRPC or compiled into your own server build | Rules the built-in policies cannot express | ## How evaluation works @@ -125,7 +125,7 @@ cp docs/guides/policy-modules/.env.example docs/guides/policy-modules/.env Edit `.guardian/built-in.toml` for your network: replace `0xREPLACE_WITH_FAUCET_ID` with the faucet id of an asset you hold, in `0x` hex form. The server does not -start until you do: `basic-policy` refuses an id that is not hex, since a +start until you do: the built-in policies refuse an id that is not hex, since a placeholder or a bech32 address would never match a transaction. The other pages swap in `remote.toml` or `custom.toml` by changing `GUARDIAN_MODULES_CONFIG` in the guide's `.env`. @@ -143,7 +143,7 @@ module state then goes to `GUARDIAN_METADATA_PATH/modules/module_state.json`. Look for this line in the log: ``` -Policy modules loaded catalog_hash=0x… params_version=… builds=caps=basic-policy , … +Policy modules loaded catalog_hash=0x… params_version=… builds=caps=spending-limit , … ``` The ports are fixed at 3000 (HTTP) and 50051 (gRPC); stop any other Guardian diff --git a/docs/guides/policy-modules/built-in.md b/docs/guides/policy-modules/built-in.md index bbff4272..801ebf77 100644 --- a/docs/guides/policy-modules/built-in.md +++ b/docs/guides/policy-modules/built-in.md @@ -1,67 +1,98 @@ -# Built-in modules - -`basic-policy` runs inside the Guardian process: no extra service, no network -hop. One kind backs any number of instances, each with its own params, hooks -and scope. Do the [setup](./README.md#setup) first; the catalog is -[`built-in.toml`](./built-in.toml). - -## `basic-policy` params - -All params are optional; an instance with none allows everything. Write every -id (faucet, recipient, signer commitment, code commitment) in the `0x` hex form -the Guardian reports, not as a bech32 address: params with another form are -refused, since such an id would never match and its rule would not apply. So -is anything else that is not hex digits after `0x`, such as a placeholder left -in an example catalog, and an id of the wrong length: a faucet or a recipient -is an account id of 30 hex digits, a signer or code commitment is 64, so an id -cut short when it was pasted, or an account id where a commitment belongs, is -caught when the params are validated. Case does not matter, and a cap that -names the same faucet twice in different case is refused. - -A param that only modifies another is refused without it: -`deny_unknown_recipients` needs `recipient_denylist`, `signer_check` needs a -signer list and `code_check` needs `allowed_code_commitments`. This matters for -account layers, which are evaluated with their own params: a layer of -`{"deny_unknown_recipients": true}` alone would do nothing, so it is not -accepted. +# Built-in policies + +Four policy kinds run inside the Guardian process: no extra service, no network +hop. Each enforces one concern, so an instance is configured with only the +params of that rule. One kind backs any number of instances, each with its own +params, hooks and scope. Do the [setup](./README.md#setup) first; the catalog +is [`built-in.toml`](./built-in.toml). + +| Kind | Judges | Hooks it supports | +|---|---|---| +| `spending-limit` | Which assets a transaction moves and how much of each it sends | `before_proposal_created`, `before_transaction_approved` | +| `recipient-policy` | Who a transaction pays | `before_proposal_created`, `before_transaction_approved` | +| `signer-policy` | Who may sign for the account | all three, including `before_account_registered` | +| `code-policy` | Which account code the account may run | all three, including `before_account_registered` | + +A catalog that subscribes a kind to a hook it does not support does not start: +a spending or recipient rule has nothing to judge at registration. A kind +refuses params that belong to another, so a signer list put into a spending +instance is caught when the params are written. + +## Ids + +Write every id (faucet, recipient, signer commitment, code commitment) in the +`0x` hex form the Guardian reports, not as a bech32 address: params with +another form are refused, since such an id would never match and its rule +would not apply. So is anything else that is not hex digits after `0x`, such as +a placeholder left in an example catalog, and an id of the wrong length: a +faucet or a recipient is an account id of 30 hex digits, a signer or code +commitment is 64, so an id cut short when it was pasted, or an account id +where a commitment belongs, is caught when the params are validated. Case does +not matter. + +All params are optional; an instance with none allows everything, which is +what an account layer or assignment of `{}` means. A param that only modifies +another is refused without it (`deny_unknown` needs `denylist`, `check` needs +a list), since an account layer is evaluated with its own params and such a +layer alone would do nothing. + +## `spending-limit` + +| Param | Value | Refuses with | Notes | +|---|---|---|---| +| `max_per_transaction` | `{ "": "" }` | `amount_cap_exceeded` | Gross amount per asset across the transaction's payment notes, in base units. The fee note is not a payment, and an asset that is not listed is not capped. A faucet named twice in different case is refused. | +| `allowed_assets` | `["", ...]` | `asset_not_allowed` | Assets sent in payment notes and received from consumed notes. Unset, any asset; empty, none. | + +Limits over a period (per day, per week) need state the Guardian does not keep +yet; they belong to this kind when they arrive. + +## `recipient-policy` + +| Param | Value | Refuses with | Notes | +|---|---|---|---| +| `allowlist` | `["", ...]` | `recipient_not_allowed` | The only accounts a payment note may go to (P2ID and P2IDE targets). A note whose recipient cannot be identified is refused. Excludes `denylist`. | +| `denylist` | `["", ...]` | `recipient_blocked` | Accounts no payment note may go to. Excludes `allowlist`. | +| `deny_unknown` | `true` / `false`; unset, `true` once `denylist` names anyone | `recipient_blocked` | With `denylist`: also refuses payment notes whose recipient the Guardian cannot identify (a partial note, or one that is not P2ID or P2IDE), since a blocked recipient could otherwise be paid through a note the Guardian cannot read. It is read from the same params as the list, so it cannot be relaxed per account: an account layer only adds restrictions. For accounts that must create custom-script notes, such as swaps, give them their own `assigned` instance with `deny_unknown = false` instead of the shared denylist. | The `blocklist` instance in the guide's catalog starts with an empty -`recipient_denylist`, which refuses nothing. Once a recipient is listed, -globally or in an account's layer, notes without a checkable recipient are -refused for the accounts that list applies to, unless the same params set -`deny_unknown_recipients` to `false`. +`denylist`, which refuses nothing. Once a recipient is listed, globally or in +an account's layer, notes without a checkable recipient are refused for the +accounts that list applies to, unless the same params set `deny_unknown` to +`false`. + +## `signer-policy` + +| Param | Value | Refuses with | Notes | +|---|---|---|---| +| `allowlist` | `["", ...]` | `signer_not_allowed` | The only signers the account may have. Excludes `denylist`. | +| `denylist` | `["", ...]` | `signer_not_allowed` | Signers the account may not have. Excludes `allowlist`. | +| `check` | `"added"` (default) or `"all"` | | `added` checks only signers a registration or transaction adds; `all` checks every signer the account has after it. | + +## `code-policy` | Param | Value | Refuses with | Notes | |---|---|---|---| -| `max_amount_per_tx` | `{ "": "" }` | `amount_cap_exceeded` | Gross amount per asset across the transaction's payment notes, in base units. The fee note is not a payment. | -| `asset_allowlist` | `["", ...]` | `asset_not_allowed` | Assets sent in payment notes and received in input notes. | -| `recipient_allowlist` | `["", ...]` | `recipient_not_allowed` | P2ID and P2IDE targets. | -| `recipient_denylist` | `["", ...]` | `recipient_blocked` | | -| `deny_unknown_recipients` | `true` / `false`; unset, `true` once the denylist names anyone | `recipient_blocked` | With `recipient_denylist`: also refuses payment notes whose recipient the Guardian cannot identify (a partial note, or one that is not P2ID or P2IDE). On by default as soon as the list is not empty, since a blocked recipient could otherwise be paid through a note the Guardian cannot read. Set it to `false` for accounts that must create custom-script notes, such as swaps. | -| `signer_allowlist` or `signer_denylist` | `["", ...]` | `signer_not_allowed` | Mutually exclusive. | -| `signer_check` | `"added"` (default) or `"all"` | | `added` checks only signers a transaction adds; `all` checks every signer after it. | -| `allowed_code_commitments` | `["", ...]` | `code_not_allowed` | Pins accounts to account code you reviewed. The Guardian does not check an account's code itself, so a module verdict is only as good as the code that requires the Guardian's signature. | -| `code_check` | `"changed"` (default) or `"all"` | | `changed` checks the code an account registers with and code a transaction replaces it with, so accounts already on other code keep working until they change it; `all` checks the code the account runs at every hook, so an account on unlisted code can only upgrade to listed code. | - -Signer and code rules apply at all three hooks, including registration. -Transaction rules (caps, assets, recipients) apply to proposals and approvals. +| `allowed` | `["", ...]` | `code_not_allowed` | Pins accounts to account code you reviewed. The Guardian does not check an account's code itself, so a module verdict is only as good as the code that requires the Guardian's signature. | +| `check` | `"changed"` (default) or `"all"` | | `changed` checks the code an account registers with and code a transaction replaces it with, so accounts already on other code keep working until they change it; `all` checks the code the account runs at every hook, so an account on unlisted code can only upgrade to listed code. | + +## Refusals Each refusal carries a fixed `client_message` naming the rule (for example "The transaction sends more than this Guardian allows per transaction."), never a list entry or a limit, so a `client_reason = "full"` instance tells users what to change without disclosing params. The exact amounts and -entries go to the server log. A transaction request without a Miden -projection is not judged: the module returns an error and the instance's +entries go to the server log. A request a kind cannot judge (a transaction +without a Miden projection, say) is an error, not an allow, so the instance's `on_error` applies. ## The example catalog | Instance | Scope | Rule | |---|---|---| -| `caps` | all | At most 5 of one asset per transaction; can be switched off; discloses its params to cosigners | -| `blocklist` | all | Recipient denylist, empty until you fill it; denies generically | -| `signers` | all | One signer may never be added; the catalog protects it from being switched off | -| `treasury-allowlist` | assigned | Opt-in: applies only to accounts you assign it to | +| `caps` (`spending-limit`) | all | At most 5 of one asset per transaction; can be switched off; discloses its params to cosigners | +| `blocklist` (`recipient-policy`) | all | Recipient denylist, empty until you fill it; denies generically | +| `signers` (`signer-policy`) | all | One signer may never be added; the catalog protects it from being switched off | +| `treasury-allowlist` (`recipient-policy`) | assigned | Opt-in: applies only to accounts you assign it to | ## Try it @@ -75,7 +106,7 @@ proposal is created: `GUARDIAN_MODULE_DENIED`, module `caps`, reason **Global blocklist.** Block the recipient for every account: ```sh -admin PUT /modules/blocklist/params '{"params":{"recipient_denylist":["RECIPIENT"]},"reason":"test"}' +admin PUT /modules/blocklist/params '{"params":{"denylist":["RECIPIENT"]},"reason":"test"}' ``` A payment to it is refused, but the client only sees @@ -87,7 +118,7 @@ has both. ```sh admin PUT /accounts/ACCOUNT/modules/caps/params \ - '{"params":{"max_amount_per_tx":{"":"2"}},"reason":"test"}' + '{"params":{"max_per_transaction":{"":"2"}},"reason":"test"}' admin GET /accounts/ACCOUNT/modules ``` @@ -105,7 +136,7 @@ admin DELETE /accounts/ACCOUNT/modules/caps/params '{"reason":"done"}' ```sh admin PUT /accounts/ACCOUNT/modules \ - '{"modules":[{"module_id":"treasury-allowlist","params":{"recipient_allowlist":["RECIPIENT"]}}],"reason":"test"}' + '{"modules":[{"module_id":"treasury-allowlist","params":{"allowlist":["RECIPIENT"]}}],"reason":"test"}' ``` A payment from that account to any other recipient is refused with diff --git a/docs/guides/policy-modules/built-in.toml b/docs/guides/policy-modules/built-in.toml index 0e5de1cc..30cc233b 100644 --- a/docs/guides/policy-modules/built-in.toml +++ b/docs/guides/policy-modules/built-in.toml @@ -1,11 +1,12 @@ -# Built-in modules: basic-policy runs inside the Guardian process. +# Built-in policies run inside the Guardian process: spending-limit, recipient-policy, +# signer-policy and code-policy, one concern each. # Copy to .guardian/built-in.toml and replace the placeholders. # `params` seed the global params on first start; change them later through the operator API. # Spending cap for every account: at most 5 base units of one asset per transaction. [[module]] id = "caps" -kind = "basic-policy" +kind = "spending-limit" scope = "all" hooks = ["before_proposal_created", "before_transaction_approved"] timeout_ms = 50 @@ -13,48 +14,48 @@ on_error = "deny" operator_can_disable = true disclosure = "params" description = "At most 5 base units of one asset per transaction" -params = { max_amount_per_tx = { "0xREPLACE_WITH_FAUCET_ID" = "5" } } +params = { max_per_transaction = { "0xREPLACE_WITH_FAUCET_ID" = "5" } } # Recipient blocklist for every account; extend it globally or per account at runtime. # Generic denials: clients learn that a policy refused, not which list or why. [[module]] id = "blocklist" -kind = "basic-policy" +kind = "recipient-policy" scope = "all" hooks = ["before_proposal_created", "before_transaction_approved"] timeout_ms = 50 on_error = "deny" operator_can_disable = true client_reason = "generic" -params = { recipient_denylist = [] } +params = { denylist = [] } # Signer rule: no account may add this signer. Protected: operators cannot disable it. [[module]] id = "signers" -kind = "basic-policy" +kind = "signer-policy" scope = "all" hooks = ["before_account_registered", "before_proposal_created", "before_transaction_approved"] timeout_ms = 50 on_error = "deny" -params = { signer_check = "added", signer_denylist = ["0xdededededededededededededededededededededededededededededededede"] } +params = { check = "added", denylist = ["0xdededededededededededededededededededededededededededededededede"] } # Code pinning (uncomment after reviewing the account code you accept): an account must # register with a listed code commitment, and a transaction that replaces its code must -# replace it with listed code. With code_check = "all", every gate hook checks the code the +# replace it with listed code. With check = "all", every gate hook checks the code the # account runs, so an account on unlisted code can only upgrade. # [[module]] # id = "reviewed-code" -# kind = "basic-policy" +# kind = "code-policy" # scope = "all" # hooks = ["before_account_registered", "before_proposal_created", "before_transaction_approved"] # timeout_ms = 50 # on_error = "deny" -# params = { code_check = "changed", allowed_code_commitments = ["0xREPLACE_WITH_REVIEWED_CODE_COMMITMENT"] } +# params = { check = "changed", allowed = ["0xREPLACE_WITH_REVIEWED_CODE_COMMITMENT"] } # Opt-in module: applies only to accounts an operator assigns it to, with their own params. [[module]] id = "treasury-allowlist" -kind = "basic-policy" +kind = "recipient-policy" scope = "assigned" hooks = ["before_proposal_created", "before_transaction_approved"] timeout_ms = 50 diff --git a/docs/guides/policy-modules/custom.md b/docs/guides/policy-modules/custom.md index 3f924531..92099aff 100644 --- a/docs/guides/policy-modules/custom.md +++ b/docs/guides/policy-modules/custom.md @@ -3,7 +3,7 @@ Write your own module against `guardian-module-sdk`, then either serve it over gRPC or compile it into your own server build. The worked example, [`note_policy/mod.rs`](../../../crates/guardian-module-sdk/examples/note_policy/mod.rs), -is a module `basic-policy` cannot express: it limits how many payment notes a +is a module the built-in policies cannot express: it limits how many payment notes a transaction creates and can refuse private notes, whose recipients the Guardian cannot see. The same code runs both ways. Do the [setup](./README.md#setup) first. @@ -199,8 +199,9 @@ ServerBuilder::new() ``` The factory gets each catalog instance's configuration and returns the module. -`build` fails if the kind name is already taken, including by `basic-policy` -or `grpc`. Run the example build: +`build` fails if the kind name is already taken, including by a built-in +policy (`spending-limit`, `recipient-policy`, `signer-policy`, `code-policy`) or +`grpc`. Run the example build: ```sh cp docs/guides/policy-modules/custom-in-process.toml .guardian/ @@ -270,7 +271,7 @@ module cannot judge), that one instance's token is refused for another, and that a request at the 2 MiB size cap goes through. A suite needs at least one request the module must deny: a module that allows everything answers consistently too, so consistency alone does not conform. A module written in -another language can port these cases to its own tests. `note-policy` and `basic-policy` run it in +another language can port these cases to its own tests. `note-policy` and the four built-in policies run it in [`tests/conformance.rs`](../../../crates/guardian-module-sdk/tests/conformance.rs). ## Shipping your module diff --git a/docs/guides/policy-modules/remote.md b/docs/guides/policy-modules/remote.md index 80865270..287931da 100644 --- a/docs/guides/policy-modules/remote.md +++ b/docs/guides/policy-modules/remote.md @@ -4,9 +4,9 @@ A remote module is its own service that implements the `GuardianModule` gRPC API from [`guardian_module_v1.proto`](../../../crates/guardian-module-sdk/proto/guardian_module_v1.proto). The Guardian finds it through the catalog's `endpoint`, and the module -describes itself when the Guardian asks. This page runs `basic-policy` as a -remote service, so the only difference from the [built-in](./built-in.md) page -is the transport. Do the [setup](./README.md#setup) first; the catalog is +describes itself when the Guardian asks. This page runs the built-in +`spending-limit` policy as a remote service, so the only difference from the +[built-in](./built-in.md) page is the transport. Do the [setup](./README.md#setup) first; the catalog is [`remote.toml`](./remote.toml). ## How the Guardian talks to it @@ -35,12 +35,13 @@ call: ```sh (umask 077; openssl rand -hex 32 > .guardian/caps.token) -cargo run -p guardian-policy-module -- \ +cargo run -p guardian-policy-module -- --kind spending-limit \ --listen 127.0.0.1:7443 --instance caps-remote .guardian/caps.token ``` The module is [`examples/policy-module`](../../../examples/policy-module/README.md), -built on the SDK's serve harness. It accepts a call only for an instance id it +built on the SDK's serve harness; `--kind` picks which of the four built-in +policies it serves. It accepts a call only for an instance id it knows, with that instance's token. One process can host several instances, each with its own token: repeat `--instance`. @@ -57,7 +58,7 @@ cannot be reached stops startup. Once the instance has started here, a later start during a module outage succeeds with the instance unavailable (its accounts get `GUARDIAN_MODULE_UNAVAILABLE`, or skip it with `on_error = "allow"`) until a health probe passes its startup checks. -The log line lists `caps-remote=basic-policy `. +The log line lists `caps-remote=spending-limit `. `auth.token_secret` names a secret in the Guardian's secrets backend (see [Credentials](#credentials)); here the `file` provider reads it from @@ -68,7 +69,7 @@ The log line lists `caps-remote=basic-policy `. | Test | How | Expected | |---|---|---| | Remote refusal | Pay 4 | Refused by `caps-remote` (cap 3); the in-process `caps` (cap 5) allows it | -| Remote params | `admin PUT /modules/caps-remote/params '{"params":{"max_amount_per_tx":{"":"1"}},"reason":"test"}'`, then pay 2 | Refused; the module was not restarted | +| Remote params | `admin PUT /modules/caps-remote/params '{"params":{"max_per_transaction":{"":"1"}},"reason":"test"}'`, then pay 2 | Refused; the module was not restarted | | Module down, fail closed | Stop the module, pay 1 | `503 GUARDIAN_MODULE_UNAVAILABLE`, module `caps-remote` | | Switch it off while down | `admin POST /modules/caps-remote/disable '{"reason":"module down"}'`, pay 1 | Allowed; start the module again and `/enable` (which re-runs `Describe` and `ValidateParams`) | | Fail open | Set `on_error = "allow"`, restart the Guardian, stop the module, pay 1 | Allowed; the delta's `modules.failed_open` on the dashboard delta detail names `caps-remote` | diff --git a/docs/guides/policy-modules/remote.toml b/docs/guides/policy-modules/remote.toml index 8ccfe35b..85e6fb28 100644 --- a/docs/guides/policy-modules/remote.toml +++ b/docs/guides/policy-modules/remote.toml @@ -1,16 +1,16 @@ -# Remote module: the same basic-policy served by a separate process over gRPC. +# Remote module: the built-in spending-limit policy, served by a separate process over gRPC. # Copy to .guardian/remote.toml, put the bearer token in .guardian/caps.token (mode 0600), # and start the module before the Guardian (see remote.md). [[module]] id = "caps" -kind = "basic-policy" +kind = "spending-limit" scope = "all" hooks = ["before_proposal_created", "before_transaction_approved"] timeout_ms = 50 on_error = "deny" operator_can_disable = true -params = { max_amount_per_tx = { "0xREPLACE_WITH_FAUCET_ID" = "5" } } +params = { max_per_transaction = { "0xREPLACE_WITH_FAUCET_ID" = "5" } } # A tighter cap (3) than the in-process one (5), so refusals show which module decided. [[module]] @@ -23,7 +23,7 @@ timeout_ms = 200 on_error = "deny" operator_can_disable = true auth = { token_secret = "caps.token" } -params = { max_amount_per_tx = { "0xREPLACE_WITH_FAUCET_ID" = "3" } } +params = { max_per_transaction = { "0xREPLACE_WITH_FAUCET_ID" = "3" } } # The same module on another host, over TLS (examples/policy-module/README.md). Its token is # read from AWS Secrets Manager in the prod stage; the CA file is relative to this catalog. diff --git a/docs/rfcs/0002-guardian-modules.md b/docs/rfcs/0002-guardian-modules.md index 7b2acd62..f9714bed 100644 --- a/docs/rfcs/0002-guardian-modules.md +++ b/docs/rfcs/0002-guardian-modules.md @@ -145,7 +145,7 @@ First-party kinds, registered by the official binary (through `ServerBuilder::fr |---|---|---|---| | `grpc` | Remote | `endpoint = "grpc://host:port"` (TLS), `auth` | Calls a service implementing `guardian.module.v1.GuardianModule` | | `http` | Remote | `endpoint = "https://host[:port]"`, `auth` | Not in M2; added if operators ask for it (section 7). Same messages in the proto3 JSON mapping at `GET /v1/describe`, `POST /v1/validate-params`, `POST /v1/evaluate`, `POST /v1/notify`, `POST /v1/notify-gap`. HTTP 404 or 501 from `/v1/notify-gap` is treated like gRPC `UNIMPLEMENTED` (section 3.3) | -| `basic-policy` | In process | none | Reference policy: recipient allowlist and denylist, asset allowlist, per-transaction amount cap, signer allowlist or denylist, account code allowlist. Stateless: supports `before_transaction_approved`, `before_proposal_created` and `before_account_registered` (section 2.3). Rules and reason codes in section 3.1, "`basic-policy` rules" | +| `spending-limit`, `recipient-policy`, `signer-policy`, `code-policy` | In process | none | Reference policies, one concern each: a per-transaction amount cap per asset and an asset allowlist; a recipient allowlist or denylist; a signer allowlist or denylist; an account code allowlist. Stateless. The first two support `before_proposal_created` and `before_transaction_approved`, the other two also `before_account_registered` (section 2.3). Params, rules and reason codes in section 3.1, "Built-in policies" | Operator-registered kinds run in process (section 2.5). The proto in section 3 is the single schema for both remote kinds, so there is one schema to version. A conformance suite in `guardian-module-sdk` runs the same cases against in-process and gRPC modules (and HTTP modules once that kind ships) and asserts identical decisions. Deferring `http` keeps the first suite free of the proto3 JSON mapping rules (base64 `bytes`, decimal-string `int64`, RFC 3339 timestamps); `grpc://` endpoints already meet R3's "registered by URL". @@ -179,12 +179,12 @@ Each catalog entry: ```toml [[module]] id = "spend-cap" -kind = "basic-policy" +kind = "spending-limit" scope = "default" hooks = ["before_transaction_approved"] timeout_ms = 50 on_error = "deny" -params = { max_amount_per_tx = { "0x5e0f...c3" = "1000000" } } +params = { max_per_transaction = { "0x5e0f...c3" = "1000000" } } [[module]] id = "risk-vendor" @@ -223,7 +223,7 @@ Two rules keep `default` predictable: ```json { "modules": [ - { "module_id": "spend-cap", "params": { "max_amount_per_tx": { "0x5e0f...c3": "500000" } } } + { "module_id": "spend-cap", "params": { "max_per_transaction": { "0x5e0f...c3": "500000" } } } ], "reason": "Raise treasury cap, ticket OP-42" } @@ -235,8 +235,8 @@ Two rules keep `default` predictable: ```json { "modules": [ - { "module_id": "compliance-caps", "scope": "all", "enabled": true, "global_params": { "max_amount_per_tx": { "0x5e0f...c3": "10000" } }, "account_layer": { "max_amount_per_tx": { "0x5e0f...c3": "2000" } } }, - { "module_id": "spend-cap", "scope": "default", "enabled": true, "params": { "max_amount_per_tx": { "0x5e0f...c3": "500000" } } }, + { "module_id": "compliance-caps", "scope": "all", "enabled": true, "global_params": { "max_per_transaction": { "0x5e0f...c3": "10000" } }, "account_layer": { "max_per_transaction": { "0x5e0f...c3": "2000" } } }, + { "module_id": "spend-cap", "scope": "default", "enabled": true, "params": { "max_per_transaction": { "0x5e0f...c3": "500000" } } }, { "module_id": "legacy-risk", "scope": "assigned", "orphaned": true, "params": { "threshold": 70 } } ] } @@ -279,20 +279,20 @@ Two rules keep `default` predictable: ```toml [[module]] id = "blocklist" -kind = "basic-policy" +kind = "recipient-policy" scope = "all" hooks = ["before_proposal_created", "before_transaction_approved"] timeout_ms = 50 on_error = "deny" -params = { recipient_denylist = ["0xaaa...", "0xbbb..."] } +params = { denylist = ["0xaaa...", "0xbbb..."] } ``` ```http PUT /dashboard/modules/blocklist/params -{ "params": { "recipient_denylist": ["0xaaa...", "0xbbb...", "0xddd..."] }, "reason": "Add 0xddd, ticket OP-90" } +{ "params": { "denylist": ["0xaaa...", "0xbbb...", "0xddd..."] }, "reason": "Add 0xddd, ticket OP-90" } PUT /dashboard/accounts/0x7bfb...a1/modules/blocklist/params -{ "params": { "recipient_denylist": ["0xccc..."] }, "reason": "Customer block, ticket OP-91" } +{ "params": { "denylist": ["0xccc..."] }, "reason": "Customer block, ticket OP-91" } ``` That account is then checked against `0xaaa`, `0xbbb` and `0xddd` by the global layer and against `0xccc` by its own; every other account only against the global list. @@ -375,22 +375,22 @@ Account self-service configuration is out of scope for this revision (section 7) - **The verdict is current, not final.** For stateful modules the answer can change between creation and the ack: a window fills or resets. A proposal that passed can still be refused at the ack, and one that was refused can be created again later. Open proposals are not part of `pending`; counting them would let proposals nobody intends to execute reserve an account's budget. Two proposals that each fit the remaining budget can both be created, and the ack refuses the second. - **Disclosure.** Instances subscribed to this hook receive proposals that may never execute, which widens what a vendor sees (invariant 5). -**Example: a signer allowlist.** An operator wants every account's signers drawn from a list of vetted keys. A signer change writes public key commitments into the multisig map slot `miden::standards::auth::multisig::approver_public_keys`, and the threshold lives in `miden::standards::auth::multisig::threshold_config` (`crates/contracts/tests/auth/multisig.rs:39-40`, `crates/server/src/delta_summary/projection.rs:429`) **[READ]**. The module does not parse those slots: the Guardian decodes them into `before` and `after` (section 3.2), so `basic-policy` runs one rule at every hook. Which signers it checks is a param, because both policies are useful: +**Example: a signer allowlist.** An operator wants every account's signers drawn from a list of vetted keys. A signer change writes public key commitments into the multisig map slot `miden::standards::auth::multisig::approver_public_keys`, and the threshold lives in `miden::standards::auth::multisig::threshold_config` (`crates/contracts/tests/auth/multisig.rs:39-40`, `crates/server/src/delta_summary/projection.rs:429`) **[READ]**. The module does not parse those slots: the Guardian decodes them into `before` and `after` (section 3.2), so `signer-policy` runs one rule at every hook. Which signers it checks is a param, because both policies are useful: -- `signer_check = "added"` checks the signers `after` adds, `after.signer_commitments` minus `before.signer_commitments` (all of them at registration, where `before` is absent). Signers that predate the list are kept and do not block unrelated transactions. -- `signer_check = "all"` checks every signer in `after`, so once the list is in force an account whose current signers are not all on it can do nothing until its signers are replaced. +- `check = "added"` checks the signers `after` adds, `after.signer_commitments` minus `before.signer_commitments` (all of them at registration, where `before` is absent). Signers that predate the list are kept and do not block unrelated transactions. +- `check = "all"` checks every signer in `after`, so once the list is in force an account whose current signers are not all on it can do nothing until its signers are replaced. -Each checked signer is matched against `signer_allowlist` or `signer_denylist`. The module compares states, not the proposal type, so adding, replacing and updating signers are all covered whatever `unverified_metadata` claims. One instance subscribes to three hooks, because each closes a different path: +Each checked signer is matched against the instance's `allowlist` or `denylist`. The module compares states, not the proposal type, so adding, replacing and updating signers are all covered whatever `unverified_metadata` claims. One instance subscribes to three hooks, because each closes a different path: ```toml [[module]] -id = "signer-policy" -kind = "basic-policy" +id = "vetted-signers" +kind = "signer-policy" scope = "all" hooks = ["before_proposal_created", "before_transaction_approved", "before_account_registered"] timeout_ms = 20 on_error = "deny" -params = { signer_check = "all", signer_allowlist = ["0x…", "0x…"] } +params = { check = "all", allowlist = ["0x…", "0x…"] } ``` - `before_proposal_created` refuses the proposal before any cosigner signs it or it takes a slot. @@ -415,7 +415,7 @@ Rust code cannot be loaded into a running binary safely, so whether a module nee | Module | Official image | Guardian rebuild | |---|---|---| -| First-party in-process kinds (`basic-policy` and later first-party kinds) | Included | No; declare instances in the catalog | +| First-party in-process kinds (the four built-in policies and later first-party kinds) | Included | No; declare instances in the catalog | | Remote modules, any author and language (kind `grpc`; `http` later) | Supported | No; run the module as its own service | | Third-party or operator-written in-process kinds | Not included | Yes; custom build through `ServerBuilder` | @@ -533,7 +533,7 @@ A cosigner learns that a module refuses a transaction when the proposal is creat "account_id": "0x7bfb...a1", "policies": [ { "module_id": "recipients", "hooks": ["before_proposal_created", "before_transaction_approved"], "description": "Payments only to the treasury's approved counterparties" }, - { "module_id": "spend-cap", "hooks": ["before_transaction_approved"], "description": "At most 500,000 USDC per transaction", "params": { "max_amount_per_tx": { "0x5e0f...c3": "500000" } } } + { "module_id": "spend-cap", "hooks": ["before_transaction_approved"], "description": "At most 500,000 USDC per transaction", "params": { "max_per_transaction": { "0x5e0f...c3": "500000" } } } ] } ``` @@ -799,20 +799,20 @@ message Gap { **The fee is a note.** In Miden 0.17 `pay_fee` creates a public `TX_FEE` output note funded from the account's vault (`miden-standards-0.17.1/src/account/auth/singlesig.rs:45`) **[READ]**. Listed as an ordinary note, the fee looks like a payment: in the prototype a cap on the fee asset refused every transaction, consuming notes included, and a recipient allowlist would refuse every transaction too, since the fee note has no P2ID recipient. The Guardian therefore marks it with `OutputNote.tx_fee`, and policies treat it as the fee, not a payment. The script alone does not identify the fee: `TX_FEE` is a standard script that any transaction script can use (`tx_fee::create_output_note` is public), with any assets, and anyone can consume the note, so a note marked by its script would move funds past every recipient, asset and amount rule. `tx_fee` is set only for the note `pay_fee` creates, recognized by everything `pay_fee` fixes: it is the transaction's only `TX_FEE` note, its serial number is `TxFeeNote::derive_serial_number(account, nonce before the transaction, block the summary binds)`, and it carries one fungible asset of the chain's fee faucet, no more of it than a transaction can owe. The Guardian reads the fee faucet and the verification base fee from the node's latest block header and its protocol configuration, and reads them again once that read is a minute old. The fee is the base fee times `ilog2(cycles) + 1`, which stays below 32 for any cycle count the kernel accepts, so the bound is 64 times the base fee: a note over it is a payment. On a chain whose base fee is zero `pay_fee` creates no note, so no note is marked there; otherwise a transaction script could create the one `TX_FEE` note itself, with the derivable serial number and any amount. Any other `TX_FEE` note, and every `TX_FEE` note when the transaction has more than one, is an ordinary output note. While the fee asset has never been read, a transaction that carries a `TX_FEE`-script note cannot be projected, so each instance's `on_error` applies (`GUARDIAN_MODULE_UNAVAILABLE` for a fail-closed one) instead of the note being judged as a payment and denied for good. -#### `basic-policy` rules +#### Built-in policies -The reference kind reads only the projection and the account views. Each rule denies with a fixed `reason_code` and a fixed `client_message` that names the rule, never a list entry or a limit, so an instance with `client_reason = "full"` tells the user what to change without disclosing params the operator kept back (`disclosure`, section 2.7): +Four first-party kinds, one concern each, so an instance carries only the params of the rule it enforces, and a kind refuses params that belong to another. Each kind supports only the hooks where its rule can refuse something, so a catalog that subscribes it to another hook does not start. They read only the projection and the account views. Each rule denies with a fixed `reason_code` and a fixed `client_message` that names the rule, never a list entry or a limit, so an instance with `client_reason = "full"` tells the user what to change without disclosing params the operator kept back (`disclosure`, section 2.7): -| Param | Rule | `reason_code` | -|---|---|---| -| `recipient_allowlist` | Every payment note's `p2id_target` is listed. A partial note, or one whose script is not a known P2ID or P2IDE script (no `p2id_target`), is refused, since its recipient cannot be checked | `recipient_not_allowed` | -| `recipient_denylist` | No payment note's `p2id_target` is listed. A partial or non-P2ID note is refused as well once the list names anyone, since a blocked recipient could otherwise be paid through a note the denylist cannot check; `deny_unknown_recipients = false` opts out, and `true` applies it to an empty list too | `recipient_blocked` | -| `asset_allowlist` | Every asset sent in a payment note or received in an input note is listed; vault changes are not used, because they cannot tell a fee from a payment | `asset_not_allowed` | -| `max_amount_per_tx` | Per listed faucet, the gross amount leaving the account (the sum of that faucet's fungible amounts over every output note, full or partial) is at most the cap. Amounts of different assets are not comparable, so the cap is per asset; input notes do not offset it, so a payment cannot be split across notes or netted against a receive; faucets not listed are uncapped; non-fungible assets are governed only by `asset_allowlist` | `amount_cap_exceeded` | -| `signer_allowlist` or `signer_denylist`, with `signer_check` | The checked signers (section 2.3, signer allowlist example) are all on the allowlist, or none is on the denylist; an instance sets at most one of the two | `signer_not_allowed` | -| `allowed_code_commitments`, with `code_check` | `code_check = "changed"` (default): at registration `after.code_commitment` is listed, and on a transaction `new_code_commitment`, when set, is listed. Code an account already runs is kept until it changes, as `signer_check = "added"` keeps signers: an account registered before the instance existed passes until it replaces its code or re-registers. `code_check = "all"`: `after.code_commitment` is listed at every gate hook, so once the list is in force an account on unlisted code can do nothing but upgrade to listed code. Pins the account to code the operator has reviewed (invariant 6) | `code_not_allowed` | +| Kind (hooks) | Param | Rule | `reason_code` | +|---|---|---|---| +| `spending-limit` (proposal creation, transaction approval) | `max_per_transaction` | Per listed faucet, the gross amount leaving the account (the sum of that faucet's fungible amounts over every output note, full or partial) is at most the cap. Amounts of different assets are not comparable, so the cap is per asset; input notes do not offset it, so a payment cannot be split across notes or netted against a receive; faucets not listed are uncapped; non-fungible assets are governed only by `allowed_assets`. Limits over a period need module state (M2b) and belong to this kind | `amount_cap_exceeded` | +| | `allowed_assets` | Every asset sent in a payment note or received in an input note is listed; vault changes are not used, because they cannot tell a fee from a payment | `asset_not_allowed` | +| `recipient-policy` (proposal creation, transaction approval) | `allowlist` | Every payment note's `p2id_target` is listed. A partial note, or one whose script is not a known P2ID or P2IDE script (no `p2id_target`), is refused, since its recipient cannot be checked. Excludes `denylist` | `recipient_not_allowed` | +| | `denylist`, with `deny_unknown` | No payment note's `p2id_target` is listed. A partial or non-P2ID note is refused as well once the list names anyone, since a blocked recipient could otherwise be paid through a note the denylist cannot check; `deny_unknown = false` opts out, and `true` applies it to an empty list too | `recipient_blocked` | +| `signer-policy` (registration, proposal creation, transaction approval) | `allowlist` or `denylist`, with `check` | The checked signers (section 2.3, signer allowlist example) are all on the allowlist, or none is on the denylist; an instance sets at most one of the two | `signer_not_allowed` | +| `code-policy` (registration, proposal creation, transaction approval) | `allowed`, with `check` | `check = "changed"` (default): at registration `after.code_commitment` is listed, and on a transaction `new_code_commitment`, when set, is listed. Code an account already runs is kept until it changes, as `check = "added"` keeps signers: an account registered before the instance existed passes until it replaces its code or re-registers. `check = "all"`: `after.code_commitment` is listed at every gate hook, so once the list is in force an account on unlisted code can do nothing but upgrade to listed code. Pins the account to code the operator has reviewed (invariant 6) | `code_not_allowed` | -The fee note (`tx_fee`) is excluded from every recipient, asset and amount rule. At `before_account_registered` there is no transaction, so only the signer and code rules apply; the transaction rules pass. A transaction request without a Miden projection is not judged: the module returns an error, as for any transaction it cannot judge (section 3.1), so the instance's `on_error` applies. +The fee note (`tx_fee`) is excluded from every recipient, asset and amount rule. A request a kind cannot judge, such as a transaction without a Miden projection, is not judged: the module returns an error, as for any transaction it cannot judge (section 3.1), so the instance's `on_error` applies. ### 3.2 Account views and proposal context @@ -1037,7 +1037,7 @@ The health probe is a `Describe` call every `GUARDIAN_MODULE_PROBE_INTERVAL_MS` 3. **Exit is never gated.** `SwitchGuardian` executes on chain without a Guardian acknowledgement, so no module can keep an account from leaving. A module may deny the best-effort push of the switch delta to the old Guardian; the release sweep then detects the switch from chain. 4. **Structure is reviewed, parameters are audited.** Only the catalog file, applied by a deploy, adds, removes or reconfigures module instances (kind, endpoint, authentication, TLS, hooks, scope, timeout, `on_error`), so no session can point the approval path or transaction data at a new destination. Params are operator-managed: operator sessions change global params (`policies:write_global`), account layers and per-account assignments, every change with a reason, an audit record and a history entry. Loosening a rule through params is an operator decision the audit trail records, not something the Guardian prevents; what it does prevent is a per-account change weakening an `all` rule, since an account layer only adds restrictions. `scope = all` instances cannot be removed from an account, only instances the catalog marks `operator_can_disable` can be disabled, and resync accepts dropped history explicitly. 5. **Disclosure.** Every external module receives the full transaction details of each account it applies to, including, for instances subscribed to `before_proposal_created` and for every instance a dry-run check reaches, transactions that are never executed, and the proposer's free-text `description` in `unverified_metadata`. This is a change to the trust boundary in `docs/CONCEPTS.md` and operators must treat module vendors as data processors. The operator and module author guides (section 7) say which request fields can carry personal data, ask vendors to document retention and processing location, and note that the Guardian's own logs hold the module's `message` for every denial. -6. **A verdict assumes the account's code.** Modules judge the transaction and the account views; the account's code decides whether the Guardian's signature is required at all. The Guardian does not verify that code (section 3.2), so an operator who relies on module verdicts as a custody control pins the code with a module, through `code_commitment` at registration and `new_code_commitment` on every transaction. `basic-policy` does this with `allowed_code_commitments` (section 3.1); `code_check = "all"` also covers accounts registered before the rule existed. Without such a rule, a code upgrade can remove the Guardian requirement from an account and no module runs for it again. +6. **A verdict assumes the account's code.** Modules judge the transaction and the account views; the account's code decides whether the Guardian's signature is required at all. The Guardian does not verify that code (section 3.2), so an operator who relies on module verdicts as a custody control pins the code with a module, through `code_commitment` at registration and `new_code_commitment` on every transaction. `code-policy` does this with `allowed` (section 3.1); `check = "all"` also covers accounts registered before the rule existed. Without such a rule, a code upgrade can remove the Guardian requirement from an account and no module runs for it again. ### 5.2 Transport authentication @@ -1105,7 +1105,7 @@ The first enclave step allows in-process kinds only; the attested tier follows o - Evaluation budget (`GUARDIAN_MODULE_EVALUATION_BUDGET_MS`) with the startup checks in section 4.3, circuit breaker and health probe (section 4.4), request size cap (section 3.4), and the module metrics. - `GUARDIAN_MODULE_DENIED` and `GUARDIAN_MODULE_UNAVAILABLE` in the server and both SDKs, on proposal creation as well as on the ack. - Policy discovery (section 2.7): the `disclosure`, `description`, `client_reason` and `dry_run` catalog fields, generic denials, `Decision.client_message`, the policy summary and dry-run check on the client API with their rate limit, and the SDK methods named in section 2.7 in both base clients and both multisig SDKs. The error contract and the protocol field must land before version 1 freezes; the two endpoints may follow in an M2a point release. -- Reference module `basic-policy` (recipient allowlist and denylist, asset allowlist, per-transaction amount cap, signer allowlist or denylist with `signer_check`, account code allowlist), shipped as a first-party in-process kind and, through the `serve` harness, as a standalone gRPC service in `examples/policy-module/`. +- Reference policies `spending-limit`, `recipient-policy`, `signer-policy` and `code-policy` (per-transaction amount cap and asset allowlist; recipient allowlist or denylist; signer allowlist or denylist; account code allowlist), shipped as first-party in-process kinds and, through the `serve` harness, as a standalone gRPC service in `examples/policy-module/`. - Account view extraction with explicit errors for unsupported auth state, effective procedure overrides, code commitment and procedure roots; `network_id`, `reference_block` and `new_code_commitment` in the projection (section 3.1); `submitter_session` (section 3.2); the params size cap (section 2.2); the `ProposalContext` lookup, first-creator-wins proposal storage on both backends (on `main`, `admit_delta_proposal` refuses an existing commitment on both), and the requester carried from the execution request to the ack (section 3.2). - Acceptance cases: a denial at proposal creation stores nothing and takes no slot; a proposal that passes creation and is denied at the ack; a transaction signed offline and pushed without a stored proposal is enforced at the ack; forged `unverified_metadata` does not change a decision; a failed account view extraction applies `on_error`. Creation denials are exercised through `guardian-client` (Rust and TypeScript) and both multisig SDKs. - Docs: configuration, trust boundary in concepts, troubleshooting codes (including the denial log fields, section 2.2), the break-glass runbook (section 4.2), data-protection guidance for operators and vendors (invariant 5), and a module author guide for remote modules. @@ -1205,7 +1205,7 @@ None. Questions resolved in earlier revisions are kept below with their answers. | Revision | Date | Changes | |---|---|---| -| 32 | 2026-11-10 | review of the M2a implementation. Protocol version 1 reopened (section 7): `Decision.allow` and the `decision.effect` capability removed, a decision without an effect is a module failure (section 3.5); `MidenTransaction.reference_block` and `expiration_block` replaced by `bound_block`, `expiration_delta` and `approval_expiration_block`, and `nonce_delta` made unsigned (section 3.1); `network_id` is the Guardian's configured network, not the account's registered one (section 3.1); `RegistrationSubject.initial_state` is sent; `tx_fee` is set only while the fee note carries no more of the fee asset than a transaction can owe, 64 times the chain's verification base fee, and for no note on a chain that charges nothing (section 3.1). Breaker: requests a module rejects do not count, a module whose timeout is the whole budget can open it, half-open sends one trial at a time, dry-run checks neither probe nor close it (section 4.4). Fail-open skips at proposal creation and registration, where no delta is signed, are recorded as `modules.failed_open` audit events; operator writes are audited with the params version they committed as (section 2.2). A health probe that finds a module incompatible opens its breaker at once and one that gets no answer counts as a failed call (section 4.4). Startup: a known instance whose module does not answer starts unavailable instead of stopping the server, and an instance the catalog declares enabled and not operator-disableable is enabled even when stored as disabled (section 2.2). `basic-policy`: per-field id lengths, and `deny_unknown_recipients` defaults to on once the denylist names anyone (section 3.1). The conformance suite checks stated outcomes and needs a request the module must deny. Body corrected to the implementation: metric names, the fixed 1000 ms timeout cap, params encoding, the `circuit_open` failure kind | +| 32 | 2026-11-10 | review of the M2a implementation. Protocol version 1 reopened (section 7): `Decision.allow` and the `decision.effect` capability removed, a decision without an effect is a module failure (section 3.5); `MidenTransaction.reference_block` and `expiration_block` replaced by `bound_block`, `expiration_delta` and `approval_expiration_block`, and `nonce_delta` made unsigned (section 3.1); `network_id` is the Guardian's configured network, not the account's registered one (section 3.1); `RegistrationSubject.initial_state` is sent; `tx_fee` is set only while the fee note carries no more of the fee asset than a transaction can owe, 64 times the chain's verification base fee, and for no note on a chain that charges nothing (section 3.1). Breaker: requests a module rejects do not count, a module whose timeout is the whole budget can open it, half-open sends one trial at a time, dry-run checks neither probe nor close it (section 4.4). Fail-open skips at proposal creation and registration, where no delta is signed, are recorded as `modules.failed_open` audit events; operator writes are audited with the params version they committed as (section 2.2). A health probe that finds a module incompatible opens its breaker at once and one that gets no answer counts as a failed call (section 4.4). Startup: a known instance whose module does not answer starts unavailable instead of stopping the server, and an instance the catalog declares enabled and not operator-disableable is enabled even when stored as disabled (section 2.2). `basic-policy`: per-field id lengths, and `deny_unknown_recipients` defaults to on once the denylist names anyone (section 3.1). The conformance suite checks stated outcomes and needs a request the module must deny. `basic-policy` is split into four kinds with short param names: `spending-limit` (`max_per_transaction`, `allowed_assets`), `recipient-policy` (`allowlist`, `denylist`, `deny_unknown`), `signer-policy` (`allowlist`, `denylist`, `check`) and `code-policy` (`allowed`, `check`), each supporting only the hooks where its rule can refuse (section 3.1). Body corrected to the implementation: metric names, the fixed 1000 ms timeout cap, params encoding, the `circuit_open` failure kind | | 31 | 2026-11-09 | failures of dry-run checks do not count toward the circuit breaker, since a cosigner sends them without anyone's signature (section 4.4); the per-account budget check refuses only writes that raise an over-budget cost (section 4.3); `GUARDIAN_MODULE_UNAVAILABLE` and `GUARDIAN_EXECUTION_MODULE_UNAVAILABLE` omit `module` for an instance whose denials are generic (section 4.1); `metadata.modules` is kept out of client delta responses (section 2.2). `OutputNote.tx_fee` set only for the fee note `pay_fee` creates (section 3.1): the only `TX_FEE` note, with the derived serial number and one asset of the chain's fee faucet. Revisions 20 to 30 set it for any note with the `TX_FEE` script, which a transaction script can create with any assets, so the flag let funds past every `basic-policy` rule. No wire change; the field's meaning is narrowed | | 30 | 2026-11-09 | the secrets backend named: `GUARDIAN_MODULE_SECRET_PROVIDER` selects AWS Secrets Manager (the prod default) or owner-only files below `GUARDIAN_MODULE_SECRET_DIR`, read once when the instances are created; a secret that cannot be read fails creation, with the enabled/disabled rule of section 2.2. Field names fixed as `auth.token_secret`, `tls.client_cert_secret` and `tls.client_key_secret`; a secret name is 1 to 512 characters of letters, digits and `/_+=.@-`, and a `$secret` object has no other key (section 2.2). In-process factories read `$secret` values from `ModuleInstanceConfig::secret`. No protocol change | | 29 | 2026-11-09 | M2a implementation of `scope = default`: the copy is written right after the claim, only into an account with no assignment and no assignment history, under the module state lock, instead of in the claim's transaction on Postgres and before the claim on the filesystem; a crash in between is repaired by the unfinished-claim retry, so both backends follow one rule and no transaction spans the metadata and module stores (section 2.3). No protocol change | diff --git a/examples/README.md b/examples/README.md index 954cbc0a..2c8302a6 100644 --- a/examples/README.md +++ b/examples/README.md @@ -4,7 +4,7 @@ Small projects that showcase different ways to interact with Guardian: - [`demo/`](./demo/) – Terminal UI for hands-on experimentation (recommended starting point). - [`operator-smoke-web/`](./operator-smoke-web/) – Minimal browser UI for local Falcon operator login and account API calls through `@openzeppelin/guardian-operator-client`. -- [`policy-module/`](./policy-module/): `basic-policy` as a standalone policy module served over gRPC (TLS, per-instance tokens, Dockerfile), for the remote module guide. +- [`policy-module/`](./policy-module/): the built-in policies as a standalone policy module served over gRPC (TLS, per-instance tokens, Dockerfile), for the remote module guide. - [`rust/`](./rust/) – Low-level Rust example with binaries for both local-node and mockchain flows. - [`smoke-web/`](./smoke-web/) – Browser smoke harness for multisig workflows and wallet integrations. diff --git a/examples/policy-module/README.md b/examples/policy-module/README.md index 7216840c..0a9ac2bc 100644 --- a/examples/policy-module/README.md +++ b/examples/policy-module/README.md @@ -1,10 +1,11 @@ # Policy module example -`basic-policy`, the Guardian's built-in policy kind, served as its own process -over gRPC through the `serve` harness of +One of the Guardian's built-in policies (`spending-limit`, `recipient-policy`, +`signer-policy` or `code-policy`, chosen with `--kind`) served as its own +process over gRPC through the `serve` harness of [`guardian-module-sdk`](../../crates/guardian-module-sdk). Use it to try a -remote module, or as the starting point for one: replace `BasicPolicy` with -your own `Module`. +remote module, or as the starting point for one: replace the policy with your +own `Module`. The Guardian side is a catalog entry of kind `grpc`; see the [remote module guide](../../docs/guides/policy-modules/remote.md) and its @@ -19,7 +20,7 @@ with, carrying that instance's token. ```sh mkdir -p .guardian (umask 077; openssl rand -hex 32 > .guardian/caps.token) -cargo run -p guardian-policy-module -- \ +cargo run -p guardian-policy-module -- --kind spending-limit \ --listen 127.0.0.1:7443 --instance caps-remote .guardian/caps.token ``` @@ -36,7 +37,7 @@ stage. The module refuses a plain-text listener on any other address unless `--insecure` is given. ```sh -policy-module --listen 0.0.0.0:7443 \ +policy-module --kind spending-limit --listen 0.0.0.0:7443 \ --instance caps-remote /run/secrets/caps.token \ --tls-cert /run/secrets/module.pem --tls-key /run/secrets/module.key ``` @@ -56,7 +57,7 @@ Build from the repository root: ```sh docker build -f examples/policy-module/Dockerfile -t guardian-policy-module . docker run --rm -p 7443:7443 -v "$PWD/secrets:/run/secrets:ro" guardian-policy-module \ - --listen 0.0.0.0:7443 \ + --kind spending-limit --listen 0.0.0.0:7443 \ --instance caps-remote /run/secrets/caps.token \ --tls-cert /run/secrets/module.pem --tls-key /run/secrets/module.key ``` @@ -68,6 +69,6 @@ must be readable by it. The SDK's conformance suite runs a module in process and over gRPC and checks that both give the same answers, that `evaluate` has no side effects, and that -a request at the Guardian's size cap goes through. `basic-policy` runs it in +a request at the Guardian's size cap goes through. The built-in policies run it in [`crates/guardian-module-sdk/tests/conformance.rs`](../../crates/guardian-module-sdk/tests/conformance.rs); the same `Suite` works for your own module with the `conformance` feature. diff --git a/packages/guardian-operator-client/README.md b/packages/guardian-operator-client/README.md index af571ae0..8b5dbc9f 100644 --- a/packages/guardian-operator-client/README.md +++ b/packages/guardian-operator-client/README.md @@ -300,8 +300,8 @@ const catalog = await client.listModules(); // catalog.modules: [{ moduleId, scope, enabled, circuit, params, paramsDrift, ... }] // catalog.undeclared: stored instances the catalog no longer declares -await client.setModuleGlobalParams('blocklist', { recipient_denylist: ['0x0a1b2c3d4e5f60718293a4b5c6d7e8'] }, 'OP-90'); // policies:write_global -await client.setAccountModuleLayer(accountId, 'blocklist', { recipient_denylist: ['0x1c2d3e4f5a6b70819203b4c5d6e7f8'] }, 'OP-91'); // policies:write +await client.setModuleGlobalParams('blocklist', { denylist: ['0x0a1b2c3d4e5f60718293a4b5c6d7e8'] }, 'OP-90'); // policies:write_global +await client.setAccountModuleLayer(accountId, 'blocklist', { denylist: ['0x1c2d3e4f5a6b70819203b4c5d6e7f8'] }, 'OP-91'); // policies:write await client.removeAccountModuleLayer(accountId, 'blocklist', 'OP-92'); await client.setAccountModules(accountId, [{ moduleId: 'treasury-allowlist', params: {} }], 'OP-93'); await client.disableModule('risk-scorer', 'incident'); // policies:write or modules:disable diff --git a/speckit/features/251-guardian-modules/contracts/catalog-config.md b/speckit/features/251-guardian-modules/contracts/catalog-config.md index d661f14a..880c2125 100644 --- a/speckit/features/251-guardian-modules/contracts/catalog-config.md +++ b/speckit/features/251-guardian-modules/contracts/catalog-config.md @@ -22,14 +22,14 @@ ```toml [[module]] id = "signer-policy" # required, unique -kind = "basic-policy" # required, registered kind +kind = "signer-policy" # required, registered kind scope = "all" # all | default | assigned hooks = ["before_proposal_created", "before_transaction_approved", "before_account_registered"] timeout_ms = 20 # required on_error = "deny" # deny (default) | allow enabled = true # seed only operator_can_disable = false -params = { signer_check = "all", signer_allowlist = ["0x…"] } # seed for the global params +params = { check = "all", allowlist = ["0x…"] } # seed for the global params [[module]] id = "risk-vendor" @@ -74,23 +74,23 @@ A secret that cannot be read fails the instance's creation: startup stops for an ## Kinds -`basic-policy` (in process) and `grpc` (remote) ship with the Guardian. A custom build registers more in-process kinds with `ServerBuilder::with_module_kind(name, factory)` (M2c, prototyped in #554); a catalog entry names one in `kind`, with no `endpoint`. A kind name is taken once, and the first-party names cannot be replaced. The stock binary refuses a catalog that names a kind it does not know. +Four in-process policies (`spending-limit`, `recipient-policy`, `signer-policy`, `code-policy`) and `grpc` (remote) ship with the Guardian. A custom build registers more in-process kinds with `ServerBuilder::with_module_kind(name, factory)` (M2c, prototyped in #554); a catalog entry names one in `kind`, with no `endpoint`. A kind name is taken once, and the first-party names cannot be replaced. The stock binary refuses a catalog that names a kind it does not know. -## `basic-policy` params (M2a) +## Built-in policy params -Every id is written in `0x` hex form (case-insensitive); `validate_params` refuses any other form, such as a bech32 address or a placeholder that is not hex digits, which would never match a request, and an id of the wrong length (30 hex digits for a faucet or recipient, 64 for a signer or code commitment). A modifier without the list it modifies (`deny_unknown_recipients`, `signer_check`, `code_check`) and a cap naming one faucet twice are refused too. +Every id is written in `0x` hex form (case-insensitive) at its kind's length (30 hex digits for a faucet or recipient, 64 for a signer or code commitment); `validate_params` refuses any other form, such as a bech32 address or a placeholder. A kind refuses fields that belong to another, a modifier without the list it modifies, and a cap naming one faucet twice. A kind supports only the hooks listed, and startup refuses an instance subscribed to another. -| Param | Type | Effect | -|---|---|---| -| `max_amount_per_tx` | map faucet id to decimal string | For each listed faucet, deny if the gross amount sent exceeds it: the sum of that faucet's fungible amounts over every output note, full or partial. Input notes consumed in the same transaction do not offset it, the fee note (`tx_fee`) is not counted, faucets not listed are uncapped, non-fungible assets are not counted (use `asset_allowlist`) | -| `recipient_allowlist` | list of account ids | Deny a payment note whose `p2id_target` is not listed; partial or non-P2ID notes deny | -| `recipient_denylist` | list of account ids | Deny a payment note whose `p2id_target` is listed | -| `deny_unknown_recipients` | bool; unset, `true` when `recipient_denylist` is not empty | With `recipient_denylist`, also deny partial and non-P2ID payment notes, whose recipient cannot be checked | -| `asset_allowlist` | list of faucet ids | Deny an unlisted faucet among assets sent in payment notes or received in input notes; the fee note (`tx_fee`) is not checked | -| `signer_allowlist` / `signer_denylist` | list of signer commitments | Check signers per `signer_check`; at most one of the two | -| `signer_check` | `added` (default) or `all` | `added`: signers in `after` not in `before`; `all`: every signer in `after` | -| `allowed_code_commitments` | list of code commitments | Code allowlist, checked per `code_check` | -| `code_check` | `changed` (default) or `all` | `changed`: `after.code_commitment` at registration and `new_code_commitment` when a transaction replaces code; `all`: `after.code_commitment` at every gate hook | +| Kind | Param | Type | Effect | +|---|---|---|---| +| `spending-limit` (proposal, transaction) | `max_per_transaction` | map faucet id to decimal string | For each listed faucet, deny if the gross amount the transaction's payment notes send exceeds it; the fee note (`tx_fee`) is not a payment | +| | `allowed_assets` | list of faucet ids | Deny an unlisted faucet among assets sent in payment notes or received in input notes | +| `recipient-policy` (proposal, transaction) | `allowlist` | list of account ids | Deny a payment note whose `p2id_target` is not listed; partial or non-P2ID notes deny. Excludes `denylist` | +| | `denylist` | list of account ids | Deny a payment note whose `p2id_target` is listed. Excludes `allowlist` | +| | `deny_unknown` | bool; unset, `true` when `denylist` is not empty | With `denylist`, also deny partial and non-P2ID payment notes, whose recipient cannot be checked | +| `signer-policy` (registration, proposal, transaction) | `allowlist` / `denylist` | list of signer commitments | Check signers per `check`; at most one of the two | +| | `check` | `added` (default) or `all` | `added`: signers in `after` not in `before`; `all`: every signer in `after` | +| `code-policy` (registration, proposal, transaction) | `allowed` | list of code commitments | Code allowlist, checked per `check` | +| | `check` | `changed` (default) or `all` | `changed`: `after.code_commitment` at registration and `new_code_commitment` when a transaction replaces code; `all`: `after.code_commitment` at every hook | `params` in the file seed the global params once (section "Layered parameters" of RFC 0002 section 2.2); afterwards they are changed through the operator API, and a changed file value is reported as drift. Per-account settings never live in this file. diff --git a/speckit/features/251-guardian-modules/quickstart.md b/speckit/features/251-guardian-modules/quickstart.md index 410a1cc0..8e8f5d9d 100644 --- a/speckit/features/251-guardian-modules/quickstart.md +++ b/speckit/features/251-guardian-modules/quickstart.md @@ -9,13 +9,22 @@ How to see the feature working locally and which checks prove each slice. Comman ```bash cat > /tmp/modules.toml <<'EOF' [[module]] -id = "caps-and-signers" -kind = "basic-policy" +id = "caps" +kind = "spending-limit" +scope = "all" +hooks = ["before_proposal_created", "before_transaction_approved"] +timeout_ms = 20 +on_error = "deny" +params = { max_per_transaction = { "0x" = "1000" } } + +[[module]] +id = "signers" +kind = "signer-policy" scope = "all" hooks = ["before_proposal_created", "before_transaction_approved", "before_account_registered"] timeout_ms = 20 on_error = "deny" -params = { max_amount_per_tx = { "0x" = "1000" }, signer_check = "added", signer_allowlist = ["0x", "0x"] } +params = { check = "added", allowlist = ["0x", "0x"] } EOF GUARDIAN_MODULES_CONFIG=/tmp/modules.toml cargo run -p guardian-server --bin server @@ -71,8 +80,8 @@ GUARDIAN_OPERATOR_PUBLIC_KEYS_FILE=.guardian/operators.json \ ADMIN="cargo run -q -p guardian-server --example modules_admin -- --key .guardian/operator.key" $ADMIN GET /modules -$ADMIN PUT /modules/blocklist/params '{"params":{"recipient_denylist":["0x","0x"]},"reason":"extend global list"}' -$ADMIN PUT /accounts/0xACCOUNT/modules/blocklist/params '{"params":{"recipient_denylist":["0x"]},"reason":"customer block"}' +$ADMIN PUT /modules/blocklist/params '{"params":{"denylist":["0x","0x"]},"reason":"extend global list"}' +$ADMIN PUT /accounts/0xACCOUNT/modules/blocklist/params '{"params":{"denylist":["0x"]},"reason":"customer block"}' $ADMIN GET /accounts/0xACCOUNT/modules $ADMIN GET /modules/blocklist/params/history $ADMIN DELETE /accounts/0xACCOUNT/modules/blocklist/params '{"reason":"lift customer block"}' diff --git a/speckit/features/251-guardian-modules/tasks.md b/speckit/features/251-guardian-modules/tasks.md index 4e0da31a..1d5a65ae 100644 --- a/speckit/features/251-guardian-modules/tasks.md +++ b/speckit/features/251-guardian-modules/tasks.md @@ -104,7 +104,7 @@ ### Implementation for User Story 3 - [X] T024 [US3] Registration per RFC section 2.3 "Registration" in `crates/server/src/services/configure_account.rs`: for a lost claim, re-plan and re-run the pipeline against the winning account (unfinished claim or existing account) before `consume_auth_timestamp`; keep the hook before the claim (P0 T085) -- [X] T025 [US3] `basic-policy` `allowed_code_commitments` with `code_check` (`changed` or `current`, reason code `code_not_allowed`) in `crates/guardian-module-sdk/src/basic_policy.rs`, reading `AccountView.code_commitment` and `MidenTransaction.new_code_commitment`; params validation and tests at registration and at code replacement (P0 T093) +- [X] T025 [US3] `basic-policy` `allowed_code_commitments` with `code_check` (`changed` or `all`, reason code `code_not_allowed`) in `crates/guardian-module-sdk/src/basic_policy.rs`, reading `AccountView.code_commitment` and `MidenTransaction.new_code_commitment`; params validation and tests at registration and at code replacement (P0 T093) - [X] T026 [US3] Document the code allowlist and signer modes in `docs/guides/policy-modules/built-in.md` and its `built-in.toml` **Checkpoint**: US3 acceptance scenarios 1 to 5 pass, and the code allowlist is in `basic-policy`. @@ -196,7 +196,7 @@ - [X] T057 Rust and TypeScript parity fixture: one shared JSON fixture of module error bodies under `packages/guardian-client/src/` (or the repo's existing shared fixture location) driving both `crates/client` and `packages/guardian-client` tests, so SC-010 is checked by the same cases - [ ] T058 (operator module routes done 2026-11-09 through `modules_admin`: validation, `$secret` refusal, `modules:disable` allowed and the 403/409/404 paths, history; the SDK, demo/web and browser smokes still open) End-to-end smokes with a catalog: `smoke-test-rust-multisig-sdk` and `smoke-test-ts-multisig-sdk` skills, refusal at creation, push and registration, and `examples/demo` and `examples/web` with and without a catalog (quickstart section 5); and the operator module routes, including `modules:disable` permission errors, through `examples/operator-smoke-web` with the `smoke-test-operator-dashboard` skill - [ ] T059 (latency A/B done 2026-11-09, see research.md "M2a end to end"; walk-through against a 0.17 local node still open) Quickstart walk-through against a local node with the filesystem backend and the latency A/B (zero, one in-process, one remote module), results in `speckit/features/251-guardian-modules/research.md` (P0 T033; SC-001, SC-006) -- [ ] T060 SC-004 run: enable `basic-policy` on all accounts with the official image and the guides only, timed, gaps fixed in `docs/guides/policy-modules/` +- [ ] T060 SC-004 run: enable the built-in policies (`spending-limit`, `recipient-policy`, `signer-policy`, `code-policy`; `basic-policy` until 2026-11-10) on all accounts with the official image and the guides only, timed, gaps fixed in `docs/guides/policy-modules/` - [X] T061 Re-check the TLA+ models whose fingerprints the modules work moved (`verify-auth-replay`, `verify-candidate-queue`, `verify-client-sync`, `verify-guardian-switch`, `verify-module-counting`, `verify-multisig-push-gate`, `verify-proposal-lifecycle` under `.agents/skills/`) with each `check.sh`, then `--accept-drift` once the model still mirrors the code - [X] T062 (2026-11-09: checks, OpenAPI, 1,729 server tests with --test-threads 4, 96 Postgres tests, Rust clients, TS 172/118/1001, terraform validate) Validation matrix of `speckit/features/251-guardian-modules/quickstart.md` section 5 (M2a rows) run end to end, including `cargo test -p guardian-server --features postgres` for module stores and proposal storage, and `gen-openapi --check` - [X] T063 Export the `guardian_module_*` metrics: add them to the CloudWatch export allowlist in `infra/observability.tf` (selector groups by label dimensions) and a "Policy modules" section of panels in `docs/guides/observability/grafana/dashboards/guardian.json`, listed in `docs/guides/observability/README.md`; validate with `terraform validate` and the local Prometheus and Grafana stack From cfe5ea6865b95174dc46c5b12cbf120a27572648 Mon Sep 17 00:00:00 2001 From: Zeljko Date: Tue, 10 Nov 2026 12:07:17 +0100 Subject: [PATCH 091/105] refactor(multisig-client): build a proposal once, then check or push it (#251) Both SDKs now split proposal creation into a draft step (summary, metadata and unsigned payload) and either a push or a policy check of that same draft. The check no longer intercepts the create path: the Rust dry-run flag and shared mutex, and the TypeScript prototype override and thrown sentinel, are gone. Public APIs are unchanged; the Rust draft type stays crate-private. Rust custom proposals use the same draft, which adds check_custom_transaction and closes the gap with TypeScript, which could already check custom proposals. The mock Guardian records check requests, and a test pins that a check sends exactly the payload a push sends, without the proposer's signature. The client-sync TLA+ mirrors point at the moved TypeScript functions and its fingerprints are re-recorded; the model is unchanged. --- .agents/skills/verify-client-sync/SKILL.md | 2 +- .../verify-client-sync/fingerprints.txt | 10 +- .../skills/verify-client-sync/mirrored.txt | 6 +- crates/client/src/testing/mocks.rs | 12 + crates/miden-multisig-client/README.md | 2 + .../src/client/anchor_binding_tests.rs | 2 +- .../src/client/endpoint_scheme_tests.rs | 2 +- .../src/client/execution_mode_tests.rs | 60 ++++ .../src/client/proposals.rs | 59 ++-- crates/miden-multisig-client/src/payload.rs | 33 +- .../src/transaction/builder.rs | 321 +++++++----------- .../src/transaction/consume.rs | 2 +- .../src/transaction/mod.rs | 1 + docs/MIDEN_COMPATIBILITY.md | 2 +- docs/MULTISIG_SDK.md | 13 +- docs/guides/policy-modules/README.md | 6 +- docs/rfcs/0002-guardian-modules.md | 4 +- .../miden-multisig-client/src/multisig.ts | 235 +++++++------ 18 files changed, 411 insertions(+), 361 deletions(-) diff --git a/.agents/skills/verify-client-sync/SKILL.md b/.agents/skills/verify-client-sync/SKILL.md index 85b6e0ef..f9075b60 100644 --- a/.agents/skills/verify-client-sync/SKILL.md +++ b/.agents/skills/verify-client-sync/SKILL.md @@ -114,7 +114,7 @@ enough, because the undo of a dropped transaction leaves the cache on the dropped config. Fix: every proposal creator (`createProposal` and each `create*Proposal` -method), `signProposal`, `signProposalOffline`, `importProposal`, +method, in the `draft*` step that `checkTransaction` shares), `signProposal`, `signProposalOffline`, `importProposal`, `syncProposals` (`reconcileProposals`), `submitTransaction` and `registerOnGuardian` re-read the store (`refreshConfigFromStore`), and `prepareProposalExecution` and `prepareCustomExecution` refresh the config diff --git a/.agents/skills/verify-client-sync/fingerprints.txt b/.agents/skills/verify-client-sync/fingerprints.txt index ebef160a..ef604583 100644 --- a/.agents/skills/verify-client-sync/fingerprints.txt +++ b/.agents/skills/verify-client-sync/fingerprints.txt @@ -24,20 +24,20 @@ packages/miden-multisig-client/src/multisig.ts refreshConfigFromAccount 960b5894 packages/miden-multisig-client/src/multisig.ts refreshConfigFromStore 514a0e803597e19b packages/miden-multisig-client/src/multisig.ts adoptConfigFromAccount 7ce5bc7d73495198 packages/miden-multisig-client/src/multisig.ts assertExecutesOnPinnedBase 097642d2f57cf0d6 -packages/miden-multisig-client/src/multisig.ts createAddSignerProposal cc9911e4559c8cb8 -packages/miden-multisig-client/src/multisig.ts createRemoveSignerProposal 9b255e9507a3cc9e +packages/miden-multisig-client/src/multisig.ts draftAddSigner c3a090c1d2023fc0 +packages/miden-multisig-client/src/multisig.ts draftRemoveSigner ad04cb5e2e58c7b0 packages/miden-multisig-client/src/multisig.ts registerOnGuardian 4f1ed89a94dabbac packages/miden-multisig-client/src/multisig.ts executeProposal 63330ec3cb16bd47 packages/miden-multisig-client/src/multisig.ts prepareProposalExecution 244406c248b93c2e packages/miden-multisig-client/src/multisig.ts prepareCustomExecution 17c6ba0b0cb35230 -packages/miden-multisig-client/src/multisig.ts createSwitchGuardianProposal 7231d0e2ffc3267a +packages/miden-multisig-client/src/multisig.ts createSwitchGuardianProposal b648a53070c3d152 packages/miden-multisig-client/src/multisig.ts signProposalOffline dc7f1cad8efed3a9 packages/miden-multisig-client/src/multisig.ts signProposal 008039ab6b8a856a packages/miden-multisig-client/src/multisig.ts importProposal e720dac9240c2c33 packages/miden-multisig-client/src/multisig.ts reconcileProposals aa7962d87eff3c9d packages/miden-multisig-client/src/multisig.ts resolveProposalNonce 7c25a02c067fe164 -packages/miden-multisig-client/src/multisig.ts createProposal a46cabc9c2655e91 -packages/miden-multisig-client/src/multisig.ts pushProposal 3c2689a1a7e193d5 +packages/miden-multisig-client/src/multisig.ts createProposal 3f5d12dff4996611 +packages/miden-multisig-client/src/multisig.ts pushDraft 81a95d58401ca3f6 packages/miden-multisig-client/src/multisig.ts submitTransaction 9e4761cb3a1172b1 packages/miden-multisig-client/src/state/adopt.ts isSafeToAdoptGuardianState d30804918814dff2 packages/miden-multisig-client/src/prover/workflow.ts submit 34c1dded2dedbc5c diff --git a/.agents/skills/verify-client-sync/mirrored.txt b/.agents/skills/verify-client-sync/mirrored.txt index bdc66dbb..53f320ad 100644 --- a/.agents/skills/verify-client-sync/mirrored.txt +++ b/.agents/skills/verify-client-sync/mirrored.txt @@ -25,8 +25,8 @@ packages/miden-multisig-client/src/multisig.ts refreshConfigFromAccount packages/miden-multisig-client/src/multisig.ts refreshConfigFromStore packages/miden-multisig-client/src/multisig.ts adoptConfigFromAccount packages/miden-multisig-client/src/multisig.ts assertExecutesOnPinnedBase -packages/miden-multisig-client/src/multisig.ts createAddSignerProposal -packages/miden-multisig-client/src/multisig.ts createRemoveSignerProposal +packages/miden-multisig-client/src/multisig.ts draftAddSigner +packages/miden-multisig-client/src/multisig.ts draftRemoveSigner packages/miden-multisig-client/src/multisig.ts registerOnGuardian packages/miden-multisig-client/src/multisig.ts executeProposal packages/miden-multisig-client/src/multisig.ts prepareProposalExecution @@ -38,7 +38,7 @@ packages/miden-multisig-client/src/multisig.ts importProposal packages/miden-multisig-client/src/multisig.ts reconcileProposals packages/miden-multisig-client/src/multisig.ts resolveProposalNonce packages/miden-multisig-client/src/multisig.ts createProposal -packages/miden-multisig-client/src/multisig.ts pushProposal +packages/miden-multisig-client/src/multisig.ts pushDraft packages/miden-multisig-client/src/multisig.ts submitTransaction packages/miden-multisig-client/src/state/adopt.ts isSafeToAdoptGuardianState packages/miden-multisig-client/src/prover/workflow.ts submit diff --git a/crates/client/src/testing/mocks.rs b/crates/client/src/testing/mocks.rs index fe942445..ba66caac 100644 --- a/crates/client/src/testing/mocks.rs +++ b/crates/client/src/testing/mocks.rs @@ -40,6 +40,8 @@ pub struct MockGuardianHandle { calls: Arc>>, /// Every `push_delta_proposal` request body, in arrival order. push_delta_proposal_requests: Arc>>, + /// Every `check_delta_proposal` request body, in arrival order. + check_delta_proposal_requests: Arc>>, /// Every `abandon_delta_candidate` request body, in arrival order. abandon_requests: Arc>>, /// Every `execute_delta_proposal` request with the auth metadata it carried, in arrival @@ -65,6 +67,11 @@ impl MockGuardianHandle { self.push_delta_proposal_requests.lock().unwrap().clone() } + /// Every `check_delta_proposal` request received so far. + pub fn checked_proposals(&self) -> Vec { + self.check_delta_proposal_requests.lock().unwrap().clone() + } + /// Every `abandon_delta_candidate` request received so far. pub fn abandon_requests(&self) -> Vec { self.abandon_requests.lock().unwrap().clone() @@ -733,6 +740,11 @@ impl Guardian for MockGuardianService { request: Request, ) -> Result, Status> { self.record_call("check_delta_proposal"); + self.handle + .check_delta_proposal_requests + .lock() + .unwrap() + .push(request.get_ref().clone()); if request.get_ref().nonce == 0 { return Err(Status::with_details( tonic::Code::PermissionDenied, diff --git a/crates/miden-multisig-client/README.md b/crates/miden-multisig-client/README.md index 67bd4d8f..b3a8757e 100644 --- a/crates/miden-multisig-client/README.md +++ b/crates/miden-multisig-client/README.md @@ -814,6 +814,8 @@ let check = client.check_transaction(TransactionType::transfer(recipient, faucet // check.complete is false when a module that opts out of checks was skipped ``` +`check_custom_transaction` does the same for a producer-built transaction. + The answer is advisory: approval still decides, and the Guardian rate limits checks per account and signer. A refusal, from a check, at creation, push or registration, is `MultisigError::ModuleDenied { module, reason_code, layer, diff --git a/crates/miden-multisig-client/src/client/anchor_binding_tests.rs b/crates/miden-multisig-client/src/client/anchor_binding_tests.rs index 1d009a29..50af031a 100644 --- a/crates/miden-multisig-client/src/client/anchor_binding_tests.rs +++ b/crates/miden-multisig-client/src/client/anchor_binding_tests.rs @@ -62,7 +62,7 @@ async fn cosigner_at_a_later_sync_height_verifies_a_pending_proposal_at_its_tip( proposer.miden_client.sync_state().await.unwrap(); // Proposal creation authenticates the notes before deriving the summary - // (see `ProposalBuilder::build_consume_notes`); mirror it here. + // (see `ProposalBuilder::draft_consume_notes`); mirror it here. let node_rpc = proposer.node_rpc_client(); crate::transaction::ensure_notes_authenticated( &mut proposer.miden_client, diff --git a/crates/miden-multisig-client/src/client/endpoint_scheme_tests.rs b/crates/miden-multisig-client/src/client/endpoint_scheme_tests.rs index ad72640e..96c51139 100644 --- a/crates/miden-multisig-client/src/client/endpoint_scheme_tests.rs +++ b/crates/miden-multisig-client/src/client/endpoint_scheme_tests.rs @@ -100,7 +100,7 @@ async fn offline_creation_queries(scheme: SignatureScheme, seed: u8) -> Vec crate::transaction::ProposalDraft { + let account = client.require_account().unwrap().clone(); + let node_rpc = client.node_rpc_client(); + crate::transaction::ProposalBuilder::new(TransactionType::UpdateProcedureThreshold { + procedure: ProcedureName::ReceiveAsset, + new_threshold: 1, + }) + .with_execution_mode(client.execution_mode) + .draft( + &mut client.miden_client, + &node_rpc, + &account, + client.key_manager.as_ref(), + ) + .await + .unwrap() +} + +/// A check answers for exactly the proposal a push would create: same nonce, same payload, and +/// no approval, since nothing a check sends is stored. +#[tokio::test] +async fn a_check_sends_the_payload_a_push_sends_without_the_signature() { + let dir = tempfile::tempdir().unwrap(); + let (mut client, handle, _signers) = proposing_client( + dir.path(), + ProposalExecutionMode::GuardianExecutable, + AccountShape::OneSigner, + MockGuardianService::default(), + ) + .await; + let draft = draft_on(&mut client).await; + let mut guardian = client.create_authenticated_guardian_client().await.unwrap(); + + let check = draft.check(&mut guardian).await.unwrap(); + assert!(!check.complete); + assert!( + handle.pushed_proposals().is_empty(), + "a check creates nothing" + ); + let _ = draft.push(&mut guardian, client.key_manager.as_ref()).await; + + let checked = &handle.checked_proposals()[0]; + let pushed = &handle.pushed_proposals()[0]; + assert_eq!(checked.nonce, pushed.nonce); + let checked: serde_json::Value = serde_json::from_str(&checked.delta_payload).unwrap(); + let mut pushed: serde_json::Value = serde_json::from_str(&pushed.delta_payload).unwrap(); + assert!( + checked.get("signatures").is_none(), + "a check carries no approval" + ); + let signatures = pushed + .as_object_mut() + .unwrap() + .remove("signatures") + .expect("a push carries the proposer's approval"); + assert_eq!(signatures.as_array().unwrap().len(), 1); + assert_eq!(checked, pushed); +} diff --git a/crates/miden-multisig-client/src/client/proposals.rs b/crates/miden-multisig-client/src/client/proposals.rs index 2bbc9d3c..e43c9e87 100644 --- a/crates/miden-multisig-client/src/client/proposals.rs +++ b/crates/miden-multisig-client/src/client/proposals.rs @@ -83,8 +83,8 @@ use crate::execution::{ use crate::keystore::{proposal_public_key_hex, word_from_hex}; use crate::proposal::{Proposal, TransactionType, is_builtin_proposal_type}; use crate::transaction::{ - ProposalBuilder, ProposalCheck, ProposalOptions, deserialize_transaction_request, - execute_for_summary_at_tip, proposal_auth_args, word_to_hex, + ProposalBuilder, ProposalCheck, ProposalDraft, ProposalOptions, + deserialize_transaction_request, execute_for_summary_at_tip, proposal_auth_args, word_to_hex, }; impl MultisigClient { @@ -543,6 +543,38 @@ impl MultisigClient { transaction_request_bytes: &[u8], proposal_type: &str, ) -> Result { + let draft = self + .draft_custom_transaction(transaction_request_bytes, proposal_type) + .await?; + let mut guardian_client = self.create_authenticated_guardian_client().await?; + let proposal = draft + .push(&mut guardian_client, self.key_manager.as_ref()) + .await?; + self.known_proposals + .record(proposal.tx_summary.account_delta().id(), &proposal); + Ok(proposal) + } + + /// Asks GUARDIAN whether a custom transaction would be accepted as a proposal: it is built + /// exactly as [`Self::propose_custom_transaction`] builds it, but nothing is stored. Mirrors + /// [`Self::check_transaction`] for the transactions the SDK does not model. + pub async fn check_custom_transaction( + &mut self, + transaction_request_bytes: &[u8], + proposal_type: &str, + ) -> Result { + let draft = self + .draft_custom_transaction(transaction_request_bytes, proposal_type) + .await?; + let mut guardian_client = self.create_authenticated_guardian_client().await?; + draft.check(&mut guardian_client).await + } + + async fn draft_custom_transaction( + &mut self, + transaction_request_bytes: &[u8], + proposal_type: &str, + ) -> Result { let proposal_type = proposal_type.trim().to_lowercase(); if proposal_type.is_empty() { return Err(MultisigError::InvalidConfig( @@ -572,7 +604,6 @@ impl MultisigClient { let tx_request = deserialize_transaction_request(transaction_request_bytes)?; let tx_summary = execute_for_summary_at_tip(&mut self.miden_client, account_id, tx_request).await?; - let tx_commitment = tx_summary.to_commitment(); let required_signatures = account.threshold()? as usize; @@ -589,32 +620,12 @@ impl MultisigClient { self.execution_mode .attachment_of_bytes(transaction_request_bytes), ) - .with_signature(self.key_manager.as_ref(), tx_commitment) .with_custom_metadata(proposal_type.to_string()) .with_required_signatures(required_signatures); let nonce = account.nonce() + 1; - let mut guardian_client = self.create_authenticated_guardian_client().await?; - let response = guardian_client - .push_delta_proposal(&account_id, nonce, &payload.to_json()) - .await - .map_err(MultisigError::proposal_push)?; - let proposal = Proposal::new(tx_summary, nonce, TransactionType::Custom, metadata); - - if !proposal - .id - .trim_start_matches("0x") - .eq_ignore_ascii_case(response.commitment.trim_start_matches("0x")) - { - return Err(MultisigError::GuardianServer(format!( - "GUARDIAN returned proposal commitment {} but expected {}", - response.commitment, proposal.id - ))); - } - - self.known_proposals.record(account_id, &proposal); - Ok(proposal) + Ok(ProposalDraft::new(proposal, payload)) } /// Assembles the validated execution advice for a threshold-met custom diff --git a/crates/miden-multisig-client/src/payload.rs b/crates/miden-multisig-client/src/payload.rs index 8d39f5d6..ee5f286a 100644 --- a/crates/miden-multisig-client/src/payload.rs +++ b/crates/miden-multisig-client/src/payload.rs @@ -147,17 +147,19 @@ impl ProposalPayload { /// Adds the proposer's signature. pub fn with_signature( - self, + mut self, key_manager: &dyn KeyManager, message: miden_protocol::Word, ) -> Self { - self.with_proposer_signature(Some(proposer_signature(key_manager, message))) - } - - /// Adds the proposer's signature when there is one: a check of a proposal carries none, - /// since nothing it checks is stored. - pub fn with_proposer_signature(mut self, signature: Option) -> Self { - self.signatures.extend(signature); + let signature_hex = key_manager.sign_word_hex(message); + self.signatures.push(DeltaSignature { + signer_id: key_manager.commitment_hex(), + signature: ProposalSignature::from_scheme( + key_manager.scheme(), + signature_hex, + proposal_public_key_hex(key_manager), + ), + }); self } @@ -330,21 +332,6 @@ impl ProposalPayload { } } -/// The proposer's signature over `message`, the commitment of the proposal's summary. -pub(crate) fn proposer_signature( - key_manager: &dyn KeyManager, - message: miden_protocol::Word, -) -> DeltaSignature { - DeltaSignature { - signer_id: key_manager.commitment_hex(), - signature: ProposalSignature::from_scheme( - key_manager.scheme(), - key_manager.sign_word_hex(message), - proposal_public_key_hex(key_manager), - ), - } -} - #[cfg(test)] mod tests { use miden_protocol::account::delta::{AccountDelta, AccountVaultDelta}; diff --git a/crates/miden-multisig-client/src/transaction/builder.rs b/crates/miden-multisig-client/src/transaction/builder.rs index 88c12336..c8cba0fd 100644 --- a/crates/miden-multisig-client/src/transaction/builder.rs +++ b/crates/miden-multisig-client/src/transaction/builder.rs @@ -47,9 +47,16 @@ pub struct ProposalBuilder { transaction_type: TransactionType, approval_expiration_delta: Option, execution_mode: ProposalExecutionMode, - /// Set by [`ProposalBuilder::check`]: the proposal is checked on GUARDIAN, not created. - dry_run: bool, - checked: Arc>>, +} + +/// A proposal built for an account and not yet sent: the payload GUARDIAN would store, without +/// the proposer's approval, and the proposal it describes. [`Self::check`] asks GUARDIAN whether +/// it would be created; [`Self::push`] signs and creates it. Both send the same payload, so a +/// check answers for exactly the proposal a push would create. +#[derive(Debug, Clone)] +pub(crate) struct ProposalDraft { + proposal: Proposal, + payload: ProposalPayload, } /// The answer of a proposal check that passed: GUARDIAN's policy modules would let the @@ -159,8 +166,6 @@ impl ProposalBuilder { Self { transaction_type, approval_expiration_delta: None, - dry_run: false, - checked: Arc::default(), execution_mode: ProposalExecutionMode::SelfExecuted, } } @@ -184,79 +189,23 @@ impl ProposalBuilder { self } - /// Builds the proposal exactly as [`Self::build`] would and asks GUARDIAN whether it - /// would be created, without storing it. Advisory: approval still decides. + /// Builds the proposal and asks GUARDIAN whether it would be created, without storing it. + /// Advisory: approval still decides. pub async fn check( - mut self, + self, miden_client: &mut MidenSdkClient, node_rpc: &Arc, guardian_client: &mut GuardianClient, account: &MultisigAccount, key_manager: &dyn KeyManager, ) -> Result { - self.dry_run = true; - let checked = self.checked.clone(); - self.build( - miden_client, - node_rpc, - guardian_client, - account, - key_manager, - ) - .await?; - let result = checked.lock().ok().and_then(|mut checked| checked.take()); - result.ok_or_else(|| { - MultisigError::GuardianServer("GUARDIAN did not answer the proposal check".into()) - }) - } - - /// The proposer's approval of a proposal that will be created. A check sends none: nothing - /// it checks is stored, so it must not hand GUARDIAN a signature that authorizes it. - fn proposer_signature( - &self, - key_manager: &dyn KeyManager, - tx_commitment: Word, - ) -> Option { - (!self.dry_run).then(|| crate::payload::proposer_signature(key_manager, tx_commitment)) - } - - /// Creates the proposal on GUARDIAN, or only checks it in a dry run. Returns the - /// commitment GUARDIAN reports for a created proposal, none for a check. - async fn send( - &self, - guardian_client: &mut GuardianClient, - account_id: &AccountId, - nonce: u64, - payload: &serde_json::Value, - ) -> Result> { - if self.dry_run { - let response = guardian_client - .check_delta_proposal(account_id, nonce, payload) - .await - .map_err(MultisigError::proposal_push)?; - if let Ok(mut checked) = self.checked.lock() { - *checked = Some(ProposalCheck { - complete: response.complete, - }); - } - return Ok(None); - } - let response = guardian_client - .push_delta_proposal(account_id, nonce, payload) + self.draft(miden_client, node_rpc, account, key_manager) + .await? + .check(guardian_client) .await - .map_err(MultisigError::proposal_push)?; - Ok(Some(response.commitment)) - } - - /// Checks GUARDIAN's commitment for a created proposal; a check has none. - fn confirm(&self, proposal: &Proposal, response_commitment: Option<&str>) -> Result<()> { - match response_commitment { - Some(commitment) => Self::ensure_response_commitment(proposal, commitment), - None => Ok(()), - } } - /// Builds and submits the proposal to GUARDIAN. + /// Builds the proposal, signs it as its proposer and creates it on GUARDIAN. pub async fn build( self, miden_client: &mut MidenSdkClient, @@ -265,6 +214,21 @@ impl ProposalBuilder { account: &MultisigAccount, key_manager: &dyn KeyManager, ) -> Result { + self.draft(miden_client, node_rpc, account, key_manager) + .await? + .push(guardian_client, key_manager) + .await + } + + /// Builds the proposal for `account` with `key_manager` as its proposer, without contacting + /// GUARDIAN: the transaction is executed locally for its summary, and nothing is signed. + pub(crate) async fn draft( + self, + miden_client: &mut MidenSdkClient, + node_rpc: &Arc, + account: &MultisigAccount, + key_manager: &dyn KeyManager, + ) -> Result { match self.transaction_type { TransactionType::AddCosigner { new_commitment, @@ -272,24 +236,12 @@ impl ProposalBuilder { } => { let new_signer = SignerSpec::new(new_commitment, scheme.unwrap_or(key_manager.scheme())); - self.build_add_cosigner( - miden_client, - guardian_client, - account, - new_signer, - key_manager, - ) - .await + self.draft_add_cosigner(miden_client, account, new_signer, key_manager) + .await } TransactionType::RemoveCosigner { commitment } => { - self.build_remove_cosigner( - miden_client, - guardian_client, - account, - commitment, - key_manager, - ) - .await + self.draft_remove_cosigner(miden_client, account, commitment, key_manager) + .await } TransactionType::P2ID { recipient, @@ -298,9 +250,8 @@ impl ProposalBuilder { note_type, heights, } => { - self.build_p2id( + self.draft_p2id( miden_client, - guardian_client, account, recipient, faucet_id, @@ -312,10 +263,9 @@ impl ProposalBuilder { .await } TransactionType::ConsumeNotes { ref note_ids, .. } => { - self.build_consume_notes( + self.draft_consume_notes( miden_client, node_rpc, - guardian_client, account, note_ids.clone(), key_manager, @@ -326,9 +276,8 @@ impl ProposalBuilder { ref new_endpoint, new_commitment, } => { - self.build_switch_guardian( + self.draft_switch_guardian( miden_client, - guardian_client, account, new_commitment, new_endpoint.clone(), @@ -340,9 +289,8 @@ impl ProposalBuilder { procedure, new_threshold, } => { - self.build_update_procedure_threshold( + self.draft_update_procedure_threshold( miden_client, - guardian_client, account, procedure, new_threshold, @@ -354,9 +302,8 @@ impl ProposalBuilder { new_threshold, ref signer_commitments, } => { - self.build_update_signers( + self.draft_update_signers( miden_client, - guardian_client, account, new_threshold, signer_commitments, @@ -370,18 +317,6 @@ impl ProposalBuilder { } } - fn ensure_response_commitment(proposal: &Proposal, response_commitment: &str) -> Result<()> { - let response_commitment = ensure_hex_prefix(response_commitment); - if hex_body_eq(&proposal.id, &response_commitment) { - return Ok(()); - } - - Err(MultisigError::GuardianServer(format!( - "GUARDIAN returned proposal commitment {} but transaction summary commitment is {}", - response_commitment, proposal.id - ))) - } - async fn fresh_auth_args(&self, miden_client: &MidenSdkClient) -> Result { proposer_auth_args( miden_client, @@ -392,14 +327,13 @@ impl ProposalBuilder { .await } - async fn build_add_cosigner( + async fn draft_add_cosigner( &self, miden_client: &mut MidenSdkClient, - guardian_client: &mut GuardianClient, account: &MultisigAccount, new_signer: SignerSpec, key_manager: &dyn KeyManager, - ) -> Result { + ) -> Result { let account_id = account.id(); let current_threshold = account.threshold()?; let approvers = account.cosigners()?; @@ -433,9 +367,6 @@ impl ProposalBuilder { let attachment = self.execution_mode.attachment(&tx_request); let tx_summary = execute_for_summary_at_tip(miden_client, account_id, tx_request).await?; - // Sign the transaction summary commitment - let tx_commitment = tx_summary.to_commitment(); - // Build proposal metadata let signer_commitments_hex: Vec = current_signers.iter().map(word_to_hex).collect(); @@ -466,7 +397,6 @@ impl ProposalBuilder { // Build the payload using ProposalPayload let payload = ProposalPayload::new(&tx_summary) .with_transaction_request(attachment) - .with_proposer_signature(self.proposer_signature(key_manager, tx_commitment)) .with_add_signer_metadata( new_threshold, signer_commitments_hex.clone(), @@ -475,11 +405,7 @@ impl ProposalBuilder { .with_signer_schemes(&signer_schemes) .with_required_signatures(required_signatures); - // Push proposal to GUARDIAN let nonce = account.nonce() + 1; - let response_commitment = self - .send(guardian_client, &account_id, nonce, &payload.to_json()) - .await?; // Build the Proposal let proposal = Proposal::new( @@ -491,28 +417,25 @@ impl ProposalBuilder { }, metadata, ); - self.confirm(&proposal, response_commitment.as_deref())?; - - Ok(proposal) + Ok(ProposalDraft::new(proposal, payload)) } /// Changes the signing threshold, leaving the signer set as it is. /// /// The on-chain procedure takes a set and a threshold together, so this is - /// the same call `build_add_cosigner` makes with the set left alone. A + /// the same call `draft_add_cosigner` makes with the set left alone. A /// membership change is refused here rather than served: deriving the new /// set from the current one is what makes add and remove safe, and a /// caller-supplied set would give that up for no gain, since this variant /// exists to move the threshold. - async fn build_update_signers( + async fn draft_update_signers( &self, miden_client: &mut MidenSdkClient, - guardian_client: &mut GuardianClient, account: &MultisigAccount, new_threshold: u32, requested_signers: &[Word], key_manager: &dyn KeyManager, - ) -> Result { + ) -> Result { let account_id = account.id(); let current_threshold = account.threshold()?; let target_signers = account.cosigners()?; @@ -543,7 +466,6 @@ impl ProposalBuilder { let attachment = self.execution_mode.attachment(&tx_request); let tx_summary = execute_for_summary_at_tip(miden_client, account_id, tx_request).await?; - let tx_commitment = tx_summary.to_commitment(); let signer_commitments_hex: Vec = current_signers.iter().map(word_to_hex).collect(); @@ -577,7 +499,6 @@ impl ProposalBuilder { let payload = ProposalPayload::new(&tx_summary) .with_transaction_request(attachment) - .with_proposer_signature(self.proposer_signature(key_manager, tx_commitment)) .with_threshold_metadata( new_threshold, signer_commitments_hex.clone(), @@ -587,9 +508,6 @@ impl ProposalBuilder { .with_required_signatures(required_signatures); let nonce = account.nonce() + 1; - let response_commitment = self - .send(guardian_client, &account_id, nonce, &payload.to_json()) - .await?; let proposal = Proposal::new( tx_summary, @@ -600,19 +518,16 @@ impl ProposalBuilder { }, metadata, ); - self.confirm(&proposal, response_commitment.as_deref())?; - - Ok(proposal) + Ok(ProposalDraft::new(proposal, payload)) } - async fn build_remove_cosigner( + async fn draft_remove_cosigner( &self, miden_client: &mut MidenSdkClient, - guardian_client: &mut GuardianClient, account: &MultisigAccount, commitment_to_remove: Word, key_manager: &dyn KeyManager, - ) -> Result { + ) -> Result { let account_id = account.id(); let current_threshold = account.threshold()?; let current_signers = account.cosigners()?; @@ -660,9 +575,6 @@ impl ProposalBuilder { let attachment = self.execution_mode.attachment(&tx_request); let tx_summary = execute_for_summary_at_tip(miden_client, account_id, tx_request).await?; - // Sign the transaction summary commitment - let tx_commitment = tx_summary.to_commitment(); - // Build proposal metadata let signer_commitments_hex: Vec = new_signers.iter().map(word_to_hex).collect(); @@ -693,7 +605,6 @@ impl ProposalBuilder { // Build the payload using ProposalPayload let payload = ProposalPayload::new(&tx_summary) .with_transaction_request(attachment) - .with_proposer_signature(self.proposer_signature(key_manager, tx_commitment)) .with_remove_signer_metadata( new_threshold, signer_commitments_hex.clone(), @@ -702,11 +613,7 @@ impl ProposalBuilder { .with_signer_schemes(&signer_schemes) .with_required_signatures(required_signatures); - // Push proposal to GUARDIAN let nonce = account.nonce() + 1; - let response_commitment = self - .send(guardian_client, &account_id, nonce, &payload.to_json()) - .await?; // Build the Proposal let proposal = Proposal::new( @@ -717,16 +624,13 @@ impl ProposalBuilder { }, metadata, ); - self.confirm(&proposal, response_commitment.as_deref())?; - - Ok(proposal) + Ok(ProposalDraft::new(proposal, payload)) } #[allow(clippy::too_many_arguments)] - async fn build_p2id( + async fn draft_p2id( &self, miden_client: &mut MidenSdkClient, - guardian_client: &mut GuardianClient, account: &MultisigAccount, recipient: AccountId, faucet_id: AccountId, @@ -734,7 +638,7 @@ impl ProposalBuilder { note_type: NoteType, heights: P2ideHeights, key_manager: &dyn KeyManager, - ) -> Result { + ) -> Result { let account_id = account.id(); let required_signatures = account.effective_threshold_for(ThresholdedTransaction::P2id)? as usize; @@ -760,9 +664,6 @@ impl ProposalBuilder { let attachment = self.execution_mode.attachment(&tx_request); let tx_summary = execute_for_summary_at_tip(miden_client, account_id, tx_request).await?; - // Sign the transaction summary commitment - let tx_commitment = tx_summary.to_commitment(); - // Build proposal metadata let metadata = ProposalMetadata { tx_summary_json: Some(tx_summary.to_json()), @@ -790,7 +691,6 @@ impl ProposalBuilder { // Build the payload using ProposalPayload let payload = ProposalPayload::new(&tx_summary) .with_transaction_request(attachment) - .with_proposer_signature(self.proposer_signature(key_manager, tx_commitment)) .with_payment_metadata( recipient.to_string(), faucet_id.to_string(), @@ -801,11 +701,7 @@ impl ProposalBuilder { ) .with_required_signatures(required_signatures); - // Push proposal to GUARDIAN let nonce = account.nonce() + 1; - let response_commitment = self - .send(guardian_client, &account_id, nonce, &payload.to_json()) - .await?; // Build the Proposal let proposal = Proposal::new( @@ -820,20 +716,17 @@ impl ProposalBuilder { }, metadata, ); - self.confirm(&proposal, response_commitment.as_deref())?; - - Ok(proposal) + Ok(ProposalDraft::new(proposal, payload)) } - async fn build_consume_notes( + async fn draft_consume_notes( &self, miden_client: &mut MidenSdkClient, node_rpc: &Arc, - guardian_client: &mut GuardianClient, account: &MultisigAccount, note_ids: Vec, key_manager: &dyn KeyManager, - ) -> Result { + ) -> Result { let account_id = account.id(); let required_signatures = account.effective_threshold_for(ThresholdedTransaction::ConsumeNotes)? as usize; @@ -877,7 +770,6 @@ impl ProposalBuilder { let attachment = self.execution_mode.attachment(&tx_request); let tx_summary = execute_for_summary_at_tip(miden_client, account_id, tx_request).await?; - let tx_commitment = tx_summary.to_commitment(); let note_ids_hex: Vec = note_ids.iter().map(|id| id.to_hex()).collect(); let metadata = ProposalMetadata { @@ -912,7 +804,6 @@ impl ProposalBuilder { let payload = ProposalPayload::new(&tx_summary) .with_transaction_request(attachment) - .with_proposer_signature(self.proposer_signature(key_manager, tx_commitment)) .with_note_consumption_metadata_v2(note_ids_hex, notes_base64, word_to_hex(&salt)) .with_required_signatures(required_signatures); @@ -929,11 +820,7 @@ impl ProposalBuilder { } } - // Push proposal to GUARDIAN let nonce = account.nonce() + 1; - let response_commitment = self - .send(guardian_client, &account_id, nonce, &payload.to_json()) - .await?; // Clone notes for the runtime TransactionType; metadata keeps its own copy. let notes_for_tx_type = metadata.consume_notes_notes.clone(); @@ -947,21 +834,18 @@ impl ProposalBuilder { }, metadata, ); - self.confirm(&proposal, response_commitment.as_deref())?; - - Ok(proposal) + Ok(ProposalDraft::new(proposal, payload)) } #[allow(clippy::too_many_arguments)] - async fn build_switch_guardian( + async fn draft_switch_guardian( &self, miden_client: &mut MidenSdkClient, - guardian_client: &mut GuardianClient, account: &MultisigAccount, new_guardian_pubkey: Word, new_guardian_endpoint: String, key_manager: &dyn KeyManager, - ) -> Result { + ) -> Result { let account_id = account.id(); let required_signatures = account.effective_threshold_for(ThresholdedTransaction::UpdateGuardian)? as usize; @@ -987,9 +871,6 @@ impl ProposalBuilder { let attachment = self.execution_mode.attachment(&tx_request); let tx_summary = execute_for_summary_at_tip(miden_client, account_id, tx_request).await?; - // Sign the transaction summary commitment - let tx_commitment = tx_summary.to_commitment(); - // Build proposal metadata let metadata = ProposalMetadata { tx_summary_json: Some(tx_summary.to_json()), @@ -1017,7 +898,6 @@ impl ProposalBuilder { // Build the payload using ProposalPayload let payload = ProposalPayload::new(&tx_summary) .with_transaction_request(attachment) - .with_proposer_signature(self.proposer_signature(key_manager, tx_commitment)) .with_guardian_update_metadata( word_to_hex(&new_guardian_pubkey), new_guardian_endpoint.clone(), @@ -1025,11 +905,7 @@ impl ProposalBuilder { ) .with_required_signatures(required_signatures); - // Push proposal to GUARDIAN let nonce = account.nonce() + 1; - let response_commitment = self - .send(guardian_client, &account_id, nonce, &payload.to_json()) - .await?; // Build the Proposal let proposal = Proposal::new( @@ -1041,20 +917,17 @@ impl ProposalBuilder { }, metadata, ); - self.confirm(&proposal, response_commitment.as_deref())?; - - Ok(proposal) + Ok(ProposalDraft::new(proposal, payload)) } - async fn build_update_procedure_threshold( + async fn draft_update_procedure_threshold( &self, miden_client: &mut MidenSdkClient, - guardian_client: &mut GuardianClient, account: &MultisigAccount, procedure: ProcedureName, new_threshold: u32, key_manager: &dyn KeyManager, - ) -> Result { + ) -> Result { let account_id = account.id(); let required_signatures = account .effective_threshold_for(ThresholdedTransaction::SetProcedureThreshold)? @@ -1071,7 +944,6 @@ impl ProposalBuilder { )?; let attachment = self.execution_mode.attachment(&tx_request); let tx_summary = execute_for_summary_at_tip(miden_client, account_id, tx_request).await?; - let tx_commitment = tx_summary.to_commitment(); let metadata = ProposalMetadata { tx_summary_json: Some(tx_summary.to_json()), @@ -1098,14 +970,10 @@ impl ProposalBuilder { let payload = ProposalPayload::new(&tx_summary) .with_transaction_request(attachment) - .with_proposer_signature(self.proposer_signature(key_manager, tx_commitment)) .with_procedure_threshold_metadata(procedure, new_threshold as u64, word_to_hex(&salt)) .with_required_signatures(required_signatures); let nonce = account.nonce() + 1; - let response_commitment = self - .send(guardian_client, &account_id, nonce, &payload.to_json()) - .await?; let proposal = Proposal::new( tx_summary, @@ -1116,9 +984,68 @@ impl ProposalBuilder { }, metadata, ); - self.confirm(&proposal, response_commitment.as_deref())?; + Ok(ProposalDraft::new(proposal, payload)) + } +} + +impl ProposalDraft { + pub(crate) fn new(proposal: Proposal, payload: ProposalPayload) -> Self { + Self { proposal, payload } + } + + fn account_id(&self) -> AccountId { + self.proposal.tx_summary.account_delta().id() + } - Ok(proposal) + /// Asks GUARDIAN whether this proposal would be created, without storing it. It carries no + /// signature: nothing it checks is stored, so it must not hand GUARDIAN an approval. A + /// refusal is the same error a push returns. Advisory: approval still decides. + pub(crate) async fn check( + &self, + guardian_client: &mut GuardianClient, + ) -> Result { + let response = guardian_client + .check_delta_proposal( + &self.account_id(), + self.proposal.nonce, + &self.payload.to_json(), + ) + .await + .map_err(MultisigError::proposal_push)?; + Ok(ProposalCheck { + complete: response.complete, + }) + } + + /// Signs the proposal with `key_manager`, the proposer it was drafted for, and creates it on + /// GUARDIAN. Refuses a reply whose commitment is not the summary's. + pub(crate) async fn push( + self, + guardian_client: &mut GuardianClient, + key_manager: &dyn KeyManager, + ) -> Result { + let account_id = self.account_id(); + let payload = self + .payload + .with_signature(key_manager, self.proposal.tx_summary.to_commitment()); + let response = guardian_client + .push_delta_proposal(&account_id, self.proposal.nonce, &payload.to_json()) + .await + .map_err(MultisigError::proposal_push)?; + Self::ensure_response_commitment(&self.proposal, &response.commitment)?; + Ok(self.proposal) + } + + fn ensure_response_commitment(proposal: &Proposal, response_commitment: &str) -> Result<()> { + let response_commitment = ensure_hex_prefix(response_commitment); + if hex_body_eq(&proposal.id, &response_commitment) { + return Ok(()); + } + + Err(MultisigError::GuardianServer(format!( + "GUARDIAN returned proposal commitment {} but transaction summary commitment is {}", + response_commitment, proposal.id + ))) } } @@ -1232,7 +1159,7 @@ mod tests { #[test] fn ensure_response_commitment_rejects_mismatch() { let proposal = test_proposal(); - let result = ProposalBuilder::ensure_response_commitment( + let result = ProposalDraft::ensure_response_commitment( &proposal, "0x0102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f20", ); diff --git a/crates/miden-multisig-client/src/transaction/consume.rs b/crates/miden-multisig-client/src/transaction/consume.rs index bc6680c3..feaf8b00 100644 --- a/crates/miden-multisig-client/src/transaction/consume.rs +++ b/crates/miden-multisig-client/src/transaction/consume.rs @@ -21,7 +21,7 @@ use crate::error::{MultisigError, Result}; /// and converts each `InputNoteRecord` to a `Note`. Returns /// `LegacyConsumeNotesNoteMissing` for the first missing ID. Used by /// both proposal creation (the proposer-local fetch in -/// `ProposalBuilder::build_consume_notes`) and the v1 verification +/// `ProposalBuilder::draft_consume_notes`) and the v1 verification /// adapter below. pub(crate) async fn fetch_notes_from_store( client: &MidenSdkClient, diff --git a/crates/miden-multisig-client/src/transaction/mod.rs b/crates/miden-multisig-client/src/transaction/mod.rs index 2fa169f0..0e4ae6d6 100644 --- a/crates/miden-multisig-client/src/transaction/mod.rs +++ b/crates/miden-multisig-client/src/transaction/mod.rs @@ -13,6 +13,7 @@ pub use auth_args::{ proposal_auth_args, proposer_auth_args, summary_approval_expiration_block_num, summary_salt, synced_fee_faucet_id, }; +pub(crate) use builder::ProposalDraft; pub use builder::{ProposalBuilder, ProposalCheck, ProposalOptions}; pub use configuration::{ build_update_procedure_threshold_transaction_request, build_update_signers_transaction_request, diff --git a/docs/MIDEN_COMPATIBILITY.md b/docs/MIDEN_COMPATIBILITY.md index 1cc5c608..856ecef3 100644 --- a/docs/MIDEN_COMPATIBILITY.md +++ b/docs/MIDEN_COMPATIBILITY.md @@ -738,7 +738,7 @@ deployment without one behaves as before. With one: - Neither enum is `#[non_exhaustive]`, so an exhaustive `match` over either stops compiling until the new variants are handled. - **New calls.** `get_policies` / `getPolicies`, `check_transaction` / - `checkTransaction`, session operations 14 (`GetPolicies`) and 15 + `checkTransaction`, Rust `check_custom_transaction`, session operations 14 (`GetPolicies`) and 15 (`CheckDeltaProposal`), and the operator client's module routes and the `policies:write_global` and `modules:disable` permissions. An operator client from 0.18.x fails to parse a session that holds either permission. diff --git a/docs/MULTISIG_SDK.md b/docs/MULTISIG_SDK.md index b06ee7c4..24ccd41a 100644 --- a/docs/MULTISIG_SDK.md +++ b/docs/MULTISIG_SDK.md @@ -810,9 +810,16 @@ matching create call would and ask the Guardian whether it would be accepted. Nothing is stored, no proposal slot is taken and no signature is sent. The result's `complete` is false when a module that opts out of checks was skipped. The answer is advisory, since approval still decides, and checks are -rate limited per account and signer. The transaction types each SDK can check -differ today: TypeScript checks every typed creator and `custom` but not a -Guardian switch; Rust checks every `TransactionType` except custom. +rate limited per account and signer. Both SDKs check every typed creator and +custom proposals (`check_custom_transaction` in Rust, `{ type: 'custom' }` in +TypeScript). A Guardian switch is checkable only in Rust, but a switch is never +gated by modules anyway. + +A check and a creation build the proposal the same way: each create call first +drafts the proposal locally (summary, metadata and payload, no signature) and +then either sends that draft to the check route or pushes it. Rust adds the +proposer's signature to a push; TypeScript pushes it unsigned and the proposer +signs afterwards, as for any other approval. A check never carries a signature. **Typed refusals.** A refusal from a check, at creation, at push or at registration carries the same information in both SDKs: diff --git a/docs/guides/policy-modules/README.md b/docs/guides/policy-modules/README.md index 45c6a14f..8f3535b5 100644 --- a/docs/guides/policy-modules/README.md +++ b/docs/guides/policy-modules/README.md @@ -77,9 +77,9 @@ Cosigners use two client endpoints: creation would return. At most `GUARDIAN_MODULE_CHECK_RATE_PER_MIN` (30) checks per account and signer per minute. -The multisig SDKs wrap both: Rust `get_policies` and `check_transaction`, -TypeScript `getPolicies` and `checkTransaction`, which build the transaction -exactly as proposing it would. +The multisig SDKs wrap both: Rust `get_policies`, `check_transaction` and +`check_custom_transaction`, TypeScript `getPolicies` and `checkTransaction`, +which build the transaction exactly as proposing it would. An instance whose catalog params contain secret references cannot use `disclosure = "params"`: the server refuses to start, since the reference diff --git a/docs/rfcs/0002-guardian-modules.md b/docs/rfcs/0002-guardian-modules.md index f9714bed..abf406f1 100644 --- a/docs/rfcs/0002-guardian-modules.md +++ b/docs/rfcs/0002-guardian-modules.md @@ -544,7 +544,7 @@ A wallet shows the two descriptions next to the transaction form; nothing in the **Client message.** A module may set `Decision.client_message` (plain text, at most 256 characters) for the person who sent the request, in addition to the logged `message`. The Guardian forwards it in `meta.client_message` only for an instance with `client_reason = "full"`, and drops it otherwise. -**Client SDKs.** The base clients mirror the RPCs (Rust `get_policies` and `check_delta_proposal`; TypeScript `getPolicies` and `checkDeltaProposal`). Both multisig SDKs expose the summary and the check in terms of transactions (Rust `get_policies`, `check_transaction` and `check_transaction_with_options`; TypeScript `getPolicies` and `checkTransaction`), so a wallet can show the rules in the form and check a transaction before the user submits it. The check builds the transaction exactly as proposing it would, so it judges the same payload. +**Client SDKs.** The base clients mirror the RPCs (Rust `get_policies` and `check_delta_proposal`; TypeScript `getPolicies` and `checkDeltaProposal`). Both multisig SDKs expose the summary and the check in terms of transactions (Rust `get_policies`, `check_transaction`, `check_transaction_with_options` and `check_custom_transaction`; TypeScript `getPolicies` and `checkTransaction`), so a wallet can show the rules in the form and check a transaction before the user submits it. Each SDK drafts a proposal once (summary, metadata and payload, unsigned) and either sends the draft to the check or pushes it (Rust adds the proposer's signature to the push), so a check judges the payload creation would send, without any signature. --- @@ -1205,7 +1205,7 @@ None. Questions resolved in earlier revisions are kept below with their answers. | Revision | Date | Changes | |---|---|---| -| 32 | 2026-11-10 | review of the M2a implementation. Protocol version 1 reopened (section 7): `Decision.allow` and the `decision.effect` capability removed, a decision without an effect is a module failure (section 3.5); `MidenTransaction.reference_block` and `expiration_block` replaced by `bound_block`, `expiration_delta` and `approval_expiration_block`, and `nonce_delta` made unsigned (section 3.1); `network_id` is the Guardian's configured network, not the account's registered one (section 3.1); `RegistrationSubject.initial_state` is sent; `tx_fee` is set only while the fee note carries no more of the fee asset than a transaction can owe, 64 times the chain's verification base fee, and for no note on a chain that charges nothing (section 3.1). Breaker: requests a module rejects do not count, a module whose timeout is the whole budget can open it, half-open sends one trial at a time, dry-run checks neither probe nor close it (section 4.4). Fail-open skips at proposal creation and registration, where no delta is signed, are recorded as `modules.failed_open` audit events; operator writes are audited with the params version they committed as (section 2.2). A health probe that finds a module incompatible opens its breaker at once and one that gets no answer counts as a failed call (section 4.4). Startup: a known instance whose module does not answer starts unavailable instead of stopping the server, and an instance the catalog declares enabled and not operator-disableable is enabled even when stored as disabled (section 2.2). `basic-policy`: per-field id lengths, and `deny_unknown_recipients` defaults to on once the denylist names anyone (section 3.1). The conformance suite checks stated outcomes and needs a request the module must deny. `basic-policy` is split into four kinds with short param names: `spending-limit` (`max_per_transaction`, `allowed_assets`), `recipient-policy` (`allowlist`, `denylist`, `deny_unknown`), `signer-policy` (`allowlist`, `denylist`, `check`) and `code-policy` (`allowed`, `check`), each supporting only the hooks where its rule can refuse (section 3.1). Body corrected to the implementation: metric names, the fixed 1000 ms timeout cap, params encoding, the `circuit_open` failure kind | +| 32 | 2026-11-10 | review of the M2a implementation. Protocol version 1 reopened (section 7): `Decision.allow` and the `decision.effect` capability removed, a decision without an effect is a module failure (section 3.5); `MidenTransaction.reference_block` and `expiration_block` replaced by `bound_block`, `expiration_delta` and `approval_expiration_block`, and `nonce_delta` made unsigned (section 3.1); `network_id` is the Guardian's configured network, not the account's registered one (section 3.1); `RegistrationSubject.initial_state` is sent; `tx_fee` is set only while the fee note carries no more of the fee asset than a transaction can owe, 64 times the chain's verification base fee, and for no note on a chain that charges nothing (section 3.1). Breaker: requests a module rejects do not count, a module whose timeout is the whole budget can open it, half-open sends one trial at a time, dry-run checks neither probe nor close it (section 4.4). Fail-open skips at proposal creation and registration, where no delta is signed, are recorded as `modules.failed_open` audit events; operator writes are audited with the params version they committed as (section 2.2). A health probe that finds a module incompatible opens its breaker at once and one that gets no answer counts as a failed call (section 4.4). Startup: a known instance whose module does not answer starts unavailable instead of stopping the server, and an instance the catalog declares enabled and not operator-disableable is enabled even when stored as disabled (section 2.2). `basic-policy`: per-field id lengths, and `deny_unknown_recipients` defaults to on once the denylist names anyone (section 3.1). The conformance suite checks stated outcomes and needs a request the module must deny. `basic-policy` is split into four kinds with short param names: `spending-limit` (`max_per_transaction`, `allowed_assets`), `recipient-policy` (`allowlist`, `denylist`, `deny_unknown`), `signer-policy` (`allowlist`, `denylist`, `check`) and `code-policy` (`allowed`, `check`), each supporting only the hooks where its rule can refuse (section 3.1). SDKs: a check and a creation send the same unsigned draft, and Rust checks custom proposals (section 2.7). Body corrected to the implementation: metric names, the fixed 1000 ms timeout cap, params encoding, the `circuit_open` failure kind | | 31 | 2026-11-09 | failures of dry-run checks do not count toward the circuit breaker, since a cosigner sends them without anyone's signature (section 4.4); the per-account budget check refuses only writes that raise an over-budget cost (section 4.3); `GUARDIAN_MODULE_UNAVAILABLE` and `GUARDIAN_EXECUTION_MODULE_UNAVAILABLE` omit `module` for an instance whose denials are generic (section 4.1); `metadata.modules` is kept out of client delta responses (section 2.2). `OutputNote.tx_fee` set only for the fee note `pay_fee` creates (section 3.1): the only `TX_FEE` note, with the derived serial number and one asset of the chain's fee faucet. Revisions 20 to 30 set it for any note with the `TX_FEE` script, which a transaction script can create with any assets, so the flag let funds past every `basic-policy` rule. No wire change; the field's meaning is narrowed | | 30 | 2026-11-09 | the secrets backend named: `GUARDIAN_MODULE_SECRET_PROVIDER` selects AWS Secrets Manager (the prod default) or owner-only files below `GUARDIAN_MODULE_SECRET_DIR`, read once when the instances are created; a secret that cannot be read fails creation, with the enabled/disabled rule of section 2.2. Field names fixed as `auth.token_secret`, `tls.client_cert_secret` and `tls.client_key_secret`; a secret name is 1 to 512 characters of letters, digits and `/_+=.@-`, and a `$secret` object has no other key (section 2.2). In-process factories read `$secret` values from `ModuleInstanceConfig::secret`. No protocol change | | 29 | 2026-11-09 | M2a implementation of `scope = default`: the copy is written right after the claim, only into an account with no assignment and no assignment history, under the module state lock, instead of in the claim's transaction on Postgres and before the claim on the filesystem; a crash in between is repaired by the unfinished-claim retry, so both backends follow one rule and no transaction spans the metadata and module stores (section 2.3). No protocol change | diff --git a/packages/miden-multisig-client/src/multisig.ts b/packages/miden-multisig-client/src/multisig.ts index 3fe1b86d..296707e5 100644 --- a/packages/miden-multisig-client/src/multisig.ts +++ b/packages/miden-multisig-client/src/multisig.ts @@ -218,8 +218,26 @@ export type CheckableTransaction = options?: CreateProposalOptions; }; -/** Thrown inside a check once the payload is built, so nothing after the push runs. */ -const CHECKED = Symbol('checked'); +/** + * A proposal built for the account and not yet sent: what GUARDIAN would store. A check and a + * push send the same draft, so a check answers for exactly the proposal a push would create. + */ +interface ProposalDraft { + nonce: number; + txSummaryBase64: string; + metadata: ProposalMetadata; + transactionRequest: TransactionRequestEnvelope | undefined; +} + +/** The payload GUARDIAN receives for `draft`. It carries no approval: a proposer signs later. */ +function deltaPayloadOf(draft: ProposalDraft) { + return { + txSummary: { data: draft.txSummaryBase64 }, + signatures: [], + metadata: ProposalMetadataCodec.toGuardian(draft.metadata), + ...(draft.transactionRequest ? { transactionRequest: draft.transactionRequest } : {}), + }; +} export interface CreateProposalOptions { /** @@ -1412,7 +1430,7 @@ export class Multisig { } await this.refreshConfigFromStore(); this.assertKeySchemeMatches(); - return this.pushProposal(nonce, txSummaryBase64, metadata, undefined); + return this.pushDraft({ nonce, txSummaryBase64, metadata, transactionRequest: undefined }); } /** @@ -1432,63 +1450,26 @@ export class Multisig { * account and signer. Mirrors the Rust `MultisigClient::check_transaction`. */ async checkTransaction(transaction: CheckableTransaction): Promise { - let result: CheckProposalResult | undefined; - const checking = Object.create(this) as Multisig; - (checking as unknown as { pushProposal: Multisig['pushProposal'] }).pushProposal = async ( - nonce, - txSummaryBase64, - metadata, - transactionRequest, - ) => { - result = await this.guardian.checkDeltaProposal({ - accountId: this._accountId, - nonce, - deltaPayload: { - txSummary: { data: txSummaryBase64 }, - signatures: [], - metadata: ProposalMetadataCodec.toGuardian(metadata), - ...(transactionRequest ? { transactionRequest } : {}), - }, - }); - throw CHECKED; - }; - try { - await proposeOn(checking, transaction); - } catch (error) { - if (error !== CHECKED) { - throw error; - } - } - if (!result) { - throw new Error('the transaction was not built, so it was not checked'); - } - return result; + const draft = await this.draftFor(transaction); + return this.guardian.checkDeltaProposal({ + accountId: this._accountId, + nonce: draft.nonce, + deltaPayload: deltaPayloadOf(draft), + }); } /** - * Push a proposal to GUARDIAN and parse the reply against the signer config - * the caller refreshed from the store. + * Push a drafted proposal to GUARDIAN and parse the reply against the signer config the + * caller refreshed from the store. */ - private async pushProposal( - nonce: number, - txSummaryBase64: string, - metadata: ProposalMetadata, - transactionRequest: TransactionRequestEnvelope | undefined, - ): Promise { - const guardianMetadata = ProposalMetadataCodec.toGuardian(metadata); - + private async pushDraft(draft: ProposalDraft): Promise { const response = await this.guardian.pushDeltaProposal({ accountId: this._accountId, - nonce, - deltaPayload: { - txSummary: { data: txSummaryBase64 }, - signatures: [], - metadata: guardianMetadata, - ...(transactionRequest ? { transactionRequest } : {}), - }, + nonce: draft.nonce, + deltaPayload: deltaPayloadOf(draft), }); - const proposal = this.proposalFactory().fromDelta(response.delta, response.commitment, metadata); + const proposal = this.proposalFactory().fromDelta(response.delta, response.commitment, draft.metadata); await this.verifyProposalMetadataBinding(proposal); this.proposals.set(proposal.id, proposal); this.guardianKnownProposalIds.add(proposal.id); @@ -1496,6 +1477,43 @@ export class Multisig { return proposal; } + /** Drafts `transaction` as its typed `create*Proposal` method would, without sending it. */ + private draftFor(transaction: CheckableTransaction): Promise { + switch (transaction.type) { + case 'p2id': + return this.draftP2id( + transaction.recipientId, + transaction.faucetId, + transaction.amount, + transaction.options, + ); + case 'addSigner': + return this.draftAddSigner(transaction.newSigner, transaction.options); + case 'removeSigner': + return this.draftRemoveSigner(transaction.signer, transaction.options); + case 'changeThreshold': + return this.draftChangeThreshold(transaction.newThreshold, transaction.options); + case 'updateProcedureThreshold': + return this.draftUpdateProcedureThreshold( + transaction.procedure, + transaction.threshold, + transaction.options, + ); + case 'consumeNotes': + return this.draftConsumeNotes(transaction.noteIds, transaction.options); + case 'custom': + return this.draftCustom( + transaction.transactionRequestBytes, + transaction.proposalType, + transaction.options, + ); + default: { + const unreachable: never = transaction; + throw new Error(`Unknown transaction ${JSON.stringify(unreachable)}`); + } + } + } + /** * Ask Guardian to prove and submit a threshold-met proposal. Resolves once the request is * accepted; {@link executionStatus} reports the outcome. The proposal must have been created @@ -1586,6 +1604,14 @@ export class Multisig { options: CreateSignerProposalOptions = {}, ...legacyArgs: never[] ): Promise { + return this.pushDraft(await this.draftAddSigner(newSigner, options, legacyArgs)); + } + + private async draftAddSigner( + newSigner: SignerInput, + options: CreateSignerProposalOptions = {}, + legacyArgs: never[] = [], + ): Promise { await this.refreshConfigFromStore(); assertProposalOptionsBag('createAddSignerProposal', options, legacyArgs); this.assertKeySchemeMatches(); @@ -1624,7 +1650,7 @@ export class Multisig { description: `Add signer ${newCommitment.slice(0, 10)}...`, }; - return this.pushProposal(proposalNonce, summaryBase64, metadata, transactionRequest); + return { nonce: proposalNonce, txSummaryBase64: summaryBase64, metadata, transactionRequest }; } /** @@ -1639,6 +1665,14 @@ export class Multisig { options: CreateSignerProposalOptions = {}, ...legacyArgs: never[] ): Promise { + return this.pushDraft(await this.draftRemoveSigner(signerToRemove, options, legacyArgs)); + } + + private async draftRemoveSigner( + signerToRemove: string, + options: CreateSignerProposalOptions = {}, + legacyArgs: never[] = [], + ): Promise { await this.refreshConfigFromStore(); assertProposalOptionsBag('createRemoveSignerProposal', options, legacyArgs); this.assertKeySchemeMatches(); @@ -1683,7 +1717,7 @@ export class Multisig { description: `Remove signer ${signerToRemove.slice(0, 10)}...`, }; - return this.pushProposal(proposalNonce, summaryBase64, metadata, transactionRequest); + return { nonce: proposalNonce, txSummaryBase64: summaryBase64, metadata, transactionRequest }; } /** @@ -1696,6 +1730,13 @@ export class Multisig { newThreshold: number, options: CreateProposalOptions = {}, ): Promise { + return this.pushDraft(await this.draftChangeThreshold(newThreshold, options)); + } + + private async draftChangeThreshold( + newThreshold: number, + options: CreateProposalOptions = {}, + ): Promise { await this.refreshConfigFromStore(); assertProposalOptionsBag('createChangeThresholdProposal', options); this.assertKeySchemeMatches(); @@ -1730,7 +1771,7 @@ export class Multisig { description: `Change threshold from ${this.threshold} to ${newThreshold}`, }; - return this.pushProposal(proposalNonce, summaryBase64, metadata, transactionRequest); + return { nonce: proposalNonce, txSummaryBase64: summaryBase64, metadata, transactionRequest }; } async createUpdateProcedureThresholdProposal( @@ -1738,6 +1779,14 @@ export class Multisig { targetThreshold: number, options: CreateProposalOptions = {}, ): Promise { + return this.pushDraft(await this.draftUpdateProcedureThreshold(targetProcedure, targetThreshold, options)); + } + + private async draftUpdateProcedureThreshold( + targetProcedure: ProcedureName, + targetThreshold: number, + options: CreateProposalOptions = {}, + ): Promise { await this.refreshConfigFromStore(); assertProposalOptionsBag('createUpdateProcedureThresholdProposal', options); this.assertKeySchemeMatches(); @@ -1782,7 +1831,7 @@ export class Multisig { description: action, }; - return this.pushProposal(proposalNonce, summaryBase64, metadata, transactionRequest); + return { nonce: proposalNonce, txSummaryBase64: summaryBase64, metadata, transactionRequest }; } /** @@ -1814,7 +1863,12 @@ export class Multisig { // sign/execute (which fetch from GUARDIAN) can find it. To leave an // unreachable GUARDIAN, use createSwitchGuardianProposalOffline instead. const proposalNonce = await this.resolveProposalNonce('createSwitchGuardianProposal', options); - return this.pushProposal(proposalNonce, summaryBase64, metadata, undefined); + return this.pushDraft({ + nonce: proposalNonce, + txSummaryBase64: summaryBase64, + metadata, + transactionRequest: undefined, + }); } /** @@ -1951,6 +2005,13 @@ export class Multisig { noteIds: string[], options: CreateProposalOptions = {}, ): Promise { + return this.pushDraft(await this.draftConsumeNotes(noteIds, options)); + } + + private async draftConsumeNotes( + noteIds: string[], + options: CreateProposalOptions = {}, + ): Promise { assertProposalOptionsBag('createConsumeNotesProposal', options); if (noteIds.length === 0) { throw new Error('At least one note ID is required'); @@ -2011,7 +2072,7 @@ export class Multisig { throw new ConsumeNotesMetadataOversizeError(MAX_CONSUME_NOTES_METADATA_BYTES, metadataSize); } - return this.pushProposal(proposalNonce, summaryBase64, metadata, transactionRequest); + return { nonce: proposalNonce, txSummaryBase64: summaryBase64, metadata, transactionRequest }; } /** @@ -2031,6 +2092,16 @@ export class Multisig { options: CreateP2idProposalOptions = {}, ...legacyArgs: never[] ): Promise { + return this.pushDraft(await this.draftP2id(recipientId, faucetId, amount, options, legacyArgs)); + } + + private async draftP2id( + recipientId: string, + faucetId: string, + amount: bigint, + options: CreateP2idProposalOptions = {}, + legacyArgs: never[] = [], + ): Promise { await this.refreshConfigFromStore(); assertProposalOptionsBag('createP2idProposal', options, legacyArgs); this.assertKeySchemeMatches(); @@ -2070,7 +2141,7 @@ export class Multisig { description: `Send ${amount} of asset ${faucetId.slice(0, 10)}... to ${recipientId.slice(0, 10)}...`, }; - return this.pushProposal(proposalNonce, summaryBase64, metadata, transactionRequest); + return { nonce: proposalNonce, txSummaryBase64: summaryBase64, metadata, transactionRequest }; } /** @@ -2844,6 +2915,14 @@ export class Multisig { proposalType: string, options: CreateProposalOptions = {}, ): Promise { + return this.pushDraft(await this.draftCustom(transactionRequestBytes, proposalType, options)); + } + + private async draftCustom( + transactionRequestBytes: Uint8Array, + proposalType: string, + options: CreateProposalOptions = {}, + ): Promise { await this.refreshConfigFromStore(); assertProposalOptionsBag('createCustomProposal', options); this.assertKeySchemeMatches(); @@ -2875,7 +2954,7 @@ export class Multisig { requiredSignatures: this.getEffectiveThreshold('custom'), }; - return this.pushProposal(proposalNonce, summaryBase64, metadata, transactionRequest); + return { nonce: proposalNonce, txSummaryBase64: summaryBase64, metadata, transactionRequest }; } /** @@ -3952,39 +4031,3 @@ function decodeEmbeddedConsumeNotes(metadata: ConsumeNotesProposalMetadata): Not } return decoded; } - -function proposeOn(multisig: Multisig, transaction: CheckableTransaction): Promise { - switch (transaction.type) { - case 'p2id': - return multisig.createP2idProposal( - transaction.recipientId, - transaction.faucetId, - transaction.amount, - transaction.options, - ); - case 'addSigner': - return multisig.createAddSignerProposal(transaction.newSigner, transaction.options); - case 'removeSigner': - return multisig.createRemoveSignerProposal(transaction.signer, transaction.options); - case 'changeThreshold': - return multisig.createChangeThresholdProposal(transaction.newThreshold, transaction.options); - case 'updateProcedureThreshold': - return multisig.createUpdateProcedureThresholdProposal( - transaction.procedure, - transaction.threshold, - transaction.options, - ); - case 'consumeNotes': - return multisig.createConsumeNotesProposal(transaction.noteIds, transaction.options); - case 'custom': - return multisig.createCustomProposal( - transaction.transactionRequestBytes, - transaction.proposalType, - transaction.options, - ); - default: { - const unreachable: never = transaction; - throw new Error(`Unknown transaction ${JSON.stringify(unreachable)}`); - } - } -} From 9602b1d6346a394bd5f310638f1c17d5f8d15b26 Mon Sep 17 00:00:00 2001 From: Zeljko Date: Tue, 10 Nov 2026 12:07:33 +0100 Subject: [PATCH 092/105] feat(modules)!: per-account params versions, so account writes share no lock (#251) Every module write used to lock and bump the one module_state_version row. That row was also the replicas' instance cache key and the version each signed delta recorded, so registering an account with default modules waited for every other registration and operator write and made every replica reload its instances. module_state_version now moves only on instance writes (global params, enabled flags). Each account has its own version in the new module_account_version table, bumped and locked by writes to that account's layers and assignment, including the default copy at registration, which is refused once the account's version is non-zero. The evaluation snapshot returns both versions in one call. Signed deltas, fail-open audit events and denial logs record params_version and account_params_version; account writes are audited with the account version; the operator account view reports it. History entries carry the version of their own counter and an id, and the history pages by id (before=), with a (module_id, id) index. The filesystem store keeps both counters in its state file, moving each once per write including writes that change nothing, and upgrades an older file from its history. The down migration restores the single version above every recorded one. Operator client types and parsers, OpenAPI, the dashboard, runbook and troubleshooting docs, RFC 0002 section 2.2 and the speckit data model are updated. --- .../down.sql | 109 +++++ .../up.sql | 144 +++++++ crates/server/src/api/dashboard_modules.rs | 2 + crates/server/src/audit/kinds.rs | 3 +- crates/server/src/delta_object.rs | 1 + crates/server/src/delta_summary/mod.rs | 5 +- crates/server/src/modules/admin.rs | 32 +- crates/server/src/modules/disclosure.rs | 4 +- crates/server/src/modules/mod.rs | 2 +- crates/server/src/modules/pipeline.rs | 50 ++- crates/server/src/modules/postgres_store.rs | 254 ++++++++++-- crates/server/src/modules/store.rs | 372 +++++++++++++++--- crates/server/src/modules/testing.rs | 4 +- .../server/src/services/ack_delta_internal.rs | 2 + .../dashboard_account_delta_detail.rs | 1 + docs/DASHBOARD.md | 24 +- docs/TROUBLESHOOTING.md | 3 +- docs/architecture/services.md | 2 +- docs/openapi-client.json | 10 +- docs/openapi-dashboard.json | 26 +- docs/openapi.json | 19 +- docs/rfcs/0002-guardian-modules.md | 16 +- docs/runbooks/policy-modules.md | 4 +- .../guardian-operator-client/src/http.test.ts | 18 +- packages/guardian-operator-client/src/http.ts | 3 + .../guardian-operator-client/src/types.ts | 14 +- .../contracts/operator-modules-api.md | 8 +- .../251-guardian-modules/data-model.md | 10 +- 28 files changed, 978 insertions(+), 164 deletions(-) create mode 100644 crates/server/migrations/2026-11-10-000002_module_account_version/down.sql create mode 100644 crates/server/migrations/2026-11-10-000002_module_account_version/up.sql diff --git a/crates/server/migrations/2026-11-10-000002_module_account_version/down.sql b/crates/server/migrations/2026-11-10-000002_module_account_version/down.sql new file mode 100644 index 00000000..77014a26 --- /dev/null +++ b/crates/server/migrations/2026-11-10-000002_module_account_version/down.sql @@ -0,0 +1,109 @@ +-- Back to one params version for every module write. Account writes made meanwhile committed +-- as their account's versions, which can be above the instance version, and a write that +-- changed nothing moved its account's version without a history row; the single version +-- continues above every one of them, so no later write reuses a number a delta recorded. +UPDATE module_state_version + SET version = GREATEST(version, + (SELECT COALESCE(MAX(version), 0) FROM module_params_history), + (SELECT COALESCE(MAX(version), 0) FROM module_account_version)); + +DROP INDEX module_params_history_module_idx; +CREATE INDEX module_params_history_module_idx ON module_params_history (module_id, version); + +DROP FUNCTION guardian_module_snapshot(TEXT, BIGINT); + +CREATE FUNCTION guardian_module_snapshot( + p_account_id TEXT, + p_cached_version BIGINT +) +RETURNS TABLE ( + version BIGINT, + instances JSONB, + account_params JSONB +) +LANGUAGE plpgsql STABLE AS $$ +DECLARE + v_version BIGINT; + v_instances JSONB; + v_account JSONB; +BEGIN + SELECT s.version INTO v_version FROM module_state_version s; + + IF p_cached_version IS DISTINCT FROM v_version THEN + SELECT COALESCE(jsonb_agg(jsonb_build_object( + 'module_id', i.module_id, + 'enabled', i.enabled, + 'global_params', i.global_params, + 'seeded_params', i.seeded_params, + 'updated_at', i.updated_at, + 'updated_by', i.updated_by + ) ORDER BY i.module_id), '[]'::jsonb) + INTO v_instances + FROM module_instances i; + END IF; + + SELECT COALESCE(jsonb_agg(jsonb_build_object( + 'account_id', p.account_id, + 'module_id', p.module_id, + 'kind', p.kind, + 'position', p.position, + 'params', p.params, + 'updated_at', p.updated_at, + 'updated_by', p.updated_by + ) ORDER BY p.position, p.module_id), '[]'::jsonb) + INTO v_account + FROM module_account_params p + WHERE p.account_id = p_account_id; + + RETURN QUERY SELECT v_version, v_instances, v_account; +END; +$$; + +CREATE OR REPLACE FUNCTION guardian_module_seed_assignment( + p_account_id TEXT, + p_modules JSONB, + p_operator TEXT, + p_reason TEXT, + p_changed_at TIMESTAMPTZ +) +RETURNS BIGINT +LANGUAGE plpgsql AS $$ +DECLARE + v_version BIGINT; +BEGIN + PERFORM 1 FROM module_state_version FOR UPDATE; + + IF EXISTS (SELECT 1 FROM module_account_params + WHERE account_id = p_account_id AND kind = 'assignment') + OR EXISTS (SELECT 1 FROM module_params_history + WHERE account_id = p_account_id) THEN + RETURN NULL; + END IF; + + UPDATE module_state_version SET version = version + 1 + RETURNING version INTO v_version; + + INSERT INTO module_account_params + (account_id, module_id, kind, position, params, updated_at, updated_by) + SELECT p_account_id, m.value->>'module_id', 'assignment', + (m.ordinality - 1)::INTEGER, m.value->'params', p_changed_at, p_operator + FROM jsonb_array_elements(p_modules) WITH ORDINALITY AS m(value, ordinality); + + INSERT INTO module_params_history + (version, module_id, account_id, previous_params, new_params, operator, reason, + changed_at) + SELECT v_version, m.value->>'module_id', p_account_id, 'null'::jsonb, + m.value->'params', p_operator, p_reason, p_changed_at + FROM jsonb_array_elements(p_modules) AS m(value) + WHERE m.value->'params' <> 'null'::jsonb + ORDER BY m.value->>'module_id'; + + RETURN v_version; +END; +$$; + +CREATE INDEX module_params_history_account_idx + ON module_params_history (account_id) + WHERE account_id IS NOT NULL; + +DROP TABLE module_account_version; diff --git a/crates/server/migrations/2026-11-10-000002_module_account_version/up.sql b/crates/server/migrations/2026-11-10-000002_module_account_version/up.sql new file mode 100644 index 00000000..d2cab7bf --- /dev/null +++ b/crates/server/migrations/2026-11-10-000002_module_account_version/up.sql @@ -0,0 +1,144 @@ +-- Per-account params versions. module_state_version now moves only on writes to the +-- instance rows, so replicas rebuild their instance cache only when an instance changes. +-- A write to one account's layers or assignment, including the default copy at +-- registration, bumps that account's row here instead: it serializes with writes to the +-- same account only, and every other account and every replica's cache is untouched. +-- A signed delta records both versions. +CREATE TABLE module_account_version ( + account_id TEXT PRIMARY KEY, + version BIGINT NOT NULL +); + +-- History rows keep the version they were written with. An account's earlier rows carry +-- global numbers, increasing in that account's write order, so its next version continues +-- above the highest of them. +INSERT INTO module_account_version (account_id, version) +SELECT account_id, MAX(version) + FROM module_params_history + WHERE account_id IS NOT NULL + GROUP BY account_id; + +DROP FUNCTION guardian_module_snapshot(TEXT, BIGINT); + +-- Everything one module evaluation reads, in one call: the instance params version, the +-- account's params version and rows and, unless the caller's cached instance version is +-- current, the instance rows. STABLE, so every statement below sees the snapshot of the +-- calling statement: the rows belong to the returned versions. +CREATE FUNCTION guardian_module_snapshot( + p_account_id TEXT, + p_cached_version BIGINT +) +RETURNS TABLE ( + version BIGINT, + account_version BIGINT, + instances JSONB, + account_params JSONB +) +LANGUAGE plpgsql STABLE AS $$ +DECLARE + v_version BIGINT; + v_account_version BIGINT; + v_instances JSONB; + v_account JSONB; +BEGIN + SELECT s.version INTO v_version FROM module_state_version s; + + SELECT COALESCE(MAX(a.version), 0) INTO v_account_version + FROM module_account_version a + WHERE a.account_id = p_account_id; + + IF p_cached_version IS DISTINCT FROM v_version THEN + SELECT COALESCE(jsonb_agg(jsonb_build_object( + 'module_id', i.module_id, + 'enabled', i.enabled, + 'global_params', i.global_params, + 'seeded_params', i.seeded_params, + 'updated_at', i.updated_at, + 'updated_by', i.updated_by + ) ORDER BY i.module_id), '[]'::jsonb) + INTO v_instances + FROM module_instances i; + END IF; + + SELECT COALESCE(jsonb_agg(jsonb_build_object( + 'account_id', p.account_id, + 'module_id', p.module_id, + 'kind', p.kind, + 'position', p.position, + 'params', p.params, + 'updated_at', p.updated_at, + 'updated_by', p.updated_by + ) ORDER BY p.position, p.module_id), '[]'::jsonb) + INTO v_account + FROM module_account_params p + WHERE p.account_id = p_account_id; + + RETURN QUERY SELECT v_version, v_account_version, v_instances, v_account; +END; +$$; + +-- The default modules a first registration copies into its account, in one call. It locks +-- only this account's version row, so registrations of different accounts and operator +-- writes to other accounts or to instances never wait for it. +-- +-- p_modules is the assignment in evaluation order: +-- [{"module_id": "...", "params": {...}}, ...]. Writes only into an account no write has +-- touched yet (version 0, no assignment), so an operator's earlier write always wins. +-- Returns the account version the copy committed as, or NULL when it wrote nothing (the +-- version does not move then). +CREATE OR REPLACE FUNCTION guardian_module_seed_assignment( + p_account_id TEXT, + p_modules JSONB, + p_operator TEXT, + p_reason TEXT, + p_changed_at TIMESTAMPTZ +) +RETURNS BIGINT +LANGUAGE plpgsql AS $$ +DECLARE + v_version BIGINT; +BEGIN + INSERT INTO module_account_version (account_id, version) + VALUES (p_account_id, 0) + ON CONFLICT (account_id) DO NOTHING; + + SELECT a.version INTO v_version + FROM module_account_version a + WHERE a.account_id = p_account_id + FOR UPDATE; + + IF v_version <> 0 + OR EXISTS (SELECT 1 FROM module_account_params + WHERE account_id = p_account_id AND kind = 'assignment') THEN + RETURN NULL; + END IF; + + v_version := 1; + UPDATE module_account_version SET version = v_version WHERE account_id = p_account_id; + + INSERT INTO module_account_params + (account_id, module_id, kind, position, params, updated_at, updated_by) + SELECT p_account_id, m.value->>'module_id', 'assignment', + (m.ordinality - 1)::INTEGER, m.value->'params', p_changed_at, p_operator + FROM jsonb_array_elements(p_modules) WITH ORDINALITY AS m(value, ordinality); + + INSERT INTO module_params_history + (version, module_id, account_id, previous_params, new_params, operator, reason, + changed_at) + SELECT v_version, m.value->>'module_id', p_account_id, 'null'::jsonb, + m.value->'params', p_operator, p_reason, p_changed_at + FROM jsonb_array_elements(p_modules) AS m(value) + WHERE m.value->'params' <> 'null'::jsonb + ORDER BY m.value->>'module_id'; + + RETURN v_version; +END; +$$; + +-- The account history lookup the default copy made is gone; the version row answers it. +DROP INDEX IF EXISTS module_params_history_account_idx; + +-- A module's history is listed newest first by row id, since the versions of its global and +-- account entries come from different counters. +DROP INDEX module_params_history_module_idx; +CREATE INDEX module_params_history_module_idx ON module_params_history (module_id, id); diff --git a/crates/server/src/api/dashboard_modules.rs b/crates/server/src/api/dashboard_modules.rs index 4cc8b7c3..47db4f7c 100644 --- a/crates/server/src/api/dashboard_modules.rs +++ b/crates/server/src/api/dashboard_modules.rs @@ -86,7 +86,9 @@ pub async fn account_modules( #[derive(Debug, Deserialize, utoipa::IntoParams)] #[into_params(parameter_in = Query)] pub struct HistoryQuery { + /// Only entries whose `id` is below this one, to page backwards. before: Option, + /// At most this many entries (1 to 1,000; default 100). limit: Option, } diff --git a/crates/server/src/audit/kinds.rs b/crates/server/src/audit/kinds.rs index 7498a6f2..ce961f0b 100644 --- a/crates/server/src/audit/kinds.rs +++ b/crates/server/src/audit/kinds.rs @@ -70,7 +70,8 @@ pub const MODULES_DISABLE: &str = "modules.disable"; /// A policy module evaluation at proposal creation or account registration let through a /// module failure because the instance is `on_error = "allow"`. System-initiated /// (`operator_identity` is `system`). `payload` carries `hook`, `submitter`, `catalog_hash`, -/// `params_version` and `failed_open` (`module_id`, `layer`, `failure`), plus the +/// `params_version`, `account_params_version` and `failed_open` (`module_id`, `layer`, +/// `failure`), plus the /// `proposal_id` at proposal creation. A transaction's skips are stored with its signed delta /// instead (`modules.failed_open` on the dashboard delta detail). pub const MODULES_FAILED_OPEN: &str = "modules.failed_open"; diff --git a/crates/server/src/delta_object.rs b/crates/server/src/delta_object.rs index d3ff8b43..b8fc3fdf 100644 --- a/crates/server/src/delta_object.rs +++ b/crates/server/src/delta_object.rs @@ -901,6 +901,7 @@ mod tests { "modules": { "catalog_hash": "0xc1", "params_version": 3, + "account_params_version": 1, "failed_open": [{ "module_id": "screening", "layer": "global", "failure": "timeout" }], "signed_at": "2026-11-09T00:00:00Z", "submitter": "0xs1", diff --git a/crates/server/src/delta_summary/mod.rs b/crates/server/src/delta_summary/mod.rs index 2cc1b6e6..78aa1d2f 100644 --- a/crates/server/src/delta_summary/mod.rs +++ b/crates/server/src/delta_summary/mod.rs @@ -64,13 +64,16 @@ pub struct DeltaMetadata { } /// The policy modules' approval of a signed delta: the configuration they ran with, when and for -/// whom. Allowed evaluations are not listed: the catalog, params version and account determine +/// whom. Allowed evaluations are not listed: the catalog, the two params versions and the account determine /// which modules ran, so only failures let through by `on_error = allow` are kept. #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, utoipa::ToSchema)] pub struct ModuleApproval { /// SHA-256 of the catalog file the approving replica loaded. pub catalog_hash: String, + /// The instance params version: every instance's global params and enabled flag. pub params_version: u64, + /// The account's params version: its layers and assignment. + pub account_params_version: u64, #[serde(default, skip_serializing_if = "Vec::is_empty")] pub failed_open: Vec, /// RFC 3339 time the Guardian signed, the accounting time the modules evaluated with. diff --git a/crates/server/src/modules/admin.rs b/crates/server/src/modules/admin.rs index 1f7f22bc..33c1c8d2 100644 --- a/crates/server/src/modules/admin.rs +++ b/crates/server/src/modules/admin.rs @@ -79,6 +79,9 @@ pub struct AccountModuleEntry { #[derive(Debug, Clone, Serialize, utoipa::ToSchema)] pub struct AccountModulesView { pub account_id: String, + /// The account's params version: moves with every write to its layers or assignment, and + /// is recorded with each delta the account's modules approve. + pub account_params_version: u64, pub modules: Vec, } @@ -177,7 +180,7 @@ async fn existing_account(state: &AppState, account_id: &str) -> Result async fn version(pipeline: &ModulePipeline) -> Result { pipeline .store() - .version() + .instance_version() .await .map_err(GuardianError::StorageError) } @@ -289,11 +292,12 @@ pub async fn account_view(state: &AppState, account_id: &str) -> Result Result { let pipeline = pipeline(state)?; - let rows = pipeline - .store() - .account_params(account_id) - .await - .map_err(GuardianError::StorageError)?; + let super::pipeline::Snapshot { + account_params_version, + rows: instance_rows, + account_rows: rows, + .. + } = pipeline.snapshot(account_id).await?; let mut modules = Vec::new(); for instance in pipeline .instances() @@ -303,9 +307,9 @@ async fn view_of(state: &AppState, account_id: &str) -> Result Result pipeline.enabled(instance).await?, + Some(instance) => ModulePipeline::enabled_in(&instance_rows, instance), None => false, }, orphaned: instance.is_none(), @@ -347,6 +351,7 @@ async fn view_of(state: &AppState, account_id: &str) -> Result Result Result, GuardianError> { let account_id = account_id.to_ascii_lowercase(); - let (_, rows, account_rows) = self.snapshot(&account_id).await?; + let super::pipeline::Snapshot { + rows, account_rows, .. + } = self.snapshot(&account_id).await?; let entry = |instance: &super::registry::Instance, params: Option, account_layer: Option| { diff --git a/crates/server/src/modules/mod.rs b/crates/server/src/modules/mod.rs index 6dca0ba3..ffba68a2 100644 --- a/crates/server/src/modules/mod.rs +++ b/crates/server/src/modules/mod.rs @@ -121,7 +121,7 @@ async fn load( }; let network_id = crate::metadata::network::MidenNetworkType::from(network).as_str(); let pipeline = ModulePipeline::new(network_id, catalog, registry, store, now, limits).await?; - let version = pipeline.store().version().await?; + let version = pipeline.store().instance_version().await?; let (over_budget, orphaned) = pipeline.report_stored_assignments().await?; let builds = pipeline .instances() diff --git a/crates/server/src/modules/pipeline.rs b/crates/server/src/modules/pipeline.rs index 0b6c4ace..0d4a5660 100644 --- a/crates/server/src/modules/pipeline.rs +++ b/crates/server/src/modules/pipeline.rs @@ -19,7 +19,10 @@ use crate::error::GuardianError; #[derive(Debug, Clone, PartialEq, Eq)] pub struct Evaluation { pub catalog_hash: String, + /// The instance params version: global params and enabled flags. pub params_version: u64, + /// The account's params version: its layers and assignment. + pub account_params_version: u64, pub failed_open: Vec, } @@ -43,6 +46,7 @@ impl Evaluation { "submitter": submitter, "catalog_hash": self.catalog_hash, "params_version": self.params_version, + "account_params_version": self.account_params_version, "failed_open": self.failed_open, }); if let Some(fields) = payload.as_object_mut() { @@ -107,6 +111,14 @@ struct OverBudget { worst_case: std::time::Duration, } +/// What one evaluation reads: see [`ModulePipeline::snapshot`]. +pub(super) struct Snapshot { + pub params_version: u64, + pub account_params_version: u64, + pub rows: Rows, + pub account_rows: Vec, +} + #[derive(Default)] struct Cache { version: Option, @@ -121,6 +133,7 @@ pub struct Plan<'a> { network_id: &'static str, catalog_hash: String, params_version: u64, + account_params_version: u64, views: Arc, limits: Limits, breakers: Arc, @@ -649,13 +662,17 @@ impl ModulePipeline { } /// The stored `(global params, enabled)` rows, cached per replica and refreshed when the - /// params version moves. One version read per call. + /// instance params version moves. One version read per call. pub(super) async fn rows(&self) -> Result { Ok(self.versioned_rows().await?.1) } async fn versioned_rows(&self) -> Result<(u64, Rows), GuardianError> { - let version = self.store.version().await.map_err(Self::store_error)?; + let version = self + .store + .instance_version() + .await + .map_err(Self::store_error)?; if let Ok(cache) = self.cache.read() && cache.version == Some(version) { @@ -679,14 +696,11 @@ impl ModulePipeline { Ok((version, rows)) } - /// The global rows and one account's rows as of a single params version, read in one store + /// The global rows and one account's rows with their two params versions, read in one store /// call. Without it a request could combine a new global rule with an old account layer, a /// combination no operator ever configured. The instance rows come from the cache when it - /// holds the version the store reports. - pub(super) async fn snapshot( - &self, - account_id: &str, - ) -> Result<(u64, Rows, Vec), GuardianError> { + /// holds the instance params version the store reports. + pub(super) async fn snapshot(&self, account_id: &str) -> Result { let cached = self .cache .read() @@ -707,7 +721,7 @@ impl ModulePipeline { ); if let Ok(mut cache) = self.cache.write() { *cache = Cache { - version: Some(snapshot.version), + version: Some(snapshot.instance_version), rows: rows.clone(), }; } @@ -720,7 +734,12 @@ impl ModulePipeline { )); } }; - Ok((snapshot.version, rows, snapshot.account_params)) + Ok(Snapshot { + params_version: snapshot.instance_version, + account_params_version: snapshot.account_version, + rows, + account_rows: snapshot.account_params, + }) } pub(super) fn global_params_in(rows: &Rows, instance: &Instance) -> serde_json::Value { @@ -793,7 +812,12 @@ impl ModulePipeline { if !relevant { return Ok((None, Vec::new())); } - let (params_version, rows, account_rows) = self.snapshot(&account_id).await?; + let Snapshot { + params_version, + account_params_version, + rows, + account_rows, + } = self.snapshot(&account_id).await?; let defaults: Vec = if first_registration { self.instances .iter() @@ -858,6 +882,7 @@ impl ModulePipeline { network_id: self.network_id, catalog_hash: self.catalog_hash.clone(), params_version, + account_params_version, views: self.views.clone(), limits: self.limits, breakers: self.breakers.clone(), @@ -955,6 +980,7 @@ impl Plan<'_> { network_id: _, catalog_hash, params_version, + account_params_version, views: _, limits, breakers, @@ -964,6 +990,7 @@ impl Plan<'_> { let mut approval = Evaluation { catalog_hash, params_version, + account_params_version, failed_open: Vec::new(), }; let request_id = format!("{:032x}", rand::random::()); @@ -1058,6 +1085,7 @@ impl Plan<'_> { message = %decision.message, catalog_hash = %approval.catalog_hash, params_version = approval.params_version, + account_params_version = approval.account_params_version, client_reason = ?instance.config.client_reason, "Policy module denied the request" ); diff --git a/crates/server/src/modules/postgres_store.rs b/crates/server/src/modules/postgres_store.rs index a6d7bdac..d8c8f37f 100644 --- a/crates/server/src/modules/postgres_store.rs +++ b/crates/server/src/modules/postgres_store.rs @@ -74,6 +74,8 @@ struct AccountParamsSql { #[derive(QueryableByName)] struct HistorySql { + #[diesel(sql_type = BigInt)] + id: i64, #[diesel(sql_type = BigInt)] version: i64, #[diesel(sql_type = Text)] @@ -104,7 +106,8 @@ struct ParamsSql { params: serde_json::Value, } -/// Takes the module write lock and returns the version this write commits as. +/// Takes the instance write lock and returns the instance params version this write commits +/// as. async fn bump(conn: &mut AsyncPgConnection) -> Result { let rows: Vec = diesel::sql_query( "UPDATE module_state_version SET version = version + 1 RETURNING version", @@ -117,6 +120,26 @@ async fn bump(conn: &mut AsyncPgConnection) -> Result Result { + let rows: Vec = diesel::sql_query( + "INSERT INTO module_account_version (account_id, version) VALUES ($1, 1) \ + ON CONFLICT (account_id) DO UPDATE SET version = module_account_version.version + 1 \ + RETURNING version", + ) + .bind::(account_id) + .load(conn) + .await?; + rows.into_iter() + .next() + .map(|row| row.version) + .ok_or(diesel::result::Error::NotFound) +} + #[allow(clippy::too_many_arguments)] async fn append( conn: &mut AsyncPgConnection, @@ -163,13 +186,13 @@ diesel::define_sql_function! { fn guardian_module_snapshot( account_id: Text, cached_version: Nullable, - ) -> Record<(BigInt, Nullable, Jsonb)>; + ) -> Record<(BigInt, BigInt, Nullable, Jsonb)>; } diesel::define_sql_function! { /// Typed so the statement is prepared once per connection: the default-module copy of a - /// first registration is one call, which holds the module state lock for that call only - /// (see the migration). + /// first registration is one call, which locks only that account's version row, for that + /// call only (see the migration). fn guardian_module_seed_assignment( account_id: Text, modules: Jsonb, @@ -440,7 +463,8 @@ impl ModuleStore for PgModuleStore { cached_version: Option, ) -> Result { let mut conn = self.conn().await?; - let (version, instances, account_params): ( + let (instance_version, account_version, instances, account_params): ( + i64, i64, Option, serde_json::Value, @@ -452,7 +476,8 @@ impl ModuleStore for PgModuleStore { .await .map_err(|e| format!("module snapshot: {e}"))?; Ok(ModuleSnapshot { - version: version as u64, + instance_version: instance_version as u64, + account_version: account_version as u64, instances: instances .map(serde_json::from_value) .transpose() @@ -503,7 +528,7 @@ impl ModuleStore for PgModuleStore { let (account_id, module_id) = (account_id.to_string(), module_id.to_string()); conn.transaction::(|conn| { async move { - let version = bump(conn).await?; + let version = bump_account(conn, &account_id).await?; let previous: Vec = diesel::sql_query( "DELETE FROM module_account_params WHERE account_id = $1 AND module_id = $2 \ AND kind = 'layer' RETURNING params", @@ -563,7 +588,7 @@ impl ModuleStore for PgModuleStore { let account_id = account_id.to_string(); conn.transaction::(|conn| { async move { - let version = bump(conn).await?; + let version = bump_account(conn, &account_id).await?; let removed: Vec = diesel::sql_query( "DELETE FROM module_account_params WHERE account_id = $1 \ AND kind = 'assignment' RETURNING account_id, module_id, kind, position, \ @@ -661,9 +686,9 @@ impl ModuleStore for PgModuleStore { ) -> Result, String> { let mut conn = self.conn().await?; let rows: Vec = diesel::sql_query( - "SELECT version, module_id, account_id, previous_params, new_params, operator, reason, \ - changed_at FROM module_params_history WHERE module_id = $1 \ - AND ($2::BIGINT IS NULL OR version < $2) ORDER BY version DESC, id DESC LIMIT $3", + "SELECT id, version, module_id, account_id, previous_params, new_params, operator, \ + reason, changed_at FROM module_params_history WHERE module_id = $1 \ + AND ($2::BIGINT IS NULL OR id < $2) ORDER BY id DESC LIMIT $3", ) .bind::(module_id) .bind::, _>(before.map(|before| before as i64)) @@ -674,6 +699,7 @@ impl ModuleStore for PgModuleStore { Ok(rows .into_iter() .map(|row| HistoryEntry { + id: row.id as u64, version: row.version as u64, module_id: row.module_id, account_id: row.account_id, @@ -686,7 +712,7 @@ impl ModuleStore for PgModuleStore { .collect()) } - async fn version(&self) -> Result { + async fn instance_version(&self) -> Result { let mut conn = self.conn().await?; let rows: Vec = diesel::sql_query("SELECT version FROM module_state_version") .load(&mut conn) @@ -712,9 +738,13 @@ mod tests { } } + async fn account_version(store: &PgModuleStore, account: &str) -> u64 { + store.snapshot(account, None).await.unwrap().account_version + } + #[tokio::test] #[ignore = "requires Postgres; run ./scripts/test-postgres.sh"] - async fn a_snapshot_reads_one_version_and_skips_rows_the_cache_holds() { + async fn a_snapshot_reads_both_versions_and_skips_rows_the_cache_holds() { let url = test_database_url().await; let store = PgModuleStore::new(build_postgres_pool_lazy(&url, 2).expect("pool")); let t0 = "2026-11-09T00:00:00Z"; @@ -724,13 +754,18 @@ mod tests { .seed_instance(&module, true, &json!({ "cap": 1000 }), t0) .await .unwrap(); + let instance_version = store.instance_version().await.unwrap(); store .set_layer(&account, &module, Some(json!({ "cap": 100 })), &change(t0)) .await .unwrap(); let fresh = store.snapshot(&account, None).await.unwrap(); - assert_eq!(fresh.version, store.version().await.unwrap()); + assert_eq!( + fresh.instance_version, instance_version, + "an account write leaves the instance version, so no cache is invalidated" + ); + assert_eq!(fresh.account_version, 1); let instances = fresh.instances.expect("no cached version"); let row = instances .iter() @@ -741,7 +776,10 @@ mod tests { assert_eq!(fresh.account_params[0].params, json!({ "cap": 100 })); assert_eq!(fresh.account_params[0].kind, ParamsKind::Layer); - let cached = store.snapshot(&account, Some(fresh.version)).await.unwrap(); + let cached = store + .snapshot(&account, Some(fresh.instance_version)) + .await + .unwrap(); assert!(cached.instances.is_none(), "the cache holds this version"); assert_eq!(cached.account_params, fresh.account_params); @@ -749,8 +787,15 @@ mod tests { .set_global(&module, json!({ "cap": 10 }), &change(t0)) .await .unwrap(); - let moved = store.snapshot(&account, Some(fresh.version)).await.unwrap(); - assert!(moved.version > fresh.version); + let moved = store + .snapshot(&account, Some(fresh.instance_version)) + .await + .unwrap(); + assert!(moved.instance_version > fresh.instance_version); + assert_eq!( + moved.account_version, 1, + "an instance write leaves the account's" + ); let row = moved .instances .expect("a stale cache gets the rows") @@ -758,14 +803,9 @@ mod tests { .find(|row| row.module_id == module) .unwrap(); assert_eq!(row.global_params, json!({ "cap": 10 })); - assert!( - store - .snapshot("0xnobody", None) - .await - .unwrap() - .account_params - .is_empty() - ); + let nobody = store.snapshot("0xnobody", None).await.unwrap(); + assert!(nobody.account_params.is_empty()); + assert_eq!(nobody.account_version, 0); } #[tokio::test] @@ -777,7 +817,7 @@ mod tests { let t0 = "2026-10-15T00:00:00Z"; let module = format!("blocklist-{}", rand::random::()); let account = format!("0xacc{}", rand::random::()); - let start = store.version().await.unwrap(); + let start = store.instance_version().await.unwrap(); store .seed_instance(&module, true, &json!({ "denylist": ["0xaaa"] }), t0) @@ -795,7 +835,7 @@ mod tests { ) .await .unwrap(); - store + let layer = store .set_layer( &account, &module, @@ -804,7 +844,7 @@ mod tests { ) .await .unwrap(); - store + let assignment = store .set_assignment( &account, vec![Assigned { @@ -815,6 +855,11 @@ mod tests { ) .await .unwrap(); + assert_eq!( + (layer, assignment), + (1, 2), + "the account counts its own writes" + ); let instance = other_replica .instances() @@ -837,15 +882,19 @@ mod tests { assert_eq!(history.len(), 3); assert_eq!(history[0].account_id.as_deref(), Some(account.as_str())); let older = other_replica - .history(&module, Some(history[0].version), 1) + .history(&module, Some(history[0].id), 1) .await .unwrap(); assert_eq!( older, vec![history[1].clone()], - "paged below a version, newest first" + "paged below an entry, newest first" + ); + assert_eq!( + other_replica.instance_version().await.unwrap(), + start + 2, + "the seed and the global write; the account's writes have their own version" ); - assert_eq!(other_replica.version().await.unwrap(), start + 4); store .set_layer(&account, &module, None, &change(t0)) @@ -875,14 +924,14 @@ mod tests { #[tokio::test] #[ignore = "requires Postgres; run ./scripts/test-postgres.sh"] - async fn concurrent_writes_serialize_and_the_version_follows_commit_order() { + async fn concurrent_writes_to_an_account_serialize_and_its_version_counts_them() { let url = test_database_url().await; let store = std::sync::Arc::new(PgModuleStore::new( build_postgres_pool_lazy(&url, 8).expect("pool"), )); let account = format!("0xacc{}", rand::random::()); let t0 = "2026-10-15T00:00:00Z"; - let before = store.version().await.unwrap(); + let before = store.instance_version().await.unwrap(); let writes = (0..8).map(|n| { let store = store.clone(); let account = account.clone(); @@ -904,7 +953,8 @@ mod tests { } let rows = store.account_params(&account).await.unwrap(); assert_eq!(rows.len(), 1, "one replacement wins, never a union"); - assert!(store.version().await.unwrap() >= before + 8); + assert_eq!(account_version(&store, &account).await, 8); + assert_eq!(store.instance_version().await.unwrap(), before); } #[tokio::test] @@ -926,7 +976,7 @@ mod tests { .await .unwrap() ); - let before = store.version().await.unwrap(); + assert_eq!(account_version(&store, &account).await, 1); assert!( !store .seed_assignment(&account, copy(), &change(t0)) @@ -935,8 +985,8 @@ mod tests { "an existing assignment is kept" ); assert_eq!( - store.version().await.unwrap(), - before, + account_version(&store, &account).await, + 1, "a refused copy does not move the version" ); store @@ -953,6 +1003,121 @@ mod tests { assert!(store.account_params(&account).await.unwrap().is_empty()); } + #[tokio::test] + #[ignore = "requires Postgres; run ./scripts/test-postgres.sh"] + async fn an_operator_write_that_changed_nothing_still_blocks_the_default_copy() { + let url = test_database_url().await; + let store = PgModuleStore::new(build_postgres_pool_lazy(&url, 2).expect("pool")); + let account = format!("0xnoop{}", rand::random::()); + store + .set_assignment(&account, Vec::new(), &change("2026-11-10T00:00:00Z")) + .await + .unwrap(); + let copied = store + .seed_assignment( + &account, + vec![Assigned { + module_id: "screening".into(), + params: json!({}), + }], + &change("2026-11-10T00:00:00Z"), + ) + .await + .unwrap(); + assert!(!copied, "the operator wrote the account first"); + assert!(store.account_params(&account).await.unwrap().is_empty()); + assert_eq!(account_version(&store, &account).await, 1); + } + + #[tokio::test] + #[ignore = "requires Postgres; run ./scripts/test-postgres.sh"] + async fn concurrent_default_copies_of_one_account_write_once() { + let url = test_database_url().await; + let store = std::sync::Arc::new(PgModuleStore::new( + build_postgres_pool_lazy(&url, 8).expect("pool"), + )); + let account = format!("0xrace{}", rand::random::()); + let copies = (0..8).map(|n| { + let store = store.clone(); + let account = account.clone(); + tokio::spawn(async move { + store + .seed_assignment( + &account, + vec![Assigned { + module_id: "screening".into(), + params: json!({ "copy": n }), + }], + &change("2026-11-10T00:00:00Z"), + ) + .await + .unwrap() + }) + }); + let mut written = 0; + for copy in copies { + written += usize::from(copy.await.unwrap()); + } + assert_eq!(written, 1, "exactly one registration copies the defaults"); + assert_eq!(store.account_params(&account).await.unwrap().len(), 1); + assert_eq!(account_version(&store, &account).await, 1); + } + + #[tokio::test] + #[ignore = "requires Postgres; run ./scripts/test-postgres.sh"] + async fn a_default_copy_racing_an_operator_write_never_overwrites_it() { + let url = test_database_url().await; + let store = std::sync::Arc::new(PgModuleStore::new( + build_postgres_pool_lazy(&url, 4).expect("pool"), + )); + for _ in 0..10 { + let account = format!("0xrace{}", rand::random::()); + let operator = Assigned { + module_id: "operator-choice".into(), + params: json!({ "set_by": "operator" }), + }; + let seed = { + let (store, account) = (store.clone(), account.clone()); + tokio::spawn(async move { + store + .seed_assignment( + &account, + vec![Assigned { + module_id: "screening".into(), + params: json!({ "set_by": "catalog" }), + }], + &change("2026-11-10T00:00:00Z"), + ) + .await + .unwrap() + }) + }; + let write = { + let (store, account, operator) = (store.clone(), account.clone(), operator.clone()); + tokio::spawn(async move { + store + .set_assignment(&account, vec![operator], &change("2026-11-10T00:00:00Z")) + .await + .unwrap() + }) + }; + let (copied, _) = (seed.await.unwrap(), write.await.unwrap()); + let rows = store.account_params(&account).await.unwrap(); + assert_eq!( + rows.iter() + .map(|row| (row.module_id.as_str(), &row.params)) + .collect::>(), + vec![(operator.module_id.as_str(), &operator.params)], + "the operator's assignment stands whichever write committed first" + ); + assert_eq!( + account_version(&store, &account).await, + 1 + u64::from(copied), + "one version per write that committed" + ); + } + } + #[tokio::test] #[ignore = "requires Postgres; run ./scripts/test-postgres.sh"] async fn a_default_copy_keeps_its_order_and_records_each_module() { @@ -961,7 +1126,7 @@ mod tests { let run = rand::random::(); let account = format!("0xorder{run}"); let (second, first) = (format!("a-second-{run}"), format!("z-first-{run}")); - let before = store.version().await.unwrap(); + let instance_version = store.instance_version().await.unwrap(); assert!( store .seed_assignment( @@ -981,8 +1146,13 @@ mod tests { .await .unwrap() ); - let version = store.version().await.unwrap(); - assert_eq!(version, before + 1, "one copy is one version"); + let version = account_version(&store, &account).await; + assert_eq!(version, 1, "one copy is one version"); + assert_eq!( + store.instance_version().await.unwrap(), + instance_version, + "a registration does not touch the instance version" + ); let rows = store.account_params(&account).await.unwrap(); assert_eq!( rows.iter() @@ -1022,7 +1192,7 @@ mod tests { .set_global(&module, json!({ "new_name": 100 }), &change(t0)) .await .unwrap(); - let before = store.version().await.unwrap(); + let before = store.instance_version().await.unwrap(); assert_eq!( store .set_global_if( @@ -1037,7 +1207,7 @@ mod tests { "the stale expectation does not write" ); assert_eq!( - store.version().await.unwrap(), + store.instance_version().await.unwrap(), before, "and does not move the version" ); diff --git a/crates/server/src/modules/store.rs b/crates/server/src/modules/store.rs index 32bce609..3a482044 100644 --- a/crates/server/src/modules/store.rs +++ b/crates/server/src/modules/store.rs @@ -62,6 +62,12 @@ pub struct AccountModule { #[derive(Debug, Clone, PartialEq, Serialize, Deserialize, utoipa::ToSchema)] pub struct HistoryEntry { + /// The entry's place in the history, increasing in write order: the cursor a page of + /// history is read below. + #[serde(default)] + pub id: u64, + /// The params version the write committed as: the instance params version for an entry + /// without `account_id`, that account's params version for one with it. pub version: u64, pub module_id: String, #[serde(default, skip_serializing_if = "Option::is_none")] @@ -90,7 +96,10 @@ pub struct Change<'a> { } /// Module state every replica reads. Each write updates its rows and appends the history in -/// one transaction; the highest history version is the params version. +/// one transaction. There are two kinds of params version: the instance params version moves +/// with every write to the instance rows and keys each replica's instance cache, and each +/// account's params version moves with every write to that account's rows. A write to one +/// account therefore never invalidates a cache or waits for a write to another account. #[async_trait] pub trait ModuleStore: Send + Sync { /// Inserts the instance row the first time `module_id` is seen; later calls do nothing. @@ -105,9 +114,9 @@ pub trait ModuleStore: Send + Sync { async fn instances(&self) -> Result, String>; /// Switches an instance on or off for every account. Recorded in the history as - /// `{"enabled": previous}` to `{"enabled": new}`, so the version moves and caches refresh. - /// Like every operator write, returns the params version the write committed as, so the - /// audit entry of the write names that version and not one read afterwards. + /// `{"enabled": previous}` to `{"enabled": new}`, so the instance params version moves and + /// caches refresh. Like every operator write, returns the version the write committed as, + /// so the audit entry of the write names that version and not one read afterwards. async fn set_enabled( &self, module_id: &str, @@ -136,8 +145,9 @@ pub trait ModuleStore: Send + Sync { async fn account_params(&self, account_id: &str) -> Result, String>; - /// What one evaluation reads, as of one params version: the account's rows and, unless - /// `cached_version` is that version, the instance rows. + /// What one evaluation reads, in one read: the instance params version, the account's + /// params version and rows and, unless `cached_version` is the instance params version, + /// the instance rows. async fn snapshot( &self, account_id: &str, @@ -149,6 +159,8 @@ pub trait ModuleStore: Send + Sync { /// account and can be large. async fn account_modules(&self) -> Result, String>; + /// Sets or removes the account's layer on a `scope = all` instance. Returns the account + /// params version the write committed as. async fn set_layer( &self, account_id: &str, @@ -157,6 +169,8 @@ pub trait ModuleStore: Send + Sync { change: &Change<'_>, ) -> Result; + /// Replaces the account's assignment. Returns the account params version the write + /// committed as. async fn set_assignment( &self, account_id: &str, @@ -164,9 +178,10 @@ pub trait ModuleStore: Send + Sync { change: &Change<'_>, ) -> Result; - /// Writes `modules` as the account's assignment only when it has neither an assignment nor - /// any assignment history, which is how `default` instances reach a newly registered - /// account; an operator's earlier write always wins. Returns whether it wrote. + /// Writes `modules` as the account's assignment only when it has no assignment and no + /// write has touched its rows yet (account params version 0), which is how `default` + /// instances reach a newly registered account; an operator's earlier write always wins. + /// Returns whether it wrote. async fn seed_assignment( &self, account_id: &str, @@ -174,7 +189,8 @@ pub trait ModuleStore: Send + Sync { change: &Change<'_>, ) -> Result; - /// The module's history, newest first: at most `limit` entries below version `before`. + /// The module's history, newest first: at most `limit` entries whose `id` is below + /// `before`. async fn history( &self, module_id: &str, @@ -182,13 +198,15 @@ pub trait ModuleStore: Send + Sync { limit: usize, ) -> Result, String>; - async fn version(&self) -> Result; + /// The instance params version: the version of the latest write to the instance rows. + async fn instance_version(&self) -> Result; } /// See [`ModuleStore::snapshot`]. #[derive(Debug, Clone)] pub struct ModuleSnapshot { - pub version: u64, + pub instance_version: u64, + pub account_version: u64, pub instances: Option>, pub account_params: Vec, } @@ -198,11 +216,46 @@ struct Tables { instances: BTreeMap, account_params: Vec, history: Vec, + instance_version: u64, + account_versions: BTreeMap, } impl Tables { - fn version(&self) -> u64 { - self.history.last().map_or(0, |entry| entry.version) + fn instance_version(&self) -> u64 { + self.instance_version + } + + fn account_version(&self, account_id: &str) -> u64 { + self.account_versions.get(account_id).copied().unwrap_or(0) + } + + /// Moves the version a write commits as, once per write however many history entries it + /// appends: the instance version for `None`, that account's for `Some`. + fn bump(&mut self, account_id: Option<&str>) -> u64 { + let version = match account_id { + None => &mut self.instance_version, + Some(account_id) => self + .account_versions + .entry(account_id.to_string()) + .or_default(), + }; + *version += 1; + *version + } + + /// The versions a state file without them implies: the highest of each scope's history + /// entries. + fn versions_from_history(&mut self) { + for entry in &self.history { + let version = match entry.account_id.as_deref() { + None => &mut self.instance_version, + Some(account_id) => self + .account_versions + .entry(account_id.to_string()) + .or_default(), + }; + *version = (*version).max(entry.version); + } } fn account_rows(&self, account_id: &str) -> Vec { @@ -218,14 +271,16 @@ impl Tables { fn append( &mut self, + version: u64, module_id: &str, account_id: Option<&str>, previous: serde_json::Value, new: serde_json::Value, change: &Change<'_>, ) { - let version = self.version() + 1; + let id = self.history.len() as u64 + 1; self.history.push(HistoryEntry { + id, version, module_id: module_id.to_string(), account_id: account_id.map(str::to_string), @@ -256,6 +311,10 @@ struct Snapshot { instances: Vec, account_params: Vec, history: Vec, + #[serde(default)] + instance_version: u64, + #[serde(default)] + account_versions: BTreeMap, } /// The filesystem backend's copy of the three tables. @@ -278,6 +337,8 @@ fn write_snapshot(dir: &std::path::Path, tables: &Tables) -> Result<(), String> instances: tables.instances.values().cloned().collect(), account_params: tables.account_params.clone(), history: tables.history.clone(), + instance_version: tables.instance_version, + account_versions: tables.account_versions.clone(), }; let json = serde_json::to_vec_pretty(&snapshot).map_err(|e| e.to_string())?; let path = dir.join(STATE_FILE); @@ -304,15 +365,23 @@ impl FsModuleStore { std::fs::create_dir_all(&dir) .map_err(|e| format!("cannot create {}: {e}", dir.display()))?; let snapshot = read_snapshot(&dir)?; - let tables = Tables { + let mut tables = Tables { instances: snapshot .instances .into_iter() .map(|row| (row.module_id.clone(), row)) .collect(), account_params: snapshot.account_params, - history: snapshot.history, + history: snapshot + .history + .into_iter() + .zip(1u64..) + .map(|(entry, id)| HistoryEntry { id, ..entry }) + .collect(), + instance_version: snapshot.instance_version, + account_versions: snapshot.account_versions, }; + tables.versions_from_history(); Ok(Self { tables: RwLock::new(tables), dir: Some(dir), @@ -367,7 +436,9 @@ impl ModuleStore for FsModuleStore { reason: "seeded from the catalog file", at: at.to_string(), }; + let version = tables.bump(None); tables.append( + version, module_id, None, serde_json::Value::Null, @@ -396,14 +467,16 @@ impl ModuleStore for FsModuleStore { let previous = std::mem::replace(&mut row.enabled, enabled); row.updated_at = change.at.clone(); row.updated_by = change.operator.to_string(); + let version = tables.bump(None); tables.append( + version, module_id, None, serde_json::json!({ "enabled": previous }), serde_json::json!({ "enabled": enabled }), change, ); - Ok(tables.version()) + Ok(version) }) } @@ -428,8 +501,9 @@ impl ModuleStore for FsModuleStore { let previous = std::mem::replace(&mut row.global_params, params.clone()); row.updated_at = change.at.clone(); row.updated_by = change.operator.to_string(); - tables.append(module_id, None, previous, params, change); - Ok(tables.version()) + let version = tables.bump(None); + tables.append(version, module_id, None, previous, params, change); + Ok(version) }) } @@ -451,8 +525,9 @@ impl ModuleStore for FsModuleStore { let previous = std::mem::replace(&mut row.global_params, params.clone()); row.updated_at = change.at.clone(); row.updated_by = change.operator.to_string(); - tables.append(module_id, None, previous, params, change); - Ok(Some(tables.version())) + let version = tables.bump(None); + tables.append(version, module_id, None, previous, params, change); + Ok(Some(version)) }) } @@ -466,10 +541,11 @@ impl ModuleStore for FsModuleStore { cached_version: Option, ) -> Result { Ok(self.read(|tables| { - let version = tables.version(); + let instance_version = tables.instance_version(); ModuleSnapshot { - version, - instances: (cached_version != Some(version)) + instance_version, + account_version: tables.account_version(account_id), + instances: (cached_version != Some(instance_version)) .then(|| tables.instances.values().cloned().collect()), account_params: tables.account_rows(account_id), } @@ -498,6 +574,7 @@ impl ModuleStore for FsModuleStore { change: &Change<'_>, ) -> Result { self.write(|tables| { + let version = tables.bump(Some(account_id)); let previous = tables.row_params(account_id, module_id, ParamsKind::Layer); tables.account_params.retain(|row| { !(row.account_id == account_id @@ -516,13 +593,14 @@ impl ModuleStore for FsModuleStore { }); } tables.append( + version, module_id, Some(account_id), previous, params.unwrap_or_default(), change, ); - Ok(tables.version()) + Ok(version) }) } @@ -553,10 +631,11 @@ impl ModuleStore for FsModuleStore { updated_by: change.operator.to_string(), }); } + let version = tables.bump(Some(account_id)); for (module_id, before, after) in assignment_changes(&previous, &modules) { - tables.append(&module_id, Some(account_id), before, after, change); + tables.append(version, &module_id, Some(account_id), before, after, change); } - Ok(tables.version()) + Ok(version) }) } @@ -571,11 +650,7 @@ impl ModuleStore for FsModuleStore { .account_params .iter() .any(|row| row.account_id == account_id && row.kind == ParamsKind::Assignment); - let history = tables - .history - .iter() - .any(|entry| entry.account_id.as_deref() == Some(account_id)); - if assigned || history || modules.is_empty() { + if assigned || tables.account_version(account_id) != 0 || modules.is_empty() { return Ok(false); } for (position, assigned) in modules.iter().enumerate() { @@ -589,8 +664,9 @@ impl ModuleStore for FsModuleStore { updated_by: change.operator.to_string(), }); } + let version = tables.bump(Some(account_id)); for (module_id, before, after) in assignment_changes(&[], &modules) { - tables.append(&module_id, Some(account_id), before, after, change); + tables.append(version, &module_id, Some(account_id), before, after, change); } Ok(true) }) @@ -608,15 +684,15 @@ impl ModuleStore for FsModuleStore { .iter() .rev() .filter(|entry| entry.module_id == module_id) - .filter(|entry| before.is_none_or(|before| entry.version < before)) + .filter(|entry| before.is_none_or(|before| entry.id < before)) .take(limit) .cloned() .collect() })) } - async fn version(&self) -> Result { - Ok(self.read(Tables::version)) + async fn instance_version(&self) -> Result { + Ok(self.read(Tables::instance_version)) } } @@ -679,7 +755,15 @@ mod tests { let rows = store.instances().await.unwrap(); assert_eq!(rows[0].global_params, json!({ "a": 2 })); assert_eq!(rows[0].seeded_params, json!({ "a": 1 })); - assert_eq!(store.version().await.unwrap(), 2); + assert_eq!(store.instance_version().await.unwrap(), 2); + } + + async fn account_version(store: &FsModuleStore, account_id: &str) -> u64 { + store + .snapshot(account_id, None) + .await + .unwrap() + .account_version } #[tokio::test] @@ -695,20 +779,12 @@ mod tests { params: json!({}), }] }; - let writes = [ + let instance_writes = [ store .set_global("caps", json!({ "a": 1 }), &change()) .await .unwrap(), store.set_enabled("caps", false, &change()).await.unwrap(), - store - .set_layer("0xacc", "caps", Some(json!({})), &change()) - .await - .unwrap(), - store - .set_assignment("0xother", assigned(), &change()) - .await - .unwrap(), store .set_global_if("caps", &json!({ "a": 1 }), json!({ "a": 2 }), &change()) .await @@ -716,10 +792,25 @@ mod tests { .expect("the expectation holds"), ]; assert!( - writes.windows(2).all(|pair| pair[0] < pair[1]), - "later writes commit as later versions: {writes:?}" + instance_writes.windows(2).all(|pair| pair[0] < pair[1]), + "later instance writes commit as later versions: {instance_writes:?}" + ); + assert_eq!( + instance_writes.last(), + Some(&store.instance_version().await.unwrap()) ); - assert_eq!(writes.last(), Some(&store.version().await.unwrap())); + let account_writes = [ + store + .set_layer("0xacc", "caps", Some(json!({})), &change()) + .await + .unwrap(), + store + .set_assignment("0xacc", assigned(), &change()) + .await + .unwrap(), + ]; + assert_eq!(account_writes, [1, 2], "each account counts its own writes"); + assert_eq!(account_version(&store, "0xacc").await, 2); assert_eq!( store .set_global_if("caps", &json!({ "a": 1 }), json!({ "a": 3 }), &change()) @@ -730,6 +821,111 @@ mod tests { ); } + #[tokio::test] + async fn a_write_moves_its_version_once_whatever_it_changes() { + let store = FsModuleStore::in_memory(); + let assigned = |ids: &[&str]| { + ids.iter() + .map(|id| Assigned { + module_id: id.to_string(), + params: json!({ "id": id }), + }) + .collect::>() + }; + let copied = store + .seed_assignment("0xacc", assigned(&["a", "b", "c"]), &change()) + .await + .unwrap(); + assert!(copied); + assert_eq!( + account_version(&store, "0xacc").await, + 1, + "one copy, one version" + ); + for id in ["a", "b", "c"] { + let entries = store.history(id, None, 1).await.unwrap(); + assert_eq!( + entries[0].version, 1, + "the entries of one write share its version" + ); + } + let unchanged = store + .set_assignment("0xacc", assigned(&["a", "b", "c"]), &change()) + .await + .unwrap(); + assert_eq!( + unchanged, 2, + "a write that changes nothing still commits as a version" + ); + } + + #[tokio::test] + async fn an_operator_write_that_changed_nothing_still_blocks_the_default_copy() { + let store = FsModuleStore::in_memory(); + store + .set_assignment("0xacc", Vec::new(), &change()) + .await + .unwrap(); + assert!( + store + .history("screening", None, 10) + .await + .unwrap() + .is_empty() + ); + let copied = store + .seed_assignment( + "0xacc", + vec![Assigned { + module_id: "screening".into(), + params: json!({}), + }], + &change(), + ) + .await + .unwrap(); + assert!(!copied, "the operator wrote the account first"); + assert!(store.account_params("0xacc").await.unwrap().is_empty()); + } + + #[tokio::test] + async fn an_account_write_moves_only_that_accounts_version() { + let store = FsModuleStore::in_memory(); + store + .seed_instance("caps", true, &json!({}), "t0") + .await + .unwrap(); + let instance_version = store.instance_version().await.unwrap(); + store + .set_layer("0xacc", "caps", Some(json!({ "b": 1 })), &change()) + .await + .unwrap(); + assert_eq!( + store.instance_version().await.unwrap(), + instance_version, + "replicas keep their instance cache" + ); + assert_eq!(account_version(&store, "0xacc").await, 1); + assert_eq!(account_version(&store, "0xother").await, 0); + let snapshot = store + .snapshot("0xacc", Some(instance_version)) + .await + .unwrap(); + assert!( + snapshot.instances.is_none(), + "the cached instance rows are current" + ); + store + .set_global("caps", json!({ "a": 1 }), &change()) + .await + .unwrap(); + assert_eq!( + account_version(&store, "0xacc").await, + 1, + "an instance write leaves every account's version" + ); + } + #[tokio::test] async fn the_enabled_switch_is_stored_and_moves_the_version() { let store = FsModuleStore::in_memory(); @@ -742,7 +938,7 @@ mod tests { let history = store.history("caps", None, 10).await.unwrap(); assert_eq!(history[0].previous, json!({ "enabled": true })); assert_eq!(history[0].new, json!({ "enabled": false })); - assert_eq!(store.version().await.unwrap(), 2); + assert_eq!(store.instance_version().await.unwrap(), 2); assert!( store .set_enabled("unknown", false, &change()) @@ -766,12 +962,16 @@ mod tests { .set_assignment("0xacc", assigned(&["a", "b"]), &change()) .await .unwrap(); - let version = store.version().await.unwrap(); + let version = account_version(&store, "0xacc").await; store .set_assignment("0xacc", assigned(&["b", "a"]), &change()) .await .unwrap(); - assert!(store.version().await.unwrap() > version); + assert_eq!( + account_version(&store, "0xacc").await, + version + 1, + "two modules moved, one write" + ); assert_eq!(store.history("a", None, 10).await.unwrap().len(), 2); let order: Vec<_> = store .account_params("0xacc") @@ -816,13 +1016,13 @@ mod tests { assert_eq!(history.len(), 2); assert_eq!(history[0].previous, json!({ "b": 1 })); let older = store - .history("blocklist", Some(history[0].version), 1) + .history("blocklist", Some(history[0].id), 1) .await .unwrap(); assert_eq!( older, vec![history[1].clone()], - "paged below a version, newest first" + "paged below an entry, newest first" ); } @@ -867,6 +1067,57 @@ mod tests { assert!(store.account_params("0xnew").await.unwrap().is_empty()); } + #[tokio::test] + async fn a_state_file_without_versions_takes_them_from_its_history() { + let dir = std::env::temp_dir().join(format!("modules_{:016x}", rand::random::())); + std::fs::create_dir_all(&dir).unwrap(); + let entry = |id: u64, version: u64, account_id: Option<&str>| { + json!({ + "id": id, "version": version, "module_id": "caps", "account_id": account_id, + "previous": null, "new": {}, "operator": "0xop", "reason": "r", "at": "t" + }) + }; + let old_file = json!({ + "instances": [], + "account_params": [], + "history": [entry(1, 1, None), entry(2, 2, Some("0xacc")), entry(3, 3, None)], + }); + std::fs::write(dir.join(STATE_FILE), old_file.to_string()).unwrap(); + let store = FsModuleStore::open(dir.clone()).unwrap(); + assert_eq!(store.instance_version().await.unwrap(), 3); + assert_eq!(account_version(&store, "0xacc").await, 2); + assert!( + !store + .seed_assignment( + "0xacc", + vec![Assigned { + module_id: "caps".into(), + params: json!({}), + }], + &change(), + ) + .await + .unwrap(), + "an account with history keeps its operator's choices" + ); + std::fs::remove_dir_all(dir).ok(); + } + + #[tokio::test] + async fn a_version_moved_by_a_write_that_changed_nothing_survives_a_restart() { + let dir = std::env::temp_dir().join(format!("modules_{:016x}", rand::random::())); + { + let store = FsModuleStore::open(dir.clone()).unwrap(); + store + .set_assignment("0xacc", Vec::new(), &change()) + .await + .unwrap(); + } + let reopened = FsModuleStore::open(dir.clone()).unwrap(); + assert_eq!(account_version(&reopened, "0xacc").await, 1); + std::fs::remove_dir_all(dir).ok(); + } + #[tokio::test] async fn tables_survive_a_restart() { let dir = std::env::temp_dir().join(format!("modules_{:016x}", rand::random::())); @@ -884,7 +1135,16 @@ mod tests { assert!(dir.join(STATE_FILE).exists()); assert!(!dir.join(STATE_FILE).with_extension("tmp").exists()); let reopened = FsModuleStore::open(dir.clone()).unwrap(); - assert_eq!(reopened.version().await.unwrap(), 2); + assert_eq!(reopened.instance_version().await.unwrap(), 1); + assert_eq!(account_version(&reopened, "0xacc").await, 1); + let ids: Vec = reopened + .history("caps", None, 10) + .await + .unwrap() + .iter() + .map(|entry| entry.id) + .collect(); + assert_eq!(ids, [2, 1], "entries keep their place across a restart"); assert_eq!(reopened.account_params("0xacc").await.unwrap().len(), 1); std::fs::remove_dir_all(dir).ok(); } diff --git a/crates/server/src/modules/testing.rs b/crates/server/src/modules/testing.rs index f6b5ffcf..2dee5a68 100644 --- a/crates/server/src/modules/testing.rs +++ b/crates/server/src/modules/testing.rs @@ -421,7 +421,7 @@ impl super::store::ModuleStore for RacingStore { self.inner.history(module_id, before, limit).await } - async fn version(&self) -> Result { - self.inner.version().await + async fn instance_version(&self) -> Result { + self.inner.instance_version().await } } diff --git a/crates/server/src/services/ack_delta_internal.rs b/crates/server/src/services/ack_delta_internal.rs index 9dee0a9b..a27e8eef 100644 --- a/crates/server/src/services/ack_delta_internal.rs +++ b/crates/server/src/services/ack_delta_internal.rs @@ -134,6 +134,7 @@ pub(crate) async fn acknowledge_applied( account_id = %delta.account_id, catalog_hash = %approval.catalog_hash, params_version = approval.params_version, + account_params_version = approval.account_params_version, "Delta has no metadata to record its module approval in" ), (None, None) => {} @@ -221,6 +222,7 @@ async fn approve( Some(ModuleApproval { catalog_hash: evaluation.catalog_hash, params_version: evaluation.params_version, + account_params_version: evaluation.account_params_version, failed_open: evaluation.failed_open, signed_at: signed_at.to_rfc3339(), submitter: submitter.commitment.to_string(), diff --git a/crates/server/src/services/dashboard_account_delta_detail.rs b/crates/server/src/services/dashboard_account_delta_detail.rs index a9d10b07..7c45c33a 100644 --- a/crates/server/src/services/dashboard_account_delta_detail.rs +++ b/crates/server/src/services/dashboard_account_delta_detail.rs @@ -504,6 +504,7 @@ mod tests { let approval = ModuleApproval { catalog_hash: "0xcatalog".into(), params_version: 4, + account_params_version: 2, failed_open: vec![crate::delta_summary::FailedOpen { module_id: "screening".into(), layer: "global".into(), diff --git a/docs/DASHBOARD.md b/docs/DASHBOARD.md index 6175fe03..cbe2f460 100644 --- a/docs/DASHBOARD.md +++ b/docs/DASHBOARD.md @@ -370,22 +370,34 @@ in the params history and the audit log. A walkthrough is in the Which configuration approved a signed delta is on its detail, `GET /dashboard/accounts/{account_id}/deltas/{nonce}`, in the `modules` field: -`catalog_hash`, `params_version`, `signed_at`, `submitter`, `proposer`, and -under `failed_open` each module failure an `on_error = "allow"` instance let +`catalog_hash`, `params_version`, `account_params_version`, `signed_at`, +`submitter`, `proposer`, and under `failed_open` each module failure an `on_error = "allow"` instance let through (`module_id`, `layer`, `failure`). It is absent when no module ran for the delta, and client routes never return it. The same skips at proposal creation and account registration, where nothing is signed, are written to the audit log as `modules.failed_open` events (`operator_identity` `system`, with -the hook, submitter, catalog hash, params version and, for a proposal, its -`proposal_id`). Operator writes are audited with the params version they -committed as, or `null` for an enable or disable that changed nothing. +the hook, submitter, catalog hash, both params versions and, for a proposal, +its `proposal_id`). Operator writes are audited with the version they +committed as (`params_version` for an instance write, `account_params_version` +for a write to one account), or `null` for an enable or disable that changed +nothing. + +There are two params versions. `params_version` moves with every write to an +instance (its global params or its enabled flag) and is what each replica keys +its instance cache on; `GET /dashboard/modules` reports it. Each account has its +own `account_params_version`, which moves with every write to that account's +layers or assignment, including the default copy at registration; +`GET /dashboard/accounts/{account_id}/modules` reports it. A write to one +account therefore neither waits for writes to other accounts nor makes any +replica reload its instances. The params history gives each entry an `id`, in +write order, and the `version` it committed as; page it with `before=`. `GET /dashboard/info` reports the catalog hash this replica loaded as `backend.module_catalog_hash`. | Endpoint | Permission | Body | |---|---|---| | `GET /dashboard/modules` | `dashboard:read` | | -| `GET /dashboard/modules/{module_id}/params/history?before=&limit=` | `dashboard:read` | | +| `GET /dashboard/modules/{module_id}/params/history?before=&limit=` | `dashboard:read` | | | `GET /dashboard/accounts/{account_id}/modules` | `dashboard:read` | | | `PUT /dashboard/modules/{module_id}/params` | `policies:write_global` | `{"params": {...}, "reason": "..."}` | | `PUT /dashboard/accounts/{account_id}/modules/{module_id}/params` | `policies:write` | `{"params": {...}, "reason": "..."}` | diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md index 69620fc7..8cef1447 100644 --- a/docs/TROUBLESHOOTING.md +++ b/docs/TROUBLESHOOTING.md @@ -862,7 +862,8 @@ Guardian execution ends `failed` with `GUARDIAN_EXECUTION_MODULE_DENIED` or `Policy module denied the request` with `request_id`, `module`, `account_id`, `hook`, `submitter`, `reason_code`, `layer` (`global` or `account`), the module's `message` (never sent to clients), - `catalog_hash`, `params_version` and `client_reason`. A denial with + `catalog_hash`, `params_version`, `account_params_version` and + `client_reason`. A denial with `meta.reason_code = "policy_denied"` and no `module` comes from an instance with `client_reason = "generic"`; only this log line names it. The `request_id` is also in the module's request, so the module's own logs can diff --git a/docs/architecture/services.md b/docs/architecture/services.md index 2c022d89..5df82376 100644 --- a/docs/architecture/services.md +++ b/docs/architecture/services.md @@ -303,7 +303,7 @@ request path uses. | [`catalog.rs`](../../crates/server/src/modules/catalog.rs) | Parses the catalog: instances, kinds, scopes (`all`, `default`, `assigned`), hooks, `on_error`, disclosure. Read once at startup. | | [`registry.rs`](../../crates/server/src/modules/registry.rs), [`grpc_kind.rs`](../../crates/server/src/modules/grpc_kind.rs) | Turns catalog entries into module instances: in-process kinds registered on the builder, or the remote `grpc` kind. Runs the startup and health checks (`Describe`, params validation). | | [`secrets.rs`](../../crates/server/src/modules/secrets.rs) | Resolves the tokens, client certificates and `$secret` params a catalog names, from AWS Secrets Manager or owner-only files. | -| [`store.rs`](../../crates/server/src/modules/store.rs), [`postgres_store.rs`](../../crates/server/src/modules/postgres_store.rs) | The mutable state: enabled flags, global params, account layers and assignments, params history, one version that every write moves. Files on a filesystem build, tables on Postgres. | +| [`store.rs`](../../crates/server/src/modules/store.rs), [`postgres_store.rs`](../../crates/server/src/modules/postgres_store.rs) | The mutable state: enabled flags, global params, account layers and assignments, params history, an instance params version moved by instance writes and a version per account moved by that account's writes. Files on a filesystem build, tables on Postgres. | | [`pipeline.rs`](../../crates/server/src/modules/pipeline.rs) | Plans which instances run for an account at a hook (one store read) and runs them in order under the evaluation budget; applies `on_error`; returns what the evaluation ran with. | | [`breaker.rs`](../../crates/server/src/modules/breaker.rs), [`limits.rs`](../../crates/server/src/modules/limits.rs) | Per-instance circuit breakers fed by calls and by the `Describe` probe; the budget, size caps and probe interval. | | [`request.rs`](../../crates/server/src/modules/request.rs), [`network/miden/module_views.rs`](../../crates/server/src/network/miden/module_views.rs) | Builds what a module receives: account views before and after, the transaction projection, the registration state. Views are cached by state commitment. | diff --git a/docs/openapi-client.json b/docs/openapi-client.json index b68cfb59..a7905359 100644 --- a/docs/openapi-client.json +++ b/docs/openapi-client.json @@ -3451,14 +3451,21 @@ }, "ModuleApproval": { "type": "object", - "description": "The policy modules' approval of a signed delta: the configuration they ran with, when and for\nwhom. Allowed evaluations are not listed: the catalog, params version and account determine\nwhich modules ran, so only failures let through by `on_error = allow` are kept.", + "description": "The policy modules' approval of a signed delta: the configuration they ran with, when and for\nwhom. Allowed evaluations are not listed: the catalog, the two params versions and the account determine\nwhich modules ran, so only failures let through by `on_error = allow` are kept.", "required": [ "catalog_hash", "params_version", + "account_params_version", "signed_at", "submitter" ], "properties": { + "account_params_version": { + "type": "integer", + "format": "int64", + "description": "The account's params version: its layers and assignment.", + "minimum": 0 + }, "catalog_hash": { "type": "string", "description": "SHA-256 of the catalog file the approving replica loaded." @@ -3472,6 +3479,7 @@ "params_version": { "type": "integer", "format": "int64", + "description": "The instance params version: every instance's global params and enabled flag.", "minimum": 0 }, "proposer": { diff --git a/docs/openapi-dashboard.json b/docs/openapi-dashboard.json index 4ecc51ee..0460e192 100644 --- a/docs/openapi-dashboard.json +++ b/docs/openapi-dashboard.json @@ -2089,6 +2089,7 @@ { "name": "before", "in": "query", + "description": "Only entries whose `id` is below this one, to page backwards.", "required": false, "schema": { "type": "integer", @@ -2099,6 +2100,7 @@ { "name": "limit", "in": "query", + "description": "At most this many entries (1 to 1,000; default 100).", "required": false, "schema": { "type": "integer", @@ -2549,12 +2551,19 @@ "type": "object", "required": [ "account_id", + "account_params_version", "modules" ], "properties": { "account_id": { "type": "string" }, + "account_params_version": { + "type": "integer", + "format": "int64", + "description": "The account's params version: moves with every write to its layers or assignment, and\nis recorded with each delta the account's modules approve.", + "minimum": 0 + }, "modules": { "type": "array", "items": { @@ -4276,6 +4285,12 @@ "at": { "type": "string" }, + "id": { + "type": "integer", + "format": "int64", + "description": "The entry's place in the history, increasing in write order: the cursor a page of\nhistory is read below.", + "minimum": 0 + }, "module_id": { "type": "string" }, @@ -4300,6 +4315,7 @@ "version": { "type": "integer", "format": "int64", + "description": "The params version the write committed as: the instance params version for an entry\nwithout `account_id`, that account's params version for one with it.", "minimum": 0 } } @@ -4317,14 +4333,21 @@ }, "ModuleApproval": { "type": "object", - "description": "The policy modules' approval of a signed delta: the configuration they ran with, when and for\nwhom. Allowed evaluations are not listed: the catalog, params version and account determine\nwhich modules ran, so only failures let through by `on_error = allow` are kept.", + "description": "The policy modules' approval of a signed delta: the configuration they ran with, when and for\nwhom. Allowed evaluations are not listed: the catalog, the two params versions and the account determine\nwhich modules ran, so only failures let through by `on_error = allow` are kept.", "required": [ "catalog_hash", "params_version", + "account_params_version", "signed_at", "submitter" ], "properties": { + "account_params_version": { + "type": "integer", + "format": "int64", + "description": "The account's params version: its layers and assignment.", + "minimum": 0 + }, "catalog_hash": { "type": "string", "description": "SHA-256 of the catalog file the approving replica loaded." @@ -4338,6 +4361,7 @@ "params_version": { "type": "integer", "format": "int64", + "description": "The instance params version: every instance's global params and enabled flag.", "minimum": 0 }, "proposer": { diff --git a/docs/openapi.json b/docs/openapi.json index cf8cf249..9584394e 100644 --- a/docs/openapi.json +++ b/docs/openapi.json @@ -2252,6 +2252,7 @@ { "name": "before", "in": "query", + "description": "Only entries whose `id` is below this one, to page backwards.", "required": false, "schema": { "type": "integer", @@ -2262,6 +2263,7 @@ { "name": "limit", "in": "query", + "description": "At most this many entries (1 to 1,000; default 100).", "required": false, "schema": { "type": "integer", @@ -5637,12 +5639,19 @@ "type": "object", "required": [ "account_id", + "account_params_version", "modules" ], "properties": { "account_id": { "type": "string" }, + "account_params_version": { + "type": "integer", + "format": "int64", + "description": "The account's params version: moves with every write to its layers or assignment, and\nis recorded with each delta the account's modules approve.", + "minimum": 0 + }, "modules": { "type": "array", "items": { @@ -8482,14 +8491,21 @@ }, "ModuleApproval": { "type": "object", - "description": "The policy modules' approval of a signed delta: the configuration they ran with, when and for\nwhom. Allowed evaluations are not listed: the catalog, params version and account determine\nwhich modules ran, so only failures let through by `on_error = allow` are kept.", + "description": "The policy modules' approval of a signed delta: the configuration they ran with, when and for\nwhom. Allowed evaluations are not listed: the catalog, the two params versions and the account determine\nwhich modules ran, so only failures let through by `on_error = allow` are kept.", "required": [ "catalog_hash", "params_version", + "account_params_version", "signed_at", "submitter" ], "properties": { + "account_params_version": { + "type": "integer", + "format": "int64", + "description": "The account's params version: its layers and assignment.", + "minimum": 0 + }, "catalog_hash": { "type": "string", "description": "SHA-256 of the catalog file the approving replica loaded." @@ -8503,6 +8519,7 @@ "params_version": { "type": "integer", "format": "int64", + "description": "The instance params version: every instance's global params and enabled flag.", "minimum": 0 }, "proposer": { diff --git a/docs/rfcs/0002-guardian-modules.md b/docs/rfcs/0002-guardian-modules.md index abf406f1..f3f566d8 100644 --- a/docs/rfcs/0002-guardian-modules.md +++ b/docs/rfcs/0002-guardian-modules.md @@ -243,7 +243,7 @@ Two rules keep `default` predictable: ``` An `all` instance shows its global params and the account's layer, if any; a `default` or `assigned` instance shows the account's own params. Secret references are shown as references, never resolved. -- `GET /dashboard/modules` (permission `dashboard:read`) lists every declared instance and every stored instance flag the catalog no longer declares, with the catalog's seed value next to the stored flag, so drift between the file and the runtime state is visible without reading startup logs (seed rules below), together with the current params version and the instance's circuit state on the replica that answered (section 4.4). `enabled_drift` is true when the catalog's `enabled` differs from the stored flag, `params_drift` when the catalog's `params` differ from the params it seeded: +- `GET /dashboard/modules` (permission `dashboard:read`) lists every declared instance and every stored instance flag the catalog no longer declares, with the catalog's seed value next to the stored flag, so drift between the file and the runtime state is visible without reading startup logs (seed rules below), together with the current instance params version and the instance's circuit state on the replica that answered (section 4.4). `enabled_drift` is true when the catalog's `enabled` differs from the stored flag, `params_drift` when the catalog's `params` differ from the params it seeded: ```json { @@ -303,10 +303,11 @@ That account is then checked against `0xaaa`, `0xbbb` and `0xddd` by the global |---|---|---| | `module_instances` | Runtime state of each instance: the `enabled` flag, the global params, and the params the catalog seeded them with (for drift) | `module_id` | | `module_account_params` | Per-account params: account layers on `all` instances and assignments of `default` and `assigned` instances, told apart by `kind` (`layer` or `assignment`), with `position` for the assignment order | `(account_id, module_id)`, with an index on `module_id` | -| `module_params_history` | Append-only record of every params change and every enable or disable (recorded as `{"enabled": previous}` to `{"enabled": new}`): module, account (absent for global), previous and new value, operator, reason, time, and the params version of the write that made it | Row id; `version` is shared by the rows of one write | -| `module_state_version` | One row: the params version | None (single row) | +| `module_params_history` | Append-only record of every params change and every enable or disable (recorded as `{"enabled": previous}` to `{"enabled": new}`): module, account (absent for global), previous and new value, operator, reason, time, and the version of the write that made it: the instance params version for a global entry, the account's params version for an account entry | Row id, which orders the history and pages it; `version` is shared by the rows of one write | +| `module_state_version` | One row: the instance params version | None (single row) | +| `module_account_version` | One row per account a write has touched: the account's params version | `account_id` | -A params write takes the `module_state_version` row lock, increments it, updates its row and appends the history rows, all in one transaction. An evaluation reads the version, the global rows and the account's rows, then the version again, and retries if it moved: since every write moves it, a request never combines a global rule and an account layer that were never committed together. A write derived from an earlier read (a module migrating stored params, section 3.5) is conditional on the stored value still being the one read, so it never overwrites a newer operator write. Writes therefore serialize and the version moves in commit order, which a sequence would not give: two writes could draw versions 10 and 11, 11 could commit first, and a replica that cached at 11 would never see 10. Operator writes are rare, so serializing them costs nothing that matters. Evaluation reads the account's rows with one indexed query, only when modules are configured; global params can be cached per replica and refreshed when the latest version changes. The filesystem backend keeps the same tables in one file, `module_state.json` in `/modules` (directory overridable with `GUARDIAN_MODULES_STATE`), replaced atomically (written, synced, renamed), so a write and its history land together; deltas gain the `module_params_version` column next to `module_catalog_hash`. +There are two kinds of params version, so that a write to one account touches nothing shared. A write to an instance (its global params or its enabled flag) takes the `module_state_version` row lock, increments it, updates its row and appends the history rows, all in one transaction. A write to an account's layers or assignment, including the default copy at registration, does the same with that account's `module_account_version` row instead. Writes to one instance version or one account therefore serialize and each version moves in commit order, which a sequence would not give: two writes could draw versions 10 and 11, 11 could commit first, and a replica that cached at 11 would never see 10. Writes to different accounts never wait for each other or for instance writes, and since replicas cache only the instance rows, keyed on the instance params version, an account write invalidates no cache; the account's rows are read on every evaluation anyway. An evaluation reads both versions, the instance rows (unless its cache holds that instance version) and the account's rows in one statement, so a request never combines a global rule and an account layer that were never committed together. A write derived from an earlier read (a module migrating stored params, section 3.5) is conditional on the stored value still being the one read, so it never overwrites a newer operator write. The filesystem backend keeps the same tables in one file, `module_state.json` in `/modules` (directory overridable with `GUARDIAN_MODULES_STATE`), replaced atomically (written, synced, renamed), so a write and its history land together. Each signed delta records the catalog hash and both versions in its evaluation trace (below). | Operator API can | Operator API cannot | |---|---| @@ -335,10 +336,11 @@ Only adding an instance, removing one, or changing its kind, endpoint, auth, hoo | Field | Holds | |---|---| | `catalog_hash` | SHA-256 of the catalog file the approving replica loaded | -| `params_version` | The params version the evaluation read; the history replayed to it gives every global param, layer, assignment and enabled flag | +| `params_version` | The instance params version the evaluation read; the global history entries replayed to it give every global param and enabled flag | +| `account_params_version` | The account's params version the evaluation read; the account's history entries replayed to it give its layers and assignment | | `failed_open` | Each evaluation that failed and was let through by `on_error = allow`: module, layer and failure kind (`timeout`, `error`, `invalid_decision`, `request_unavailable`, `circuit_open`); omitted when empty, the detail goes to the log | -Allowed evaluations are not listed: the catalog, the params version and the account determine which modules ran. Proposal creation and registration sign no delta, so a failure let through there is written to the audit log instead, as a `modules.failed_open` event with the hook, submitter, catalog hash, params version, the failures and, for a proposal, its id. Denials create no delta. Each is logged with `request_id`, account, hook, module, layer, `reason_code`, the module's `message`, the catalog hash and the params version, so "why was this account refused" is answered from the logs; M2a has no API for denials, and a durable decision log is future work (section 7). A durable record of module builds per configuration, a hash of the request and the inputs not stored elsewhere (accounting time, proposer) are added with the replay tool that would consume them. +Allowed evaluations are not listed: the catalog, the two params versions and the account determine which modules ran. Proposal creation and registration sign no delta, so a failure let through there is written to the audit log instead, as a `modules.failed_open` event with the hook, submitter, catalog hash, both params versions, the failures and, for a proposal, its id. Denials create no delta. Each is logged with `request_id`, account, hook, module, layer, `reason_code`, the module's `message`, the catalog hash and both params versions, so "why was this account refused" is answered from the logs; M2a has no API for denials, and a durable decision log is future work (section 7). A durable record of module builds per configuration, a hash of the request and the inputs not stored elsewhere (accounting time, proposer) are added with the replay tool that would consume them. **Order:** `scope = all` modules in catalog order, each with its global layer first and the account's layer, if any, right after it; then the account's stored assignment in its stored order. Copied `default` modules are stored first, in catalog order, and the operator may reorder them afterwards. Evaluation stops at the first deny. `all` modules always run before the account's own modules, so when an `all` module denies, `meta.module` names it and any account-level module that would also have denied is never called. Operators debugging per-account policy should check the `all` modules first. @@ -1205,7 +1207,7 @@ None. Questions resolved in earlier revisions are kept below with their answers. | Revision | Date | Changes | |---|---|---| -| 32 | 2026-11-10 | review of the M2a implementation. Protocol version 1 reopened (section 7): `Decision.allow` and the `decision.effect` capability removed, a decision without an effect is a module failure (section 3.5); `MidenTransaction.reference_block` and `expiration_block` replaced by `bound_block`, `expiration_delta` and `approval_expiration_block`, and `nonce_delta` made unsigned (section 3.1); `network_id` is the Guardian's configured network, not the account's registered one (section 3.1); `RegistrationSubject.initial_state` is sent; `tx_fee` is set only while the fee note carries no more of the fee asset than a transaction can owe, 64 times the chain's verification base fee, and for no note on a chain that charges nothing (section 3.1). Breaker: requests a module rejects do not count, a module whose timeout is the whole budget can open it, half-open sends one trial at a time, dry-run checks neither probe nor close it (section 4.4). Fail-open skips at proposal creation and registration, where no delta is signed, are recorded as `modules.failed_open` audit events; operator writes are audited with the params version they committed as (section 2.2). A health probe that finds a module incompatible opens its breaker at once and one that gets no answer counts as a failed call (section 4.4). Startup: a known instance whose module does not answer starts unavailable instead of stopping the server, and an instance the catalog declares enabled and not operator-disableable is enabled even when stored as disabled (section 2.2). `basic-policy`: per-field id lengths, and `deny_unknown_recipients` defaults to on once the denylist names anyone (section 3.1). The conformance suite checks stated outcomes and needs a request the module must deny. `basic-policy` is split into four kinds with short param names: `spending-limit` (`max_per_transaction`, `allowed_assets`), `recipient-policy` (`allowlist`, `denylist`, `deny_unknown`), `signer-policy` (`allowlist`, `denylist`, `check`) and `code-policy` (`allowed`, `check`), each supporting only the hooks where its rule can refuse (section 3.1). SDKs: a check and a creation send the same unsigned draft, and Rust checks custom proposals (section 2.7). Body corrected to the implementation: metric names, the fixed 1000 ms timeout cap, params encoding, the `circuit_open` failure kind | +| 32 | 2026-11-10 | review of the M2a implementation. Protocol version 1 reopened (section 7): `Decision.allow` and the `decision.effect` capability removed, a decision without an effect is a module failure (section 3.5); `MidenTransaction.reference_block` and `expiration_block` replaced by `bound_block`, `expiration_delta` and `approval_expiration_block`, and `nonce_delta` made unsigned (section 3.1); `network_id` is the Guardian's configured network, not the account's registered one (section 3.1); `RegistrationSubject.initial_state` is sent; `tx_fee` is set only while the fee note carries no more of the fee asset than a transaction can owe, 64 times the chain's verification base fee, and for no note on a chain that charges nothing (section 3.1). Breaker: requests a module rejects do not count, a module whose timeout is the whole budget can open it, half-open sends one trial at a time, dry-run checks neither probe nor close it (section 4.4). Fail-open skips at proposal creation and registration, where no delta is signed, are recorded as `modules.failed_open` audit events; operator writes are audited with the params version they committed as (section 2.2). A health probe that finds a module incompatible opens its breaker at once and one that gets no answer counts as a failed call (section 4.4). Startup: a known instance whose module does not answer starts unavailable instead of stopping the server, and an instance the catalog declares enabled and not operator-disableable is enabled even when stored as disabled (section 2.2). `basic-policy`: per-field id lengths, and `deny_unknown_recipients` defaults to on once the denylist names anyone (section 3.1). The conformance suite checks stated outcomes and needs a request the module must deny. `basic-policy` is split into four kinds with short param names: `spending-limit` (`max_per_transaction`, `allowed_assets`), `recipient-policy` (`allowlist`, `denylist`, `deny_unknown`), `signer-policy` (`allowlist`, `denylist`, `check`) and `code-policy` (`allowed`, `check`), each supporting only the hooks where its rule can refuse (section 3.1). SDKs: a check and a creation send the same unsigned draft, and Rust checks custom proposals (section 2.7). Per-account params versions: a write to one account's layers or assignment, including the default copy at registration, moves only that account's version and locks only its row, so it neither waits for other accounts nor invalidates the replicas' instance cache; each signed delta records `params_version` (instances) and `account_params_version`, and the params history pages by entry id (section 2.2). Body corrected to the implementation: metric names, the fixed 1000 ms timeout cap, params encoding, the `circuit_open` failure kind | | 31 | 2026-11-09 | failures of dry-run checks do not count toward the circuit breaker, since a cosigner sends them without anyone's signature (section 4.4); the per-account budget check refuses only writes that raise an over-budget cost (section 4.3); `GUARDIAN_MODULE_UNAVAILABLE` and `GUARDIAN_EXECUTION_MODULE_UNAVAILABLE` omit `module` for an instance whose denials are generic (section 4.1); `metadata.modules` is kept out of client delta responses (section 2.2). `OutputNote.tx_fee` set only for the fee note `pay_fee` creates (section 3.1): the only `TX_FEE` note, with the derived serial number and one asset of the chain's fee faucet. Revisions 20 to 30 set it for any note with the `TX_FEE` script, which a transaction script can create with any assets, so the flag let funds past every `basic-policy` rule. No wire change; the field's meaning is narrowed | | 30 | 2026-11-09 | the secrets backend named: `GUARDIAN_MODULE_SECRET_PROVIDER` selects AWS Secrets Manager (the prod default) or owner-only files below `GUARDIAN_MODULE_SECRET_DIR`, read once when the instances are created; a secret that cannot be read fails creation, with the enabled/disabled rule of section 2.2. Field names fixed as `auth.token_secret`, `tls.client_cert_secret` and `tls.client_key_secret`; a secret name is 1 to 512 characters of letters, digits and `/_+=.@-`, and a `$secret` object has no other key (section 2.2). In-process factories read `$secret` values from `ModuleInstanceConfig::secret`. No protocol change | | 29 | 2026-11-09 | M2a implementation of `scope = default`: the copy is written right after the claim, only into an account with no assignment and no assignment history, under the module state lock, instead of in the claim's transaction on Postgres and before the claim on the filesystem; a crash in between is repaired by the unfinished-claim retry, so both backends follow one rule and no transaction spans the metadata and module stores (section 2.3). No protocol change | diff --git a/docs/runbooks/policy-modules.md b/docs/runbooks/policy-modules.md index d4bba089..ca413e10 100644 --- a/docs/runbooks/policy-modules.md +++ b/docs/runbooks/policy-modules.md @@ -73,7 +73,7 @@ module is skipped without waiting for its timeout. ``` Requests stop calling it on every replica at once. Deltas signed meanwhile - name the catalog and params version they were approved under in the + name the catalog and the two params versions they were approved under in the `modules` field of `GET /dashboard/accounts/{account_id}/deltas/{nonce}`, so the gap is auditable. 3. When the module is healthy again, enable it. Enabling runs `Describe` and @@ -107,7 +107,7 @@ the replica that answered. Symptoms: `403 GUARDIAN_MODULE_DENIED` with a `reason_code` that should not apply; the `info` log line `Policy module denied the request` names the `module`, `layer`, `reason_code`, the module's `message`, and the -`params_version` it decided under. +`params_version` and `account_params_version` it decided under. 1. Find the change: `admin GET /modules/{id}/params/history` lists every params write with its previous and new value, operator and reason. A diff --git a/packages/guardian-operator-client/src/http.test.ts b/packages/guardian-operator-client/src/http.test.ts index 494dfada..b61a568e 100644 --- a/packages/guardian-operator-client/src/http.test.ts +++ b/packages/guardian-operator-client/src/http.test.ts @@ -1271,6 +1271,7 @@ describe('GuardianOperatorHttpClient — per-account history', () => { modules: { catalog_hash: '0xcatalog', params_version: 4, + account_params_version: 2, failed_open: [{ module_id: 'screening', layer: 'global', failure: 'circuit_open' }], signed_at: '2026-11-09T10:00:00+00:00', submitter: '0xsigner', @@ -1283,6 +1284,7 @@ describe('GuardianOperatorHttpClient — per-account history', () => { expect(approved.modules).toEqual({ catalogHash: '0xcatalog', paramsVersion: 4, + accountParamsVersion: 2, failedOpen: [{ moduleId: 'screening', layer: 'global', failure: 'circuit_open' }], signedAt: '2026-11-09T10:00:00+00:00', submitter: '0xsigner', @@ -2321,6 +2323,7 @@ describe('GuardianOperatorHttpClient — account pausing (feature 001)', () => { it('reads and writes an account module set', async () => { const view = { account_id: 'acc-1', + account_params_version: 3, modules: [ { module_id: 'caps', scope: 'all', enabled: true, orphaned: false, global_params: {}, account_layer: { cap: 1 } }, { module_id: 'screening', scope: 'default', enabled: true, orphaned: false, params: { list: 'eu' } }, @@ -2338,6 +2341,7 @@ describe('GuardianOperatorHttpClient — account pausing (feature 001)', () => { ]); expect(modules.modules[0].accountLayer).toEqual({ cap: 1 }); expect(modules.modules[1].globalParams).toBeNull(); + expect(modules.accountParamsVersion).toBe(3); mockFetch.mockResolvedValueOnce(okJson(view)); await client.setAccountModules('acc-1', [{ moduleId: 'screening', params: { list: 'eu' } }], 'OP-1'); @@ -2388,18 +2392,18 @@ describe('GuardianOperatorHttpClient — account pausing (feature 001)', () => { okJson({ module_id: 'caps', entries: [ - { version: 9, account_id: 'acc-1', previous: null, new: { cap: 1 }, operator: '0xop', reason: 'OP-2', at: 't9' }, - { version: 8, previous: { a: 1 }, new: { a: 2 }, operator: '0xop', reason: 'OP-1', at: 't8' }, + { id: 12, version: 1, account_id: 'acc-1', previous: null, new: { cap: 1 }, operator: '0xop', reason: 'OP-2', at: 't9' }, + { id: 11, version: 8, previous: { a: 1 }, new: { a: 2 }, operator: '0xop', reason: 'OP-1', at: 't8' }, ], }), ); - const history = await client.getModuleParamsHistory('caps', { before: 10, limit: 2 }); - expect(history.entries.map((entry) => [entry.version, entry.accountId, entry.previous])).toEqual([ - [9, 'acc-1', null], - [8, null, { a: 1 }], + const history = await client.getModuleParamsHistory('caps', { before: 13, limit: 2 }); + expect(history.entries.map((entry) => [entry.id, entry.version, entry.accountId, entry.previous])).toEqual([ + [12, 1, 'acc-1', null], + [11, 8, null, { a: 1 }], ]); expect(mockFetch).toHaveBeenLastCalledWith( - 'https://guardian.example/dashboard/modules/caps/params/history?before=10&limit=2', + 'https://guardian.example/dashboard/modules/caps/params/history?before=13&limit=2', expect.objectContaining({ method: 'GET' }), ); }); diff --git a/packages/guardian-operator-client/src/http.ts b/packages/guardian-operator-client/src/http.ts index 82c0e712..022c20aa 100644 --- a/packages/guardian-operator-client/src/http.ts +++ b/packages/guardian-operator-client/src/http.ts @@ -2318,6 +2318,7 @@ function parseModuleApproval(value: unknown, context: string): DashboardDeltaMod return { catalogHash: requireString(record, 'catalog_hash', context), paramsVersion: requireInteger(record, 'params_version', context), + accountParamsVersion: requireInteger(record, 'account_params_version', context), failedOpen: failedOpen.map((entry, i) => { const entryContext = `${context}.failed_open[${i}]`; const failure = asRecord(entry, entryContext); @@ -2619,6 +2620,7 @@ function parseAccountModules(value: unknown): AccountModules { const record = asRecord(value, context); return { accountId: requireString(record, 'account_id', context), + accountParamsVersion: requireInteger(record, 'account_params_version', context), modules: requireArray(record, 'modules', context).map((entry) => { const item = asRecord(entry, `${context}.modules`); const itemContext = `${context}.modules`; @@ -2644,6 +2646,7 @@ function parseModuleParamsHistory(value: unknown): ModuleParamsHistory { const item = asRecord(entry, `${context}.entries`); const itemContext = `${context}.entries`; return { + id: requireInteger(item, 'id', itemContext), version: requireInteger(item, 'version', itemContext), accountId: optionalString(item, 'account_id', itemContext), previous: nullableParams(item, 'previous', itemContext), diff --git a/packages/guardian-operator-client/src/types.ts b/packages/guardian-operator-client/src/types.ts index 7a1e1c75..bf447c87 100644 --- a/packages/guardian-operator-client/src/types.ts +++ b/packages/guardian-operator-client/src/types.ts @@ -475,7 +475,10 @@ export interface DashboardDeltaModuleFailedOpen { export interface DashboardDeltaModuleApproval { /** SHA-256 of the catalog file the approving replica loaded. */ catalogHash: string; + /** The instance params version: every instance's global params and enabled flag. */ paramsVersion: number; + /** The account's params version: its layers and assignment. */ + accountParamsVersion: number; failedOpen: DashboardDeltaModuleFailedOpen[]; /** RFC 3339 time the Guardian signed. */ signedAt: string; @@ -909,6 +912,8 @@ export interface UndeclaredModuleInstance { export interface ModuleCatalog { catalogHash: string; + /** The instance params version: moves with every write to an instance's global params or + * enabled flag, never with a write to one account. */ paramsVersion: number; modules: ModuleInstance[]; undeclared: UndeclaredModuleInstance[]; @@ -931,6 +936,8 @@ export interface AccountModuleEntry { export interface AccountModules { accountId: string; + /** The account's params version: moves with every write to its layers or assignment. */ + accountParamsVersion: number; modules: AccountModuleEntry[]; } @@ -940,6 +947,11 @@ export interface ModuleAssignment { } export interface ModuleParamsHistoryEntry { + /** The entry's place in the history, increasing in write order: pass it as `before` to + * read the page after this entry. */ + id: number; + /** The version the change committed as: the instance params version for a global change, + * the account's params version for a per-account one. */ version: number; /** The account a per-account change applied to; `null` for a global change. */ accountId: string | null; @@ -959,7 +971,7 @@ export interface ModuleParamsHistory { } export interface ModuleParamsHistoryOptions { - /** Only changes with a version below this one, to page backwards. */ + /** Only entries whose `id` is below this one, to page backwards. */ before?: number; /** At most this many entries (1 to 1,000; the server defaults to 100). */ limit?: number; diff --git a/speckit/features/251-guardian-modules/contracts/operator-modules-api.md b/speckit/features/251-guardian-modules/contracts/operator-modules-api.md index 3ed9af3e..61d70284 100644 --- a/speckit/features/251-guardian-modules/contracts/operator-modules-api.md +++ b/speckit/features/251-guardian-modules/contracts/operator-modules-api.md @@ -12,7 +12,7 @@ | `PUT /dashboard/modules/{module_id}/params` | `policies:write_global` | M2a | `ParamsBody` | 200 `ModuleInstanceView` | | `PUT /dashboard/accounts/{account_id}/modules/{module_id}/params` | `policies:write` | M2a | `ParamsBody` | 200 `AccountModulesView` | | `DELETE /dashboard/accounts/{account_id}/modules/{module_id}/params` | `policies:write` | M2a | `ReasonBody` | 200 `AccountModulesView` | -| `GET /dashboard/modules/{module_id}/params/history` | `dashboard:read` | M2a | `?before=&limit=`, newest first | 200 `ParamsHistory` | +| `GET /dashboard/modules/{module_id}/params/history` | `dashboard:read` | M2a | `?before=&limit=`, newest first | 200 `ParamsHistory` | | `POST /dashboard/modules/{module_id}/enable` | `policies:write` | M2a | `ReasonBody` | 200 `ModuleInstanceView` | | `POST /dashboard/modules/{module_id}/disable` | `policies:write` or `modules:disable` | M2a | `ReasonBody` | 200 `ModuleInstanceView` | | `POST /dashboard/modules/{module_id}/resync` | `policies:write` | M2b | `ResyncBody` | 200 `ResyncResult` | @@ -49,7 +49,7 @@ ModuleInstanceView { circuit: "closed" | "open" | "half_open" // on the replica that answered } UndeclaredInstanceView { module_id: string, enabled: bool, params: object } // stored, no longer in the catalog; never evaluated -ModuleCatalogView { catalog_hash: string, params_version: number, modules: ModuleInstanceView[], undeclared: UndeclaredInstanceView[] } +ModuleCatalogView { catalog_hash: string, params_version: number, modules: ModuleInstanceView[], undeclared: UndeclaredInstanceView[] } // params_version: the instance params version AccountModuleEntry { module_id: string, @@ -60,10 +60,10 @@ AccountModuleEntry { account_layer?: object, // scope = all: this account's layer, when set params?: object // default / assigned: this account's own params } // secret references are shown unresolved -AccountModulesView { account_id: string, modules: AccountModuleEntry[] } // evaluation order +AccountModulesView { account_id: string, account_params_version: number, modules: AccountModuleEntry[] } // evaluation order ResyncResult { module_id: string, account_ids: string[] } // pairs cleared -ParamsHistory { module_id: string, entries: [{ version: number, account_id?: string, previous: object, new: object, operator: string, reason: string, at: string }] } +ParamsHistory { module_id: string, entries: [{ id: number, version: number, account_id?: string, previous: object, new: object, operator: string, reason: string, at: string }] } ``` ## Errors diff --git a/speckit/features/251-guardian-modules/data-model.md b/speckit/features/251-guardian-modules/data-model.md index 06fb2b28..7485fcf6 100644 --- a/speckit/features/251-guardian-modules/data-model.md +++ b/speckit/features/251-guardian-modules/data-model.md @@ -65,11 +65,15 @@ Assignments are created for `default` instances in the same transaction as the c #### `module_params_history` -Append-only: `id` (primary key), `version`, `module_id`, `account_id` (null for global), `previous`, `new`, `operator`, `reason`, `at`. Rows of one write share its `version`. +Append-only: `id` (primary key, the order the history is listed and paged in), `version`, `module_id`, `account_id` (null for global), `previous`, `new`, `operator`, `reason`, `at`. Rows of one write share its `version`: the instance params version for a global row, the account's params version for an account row. #### `module_state_version` -One row holding the params version. Every write takes its lock first, increments it, updates its rows and appends the history in one transaction, so writes serialize and the version moves in commit order; replicas key their cache on it. On the filesystem backend all tables are one file, `module_state.json`, replaced atomically. +One row holding the instance params version. Every write to `module_instances` takes its lock first, increments it, updates its rows and appends the history in one transaction, so instance writes serialize and the version moves in commit order; replicas key their instance cache on it. + +#### `module_account_version` + +One row per account a write has touched: `account_id` (primary key) and the account's params version. Every write to an account's rows in `module_account_params`, including the default copy at registration, takes that row's lock, increments it, updates the rows and appends the history in one transaction, so writes to one account serialize while writes to different accounts never wait for each other, and no account write moves the instance version. On the filesystem backend all tables are one file, `module_state.json`, replaced atomically, and each version is the highest of its history rows. ### Delta additions (both backends) @@ -77,7 +81,7 @@ The approval record is `metadata.modules` on the signed delta (`ModuleApproval`) | Field | Set when | Notes | |---|---|---| -| `catalog_hash`, `params_version`, `failed_open` | The Guardian signs the delta after modules ran | The configuration the modules ran with; `failed_open` lists module, layer and failure kind, omitted when empty. Allowed evaluations are derived from the catalog, not stored | +| `catalog_hash`, `params_version`, `account_params_version`, `failed_open` | The Guardian signs the delta after modules ran | The configuration the modules ran with; `failed_open` lists module, layer and failure kind, omitted when empty. Allowed evaluations are derived from the catalog, not stored | | `signed_at` | Fixed before the pipeline runs | RFC 3339; the accounting clock, sent as `accounting_time` and repeated in `pending` and `CommitEvent` (M2b) | | `submitter` | At signing | Verified signer commitment of the request being acked | | `proposer` | At signing | From `ProposalContext`; omitted when no proposal matched | From e10b61a98952c1cfb983cc0ea7c70b04ba941686 Mon Sep 17 00:00:00 2001 From: Zeljko Date: Tue, 10 Nov 2026 12:07:49 +0100 Subject: [PATCH 093/105] refactor(modules): split startup, budget and probe out of the pipeline (#251) pipeline.rs held startup reconciliation, the instance cache, planning, the evaluation loop, budget reporting, the health probe and their tests in one file. It is now pipeline/ with: - mod.rs: evaluation (the cache and snapshot, planning, Plan::run, failure handling); - startup.rs: ModulePipeline::new in named steps (read the stored instance rows, apply them to the catalog, build and check the instances, then the startup writes: catalog-required enables, seeds of new instances, params a module migrated), so nothing is written before every instance passed its checks; - budget.rs: the per-account budget check and the over-budget recount; - probe.rs: the health probe loop and the state gauges. No behaviour change: every function and test body is HEAD's apart from module paths, and the tests moved with their topic. --- crates/server/src/modules/pipeline/budget.rs | 159 +++ .../modules/{pipeline.rs => pipeline/mod.rs} | 1019 +---------------- crates/server/src/modules/pipeline/probe.rs | 266 +++++ crates/server/src/modules/pipeline/startup.rs | 774 +++++++++++++ docs/architecture/services.md | 6 +- 5 files changed, 1212 insertions(+), 1012 deletions(-) create mode 100644 crates/server/src/modules/pipeline/budget.rs rename crates/server/src/modules/{pipeline.rs => pipeline/mod.rs} (60%) create mode 100644 crates/server/src/modules/pipeline/probe.rs create mode 100644 crates/server/src/modules/pipeline/startup.rs diff --git a/crates/server/src/modules/pipeline/budget.rs b/crates/server/src/modules/pipeline/budget.rs new file mode 100644 index 00000000..56fe1fc2 --- /dev/null +++ b/crates/server/src/modules/pipeline/budget.rs @@ -0,0 +1,159 @@ +//! The evaluation budget of an account's stored modules: the check an operator write must pass, +//! and the recount behind the over-budget and orphaned-row gauges. + +use super::ModulePipeline; +use crate::error::GuardianError; +use crate::modules::catalog::{HookName, Scope}; +use crate::modules::store::{AccountParamsRow, ParamsKind}; + +/// An account whose stored modules could take longer than the evaluation budget. +struct OverBudget { + account_id: String, + hook: HookName, + worst_case: std::time::Duration, +} + +impl ModulePipeline { + /// The hook with the largest worst-case module time for an account whose rows name + /// `modules`, and that time: every `scope = all` instance, once more for an account layer on + /// it, plus every listed instance. Disabled instances count, since enabling needs no further + /// check; a row naming an instance the catalog no longer declares costs nothing. + fn worst_case(&self, modules: &[(&str, ParamsKind)]) -> (HookName, std::time::Duration) { + self.costs(modules) + .into_iter() + .max_by_key(|(_, total)| *total) + .unwrap_or(( + HookName::BeforeTransactionApproved, + std::time::Duration::ZERO, + )) + } + + /// The summed timeouts of the module calls an account naming `modules` makes at each gate + /// hook. + fn costs(&self, modules: &[(&str, ParamsKind)]) -> Vec<(HookName, std::time::Duration)> { + let calls = |id: &str, kind: ParamsKind| { + modules + .iter() + .filter(|(module_id, named)| *named == kind && *module_id == id) + .count() as u32 + }; + HookName::GATES + .into_iter() + .map(|hook| { + let total = self + .instances + .iter() + .filter(|instance| instance.config.hooks.contains(&hook)) + .map(|instance| { + let id = instance.config.id.as_str(); + let count = match instance.config.scope { + Scope::All => 1 + calls(id, ParamsKind::Layer), + Scope::Default | Scope::Assigned => calls(id, ParamsKind::Assignment), + }; + instance.config.timeout * count + }) + .sum(); + (hook, total) + }) + .collect() + } + + /// Refuses a write that would take the account's modules over the budget at a hook where + /// they are not already at least that far over. A write that keeps or lowers the cost passes, + /// so an account a deploy pushed over the budget can still be brought back under it. + pub fn check_budget( + &self, + current: &[AccountParamsRow], + proposed: &[AccountParamsRow], + ) -> Result<(), GuardianError> { + let named = |rows: &[AccountParamsRow]| -> Vec<(HookName, std::time::Duration)> { + let modules: Vec<(&str, ParamsKind)> = rows + .iter() + .map(|row| (row.module_id.as_str(), row.kind)) + .collect(); + self.costs(&modules) + }; + for ((hook, total), (_, now)) in named(proposed).into_iter().zip(named(current)) { + if total > self.limits.budget && total > now { + return Err(GuardianError::InvalidInput(format!( + "the account's modules at {} would take up to {} ms, over the evaluation budget of {} ms", + hook.as_str(), + total.as_millis(), + self.limits.budget.as_millis() + ))); + } + } + Ok(()) + } + + /// The accounts whose stored modules exceed the budget, each with its worst hook and that + /// hook's time, and the count of stored rows naming an instance the catalog no longer + /// declares. One scan of which module each account row names, without params. + async fn scan_assignments(&self) -> Result<(Vec, usize), String> { + let rows = self.store.account_modules().await?; + let orphaned = rows + .iter() + .filter(|row| self.instance(&row.module_id).is_none()) + .count(); + let over = rows + .chunk_by(|a, b| a.account_id == b.account_id) + .filter_map(|account| { + let modules: Vec<(&str, ParamsKind)> = account + .iter() + .map(|row| (row.module_id.as_str(), row.kind)) + .collect(); + let (hook, worst_case) = self.worst_case(&modules); + (worst_case > self.limits.budget).then(|| OverBudget { + account_id: account[0].account_id.clone(), + hook, + worst_case, + }) + }) + .collect(); + Ok((over, orphaned)) + } + + /// The over-budget account count and the orphaned row count as last counted. + #[cfg(test)] + pub fn assignment_report(&self) -> (usize, usize) { + self.assignment_report + .lock() + .map(|report| *report) + .unwrap_or_default() + } + + fn record_assignment_report(&self, over_budget: usize, orphaned: usize) { + if let Ok(mut report) = self.assignment_report.lock() { + *report = (over_budget, orphaned); + } + } + + /// Logs every account whose stored modules exceed the budget, without refusing to start: a + /// deploy that raised a timeout must not become an outage. Returns the count of those + /// accounts and of stored rows naming an instance the catalog no longer declares. + pub async fn report_stored_assignments(&self) -> Result<(usize, usize), String> { + let (over, orphaned) = self.scan_assignments().await?; + for account in &over { + tracing::warn!( + account_id = %account.account_id, + hook = account.hook.as_str(), + worst_case_ms = account.worst_case.as_millis() as u64, + budget_ms = self.limits.budget.as_millis() as u64, + "Account's policy modules exceed the evaluation budget; the runtime budget applies" + ); + } + self.record_assignment_report(over.len(), orphaned); + Ok((over.len(), orphaned)) + } + + /// Recounts the over-budget accounts and orphaned rows for the gauges, so they follow what + /// operators change after startup: an alarm clears once the assignment is fixed. + pub async fn refresh_assignment_report(&self) { + match self.scan_assignments().await { + Ok((over, orphaned)) => self.record_assignment_report(over.len(), orphaned), + Err(error) => { + tracing::warn!(%error, "Stored module assignments not recounted; the gauges keep their last values"); + } + } + } +} diff --git a/crates/server/src/modules/pipeline.rs b/crates/server/src/modules/pipeline/mod.rs similarity index 60% rename from crates/server/src/modules/pipeline.rs rename to crates/server/src/modules/pipeline/mod.rs index 0d4a5660..e6ebc19b 100644 --- a/crates/server/src/modules/pipeline.rs +++ b/crates/server/src/modules/pipeline/mod.rs @@ -2,13 +2,17 @@ use guardian_module_sdk::{Decision, Effect, HookRequest, is_valid_reason_code}; -use super::catalog::{Catalog, ClientReason, HookName, OnError, Scope}; +mod budget; +mod probe; +mod startup; + +use super::catalog::{ClientReason, HookName, OnError, Scope}; use std::collections::{HashMap, HashSet}; use std::sync::{Arc, RwLock}; -use super::breaker::{Breakers, Caller, CircuitState}; +use super::breaker::{Breakers, Caller}; use super::limits::Limits; -use super::registry::{CallError, Instance, Registry, Unhealthy, isolated}; +use super::registry::{CallError, Instance, isolated}; use super::request::ViewCache; use super::store::{AccountParamsRow, Assigned, ModuleStore, ParamsKind}; use crate::delta_summary::FailedOpen; @@ -101,16 +105,6 @@ pub struct ModulePipeline { pub(super) type Rows = Arc>; -/// How often the probe loop recounts the over-budget accounts and orphaned rows. -const ASSIGNMENT_REPORT_INTERVAL: std::time::Duration = std::time::Duration::from_secs(60); - -/// An account whose stored modules could take longer than the evaluation budget. -struct OverBudget { - account_id: String, - hook: HookName, - worst_case: std::time::Duration, -} - /// What one evaluation reads: see [`ModulePipeline::snapshot`]. pub(super) struct Snapshot { pub params_version: u64, @@ -186,165 +180,10 @@ impl std::fmt::Display for Failure { } } -/// The rules every stored params value follows, applied to what a module returns as normalized -/// params: within the size cap and free of secret references. -fn storable(limits: &Limits, params: &serde_json::Value) -> Result<(), String> { - limits.check_params_size(params)?; - if super::catalog::contains_secret_reference(params) { - return Err("normalized params contain a secret reference".into()); - } - Ok(()) -} - impl ModulePipeline { - /// [`storable`] under this pipeline's limits. + /// [`startup::storable`] under this pipeline's limits. pub fn storable_normalization(&self, params: &serde_json::Value) -> Result<(), String> { - storable(&self.limits, params) - } - - pub async fn new( - network_id: &'static str, - mut catalog: Catalog, - registry: &Registry, - store: Arc, - now: String, - limits: Limits, - ) -> Result { - for config in &catalog.instances { - limits - .check_params_size(&config.params) - .map_err(|e| format!("module {}: catalog {e}", config.id))?; - } - let rows = store.instances().await?; - let seeded: HashMap = rows - .iter() - .map(|row| (row.module_id.clone(), row.seeded_params.clone())) - .collect(); - let stored: HashMap = rows - .into_iter() - .map(|row| (row.module_id, (row.global_params, row.enabled))) - .collect(); - let known: HashSet = stored.keys().cloned().collect(); - let mut effective = HashMap::new(); - let mut seed_drift = HashSet::new(); - let mut enabled_by_catalog = Vec::new(); - for config in &mut catalog.instances { - let Some((params, enabled)) = stored.get(&config.id) else { - continue; - }; - if !config.file_managed_params - && seeded - .get(&config.id) - .is_some_and(|seeded| *seeded != config.params) - { - seed_drift.insert(config.id.clone()); - } - // The stored flag is the switch, with one exception: an instance the catalog - // declares enabled and not operator-disableable cannot be left off by a disable - // that was allowed under an earlier catalog. Switching it on only tightens policy. - let catalog_requires_it = - !*enabled && config.catalog_enabled && !config.operator_can_disable; - if catalog_requires_it { - tracing::warn!(module = %config.id, "Stored flag disables an instance the catalog declares enabled and not operator-disableable; enabling it"); - enabled_by_catalog.push(config.id.clone()); - } else if *enabled != config.catalog_enabled { - tracing::warn!(module = %config.id, enabled, "Catalog `enabled` differs from the stored runtime flag; the stored flag applies"); - } - config.enabled = *enabled || catalog_requires_it; - if !config.file_managed_params && *params != config.params { - tracing::warn!(module = %config.id, "Catalog params differ from the operator-managed global params; the stored params apply"); - effective.insert(config.id.clone(), params.clone()); - } - } - let super::registry::Instantiated { - instances, - normalized, - unreachable, - } = registry.instantiate(&catalog, &effective, &known).await?; - for module_id in enabled_by_catalog { - store - .set_enabled( - &module_id, - true, - &super::store::Change { - operator: "catalog", - reason: "the catalog declares the instance enabled and not operator-disableable", - at: now.clone(), - }, - ) - .await?; - } - for config in catalog - .instances - .iter() - .filter(|config| !stored.contains_key(&config.id)) - { - let seed = if config.file_managed_params { - serde_json::json!({}) - } else { - normalized - .get(&config.id) - .filter(|params| storable(&limits, params).is_ok()) - .unwrap_or(&config.params) - .clone() - }; - store - .seed_instance(&config.id, config.enabled, &seed, &now) - .await?; - } - for instance in instances - .iter() - .filter(|instance| !instance.config.file_managed_params) - { - let (Some(params), Some((read, _))) = ( - normalized.get(&instance.config.id), - stored.get(&instance.config.id), - ) else { - continue; - }; - if let Err(error) = storable(&limits, params) { - tracing::warn!(module = %instance.config.id, %error, "Module's normalized params break the params rules; kept the stored params"); - continue; - } - let operator = format!( - "module:{}", - instance.build.as_deref().unwrap_or(&instance.config.kind) - ); - let migrated = store - .set_global_if( - &instance.config.id, - read, - params.clone(), - &super::store::Change { - operator: &operator, - reason: "params migrated by the module", - at: now.clone(), - }, - ) - .await?; - if migrated.is_some() { - tracing::info!(module = %instance.config.id, %operator, "Module normalized its stored global params; stored the migrated form"); - } else { - tracing::warn!(module = %instance.config.id, "Global params changed while the module migrated them; kept the newer value, migration retries next start"); - } - } - let breakers = Arc::new(Breakers::new(limits.breaker_failures)); - for module_id in &unreachable { - breakers.hold_open(module_id); - } - Ok(Self { - instances, - store, - cache: RwLock::new(Cache::default()), - views: Arc::default(), - breakers, - unchecked: std::sync::Mutex::new(unreachable), - limits, - catalog_hash: catalog.hash, - network_id, - seed_drift, - assignment_report: std::sync::Mutex::new((0, 0)), - }) + startup::storable(&self.limits, params) } #[cfg(test)] @@ -396,248 +235,6 @@ impl ModulePipeline { &self.breakers } - /// The hook with the largest worst-case module time for an account whose rows name - /// `modules`, and that time: every `scope = all` instance, once more for an account layer on - /// it, plus every listed instance. Disabled instances count, since enabling needs no further - /// check; a row naming an instance the catalog no longer declares costs nothing. - fn worst_case(&self, modules: &[(&str, ParamsKind)]) -> (HookName, std::time::Duration) { - self.costs(modules) - .into_iter() - .max_by_key(|(_, total)| *total) - .unwrap_or(( - HookName::BeforeTransactionApproved, - std::time::Duration::ZERO, - )) - } - - /// The summed timeouts of the module calls an account naming `modules` makes at each gate - /// hook. - fn costs(&self, modules: &[(&str, ParamsKind)]) -> Vec<(HookName, std::time::Duration)> { - let calls = |id: &str, kind: ParamsKind| { - modules - .iter() - .filter(|(module_id, named)| *named == kind && *module_id == id) - .count() as u32 - }; - HookName::GATES - .into_iter() - .map(|hook| { - let total = self - .instances - .iter() - .filter(|instance| instance.config.hooks.contains(&hook)) - .map(|instance| { - let id = instance.config.id.as_str(); - let count = match instance.config.scope { - Scope::All => 1 + calls(id, ParamsKind::Layer), - Scope::Default | Scope::Assigned => calls(id, ParamsKind::Assignment), - }; - instance.config.timeout * count - }) - .sum(); - (hook, total) - }) - .collect() - } - - /// Refuses a write that would take the account's modules over the budget at a hook where - /// they are not already at least that far over. A write that keeps or lowers the cost passes, - /// so an account a deploy pushed over the budget can still be brought back under it. - pub fn check_budget( - &self, - current: &[AccountParamsRow], - proposed: &[AccountParamsRow], - ) -> Result<(), GuardianError> { - let named = |rows: &[AccountParamsRow]| -> Vec<(HookName, std::time::Duration)> { - let modules: Vec<(&str, ParamsKind)> = rows - .iter() - .map(|row| (row.module_id.as_str(), row.kind)) - .collect(); - self.costs(&modules) - }; - for ((hook, total), (_, now)) in named(proposed).into_iter().zip(named(current)) { - if total > self.limits.budget && total > now { - return Err(GuardianError::InvalidInput(format!( - "the account's modules at {} would take up to {} ms, over the evaluation budget of {} ms", - hook.as_str(), - total.as_millis(), - self.limits.budget.as_millis() - ))); - } - } - Ok(()) - } - - /// The accounts whose stored modules exceed the budget, each with its worst hook and that - /// hook's time, and the count of stored rows naming an instance the catalog no longer - /// declares. One scan of which module each account row names, without params. - async fn scan_assignments(&self) -> Result<(Vec, usize), String> { - let rows = self.store.account_modules().await?; - let orphaned = rows - .iter() - .filter(|row| self.instance(&row.module_id).is_none()) - .count(); - let over = rows - .chunk_by(|a, b| a.account_id == b.account_id) - .filter_map(|account| { - let modules: Vec<(&str, ParamsKind)> = account - .iter() - .map(|row| (row.module_id.as_str(), row.kind)) - .collect(); - let (hook, worst_case) = self.worst_case(&modules); - (worst_case > self.limits.budget).then(|| OverBudget { - account_id: account[0].account_id.clone(), - hook, - worst_case, - }) - }) - .collect(); - Ok((over, orphaned)) - } - - /// The over-budget account count and the orphaned row count as last counted. - #[cfg(test)] - pub fn assignment_report(&self) -> (usize, usize) { - self.assignment_report - .lock() - .map(|report| *report) - .unwrap_or_default() - } - - fn record_assignment_report(&self, over_budget: usize, orphaned: usize) { - if let Ok(mut report) = self.assignment_report.lock() { - *report = (over_budget, orphaned); - } - } - - /// Logs every account whose stored modules exceed the budget, without refusing to start: a - /// deploy that raised a timeout must not become an outage. Returns the count of those - /// accounts and of stored rows naming an instance the catalog no longer declares. - pub async fn report_stored_assignments(&self) -> Result<(usize, usize), String> { - let (over, orphaned) = self.scan_assignments().await?; - for account in &over { - tracing::warn!( - account_id = %account.account_id, - hook = account.hook.as_str(), - worst_case_ms = account.worst_case.as_millis() as u64, - budget_ms = self.limits.budget.as_millis() as u64, - "Account's policy modules exceed the evaluation budget; the runtime budget applies" - ); - } - self.record_assignment_report(over.len(), orphaned); - Ok((over.len(), orphaned)) - } - - /// Recounts the over-budget accounts and orphaned rows for the gauges, so they follow what - /// operators change after startup: an alarm clears once the assignment is fixed. - pub async fn refresh_assignment_report(&self) { - match self.scan_assignments().await { - Ok((over, orphaned)) => self.record_assignment_report(over.len(), orphaned), - Err(error) => { - tracing::warn!(%error, "Stored module assignments not recounted; the gauges keep their last values"); - } - } - } - - /// Sets the state gauges from the stored rows and this replica's breakers. Run on every probe, - /// so they are set once a metrics recorder exists and follow changes other replicas make. - fn publish(&self, rows: &Rows) { - super::metrics::catalog(&self.catalog_hash); - let (over_budget, orphaned) = self - .assignment_report - .lock() - .map(|report| *report) - .unwrap_or_default(); - super::metrics::stored_assignments(over_budget, orphaned); - for instance in &self.instances { - let id = &instance.config.id; - let enabled = Self::enabled_in(rows, instance); - super::metrics::enabled(id, enabled); - super::metrics::config_drift( - id, - enabled != instance.config.catalog_enabled || self.seed_drift.contains(id), - ); - super::metrics::circuit_open(id, self.breakers.state(id) == CircuitState::Open); - } - } - - /// One health probe of every enabled instance: `Describe` under its timeout, with the startup - /// checks. A healthy module half-opens an open breaker so the next real call is sent. One - /// that does not answer counts as a failed call toward its breaker. One that answers with a - /// protocol version, capability or hook set this Guardian cannot work with opens its breaker - /// at once: its decisions are not trusted until a probe passes again. - pub async fn probe(&self) { - let Ok(rows) = self.rows().await else { - return; - }; - self.publish(&rows); - for instance in &self.instances { - if !Self::enabled_in(&rows, instance) { - continue; - } - let id = instance.config.id.as_str(); - let unchecked = self - .unchecked - .lock() - .is_ok_and(|unchecked| unchecked.contains(id)); - // An instance that started without its startup checks runs all of them here, the - // params that apply included, before any call is let through. - let healthy = if unchecked { - super::registry::check( - &instance.config, - &instance.module, - &Self::global_params_in(&rows, instance), - ) - .await - .map(|_| ()) - } else { - super::registry::describe_healthy(&instance.config, &instance.module) - .await - .map(|_| ()) - }; - super::metrics::up(id, healthy.is_ok()); - match healthy { - Ok(()) => { - if unchecked { - if let Ok(mut unchecked) = self.unchecked.lock() { - unchecked.remove(id); - } - tracing::info!( - module = id, - "Policy module passed the startup checks it could not be reached for" - ); - } - self.breakers.probe_succeeded(id); - } - Err(Unhealthy::Unreachable(error)) => { - tracing::warn!(module = id, %error, "Policy module health probe failed"); - self.breakers.failed(id); - } - Err(Unhealthy::Incompatible(error) | Unhealthy::InvalidParams(error)) => { - tracing::warn!(module = id, %error, "Policy module cannot be used by this Guardian; its circuit is open until a probe passes"); - self.breakers.hold_open(id); - } - } - } - } - - /// Runs [`Self::probe`] every `GUARDIAN_MODULE_PROBE_INTERVAL_MS` for the life of the server. - pub fn spawn_probe(self: Arc) -> tokio::task::JoinHandle<()> { - tokio::spawn(async move { - let mut interval = tokio::time::interval(self.limits.probe_interval); - interval.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Delay); - let mut counted = tokio::time::Instant::now(); - loop { - interval.tick().await; - if counted.elapsed() >= ASSIGNMENT_REPORT_INTERVAL { - self.refresh_assignment_report().await; - counted = tokio::time::Instant::now(); - } - self.probe().await; - } - }) - } - pub fn instances(&self) -> &[Instance] { &self.instances } @@ -1199,140 +796,6 @@ mod tests { .await } - fn caps_catalog(params: &str) -> Catalog { - Catalog::parse( - &format!( - r#" -[[module]] -id = "caps" -kind = "spending-limit" -scope = "all" -hooks = ["before_transaction_approved"] -timeout_ms = 50 -params = {params} -"# - ), - None, - ) - .unwrap() - } - - #[tokio::test] - async fn a_probe_publishes_the_state_gauges() { - let pipeline = pipeline(vec![instance( - "caps", - &[HookName::BeforeTransactionApproved], - OnError::Deny, - StubModule::allowing(), - )]); - let rows = pipeline.rows().await.unwrap(); - let recorder = crate::metrics::build_recorder(); - let handle = recorder.handle(); - metrics::with_local_recorder(&recorder, || pipeline.publish(&rows)); - let text = handle.render(); - for line in [ - "guardian_module_enabled{module=\"caps\"} 1", - "guardian_module_circuit_open{module=\"caps\"} 0", - "guardian_module_config_drift{module=\"caps\"} 0", - "guardian_module_over_budget_accounts 0", - "guardian_module_orphaned_assignments 0", - "guardian_module_catalog_info{catalog_hash=\"\"} 1", - ] { - assert!(text.contains(line), "{line} missing from:\n{text}"); - } - } - - #[tokio::test] - async fn invalid_catalog_params_stop_startup_without_seeding_them() { - let store: Arc = Arc::new(super::super::store::FsModuleStore::in_memory()); - let registry = Registry::first_party(); - let now = "2026-10-15T00:00:00Z".to_string(); - let started = ModulePipeline::new( - "local", - caps_catalog(r#"{ max_per_transactionx = {} }"#), - ®istry, - store.clone(), - now.clone(), - crate::modules::limits::Limits::default(), - ) - .await; - assert!(started.is_err()); - assert!(store.instances().await.unwrap().is_empty()); - - let fixed = caps_catalog( - r#"{ max_per_transaction = { "0x0000000000000000000000000000aa" = "5" } }"#, - ); - let started = ModulePipeline::new( - "local", - fixed, - ®istry, - store.clone(), - now, - crate::modules::limits::Limits::default(), - ) - .await - .expect("the corrected catalog starts"); - assert!( - started.instances()[0] - .build - .as_deref() - .is_some_and(|build| build.starts_with("spending-limit")) - ); - assert_eq!(store.instances().await.unwrap().len(), 1); - } - - #[tokio::test] - async fn stored_params_not_the_stale_catalog_seed_are_checked_at_startup() { - let store: Arc = Arc::new(super::super::store::FsModuleStore::in_memory()); - let registry = Registry::first_party(); - let now = "2026-10-15T00:00:00Z".to_string(); - store - .seed_instance( - "caps", - true, - &serde_json::json!({ "max_per_transaction": {} }), - &now, - ) - .await - .unwrap(); - ModulePipeline::new( - "local", - caps_catalog(r#"{ max_per_transactionx = {} }"#), - ®istry, - store.clone(), - now.clone(), - crate::modules::limits::Limits::default(), - ) - .await - .expect("the stored params apply, so the stale seed is not checked"); - - store - .set_global( - "caps", - serde_json::json!({ "unknown": true }), - &super::super::store::Change { - operator: "0xop", - reason: "test", - at: now.clone(), - }, - ) - .await - .unwrap(); - let valid_seed = caps_catalog(r#"{ max_per_transaction = {} }"#); - assert!( - ModulePipeline::new( - "local", - valid_seed, - ®istry, - store, - now, - crate::modules::limits::Limits::default() - ) - .await - .is_err() - ); - } - #[tokio::test] async fn fail_closed_timeout_refuses_as_unavailable() { let pipeline = pipeline(vec![instance( @@ -1493,310 +956,6 @@ params = {params} } } - #[tokio::test] - async fn normalized_params_that_break_the_params_rules_are_not_stored() { - use crate::modules::testing::{FixedFactory, ProtocolStub}; - let catalog = Catalog::parse( - r#" -[[module]] -id = "migrating" -kind = "protocol-stub" -scope = "all" -hooks = ["before_transaction_approved"] -timeout_ms = 50 -params = { old_name = 5 } -"#, - None, - ) - .unwrap(); - for normalized in [ - serde_json::json!({ "new_name": "x".repeat(200) }), - serde_json::json!({ "key": { "$secret": "vendor-key" } }), - ] { - let mut stub = ProtocolStub::new(); - stub.normalized = Some(normalized.clone()); - let mut registry = Registry::first_party(); - registry - .register("protocol-stub", Arc::new(FixedFactory(Arc::new(stub)))) - .unwrap(); - let store: Arc = - Arc::new(super::super::store::FsModuleStore::in_memory()); - ModulePipeline::new( - "local", - catalog.clone(), - ®istry, - store.clone(), - "2026-10-16T00:00:00Z".to_string(), - crate::modules::limits::Limits { - params_max_bytes: 100, - ..Default::default() - }, - ) - .await - .unwrap(); - assert_eq!( - store.instances().await.unwrap()[0].global_params, - serde_json::json!({ "old_name": 5 }), - "kept the catalog params instead of {normalized}" - ); - } - } - - const OUTAGE_CATALOG: &str = r#" -[[module]] -id = "screening" -kind = "outage-stub" -scope = "all" -hooks = ["before_transaction_approved"] -timeout_ms = 50 -"#; - - async fn start_with( - module: Arc, - catalog: &str, - store: Arc, - ) -> Result { - let mut registry = Registry::first_party(); - registry - .register( - "outage-stub", - Arc::new(crate::modules::testing::FixedFactory(module)), - ) - .unwrap(); - ModulePipeline::new( - "local", - Catalog::parse(catalog, None).unwrap(), - ®istry, - store, - "2026-11-10T00:00:00Z".to_string(), - crate::modules::limits::Limits::default(), - ) - .await - } - - #[tokio::test] - async fn a_known_instance_whose_module_is_down_starts_unavailable_and_recovers_on_a_probe() { - use std::sync::atomic::Ordering; - let module = crate::modules::testing::Outage::new(false); - let store: Arc = Arc::new(super::super::store::FsModuleStore::in_memory()); - start_with(module.clone(), OUTAGE_CATALOG, store.clone()) - .await - .expect("the first start passes the checks and makes the instance known"); - - module.set_down(true); - let pipeline = start_with(module.clone(), OUTAGE_CATALOG, store) - .await - .expect("a module outage does not keep the Guardian from restarting"); - assert_eq!(pipeline.breakers().state("screening"), CircuitState::Open); - assert!( - matches!( - run(&pipeline).await, - Err(GuardianError::ModuleUnavailable { .. }) - ), - "its accounts are refused meanwhile, not approved" - ); - - pipeline.probe().await; - assert_eq!( - pipeline.breakers().state("screening"), - CircuitState::Open, - "still down" - ); - - module.set_down(false); - pipeline.probe().await; - assert_eq!( - pipeline.breakers().state("screening"), - CircuitState::HalfOpen - ); - run(&pipeline).await.expect("the module decides again"); - assert_eq!(pipeline.breakers().state("screening"), CircuitState::Closed); - assert_eq!(module.evaluations.load(Ordering::SeqCst), 1); - } - - #[tokio::test] - async fn an_instance_new_to_this_guardian_must_answer_at_startup() { - let module = crate::modules::testing::Outage::new(true); - let store: Arc = Arc::new(super::super::store::FsModuleStore::in_memory()); - let refused = start_with(module, OUTAGE_CATALOG, store.clone()) - .await - .err() - .expect("a wrong endpoint in a new catalog entry is found at deploy time"); - assert!(refused.contains("screening"), "{refused}"); - assert!(store.instances().await.unwrap().is_empty()); - } - - #[tokio::test] - async fn a_known_instance_that_answers_incompatibly_still_stops_startup() { - use crate::modules::testing::{FixedFactory, ProtocolStub}; - const CATALOG: &str = r#" -[[module]] -id = "screening" -kind = "protocol-stub" -scope = "all" -hooks = ["before_transaction_approved"] -timeout_ms = 50 -"#; - let start = |protocol_version: u32, store: Arc| async move { - let mut stub = ProtocolStub::new(); - stub.protocol_version = protocol_version; - let mut registry = Registry::first_party(); - registry - .register("protocol-stub", Arc::new(FixedFactory(Arc::new(stub)))) - .unwrap(); - ModulePipeline::new( - "local", - Catalog::parse(CATALOG, None).unwrap(), - ®istry, - store, - "2026-11-10T00:00:00Z".to_string(), - crate::modules::limits::Limits::default(), - ) - .await - }; - let store: Arc = Arc::new(super::super::store::FsModuleStore::in_memory()); - start(guardian_module_sdk::PROTOCOL_VERSION, store.clone()) - .await - .unwrap(); - assert!( - start(guardian_module_sdk::PROTOCOL_VERSION + 1, store) - .await - .is_err(), - "only a module that does not answer may start unavailable" - ); - } - - #[tokio::test] - async fn an_instance_the_catalog_requires_is_enabled_at_startup() { - let disabled_in_store = || async { - let store: Arc = - Arc::new(super::super::store::FsModuleStore::in_memory()); - store - .seed_instance("screening", false, &serde_json::json!({}), "t0") - .await - .unwrap(); - store - }; - - let store = disabled_in_store().await; - let pipeline = start_with( - crate::modules::testing::Outage::new(false), - OUTAGE_CATALOG, - store.clone(), - ) - .await - .unwrap(); - assert!( - store.instances().await.unwrap()[0].enabled, - "enabled and not operator-disableable in the catalog: a stored disable does not stand" - ); - let history = store.history("screening", None, 10).await.unwrap(); - assert_eq!(history[0].operator, "catalog"); - assert_eq!(history[0].new, serde_json::json!({ "enabled": true })); - assert!( - pipeline - .applies(HookName::BeforeTransactionApproved, "0xacc") - .await - .unwrap() - ); - - let store = disabled_in_store().await; - let disableable = format!("{OUTAGE_CATALOG}operator_can_disable = true\n"); - let pipeline = start_with( - crate::modules::testing::Outage::new(false), - &disableable, - store.clone(), - ) - .await - .unwrap(); - assert!( - !store.instances().await.unwrap()[0].enabled, - "an operator may hold a disableable instance off, so the stored flag stands" - ); - assert!( - !pipeline - .applies(HookName::BeforeTransactionApproved, "0xacc") - .await - .unwrap() - ); - } - - #[tokio::test] - async fn startup_stores_params_the_module_migrated() { - use crate::modules::testing::{FixedFactory, ProtocolStub}; - let catalog = || { - Catalog::parse( - r#" -[[module]] -id = "migrating" -kind = "protocol-stub" -scope = "all" -hooks = ["before_transaction_approved"] -timeout_ms = 50 -params = { old_name = 5 } -"#, - None, - ) - .unwrap() - }; - let mut stub = ProtocolStub::new(); - stub.normalized = Some(serde_json::json!({ "new_name": 5 })); - let mut registry = Registry::first_party(); - registry - .register("protocol-stub", Arc::new(FixedFactory(Arc::new(stub)))) - .unwrap(); - let store: Arc = Arc::new(super::super::store::FsModuleStore::in_memory()); - let now = "2026-10-16T00:00:00Z".to_string(); - - ModulePipeline::new( - "local", - catalog(), - ®istry, - store.clone(), - now.clone(), - crate::modules::limits::Limits::default(), - ) - .await - .unwrap(); - let seeded = store.instances().await.unwrap(); - assert_eq!( - seeded[0].global_params, - serde_json::json!({ "new_name": 5 }), - "a new instance is seeded in the migrated shape" - ); - - store - .set_global( - "migrating", - serde_json::json!({ "old_name": 7 }), - &super::super::store::Change { - operator: "0xop", - reason: "old shape", - at: now.clone(), - }, - ) - .await - .unwrap(); - ModulePipeline::new( - "local", - catalog(), - ®istry, - store.clone(), - now, - crate::modules::limits::Limits::default(), - ) - .await - .unwrap(); - assert_eq!( - store.instances().await.unwrap()[0].global_params, - serde_json::json!({ "new_name": 5 }) - ); - let last = store.history("migrating", None, 1).await.unwrap().remove(0); - assert_eq!(last.operator, "module:protocol-stub 1"); - assert_eq!(last.reason, "params migrated by the module"); - assert_eq!(last.previous, serde_json::json!({ "old_name": 7 })); - } - #[tokio::test] async fn a_generic_instance_denies_without_details() { let deny = Behaviour::Decide( @@ -1891,68 +1050,6 @@ params = { old_name = 5 } ); } - /// An operator lowers the stored params while the module is migrating them at startup; - /// the migration must not replace the operator's newer value with its stale result. - #[tokio::test] - async fn a_startup_migration_never_overwrites_a_newer_operator_write() { - use crate::modules::testing::{FixedFactory, ProtocolStub, RacingStore, RacingWrite}; - let catalog = Catalog::parse( - r#" -[[module]] -id = "migrating" -kind = "protocol-stub" -scope = "all" -hooks = ["before_transaction_approved"] -timeout_ms = 50 -params = { old_name = 1000 } -"#, - None, - ) - .unwrap(); - let mut stub = ProtocolStub::new(); - stub.normalized = Some(serde_json::json!({ "new_name": 1000 })); - let mut registry = Registry::first_party(); - registry - .register("protocol-stub", Arc::new(FixedFactory(Arc::new(stub)))) - .unwrap(); - let store = Arc::new(RacingStore::new()); - store - .inner - .seed_instance( - "migrating", - true, - &serde_json::json!({ "old_name": 1000 }), - "2026-10-16T00:00:00Z", - ) - .await - .unwrap(); - *store.before_set_global_if.lock().unwrap() = vec![RacingWrite::Global( - "migrating", - serde_json::json!({ "new_name": 100 }), - )]; - - ModulePipeline::new( - "local", - catalog, - ®istry, - store.clone(), - "2026-10-16T00:00:02Z".into(), - crate::modules::limits::Limits::default(), - ) - .await - .unwrap(); - assert_eq!( - store.instances().await.unwrap()[0].global_params, - serde_json::json!({ "new_name": 100 }), - "the operator's cap of 100 stays" - ); - let last = store.history("migrating", None, 1).await.unwrap().remove(0); - assert_eq!( - last.operator, "0xracing-operator", - "no migration entry after it" - ); - } - #[tokio::test] async fn a_deny_stops_evaluation() { let later = StubModule::allowing(); @@ -2535,102 +1632,4 @@ mod failure_handling_tests { Err(GuardianError::ModuleDenied { module, .. }) if module == "caps" )); } - - #[tokio::test] - async fn a_module_that_turns_incompatible_is_not_trusted_until_a_probe_passes() { - let mut stub = crate::modules::testing::ProtocolStub::new(); - stub.protocol_version = guardian_module_sdk::PROTOCOL_VERSION + 1; - let pipeline = ModulePipeline::from_instances(vec![instance( - "screening", - &[HOOK], - OnError::Deny, - Arc::new(stub), - )]); - run(&pipeline) - .await - .expect("the module allows until a probe finds it incompatible"); - pipeline.probe().await; - assert_eq!(pipeline.breakers().state("screening"), CircuitState::Open); - assert!(matches!( - run(&pipeline).await, - Err(GuardianError::ModuleUnavailable { .. }) - )); - pipeline.probe().await; - assert_eq!( - pipeline.breakers().state("screening"), - CircuitState::Open, - "it stays open while the probe keeps failing" - ); - } - - /// Allows every request but never answers `Describe`. - struct Undescribed; - - #[async_trait::async_trait] - impl guardian_module_sdk::Module for Undescribed { - async fn describe( - &self, - _: &guardian_module_sdk::DescribeRequest, - ) -> Result { - Err(guardian_module_sdk::ModuleError::Unavailable( - "no answer".into(), - )) - } - - async fn validate_params( - &self, - _: &[u8], - ) -> Result { - Ok(guardian_module_sdk::ParamsVerdict::ok()) - } - - async fn evaluate( - &self, - _: &HookRequest, - ) -> Result { - Ok(guardian_module_sdk::Decision::allow()) - } - } - - #[tokio::test] - async fn probes_a_module_does_not_answer_count_toward_its_breaker() { - let pipeline = ModulePipeline::from_instances(vec![instance( - "screening", - &[HOOK], - OnError::Deny, - Arc::new(Undescribed), - )]) - .with_limits(Limits { - breaker_failures: 2, - ..Limits::default() - }); - pipeline.probe().await; - assert_eq!(pipeline.breakers().state("screening"), CircuitState::Closed); - pipeline.probe().await; - assert_eq!( - pipeline.breakers().state("screening"), - CircuitState::Open, - "no request had to find the module down" - ); - } - - #[tokio::test] - async fn a_healthy_probe_half_opens_and_a_failing_one_leaves_the_circuit_open() { - let healthy = crate::modules::testing::instance_with_params( - "caps", - &[HOOK], - Arc::new(guardian_module_sdk::policies::RecipientPolicy), - serde_json::json!({}), - ); - let (down, _) = hanging("screening", OnError::Deny, Duration::from_millis(20)); - let pipeline = ModulePipeline::from_instances(vec![healthy, down]).with_limits(Limits { - breaker_failures: 1, - ..Limits::default() - }); - pipeline.breakers().failed("caps"); - pipeline.breakers().failed("screening"); - pipeline.probe().await; - assert_eq!(pipeline.breakers().state("caps"), CircuitState::HalfOpen); - assert_eq!(pipeline.breakers().state("screening"), CircuitState::Open); - } } diff --git a/crates/server/src/modules/pipeline/probe.rs b/crates/server/src/modules/pipeline/probe.rs new file mode 100644 index 00000000..34d410da --- /dev/null +++ b/crates/server/src/modules/pipeline/probe.rs @@ -0,0 +1,266 @@ +//! The health probe: every `GUARDIAN_MODULE_PROBE_INTERVAL_MS` it asks each enabled module +//! whether it is up, half-opens or holds open its breaker, reruns the startup checks of an +//! instance that started unchecked, and publishes the state gauges. + +use std::sync::Arc; + +use super::{ModulePipeline, Rows}; +use crate::modules::breaker::CircuitState; +use crate::modules::registry::Unhealthy; + +/// How often the probe loop recounts the over-budget accounts and orphaned rows. +const ASSIGNMENT_REPORT_INTERVAL: std::time::Duration = std::time::Duration::from_secs(60); + +impl ModulePipeline { + /// Sets the state gauges from the stored rows and this replica's breakers. Run on every probe, + /// so they are set once a metrics recorder exists and follow changes other replicas make. + fn publish(&self, rows: &Rows) { + crate::modules::metrics::catalog(&self.catalog_hash); + let (over_budget, orphaned) = self + .assignment_report + .lock() + .map(|report| *report) + .unwrap_or_default(); + crate::modules::metrics::stored_assignments(over_budget, orphaned); + for instance in &self.instances { + let id = &instance.config.id; + let enabled = Self::enabled_in(rows, instance); + crate::modules::metrics::enabled(id, enabled); + crate::modules::metrics::config_drift( + id, + enabled != instance.config.catalog_enabled || self.seed_drift.contains(id), + ); + crate::modules::metrics::circuit_open( + id, + self.breakers.state(id) == CircuitState::Open, + ); + } + } + + /// One health probe of every enabled instance: `Describe` under its timeout, with the startup + /// checks. A healthy module half-opens an open breaker so the next real call is sent. One + /// that does not answer counts as a failed call toward its breaker. One that answers with a + /// protocol version, capability or hook set this Guardian cannot work with opens its breaker + /// at once: its decisions are not trusted until a probe passes again. + pub async fn probe(&self) { + let Ok(rows) = self.rows().await else { + return; + }; + self.publish(&rows); + for instance in &self.instances { + if !Self::enabled_in(&rows, instance) { + continue; + } + let id = instance.config.id.as_str(); + let unchecked = self + .unchecked + .lock() + .is_ok_and(|unchecked| unchecked.contains(id)); + // An instance that started without its startup checks runs all of them here, the + // params that apply included, before any call is let through. + let healthy = if unchecked { + crate::modules::registry::check( + &instance.config, + &instance.module, + &Self::global_params_in(&rows, instance), + ) + .await + .map(|_| ()) + } else { + crate::modules::registry::describe_healthy(&instance.config, &instance.module) + .await + .map(|_| ()) + }; + crate::modules::metrics::up(id, healthy.is_ok()); + match healthy { + Ok(()) => { + if unchecked { + if let Ok(mut unchecked) = self.unchecked.lock() { + unchecked.remove(id); + } + tracing::info!( + module = id, + "Policy module passed the startup checks it could not be reached for" + ); + } + self.breakers.probe_succeeded(id); + } + Err(Unhealthy::Unreachable(error)) => { + tracing::warn!(module = id, %error, "Policy module health probe failed"); + self.breakers.failed(id); + } + Err(Unhealthy::Incompatible(error) | Unhealthy::InvalidParams(error)) => { + tracing::warn!(module = id, %error, "Policy module cannot be used by this Guardian; its circuit is open until a probe passes"); + self.breakers.hold_open(id); + } + } + } + } + + /// Runs [`Self::probe`] every `GUARDIAN_MODULE_PROBE_INTERVAL_MS` for the life of the server. + pub fn spawn_probe(self: Arc) -> tokio::task::JoinHandle<()> { + tokio::spawn(async move { + let mut interval = tokio::time::interval(self.limits.probe_interval); + interval.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Delay); + let mut counted = tokio::time::Instant::now(); + loop { + interval.tick().await; + if counted.elapsed() >= ASSIGNMENT_REPORT_INTERVAL { + self.refresh_assignment_report().await; + counted = tokio::time::Instant::now(); + } + self.probe().await; + } + }) + } +} + +#[cfg(test)] +mod tests { + use std::time::Duration; + + use guardian_module_sdk::HookRequest; + + use super::super::*; + use crate::modules::breaker::CircuitState; + use crate::modules::catalog::{HookName, OnError}; + use crate::modules::testing::{Behaviour, StubModule, instance, pipeline}; + + const HOOK: HookName = HookName::BeforeTransactionApproved; + + fn hanging(id: &str, on_error: OnError, timeout: Duration) -> (Instance, Arc) { + let module = StubModule::new(Behaviour::Hang); + let mut hung = instance(id, &[HOOK], on_error, module.clone()); + hung.config.timeout = timeout; + (hung, module) + } + + async fn run(pipeline: &ModulePipeline) -> Result<(), GuardianError> { + pipeline + .run(HOOK, "0xacc", || Ok(HookRequest::default())) + .await + } + + #[tokio::test] + async fn a_probe_publishes_the_state_gauges() { + let pipeline = pipeline(vec![instance( + "caps", + &[HookName::BeforeTransactionApproved], + OnError::Deny, + StubModule::allowing(), + )]); + let rows = pipeline.rows().await.unwrap(); + let recorder = crate::metrics::build_recorder(); + let handle = recorder.handle(); + metrics::with_local_recorder(&recorder, || pipeline.publish(&rows)); + let text = handle.render(); + for line in [ + "guardian_module_enabled{module=\"caps\"} 1", + "guardian_module_circuit_open{module=\"caps\"} 0", + "guardian_module_config_drift{module=\"caps\"} 0", + "guardian_module_over_budget_accounts 0", + "guardian_module_orphaned_assignments 0", + "guardian_module_catalog_info{catalog_hash=\"\"} 1", + ] { + assert!(text.contains(line), "{line} missing from:\n{text}"); + } + } + + #[tokio::test] + async fn a_module_that_turns_incompatible_is_not_trusted_until_a_probe_passes() { + let mut stub = crate::modules::testing::ProtocolStub::new(); + stub.protocol_version = guardian_module_sdk::PROTOCOL_VERSION + 1; + let pipeline = ModulePipeline::from_instances(vec![instance( + "screening", + &[HOOK], + OnError::Deny, + Arc::new(stub), + )]); + run(&pipeline) + .await + .expect("the module allows until a probe finds it incompatible"); + pipeline.probe().await; + assert_eq!(pipeline.breakers().state("screening"), CircuitState::Open); + assert!(matches!( + run(&pipeline).await, + Err(GuardianError::ModuleUnavailable { .. }) + )); + pipeline.probe().await; + assert_eq!( + pipeline.breakers().state("screening"), + CircuitState::Open, + "it stays open while the probe keeps failing" + ); + } + + #[tokio::test] + async fn probes_a_module_does_not_answer_count_toward_its_breaker() { + let pipeline = ModulePipeline::from_instances(vec![instance( + "screening", + &[HOOK], + OnError::Deny, + Arc::new(Undescribed), + )]) + .with_limits(Limits { + breaker_failures: 2, + ..Limits::default() + }); + pipeline.probe().await; + assert_eq!(pipeline.breakers().state("screening"), CircuitState::Closed); + pipeline.probe().await; + assert_eq!( + pipeline.breakers().state("screening"), + CircuitState::Open, + "no request had to find the module down" + ); + } + + #[tokio::test] + async fn a_healthy_probe_half_opens_and_a_failing_one_leaves_the_circuit_open() { + let healthy = crate::modules::testing::instance_with_params( + "caps", + &[HOOK], + Arc::new(guardian_module_sdk::policies::RecipientPolicy), + serde_json::json!({}), + ); + let (down, _) = hanging("screening", OnError::Deny, Duration::from_millis(20)); + let pipeline = ModulePipeline::from_instances(vec![healthy, down]).with_limits(Limits { + breaker_failures: 1, + ..Limits::default() + }); + pipeline.breakers().failed("caps"); + pipeline.breakers().failed("screening"); + pipeline.probe().await; + assert_eq!(pipeline.breakers().state("caps"), CircuitState::HalfOpen); + assert_eq!(pipeline.breakers().state("screening"), CircuitState::Open); + } + + /// Allows every request but never answers `Describe`. + struct Undescribed; + + #[async_trait::async_trait] + impl guardian_module_sdk::Module for Undescribed { + async fn describe( + &self, + _: &guardian_module_sdk::DescribeRequest, + ) -> Result { + Err(guardian_module_sdk::ModuleError::Unavailable( + "no answer".into(), + )) + } + + async fn validate_params( + &self, + _: &[u8], + ) -> Result { + Ok(guardian_module_sdk::ParamsVerdict::ok()) + } + + async fn evaluate( + &self, + _: &HookRequest, + ) -> Result { + Ok(guardian_module_sdk::Decision::allow()) + } + } +} diff --git a/crates/server/src/modules/pipeline/startup.rs b/crates/server/src/modules/pipeline/startup.rs new file mode 100644 index 00000000..21707495 --- /dev/null +++ b/crates/server/src/modules/pipeline/startup.rs @@ -0,0 +1,774 @@ +//! Startup reconciliation: the catalog file and the stored module state become the running +//! pipeline. It runs once per process, before any request, in this order: +//! +//! 1. The catalog's params are checked against the size cap. +//! 2. The stored instance rows are read and applied to the catalog: the stored enabled flag and +//! operator-managed global params replace the catalog's, except that an instance the catalog +//! requires is enabled ([`Stored::apply_to`]). +//! 3. The instances are built and checked against their modules +//! ([`Registry::instantiate`](crate::modules::registry::Registry::instantiate)). A failure here +//! stops startup before anything is written. +//! 4. The startup writes ([`StartupWrites`]): the catalog-required enables, the seeds of +//! instances new to this Guardian, and the params a module migrated. +//! 5. Instances whose module did not answer start with their breaker held open, and each health +//! probe runs their checks until they pass. + +use std::collections::{HashMap, HashSet}; +use std::sync::{Arc, RwLock}; + +use super::{Cache, ModulePipeline}; +use crate::modules::breaker::Breakers; +use crate::modules::catalog::Catalog; +use crate::modules::limits::Limits; +use crate::modules::registry::{Instance, Instantiated, Registry}; +use crate::modules::store::{Change, InstanceRow, ModuleStore}; + +/// The rules every stored params value follows, applied to what a module returns as normalized +/// params: within the size cap and free of secret references. +pub(super) fn storable(limits: &Limits, params: &serde_json::Value) -> Result<(), String> { + limits.check_params_size(params)?; + if crate::modules::catalog::contains_secret_reference(params) { + return Err("normalized params contain a secret reference".into()); + } + Ok(()) +} + +/// The stored instance rows as startup found them, by module id. +struct Stored { + rows: HashMap, +} + +/// What the stored state changes in the catalog before the instances are built. +struct Applied { + /// Operator-managed global params that differ from the catalog's and apply instead. + effective: HashMap, + /// Instances whose stored seed differs from the catalog's params. + seed_drift: HashSet, + /// Instances stored as disabled that the catalog declares enabled and not + /// operator-disableable, so startup enables them. + enabled_by_catalog: Vec, +} + +impl Stored { + async fn read(store: &dyn ModuleStore) -> Result { + Ok(Self { + rows: store + .instances() + .await? + .into_iter() + .map(|row| (row.module_id.clone(), row)) + .collect(), + }) + } + + /// The instances this Guardian has run before. + fn known(&self) -> HashSet { + self.rows.keys().cloned().collect() + } + + fn contains(&self, module_id: &str) -> bool { + self.rows.contains_key(module_id) + } + + fn global_params(&self, module_id: &str) -> Option<&serde_json::Value> { + self.rows.get(module_id).map(|row| &row.global_params) + } + + /// Applies the stored state to every catalog instance it has a row for. The stored flag is + /// the switch, with one exception: an instance the catalog declares enabled and not + /// operator-disableable cannot be left off by a disable that was allowed under an earlier + /// catalog, and switching it on only tightens policy. + fn apply_to(&self, catalog: &mut Catalog) -> Applied { + let mut applied = Applied { + effective: HashMap::new(), + seed_drift: HashSet::new(), + enabled_by_catalog: Vec::new(), + }; + for config in &mut catalog.instances { + let Some(row) = self.rows.get(&config.id) else { + continue; + }; + if !config.file_managed_params && row.seeded_params != config.params { + applied.seed_drift.insert(config.id.clone()); + } + let catalog_requires_it = + !row.enabled && config.catalog_enabled && !config.operator_can_disable; + if catalog_requires_it { + tracing::warn!(module = %config.id, "Stored flag disables an instance the catalog declares enabled and not operator-disableable; enabling it"); + applied.enabled_by_catalog.push(config.id.clone()); + } else if row.enabled != config.catalog_enabled { + tracing::warn!(module = %config.id, enabled = row.enabled, "Catalog `enabled` differs from the stored runtime flag; the stored flag applies"); + } + config.enabled = row.enabled || catalog_requires_it; + if !config.file_managed_params && row.global_params != config.params { + tracing::warn!(module = %config.id, "Catalog params differ from the operator-managed global params; the stored params apply"); + applied + .effective + .insert(config.id.clone(), row.global_params.clone()); + } + } + applied + } +} + +/// The writes startup makes once the instances are built, each recorded in the params history +/// with startup as its operator. +struct StartupWrites<'a> { + store: &'a dyn ModuleStore, + limits: &'a Limits, + now: &'a str, +} + +impl StartupWrites<'_> { + fn change<'c>(&self, operator: &'c str, reason: &'c str) -> Change<'c> { + Change { + operator, + reason, + at: self.now.to_string(), + } + } + + async fn enable_required(&self, module_ids: &[String]) -> Result<(), String> { + for module_id in module_ids { + self.store + .set_enabled( + module_id, + true, + &self.change( + "catalog", + "the catalog declares the instance enabled and not operator-disableable", + ), + ) + .await?; + } + Ok(()) + } + + /// Seeds every catalog instance without a stored row: with the module's normalized form of + /// the catalog params when it is storable, an empty object for file-managed params. + async fn seed_new( + &self, + catalog: &Catalog, + stored: &Stored, + normalized: &HashMap, + ) -> Result<(), String> { + for config in catalog + .instances + .iter() + .filter(|config| !stored.contains(&config.id)) + { + let seed = if config.file_managed_params { + serde_json::json!({}) + } else { + normalized + .get(&config.id) + .filter(|params| storable(self.limits, params).is_ok()) + .unwrap_or(&config.params) + .clone() + }; + self.store + .seed_instance(&config.id, config.enabled, &seed, self.now) + .await?; + } + Ok(()) + } + + /// Stores the form a module normalized stored global params into, only while they are still + /// the value startup read, so an operator's newer write is never overwritten. + async fn store_migrations( + &self, + instances: &[Instance], + stored: &Stored, + normalized: &HashMap, + ) -> Result<(), String> { + for instance in instances + .iter() + .filter(|instance| !instance.config.file_managed_params) + { + let (Some(params), Some(read)) = ( + normalized.get(&instance.config.id), + stored.global_params(&instance.config.id), + ) else { + continue; + }; + if let Err(error) = storable(self.limits, params) { + tracing::warn!(module = %instance.config.id, %error, "Module's normalized params break the params rules; kept the stored params"); + continue; + } + let operator = format!( + "module:{}", + instance.build.as_deref().unwrap_or(&instance.config.kind) + ); + let migrated = self + .store + .set_global_if( + &instance.config.id, + read, + params.clone(), + &self.change(&operator, "params migrated by the module"), + ) + .await?; + if migrated.is_some() { + tracing::info!(module = %instance.config.id, %operator, "Module normalized its stored global params; stored the migrated form"); + } else { + tracing::warn!(module = %instance.config.id, "Global params changed while the module migrated them; kept the newer value, migration retries next start"); + } + } + Ok(()) + } +} + +impl ModulePipeline { + /// Reconciles the catalog with the stored state and builds the pipeline (see the module + /// documentation for the steps). + pub async fn new( + network_id: &'static str, + mut catalog: Catalog, + registry: &Registry, + store: Arc, + now: String, + limits: Limits, + ) -> Result { + for config in &catalog.instances { + limits + .check_params_size(&config.params) + .map_err(|e| format!("module {}: catalog {e}", config.id))?; + } + let stored = Stored::read(store.as_ref()).await?; + let applied = stored.apply_to(&mut catalog); + let Instantiated { + instances, + normalized, + unreachable, + } = registry + .instantiate(&catalog, &applied.effective, &stored.known()) + .await?; + let writes = StartupWrites { + store: store.as_ref(), + limits: &limits, + now: &now, + }; + writes.enable_required(&applied.enabled_by_catalog).await?; + writes.seed_new(&catalog, &stored, &normalized).await?; + writes + .store_migrations(&instances, &stored, &normalized) + .await?; + let breakers = Arc::new(Breakers::new(limits.breaker_failures)); + for module_id in &unreachable { + breakers.hold_open(module_id); + } + Ok(Self { + instances, + store, + cache: RwLock::new(Cache::default()), + views: Arc::default(), + breakers, + unchecked: std::sync::Mutex::new(unreachable), + limits, + catalog_hash: catalog.hash, + network_id, + seed_drift: applied.seed_drift, + assignment_report: std::sync::Mutex::new((0, 0)), + }) + } +} + +#[cfg(test)] +mod tests { + use guardian_module_sdk::HookRequest; + + use super::super::*; + use crate::modules::breaker::CircuitState; + use crate::modules::catalog::{Catalog, HookName}; + use crate::modules::registry::Registry; + use crate::modules::store::ModuleStore; + + const HOOK: HookName = HookName::BeforeTransactionApproved; + + async fn run(pipeline: &ModulePipeline) -> Result<(), GuardianError> { + pipeline + .run(HOOK, "0xacc", || Ok(HookRequest::default())) + .await + } + + fn caps_catalog(params: &str) -> Catalog { + Catalog::parse( + &format!( + r#" +[[module]] +id = "caps" +kind = "spending-limit" +scope = "all" +hooks = ["before_transaction_approved"] +timeout_ms = 50 +params = {params} +"# + ), + None, + ) + .unwrap() + } + + #[tokio::test] + async fn invalid_catalog_params_stop_startup_without_seeding_them() { + let store: Arc = + Arc::new(crate::modules::store::FsModuleStore::in_memory()); + let registry = Registry::first_party(); + let now = "2026-10-15T00:00:00Z".to_string(); + let started = ModulePipeline::new( + "local", + caps_catalog(r#"{ max_per_transactionx = {} }"#), + ®istry, + store.clone(), + now.clone(), + crate::modules::limits::Limits::default(), + ) + .await; + assert!(started.is_err()); + assert!(store.instances().await.unwrap().is_empty()); + + let fixed = caps_catalog( + r#"{ max_per_transaction = { "0x0000000000000000000000000000aa" = "5" } }"#, + ); + let started = ModulePipeline::new( + "local", + fixed, + ®istry, + store.clone(), + now, + crate::modules::limits::Limits::default(), + ) + .await + .expect("the corrected catalog starts"); + assert!( + started.instances()[0] + .build + .as_deref() + .is_some_and(|build| build.starts_with("spending-limit")) + ); + assert_eq!(store.instances().await.unwrap().len(), 1); + } + + #[tokio::test] + async fn stored_params_not_the_stale_catalog_seed_are_checked_at_startup() { + let store: Arc = + Arc::new(crate::modules::store::FsModuleStore::in_memory()); + let registry = Registry::first_party(); + let now = "2026-10-15T00:00:00Z".to_string(); + store + .seed_instance( + "caps", + true, + &serde_json::json!({ "max_per_transaction": {} }), + &now, + ) + .await + .unwrap(); + ModulePipeline::new( + "local", + caps_catalog(r#"{ max_per_transactionx = {} }"#), + ®istry, + store.clone(), + now.clone(), + crate::modules::limits::Limits::default(), + ) + .await + .expect("the stored params apply, so the stale seed is not checked"); + + store + .set_global( + "caps", + serde_json::json!({ "unknown": true }), + &crate::modules::store::Change { + operator: "0xop", + reason: "test", + at: now.clone(), + }, + ) + .await + .unwrap(); + let valid_seed = caps_catalog(r#"{ max_per_transaction = {} }"#); + assert!( + ModulePipeline::new( + "local", + valid_seed, + ®istry, + store, + now, + crate::modules::limits::Limits::default() + ) + .await + .is_err() + ); + } + + #[tokio::test] + async fn normalized_params_that_break_the_params_rules_are_not_stored() { + use crate::modules::testing::{FixedFactory, ProtocolStub}; + let catalog = Catalog::parse( + r#" +[[module]] +id = "migrating" +kind = "protocol-stub" +scope = "all" +hooks = ["before_transaction_approved"] +timeout_ms = 50 +params = { old_name = 5 } +"#, + None, + ) + .unwrap(); + for normalized in [ + serde_json::json!({ "new_name": "x".repeat(200) }), + serde_json::json!({ "key": { "$secret": "vendor-key" } }), + ] { + let mut stub = ProtocolStub::new(); + stub.normalized = Some(normalized.clone()); + let mut registry = Registry::first_party(); + registry + .register("protocol-stub", Arc::new(FixedFactory(Arc::new(stub)))) + .unwrap(); + let store: Arc = + Arc::new(crate::modules::store::FsModuleStore::in_memory()); + ModulePipeline::new( + "local", + catalog.clone(), + ®istry, + store.clone(), + "2026-10-16T00:00:00Z".to_string(), + crate::modules::limits::Limits { + params_max_bytes: 100, + ..Default::default() + }, + ) + .await + .unwrap(); + assert_eq!( + store.instances().await.unwrap()[0].global_params, + serde_json::json!({ "old_name": 5 }), + "kept the catalog params instead of {normalized}" + ); + } + } + + const OUTAGE_CATALOG: &str = r#" +[[module]] +id = "screening" +kind = "outage-stub" +scope = "all" +hooks = ["before_transaction_approved"] +timeout_ms = 50 +"#; + + async fn start_with( + module: Arc, + catalog: &str, + store: Arc, + ) -> Result { + let mut registry = Registry::first_party(); + registry + .register( + "outage-stub", + Arc::new(crate::modules::testing::FixedFactory(module)), + ) + .unwrap(); + ModulePipeline::new( + "local", + Catalog::parse(catalog, None).unwrap(), + ®istry, + store, + "2026-11-10T00:00:00Z".to_string(), + crate::modules::limits::Limits::default(), + ) + .await + } + + #[tokio::test] + async fn a_known_instance_whose_module_is_down_starts_unavailable_and_recovers_on_a_probe() { + use std::sync::atomic::Ordering; + let module = crate::modules::testing::Outage::new(false); + let store: Arc = + Arc::new(crate::modules::store::FsModuleStore::in_memory()); + start_with(module.clone(), OUTAGE_CATALOG, store.clone()) + .await + .expect("the first start passes the checks and makes the instance known"); + + module.set_down(true); + let pipeline = start_with(module.clone(), OUTAGE_CATALOG, store) + .await + .expect("a module outage does not keep the Guardian from restarting"); + assert_eq!(pipeline.breakers().state("screening"), CircuitState::Open); + assert!( + matches!( + run(&pipeline).await, + Err(GuardianError::ModuleUnavailable { .. }) + ), + "its accounts are refused meanwhile, not approved" + ); + + pipeline.probe().await; + assert_eq!( + pipeline.breakers().state("screening"), + CircuitState::Open, + "still down" + ); + + module.set_down(false); + pipeline.probe().await; + assert_eq!( + pipeline.breakers().state("screening"), + CircuitState::HalfOpen + ); + run(&pipeline).await.expect("the module decides again"); + assert_eq!(pipeline.breakers().state("screening"), CircuitState::Closed); + assert_eq!(module.evaluations.load(Ordering::SeqCst), 1); + } + + #[tokio::test] + async fn an_instance_new_to_this_guardian_must_answer_at_startup() { + let module = crate::modules::testing::Outage::new(true); + let store: Arc = + Arc::new(crate::modules::store::FsModuleStore::in_memory()); + let refused = start_with(module, OUTAGE_CATALOG, store.clone()) + .await + .err() + .expect("a wrong endpoint in a new catalog entry is found at deploy time"); + assert!(refused.contains("screening"), "{refused}"); + assert!(store.instances().await.unwrap().is_empty()); + } + + #[tokio::test] + async fn a_known_instance_that_answers_incompatibly_still_stops_startup() { + use crate::modules::testing::{FixedFactory, ProtocolStub}; + const CATALOG: &str = r#" +[[module]] +id = "screening" +kind = "protocol-stub" +scope = "all" +hooks = ["before_transaction_approved"] +timeout_ms = 50 +"#; + let start = |protocol_version: u32, store: Arc| async move { + let mut stub = ProtocolStub::new(); + stub.protocol_version = protocol_version; + let mut registry = Registry::first_party(); + registry + .register("protocol-stub", Arc::new(FixedFactory(Arc::new(stub)))) + .unwrap(); + ModulePipeline::new( + "local", + Catalog::parse(CATALOG, None).unwrap(), + ®istry, + store, + "2026-11-10T00:00:00Z".to_string(), + crate::modules::limits::Limits::default(), + ) + .await + }; + let store: Arc = + Arc::new(crate::modules::store::FsModuleStore::in_memory()); + start(guardian_module_sdk::PROTOCOL_VERSION, store.clone()) + .await + .unwrap(); + assert!( + start(guardian_module_sdk::PROTOCOL_VERSION + 1, store) + .await + .is_err(), + "only a module that does not answer may start unavailable" + ); + } + + #[tokio::test] + async fn an_instance_the_catalog_requires_is_enabled_at_startup() { + let disabled_in_store = || async { + let store: Arc = + Arc::new(crate::modules::store::FsModuleStore::in_memory()); + store + .seed_instance("screening", false, &serde_json::json!({}), "t0") + .await + .unwrap(); + store + }; + + let store = disabled_in_store().await; + let pipeline = start_with( + crate::modules::testing::Outage::new(false), + OUTAGE_CATALOG, + store.clone(), + ) + .await + .unwrap(); + assert!( + store.instances().await.unwrap()[0].enabled, + "enabled and not operator-disableable in the catalog: a stored disable does not stand" + ); + let history = store.history("screening", None, 10).await.unwrap(); + assert_eq!(history[0].operator, "catalog"); + assert_eq!(history[0].new, serde_json::json!({ "enabled": true })); + assert!( + pipeline + .applies(HookName::BeforeTransactionApproved, "0xacc") + .await + .unwrap() + ); + + let store = disabled_in_store().await; + let disableable = format!("{OUTAGE_CATALOG}operator_can_disable = true\n"); + let pipeline = start_with( + crate::modules::testing::Outage::new(false), + &disableable, + store.clone(), + ) + .await + .unwrap(); + assert!( + !store.instances().await.unwrap()[0].enabled, + "an operator may hold a disableable instance off, so the stored flag stands" + ); + assert!( + !pipeline + .applies(HookName::BeforeTransactionApproved, "0xacc") + .await + .unwrap() + ); + } + + #[tokio::test] + async fn startup_stores_params_the_module_migrated() { + use crate::modules::testing::{FixedFactory, ProtocolStub}; + let catalog = || { + Catalog::parse( + r#" +[[module]] +id = "migrating" +kind = "protocol-stub" +scope = "all" +hooks = ["before_transaction_approved"] +timeout_ms = 50 +params = { old_name = 5 } +"#, + None, + ) + .unwrap() + }; + let mut stub = ProtocolStub::new(); + stub.normalized = Some(serde_json::json!({ "new_name": 5 })); + let mut registry = Registry::first_party(); + registry + .register("protocol-stub", Arc::new(FixedFactory(Arc::new(stub)))) + .unwrap(); + let store: Arc = + Arc::new(crate::modules::store::FsModuleStore::in_memory()); + let now = "2026-10-16T00:00:00Z".to_string(); + + ModulePipeline::new( + "local", + catalog(), + ®istry, + store.clone(), + now.clone(), + crate::modules::limits::Limits::default(), + ) + .await + .unwrap(); + let seeded = store.instances().await.unwrap(); + assert_eq!( + seeded[0].global_params, + serde_json::json!({ "new_name": 5 }), + "a new instance is seeded in the migrated shape" + ); + + store + .set_global( + "migrating", + serde_json::json!({ "old_name": 7 }), + &crate::modules::store::Change { + operator: "0xop", + reason: "old shape", + at: now.clone(), + }, + ) + .await + .unwrap(); + ModulePipeline::new( + "local", + catalog(), + ®istry, + store.clone(), + now, + crate::modules::limits::Limits::default(), + ) + .await + .unwrap(); + assert_eq!( + store.instances().await.unwrap()[0].global_params, + serde_json::json!({ "new_name": 5 }) + ); + let last = store.history("migrating", None, 1).await.unwrap().remove(0); + assert_eq!(last.operator, "module:protocol-stub 1"); + assert_eq!(last.reason, "params migrated by the module"); + assert_eq!(last.previous, serde_json::json!({ "old_name": 7 })); + } + + /// An operator lowers the stored params while the module is migrating them at startup; + /// the migration must not replace the operator's newer value with its stale result. + #[tokio::test] + async fn a_startup_migration_never_overwrites_a_newer_operator_write() { + use crate::modules::testing::{FixedFactory, ProtocolStub, RacingStore, RacingWrite}; + let catalog = Catalog::parse( + r#" +[[module]] +id = "migrating" +kind = "protocol-stub" +scope = "all" +hooks = ["before_transaction_approved"] +timeout_ms = 50 +params = { old_name = 1000 } +"#, + None, + ) + .unwrap(); + let mut stub = ProtocolStub::new(); + stub.normalized = Some(serde_json::json!({ "new_name": 1000 })); + let mut registry = Registry::first_party(); + registry + .register("protocol-stub", Arc::new(FixedFactory(Arc::new(stub)))) + .unwrap(); + let store = Arc::new(RacingStore::new()); + store + .inner + .seed_instance( + "migrating", + true, + &serde_json::json!({ "old_name": 1000 }), + "2026-10-16T00:00:00Z", + ) + .await + .unwrap(); + *store.before_set_global_if.lock().unwrap() = vec![RacingWrite::Global( + "migrating", + serde_json::json!({ "new_name": 100 }), + )]; + + ModulePipeline::new( + "local", + catalog, + ®istry, + store.clone(), + "2026-10-16T00:00:02Z".into(), + crate::modules::limits::Limits::default(), + ) + .await + .unwrap(); + assert_eq!( + store.instances().await.unwrap()[0].global_params, + serde_json::json!({ "new_name": 100 }), + "the operator's cap of 100 stays" + ); + let last = store.history("migrating", None, 1).await.unwrap().remove(0); + assert_eq!( + last.operator, "0xracing-operator", + "no migration entry after it" + ); + } +} diff --git a/docs/architecture/services.md b/docs/architecture/services.md index 5df82376..13d0dc71 100644 --- a/docs/architecture/services.md +++ b/docs/architecture/services.md @@ -295,7 +295,7 @@ A hook pipeline the server consults before it approves anything ([RFC 0002](../rfcs/0002-guardian-modules.md), [guide](../guides/policy-modules/README.md)). It is off unless `GUARDIAN_MODULES_CONFIG` names a catalog file, and `AppState.modules` is then -the one [`ModulePipeline`](../../crates/server/src/modules/pipeline.rs) every +the one [`ModulePipeline`](../../crates/server/src/modules/pipeline/mod.rs) every request path uses. | File | Purpose | @@ -304,7 +304,9 @@ request path uses. | [`registry.rs`](../../crates/server/src/modules/registry.rs), [`grpc_kind.rs`](../../crates/server/src/modules/grpc_kind.rs) | Turns catalog entries into module instances: in-process kinds registered on the builder, or the remote `grpc` kind. Runs the startup and health checks (`Describe`, params validation). | | [`secrets.rs`](../../crates/server/src/modules/secrets.rs) | Resolves the tokens, client certificates and `$secret` params a catalog names, from AWS Secrets Manager or owner-only files. | | [`store.rs`](../../crates/server/src/modules/store.rs), [`postgres_store.rs`](../../crates/server/src/modules/postgres_store.rs) | The mutable state: enabled flags, global params, account layers and assignments, params history, an instance params version moved by instance writes and a version per account moved by that account's writes. Files on a filesystem build, tables on Postgres. | -| [`pipeline.rs`](../../crates/server/src/modules/pipeline.rs) | Plans which instances run for an account at a hook (one store read) and runs them in order under the evaluation budget; applies `on_error`; returns what the evaluation ran with. | +| [`pipeline/mod.rs`](../../crates/server/src/modules/pipeline/mod.rs) | Plans which instances run for an account at a hook (one store read) and runs them in order under the evaluation budget; applies `on_error`; returns what the evaluation ran with. | +| [`pipeline/startup.rs`](../../crates/server/src/modules/pipeline/startup.rs) | Builds the pipeline once at startup: applies the stored flags and params to the catalog, builds and checks the instances, then seeds new instances, enables those the catalog requires and stores params a module migrated. Nothing is written if an instance fails its checks. | +| [`pipeline/budget.rs`](../../crates/server/src/modules/pipeline/budget.rs), [`pipeline/probe.rs`](../../crates/server/src/modules/pipeline/probe.rs) | The per-account budget check on operator writes and the over-budget recount; the health probe loop and the state gauges. | | [`breaker.rs`](../../crates/server/src/modules/breaker.rs), [`limits.rs`](../../crates/server/src/modules/limits.rs) | Per-instance circuit breakers fed by calls and by the `Describe` probe; the budget, size caps and probe interval. | | [`request.rs`](../../crates/server/src/modules/request.rs), [`network/miden/module_views.rs`](../../crates/server/src/network/miden/module_views.rs) | Builds what a module receives: account views before and after, the transaction projection, the registration state. Views are cached by state commitment. | | [`admin.rs`](../../crates/server/src/modules/admin.rs), [`api/dashboard_modules.rs`](../../crates/server/src/api/dashboard_modules.rs) | Operator writes and views behind `/dashboard/modules*` and `/dashboard/accounts/{id}/modules*`. | From 5c08b73bab014ef77bd4266764a2646090445501 Mon Sep 17 00:00:00 2001 From: Zeljko Date: Tue, 10 Nov 2026 12:33:54 +0100 Subject: [PATCH 094/105] test(qualification): a live recipient denylist scenario on both SDKs (#251) live-module-recipient-1of1-ecdsa assigns the stack's new qual-recipient instance (recipient-policy, params disclosed) with a denylist naming the funding faucet, which the scenario never pays, and reads it back through the account's own policy listing. A payment to the faucet is refused at the check and at creation with recipient_blocked; a payment to the treasury passes, is signed by GUARDIAN after the approval hook runs on the real transaction, and lands. The denylist names someone, so deny_unknown is on and a fee note read as a payment would refuse the send. New actions module-recipient-assign and module-recipient-refuses in the Rust and TypeScript drivers; the cap scenario's assign step shares their helper. Required on testnet, excluded on devnet like the cap scenario. --- .../qualification-driver/src/manifest/mod.rs | 4 + .../qualification-driver/src/scenario/mod.rs | 6 + .../src/scenario/modules.rs | 118 +++++++++++++++--- docs/QUALIFICATION.md | 12 +- .../tests/qualification/actions/live.ts | 95 ++++++++++++-- .../tests/qualification/actions/modules.ts | 1 + .../tests/qualification/runner.ts | 4 + qualification/manifest/manifest.json | 25 ++++ qualification/manifest/matrix.toml | 2 + qualification/manifest/scenarios.toml | 19 +++ qualification/stack/lib/modules.sh | 10 ++ 11 files changed, 272 insertions(+), 24 deletions(-) diff --git a/crates/qualification-driver/src/manifest/mod.rs b/crates/qualification-driver/src/manifest/mod.rs index 2376983f..1004435d 100644 --- a/crates/qualification-driver/src/manifest/mod.rs +++ b/crates/qualification-driver/src/manifest/mod.rs @@ -211,6 +211,8 @@ pub enum Action { ModuleBreakGlass, ModuleCapAssign, ModuleCapRefuses, + ModuleRecipientAssign, + ModuleRecipientRefuses, Unknown(String), } @@ -295,6 +297,8 @@ impl From for Action { "module-break-glass" => Self::ModuleBreakGlass, "module-cap-assign" => Self::ModuleCapAssign, "module-cap-refuses" => Self::ModuleCapRefuses, + "module-recipient-assign" => Self::ModuleRecipientAssign, + "module-recipient-refuses" => Self::ModuleRecipientRefuses, other => Self::Unknown(other.to_string()), } } diff --git a/crates/qualification-driver/src/scenario/mod.rs b/crates/qualification-driver/src/scenario/mod.rs index 42915eb2..98909de4 100644 --- a/crates/qualification-driver/src/scenario/mod.rs +++ b/crates/qualification-driver/src/scenario/mod.rs @@ -374,6 +374,12 @@ impl Runner { } Action::ModuleCapAssign => Some(modules::assign_cap(self).await), Action::ModuleCapRefuses => Some(modules::assert_cap_refuses(self).await), + Action::ModuleRecipientAssign => { + Some(modules::assign_recipient_denylist(self).await) + } + Action::ModuleRecipientRefuses => { + Some(modules::assert_recipient_refuses(self).await) + } _ => None, } } else { diff --git a/crates/qualification-driver/src/scenario/modules.rs b/crates/qualification-driver/src/scenario/modules.rs index f54fde39..51383f60 100644 --- a/crates/qualification-driver/src/scenario/modules.rs +++ b/crates/qualification-driver/src/scenario/modules.rs @@ -26,6 +26,7 @@ const GATE: &str = "qual-gate"; const CAP: &str = "qual-cap"; const SWITCH: &str = "qual-switch"; const REMOTE: &str = "qual-remote"; +const RECIPIENT: &str = "qual-recipient"; /// A signer commitment nobody holds. Checked against every signer, an allowlist of only this /// refuses every transaction of the fixture account. @@ -554,6 +555,33 @@ async fn assert_switch_survived(operator: &Operator<'_>) -> ActionOutcome { /// Assigns the gate to the scenario's account with a cap of exactly what `asset-send` sends, /// and reads it back through the account's own policy listing. pub async fn assign_cap(runner: &Runner) -> ActionOutcome { + assign_to_funded_account(runner, CAP, |faucet| { + let mut limit = serde_json::Map::new(); + limit.insert(faucet.to_hex(), json!(super::live::P2ID_AMOUNT.to_string())); + json!({ "max_per_transaction": limit }) + }) + .await +} + +/// Assigns `qual-recipient` to the scenario's account with a denylist naming the funding +/// faucet, an account the scenario never pays, and reads it back through the account's own +/// policy listing. `deny_unknown` is left unset, so it is on. +pub async fn assign_recipient_denylist(runner: &Runner) -> ActionOutcome { + assign_to_funded_account( + runner, + RECIPIENT, + |faucet| json!({ "denylist": [faucet.to_hex()] }), + ) + .await +} + +/// Assigns `module` to the scenario's account with the params `params` builds from the funding +/// faucet, and checks the account's own policy listing shows them. +async fn assign_to_funded_account( + runner: &Runner, + module: &str, + params: impl FnOnce(miden_protocol::account::AccountId) -> Value, +) -> ActionOutcome { let Some(fixtures) = runner.fixtures.as_ref() else { return ActionOutcome::failed_setup("the server fixtures were not loaded"); }; @@ -563,18 +591,16 @@ pub async fn assign_cap(runner: &Runner) -> ActionOutcome { }; let Some(faucet) = session.faucet else { return ActionOutcome::failed_setup( - "the account was never funded, so there is no asset to cap", + "the account was never funded, so there is no asset to build the params from", ); }; let operator = match Operator::login(runner, fixtures).await { Ok(operator) => operator, Err(outcome) => return outcome, }; - let mut limit = serde_json::Map::new(); - limit.insert(faucet.to_hex(), json!(super::live::P2ID_AMOUNT.to_string())); - let cap = json!({ "max_per_transaction": limit }); + let params = params(faucet); if let Err(outcome) = operator - .assign(&session.account_id.to_string(), CAP, cap.clone()) + .assign(&session.account_id.to_string(), module, params.clone()) .await { return outcome; @@ -588,19 +614,19 @@ pub async fn assign_cap(runner: &Runner) -> ActionOutcome { )); } }; - match policies.iter().find(|policy| policy.module_id == CAP) { + match policies.iter().find(|policy| policy.module_id == module) { Some(policy) if [&policy.params, &policy.account_layer] .iter() - .any(|params| params.as_ref() == Some(&cap)) => + .any(|listed| listed.as_ref() == Some(¶ms)) => { ActionOutcome::Passed } Some(policy) => ActionOutcome::failed_product(format!( - "the account's policies list {CAP} without the cap it was assigned: {policy:?}" + "the account's policies list {module} without the params it was assigned: {policy:?}" )), None => ActionOutcome::failed_product(format!( - "the account's policies do not list the {CAP} it was assigned: {policies:?}" + "the account's policies do not list the {module} it was assigned: {policies:?}" )), } } @@ -624,12 +650,22 @@ pub async fn assert_cap_refuses(runner: &Runner) -> ActionOutcome { let client = &mut session.clients[0]; let over_check = settled!(client.check_transaction(send(amount + 1))); - let over_check = expect_cap_denied("the check of a payment over the cap", over_check.map(drop)); + let over_check = expect_module_denied( + "the check of a payment over the cap", + over_check.map(drop), + CAP, + "amount_cap_exceeded", + ); if !matches!(over_check, ActionOutcome::Passed) { return over_check; } let over = settled!(client.propose_transaction(send(amount + 1))); - let over = expect_cap_denied("a payment over the cap", over.map(drop)); + let over = expect_module_denied( + "a payment over the cap", + over.map(drop), + CAP, + "amount_cap_exceeded", + ); if !matches!(over, ActionOutcome::Passed) { return over; } @@ -642,16 +678,70 @@ pub async fn assert_cap_refuses(runner: &Runner) -> ActionOutcome { } } -fn expect_cap_denied(what: &str, result: Result<(), MultisigError>) -> ActionOutcome { +/// A payment to the blocked recipient is refused by the dry-run check and at creation, naming +/// the module and `recipient_blocked`; a payment to the treasury, which the denylist does not +/// name, passes the check. That transaction also carries the fee note, which has no recipient +/// a denylist can check, so it passing shows the fee note is not read as a payment. +pub async fn assert_recipient_refuses(runner: &Runner) -> ActionOutcome { + let mut guard = runner.session.lock().await; + let Some(session) = guard.as_mut() else { + return ActionOutcome::failed_setup("no account has been created in this scenario"); + }; + let (Some(faucet), Some(treasury)) = (session.faucet, session.treasury) else { + return ActionOutcome::failed_setup( + "the account was never funded, so it holds nothing to send", + ); + }; + let amount = super::live::P2ID_AMOUNT; + let client = &mut session.clients[0]; + + let blocked_check = + settled!(client.check_transaction(TransactionType::transfer(faucet, faucet, amount))); + let blocked_check = expect_module_denied( + "the check of a payment to the blocked recipient", + blocked_check.map(drop), + RECIPIENT, + "recipient_blocked", + ); + if !matches!(blocked_check, ActionOutcome::Passed) { + return blocked_check; + } + let blocked = + settled!(client.propose_transaction(TransactionType::transfer(faucet, faucet, amount))); + let blocked = expect_module_denied( + "a payment to the blocked recipient", + blocked.map(drop), + RECIPIENT, + "recipient_blocked", + ); + if !matches!(blocked, ActionOutcome::Passed) { + return blocked; + } + match settled!(client.check_transaction(TransactionType::transfer(treasury, faucet, amount))) { + Ok(_) => ActionOutcome::Passed, + Err(error) => ActionOutcome::failed_product(format!( + "the check of a payment to a recipient the denylist does not name was refused, so \ + the fee note may be read as a payment to an unknown recipient: {error}" + )), + } +} + +/// A multisig SDK call refused by `expected_module` for `expected_reason`. +fn expect_module_denied( + what: &str, + result: Result<(), MultisigError>, + expected_module: &str, + expected_reason: &str, +) -> ActionOutcome { match result { Ok(()) => ActionOutcome::failed_product(format!("{what} was accepted")), Err(MultisigError::ModuleDenied { module: Some(module), reason_code, .. - }) if module == CAP && reason_code == "amount_cap_exceeded" => ActionOutcome::Passed, + }) if module == expected_module && reason_code == expected_reason => ActionOutcome::Passed, Err(error) => ActionOutcome::failed_product(format!( - "{what} was refused, but not by {CAP} for amount_cap_exceeded: {error}" + "{what} was refused, but not by {expected_module} for {expected_reason}: {error}" )), } } diff --git a/docs/QUALIFICATION.md b/docs/QUALIFICATION.md index beca0ed5..01a11e09 100644 --- a/docs/QUALIFICATION.md +++ b/docs/QUALIFICATION.md @@ -85,7 +85,7 @@ gitignored directories, and tears it down afterwards: | A fourth Guardian that offers execution, `server-executing` | a configured prover and a database of its own (`guardian_executing`), so execution requests get past the capability gate in the deterministic profile | | A fifth Guardian that queues chained candidates, `server-queue` | `GUARDIAN_MAX_PENDING_CANDIDATES_PER_ACCOUNT` set to `2` in the deterministic profile and `4` in the live one (`QUAL_QUEUE_DEPTH` overrides it), the main server's acknowledgement identity, and a database of its own, so the candidate queue (issue #17) is qualified as an operator opts into it while the main server keeps the default of one in-flight candidate | | Operator allowlist | generated from the server fixtures via `qualification-driver operator-keys`, so the identities the scenarios sign with cannot drift from the ones the server accepts | -| Policy module catalog | `lib/modules.sh` writes the main server's catalog per run: three in-process instances (`qual-gate` and `qual-switch` of kind `signer-policy`, `qual-cap` of kind `spending-limit`) and one remote `grpc` instance, all scoped `assigned` so no other scenario meets them. The remote one points at a module the Rust driver serves on the host (`host.docker.internal`, on `QUAL_MODULE_PORT`) over TLS, with a certificate a per-run CA signs and a bearer token the server reads through the file secrets backend | +| Policy module catalog | `lib/modules.sh` writes the main server's catalog per run: four in-process instances (`qual-gate` and `qual-switch` of kind `signer-policy`, `qual-cap` of kind `spending-limit`, `qual-recipient` of kind `recipient-policy`) and one remote `grpc` instance, all scoped `assigned` so no other scenario meets them. The remote one points at a module the Rust driver serves on the host (`host.docker.internal`, on `QUAL_MODULE_PORT`) over TLS, with a certificate a per-run CA signs and a bearer token the server reads through the file secrets backend | | Guardian execution | the live profile points the server at the network's public prover (`https://tx-prover..miden.io`, overridable with `QUAL_TX_PROVER_URL`), so it offers execution; the deterministic stack configures none, so execution must be refused | | Postgres password | random per run | | Ports | picked per run, so concurrent runs do not collide | @@ -301,7 +301,7 @@ testnet run of this line fails them along with everything else on 0.17. ### Policy modules -Four scenarios cover policy modules ([RFC 0002](./rfcs/0002-guardian-modules.md)). Every +Five scenarios cover policy modules ([RFC 0002](./rfcs/0002-guardian-modules.md)). Every instance in the stack's catalog is scoped `assigned`, so it applies only to an account a scenario assigns it to through the operator API, and the operator in the allowlist holds `policies:write` for that. @@ -328,6 +328,14 @@ scenario assigns it to through the operator API, and the operator in the allowli transaction, and lands. The funding asset is the network's fee asset, so a fee note counted as a payment would push the capped send over the cap and fail it. Devnet's pairs exclude it for the window reason above. +- `live-module-recipient-1of1-ecdsa` (live, both SDKs, required on testnet): `qual-recipient` + gives the account a denylist naming the funding faucet, which the scenario never pays, and + the account's own policy listing shows it. A payment to the faucet is refused at the check + and at creation with `recipient_blocked`; a payment to the treasury passes, is signed by + GUARDIAN at execution after the approval hook runs on the real transaction, and lands. The + denylist names someone, so `deny_unknown` is on, and the fee note has no recipient a + denylist can check: a fee note read as a payment would refuse the send. Devnet's pairs + exclude it for the same window reason. The deterministic scenarios propose the first threshold-only fixture delta (`queue_1`), not `delta_1`: the fixture generator adds `delta_1`'s signer without the approver scheme entry a diff --git a/packages/miden-multisig-client/tests/qualification/actions/live.ts b/packages/miden-multisig-client/tests/qualification/actions/live.ts index cf25115e..d984deaa 100644 --- a/packages/miden-multisig-client/tests/qualification/actions/live.ts +++ b/packages/miden-multisig-client/tests/qualification/actions/live.ts @@ -26,7 +26,7 @@ import { type LiveSession, type Scheme, } from '../live.js'; -import { CAP, expectDenied } from './modules.js'; +import { CAP, RECIPIENT, expectDenied } from './modules.js'; import { setAccountModules, setAccountPaused } from './operator.js'; import type { ActionContext, ActionOutcome } from '../runner.js'; @@ -3428,33 +3428,62 @@ export async function abandonStrandedHeadAndRecover( * own policy listing. Mirrors `assign_cap` in the Rust driver. */ export async function assignModuleCap(context: ActionContext, scenarioId: string): Promise { + return assignToFundedAccount(context, scenarioId, CAP, (faucetId) => ({ + max_per_transaction: { [faucetId]: P2ID_AMOUNT.toString() }, + })); +} + +/** + * Assigns the stack's `qual-recipient` module to the scenario's account with a + * denylist naming the funding faucet, an account the scenario never pays, and + * reads it back through the account's own policy listing. `deny_unknown` is + * left unset, so it is on. Mirrors `assign_recipient_denylist` in the Rust + * driver. + */ +export async function assignModuleRecipientDenylist( + context: ActionContext, + scenarioId: string, +): Promise { + return assignToFundedAccount(context, scenarioId, RECIPIENT, (faucetId) => ({ denylist: [faucetId] })); +} + +async function assignToFundedAccount( + context: ActionContext, + scenarioId: string, + moduleId: string, + params: (faucetId: string) => Record, +): Promise { const session = sessions.get(scenarioId); if (!session?.multisig || !session.accountId) { return { kind: 'failed', classification: 'setup', reason: 'no account has been created in this scenario' }; } if (!session.faucetId) { - return { kind: 'failed', classification: 'setup', reason: 'the account was never funded, so there is no asset to cap' }; + return { + kind: 'failed', + classification: 'setup', + reason: 'the account was never funded, so there is no asset to build the params from', + }; } - const cap = { max_per_transaction: { [session.faucetId]: P2ID_AMOUNT.toString() } }; - const assigned = await setAccountModules(context, session.accountId, [{ moduleId: CAP, params: cap }]); + const assignedParams = params(session.faucetId); + const assigned = await setAccountModules(context, session.accountId, [{ moduleId, params: assignedParams }]); if (assigned) return assigned; try { const policies = await session.multisig.getPolicies(); - const policy = policies.find((entry) => entry.moduleId === CAP); + const policy = policies.find((entry) => entry.moduleId === moduleId); if (!policy) { return { kind: 'failed', classification: 'product', - reason: `the account's policies do not list the ${CAP} it was assigned: ${JSON.stringify(policies)}`, + reason: `the account's policies do not list the ${moduleId} it was assigned: ${JSON.stringify(policies)}`, }; } - const expected = JSON.stringify(cap); + const expected = JSON.stringify(assignedParams); if (JSON.stringify(policy.params) !== expected && JSON.stringify(policy.accountLayer) !== expected) { return { kind: 'failed', classification: 'product', - reason: `the account's policies list ${CAP} without the cap it was assigned: ${JSON.stringify(policy)}`, + reason: `the account's policies list ${moduleId} without the params it was assigned: ${JSON.stringify(policy)}`, }; } return { kind: 'passed' }; @@ -3511,3 +3540,53 @@ export async function assertModuleCapRefuses(_context: ActionContext, scenarioId }; } } + +/** + * A payment to the blocked recipient is refused by the dry-run check and at + * creation, naming the module and `recipient_blocked`; a payment to the + * treasury, which the denylist does not name, passes the check. That + * transaction also carries the fee note, which has no recipient a denylist can + * check, so it passing shows the fee note is not read as a payment. Mirrors + * `assert_recipient_refuses` in the Rust driver. + */ +export async function assertModuleRecipientRefuses(_context: ActionContext, scenarioId: string): Promise { + const session = sessions.get(scenarioId); + if (!session?.multisig) { + return { kind: 'failed', classification: 'setup', reason: 'no account has been created in this scenario' }; + } + if (!session.faucetId || !session.treasuryId) { + return { kind: 'failed', classification: 'setup', reason: 'the account was never funded, so it holds nothing to send' }; + } + const multisig = session.multisig; + const faucetId = session.faucetId; + const pay = (recipientId: string) => + ({ type: 'p2id', recipientId, faucetId, amount: P2ID_AMOUNT }) as const; + + const blockedCheck = await expectDenied( + 'the check of a payment to the blocked recipient', + () => proposeWhenSettled(() => multisig.checkTransaction(pay(faucetId))), + RECIPIENT, + 'recipient_blocked', + ); + if (blockedCheck.kind !== 'passed') return blockedCheck; + const blocked = await expectDenied( + 'a payment to the blocked recipient', + () => proposeWhenSettled(() => multisig.createP2idProposal(faucetId, faucetId, P2ID_AMOUNT)), + RECIPIENT, + 'recipient_blocked', + ); + if (blocked.kind !== 'passed') return blocked; + + try { + await proposeWhenSettled(() => multisig.checkTransaction(pay(session.treasuryId!))); + return { kind: 'passed' }; + } catch (error) { + return { + kind: 'failed', + classification: 'product', + reason: + 'the check of a payment to a recipient the denylist does not name was refused, so the fee note may be ' + + `read as a payment to an unknown recipient: ${String(error)}`, + }; + } +} diff --git a/packages/miden-multisig-client/tests/qualification/actions/modules.ts b/packages/miden-multisig-client/tests/qualification/actions/modules.ts index 321b8877..5c0caf37 100644 --- a/packages/miden-multisig-client/tests/qualification/actions/modules.ts +++ b/packages/miden-multisig-client/tests/qualification/actions/modules.ts @@ -8,6 +8,7 @@ import type { ActionContext, ActionOutcome } from '../runner.js'; /** The instance the stack's catalog declares for rules a scenario assigns. */ export const GATE = 'qual-gate'; export const CAP = 'qual-cap'; +export const RECIPIENT = 'qual-recipient'; /** * A signer commitment nobody holds. Checked against every signer, an allowlist diff --git a/packages/miden-multisig-client/tests/qualification/runner.ts b/packages/miden-multisig-client/tests/qualification/runner.ts index 14610e10..eab981d0 100644 --- a/packages/miden-multisig-client/tests/qualification/runner.ts +++ b/packages/miden-multisig-client/tests/qualification/runner.ts @@ -201,6 +201,10 @@ async function runLiveAction( return live.assignModuleCap(context, scenario.id); case 'module-cap-refuses': return live.assertModuleCapRefuses(context, scenario.id); + case 'module-recipient-assign': + return live.assignModuleRecipientDenylist(context, scenario.id); + case 'module-recipient-refuses': + return live.assertModuleRecipientRefuses(context, scenario.id); default: return null; } diff --git a/qualification/manifest/manifest.json b/qualification/manifest/manifest.json index 554e1b72..3493af9f 100644 --- a/qualification/manifest/manifest.json +++ b/qualification/manifest/manifest.json @@ -934,6 +934,31 @@ "step_budget": "PT8M", "title": "A per-account amount cap refuses a payment over it, and a payment at the cap lands with its fee" }, + { + "actions": [ + "account-create", + "account-register", + "asset-transfer", + "note-consume", + "module-recipient-assign", + "module-recipient-refuses", + "asset-send", + "proposal-sign", + "proposal-execute", + "asset-send-assert" + ], + "core": false, + "id": "live-module-recipient-1of1-ecdsa", + "mode": "online", + "profile": "live", + "required": true, + "runtime": "server-side", + "scheme": "ecdsa", + "sdk": "both", + "shape": "1-of-1", + "step_budget": "PT8M", + "title": "A recipient denylist refuses a payment to a blocked account, and a payment elsewhere lands with its fee" + }, { "actions": [ "account-create", diff --git a/qualification/manifest/matrix.toml b/qualification/manifest/matrix.toml index 55691c0e..68d97406 100644 --- a/qualification/manifest/matrix.toml +++ b/qualification/manifest/matrix.toml @@ -59,6 +59,7 @@ excluded_scenarios = [ "live-candidate-queue-stranded-head-1of1-ecdsa", "live-send-override-p2id-2of3-falcon", "live-module-cap-1of1-ecdsa", + "live-module-recipient-1of1-ecdsa", ] [[pair]] @@ -97,4 +98,5 @@ excluded_scenarios = [ "live-candidate-queue-stranded-head-1of1-ecdsa", "live-send-override-p2id-2of3-falcon", "live-module-cap-1of1-ecdsa", + "live-module-recipient-1of1-ecdsa", ] diff --git a/qualification/manifest/scenarios.toml b/qualification/manifest/scenarios.toml index 9bc47d7e..4bb1fb80 100644 --- a/qualification/manifest/scenarios.toml +++ b/qualification/manifest/scenarios.toml @@ -784,6 +784,25 @@ step_budget = "480s" required = true core = false +# A recipient denylist on a real transaction. The denylist names the funding faucet, which the +# scenario never pays: a payment to it is refused at the check and at creation, and a payment +# to the treasury passes, is signed by GUARDIAN after the approval hook runs again, and lands. +# `deny_unknown` is on by default once the denylist names anyone, and the fee note has no +# recipient a denylist can check, so a fee note read as a payment would refuse the send. +[[scenario]] +id = "live-module-recipient-1of1-ecdsa" +title = "A recipient denylist refuses a payment to a blocked account, and a payment elsewhere lands with its fee" +profile = "live" +sdk = "both" +runtime = "server-side" +scheme = "ecdsa" +shape = "1-of-1" +mode = "online" +actions = ["account-create", "account-register", "asset-transfer", "note-consume", "module-recipient-assign", "module-recipient-refuses", "asset-send", "proposal-sign", "proposal-execute", "asset-send-assert"] +step_budget = "480s" +required = true +core = false + # The config-writing procedures encode the signature scheme into the advice # payload they build, and two scheme-binding defects have already been found # here (F8, F13). Running membership changes on one scheme only would leave an diff --git a/qualification/stack/lib/modules.sh b/qualification/stack/lib/modules.sh index 47da2e5a..7ebd6657 100644 --- a/qualification/stack/lib/modules.sh +++ b/qualification/stack/lib/modules.sh @@ -62,6 +62,16 @@ on_error = "deny" disclosure = "params" description = "Qualification spending cap for the accounts a scenario assigns" +[[module]] +id = "qual-recipient" +kind = "recipient-policy" +scope = "assigned" +hooks = ["before_proposal_created", "before_transaction_approved"] +timeout_ms = 200 +on_error = "deny" +disclosure = "params" +description = "Qualification recipient denylist for the accounts a scenario assigns" + [[module]] id = "qual-switch" kind = "signer-policy" From e502567cac838e054dba9cfea72c6adcb9854589 Mon Sep 17 00:00:00 2001 From: Zeljko Date: Tue, 10 Nov 2026 12:33:59 +0100 Subject: [PATCH 095/105] feat(operator-smoke-web): a policy modules panel (#251) The smoke harness drives every module call of the operator client: the catalog with enable and disable per instance, the params history paged by entry id, an account's modules with its params version, and the writes (global params, setting or clearing an account layer, replacing the assignment). Params are checked as JSON objects in the browser and every write takes a reason. Errors now show the HTTP status before the error code, so a missing permission reads as HTTP 403. Changing the signer or logging out clears the module state. The README shows how to start Guardian with the guide's built-in catalog and which operator permissions each action needs, and the smoke-test skill lists the panel. --- .../smoke-test-operator-dashboard/SKILL.md | 6 +- examples/operator-smoke-web/README.md | 92 ++- examples/operator-smoke-web/src/App.tsx | 604 +++++++++++++++++- examples/operator-smoke-web/src/index.css | 10 + 4 files changed, 700 insertions(+), 12 deletions(-) diff --git a/.agents/skills/smoke-test-operator-dashboard/SKILL.md b/.agents/skills/smoke-test-operator-dashboard/SKILL.md index b1283e5f..b8efc0b3 100644 --- a/.agents/skills/smoke-test-operator-dashboard/SKILL.md +++ b/.agents/skills/smoke-test-operator-dashboard/SKILL.md @@ -1,6 +1,6 @@ --- name: smoke-test-operator-dashboard -description: Run or guide manual smoke testing of Guardian operator dashboard auth and account APIs through `examples/operator-smoke-web` and `@openzeppelin/guardian-operator-client`. Use when Codex needs to verify operator challenge signing, session login, logout, account listing, account detail, local signer behavior, local or remote Guardian targets, or workspace versus published operator client package behavior. +description: Run or guide manual smoke testing of Guardian operator dashboard auth and account APIs through `examples/operator-smoke-web` and `@openzeppelin/guardian-operator-client`. Use when Codex needs to verify operator challenge signing, session login, logout, account listing, account detail, local signer behavior, policy module catalog, params history and writes, local or remote Guardian targets, or workspace versus published operator client package behavior. --- # Smoke Test Operator Dashboard @@ -118,6 +118,10 @@ Set `HEADLESS=false` to watch the browser. Set `CHROME_EXECUTABLE` if Chrome is Use `GUARDIAN_URL=http://127.0.0.1:3000` for local runs. For deployed runs, use the deployed Guardian URL. +## Policy Modules Panel + +The `Policy modules` panel covers the module operator endpoints: the catalog (instances, `catalogHash`, `paramsVersion`, enable and disable), the params history paged with `before`, an account's modules with `accountParamsVersion`, and the writes (global params, account layer set or clear, assignment replace). Start Guardian with a catalog and the allowlist permissions as described in `examples/operator-smoke-web/README.md` ("Policy modules panel"). Check that each write shows up in the params history and that a write without its permission surfaces `HTTP 403 [insufficient_operator_permission]`. The automated script does not drive this panel. + ## Assertions - The configured operator public key derives to the active local signer commitment in the UI. diff --git a/examples/operator-smoke-web/README.md b/examples/operator-smoke-web/README.md index 8064e959..e14cb1d2 100644 --- a/examples/operator-smoke-web/README.md +++ b/examples/operator-smoke-web/README.md @@ -2,12 +2,13 @@ Minimal browser UI for Guardian operator endpoints using a generated Falcon key. -This example does only four things: +This example does only these things: - generate and persist a Falcon key in the browser - show the derived public key and commitment - call `@openzeppelin/guardian-operator-client` - let you manually drive challenge, login, account list, account detail, and logout +- read and write policy module state (see [Policy modules panel](#policy-modules-panel)) ## Setup @@ -138,13 +139,11 @@ Then exercise each profile: Guardian with `cargo run -p guardian-server --features authz-test-probe` when smoke-testing US2; release builds return `404` for that path. -**Note on `policies:write`**: the v1 permission vocabulary includes -`policies:write` but no route requires it yet. Granting it on an -allowlist entry loads cleanly but has no behavioral effect — the -first consumer ships with #182. The grant is **not** inert against -downgrade though: rolling back to a server build that predates the -permission will fail to load the allowlist. Remove forward-defined -permissions before downgrading the server binary. +**Note on module permissions**: `policies:write`, `policies:write_global` +and `modules:disable` gate the policy module writes (see +[Policy modules panel](#policy-modules-panel)). Rolling back to a server +build that predates one of them fails to load the allowlist, so remove +them before downgrading the server binary. The browser UI's `Operator Public Keys JSON` field shows the legacy single-string form — to test profile B or C, paste a JSON array of @@ -152,6 +151,83 @@ mixed entries into the file directly and the next Guardian reload will pick them up (hot-reload is already supported by `002-operator-auth`). +## Policy modules panel + +The `Policy modules` panel drives the operator module endpoints (RFC 0002, +issue #251; not in a release yet). Endpoint semantics are in +[`docs/DASHBOARD.md`](../../docs/DASHBOARD.md#policy-modules) and the +walkthrough is the +[policy modules guide](../../docs/guides/policy-modules/README.md). The panel +covers: + +- **Catalog**: `Load catalog` lists every instance with its id, kind, scope, + hooks, enabled flag, circuit, enabled and params drift, plus the + `catalogHash`, `paramsVersion` and undeclared instances. Each card has + `Enable` and `Disable` (a `409 GUARDIAN_MODULE_NOT_DISABLEABLE` is expected + for an instance without `operator_can_disable`) and `Use in forms`, which + copies its id and current global params into the forms below. +- **Params history**: newest first for one module id. `Load older` pages with + `before` set to the last entry's `id`; it is disabled once a page returns + fewer entries than the limit. +- **Account modules**: `Load account modules` shows `accountParamsVersion` and + the entries in evaluation order for the `Account ID` from the Accounts panel. +- **Writes**: set an instance's global params, set or clear an account layer + on a `scope = all` instance, and replace the account's assignment with a + JSON array of `{ "moduleId": ..., "params": {...} }` (`Copy current + assignment` fills it from the loaded account modules). Params are checked + as JSON objects in the browser before anything is sent, and every write + sends the panel's `Reason`, which is required. + +Errors show in the Session panel's `Action error` box as +`HTTP [] `, so a missing permission reads as +`HTTP 403 [insufficient_operator_permission] ...`. + +### Starting Guardian with a catalog + +Use the guide's built-in catalog, +[`docs/guides/policy-modules/built-in.toml`](../../docs/guides/policy-modules/built-in.toml), +and its environment file, from the repository root (guide steps 2 and 3): + +```bash +mkdir -p .guardian +cp docs/guides/policy-modules/built-in.toml .guardian/ +cp docs/guides/policy-modules/.env.example docs/guides/policy-modules/.env +cp docs/guides/policy-modules/operators.example.json .guardian/operators.json +# Replace 0xREPLACE_WITH_FAUCET_ID in .guardian/built-in.toml (the server does not start until you do). + +set -a && . docs/guides/policy-modules/.env && set +a +cargo run -p guardian-server --bin server +``` + +The guide's `.env` points `GUARDIAN_OPERATOR_PUBLIC_KEYS_FILE` at +`.guardian/operators.json`. Instead of the guide's `modules_admin keygen` +key, paste this UI's signer public key (the string inside `Operator Public +Keys JSON`) into the `public_key` field, keeping the structured entry so the +permissions apply: + +```json +[ + { + "public_key": "0x", + "permissions": ["dashboard:read", "policies:write", "policies:write_global", "modules:disable"] + } +] +``` + +| Panel action | Permission | +|---|---| +| Load catalog, params history, account modules | `dashboard:read` | +| Set or clear an account layer, replace assignment, enable | `policies:write` | +| Set global params | `policies:write_global` | +| Disable | `policies:write` or `modules:disable` | + +To see the `403` path, drop a permission from the entry and repeat the +write; the allowlist is reread without a restart. With `built-in.toml`, try +`Set account layer` on `blocklist` with `{"denylist": ["0x..."]}`, and +replace an account's assignment with +`[{"moduleId": "treasury-allowlist", "params": {"allowlist": ["0x..."]}}]`. +Each write then appears in `Params history` for that module. + ## Inspecting audit events Every probe denial or success writes one `admin_actions` event. The diff --git a/examples/operator-smoke-web/src/App.tsx b/examples/operator-smoke-web/src/App.tsx index 4de262ba..5e2fff23 100644 --- a/examples/operator-smoke-web/src/App.tsx +++ b/examples/operator-smoke-web/src/App.tsx @@ -9,6 +9,13 @@ import { type DashboardDeltaDetail, type DashboardDeltaEntry, type DashboardGlobalDeltaEntry, + type AccountModules, + type ModuleAssignment, + type ModuleCatalog, + type ModuleCircuit, + type ModuleInstance, + type ModuleParams, + type ModuleParamsHistoryEntry, type OperatorChallenge, type VerifyOperatorResponse, } from '@openzeppelin/guardian-operator-client'; @@ -29,12 +36,12 @@ function normalizeError(error: unknown): string { // `GUARDIAN_ACCOUNT_PAUSED`, client surfaces `account_paused` // with `pausedAt` / `pausedReason`). if (data?.code === 'account_paused') { - return `[${data.code}] ${base} (pausedAt=${data.pausedAt ?? 'null'}, pausedReason=${data.pausedReason ?? 'null'})`; + return `HTTP ${error.status} [${data.code}] ${base} (pausedAt=${data.pausedAt ?? 'null'}, pausedReason=${data.pausedReason ?? 'null'})`; } if (data?.code) { - return `[${data.code}] ${base}`; + return `HTTP ${error.status} [${data.code}] ${base}`; } - return base; + return `HTTP ${error.status} ${base}`; } if (error instanceof Error) { @@ -190,6 +197,52 @@ function normalizeHex(value: string | null | undefined): string { return (value ?? '').trim().toLowerCase(); } +const MODULE_CIRCUIT_BADGE: Record = { + closed: 'success', + half_open: 'warning', + open: 'warning', +}; + +function parseJsonText(text: string, label: string): unknown { + try { + return JSON.parse(text); + } catch (error) { + const detail = error instanceof Error ? error.message : String(error); + throw new Error(`${label} is not valid JSON: ${detail}`); + } +} + +function requireJsonObject(value: unknown, label: string): ModuleParams { + if (typeof value !== 'object' || value === null || Array.isArray(value)) { + throw new Error(`${label} must be a JSON object`); + } + return value as ModuleParams; +} + +function parseParamsJson(text: string, label: string): ModuleParams { + return requireJsonObject(parseJsonText(text, label), label); +} + +function parseAssignmentJson(text: string): ModuleAssignment[] { + const value = parseJsonText(text, 'Assignment'); + if (!Array.isArray(value)) { + throw new Error('Assignment must be a JSON array of { "moduleId": ..., "params": {...} }'); + } + return value.map((entry, index) => { + const record = requireJsonObject(entry, `Assignment entry ${index}`); + const moduleId = record.moduleId; + if (typeof moduleId !== 'string' || moduleId.trim().length === 0) { + throw new Error(`Assignment entry ${index}: moduleId must be a non-empty string`); + } + const params = requireJsonObject(record.params, `Assignment entry ${index}: params`); + return { moduleId: moduleId.trim(), params }; + }); +} + +function formatOptionalParams(params: ModuleParams | null): string { + return params === null ? 'null' : formatJson(params); +} + export default function App() { const { session, sessionError, generate, clear, signWordHex } = useLocalFalconSigner(); const [guardianBaseUrl, setGuardianBaseUrl] = useState(DEFAULT_GUARDIAN_BASE_URL); @@ -228,6 +281,20 @@ export default function App() { null, ); + const [moduleCatalog, setModuleCatalog] = useState(null); + const [moduleReason, setModuleReason] = useState('smoke-test'); + const [historyModuleId, setHistoryModuleId] = useState(''); + const [historyLimit, setHistoryLimit] = useState('20'); + const [historyEntries, setHistoryEntries] = useState([]); + const [historyLoadedFor, setHistoryLoadedFor] = useState(null); + const [historyHasMore, setHistoryHasMore] = useState(false); + const [accountModules, setAccountModules] = useState(null); + const [globalParamsModuleId, setGlobalParamsModuleId] = useState(''); + const [globalParamsJson, setGlobalParamsJson] = useState('{}'); + const [layerModuleId, setLayerModuleId] = useState(''); + const [layerParamsJson, setLayerParamsJson] = useState('{}'); + const [assignmentJson, setAssignmentJson] = useState('[]'); + const client = useMemo( () => new GuardianOperatorHttpClient({ @@ -263,6 +330,7 @@ export default function App() { setAccounts([]); setAccount(null); resetPagination(); + resetModules(); return nextSession; }); } @@ -276,6 +344,7 @@ export default function App() { setAccounts([]); setAccount(null); resetPagination(); + resetModules(); return nextSession; }); } @@ -525,6 +594,179 @@ export default function App() { setPagedPageCount(0); } + function requireAccountId(): string { + const id = accountId.trim(); + if (!id) throw new Error('Account ID is required'); + return id; + } + + function requireModuleReason(): string { + const reason = moduleReason.trim(); + if (!reason) throw new Error('Reason is required'); + return reason; + } + + function requireModuleId(value: string): string { + const moduleId = value.trim(); + if (!moduleId) throw new Error('Module ID is required'); + return moduleId; + } + + function parseHistoryLimit(): number { + const parsed = Number.parseInt(historyLimit, 10); + if (!Number.isFinite(parsed) || parsed < 1 || parsed > 1000) { + throw new Error('History limit must be an integer from 1 to 1000'); + } + return parsed; + } + + function replaceCatalogInstance(instance: ModuleInstance) { + setModuleCatalog((current) => + current + ? { + ...current, + modules: current.modules.map((entry) => + entry.moduleId === instance.moduleId ? instance : entry, + ), + } + : current, + ); + } + + function selectModule(instance: ModuleInstance) { + setHistoryModuleId(instance.moduleId); + setGlobalParamsModuleId(instance.moduleId); + setGlobalParamsJson(formatJson(instance.params)); + if (instance.scope === 'all') { + setLayerModuleId(instance.moduleId); + } + } + + function resetModuleHistory() { + setHistoryEntries([]); + setHistoryLoadedFor(null); + setHistoryHasMore(false); + } + + function resetModules() { + setModuleCatalog(null); + setAccountModules(null); + resetModuleHistory(); + } + + async function listModules() { + await runAction('listModules', async () => { + const catalog = await client.listModules(); + setModuleCatalog(catalog); + return catalog; + }); + } + + async function enableModule(moduleId: string) { + await runAction(`enableModule(${moduleId})`, async () => { + const instance = await client.enableModule(moduleId, requireModuleReason()); + replaceCatalogInstance(instance); + return instance; + }); + } + + async function disableModule(moduleId: string) { + await runAction(`disableModule(${moduleId})`, async () => { + const instance = await client.disableModule(moduleId, requireModuleReason()); + replaceCatalogInstance(instance); + return instance; + }); + } + + async function loadModuleHistory() { + await runAction('getModuleParamsHistory', async () => { + const moduleId = requireModuleId(historyModuleId); + const limit = parseHistoryLimit(); + const page = await client.getModuleParamsHistory(moduleId, { limit }); + setHistoryEntries(page.entries); + setHistoryLoadedFor(moduleId); + setHistoryHasMore(page.entries.length === limit); + return page; + }); + } + + async function loadOlderModuleHistory() { + const last = historyEntries[historyEntries.length - 1]; + await runAction(`getModuleParamsHistory(before=${last?.id ?? 'none'})`, async () => { + if (!historyLoadedFor || !last) { + throw new Error('Load the newest history page first'); + } + const limit = parseHistoryLimit(); + const page = await client.getModuleParamsHistory(historyLoadedFor, { + before: last.id, + limit, + }); + setHistoryEntries((prev) => [...prev, ...page.entries]); + setHistoryHasMore(page.entries.length === limit); + return page; + }); + } + + async function getAccountModules() { + await runAction('getAccountModules', async () => { + const modules = await client.getAccountModules(requireAccountId()); + setAccountModules(modules); + return modules; + }); + } + + async function setModuleGlobalParams() { + await runAction('setModuleGlobalParams', async () => { + const moduleId = requireModuleId(globalParamsModuleId); + const params = parseParamsJson(globalParamsJson, 'Global params'); + const instance = await client.setModuleGlobalParams(moduleId, params, requireModuleReason()); + replaceCatalogInstance(instance); + return instance; + }); + } + + async function setAccountModuleLayer() { + await runAction('setAccountModuleLayer', async () => { + const id = requireAccountId(); + const moduleId = requireModuleId(layerModuleId); + const params = parseParamsJson(layerParamsJson, 'Account layer params'); + const modules = await client.setAccountModuleLayer(id, moduleId, params, requireModuleReason()); + setAccountModules(modules); + return modules; + }); + } + + async function removeAccountModuleLayer() { + await runAction('removeAccountModuleLayer', async () => { + const id = requireAccountId(); + const moduleId = requireModuleId(layerModuleId); + const modules = await client.removeAccountModuleLayer(id, moduleId, requireModuleReason()); + setAccountModules(modules); + return modules; + }); + } + + async function setAccountModuleAssignment() { + await runAction('setAccountModules', async () => { + const id = requireAccountId(); + const assignment = parseAssignmentJson(assignmentJson); + const modules = await client.setAccountModules(id, assignment, requireModuleReason()); + setAccountModules(modules); + return modules; + }); + } + + function copyAssignmentFromAccount() { + if (!accountModules) { + setUiError('Load account modules first'); + return; + } + const assignment: ModuleAssignment[] = accountModules.modules + .filter((entry) => entry.scope !== 'all') + .map((entry) => ({ moduleId: entry.moduleId, params: entry.params ?? {} })); + setAssignmentJson(formatJson(assignment)); + } + async function logout() { await runAction('logout', async () => { const response = await client.logout(); @@ -532,6 +774,7 @@ export default function App() { setAccounts([]); setAccount(null); resetPagination(); + resetModules(); setChallenge(null); return response; }); @@ -805,6 +1048,361 @@ export default function App() { )} +
+
+

Policy modules

+ + {moduleCatalog + ? `${moduleCatalog.modules.length} instances · paramsVersion ${moduleCatalog.paramsVersion}` + : 'not loaded'} + +
+ +

+ RFC 0002 / issue #251. Reads need dashboard:read. Account layers, + assignments and enable need policies:write; global params need{' '} + policies:write_global; disable takes policies:write or{' '} + modules:disable. Account calls use the Account ID from + the Accounts panel, and every write sends the reason below. +

+ + +
+ + +
+ +

Catalog

+ {moduleCatalog ? ( + <> +
+
+ Catalog hash + {moduleCatalog.catalogHash} +
+
+ paramsVersion + {moduleCatalog.paramsVersion} +
+
+ Undeclared instances + {moduleCatalog.undeclared.length} +
+
+

+ Enable, disable and global params writes update the card in place; reload the + catalog to see the new paramsVersion. +

+
+ {moduleCatalog.modules.map((instance) => ( +
+
+ {instance.moduleId} + + {instance.enabled ? 'enabled' : 'disabled'} + +
+
+
+ Kind + {instance.kind} +
+
+ Scope + {instance.scope} +
+
+ Hooks + {instance.hooks.join(', ')} +
+
+ Circuit + + + {instance.circuit} + + +
+
+ Enabled drift + + {instance.enabledDrift + ? `yes (catalog says ${instance.catalogEnabled ? 'enabled' : 'disabled'})` + : 'no'} + +
+
+ Params drift + {instance.paramsDrift ? 'yes' : 'no'} +
+
+ Operator can disable + {instance.operatorCanDisable ? 'yes' : 'no'} +
+
+ Build + {instance.build ?? startup checks failed} +
+
+
+ Global params +
{formatJson(instance.params)}
+
+
+ + + +
+
+ ))} +
+ {moduleCatalog.undeclared.length > 0 ? ( +
    + {moduleCatalog.undeclared.map((entry) => ( +
  • + undeclared {entry.moduleId} · stored{' '} + {entry.enabled ? 'enabled' : 'disabled'} · never evaluated +
  • + ))} +
+ ) : null} + + ) : ( +

Click Load catalog to list the module instances.

+ )} + +

Params history

+
+ + +
+
+ + + +
+

+ Module: {historyLoadedFor ?? 'none'}; entries loaded:{' '} + {historyEntries.length}; next before:{' '} + {historyHasMore ? historyEntries[historyEntries.length - 1]?.id : 'null'} +

+ {historyEntries.length > 0 ? ( +
+ {historyEntries.map((entry) => ( +
+
+ + #{entry.id} · {entry.accountId ? 'account' : 'global'} + + version {entry.version} +
+
+ {entry.accountId ? ( +
+ Account + {entry.accountId} +
+ ) : null} +
+ Operator + {entry.operator} +
+
+ Reason + {entry.reason} +
+
+ At + {entry.at} +
+
+
+ Previous and new params +
+
+ previous +
{formatOptionalParams(entry.previous)}
+
+
+ new +
{formatOptionalParams(entry.new)}
+
+
+
+
+ ))} +
+ ) : ( +

No history loaded.

+ )} + +

Account modules

+ {accountModules ? ( + <> +
+
+ Account + {accountModules.accountId} +
+
+ accountParamsVersion + {accountModules.accountParamsVersion} +
+
+ {accountModules.modules.length > 0 ? ( +
+ {accountModules.modules.map((entry, index) => ( +
+
+ + {index + 1}. {entry.moduleId} + + + {entry.orphaned ? 'orphaned' : entry.enabled ? 'enabled' : 'disabled'} + +
+
+
+ Scope + {entry.scope} +
+ {entry.scope === 'all' ? ( + <> +
+ Global params +
{formatOptionalParams(entry.globalParams)}
+
+
+ Account layer +
{formatOptionalParams(entry.accountLayer)}
+
+ + ) : ( +
+ Params +
{formatOptionalParams(entry.params)}
+
+ )} +
+
+ ))} +
+ ) : ( +

No modules apply to this account.

+ )} + + ) : ( +

+ Click Load account modules for the account ID above. +

+ )} + +

Writes

+
+
+ +