scursor

Secure cursor library with support for read and write transactions.

Panic-free design

scursor is designed to be strictly panic-free. This makes it suitable for parsing untrusted input in security-sensitive contexts, embedded systems with panic = "abort", or anywhere predictable failure handling is required.

The ReadCursor uses a consumption model where each read operation advances an internal position within a borrowed byte slice. The key insight is that all operations use inherently safe methods. For example, the core read_array routine is implemented as:

pubfnread_array<constN:usize>(&mutself) -> Result<[u8;N],ReadError>{let chunk = self.input.get(self.pos..).and_then(|s| s.first_chunk::<N>())// non-panicking bounds check.ok_or(ReadError)?;self.pos = self.pos.checked_add(N).ok_or(ReadError)?;// overflow-safe arithmeticOk(*chunk)}

Higher-level routines are composed from these primitives. There are no direct slice indexing operations (slice[i]), no .unwrap() or .expect() calls, and no arithmetic that could overflow. Every failure path returns a Result.

Safety by Composition

The core philosophy of scursor is that complexity should be built from verified, safe foundations. You can build complex, multi-step parsers that inherit the library's panic-free guarantees:

use scursor::{ReadCursor,ReadError};structPacket{id:u32,payload:[u8;4],checksum:u16,}fnparse_packet(cursor:&mutReadCursor) -> Result<Packet,ReadError>{// All of these calls are panic-free and bounds-checkedOk(Packet{id: cursor.read_u32_le()?,payload: cursor.read_array()?,checksum: cursor.read_u16_le()?,})}fnmain(){let data = [0x01,0x02,0x03,0x04,0xAA,0xBB,0xCC,0xDD,0xEE,0xFF];letmut cursor = ReadCursor::new(&data);// The transaction API rolls back the cursor if any part of the parser failslet packet = cursor.transaction(|cur| parse_packet(cur));}

Formal Verification

This library is formally verified to be panic-free using the Kani Rust Verifier. Kani uses bit-precise model checking to mathematically prove the absence of panics, out-of-bounds accesses, and overflows across all possible execution paths and inputs.

To run the mathematical proofs yourself:

1. Install Kani:

   cargo install --locked kani-verifier
   cargo kani setup

2. Run Verification:

   cargo kani

License

Licensed under the terms of the MIT or Apache v2 licenses at your choice.