Skip to content

Commit 559eb30

Browse files
ss-dev-00baxen
andcommitted
broker: freeze normalized args, correlate identities, close two strictness holes
Four review findings on #6742. Each was reproduced with a failing test before the fix, and each fix was mutation-tested by reverting it and confirming the new test dies. 1. Freeze normalized action arguments (Codex, mod.rs:230). `BrokerRequest::new` and `prepare` both called `validate()`, which is `validated().map(|_| ())` — it computes the normalized copy and throws it away. So `AgentTarget::Name(" helper ")` passed validation and stayed padded in the frozen wire body: the host would look up an agent the validator never approved. `new` now stores the normalized action, and `prepare` normalizes before serializing. `prepare` deliberately still validates. It is not redundant: every field of `BrokerRequest` is public and the type is `Deserialize`, so a value can reach `prepare` without passing through `new` — struct literal, parsed JSON, or mutated after construction. Freezing bytes is the last checkable point, so both paths now satisfy one invariant: the frozen body holds exactly what validation approved. To avoid validating args twice on that path, the envelope checks are split into `validate_envelope` and `prepare` takes the normalized value from a single `validated` call. 2. Correlate every echoed identity, not just the pubkey (Codex mod.rs:856, extended per bugs-00's agents.create finding). `validate_for` compared only requestId, action, and read limit, so a response with a matching requestId but a different `agentPubkey` — or a different `channelId` on agents.create — validated, and a host routing bug could hand a caller an outcome for another subject. Generalized rather than patched per action: `correlate::correlate_identities` matches exhaustively over `ActionArgs`, so adding an action is a compile error instead of a silent default to "not compared". The full table of what is and is not compared, with the reason for each omission, is on `validate_for` where a host author reads it; the private fn points there so there is one copy to keep true. Extracted to `broker/correlate.rs` because the table pushed mod.rs to 1,019 lines, past the repo's 1,000-line ceiling. 3. Nested action enums ignored sibling members (bugs-00). `ActionArgs`/`ActionOutcome` are adjacently tagged and lacked `deny_unknown_fields`, so a sibling of their two keys — `secretKey` beside `args` — was silently dropped when either type was deserialized directly. Both are public and wire-facing, so that is a real door the envelope's own strictness does not cover. Closed at the type level rather than documented as a limitation: it turned out to be a one-attribute fix that breaks nothing. 4. Duplicate object keys were accepted inside `outcome` (bugs-00). Confirmed and fixed, but narrower than reported: serde's derived readers already reject repeated fields, so top-level members, flattened members, typed error payloads, and `args` all rejected duplicates. `outcome` did not, because `WireResponse` buffered it through `serde_json::Value`, which collapses duplicates last-wins. That made it the one place a reader could observe a value the envelope's strictness never vetted — so it is a real divergence, not a style question, and `outcome` now re-parses the original bytes via `RawValue`. This enables serde_json's `raw_value` feature, which adds no dependency and leaves Cargo.lock unchanged. Validation: 295 tests pass in buzz-sdk (291 before, plus four new), full `cargo test --workspace` green, workspace clippy `-D warnings` clean, fmt clean, `cargo doc` warning-free, every touched file under 1,000 lines. Signed-off-by: ss-dev-00 <a02c4e0850e5e612b4ddf95dbe2f5c56467cf27c6552203bc833ff438fb31971@buzz.block.builderlab.xyz> Co-authored-by: Bradley Axen <[email protected]> Signed-off-by: Bradley Axen <[email protected]>
1 parent 0311d14 commit 559eb30

6 files changed

Lines changed: 498 additions & 24 deletions

File tree

