vstore
Merkle DVCS, Parallel Change Sets, Verifiable CI & Zero-Knowledge Vault

vstore - Zero-Knowledge Content-Addressed Version Control, CI & Web Studio

vstore - Zero-Knowledge Content-Addressed Version Control

Overview

vstore is a self-contained, zero-external-dependency Content-Addressed Distributed Version Control System (DVCS) paired with vstore-ci (a deterministic topological build pipeline runner with linked artifact provenance) and vstore-web (an embedded Repository Studio, REST API, and client-side WebCrypto Zero-Knowledge Vault). Distributed as native single-file executables for Windows, Linux, and macOS, vstore protects source code, release provenance, and build artifacts across untrusted infrastructure without sacrificing developer speed.

ARCHITECTURE DIAGRAM

vstore Architecture Flow #1

Click any component node to view contextual details.

Interactive SVG • Click any node (5 components)
Component Developer CLI & Web Studio CliWeb Component Browser WebCrypto ZK Vault (/zk) BrowserZk Component Ed25519 Quorums & Merkle Log TrustEngine Component SHA-256 CAS, Gear-CDC & Packfiles CasStore Component Blind VSRP Sync & CI Runner SyncPipeline
Components:
Component
Developer CLI & Web Studio
Core DVCS Architecture
Component 1 of 5
Architectural Role & Purpose

Architectural component "Developer CLI & Web Studio" (CliWeb) in the vstore pipeline.

Contextual Description & System Interaction

Interactive diagram component parsed from Markdown specification.

Core Functionality & Security Mechanics
  • Participates in the CliWeb execution stage
  • Maintains cryptographic integrity and zero-knowledge boundaries
Component
Browser WebCrypto ZK Vault (/zk)
Core DVCS Architecture
Component 2 of 5
Architectural Role & Purpose

Architectural component "Browser WebCrypto ZK Vault (/zk)" (BrowserZk) in the vstore pipeline.

Contextual Description & System Interaction

Interactive diagram component parsed from Markdown specification.

Core Functionality & Security Mechanics
  • Participates in the BrowserZk execution stage
  • Maintains cryptographic integrity and zero-knowledge boundaries
Component
Ed25519 Quorums & Merkle Log
Core DVCS Architecture
Component 3 of 5
Architectural Role & Purpose

Architectural component "Ed25519 Quorums & Merkle Log" (TrustEngine) in the vstore pipeline.

Contextual Description & System Interaction

Interactive diagram component parsed from Markdown specification.

Core Functionality & Security Mechanics
  • Participates in the TrustEngine execution stage
  • Maintains cryptographic integrity and zero-knowledge boundaries
Component
SHA-256 CAS, Gear-CDC & Packfiles
Core DVCS Architecture
Component 4 of 5
Architectural Role & Purpose

Architectural component "SHA-256 CAS, Gear-CDC & Packfiles" (CasStore) in the vstore pipeline.

Contextual Description & System Interaction

Interactive diagram component parsed from Markdown specification.

Core Functionality & Security Mechanics
  • Participates in the CasStore execution stage
  • Maintains cryptographic integrity and zero-knowledge boundaries
Component
Blind VSRP Sync & CI Runner
Core DVCS Architecture
Component 5 of 5
Architectural Role & Purpose

Architectural component "Blind VSRP Sync & CI Runner" (SyncPipeline) in the vstore pipeline.

Contextual Description & System Interaction

Interactive diagram component parsed from Markdown specification.

Core Functionality & Security Mechanics
  • Participates in the SyncPipeline execution stage
  • Maintains cryptographic integrity and zero-knowledge boundaries

Core Capabilities

