> ## Documentation Index
> Fetch the complete documentation index at: https://docs.everabyte.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrating legacy files to zero-knowledge

> How existing server-encrypted files move to the zero-knowledge model — what the in-app migration does, what it preserves, and what it skips.

Files uploaded before an account adopted zero-knowledge encryption were encrypted **server-side** (the layered model in [Encryption architecture](https://docs.everabyte.com/security/encryption-architecture.md)): Everabyte's services held the ability to decrypt them. Moving such a file to zero-knowledge is a **re-encryption on a client** — the server cannot do it, because the point is for the plaintext to travel no further than the device performing the migration.

## How accounts get here

| Account | State | Path |
| - | - | - |
| Created **before 2026-11-13** | Zero-knowledge is opt-in | Enroll once (Settings → Security), then migrate files |
| Created **after 2026-11-13** | Zero-knowledge by default (`zkRequired`) | Uploads are client-encrypted from the start; files that slip through unencrypted (raw-API upload before enrollment) are **refused on download (403)** and swept after the grace window — see the [mandatory rule](https://docs.everabyte.com/sdk/overview.md#mandatory-for-new-accounts) |

## The in-app migration (recommended)

The web app's **Settings → Security → Client encryption** page provides the migration controls. For an enrolled account with the vault unlocked:

1. **Migrate legacy files** — walks your Drive (all buckets, folders at every level), and for each server-encrypted file: downloads the plaintext, encrypts it locally into `EVB1`, uploads the ciphertext under the opaque wire alias, attaches the fresh DEK envelope, moves user permissions and public links onto the new row, re-wraps the file key for each share recipient, then removes the legacy row.
2. **Encrypt existing file names** — retroactively aliases file names and stores their encrypted display names.
3. **Encrypt existing folder names** — same, for folders.

Migration preserves: folder placement, user permissions, public links (their permanent URLs keep resolving), pending share invitations, and version history being restarted on the new row's own timeline. Files that cannot be migrated safely are **skipped with a stated reason** rather than half-moved: files under an active retention hold (WORM), files shared at the *folder* level (scope handled at folder level), agent machine subfolders (owned by device manifests), and files sitting in trash (they purge on schedule). The results panel reports migrated / failed / skipped counts with reasons.

## Migration through the SDK (custom pipelines)

`POST /e2ee/files/:fileId/transfer-shares` and the `/e2ee/*` endpoints are API-key reachable, so a migration script follows the same five steps as the app:

1. `GET /files/{id}/stream` — download the server-encrypted plaintext (this is the last plaintext transit).
2. Encrypt locally: fresh DEK, `evb1_seal_all`, wire alias, encrypted name (`sdk/api-reference`).
3. `POST /files/upload/{bucketId}/{folderId}` — ciphertext under the wire alias, same folder.
4. `POST /e2ee/files/by-path/envelope` — attach the envelope **and** `encryptedName`.
5. `POST /e2ee/files/{legacyId}/transfer-shares { targetFileId }` — move permissions and links; then `DELETE /files/delete/{legacyId}?trash=hard`.

Step 4 failing means step 6 must not happen: delete the fresh copy and keep the legacy row (fail closed, never leave a dead ciphertext).

## What migration does *not* change

* **SSE stays for what remains.** Files that are not migrated keep the layered server-side encryption described in [Encryption architecture](https://docs.everabyte.com/security/encryption-architecture.md); the recovery phrase, retention, versions, sharing and the rest of the product are unaffected.
* **The backup agent's restore** works across both models: it resolves restored entries by file id and decrypts zero-knowledge entries locally when the device is enrolled.
* **Storage metrics** (quota, deduplication, version counts) are unchanged — the wire names and ciphertext occupy the same accounting.

## Frequently asked

**Does Everabyte ever see the plaintext during migration?**
Only in the same sense as any legacy download: step 1 is a download of a server-encrypted file, decrypted by Everabyte's server-side pipeline as it streams out — the exact disclosed path of the legacy model. From step 2 onward the bytes never leave your machine unencrypted.

**Can the server migrate files for me?**
No — that would require the plaintext to exist at Everabyte under zero-knowledge custody, which contradicts the model. Migration is client work by construction.

**What happens if the vault is locked?**
On zero-knowledge-default accounts, uploads block until you unlock; the migration controls likewise require the unlocked session. On legacy accounts, an upload while locked proceeds on the legacy path with an explicit notice.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.