app

Local-first trade for farms and co-ops
git clone https://radroots.dev/git/app.git
Log | Files | Refs | README | LICENSE

commit 2607ef68fecbdbb2ead383cdee78d1adbd35de89
parent 4a6f69d1d35b4e909423b7c47a90eb9fdf9b7699
Author: triesap <tyson@radroots.org>
Date:   Fri,  2 Oct 2026 13:50:56 +0000

availability: define query scope and opaque page contracts

- Bind owner context and snapshot generations to exact bounded local filters
- Order pages by signed time and event identity with canonical continuations
- Preserve explicit local page state and static safe query diagnostics
- Verify twenty frozen cases and current Rust native and graph guards

Diffstat:
Mcore/Cargo.lock | 1+
Acore/crates/harvestcircle_application/src/availability_query.rs | 209+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Mcore/crates/harvestcircle_application/src/lib.rs | 2++
Acore/crates/harvestcircle_application/tests/focused_availability_query.rs | 1168+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Mcore/crates/harvestcircle_domain/Cargo.toml | 1+
Mcore/crates/harvestcircle_domain/src/availability/mod.rs | 8++++++++
Acore/crates/harvestcircle_domain/src/availability/query.rs | 540+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Mcore/crates/harvestcircle_domain/src/lib.rs | 10+++++++---
Mradroots.lib.source-lock.v1.toml | 2+-
Mtools/xtask/src/lib.rs | 4++--
10 files changed, 1939 insertions(+), 6 deletions(-)

