AxiomVault

Private files first. Cloud sync second.

AxiomVault is an encrypted vault for people who want local-first control with optional cloud sync. It is built around client-side encryption, a zero-knowledge design goal, and a CLI-first workflow that can grow into desktop and mobile clients over time.

What AxiomVault is trying to be

AxiomVault aims to make a simple promise:

1. encrypt data on your device
2. keep cloud providers unaware of plaintext contents
3. let you move the same vault across machines without changing how it works

Today, the docs describe an early-development implementation centered on axiom-cli and the shared axiom-core Rust workspace.

Product snapshot

Why it exists

• Private by default — data is encrypted before it leaves your machine.
• Local-first workflow — the vault remains useful even without a cloud connection.
• Composable architecture — the same core is intended to serve CLI, sync, mount, and future client surfaces.
• Portable model — a vault should be understandable as a product, not tied to one storage vendor.

Start here

• Quickstart — create a vault, add a file, and run a first sync.
• Security — review the crypto model, trust assumptions, and safeguards.
• Threat Model — see which attackers and boundaries the design focuses on.
• Current Limitations — understand what is incomplete or risky today.
• MCP Status — see what MCP-related automation is and is not available today.
• YubiKey and Hardware Keys — see the current lack of hardware-key integration claims.
• Architecture — understand how axiom-cli and axiom-core fit together.
• Sync and Cloud — review current backend support and sync behavior.

Main capabilities in scope

• Local encryption before data touches cloud storage
• Vault lifecycle management from the CLI
• Encrypted file storage with a tree index
• Sync engine with conflict handling strategies
• Optional FUSE mount and WebDAV access layers
• Shared Rust core intended for reuse across clients
• No documented MCP integration today
• No documented YubiKey or hardware-key workflow today

Repository components

• axiom-cli — commands for creating, opening, mounting, and syncing vaults.
• axiom-core — shared Rust crates for crypto, storage, sync, FFI, WebDAV, and FUSE.

Current status

AxiomVault is in early development. Expect rough edges, format changes, incomplete hardening, and missing operational polish. These docs should help contributors and evaluators understand the direction of the project, not treat it as production-ready security guidance.

Quickstart

1. Install the CLI

curl -fsSL https://raw.githubusercontent.com/axiom-vault/axiom-cli/main/install.sh | bash

Other install paths include GitHub Releases, Homebrew, and building from source.

2. Create a vault

axiom vault create --name MyVault --path ~/my-vault

3. Add a file

axiom file add \
  --vault-path ~/my-vault \
  --source ~/secret.pdf \
  --dest /secret.pdf

4. Inspect contents

axiom file list --vault-path ~/my-vault

5. Extract a file

axiom file extract \
  --vault-path ~/my-vault \
  --source /secret.pdf \
  --dest ~/secret.pdf

6. Open an interactive session

axiom vault open --path ~/my-vault

Optional: enable sync

axiom sync run --vault-path ~/my-vault --strategy keep-both
axiom sync status --vault-path ~/my-vault

Optional: mount the vault

mkdir -p ~/my-vault-mount
axiom mount fuse --path ~/my-vault ~/my-vault-mount

Build from source

git clone https://github.com/axiom-vault/axiom-cli.git
cd axiom-cli
cargo build --release

CLI Usage

The axiom binary is the main operator interface for local vaults, remotes, sync, and mounts.

Vault commands

• axiom vault create
• axiom vault open
• axiom vault info
• axiom vault check
• axiom vault migrate

File commands

• axiom file list
• axiom file add
• axiom file extract
• axiom file mkdir
• axiom file remove

Password and recovery

• axiom password change
• axiom password reset
• axiom recovery show-key
• axiom recovery enable

Remotes

Google Drive

axiom remote gdrive auth --output ~/gdrive-tokens.json
axiom remote gdrive create \
  --name CloudVault \
  --folder-id YOUR_FOLDER_ID \
  --tokens ~/gdrive-tokens.json
