Skip to content

v0.md

Latest commit

 

History

History
555 lines (370 loc) · 6.42 KB

v0.md

File metadata and controls

555 lines (370 loc) · 6.42 KB

VaultRS Architecture & Repository Design

Vision

VaultRS is an encrypted embedded storage engine written in Rust.

It is not:

  • A notes app
  • A password manager
  • A database server

Instead, it is a local-first encrypted data engine that allows applications to securely store arbitrary records inside a single binary vault.

Applications built on top may include:

  • Notes applications
  • Knowledge bases
  • Secret managers
  • Research databases
  • SVG libraries
  • Offline project managers

The vault engine itself remains application-agnostic.

High-Level Architecture

┌─────────────────────────┐
│ Applications            │
│                         │
│ Notes App               │
│ CLI                     │
│ Desktop UI              │
│ SDKs                    │
└──────────┬──────────────┘
           │
           ▼
┌─────────────────────────┐
│ Vault Core API          │
└──────────┬──────────────┘
           │
           ▼
┌─────────────────────────┐
│ Storage Layer           │
│ Crypto Layer            │
│ Index Layer             │
│ Serialization Layer     │
└──────────┬──────────────┘
           │
           ▼
┌─────────────────────────┐
│ vault.vlt              │
└─────────────────────────┘

Repository Structure

vaultrs/

├── Cargo.toml
├── Cargo.lock
│
├── apps/
│   ├── cli/
│   ├── desktop/
│   └── examples/
│
├── crates/
│   ├── vault-core/
│   ├── vault-storage/
│   ├── vault-crypto/
│   ├── vault-index/
│   ├── vault-types/
│   ├── vault-search/
│   ├── vault-compression/
│   └── vault-sdk/
│
├── docs/
│   ├── architecture/
│   ├── file-format/
│   └── api/
│
├── tests/
│
├── benches/
│
└── scripts/

Crate Responsibilities

vault-types

Shared data structures.

Contains:

Record
VaultHeader
Page
Collection
Tag
Metadata

No business logic.

Only definitions.

vault-core

Main public API.

Applications interact only with this crate.

Example:

let vault = Vault::open(...);

vault.put(...);

vault.get(...);

This crate orchestrates:

  • storage
  • encryption
  • indexing

without exposing internals.

vault-storage

Responsible for:

  • page allocation
  • page reuse
  • fragmentation
  • compaction

The storage engine never understands notes or SVGs.

It only understands bytes.

vault-crypto

Responsible for:

  • password handling
  • key derivation
  • encryption
  • integrity verification

Provides:

encrypt()
decrypt()
derive_key()

Nothing else.

vault-index

Responsible for:

Record ID
→
Page Location

Acts similarly to a database index.

Used for:

  • lookups
  • listings
  • traversal

vault-search

Future crate.

Will contain:

  • tokenization
  • search indexes
  • ranking

Excluded from V1.

vault-compression

Future crate.

Provides:

  • page compression
  • blob compression

Excluded from V1.

Vault File Format

Extension:

.vlt

Example:

myvault.vlt

File Layout

┌──────────────┐
│ Header       │
├──────────────┤
│ Index Pages  │
├──────────────┤
│ Data Pages   │
├──────────────┤
│ Metadata     │
└──────────────┘

Everything except the header is encrypted.

Header Structure

pub struct VaultHeader {
    magic: [u8; 8],
    version: u32,
    page_size: u32,
    salt: [u8; 32],
}

Example:

VLTDB001

Used to verify file integrity.

Record Model

Everything is a record.

pub struct Record {
    id: Uuid,
    collection: String,
    kind: String,
    metadata: Metadata,
    payload: Vec<u8>,
}

Examples:

kind=text
kind=svg
kind=json
kind=binary

Storage engine doesn't care.

Collections

Collections are logical containers.

Example:

Projects
Research
Personal
Work

Each collection contains records.

Collections are metadata only.

Write Flow

Application
↓
Serialize Record
↓
Encrypt Record
↓
Allocate Page
↓
Write Page
↓
Update Index
↓
Commit

Read Flow

Application
↓
Lookup ID
↓
Locate Page
↓
Read Page
↓
Decrypt
↓
Deserialize
↓
Return Record

Update Flow

Locate Record
↓
Create New Page
↓
Write Updated Data
↓
Update Index
↓
Mark Old Page Stale

This avoids corruption.

Delete Flow

Locate Record
↓
Remove Index Entry
↓
Mark Page Free

Future compaction reclaims space.

Page System

Storage is page-based.

Example:

Page Size = 4KB

Large documents span multiple pages.

Benefits:

  • efficient reads
  • efficient writes
  • scalable growth

V1 Features

Create Vault

Open Vault

Close Vault

Store Record

Read Record

Update Record

Delete Record

List Records

Collections

Password Protection

Single Binary File

V1 Exclusions

No Search

No Sync

No Networking

No Cloud

No Teams

No Attachments

No Compression

No SDK Bindings

No Rich Text

No Version History

CLI

Commands:

vault create

vault open

vault put

vault get

vault delete

vault list

vault collections

The CLI becomes the reference implementation.

Future Architecture

V2

Search Engine

Tag System

Attachments

Compression

V3

Node SDK

Go SDK

Swift SDK

WASM SDK

V4

Desktop Applications

macOS

Windows

Linux

V5

Optional Sync Layer

Self-hosted only

Still encrypted end-to-end

Design Philosophy

The vault engine is not a notes application.

The vault engine is infrastructure.

Applications should depend on the engine.

The engine should never depend on applications.

This allows a single encrypted storage format to power multiple products while maintaining one trusted codebase for storage, indexing, and security.