DLFS (Decentralised Lattice File System)

DLFS provides self-sovereign, decentralised file storage on Covia venues. Each user gets per-user drives that are cryptographically signed with their own Ed25519 key, stored in an independent lattice region, and portable across venues.

Key Properties

• User-signed — every write is signed by the user's own key, not the venue's
• Lattice-backed — drives use CRDT merge semantics for conflict-free cross-venue synchronisation
• Portable — users can migrate drives to another venue by exporting their key
• Isolated — DLFS occupies a separate lattice region from venue state; the venue operator cannot forge modifications

Drives

Each user can create and manage multiple named drives. A drive is a named file system root.

// Create a drive
{ "operation": "dlfs:createDrive", "input": { "name": "documents" } }

// List your drives
{ "operation": "dlfs:listDrives" }
// → { "drives": ["documents", "health-vault", "archive"] }

// Delete a drive and all its contents
{ "operation": "dlfs:deleteDrive", "input": { "name": "archive" } }

Drive creation is idempotent — creating the same drive twice succeeds without error. The first write to a drive also auto-creates it if needed.

File Operations

All file operations take a drive name and a path within that drive.

Reading Files

{ "operation": "dlfs:read", "input": { "drive": "documents", "path": "report.json" } }

Response:

{ "content": "{\"title\": \"Q1 Report\"...}", "encoding": "utf-8", "size": 2048 }

Text files are returned as UTF-8 strings. Binary files (images, PDFs) are returned as Base64-encoded strings with "encoding": "base64".

Writing Files

// Write inline text content
{
  "operation": "dlfs:write",
  "input": {
    "drive": "documents",
    "path": "report.json",
    "content": "{\"title\": \"Q1 Report\", \"status\": \"draft\"}"
  }
}

// Write from a Covia asset (for binary files)
{
  "operation": "dlfs:write",
  "input": {
    "drive": "documents",
    "path": "logo.png",
    "asset": "/a/0x7a8b9c0d..."
  }
}

Creates the file if absent, overwrites if it exists. Returns {written: <bytes>, created: <boolean>}.

Listing Directories

{ "operation": "dlfs:list", "input": { "drive": "documents", "path": "reports" } }

Response:

{
  "entries": [
    { "name": "q1-report.json", "type": "file", "size": 2048 },
    { "name": "q2-report.json", "type": "file", "size": 3100 },
    { "name": "attachments", "type": "directory" }
  ]
}

Omit path to list the drive root.

Creating Directories

{ "operation": "dlfs:mkdir", "input": { "drive": "documents", "path": "reports/2026" } }

Parent directories must already exist.

Deleting Files

{ "operation": "dlfs:delete", "input": { "drive": "documents", "path": "reports/draft.json" } }

Cannot delete non-empty directories — delete contents first.

Operations Reference

Operation	Input	Description
dlfs:listDrives	—	List all drives for the caller
dlfs:createDrive	name	Create a named drive (idempotent)
dlfs:deleteDrive	name	Delete a drive and all contents
dlfs:list	drive, path?	List directory entries
dlfs:read	drive, path	Read file content
dlfs:write	drive, path, content? or asset?	Write file content
dlfs:mkdir	drive, path	Create a directory
dlfs:delete	drive, path	Delete a file or empty directory

WebDAV

DLFS drives can be mounted as network file systems via WebDAV, enabling drag-and-drop access from native file managers and desktop applications.

Enabling WebDAV

WebDAV must be enabled in venue configuration:

{
  "webdav": { "enabled": true }
}

Endpoint

WebDAV is served at /dlfs/ on the venue:

https://your-venue.example.com/dlfs/{drive-name}/{path}

Standard WebDAV verbs are supported:

Verb	Example	Effect
GET	/dlfs/documents/report.json	Read file
PUT	/dlfs/documents/report.json	Write file
PROPFIND	/dlfs/documents/	List directory
MKCOL	/dlfs/documents/new-folder	Create directory
DELETE	/dlfs/documents/temp.txt	Delete file

Mounting

macOS Finder: Go > Connect to Server > https://your-venue.example.com/dlfs/documents

Windows Explorer: Map Network Drive > \\your-venue.example.com\dlfs\documents

CLI tools like rclone or cadaver can also connect via the WebDAV endpoint.

Security

Key Management

When a user first accesses DLFS, the adapter generates a unique Ed25519 keypair. The private key is encrypted and stored in the venue's secret store. Every operation on that user's drives is signed with this key.

Access Control

• Each user can only access their own drives
• The venue operator cannot modify a user's drives (modifications require the user's signature)
• Anonymous requests are rejected — all DLFS operations require authentication

Cross-Venue Portability

Because drives are signed by the user's key rather than the venue's:

1. Export the DLFS key seed
2. Import it on another venue
3. Access your drives unchanged

The venue cannot lock users in via cryptographic ownership.

Merge Semantics

DLFS uses timestamp-wins CRDT merge:

• When two venues modify the same file, the newest version wins
• Changes made offline are stored locally and sync when reconnected
• No manual conflict resolution — merging is automatic and deterministic

Related

• Vault — simplified DLFS wrapper for health vault access
• REST API — HTTP endpoints