koenvanderveen · Oct 26, 2026 · Oct 7, 2026 · Oct 7, 2026 · Oct 7, 2026 · Oct 8, 2026
diff --git a/docs/connections.md b/docs/connections.md
@@ -48,6 +48,25 @@ Syft uses Google Drive as its file-based transport layer. All peer-to-peer commu
 
 ---
 
+## Encryption Policy
+
+Each client advertises an encryption policy in `SYFT_version.json`:
+
+| Policy     | Set with                                     | Effect                                    |
+| ---------- | -------------------------------------------- | ----------------------------------------- |
+| `optional` | default on a new SyftBox, `encryption=False` | encrypt only with a peer that requires it |
+| `required` | `encryption=True`                            | encrypt with every peer; refuse plaintext |
+
+A pair encrypts when one side is `required`.
+
+A SyftBox has one policy, kept in `<syftbox>/<email>/private/syft_settings.json`. The first client to start on a new SyftBox writes it: the `encryption` it logged in with, or `optional`. A later client, the notebook or syft-bg, logs in without `encryption` and gets the policy on disk. A client that asks for another policy raises `EncryptionPolicyMismatchError`, and so does a running client at its next sync when the file changed under it. Files at rest are read with the current policy, so to change the policy, delete the SyftBox (`client.delete_syftbox()`) and log in again. `syft-bg init --encryption ...` sets the policy the same way as a login.
+
+Nothing is sent to a peer until its policy is known, that is, until it accepts and shares its version file. A scientist's change for a peer whose policy or bundle is not known is dropped, and the send raises. An owner's send to that peer raises, and the change stays pending, so a later sync sends it. An owner keeps a message it cannot read yet in the inbox, with a warning.
+
+The format of a message must match the pair: plaintext in a pair that encrypts is refused, and so is an envelope in a pair that does not. The owner archives such a message unread, and a scientist skips it, each with a warning.
+
+A peer whose version file has no policy, written by a syft older than `PeerInfo`, counts as `optional`. A peer whose version file is not read yet has a policy that is not known: nothing is exchanged with it.
+
 ## Peer Requests
 
 DS creates inbox/outbox folders on their own drive and grants the DO write access. The DO discovers these folders by searching for `syft_datasite#{my_email}#` folders they don't own.

diff --git a/notebooks/ai_audit/internal/DO_Tutorial_V3.ipynb b/notebooks/ai_audit/internal/DO_Tutorial_V3.ipynb
@@ -858,6 +858,7 @@
     "\n",
     "syft_bg.init(\n",
     "    do_email=DO_EMAIL,\n",
+    "    encryption=False,\n",
     "    token_path=str(TOKEN_PATH),\n",
     "    settings=settings,\n",
     ")\n"

