Module versioned_files

Versioned file operations with Git-based version control for VPR.

VPR stores patient data as files on disk and versions each patient directory using a local Git repository (git2/libgit2). This module provides high-level services for managing versioned files, ensuring:

• Atomic Multi-file Operations: Write multiple files and commit them in a single transaction with automatic rollback on failure
• Consistent Commit Creation: Structured commit messages with controlled vocabulary across all services (clinical, demographics, coordination)
• Cryptographic Signing: ECDSA P-256 signatures with X.509 certificate validation
• Immutable Audit Trail: Nothing is ever deleted; all changes are preserved in version control history for patient safety and legal compliance

Purpose and Scope

This module is the core of VPR’s version control system. It centralises Git operations to ensure consistency and safety when modifying patient records. The VersionedFileService provides high-level operations that handle directory creation, file writing, Git commits, and automatic rollback on errors.

The module supports both signed (with X.509 certificates) and unsigned commits, with signature verification available for auditing purposes.

Architecture

The module provides four main components:

• File Operations: FileToWrite struct for describing atomic file write operations
• Repository Management: VersionedFileService for high-level Git operations
• Commit Messages: [VprCommitMessage] with structured domains and actions
• Cryptographic Signing: ECDSA P-256 signature creation and verification

Branch Policy

VPR standardises on refs/heads/main for all patient repositories.

libgit2’s commit_signed creates a commit object but does not update refs (no branch movement and no HEAD update). For signed commits, this module explicitly updates refs/heads/main and points HEAD to it to maintain proper branch state.

Signature Format

When Author.signature is present, VPR signs commits using ECDSA P-256.

• Signed payload: the unsigned commit buffer produced by Repository::commit_create_buffer
• Signature bytes: raw 64 bytes (r || s, not DER)
• Stored form: base64 of a deterministic JSON container passed to commit_signed and written into the commit header field gpgsig

The container embeds:

• signature: base64 of raw 64-byte r||s
• public_key: base64 of SEC1-encoded public key bytes
• certificate (optional): base64 of the certificate bytes (PEM or DER)

Safety and Immutability

VPR maintains an immutable audit trail where nothing is ever truly deleted. The [VprCommitAction] enum documents the four allowed operations (Create, Update, Superseded, Redact), all of which preserve historical data in version control. This design ensures patient safety, legal compliance, and complete accountability for all modifications to patient records.

The verifier in clinical code (ClinicalService::verify_commit_signature) expects this exact scheme.

Structs

FileToWrite

Service for common Git operations on a repository rooted at workdir.

VersionedFileService

Service for managing versioned files with Git version control.