axiom remote gdrive open \
  --folder-id YOUR_FOLDER_ID \
  --tokens ~/gdrive-tokens.json

Planned remotes

• iCloud
• Dropbox

Sync

axiom sync run --vault-path ~/my-vault --strategy keep-both
axiom sync status --vault-path ~/my-vault
axiom sync configure --vault-path ~/my-vault --mode periodic --interval 300

Mounts

• axiom mount webdav
• axiom mount fuse

KDF strength levels

--strength interactive
--strength moderate
--strength sensitive

Architecture

AxiomVault is split into a CLI and a shared Rust core.

Repositories in this workspace

axiom-cli

The CLI provides the user-facing commands for:

• Creating and opening vaults
• Adding and extracting files
• Authenticating remotes
• Running sync
• Mounting vaults over FUSE or WebDAV

axiom-core

The shared Rust workspace contains the underlying implementation.

Design goals

• Encrypt locally before remote storage
• Keep the system zero-knowledge
• Support multiple clients through a reusable core
• Separate transport and storage logic from vault semantics

Vault Format

A vault is organized around encrypted metadata, encrypted content, and an encrypted tree index.

Simplified layout

flowchart TD
    V[vault-root/] --> C[vault.config]
    V --> D[d/ encrypted content]
    V --> M[m/ metadata]
    M --> T[tree.json]

Directory sketch

vault-root/
├── vault.config
├── d/
└── m/
    └── tree.json

Components

• vault.config — encrypted metadata including salt, KDF parameters, and versioning
• d/ — encrypted file content
• m/tree.json — encrypted directory tree index

Operational notes

• File content is encrypted in chunks
• Directory and filename information is protected
• Integrity checks are part of the design, not a separate afterthought
• Layout details may evolve before the format is declared stable

Sync and Cloud

AxiomVault is designed to encrypt data before it touches cloud storage.

Current remote support

• Google Drive with OAuth2 and resumable uploads
• Local filesystem storage for offline or self-hosted workflows

Planned remote support

These are roadmap items, not current capabilities:

• iCloud
• Dropbox
• OneDrive

Sync behavior

The sync engine supports:

• On-demand sync runs
• Periodic background sync
• ETag-based conflict detection
• Conflict resolution strategies such as keep-both, prefer local, prefer remote, and manual handling
• Retry with exponential backoff

Simplified sync flow

flowchart LR
    L[Local plaintext changes] --> E[Encrypt locally]
    E --> V[Update local vault state]
    V --> S[Sync engine]
    S --> R[Remote encrypted objects]
    R --> S
    S --> C{Conflict detected?}
    C -- no --> D[Sync complete]
    C -- yes --> H[Apply selected resolution strategy]
    H --> D

Typical flow

axiom remote gdrive auth --output ~/gdrive-tokens.json
axiom sync run --vault-path ~/my-vault --strategy keep-both
axiom sync status --vault-path ~/my-vault

Caveats

• Sync correctness matters as much as encryption correctness for real users.
• Remote providers may differ in metadata, retry, and error behavior.
• Treat backend support as evolving until compatibility guarantees are documented.

Security

Important warning

AxiomVault is still in early development and is not production ready.

Security model

• Client-side encryption first
• Zero-knowledge architecture as a design goal
• Authenticated encryption on every chunk
• Chunk ordering protection
• Memory zeroization for key material
• Constant-time comparisons where appropriate
• No plaintext secrets in logs

Crypto and data protection

Trust assumptions

AxiomVault’s security depends on these assumptions:

• Build artifacts are produced from reviewed source.
• Rust’s memory safety guarantees hold outside explicitly-audited unsafe blocks.
• The underlying cryptographic primitives remain sound.
• The OS kernel and FUSE subsystem correctly enforce mount permissions.

Key hierarchy