diff --git a/notebooks/ai_audit/internal/test_email_e2e.ipynb b/notebooks/ai_audit/internal/test_email_e2e.ipynb
@@ -195,6 +195,7 @@
    "source": [
     "syft_bg.init(\n",
     "    do_email=DO_EMAIL,\n",
+    "    encryption=False,\n",
     "    token_path=do_token_path,\n",
     "    settings={\n",
     "        \"email_approve\": {\"gcp_project_id\": GCP_PROJECT_ID},\n",

diff --git a/notebooks/ai_audit/internal/test_multiple_clients.ipynb b/notebooks/ai_audit/internal/test_multiple_clients.ipynb
@@ -228,6 +228,7 @@
    "source": [
     "syft_bg.init(\n",
     "    do_email=DO_EMAIL,\n",
+    "    encryption=False,\n",
     "    token_path=str(DO_TOKEN),\n",
     "    settings={\n",
     "        \"email_approve\": {\"gcp_project_id\": GCP_PROJECT_ID},\n",
@@ -363,6 +364,7 @@
     "syft_bg.reset()\n",
     "syft_bg.init(\n",
     "    do_email=DO_EMAIL,\n",
+    "    encryption=False,\n",
     "    token_path=str(DO_TOKEN),\n",
     "    settings={\n",
     "        \"email_approve\": {\"gcp_project_id\": GCP_PROJECT_ID},\n",

diff --git a/notebooks/ai_audit/internal/test_syft_bg.ipynb b/notebooks/ai_audit/internal/test_syft_bg.ipynb
@@ -217,6 +217,7 @@
    "source": [
     "syft_bg.init(\n",
     "    do_email=DO_EMAIL,\n",
+    "    encryption=False,\n",
     "    token_path=do_token_path,\n",
     "    settings={\n",
     "        \"email_approve\": {\"gcp_project_id\": GCP_PROJECT_ID},\n",
@@ -282,7 +283,7 @@
    "outputs": [],
    "source": [
     "syft_bg.reset()\n",
-    "syft_bg.init(do_email=DO_EMAIL, token_path=do_token_path)\n",
+    "syft_bg.init(do_email=DO_EMAIL, encryption=False, token_path=do_token_path)\n",
     "\n",
     "syft_bg.ensure_running(services=[\"email_approve\"])\n",
     "time.sleep(3)  # wait for subprocess to fail\n",
@@ -309,7 +310,7 @@
    "outputs": [],
    "source": [
     "syft_bg.reset()\n",
-    "syft_bg.init(do_email=DO_EMAIL, token_path=do_token_path,\n",
+    "syft_bg.init(do_email=DO_EMAIL, encryption=False, token_path=do_token_path,\n",
     "             settings={\"email_approve\": {\"gcp_project_id\": GCP_PROJECT_ID}})\n",
     "\n",
     "SERVICES = [\"sync\", \"notify\", \"approve\"]\n",
@@ -447,6 +448,7 @@
     "syft_bg.reset()\n",
     "syft_bg.init(\n",
     "    do_email=DO_EMAIL,\n",
+    "    encryption=False,\n",
     "    token_path=do_token_path,\n",
     "    settings={\n",
     "        \"email_approve\": {\"gcp_project_id\": GCP_PROJECT_ID},\n",
@@ -679,7 +681,7 @@
     "bad_token = Path(tempfile.mktemp(suffix=\".json\"))\n",
     "bad_token.write_text(json.dumps({\"invalid\": True}))\n",
     "\n",
-    "syft_bg.init(do_email=DO_EMAIL, token_path=str(bad_token),\n",
+    "syft_bg.init(do_email=DO_EMAIL, encryption=False, token_path=str(bad_token),\n",
     "             settings={\"email_approve\": {\"gcp_project_id\": GCP_PROJECT_ID}})\n",
     "\n",
     "syft_bg.ensure_running(services=[\"sync\"])\n",

diff --git a/notebooks/enclave/double-blind-eval-w-receipts/1. DO-benchmark-owner-dbe.ipynb b/notebooks/enclave/double-blind-eval-w-receipts/1. DO-benchmark-owner-dbe.ipynb
@@ -102,13 +102,18 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "CRYPTO_KEYS_PATH = None\n",
-    "# NOTE: Re-storing Private Key from local_file, if you have it, uncomment the following line and upload the file.\n",
+    "KEY_FILE = None\n",
+    "# To restore the encryption key of an earlier session, uncomment the next two lines and upload crypto_keys.json.\n",
     "# from google.colab import files; files.upload()\n",
-    "# CRYPTO_KEYS_PATH = \"crypto_keys.json\"\n",
+    "# KEY_FILE = \"crypto_keys.json\"\n",
     "\n",
-    "benchmark_owner = login_do(encryption=True, crypto_keys_path=CRYPTO_KEYS_PATH)\n",
-    "print(f\"  Benchmark owner : {benchmark_owner.email}\")"
+    "benchmark_owner = login_do(key_file=KEY_FILE)\n",
+    "print(f\"  Benchmark owner : {benchmark_owner.email}\")\n",
+    "\n",
+    "# First login: back up the encryption key. It lives only on this runtime's filesystem.\n",
+    "if KEY_FILE is None:\n",
+    "    from google.colab import files\n",
+    "    files.download(str(benchmark_owner.syftbox_folder / benchmark_owner.email / \"private\" / \"crypto_keys.json\"))"
    ]
   },
   {
@@ -119,7 +124,7 @@
    "source": [
     "# # Optionally, to start from a clean SyftBox\n",
     "# benchmark_owner.delete_syftbox()\n",
-    "# benchmark_owner._rds.peer_manager.write_own_version()"
+    "# benchmark_owner._rds.peer_manager.write_own_peer_info()"
    ]
   },
   {

diff --git a/notebooks/enclave/double-blind-eval-w-receipts/2. DO-model-owner-dbe.ipynb b/notebooks/enclave/double-blind-eval-w-receipts/2. DO-model-owner-dbe.ipynb
@@ -100,13 +100,18 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "CRYPTO_KEYS_PATH = None\n",
-    "# NOTE: Re-storing Private Key from local_file, if you have it, uncomment the following line and upload the file.\n",
+    "KEY_FILE = None\n",
+    "# To restore the encryption key of an earlier session, uncomment the next two lines and upload crypto_keys.json.\n",
     "# from google.colab import files; files.upload()\n",
-    "# CRYPTO_KEYS_PATH = \"crypto_keys.json\"\n",
+    "# KEY_FILE = \"crypto_keys.json\"\n",
     "\n",
-    "model_owner = login_do(encryption=True, crypto_keys_path=CRYPTO_KEYS_PATH)\n",
-    "print(f\"  Model owner : {model_owner.email}\")"
+    "model_owner = login_do(key_file=KEY_FILE)\n",
+    "print(f\"  Model owner : {model_owner.email}\")\n",
+    "\n",
+    "# First login: back up the encryption key. It lives only on this runtime's filesystem.\n",
+    "if KEY_FILE is None:\n",
+    "    from google.colab import files\n",
+    "    files.download(str(model_owner.syftbox_folder / model_owner.email / \"private\" / \"crypto_keys.json\"))"
    ]
   },
   {
@@ -117,7 +122,7 @@
    "source": [
     "# # Optionally, to start from a clean SyftBox\n",
     "# model_owner.delete_syftbox()\n",
-    "# model_owner._rds.peer_manager.write_own_version()"
+    "# model_owner._rds.peer_manager.write_own_peer_info()"
    ]
   },
   {

diff --git a/notebooks/enclave/gemma/colab-3-persona/1. DO-model-owner-gemma-restrict.ipynb b/notebooks/enclave/gemma/colab-3-persona/1. DO-model-owner-gemma-restrict.ipynb
@@ -125,7 +125,7 @@
    "source": [
     "# # Optionally to clear state\n",
     "# model_owner._manager.delete_syftbox()\n",
-    "# model_owner._manager.peer_manager.write_own_version()"
+    "# model_owner._manager.peer_manager.write_own_peer_info()"
    ]
   },
   {

diff --git a/notebooks/enclave/gemma/colab-3-persona/2. DO-benchmark-owner-gemma-restrict.ipynb b/notebooks/enclave/gemma/colab-3-persona/2. DO-benchmark-owner-gemma-restrict.ipynb
@@ -98,7 +98,7 @@
    "source": [
     "# # Optionally to clear state\n",
     "# benchmark_owner._manager.delete_syftbox()\n",
-    "# benchmark_owner._manager.peer_manager.write_own_version()"
+    "# benchmark_owner._manager.peer_manager.write_own_peer_info()"
    ]
   },
   {

diff --git a/notebooks/enclave/gemma/colab-3-persona/3. DS-researcher-gemma-restrict.ipynb b/notebooks/enclave/gemma/colab-3-persona/3. DS-researcher-gemma-restrict.ipynb
@@ -96,7 +96,7 @@
    "source": [
     "# # Optionally to clear state\n",
     "# researcher._manager.delete_syftbox()\n",
-    "# researcher._manager.peer_manager.write_own_version()"
+    "# researcher._manager.peer_manager.write_own_peer_info()"
    ]
   },
   {

diff --git a/notebooks/enclave/gemma/colab-shield/0. clear-state-gemma.ipynb b/notebooks/enclave/gemma/colab-shield/0. clear-state-gemma.ipynb
@@ -12,7 +12,7 @@
     "\n",
     "```python\n",
     "client._manager.delete_syftbox()\n",
-    "client._manager.peer_manager.write_own_version()\n",
+    "client._manager.peer_manager.write_own_peer_info()\n",
     "```"
    ]
   },
@@ -68,7 +68,7 @@
     "\n",
     "client = login_do(sync=False, load_peers=False)\n",
     "client._rds.delete_syftbox()\n",
-    "client._rds.peer_manager.write_own_version()"
+    "client._rds.peer_manager.write_own_peer_info()"
    ]
   }
  ],