Audience Capability Operational Value
Software Developers Parallel Change Sets (vstore cs) & Clean Linear Merges Develop multiple independent features and hotfixes concurrently inside a single working directory without branch-switching churn or stash collisions, then land changes as clean single-parent commits carrying full checkpoint provenance.
Software Developers Repository Web Studio (vstore-web) & Split Diffs Browse commit graphs, side-by-side split diffs, line-level blame, sparse workspace views, and interactive staging/branching workflows locally at http://127.0.0.1:8080.
Security-Conscious Teams Zero-Knowledge Encryption & Ref Obfuscation Seal every blob, tree, commit, tag, chunk, changeset, sparse view, and CI artifact on the client using Argon2id (64 MiB) + AES-256-GCM (VSTOREN1), and scramble branch/tag names via HMAC-SHA256 (--obfuscate-refs).
Remote Reviewers Browser WebCrypto Zero-Knowledge Vault (/zk) Inspect encrypted commits, trees, and blobs directly inside a standard browser using window.crypto.subtle while the hosting server operates in --blind mode with zero keys in RAM.
Platform & Release Engineers Ed25519 Quorums, Transparency Log & Deterministic CI Enforce $M$-of-$N$ multi-signer branch/tag quorums, RFC 6962 dual-signed Merkle Transparency Logs, and vstore-ci topological build pipelines with signed linked artifacts (vstore://, https://, s3://, scp://).

Security & Cryptographic Guarantees

Security Pillar Enforcement Mechanism in vstore
Confidentiality Two-tier Argon2id Key-Encryption Key (KEK) wrapping a random 256-bit Data-Encryption Key (wrapped_dek), sealing every repository object with AES-256-GCM (AAD = object_id).
Metadata Privacy Optional HMAC-SHA256 reference obfuscation (refs/zk/<hmac>) plus encrypted ref_catalog so blind relay servers cannot observe branch, tag, or feature names.
Integrity & Non-Repudiation End-to-end SHA-256 Merkle DAG addressing, automatic Ed25519 (or hardware FIDO2/HSM) signatures on every commit and release tag, and $M$-of-$N$ quorum enforcement.
Rollback & Split-View Defense Append-only RFC 6962 Merkle Transparency Log (.vstore/transparency.log) recording dual-signed state roots verified automatically on every clone, fetch, pull, and push.
Storage Efficiency Gear rolling-hash Content-Defined Chunking (.chunked for files $> 64\text{ KiB}$), VSTZ compression, and indexed .vstpack / .vstidx binary packfiles.

Live Workspace Preview

Repository Overview & Hybrid Studio (/)

vstore Repository Dashboard and Hybrid Studio

Browser WebCrypto Zero-Knowledge Vault (/zk)

vstore Browser WebCrypto Zero-Knowledge Vault


End-User Documentation Suite

  1. Overview & Readme - Product overview, cryptographic summary, workspace previews, and quickstart commands.
  2. How-To Guide - Step-by-step operational recipes for encrypted repositories, parallel changesets, linear merges, blind remote sync, CI pipelines, and the vblog hands-on tutorial.
  3. End-User Guide - Complete day-to-day manual for the vstore CLI, branches, logical releases, parallel changesets, sparse views, vstore-web Studio, and the /zk Browser Vault.
  4. Administrator Guide - Production server deployment (systemd, reverse proxy TLS), Blind Zero-Knowledge relay hosting, RBAC (access.json), $M$-of-$N$ quorums, backups, fsck, packfile maintenance, and key rotation (rekey).
  5. Operations, Use Cases & Comparisons - vstore-ci build pipelines, multi-developer review workflows, air-gapped compliance operations, Git migration, and architectural comparison against Git, Jujutsu, Pijul, Fossil, and Mercurial.
  6. Configuration & CLI Reference - Exhaustive command, flag, environment variable, configuration schema, and HTTP/JSON REST API (/api/* and /api/v1/*) reference for vstore, vstore-web, and vstore-ci.
  7. Performance & Capacity Guide - Content-addressed storage throughput, Gear-CDC deduplication ratios, .vstpack 256-fanout index latency, AES-256-GCM overhead, and server sizing guidelines.
  8. Consolidated User Handbook - Single-file master handbook combining all End-User, How-To, Administrator, Operations, Reference, and Performance guides.

Quickstart

Use the prebuilt binaries for your platform (dist/bin/windows/, dist/bin/linux/, or dist/bin/macos/):

BASH
# 1. Verify installed CLI, CI runner, and Web Studio versions
vstore --version
vstore-ci --version
vstore-web --version

# 2. Initialize a signed, zero-knowledge encrypted repository
export VSTORE_PASSPHRASE="correct-horse-battery-staple"
vstore init --encrypt --obfuscate-refs --author "Ada Lovelace <ada@example.org>" ./my-service
cd ./my-service

# 3. Stage files and record an Ed25519-signed SHA-256 snapshot
echo '{"service":"payments","version":"1.0.0"}' > manifest.json
vstore add manifest.json
vstore snapshot -m "Initialize payments service manifest"
vstore verify HEAD

# 4. Launch the local Repository Web Studio on 127.0.0.1:8080
vstore-web --addr 127.0.0.1 --port 8080 --repo .

Open http://127.0.0.1:8080 in your browser to explore the Repository Dashboard, Commit DAG, Change Sets Studio, CI Provenance inspector, and /zk Browser WebCrypto Vault.

vstore - How-To Guide & Hands-On Tutorial

vstore - How-To Guide

Overview

This guide provides copy-pasteable step-by-step recipes for everyday developer and operator tasks across vstore, vstore-ci, and vstore-web, followed by a complete end-to-end walkthrough using the vblog sample web application.


Recipe 1: Initialize Plain vs. Zero-Knowledge Encrypted Repositories

Standard Signed Repository (Plaintext Storage, Ed25519 Signed)

BASH
mkdir ./api-gateway && cd ./api-gateway
vstore init --author "Ada Lovelace <ada@example.org>"

# Check repository status and generated Ed25519 identity
vstore status
vstore trust status

Zero-Knowledge Encrypted & Ref-Obfuscated Repository

Use --encrypt to seal every stored object with AES-256-GCM (VSTOREN1) and --obfuscate-refs to replace human-readable branch/tag filenames on disk with HMAC-SHA256 digests:

BASH
export VSTORE_PASSPHRASE="strong-team-vault-passphrase"
vstore init --encrypt --obfuscate-refs --author "Ada Lovelace <ada@example.org>" ./zk-vault-repo
cd ./zk-vault-repo

# Export the 64-character hex Vault Key for the /zk Browser WebCrypto Vault
vstore trust vault-key

Recipe 2: Configure .vstoreignore, Stage Selectively & Record Snapshots

Create a .vstoreignore file using standard glob (*, **) and negation (!) rules so runtime databases, build outputs, and temporary files never pollute snapshots:

GITIGNORE
# Ignore build outputs and runtime artifacts
dist/
target/
*.db
*.db-wal
*.db-shm
*.log
*.tmp

# Explicitly track versioned seed data and static web assets
!data/seed_posts.json
!src/assets/**

Stage specific paths, inspect staged vs. working-tree diffs, and record a signed commit:

BASH
vstore add .vstoreignore data/seed_posts.json src/assets/style.css
vstore diff --staged
vstore snapshot -m "Add ignore policy, starter seed data, and base stylesheet"

# Verify the Ed25519 cryptographic signature on HEAD
vstore verify HEAD

If you stage a file by mistake or want to revert a modified working file:

BASH
# Unstage a single path without modifying the file on disk
vstore reset src/assets/style.css

# Restore a working-tree file back to its HEAD contents
vstore restore src/assets/style.css

# Revert the last local branch or HEAD transition via the reflog
vstore reflog -n 5
vstore undo

Recipe 3: Work on Two Tasks Simultaneously with Parallel Change Sets (vstore cs)

Instead of juggling stash stacks or switching branches mid-thought, isolate concurrent workstreams inside named Change Sets in the same working folder:

BASH
# Create two independent Change Sets anchored at current HEAD
vstore cs create theme-and-search -m "Add dark-mode toggle and live post search"
vstore cs create xss-escape-fix   -m "Escape untrusted HTML in user comments"

# Edit files for both tasks in your working directory, then route each file to its Change Set
vstore cs add theme-and-search src/assets/style.css src/assets/app.js
vstore cs commit theme-and-search -m "Implement dark theme tokens and instant search filter"

vstore cs add xss-escape-fix src/sanitizer.ts
vstore cs commit xss-escape-fix -m "Escape angle brackets, quotes, and ampersands"

# Inspect open Change Sets, checkpoints, and combined diffs
vstore cs list
vstore cs diff xss-escape-fix

Temporarily shelve a Change Set if you want a clean working directory for testing, then unshelve or land it cleanly onto main:

BASH
# Shelve theme-and-search back to HEAD on disk without losing its checkpoints
vstore cs shelve theme-and-search

# Land the hotfix onto main as a clean single-parent linear commit with provenance headers
vstore cs merge xss-escape-fix -m "Land XSS comment sanitization hotfix"
vstore cs delete xss-escape-fix

# Re-apply theme-and-search to the working folder, then land it on main
vstore cs unshelve theme-and-search
vstore cs merge theme-and-search -m "Land dark-mode toggle and live search"
vstore cs delete theme-and-search

Recipe 4: Feature Branches, Clean Linear Merges & Conflict Resolution

vstore keeps main strictly linear by default (Option 1A): merging a feature branch performs a 3-way diff3 merge and writes a single-parent commit on main carrying changeset and changeset_tip provenance headers.

BASH
# Create and switch to a feature branch
vstore checkout -b feature/export-api
echo '{"export_version": 2}' > data/export_schema.json
vstore add data/export_schema.json
vstore snapshot -m "Add JSON export schema v2"

# Switch back to main and merge linearly
vstore checkout main
vstore merge feature/export-api -m "Integrate JSON export schema v2"

# Safely delete the merged branch (verified via ancestry or trunk provenance headers)
vstore branch -d feature/export-api

If both main and feature/export-api modified the same lines:

  1. vstore merge feature/export-api writes standard diff3 conflict markers (<<<<<<<, =======, >>>>>>>) and pauses the merge (vstore snapshot automatically blocks commits while conflict markers remain).
  2. Either edit the file to resolve the conflict and run vstore merge --continue, abort cleanly with vstore merge --abort, or explicitly resolve overlapping hunks in favor of the incoming branch (Option 1B) via vstore merge feature/export-api --authoritative.

Recipe 5: Enforce 2-of-2 Team Quorums & Co-Signed Releases

Require two distinct trusted Ed25519 signers before main or v* release tags can advance:

BASH
# Register a teammate's Ed25519 public key in the repository trust ring
vstore trust allow "Grace Hopper <grace@example.org>" 8f4a2d91c7e03b65a1d2e3f405162738495a6b7c8d9e0f1a2b3c4d5e6f708192
vstore trust policy strict

# Require 2 distinct signatures on main and production release tags
vstore trust quorum set "refs/heads/main" 2
vstore trust quorum set "refs/tags/v*" 2

# Reviewer attaches a detached co-signature attestation to HEAD or approves a Change Set
vstore trust attest HEAD
vstore cs approve release-prep

# Create and co-sign a production release tag
vstore tag -s -m "Production release v1.0.0" v1.0.0
vstore tag --cosign v1.0.0
vstore verify v1.0.0

Recipe 6: Sync with a Blind Zero-Knowledge Server (ws:// or https://)

Host a remote sync relay that stores ciphertext objects, verifies Ed25519 signatures and $M$-of-$N$ quorums, and appends RFC 6962 Merkle Transparency Log entries without ever possessing the repository passphrase or DEK:

BASH
# On the remote server: initialize or open in Blind Mode (--blind)
vstore serve --port 9418 --blind --require-auth

# On the developer workstation: register the remote and push encrypted packfiles
vstore remote add origin ws://127.0.0.1:9418
vstore push origin main
vstore push origin --tags

# On a teammate's workstation: clone with passphrase and audit the Merkle Transparency Log
export VSTORE_PASSPHRASE="strong-team-vault-passphrase"
vstore clone ws://127.0.0.1:9418 ./teammate-copy
cd ./teammate-copy
vstore trust verify-log

Recipe 7: Partial Checkouts with Sparse Workspace Views (vstore view)

For large monorepos or media-heavy repositories, check out only the subdirectories relevant to your role while fetching blobs by hash on demand:

BASH
# Define a frontend-only Workspace View
vstore view create frontend -i "src/assets/**,data/**,README.md" -e "*.bak" -m "Frontend assets and seed data"

# Activate the view (non-matching files are cleanly removed from the working directory)
vstore view use frontend
vstore view inspect frontend

# Hydrate any missing blobs from origin on demand, or return to the full repository tree
vstore view hydrate origin
vstore view clear

Recipe 8: Run Deterministic CI Pipelines & Hydrate Linked Artifacts (vstore-ci)

Execute topological build and verification waves, seal output artifacts into linked storage, and verify end-to-end build provenance:

BASH
# Inspect pipeline tasks and topological execution plan
vstore ci list
vstore ci graph

# Execute the pipeline in parallel across 4 workers and record a signed provenance receipt
vstore ci run --parallel -j 4

# Audit the recorded build run's Ed25519 signature, step hash chain, and artifact digests
vstore ci runs
vstore ci verify

# Pull and verify linked build artifacts directly onto a developer machine
vstore pull origin main --with-build latest

Hands-On Walkthrough: Versioning & Governing vblog End-to-End

The vblog sample application (examples/vblog/ or [vblog-sample-app.zip](/docs/vblog-sample-app.zip)) demonstrates every vstore workflow on a realistic full-stack developer blog featuring SQLite persistence, JSON seed/export (data/seed_posts.json), responsive CSS3 dark/light themes (src/assets/style.css), and vanilla JavaScript live filtering (src/assets/app.js):

ARCHITECTURE DIAGRAM

vstore Architecture Flow #1

Click any component node to view contextual details.

Interactive SVG • Click any node (4 components)
Component 1. Init Encrypted vblog Repo Step1 Component 3. Packfiles & Sparse Views Step3 Component 4. 2-of-2 Quorum & Signed v1.0.0 Step4 Component 5. Blind Sync & /zk WebCrypto Tour Step5
Components:
Component
1. Init Encrypted vblog Repo
Core DVCS Architecture
Component 1 of 4
Architectural Role & Purpose

Architectural component "1. Init Encrypted vblog Repo" (Step1) in the vstore pipeline.

Contextual Description & System Interaction

Interactive diagram component parsed from Markdown specification.

Core Functionality & Security Mechanics
  • Participates in the Step1 execution stage
  • Maintains cryptographic integrity and zero-knowledge boundaries
Component
3. Packfiles & Sparse Views
Core DVCS Architecture
Component 2 of 4
Architectural Role & Purpose

Architectural component "3. Packfiles & Sparse Views" (Step3) in the vstore pipeline.

Contextual Description & System Interaction

Interactive diagram component parsed from Markdown specification.

Core Functionality & Security Mechanics
  • Participates in the Step3 execution stage
  • Maintains cryptographic integrity and zero-knowledge boundaries
Component
4. 2-of-2 Quorum & Signed v1.0.0
Core DVCS Architecture
Component 3 of 4
Architectural Role & Purpose

Architectural component "4. 2-of-2 Quorum & Signed v1.0.0" (Step4) in the vstore pipeline.

Contextual Description & System Interaction

Interactive diagram component parsed from Markdown specification.

Core Functionality & Security Mechanics
  • Participates in the Step4 execution stage
  • Maintains cryptographic integrity and zero-knowledge boundaries
Component
5. Blind Sync & /zk WebCrypto Tour
Core DVCS Architecture
Component 4 of 4
Architectural Role & Purpose

Architectural component "5. Blind Sync & /zk WebCrypto Tour" (Step5) in the vstore pipeline.

Contextual Description & System Interaction

Interactive diagram component parsed from Markdown specification.

Core Functionality & Security Mechanics
  • Participates in the Step5 execution stage
  • Maintains cryptographic integrity and zero-knowledge boundaries
  1. Extract or copy vblog into a clean workspace and run vstore init --encrypt --obfuscate-refs --author "Ada Lovelace".
  2. Stage .vstoreignore, README.md, data/seed_posts.json, and src/, then create your baseline signed snapshot (vstore snapshot -m "Initial vblog application snapshot").
  3. Install a pre-commit quality hook (vstore hook install pre-commit -c "vstore status") and ergonomic shortcut (vstore alias set st "status").
  4. Develop two changes concurrently (vstore cs create theme-and-search and vstore cs create xss-escape-fix), commit checkpoints independently, and merge both cleanly onto main.
  5. Compact objects into an indexed .vstpack archive (vstore pack --packfile) and verify zero corruption via vstore status and /storage in vstore-web.
  6. Launch vstore-web --blind --port 8080, open http://127.0.0.1:8080/zk, paste the output of vstore trust vault-key, and browse decrypted vblog commits, directory trees, and files entirely inside your browser's WebCrypto sandbox.

vstore - End-User Guide

vstore - End-User Guide

Overview

This guide covers day-to-day software engineering workflows using the vstore command-line interface and the vstore-web Repository Studio, including staging, signed snapshots, trunk-based branching and logical releases, concurrent Parallel Change Sets, sparse Workspace Views, interactive Split Diffs and Line Blame, and client-side inspection inside the Browser WebCrypto Zero-Knowledge Vault (/zk).


1. Repository Lifecycle, Staging & Signed Snapshots

Every vstore repository stores its content-addressed object database, references, signing keys, and governance metadata inside a single .vstore/ directory at the root of your project.

Initializing or Cloning a Workspace

  • New Plaintext Repository: vstore init --author "Ada Lovelace <ada@example.org>" generates an Ed25519 signing keypair and sets the default branch to main.
  • New Encrypted Repository: vstore init --encrypt --obfuscate-refs --author "Ada Lovelace" derives an Argon2id Key-Encryption Key from your passphrase (VSTORE_PASSPHRASE or interactive prompt), wraps a random 256-bit Data-Encryption Key (wrapped_dek), seals all objects with AES-256-GCM, and hashes branch/tag filenames via HMAC-SHA256.
  • Cloning a Remote Repository: vstore clone ws://sync.example.org:9418 ./project (also supports wss://, http://, https://, and ssh://) downloads .vstpack streams, verifies the server's RFC 6962 Merkle Transparency Log, and unwraps wrapped_dek locally when encrypted.

Selective Staging, Status, Restore & Undo

Task Command Behavior
Inspect workspace state vstore status Displays active branch, remote ahead/behind counts (origin/main), active Workspace View, open Change Sets, staged index changes, unstaged edits, detected file renames, and untracked paths.
Stage files or folders vstore add src/ manifest.json Hashes and stages matching files into .vstore/index while respecting .vstoreignore glob and ! negation rules.
Record signed snapshot vstore snapshot -m "Message" Writes tree and commit objects, signs the canonical commit payload with your Ed25519 key, updates HEAD, and appends a local reflog entry.
Amend latest snapshot vstore snapshot --amend -m "New msg" Replaces the tip commit on the current branch with updated staged content or an updated commit message.
Unstage paths vstore reset src/config.toml Removes paths from .vstore/index (or clears the entire index when called without arguments) without altering working files.
Discard working edits vstore restore src/config.toml Restores files or directories from HEAD or --source <commit>.
Undo last ref transition vstore undo Reverts the most recent branch or HEAD movement recorded in .vstore/reflog.json.

2. Branches, Trunk-Based Linear Merges, Tags & Releases

Branch Management & Linear Provenance

vstore supports full feature branching (vstore branch, vstore checkout -b <branch>) while keeping trunk history clean and readable by default:

  • Option 1A - Clean Linear Merge (Default): vstore merge feature/search computes a 3-way diff3 merge against the lowest common ancestor and records a single-parent linear commit on the target branch carrying changeset and changeset_tip provenance headers. vstore branch -d feature/search recognizes both direct DAG ancestry and changeset_tip headers when verifying safe deletion.
  • Option 1B - Authoritative Merge (--authoritative / --theirs): vstore merge feature/search --authoritative resolves overlapping diff3 hunks deterministically in favor of the incoming branch while preserving non-conflicting trunk changes.

Commit History & Cryptographic Signatures (/commits)

vstore Commit DAG History and Ed25519 Signature Verification

Signed Tags & Logical Trunk Releases

  • Annotated Signed Tags: vstore tag -s -m "Release v1.0.0" v1.0.0 creates a signed tag object in the CAS; teammates can attach additional quorum signatures via vstore tag --cosign v1.0.0.
  • Logical Releases & Backports:
  • vstore release create 1.2.0 -m "Q4 Production Release" creates signed tag v1.2.0 (and optional release/1.2 maintenance branch with --branch).
  • vstore release list summarizes all semantic releases and their target commits.
  • vstore release backport 1.2.0 <commit_sha> cherry-picks a hotfix cleanly onto release/1.2.

3. Concurrent Development with Parallel Change Sets (vstore cs)

Parallel Change Sets allow a developer to work on two, three, or more independent tasks inside a single checkout without switching branches or stashing half-finished edits:

ARCHITECTURE DIAGRAM

vstore Architecture Flow #1

Click any component node to view contextual details.

Interactive SVG • Click any node (5 components)
Component Trunk HEAD Commit BaseHead Component Change Set: rbac-audit-fix CsBeta Component Signed Checkpoints + Reviewer Approval CheckpointsA Component Signed Checkpoints + Shelve/Unshelve CheckpointsB Component Clean Linear Trunk Commit (Provenance Linked) LinearTrunk
Components:
Component
Trunk HEAD Commit
Core DVCS Architecture
Component 1 of 5
Architectural Role & Purpose

Architectural component "Trunk HEAD Commit" (BaseHead) in the vstore pipeline.

Contextual Description & System Interaction

Interactive diagram component parsed from Markdown specification.

Core Functionality & Security Mechanics
  • Participates in the BaseHead execution stage
  • Maintains cryptographic integrity and zero-knowledge boundaries
Component
Change Set: rbac-audit-fix
Core DVCS Architecture
Component 2 of 5
Architectural Role & Purpose

Architectural component "Change Set: rbac-audit-fix" (CsBeta) in the vstore pipeline.

Contextual Description & System Interaction

Interactive diagram component parsed from Markdown specification.

Core Functionality & Security Mechanics
  • Participates in the CsBeta execution stage
  • Maintains cryptographic integrity and zero-knowledge boundaries
Component
Signed Checkpoints + Reviewer Approval
Core DVCS Architecture
Component 3 of 5
Architectural Role & Purpose

Architectural component "Signed Checkpoints + Reviewer Approval" (CheckpointsA) in the vstore pipeline.

Contextual Description & System Interaction

Interactive diagram component parsed from Markdown specification.

Core Functionality & Security Mechanics
  • Participates in the CheckpointsA execution stage
  • Maintains cryptographic integrity and zero-knowledge boundaries
Component
Signed Checkpoints + Shelve/Unshelve
Core DVCS Architecture
Component 4 of 5
Architectural Role & Purpose

Architectural component "Signed Checkpoints + Shelve/Unshelve" (CheckpointsB) in the vstore pipeline.

Contextual Description & System Interaction

Interactive diagram component parsed from Markdown specification.

Core Functionality & Security Mechanics
  • Participates in the CheckpointsB execution stage
  • Maintains cryptographic integrity and zero-knowledge boundaries
Component
Clean Linear Trunk Commit (Provenance Linked)
Core DVCS Architecture
Component 5 of 5
Architectural Role & Purpose

Architectural component "Clean Linear Trunk Commit (Provenance Linked)" (LinearTrunk) in the vstore pipeline.

Contextual Description & System Interaction

Interactive diagram component parsed from Markdown specification.

Core Functionality & Security Mechanics
  • Participates in the LinearTrunk execution stage
  • Maintains cryptographic integrity and zero-knowledge boundaries
  1. Create: vstore cs create zk-pack-stream -m "Optimize encrypted packfile streaming" anchors a named Change Set at HEAD.
  2. Stage & Checkpoint: vstore cs add zk-pack-stream src/streamer.rs and vstore cs commit zk-pack-stream -m "Add buffered chunk reader" record signed checkpoint commits under refs/changesets/zk-pack-stream without moving main. Single-author ownership is enforced automatically unless --allow-coauthor is passed.
  3. Shelve & Unshelve: vstore cs shelve zk-pack-stream temporarily restores touched files in your working folder back to HEAD; vstore cs unshelve zk-pack-stream puts them right back.
  4. Remote Collaboration & Approval: vstore cs push zk-pack-stream origin publishes encrypted checkpoints so teammates can pull (vstore cs pull zk-pack-stream origin), inspect diffs, and co-sign (vstore cs approve zk-pack-stream).
  5. Land on Trunk: vstore cs merge zk-pack-stream verifies any configured branch quorums and lands a single linear commit on main whose changeset_commits list links every checkpoint.

Parallel Change Sets Studio (/changesets)

vstore Parallel Change Sets Studio


4. Sparse Workspace Views (vstore view)

When working in large multi-project repositories or repositories containing large binary assets (automatically deduplicated via Gear rolling-hash .chunked manifests above 64 KiB), Workspace Views let you materialize only the paths you care about:

  • vstore view create backend -i "services/auth/**,shared/**,README.md" --ci-build latest
  • vstore view use backend filters the working tree immediately.
  • vstore view hydrate origin fetches any missing blobs by SHA-256 digest without leaking plaintext filenames to a blind server.
  • vstore view clear restores the complete repository tree.

5. Exploring & Operating in vstore-web Studio

Launch vstore-web locally against any repository:

BASH
vstore-web --addr 127.0.0.1 --port 8080 --repo .

The Studio organizes repository workflows into six primary navigation workspaces:

  1. Overview (/, /status, /views, /storage, /hooks): Live repository health metrics, interactive staging/snapshot controls, Sparse View toggles, .vstpack / fsck integrity runner, and hook/alias inspection.
  2. Files & Code (/tree, /blob, /blame, /grep, /diff, /archive): Directory tree browser, syntax-highlighted blob viewer with rendered Markdown preview, line-by-line authorship blame, full-repository regex/substring search, arbitrary two-ref Diff Explorer, and clean .zip export.
  3. History & Refs (/commits, /commit, /branches, /releases, /remotes, /reflog, /inspect): Paginated commit DAG with signature badges, Unified vs. Side-by-Side Split Diff commit detail view, detached attestation list, branch/tag/release management, remote sync controls, reflog undo, and raw CAS object inspector.
  4. Change Sets (/changesets, /changeset): Visual dashboard of open and merged Change Sets, checkpoint logs, combined diffs, shelve/unshelve actions, reviewer approval, and one-click linear landing.
  5. CI/CD (/ci): Build run history, step-by-step execution hashes, stage mount digests, linked artifact signatures, and redacted secret key metadata.
  6. Trust & ZK Vault (/trust, /access, /zk): Allowed Signers ring, key revocations, $M$-of-$N$ quorum rules, RFC 6962 Merkle Transparency Log audit report, branch RBAC table, and the Browser WebCrypto Vault.

Split Diff, Ed25519 Signature & Quorum Attestation View (/commit)

vstore Split Diff and Cryptographic Commit Attestation View


6. Using the Browser WebCrypto Zero-Knowledge Vault (/zk)

When vstore-web runs on an untrusted host with --blind (vstore-web --port 8080 --blind --repo ./repos/app), server-side plaintext routes lock down automatically and redirect to /zk:

  1. Run vstore trust vault-key on an authorized workstation (or use your repository passphrase when PBKDF2/WebCrypto unwrap is configured) to copy your 64-character hex Vault Key.
  2. Open /zk in any modern browser and paste the Vault Key into the Client-Side WebCrypto Unlock panel.
  3. Your browser imports the key into non-exportable CryptoKey memory via window.crypto.subtle.importKey, fetches encrypted VSTOREN1 envelopes from /api/zk/manifest and /api/zk/object, verifies AAD = object_id, decompresses VSTZ payloads, and renders decrypted branches, commit histories, trees, and file contents locally - transmitting zero key material over the network.

vstore - Administrator Guide

vstore - Administrator Guide

Overview

This guide covers production deployment, network transport hardening, Blind Zero-Knowledge Relay Mode, role-based branch access control (access.json), cryptographic trust governance (allowed_signers, revocations, $M$-of-$N$ quorums, hardware signers, Merkle Transparency Logs), storage compaction (.vstpack), integrity verification (fsck), backups, and key rotation (rekey).


1. Deployment Topologies

vstore separates remote synchronization (vstore serve) from web browsing and REST inspection (vstore-web), allowing administrators to deploy either or both with minimal attack surface:

Component Recommended Bind & Transport Key Custody Mode Primary Role
vstore serve --blind 127.0.0.1:9418 behind TLS reverse proxy, direct --tls-cert/--tls-key (wss://), or SSH --stdio (ssh://) Zero keys in RAM (--blind) Receives/serves encrypted .vstpack streams, enforces Ed25519 auth, RBAC, $M$-of-$N$ quorums, and appends Merkle Transparency Log entries.
vstore-web --blind 127.0.0.1:8080 behind Caddy/Nginx HTTPS Zero keys in RAM (--blind) Serves /zk Browser WebCrypto Vault, /trust Transparency Log inspector, /api/zk/*, and /api/health while blocking all server-side plaintext & /api/v1/* mutation routes.
vstore-web (Local Studio) 127.0.0.1:8080 (workstation loopback only) Unlocked locally Full developer UI and /api/v1/* Studio actions on trusted developer hardware.

2. Production Linux (systemd) & Reverse Proxy Setup

Dedicated System Account & Repository Directory

BASH
sudo useradd --system --home-dir ./data --create-home --shell /usr/sbin/nologin vstore
sudo install -m 0755 vstore ./vstore
sudo install -m 0755 vstore-web ./vstore-web
sudo install -m 0755 vstore-ci ./vstore-ci

sudo -u vstore mkdir -p ./data/repos/core-platform
sudo -u vstore ./vstore init --author "Platform Relay" ./data/repos/core-platform

systemd Service Units (Native TLS Blind Sync Relay + Read-Only Blind Web Vault)

Create /etc/systemd/system/vstore-serve.service (native TLS via --tls-cert / --tls-key; a reverse proxy is optional):

INI
[Unit]
Description=vstore Zero-Knowledge VSRP Sync Server
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=vstore
Group=vstore
WorkingDirectory=./data/repos/core-platform
ExecStart=./vstore serve --http --host 0.0.0.0 --port 9418 --blind --require-auth --tls-cert /etc/vstore/tls/fullchain.pem --tls-key /etc/vstore/tls/privkey.pem --log-format json
Restart=on-failure
RestartSec=3
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
PrivateTmp=true
ReadWritePaths=./data/repos/core-platform
ReadOnlyPaths=/etc/vstore

[Install]
WantedBy=multi-user.target

Create /etc/systemd/system/vstore-web.service (read-only by default; pass --enable-studio with VSTORE_WEB_TOKEN only if authenticated web mutations are required):

INI
[Unit]
Description=vstore Blind WebCrypto Vault & Audit Portal
After=network-online.target

[Service]
Type=simple
User=vstore
Group=vstore
WorkingDirectory=./data/repos/core-platform
ExecStart=./vstore-web --addr 0.0.0.0 --port 8443 --blind --repo ./data/repos/core-platform --tls-cert /etc/vstore/tls/fullchain.pem --tls-key /etc/vstore/tls/privkey.pem --log-format json
Restart=on-failure
RestartSec=3
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
PrivateTmp=true
ReadOnlyPaths=./data/repos/core-platform /etc/vstore

[Install]
WantedBy=multi-user.target

Optional Caddy TLS 1.3 Reverse Proxy Example

If you prefer terminating TLS at an edge proxy instead of using --tls-cert / --tls-key, bind vstore serve and vstore-web to 127.0.0.1 with --trust-proxy:

TEXT
vcs.example.org {
    encode zstd gzip

    handle /vstore/* {
        reverse_proxy 127.0.0.1:9418
    }

    handle {
        reverse_proxy 127.0.0.1:8080
    }
}

SSH Zero-Daemon Transport (--stdio)

For teams using SSH keys and authorized_keys bastion controls without opening additional TCP ports, vstore speaks the VSRP sync framing directly over SSH standard input/output:

BASH
# Client pushes directly over SSH; remote host invokes `vstore serve --stdio` automatically
vstore remote add origin ssh://vstore@vcs.example.org./data/repos/core-platform
vstore push origin main

3. Authentication, Branch RBAC (access.json) & Governance

Challenge-Response Client Authentication

When --require-auth (and optionally --authorized-keys <pub1,pub2>) is passed to vstore serve, every connecting client must sign a per-session random 32-byte server challenge using its Ed25519 private key before reading or pushing refs.

Granular Per-Branch RBAC (vstore access)

Administrators define branch-pattern permissions (read, write, admin, deny) in .vstore/access.json, evaluated with explicit deny precedence:

BASH
# Grant write access on feature/* to all authenticated developers
vstore access add -k "*" -b "refs/heads/feature/*" -p write -a "All Developers"

# Restrict main and release/* writes to Release Engineering leads
vstore access add -k 3b6a27bcceb6a42d62a3a8d02a6f0d73653215771de243a63ac048a18b59da29 \
  -b "refs/heads/main,refs/heads/release/*" -p admin -a "Release Lead"

# Audit active RBAC policy
vstore access list

Trust Ring, Hardware Signers, Revocations & $M$-of-$N$ Quorums

  1. Allowed Signers & Validity Windows:
BASH
   vstore trust allow "Security Reviewer <sec@example.org>" <pubkey_hex> --from 1735689600 --until 1767225600
   vstore trust policy strict
  1. External / Hardware Signer Integration (FIDO2 / YubiKey / Cloud KMS):
BASH
   vstore trust signer --provider external --command "custom-kms-sign --key prod-ed25519" --key-id <pubkey_hex>
  1. Signed Key Revocation:
BASH
   vstore trust revoke <compromised_pubkey_hex> -m "Workstation rotated 2026-11-14"

Revocations are Ed25519-signed records synchronized automatically via vstore trust sync, push, pull, and fetch.

  1. $M$-of-$N$ Multi-Party Quorums:
BASH
   vstore trust quorum set "refs/heads/main" 2
   vstore trust quorum set "refs/tags/v*" 2

Both local merges and remote vstore serve ref updates reject updates to matching patterns unless at least $M$ distinct non-revoked Allowed Signers have signed the commit/tag and its detached .vstore/attestations/<hash>.json records.


4. Storage Maintenance, Integrity (fsck), Backups & Key Rotation

Packfile Compaction & Garbage Collection

As repositories accumulate thousands of loose objects, bundle them into indexed .vstpack / .vstidx archives with 256-entry first-byte fanout tables for $O(\log N)$ binary-search reads and single-stream network transfers:

BASH
# Bundle loose objects into a binary .vstpack + .vstidx archive
vstore pack --packfile

# Prune unreachable objects older than 24 hours (86400s) and consolidate packfiles
vstore gc --grace 86400 --packfile

Full Cryptographic Repository Verification (fsck & verify-log)

Run periodic scheduled health checks on both server relays and CI agents:

BASH
# Run full 4-tier cryptographic object and packfile integrity check
vstore fsck

# Verify Merkle Transparency Log hash chain and dual signatures
vstore trust verify-log

# Verify HEAD and release tag signatures against Allowed Signers & Revocations
vstore verify HEAD
vstore verify v1.0.0

You can also inspect live object counts, packfile indexes, and run full fsck verification via GET /api/fsck or /storage in vstore-web.

Consistent Backups & Disaster Recovery

Because vstore writes objects immutably (atomic_write_bytes via fsync + temp-file rename) and serializes ref updates under .vstore/repo.lock, backing up .vstore/ is straightforward:

  1. For cold or snapshot backups: take an atomic ZFS/LVM/EBS filesystem snapshot of the repository directory, or run vstore clone / vstore fetch to a warm standby server.
  2. After restoring a backup, run vstore trust verify-log against developers' locally cached remote checkpoints (.vstore/remote_checkpoints.json) to confirm zero silent rollback occurred.
  3. For encrypted repositories, store the repository passphrase or wrapped recovery key in an offline enterprise secret vault; a --blind server backup contains only AES-256-GCM ciphertext and cannot be decrypted without the KEK/DEK.

vstore - Operations, Use Cases & DVCS Comparisons

vstore - Operations, Use Cases & DVCS Comparisons

Overview

This guide details operational playbooks for vstore-ci topological pipelines, linked artifact provenance (vstore://, https://, s3://, scp://), multi-developer Change Set code review, regulated/air-gapped release engineering, Git repository migration, and a comprehensive architectural comparison of vstore against Git, Jujutsu (jj), Pijul, Fossil, and Mercurial.


1. Deterministic Build Pipelines & Linked Provenance (vstore-ci)

Unlike external CI SaaS platforms that run opaque YAML scripts decoupled from version-control cryptography, vstore-ci executes declarative DAG tasks directly against the content-addressed repository state and binds every build step, inter-stage mount, and published binary artifact to an Ed25519-signed provenance receipt (.vstore/ci/runs/<run_id>.json).

CI Pipeline & Cryptographic Trust Audit (/ci)

vstore CI Pipeline Provenance and Merkle Trust Audit

Key Operational Properties of vstore-ci

  1. Topological Wave Execution (--parallel -j <N>): Tasks declare explicit dependencies (depends), timeouts (timeout_sec), optional OCI container sandboxes (docker, podman, nerdctl), and default-isolated network policies (isolated vs. enabled). Independent tasks within each wave execute concurrently.
  2. Zero-CAS-Bloat Stage & Cache Mounts: Intermediate compiler outputs pass between stages via hashed staging directories (input_Digest -> output_Digest) without bloating .vstore/objects/ with transient object files.
  3. Linked Artifact Storage with End-to-End Encryption: Final release binaries are signed with Ed25519, sealed with VSTOREN1 AES-256-GCM (aad = "ci_artifact:<sha256>") when the repository is encrypted, and published to configurable storage backends:
    • vstore:// (built-in .vstore/ci/artifacts/<sha256>, synced over VSRP)
    • ./artifacts/prod (shared NAS or air-gapped transfer volume)
    • https://artifacts.example.org/upload (HTTP PUT/GET object gateway)
    • s3://release-bucket/vstore-builds (S3-compatible object storage)
    • scp://ci@vault.example.org/srv/artifacts (SSH/SCP bastion storage)
  4. Encrypted Secret Redaction: Secrets stored via vstore ci secret set <KEY> <VALUE> are encrypted at rest in .vstore/ci/secrets.enc and automatically scrubbed from captured step logs before provenance receipts are written.
  5. Retention Without Provenance Loss (vstore ci prune): vstore ci prune --keep-last 5 --keep-tagged reclaims gigabytes of older binary artifacts while permanently preserving lightweight .vstore/ci/runs/*.json cryptographic receipts.
BASH
# Configure external S3 or HTTPS artifact storage and encrypted secrets
vstore ci storage set s3://prod-release-artifacts/payments
vstore ci secret set SIGNING_ENDPOINT "https://kms.internal.example.org"

# Trigger automated verification and release packaging
vstore ci run --parallel -j 4
vstore ci verify

# Hydrate verified release artifacts onto a target deployment host
vstore clone wss://vcs.example.org:9418 ./deploy-target --view runtime --with-build latest

2. Multi-Developer Change Set Code Review Playbook

Teams can collaborate on pre-merge changesets across a Blind Zero-Knowledge Relay without opening long-lived feature branches or exposing plaintext source code to the hosting server:

  1. Author Creates & Publishes Change Set:
BASH
   vstore cs create ledger-reconcile -m "Add idempotent settlement reconciliation"
   vstore cs add ledger-reconcile services/ledger/reconcile.go services/ledger/reconcile_test.go
   vstore cs commit ledger-reconcile -m "Implement double-entry invariant checks"
   vstore cs push ledger-reconcile origin
  1. Reviewer Pulls, Audits & Approves:
BASH
   vstore cs pull ledger-reconcile origin
   vstore cs diff ledger-reconcile
   vstore cs approve ledger-reconcile
   vstore cs push ledger-reconcile origin
  1. Maintainer Lands Clean Linear Commit Under Quorum:
BASH
   vstore cs pull ledger-reconcile origin
   vstore cs merge ledger-reconcile -m "Land idempotent settlement reconciliation"
   vstore push origin main

3. Air-Gapped, Regulated & Zero-Trust Cloud Workflows

Use Case A: Untrusted Public Cloud Hosting (Zero-Knowledge SaaS Relay)

  • Challenge: Engineering teams want low-latency cloud replication across continents without granting cloud administrators or subpoenaed storage providers read access to proprietary algorithms, security patches, or roadmap branch names.
  • Solution: Initialize with vstore init --encrypt --obfuscate-refs and run vstore serve --blind --require-auth + vstore-web --blind on cloud VMs. Cloud disks hold only VSTOREN1 ciphertexts and HMAC-SHA256 ref tokens, while developers inspect repositories locally or via /zk WebCrypto in the browser.

Use Case B: Air-Gapped Defense & Financial Release Promotion

  • Challenge: Moving verified source snapshots and compiled release binaries across an air gap while proving 2-of-2 human review, deterministic CI execution, and zero history tampering.
  • Solution: Bundle .vstpack archives, .vstore/transparency.log, .vstore/attestations/, and .vstore/ci/artifacts/ onto read-only transfer media. On the high-side network, run vstore trust verify-log, vstore verify v1.0.0, and vstore ci verify entirely offline with zero external dependencies.

4. Migrating from Git (import-git & archive)

vstore provides built-in topological Git import and clean archive export:

BASH
# Initialize a new encrypted vstore repository and import existing Git history + tags
export VSTORE_PASSPHRASE="enterprise-migration-passphrase"
vstore init --encrypt --author "Migration Bot <releng@example.org>" ./migrated-repo
cd ./migrated-repo
vstore import-git /path/to/legacy-git-repo --branch main

# Export any snapshot or tag as a clean .zip source bundle without .vstore metadata
vstore archive v1.0.0 -o ./release-v1.0.0-src.zip --prefix service-1.0.0

5. Architectural Comparison with Other Version Control Systems

Capability vstore Git Jujutsu (jj) Pijul Fossil Mercurial (hg)
Object Hash Algorithm SHA-256 (native everywhere) SHA-1 default (SHA-256 opt-in) SHA-256 / Git backend BLAKE3 SHA3-256 / SHA-1 SHA-1
Client-Side Zero-Knowledge Encryption Built-in (Argon2id + AES-256-GCM) External plugins (git-crypt, age) External via backend None built-in None built-in External extensions
Branch/Ref Name Obfuscation Built-in (HMAC-SHA256 refs/zk/) Not supported Not supported Not supported Not supported Not supported
Blind Zero-Knowledge Server & Browser WebCrypto UI Built-in (--blind + /zk Vault) Not supported Not supported Not supported Server sees plaintext SQLite Server sees plaintext revlogs
Concurrent Same-Tree Workstreams Parallel Change Sets (vstore cs) Requires worktrees or stash Anonymous/named changes Commutative patches Branches / stash Shelve / MQ / topics
Sub-File Large Binary Deduplication Native Gear-CDC (.chunked $> 64\text{ KiB}$) Requires external Git LFS Via backend Line/byte patches Delta compression Largefiles extension
Automatic Commit Signatures & $M$-of-$N$ Quorums Native Ed25519 + FIDO2 + quorum.json Optional GPG/SSH; server forge rules Optional signing Ed25519 patch keys Optional PGP clearsign GPG extension
Tamper-Evident Merkle Transparency Log Native RFC 6962 Dual-Signed Log External (gittuf / Sigstore) Operation log (local) Patch set state Blockchain-like timeline Revlog append-only
Integrated Deterministic CI & Signed Artifacts Built-in (vstore-ci + 5 URI stores) External (GitHub Actions, GitLab CI) External External External External
Embedded Web Studio & JSON API Built-in (vstore-web binary) git instaweb (CGI legacy) Community GUIs Nest (hosted) Built-in (fossil ui) hg serve (read-only)

vstore - Configuration, CLI & REST API Reference

vstore - Configuration, CLI & REST API Reference

Overview

This reference documents every command, subcommand, flag, environment variable, .vstore/ configuration file, and HTTP/JSON REST API endpoint across vstore, vstore-ci, and vstore-web.


1. Top-Level vstore CLI Reference

Command Syntax & Flags Description
help vstore help | -h | --help Prints top-level CLI usage and command summary.
version vstore version | -v | --version Prints semantic version (vstore 0.1.0).
init vstore init [-e|--encrypt] [-o|--obfuscate-refs] [-a|--author "<name>"] [path] Initializes .vstore/, generates Ed25519 signing keys, and configures optional encryption and ref obfuscation.
add vstore add <path>... Stages files or directories into .vstore/index (respecting .vstoreignore).
reset vstore reset [path]... Unstages specified paths or clears .vstore/index when called with no paths.
restore vstore restore <path>... [--source <commit>] [--staged] Restores working-tree files (or staged index entries with --staged) from HEAD or --source.
snapshot vstore snapshot -m "<msg>" [--amend] [--allow-coauthor] (alias: commit) Records an Ed25519-signed SHA-256 commit snapshot or amends HEAD.
status vstore status Reports active branch, remote ahead/behind counts, Sparse View, open Change Sets, staged/unstaged/untracked files, renames, and conflicts.
log vstore log [ref] [-n|--limit <N>] [-- <path>] Lists commit DAG history with Ed25519 verification status and Change Set provenance.
show vstore show [commit_or_tag] Displays full commit or annotated tag headers, signature status, and unified diff.
diff vstore diff [--staged|--cached] [-w|--worktree] [ref_a] [ref_b] [-- <path>...] Computes unified diffs across working tree, staging index, commits, or branches.
branch vstore branch [name] | -d <name> | -D <name> | -m <old> <new> Lists, creates, safely deletes (-d), force-deletes (-D), or renames (-m) local branches.
checkout vstore checkout <branch> [-b|--create] [-f|--force] [--ci-build <latest|id|none>] Switches active branch, updates working tree, and optionally hydrates verified CI artifacts.
merge vstore merge <branch> [--authoritative|--theirs] [-m "<msg>"] | --continue | --abort Performs a 3-way linear merge with provenance headers (Option 1A) or authoritative resolution (Option 1B).
tag vstore tag [-s|--sign] [-a|--annotate] [-m "<msg>"] [-c|--cosign] [-d <name>] [name] [commit] Lists, creates, signs, co-signs, or deletes repository tags.
release vstore release <create|list|backport> [version] [commit] [--branch] [-m "<msg>"] Creates signed v<version> tags and release/<major>.<minor> branches, lists releases, or backports commits.
verify vstore verify [commit_or_tag] Verifies Ed25519 signatures, Allowed Signers rules, revocations, and trust policy.
pack vstore pack [--packfile] [--prune] Compresses loose objects (VSTZ) or builds .vstpack/.vstidx binary packfiles (--packfile).
gc vstore gc [--grace <seconds>] [--packfile] Prunes unreachable objects older than --grace seconds and repacks reachable objects.
remote vstore remote [add <name> <url>] Lists remotes or configures <name> (ws://, wss://, http://, https://, ssh://).
fetch vstore fetch [remote] [branch] Downloads missing objects incrementally, audits remote Merkle log, and updates refs/remotes/<remote>/<branch>.
push vstore push [remote] [branch|tag] [-t|--tags] [-d|--delete <ref>] Streams missing objects as .vstpack, syncs governance & CI provenance, and updates remote refs.
pull vstore pull [remote] [branch] [-f|--force] [--with-build [latest|id]] Fetches, audits Merkle log, performs 3-way linear merge, and optionally hydrates CI build artifacts.
serve vstore serve [-p <port>] [--http] [--stdio] [-b|--blind] [-r|--require-auth] [-k <keys>] [--tls-cert <f> --tls-key <f>] [--auto-ci] Starts VSRP sync server over WebSocket/WSS, HTTP, or SSH stdio.
clone vstore clone <url> [path] [--view <name>] [--with-build [latest|id]] Clones remote repository, verifies Merkle Transparency Log, and unwraps wrapped_dek when encrypted.
reflog vstore reflog [-n|--limit <N>] Prints local reference transition log (.vstore/reflog.json).
undo vstore undo Rolls back the most recent local reference transition in .vstore/reflog.json.
import-git vstore import-git <git-dir> [-b|--branch <name>] Imports commits, trees, file modes, and tags from an existing Git repository.
archive vstore archive [ref] -o <output.zip> [--prefix <dir>] Exports tracked files at [ref] into a .zip archive without .vstore/ metadata.

2. Subsystem Commands (cs, view, trust, hook, alias, access, ci)

vstore cs (changeset)

Subcommand Syntax Purpose
list (ls) vstore cs list Lists open and merged Change Sets.
create (new) vstore cs create <name> [-m "<desc>"] Creates a Change Set anchored at HEAD.
add / rm vstore cs add <name> <path>... / vstore cs rm <name> [path]... Stages or unstages paths inside Change Set <name>.
commit vstore cs commit <name> -m "<msg>" [--allow-coauthor] Records a signed checkpoint commit inside <name>.
status / log / diff vstore cs <status|log|diff> <name> Inspects Change Set metadata, checkpoints, or combined diff against base.
shelve / unshelve vstore cs <shelve|unshelve> <name> Restores working tree to HEAD or re-applies <name>'s files.
approve vstore cs approve <name> Attaches a reviewer Ed25519 approval signature to <name>'s tip.
push / pull vstore cs push <name> [remote] / vstore cs pull [name] [remote] Syncs Change Set checkpoints and approvals with <remote>.
merge / delete vstore cs merge <name> [-m "<msg>"] [--authoritative] / vstore cs delete <name> [-f] Lands <name> linearly onto active branch or deletes metadata.

vstore view, vstore trust, vstore hook, vstore alias & vstore access

Subsystem Subcommands & Syntax
vstore view list, create <name> [-i "<globs>"] [-e "<globs>"] [-m "<desc>"] [-l|--lazy] [--ci-build <latest|id|none>], inspect [name] [-c <sha>], use <name|all>, clear, hydrate [remote], delete <name>
vstore trust status, policy [permissive|strict|head_only], allow "<id>" <pubkey> [-t ed25519|ed25519-sk] [--from <ts>] [--until <ts>], rm <pubkey>, revoke <pubkey> [-m "<reason>"], signer [-p internal|external] [-c "<cmd>"] [-k <pubkey>], vault-key, attest [sha|HEAD], log, verify-log, anchor [ref], quorum <list|set "<glob>" <min>|rm "<glob>">, sync [remote]
vstore hook list, install <pre-commit|post-commit|pre-push|pre-receive|update|post-receive> (-c "<cmd>" | -f <file>), rm <name>, run <name> [args...]
vstore alias list, set <short> "<expansion>", rm <short>
vstore access list, add -k <pubkey|*> -b "<branch-globs>" -p <read|write|admin|deny> [-a "<label>"]

vstore ci (and standalone vstore-ci)

Subcommand Syntax Purpose
run vstore ci run [targets...] [-f <pipeline>] [--parallel] [-j <N>] [--no-cache] [--no-attest] [--container-engine <docker|podman|nerdctl>] Executes pipeline DAG, signs provenance receipt, and publishes artifacts.
list / graph vstore ci list / vstore ci graph [targets...] [--mermaid] Lists declared tasks/artifacts or renders execution DAG.
runs / inspect vstore ci runs / vstore ci inspect <run-id|commit> Lists recorded build runs or prints full step/mount/artifact digests.
verify vstore ci verify [run-id|commit] Audits receipt Ed25519 signature, step chain, artifact hashes, and TLog entry.
fetch vstore ci fetch [latest|run-id|commit] [remote] Downloads, verifies, and decrypts linked build artifacts into workspace.
prune vstore ci prune [--keep-last <N>] [--keep-tagged] Prunes older binary artifacts while preserving run provenance JSON.
storage vstore ci storage [show | set <uri>] Configures vstore://, file://, https://, s3://, or scp:// store.
secret vstore ci secret <list | set <KEY> <VAL> | rm <KEY>> Manages AES-256-GCM encrypted CI secrets (.vstore/ci/secrets.enc).

3. vstore-web CLI Flags & Environment Variables

Flag / Env Var Default Description
-a, --addr, -H, --host <ip> 127.0.0.1 Listen address (127.0.0.1 by default; bind 0.0.0.0 with --tls-cert/--tls-key or reverse proxy).
-p, --port <port> 8080 HTTP/HTTPS TCP listen port (1..65535).
-r, --repo <path> . Target repository directory (also accepted as positional argument).
--blind, --zk false Forces Blind Zero-Knowledge Mode (zero keys in RAM; locks /api/v1/* and redirects plaintext views to /zk).
--enable-studio false Opt-in to authenticated mutating Studio API (POST /api/v1/*). Without this flag, vstore-web is strictly read-only.
--studio-token <token> auto-generated Bearer token required in Authorization: Bearer <token> for Studio API mutations (or set VSTORE_WEB_TOKEN).
--tls-cert <path> "" Path to PEM TLS certificate for native HTTPS termination (VSTORE_TLS_CERT).
--tls-key <path> "" Path to PEM TLS private key for native HTTPS termination (VSTORE_TLS_KEY).
--trust-proxy false Trust X-Forwarded-For / X-Real-IP headers from a reverse proxy (VSTORE_TRUST_PROXY=1).
--log-format <fmt> plain Access log format (plain or json, or VSTORE_LOG_FORMAT=json).
--passphrase <str> "" Unlocks encrypted repository for trusted local Studio browsing (prefer VSTORE_PASSPHRASE env var).
VSTORE_PASSPHRASE unset Supplies repository passphrase non-interactively to vstore, vstore-ci, or vstore-web.
VSTORE_AUTHOR unset Default author identity used by vstore init when --author is omitted.
VSTORE_RELEASE_SIGNING_KEY unset Persistent 32-byte hex Ed25519 seed (or file path) used by the release packaging pipeline to sign SHA256SUMS.txt.

4. .vstore/ Repository Configuration Schema

.vstore/config.json stores non-secret repository parameters alongside wrapped key metadata:

JSON
{
  "version": 1,
  "author": "Ada Lovelace <ada@example.org>",
  "encrypted": true,
  "obfuscate_refs": true,
  "kdf_salt": "a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "kdf_time": 3,
  "kdf_memory": 65536,
  "kdf_threads": 4,
  "wrapped_dek": "base64-encoded-vstoren1-envelope",
  "ci_storage_uri": "vstore://"
}

5. vstore-web HTTP & JSON REST API Reference

Read-Only Inspection & Zero-Knowledge Endpoints (GET / HEAD)

Endpoint Query Parameters Response Summary
GET /healthz, GET /api/health none {"status":"ok","version":"0.1.0","uptime_sec":...}
GET /readyz none {"status":"ready"} (verifies .vstore store directory accessibility; 503 if unavailable).
GET /metrics none Prometheus text exposition metrics (uptime, request/error/auth counters, active sessions).
GET /api/info none Repository encryption/blind flags, active branch, commit/branch/tag/changeset counts.
GET /api/branches, GET /api/tags, GET /api/releases none Branch tips, signed tag metadata, and logical release records.
GET /api/commits branch, search, page, limit Paginated commit summaries with Ed25519 verification flags.
GET /api/commit id=<64-hex> Full commit metadata, parents, Change Set provenance, signature, and detached attestations.
GET /api/tree commit, branch, path Directory entries (mode, name, hash, kind).
GET /api/blob id=<64-hex> Raw binary/UTF-8 blob payload (application/octet-stream).
GET /api/diff from, to, path Structured unified diff files and hunks.
GET /api/grep q, branch, path Matching file paths, line numbers, and snippets.
GET /api/status, GET /api/reflog limit (reflog) Working-tree status summary or reference transition entries.
GET /api/changesets, GET /api/changeset name (detail) Open/merged Change Sets and checkpoint metadata.
GET /api/views, GET /api/packs, GET /api/fsck none Sparse Workspace Views, .vstpack inventory, and live cryptographic fsck report.
GET /api/transparency, GET /api/quorum, GET /api/access none RFC 6962 Merkle Transparency Log audit report, quorum rules, and RBAC rules.
GET /api/ci/runs, GET /api/ci/run, GET /api/ci/secrets id (run detail) Recorded vstore-ci runs, step/artifact digests, and secret key names (values never exposed).
GET /api/zk/manifest none Encrypted KDF parameters, wrapped_dek, ref_catalog_b64, head_enc_b64, governance blobs, and TLog root for /zk WebCrypto.
GET /api/zk/object id=<64-hex> Base64-encoded raw storage envelope (VSTOREN1 ciphertext) for browser-side AES-256-GCM decryption.

Authenticated Studio Mutation Endpoints (POST /api/v1/*, Opt-In via --enable-studio)

By default, vstore-web runs in read-only mode and rejects all POST /api/v1/* requests with 403 Forbidden. When explicitly started with --enable-studio (and not in --blind mode), /api/v1/* routes enforce:

  • Authorization: Bearer <token> (constant-time verified against --studio-token / VSTORE_WEB_TOKEN or the startup-generated CSPRNG token)
  • Strict Content-Type: application/json and same-origin Origin/Host CSRF validation
  • Host-execution endpoints (/api/v1/hook/install, /api/v1/hook/run, /api/v1/trust/signer, /api/v1/ci/run) remain permanently disabled over HTTP (403 Forbidden) and must be run via the local vstore CLI.
  • Working Tree & Snapshots: /api/v1/stage, /api/v1/unstage, /api/v1/snapshot, /api/v1/restore, /api/v1/undo
  • Branches, Tags & Releases: /api/v1/branch/create, /api/v1/branch/checkout, /api/v1/branch/delete, /api/v1/branch/merge, /api/v1/tag/create, /api/v1/tag/delete, /api/v1/release/create
  • Parallel Change Sets: /api/v1/cs/create, /api/v1/cs/add, /api/v1/cs/commit, /api/v1/cs/shelve, /api/v1/cs/unshelve, /api/v1/cs/approve, /api/v1/cs/merge, /api/v1/cs/delete
  • Views, Storage & Remotes: /api/v1/view/create, /api/v1/view/use, /api/v1/view/clear, /api/v1/pack, /api/v1/gc, /api/v1/remote/add, /api/v1/remote/fetch, /api/v1/remote/push, /api/v1/remote/pull
  • Trust, Governance & CI Metadata: /api/v1/trust/policy, /api/v1/trust/allow, /api/v1/trust/revoke, /api/v1/trust/attest, /api/v1/trust/anchor, /api/v1/quorum/set, /api/v1/access/add, /api/v1/ci/secret/set, /api/v1/ci/prune

vstore - Performance, Benchmarks & Capacity Sizing

vstore - Performance & Capacity Sizing

Overview

vstore, vstore-ci, and vstore-web are compiled ahead-of-time to native machine code with zero garbage-collected VM startup penalty and zero external database dependencies. This guide documents storage deduplication ratios, SHA-256 + AES-256-GCM cryptographic throughput, .vstpack random-access lookup latency, DAG traversal scaling, and hardware sizing recommendations.


1. Subsystem Throughput & Latency Profile

Representative single-node measurements on a 4-core / 8-thread x86-64 workstation with NVMe SSD storage (Windows 11 and Linux 6.x -prod builds):

Operation Subsystem Mechanics Typical Latency / Throughput
SHA-256 Object Hashing & Framing Canonical <kind> <len>\0<body> digesting 480 - 650 MiB/s per core
Gear-CDC Content-Defined Chunking Rolling 64-bit Gear table scan for files $> 64\text{ KiB}$ (16 KiB min, 64 KiB avg, 256 KiB max) 520 - 700 MiB/s streaming
VSTOREN1 AES-256-GCM Sealing Per-object random 96-bit nonce + AAD = object_id + 128-bit authentication tag 390 - 540 MiB/s (< 6% wall-clock overhead vs. plaintext NVMe I/O)
Argon2id KEK Unwrap (init / unlock) 64 MiB memory-hard grid, t = 3 passes, p = 4 lanes (executed once per CLI/session unlock) 85 - 145 ms one-time session cost
.vstidx Packed Object Lookup 256-entry first-byte fanout table + binary search over sorted 32-byte digests + pread offset seek < 35 us for 100,000 packed objects ($O(\log N)$)
Ed25519 Commit Sign / Verify Deterministic RFC 8032 signature over canonical commit envelope ~0.06 ms sign / ~0.14 ms verify
DAG Ancestor & Reachability Walk Topological reachable_between bitset/hashset pruning during incremental push/fetch < 12 ms across 10,000 commits
3-Way LCS Diff & Line Blame Myers/LCS hunk diffing and parent-tree hash short-circuiting during blame < 8 ms for 2,000-line source files

2. Gear-CDC Deduplication & .vstpack Storage Efficiency

Traditional whole-blob storage writes an entirely new compressed copy whenever a single byte changes inside a large asset (for example, SQLite seed fixtures, PDF specifications, container layers, or media bundles). vstore eliminates this amplification automatically:

  1. Threshold Activation (> 64 KiB): Files $\le 64\text{ KiB}$ are stored directly as single blob objects to minimize metadata indirection. Files $> 64\text{ KiB}$ are split at content-defined Gear rolling-hash boundaries into variable-sized blob chunks referenced by a compact .chunked manifest.
  2. Localized Mutation Cost: Editing 4 KiB in the middle of a 50 MiB binary file produces only 1-2 new ~64 KiB chunks plus a ~40-kilobyte .chunked manifest, achieving > 99.5% deduplication across incremental snapshots without requiring external plugins like Git LFS.
  3. VSTZ Compression Before Encryption: Because ciphertext is indistinguishable from random noise and cannot be compressed after encryption, vstore applies VSTZ compression to raw canonical objects before sealing them with VSTOREN1 AES-256-GCM.
  4. .vstpack + .vstidx Compaction: Bundling 50,000 loose .vstore/objects/aa/bb... files into a single .vstpack eliminates filesystem inode fragmentation (especially NTFS 4 KiB cluster slack on Windows) and allows vstore push / vstore clone to stream contiguous ciphertext frames in a single network round-trip.

3. Encryption Overhead & Blind Server Advantages

Because all Argon2id key derivation, VSTZ compression, Gear-CDC chunking, and AES-256-GCM encryption happen on client workstations, running a central vstore serve --blind or vstore-web --blind server actually consumes less CPU and RAM than a traditional plaintext forge:

  • Zero Server KDF or Cipher CPU: A --blind relay never runs Argon2id, never decrypts payloads, and never decompresses trees to render server-side diffs.
  • Lightweight Server Verification: On push, a --blind relay verifies only the Ed25519 client challenge, checks .vstore/access.json RBAC and .vstore/quorum.json signature counts, validates .vstpack SHA-256 stream framing, and appends one 32-byte leaf to .vstore/transparency.log.

4. Production Capacity & Sizing Guidelines

Deployment Tier Team / Repo Scale Recommended CPU & RAM Storage & Maintenance Cadence
Solo / Small Team Blind Relay 1 - 15 engineers, < 5 GiB repo 1 - 2 vCPU, 512 MiB RAM SSD storage; run vstore pack --packfile weekly.
Mid-Size Engineering Org 15 - 150 engineers, 5 - 100 GiB monorepo + CI 4 vCPU, 4 GiB RAM (relay) + dedicated 8 vCPU vstore-ci runner NVMe SSD; external s3:// or https:// linked CI artifact URI + nightly vstore gc --packfile and vstore ci prune --keep-last 10 --keep-tagged.
Enterprise / Regulated Enclave 150+ engineers, strict 2-of-2 quorums & Sparse Views 8+ vCPU, 8 - 16 GiB RAM, active-passive ZFS/NVMe replication Clients clone with --view <role> to minimize workstation disk I/O; anchor Merkle Transparency Log roots hourly (vstore trust anchor).

vstore — Consolidated Master Handbook (End-User, Administrator & Operations)

vstore — Merkle DVCS, Parallel Change Sets & Zero-Knowledge Vault


Part I: vstore - Zero-Knowledge Content-Addressed Version Control, CI & Web Studio

Overview

vstore is a self-contained, zero-external-dependency Content-Addressed Distributed Version Control System (DVCS) paired with vstore-ci (a deterministic topological build pipeline runner with linked artifact provenance) and vstore-web (an embedded Repository Studio, REST API, and client-side WebCrypto Zero-Knowledge Vault). Distributed as native single-file executables for Windows, Linux, and macOS, vstore protects source code, release provenance, and build artifacts across untrusted infrastructure without sacrificing developer speed.

ARCHITECTURE DIAGRAM

vstore Architecture Flow #1

Click any component node to view contextual details.

Interactive SVG • Click any node (5 components)
Component Developer CLI & Web Studio CliWeb Component Browser WebCrypto ZK Vault (/zk) BrowserZk Component Ed25519 Quorums & Merkle Log TrustEngine Component SHA-256 CAS, Gear-CDC & Packfiles CasStore Component Blind VSRP Sync & CI Runner SyncPipeline
Components:
Component
Developer CLI & Web Studio
Core DVCS Architecture
Component 1 of 5
Architectural Role & Purpose

Architectural component "Developer CLI & Web Studio" (CliWeb) in the vstore pipeline.

Contextual Description & System Interaction

Interactive diagram component parsed from Markdown specification.

Core Functionality & Security Mechanics
  • Participates in the CliWeb execution stage
  • Maintains cryptographic integrity and zero-knowledge boundaries
Component
Browser WebCrypto ZK Vault (/zk)
Core DVCS Architecture
Component 2 of 5
Architectural Role & Purpose

Architectural component "Browser WebCrypto ZK Vault (/zk)" (BrowserZk) in the vstore pipeline.

Contextual Description & System Interaction

Interactive diagram component parsed from Markdown specification.

Core Functionality & Security Mechanics
  • Participates in the BrowserZk execution stage
  • Maintains cryptographic integrity and zero-knowledge boundaries
Component
Ed25519 Quorums & Merkle Log
Core DVCS Architecture
Component 3 of 5
Architectural Role & Purpose

Architectural component "Ed25519 Quorums & Merkle Log" (TrustEngine) in the vstore pipeline.

Contextual Description & System Interaction

Interactive diagram component parsed from Markdown specification.

Core Functionality & Security Mechanics
  • Participates in the TrustEngine execution stage
  • Maintains cryptographic integrity and zero-knowledge boundaries
Component
SHA-256 CAS, Gear-CDC & Packfiles
Core DVCS Architecture
Component 4 of 5
Architectural Role & Purpose

Architectural component "SHA-256 CAS, Gear-CDC & Packfiles" (CasStore) in the vstore pipeline.

Contextual Description & System Interaction

Interactive diagram component parsed from Markdown specification.

Core Functionality & Security Mechanics
  • Participates in the CasStore execution stage
  • Maintains cryptographic integrity and zero-knowledge boundaries
Component
Blind VSRP Sync & CI Runner
Core DVCS Architecture
Component 5 of 5
Architectural Role & Purpose

Architectural component "Blind VSRP Sync & CI Runner" (SyncPipeline) in the vstore pipeline.

Contextual Description & System Interaction

Interactive diagram component parsed from Markdown specification.

Core Functionality & Security Mechanics
  • Participates in the SyncPipeline execution stage
  • Maintains cryptographic integrity and zero-knowledge boundaries

Core Capabilities

Audience Capability Operational Value
Software Developers Parallel Change Sets (vstore cs) & Clean Linear Merges Develop multiple independent features and hotfixes concurrently inside a single working directory without branch-switching churn or stash collisions, then land changes as clean single-parent commits carrying full checkpoint provenance.
Software Developers Repository Web Studio (vstore-web) & Split Diffs Browse commit graphs, side-by-side split diffs, line-level blame, sparse workspace views, and interactive staging/branching workflows locally at http://127.0.0.1:8080.
Security-Conscious Teams Zero-Knowledge Encryption & Ref Obfuscation Seal every blob, tree, commit, tag, chunk, changeset, sparse view, and CI artifact on the client using Argon2id (64 MiB) + AES-256-GCM (VSTOREN1), and scramble branch/tag names via HMAC-SHA256 (--obfuscate-refs).
Remote Reviewers Browser WebCrypto Zero-Knowledge Vault (/zk) Inspect encrypted commits, trees, and blobs directly inside a standard browser using window.crypto.subtle while the hosting server operates in --blind mode with zero keys in RAM.
Platform & Release Engineers Ed25519 Quorums, Transparency Log & Deterministic CI Enforce $M$-of-$N$ multi-signer branch/tag quorums, RFC 6962 dual-signed Merkle Transparency Logs, and vstore-ci topological build pipelines with signed linked artifacts (vstore://, https://, s3://, scp://).

Security & Cryptographic Guarantees

Security Pillar Enforcement Mechanism in vstore
Confidentiality Two-tier Argon2id Key-Encryption Key (KEK) wrapping a random 256-bit Data-Encryption Key (wrapped_dek), sealing every repository object with AES-256-GCM (AAD = object_id).
Metadata Privacy Optional HMAC-SHA256 reference obfuscation (refs/zk/<hmac>) plus encrypted ref_catalog so blind relay servers cannot observe branch, tag, or feature names.
Integrity & Non-Repudiation End-to-end SHA-256 Merkle DAG addressing, automatic Ed25519 (or hardware FIDO2/HSM) signatures on every commit and release tag, and $M$-of-$N$ quorum enforcement.
Rollback & Split-View Defense Append-only RFC 6962 Merkle Transparency Log (.vstore/transparency.log) recording dual-signed state roots verified automatically on every clone, fetch, pull, and push.
Storage Efficiency Gear rolling-hash Content-Defined Chunking (.chunked for files $> 64\text{ KiB}$), VSTZ compression, and indexed .vstpack / .vstidx binary packfiles.

Live Workspace Preview

Repository Overview & Hybrid Studio (/)

vstore Repository Dashboard and Hybrid Studio

Browser WebCrypto Zero-Knowledge Vault (/zk)

vstore Browser WebCrypto Zero-Knowledge Vault


End-User Documentation Suite

  1. Overview & Readme - Product overview, cryptographic summary, workspace previews, and quickstart commands.
  2. How-To Guide - Step-by-step operational recipes for encrypted repositories, parallel changesets, linear merges, blind remote sync, CI pipelines, and the vblog hands-on tutorial.
  3. End-User Guide - Complete day-to-day manual for the vstore CLI, branches, logical releases, parallel changesets, sparse views, vstore-web Studio, and the /zk Browser Vault.
  4. Administrator Guide - Production server deployment (systemd, reverse proxy TLS), Blind Zero-Knowledge relay hosting, RBAC (access.json), $M$-of-$N$ quorums, backups, fsck, packfile maintenance, and key rotation (rekey).
  5. Operations, Use Cases & Comparisons - vstore-ci build pipelines, multi-developer review workflows, air-gapped compliance operations, Git migration, and architectural comparison against Git, Jujutsu, Pijul, Fossil, and Mercurial.
  6. Configuration & CLI Reference - Exhaustive command, flag, environment variable, configuration schema, and HTTP/JSON REST API (/api/* and /api/v1/*) reference for vstore, vstore-web, and vstore-ci.
  7. Performance & Capacity Guide - Content-addressed storage throughput, Gear-CDC deduplication ratios, .vstpack 256-fanout index latency, AES-256-GCM overhead, and server sizing guidelines.
  8. Consolidated User Handbook - Single-file master handbook combining all End-User, How-To, Administrator, Operations, Reference, and Performance guides.

Quickstart

Use the prebuilt binaries for your platform (dist/bin/windows/, dist/bin/linux/, or dist/bin/macos/):

BASH
# 1. Verify installed CLI, CI runner, and Web Studio versions
vstore --version
vstore-ci --version
vstore-web --version

# 2. Initialize a signed, zero-knowledge encrypted repository
export VSTORE_PASSPHRASE="correct-horse-battery-staple"
vstore init --encrypt --obfuscate-refs --author "Ada Lovelace <ada@example.org>" ./my-service
cd ./my-service

# 3. Stage files and record an Ed25519-signed SHA-256 snapshot
echo '{"service":"payments","version":"1.0.0"}' > manifest.json
vstore add manifest.json
vstore snapshot -m "Initialize payments service manifest"
vstore verify HEAD

# 4. Launch the local Repository Web Studio on 127.0.0.1:8080
vstore-web --addr 127.0.0.1 --port 8080 --repo .

Open http://127.0.0.1:8080 in your browser to explore the Repository Dashboard, Commit DAG, Change Sets Studio, CI Provenance inspector, and /zk Browser WebCrypto Vault.


Part II: vstore - How-To Guide & Hands-On Tutorial

Overview

This guide provides copy-pasteable step-by-step recipes for everyday developer and operator tasks across vstore, vstore-ci, and vstore-web, followed by a complete end-to-end walkthrough using the vblog sample web application.


Recipe 1: Initialize Plain vs. Zero-Knowledge Encrypted Repositories

Standard Signed Repository (Plaintext Storage, Ed25519 Signed)

BASH
mkdir ./api-gateway && cd ./api-gateway
vstore init --author "Ada Lovelace <ada@example.org>"

# Check repository status and generated Ed25519 identity
vstore status
vstore trust status

Zero-Knowledge Encrypted & Ref-Obfuscated Repository

Use --encrypt to seal every stored object with AES-256-GCM (VSTOREN1) and --obfuscate-refs to replace human-readable branch/tag filenames on disk with HMAC-SHA256 digests:

BASH
export VSTORE_PASSPHRASE="strong-team-vault-passphrase"
vstore init --encrypt --obfuscate-refs --author "Ada Lovelace <ada@example.org>" ./zk-vault-repo
cd ./zk-vault-repo

# Export the 64-character hex Vault Key for the /zk Browser WebCrypto Vault
vstore trust vault-key

Recipe 2: Configure .vstoreignore, Stage Selectively & Record Snapshots

Create a .vstoreignore file using standard glob (*, **) and negation (!) rules so runtime databases, build outputs, and temporary files never pollute snapshots:

GITIGNORE
# Ignore build outputs and runtime artifacts
dist/
target/
*.db
*.db-wal
*.db-shm
*.log
*.tmp

# Explicitly track versioned seed data and static web assets
!data/seed_posts.json
!src/assets/**

Stage specific paths, inspect staged vs. working-tree diffs, and record a signed commit:

BASH
vstore add .vstoreignore data/seed_posts.json src/assets/style.css
vstore diff --staged
vstore snapshot -m "Add ignore policy, starter seed data, and base stylesheet"

# Verify the Ed25519 cryptographic signature on HEAD
vstore verify HEAD

If you stage a file by mistake or want to revert a modified working file:

BASH
# Unstage a single path without modifying the file on disk
vstore reset src/assets/style.css

# Restore a working-tree file back to its HEAD contents
vstore restore src/assets/style.css

# Revert the last local branch or HEAD transition via the reflog
vstore reflog -n 5
vstore undo

Recipe 3: Work on Two Tasks Simultaneously with Parallel Change Sets (vstore cs)

Instead of juggling stash stacks or switching branches mid-thought, isolate concurrent workstreams inside named Change Sets in the same working folder:

BASH
# Create two independent Change Sets anchored at current HEAD
vstore cs create theme-and-search -m "Add dark-mode toggle and live post search"
vstore cs create xss-escape-fix   -m "Escape untrusted HTML in user comments"

# Edit files for both tasks in your working directory, then route each file to its Change Set
vstore cs add theme-and-search src/assets/style.css src/assets/app.js
vstore cs commit theme-and-search -m "Implement dark theme tokens and instant search filter"

vstore cs add xss-escape-fix src/sanitizer.ts
vstore cs commit xss-escape-fix -m "Escape angle brackets, quotes, and ampersands"

# Inspect open Change Sets, checkpoints, and combined diffs
vstore cs list
vstore cs diff xss-escape-fix

Temporarily shelve a Change Set if you want a clean working directory for testing, then unshelve or land it cleanly onto main:

BASH
# Shelve theme-and-search back to HEAD on disk without losing its checkpoints
vstore cs shelve theme-and-search

# Land the hotfix onto main as a clean single-parent linear commit with provenance headers
vstore cs merge xss-escape-fix -m "Land XSS comment sanitization hotfix"
vstore cs delete xss-escape-fix

# Re-apply theme-and-search to the working folder, then land it on main
vstore cs unshelve theme-and-search
vstore cs merge theme-and-search -m "Land dark-mode toggle and live search"
vstore cs delete theme-and-search

Recipe 4: Feature Branches, Clean Linear Merges & Conflict Resolution

vstore keeps main strictly linear by default (Option 1A): merging a feature branch performs a 3-way diff3 merge and writes a single-parent commit on main carrying changeset and changeset_tip provenance headers.

BASH
# Create and switch to a feature branch
vstore checkout -b feature/export-api
echo '{"export_version": 2}' > data/export_schema.json
vstore add data/export_schema.json
vstore snapshot -m "Add JSON export schema v2"

# Switch back to main and merge linearly
vstore checkout main
vstore merge feature/export-api -m "Integrate JSON export schema v2"

# Safely delete the merged branch (verified via ancestry or trunk provenance headers)
vstore branch -d feature/export-api

If both main and feature/export-api modified the same lines:

  1. vstore merge feature/export-api writes standard diff3 conflict markers (<<<<<<<, =======, >>>>>>>) and pauses the merge (vstore snapshot automatically blocks commits while conflict markers remain).
  2. Either edit the file to resolve the conflict and run vstore merge --continue, abort cleanly with vstore merge --abort, or explicitly resolve overlapping hunks in favor of the incoming branch (Option 1B) via vstore merge feature/export-api --authoritative.

Recipe 5: Enforce 2-of-2 Team Quorums & Co-Signed Releases

Require two distinct trusted Ed25519 signers before main or v* release tags can advance:

BASH
# Register a teammate's Ed25519 public key in the repository trust ring
vstore trust allow "Grace Hopper <grace@example.org>" 8f4a2d91c7e03b65a1d2e3f405162738495a6b7c8d9e0f1a2b3c4d5e6f708192
vstore trust policy strict

# Require 2 distinct signatures on main and production release tags
vstore trust quorum set "refs/heads/main" 2
vstore trust quorum set "refs/tags/v*" 2

# Reviewer attaches a detached co-signature attestation to HEAD or approves a Change Set
vstore trust attest HEAD
vstore cs approve release-prep

# Create and co-sign a production release tag
vstore tag -s -m "Production release v1.0.0" v1.0.0
vstore tag --cosign v1.0.0
vstore verify v1.0.0

Recipe 6: Sync with a Blind Zero-Knowledge Server (ws:// or https://)

Host a remote sync relay that stores ciphertext objects, verifies Ed25519 signatures and $M$-of-$N$ quorums, and appends RFC 6962 Merkle Transparency Log entries without ever possessing the repository passphrase or DEK:

BASH
# On the remote server: initialize or open in Blind Mode (--blind)
vstore serve --port 9418 --blind --require-auth

# On the developer workstation: register the remote and push encrypted packfiles
vstore remote add origin ws://127.0.0.1:9418
vstore push origin main
vstore push origin --tags

# On a teammate's workstation: clone with passphrase and audit the Merkle Transparency Log
export VSTORE_PASSPHRASE="strong-team-vault-passphrase"
vstore clone ws://127.0.0.1:9418 ./teammate-copy
cd ./teammate-copy
vstore trust verify-log

Recipe 7: Partial Checkouts with Sparse Workspace Views (vstore view)

For large monorepos or media-heavy repositories, check out only the subdirectories relevant to your role while fetching blobs by hash on demand:

BASH
# Define a frontend-only Workspace View
vstore view create frontend -i "src/assets/**,data/**,README.md" -e "*.bak" -m "Frontend assets and seed data"

# Activate the view (non-matching files are cleanly removed from the working directory)
vstore view use frontend
vstore view inspect frontend

# Hydrate any missing blobs from origin on demand, or return to the full repository tree
vstore view hydrate origin
vstore view clear

Recipe 8: Run Deterministic CI Pipelines & Hydrate Linked Artifacts (vstore-ci)

Execute topological build and verification waves, seal output artifacts into linked storage, and verify end-to-end build provenance:

BASH
# Inspect pipeline tasks and topological execution plan
vstore ci list
vstore ci graph

# Execute the pipeline in parallel across 4 workers and record a signed provenance receipt
vstore ci run --parallel -j 4

# Audit the recorded build run's Ed25519 signature, step hash chain, and artifact digests
vstore ci runs
vstore ci verify

# Pull and verify linked build artifacts directly onto a developer machine
vstore pull origin main --with-build latest

Hands-On Walkthrough: Versioning & Governing vblog End-to-End

The vblog sample application (examples/vblog/ or [vblog-sample-app.zip](/docs/vblog-sample-app.zip)) demonstrates every vstore workflow on a realistic full-stack developer blog featuring SQLite persistence, JSON seed/export (data/seed_posts.json), responsive CSS3 dark/light themes (src/assets/style.css), and vanilla JavaScript live filtering (src/assets/app.js):

ARCHITECTURE DIAGRAM

vstore Architecture Flow #2

Click any component node to view contextual details.

Interactive SVG • Click any node (4 components)
Component 1. Init Encrypted vblog Repo Step1 Component 3. Packfiles & Sparse Views Step3 Component 4. 2-of-2 Quorum & Signed v1.0.0 Step4 Component 5. Blind Sync & /zk WebCrypto Tour Step5
Components:
Component
1. Init Encrypted vblog Repo
Core DVCS Architecture
Component 1 of 4
Architectural Role & Purpose

Architectural component "1. Init Encrypted vblog Repo" (Step1) in the vstore pipeline.

Contextual Description & System Interaction

Interactive diagram component parsed from Markdown specification.

Core Functionality & Security Mechanics
  • Participates in the Step1 execution stage
  • Maintains cryptographic integrity and zero-knowledge boundaries
Component
3. Packfiles & Sparse Views
Core DVCS Architecture
Component 2 of 4
Architectural Role & Purpose

Architectural component "3. Packfiles & Sparse Views" (Step3) in the vstore pipeline.

Contextual Description & System Interaction

Interactive diagram component parsed from Markdown specification.

Core Functionality & Security Mechanics
  • Participates in the Step3 execution stage
  • Maintains cryptographic integrity and zero-knowledge boundaries
Component
4. 2-of-2 Quorum & Signed v1.0.0
Core DVCS Architecture
Component 3 of 4
Architectural Role & Purpose

Architectural component "4. 2-of-2 Quorum & Signed v1.0.0" (Step4) in the vstore pipeline.

Contextual Description & System Interaction

Interactive diagram component parsed from Markdown specification.

Core Functionality & Security Mechanics
  • Participates in the Step4 execution stage
  • Maintains cryptographic integrity and zero-knowledge boundaries
Component
5. Blind Sync & /zk WebCrypto Tour
Core DVCS Architecture
Component 4 of 4
Architectural Role & Purpose

Architectural component "5. Blind Sync & /zk WebCrypto Tour" (Step5) in the vstore pipeline.

Contextual Description & System Interaction

Interactive diagram component parsed from Markdown specification.

Core Functionality & Security Mechanics
  • Participates in the Step5 execution stage
  • Maintains cryptographic integrity and zero-knowledge boundaries
  1. Extract or copy vblog into a clean workspace and run vstore init --encrypt --obfuscate-refs --author "Ada Lovelace".
  2. Stage .vstoreignore, README.md, data/seed_posts.json, and src/, then create your baseline signed snapshot (vstore snapshot -m "Initial vblog application snapshot").
  3. Install a pre-commit quality hook (vstore hook install pre-commit -c "vstore status") and ergonomic shortcut (vstore alias set st "status").
  4. Develop two changes concurrently (vstore cs create theme-and-search and vstore cs create xss-escape-fix), commit checkpoints independently, and merge both cleanly onto main.
  5. Compact objects into an indexed .vstpack archive (vstore pack --packfile) and verify zero corruption via vstore status and /storage in vstore-web.
  6. Launch vstore-web --blind --port 8080, open http://127.0.0.1:8080/zk, paste the output of vstore trust vault-key, and browse decrypted vblog commits, directory trees, and files entirely inside your browser's WebCrypto sandbox.

Part III: vstore - End-User Guide

Overview

This guide covers day-to-day software engineering workflows using the vstore command-line interface and the vstore-web Repository Studio, including staging, signed snapshots, trunk-based branching and logical releases, concurrent Parallel Change Sets, sparse Workspace Views, interactive Split Diffs and Line Blame, and client-side inspection inside the Browser WebCrypto Zero-Knowledge Vault (/zk).


1. Repository Lifecycle, Staging & Signed Snapshots

Every vstore repository stores its content-addressed object database, references, signing keys, and governance metadata inside a single .vstore/ directory at the root of your project.

Initializing or Cloning a Workspace

  • New Plaintext Repository: vstore init --author "Ada Lovelace <ada@example.org>" generates an Ed25519 signing keypair and sets the default branch to main.
  • New Encrypted Repository: vstore init --encrypt --obfuscate-refs --author "Ada Lovelace" derives an Argon2id Key-Encryption Key from your passphrase (VSTORE_PASSPHRASE or interactive prompt), wraps a random 256-bit Data-Encryption Key (wrapped_dek), seals all objects with AES-256-GCM, and hashes branch/tag filenames via HMAC-SHA256.
  • Cloning a Remote Repository: vstore clone ws://sync.example.org:9418 ./project (also supports wss://, http://, https://, and ssh://) downloads .vstpack streams, verifies the server's RFC 6962 Merkle Transparency Log, and unwraps wrapped_dek locally when encrypted.

Selective Staging, Status, Restore & Undo

Task Command Behavior
Inspect workspace state vstore status Displays active branch, remote ahead/behind counts (origin/main), active Workspace View, open Change Sets, staged index changes, unstaged edits, detected file renames, and untracked paths.
Stage files or folders vstore add src/ manifest.json Hashes and stages matching files into .vstore/index while respecting .vstoreignore glob and ! negation rules.
Record signed snapshot vstore snapshot -m "Message" Writes tree and commit objects, signs the canonical commit payload with your Ed25519 key, updates HEAD, and appends a local reflog entry.
Amend latest snapshot vstore snapshot --amend -m "New msg" Replaces the tip commit on the current branch with updated staged content or an updated commit message.
Unstage paths vstore reset src/config.toml Removes paths from .vstore/index (or clears the entire index when called without arguments) without altering working files.
Discard working edits vstore restore src/config.toml Restores files or directories from HEAD or --source <commit>.
Undo last ref transition vstore undo Reverts the most recent branch or HEAD movement recorded in .vstore/reflog.json.

2. Branches, Trunk-Based Linear Merges, Tags & Releases

Branch Management & Linear Provenance

vstore supports full feature branching (vstore branch, vstore checkout -b <branch>) while keeping trunk history clean and readable by default:

  • Option 1A - Clean Linear Merge (Default): vstore merge feature/search computes a 3-way diff3 merge against the lowest common ancestor and records a single-parent linear commit on the target branch carrying changeset and changeset_tip provenance headers. vstore branch -d feature/search recognizes both direct DAG ancestry and changeset_tip headers when verifying safe deletion.
  • Option 1B - Authoritative Merge (--authoritative / --theirs): vstore merge feature/search --authoritative resolves overlapping diff3 hunks deterministically in favor of the incoming branch while preserving non-conflicting trunk changes.

Commit History & Cryptographic Signatures (/commits)

vstore Commit DAG History and Ed25519 Signature Verification

Signed Tags & Logical Trunk Releases

  • Annotated Signed Tags: vstore tag -s -m "Release v1.0.0" v1.0.0 creates a signed tag object in the CAS; teammates can attach additional quorum signatures via vstore tag --cosign v1.0.0.
  • Logical Releases & Backports:
  • vstore release create 1.2.0 -m "Q4 Production Release" creates signed tag v1.2.0 (and optional release/1.2 maintenance branch with --branch).
  • vstore release list summarizes all semantic releases and their target commits.
  • vstore release backport 1.2.0 <commit_sha> cherry-picks a hotfix cleanly onto release/1.2.

3. Concurrent Development with Parallel Change Sets (vstore cs)

Parallel Change Sets allow a developer to work on two, three, or more independent tasks inside a single checkout without switching branches or stashing half-finished edits:

ARCHITECTURE DIAGRAM

vstore Architecture Flow #3

Click any component node to view contextual details.

Interactive SVG • Click any node (5 components)
Component Trunk HEAD Commit BaseHead Component Change Set: rbac-audit-fix CsBeta Component Signed Checkpoints + Reviewer Approval CheckpointsA Component Signed Checkpoints + Shelve/Unshelve CheckpointsB Component Clean Linear Trunk Commit (Provenance Linked) LinearTrunk
Components:
Component
Trunk HEAD Commit
Core DVCS Architecture
Component 1 of 5
Architectural Role & Purpose

Architectural component "Trunk HEAD Commit" (BaseHead) in the vstore pipeline.

Contextual Description & System Interaction

Interactive diagram component parsed from Markdown specification.

Core Functionality & Security Mechanics
  • Participates in the BaseHead execution stage
  • Maintains cryptographic integrity and zero-knowledge boundaries
Component
Change Set: rbac-audit-fix
Core DVCS Architecture
Component 2 of 5
Architectural Role & Purpose

Architectural component "Change Set: rbac-audit-fix" (CsBeta) in the vstore pipeline.

Contextual Description & System Interaction

Interactive diagram component parsed from Markdown specification.

Core Functionality & Security Mechanics
  • Participates in the CsBeta execution stage
  • Maintains cryptographic integrity and zero-knowledge boundaries
Component
Signed Checkpoints + Reviewer Approval
Core DVCS Architecture
Component 3 of 5
Architectural Role & Purpose

Architectural component "Signed Checkpoints + Reviewer Approval" (CheckpointsA) in the vstore pipeline.

Contextual Description & System Interaction

Interactive diagram component parsed from Markdown specification.

Core Functionality & Security Mechanics
  • Participates in the CheckpointsA execution stage
  • Maintains cryptographic integrity and zero-knowledge boundaries
Component
Signed Checkpoints + Shelve/Unshelve
Core DVCS Architecture
Component 4 of 5
Architectural Role & Purpose

Architectural component "Signed Checkpoints + Shelve/Unshelve" (CheckpointsB) in the vstore pipeline.

Contextual Description & System Interaction

Interactive diagram component parsed from Markdown specification.

Core Functionality & Security Mechanics
  • Participates in the CheckpointsB execution stage
  • Maintains cryptographic integrity and zero-knowledge boundaries
Component
Clean Linear Trunk Commit (Provenance Linked)
Core DVCS Architecture
Component 5 of 5
Architectural Role & Purpose

Architectural component "Clean Linear Trunk Commit (Provenance Linked)" (LinearTrunk) in the vstore pipeline.

Contextual Description & System Interaction

Interactive diagram component parsed from Markdown specification.

Core Functionality & Security Mechanics
  • Participates in the LinearTrunk execution stage
  • Maintains cryptographic integrity and zero-knowledge boundaries
  1. Create: vstore cs create zk-pack-stream -m "Optimize encrypted packfile streaming" anchors a named Change Set at HEAD.
  2. Stage & Checkpoint: vstore cs add zk-pack-stream src/streamer.rs and vstore cs commit zk-pack-stream -m "Add buffered chunk reader" record signed checkpoint commits under refs/changesets/zk-pack-stream without moving main. Single-author ownership is enforced automatically unless --allow-coauthor is passed.
  3. Shelve & Unshelve: vstore cs shelve zk-pack-stream temporarily restores touched files in your working folder back to HEAD; vstore cs unshelve zk-pack-stream puts them right back.
  4. Remote Collaboration & Approval: vstore cs push zk-pack-stream origin publishes encrypted checkpoints so teammates can pull (vstore cs pull zk-pack-stream origin), inspect diffs, and co-sign (vstore cs approve zk-pack-stream).
  5. Land on Trunk: vstore cs merge zk-pack-stream verifies any configured branch quorums and lands a single linear commit on main whose changeset_commits list links every checkpoint.

Parallel Change Sets Studio (/changesets)

vstore Parallel Change Sets Studio


4. Sparse Workspace Views (vstore view)

When working in large multi-project repositories or repositories containing large binary assets (automatically deduplicated via Gear rolling-hash .chunked manifests above 64 KiB), Workspace Views let you materialize only the paths you care about:

  • vstore view create backend -i "services/auth/**,shared/**,README.md" --ci-build latest
  • vstore view use backend filters the working tree immediately.
  • vstore view hydrate origin fetches any missing blobs by SHA-256 digest without leaking plaintext filenames to a blind server.
  • vstore view clear restores the complete repository tree.

5. Exploring & Operating in vstore-web Studio

Launch vstore-web locally against any repository:

BASH
vstore-web --addr 127.0.0.1 --port 8080 --repo .

The Studio organizes repository workflows into six primary navigation workspaces:

  1. Overview (/, /status, /views, /storage, /hooks): Live repository health metrics, interactive staging/snapshot controls, Sparse View toggles, .vstpack / fsck integrity runner, and hook/alias inspection.
  2. Files & Code (/tree, /blob, /blame, /grep, /diff, /archive): Directory tree browser, syntax-highlighted blob viewer with rendered Markdown preview, line-by-line authorship blame, full-repository regex/substring search, arbitrary two-ref Diff Explorer, and clean .zip export.
  3. History & Refs (/commits, /commit, /branches, /releases, /remotes, /reflog, /inspect): Paginated commit DAG with signature badges, Unified vs. Side-by-Side Split Diff commit detail view, detached attestation list, branch/tag/release management, remote sync controls, reflog undo, and raw CAS object inspector.
  4. Change Sets (/changesets, /changeset): Visual dashboard of open and merged Change Sets, checkpoint logs, combined diffs, shelve/unshelve actions, reviewer approval, and one-click linear landing.
  5. CI/CD (/ci): Build run history, step-by-step execution hashes, stage mount digests, linked artifact signatures, and redacted secret key metadata.
  6. Trust & ZK Vault (/trust, /access, /zk): Allowed Signers ring, key revocations, $M$-of-$N$ quorum rules, RFC 6962 Merkle Transparency Log audit report, branch RBAC table, and the Browser WebCrypto Vault.

Split Diff, Ed25519 Signature & Quorum Attestation View (/commit)

vstore Split Diff and Cryptographic Commit Attestation View


6. Using the Browser WebCrypto Zero-Knowledge Vault (/zk)

When vstore-web runs on an untrusted host with --blind (vstore-web --port 8080 --blind --repo ./repos/app), server-side plaintext routes lock down automatically and redirect to /zk:

  1. Run vstore trust vault-key on an authorized workstation (or use your repository passphrase when PBKDF2/WebCrypto unwrap is configured) to copy your 64-character hex Vault Key.
  2. Open /zk in any modern browser and paste the Vault Key into the Client-Side WebCrypto Unlock panel.
  3. Your browser imports the key into non-exportable CryptoKey memory via window.crypto.subtle.importKey, fetches encrypted VSTOREN1 envelopes from /api/zk/manifest and /api/zk/object, verifies AAD = object_id, decompresses VSTZ payloads, and renders decrypted branches, commit histories, trees, and file contents locally - transmitting zero key material over the network.

Part IV: vstore - Administrator Guide

Overview

This guide covers production deployment, network transport hardening, Blind Zero-Knowledge Relay Mode, role-based branch access control (access.json), cryptographic trust governance (allowed_signers, revocations, $M$-of-$N$ quorums, hardware signers, Merkle Transparency Logs), storage compaction (.vstpack), integrity verification (fsck), backups, and key rotation (rekey).


1. Deployment Topologies

vstore separates remote synchronization (vstore serve) from web browsing and REST inspection (vstore-web), allowing administrators to deploy either or both with minimal attack surface:

Component Recommended Bind & Transport Key Custody Mode Primary Role
vstore serve --blind 127.0.0.1:9418 behind TLS reverse proxy, direct --tls-cert/--tls-key (wss://), or SSH --stdio (ssh://) Zero keys in RAM (--blind) Receives/serves encrypted .vstpack streams, enforces Ed25519 auth, RBAC, $M$-of-$N$ quorums, and appends Merkle Transparency Log entries.
vstore-web --blind 127.0.0.1:8080 behind Caddy/Nginx HTTPS Zero keys in RAM (--blind) Serves /zk Browser WebCrypto Vault, /trust Transparency Log inspector, /api/zk/*, and /api/health while blocking all server-side plaintext & /api/v1/* mutation routes.
vstore-web (Local Studio) 127.0.0.1:8080 (workstation loopback only) Unlocked locally Full developer UI and /api/v1/* Studio actions on trusted developer hardware.

2. Production Linux (systemd) & Reverse Proxy Setup

Dedicated System Account & Repository Directory

BASH
sudo useradd --system --home-dir ./data --create-home --shell /usr/sbin/nologin vstore
sudo install -m 0755 vstore ./vstore
sudo install -m 0755 vstore-web ./vstore-web
sudo install -m 0755 vstore-ci ./vstore-ci

sudo -u vstore mkdir -p ./data/repos/core-platform
sudo -u vstore ./vstore init --author "Platform Relay" ./data/repos/core-platform

systemd Service Units (Native TLS Blind Sync Relay + Read-Only Blind Web Vault)

Create /etc/systemd/system/vstore-serve.service (native TLS via --tls-cert / --tls-key; a reverse proxy is optional):

INI
[Unit]
Description=vstore Zero-Knowledge VSRP Sync Server
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=vstore
Group=vstore
WorkingDirectory=./data/repos/core-platform
ExecStart=./vstore serve --http --host 0.0.0.0 --port 9418 --blind --require-auth --tls-cert /etc/vstore/tls/fullchain.pem --tls-key /etc/vstore/tls/privkey.pem --log-format json
Restart=on-failure
RestartSec=3
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
PrivateTmp=true
ReadWritePaths=./data/repos/core-platform
ReadOnlyPaths=/etc/vstore

[Install]
WantedBy=multi-user.target

Create /etc/systemd/system/vstore-web.service (read-only by default; pass --enable-studio with VSTORE_WEB_TOKEN only if authenticated web mutations are required):

INI
[Unit]
Description=vstore Blind WebCrypto Vault & Audit Portal
After=network-online.target

[Service]
Type=simple
User=vstore
Group=vstore
WorkingDirectory=./data/repos/core-platform
ExecStart=./vstore-web --addr 0.0.0.0 --port 8443 --blind --repo ./data/repos/core-platform --tls-cert /etc/vstore/tls/fullchain.pem --tls-key /etc/vstore/tls/privkey.pem --log-format json
Restart=on-failure
RestartSec=3
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
PrivateTmp=true
ReadOnlyPaths=./data/repos/core-platform /etc/vstore

[Install]
WantedBy=multi-user.target

Optional Caddy TLS 1.3 Reverse Proxy Example

If you prefer terminating TLS at an edge proxy instead of using --tls-cert / --tls-key, bind vstore serve and vstore-web to 127.0.0.1 with --trust-proxy:

TEXT
vcs.example.org {
    encode zstd gzip

    handle /vstore/* {
        reverse_proxy 127.0.0.1:9418
    }

    handle {
        reverse_proxy 127.0.0.1:8080
    }
}

SSH Zero-Daemon Transport (--stdio)

For teams using SSH keys and authorized_keys bastion controls without opening additional TCP ports, vstore speaks the VSRP sync framing directly over SSH standard input/output:

BASH
# Client pushes directly over SSH; remote host invokes `vstore serve --stdio` automatically
vstore remote add origin ssh://vstore@vcs.example.org./data/repos/core-platform
vstore push origin main

3. Authentication, Branch RBAC (access.json) & Governance

Challenge-Response Client Authentication

When --require-auth (and optionally --authorized-keys <pub1,pub2>) is passed to vstore serve, every connecting client must sign a per-session random 32-byte server challenge using its Ed25519 private key before reading or pushing refs.

Granular Per-Branch RBAC (vstore access)

Administrators define branch-pattern permissions (read, write, admin, deny) in .vstore/access.json, evaluated with explicit deny precedence:

BASH
# Grant write access on feature/* to all authenticated developers
vstore access add -k "*" -b "refs/heads/feature/*" -p write -a "All Developers"

# Restrict main and release/* writes to Release Engineering leads
vstore access add -k 3b6a27bcceb6a42d62a3a8d02a6f0d73653215771de243a63ac048a18b59da29 \
  -b "refs/heads/main,refs/heads/release/*" -p admin -a "Release Lead"

# Audit active RBAC policy
vstore access list

Trust Ring, Hardware Signers, Revocations & $M$-of-$N$ Quorums

  1. Allowed Signers & Validity Windows:
BASH
   vstore trust allow "Security Reviewer <sec@example.org>" <pubkey_hex> --from 1735689600 --until 1767225600
   vstore trust policy strict
  1. External / Hardware Signer Integration (FIDO2 / YubiKey / Cloud KMS):
BASH
   vstore trust signer --provider external --command "custom-kms-sign --key prod-ed25519" --key-id <pubkey_hex>
  1. Signed Key Revocation:
BASH
   vstore trust revoke <compromised_pubkey_hex> -m "Workstation rotated 2026-11-14"

Revocations are Ed25519-signed records synchronized automatically via vstore trust sync, push, pull, and fetch.

  1. $M$-of-$N$ Multi-Party Quorums:
BASH
   vstore trust quorum set "refs/heads/main" 2
   vstore trust quorum set "refs/tags/v*" 2

Both local merges and remote vstore serve ref updates reject updates to matching patterns unless at least $M$ distinct non-revoked Allowed Signers have signed the commit/tag and its detached .vstore/attestations/<hash>.json records.


4. Storage Maintenance, Integrity (fsck), Backups & Key Rotation

Packfile Compaction & Garbage Collection

As repositories accumulate thousands of loose objects, bundle them into indexed .vstpack / .vstidx archives with 256-entry first-byte fanout tables for $O(\log N)$ binary-search reads and single-stream network transfers:

BASH
# Bundle loose objects into a binary .vstpack + .vstidx archive
vstore pack --packfile

# Prune unreachable objects older than 24 hours (86400s) and consolidate packfiles
vstore gc --grace 86400 --packfile

Full Cryptographic Repository Verification (fsck & verify-log)

Run periodic scheduled health checks on both server relays and CI agents:

BASH
# Run full 4-tier cryptographic object and packfile integrity check
vstore fsck

# Verify Merkle Transparency Log hash chain and dual signatures
vstore trust verify-log

# Verify HEAD and release tag signatures against Allowed Signers & Revocations
vstore verify HEAD
vstore verify v1.0.0

You can also inspect live object counts, packfile indexes, and run full fsck verification via GET /api/fsck or /storage in vstore-web.

Consistent Backups & Disaster Recovery

Because vstore writes objects immutably (atomic_write_bytes via fsync + temp-file rename) and serializes ref updates under .vstore/repo.lock, backing up .vstore/ is straightforward:

  1. For cold or snapshot backups: take an atomic ZFS/LVM/EBS filesystem snapshot of the repository directory, or run vstore clone / vstore fetch to a warm standby server.
  2. After restoring a backup, run vstore trust verify-log against developers' locally cached remote checkpoints (.vstore/remote_checkpoints.json) to confirm zero silent rollback occurred.
  3. For encrypted repositories, store the repository passphrase or wrapped recovery key in an offline enterprise secret vault; a --blind server backup contains only AES-256-GCM ciphertext and cannot be decrypted without the KEK/DEK.

Part V: vstore - Operations, Use Cases & DVCS Comparisons

Overview

This guide details operational playbooks for vstore-ci topological pipelines, linked artifact provenance (vstore://, https://, s3://, scp://), multi-developer Change Set code review, regulated/air-gapped release engineering, Git repository migration, and a comprehensive architectural comparison of vstore against Git, Jujutsu (jj), Pijul, Fossil, and Mercurial.


1. Deterministic Build Pipelines & Linked Provenance (vstore-ci)

Unlike external CI SaaS platforms that run opaque YAML scripts decoupled from version-control cryptography, vstore-ci executes declarative DAG tasks directly against the content-addressed repository state and binds every build step, inter-stage mount, and published binary artifact to an Ed25519-signed provenance receipt (.vstore/ci/runs/<run_id>.json).

CI Pipeline & Cryptographic Trust Audit (/ci)

vstore CI Pipeline Provenance and Merkle Trust Audit

Key Operational Properties of vstore-ci

  1. Topological Wave Execution (--parallel -j <N>): Tasks declare explicit dependencies (depends), timeouts (timeout_sec), optional OCI container sandboxes (docker, podman, nerdctl), and default-isolated network policies (isolated vs. enabled). Independent tasks within each wave execute concurrently.
  2. Zero-CAS-Bloat Stage & Cache Mounts: Intermediate compiler outputs pass between stages via hashed staging directories (input_Digest -> output_Digest) without bloating .vstore/objects/ with transient object files.
  3. Linked Artifact Storage with End-to-End Encryption: Final release binaries are signed with Ed25519, sealed with VSTOREN1 AES-256-GCM (aad = "ci_artifact:<sha256>") when the repository is encrypted, and published to configurable storage backends:
    • vstore:// (built-in .vstore/ci/artifacts/<sha256>, synced over VSRP)
    • ./artifacts/prod (shared NAS or air-gapped transfer volume)
    • https://artifacts.example.org/upload (HTTP PUT/GET object gateway)
    • s3://release-bucket/vstore-builds (S3-compatible object storage)
    • scp://ci@vault.example.org/srv/artifacts (SSH/SCP bastion storage)
  4. Encrypted Secret Redaction: Secrets stored via vstore ci secret set <KEY> <VALUE> are encrypted at rest in .vstore/ci/secrets.enc and automatically scrubbed from captured step logs before provenance receipts are written.
  5. Retention Without Provenance Loss (vstore ci prune): vstore ci prune --keep-last 5 --keep-tagged reclaims gigabytes of older binary artifacts while permanently preserving lightweight .vstore/ci/runs/*.json cryptographic receipts.
BASH
# Configure external S3 or HTTPS artifact storage and encrypted secrets
vstore ci storage set s3://prod-release-artifacts/payments
vstore ci secret set SIGNING_ENDPOINT "https://kms.internal.example.org"

# Trigger automated verification and release packaging
vstore ci run --parallel -j 4
vstore ci verify

# Hydrate verified release artifacts onto a target deployment host
vstore clone wss://vcs.example.org:9418 ./deploy-target --view runtime --with-build latest

2. Multi-Developer Change Set Code Review Playbook

Teams can collaborate on pre-merge changesets across a Blind Zero-Knowledge Relay without opening long-lived feature branches or exposing plaintext source code to the hosting server:

  1. Author Creates & Publishes Change Set:
BASH
   vstore cs create ledger-reconcile -m "Add idempotent settlement reconciliation"
   vstore cs add ledger-reconcile services/ledger/reconcile.go services/ledger/reconcile_test.go
   vstore cs commit ledger-reconcile -m "Implement double-entry invariant checks"
   vstore cs push ledger-reconcile origin
  1. Reviewer Pulls, Audits & Approves:
BASH
   vstore cs pull ledger-reconcile origin
   vstore cs diff ledger-reconcile
   vstore cs approve ledger-reconcile
   vstore cs push ledger-reconcile origin
  1. Maintainer Lands Clean Linear Commit Under Quorum:
BASH
   vstore cs pull ledger-reconcile origin
   vstore cs merge ledger-reconcile -m "Land idempotent settlement reconciliation"
   vstore push origin main

3. Air-Gapped, Regulated & Zero-Trust Cloud Workflows

Use Case A: Untrusted Public Cloud Hosting (Zero-Knowledge SaaS Relay)

  • Challenge: Engineering teams want low-latency cloud replication across continents without granting cloud administrators or subpoenaed storage providers read access to proprietary algorithms, security patches, or roadmap branch names.
  • Solution: Initialize with vstore init --encrypt --obfuscate-refs and run vstore serve --blind --require-auth + vstore-web --blind on cloud VMs. Cloud disks hold only VSTOREN1 ciphertexts and HMAC-SHA256 ref tokens, while developers inspect repositories locally or via /zk WebCrypto in the browser.

Use Case B: Air-Gapped Defense & Financial Release Promotion

  • Challenge: Moving verified source snapshots and compiled release binaries across an air gap while proving 2-of-2 human review, deterministic CI execution, and zero history tampering.
  • Solution: Bundle .vstpack archives, .vstore/transparency.log, .vstore/attestations/, and .vstore/ci/artifacts/ onto read-only transfer media. On the high-side network, run vstore trust verify-log, vstore verify v1.0.0, and vstore ci verify entirely offline with zero external dependencies.

4. Migrating from Git (import-git & archive)

vstore provides built-in topological Git import and clean archive export:

BASH
# Initialize a new encrypted vstore repository and import existing Git history + tags
export VSTORE_PASSPHRASE="enterprise-migration-passphrase"
vstore init --encrypt --author "Migration Bot <releng@example.org>" ./migrated-repo
cd ./migrated-repo
vstore import-git /path/to/legacy-git-repo --branch main

# Export any snapshot or tag as a clean .zip source bundle without .vstore metadata
vstore archive v1.0.0 -o ./release-v1.0.0-src.zip --prefix service-1.0.0

5. Architectural Comparison with Other Version Control Systems

Capability vstore Git Jujutsu (jj) Pijul Fossil Mercurial (hg)
Object Hash Algorithm SHA-256 (native everywhere) SHA-1 default (SHA-256 opt-in) SHA-256 / Git backend BLAKE3 SHA3-256 / SHA-1 SHA-1
Client-Side Zero-Knowledge Encryption Built-in (Argon2id + AES-256-GCM) External plugins (git-crypt, age) External via backend None built-in None built-in External extensions
Branch/Ref Name Obfuscation Built-in (HMAC-SHA256 refs/zk/) Not supported Not supported Not supported Not supported Not supported
Blind Zero-Knowledge Server & Browser WebCrypto UI Built-in (--blind + /zk Vault) Not supported Not supported Not supported Server sees plaintext SQLite Server sees plaintext revlogs
Concurrent Same-Tree Workstreams Parallel Change Sets (vstore cs) Requires worktrees or stash Anonymous/named changes Commutative patches Branches / stash Shelve / MQ / topics
Sub-File Large Binary Deduplication Native Gear-CDC (.chunked $> 64\text{ KiB}$) Requires external Git LFS Via backend Line/byte patches Delta compression Largefiles extension
Automatic Commit Signatures & $M$-of-$N$ Quorums Native Ed25519 + FIDO2 + quorum.json Optional GPG/SSH; server forge rules Optional signing Ed25519 patch keys Optional PGP clearsign GPG extension
Tamper-Evident Merkle Transparency Log Native RFC 6962 Dual-Signed Log External (gittuf / Sigstore) Operation log (local) Patch set state Blockchain-like timeline Revlog append-only
Integrated Deterministic CI & Signed Artifacts Built-in (vstore-ci + 5 URI stores) External (GitHub Actions, GitLab CI) External External External External
Embedded Web Studio & JSON API Built-in (vstore-web binary) git instaweb (CGI legacy) Community GUIs Nest (hosted) Built-in (fossil ui) hg serve (read-only)

Part VI: vstore - Configuration, CLI & REST API Reference

Overview

This reference documents every command, subcommand, flag, environment variable, .vstore/ configuration file, and HTTP/JSON REST API endpoint across vstore, vstore-ci, and vstore-web.


1. Top-Level vstore CLI Reference

Command Syntax & Flags Description
help vstore help | -h | --help Prints top-level CLI usage and command summary.
version vstore version | -v | --version Prints semantic version (vstore 0.1.0).
init vstore init [-e|--encrypt] [-o|--obfuscate-refs] [-a|--author "<name>"] [path] Initializes .vstore/, generates Ed25519 signing keys, and configures optional encryption and ref obfuscation.
add vstore add <path>... Stages files or directories into .vstore/index (respecting .vstoreignore).
reset vstore reset [path]... Unstages specified paths or clears .vstore/index when called with no paths.
restore vstore restore <path>... [--source <commit>] [--staged] Restores working-tree files (or staged index entries with --staged) from HEAD or --source.
snapshot vstore snapshot -m "<msg>" [--amend] [--allow-coauthor] (alias: commit) Records an Ed25519-signed SHA-256 commit snapshot or amends HEAD.
status vstore status Reports active branch, remote ahead/behind counts, Sparse View, open Change Sets, staged/unstaged/untracked files, renames, and conflicts.
log vstore log [ref] [-n|--limit <N>] [-- <path>] Lists commit DAG history with Ed25519 verification status and Change Set provenance.
show vstore show [commit_or_tag] Displays full commit or annotated tag headers, signature status, and unified diff.
diff vstore diff [--staged|--cached] [-w|--worktree] [ref_a] [ref_b] [-- <path>...] Computes unified diffs across working tree, staging index, commits, or branches.
branch vstore branch [name] | -d <name> | -D <name> | -m <old> <new> Lists, creates, safely deletes (-d), force-deletes (-D), or renames (-m) local branches.
checkout vstore checkout <branch> [-b|--create] [-f|--force] [--ci-build <latest|id|none>] Switches active branch, updates working tree, and optionally hydrates verified CI artifacts.
merge vstore merge <branch> [--authoritative|--theirs] [-m "<msg>"] | --continue | --abort Performs a 3-way linear merge with provenance headers (Option 1A) or authoritative resolution (Option 1B).
tag vstore tag [-s|--sign] [-a|--annotate] [-m "<msg>"] [-c|--cosign] [-d <name>] [name] [commit] Lists, creates, signs, co-signs, or deletes repository tags.
release vstore release <create|list|backport> [version] [commit] [--branch] [-m "<msg>"] Creates signed v<version> tags and release/<major>.<minor> branches, lists releases, or backports commits.
verify vstore verify [commit_or_tag] Verifies Ed25519 signatures, Allowed Signers rules, revocations, and trust policy.
pack vstore pack [--packfile] [--prune] Compresses loose objects (VSTZ) or builds .vstpack/.vstidx binary packfiles (--packfile).
gc vstore gc [--grace <seconds>] [--packfile] Prunes unreachable objects older than --grace seconds and repacks reachable objects.
remote vstore remote [add <name> <url>] Lists remotes or configures <name> (ws://, wss://, http://, https://, ssh://).
fetch vstore fetch [remote] [branch] Downloads missing objects incrementally, audits remote Merkle log, and updates refs/remotes/<remote>/<branch>.
push vstore push [remote] [branch|tag] [-t|--tags] [-d|--delete <ref>] Streams missing objects as .vstpack, syncs governance & CI provenance, and updates remote refs.
pull vstore pull [remote] [branch] [-f|--force] [--with-build [latest|id]] Fetches, audits Merkle log, performs 3-way linear merge, and optionally hydrates CI build artifacts.
serve vstore serve [-p <port>] [--http] [--stdio] [-b|--blind] [-r|--require-auth] [-k <keys>] [--tls-cert <f> --tls-key <f>] [--auto-ci] Starts VSRP sync server over WebSocket/WSS, HTTP, or SSH stdio.
clone vstore clone <url> [path] [--view <name>] [--with-build [latest|id]] Clones remote repository, verifies Merkle Transparency Log, and unwraps wrapped_dek when encrypted.
reflog vstore reflog [-n|--limit <N>] Prints local reference transition log (.vstore/reflog.json).
undo vstore undo Rolls back the most recent local reference transition in .vstore/reflog.json.
import-git vstore import-git <git-dir> [-b|--branch <name>] Imports commits, trees, file modes, and tags from an existing Git repository.
archive vstore archive [ref] -o <output.zip> [--prefix <dir>] Exports tracked files at [ref] into a .zip archive without .vstore/ metadata.

2. Subsystem Commands (cs, view, trust, hook, alias, access, ci)

vstore cs (changeset)

Subcommand Syntax Purpose
list (ls) vstore cs list Lists open and merged Change Sets.
create (new) vstore cs create <name> [-m "<desc>"] Creates a Change Set anchored at HEAD.
add / rm vstore cs add <name> <path>... / vstore cs rm <name> [path]... Stages or unstages paths inside Change Set <name>.
commit vstore cs commit <name> -m "<msg>" [--allow-coauthor] Records a signed checkpoint commit inside <name>.
status / log / diff vstore cs <status|log|diff> <name> Inspects Change Set metadata, checkpoints, or combined diff against base.
shelve / unshelve vstore cs <shelve|unshelve> <name> Restores working tree to HEAD or re-applies <name>'s files.
approve vstore cs approve <name> Attaches a reviewer Ed25519 approval signature to <name>'s tip.
push / pull vstore cs push <name> [remote] / vstore cs pull [name] [remote] Syncs Change Set checkpoints and approvals with <remote>.
merge / delete vstore cs merge <name> [-m "<msg>"] [--authoritative] / vstore cs delete <name> [-f] Lands <name> linearly onto active branch or deletes metadata.

vstore view, vstore trust, vstore hook, vstore alias & vstore access

Subsystem Subcommands & Syntax
vstore view list, create <name> [-i "<globs>"] [-e "<globs>"] [-m "<desc>"] [-l|--lazy] [--ci-build <latest|id|none>], inspect [name] [-c <sha>], use <name|all>, clear, hydrate [remote], delete <name>
vstore trust status, policy [permissive|strict|head_only], allow "<id>" <pubkey> [-t ed25519|ed25519-sk] [--from <ts>] [--until <ts>], rm <pubkey>, revoke <pubkey> [-m "<reason>"], signer [-p internal|external] [-c "<cmd>"] [-k <pubkey>], vault-key, attest [sha|HEAD], log, verify-log, anchor [ref], quorum <list|set "<glob>" <min>|rm "<glob>">, sync [remote]
vstore hook list, install <pre-commit|post-commit|pre-push|pre-receive|update|post-receive> (-c "<cmd>" | -f <file>), rm <name>, run <name> [args...]
vstore alias list, set <short> "<expansion>", rm <short>
vstore access list, add -k <pubkey|*> -b "<branch-globs>" -p <read|write|admin|deny> [-a "<label>"]

vstore ci (and standalone vstore-ci)

Subcommand Syntax Purpose
run vstore ci run [targets...] [-f <pipeline>] [--parallel] [-j <N>] [--no-cache] [--no-attest] [--container-engine <docker|podman|nerdctl>] Executes pipeline DAG, signs provenance receipt, and publishes artifacts.
list / graph vstore ci list / vstore ci graph [targets...] [--mermaid] Lists declared tasks/artifacts or renders execution DAG.
runs / inspect vstore ci runs / vstore ci inspect <run-id|commit> Lists recorded build runs or prints full step/mount/artifact digests.
verify vstore ci verify [run-id|commit] Audits receipt Ed25519 signature, step chain, artifact hashes, and TLog entry.
fetch vstore ci fetch [latest|run-id|commit] [remote] Downloads, verifies, and decrypts linked build artifacts into workspace.
prune vstore ci prune [--keep-last <N>] [--keep-tagged] Prunes older binary artifacts while preserving run provenance JSON.
storage vstore ci storage [show | set <uri>] Configures vstore://, file://, https://, s3://, or scp:// store.
secret vstore ci secret <list | set <KEY> <VAL> | rm <KEY>> Manages AES-256-GCM encrypted CI secrets (.vstore/ci/secrets.enc).

3. vstore-web CLI Flags & Environment Variables

Flag / Env Var Default Description
-a, --addr, -H, --host <ip> 127.0.0.1 Listen address (127.0.0.1 by default; bind 0.0.0.0 with --tls-cert/--tls-key or reverse proxy).
-p, --port <port> 8080 HTTP/HTTPS TCP listen port (1..65535).
-r, --repo <path> . Target repository directory (also accepted as positional argument).
--blind, --zk false Forces Blind Zero-Knowledge Mode (zero keys in RAM; locks /api/v1/* and redirects plaintext views to /zk).
--enable-studio false Opt-in to authenticated mutating Studio API (POST /api/v1/*). Without this flag, vstore-web is strictly read-only.
--studio-token <token> auto-generated Bearer token required in Authorization: Bearer <token> for Studio API mutations (or set VSTORE_WEB_TOKEN).
--tls-cert <path> "" Path to PEM TLS certificate for native HTTPS termination (VSTORE_TLS_CERT).
--tls-key <path> "" Path to PEM TLS private key for native HTTPS termination (VSTORE_TLS_KEY).
--trust-proxy false Trust X-Forwarded-For / X-Real-IP headers from a reverse proxy (VSTORE_TRUST_PROXY=1).
--log-format <fmt> plain Access log format (plain or json, or VSTORE_LOG_FORMAT=json).
--passphrase <str> "" Unlocks encrypted repository for trusted local Studio browsing (prefer VSTORE_PASSPHRASE env var).
VSTORE_PASSPHRASE unset Supplies repository passphrase non-interactively to vstore, vstore-ci, or vstore-web.
VSTORE_AUTHOR unset Default author identity used by vstore init when --author is omitted.
VSTORE_RELEASE_SIGNING_KEY unset Persistent 32-byte hex Ed25519 seed (or file path) used by the release packaging pipeline to sign SHA256SUMS.txt.

4. .vstore/ Repository Configuration Schema

.vstore/config.json stores non-secret repository parameters alongside wrapped key metadata:

JSON
{
  "version": 1,
  "author": "Ada Lovelace <ada@example.org>",
  "encrypted": true,
  "obfuscate_refs": true,
  "kdf_salt": "a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "kdf_time": 3,
  "kdf_memory": 65536,
  "kdf_threads": 4,
  "wrapped_dek": "base64-encoded-vstoren1-envelope",
  "ci_storage_uri": "vstore://"
}

5. vstore-web HTTP & JSON REST API Reference

Read-Only Inspection & Zero-Knowledge Endpoints (GET / HEAD)

Endpoint Query Parameters Response Summary
GET /healthz, GET /api/health none {"status":"ok","version":"0.1.0","uptime_sec":...}
GET /readyz none {"status":"ready"} (verifies .vstore store directory accessibility; 503 if unavailable).
GET /metrics none Prometheus text exposition metrics (uptime, request/error/auth counters, active sessions).
GET /api/info none Repository encryption/blind flags, active branch, commit/branch/tag/changeset counts.
GET /api/branches, GET /api/tags, GET /api/releases none Branch tips, signed tag metadata, and logical release records.
GET /api/commits branch, search, page, limit Paginated commit summaries with Ed25519 verification flags.
GET /api/commit id=<64-hex> Full commit metadata, parents, Change Set provenance, signature, and detached attestations.
GET /api/tree commit, branch, path Directory entries (mode, name, hash, kind).
GET /api/blob id=<64-hex> Raw binary/UTF-8 blob payload (application/octet-stream).
GET /api/diff from, to, path Structured unified diff files and hunks.
GET /api/grep q, branch, path Matching file paths, line numbers, and snippets.
GET /api/status, GET /api/reflog limit (reflog) Working-tree status summary or reference transition entries.
GET /api/changesets, GET /api/changeset name (detail) Open/merged Change Sets and checkpoint metadata.
GET /api/views, GET /api/packs, GET /api/fsck none Sparse Workspace Views, .vstpack inventory, and live cryptographic fsck report.
GET /api/transparency, GET /api/quorum, GET /api/access none RFC 6962 Merkle Transparency Log audit report, quorum rules, and RBAC rules.
GET /api/ci/runs, GET /api/ci/run, GET /api/ci/secrets id (run detail) Recorded vstore-ci runs, step/artifact digests, and secret key names (values never exposed).
GET /api/zk/manifest none Encrypted KDF parameters, wrapped_dek, ref_catalog_b64, head_enc_b64, governance blobs, and TLog root for /zk WebCrypto.
GET /api/zk/object id=<64-hex> Base64-encoded raw storage envelope (VSTOREN1 ciphertext) for browser-side AES-256-GCM decryption.

Authenticated Studio Mutation Endpoints (POST /api/v1/*, Opt-In via --enable-studio)

By default, vstore-web runs in read-only mode and rejects all POST /api/v1/* requests with 403 Forbidden. When explicitly started with --enable-studio (and not in --blind mode), /api/v1/* routes enforce:

  • Authorization: Bearer <token> (constant-time verified against --studio-token / VSTORE_WEB_TOKEN or the startup-generated CSPRNG token)
  • Strict Content-Type: application/json and same-origin Origin/Host CSRF validation
  • Host-execution endpoints (/api/v1/hook/install, /api/v1/hook/run, /api/v1/trust/signer, /api/v1/ci/run) remain permanently disabled over HTTP (403 Forbidden) and must be run via the local vstore CLI.
  • Working Tree & Snapshots: /api/v1/stage, /api/v1/unstage, /api/v1/snapshot, /api/v1/restore, /api/v1/undo
  • Branches, Tags & Releases: /api/v1/branch/create, /api/v1/branch/checkout, /api/v1/branch/delete, /api/v1/branch/merge, /api/v1/tag/create, /api/v1/tag/delete, /api/v1/release/create
  • Parallel Change Sets: /api/v1/cs/create, /api/v1/cs/add, /api/v1/cs/commit, /api/v1/cs/shelve, /api/v1/cs/unshelve, /api/v1/cs/approve, /api/v1/cs/merge, /api/v1/cs/delete
  • Views, Storage & Remotes: /api/v1/view/create, /api/v1/view/use, /api/v1/view/clear, /api/v1/pack, /api/v1/gc, /api/v1/remote/add, /api/v1/remote/fetch, /api/v1/remote/push, /api/v1/remote/pull
  • Trust, Governance & CI Metadata: /api/v1/trust/policy, /api/v1/trust/allow, /api/v1/trust/revoke, /api/v1/trust/attest, /api/v1/trust/anchor, /api/v1/quorum/set, /api/v1/access/add, /api/v1/ci/secret/set, /api/v1/ci/prune

Part VII: vstore - Performance, Benchmarks & Capacity Sizing

Overview

vstore, vstore-ci, and vstore-web are compiled ahead-of-time to native machine code with zero garbage-collected VM startup penalty and zero external database dependencies. This guide documents storage deduplication ratios, SHA-256 + AES-256-GCM cryptographic throughput, .vstpack random-access lookup latency, DAG traversal scaling, and hardware sizing recommendations.


1. Subsystem Throughput & Latency Profile

Representative single-node measurements on a 4-core / 8-thread x86-64 workstation with NVMe SSD storage (Windows 11 and Linux 6.x -prod builds):

Operation Subsystem Mechanics Typical Latency / Throughput
SHA-256 Object Hashing & Framing Canonical <kind> <len>\0<body> digesting 480 - 650 MiB/s per core
Gear-CDC Content-Defined Chunking Rolling 64-bit Gear table scan for files $> 64\text{ KiB}$ (16 KiB min, 64 KiB avg, 256 KiB max) 520 - 700 MiB/s streaming
VSTOREN1 AES-256-GCM Sealing Per-object random 96-bit nonce + AAD = object_id + 128-bit authentication tag 390 - 540 MiB/s (< 6% wall-clock overhead vs. plaintext NVMe I/O)
Argon2id KEK Unwrap (init / unlock) 64 MiB memory-hard grid, t = 3 passes, p = 4 lanes (executed once per CLI/session unlock) 85 - 145 ms one-time session cost
.vstidx Packed Object Lookup 256-entry first-byte fanout table + binary search over sorted 32-byte digests + pread offset seek < 35 us for 100,000 packed objects ($O(\log N)$)
Ed25519 Commit Sign / Verify Deterministic RFC 8032 signature over canonical commit envelope ~0.06 ms sign / ~0.14 ms verify
DAG Ancestor & Reachability Walk Topological reachable_between bitset/hashset pruning during incremental push/fetch < 12 ms across 10,000 commits
3-Way LCS Diff & Line Blame Myers/LCS hunk diffing and parent-tree hash short-circuiting during blame < 8 ms for 2,000-line source files

2. Gear-CDC Deduplication & .vstpack Storage Efficiency

Traditional whole-blob storage writes an entirely new compressed copy whenever a single byte changes inside a large asset (for example, SQLite seed fixtures, PDF specifications, container layers, or media bundles). vstore eliminates this amplification automatically:

  1. Threshold Activation (> 64 KiB): Files $\le 64\text{ KiB}$ are stored directly as single blob objects to minimize metadata indirection. Files $> 64\text{ KiB}$ are split at content-defined Gear rolling-hash boundaries into variable-sized blob chunks referenced by a compact .chunked manifest.
  2. Localized Mutation Cost: Editing 4 KiB in the middle of a 50 MiB binary file produces only 1-2 new ~64 KiB chunks plus a ~40-kilobyte .chunked manifest, achieving > 99.5% deduplication across incremental snapshots without requiring external plugins like Git LFS.
  3. VSTZ Compression Before Encryption: Because ciphertext is indistinguishable from random noise and cannot be compressed after encryption, vstore applies VSTZ compression to raw canonical objects before sealing them with VSTOREN1 AES-256-GCM.
  4. .vstpack + .vstidx Compaction: Bundling 50,000 loose .vstore/objects/aa/bb... files into a single .vstpack eliminates filesystem inode fragmentation (especially NTFS 4 KiB cluster slack on Windows) and allows vstore push / vstore clone to stream contiguous ciphertext frames in a single network round-trip.

3. Encryption Overhead & Blind Server Advantages

Because all Argon2id key derivation, VSTZ compression, Gear-CDC chunking, and AES-256-GCM encryption happen on client workstations, running a central vstore serve --blind or vstore-web --blind server actually consumes less CPU and RAM than a traditional plaintext forge:

  • Zero Server KDF or Cipher CPU: A --blind relay never runs Argon2id, never decrypts payloads, and never decompresses trees to render server-side diffs.
  • Lightweight Server Verification: On push, a --blind relay verifies only the Ed25519 client challenge, checks .vstore/access.json RBAC and .vstore/quorum.json signature counts, validates .vstpack SHA-256 stream framing, and appends one 32-byte leaf to .vstore/transparency.log.

4. Production Capacity & Sizing Guidelines

Deployment Tier Team / Repo Scale Recommended CPU & RAM Storage & Maintenance Cadence
Solo / Small Team Blind Relay 1 - 15 engineers, < 5 GiB repo 1 - 2 vCPU, 512 MiB RAM SSD storage; run vstore pack --packfile weekly.
Mid-Size Engineering Org 15 - 150 engineers, 5 - 100 GiB monorepo + CI 4 vCPU, 4 GiB RAM (relay) + dedicated 8 vCPU vstore-ci runner NVMe SSD; external s3:// or https:// linked CI artifact URI + nightly vstore gc --packfile and vstore ci prune --keep-last 10 --keep-tagged.
Enterprise / Regulated Enclave 150+ engineers, strict 2-of-2 quorums & Sparse Views 8+ vCPU, 8 - 16 GiB RAM, active-passive ZFS/NVMe replication Clients clone with --view <role> to minimize workstation disk I/O; anchor Merkle Transparency Log roots hourly (vstore trust anchor).