diff --git a/core/Cargo.lock b/core/Cargo.lock @@ -995,6 +995,7 @@ dependencies = [ "radroots_event_codec", "radroots_identity", "secrecy", + "sha2", "zeroize", ] diff --git a/core/crates/harvestcircle_application/src/availability_query.rs b/core/crates/harvestcircle_application/src/availability_query.rs @@ -0,0 +1,209 @@ +//! Pure structural scopes and bounded owned local availability queries. +//! +//! These values need no signing capability and perform no query or external +//! effect. Runtime admission and the actual validated storage snapshot remain +//! the responsibility of the later local query adapter. + +use std::fmt; + +use harvestcircle_domain::{ + AvailabilityOrderKey, AvailabilityPage, AvailabilityPageContinuation, AvailabilityPageCursor, + AvailabilityPageLimit, AvailabilityQueryContext, AvailabilityQueryError, + AvailabilityQueryFilters, AvailabilityQueryFingerprint, PublicKey, +}; + +use crate::SessionGeneration; + +/// Caller-supplied local owner/context/session bindings without admission proof. +#[derive(Clone, Copy, Eq, PartialEq)] +pub struct AvailabilityLocalQueryScope { + owner: PublicKey, + context: AvailabilityQueryContext, + session_generation: SessionGeneration, +} + +impl AvailabilityLocalQueryScope { + #[must_use] + pub const fn new( + owner: PublicKey, + context: AvailabilityQueryContext, + session_generation: SessionGeneration, + ) -> Self { + Self { + owner, + context, + session_generation, + } + } + + #[must_use] + pub const fn owner(&self) -> PublicKey { + self.owner + } + + #[must_use] + pub const fn context(&self) -> &AvailabilityQueryContext { + &self.context + } + + #[must_use] + pub const fn session_generation(&self) -> SessionGeneration { + self.session_generation + } +} + +impl fmt::Debug for AvailabilityLocalQueryScope { + fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { + formatter + .debug_struct("AvailabilityLocalQueryScope") + .field("source_revision", &self.context.source_revision()) + .field( + "projection_generation", + &self.context.projection_generation(), + ) + .field("session_generation", &self.session_generation.value()) + .finish_non_exhaustive() + } +} + +/// Immutable complete request with an independently validated public cursor. +#[derive(Clone, Eq, PartialEq)] +pub struct ScopedAvailabilityQuery { + scope: AvailabilityLocalQueryScope, + filters: AvailabilityQueryFilters, + limit: AvailabilityPageLimit, + cursor: Option<AvailabilityPageCursor>, + fingerprint: AvailabilityQueryFingerprint, +} + +impl ScopedAvailabilityQuery { + /// Binds the complete request and validates borrowed cursor bytes before + /// retaining their owned representation. + /// + /// # Errors + /// + /// Returns the static cursor-contract error for an oversized, malformed or + /// different-request cursor. This does not admit the structural local scope. + pub fn new( + scope: AvailabilityLocalQueryScope, + filters: AvailabilityQueryFilters, + limit: AvailabilityPageLimit, + cursor: Option<&str>, + ) -> Result<Self, AvailabilityQueryError> { + let fingerprint = AvailabilityQueryFingerprint::new( + scope.owner(), + scope.context(), + scope.session_generation().value(), + &filters, + limit, + ); + let cursor = cursor + .map(|value| AvailabilityPageCursor::parse(value, fingerprint)) + .transpose()?; + Ok(Self { + scope, + filters, + limit, + cursor, + fingerprint, + }) + } + + #[must_use] + pub const fn scope(&self) -> &AvailabilityLocalQueryScope { + &self.scope + } + + #[must_use] + pub const fn filters(&self) -> &AvailabilityQueryFilters { + &self.filters + } + + #[must_use] + pub const fn limit(&self) -> AvailabilityPageLimit { + self.limit + } + + #[must_use] + pub const fn cursor(&self) -> Option<&AvailabilityPageCursor> { + self.cursor.as_ref() + } + + #[must_use] + pub const fn fingerprint(&self) -> AvailabilityQueryFingerprint { + self.fingerprint + } + + /// Compares the caller's structural bindings without checking installed + /// accounts, signing state, storage admission or performing a query. + /// + /// # Errors + /// + /// Returns `ScopeMismatch` for a different owner/context identity and + /// `StaleQuery` for a different store/source/projection/session binding. + pub fn validate_scope( + &self, + current: &AvailabilityLocalQueryScope, + ) -> Result<(), AvailabilityQueryError> { + let original_context = self.scope.context(); + let current_context = current.context(); + if self.scope.owner() != current.owner() + || original_context.context_id() != current_context.context_id() + { + return Err(AvailabilityQueryError::ScopeMismatch); + } + if original_context.store_generation() != current_context.store_generation() + || original_context.source_revision() != current_context.source_revision() + || original_context.projection_generation() != current_context.projection_generation() + || self.scope.session_generation() != current.session_generation() + { + return Err(AvailabilityQueryError::StaleQuery); + } + Ok(()) + } + + /// Moves bounded rows into a page at this query's exact projection. + /// + /// The caller must supply actual ordered selected rows and the correct last + /// position for its validated snapshot. This method neither scans nor + /// derives a continuation from item payloads. `End` describes only this + /// local query snapshot, without network freshness/completeness guarantees. + /// + /// # Errors + /// + /// Returns `Capacity` if the supplied row count exceeds this request's limit. + pub fn page<T>( + &self, + items: Vec<T>, + next: Option<AvailabilityOrderKey>, + ) -> Result<AvailabilityPage<T>, AvailabilityQueryError> { + if items.len() > usize::from(self.limit.rows()) { + return Err(AvailabilityQueryError::Capacity); + } + let continuation = match next { + None => AvailabilityPageContinuation::End, + Some(after) => AvailabilityPageContinuation::More(AvailabilityPageCursor::encode( + self.fingerprint, + after, + )), + }; + AvailabilityPage::new( + self.limit, + items, + continuation, + self.scope.context().projection_generation(), + ) + } +} + +impl fmt::Debug for ScopedAvailabilityQuery { + fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { + formatter + .debug_struct("ScopedAvailabilityQuery") + .field("scope", &self.scope) + .field("filters", &self.filters) + .field("limit", &self.limit) + .field("cursor_present", &self.cursor.is_some()) + .finish_non_exhaustive() + } +} diff --git a/core/crates/harvestcircle_application/src/lib.rs b/core/crates/harvestcircle_application/src/lib.rs @@ -2,6 +2,7 @@ pub mod actor; pub mod app_core; +pub mod availability_query; mod change_stream; pub mod config; pub mod custody; @@ -23,6 +24,7 @@ pub use actor::{ RuntimeCommandClass, RuntimeLifecycle, SessionGeneration, TaskCorrelation, }; pub use app_core::{AppCore, RemovalConfirmationToken, RemovalImpact}; +pub use availability_query::{AvailabilityLocalQueryScope, ScopedAvailabilityQuery}; pub use change_stream::{ ChangeSubscriptionId, OrderedSnapshotChanges, SnapshotChange, SnapshotChangeReceiver, }; diff --git a/core/crates/harvestcircle_application/tests/focused_availability_query.rs b/core/crates/harvestcircle_application/tests/focused_availability_query.rs @@ -0,0 +1,1168 @@ +use std::error::Error; +use std::fmt::Write; + +use harvestcircle_application::{ + AvailabilityLocalQueryScope, ScopedAvailabilityQuery, SessionGeneration, +}; +use harvestcircle_domain::availability::query::{EventTimestamp, FoodAvailabilityStatus}; +use harvestcircle_domain::{ + AVAILABILITY_CURSOR_MAX_BYTES, AVAILABILITY_PAGE_DEFAULT_ROWS, AVAILABILITY_PAGE_MAX_ROWS, + AVAILABILITY_QUERY_TEXT_MAX_BYTES, AvailabilityEventVersion, AvailabilityOrderKey, + AvailabilityPage, AvailabilityPageContinuation, AvailabilityPageCursor, AvailabilityPageLimit, + AvailabilityQueryContext, AvailabilityQueryError, AvailabilityQueryFilters, + AvailabilityQueryFingerprint, AvailabilitySearchText, PublicKey, PublicPublisher, +}; + +const AUTHOR_HEX: &str = "79be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798"; +const OTHER_AUTHOR_HEX: &str = "7e7e9c42a91bfef19fa7ea99d52d8afdb67d893a8fefba1f5cb9793f2107f6d7"; +// Independent pre-production SHA-256 of the specified v1 frame, not an encoder result. +const GOLDEN_FINGERPRINT_HEX: &str = + "3db9ea644546b310f06abf524cfa0248fb5b1757e8a34620a4c820ba16a20276"; +const GOLDEN_FINGERPRINT_BYTES: [u8; 32] = [ + 0x3d, 0xb9, 0xea, 0x64, 0x45, 0x46, 0xb3, 0x10, 0xf0, 0x6a, 0xbf, 0x52, 0x4c, 0xfa, 0x02, 0x48, + 0xfb, 0x5b, 0x17, 0x57, 0xe8, 0xa3, 0x46, 0x20, 0xa4, 0xc8, 0x20, 0xba, 0x16, 0xa2, 0x02, 0x76, +]; + +fn author() -> PublicKey { + PublicKey::from_hex(AUTHOR_HEX).expect("fixed valid public curve author") +} + +fn other_author() -> PublicKey { + PublicKey::from_hex(OTHER_AUTHOR_HEX).expect("second fixed valid public curve author") +} + +fn publisher() -> PublicPublisher { + PublicPublisher::from_public_key(author()) +} + +fn other_publisher() -> PublicPublisher { + PublicPublisher::from_public_key(other_author()) +} + +fn context( + context_id: [u8; 32], + store_generation: [u8; 32], + source_revision: u64, + projection_generation: u64, +) -> AvailabilityQueryContext { + AvailabilityQueryContext::new( + context_id, + store_generation, + source_revision, + projection_generation, + ) + .expect("nonzero structural query identities") +} + +fn base_context() -> AvailabilityQueryContext { + context([1; 32], [2; 32], 5, 7) +} + +fn filters( + search: Option<&str>, + publisher: Option<PublicPublisher>, + status: Option<FoodAvailabilityStatus>, +) -> AvailabilityQueryFilters { + AvailabilityQueryFilters::new( + search.map(|text| AvailabilitySearchText::new(text).expect("bounded cached search text")), + publisher, + status, + ) +} + +fn base_filters() -> AvailabilityQueryFilters { + filters(Some("a"), None, Some(FoodAvailabilityStatus::Active)) +} + +fn scope( + owner: PublicKey, + context: AvailabilityQueryContext, + session_generation: u64, +) -> AvailabilityLocalQueryScope { + AvailabilityLocalQueryScope::new( + owner, + context, + SessionGeneration::from_value(session_generation), + ) +} + +fn base_scope() -> AvailabilityLocalQueryScope { + scope(author(), base_context(), 3) +} + +fn base_fingerprint() -> AvailabilityQueryFingerprint { + AvailabilityQueryFingerprint::new( + author(), + &base_context(), + 3, + &base_filters(), + AvailabilityPageLimit::default(), + ) +} + +fn base_query() -> ScopedAvailabilityQuery { + ScopedAvailabilityQuery::new( + base_scope(), + base_filters(), + AvailabilityPageLimit::default(), + None, + ) + .expect("pure local structural query") +} + +fn hex(bytes: &[u8]) -> String { + let mut text = String::with_capacity(bytes.len() * 2); + for byte in bytes { + write!(&mut text, "{byte:02x}").expect("writing hexadecimal into a string"); + } + text +} + +fn version(bytes: [u8; 32]) -> AvailabilityEventVersion { + AvailabilityEventVersion::from_hex(&hex(&bytes)).expect("exact public event ID") +} + +fn order(timestamp: u64, event_id: [u8; 32]) -> AvailabilityOrderKey { + AvailabilityOrderKey::new(EventTimestamp::new(timestamp), version(event_id)) +} + +fn canonical_cursor(timestamp_hex: &str, event_id: [u8; 32]) -> String { + format!( + "hcq1:{GOLDEN_FINGERPRINT_HEX}:{timestamp_hex}:{}", + hex(&event_id) + ) +} + +fn text_at_byte_count(unit: &str, count: usize) -> String { + unit.repeat(count / unit.len()) + &"x".repeat(count % unit.len()) +} + +fn assert_distinct(fingerprints: &[AvailabilityQueryFingerprint]) { + for (index, fingerprint) in fingerprints.iter().enumerate() { + for other in &fingerprints[index + 1..] { + assert_ne!( + fingerprint, other, + "different framed requests must remain distinct" + ); + } + } +} + +#[test] +fn page_limits_admit_default_and_exact_maximum() { + assert_eq!(AVAILABILITY_PAGE_DEFAULT_ROWS, 50_u16); + assert_eq!(AVAILABILITY_PAGE_MAX_ROWS, 100_u16); + assert_eq!(AvailabilityPageLimit::default().rows(), 50); + + for rows in 1..=100 { + assert_eq!( + AvailabilityPageLimit::new(rows) + .expect("admitted row limit") + .rows(), + rows + ); + } + for rows in [0, 101, u16::MAX] { + assert_eq!( + AvailabilityPageLimit::new(rows).expect_err("outside the exact row bounds"), + AvailabilityQueryError::InvalidInput, + ); + } +} + +#[test] +fn search_text_preserves_exact_utf8_with_byte_boundaries() { + assert_eq!(AVAILABILITY_QUERY_TEXT_MAX_BYTES, 512_usize); + for text in [ + "", + " ", + " farm:%_\\\t\n\0🥕 ", + "é", + "e\u{301}", + "a\u{200d}b", + ] { + let search = AvailabilitySearchText::new(text).expect("opaque cached search text"); + assert_eq!(search.as_str().as_bytes(), text.as_bytes()); + } + assert_ne!( + AvailabilitySearchText::new("é") + .expect("precomposed") + .as_str(), + AvailabilitySearchText::new("e\u{301}") + .expect("combining") + .as_str(), + ); + + for unit in ["x", "é", "🥕", "e\u{301}"] { + for count in [511, 512] { + let text = text_at_byte_count(unit, count); + assert_eq!(text.len(), count); + assert_eq!( + AvailabilitySearchText::new(&text) + .expect("exact UTF-8 byte boundary") + .as_str(), + text, + ); + } + let text = text_at_byte_count(unit, 513); + assert_eq!(text.len(), 513); + assert_eq!( + AvailabilitySearchText::new(&text).expect_err("one byte over the text cap"), + AvailabilityQueryError::InputTooLarge, + ); + } +} + +#[test] +fn filters_keep_optional_search_publisher_and_shared_status() { + for search in [None, Some(""), Some(" \té\0%_\n")] { + for publisher in [None, Some(publisher()), Some(other_publisher())] { + for status in [ + None, + Some(FoodAvailabilityStatus::Active), + Some(FoodAvailabilityStatus::Sold), + ] { + let value = filters(search, publisher, status); + assert_eq!(value.search().map(AvailabilitySearchText::as_str), search); + assert_eq!(value.publisher(), publisher); + assert_eq!(value.status(), status); + } + } + } + assert_eq!(FoodAvailabilityStatus::Active.as_str(), "active"); + assert_eq!(FoodAvailabilityStatus::Sold.as_str(), "sold"); + assert!(filters(None, None, None).search().is_none()); + assert_eq!( + filters(Some(""), None, None) + .search() + .expect("present empty search") + .as_str(), + "" + ); +} + +#[test] +fn context_binds_nonzero_identity_and_full_width_generations() { + for (source_revision, projection_generation) in [ + (0, 0), + (5, 7), + (1_u64 << 63, (1_u64 << 63) + 1), + (u64::MAX, u64::MAX), + ] { + let value = context([1; 32], [2; 32], source_revision, projection_generation); + assert_eq!(value.context_id(), &[1; 32]); + assert_eq!(value.store_generation(), &[2; 32]); + assert_eq!(value.source_revision(), source_revision); + assert_eq!(value.projection_generation(), projection_generation); + } + for index in [0, 16, 31] { + let mut nonzero = [0; 32]; + nonzero[index] = 1; + let value = context(nonzero, nonzero, 0, 0); + assert_eq!(value.context_id(), &nonzero); + assert_eq!(value.store_generation(), &nonzero); + } + for (context_id, store_generation) in + [([0; 32], [2; 32]), ([1; 32], [0; 32]), ([0; 32], [0; 32])] + { + assert_eq!( + AvailabilityQueryContext::new(context_id, store_generation, 0, u64::MAX) + .expect_err("zero opaque identity"), + AvailabilityQueryError::InvalidInput, + ); + } +} + +#[test] +fn ordering_uses_descending_signed_time_then_lowest_event_id() { + let mut middle_id = [0; 32]; + middle_id[16] = 1; + let mut last_id = [0; 32]; + last_id[31] = 1; + let expected = vec![ + order(u64::MAX, [0; 32]), + order(u64::MAX, [u8::MAX; 32]), + order(u64::MAX - 1, [0; 32]), + order(1_u64 << 63, [0; 32]), + order((1_u64 << 63) - 1, [0; 32]), + order(10, [0; 32]), + order(10, last_id), + order(10, middle_id), + order(10, [1; 32]), + order(0, [u8::MAX; 32]), + ]; + let mut reversed = expected.clone(); + reversed.reverse(); + reversed.sort(); + assert_eq!(reversed, expected); + let permutation = [7, 3, 9, 1, 5, 0, 8, 4, 2, 6]; + let mut permuted: Vec<_> = permutation + .into_iter() + .map(|index| expected[index]) + .collect(); + permuted.sort(); + assert_eq!(permuted, expected); + for rotation in 1..expected.len() { + let mut input = expected.clone(); + input.rotate_left(rotation); + input.sort(); + assert_eq!(input, expected); + } + assert_eq!(expected[0].created_at().as_u64(), u64::MAX); + assert_eq!(expected[3].created_at().as_u64(), 1_u64 << 63); + assert_eq!(expected[6].version().event_id().as_bytes(), &last_id); + assert_eq!( + order(10, middle_id).cmp(&order(10, middle_id)), + std::cmp::Ordering::Equal + ); + assert_eq!( + order(0, [0; 32]).version(), + order(u64::MAX, [0; 32]).version() + ); + assert!(order(u64::MAX, [0; 32]) < order(0, [0; 32])); +} + +#[test] +fn continuation_position_is_strict_for_time_and_id_ties() { + let mut last_id = [0; 32]; + last_id[31] = 1; + let mut middle_id = [0; 32]; + middle_id[16] = 1; + let positions = [ + order(u64::MAX, [0; 32]), + order(1_u64 << 63, [0; 32]), + order((1_u64 << 63) - 1, [0; 32]), + order(10, [0; 32]), + order(10, last_id), + order(10, middle_id), + order(10, [u8::MAX; 32]), + order(0, [0; 32]), + ]; + for (previous_index, previous) in positions.into_iter().enumerate() { + assert!( + !previous.is_after(previous), + "equal keys are never continuation positions" + ); + for (candidate_index, candidate) in positions.into_iter().enumerate() { + assert_eq!( + candidate.is_after(previous), + candidate_index > previous_index + ); + } + } + assert!(order(9, [0; 32]).is_after(order(10, [u8::MAX; 32]))); + assert!(!order(11, [u8::MAX; 32]).is_after(order(10, [0; 32]))); +} + +#[test] +fn cursor_roundtrip_preserves_canonical_version_and_full_width_key() { + for (timestamp, timestamp_hex) in [ + (0, "0000000000000000"), + (1, "0000000000000001"), + ((1_u64 << 63) - 1, "7fffffffffffffff"), + (1_u64 << 63, "8000000000000000"), + (u64::MAX, "ffffffffffffffff"), + ] { + for event_id in [[0; 32], [0xab; 32], [u8::MAX; 32]] { + let key = order(timestamp, event_id); + let expected = canonical_cursor(timestamp_hex, event_id); + let encoded = AvailabilityPageCursor::encode(base_fingerprint(), key); + assert_eq!(encoded.as_str().as_bytes(), expected.as_bytes()); + assert_eq!(encoded.as_str().len(), 151); + assert!(encoded.as_str().is_ascii()); + assert_eq!(encoded.after(), key); + let parsed = AvailabilityPageCursor::parse(&expected, base_fingerprint()) + .expect("independently expected canonical cursor"); + assert_eq!(parsed.as_str(), expected); + assert_eq!(parsed.after().created_at().as_u64(), timestamp); + assert_eq!(parsed.after().version().event_id().as_bytes(), &event_id); + } + } +} + +#[test] +fn cursor_rejects_malformed_noncanonical_and_unknown_versions() { + let valid = canonical_cursor("ffffffffffffffff", [0xab; 32]); + let mut malformed = vec![ + String::new(), + valid[..150].to_owned(), + format!("{valid}x"), + valid.replacen("hcq1:", "hcq0:", 1), + valid.replacen("hcq1:", "hcq2:", 1), + valid.replacen("hcq1:", "HCQ1:", 1), + valid.replacen("hcq1:", "hcq01:", 1), + format!(" {valid}"), + format!("{valid}\n"), + valid.replacen(":ffffffffffffffff:", ":fffffffffffffff:", 1), + valid.replacen(":ffffffffffffffff:", ":0xffffffffffffffff:", 1), + ]; + for index in [4, 69, 86] { + let mut wrong_separator = valid.clone(); + wrong_separator.replace_range(index..index + 1, "-"); + malformed.push(wrong_separator); + } + for index in [5, 70, 87] { + for invalid in ["A", "g", " ", "\0"] { + let mut changed = valid.clone(); + changed.replace_range(index..index + 1, invalid); + assert_eq!(changed.len(), 151); + malformed.push(changed); + } + } + for (end, replacement) in [(7, "é"), (9, "🥕")] { + let mut non_ascii = valid.clone(); + non_ascii.replace_range(5..end, replacement); + assert_eq!(non_ascii.len(), 151); + malformed.push(non_ascii); + } + for text in malformed { + assert_eq!( + AvailabilityPageCursor::parse(&text, base_fingerprint()).expect_err("malformed cursor"), + AvailabilityQueryError::InvalidInput, + ); + } + let mut other_fingerprint = valid; + other_fingerprint.replace_range(5..6, "0"); + assert_eq!( + AvailabilityPageCursor::parse(&other_fingerprint, base_fingerprint()) + .expect_err("canonical different fingerprint"), + AvailabilityQueryError::StaleQuery, + ); +} + +#[test] +fn cursor_rejects_overlong_input_before_retention() { + assert_eq!(AVAILABILITY_CURSOR_MAX_BYTES, 512_usize); + for count in [511, 512] { + for unit in ["x", "\0", "é", "🥕"] { + let text = text_at_byte_count(unit, count); + assert_eq!(text.len(), count); + assert_eq!( + AvailabilityPageCursor::parse(&text, base_fingerprint()) + .expect_err("bounded malformed cursor"), + AvailabilityQueryError::InvalidInput, + ); + } + } + let valid = canonical_cursor("ffffffffffffffff", [0xab; 32]); + let oversized_valid_prefix = format!("{valid}{}", "x".repeat(513 - valid.len())); + let mut wrong_fingerprint = valid.clone(); + wrong_fingerprint.replace_range(5..6, "0"); + let oversized_wrong_fingerprint = format!( + "{wrong_fingerprint}{}", + "x".repeat(513 - wrong_fingerprint.len()) + ); + let oversized_unknown_version = format!("hcq9:{}", "g".repeat(508)); + for text in [ + "x".repeat(513), + "\0".repeat(513), + text_at_byte_count("é", 513), + text_at_byte_count("🥕", 513), + oversized_valid_prefix, + oversized_wrong_fingerprint, + oversized_unknown_version, + "g".repeat(4_096), + ] { + assert!(text.len() > 512); + assert_eq!( + AvailabilityPageCursor::parse(&text, base_fingerprint()) + .expect_err("byte cap takes precedence over shape and fingerprint"), + AvailabilityQueryError::InputTooLarge, + ); + } +} + +#[test] +fn fingerprint_binds_owner_context_and_store_identity() { + let baseline = base_fingerprint(); + assert_eq!(baseline, base_fingerprint()); + let mut fingerprints = vec![baseline]; + fingerprints.push(AvailabilityQueryFingerprint::new( + other_author(), + &base_context(), + 3, + &base_filters(), + AvailabilityPageLimit::default(), + )); + for index in [0, 16, 31] { + let mut changed_context = [1; 32]; + changed_context[index] = 3; + let mut changed_store = [2; 32]; + changed_store[index] = 3; + for changed in [ + context(changed_context, [2; 32], 5, 7), + context([1; 32], changed_store, 5, 7), + ] { + fingerprints.push(AvailabilityQueryFingerprint::new( + author(), + &changed, + 3, + &base_filters(), + AvailabilityPageLimit::default(), + )); + } + } + assert_distinct(&fingerprints); +} + +#[test] +fn fingerprint_binds_source_projection_and_session_generations() { + let mut fingerprints = vec![base_fingerprint()]; + for value in [0, 1, 1_u64 << 63, u64::MAX] { + for (changed_context, session) in [ + (context([1; 32], [2; 32], value, 7), 3), + (context([1; 32], [2; 32], 5, value), 3), + (base_context(), value), + ] { + fingerprints.push(AvailabilityQueryFingerprint::new( + author(), + &changed_context, + session, + &base_filters(), + AvailabilityPageLimit::default(), + )); + } + } + for (source, projection, session) in [(1, 2, 3), (2, 1, 3), (1, 3, 2), (3, 2, 1)] { + fingerprints.push(AvailabilityQueryFingerprint::new( + author(), + &context([1; 32], [2; 32], source, projection), + session, + &base_filters(), + AvailabilityPageLimit::default(), + )); + } + assert_distinct(&fingerprints); +} + +#[test] +fn fingerprint_binds_exact_filters_and_row_limit() { + assert_eq!(base_fingerprint().bytes(), &GOLDEN_FINGERPRINT_BYTES); + let mut fingerprints = vec![base_fingerprint()]; + let exact_ascii = "a".repeat(512); + let exact_unicode = "é".repeat(256); + for search in [ + None, + Some(""), + Some("A"), + Some("a "), + Some(" a"), + Some("é"), + Some("e\u{301}"), + Some("a\0"), + Some(exact_ascii.as_str()), + Some(exact_unicode.as_str()), + ] { + fingerprints.push(AvailabilityQueryFingerprint::new( + author(), + &base_context(), + 3, + &filters(search, None, Some(FoodAvailabilityStatus::Active)), + AvailabilityPageLimit::default(), + )); + } + for publisher in [publisher(), other_publisher()] { + fingerprints.push(AvailabilityQueryFingerprint::new( + author(), + &base_context(), + 3, + &filters( + Some("a"), + Some(publisher), + Some(FoodAvailabilityStatus::Active), + ), + AvailabilityPageLimit::default(), + )); + } + for status in [None, Some(FoodAvailabilityStatus::Sold)] { + fingerprints.push(AvailabilityQueryFingerprint::new( + author(), + &base_context(), + 3, + &filters(Some("a"), None, status), + AvailabilityPageLimit::default(), + )); + } + for rows in 1..=100 { + if rows != 50 { + fingerprints.push(AvailabilityQueryFingerprint::new( + author(), + &base_context(), + 3, + &base_filters(), + AvailabilityPageLimit::new(rows).expect("valid distinct row limit"), + )); + } + } + assert_distinct(&fingerprints); +} + +#[test] +fn fingerprint_option_and_length_framing_prevent_ambiguous_queries() { + assert_eq!(base_fingerprint().bytes(), &GOLDEN_FINGERPRINT_BYTES); + let mut fingerprints = Vec::new(); + for search in [ + None, + Some(""), + Some("a"), + Some("a\0"), + Some("a\0\0"), + Some("active"), + Some("sold"), + Some("None"), + Some("0:1:32"), + Some(AUTHOR_HEX), + ] { + for publisher in [None, Some(publisher())] { + for status in [ + None, + Some(FoodAvailabilityStatus::Active), + Some(FoodAvailabilityStatus::Sold), + ] { + fingerprints.push(AvailabilityQueryFingerprint::new( + author(), + &base_context(), + 3, + &filters(search, publisher, status), + AvailabilityPageLimit::default(), + )); + } + } + } + assert_distinct(&fingerprints); + let with_search = AvailabilityQueryFingerprint::new( + author(), + &base_context(), + 3, + &filters(Some(AUTHOR_HEX), None, None), + AvailabilityPageLimit::default(), + ); + let with_publisher = AvailabilityQueryFingerprint::new( + author(), + &base_context(), + 3, + &filters(Some(""), Some(publisher()), None), + AvailabilityPageLimit::default(), + ); + assert_ne!( + with_search, with_publisher, + "search bytes cannot become a publisher field" + ); +} + +#[test] +fn scoped_query_uses_local_owner_without_signing_capability() { + for session in [0, 3, u64::MAX] { + let local = scope(author(), base_context(), session); + assert_eq!(local.owner(), author()); + assert_eq!(local.context().context_id(), &[1; 32]); + assert_eq!(local.context().store_generation(), &[2; 32]); + assert_eq!(local.context().source_revision(), 5); + assert_eq!(local.context().projection_generation(), 7); + assert_eq!( + local.session_generation(), + SessionGeneration::from_value(session) + ); + let query = ScopedAvailabilityQuery::new( + local, + base_filters(), + AvailabilityPageLimit::default(), + None, + ) + .expect("public owner and structural generations require no signing capability"); + assert_eq!(query.scope().owner(), author()); + assert_eq!(query.scope().session_generation().value(), session); + assert_eq!( + query.filters().search().expect("exact search").as_str(), + "a" + ); + assert_eq!(query.filters().publisher(), None); + assert_eq!( + query.filters().status(), + Some(FoodAvailabilityStatus::Active) + ); + assert_eq!(query.limit().rows(), 50); + assert!(query.cursor().is_none()); + assert_eq!( + query.validate_scope(&scope(author(), base_context(), session)), + Ok(()) + ); + } + assert_eq!( + base_query().fingerprint().bytes(), + &GOLDEN_FINGERPRINT_BYTES + ); +} + +#[test] +fn scoped_query_refuses_owner_and_context_changes() { + let query = base_query(); + assert_eq!(query.validate_scope(&base_scope()), Ok(())); + assert_eq!( + query.validate_scope(&scope(other_author(), base_context(), 3)), + Err(AvailabilityQueryError::ScopeMismatch), + ); + for index in [0, 16, 31] { + let mut changed_context = [1; 32]; + changed_context[index] = 3; + let changed = scope(author(), context(changed_context, [2; 32], 5, 7), 3); + assert_eq!( + query.validate_scope(&changed), + Err(AvailabilityQueryError::ScopeMismatch) + ); + } + assert_eq!(query.validate_scope(&base_scope()), Ok(())); + assert_eq!(query.scope().owner(), author()); + assert_eq!(query.scope().context().context_id(), &[1; 32]); +} + +#[test] +fn scoped_query_refuses_stale_session_store_source_and_projection() { + let query = base_query(); + for index in [0, 16, 31] { + let mut changed_store = [2; 32]; + changed_store[index] = 3; + let changed = scope(author(), context([1; 32], changed_store, 5, 7), 3); + assert_eq!( + query.validate_scope(&changed), + Err(AvailabilityQueryError::StaleQuery) + ); + } + for value in [0, 1, 1_u64 << 63, u64::MAX] { + for changed in [ + scope(author(), context([1; 32], [2; 32], value, 7), 3), + scope(author(), context([1; 32], [2; 32], 5, value), 3), + scope(author(), base_context(), value), + ] { + assert_eq!( + query.validate_scope(&changed), + Err(AvailabilityQueryError::StaleQuery) + ); + assert_eq!(query.validate_scope(&base_scope()), Ok(())); + } + } + let full_width = ScopedAvailabilityQuery::new( + scope( + author(), + context([1; 32], [2; 32], u64::MAX, u64::MAX), + u64::MAX, + ), + base_filters(), + AvailabilityPageLimit::default(), + None, + ) + .expect("full-width structural generations"); + assert_eq!( + full_width.validate_scope(&scope( + author(), + context([1; 32], [2; 32], u64::MAX, u64::MAX), + u64::MAX + )), + Ok(()), + ); + assert_eq!( + full_width.validate_scope(&scope( + author(), + context([1; 32], [2; 32], u64::MAX, u64::MAX), + (1_u64 << 63) - 1 + )), + Err(AvailabilityQueryError::StaleQuery), + ); + assert_eq!(query.scope().context().store_generation(), &[2; 32]); + assert_eq!(query.scope().context().source_revision(), 5); + assert_eq!(query.scope().context().projection_generation(), 7); + assert_eq!(query.scope().session_generation().value(), 3); +} + +#[test] +fn scoped_query_validates_cursor_against_complete_request() { + let cursor_text = canonical_cursor("ffffffffffffffff", [0xab; 32]); + let query = { + let borrowed_input = cursor_text.clone(); + ScopedAvailabilityQuery::new( + base_scope(), + base_filters(), + AvailabilityPageLimit::default(), + Some(&borrowed_input), + ) + .expect("valid borrowed cursor retained as a bounded owned value") + }; + let retained = query.cursor().expect("explicit continuation"); + assert_eq!(retained.as_str(), cursor_text); + assert_eq!(retained.after().created_at().as_u64(), u64::MAX); + assert_eq!( + retained.after().version().event_id().as_bytes(), + &[0xab; 32] + ); + assert_eq!(query.fingerprint().bytes(), &GOLDEN_FINGERPRINT_BYTES); + assert_eq!(query.validate_scope(&base_scope()), Ok(())); + + let mut changed_requests = vec![( + scope(other_author(), base_context(), 3), + base_filters(), + AvailabilityPageLimit::default(), + )]; + for index in [0, 16, 31] { + let mut changed_context = [1; 32]; + changed_context[index] = 3; + let mut changed_store = [2; 32]; + changed_store[index] = 3; + for changed_scope in [ + scope(author(), context(changed_context, [2; 32], 5, 7), 3), + scope(author(), context([1; 32], changed_store, 5, 7), 3), + ] { + changed_requests.push(( + changed_scope, + base_filters(), + AvailabilityPageLimit::default(), + )); + } + } + for value in [0, 1_u64 << 63, u64::MAX] { + for changed_scope in [ + scope(author(), context([1; 32], [2; 32], value, 7), 3), + scope(author(), context([1; 32], [2; 32], 5, value), 3), + scope(author(), base_context(), value), + ] { + changed_requests.push(( + changed_scope, + base_filters(), + AvailabilityPageLimit::default(), + )); + } + } + for search in [ + None, + Some(""), + Some("A"), + Some("a "), + Some("é"), + Some("e\u{301}"), + Some("a\0"), + ] { + changed_requests.push(( + base_scope(), + filters(search, None, Some(FoodAvailabilityStatus::Active)), + AvailabilityPageLimit::default(), + )); + } + for changed_publisher in [publisher(), other_publisher()] { + changed_requests.push(( + base_scope(), + filters( + Some("a"), + Some(changed_publisher), + Some(FoodAvailabilityStatus::Active), + ), + AvailabilityPageLimit::default(), + )); + } + for status in [None, Some(FoodAvailabilityStatus::Sold)] { + changed_requests.push(( + base_scope(), + filters(Some("a"), None, status), + AvailabilityPageLimit::default(), + )); + } + for rows in [1, 49, 51, 100] { + changed_requests.push(( + base_scope(), + base_filters(), + AvailabilityPageLimit::new(rows).expect("changed bounded row limit"), + )); + } + assert!( + changed_requests.len() >= 20, + "complete independent scope/filter/limit mutations" + ); + for (changed_scope, changed_filters, changed_limit) in changed_requests { + assert_eq!( + ScopedAvailabilityQuery::new( + changed_scope, + changed_filters, + changed_limit, + Some(&cursor_text) + ) + .expect_err("cursor belongs to a different complete request"), + AvailabilityQueryError::StaleQuery, + ); + } + for invalid in ["", "hcq9:invalid", "HCAV_UNTRUSTED_CURSOR_MARKER"] { + assert_eq!( + ScopedAvailabilityQuery::new( + base_scope(), + base_filters(), + AvailabilityPageLimit::default(), + Some(invalid) + ) + .expect_err("malformed borrowed cursor"), + AvailabilityQueryError::InvalidInput, + ); + } + let oversized = "\0".repeat(513); + assert_eq!( + ScopedAvailabilityQuery::new( + base_scope(), + base_filters(), + AvailabilityPageLimit::default(), + Some(&oversized) + ) + .expect_err("oversized borrowed cursor"), + AvailabilityQueryError::InputTooLarge, + ); + assert_eq!(base_query().fingerprint(), query.fingerprint()); + assert!(base_query().cursor().is_none()); +} + +#[test] +fn page_contract_enforces_rows_and_preserves_projection() { + // This type deliberately has neither Clone nor Debug: owned pages need neither. + struct Row(u16); + + for (rows, limit) in [(0, 50), (50, 50), (100, 100), (1, 1)] { + let items: Vec<_> = (0..rows).map(Row).collect(); + let pointer = items.as_ptr(); + let capacity = items.capacity(); + let page = AvailabilityPage::new( + AvailabilityPageLimit::new(limit).expect("bounded row limit"), + items, + AvailabilityPageContinuation::End, + u64::MAX, + ) + .expect("owned row count within limit"); + assert_eq!(page.items().len(), usize::from(rows)); + assert_eq!(page.items().as_ptr(), pointer); + assert_eq!(page.projection_generation(), u64::MAX); + assert!(matches!( + page.continuation(), + AvailabilityPageContinuation::End + )); + assert_eq!( + page.items().iter().map(|row| row.0).collect::<Vec<_>>(), + (0..rows).collect::<Vec<_>>() + ); + let returned = page.into_items(); + assert_eq!(returned.as_ptr(), pointer); + assert_eq!(returned.capacity(), capacity); + assert_eq!(returned.len(), usize::from(rows)); + } + for limit in [1, 7, 50, 100] { + let items: Vec<_> = (0..=limit).map(Row).collect(); + assert_eq!( + AvailabilityPage::new( + AvailabilityPageLimit::new(limit).expect("bounded row limit"), + items, + AvailabilityPageContinuation::End, + 7, + ) + .expect_err("configured limit plus one, including 101 rows"), + AvailabilityQueryError::Capacity, + ); + } + let query = base_query(); + assert_eq!( + query + .page(vec![0_u8; 50], None) + .expect("default full page") + .projection_generation(), + 7 + ); + assert_eq!( + query + .page(vec![0_u8; 51], None) + .expect_err("default row overflow"), + AvailabilityQueryError::Capacity + ); + for generation in [0, u64::MAX] { + let query = ScopedAvailabilityQuery::new( + scope(author(), context([1; 32], [2; 32], 5, generation), 3), + base_filters(), + AvailabilityPageLimit::new(100).expect("maximum limit"), + None, + ) + .expect("exact projection query"); + assert_eq!( + query + .page(vec![0_u8; 100], None) + .expect("maximum full page") + .projection_generation(), + generation + ); + assert_eq!( + query + .page(vec![0_u8; 101], None) + .expect_err("maximum overflow"), + AvailabilityQueryError::Capacity + ); + } +} + +#[test] +fn local_page_end_and_continuation_remain_distinct() { + let query = base_query(); + let next = order(u64::MAX, [0xab; 32]); + let ended = query + .page(Vec::<u8>::new(), None) + .expect("explicit local end"); + assert!(ended.items().is_empty()); + assert!(matches!( + ended.continuation(), + AvailabilityPageContinuation::End + )); + assert_eq!(ended.projection_generation(), 7); + let continued = query + .page(vec![42_u8], Some(next)) + .expect("explicit local continuation"); + assert_eq!(continued.items(), &[42]); + assert_eq!(continued.projection_generation(), 7); + let AvailabilityPageContinuation::More(cursor) = continued.continuation() else { + panic!("explicit next position must retain a continuation"); + }; + assert_eq!( + cursor.as_str(), + canonical_cursor("ffffffffffffffff", [0xab; 32]) + ); + assert_eq!(cursor.after(), next); + assert_eq!( + AvailabilityPageCursor::parse(cursor.as_str(), query.fingerprint()) + .expect("query-bound continuation") + .after(), + next + ); + let empty_continued = query + .page(Vec::<u8>::new(), Some(next)) + .expect("caller explicitly supplies continuation"); + assert!(empty_continued.items().is_empty()); + assert!(matches!( + empty_continued.continuation(), + AvailabilityPageContinuation::More(_) + )); + assert_eq!( + empty_continued.projection_generation(), + ended.projection_generation() + ); + assert!(format!("{:?}", ended.continuation()).contains("End")); + assert!(format!("{:?}", continued.continuation()).contains("More")); +} + +#[test] +fn query_errors_and_debug_never_echo_untrusted_payloads() { + const SEARCH_MARKER: &str = "HCAV_UNTRUSTED_SEARCH_PAYLOAD_é\0%_"; + const ITEM_MARKER: &str = "HCAV_UNTRUSTED_ITEM_PAYLOAD"; + const CURSOR_MARKER: &str = "HCAV_UNTRUSTED_CURSOR_PAYLOAD"; + let mut event_id = [0xde; 32]; + event_id[..4].copy_from_slice(&[0xde, 0xad, 0xc0, 0xde]); + let search = AvailabilitySearchText::new(SEARCH_MARKER).expect("bounded marker search"); + let marked_filters = filters( + Some(SEARCH_MARKER), + Some(publisher()), + Some(FoodAvailabilityStatus::Sold), + ); + let marked_fingerprint = AvailabilityQueryFingerprint::new( + author(), + &base_context(), + 3, + &marked_filters, + AvailabilityPageLimit::default(), + ); + let cursor = AvailabilityPageCursor::encode(marked_fingerprint, order(u64::MAX, event_id)); + let cursor_text = cursor.as_str().to_owned(); + let scope_debug = format!("{:?}", base_scope()); + let query = ScopedAvailabilityQuery::new( + base_scope(), + marked_filters, + AvailabilityPageLimit::default(), + Some(&cursor_text), + ) + .expect("valid query carrying untrusted bounded search and public continuation"); + let search_debug = format!("{search:?}"); + assert!(search_debug.contains(&SEARCH_MARKER.len().to_string())); + let cursor_debug = format!("{cursor:?}"); + assert!(cursor_debug.contains("151")); + let mut debug_values = vec![ + search_debug, + format!("{:?}", query.filters()), + cursor_debug, + scope_debug, + format!("{query:?}"), + format!("{:?}", AvailabilityPageContinuation::End), + ]; + for next in [None, Some(order(u64::MAX, event_id))] { + let page = query + .page(vec![ITEM_MARKER.to_owned()], next) + .expect("bounded marker page"); + debug_values.push(format!("{page:?}")); + debug_values.push(format!("{:?}", page.continuation())); + } + let event_id_hex = hex(&event_id); + let event_id_debug = format!("{event_id:?}"); + let fingerprint_hex = hex(marked_fingerprint.bytes()); + let fingerprint_debug = format!("{:?}", marked_fingerprint.bytes()); + let context_hex = hex(&[1; 32]); + let store_hex = hex(&[2; 32]); + let context_debug = format!("{:?}", [1_u8; 32]); + let store_debug = format!("{:?}", [2_u8; 32]); + for text in debug_values { + for forbidden in [ + "HCAV_UNTRUSTED_SEARCH_PAYLOAD_", + SEARCH_MARKER, + ITEM_MARKER, + CURSOR_MARKER, + cursor_text.as_str(), + event_id_hex.as_str(), + event_id_debug.as_str(), + fingerprint_hex.as_str(), + fingerprint_debug.as_str(), + context_hex.as_str(), + store_hex.as_str(), + context_debug.as_str(), + store_debug.as_str(), + ] { + assert!( + !text.contains(forbidden), + "diagnostics must omit untrusted payload and opaque identities" + ); + } + } + let invalid_cursor = ScopedAvailabilityQuery::new( + base_scope(), + base_filters(), + AvailabilityPageLimit::default(), + Some(CURSOR_MARKER), + ) + .expect_err("untrusted malformed cursor"); + let invalid_search = AvailabilitySearchText::new(&SEARCH_MARKER.repeat(32)) + .expect_err("oversized untrusted search"); + assert_eq!(invalid_cursor, AvailabilityQueryError::InvalidInput); + assert_eq!(invalid_search, AvailabilityQueryError::InputTooLarge); + for (error, name) in [ + (AvailabilityQueryError::InvalidInput, "InvalidInput"), + (AvailabilityQueryError::InputTooLarge, "InputTooLarge"), + (AvailabilityQueryError::ScopeMismatch, "ScopeMismatch"), + (AvailabilityQueryError::StaleQuery, "StaleQuery"), + (AvailabilityQueryError::Capacity, "Capacity"), + ] { + let copied = error; + assert_eq!(copied, error); + let standard_error: &dyn Error = &error; + assert!(standard_error.source().is_none()); + assert_eq!(format!("{error:?}"), name); + let display = error.to_string(); + assert!(!display.is_empty()); + assert_eq!(display, copied.to_string()); + for forbidden in [ + "HCAV_UNTRUSTED_SEARCH_PAYLOAD_", + SEARCH_MARKER, + ITEM_MARKER, + CURSOR_MARKER, + cursor_text.as_str(), + ] { + assert!(!format!("{error:?} {error}").contains(forbidden)); + } + } + for error in [invalid_cursor, invalid_search] { + assert!(!format!("{error:?} {error}").contains("HCAV_UNTRUSTED_SEARCH_PAYLOAD_")); + assert!(!format!("{error:?} {error}").contains(SEARCH_MARKER)); + assert!(!format!("{error:?} {error}").contains(CURSOR_MARKER)); + } +} diff --git a/core/crates/harvestcircle_domain/Cargo.toml b/core/crates/harvestcircle_domain/Cargo.toml @@ -17,6 +17,7 @@ radroots_event.workspace = true radroots_event_codec = { workspace = true, features = ["json"] } radroots_identity.workspace = true secrecy = "=0.10.3" +sha2.workspace = true zeroize = "=1.9.0" [lints] diff --git a/core/crates/harvestcircle_domain/src/availability/mod.rs b/core/crates/harvestcircle_domain/src/availability/mod.rs @@ -2,9 +2,17 @@ pub mod identity; pub mod projection; +pub mod query; pub use identity::{AvailabilityEventVersion, AvailabilityListingCoordinate, PublicPublisher}; pub use projection::{ AvailabilityHeadState, AvailabilityHeadView, AvailabilityObservation, AvailabilityUnsupportedReason, AvailabilityVersionView, }; +pub use query::{ + AVAILABILITY_CURSOR_MAX_BYTES, AVAILABILITY_PAGE_DEFAULT_ROWS, AVAILABILITY_PAGE_MAX_ROWS, + AVAILABILITY_QUERY_TEXT_MAX_BYTES, AvailabilityOrderKey, AvailabilityPage, + AvailabilityPageContinuation, AvailabilityPageCursor, AvailabilityPageLimit, + AvailabilityQueryContext, AvailabilityQueryError, AvailabilityQueryFilters, + AvailabilityQueryFingerprint, AvailabilitySearchText, +}; diff --git a/core/crates/harvestcircle_domain/src/availability/query.rs b/core/crates/harvestcircle_domain/src/availability/query.rs @@ -0,0 +1,540 @@ +//! Bounded local availability query values and public snapshot continuations. +//! +//! These values retain structural bindings supplied by a caller. They prove no +//! installed-account admission, event signature, physical inventory, network +//! completeness or current database state. The storage adapter must supply its +//! actual validated store identity, source revision and projection snapshot. + +use std::cmp::Ordering; +use std::fmt; + +pub use radroots_event::envelope::EventTimestamp; +pub use radroots_event::food::availability::FoodAvailabilityStatus; +use sha2::{Digest, Sha256}; + +use crate::PublicKey; + +use super::{AvailabilityEventVersion, PublicPublisher}; + +pub const AVAILABILITY_PAGE_DEFAULT_ROWS: u16 = 50; +pub const AVAILABILITY_PAGE_MAX_ROWS: u16 = 100; +pub const AVAILABILITY_QUERY_TEXT_MAX_BYTES: usize = 512; +pub const AVAILABILITY_CURSOR_MAX_BYTES: usize = 512; + +const QUERY_FINGERPRINT_DOMAIN: &[u8] = b"harvestcircle.availability.query.v1\0"; +const CURSOR_ENCODED_BYTES: usize = 151; +const HEX_DIGITS: &[u8; 16] = b"0123456789abcdef"; + +/// Static query-contract failures without untrusted input or dependent errors. +#[derive(Clone, Copy, Debug, Eq, PartialEq)] +pub enum AvailabilityQueryError { + InvalidInput, + InputTooLarge, + ScopeMismatch, + StaleQuery, + Capacity, +} + +impl fmt::Display for AvailabilityQueryError { + fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { + formatter.write_str(match self { + Self::InvalidInput => "The availability query input is invalid.", + Self::InputTooLarge => "The availability query input exceeds its byte limit.", + Self::ScopeMismatch => "The availability query scope does not match.", + Self::StaleQuery => "The availability query is stale.", + Self::Capacity => "The availability page exceeds its row limit.", + }) + } +} + +impl std::error::Error for AvailabilityQueryError {} + +/// A positive row limit bounded by the local page contract. +#[derive(Clone, Copy, Debug, Eq, PartialEq)] +pub struct AvailabilityPageLimit(u16); + +impl AvailabilityPageLimit { + /// Admits exactly one through one hundred rows. + /// + /// # Errors + /// + /// Returns `InvalidInput` for zero or a limit above the maximum. + pub const fn new(rows: u16) -> Result<Self, AvailabilityQueryError> { + if rows == 0 || rows > AVAILABILITY_PAGE_MAX_ROWS { + return Err(AvailabilityQueryError::InvalidInput); + } + Ok(Self(rows)) + } + + #[must_use] + pub const fn rows(self) -> u16 { + self.0 + } +} + +impl Default for AvailabilityPageLimit { + fn default() -> Self { + Self(AVAILABILITY_PAGE_DEFAULT_ROWS) + } +} + +/// Exact opaque cached search text, including a present empty value. +#[derive(Clone, Eq, PartialEq)] +pub struct AvailabilitySearchText(String); + +impl AvailabilitySearchText { + /// Retains exact UTF-8 bytes after checking their bound before copying. + /// + /// This applies no trimming, normalization, location policy or SQL wildcard + /// interpretation and initiates no remote search. + /// + /// # Errors + /// + /// Returns `InputTooLarge` when the borrowed input exceeds 512 bytes. + pub fn new(value: &str) -> Result<Self, AvailabilityQueryError> { + if value.len() > AVAILABILITY_QUERY_TEXT_MAX_BYTES { + return Err(AvailabilityQueryError::InputTooLarge); + } + Ok(Self(value.to_owned())) + } + + #[must_use] + pub fn as_str(&self) -> &str { + &self.0 + } +} + +impl fmt::Debug for AvailabilitySearchText { + fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { + formatter + .debug_struct("AvailabilitySearchText") + .field("bytes", &self.0.len()) + .finish() + } +} + +/// Immutable optional local filters using the selected shared status enum. +#[derive(Clone, Eq, PartialEq)] +pub struct AvailabilityQueryFilters { + search: Option<AvailabilitySearchText>, + publisher: Option<PublicPublisher>, + status: Option<FoodAvailabilityStatus>, +} + +impl AvailabilityQueryFilters { + #[must_use] + pub fn new( + search: Option<AvailabilitySearchText>, + publisher: Option<PublicPublisher>, + status: Option<FoodAvailabilityStatus>, + ) -> Self { + Self { + search, + publisher, + status, + } + } + + #[must_use] + pub const fn search(&self) -> Option<&AvailabilitySearchText> { + self.search.as_ref() + } + + #[must_use] + pub const fn publisher(&self) -> Option<PublicPublisher> { + self.publisher + } + + #[must_use] + pub const fn status(&self) -> Option<FoodAvailabilityStatus> { + self.status + } +} + +impl fmt::Debug for AvailabilityQueryFilters { + fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { + formatter + .debug_struct("AvailabilityQueryFilters") + .field( + "search_bytes", + &self.search().map(|value| value.as_str().len()), + ) + .field("publisher_present", &self.publisher.is_some()) + .field("status", &self.status) + .finish() + } +} + +/// Caller-supplied selected-context and local snapshot bindings. +/// +/// Nonzero opaque identities are structural values, not proof that a context +/// or store is installed, admitted, current or validated by this module. +#[derive(Clone, Copy, Eq, PartialEq)] +pub struct AvailabilityQueryContext { + context_id: [u8; 32], + store_generation: [u8; 32], + source_revision: u64, + projection_generation: u64, +} + +impl AvailabilityQueryContext { + /// Retains exact identities and full-width revisions and generations. + /// + /// # Errors + /// + /// Returns `InvalidInput` if either opaque identity is all zero. + pub fn new( + context_id: [u8; 32], + store_generation: [u8; 32], + source_revision: u64, + projection_generation: u64, + ) -> Result<Self, AvailabilityQueryError> { + if context_id == [0; 32] || store_generation == [0; 32] { + return Err(AvailabilityQueryError::InvalidInput); + } + Ok(Self { + context_id, + store_generation, + source_revision, + projection_generation, + }) + } + + #[must_use] + pub const fn context_id(&self) -> &[u8; 32] { + &self.context_id + } + + #[must_use] + pub const fn store_generation(&self) -> &[u8; 32] { + &self.store_generation + } + + #[must_use] + pub const fn source_revision(&self) -> u64 { + self.source_revision + } + + #[must_use] + pub const fn projection_generation(&self) -> u64 { + self.projection_generation + } +} + +impl fmt::Debug for AvailabilityQueryContext { + fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { + formatter + .debug_struct("AvailabilityQueryContext") + .field("source_revision", &self.source_revision) + .field("projection_generation", &self.projection_generation) + .finish_non_exhaustive() + } +} + +/// A page position ordered by descending signed event time and ascending ID. +/// +/// Signed event time retains the shared timestamp's complete `u64` range. +/// Lower `Ord` values come earlier in the page; this selects no event head. +#[derive(Clone, Copy, Debug, Eq, PartialEq)] +pub struct AvailabilityOrderKey { + created_at: EventTimestamp, + version: AvailabilityEventVersion, +} + +impl AvailabilityOrderKey { + #[must_use] + pub const fn new(created_at: EventTimestamp, version: AvailabilityEventVersion) -> Self { + Self { + created_at, + version, + } + } + + #[must_use] + pub const fn created_at(self) -> EventTimestamp { + self.created_at + } + + #[must_use] + pub const fn version(self) -> AvailabilityEventVersion { + self.version + } + + #[must_use] + pub fn is_after(self, previous: Self) -> bool { + self > previous + } +} + +impl Ord for AvailabilityOrderKey { + fn cmp(&self, other: &Self) -> Ordering { + other.created_at.cmp(&self.created_at).then_with(|| { + self.version + .event_id() + .as_bytes() + .cmp(other.version.event_id().as_bytes()) + }) + } +} + +impl PartialOrd for AvailabilityOrderKey { + fn partial_cmp(&self, other: &Self) -> Option<Ordering> { + Some(self.cmp(other)) + } +} + +/// A versioned public request digest, with no signature or authorization claim. +#[derive(Clone, Copy, Eq, PartialEq)] +pub struct AvailabilityQueryFingerprint([u8; 32]); + +impl AvailabilityQueryFingerprint { + /// Streams the fixed v1 frame through standard SHA-256. + /// + /// The frame binds full owner/context/store bytes, big-endian counters, + /// exact option discriminants and search byte length, shared status and + /// row limit. No secret, host entropy or intermediate request string exists. + #[must_use] + pub fn new( + owner: PublicKey, + context: &AvailabilityQueryContext, + session_generation: u64, + filters: &AvailabilityQueryFilters, + limit: AvailabilityPageLimit, + ) -> Self { + let mut digest = Sha256::new(); + digest.update(QUERY_FINGERPRINT_DOMAIN); + digest.update(owner.as_bytes()); + digest.update(context.context_id()); + digest.update(context.store_generation()); + digest.update(context.source_revision().to_be_bytes()); + digest.update(context.projection_generation().to_be_bytes()); + digest.update(session_generation.to_be_bytes()); + match filters.search() { + None => digest.update([0]), + Some(search) => { + digest.update([1]); + // The validated text type bounds this length to at most 512. + digest.update((search.as_str().len() as u64).to_be_bytes()); + digest.update(search.as_str().as_bytes()); + } + } + match filters.publisher() { + None => digest.update([0]), + Some(publisher) => { + digest.update([1]); + digest.update(publisher.public_key().as_bytes()); + } + } + digest.update([match filters.status() { + None => 0, + Some(FoodAvailabilityStatus::Active) => 1, + Some(FoodAvailabilityStatus::Sold) => 2, + }]); + digest.update(limit.rows().to_be_bytes()); + Self(digest.finalize().into()) + } + + #[must_use] + pub const fn bytes(&self) -> &[u8; 32] { + &self.0 + } +} + +impl fmt::Debug for AvailabilityQueryFingerprint { + fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { + formatter + .debug_struct("AvailabilityQueryFingerprint") + .finish_non_exhaustive() + } +} + +/// Canonical public continuation for one exact structural query snapshot. +/// +/// A cursor is forgeable by design. Its fingerprint is correspondence, not a +/// permission token; a future consumer must separately admit the local scope. +#[derive(Clone, Eq, PartialEq)] +pub struct AvailabilityPageCursor { + value: String, + after: AvailabilityOrderKey, +} + +impl AvailabilityPageCursor { + #[must_use] + pub fn encode(fingerprint: AvailabilityQueryFingerprint, after: AvailabilityOrderKey) -> Self { + let mut value = String::with_capacity(CURSOR_ENCODED_BYTES); + value.push_str("hcq1:"); + append_hex(&mut value, fingerprint.bytes()); + value.push(':'); + append_hex(&mut value, &after.created_at().as_u64().to_be_bytes()); + value.push(':'); + append_hex(&mut value, after.version().event_id().as_bytes()); + Self { value, after } + } + + /// Validates the complete borrowed cursor before allocating its owned text. + /// + /// # Errors + /// + /// Returns `InputTooLarge` first for input above 512 bytes, `InvalidInput` + /// for noncanonical version/framing/hex, or `StaleQuery` for a different + /// complete request fingerprint. + pub fn parse( + value: &str, + expected: AvailabilityQueryFingerprint, + ) -> Result<Self, AvailabilityQueryError> { + if value.len() > AVAILABILITY_CURSOR_MAX_BYTES { + return Err(AvailabilityQueryError::InputTooLarge); + } + if value.len() != CURSOR_ENCODED_BYTES || !value.is_ascii() { + return Err(AvailabilityQueryError::InvalidInput); + } + let bytes = value.as_bytes(); + if &bytes[..5] != b"hcq1:" || bytes[69] != b':' || bytes[86] != b':' { + return Err(AvailabilityQueryError::InvalidInput); + } + let fingerprint = decode_hex::<32>(&bytes[5..69])?; + let timestamp = u64::from_be_bytes(decode_hex::<8>(&bytes[70..86])?); + let event_id = decode_hex::<32>(&bytes[87..151])?; + if &fingerprint != expected.bytes() { + return Err(AvailabilityQueryError::StaleQuery); + } + let after = AvailabilityOrderKey::new( + EventTimestamp::new(timestamp), + AvailabilityEventVersion::from_canonical(radroots_event::EventId::from_bytes(event_id)), + ); + Ok(Self { + value: value.to_owned(), + after, + }) + } + + #[must_use] + pub fn as_str(&self) -> &str { + &self.value + } + + #[must_use] + pub const fn after(&self) -> AvailabilityOrderKey { + self.after + } +} + +impl fmt::Debug for AvailabilityPageCursor { + fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { + formatter + .debug_struct("AvailabilityPageCursor") + .field("bytes", &self.value.len()) + .finish() + } +} + +fn append_hex(value: &mut String, bytes: &[u8]) { + for byte in bytes { + value.push(char::from(HEX_DIGITS[usize::from(byte >> 4)])); + value.push(char::from(HEX_DIGITS[usize::from(byte & 0x0f)])); + } +} + +fn decode_hex<const N: usize>(input: &[u8]) -> Result<[u8; N], AvailabilityQueryError> { + if input.len() != N * 2 { + return Err(AvailabilityQueryError::InvalidInput); + } + let mut result = [0; N]; + for (output, pair) in result.iter_mut().zip(input.chunks_exact(2)) { + *output = (hex_digit(pair[0])? << 4) | hex_digit(pair[1])?; + } + Ok(result) +} + +const fn hex_digit(byte: u8) -> Result<u8, AvailabilityQueryError> { + match byte { + b'0'..=b'9' => Ok(byte - b'0'), + b'a'..=b'f' => Ok(byte - b'a' + 10), + _ => Err(AvailabilityQueryError::InvalidInput), + } +} + +/// End or continuation of this local query snapshot only. +/// +/// `End` proves no exhaustive network/deletion knowledge, fresh inventory or +/// absence of food outside the rows supplied by the local query adapter. +#[derive(Clone, Eq, PartialEq)] +pub enum AvailabilityPageContinuation { + End, + More(AvailabilityPageCursor), +} + +impl fmt::Debug for AvailabilityPageContinuation { + fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { + formatter.write_str(match self { + Self::End => "End", + Self::More(_) => "More", + }) + } +} + +/// A bounded-row owned result without a database or serialization-cap claim. +/// +/// The storage adapter remains responsible for bounded scanning, actual +/// snapshot selection, response bytes and deadlines. +pub struct AvailabilityPage<T> { + items: Vec<T>, + continuation: AvailabilityPageContinuation, + projection_generation: u64, +} + +impl<T> AvailabilityPage<T> { + /// Moves the supplied vector after checking its configured row bound. + /// + /// No item is cloned and no additional vector allocation is made. + /// + /// # Errors + /// + /// Returns `Capacity` when the owned row count exceeds the limit. + pub fn new( + limit: AvailabilityPageLimit, + items: Vec<T>, + continuation: AvailabilityPageContinuation, + projection_generation: u64, + ) -> Result<Self, AvailabilityQueryError> { + if items.len() > usize::from(limit.rows()) { + return Err(AvailabilityQueryError::Capacity); + } + Ok(Self { + items, + continuation, + projection_generation, + }) + } + + #[must_use] + pub fn items(&self) -> &[T] { + &self.items + } + + #[must_use] + pub const fn continuation(&self) -> &AvailabilityPageContinuation { + &self.continuation + } + + #[must_use] + pub const fn projection_generation(&self) -> u64 { + self.projection_generation + } + + #[must_use] + pub fn into_items(self) -> Vec<T> { + self.items + } +} + +impl<T> fmt::Debug for AvailabilityPage<T> { + fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { + formatter + .debug_struct("AvailabilityPage") + .field("item_count", &self.items.len()) + .field("projection_generation", &self.projection_generation) + .field("continuation", &self.continuation) + .finish() + } +} diff --git a/core/crates/harvestcircle_domain/src/lib.rs b/core/crates/harvestcircle_domain/src/lib.rs @@ -8,9 +8,13 @@ pub mod profile; pub mod time; pub use availability::{ - AvailabilityEventVersion, AvailabilityHeadState, AvailabilityHeadView, - AvailabilityListingCoordinate, AvailabilityObservation, AvailabilityUnsupportedReason, - AvailabilityVersionView, PublicPublisher, + AVAILABILITY_CURSOR_MAX_BYTES, AVAILABILITY_PAGE_DEFAULT_ROWS, AVAILABILITY_PAGE_MAX_ROWS, + AVAILABILITY_QUERY_TEXT_MAX_BYTES, AvailabilityEventVersion, AvailabilityHeadState, + AvailabilityHeadView, AvailabilityListingCoordinate, AvailabilityObservation, + AvailabilityOrderKey, AvailabilityPage, AvailabilityPageContinuation, AvailabilityPageCursor, + AvailabilityPageLimit, AvailabilityQueryContext, AvailabilityQueryError, + AvailabilityQueryFilters, AvailabilityQueryFingerprint, AvailabilitySearchText, + AvailabilityUnsupportedReason, AvailabilityVersionView, PublicPublisher, }; pub use error::{SafeError, SafeErrorCode, SafeMessage}; pub use identity::{ diff --git a/radroots.lib.source-lock.v1.toml b/radroots.lib.source-lock.v1.toml @@ -6,4 +6,4 @@ workspace_catalog_sha256 = "ee295f2352e2577a4052d980624415aec9871197d4fc9910a4c2 version = "0.1.0-alpha" source_archive_sha256 = "c648a3ab993d10253b9073e7e86db7b8970863bdf1d394d9fc30d66825695240" lockfile = "core/Cargo.lock" -lockfile_sha256 = "049aea164146e45c41a4a9d9686cca4a9ca88413d8a5b17aaec78b2bef0947bc" +lockfile_sha256 = "8f31db666b29a3864a006d318e44e14c246f7aeda60921f56f914de9dca62ed6" diff --git a/tools/xtask/src/lib.rs b/tools/xtask/src/lib.rs @@ -1159,7 +1159,7 @@ fn provenance_check(root: &Path, inventory: &Inventory, findings: &mut Vec<Strin "version = \"0.1.0-alpha\"\n", "source_archive_sha256 = \"c648a3ab993d10253b9073e7e86db7b8970863bdf1d394d9fc30d66825695240\"\n", "lockfile = \"core/Cargo.lock\"\n", - "lockfile_sha256 = \"049aea164146e45c41a4a9d9686cca4a9ca88413d8a5b17aaec78b2bef0947bc\"\n", + "lockfile_sha256 = \"8f31db666b29a3864a006d318e44e14c246f7aeda60921f56f914de9dca62ed6\"\n", ); let source_lock_bytes = match bounded_no_follow_bytes(root, Path::new(SOURCE_LOCK_PATH), MAX_SOURCE_LOCK_BYTES) { @@ -2434,7 +2434,7 @@ mod tests { "version = \"0.1.0-alpha\"\n", "source_archive_sha256 = \"c648a3ab993d10253b9073e7e86db7b8970863bdf1d394d9fc30d66825695240\"\n", "lockfile = \"core/Cargo.lock\"\n", - "lockfile_sha256 = \"049aea164146e45c41a4a9d9686cca4a9ca88413d8a5b17aaec78b2bef0947bc\"\n", + "lockfile_sha256 = \"8f31db666b29a3864a006d318e44e14c246f7aeda60921f56f914de9dca62ed6\"\n", ), ); write(&root, "core/Cargo.toml", "");