vcon 0.4.0

A library for vCons. It reads and checks a vCon (form, compression, uuid, critical extensions) and writes one, unsigned, gzipped, signed or encrypted.
Documentation

vcon

A Rust library for vCons, the IETF conversation-record format.

It reads and checks a vCon: which of the three forms it is in (unsigned, signed or encrypted), whether it is gzipped, its uuid, and whether it needs extensions the caller does not support. If the vCon is refused, it says why. Reading does no I/O and returns no bytes, so the caller can keep the body exactly as received.

It also writes vCons, in vcon::write: an object model of the vCon core draft, written unsigned, gzipped, signed (a JWS) or encrypted (a JWE). The cryptography is the caller's, through the Signer, ContentEncrypter and KeyEncrypter traits. What the draft does not allow is refused, with the JSON path at fault, and read::inspect reads every output back. The examples are in the vcon::write documentation.

read::fields reads the members a Parquet export copies into clear columns: created_at, updated_at, subject, each party's tel, mailto and name, and the number of dialogs.

Status: 0.4.0 released, not yet for production. The API may change in any release before 1.0.

vcon-server uses this crate to check every vCon it receives.

Example

use std::collections::BTreeSet;

use vcon::Form;
use vcon::read::{Limits, Rejection, inspect};

// Gzip inflation in one body may produce at most this many bytes.
let limits = Limits::new(1 << 20);
// The extensions this caller supports in `critical`: none.
let supported = BTreeSet::new();

let body = br#"{
  "uuid": "01a07da8-c2bb-83e5-b9a2-279e0d16bc46",
  "created_at": "2026-10-23T00:00:00Z",
  "parties": []
}"#;
let found = inspect(body, Some("application/vcon+json"), &limits, &supported)
    .expect("the body is a vCon");
assert_eq!(found.form, Form::Unsigned);
assert!(!found.gzip);
assert_eq!(found.uuid.to_string(), "01a07da8-c2bb-83e5-b9a2-279e0d16bc46");

// A vCon that needs an extension the caller does not support is refused,
// with the names it lists.
let needs = br#"{
  "uuid": "01a07da8-c2bb-83e5-b9a2-279e0d16bc46",
  "created_at": "2026-10-23T00:00:00Z",
  "critical": ["example-extension"]
}"#;
assert_eq!(
    inspect(needs, None, &limits, &supported),
    Err(Rejection::UnsupportedCritical(vec!["example-extension".to_string()]))
);

// A body that is not a vCon is refused too.
assert_eq!(inspect(b"[]", None, &limits, &supported), Err(Rejection::NotJson));

What it checks

  • The body is gzip when its media type is application/vcon+gzip or it starts with the gzip magic number; inflation is bounded by read::Limits, and every gzipped layer inside a signed vCon shares the same bound.
  • The body is exactly one JSON object, no object in it repeats a member name, and no JSON text read has more than read::MAX_JSON_DEPTH (64) arrays and objects open at once.
  • The form, told from the members present: payload and signatures for a signed vCon (a JWS), ciphertext and recipients for an encrypted one (a JWE), otherwise the members of an unsigned vCon.
  • The uuid, in RFC 9562 text form: from the vCon itself, from the innermost signed payload, or from the unprotected header of an encrypted vCon. A uuid in a JWS header must match the signed vCon's. Nested signed layers are read in a loop, at most read::MAX_SIGNED_LAYERS (64) of them; deeper nesting is read::Rejection::TooDeep.
  • created_at is present.
  • critical (and must_support, its earlier name) lists only extensions the caller supports. An encrypted vCon's critical cannot be read and is not checked.

It does not verify signatures or decrypt.

Links

License

Licensed under either of the Apache License, Version 2.0 or the MIT License, at your option.