cdx-core

Core Rust library for reading, writing, and validating Codex Document Format (.cdx) files.

Overview

Codex is an open document format designed for:

• Semantic content - Structured content blocks, not just rendered output
• Verifiable integrity - Content-addressable hashing and digital signatures
• Machine readability - JSON-based format with well-defined schemas
• Modern security - Built-in support for signatures and encryption

This library provides the foundational capabilities for working with Codex documents in Rust, with support for WASM compilation.

Features

• Archive I/O - Read and write .cdx ZIP archives with proper structure validation
• Content Model - Full support for all 13 content block types (paragraphs, headings, lists, tables, code, math, images, etc.)
• Document Builder - Fluent API for creating documents programmatically
• Metadata - Dublin Core metadata support
• Presentation Layers - Paginated and continuous presentation types
• Digital Signatures - ECDSA P-256 (ES256), P-384 (ES384), Ed25519, RSA-PSS (PS256), and ML-DSA-65 signing and verification
• Encryption - AES-256-GCM and ChaCha20-Poly1305 content encryption
• Asset Management - Embed and manage images, fonts, and files
• Document Verification - Verify content hashes and document integrity
• Provenance - Merkle trees, block proofs, and timestamp support for content lineage
• Multiple Hash Algorithms - SHA-256 (default), SHA-3, and BLAKE3
• Zstandard Compression - Optional high-ratio compression support
• WASM Compatible - Compile to WebAssembly with the wasm feature

Installation

Add to your Cargo.toml:

[dependencies]
cdx-core = "0.4"

Feature Flags

Quick Start

Creating a Document

use cdx_core::{Document, Result};

fn main() -> Result<()> {
    let document = Document::builder()
        .title("My Document")
        .creator("Jane Doe")
        .add_heading(1, "Introduction")
        .add_paragraph("This is my first Codex document.")
        .add_heading(2, "Features")
        .add_paragraph("Codex provides semantic structure and verifiable integrity.")
        .build()?;

    // Compute the document ID
    let doc_id = document.compute_id()?;
    println!("Document ID: {doc_id}");

    // Save the document
    document.save("output.cdx")?;
    Ok(())
}

Opening and Verifying

use cdx_core::{Document, Result};

fn main() -> Result<()> {
    let document = Document::open("example.cdx")?;

    println!("Title: {:?}", document.dublin_core().terms.title);
    println!("State: {:?}", document.state());

    // Verify document integrity
    let report = document.verify()?;
    if report.is_valid() {
        println!("Document integrity verified!");
    }
    Ok(())
}

Digital Signatures

use cdx_core::{Document, Result};
use cdx_core::security::{EcdsaSigner, SignerInfo, Signer};

fn main() -> Result<()> {
    let document = Document::builder()
        .title("Signed Document")
        .creator("Signing Example")
        .add_paragraph("This document will be signed.")
        .build()?;

    let doc_id = document.compute_id()?;

    // Create a signer
    let signer_info = SignerInfo::new("Alice")
        .with_email("alice@example.com");
    let (signer, public_key) = EcdsaSigner::generate(signer_info)?;

    // Sign the document
    let signature = signer.sign(&doc_id)?;
    println!("Signed with algorithm: {}", signature.algorithm);
    Ok(())
}

Examples

Run the included examples:

# Create a document from scratch
cargo run --example create_document

# Extract content from a document
cargo run --example extract_content

# Sign a document (requires signatures feature)
cargo run --example sign_document --features signatures

# Open and verify a document
cargo run --example open_and_verify path/to/document.cdx

Specification Compliance

This library implements the Codex Document Format Specification v0.1.

Module Status

Development

See CONTRIBUTING.md for detailed development setup, building, testing, and contribution guidelines.

Quick Start

cargo build --all-features    # Build
cargo test --all-features     # Test
cargo clippy --all-features   # Lint

API Documentation

See the API documentation on docs.rs for detailed information about all types and functions.

Contributing

Contributions are welcome! Please read CONTRIBUTING.md before submitting PRs.

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.