flowchart TD
P[User password] --> A[Argon2id]
A --> PK[Password KEK]
PK --> WMK[Wrapped master key]
R[24-word recovery mnemonic] --> B[Blake2b context derivation]
B --> RK[Recovery KEK]
RK --> WMK
WMK --> MK[Master key in memory after unlock]
MK --> FK[Derived file and directory keys]

The master key is randomly generated and stored only in wrapped form. Two independent KEKs can unwrap it: one from the password and one from the recovery mnemonic.

File encryption

Files are encrypted using chunked streaming encryption. Each chunk is independently authenticated, and chunk indices are included in authenticated data to help detect reordering or truncation.

Security practices

• Dependency auditing with cargo audit
• Secret scanning with gitleaks
• Lint enforcement with cargo clippy -D warnings
• // SAFETY: comments for every unsafe block
• Zeroize and ZeroizeOnDrop on sensitive key material
• Constant-time comparisons for sensitive equality checks

What this page does not claim

This page describes the intended design and current implementation direction. It does not claim:

• an external security audit
• completed hardening across all platforms
• a stable long-term vault format guarantee
• safety against a compromised endpoint
• implemented MCP-based security controls
• implemented YubiKey or other hardware-key backed unlock flows

Related pages

• Threat Model
• MCP Status
• YubiKey and Hardware Keys
• Current Limitations

Supported versions

Only the latest release receives security patches.

Threat Model

Status

This threat model describes the intended security boundaries of AxiomVault in its current early-development state. It is not a claim of completed review, audit, or production hardening.

Security goals

AxiomVault is designed to reduce risk in these areas:

• Protect file contents before data is uploaded to a remote backend
• Prevent storage providers from learning plaintext file data
• Preserve integrity of encrypted chunks and vault metadata
• Allow recovery of the same master key through either a password-derived key or a recovery mnemonic

Assets to protect

• Master key
• Password-derived KEK
• Recovery-derived KEK
• Plaintext file contents
• Plaintext filenames and directory structure
• OAuth tokens or remote credentials
• Local vault configuration and sync state

Trust boundaries

flowchart LR
    U[User device] --> C[axiom-cli / axiom-core]
    C --> E[Local encrypted vault]
    C --> R[Remote backend]
    C --> M[Optional FUSE / WebDAV access]

    subgraph Trusted more
      U
      C
    end

    subgraph Trusted less
      R
      M
    end

Threats the design tries to address

Remote storage compromise

If a cloud provider account or backend is read without access to vault keys, the design intends that the attacker sees encrypted blobs and encrypted metadata rather than plaintext file contents.

Network or transport observation

AxiomVault assumes transport security still matters, but the main confidentiality control is local encryption before upload.

Chunk tampering or reordering

Chunk authentication and authenticated chunk ordering are intended to detect modified, truncated, or reordered encrypted content.

Accidental secret exposure in logs

The implementation aims to avoid plaintext secrets in logs and to zeroize sensitive key material where practical.

Threats not fully solved

Compromised endpoint

If the user device is already compromised while the vault is unlocked, malware, keyloggers, or memory inspection can still expose plaintext data or credentials.

Malicious or vulnerable dependencies

Client-side encryption does not protect against vulnerable build inputs, compromised packages, or malicious updates.

Unsafe access layers

FUSE and WebDAV improve usability, but they also increase the attack surface and rely on the host OS and surrounding tooling to enforce access controls correctly.

Out of scope assumptions

AxiomVault currently assumes:

• the operating system is enforcing file permissions correctly
• cryptographic primitives remain secure
• reviewed source matches shipped binaries
• users protect passwords, recovery phrases, and OAuth tokens

Open risks for an early project

• limited external review and no production audit claim
• possible vault format and sync behavior changes
• incomplete hardening around operational edge cases
• backend-specific bugs that may affect sync correctness or recovery workflows

See also

• Security
• Current Limitations
• Sync and Cloud

MCP Status

Current status

AxiomVault does not currently ship a documented Model Context Protocol (MCP) server, MCP client integration, or MCP-specific CLI workflow in this repository.

