//! Strict PBX v0 envelope and Registry sections. No legacy fallback. //! Envelope parsing is structural only: non-Registry sections and instructions //! must be validated by their consumers before an executable image is published. use crate::load_limits::{ LoadBudget, LoadCode as C, LoadFailure as E, LoadReason as R, LoadResource as Q, }; use crate::registry::*; #[derive(Debug, Clone, Copy)] pub struct Section<'a> { pub kind: u32, pub offset: usize, pub bytes: &'a [u8], } #[derive(Debug)] pub struct PbxEnvelope<'a> { sections: [Option>; 9], } impl<'a> PbxEnvelope<'a> { pub fn section(&self, kind: u32) -> Option> { self.sections.get(kind as usize).copied().flatten() } pub fn parse(bytes: &'a [u8], b: &mut LoadBudget) -> Result { b.transaction(|b| Self::parse_inner(bytes, b)) } fn parse_inner(bytes: &'a [u8], b: &mut LoadBudget) -> Result { b.check(Q::PbxBytes, bytes.len() as u64)?; if bytes.len() < 32 { return Err(E::new(C::InvalidFormat, R::Truncated)); } b.work(32)?; if &bytes[..4] != b"PBX\0" { return Err(E::new(C::InvalidFormat, R::Magic)); } if bytes[4..6] != [0, 0] { return Err(E::new(C::UnsupportedFormat, R::Version)); } if bytes[6] != 0 { return Err(E::new(C::InvalidFormat, R::Endianness)); } if bytes[7] != 0 || bytes[12..32].iter().any(|&x| x != 0) { return Err(E::new(C::InvalidFormat, R::Reserved)); } let count = u32::from_le_bytes(bytes[8..12].try_into().unwrap()) as usize; let directory_end = count.checked_mul(12).and_then(|n| n.checked_add(32)).ok_or_else(overflow)?; if directory_end > bytes.len() { return Err(E::new(C::InvalidFormat, R::Truncated)); } let mut result = Self { sections: [None; 9] }; for i in 0..count { b.work(13)?; let pos = 32 + i * 12; let kind = u32::from_le_bytes(bytes[pos..pos + 4].try_into().unwrap()); if kind > 8 { return Err(E::new(C::UnsupportedFormat, R::SectionKind).at(kind, pos)); } if result.sections[kind as usize].is_some() { return Err(E::new(C::InvalidFormat, R::DuplicateSection).at(kind, pos)); } let start = u32::from_le_bytes(bytes[pos + 4..pos + 8].try_into().unwrap()) as usize; let len = u32::from_le_bytes(bytes[pos + 8..pos + 12].try_into().unwrap()) as usize; let end = start.checked_add(len).ok_or_else(overflow)?; if end > bytes.len() { return Err(E::new(C::InvalidFormat, R::Truncated).at(kind, start)); } if start < directory_end { return Err(E::new(C::InvalidFormat, R::Overlap).at(kind, start)); } if kind == 2 { b.check(Q::CodeBytes, len as u64)?; } for other in result.sections.iter().flatten() { b.work(1)?; if len > 0 && !other.bytes.is_empty() && start < other.offset + other.bytes.len() && other.offset < end { return Err(E::new(C::InvalidFormat, R::Overlap).at(kind, start)); } } result.sections[kind as usize] = Some(Section { kind, offset: start, bytes: &bytes[start..end] }); } for kind in [0, 1, 2, 4, 5, 6, 7, 8] { if result.sections[kind].is_none() { return Err(E::new(C::InvalidFormat, R::MissingSection).at(kind as u32, 8)); } } Ok(result) } /// Decode and resolve Registry metadata only. This is not an executable loader. pub fn resolve_registry(&self, b: &mut LoadBudget) -> Result { b.transaction(|b| { let resources = [ Q::TemporaryBytes, Q::Types, Q::Functions, Q::Implementations, Q::NestedRecords, Q::NameBytes, ]; let before = resources.map(|r| b.used(r)); let types = Reader::new(self.section(6).unwrap(), b).types()?; let mut functions = Reader::new(self.section(1).unwrap(), b).functions()?; Reader::new(self.section(8).unwrap(), b).captures(&mut functions)?; let implementations = Reader::new(self.section(7).unwrap(), b).implementations()?; // Ownership moves from parse scratch to retained Registry. No clone or // simultaneous second declaration allocation occurs at this boundary. for (r, used) in resources.into_iter().zip(before) { b.refund(r, b.used(r) - used); } Registry::resolve( RegistryDeclarations { types, functions, implementations }, self.section(2).unwrap().bytes.len(), b, ) }) } } fn overflow() -> E { E::new(C::ResourceLimit, R::Overflow) } struct Reader<'a, 'b> { section: Section<'a>, pos: usize, budget: &'b mut LoadBudget, } impl<'a, 'b> Reader<'a, 'b> { fn new(section: Section<'a>, budget: &'b mut LoadBudget) -> Self { Self { section, pos: 0, budget } } fn error(&self, code: C, reason: R) -> E { E::new(code, reason).at(self.section.kind, self.section.offset + self.pos) } fn take(&mut self, n: usize) -> Result<&'a [u8], E> { let end = self.pos.checked_add(n).ok_or_else(overflow)?; let value = self .section .bytes .get(self.pos..end) .ok_or_else(|| self.error(C::InvalidFormat, R::Truncated))?; self.budget.work(n)?; self.pos = end; Ok(value) } fn byte(&mut self) -> Result { Ok(self.take(1)?[0]) } fn u32(&mut self) -> Result { Ok(u32::from_le_bytes(self.take(4)?.try_into().unwrap())) } fn finish(&self) -> Result<(), E> { if self.pos == self.section.bytes.len() { Ok(()) } else { Err(self.error(C::InvalidFormat, R::TrailingBytes)) } } fn list(&mut self, resource: Q, min_bytes: usize) -> Result<(Vec, usize), E> { let count = self.u32()? as usize; self.budget.charge(resource, count as u64)?; let min = count.checked_mul(min_bytes).ok_or_else(overflow)?; if min > self.section.bytes.len() - self.pos { return Err(self.error(C::InvalidFormat, R::Truncated)); } Ok((self.budget.vector(count, Q::TemporaryBytes)?, count)) } fn name(&mut self) -> Result, E> { match self.byte()? { 0 => Ok(None), 1 => { let len = self.u32()? as usize; if len as u64 > self.budget.individual_name_limit() { return Err(E::resource( Q::NameBytes, len as u64, self.budget.individual_name_limit(), ) .at(self.section.kind, self.section.offset + self.pos)); } self.budget.charge(Q::NameBytes, len as u64)?; let bytes = self.take(len)?; self.budget.work(len)?; let value = std::str::from_utf8(bytes) .map_err(|_| self.error(C::InvalidFormat, R::Utf8))?; self.budget.work(len)?; let mut storage = self.budget.vector::(len, Q::TemporaryBytes)?; storage.extend_from_slice(value.as_bytes()); // UTF-8 was checked above; moving Vec into String performs no allocation. Ok(Some( String::from_utf8(storage) .map_err(|_| self.error(C::InvalidFormat, R::Utf8))?, )) } _ => Err(self.error(C::InvalidFormat, R::InvalidFlag)), } } fn named(&mut self) -> Result, E> { let (mut out, n) = self.list(Q::NestedRecords, 5)?; for i in 0..n { self.budget.work(1)?; let type_id = TypeId(self.u32()?); let name = self.name().map_err(|e| e.member(i as u32))?; out.push(NamedType { type_id, name }); } Ok(out) } fn signature(&mut self) -> Result { let parameters = self.named()?; let (mut results, n) = self.list(Q::NestedRecords, 4)?; for _ in 0..n { self.budget.work(1)?; results.push(TypeId(self.u32()?)); } Ok(Signature { parameters, results }) } fn types(mut self) -> Result, E> { let (mut out, n) = self.list(Q::Types, 6)?; for i in 0..n { self.budget.work(1)?; let record = (|| { let kind = self.byte()?; let name = self.name()?; let kind = match kind { 0 => TypeKind::Builtin(BuiltinId(self.u32()?)), 1 => TypeKind::Struct(self.named()?), 2 => TypeKind::Array(TypeId(self.u32()?)), 4 => TypeKind::Fn(self.signature()?), 3 => { let (mut methods, n) = self.list(Q::NestedRecords, 9)?; for j in 0..n { self.budget.work(1)?; let name = self.name()?; let signature = self.signature().map_err(|e| e.member(j as u32))?; methods.push(MethodDecl { name, signature }); } TypeKind::Trait(methods) } _ => return Err(self.error(C::UnsupportedFormat, R::Category)), }; Ok(TypeDecl { name, kind }) })() .map_err(|e: E| e.record(i as u32))?; out.push(record); } self.finish()?; Ok(out) } fn functions(mut self) -> Result, E> { let (mut out, n) = self.list(Q::Functions, 26)?; for i in 0..n { self.budget.work(1)?; let f = (|| { Ok(FunctionDecl { lifecycle_role: LifecycleRole::try_from(self.byte()?).map_err(|e| { e.at(1, self.section.offset + self.pos - 1).in_function(i as u32, None) })?, name: self.name()?, signature: self.signature()?, code_offset: self.u32()?, code_len: self.u32()?, local_slots: self.u32()?, max_stack_slots: self.u32()?, captures: Vec::new(), }) })() .map_err(|e: E| e.record(i as u32))?; out.push(f); } self.finish()?; Ok(out) } fn captures(mut self, functions: &mut [FunctionDecl]) -> Result<(), E> { let n = self.u32()? as usize; if n != functions.len() { let mut error = self.error(C::InvalidFormat, R::CaptureCount); error.requested = Some(n as u64); error.limit = Some(functions.len() as u64); return Err(error); } for (i, function) in functions.iter_mut().enumerate() { self.budget.work(1)?; let (mut captures, n) = self.list(Q::NestedRecords, 4).map_err(|e| e.record(i as u32))?; for _ in 0..n { self.budget.work(1)?; captures.push(TypeId(self.u32()?)); } function.captures = captures; } self.finish() } fn implementations(mut self) -> Result, E> { let (mut out, n) = self.list(Q::Implementations, 12)?; for i in 0..n { self.budget.work(1)?; let imp = (|| { let owner = TypeId(self.u32()?); let trait_id = TypeId(self.u32()?); let (mut methods, n) = self.list(Q::NestedRecords, 4)?; for _ in 0..n { self.budget.work(1)?; methods.push(FunctionId(self.u32()?)); } Ok(ImplementationDecl { owner, trait_id, methods }) })() .map_err(|e: E| e.record(i as u32))?; out.push(imp); } self.finish()?; Ok(out) } } /// Raw section input for a v0 envelope writer. Non-Registry section bytes must /// come from their own validated writers; this API never invents defaults. #[derive(Clone, Copy)] pub struct SectionData<'a> { pub kind: u32, pub bytes: &'a [u8], } /// Assemble strict v0 sections. The output buffer is charged to temporary load storage. pub fn encode_envelope(sections: &[SectionData<'_>], b: &mut LoadBudget) -> Result, E> { b.transaction(|b| { let mut by_kind = [None; 9]; for section in sections { b.work(1)?; if section.kind > 8 { return Err(E::new(C::UnsupportedFormat, R::SectionKind)); } if by_kind[section.kind as usize].replace(section.bytes).is_some() { return Err(E::new(C::InvalidFormat, R::DuplicateSection)); } } for k in [0, 1, 2, 4, 5, 6, 7, 8] { if by_kind[k].is_none() { return Err(E::new(C::InvalidFormat, R::MissingSection).at(k as u32, 8)); } } b.check(Q::CodeBytes, by_kind[2].unwrap().len() as u64)?; let count = sections.len(); let directory_end = 32 + 12 * count; let total = sections .iter() .try_fold(directory_end, |n, s| n.checked_add(s.bytes.len()).ok_or_else(overflow))?; b.check(Q::PbxBytes, total as u64)?; b.work(total)?; let mut out = b.vector(total, Q::TemporaryBytes)?; out.extend_from_slice(b"PBX\0"); out.extend_from_slice(&[0, 0, 0, 0]); out.extend_from_slice(&(count as u32).to_le_bytes()); out.extend_from_slice(&[0; 20]); let mut offset = directory_end; for (kind, data) in by_kind.iter().enumerate() { if let Some(data) = data { out.extend_from_slice(&(kind as u32).to_le_bytes()); out.extend_from_slice(&(offset as u32).to_le_bytes()); out.extend_from_slice(&(data.len() as u32).to_le_bytes()); offset += data.len(); } } for data in by_kind.into_iter().flatten() { out.extend_from_slice(data); } Ok(out) }) } #[derive(Debug)] pub struct RegistrySections { pub types: Vec, pub functions: Vec, pub implementations: Vec, pub captures: Vec, } /// Field-by-field serialization of already resolved Registry declarations. /// There is no source-language inference or unsupported-value-to-null fallback. pub fn encode_registry(registry: &Registry, b: &mut LoadBudget) -> Result { b.transaction(|b| { let d = registry.declarations(); let types = write_section(b, |w| { w.count(d.types.len())?; for t in &d.types { w.byte(match t.kind { TypeKind::Builtin(_) => 0, TypeKind::Struct(_) => 1, TypeKind::Array(_) => 2, TypeKind::Trait(_) => 3, TypeKind::Fn(_) => 4, })?; w.name(&t.name)?; match &t.kind { TypeKind::Builtin(id) => w.u32(id.0)?, TypeKind::Struct(fields) => w.named(fields)?, TypeKind::Array(id) => w.u32(id.0)?, TypeKind::Fn(s) => w.signature(s)?, TypeKind::Trait(methods) => { w.count(methods.len())?; for m in methods { w.name(&m.name)?; w.signature(&m.signature)?; } } } } Ok(()) })?; let functions = write_section(b, |w| { w.count(d.functions.len())?; for f in &d.functions { w.byte(f.lifecycle_role as u8)?; w.name(&f.name)?; w.signature(&f.signature)?; w.u32(f.code_offset)?; w.u32(f.code_len)?; w.u32(f.local_slots)?; w.u32(f.max_stack_slots)?; } Ok(()) })?; let implementations = write_section(b, |w| { w.count(d.implementations.len())?; for imp in &d.implementations { w.u32(imp.owner.0)?; w.u32(imp.trait_id.0)?; w.count(imp.methods.len())?; for id in &imp.methods { w.u32(id.0)?; } } Ok(()) })?; let captures = write_section(b, |w| { w.count(d.functions.len())?; for f in &d.functions { w.count(f.captures.len())?; for id in &f.captures { w.u32(id.0)?; } } Ok(()) })?; Ok(RegistrySections { types, functions, implementations, captures }) }) } // Count first so a malicious producer cannot trigger unbounded geometric growth. struct Writer<'a> { out: Option<&'a mut Vec>, len: usize, budget: &'a mut LoadBudget, } impl Writer<'_> { fn bytes(&mut self, bytes: &[u8]) -> Result<(), E> { self.budget.work(bytes.len())?; self.len = self.len.checked_add(bytes.len()).ok_or_else(overflow)?; self.budget.check(Q::PbxBytes, self.len as u64)?; if let Some(out) = self.out.as_mut() { out.extend_from_slice(bytes); } Ok(()) } fn byte(&mut self, n: u8) -> Result<(), E> { self.bytes(&[n]) } fn u32(&mut self, n: u32) -> Result<(), E> { self.bytes(&n.to_le_bytes()) } fn count(&mut self, n: usize) -> Result<(), E> { self.u32(u32::try_from(n).map_err(|_| overflow())?) } fn name(&mut self, n: &Option) -> Result<(), E> { match n { None => self.byte(0), Some(n) => { self.byte(1)?; self.count(n.len())?; self.bytes(n.as_bytes()) } } } fn named(&mut self, items: &[NamedType]) -> Result<(), E> { self.count(items.len())?; for p in items { self.u32(p.type_id.0)?; self.name(&p.name)?; } Ok(()) } fn signature(&mut self, s: &Signature) -> Result<(), E> { self.named(&s.parameters)?; self.count(s.results.len())?; for id in &s.results { self.u32(id.0)?; } Ok(()) } } fn write_section( b: &mut LoadBudget, write: impl Fn(&mut Writer<'_>) -> Result<(), E>, ) -> Result, E> { let mut counter = Writer { out: None, len: 0, budget: b }; write(&mut counter)?; let len = counter.len; let mut out = b.vector(len, Q::TemporaryBytes)?; write(&mut Writer { out: Some(&mut out), len: 0, budget: b })?; Ok(out) } mod payloads; pub use payloads::{OwnedPbx, ParsedPbx}; mod writer; pub use writer::PbxModule;