pask-wire 0.2.0

SCITT-style COSE receipt library for Physical-Site Engagement Receipts: supplied-key production and verification for the wilder.pser/0.5, 0.6 and 0.7 profiles, not complete conformance
Documentation
// SPDX-License-Identifier: Apache-2.0
// Copyright (c) 2026 Wilder Management Inc. (d/b/a Wilder Robotics) <rob@wilder-robotics.com>
// pask-wire is licensed Apache-2.0. No commercial agreement is required to use,
// modify or redistribute it; see LICENSING.md in the workspace root.

//! The canonical example instance carried by the profile document.
//!
//! The example embedded in the Internet-Draft is emitted from this function,
//! never typed by hand. A test asserts the two are byte-identical, so a change
//! to the wire format that is not reflected in the document fails CI rather
//! than shipping.
//!
//! This exists because the `-00` revision embedded a hand-written figure that
//! used unquoted placeholders (`"sizeBytes": <int>`). It was a schema template
//! presented in a JSON code block, and it was never parseable JSON, so nothing
//! in the build could have caught the three attestation members that had
//! drifted away from the implementation.

use alloc::string::{String, ToString};

use crate::{Error, Payload, Result, testvectors::MINIMAL_VALID_JCS};

/// Emits the canonical example instance, pretty-printed for the document.
///
/// The value is parsed and validated as a [`Payload`], re-serialized to its
/// JCS form, and then indented. Key order is JCS key order; indentation is two
/// spaces. The output is deterministic.
///
/// # Errors
///
/// Returns an error if the canonical test vector fails payload validation or
/// cannot be serialized — either of which is a defect in this crate.
pub fn canonical_example() -> Result<String> {
    let payload = Payload::from_json(MINIMAL_VALID_JCS.as_bytes())?;
    let canonical = payload.to_jcs()?;
    let value: serde_json::Value =
        serde_json::from_slice(&canonical).map_err(|error| Error::Json(error.to_string()))?;
    serde_json::to_string_pretty(&value).map_err(|error| Error::Json(error.to_string()))
}

/// Emits the canonical example instance for the 0.6 profile, pretty-printed.
///
/// Same construction as [`canonical_example`] but starts from the 0.5 minimal
/// vector with `spec` changed to `wilder.pser/0.6`. Uses
/// [`Payload::from_json_for_production`] so the `chain.hash` is recomputed
/// for the 0.6 JCS form rather than inherited from the 0.5 vector.
///
/// # Errors
///
/// Returns an error if the 0.6 payload fails validation (including the
/// timestamp containment check) or cannot be serialized.
pub fn canonical_example_06() -> Result<String> {
    let input_06 = MINIMAL_VALID_JCS.replace("wilder.pser/0.5", "wilder.pser/0.6");
    let payload = Payload::from_json_for_production(input_06.as_bytes())?;
    let canonical = payload.to_jcs()?;
    let value: serde_json::Value =
        serde_json::from_slice(&canonical).map_err(|error| Error::Json(error.to_string()))?;
    serde_json::to_string_pretty(&value).map_err(|error| Error::Json(error.to_string()))
}

/// Emits the proposed 0.7 null-content example, pretty-printed for the draft.
///
/// Starts from the unchanged 0.5 vector, changes only the profile and the new
/// explicit null member, and recomputes `chain.hash` through production logic.
/// This does not change either historical emitter or the CLI's default example.
///
/// # Errors
///
/// Returns an error if the source vector has an unexpected shape, or if the
/// generated payload fails production validation or serialization.
pub fn canonical_example_07() -> Result<String> {
    let mut input: serde_json::Value =
        serde_json::from_str(MINIMAL_VALID_JCS).map_err(|error| Error::Json(error.to_string()))?;
    input["spec"] = serde_json::Value::String(crate::SPEC_VERSION_07.to_string());
    let engagement = input
        .get_mut("engagement")
        .and_then(serde_json::Value::as_object_mut)
        .ok_or(Error::Validation(
            "canonical example lacks engagement object",
        ))?;
    engagement.insert("contentDigest".to_string(), serde_json::Value::Null);
    let input_bytes = serde_json::to_vec(&input).map_err(|error| Error::Json(error.to_string()))?;
    let payload = Payload::from_json_for_production(&input_bytes)?;
    let canonical = payload.to_jcs()?;
    let value: serde_json::Value =
        serde_json::from_slice(&canonical).map_err(|error| Error::Json(error.to_string()))?;
    serde_json::to_string_pretty(&value).map_err(|error| Error::Json(error.to_string()))
}