Storage & encryption

The Data Portability Protocol encrypts user data before it leaves the Personal Server. This page covers how encryption keys are derived, how data is encrypted, where encrypted blobs are stored, and how multiple Personal Server instances stay in sync.

Key derivation

Encryption keys are deterministically derived from the user’s wallet signature. This means any Personal Server instance with the correct signature can decrypt the user’s data — no key exchange required.

Derivation chain

Wallet
  → EIP-191 personal_sign("vana-master-key-v1")
  → raw signature bytes (master key material)
  → HKDF-SHA256(master_key_material, "vana", "scope:{scope}")
  → 32-byte scope key
  → hex(scope_key) = encryption password

Step by step

Master key material. The user signs the fixed message "vana-master-key-v1" using EIP-191 personal_sign. The raw signature bytes become the master key material. This happens once — when the user first opens the Desktop App or when enabling ODL Cloud.
Scope key. For each scope, a 32-byte scope key is derived using HKDF-SHA256:
```
scope_key = HKDF-SHA256(
  ikm:  master_key_material,
  salt: "vana",
  info: "scope:{scope}"
)
```
For example, instagram.profile produces HKDF-SHA256(master_key_material, "vana", "scope:instagram.profile").
Encryption password. The scope key is hex-encoded to a 64-character string, which serves as the password for OpenPGP symmetric encryption.

Changing a scope name changes the derived key. If a scope is renamed, existing encrypted data for that scope cannot be decrypted with the new key. Keep scope names stable.

Key derivation stability

The derivation inputs are versioned and stable:

Signed message: "vana-master-key-v1" — the v1 suffix is a version marker.
HKDF salt: "vana" (fixed).
HKDF info: "scope:{scope}" (deterministic from scope name).

These inputs are part of the protocol specification. They will not change without a major protocol version bump. If a future version introduces a new derivation (e.g. v2), Personal Servers will support both versions during a migration window so existing encrypted data remains accessible. Builders do not manage encryption keys — the Personal Server and Desktop App handle all key derivation, encryption, and decryption internally. Builders read plaintext data from the Personal Server API; the encryption layer is transparent.

What the Personal Server needs

The Personal Server does not need the user’s wallet private key. It only needs the master key signature (the output of personal_sign). For desktop-bundled servers, the user signs on app open. For ODL Cloud, the signature is stored encrypted in the Sprite (see delegated signature).

Encryption

The protocol uses OpenPGP password-based symmetric encryption.

How it works

Take the plaintext JSON data file
Derive the scope key for the file’s scope
Hex-encode the scope key to get the encryption password
Encrypt the entire JSON as a single OpenPGP message using the password

The output is a standard OpenPGP binary message. No plaintext metadata is stored alongside the ciphertext — the entire file envelope (including scope, collectedAt, and data) is encrypted as one blob.

Encryption requirements by hosting option

Hosting option	Encrypted at rest?	Rationale
ODL Cloud (Vana-hosted)	Must encrypt	Blind infrastructure — Vana must not access plaintext
Desktop-bundled	May store unencrypted	User’s device is the security zone
Self-hosted	User’s choice	User controls the infrastructure

In all cases, data must be encrypted before uploading to a storage backend, and must be encrypted in transit (TLS 1.3).

Storage backends

Storage backends hold encrypted data blobs. The Personal Server encrypts data before upload and decrypts on download — the backend never sees plaintext. Users select one storage backend for all their data (per-user, not per-file). The selection is made during Desktop App setup and stored in ~/.vana/server.json. Until a backend is selected, the Personal Server operates in local-only mode with no remote storage or DataRegistry writes.

Available backends

Backend	URL format	Notes
Vana Storage (default)	`https://storage.vana.com/v1/blobs/{owner}/{scope}/{collectedAt}`	Managed by Vana, zero-config
Google Drive	`gdrive://{fileId}`	User authorizes via OAuth
Dropbox	`dropbox://{path}`	User authorizes via OAuth
IPFS	`ipfs://{cid}`	Content-addressed, immutable

Backend requirements

Every storage backend must:

Accept only encrypted blobs
Authenticate requests (verify the requester is authorized)
Support hierarchical key format
Return a canonical URL after upload

Backend interface

interface StorageBackend {
  upload(key: string, data: Uint8Array): Promise<string>;
  download(url: string): Promise<Uint8Array>;
  delete(url: string): Promise<boolean>;
  exists(url: string): Promise<boolean>;
  deleteScope?(scope: string): Promise<number>;
  deleteAll?(): Promise<number>;
}

New storage backends can be added by implementing this interface.

Server configuration

