Verifiable Trust Infrastructure

A Rust workspace implementing the two service backends of the First Person Network:

• Verifiable Trust Agent (VTA) — manages cryptographic keys, DIDs, and access-control policies for a single organisational identity.
• Verifiable Trust Community (VTC) — manages a community of members, their credentials, the policies that gate them, and the optional public website + admin UX.

Plus the CLIs, SDKs, and shared crates that compose them.

Specification

This workspace implements the Verifiable Trust Infrastructure (VTI) specification: https://trustoverip.github.io/dtgwg-vti-spec/ (source: trustoverip/dtgwg-vti-spec).

The specification is normative and this workspace is an implementation of it. Where the two disagree, the specification is what is correct and the code is what changes. Known differences are recorded in the specification's divergence register (Appendix F), with the requirement, the observed behaviour and the intended resolution.

Read it before changing the authority model, the client lifecycle, the operation surface, transports, sessions, credentials or the audit trail — see CONTRIBUTING.md.

Which service do you need?

flowchart TD
    start([What are you trying to do?])
    keys{Custody<br/>cryptographic<br/>keys + DIDs<br/>for an<br/>organisation?}
    members{Run a<br/>self-governing<br/>community of<br/>members?}
    vta[Start with <b>VTA</b><br/>docs/02-vta/]
    pair[Provision a VTA first,<br/>then a VTC on top of it]
    vtc[VTC docs<br/>docs/03-vtc/]

    start --> keys
    keys -- "yes, only keys" --> vta
    keys -- "yes, plus a community" --> pair
    keys -- "no, just a community" --> pair
    pair --> vtc

    classDef vta fill:#d4e6f9,stroke:#3a6fb0,stroke-width:1.5px,color:#08305f
    classDef vtc fill:#e9d7f7,stroke:#7e3fa6,stroke-width:1.5px,color:#3a0a5a
    class vta vta
    class vtc,pair vtc

Loading

A VTC always sits on top of a VTA: the VTA mints the VTC's keys at first boot via the vtc-host DID template (vtc setup drives the provision-integration flow against the VTA). One VTA can host many VTCs.

Workspace layout

The workspace has 47 crates. The spine most of them sit on, each arrow pointing from a dependency to the crate that depends on it:

graph LR
    vti-specs --> vta-sdk
    vta-sdk --> vti-common
    vti-common --> vta-subsystems["vta-* subsystem crates"]
    vta-subsystems --> vta-service
    vta-sdk --> vtc-client
    vtc-client --> vta-cli-common
    vti-common --> vtc-service
    vti-common --> vti-rooms
    vti-rooms --> vtc-service
    vti-rooms --> vta-service
    vta-cli-common --> vta-service
    vta-cli-common --> pnm-cli
    vta-cli-common --> cnm-cli
    vta-service --> vta-enclave["vta-enclave (TEE binary)"]

Loading

Dependencies flow strictly downward — no cycles. The complete map — every crate, its layer and its internal dependencies, generated from the manifests and checked in CI — and a one-line role for each crate are in CLAUDE.md § Workspace layout.

The crates an operator meets first:

Crate	Role
vti-common	Shared foundation: JWT auth, ACL, Store/KeyspaceHandle, error types, config, telemetry sink, audit envelopes.
vta-sdk	Public SDK: types, the Trust Task client over TSP / DIDComm / HTTPS, sealed-transfer, DID-template engine, attestation verification.
vta-cli-common	Shared CLI command implementations used by both pnm and cnm.
vta-service	VTA library + local/dev binary (vta): the Trust Task spine, operations, setup wizards.
vta-enclave	VTA binary for AWS Nitro Enclaves (TEE bootstrap, KMS, vsock-store, attestation). Linux-only.
vtc-service	VTC binary (vtc) — community lifecycle, policies, credentials, public website, admin UX.
pnm-cli	Personal Network Manager — single-VTA operator CLI (pnm).
cnm-cli	Community Network Manager — multi-community operator CLI (cnm).
vti-witness, vti-voting-service, room-host	Host services: witnesses, ballot boxes, data-room storage.

Quick start

Build the workspace:

cargo build --workspace --locked

Always pass --locked, and never install without it. Cargo.lock is this workspace's tested dependency set, and re-resolving it is not a harmless refresh — the AWS SDK subtree currently only compiles at the versions pinned there. aws-smithy-types 1.7.0 replaced Document::Object's payload in a minor release, which aws-smithy-json 0.63.0 (reached through the latest aws-config) does not compile against while still declaring it compatible. A build that re-resolves therefore fails with E0308/E0004 errors inside the registry source, naming files nobody here wrote.

cargo build and cargo test honour the lockfile on their own; --locked makes them say so and turns a silently stale lock into an error. cargo install is the trap: it ignores Cargo.lock by default, so a host install must be spelled

cargo install --locked --path vtc-service   # or any workspace binary

The Dockerfiles already pass --locked; a command typed by hand on a box does not.

Pick a path:

If you need…	Start at
A new VTA from scratch	docs/02-vta/cold-start.md
A VTA inside a Nitro Enclave	docs/02-vta/tee-architecture.md
A new VTC on an existing VTA	docs/03-vtc/getting-started.md
To integrate an app against a VTA	docs/02-vta/integration-guide.md
To understand the architecture	docs/01-concepts/overview.md

Documentation

The documentation tree is split by audience:

• docs/README.md — full index with topic search.
• docs/01-concepts/ — shared concepts that apply to both VTA and VTC (overview, architecture, security model).
• docs/02-vta/ — VTA operator + integrator documentation (cold-start, secret backends, TEE deployment, TSP, provision-integration, runtime service management, data rooms).
• docs/03-vtc/ — VTC operator + integrator documentation (getting started, community lifecycle, credentials, trust-registry, website, admin UX).
• docs/04-reference/ — reference material (BIP-32 paths, CLI conventions, workspace engineering notes).
• docs/05-design-notes/ — design history and implementation notes, each with a status line.
• docs/06-witness/ — the witness host service.
• docs/07-voting/ — community voting and the ballot-box service.
• First Person Project White Paper — the broader research context.

Repository structure

Path	Contents
vt*-*/, room-host/, pnm-cli/, cnm-cli/, didcomm-test/	The workspace's crates, one directory each (the full list and roles: CLAUDE.md).
vti-specs-*/trust-tasks/	The pinned Trust Task specification bundles the generated wire types are built from.
docs/	Documentation tree (this section).
trust-tasks/	Trust Task spec + schema files. Every wire op binds to a versioned task; the index.json manifest lists all of them.
deploy/nitro/	Nitro Enclave deployment scaffolding.
tests/	End-to-end workspace tests.
tasks/	Phase planning documents (internal).

Prerequisites

• Rust 1.95.0+ (edition 2024).
• For the default keyring secret backend: platform credential manager (macOS Keychain, Linux secret-service, Windows Credential Manager). Alternatives: AWS / GCP / Azure / HashiCorp Vault / KMS-TEE — see docs/02-vta/secret-backends.md.

Contributing

See CONTRIBUTING.md. Workspace-wide design principles live in CLAUDE.md; each crate has its own CLAUDE.md with crate-scoped guidance.

Every PR targets main; a fix a supported release also needs is backported from there by label. Changelogs are generated from conventional-commit PR titles — a PR adds no changelog file and edits no version.

Releases and branches

• RELEASES.md — named releases (Eucalyptus, Fig, …), cut every 4–6 weeks onto release/<name> branches and patched there; the nightly branch; the schedule; which releases are supported; backports.
• RELEASING.md — how crates are versioned and published to crates.io, from main and from release branches.

License

Apache-2.0. See LICENSE.