Crate sacp_cbor 

sacp-cbor

Strict deterministic CBOR validation and canonical encoding for the SACP-CBOR/1 profile used by the Synext Agent Control Protocol (SACP).

Design principles

• Canonical bytes are the value. Under SACP-CBOR/1, any valid encoding is canonical; therefore, semantic equality for opaque payloads reduces to byte equality.
• Hot-path validation is allocation-free. Use validate_canonical to validate a single CBOR data item with strict SACP-CBOR/1 rules.
• Encoding is streaming-first. Use Encoder or cbor_bytes! to emit canonical bytes without building an owned tree.

SACP-CBOR/1 profile (explicit)

Terminology note: “canonical” in this crate means canonical under the strict SACP-CBOR/1 profile defined here, not RFC 8949 canonical CBOR.

Allowed data model

• Single CBOR item only (no trailing bytes).
• Definite-length items only (no indefinite-length encodings).
• Map keys must be text strings (major 3) and valid UTF-8.
• Only tags 2 and 3 are allowed (bignums), and bignums must be canonical and outside the safe-int range.
• Integers (major 0/1) must be in the safe range [-(2^53-1), +(2^53-1)].
• Floats must be encoded as float64 (major 7, ai=27), forbid -0.0, and require the canonical NaN bit pattern.
• Only simple values false, true, and null are allowed.

Canonical encoding constraints

• Minimal integer/length encoding (no overlong forms).
• Map keys are strictly increasing by canonical CBOR key ordering: (encoded length, then lexicographic encoded bytes).

Feature flags

• std (default): implements std::error::Error for CborError.
• alloc (default): enables owned canonical bytes (CanonicalCbor), editing, and encoding helpers.
• sha2 (default): enables SHA-256 hashing helpers for canonical bytes.
• simdutf8: enables SIMD-accelerated UTF-8 validation where supported.
• unsafe: allows unchecked UTF-8 for canonical-trusted inputs.

Safety

This crate forbids unsafe code by default. Enabling the unsafe feature allows unchecked UTF-8 conversion on canonical-trusted inputs.

no_std

The crate is no_std compatible.

• Validation-only usage works without alloc.
• Owned APIs (canonical bytes + editor) require alloc and therefore an allocator provided by your environment.

Macros

cbor_bytesalloc

Construct canonical CBOR bytes with a JSON-like literal syntax.

path

Construct a path slice for query/edit operations.

Structs

ArrayDecoder

Array decoder guard that manages depth and length.

ArrayEncoderalloc

Builder for writing array elements into a canonical CBOR stream.

ArrayRef

A borrowed view into a canonical CBOR array.

ArraySpliceBuilderalloc

Builder for an array splice edit.

BigIntalloc

A tagged bignum integer (CBOR tag 2 or 3).

BigIntRef

A borrowed view of a CBOR bignum (tag 2 / tag 3).

CanonicalCboralloc

An owned canonical SACP-CBOR/1 data item.

CanonicalCborRef

A validated canonical SACP-CBOR/1 data item borrowed from an input buffer.

CborError

An SACP-CBOR/1 error with structured classification, a stable code, and a byte offset.

CborIntegeralloc

An integer value permitted by SACP-CBOR/1.

CborLimits

End-to-end limits used by SACP implementations.

CborValueRef

A borrowed view into a canonical CBOR message.

DeErrorserde

A serde decoding error that preserves an ErrorCode plus an input offset.

DecodeLimits

Decode-time resource limits for validation and decoding.

Decoder

Streaming decoder over canonical CBOR bytes.

EditOptionsalloc

Edit behavior options.

EditValuealloc

Encoded edit value used by the editor.

Editoralloc

Incremental editor for canonical CBOR bytes.

EncodedTextKey

A validated canonical CBOR-encoded text-string key.

Encoderalloc

Streaming encoder that writes canonical CBOR directly into a Vec<u8>.

F64Bits

A validated float64 bit-pattern suitable for SACP-CBOR/1 encoding.

MapDecoder

Map decoder guard that manages depth, length, and key ordering.

MapEncoderalloc

Builder for writing map entries into a canonical CBOR stream.

MapEntriesalloc

A CBOR map represented as ordered key/value entries.

MapRef

A borrowed view into a canonical CBOR map.

Enums

ArrayPosalloc

Array splice position.

CborIntegerRef

A borrowed view of an integer (safe or bignum).

CborKind

The CBOR data model supported by this crate.

DeleteModealloc

Mode for delete operations.

ErrorCode

A structured error code identifying the reason a CBOR item was rejected.

PathElem

A path element for navigating inside a CBOR value.

SetModealloc

Mode for map set operations.

Constants

MAX_SAFE_INTEGER

Maximum safe integer (2^53-1).

MAX_SAFE_INTEGER_I64

Maximum safe integer as i64 (2^53-1).

MIN_SAFE_INTEGER

Minimum safe integer (-(2^53-1)).

Traits

CborArrayElemalloc

Marker trait for values that can appear as CBOR array elements.

CborDecode

Decode a value from a streaming decoder.

CborEncodealloc

Encode a value into canonical CBOR bytes using the streaming encoder.

EditEncodealloc

Encodes a single canonical CBOR value into an Encoder.

Functions

decode

Validate canonical CBOR and decode a value using CborDecode.

decode_canonical

Decode a value from validated canonical bytes.

decode_canonical_ownedalloc

Decode a value from owned canonical bytes.

encode_intoalloc

Encode a value into an existing encoder, reusing its capacity.

encode_to_canonicalalloc

Encode a value into owned canonical CBOR bytes.

encode_to_vecalloc

Encode a value into canonical CBOR bytes.

from_canonical_bytesserde

Deserialize T from owned canonical bytes without re-checking canonical encodings.

from_canonical_bytes_refserde

Deserialize T from validated canonical bytes without re-checking canonical encodings.

from_sliceserde

Deserialize a Rust value from canonical SACP-CBOR/1 bytes.

from_slice_borrowedserde

Deserialize T with zero-copy borrows, validating during parsing.

to_vecserde

Serialize a Rust value into canonical SACP-CBOR/1 bytes.

to_vec_sorted_mapsserde

Serialize a Rust value into canonical SACP-CBOR/1 bytes while sorting map keys.

validate

Validate that bytes contain exactly one canonical SACP-CBOR/1 data item.

validate_canonical

Validate that bytes contain exactly one canonical SACP-CBOR/1 data item and return a wrapper.

Type Aliases

CheckedDecoder

Decoder that enforces canonical constraints while decoding.

TrustedDecoder

Decoder that trusts inputs are already canonical.

Derive Macros

CborDecode

Derive canonical CBOR decoding for structs and enums.

CborEncode

Derive canonical CBOR encoding for structs and enums.