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 first initializes the web Personal Server.
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), which the user produces when they first open the desktop app or initialize the web Personal Server. Because every Personal Server form runs client-side — bundled in the desktop app or in a browser tab — this signature stays on the user’s own device.

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

Personal Server form	Local copy encrypted at rest?	Rationale
Desktop-bundled	May store unencrypted	The user’s device is the security zone
Web (browser tab)	Held in the browser (IndexedDB) on the user’s device	The user’s device is the security zone
Self-hosted	User’s choice	The user controls the infrastructure

The local working copy lives on the user’s own device in every form. 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, and has no ability to decrypt what it stores. 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}`	Hosted default backend on Cloudflare R2; zero-config. Stores encrypted blobs only — it never decrypts and holds no keys to do so
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 DP RPC (with schemaId)

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

Data sync

When a user runs more than one Personal Server instance (e.g. the desktop app on two machines, or desktop plus the web browser tab), 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 DP RPC 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. on a new device, or the first time the web Personal Server loads), it runs a full backfill:

Query the DP RPC 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

Deleting a scope’s data is user-initiated, and what it removes today depends on the deployment:

Local data is removed. The Personal Server deletes the on-disk blobs and index rows for the scope from the user’s device.
Remote copies are not yet removed on the current (DPv2) gateway. There is no data-point deregistration or deletion endpoint yet, so the remote data-point records and the encrypted blobs in the storage backend remain in place until that API ships. They stay encrypted under the user’s key — the storage backend cannot read them — but they are not erased. (Deleting the blob alone would leave the data point listed and wedge other servers’ sync, so the current behavior is deliberately a local-only delete.)

Records anchored on-chain (e.g. grant history) are immutable and cannot be removed from the chain.

Data deletion is user-initiated only — builders cannot delete user data. A remote deletion / deregistration API for DPv2 is planned; until it ships, deletion removes the local copy but not the remote encrypted copy.

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

Applications

Security

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

​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