diff --git a/notebooks/enclave/gemma/colab-shield/1. DO-model-owner-gemma-shield.ipynb b/notebooks/enclave/gemma/colab-shield/1. DO-model-owner-gemma-shield.ipynb
@@ -156,16 +156,16 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "CRYPTO_KEYS_PATH = None\n",
-    "# NOTE: Re-storing Private Key from local_file, if you have it, uncomment the following line and upload the file.\n",
+    "KEY_FILE = None\n",
+    "# To restore the encryption key of an earlier session, uncomment the next two lines and upload crypto_keys.json.\n",
     "# from google.colab import files; files.upload()\n",
-    "# CRYPTO_KEYS_PATH = \"crypto_keys.json\"\n",
+    "# KEY_FILE = \"crypto_keys.json\"\n",
     "\n",
-    "model_owner = login_do(encryption=True, crypto_keys_path=CRYPTO_KEYS_PATH)\n",
+    "model_owner = login_do(key_file=KEY_FILE)\n",
     "print(f\"  Model owner : {model_owner.email}\")\n",
     "\n",
-    "# First login: back up the encryption key — it lives only on this runtime's filesystem.\n",
-    "if CRYPTO_KEYS_PATH is None:\n",
+    "# First login: back up the encryption key. It lives only on this runtime's filesystem.\n",
+    "if KEY_FILE is None:\n",
     "    from google.colab import files\n",
     "    files.download(str(model_owner.syftbox_folder / model_owner.email / \"private\" / \"crypto_keys.json\"))"
    ]
