A Verifiable Trust Agent (VTA) is an always-on service that manages cryptographic keys, DIDs, and access-control policies for a Verifiable Trust Community. This repository contains the VTA service, a shared SDK, and the Community Network Manager (CNM) CLI.

• Overview
• Architecture
• Prerequisites
• Getting Started
• Example: Creating a New Application Context
• Additional Resources

The repository is a Rust workspace:

graph LR
    vti-common --> vta-sdk
    vti-common --> vta-service
    vti-common --> vtc-service
    vta-sdk --> vta-service
    vta-sdk --> vta-cli-common
    vta-service --> vta-enclave["vta-enclave (TEE binary)"]
    vta-cli-common --> pnm-cli
    vta-cli-common --> cnm-cli

The VTA is built on Axum with an embedded fjall key-value store for persistence. Cryptographic keys derive from a single BIP-39 mnemonic via BIP-32 Ed25519 derivation, and the master seed is stored in a pluggable backend (OS keyring by default; see Feature Flags). Authentication uses a DIDComm v2 challenge-response flow that issues short-lived EdDSA JWTs.

See docs/design.md for the full design document.

See Feature Flags for compile-time feature configuration.

• Rust 1.91.0+ (edition 2024)
• OS keyring support (when using the default keyring feature) -- the master seed is stored in your platform's credential manager:
  • macOS: Keychain
  • Linux: secret-service (e.g. GNOME Keyring)
  • Windows: Credential Manager

cargo build --workspace

The setup wizard bootstraps a new VTA instance. It is behind the setup feature flag:

cargo run --package vta-service --features setup -- setup

The wizard walks through these steps:

1. Server configuration -- host, port, log level, data directory.
2. Seed context -- creates the vta context (and mediator if DIDComm is enabled).
3. Mnemonic -- generate a new BIP-39 mnemonic or import an existing one. The derived seed is stored in the OS keyring.
4. JWT signing key -- a random Ed25519 key for signing access tokens.
5. Mediator DID -- creates a did:webvh with signing and key-agreement keys.
6. VTA DID -- creates a did:webvh with a DIDComm service endpoint pointing to the mediator.
7. Admin credential -- generates a did:key credential for the first administrator.
8. ACL bootstrap -- registers the admin in the access-control list.
9. Persist -- writes config.toml and flushes the store.

Save the mnemonic and admin credential. The mnemonic is the root of all key material; the admin credential is required to authenticate the CLI.

cargo run --package vta-service

The service listens on the host and port configured during setup (default 127.0.0.1:3000). Verify it is running:

# Using the Community Network Manager (multi-community):
cargo run --package cnm-cli -- health

# Or using the Personal Network Manager (single VTA):
cargo run --package pnm-cli -- health --url http://localhost:3000

Use the admin credential printed during setup:

# CNM -- multi-community, interactive setup
cargo run --package cnm-cli -- auth login <credential>

# PNM -- single VTA, non-interactive setup
cargo run --package pnm-cli -- setup --url http://localhost:3000 --credential <credential>

This imports the credential into the OS keyring, performs a DIDComm challenge-response handshake, and caches the resulting tokens. Subsequent commands authenticate automatically.

The contexts bootstrap command creates a context and generates credentials for its first admin in a single step:

cargo run --package cnm-cli -- contexts bootstrap \
  --id myapp \
  --name "My Application" \
  --admin-label "MyApp Admin"

This outputs a credential string. Give it to the context administrator so they can authenticate:

cargo run --package cnm-cli -- auth login <context-admin-credential>

Follow-up commands the context admin can now run:

# List all contexts visible to this credential
cargo run --package cnm-cli -- contexts list

# Create an Ed25519 signing key in the new context
cargo run --package cnm-cli -- keys create --key-type ed25519 --context-id myapp --label "Signing Key"

# List keys
cargo run --package cnm-cli -- keys list

See PNM CLI and CNM CLI for command references.

• Design Document -- architecture, API, and workspace structure
• Security Architecture -- defense-in-depth model and threat model
• TEE Enclave Security -- Nitro Enclave KMS bootstrap and encrypted storage design
• Cold-Start Guide -- bootstrapping a VTA + WebVH + mediator from scratch
• Integration Guide -- integrating a 3rd-party application with the VTA
• DIDComm Protocol -- message types, schemas, and authorization
• BIP-32 Path Specification -- hierarchical key derivation paths
• Feature Flags -- Cargo feature flags and deployment profiles
• Adding a Front-End -- how to add a new VTA deployment binary
• Store Migration -- enum-to-trait migration path for storage backends
• First Person Project White Paper