Today, the supported interface described by this mdBook is the regular command-line workflow in axiom-cli.

What is supported today

• Local CLI-driven vault operations
• Shared Rust core libraries used by the CLI and optional access layers
• Documentation for native commands, sync, vault format, and security boundaries

What is not supported today

The docs do not currently describe or promise:

• a first-party MCP server for exposing vault operations to external tools
• an MCP client for connecting AxiomVault to other MCP servers
• MCP-specific authentication, permission prompts, or sandbox policies
• a stable MCP API contract

Planned or future work

MCP-based tooling may be explored later, but this repository does not currently document an implemented MCP feature set. Until code and release notes exist, treat MCP support as not implemented.

Guidance for contributors and evaluators

If you need automation today, use the documented CLI directly and review the source before depending on behavior as an API contract.

See also

• Overview
• CLI Usage
• Current Limitations

YubiKey and Hardware-Key Status

Current status

AxiomVault does not currently document or claim implemented support for YubiKey, PIV/smartcard, FIDO2/WebAuthn, or other hardware-backed key workflows in this repository.

The current documented recovery and unlock model is:

• password-derived key encryption
• recovery mnemonic wrapping the same master key

What is supported today

• Password-based vault unlock
• Recovery via the documented mnemonic flow
• Software-based local key handling described in the current security pages

What is not supported today

The docs do not currently promise:

• YubiKey-backed vault unlock
• hardware-enforced key wrapping or unwrapping
• smartcard or PIV integration
• FIDO2/WebAuthn login or recovery flows
• resident-key, touch-policy, or PIN-policy integration

Security implications

Because hardware-backed key workflows are not currently documented as implemented, users should assume vault access depends on the host device, password handling, recovery phrase protection, and local operational security.

Hardware keys may become useful in the future for stronger local key protection or operator workflows, but that is not a current feature claim.

Guidance for contributors and evaluators

Avoid presenting AxiomVault as if it already has phishing-resistant or hardware-backed unlock guarantees. If hardware-key support is added later, the docs should describe the exact mechanism, platform coverage, failure modes, and recovery implications.

See also

• Security
• Threat Model
• Current Limitations

Current Limitations

Read this first

AxiomVault is not production ready. The project is still shaping its format, sync behavior, and operational model.

Product maturity limitations

• Early-development codebase with evolving architecture
• Documentation describes direction and current behavior, not a finished product contract
• Vault format details may change before a stable compatibility promise exists
• Security posture should be treated as promising but incomplete

Security and assurance limitations

• No claim of external security audit in these docs
• No claim of formal verification or hardened release process
• Endpoint compromise is still a major risk when a vault is unlocked
• Optional access layers such as FUSE or WebDAV expand the exposed surface area
• No current claim of YubiKey, smartcard, FIDO2, or other hardware-backed key protection

Platform and backend limitations

• Current remote support is limited to Google Drive and local filesystem workflows
• Planned providers such as iCloud, Dropbox, and OneDrive are not yet current capabilities
• No current MCP server or MCP client workflow is documented as a supported interface
• Cross-platform behavior may still vary as the CLI and shared core mature

Operational limitations

• Recovery, conflict handling, and sync edge cases need continued testing
• Background sync behavior depends on the surrounding client environment
• OAuth token handling and local secret storage should be reviewed carefully before broader deployment
• Observability, packaging, and installer polish are still incomplete

Documentation limitations

• Some pages describe intended design boundaries rather than battle-tested guarantees
• Diagrams are simplified and do not replace code-level review
• Newly added status pages for MCP and hardware keys are intentionally conservative and should not be read as feature promises
• These docs should help contributors and evaluators, not serve as a certification of readiness

Recommended use today

A reasonable current use case is:

• internal development
• architecture review
• contributor onboarding
• controlled experimentation with non-critical data

Avoid presenting AxiomVault as a finished consumer security product until the project has stable releases, stronger compatibility guarantees, and broader verification.