‎Cargo.toml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -77,7 +77,7 @@ postcard = { version = "1", default-features = false, features = ["use-std"]
7777

7878
# Inter-relay mesh transport (buzz-relay-mesh)
7979
iroh = { version = "1.0.0-rc.0", default-features = false, features = ["tls-ring"] }
80-
serde_json = "1"
80+
serde_json = { version = "1", features = ["raw_value"] }
8181
serde_yaml = "0.9"
8282
evalexpr = "11"
8383
cron = "0.16"

‎crates/buzz-sdk/src/broker/actions/args.rs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -505,7 +505,7 @@ impl AgentsDeleteArgs {
505505
/// `{ "action": "message.post", "args": { … } }` and an args shape can never be
506506
/// paired with the wrong action name.
507507
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
508-
#[serde(tag = "action", content = "args")]
508+
#[serde(tag = "action", content = "args", deny_unknown_fields)]
509509
pub enum ActionArgs {
510510
/// Read a channel, thread, or mention feed.
511511
#[serde(rename = "channel.read")]

‎crates/buzz-sdk/src/broker/actions/outcomes.rs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -219,7 +219,7 @@ pub struct AgentsDeleteOutcome {
219219

220220
/// An action-specific success payload.
221221
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
222-
#[serde(tag = "action", content = "outcome")]
222+
#[serde(tag = "action", content = "outcome", deny_unknown_fields)]
223223
pub enum ActionOutcome {
224224
/// `channel.read` succeeded.
225225
#[serde(rename = "channel.read")]
Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
//! Response-to-request identity correlation.
2+
//!
3+
//! Split from [`super`] to keep that file within the repo's 1,000-line
4+
//! ceiling; the rule it implements is part of response validation.
5+
6+
use super::{ActionArgs, ActionOutcome, AgentTarget, PubkeyHex, SdkError};
7+
8+
/// Reject an outcome that echoes back a different identity than the request
9+
/// supplied.
10+
///
11+
/// The table of what is and is not compared, with the reasoning for each, is on
12+
/// [`BrokerResponse::validate_for`][super::BrokerResponse::validate_for] — the
13+
/// public entry point a host author reads. It is documented there rather than
14+
/// here so there is one copy to keep true.
15+
///
16+
/// The match below is exhaustive over [`ActionArgs`], so adding an action is a
17+
/// compile error here rather than a silent default to "not compared".
18+
pub(super) fn correlate_identities(
19+
args: &ActionArgs,
20+
outcome: &ActionOutcome,
21+
) -> Result<(), SdkError> {
22+
/// Compare one echoed identity, naming the field in the error.
23+
fn same(field: &str, requested: &str, returned: &str) -> Result<(), SdkError> {
24+
if requested == returned {
25+
return Ok(());
26+
}
27+
Err(SdkError::InvalidInput(format!(
28+
"response {field} \"{returned}\" does not match the requested \"{requested}\""
29+
)))
30+
}
31+
32+
/// The pubkey a target names immutably, if it names one.
33+
fn targeted(target: &AgentTarget) -> Option<&PubkeyHex> {
34+
match target {
35+
AgentTarget::Pubkey(pubkey) => Some(pubkey),
36+
AgentTarget::Name(_) => None,
37+
}
38+
}
39+
40+
match (args, outcome) {
41+
(ActionArgs::AgentsCreate(args), ActionOutcome::AgentsCreate(outcome)) => {
42+
same("channelId", &args.channel_id, &outcome.channel_id)
43+
}
44+
(ActionArgs::AgentsUpdate(args), ActionOutcome::AgentsUpdate(outcome)) => {
45+
match targeted(&args.target) {
46+
Some(requested) => same(
47+
"agentPubkey",
48+
requested.as_str(),
49+
outcome.agent_pubkey.as_str(),
50+
),
51+
None => Ok(()),
52+
}
53+
}
54+
(ActionArgs::AgentsDelete(args), ActionOutcome::AgentsDelete(outcome)) => {
55+
match targeted(&args.target) {
56+
Some(requested) => same(
57+
"agentPubkey",
58+
requested.as_str(),
59+
outcome.agent_pubkey.as_str(),
60+
),
61+
None => Ok(()),
62+
}
63+
}
64+
// These outcomes echo no identity the request supplied; see the table.
65+
(ActionArgs::ChannelRead(_), _)
66+
| (ActionArgs::MessagePost(_), _)
67+
| (ActionArgs::MessageReply(_), _)
68+
| (ActionArgs::ReactionAdd(_), _)
69+
| (ActionArgs::ProfileSet(_), _)
70+
| (ActionArgs::StorageAddress(_), _)
71+
| (ActionArgs::AgentsCreate(_), _)
72+
| (ActionArgs::AgentsUpdate(_), _)
73+
| (ActionArgs::AgentsDelete(_), _) => Ok(()),
74+
}
75+
}

‎crates/buzz-sdk/src/broker/mod.rs‎

Lines changed: 99 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -55,16 +55,32 @@
5555
//! [`AgentsCreateOutcome`] is the case that matters — it returns public identity
5656
//! only, never the key it just minted.
5757
//!
58-
//! Strictness has to hold at every layer, or the outermost one decides. Two
58+
//! Strictness has to hold at every layer, or the outermost one decides. Three
5959
//! places needed explicit work, because each had a hole a derive left open:
6060
//! [`BrokerResponse`] cannot combine `deny_unknown_fields` with the `flatten`
61-
//! that produces its wire shape, and [`BrokerMessage`] wraps `nostr`'s `Event`,
62-
//! whose own deserializer discards unknown members. Both now deserialize through
63-
//! private strict intermediaries, so the rule reaches *inside* the envelope and
64-
//! inside each event object — a host cannot ship a `secretKey` beside `sig` and
65-
//! have it silently trimmed.
61+
//! that produces its wire shape; [`BrokerMessage`] wraps `nostr`'s `Event`,
62+
//! whose own deserializer discards unknown members; and [`ActionArgs`] /
63+
//! [`ActionOutcome`] are adjacently tagged, so without `deny_unknown_fields` on
64+
//! the enum itself a sibling of their two keys was ignored when either type was
65+
//! deserialized directly — and both are public and wire-facing, so that is a
66+
//! real door, not a hypothetical one. The first two now deserialize through
67+
//! private strict intermediaries and the third denies unknown fields, so the
68+
//! rule reaches *inside* the envelope, inside each event object, and around each
69+
//! nested action object — a host cannot ship a `secretKey` beside `sig`, or
70+
//! beside `args`, and have it silently trimmed.
6671
//!
67-
//! A third hole was subtler and is closed the same way — see
72+
//! # Duplicate members are rejected
73+
//!
74+
//! A key may appear at most once in any object. serde's derived readers reject a
75+
//! repeated field, so most of this contract gets that for free — but the strict
76+
//! response intermediary originally buffered `outcome` through a
77+
//! `serde_json::Value`, and that collapses duplicates last-wins. `outcome` was
78+
//! therefore the one place a reader could observe a value the envelope's own
79+
//! strictness never vetted, so it now re-parses the original bytes. The practical
80+
//! consequence for a host author is the same as the no-null rule: emit each
81+
//! member once, and do not rely on a later occurrence overriding an earlier one.
82+
//!
83+
//! A fourth hole was subtler and is closed the same way — see
6884
//! [Optional members](#optional-members-omission-is-the-only-spelling-of-absence).
6985
//!
7086
//! Two limits are worth stating. A `String` field can physically hold secret
@@ -138,6 +154,7 @@ use crate::SdkError;
138154

139155
pub mod actions;
140156
pub mod client;
157+
mod correlate;
141158

142159
use actions::absent_or_valued;
143160
pub use actions::{
@@ -219,15 +236,21 @@ impl BrokerRequest {
219236
/// [`MAX_REQUEST_ID_LEN`], or not printable ASCII, or if the action's
220237
/// arguments fail validation.
221238
pub fn new(request_id: impl Into<String>, action: ActionArgs) -> Result<Self, SdkError> {
222-
let request = Self {
239+
let request_id = request_id.into();
240+
validate_request_id(&request_id)?;
241+
// Store the normalized copy, not the caller's. `validated` both checks
242+
// and normalizes (trimming names, lowercasing pubkeys), so keeping the
243+
// original would let a padded selector pass validation and then travel
244+
// in the frozen body — the host would look up something the validator
245+
// never approved.
246+
let action = action.validated()?;
247+
Ok(Self {
223248
r#type: BROKER_REQUEST_TYPE.to_string(),
224249
protocol_version: BROKER_PROTOCOL_VERSION,
225-
request_id: request_id.into(),
250+
request_id,
226251
action_version: action.action().current_version(),
227252
action,
228-
};
229-
request.validate()?;
230-
Ok(request)
253+
})
231254
}
232255

233256
/// The action this request invokes.
@@ -236,14 +259,25 @@ impl BrokerRequest {
236259
self.action.action()
237260
}
238261

239-
/// Validate, then serialize once into the bytes every attempt will send.
262+
/// Validate and normalize, then serialize once into the bytes every attempt
263+
/// will send.
264+
///
265+
/// This re-validates even though [`Self::new`] already did. That is not
266+
/// redundant: every field of this struct is public and the type is
267+
/// [`Deserialize`], so a value can reach here without ever passing through
268+
/// [`Self::new`] — built with a struct literal, parsed from JSON, or mutated
269+
/// after construction. Freezing bytes is the last point where anything can
270+
/// be checked, so it normalizes here too and serializes the normalized copy.
271+
/// Both paths therefore satisfy the same invariant: the frozen body contains
272+
/// exactly what validation approved.
240273
///
241274
/// # Errors
242275
///
243276
/// Returns [`SdkError`] when [`Self::validate`] fails, or
244277
/// [`SdkError::InvalidInput`] if serialization fails.
245-
pub fn prepare(self) -> Result<PreparedRequest, SdkError> {
246-
self.validate()?;
278+
pub fn prepare(mut self) -> Result<PreparedRequest, SdkError> {
279+
self.validate_envelope()?;
280+
self.action = self.action.validated()?;
247281
let body = serde_json::to_vec(&self).map_err(|e| {
248282
SdkError::InvalidInput(format!("broker request is not serializable: {e}"))
249283
})?;
@@ -264,6 +298,16 @@ impl BrokerRequest {
264298
/// `protocolVersion` or `actionVersion`, a malformed `requestId`, or
265299
/// arguments that fail their own validation.
266300
pub fn validate(&self) -> Result<(), SdkError> {
301+
self.validate_envelope()?;
302+
self.action.validate()
303+
}
304+
305+
/// Validate everything except the action arguments.
306+
///
307+
/// Split out so [`Self::prepare`] can check the envelope and then take the
308+
/// normalized arguments from a single `validated` call, rather than
309+
/// validating the arguments twice on the way to freezing bytes.
310+
fn validate_envelope(&self) -> Result<(), SdkError> {
267311
if self.r#type != BROKER_REQUEST_TYPE {
268312
return Err(SdkError::InvalidInput(format!(
269313
"broker request type must be \"{BROKER_REQUEST_TYPE}\", got \"{}\"",
@@ -286,7 +330,7 @@ impl BrokerRequest {
286330
action.current_version()
287331
)));
288332
}
289-
self.action.validate()
333+
Ok(())
290334
}
291335
}
292336

@@ -671,7 +715,7 @@ struct WireResponse {
671715
#[serde(default, deserialize_with = "absent_or_valued")]
672716
action: Option<String>,
673717
#[serde(default, deserialize_with = "absent_or_valued")]
674-
outcome: Option<serde_json::Value>,
718+
outcome: Option<Box<serde_json::value::RawValue>>,
675719
#[serde(default, deserialize_with = "absent_or_valued")]
676720
error: Option<BrokerError>,
677721
#[serde(default)]
@@ -706,9 +750,17 @@ impl<'de> Deserialize<'de> for BrokerResponse {
706750
// Re-deserialize the outcome under its action tag, which is how
707751
// the adjacently-tagged `ActionOutcome` — and the
708752
// `deny_unknown_fields` on each outcome type — get applied.
709-
let tagged = serde_json::json!({ "action": action, "outcome": outcome });
753+
// Re-deserialize from the original bytes, not from a
754+
// `serde_json::Value`: buffering through `Value` collapses
755+
// duplicate keys last-wins, which would let `outcome` carry a
756+
// duplicate that no other part of this contract accepts.
757+
let tagged = format!(
758+
"{{\"action\":{},\"outcome\":{}}}",
759+
serde_json::to_string(&action).map_err(D::Error::custom)?,
760+
outcome.get()
761+
);
710762
let outcome: ActionOutcome =
711-
serde_json::from_value(tagged).map_err(D::Error::custom)?;
763+
serde_json::from_str(&tagged).map_err(D::Error::custom)?;
712764
BrokerResult::Succeeded { outcome }
713765
}
714766
status @ ("failed" | "indeterminate") => {
@@ -834,8 +886,33 @@ impl BrokerResponse {
834886
///
835887
/// Returns everything [`Self::validate`] returns, plus
836888
/// [`SdkError::InvalidInput`] when the `requestId` does not correlate, a
837-
/// success outcome names a different action than the request, or a read
838-
/// returned more messages than the request allowed.
889+
/// success outcome names a different action than the request, a success
890+
/// outcome echoes a different identity than the request supplied, or a
891+
/// read returned more messages than the request allowed.
892+
///
893+
/// # What identity correlation compares
894+
///
895+
/// `requestId` plus action is not enough: a host routing bug can return a
896+
/// well-formed success for the wrong *subject*. Every identity the request
897+
/// supplies and the outcome echoes must match exactly. This is the whole
898+
/// table:
899+
///
900+
/// | Action | compared | not compared, and why |
901+
/// |---|---|---|
902+
/// | `channel.read` | — | outcome carries a page and cursor, no echo of `channelId` |
903+
/// | `message.post` | — | outcome is `eventId`/`kind`/`createdAt`, all host-minted |
904+
/// | `message.reply` | — | same; the parent id is not echoed |
905+
/// | `reaction.add` | — | same |
906+
/// | `profile.set` | — | same |
907+
/// | `storage.address` | — | `slug` is deliberately absent from the outcome: a `d` tag is a keyed hash of it, and echoing the slug would defeat that |
908+
/// | `agents.create` | `channelId` | pubkey and name are newly minted, so there is nothing prior to compare |
909+
/// | `agents.update` | `agentPubkey` when targeted by pubkey | a name target is resolved host-side; `displayName` may be exactly what this call changed |
910+
/// | `agents.delete` | `agentPubkey` when targeted by pubkey | ditto for a name target |
911+
///
912+
/// A name-targeted `agents.update`/`agents.delete` is the one case where the
913+
/// caller asked for an identity it cannot verify in the reply. That is
914+
/// inherent: the host resolves the name, and a rename may be the very thing
915+
/// the call performed.
839916
pub fn validate_for(&self, request: &PreparedRequest) -> Result<(), SdkError> {
840917
self.validate()?;
841918
if self.request_id != request.request_id() {
@@ -854,6 +931,7 @@ impl BrokerResponse {
854931
expected.as_str()
855932
)));
856933
}
934+
correlate::correlate_identities(&request.request.action, outcome)?;
857935
// `ActionOutcome::validate` can only enforce the protocol-wide cap,
858936
// because it never sees the request. A page bounded only by that cap
859937
// still overruns a caller that asked for one message and was handed

0 commit comments

Comments
 (0)