The MyClerk Virtual File System: Distributed Storage for Family Networks

1.1. Requirements Language

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶

1.2. Terminology

Chunk

A fixed-size segment of file data, typically 4-16 MB, that forms the unit of storage, encryption, and distribution.¶

Fragment

One piece of an erasure-coded chunk. A chunk with k=3, m=2 produces 5 fragments.¶

Core Node

A storage node with high availability (>95% uptime over 30 days) that participates in guaranteed fragment storage.¶

Bonus Node

A storage node with variable availability that provides additional redundancy when online.¶

CRDT

Conflict-free Replicated Data Type. A data structure that can be replicated across multiple nodes and merged without conflicts.¶

LWW-Register

Last-Writer-Wins Register. A CRDT where concurrent writes are resolved by timestamp.¶

OR-Set

Observed-Remove Set. A CRDT that supports add and remove operations without conflicts.¶

2.1. Design Principles

• Zero Data Loss: Erasure coding ensures data survives multiple node failures.¶
• End-to-End Encryption: Only authorized users can read data; storage nodes see only ciphertext.¶
• Self-Healing: Automatic fragment redistribution when nodes fail.¶
• User-Friendly: Complex internals hidden behind simple folder interface.¶

4.1. Erasure Coding Profiles

The Standard profile with k=3, m=2 is RECOMMENDED for most use cases. It provides tolerance for two simultaneous node failures with reasonable storage overhead.¶

4.2. Fragment Distribution

Fragments MUST be distributed across different nodes to maximize fault tolerance. The distribution algorithm SHOULD:¶

• Place at least k fragments on Core Nodes¶
• Distribute fragments across different physical locations when possible¶
• Use Bonus Nodes for additional copies¶
• Avoid placing multiple fragments on the same node¶

5.1. Health Levels

5.2. Node Failure Escalation

When a node becomes unreachable, the following escalation timeline applies:¶

0-30 minutes

Ping retry with exponential backoff (10s, 30s, 90s). No status change or alerts.¶

30 minutes - 1 hour

Alert sent to family administrator: "Node XY unreachable".¶

1-6 hours

YELLOW status. System evaluates redistribution options and checks capacity on other nodes.¶

6-24 hours

Redistribution begins. Fragments are copied to available nodes. Priority: Critical > Standard > Economy. Bandwidth limit: 50% of available capacity.¶

>72 hours

Node downgrade: Core Node becomes Bonus Node. Fragments are no longer primarily placed on this node.¶

6.1. Hybrid CRDT Approach

The VFS employs a hybrid CRDT strategy:¶

• LWW-Register: Used for file content references, file attributes (size, mtime), and single-value fields.¶
• OR-Set: Used for directory entries, tag lists, and permission sets.¶

This combination provides optimal semantics for file system operations: LWW-Register ensures the latest file version wins, while OR-Set correctly handles concurrent file creation and deletion in directories.¶

6.2. LWW-Register Specification

The following CDDL [RFC8610] schema defines the LWW-Register structure. Values are encoded using CBOR [RFC8949].¶

lww-register<T> = {
    value: T,
    timestamp: uint,          ; Unix microseconds
    node-id: bstr .size 16,   ; Writer node ID
}

; Merge rule: Higher timestamp wins
; Tie-breaker: Lexicographically higher node-id wins

6.3. OR-Set Specification

or-set<T> = {
    elements: [* or-set-element<T>],
}

or-set-element<T> = {
    value: T,
    add-id: bstr .size 16,    ; Unique ID for this add operation
    removed: bool,            ; Tombstone flag
}

; Add: Create new element with unique add-id
; Remove: Set removed=true for all elements with matching value
; Merge: Union of all elements, removed flags propagate

6.4. File Metadata Structure

