OSDF

Open Secure Document Format · Cryptographic document packages with local, fail-closed verification.

OSDF Systems · Repository

License: PolyForm Noncommercial 1.0.0 today · Planned Apache/MIT open core

Platforms: Windows · macOS (Intel & Apple Silicon) · Linux · Platform guides →

---

Overview

OSDF is a data-centric document format: every byte in a package is declared, hashed, and signed. Verification runs locally in a memory-safe Rust core (CLI, library, or WASM) with explicit pass/fail reporting and no dependency on a remote service for integrity checks.

This repository is the public source-available alpha of the OSDF core: container format, verifier, transparency-log proofs, browser UI, and a gateway proof-of-concept.

The stable open core is planned for Apache-2.0 OR MIT licensing (see docs/licensing.md).

Property	Behavior
Integrity	SHA-256 per object, Merkle root, Ed25519 signatures, revision chain
Parser safety	Fail-closed ZIP walk; rejects traversal, undeclared objects, trailing bytes
Offline use	Embedded proofs and optional registry snapshots; live checks reported explicitly
Transparency	CT-style append-only ledger with inclusion proofs (Phase D)
Provenance	Structured verification summaries plus transform/inspection receipt schemas

_{Cryptographic chain-of-custody on a valid package}

_{Single-byte tamper detected in sub-millisecond verify paths (hardware-dependent)}

---

v0.2 direction

The next core milestone focuses on OSDF as a verifiable lifecycle substrate: object metadata, inspection results, transform receipts, derived capsules, and a self-hosted test ledger for online-enhanced verification. See docs/roadmap.md and specs/transformation-receipt.md.

---

Quick start

Requirements: Rust 1.93+ (rustup)

These steps are identical on every OS:

git clone https://github.com/osdf-systems/osdf.git
cd osdf
cargo build --release -p osdf-cli
cargo run --release -p osdf-cli -- demo safety

macOS / Linux (verify, install, browser demo)

./target/release/osdf verify fixtures/valid/valid-committed.osdf
chmod +x scripts/*.sh
./scripts/install-cli.sh          # optional: ~/.local/bin/osdf
./scripts/build-wasm.sh && ./scripts/serve-demo.sh   # gateway on :8081

Full walkthrough: docs/getting-started.md#macos

Windows (verify, install, browser demo)

.\target\release\osdf.exe verify fixtures\valid\valid-committed.osdf
.\scripts\install-cli.ps1
.\scripts\build-wasm.ps1
.\scripts\serve-demo.ps1

Full walkthrough: docs/getting-started.md#windows

Cross-platform install (any OS):

cargo install --path crates/osdf-cli --locked
osdf version

Releases: stable tags, prereleases, and nightly CI artifacts. See CHANGELOG.md.

---

Components

Crate / path	Role
crates/osdf-core	Parser, builder, Merkle manifest, signatures, ledger proofs
crates/osdf-cli	Command-line tool (verify, create, ledger, demo)
crates/osdf-wasm	Read-only WASM bindings for browser verification
web/	Static drag-and-drop verifier (local-only, no upload)
gateway/	Transparent Gateway PoC (MFA gate + structured document render)
fixtures/	Valid and adversarial test packages
specs/	Phase specifications and demonstration plan
scripts/	Platform helpers (index)

---

Browser verifier

The WASM verifier uses the same Rust library as the CLI. Files never leave the browser.

Step	macOS / Linux	Windows
Build	./scripts/build-wasm.sh	.\scripts\build-wasm.ps1
Serve	./scripts/serve-web.sh	.\scripts\serve-web.ps1

Open http://localhost:8080/. Details: docs/web-verifier.md.

Current scope: structural and cryptographic verification. Organizational credentials, revocation, timestamps, and authoring are out of scope for this alpha. Supply a ledger trust file for transparency proof checks (CLI --ledger-config or browser textarea).

---

Transparent Gateway (PoC)

Local MFA gate, verify, then render content/document.json as a readable form (tax demo fixtures).

Step	macOS / Linux	Windows
Build & serve	./scripts/build-wasm.sh && ./scripts/serve-demo.sh	.\scripts\build-wasm.ps1 then .\scripts\serve-demo.ps1
Narrated tour	./scripts/run-demo-package.sh	.\scripts\run-demo-package.ps1

Open http://localhost:8081/gateway/ · demo MFA code: 847291

Fixture	Rev	Description
fixtures/valid/taxes-template.osdf	1	Blank simplified tax form
fixtures/valid/Taxes.osdf	2	Demo-filled submission

Specification: specs/phase-c-gateway.md

---

CLI examples

# Create and sign
osdf create output/signed.osdf --title "Signed" --commit
osdf verify output/signed.osdf
osdf inspect output/signed.osdf --json

# New revision
osdf commit-revision output/signed.osdf --output output/signed-rev2.osdf

# Transparency ledger
osdf ledger init --store ledger.json --key ledger-key.json
osdf ledger append --store ledger.json --package output/signed.osdf
osdf ledger attach-proof --store ledger.json --key ledger-key.json \
  --package output/signed.osdf --output output/with-proof.osdf --trust-config trust.json
osdf verify output/with-proof.osdf --ledger-config trust.json

ledger-key.json and ledger.json are gitignored; generate locally. Do not commit operator keys.

Regenerate committed fixtures:

cargo test -p osdf-core --test generate_fixtures write_fixtures -- --ignored

Regenerate README demo images after verifier output changes:

osdf demo safety --write-readme-assets docs/assets

---

Architecture

Zero Trust document flow (ingress, verify layers, verdict, render, egress):

docs/architecture.md · Mermaid diagrams for the verification pipeline and profile placement.

---

Benchmarks

Reproducible performance measurements (Criterion + Hyperfine + scale_bench). Compare OSDF profiles and optional GPG wall-clock checks with honest scope notes for OpenTDF.

Tool	Command
Criterion	cargo bench -p osdf-core --bench verify_throughput
Throughput	cargo run --release -p osdf-core --example scale_bench -- --auto --objects 10 --bytes 1024
Hyperfine	./scripts/run-benchmarks.sh or .\scripts\run-benchmarks.ps1

Full methodology, Mermaid charts, and comparison scope: docs/benchmarks.md

---

Roadmap

Phase	Status	Deliverable
A	Complete	Core format, CLI, adversarial fixtures
B	Complete	WASM verifier and static web UI
C	PoC	Transparent Gateway and tax demo
D (M1)	Complete	Transparency log proofs in verifier
B.3	In progress	Latest-revision registry; freshness/revocation next
Demo package	Active	Scripted end-to-end gateway demo (plan)

Profile note: This build implements OSDF-Core with inline payload mode. Encrypted packages and live ledger services are planned for later phases.

---

Development

cargo build --release
cargo test --workspace

CI runs on Ubuntu and macOS. Contributing: CONTRIBUTING.md · Security: SECURITY.md

Implementer specifications live in specs/. Marketing and HTML documentation sites are maintained outside this repository.

---

License

Current: PolyForm Noncommercial License 1.0.0 (noncommercial use, research, education, and qualifying organizations).

Planned: The open core will relicense to Apache-2.0 OR MIT at stable v1.0 or within 24 months of going public, whichever comes first. Details: docs/licensing.md.

Commercial use or early licensing: dan@osdfsystems.com.