@@ -179,7 +179,7 @@
    "source": [
     "# # Optionally to clear state\n",
     "# model_owner._manager.delete_syftbox()\n",
-    "# model_owner._manager.peer_manager.write_own_version()"
+    "# model_owner._manager.peer_manager.write_own_peer_info()"
    ]
   },
   {

diff --git a/notebooks/enclave/gemma/colab-shield/2. DO-benchmark-owner-gemma-shield.ipynb b/notebooks/enclave/gemma/colab-shield/2. DO-benchmark-owner-gemma-shield.ipynb
@@ -100,16 +100,16 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "CRYPTO_KEYS_PATH = None\n",
-    "# NOTE: Re-storing Private Key from local_file, if you have it, uncomment the following line and upload the file.\n",
+    "KEY_FILE = None\n",
+    "# To restore the encryption key of an earlier session, uncomment the next two lines and upload crypto_keys.json.\n",
     "# from google.colab import files; files.upload()\n",
-    "# CRYPTO_KEYS_PATH = \"crypto_keys.json\"\n",
+    "# KEY_FILE = \"crypto_keys.json\"\n",
     "\n",
-    "benchmark_owner = login_do(encryption=True, crypto_keys_path=CRYPTO_KEYS_PATH)\n",
+    "benchmark_owner = login_do(key_file=KEY_FILE)\n",
     "print(f\"  Benchmark owner : {benchmark_owner.email}\")\n",
     "\n",
-    "# First login: back up the encryption key — it lives only on this runtime's filesystem.\n",
-    "if CRYPTO_KEYS_PATH is None:\n",
+    "# First login: back up the encryption key. It lives only on this runtime's filesystem.\n",
+    "if KEY_FILE is None:\n",
     "    from google.colab import files\n",
     "    files.download(str(benchmark_owner.syftbox_folder / benchmark_owner.email / \"private\" / \"crypto_keys.json\"))"
    ]
@@ -123,7 +123,7 @@
    "source": [
     "# # Optionally to clear state\n",
     "# benchmark_owner._manager.delete_syftbox()\n",
-    "# benchmark_owner._manager.peer_manager.write_own_version()"
+    "# benchmark_owner._manager.peer_manager.write_own_peer_info()"
    ]
   },
   {

diff --git a/notebooks/enclave/gemma/colab/0. clear-state-gemma.ipynb b/notebooks/enclave/gemma/colab/0. clear-state-gemma.ipynb
@@ -12,7 +12,7 @@
     "\n",
     "```python\n",
     "client._manager.delete_syftbox()\n",
-    "client._manager.peer_manager.write_own_version()\n",
+    "client._manager.peer_manager.write_own_peer_info()\n",
     "```"
    ]
   },
@@ -68,7 +68,7 @@
     "\n",
     "client = login_do(sync=False, load_peers=False)\n",
     "client._manager.delete_syftbox()\n",
-    "client._manager.peer_manager.write_own_version()"
+    "client._manager.peer_manager.write_own_peer_info()"
    ]
   }
  ],

diff --git a/notebooks/enclave/gemma/colab/1. DO-model-owner-gemma-restrict.ipynb b/notebooks/enclave/gemma/colab/1. DO-model-owner-gemma-restrict.ipynb
@@ -108,16 +108,16 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "CRYPTO_KEYS_PATH = None\n",
-    "# NOTE: Re-storing Private Key from local_file, if you have it, uncomment the following line and upload the file.\n",
+    "KEY_FILE = None\n",
+    "# To restore the encryption key of an earlier session, uncomment the next two lines and upload crypto_keys.json.\n",
     "# from google.colab import files; files.upload()\n",
-    "# CRYPTO_KEYS_PATH = \"crypto_keys.json\"\n",
+    "# KEY_FILE = \"crypto_keys.json\"\n",
     "\n",
-    "model_owner = login_do(encryption=True, crypto_keys_path=CRYPTO_KEYS_PATH)\n",
+    "model_owner = login_do(key_file=KEY_FILE)\n",
     "print(f\"  Model owner : {model_owner.email}\")\n",
     "\n",
