canaad-core

Internal developer documentation for canaad-core v0.3.0 — the core library for AAD canonicalization per RFC 8785 (JCS).

---

Dependencies

Runtime

Dev-only

Note: The crate does not expose a test-helpers feature gate. Test utilities are internal to src/tests/. If downstream crates need shared fixtures, a test-helpers feature exporting builder helpers and known-answer vectors would be the idiomatic path — it does not exist yet.

---

Module map

canaad-core/src/
├── lib.rs                  # crate root, module declarations, public re-exports
├── api.rs                  # free-standing public functions: parse, validate, canonicalize, canonicalize_string
├── canon.rs                # RFC 8785 canonicalization: canonicalize_value, canonicalize_serializable, canonicalize_context
├── error.rs                # AadError enum, JsonType helper enum
├── context/
│   ├── mod.rs              # AadContext struct, Serialize impl, TryFrom<ParsedAad>, methods
│   ├── builder.rs          # AadContextBuilder with deferred validation
│   └── tests.rs            # unit tests for AadContext and builder
├── parse/
│   ├── mod.rs              # module root, re-exports parse_aad, CURRENT_VERSION, MAX_AAD_SIZE
│   ├── aad.rs              # parse_aad(): field extraction, version/field-name/type validation
│   └── scan.rs             # single-pass serde_json visitor for duplicate-key detection
├── types/
│   ├── mod.rs              # module root, re-exports, integration tests
│   ├── safe_int.rs         # SafeInt newtype (0..2^53-1), TryFrom impls, Serialize/Deserialize
│   ├── string_types.rs     # Tenant (1-256 B), Resource (1-1024 B), Purpose (1+ B) newtypes
│   ├── field_key.rs        # FieldKey newtype ([a-z_]+), RESERVED_KEYS, extension key validation
│   └── extension.rs        # ExtensionValue enum (String | Integer), Extensions type alias
└── tests/
    ├── mod.rs              # test module root
    └── test_vectors/
        ├── mod.rs          # sub-module declarations
        ├── section_10.rs   # spec §10 known-answer vectors (§10.1–10.5)
        ├── negative.rs     # rejection / error-case inputs
        └── edge_cases.rs   # boundary and special-character tests

---

Constants

All four are re-exported from the crate root via lib.rs.

---

AadError variants

Defined in error.rs. Every variant carries structured fields for programmatic matching.

ReservedKeyAsExtension vs InvalidExtensionKeyFormat (0.2.2 fix)

Prior to 0.2.2, with_extension called validate_as_extension() before is_reserved(). Reserved keys like "v" or "ts" would fail the x_<app>_<field> pattern check first, returning InvalidExtensionKeyFormat instead of the semantically correct ReservedKeyAsExtension.

The fix reordered the checks: is_reserved() is now evaluated first. The test test_with_extension_reserved_keys_return_correct_error in context/tests.rs guards this invariant for all five reserved keys.

---

AadContext / AadContextBuilder

AadContext

Fully validated, immutable AAD object. Three construction paths:

1. AadContext::new(tenant, resource, purpose) — validates required fields immediately, returns Result<Self, AadError>
2. AadContext::builder() — returns an AadContextBuilder for incremental construction
3. parse(json) / validate(json) — parse from JSON string, returns Result<AadContext, AadError>

Chaining methods on AadContext

All consume and return self (builder-style chaining on an already-valid context):

AadContextBuilder

All setters store raw values with no validation. Validation fires entirely within .build().

build() checks required fields are present, then delegates to AadContext::new() and the with_* methods, surfacing the first error encountered.

Field constraints

Serialization

AadContext implements Serialize manually to emit keys in strict lexicographic order: purpose, resource, tenant, ts (if present), v, then x_* extensions (already sorted via BTreeMap). This matches RFC 8785 requirements and is guarded by test_serialize_key_order.

---

Public functions

All re-exported from the crate root.

parse(json: &str) -> Result<AadContext, AadError>

Parses a JSON string through the duplicate-key scanner, extracts and validates all fields, returns a fully validated AadContext.

validate(json: &str) -> Result<AadContext, AadError>

Semantic alias for parse(). Same implementation, same return type. Use validate at call sites where you only care whether input is valid and want that intent explicit. Documented as an alias since 0.2.3.

canonicalize(json: &str) -> Result<Vec<u8>, AadError>

Parses, validates, then returns the RFC 8785 canonical byte form. Errors on invalid JSON, constraint violations, or output > 16 KiB.

canonicalize_string(json: &str) -> Result<String, AadError>

Same as canonicalize but returns a UTF-8 String. Additional error if canonical bytes are not valid UTF-8.

---

Duplicate-key detection

Defined in parse/scan.rs.

Problem

serde_json silently drops duplicate keys, keeping only the last value. The AAD spec requires duplicate keys to be rejected.

Solution

A single-pass custom serde Visitor (DupCheckVisitor) that:

1. Deserializes the JSON stream into a serde_json::Value as normal
2. Maintains a HashSet<String> per object level
3. On each key, checks seen.insert(key) — if it returns false, emits a custom error with the sentinel prefix "duplicate key: "
4. Recurses into nested values via DupCheckSeed to catch duplicates at any depth

The into_aad_error function strips the at line N column M suffix that serde_json appends to custom errors, then pattern-matches the sentinel prefix to produce AadError::DuplicateKey.

This replaced a prior implementation (pre-0.2.1) that allocated a Vec<char> and traversed the input twice.

---

test-helpers feature

The crate does not define a test-helpers feature in Cargo.toml. All test utilities are internal to src/tests/. If a test-helpers feature is added in the future, the expected pattern would be:

# In consuming crate's Cargo.toml
[dev-dependencies]
canaad-core = { version = "0.3", features = ["test-helpers"] }

Candidate exports: builder presets for common test contexts, known-answer canonical strings, and SHA-256 digests from the §10 vectors.

---

Test vectors

Located at src/tests/test_vectors/. Split from a single 448-line file in 0.3.0.

section_10.rs — spec §10 known-answer vectors

Covers spec sections 10.1 through 10.5, each tested via both JSON parse and builder construction:

negative.rs — rejection tests

Inputs that must fail validation. Covers:

• Integer above MAX_SAFE_INTEGER, negative integer
• Empty tenant, NUL byte in tenant
• Unknown field, missing required field
• Duplicate key
• Invalid extension keys (single underscore, empty app, empty field)
• Unsupported version (0, 2)
• Wrong field types (v as string, tenant as number, ts as string)
• Invalid JSON syntax, non-object root

edge_cases.rs — boundary tests

Covers:

• Integer extension values, multiple extensions, multi-underscore field segments
• Tenant and resource at exact max length and one byte over
• Whitespace handling in input (canonical output must be whitespace-free)
• Special characters in string values (slashes, backslashes, tabs)
• Empty resource and empty purpose rejection