canaad

Deterministic AAD for AEAD. Build it, canonicalize it, get the same bytes everywhere.

Implements RFC 8785 (JSON Canonicalization Scheme) for Additional Authenticated Data contexts. Three crates, one spec.

Rust

[dependencies]
canaad-core = "0.3"

use canaad_core::{AadContext, canonicalize};

let json = r#"{"v":1,"tenant":"acme","resource":"/doc/123","purpose":"encrypt"}"#;
let canonical = canonicalize(json)?;

// or build it
let ctx = AadContext::new("acme", "/doc/123", "encrypt")?
    .with_timestamp(1700000000)?;
let bytes = ctx.canonicalize()?;

CLI

cargo install canaad-cli

echo '{"v":1,"tenant":"acme","resource":"/doc/123","purpose":"encrypt"}' | canaad canonicalize
canaad canonicalize -f input.json --to-file output.bin
canaad validate -f input.json
canaad validate -f input.json --quiet   # exit code only
canaad hash -f input.json -o hex

JavaScript

versioning: @gnufoo/canaad (npm) and the rust crates are versioned independently — npm at 0.5.x, rust at 0.3.x.

npm install @gnufoo/canaad@^0.5

import { canonicalize, validate, hash, AadBuilder } from '@gnufoo/canaad';

const canonical = canonicalize('{"v":1,"tenant":"acme","resource":"/doc/123","purpose":"encrypt"}');

const aad = new AadBuilder()
    .tenant("acme")
    .resource("/doc/123")
    .purpose("encrypt")
    .timestamp(1700000000)
    .build();

Numbers only — no BigInt. Integers validated at build(): NaN, Infinity, negative, and fractional values are rejected.

The spec

See the AAD specification for field constraints, extension patterns, and test vectors.

At decryption boundaries, wrap errors into a single opaque failure. Don't leak AadError variants to callers who don't own the input — that's an oracle. See architecture.md Section 9.

License

MIT OR Apache-2.0