-    "# First login: back up the encryption key — it lives only on this runtime's filesystem.\n",
-    "if CRYPTO_KEYS_PATH is None:\n",
+    "# First login: back up the encryption key. It lives only on this runtime's filesystem.\n",
+    "if KEY_FILE is None:\n",
     "    from google.colab import files\n",
     "    files.download(str(model_owner.syftbox_folder / model_owner.email / \"private\" / \"crypto_keys.json\"))"
    ]
@@ -131,7 +131,7 @@
    "source": [
     "# # Optionally to clear state\n",
     "# model_owner._manager.delete_syftbox()\n",
-    "# model_owner._manager.peer_manager.write_own_version()"
+    "# model_owner._manager.peer_manager.write_own_peer_info()"
    ]
   },
   {

diff --git a/notebooks/enclave/gemma/colab/2. DO-benchmark-owner-gemma-restrict.ipynb b/notebooks/enclave/gemma/colab/2. DO-benchmark-owner-gemma-restrict.ipynb
@@ -89,16 +89,16 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "CRYPTO_KEYS_PATH = None\n",
-    "# NOTE: Re-storing Private Key from local_file, if you have it, uncomment the following line and upload the file.\n",
+    "KEY_FILE = None\n",
+    "# To restore the encryption key of an earlier session, uncomment the next two lines and upload crypto_keys.json.\n",
     "# from google.colab import files; files.upload()\n",
-    "# CRYPTO_KEYS_PATH = \"crypto_keys.json\"\n",
+    "# KEY_FILE = \"crypto_keys.json\"\n",
     "\n",
-    "benchmark_owner = login_do(encryption=True, crypto_keys_path=CRYPTO_KEYS_PATH)\n",
+    "benchmark_owner = login_do(key_file=KEY_FILE)\n",
     "print(f\"  Benchmark owner : {benchmark_owner.email}\")\n",
     "\n",
-    "# First login: back up the encryption key — it lives only on this runtime's filesystem.\n",
-    "if CRYPTO_KEYS_PATH is None:\n",
+    "# First login: back up the encryption key. It lives only on this runtime's filesystem.\n",
+    "if KEY_FILE is None:\n",
     "    from google.colab import files\n",
     "    files.download(str(benchmark_owner.syftbox_folder / benchmark_owner.email / \"private\" / \"crypto_keys.json\"))"
    ]
@@ -112,7 +112,7 @@
    "source": [
     "# # Optionally to clear state\n",
     "# benchmark_owner._manager.delete_syftbox()\n",
-    "# benchmark_owner._manager.peer_manager.write_own_version()"
+    "# benchmark_owner._manager.peer_manager.write_own_peer_info()"
    ]
   },
   {

diff --git a/notebooks/enclave/nanolm/2. enclave_eval_localenc.ipynb b/notebooks/enclave/nanolm/2. enclave_eval_localenc.ipynb
@@ -272,9 +272,9 @@
     "researcher._manager.delete_syftbox()\n",
     "\n",
     "# Write Own Version\n",
-    "model_owner._manager.peer_manager.write_own_version()\n",
-    "benchmark_owner._manager.peer_manager.write_own_version()\n",
-    "researcher._manager.peer_manager.write_own_version()"
+    "model_owner._manager.peer_manager.write_own_peer_info()\n",
+    "benchmark_owner._manager.peer_manager.write_own_peer_info()\n",
+    "researcher._manager.peer_manager.write_own_peer_info()"
    ]
   },
   {

diff --git a/notebooks/enclave/nanolm/3. enclave_eval_e2e.ipynb b/notebooks/enclave/nanolm/3. enclave_eval_e2e.ipynb
@@ -177,9 +177,9 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# model_owner._manager.peer_manager.write_own_version()\n",
-    "# benchmark_owner._manager.peer_manager.write_own_version()\n",
-    "# researcher._manager.peer_manager.write_own_version()"
+    "# model_owner._manager.peer_manager.write_own_peer_info()\n",
+    "# benchmark_owner._manager.peer_manager.write_own_peer_info()\n",
+    "# researcher._manager.peer_manager.write_own_peer_info()"
    ]
   },
   {

diff --git a/notebooks/enclave/nanolm/nbsplit/1. DO-model-owner-nanolm.ipynb b/notebooks/enclave/nanolm/nbsplit/1. DO-model-owner-nanolm.ipynb
@@ -95,7 +95,7 @@
    "source": [
     "# Optionally to clear state\n",
     "model_owner._manager.delete_syftbox()\n",
-    "model_owner._manager.peer_manager.write_own_version()"
+    "model_owner._manager.peer_manager.write_own_peer_info()"
    ]
   },
   {