Storage backend selection and OAuth tokens are stored in ~/.vana/server.json:

{
  "version": "1.0",
  "server": {
    "address": "0x...",
    "url": "https://user-abc.server.vana.com",
    "capabilities": {
      "mcp": true,
      "compute": true
    }
  },
  "storage": {
    "backend": "vana",
    "config": {},
    "oauth": {
      "gdrive": { "accessToken": "...", "refreshToken": "...", "expiresAt": "..." },
      "dropbox": { "accessToken": "...", "refreshToken": "...", "expiresAt": "..." }
    }
  },
  "sync": {
    "lastProcessedTimestamp": "2026-01-21T10:00:00Z"
  }
}

The backend field accepts: vana, gdrive, dropbox, ipfs, or local.

Data flow

When new data is collected:

Data Connector collects data from a platform
Desktop App sends raw data to the Personal Server via POST /v1/data/{scope}
Personal Server stores the data locally (unencrypted) at ~/.vana/data/{scope}/
Personal Server encrypts the data with the scope key
Encrypted blob is uploaded to the storage backend
File record is registered in the DataRegistry via the Gateway (with schemaId)

If no storage backend is selected, steps 4-6 are skipped and data remains local-only.

Data sync

When a user has multiple Personal Server instances (e.g. desktop-bundled + ODL Cloud), they stay in sync through the storage backend and Data Registry. The storage backend is the source of truth for encrypted data; each Personal Server maintains a local decrypted copy.

How sync works

Each Personal Server polls the Gateway for new file records using a lastProcessedTimestamp cursor:

GET /v1/files?user={address}&since={lastProcessedTimestamp}

For each new file record:

Download the encrypted blob from the storage backend
Resolve the schemaId to the canonical scope (via GET /v1/schemas/{schemaId})
Derive the scope key and decrypt
Read scope and collectedAt from the decrypted payload
Store locally at ~/.vana/data/{scope}/{collectedAt}.json
Update the local index (fileId → path, scope, collectedAt)

First activation

When a Personal Server starts for the first time (e.g. when a user enables ODL Cloud), it runs a full backfill:

Query the Gateway for all file records for the user
Download, decrypt, and index each file
Set lastProcessedTimestamp to the most recent record

Conflict resolution

If two instances write to the same scope concurrently, the last-write-wins strategy applies based on the collectedAt timestamp in the payload.

Sync API (internal)

The Personal Server exposes internal sync endpoints:

Method	Path	Description
`POST`	`/v1/sync/trigger`	Force a sync from the storage backend
`GET`	`/v1/sync/status`	Get sync status (last sync, pending files, errors)
`POST`	`/v1/sync/file/{fileId}`	Sync a specific file from the storage backend

Before storage backend selection

Until the user selects a storage backend, sync is disabled. Data exists only on the local Personal Server instance, and no DataRegistry writes occur.

Data deletion

DataRegistry file entries are immutable — you cannot remove a record from the chain. Deletion is implemented as:

Delete the encrypted blob from the storage backend
Remove the local decrypted copy
Write a tombstone / delete marker via the Gateway

Personal Servers treat tombstoned file records as non-existent and return 410 Gone or 404 Not Found.

Data deletion is user-initiated only. Builders cannot delete user data.

Personal Servers — Where data is stored and served
Scopes & Schemas — Data taxonomy and file format
Grants & Permissions — Access control for stored data

Overview

Protocol reference

Network

Resources

Key derivation

Derivation chain

Step by step

Key derivation stability

What the Personal Server needs

Encryption

How it works

Encryption requirements by hosting option

Storage backends

Available backends

Backend requirements

Backend interface

Server configuration

Data flow

Data sync

How sync works

First activation

Conflict resolution

Sync API (internal)

Before storage backend selection

Data deletion

Overview

Protocol reference

Network

Resources

Documentation Index

​Key derivation

​Derivation chain

​Step by step

​Key derivation stability

​What the Personal Server needs

​Encryption

​How it works

​Encryption requirements by hosting option

​Storage backends

​Available backends

​Backend requirements

​Backend interface

​Server configuration

​Data flow

​Data sync

​How sync works

​First activation

​Conflict resolution

​Sync API (internal)

​Before storage backend selection

​Data deletion

​Related

Key derivation

Derivation chain

Step by step

Key derivation stability

What the Personal Server needs

Encryption

How it works

Encryption requirements by hosting option

Storage backends

Available backends

Backend requirements

Backend interface

Server configuration

Data flow

Data sync

How sync works

First activation

Conflict resolution

Sync API (internal)

Before storage backend selection

Data deletion

Related