file-metadata = {
    id: bstr .size 16,                    ; Unique file ID
    name: lww-register<tstr>,             ; File name
    parent: lww-register<bstr .size 16>,  ; Parent directory ID
    content-hash: lww-register<bstr .size 32>, ; BLAKE3 hash
    size: lww-register<uint>,             ; File size in bytes
    mtime: lww-register<uint>,            ; Modification time
    chunks: lww-register<[* chunk-ref]>,  ; Chunk references
    tags: or-set<tstr>,                   ; User tags
    permissions: or-set<permission>,      ; Access permissions
}

chunk-ref = {
    hash: bstr .size 32,      ; BLAKE3 hash of chunk
    offset: uint,             ; Offset in file
    size: uint,               ; Chunk size
    ec-profile: tstr,         ; Erasure coding profile
}

permission = {
    principal: bstr .size 16, ; User or group ID
    access: uint,             ; Access flags (read, write, etc.)
}

6.5. Directory Metadata Structure

directory-metadata = {
    id: bstr .size 16,                    ; Unique directory ID
    name: lww-register<tstr>,             ; Directory name
    parent: lww-register<bstr .size 16>,  ; Parent directory ID
    children: or-set<bstr .size 16>,      ; Child file/directory IDs
    mtime: lww-register<uint>,            ; Modification time
    permissions: or-set<permission>,      ; Access permissions
}

7.1. Key Hierarchy

Keys are derived hierarchically using HKDF [RFC5869]:¶

Family Master Key (FMK)
    |
    +-- Folder Key: /family/photos/
    |       |
    |       +-- File Key: photo.jpg
    |               |
    |               +-- Chunk Key: a1b2c3...
    |
    +-- Folder Key: /family/documents/
    |
    +-- Session Keys (for Federation)

7.2. Key Derivation

folder_key = HKDF-SHA256(
    IKM  = family_master_key,
    salt = folder_id,
    info = "myclerk-vfs-folder-v0",
    L    = 32
)

file_key = HKDF-SHA256(
    IKM  = folder_key,
    salt = file_id,
    info = "myclerk-vfs-file-v0",
    L    = 32
)

chunk_key = HKDF-SHA256(
    IKM  = file_key,
    salt = chunk_index (4 bytes, big-endian),
    info = "myclerk-vfs-chunk-v0",
    L    = 32
)

7.3. Nonce Construction

Each encryption operation requires a unique 96-bit nonce:¶

 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                      Timestamp (32 bits)                      |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                       Random (32 bits)                        |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                      Counter (32 bits)                        |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

This construction provides collision probability less than 2^-80 per year at 1 million operations per second.¶

7.4. Content Hashing

All content is hashed using BLAKE3 [BLAKE3] for content addressing:¶

• Chunks: BLAKE3 hash of plaintext content¶
• Files: Merkle tree of chunk hashes¶

11.1. Basic Operations (0x0500-0x050F)

11.2. Chunk Operations (0x0510-0x051F)

11.3. Fragment Operations (0x0520-0x052F)

11.4. Metadata Operations (0x0530-0x053F)

11.5. Sharing Operations (0x0550-0x055F)

11.6. Emergency Operations (0x05C0-0x05CF)

12.1. Cache Security

Shared access uses time-limited tokens:¶

• Validity check interval: 10 minutes¶
• Offline tolerance: 1 hour¶
• Key rotation interval: 24 hours¶

Emergency Cut-Off immediately invalidates all tokens and keys.¶

13.1. Encryption

All data is encrypted with ChaCha20-Poly1305 before leaving the client. Storage nodes never see plaintext. Key compromise affects only the specific folder/file/chunk level in the hierarchy.¶

13.2. Nonce Handling

Nonce reuse with the same key completely compromises security. The timestamp+random+counter construction ensures collision probability below 2^-80 per year.¶

13.3. CRDT Security

CRDT operations are authenticated using the MyClerk Protocol's session keys. Unauthorized nodes cannot inject or modify metadata.¶

13.4. Federation Security

Federation uses separate session keys. Emergency Cut-Off can immediately revoke all access. Cached data becomes cryptographically inaccessible when keys are rotated.¶